{"record":{"id":"3131f1737691531a","repo":"JuliusBrussee/caveman","slug":"caveman-agent-entry-must-export-default-agent","errorCode":null,"errorMessage":"caveman agent: entry must export default agent()","messagePattern":"caveman agent: entry must export default agent\\(\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/agent/src/cli.ts","lineNumber":1383,"sourceCode":"  const configured = [\n    process.env.ANTHROPIC_API_KEY && \"anthropic/claude-haiku-4-5\",\n    process.env.OPENAI_API_KEY && \"openai/gpt-5.4-mini\",\n    (process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY) && \"google/gemini-2.5-flash\",\n  ].filter((value): value is string => typeof value === \"string\");\n  if (configured.length !== 1) {\n    throw new Error(\"caveman build: set CAVE_MODEL when zero or multiple provider credentials exist\");\n  }\n  return configured[0]!;\n}\n\nasync function loadAgent(path: string): Promise<AgentDefinition> {\n  return agentFromImported(await importFresh(path));\n}\n\nfunction agentFromImported(imported: unknown): AgentDefinition {\n  const exported = imported as { default?: AgentDefinition; agent?: AgentDefinition };\n  const definition = exported.default ?? exported.agent;\n  if (!definition || definition.kind !== \"agent\") throw new Error(\"caveman agent: entry must export default agent()\");\n  return definition;\n}\n\nasync function readLock(root: string): Promise<CaveBuildLock> {\n  return parseCaveBuildLock(JSON.parse(await readFile(resolve(root, \".caveman/agent.lock.json\"), \"utf8\")));\n}\n\nfunction importFresh(path: string): Promise<unknown> {\n  return import(`${pathToFileURL(path).href}?cave=${Date.now()}-${crypto.randomUUID()}`);\n}\n\nfunction isEval(value: unknown): value is EvalDefinition {\n  return value !== null && typeof value === \"object\" && (value as { kind?: unknown }).kind === \"eval\";\n}\n\nfunction fixtureInput(value: unknown): string {\n  return typeof value === \"string\" ? value : JSON.stringify(value);\n}","sourceCodeStart":1365,"sourceCodeEnd":1401,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/cli.ts#L1365-L1401","documentation":"Thrown by `agentFromImported` while loading the agent entry module (`loadAgent`). The module must export the agent definition as `default` or as a named `agent` export, and that object must carry `kind: \"agent\"`. Anything else — a module exporting a function, a builder result without the kind tag, or no relevant export at all — fails with this message.","triggerScenarios":"`config.entry` points at a module whose exports are neither `default` nor `agent`, or whose exported value lacks `kind === \"agent\"` — e.g. `export const agent = () => buildAgent(...)` (exports a factory function, not a definition) or `export default tool({...})`.","commonSituations":"Exporting the factory instead of calling it (`export default agent` vs `export default agent()`); renaming exports; an entry file that re-exports from a barrel that drops the default; definitions built by hand rather than the `agent()` builder so `kind` was never set.","solutions":["Change the entry to `export default agent({...})` — call the builder and export its returned definition.","If using a named export, use exactly `export const agent = ...`.","Only use the framework's `agent()` builder to produce definitions; hand-made objects lack the `kind: \"agent\"` tag.","Confirm `config.entry` points at the intended file and that any barrel re-export preserves `default`."],"exampleFix":"// before\nexport const myAgent = agent({ ... });\n\n// after\nexport default agent({ ... });\n// or: export const agent = agent({ ... });","handlingStrategy":"type-guard","validationCode":"function moduleExportsAgentDefinition(mod: Record<string, unknown>): boolean {\n  const def = (mod.default ?? mod.agent) as { kind?: unknown } | undefined;\n  return !!def && def.kind === \"agent\";\n}\n// const mod = await import(entryPath); assert moduleExportsAgentDefinition(mod);","typeGuard":"function isAgentDefinition(v: unknown): v is { kind: \"agent\" } {\n  return typeof v === \"object\" && v !== null && (v as { kind?: unknown }).kind === \"agent\";\n}","tryCatchPattern":"try {\n  await build(args);\n} catch (error) {\n  if (error instanceof Error && error.message === \"caveman agent: entry must export default agent()\") {\n    // change entry to `export default agent({...})` (call the builder) and retry\n  } else throw error;\n}","preventionTips":["Always `export default agent({...})` — invoke the builder, don't export the factory.","Avoid barrel re-exports for the entry; point config.entry at the defining module.","Only build definitions with the framework agent() builder so `kind` is set."],"tags":["agent-definition","esm","config","build"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}