feat(init): add .agents/types directory scaffolding and schema error handling

- Add .agents/ and .agents/types/ directory creation in init command
- Copy agent-definition.ts, tools.ts, util-types.ts type files
- Add ensureJsonSchemaCompatible fallback for invalid Zod schemas
- Add toJsonSchemaSafe error handling in lookup-agent-info
- Always include local agents in spawnableAgents (remove agentId check)
- Add comprehensive tests for init command (19 tests)
- Add schema handling error recovery tests (13 tests)

Author: brandonkachen

cli/src/commands/__tests__/init.test.ts

@@ -1,6 +1,10 @@
-import { existsSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, writeFileSync } from 'fs'
 import path from 'path'
 
+import agentDefinitionSource from '../../../common/src/templates/initial-agents-dir/types/agent-definition' with { type: 'text' }
+import toolsSource from '../../../common/src/templates/initial-agents-dir/types/tools' with { type: 'text' }
+import utilTypesSource from '../../../common/src/templates/initial-agents-dir/types/util-types' with { type: 'text' }
+
 import { getProjectRoot } from '../project-files'
 import { getSystemMessage } from '../utils/message-history'
 
@@ -27,25 +31,77 @@ This file gives Codebuff context about your project: goals, commands, convention
 - Things to avoid:
 `
 
+const COMMON_TYPE_FILES = [
+  {
+    fileName: 'agent-definition.ts',
+    source: agentDefinitionSource,
+  },
+  {
+    fileName: 'tools.ts',
+    source: toolsSource,
+  },
+  {
+    fileName: 'util-types.ts',
+    source: utilTypesSource,
+  },
+]
+
 export function handleInitializationFlowLocally(): {
   postUserMessage: PostUserMessageFn
 } {
   const projectRoot = getProjectRoot()
   const knowledgePath = path.join(projectRoot, KNOWLEDGE_FILE_NAME)
+  const messages: string[] = []
 
   if (existsSync(knowledgePath)) {
-    const postUserMessage: PostUserMessageFn = (prev) => [
-      ...prev,
-      getSystemMessage(`📋 \`${KNOWLEDGE_FILE_NAME}\` already exists.`),
-    ]
-    return { postUserMessage }
+    messages.push(`📋 \`${KNOWLEDGE_FILE_NAME}\` already exists.`)
+  } else {
+    writeFileSync(knowledgePath, INITIAL_KNOWLEDGE_FILE)
+    messages.push(`✅ Created \`${KNOWLEDGE_FILE_NAME}\``)
+  }
+
+  const agentsDir = path.join(projectRoot, '.agents')
+  const agentsTypesDir = path.join(agentsDir, 'types')
+
+  if (existsSync(agentsDir)) {
+    messages.push('📋 `.agents/` already exists.')
+  } else {
+    mkdirSync(agentsDir, { recursive: true })
+    messages.push('✅ Created `.agents/`')
   }
 
-  writeFileSync(knowledgePath, INITIAL_KNOWLEDGE_FILE)
+  if (existsSync(agentsTypesDir)) {
+    messages.push('📋 `.agents/types/` already exists.')
+  } else {
+    mkdirSync(agentsTypesDir, { recursive: true })
+    messages.push('✅ Created `.agents/types/`')
+  }
+
+  for (const { fileName, source } of COMMON_TYPE_FILES) {
+    const targetPath = path.join(agentsTypesDir, fileName)
+    if (existsSync(targetPath)) {
+      messages.push(`📋 \`.agents/types/${fileName}\` already exists.`)
+      continue
+    }
+
+    try {
+      if (!source || source.trim().length === 0) {
+        throw new Error('Source content is empty')
+      }
+      writeFileSync(targetPath, source)
+      messages.push(`✅ Copied \`.agents/types/${fileName}\``)
+    } catch (error) {
+      messages.push(
+        `⚠️ Failed to copy \`.agents/types/${fileName}\`: ${
+          error instanceof Error ? error.message : String(error ?? 'Unknown')
+        }`,
+      )
+    }
+  }
 
   const postUserMessage: PostUserMessageFn = (prev) => [
     ...prev,
-    getSystemMessage(`✅ Created \`${KNOWLEDGE_FILE_NAME}\``),
+    ...messages.map((message) => getSystemMessage(message)),
   ]
   return { postUserMessage }
 }

cli/src/commands/init.ts

@@ -200,6 +200,68 @@ describe('mainPrompt', () => {
     },
   }
 
+  it('includes local agents in spawnableAgents when agentId is provided', async () => {
+    const sessionState = getInitialSessionState(mockFileContext)
+    const mainAgentId = 'test-main-agent'
+    const localAgentId = 'test-local-agent'
+
+    const localAgentTemplates: Record<string, AgentTemplate> = {
+      [mainAgentId]: {
+        id: mainAgentId,
+        displayName: 'Test Main Agent',
+        outputMode: 'last_message',
+        inputSchema: {},
+        spawnerPrompt: '',
+        model: 'gpt-4o-mini',
+        includeMessageHistory: true,
+        inheritParentSystemPrompt: false,
+        mcpServers: {},
+        toolNames: ['write_file', 'run_terminal_command', 'end_turn'],
+        spawnableAgents: [],
+        systemPrompt: '',
+        instructionsPrompt: '',
+        stepPrompt: '',
+      },
+      [localAgentId]: {
+        id: localAgentId,
+        displayName: 'Test Local Agent',
+        outputMode: 'last_message',
+        inputSchema: {},
+        spawnerPrompt: '',
+        model: 'gpt-4o-mini',
+        includeMessageHistory: false,
+        inheritParentSystemPrompt: false,
+        mcpServers: {},
+        toolNames: ['write_file', 'run_terminal_command', 'end_turn'],
+        spawnableAgents: [],
+        systemPrompt: '',
+        instructionsPrompt: '',
+        stepPrompt: '',
+      },
+    }
+
+    const action = {
+      type: 'prompt' as const,
+      prompt: 'Hello',
+      sessionState,
+      fingerprintId: 'test',
+      costMode: 'normal' as const,
+      promptId: 'test',
+      toolResults: [],
+      agentId: mainAgentId,
+    }
+
+    await mainPrompt({
+      ...mainPromptBaseParams,
+      action,
+      localAgentTemplates,
+    })
+
+    expect(localAgentTemplates[mainAgentId].spawnableAgents).toContain(
+      localAgentId,
+    )
+  })
+
   it('should handle write_file tool call', async () => {
     // Mock LLM to return a write_file tool call using native tool call chunks
     mockAgentStream([