@inkeep/agents-cli 0.21.1 → 0.22.0

package/dist/index.js

@@ -234088,10 +234088,10 @@ function maskSensitiveConfig(config) {
   if (!config) return config;
   const masked = { ...config };
   if (masked.agentsManageApiKey) {
-    masked.agentsManageApiKey = "***" + masked.agentsManageApiKey.slice(-4);
+    masked.agentsManageApiKey = `***${masked.agentsManageApiKey.slice(-4)}`;
   }
   if (masked.agentsRunApiKey) {
-    masked.agentsRunApiKey = "***" + masked.agentsRunApiKey.slice(-4);
+    masked.agentsRunApiKey = `***${masked.agentsRunApiKey.slice(-4)}`;
   }
   return masked;
 }
@@ -234535,6 +234535,9 @@ function isJsonSchemaPath(path3) {
   if (path3.includes("dataComponents") && path3.endsWith("props")) {
     return true;
   }
+  if (path3.includes("statusComponents") && path3.endsWith("detailsSchema")) {
+    return true;
+  }
   return false;
 }
 function updateTracker(tracker, placeholder, value) {
@@ -234613,7 +234616,7 @@ function restorePlaceholders(generatedCode, replacements) {
   const sortedPlaceholders = Object.keys(replacements).sort((a, b2) => b2.length - a.length);
   for (const placeholder of sortedPlaceholders) {
     let originalValue = replacements[placeholder];
-    originalValue = originalValue.replace(/`/g, "\\`");
+    originalValue = originalValue.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
     const escapedPlaceholder = placeholder.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const regex = new RegExp(escapedPlaceholder, "g");
     restoredCode = restoredCode.replace(regex, originalValue);
@@ -234653,6 +234656,7 @@ __export(pull_llm_generate_exports, {
   generateDataComponentFile: () => generateDataComponentFile,
   generateEnvironmentFiles: () => generateEnvironmentFiles,
   generateIndexFile: () => generateIndexFile,
+  generateStatusComponentFile: () => generateStatusComponentFile,
   generateTextWithPlaceholders: () => generateTextWithPlaceholders,
   generateToolFile: () => generateToolFile,
   generateTypeScriptFileWithLLM: () => generateTypeScriptFileWithLLM,
@@ -234818,22 +234822,48 @@ ${NAMING_CONVENTION_RULES}
 ${IMPORT_INSTRUCTIONS}
 
 REQUIREMENTS:
-1. Import { agent, subAgent } from '@inkeep/agents-sdk'
+1. IMPORTS (CRITICAL):
+   - ALWAYS import { agent, subAgent } from '@inkeep/agents-sdk'
+   - ALWAYS import { z } from 'zod' when using ANY Zod schemas (responseSchema, headersSchema, etc.)
+   - ALWAYS import { contextConfig, fetchDefinition, headers } from '@inkeep/agents-core' when agent has contextConfig
+   - Import status components from '../status-components/' when needed
 2. Define each agent using the agent() function following the type definitions provided above
 3. Create the agent using agent() with proper structure
    - IMPORTANT: If description is null, undefined, or empty string, omit the description field entirely
-4. CRITICAL: For multi-line strings (especially prompts), ALWAYS use template literals with backticks:
-   - Single-line strings: use regular quotes 'short string'
-   - Multi-line strings: MUST use template literals starting and ending with backticks
+4. CRITICAL: Template Literals vs Raw Code:
+   - For STRING VALUES: ALWAYS use template literals with backticks: \`string content\`
+   - This includes: prompt, description, query, url, method, body, defaultValue, etc.
+   - This prevents TypeScript syntax errors with apostrophes (user's, don't, etc.)
    - IMPORTANT: ANY placeholder that starts with < and ends with > MUST be wrapped in template literals (backticks)
-   - Placeholders contain multi-line content and require template literals
-   - This prevents TypeScript syntax errors with newlines and special characters
-   - you must import { z } from 'zod' if you are using zod schemas in the agent file.
-   - you must import { headers } from '@inkeep/agents-core' and use it to create the headers schema if you are using headers in a contextConfig.
+   - For object keys: use quotes only for keys with hyphens ('Content-Type'), omit for simple identifiers (Authorization)
+   
+   EXCEPTION - Schema Fields (NO template literals):
+   - headersSchema: z.object({ ... }) (raw Zod code, NOT a string)
+   - responseSchema: z.object({ ... }) (raw Zod code, NOT a string)
+   - These are TypeScript expressions, not string values
+   
+   Examples:
+   \u2705 prompt: \`You are a helpful assistant.\` (string value, use backticks)
+   \u2705 query: \`query GetData { field }\` (string value, use backticks)
+   \u2705 responseSchema: z.object({ name: z.string() }) (Zod code, NO backticks)
+   \u2705 headersSchema: z.object({ 'inkeep_api_key': z.string() }) (Zod code, NO backticks)
+   \u274C responseSchema: \`z.object({ name: z.string() })\` (WRONG - don't wrap Zod in backticks)
+   
    - convert template literals to use the appropriate headers schema or context config toTemplate method. a template literal is a substring that starts with {{ and ends with }}.
     - if you see a template literal with {{headers.}}, convert it to use the headers schema toTemplate method.
     - if you see a template literal with {{contextVariableKey.field_name}}, convert it to use the context config toTemplate method.
-6. If you are writing zod schemas make them clean. For example if you see z.union([z.string(), z.null()]) write it as z.string().nullable()
+5. For contextConfig (CRITICAL):
+   - NEVER use plain objects for contextConfig
+   - ALWAYS use helper functions: headers(), fetchDefinition(), contextConfig()
+   - Create separate const variables for each helper before the agent definition
+   - Pattern: const myHeaders = headers({ schema: z.object({ api_key: z.string() }) });
+   - Pattern: const myFetch = fetchDefinition({ id: '...', fetchConfig: {...}, responseSchema: z.object({...}) });
+   - Pattern: const myContext = contextConfig({ headers: myHeaders, contextVariables: { data: myFetch } });
+   - Then use: export const myAgent = agent({ contextConfig: myContext });
+   - Use myHeaders.toTemplate('key_name') for header interpolation in fetch configs
+   - Use myContext.toTemplate('variable.field') for context variable interpolation
+
+7. If you are writing zod schemas make them clean. For example if you see z.union([z.string(), z.null()]) write it as z.string().nullable()
 
 PLACEHOLDER HANDLING EXAMPLES:
 // CORRECT - Placeholder wrapped in template literals:
@@ -234848,6 +234878,8 @@ import { contextConfig, fetchDefinition, headers } from '@inkeep/agents-core';
 import { userProfile } from '../data-components/user-profile';
 import { searchTool } from '../tools/search-tool';
 import { weatherTool } from '../tools/weather-tool';
+import { toolSummary } from '../status-components/tool-summary';
+import { progressStatus } from '../status-components/progress-status';
 import { z } from 'zod';
 
 const supportAgentHeaders = headers({
@@ -234912,7 +234944,16 @@ export const supportAgent = agent({
   name: 'Support Agent',
   description: 'Multi-agent support system', // Only include if description has a value
   defaultSubAgent: routerAgent,
-  subAgents: () => [routerAgent, qaAgent]
+  subAgents: () => [routerAgent, qaAgent],
+  models: {
+    base: { model: 'gpt-4' },
+    summarizer: { model: 'gpt-4' },
+  },
+  statusUpdates: {
+    numEvents: 3,
+    timeInSeconds: 15,
+    statusComponents: [toolSummary.config, progressStatus.config],
+  },
 });
 
 Generate ONLY the TypeScript code without any markdown or explanations.`;
@@ -235196,6 +235237,75 @@ Generate ONLY the TypeScript code without any markdown or explanations.`;
   });
   writeFileSync3(outputPath, cleanGeneratedCode(text2));
 }
+async function generateStatusComponentFile(componentData, componentId, outputPath, modelSettings) {
+  const model = createModel(modelSettings);
+  const promptTemplate = `Generate a TypeScript file for an Inkeep status component.
+
+STATUS COMPONENT DATA:
+{{DATA}}
+
+COMPONENT ID: ${componentId}
+
+${getTypeDefinitions()}
+
+${NAMING_CONVENTION_RULES}
+
+${IMPORT_INSTRUCTIONS}
+
+REQUIREMENTS:
+1. Import statusComponent from '@inkeep/agents-sdk'
+2. Import z from 'zod' for schema definitions
+3. Create the status component using statusComponent()
+4. Export following naming convention rules (camelCase version of ID)
+5. Use 'type' field as the identifier (like 'tool_summary')
+6. CRITICAL: All imports must be alphabetically sorted to comply with Biome linting
+7. If you are writing zod schemas make them clean. For example if you see z.union([z.string(), z.null()]) write it as z.string().nullable()
+8. The statusComponent() function handles conversion to .config automatically
+
+EXAMPLE:
+import { statusComponent } from '@inkeep/agents-sdk';
+import { z } from 'zod';
+
+export const toolSummary = statusComponent({
+  type: 'tool_summary',
+  description: 'Summary of tool calls and their purpose',
+  detailsSchema: z.object({
+    tool_name: z.string().describe('Name of tool used'),
+    summary: z.string().describe('What was discovered or accomplished'),
+  }),
+});
+
+EXAMPLE WITH HYPHEN TYPE:
+import { statusComponent } from '@inkeep/agents-sdk';
+import { z } from 'zod';
+
+// Component type 'search-progress' becomes export name 'searchProgress'
+export const searchProgress = statusComponent({
+  type: 'search-progress',
+  description: 'Progress of search operation',
+  detailsSchema: z.object({
+    query: z.string().describe('Search query being executed'),
+    results_found: z.number().describe('Number of results found'),
+    time_elapsed: z.number().optional().describe('Time elapsed in milliseconds'),
+  }),
+});
+
+EXAMPLE WITHOUT DETAILS SCHEMA:
+import { statusComponent } from '@inkeep/agents-sdk';
+
+export const simpleStatus = statusComponent({
+  type: 'simple_status',
+  description: 'A simple status with no additional details',
+});
+
+Generate ONLY the TypeScript code without any markdown or explanations.`;
+  const text2 = await generateTextWithPlaceholders(model, componentData, promptTemplate, {
+    temperature: 0.1,
+    maxOutputTokens: 4e3,
+    abortSignal: AbortSignal.timeout(6e4)
+  });
+  writeFileSync3(outputPath, cleanGeneratedCode(text2));
+}
 async function generateEnvironmentFiles(environmentsDir, credentials, environment = "development") {
   const generateCredentialCode = (cred) => {
     const params = [
@@ -235642,6 +235752,18 @@ function collectAllEntities(projectData) {
       entities.push({ id: compId, type: "artifactComponent" });
     }
   }
+  if (projectData.agents) {
+    for (const [_agentId, agentData] of Object.entries(projectData.agents)) {
+      const agentObj = agentData;
+      if (agentObj.statusUpdates?.statusComponents) {
+        for (const statusComp of agentObj.statusUpdates.statusComponents) {
+          if (statusComp.type) {
+            entities.push({ id: statusComp.type, type: "statusComponent" });
+          }
+        }
+      }
+    }
+  }
   if (projectData.credentialReferences) {
     for (const credId of Object.keys(projectData.credentialReferences)) {
       entities.push({ id: credId, type: "credential" });
@@ -235661,6 +235783,7 @@ var init_variable_name_registry = __esm({
       // Usually no suffix needed
       dataComponentSuffix: null,
       artifactComponentSuffix: null,
+      statusComponentSuffix: null,
       credentialSuffix: null
     };
     VariableNameGenerator = class {
@@ -235674,6 +235797,7 @@ var init_variable_name_registry = __esm({
           tools: /* @__PURE__ */ new Map(),
           dataComponents: /* @__PURE__ */ new Map(),
           artifactComponents: /* @__PURE__ */ new Map(),
+          statusComponents: /* @__PURE__ */ new Map(),
           credentials: /* @__PURE__ */ new Map(),
           usedNames: /* @__PURE__ */ new Map()
         };
@@ -235785,6 +235909,8 @@ var init_variable_name_registry = __esm({
             return this.conventions.dataComponentSuffix || "";
           case "artifactComponent":
             return this.conventions.artifactComponentSuffix || "";
+          case "statusComponent":
+            return this.conventions.statusComponentSuffix || "";
           case "credential":
             return this.conventions.credentialSuffix || "";
           default:
@@ -235806,6 +235932,8 @@ var init_variable_name_registry = __esm({
             return this.registry.dataComponents;
           case "artifactComponent":
             return this.registry.artifactComponents;
+          case "statusComponent":
+            return this.registry.statusComponents;
           case "credential":
             return this.registry.credentials;
           default:
@@ -236120,6 +236248,7 @@ function displayPlanSummary(plan) {
     tool: [],
     dataComponent: [],
     artifactComponent: [],
+    statusComponent: [],
     environment: []
   };
   for (const file of plan.files) {
@@ -236172,6 +236301,15 @@ function displayPlanSummary(plan) {
       }
     }
   }
+  if (filesByType.statusComponent.length > 0) {
+    console.log(chalk7.gray("\n  Status Components:"));
+    for (const file of filesByType.statusComponent) {
+      console.log(chalk7.gray(`    \u2022 ${file.path}`));
+      for (const entity of file.entities) {
+        console.log(chalk7.gray(`        - ${entity.variableName}`));
+      }
+    }
+  }
   if (filesByType.environment.length > 0) {
     console.log(chalk7.gray("\n  Environments:"));
     for (const file of filesByType.environment) {
@@ -236193,7 +236331,9 @@ function displayPatternSummary(patterns) {
   console.log(chalk7.gray(`    \u2022 Agent suffix: "${patterns.namingConventions.agentSuffix}"`));
   console.log(chalk7.gray(`    \u2022 SubAgent suffix: "${patterns.namingConventions.subAgentSuffix}"`));
   if (patterns.examples.mappings && patterns.examples.mappings.length > 0) {
-    console.log(chalk7.gray(`  Found ${patterns.examples.mappings.length} existing variable mappings`));
+    console.log(
+      chalk7.gray(`  Found ${patterns.examples.mappings.length} existing variable mappings`)
+    );
   }
 }
 function displayRecommendedPattern() {
@@ -236300,10 +236440,7 @@ async function generatePlan(projectData, patterns, modelSettings, createModel2)
     nameGenerator.generateVariableName(entity.id, entity.type);
   }
   const model = createModel2(modelSettings);
-  const promptTemplate = createPlanningPromptTemplate(
-    nameGenerator.getRegistry(),
-    allEntities
-  );
+  const promptTemplate = createPlanningPromptTemplate(nameGenerator.getRegistry(), allEntities);
   const promptData = {
     projectData,
     patterns
@@ -236353,28 +236490,42 @@ CRITICAL RULES:
 1. TOOL TYPES - VERY IMPORTANT:
    - **Function Tools** (type: "function"): ALWAYS define INLINE within agent files using "inlineContent" array
    - **MCP Tools** (type: "mcp"): Create separate files in tools/ directory
-   - VALID FILE TYPES: Only use these exact types: "agent", "tool", "dataComponent", "artifactComponent", "environment", "index"
+   - VALID FILE TYPES: Only use these exact types: "agent", "tool", "dataComponent", "artifactComponent", "statusComponent", "environment", "index"
    - NEVER create file type "functionTool" - function tools go in "inlineContent" of agent files
 
-2. File Structure:
+2. STATUS COMPONENTS - VERY IMPORTANT:
+   - **Status Components**: ALWAYS create separate files in status-components/ directory
+   - Status components are found in agent.statusUpdates.statusComponents array
+   - Each status component should get its own file
+   - Agents must import status components from status-components/ directory
+   - Status components are NEVER inlined in agent files
+
+3. File Structure:
    - If patterns show "toolsLocation": "inline", ALL tools should be in "inlineContent" of agent files
    - If patterns show "toolsLocation": "separate", MCP tools get separate files, function tools still inline
    - Follow the detected file naming convention (kebab-case, camelCase, or snake_case)
 
-3. Variable Names:
+4. Variable Names:
    - MUST use the exact variable names from the mappings above
    - If ID "weather" is used by both agent and subAgent, they will have different variable names
    - Do NOT generate new variable names - use what's provided
 
-4. File Placement:
+5. File Placement:
    - agents/ directory: Agent files (with function tools in "inlineContent")
    - tools/ directory: MCP tool files only
    - data-components/ directory: Data component files
    - artifact-components/ directory: Artifact component files
+   - status-components/ directory: Status component files
    - environments/ directory: Environment/credential files
    - index.ts: Main project file
 
-5. Dependencies:
+6. File Paths (CRITICAL):
+   - Paths MUST be relative to the project root directory
+   - DO NOT include the project name in the path
+   - CORRECT: "agents/weather-agent.ts", "tools/inkeep-facts.ts", "status-components/tool-summary.ts"
+   - WRONG: "my-project/agents/weather-agent.ts", "project-name/tools/inkeep-facts.ts"
+
+7. Dependencies:
    - Each file should list which variables it needs to import from other files
    - Imports should use relative paths
    - Respect detected import style (named vs default)
@@ -236429,6 +236580,20 @@ OUTPUT FORMAT (JSON):
       "dependencies": [],
       "inlineContent": null
     },
+    {
+      "path": "status-components/tool-summary.ts",
+      "type": "statusComponent",
+      "entities": [
+        {
+          "id": "tool_summary",
+          "variableName": "toolSummary",
+          "entityType": "statusComponent",
+          "exportName": "toolSummary"
+        }
+      ],
+      "dependencies": [],
+      "inlineContent": null
+    },
     {
       "path": "index.ts",
       "type": "index",
@@ -236466,6 +236631,7 @@ function formatVariableMappings(registry2, allEntities) {
     tool: [],
     dataComponent: [],
     artifactComponent: [],
+    statusComponent: [],
     credential: []
   };
   for (const entity of allEntities) {
@@ -236500,6 +236666,8 @@ function getRegistryMap(registry2, entityType) {
       return registry2.dataComponents;
     case "artifactComponent":
       return registry2.artifactComponents;
+    case "statusComponent":
+      return registry2.statusComponents;
     case "credential":
       return registry2.credentials;
     default:
@@ -236582,6 +236750,21 @@ function generateDefaultPlan(registry2) {
       dependencies: []
     });
   }
+  for (const [compId, variableName] of registry2.statusComponents.entries()) {
+    files.push({
+      path: `status-components/${kebabCase(compId)}.ts`,
+      type: "statusComponent",
+      entities: [
+        {
+          id: compId,
+          variableName,
+          entityType: "statusComponent",
+          exportName: variableName
+        }
+      ],
+      dependencies: []
+    });
+  }
   files.push({
     path: "index.ts",
     type: "index",
@@ -236617,14 +236800,18 @@ async function generateFilesFromPlan(plan, projectData, dirs, modelSettings, deb
     (fileInfo, index2) => generateFile(fileInfo, projectData, plan, dirs, modelSettings, debug).then(() => {
       if (debug) {
         const elapsed = ((Date.now() - startTime) / 1e3).toFixed(1);
-        console.log(`[DEBUG] \u2713 Completed ${index2 + 1}/${plan.files.length}: ${fileInfo.path} (${elapsed}s elapsed)`);
+        console.log(
+          `[DEBUG] \u2713 Completed ${index2 + 1}/${plan.files.length}: ${fileInfo.path} (${elapsed}s elapsed)`
+        );
       }
     })
   );
   await Promise.all(tasks2);
   const totalTime = ((Date.now() - startTime) / 1e3).toFixed(1);
   if (debug) {
-    console.log(`[DEBUG] All files generated in ${totalTime}s (${plan.files.length} files in parallel)`);
+    console.log(
+      `[DEBUG] All files generated in ${totalTime}s (${plan.files.length} files in parallel)`
+    );
   }
 }
 async function generateFile(fileInfo, projectData, plan, dirs, modelSettings, debug) {
@@ -236662,7 +236849,9 @@ async function generateFile(fileInfo, projectData, plan, dirs, modelSettings, de
     writeFileSync4(outputPath, cleanedCode);
     const totalDuration = ((Date.now() - fileStartTime) / 1e3).toFixed(1);
     if (debug) {
-      console.log(`[DEBUG] \u2713 Completed: ${fileInfo.path} (LLM: ${llmDuration}s, Total: ${totalDuration}s)`);
+      console.log(
+        `[DEBUG] \u2713 Completed: ${fileInfo.path} (LLM: ${llmDuration}s, Total: ${totalDuration}s)`
+      );
     }
   } catch (error) {
     console.error(`[ERROR] Failed to generate ${fileInfo.path}:`, error.message);
@@ -236701,6 +236890,21 @@ function extractDataForFile(fileInfo, projectData) {
       }
       return {};
     }
+    case "statusComponent": {
+      const statusType = fileInfo.entities[0]?.id;
+      if (statusType && projectData.agents) {
+        for (const agentData of Object.values(projectData.agents)) {
+          const agent = agentData;
+          if (agent.statusUpdates?.statusComponents) {
+            const found = agent.statusUpdates.statusComponents.find(
+              (sc) => sc.type === statusType
+            );
+            if (found) return found;
+          }
+        }
+      }
+      return {};
+    }
     case "environment":
       return projectData.credentialReferences || {};
     default:
@@ -236756,11 +236960,13 @@ CRITICAL RULES:
       return createDataComponentPrompt(fileData, context, registryInfo, commonInstructions);
     case "artifactComponent":
       return createArtifactComponentPrompt(fileData, context, registryInfo, commonInstructions);
+    case "statusComponent":
+      return createStatusComponentPrompt(fileData, context, registryInfo, commonInstructions);
     default:
       throw new Error(`Unknown file type: ${fileInfo.type}`);
   }
 }
-function createIndexPrompt(projectData, context, registryInfo, commonInstructions) {
+function createIndexPrompt(_projectData, context, _registryInfo, commonInstructions) {
   const importMappings = generateImportMappings(context.plan);
   return `Generate index.ts for Inkeep project.
 
@@ -236787,7 +236993,7 @@ export const myProject = project({
 
 Generate ONLY the TypeScript code without markdown.`;
 }
-function createAgentPrompt(agentData, context, registryInfo, commonInstructions) {
+function createAgentPrompt(_agentData, context, _registryInfo, commonInstructions) {
   const inlineTools = context.fileInfo.inlineContent || [];
   const hasInlineTools = inlineTools.length > 0;
   return `Generate TypeScript file for Inkeep agent.
@@ -236841,17 +237047,62 @@ const calculateBMI = functionTool({
 ` : ""}
 
 IMPORTS (CRITICAL - MUST BE FIRST):
-ALWAYS import these from '@inkeep/agents-sdk' at the TOP of the file:
-import { agent, subAgent, functionTool } from '@inkeep/agents-sdk';
+ALWAYS import these at the TOP of the file:
+- import { agent, subAgent, functionTool } from '@inkeep/agents-sdk';
+- import { z } from 'zod'; (REQUIRED when using ANY Zod schemas like responseSchema, headersSchema)
+- import { contextConfig, fetchDefinition, headers } from '@inkeep/agents-core'; (REQUIRED when agent has contextConfig)
+- import status components from '../status-components/' when needed
 
 SUBAGENT AND AGENT API (CRITICAL):
 - Use 'canUse' (NOT 'tools') - must be a FUNCTION returning array
 - Use 'canDelegateTo' - must be a FUNCTION returning array
 - Use 'dataComponents' - must be a FUNCTION returning array
 - Use 'subAgents' in agent() - must be a FUNCTION returning array
-- For multi-line strings (like 'prompt'), ALWAYS use template literals (backticks \`...\`)
+
+CONTEXT CONFIG (CRITICAL - NO PLAIN OBJECTS):
+- NEVER use plain objects for contextConfig
+- ALWAYS use helper functions: headers(), fetchDefinition(), contextConfig()
+- Create separate const variables for each helper before the agent definition
+- Pattern:
+  const myHeaders = headers({ schema: z.object({ api_key: z.string() }) });
+  const myFetch = fetchDefinition({ id: '...', fetchConfig: {...}, responseSchema: z.object({...}) });
+  const myContext = contextConfig({ headers: myHeaders, contextVariables: { data: myFetch } });
+  export const myAgent = agent({ contextConfig: myContext });
+- Use myHeaders.toTemplate('key_name') for header values in fetchConfig
+- Use myContext.toTemplate('variable.field') for prompt interpolation
+
+STRING LITERALS (CRITICAL - MUST FOLLOW):
+- For STRING VALUES: ALWAYS use template literals (backticks \`)
+- This includes: prompt, description, query, url, method, body, defaultValue, etc.
+- Template literals prevent syntax errors with apostrophes (don't, user's, it's)
+- For object keys that are identifiers (no hyphens), omit quotes: Authorization not 'Authorization'
+- For object keys with hyphens, use quotes: 'Content-Type'
+
+EXCEPTION - Schema Fields (NO template literals):
+- headersSchema: z.object({ ... }) (raw Zod code, NOT a string)
+- responseSchema: z.object({ ... }) (raw Zod code, NOT a string)
+- These are TypeScript expressions, not string values
+
+CORRECT EXAMPLES:
+\u2705 prompt: \`You are a helpful assistant.\` (string value)
+\u2705 query: \`query GetData { field }\` (string value)
+\u2705 responseSchema: z.object({ name: z.string() }) (Zod code, NO backticks)
+\u2705 headersSchema: z.object({ 'inkeep_api_key': z.string() }) (Zod code, NO backticks)
+
+WRONG EXAMPLES:
+\u274C prompt: 'You are a helpful assistant.' (use backticks not single quotes)
+\u274C responseSchema: \`z.object({ name: z.string() })\` (don't wrap Zod in backticks)
+
+STATUS COMPONENTS (CRITICAL):
+- Status components are ALWAYS imported from '../status-components/' directory
+- In statusUpdates.statusComponents array, use statusComponent.config to get the config object
+- NEVER inline status component definitions in the agent file
+- Example: import { toolSummary } from '../status-components/tool-summary'
+- Then use: statusComponents: [toolSummary.config]
 
 \u2705 CORRECT:
+import { toolSummary } from '../status-components/tool-summary';
+
 const weatherSubAgent = subAgent({
   id: 'weather',
   name: 'Weather Sub',
@@ -236868,7 +237119,12 @@ const weatherAgent = agent({
   id: 'weather',
   name: 'Weather Agent',
   defaultSubAgent: weatherSubAgent,
-  subAgents: () => [weatherSubAgent]  // FUNCTION returning array
+  subAgents: () => [weatherSubAgent],  // FUNCTION returning array
+  statusUpdates: {
+    numEvents: 1,
+    timeInSeconds: 1,
+    statusComponents: [toolSummary.config]  // Use .config
+  }
 });
 
 \u274C WRONG:
@@ -236877,10 +237133,11 @@ string',  // NO - use backticks for multi-line
 tools: [tool1, tool2],  // NO - use 'canUse' not 'tools'
 canUse: [tool1, tool2],  // NO - must be a function
 subAgents: [weatherSubAgent],  // NO - must be a function
+statusComponents: [{ type: '...', ... }],  // NO - import from files
 
 Generate ONLY the TypeScript code without markdown.`;
 }
-function createToolPrompt(toolData, context, registryInfo, commonInstructions) {
+function createToolPrompt(_toolData, _context, _registryInfo, commonInstructions) {
   return `Generate TypeScript file for Inkeep tool.
 
 TOOL DATA:
@@ -236896,7 +237153,7 @@ REQUIREMENTS:
 
 Generate ONLY the TypeScript code without markdown.`;
 }
-function createDataComponentPrompt(componentData, context, registryInfo, commonInstructions) {
+function createDataComponentPrompt(_componentData, _context, _registryInfo, commonInstructions) {
   return `Generate TypeScript file for Inkeep data component.
 
 COMPONENT DATA:
@@ -236952,7 +237209,7 @@ REQUIREMENTS:
 
 Generate ONLY the TypeScript code without markdown.`;
 }
-function createArtifactComponentPrompt(componentData, context, registryInfo, commonInstructions) {
+function createArtifactComponentPrompt(_componentData, _context, _registryInfo, commonInstructions) {
   return `Generate TypeScript file for Inkeep artifact component.
 
 COMPONENT DATA:
@@ -236969,7 +237226,38 @@ REQUIREMENTS:
 
 Generate ONLY the TypeScript code without markdown.`;
 }
-function formatRegistryForFile(fileInfo, registry2) {
+function createStatusComponentPrompt(_componentData, _context, _registryInfo, commonInstructions) {
+  return `Generate TypeScript file for Inkeep status component.
+
+COMPONENT DATA:
+{{DATA}}
+
+${commonInstructions}
+
+REQUIREMENTS:
+1. Import statusComponent from '@inkeep/agents-sdk'
+2. Import z from 'zod' for schema definitions if detailsSchema is present
+3. Use exact variable name from registry
+4. Convert any JSON Schema in detailsSchema to Zod schema
+5. Use 'type' field as the identifier
+6. The statusComponent() function handles .config conversion automatically
+
+EXAMPLE:
+import { statusComponent } from '@inkeep/agents-sdk';
+import { z } from 'zod';
+
+export const toolSummary = statusComponent({
+  type: 'tool_summary',
+  description: 'Summary of tool calls',
+  detailsSchema: z.object({
+    tool_name: z.string().describe('Name of tool used'),
+    summary: z.string().describe('What was accomplished'),
+  }),
+});
+
+Generate ONLY the TypeScript code without markdown.`;
+}
+function formatRegistryForFile(fileInfo, _registry) {
   let result = "Entities in this file:\n";
   for (const entity of fileInfo.entities) {
     result += `  - ${entity.entityType} "${entity.id}" \u2192 variable: ${entity.variableName}
@@ -237635,9 +237923,7 @@ async function configGetCommand(key, options) {
   if (!existsSync(configPath)) {
     console.error(chalk2.red("No configuration file found."));
     console.log(
-      chalk2.gray(
-        'Run "inkeep init" to create one, or specify a config file with --config'
-      )
+      chalk2.gray('Run "inkeep init" to create one, or specify a config file with --config')
     );
     process.exit(1);
   }
@@ -238264,7 +238550,9 @@ async function detectCurrentProject(debug = false) {
         if (typeof value.getId === "function") {
           const projectId = value.getId();
           if (debug) {
-            console.log(chalk8.gray(`  \u2022 Project detected: ${projectId} (from export: ${exportKey})`));
+            console.log(
+              chalk8.gray(`  \u2022 Project detected: ${projectId} (from export: ${exportKey})`)
+            );
           }
           return projectId;
         }
@@ -238282,7 +238570,7 @@ async function detectCurrentProject(debug = false) {
     try {
       const content = readFileSync5(indexPath, "utf-8");
       const projectIdMatch = content.match(/project\s*\(\s*\{\s*id\s*:\s*['"]([^'"]+)['"]/);
-      if (projectIdMatch && projectIdMatch[1]) {
+      if (projectIdMatch?.[1]) {
         const projectId = projectIdMatch[1];
         if (debug) {
           console.log(chalk8.gray(`  \u2022 Project ID extracted from static parse: ${projectId}`));
@@ -238315,7 +238603,7 @@ async function verifyGeneratedFiles(projectDir, originalProjectData, debug = fal
       errors.push("index.ts does not contain a project() call");
     }
     const projectIdMatch = indexContent.match(/project\s*\(\s*\{\s*id\s*:\s*['"]([^'"]+)['"]/);
-    if (projectIdMatch && projectIdMatch[1]) {
+    if (projectIdMatch?.[1]) {
       const extractedProjectId = projectIdMatch[1];
       if (extractedProjectId !== originalProjectData.id) {
         warnings.push(
@@ -238332,31 +238620,36 @@ async function verifyGeneratedFiles(projectDir, originalProjectData, debug = fal
     const agentsDir = join9(projectDir, "agents");
     const expectedAgents = Object.keys(originalProjectData.agents || {});
     for (const agentId of expectedAgents) {
-      const agentPath = join9(agentsDir, `${agentId}.ts`);
+      const kebabCaseId = agentId.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+      const agentPath = join9(agentsDir, `${kebabCaseId}.ts`);
       if (!existsSync8(agentPath)) {
-        errors.push(`Agent file not found: agents/${agentId}.ts`);
+        errors.push(`Agent file not found: agents/${kebabCaseId}.ts`);
       } else if (debug) {
-        console.log(chalk8.gray(`  \u2713 Agent file exists: agents/${agentId}.ts`));
+        console.log(chalk8.gray(`  \u2713 Agent file exists: agents/${kebabCaseId}.ts`));
       }
     }
     const toolsDir = join9(projectDir, "tools");
     const expectedTools = Object.keys(originalProjectData.tools || {});
     for (const toolId of expectedTools) {
-      const toolPath = join9(toolsDir, `${toolId}.ts`);
+      const kebabCaseId = toolId.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+      const toolPath = join9(toolsDir, `${kebabCaseId}.ts`);
       if (!existsSync8(toolPath)) {
-        errors.push(`Tool file not found: tools/${toolId}.ts`);
+        errors.push(`Tool file not found: tools/${kebabCaseId}.ts`);
       } else if (debug) {
-        console.log(chalk8.gray(`  \u2713 Tool file exists: tools/${toolId}.ts`));
+        console.log(chalk8.gray(`  \u2713 Tool file exists: tools/${kebabCaseId}.ts`));
       }
     }
     const dataComponentsDir = join9(projectDir, "data-components");
     const expectedDataComponents = Object.keys(originalProjectData.dataComponents || {});
     for (const componentId of expectedDataComponents) {
-      const componentPath = join9(dataComponentsDir, `${componentId}.ts`);
+      const kebabCaseId = componentId.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+      const componentPath = join9(dataComponentsDir, `${kebabCaseId}.ts`);
       if (!existsSync8(componentPath)) {
-        errors.push(`Data component file not found: data-components/${componentId}.ts`);
+        errors.push(`Data component file not found: data-components/${kebabCaseId}.ts`);
       } else if (debug) {
-        console.log(chalk8.gray(`  \u2713 Data component file exists: data-components/${componentId}.ts`));
+        console.log(
+          chalk8.gray(`  \u2713 Data component file exists: data-components/${kebabCaseId}.ts`)
+        );
       }
     }
     const environmentsDir = join9(projectDir, "environments");
@@ -238382,8 +238675,12 @@ async function verifyGeneratedFiles(projectDir, originalProjectData, debug = fal
     if (debug) {
       console.log(chalk8.gray("\n\u{1F50D} Verification Summary:"));
       console.log(chalk8.gray(`  \u2022 index.ts: ${existsSync8(indexPath) ? "\u2713" : "\u2717"}`));
-      console.log(chalk8.gray(`  \u2022 Agent files: ${expectedAgents.length}/${expectedAgents.length} found`));
-      console.log(chalk8.gray(`  \u2022 Tool files: ${expectedTools.length}/${expectedTools.length} found`));
+      console.log(
+        chalk8.gray(`  \u2022 Agent files: ${expectedAgents.length}/${expectedAgents.length} found`)
+      );
+      console.log(
+        chalk8.gray(`  \u2022 Tool files: ${expectedTools.length}/${expectedTools.length} found`)
+      );
       console.log(
         chalk8.gray(
           `  \u2022 Data component files: ${expectedDataComponents.length}/${expectedDataComponents.length} found`
@@ -238439,12 +238736,14 @@ function createProjectStructure(projectDir, projectId, useCurrentDirectory = fal
   const toolsDir = join9(projectRoot, "tools");
   const dataComponentsDir = join9(projectRoot, "data-components");
   const artifactComponentsDir = join9(projectRoot, "artifact-components");
+  const statusComponentsDir = join9(projectRoot, "status-components");
   const environmentsDir = join9(projectRoot, "environments");
   ensureDirectoryExists(projectRoot);
   ensureDirectoryExists(agentsDir);
   ensureDirectoryExists(toolsDir);
   ensureDirectoryExists(dataComponentsDir);
   ensureDirectoryExists(artifactComponentsDir);
+  ensureDirectoryExists(statusComponentsDir);
   ensureDirectoryExists(environmentsDir);
   return {
     projectRoot,
@@ -238452,6 +238751,7 @@ function createProjectStructure(projectDir, projectId, useCurrentDirectory = fal
     toolsDir,
     dataComponentsDir,
     artifactComponentsDir,
+    statusComponentsDir,
     environmentsDir
   };
 }
@@ -238628,6 +238928,11 @@ async function pullProjectCommand(options) {
     }, 0);
     const dataComponentCount = Object.keys(projectData.dataComponents || {}).length;
     const artifactComponentCount = Object.keys(projectData.artifactComponents || {}).length;
+    const statusComponentCount = Object.values(projectData.agents || {}).reduce((total, agent) => {
+      const agentObj = agent;
+      const statusComponents = agentObj.statusUpdates?.statusComponents || [];
+      return total + statusComponents.length;
+    }, 0);
     console.log(chalk8.cyan("\n\u{1F4CA} Project Summary:"));
     console.log(chalk8.gray(`  \u2022 Name: ${projectData.name}`));
     console.log(chalk8.gray(`  \u2022 Description: ${projectData.description || "No description"}`));
@@ -238640,6 +238945,9 @@ async function pullProjectCommand(options) {
     if (artifactComponentCount > 0) {
       console.log(chalk8.gray(`  \u2022 Artifact Components: ${artifactComponentCount}`));
     }
+    if (statusComponentCount > 0) {
+      console.log(chalk8.gray(`  \u2022 Status Components: ${statusComponentCount}`));
+    }
     const credentialReferences2 = projectData.credentialReferences || {};
     const credentialCount = Object.keys(credentialReferences2).length;
     if (credentialCount > 0) {
@@ -238738,13 +239046,19 @@ async function pullProjectCommand(options) {
     if (options.debug) {
       console.log(chalk8.gray("\n\u{1F4CD} Plan saved to .inkeep/generation-plan.json"));
     }
+    const statusComponentsCount = Object.values(projectData.agents || {}).reduce((total, agent) => {
+      const agentObj = agent;
+      const statusComponents = agentObj.statusUpdates?.statusComponents || [];
+      return total + statusComponents.length;
+    }, 0);
     const fileCount = {
       agents: Object.keys(projectData.agents || {}).length,
       tools: Object.keys(projectData.tools || {}).length,
       dataComponents: Object.keys(projectData.dataComponents || {}).length,
-      artifactComponents: Object.keys(projectData.artifactComponents || {}).length
+      artifactComponents: Object.keys(projectData.artifactComponents || {}).length,
+      statusComponents: statusComponentsCount
     };
-    const totalFiles = fileCount.agents + fileCount.tools + fileCount.dataComponents + fileCount.artifactComponents + 5;
+    const totalFiles = fileCount.agents + fileCount.tools + fileCount.dataComponents + fileCount.artifactComponents + fileCount.statusComponents + 5;
     spinner.succeed(`Project files generated (${totalFiles} files created)`);
     spinner.start("Verifying generated files...");
     try {
@@ -238801,6 +239115,9 @@ async function pullProjectCommand(options) {
     if (fileCount.artifactComponents > 0) {
       console.log(chalk8.gray(`  \u251C\u2500\u2500 artifact-components/ (${fileCount.artifactComponents} files)`));
     }
+    if (fileCount.statusComponents > 0) {
+      console.log(chalk8.gray(`  \u251C\u2500\u2500 status-components/ (${fileCount.statusComponents} files)`));
+    }
     console.log(chalk8.gray("  \u2514\u2500\u2500 environments/ (4 files)"));
     console.log(chalk8.cyan("\n\u{1F4DD} Next steps:"));
     console.log(chalk8.gray(`  \u2022 cd ${dirs.projectRoot}`));
@@ -238964,9 +239281,12 @@ async function pushCommand(options) {
         console.log(chalk9.gray(`  \u2022 Size: ${JSON.stringify(projectDefinition).length} bytes`));
         const agentCount = Object.keys(projectDefinition.agents || {}).length;
         const toolCount = Object.keys(projectDefinition.tools || {}).length;
-        const subAgentCount = Object.values(projectDefinition.agents || {}).reduce((total, agent) => {
-          return total + Object.keys(agent.subAgents || {}).length;
-        }, 0);
+        const subAgentCount = Object.values(projectDefinition.agents || {}).reduce(
+          (total, agent) => {
+            return total + Object.keys(agent.subAgents || {}).length;
+          },
+          0
+        );
         console.log(chalk9.cyan("\n\u{1F4CA} Project Data Summary:"));
         console.log(chalk9.gray(`  \u2022 Agent: ${agentCount}`));
         console.log(chalk9.gray(`  \u2022 Tools: ${toolCount}`));
@@ -239088,7 +239408,7 @@ program.command("chat [agent-id]").description(
   const config = options.config || options.configFilePath;
   await chatCommandEnhanced2(agentId, { ...options, config });
 });
-program.command("list-agent").description("List all available agent for a specific project").requiredOption("--project <project-id>", "Project ID to list agent for").option("--tenant-id <tenant-id>", "Tenant ID").option("--agents-manage-api-url <url>", "Agents manage API URL").option("--config <path>", "Path to configuration file").option("--config-file-path <path>", "Path to configuration file (deprecated, use --config)").action(async (options) => {
+program.command("list-agent").description("List all available agents for a specific project").requiredOption("--project <project-id>", "Project ID to list agent for").option("--tenant-id <tenant-id>", "Tenant ID").option("--agents-manage-api-url <url>", "Agents manage API URL").option("--config <path>", "Path to configuration file").option("--config-file-path <path>", "Path to configuration file (deprecated, use --config)").action(async (options) => {
   const config = options.config || options.configFilePath;
   await listAgentsCommand({ ...options, config });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkeep/agents-cli",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Inkeep CLI tool",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,8 +46,8 @@
     "recast": "^0.23.0",
     "ts-morph": "^26.0.0",
     "tsx": "^4.20.5",
-    "@inkeep/agents-core": "^0.21.1",
-    "@inkeep/agents-sdk": "^0.21.1"
+    "@inkeep/agents-core": "^0.22.0",
+    "@inkeep/agents-sdk": "^0.22.0"
   },
   "devDependencies": {
     "@types/degit": "^2.8.6",