{"record":{"id":"bb098d9fb1fd7e60","repo":"moeru-ai/airi","slug":"gameletkit-requires-a-host-gamelet-orchestration-r","errorCode":null,"errorMessage":"gameletKit requires a host gamelet orchestration runtime.","messagePattern":"gameletKit requires a host gamelet orchestration runtime\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/plugin-sdk-tamagotchi/src/kits/gamelet/index.ts","lineNumber":128,"sourceCode":"      await gamelets.orchestration?.close(bindingId)\n    },\n  })\n\n  if (options.init === undefined) {\n    return handle\n  }\n\n  return {\n    ...handle,\n    init: options.init,\n  }\n}\n\nexport { gameletKit }\n\nfunction requireOrchestration(gamelets: Awaited<ReturnType<typeof gameletKit.createClient>>): NonNullable<typeof gamelets.orchestration> {\n  if (!gamelets.orchestration) {\n    throw new Error(GAMELET_RUNTIME_UNAVAILABLE_MESSAGE)\n  }\n\n  return gamelets.orchestration\n}\n","sourceCodeStart":110,"sourceCodeEnd":133,"githubUrl":"https://github.com/moeru-ai/airi/blob/27111382b4a79a7e983289d6e983a06af185ed0f/packages/plugin-sdk-tamagotchi/src/kits/gamelet/index.ts#L110-L133","documentation":"Thrown by requireOrchestration() when a gamelet handle method (open, configure, request, close, isOpen) is called but the host did not wire the optional `gamelets` orchestration runtime into the gameletKit client. The gamelet was mounted successfully (bindings runtime was present) but the host never provided the open/close/request implementation, so orchestration calls cannot be routed.","triggerScenarios":"Calling any method on the GameletHandle returned by createGamelet() — handle.open(), handle.configure(), handle.request(), handle.close(), or handle.isOpen() — when the GameletKitRuntime passed to gameletKit.createClient had no `gamelets` field (it is optional: `orchestration?: GameletKitRuntime['gamelets']`).","commonSituations":"A Tamagotchi host registers the gameletKit with only a `bindings` binding implementation (enough for mount) but forgets to supply the `gamelets` orchestration handlers. Also happens in tests or minimal host stubs that only exercise mounting, or after a host refactor that split binding from orchestration but only wired the binding side.","solutions":["Ensure the host contribution that creates the gameletKit client provides a `gamelets` object on the runtime with open, configure, request, close, and isOpen implementations.","If orchestration is genuinely optional for your host, guard handle calls by checking whether orchestration is available before invoking open/configure/request/close/isOpen.","Register a no-op or stub `gamelets` implementation during development so mount + handle calls do not throw."],"exampleFix":"// before (host contribution omits gamelets)\nregisterKitApi({ id: 'kit.gamelet', createClient: () => gameletKit.createClient({ bindings: myBindings }) })\n\n// after (host provides gamelets orchestration)\nregisterKitApi({\n  id: 'kit.gamelet',\n  createClient: () => gameletKit.createClient({\n    bindings: myBindings,\n    gamelets: {\n      open: (id, payload) => myOrchestrator.open(id, payload),\n      configure: (id, payload) => myOrchestrator.configure(id, payload),\n      request: (id, payload, opts) => myOrchestrator.request(id, payload, opts),\n      close: id => myOrchestrator.close(id),\n      isOpen: id => myOrchestrator.isOpen(id),\n    },\n  }),\n})","handlingStrategy":"type-guard","validationCode":"const gamelets = await module.kits.use(gameletKit)\nif (!gamelets.orchestration) {\n  throw new Error('Host did not provide gamelet orchestration; cannot open/configure/request/close.')\n}\nawait gamelets.orchestration.open(bindingId)","typeGuard":"function hasGameletOrchestration(\n  gamelets: Awaited<ReturnType<typeof gameletKit.createClient>>,\n): gamelets is { orchestration: NonNullable<typeof gamelets.orchestration> } {\n  return gamelets.orchestration !== undefined\n}","tryCatchPattern":"try {\n  await handle.open()\n} catch (error) {\n  if (error instanceof Error && error.message === 'gameletKit requires a host gamelet orchestration runtime.') {\n    // host did not wire orchestration; degrade gracefully\n  } else {\n    throw error\n  }\n}","preventionTips":["When writing a host contribution for gameletKit, always supply the `gamelets` field on the runtime, not just `bindings`.","In tests, assert the kit client exposes a non-undefined orchestration before exercising handle methods.","Document the host contract: mount needs `bindings`, handle methods need `gamelets`."],"tags":["runtime","gamelet","host-configuration","missing-dependency"],"backgroundTag":null,"analyzedSha":"27111382b4a79a7e983289d6e983a06af185ed0f","analyzedAt":"2026-08-12T18:33:34.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}