{"record":{"id":"ba966bd1b63b5e5e","repo":"JuliusBrussee/caveman","slug":"cave-sandbox-agent-export-missing","errorCode":"cave_sandbox_agent_export_missing","errorMessage":"cave_sandbox_agent_export_missing","messagePattern":"cave_sandbox_agent_export_missing","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/tool-worker.ts","lineNumber":106,"sourceCode":"  const request = await readRequest();\n  if (typeof request.entry !== \"string\" || !Array.isArray(request.agentPath) ||\n      request.agentPath.length > 8 ||\n      request.agentPath.some((item) => typeof item !== \"string\" ||\n        !/^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/.test(item)) ||\n      typeof request.rootDefinitionSha256 !== \"string\" ||\n      !/^[a-f0-9]{64}$/.test(request.rootDefinitionSha256) ||\n      typeof request.toolDefinitionSha256 !== \"string\" ||\n      !/^[a-f0-9]{64}$/.test(request.toolDefinitionSha256) ||\n      typeof request.tool !== \"string\" ||\n      !/^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/.test(request.tool) ||\n      typeof request.allowSideEffects !== \"boolean\" ||\n      typeof request.allowNetwork !== \"boolean\") {\n    throw new Error(\"cave_sandbox_request_invalid\");\n  }\n  if (request.allowNetwork !== true) installNetworkDeny();\n  const imported = await import(request.entry) as { default?: AgentDefinition; agent?: AgentDefinition };\n  let definition = imported.default ?? imported.agent;\n  if (!definition || definition.kind !== \"agent\") throw new Error(\"cave_sandbox_agent_export_missing\");\n  validateAgentGraph(definition);\n  if (agentDefinitionSHA256(definition) !== request.rootDefinitionSha256) {\n    throw new Error(\"cave_sandbox_definition_mismatch\");\n  }\n  const visited = new Set<AgentDefinition>([definition]);\n  for (const name of request.agentPath) {\n    const delegated = definition.tools.filter((item) =>\n      item.name === name && item.runtime?.kind === \"subagent\"\n    );\n    if (delegated.length !== 1) throw new Error(\"cave_sandbox_unknown_subagent\");\n    const child = delegated[0]!.runtime!.definition as AgentDefinition;\n    if (!child || child.kind !== \"agent\") {\n      throw new Error(\"cave_sandbox_subagent_definition_invalid\");\n    }\n    if (visited.has(child)) throw new Error(\"cave_sandbox_subagent_cycle\");\n    visited.add(child);\n    definition = child;\n  }","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/tool-worker.ts#L88-L124","documentation":"After importing the entry module, the worker looks for the agent definition as the module's `default` export or named `agent` export. If neither is present, or the found object is not an object with `kind: \"agent\"`, it throws `cave_sandbox_agent_export_missing`. The sandbox can only run a definition it can locate and recognize in the entry module.","triggerScenarios":"The request.entry module exports the agent under a custom name (not `default` or `agent`), has no export at all, exports only a factory function, or exports an object whose `kind` is not \"agent\" (e.g. a tool or workflow definition).","commonSituations":"Refactoring renamed the export (e.g. `export const myAgent = ...`); building the agent via a builder call assigned to a differently named const; exporting a factory `createAgent()` result directly instead of the built definition; tree-shaking or bundling dropping the expected export.","solutions":["Export the agent definition as the default export: `export default myAgent;` in the entry file.","Alternatively name the export exactly `agent`: `export const agent = myAgent;`.","Ensure the exported value is the built definition object with `kind: \"agent\"`, not a factory or builder instance.","Verify request.entry points at the file that actually holds the definition."],"exampleFix":"// before\nexport const researcher = agent(\"researcher\").tool(search).build();\n\n// after\nconst researcher = agent(\"researcher\").tool(search).build();\nexport default researcher;","handlingStrategy":"validation","validationCode":"const mod = await import(entryPath);\nconst def = (mod as { default?: unknown; agent?: unknown }).default ?? (mod as { agent?: unknown }).agent;\nif (!def || (def as { kind?: string }).kind !== \"agent\") {\n  throw new Error(`${entryPath} must default-export (or export 'agent' as) a built agent definition`);\n}","typeGuard":"const isAgentExport = (mod: unknown): mod is { default: AgentDefinition } | { agent: AgentDefinition } =>\n  typeof mod === \"object\" && mod !== null &&\n  (Boolean((mod as any).default && (mod as any).default.kind === \"agent\") ||\n   Boolean((mod as any).agent && (mod as any).agent.kind === \"agent\"));","tryCatchPattern":null,"preventionTips":["Always `export default` the built agent definition from the sandbox entry file (or name it exactly `agent`).","Export the built definition object, never a builder or factory function.","Verify the built object's `kind` is \"agent\" before exporting.","Add an import smoke test that loads each entry module and asserts the export shape."],"tags":["sandbox","module","exports","validation"],"backgroundTag":"unexpected-response-shape","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}