@standardagents/cli 0.12.0-next.30cb17a → 0.12.0

package/dist/index.js

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import fs3, { readFileSync } from 'fs';
-import path3, { dirname, resolve } from 'path';
-import { fileURLToPath } from 'url';
+import path3 from 'path';
+import fs3 from 'fs';
 import crypto from 'crypto';
 import readline from 'readline';
 import { spawn } from 'child_process';
@@ -11,6 +10,7 @@ import { parse, modify, applyEdits } from 'jsonc-parser';
 import { loadFile, writeFile, generateCode } from 'magicast';
 import { addVitePlugin } from 'magicast/helpers';
 import net from 'net';
+import { fileURLToPath } from 'url';
 
 var logger = {
   success: (message) => {
@@ -116,34 +116,48 @@ agents/
 
 Files are **auto-discovered** at runtime. No manual registration needed.
 
-## FlowState
+## ThreadState
 
-\`FlowState\` is the central state object available in tools and hooks:
+\`ThreadState\` is the state object available in tools and hooks:
 
 \`\`\`typescript
-interface FlowState {
-  thread: {
-    id: string;           // Thread identifier
-    instance: DurableThread;  // Durable Object instance
-  };
-  agent: AgentConfig;     // Current agent configuration
-  prompt: PromptConfig;   // Current prompt configuration
-  model: ModelConfig;     // Current model configuration
-  messages: Message[];    // Conversation history
-  env: Env;               // Cloudflare Worker environment
-  rootState: FlowState;   // Parent state (for sub-prompts)
+interface ThreadState {
+  // Identity (readonly)
+  threadId: string;           // Thread identifier
+  agentId: string;            // Agent identifier
+  userId: string | null;      // User identifier (if set)
+  createdAt: number;          // Creation timestamp
+
+  // Methods
+  getMessages(options?): Promise<MessagesResult>;  // Get conversation history
+  injectMessage(input): Promise<Message>;          // Add message to thread
+  loadModel(name): Promise<ModelConfig>;           // Load model definition
+  loadPrompt(name): Promise<PromptConfig>;         // Load prompt definition
+  loadAgent(name): Promise<AgentConfig>;           // Load agent definition
 }
 \`\`\`
 
 Access in tools:
 \`\`\`typescript
-export default defineTool('...', schema, async (flow, args) => {
-  const threadId = flow.thread.id;
-  const messages = flow.messages;
+export default defineTool('...', schema, async (state, args) => {
+  const threadId = state.threadId;
+  const { messages } = await state.getMessages();
   // ...
 });
 \`\`\`
 
+Access in hooks:
+\`\`\`typescript
+export default defineHook({
+  hook: 'before_create_message',
+  id: 'my_hook',
+  execute: async (state, message) => {
+    console.log(\`Thread: \${state.threadId}, Agent: \${state.agentId}\`);
+    return message;
+  }
+});
+\`\`\`
+
 ## Quick Reference
 
 | Function | Purpose | Directory |
@@ -178,7 +192,7 @@ Full documentation: https://docs.standardagentbuilder.com
 - [Agents](https://docs.standardagentbuilder.com/core-concepts/agents)
 - [Tools](https://docs.standardagentbuilder.com/core-concepts/tools)
 - [Hooks](https://docs.standardagentbuilder.com/core-concepts/hooks)
-- [FlowState](https://docs.standardagentbuilder.com/core-concepts/flowstate)
+- [ThreadState](https://docs.standardagentbuilder.com/core-concepts/threadstate)
 - [Thread API](https://docs.standardagentbuilder.com/core-concepts/api)
 `;
 
@@ -289,6 +303,7 @@ Prompts define system instructions, model selection, and available tools for LLM
 | \`parallelToolCalls\` | \`boolean\` | No | Allow multiple concurrent tool calls |
 | \`toolChoice\` | \`'auto' \\| 'none' \\| 'required'\` | No | Tool calling strategy |
 | \`requiredSchema\` | \`z.ZodObject\` | No | Input validation when called as tool |
+| \`hooks\` | \`string[]\` | No | Hook IDs to run for this prompt (overrides agent hooks) |
 | \`reasoning\` | \`ReasoningConfig\` | No | Extended thinking configuration |
 
 ## Basic Example
@@ -387,6 +402,22 @@ reasoning: {
 },
 \`\`\`
 
+## Hooks
+
+Attach lifecycle hooks to a prompt:
+
+\`\`\`typescript
+export default definePrompt({
+  name: 'customer_support',
+  toolDescription: 'Handle customer support',
+  model: 'default',
+  prompt: 'You are a support agent...',
+  hooks: ['limit_to_20', 'redact_pii'],  // Hook IDs from agents/hooks/
+});
+\`\`\`
+
+Prompt hooks take precedence over agent hooks. See \`agents/hooks/CLAUDE.md\` for details.
+
 ## Best Practices
 
 - **Write clear instructions** - Structure with headers and bullet points
@@ -416,6 +447,7 @@ Agents orchestrate conversations by defining prompts, stop conditions, and turn
 | \`maxSessionTurns\` | \`number\` | No | Max total turns across both sides |
 | \`exposeAsTool\` | \`boolean\` | No | Allow other prompts to hand off to this agent |
 | \`toolDescription\` | \`string\` | No | Description when used as tool (required if exposeAsTool) |
+| \`hooks\` | \`string[]\` | No | Hook IDs to run for this agent (fallback if prompt has no hooks) |
 | \`tags\` | \`string[]\` | No | Tags for categorization and filtering |
 
 ## Side Configuration
@@ -498,6 +530,23 @@ Other prompts can then include the agent name in their \`tools\` array to enable
 4. **stopOnResponse** - Ends turn when LLM returns text
 5. **maxSessionTurns** - Ends conversation (hard limit: 250)
 
+## Hooks
+
+Attach lifecycle hooks at the agent level:
+
+\`\`\`typescript
+export default defineAgent({
+  name: 'support_agent',
+  type: 'ai_human',
+  hooks: ['log_all_messages', 'sanitize_results'],
+  sideA: {
+    prompt: 'customer_support',
+  },
+});
+\`\`\`
+
+Agent hooks run as a fallback when the active prompt has no hooks defined. Prompt hooks always take precedence. See \`agents/hooks/CLAUDE.md\` for details.
+
 ## Naming Convention
 
 Agent names **must** end with the \`_agent\` suffix (e.g., \`support_agent\`, \`research_agent\`).
@@ -525,12 +574,12 @@ Tools extend agent capabilities beyond text generation. They allow LLMs to fetch
 ## Function Signature
 
 \`\`\`typescript
-defineTool(
+defineTool({
   description: string,           // What the tool does (shown to LLM)
-  args: z.ZodObject,             // Input validation schema
-  handler: (flow, args) => ToolResult,  // Implementation
-  returnSchema?: z.ZodObject     // Optional output schema
-)
+  args?: z.ZodObject,            // Input validation schema (optional)
+  execute: (state, args) => ToolResult,  // Implementation
+  tenvs?: z.ZodObject,           // Thread environment variables (optional)
+})
 \`\`\`
 
 ## Basic Example
@@ -539,20 +588,20 @@ defineTool(
 import { defineTool } from '@standardagents/builder';
 import { z } from 'zod';
 
-export default defineTool(
-  'Search the knowledge base for articles matching a query',
-  z.object({
+export default defineTool({
+  description: 'Search the knowledge base for articles matching a query',
+  args: z.object({
     query: z.string().describe('Search query'),
     limit: z.number().optional().default(10).describe('Max results'),
   }),
-  async (flow, args) => {
+  execute: async (state, args) => {
     const results = await searchKB(args.query, args.limit);
     return {
       status: 'success',
       result: JSON.stringify(results),
     };
-  }
-);
+  },
+});
 \`\`\`
 
 ## ToolResult Interface
@@ -562,44 +611,45 @@ export default defineTool(
 | \`status\` | \`'success' \\| 'error'\` | Whether the tool succeeded |
 | \`result\` | \`string\` | Tool output (required for success) |
 | \`error\` | \`string\` | Error message (for error status) |
+| \`attachments\` | \`ToolAttachment[]\` | Files to attach (images, etc.) |
 
-## FlowState Access
+## ThreadState Access
 
-The \`flow\` parameter provides access to:
+The \`state\` parameter provides access to:
 
 \`\`\`typescript
-async (flow, args) => {
+execute: async (state, args) => {
   // Thread information
-  const threadId = flow.thread.id;
-  const thread = flow.thread.instance;
+  const threadId = state.thread.id;
+  const thread = state.thread.instance;
 
   // Configuration
-  const agentName = flow.agent.name;
-  const modelName = flow.model.name;
+  const agentName = state.agent.name;
+  const modelName = state.model.name;
 
   // Message history
-  const messages = flow.messages;
+  const messages = state.messages;
 
   // Environment bindings
-  const env = flow.env;
+  const env = state.env;
 
   // Parent state (for sub-prompts)
-  const root = flow.rootState;
+  const root = state.rootState;
 }
 \`\`\`
 
 ## Tool Without Arguments
 
 \`\`\`typescript
-export default defineTool(
-  'Get current server time',
-  async (flow) => {
+export default defineTool({
+  description: 'Get current server time',
+  execute: async (state) => {
     return {
       status: 'success',
       result: new Date().toISOString(),
     };
-  }
-);
+  },
+});
 \`\`\`
 
 ## Error Handling
@@ -607,10 +657,10 @@ export default defineTool(
 Return errors gracefully instead of throwing:
 
 \`\`\`typescript
-export default defineTool(
-  'Fetch user data',
-  z.object({ userId: z.string() }),
-  async (flow, args) => {
+export default defineTool({
+  description: 'Fetch user data',
+  args: z.object({ userId: z.string() }),
+  execute: async (state, args) => {
     try {
       const user = await fetchUser(args.userId);
       return { status: 'success', result: JSON.stringify(user) };
@@ -620,8 +670,8 @@ export default defineTool(
         error: \`Failed to fetch user: \${error.message}\`,
       };
     }
-  }
-);
+  },
+});
 \`\`\`
 
 ## Queueing Additional Tools
@@ -631,21 +681,21 @@ Queue another tool to run after the current one:
 \`\`\`typescript
 import { queueTool } from '@standardagents/builder';
 
-export default defineTool(
-  'Create order and send confirmation',
-  z.object({ items: z.array(z.string()) }),
-  async (flow, args) => {
+export default defineTool({
+  description: 'Create order and send confirmation',
+  args: z.object({ items: z.array(z.string()) }),
+  execute: async (state, args) => {
     const order = await createOrder(args.items);
 
     // Queue email tool to run next
-    queueTool(flow, 'send_confirmation_email', {
+    queueTool(state, 'send_confirmation_email', {
       orderId: order.id,
-      email: flow.thread.metadata.userEmail,
+      email: state.thread.metadata.userEmail,
     });
 
     return { status: 'success', result: JSON.stringify(order) };
-  }
-);
+  },
+});
 \`\`\`
 
 ## Injecting Messages
@@ -655,17 +705,61 @@ Add messages without triggering re-execution:
 \`\`\`typescript
 import { injectMessage } from '@standardagents/builder';
 
-export default defineTool(
-  'Log audit event',
-  z.object({ event: z.string() }),
-  async (flow, args) => {
-    await injectMessage(flow, {
+export default defineTool({
+  description: 'Log audit event',
+  args: z.object({ event: z.string() }),
+  execute: async (state, args) => {
+    await injectMessage(state, {
       role: 'system',
       content: \`[AUDIT] \${args.event}\`,
     });
     return { status: 'success', result: 'Logged' };
-  }
-);
+  },
+});
+\`\`\`
+
+## Thread Environment Variables (tenvs)
+
+Tools can declare required thread environment variables:
+
+\`\`\`typescript
+export default defineTool({
+  description: 'Search uploaded documents',
+  args: z.object({ query: z.string() }),
+  execute: async (state, args) => {
+    const vectorStoreId = state.tenvs.vectorStoreId;
+    const results = await searchVectorStore(vectorStoreId, args.query);
+    return { status: 'success', result: JSON.stringify(results) };
+  },
+  tenvs: z.object({
+    vectorStoreId: z.string().describe('OpenAI Vector Store ID'),
+  }),
+});
+\`\`\`
+
+## Returning Attachments
+
+Tools can return file attachments (e.g., generated images):
+
+\`\`\`typescript
+export default defineTool({
+  description: 'Generate a chart from data',
+  args: z.object({ data: z.array(z.number()) }),
+  execute: async (state, args) => {
+    const chartImage = await generateChart(args.data);
+    return {
+      status: 'success',
+      result: 'Chart generated successfully',
+      attachments: [{
+        name: 'chart.png',
+        mimeType: 'image/png',
+        data: chartImage.base64,
+        width: 800,
+        height: 600,
+      }],
+    };
+  },
+});
 \`\`\`
 
 ## Best Practices
@@ -675,7 +769,7 @@ export default defineTool(
 - **Handle errors gracefully** - return error status, don't throw
 - **Use snake_case** for file names (\`search_knowledge_base.ts\`)
 - **Keep tools focused** - one task per tool
-- **Use \`flow.rootState\`** when queueing from sub-prompts
+- **Use \`state.rootState\`** when queueing from sub-prompts
 
 ## Supported Zod Types
 
@@ -701,31 +795,69 @@ Hooks intercept and modify agent execution at specific lifecycle points.
 
 | Hook | Signature | Purpose |
 |------|-----------|---------|
-| \`filter_messages\` | \`(state, rows) => Message[]\` | Filter raw message rows before LLM context |
-| \`prefilter_llm_history\` | \`(state, messages) => Message[]\` | Modify messages after filtering, before LLM |
-| \`before_create_message\` | \`(state, message) => Message\` | Modify message before database insert |
-| \`after_create_message\` | \`(state, message) => void\` | Run logic after message created |
-| \`before_update_message\` | \`(state, id, updates) => Updates\` | Modify updates before message update |
-| \`after_update_message\` | \`(state, message) => void\` | Run logic after message updated |
-| \`before_store_tool_result\` | \`(state, toolCall, result) => Result\` | Modify tool result before storage |
-| \`after_tool_call_success\` | \`(state, toolCall, result) => Result\` | Process successful tool execution |
-| \`after_tool_call_failure\` | \`(state, toolCall, result) => Result\` | Process failed tool execution |
+| \`filter_messages\` | \`(state: ThreadState, messages: Message[]) => Message[]\` | Filter raw messages before LLM context |
+| \`prefilter_llm_history\` | \`(state: ThreadState, messages: LLMMessage[]) => LLMMessage[]\` | Modify chat completion messages before LLM |
+| \`before_create_message\` | \`(state: ThreadState, message: Message) => Message\` | Modify message before database insert |
+| \`after_create_message\` | \`(state: ThreadState, message: Message) => void\` | Run logic after message created |
+| \`before_update_message\` | \`(state: ThreadState, id: string, updates: Record) => Record\` | Modify updates before message update |
+| \`after_update_message\` | \`(state: ThreadState, message: Message) => void\` | Run logic after message updated |
+| \`before_store_tool_result\` | \`(state: ThreadState, toolCall: HookToolCall, result: HookToolResult) => HookToolResult\` | Modify tool result before storage |
+| \`after_tool_call_success\` | \`(state: ThreadState, toolCall: HookToolCall, result: HookToolResult) => HookToolResult \\| null\` | Process successful tool execution |
+| \`after_tool_call_failure\` | \`(state: ThreadState, toolCall: HookToolCall, result: HookToolResult) => HookToolResult \\| null\` | Process failed tool execution |
+
+All hooks receive \`ThreadState\` as their first parameter, providing access to thread identity, message history, and resource loading.
+
+## Creating a Hook
+
+Each hook file exports a default \`defineHook\` call with three properties:
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook({
+  hook: 'filter_messages',       // Hook type
+  id: 'limit_recent_messages',   // Unique ID (snake_case)
+  execute: async (state, messages) => {
+    return messages.slice(-20);
+  }
+});
+\`\`\`
+
+## Hook Scoping
+
+Hooks are scoped to **prompts** or **agents** via their ID:
+
+\`\`\`typescript
+// In a prompt definition
+definePrompt({
+  name: 'customer_support',
+  hooks: ['limit_recent_messages', 'redact_pii'],
+  // ...
+});
+
+// In an agent definition
+defineAgent({
+  name: 'support_agent',
+  hooks: ['log_all_messages'],
+  // ...
+});
+\`\`\`
+
+- **Prompt hooks** take precedence over agent hooks
+- If a prompt defines hooks, only those run (agent hooks are skipped)
+- If no prompt hooks are defined, agent hooks run as fallback
+- Hooks are filtered by type at runtime
 
 ## File Naming
 
-Hook files **must** be named exactly as the hook type:
+Hook files can use **any name** \u2014 the hook type and ID are defined inside the file:
 
 \`\`\`
 agents/hooks/
-\u251C\u2500\u2500 filter_messages.ts
-\u251C\u2500\u2500 prefilter_llm_history.ts
-\u251C\u2500\u2500 before_create_message.ts
-\u251C\u2500\u2500 after_create_message.ts
-\u251C\u2500\u2500 before_update_message.ts
-\u251C\u2500\u2500 after_update_message.ts
-\u251C\u2500\u2500 before_store_tool_result.ts
-\u251C\u2500\u2500 after_tool_call_success.ts
-\u2514\u2500\u2500 after_tool_call_failure.ts
+\u251C\u2500\u2500 my_filter.ts              # Could contain any hook type
+\u251C\u2500\u2500 redact_sensitive_data.ts
+\u251C\u2500\u2500 log_tool_usage.ts
+\u2514\u2500\u2500 add_metadata.ts
 \`\`\`
 
 ## Examples
@@ -735,23 +867,31 @@ agents/hooks/
 \`\`\`typescript
 import { defineHook } from '@standardagents/builder';
 
-export default defineHook('filter_messages', async (state, rows) => {
-  // Only include last 20 messages
-  return rows.slice(-20);
+export default defineHook({
+  hook: 'filter_messages',
+  id: 'limit_to_20',
+  execute: async (state, messages) => {
+    return messages.slice(-20);
+  }
 });
 \`\`\`
 
-### Prefilter LLM History (Modify Content)
+### Prefilter LLM History (Redact Content)
 
 \`\`\`typescript
 import { defineHook } from '@standardagents/builder';
 
-export default defineHook('prefilter_llm_history', async (state, messages) => {
-  // Remove sensitive data from message content
-  return messages.map(msg => ({
-    ...msg,
-    content: msg.content?.replace(/\\b\\d{4}-\\d{4}-\\d{4}-\\d{4}\\b/g, '[REDACTED]'),
-  }));
+export default defineHook({
+  hook: 'prefilter_llm_history',
+  id: 'redact_pii',
+  execute: async (state, messages) => {
+    return messages.map(msg => ({
+      ...msg,
+      content: typeof msg.content === 'string'
+        ? msg.content.replace(/\\b\\d{4}-\\d{4}-\\d{4}-\\d{4}\\b/g, '[REDACTED]')
+        : msg.content,
+    }));
+  }
 });
 \`\`\`
 
@@ -760,15 +900,34 @@ export default defineHook('prefilter_llm_history', async (state, messages) => {
 \`\`\`typescript
 import { defineHook } from '@standardagents/builder';
 
-export default defineHook('before_create_message', async (state, message) => {
-  return {
-    ...message,
-    metadata: {
-      ...message.metadata,
-      createdAt: Date.now(),
-      agentVersion: '1.0.0',
-    },
-  };
+export default defineHook({
+  hook: 'before_create_message',
+  id: 'add_version_metadata',
+  execute: async (state, message) => {
+    if (message.role === 'user' && message.content) {
+      return { ...message, content: \`[v1.0] \${message.content}\` };
+    }
+    return message;
+  }
+});
+\`\`\`
+
+### Before Store Tool Result (Sanitize)
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook({
+  hook: 'before_store_tool_result',
+  id: 'sanitize_results',
+  execute: async (state, toolCall, toolResult) => {
+    // toolCall: { id, type: 'function', function: { name, arguments } }
+    // toolResult: { status, result?, error?, stack?, attachments? }
+    if (toolResult.result) {
+      return { ...toolResult, result: toolResult.result.replace(/secret/gi, '[REDACTED]') };
+    }
+    return toolResult;
+  }
 });
 \`\`\`
 
@@ -777,9 +936,13 @@ export default defineHook('before_create_message', async (state, message) => {
 \`\`\`typescript
 import { defineHook } from '@standardagents/builder';
 
-export default defineHook('after_tool_call_success', async (state, toolCall, result) => {
-  console.log(\`Tool \${toolCall.function.name} succeeded:\`, result);
-  return result;  // Return result unchanged, or modify it
+export default defineHook({
+  hook: 'after_tool_call_success',
+  id: 'log_tool_success',
+  execute: async (state, toolCall, result) => {
+    console.log(\`Tool \${toolCall.function.name} succeeded\`);
+    return null;  // Return null to use original result
+  }
 });
 \`\`\`
 
@@ -788,15 +951,18 @@ export default defineHook('after_tool_call_success', async (state, toolCall, res
 \`\`\`typescript
 import { defineHook } from '@standardagents/builder';
 
-export default defineHook('after_tool_call_failure', async (state, toolCall, result) => {
-  // Override error with fallback result
-  if (toolCall.function.name === 'fetch_weather') {
-    return {
-      status: 'success',
-      result: JSON.stringify({ temp: 'unavailable', fallback: true }),
-    };
+export default defineHook({
+  hook: 'after_tool_call_failure',
+  id: 'weather_fallback',
+  execute: async (state, toolCall, result) => {
+    if (toolCall.function.name === 'fetch_weather') {
+      return {
+        status: 'success',
+        result: JSON.stringify({ temp: 'unavailable', fallback: true }),
+      };
+    }
+    return null;  // Use original error for other tools
   }
-  return result;  // Return original error
 });
 \`\`\`
 
@@ -808,8 +974,8 @@ export default defineHook('after_tool_call_failure', async (state, toolCall, res
 - \`before_create_message\`
 - \`before_update_message\`
 - \`before_store_tool_result\`
-- \`after_tool_call_success\`
-- \`after_tool_call_failure\`
+- \`after_tool_call_success\` (return modified result or null)
+- \`after_tool_call_failure\` (return modified result or null)
 
 **Event hooks** (side effects only):
 - \`after_create_message\`
@@ -818,8 +984,9 @@ export default defineHook('after_tool_call_failure', async (state, toolCall, res
 ## Best Practices
 
 - **Keep hooks fast** - target <100ms execution
-- **Wrap in try-catch** - hooks continue on error
-- **Validate input data** before processing
+- **Wrap in try-catch** - hooks continue on error (original data preserved)
+- **Use unique IDs** - hook IDs must be snake_case and unique across the project
+- **Scope appropriately** - assign hooks to prompts or agents that need them
 - **Document purpose** with clear comments
 - **Use for cross-cutting concerns** - logging, redaction, enrichment
 
@@ -831,7 +998,7 @@ Full reference: https://docs.standardagentbuilder.com/api-reference/define/hook
 // src/templates/api.ts
 var API_CLAUDE_MD = `# Thread-Specific API Endpoints
 
-Define custom API endpoints that operate on specific threads with access to the thread's Durable Object instance and SQLite storage.
+Define custom API endpoints that operate on specific threads with access to the thread's ThreadState.
 
 ## File-Based Routing
 
@@ -848,15 +1015,14 @@ Define custom API endpoints that operate on specific threads with access to the
 
 \`\`\`typescript
 // agents/api/status.get.ts -> GET /api/threads/:id/status
-import { defineThreadEndpoint } from '@standardagents/builder';
+import { defineThreadEndpoint } from '@standardagents/spec';
 
-export default defineThreadEndpoint(async (thread, request, env) => {
-  const messages = await thread.getMessages();
-  return new Response(JSON.stringify({
-    messageCount: messages.length,
+export default defineThreadEndpoint(async (req, state) => {
+  const { messages, total } = await state.getMessages();
+  return Response.json({
+    threadId: state.threadId,
+    messageCount: total,
     status: 'active',
-  }), {
-    headers: { 'Content-Type': 'application/json' },
   });
 });
 \`\`\`
@@ -865,30 +1031,40 @@ export default defineThreadEndpoint(async (thread, request, env) => {
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| \`thread\` | \`DurableThread\` | The thread's Durable Object instance |
-| \`request\` | \`Request\` | The incoming HTTP request |
-| \`env\` | \`Env\` | Cloudflare Worker environment bindings |
+| \`req\` | \`Request\` | The incoming HTTP request |
+| \`state\` | \`ThreadState\` | Thread state with messages, identity, file system, etc. |
+
+Note: \`state.execution\` is always \`null\` in endpoints since the thread is at rest.
 
-## Thread Methods
+## ThreadState Methods
 
-Access thread data through the instance:
+Access thread data through the state object:
 
 \`\`\`typescript
-export default defineThreadEndpoint(async (thread, request, env) => {
+import { defineThreadEndpoint } from '@standardagents/spec';
+
+export default defineThreadEndpoint(async (req, state) => {
+  // Thread identity
+  console.log('Thread ID:', state.threadId);
+  console.log('Agent ID:', state.agentId);
+  console.log('User ID:', state.userId);
+
   // Message operations
-  const messages = await thread.getMessages({ limit: 100, offset: 0 });
-  const count = await thread.getMessageCount();
+  const { messages, total, hasMore } = await state.getMessages({
+    limit: 100,
+    offset: 0,
+    order: 'desc',
+  });
 
-  // Thread metadata
-  const metadata = thread.getMetadata();
+  // File system operations
+  const files = await state.findFiles('**/*.json');
+  const data = await state.readFile('/data/config.json');
 
-  // Execution control
-  await thread.stop();
+  // Resource loading
+  const agent = await state.loadAgent('my-agent');
+  const prompt = await state.loadPrompt('my-prompt');
 
-  // Custom SQL queries
-  const result = thread.ctx.storage.sql.exec(\`
-    SELECT * FROM messages WHERE role = 'user'
-  \`);
+  return Response.json({ messages, total });
 });
 \`\`\`
 
@@ -896,13 +1072,13 @@ export default defineThreadEndpoint(async (thread, request, env) => {
 
 \`\`\`typescript
 // agents/api/export.post.ts -> POST /api/threads/:id/export
-import { defineThreadEndpoint } from '@standardagents/builder';
+import { defineThreadEndpoint } from '@standardagents/spec';
 
-export default defineThreadEndpoint(async (thread, request, env) => {
-  const body = await request.json();
+export default defineThreadEndpoint(async (req, state) => {
+  const body = await req.json();
   const { format = 'json' } = body;
 
-  const messages = await thread.getMessages();
+  const { messages } = await state.getMessages();
 
   if (format === 'csv') {
     const csv = messages.map(m => \`\${m.role},\${m.content}\`).join('\\n');
@@ -911,9 +1087,7 @@ export default defineThreadEndpoint(async (thread, request, env) => {
     });
   }
 
-  return new Response(JSON.stringify(messages), {
-    headers: { 'Content-Type': 'application/json' },
-  });
+  return Response.json(messages);
 });
 \`\`\`
 
@@ -933,35 +1107,38 @@ agents/api/
 ## Error Handling
 
 \`\`\`typescript
-export default defineThreadEndpoint(async (thread, request, env) => {
+import { defineThreadEndpoint } from '@standardagents/spec';
+
+export default defineThreadEndpoint(async (req, state) => {
   try {
     const data = await riskyOperation();
-    return new Response(JSON.stringify(data), {
-      headers: { 'Content-Type': 'application/json' },
-    });
+    return Response.json(data);
   } catch (error) {
-    return new Response(JSON.stringify({
-      error: error.message,
-    }), {
-      status: 500,
-      headers: { 'Content-Type': 'application/json' },
-    });
+    return Response.json({ error: error.message }, { status: 500 });
   }
 });
 \`\`\`
 
-## Using Environment Variables
+## File System Operations
 
 \`\`\`typescript
-export default defineThreadEndpoint(async (thread, request, env) => {
-  // Access secrets and bindings
-  const apiKey = env.EXTERNAL_API_KEY;
-  const kv = env.MY_KV_NAMESPACE;
+import { defineThreadEndpoint } from '@standardagents/spec';
+
+export default defineThreadEndpoint(async (req, state) => {
+  // Read files
+  const content = await state.readFile('/data/file.txt');
+
+  // Write files
+  await state.writeFile('/output/result.json', JSON.stringify(data), 'application/json');
 
-  const data = await fetchExternalAPI(apiKey);
-  await kv.put(\`thread:\${thread.id}\`, JSON.stringify(data));
+  // List directory
+  const { entries } = await state.readdirFile('/data');
 
-  return new Response('OK');
+  // Search files
+  const matches = await state.grepFiles('pattern');
+  const paths = await state.findFiles('**/*.ts');
+
+  return Response.json({ success: true });
 });
 \`\`\`
 
@@ -972,6 +1149,7 @@ export default defineThreadEndpoint(async (thread, request, env) => {
 - **Validate input data** - check request body before processing
 - **Use descriptive file names** - \`export.post.ts\` not \`ep1.ts\`
 - **Return proper status codes** - 200, 400, 404, 500
+- **Import from spec** - use \`@standardagents/spec\` for \`defineThreadEndpoint\`
 
 ## Documentation
 
@@ -979,17 +1157,19 @@ Full reference: https://docs.standardagentbuilder.com/core-concepts/api
 `;
 
 // src/commands/scaffold.ts
-var WRANGLER_TEMPLATE = (name) => `{
+var WRANGLER_TEMPLATE = (name) => {
+  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  return `{
   "$schema": "node_modules/wrangler/config-schema.json",
   "name": "${name}",
   "main": "worker/index.ts",
-  "compatibility_date": "2025-01-01",
+  "compatibility_date": "${today}",
   "compatibility_flags": ["nodejs_compat"],
   "observability": {
     "enabled": true
   },
   "assets": {
-    "directory": "dist",
+    "directory": "dist/client",
     "not_found_handling": "single-page-application",
     "binding": "ASSETS",
     "run_worker_first": ["/**"]
@@ -1018,6 +1198,7 @@ var WRANGLER_TEMPLATE = (name) => `{
   ]
 }
 `;
+};
 var THREAD_TS = `import { DurableThread } from 'virtual:@standardagents/builder'
 
 export default class Thread extends DurableThread {}
@@ -1043,9 +1224,9 @@ function getProjectName(cwd) {
   const packageJsonPath = path3.join(cwd, "package.json");
   if (fs3.existsSync(packageJsonPath)) {
     try {
-      const pkg2 = JSON.parse(fs3.readFileSync(packageJsonPath, "utf-8"));
-      if (pkg2.name) {
-        return pkg2.name.replace(/^@[^/]+\//, "");
+      const pkg = JSON.parse(fs3.readFileSync(packageJsonPath, "utf-8"));
+      if (pkg.name) {
+        return pkg.name.replace(/^@[^/]+\//, "");
       }
     } catch {
     }
@@ -1082,14 +1263,6 @@ async function modifyViteConfig(configPath, force) {
       logger.info("Vite config already includes Standard Agents plugins");
       return true;
     }
-    if (!hasCloudflare || force) {
-      addVitePlugin(mod, {
-        from: "@cloudflare/vite-plugin",
-        imported: "cloudflare",
-        constructor: "cloudflare"
-      });
-      logger.success("Added cloudflare plugin to vite.config");
-    }
     if (!hasAgentBuilder || force) {
       addVitePlugin(mod, {
         from: "@standardagents/builder",
@@ -1099,6 +1272,14 @@ async function modifyViteConfig(configPath, force) {
       });
       logger.success("Added agentbuilder plugin to vite.config");
     }
+    if (!hasCloudflare || force) {
+      addVitePlugin(mod, {
+        from: "@cloudflare/vite-plugin",
+        imported: "cloudflare",
+        constructor: "cloudflare"
+      });
+      logger.success("Added cloudflare plugin to vite.config");
+    }
     await writeFile(mod, configPath);
     return true;
   } catch (error) {
@@ -1106,10 +1287,10 @@ async function modifyViteConfig(configPath, force) {
     logger.log("");
     logger.log("Please manually add the following to your vite.config.ts:");
     logger.log("");
-    logger.log(`  import { cloudflare } from '@cloudflare/vite-plugin'`);
     logger.log(`  import { agentbuilder } from '@standardagents/builder'`);
+    logger.log(`  import { cloudflare } from '@cloudflare/vite-plugin'`);
     logger.log("");
-    logger.log(`  plugins: [cloudflare(), agentbuilder({ mountPoint: '/' })]`);
+    logger.log(`  plugins: [agentbuilder({ mountPoint: '/' }), cloudflare()]`);
     logger.log("");
     return false;
   }
@@ -1158,7 +1339,7 @@ function createOrUpdateWranglerConfig(cwd, projectName, force) {
       }
       if (!config.assets) {
         const edits = modify(result, ["assets"], {
-          directory: "dist",
+          directory: "dist/client",
           not_found_handling: "single-page-application",
           binding: "ASSETS",
           run_worker_first: ["/**"]
@@ -1430,15 +1611,15 @@ async function prompt(question) {
     input: process.stdin,
     output: process.stdout
   });
-  return new Promise((resolve2) => {
+  return new Promise((resolve) => {
     rl.question(question, (answer) => {
       rl.close();
-      resolve2(answer.trim());
+      resolve(answer.trim());
     });
   });
 }
 async function promptPassword(question) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve) => {
     const stdin = process.stdin;
     const stdout = process.stdout;
     stdout.write(question);
@@ -1459,7 +1640,7 @@ async function promptPassword(question) {
           stdin.pause();
           stdin.removeListener("data", onData);
           stdout.write("\n");
-          resolve2(password);
+          resolve(password);
           break;
         case "":
           stdout.write("\n");
@@ -1485,7 +1666,7 @@ async function promptPassword(question) {
   });
 }
 function runCommand(command, args, cwd) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve, reject) => {
     const child = spawn(command, args, {
       cwd,
       stdio: "inherit",
@@ -1493,7 +1674,7 @@ function runCommand(command, args, cwd) {
     });
     child.on("close", (code) => {
       if (code === 0) {
-        resolve2();
+        resolve();
       } else {
         reject(new Error(`Command failed with exit code ${code}`));
       }
@@ -1517,25 +1698,16 @@ function detectPackageManager() {
   if (fs3.existsSync("package-lock.json")) return "npm";
   return "npm";
 }
-function getBuilderPackageVersion() {
-  try {
-    const __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
-    const pkgPath = path3.resolve(__dirname2, "../../package.json");
-    const pkg2 = JSON.parse(fs3.readFileSync(pkgPath, "utf-8"));
-    const version = pkg2.version;
-    const prereleaseMatch = version.match(/-([a-z]+)\./i);
-    if (prereleaseMatch) {
-      return `@${prereleaseMatch[1]}`;
-    }
-    return `@^${version}`;
-  } catch {
-    return "";
+function getPackageVersion() {
+  if (process.env.STANDARDAGENTS_WORKSPACE === "1") {
+    return "workspace:*";
   }
+  return "0.12.0";
 }
 async function selectPackageManager(detected) {
   const options = ["npm", "pnpm", "yarn", "bun"];
   const detectedIndex = options.indexOf(detected);
-  return new Promise((resolve2) => {
+  return new Promise((resolve) => {
     const stdin = process.stdin;
     const stdout = process.stdout;
     let selectedIndex = detectedIndex;
@@ -1581,7 +1753,7 @@ async function selectPackageManager(detected) {
         renderOptions();
       } else if (key === "\r" || key === "\n") {
         cleanup();
-        resolve2(options[selectedIndex]);
+        resolve(options[selectedIndex]);
       } else if (key === "") {
         cleanup();
         stdout.write("\n");
@@ -1667,31 +1839,7 @@ export default defineConfig({
     }
   }
   logger.log("");
-  logger.info("Step 2: Installing Standard Agents dependencies...");
-  logger.log("");
-  try {
-    const installCmd = pm === "npm" ? "install" : "add";
-    const devFlag = pm === "npm" ? "--save-dev" : "-D";
-    const builderVersion = getBuilderPackageVersion();
-    await runCommand(pm, [
-      installCmd,
-      devFlag,
-      "@cloudflare/vite-plugin",
-      `@standardagents/builder${builderVersion}`,
-      "wrangler",
-      "zod"
-    ], projectPath);
-  } catch (error) {
-    logger.error("Failed to install dependencies");
-    process.exit(1);
-  }
-  logger.log("");
-  logger.info("Step 3: Configuring Standard Agents...");
-  logger.log("");
-  process.chdir(projectPath);
-  await scaffold({ force: true });
-  logger.log("");
-  logger.info("Step 4: Configuring environment variables...");
+  logger.info("Step 2: Configuring environment variables...");
   logger.log("");
   const encryptionKey = crypto.randomBytes(32).toString("hex");
   let openrouterKey = "";
@@ -1726,6 +1874,44 @@ export default defineConfig({
   if (!adminPassword) {
     adminPassword = "admin";
   }
+  logger.log("");
+  logger.info("Step 3: Installing Standard Agents dependencies...");
+  logger.log("");
+  try {
+    const installCmd = pm === "npm" ? "install" : "add";
+    const devFlag = pm === "npm" ? "--save-dev" : "-D";
+    const packageVersion = getPackageVersion();
+    await runCommand(pm, [
+      installCmd,
+      devFlag,
+      "@cloudflare/vite-plugin",
+      "wrangler"
+    ], projectPath);
+    const deps = [
+      `@standardagents/builder@${packageVersion}`,
+      `@standardagents/spec@${packageVersion}`,
+      `@standardagents/sip@${packageVersion}`,
+      "zod"
+    ];
+    if (openaiKey) {
+      deps.push(`@standardagents/openai@${packageVersion}`);
+    }
+    if (openrouterKey) {
+      deps.push(`@standardagents/openrouter@${packageVersion}`);
+    }
+    await runCommand(pm, [installCmd, ...deps], projectPath);
+  } catch (error) {
+    logger.error("Failed to install dependencies");
+    process.exit(1);
+  }
+  logger.log("");
+  logger.info("Step 4: Configuring Standard Agents...");
+  logger.log("");
+  process.chdir(projectPath);
+  await scaffold({ force: true });
+  logger.log("");
+  logger.info("Writing environment configuration...");
+  logger.log("");
   const devVarsLines = [
     "# Standard Agents Environment Variables",
     "# This file contains secrets for local development only",
@@ -1782,10 +1968,10 @@ export default defineConfig({
 }
 function getReactPackageVersion() {
   try {
-    const __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
-    const pkgPath = path3.resolve(__dirname2, "../package.json");
-    const pkg2 = JSON.parse(fs3.readFileSync(pkgPath, "utf-8"));
-    const version = pkg2.version;
+    const __dirname = path3.dirname(fileURLToPath(import.meta.url));
+    const pkgPath = path3.resolve(__dirname, "../package.json");
+    const pkg = JSON.parse(fs3.readFileSync(pkgPath, "utf-8"));
+    const version = pkg.version;
     const prereleaseMatch = version.match(/-([a-z]+)\./i);
     if (prereleaseMatch) {
       return prereleaseMatch[1];
@@ -1796,23 +1982,23 @@ function getReactPackageVersion() {
   }
 }
 function getChatSourceDir() {
-  const __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
-  return path3.resolve(__dirname2, "../chat");
+  const __dirname = path3.dirname(fileURLToPath(import.meta.url));
+  return path3.resolve(__dirname, "../chat");
 }
 async function prompt2(question) {
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout
   });
-  return new Promise((resolve2) => {
+  return new Promise((resolve) => {
     rl.question(question, (answer) => {
       rl.close();
-      resolve2(answer.trim());
+      resolve(answer.trim());
     });
   });
 }
 function runCommand2(command, args, cwd) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve, reject) => {
     const child = spawn(command, args, {
       cwd,
       stdio: "inherit",
@@ -1820,7 +2006,7 @@ function runCommand2(command, args, cwd) {
     });
     child.on("close", (code) => {
       if (code === 0) {
-        resolve2();
+        resolve();
       } else {
         reject(new Error(`Command failed with exit code ${code}`));
       }
@@ -1844,7 +2030,7 @@ function detectPackageManager2() {
 async function selectPackageManager2(detected) {
   const options = ["npm", "pnpm", "yarn", "bun"];
   const detectedIndex = options.indexOf(detected);
-  return new Promise((resolve2) => {
+  return new Promise((resolve) => {
     const stdin = process.stdin;
     const stdout = process.stdout;
     let selectedIndex = detectedIndex;
@@ -1890,7 +2076,7 @@ async function selectPackageManager2(detected) {
         renderOptions();
       } else if (key === "\r" || key === "\n") {
         cleanup();
-        resolve2(options[selectedIndex]);
+        resolve(options[selectedIndex]);
       } else if (key === "") {
         cleanup();
         stdout.write("\n");
@@ -1905,7 +2091,7 @@ async function selectFramework() {
     { value: "vite", label: "Vite (React + TypeScript)" },
     { value: "nextjs", label: "Next.js (App Router)" }
   ];
-  return new Promise((resolve2) => {
+  return new Promise((resolve) => {
     const stdin = process.stdin;
     const stdout = process.stdout;
     let selectedIndex = 0;
@@ -1949,7 +2135,7 @@ async function selectFramework() {
         renderOptions();
       } else if (key === "\r" || key === "\n") {
         cleanup();
-        resolve2(options[selectedIndex].value);
+        resolve(options[selectedIndex].value);
       } else if (key === "") {
         cleanup();
         stdout.write("\n");
@@ -1969,20 +2155,20 @@ function isValidUrl(url) {
 }
 async function isPortOpen(port) {
   const tryConnect = (host) => {
-    return new Promise((resolve2) => {
+    return new Promise((resolve) => {
       const socket = new net.Socket();
       socket.setTimeout(200);
       socket.on("connect", () => {
         socket.destroy();
-        resolve2(true);
+        resolve(true);
       });
       socket.on("timeout", () => {
         socket.destroy();
-        resolve2(false);
+        resolve(false);
       });
       socket.on("error", () => {
         socket.destroy();
-        resolve2(false);
+        resolve(false);
       });
       socket.connect(port, host);
     });
@@ -2206,21 +2392,21 @@ export default defineConfig({
   fs3.writeFileSync(path3.join(projectPath, "tsconfig.json"), JSON.stringify(tsconfig, null, 2) + "\n", "utf-8");
   logger.success("Created tsconfig.json");
   fs3.copyFileSync(path3.join(chatSourceDir, "package.json"), path3.join(projectPath, "package.json"));
-  const pkg2 = JSON.parse(fs3.readFileSync(path3.join(projectPath, "package.json"), "utf-8"));
-  pkg2.name = projectName;
-  pkg2.scripts = {
+  const pkg = JSON.parse(fs3.readFileSync(path3.join(projectPath, "package.json"), "utf-8"));
+  pkg.name = projectName;
+  pkg.scripts = {
     dev: "vite",
     build: "vite build",
     preview: "vite preview"
   };
-  delete pkg2.private;
-  if (pkg2.dependencies?.["@standardagents/react"]) {
-    pkg2.dependencies["@standardagents/react"] = reactVersion;
-  }
-  delete pkg2.dependencies?.["next"];
-  delete pkg2.devDependencies?.["@tailwindcss/postcss"];
-  delete pkg2.devDependencies?.["postcss"];
-  fs3.writeFileSync(path3.join(projectPath, "package.json"), JSON.stringify(pkg2, null, 2) + "\n", "utf-8");
+  delete pkg.private;
+  if (pkg.dependencies?.["@standardagents/react"]) {
+    pkg.dependencies["@standardagents/react"] = reactVersion;
+  }
+  delete pkg.dependencies?.["next"];
+  delete pkg.devDependencies?.["@tailwindcss/postcss"];
+  delete pkg.devDependencies?.["postcss"];
+  fs3.writeFileSync(path3.join(projectPath, "package.json"), JSON.stringify(pkg, null, 2) + "\n", "utf-8");
   logger.success("Created package.json");
   const envContent = `# Agentbuilder connection
 VITE_AGENTBUILDER_URL=${serverUrl}
@@ -2275,21 +2461,21 @@ async function scaffoldNextjs(projectPath, chatSourceDir, projectName, serverUrl
   };
   fs3.writeFileSync(path3.join(projectPath, "tsconfig.json"), JSON.stringify(tsconfig, null, 2) + "\n", "utf-8");
   logger.success("Created tsconfig.json");
-  const pkg2 = JSON.parse(fs3.readFileSync(path3.join(chatSourceDir, "package.json"), "utf-8"));
-  pkg2.name = projectName;
-  pkg2.scripts = {
+  const pkg = JSON.parse(fs3.readFileSync(path3.join(chatSourceDir, "package.json"), "utf-8"));
+  pkg.name = projectName;
+  pkg.scripts = {
     dev: "next dev",
     build: "next build",
     start: "next start"
   };
-  delete pkg2.private;
-  if (pkg2.dependencies?.["@standardagents/react"]) {
-    pkg2.dependencies["@standardagents/react"] = reactVersion;
-  }
-  delete pkg2.devDependencies?.["@tailwindcss/vite"];
-  delete pkg2.devDependencies?.["@vitejs/plugin-react"];
-  delete pkg2.devDependencies?.["vite"];
-  fs3.writeFileSync(path3.join(projectPath, "package.json"), JSON.stringify(pkg2, null, 2) + "\n", "utf-8");
+  delete pkg.private;
+  if (pkg.dependencies?.["@standardagents/react"]) {
+    pkg.dependencies["@standardagents/react"] = reactVersion;
+  }
+  delete pkg.devDependencies?.["@tailwindcss/vite"];
+  delete pkg.devDependencies?.["@vitejs/plugin-react"];
+  delete pkg.devDependencies?.["vite"];
+  fs3.writeFileSync(path3.join(projectPath, "package.json"), JSON.stringify(pkg, null, 2) + "\n", "utf-8");
   logger.success("Created package.json");
   const envContent = `# Agentbuilder connection
 NEXT_PUBLIC_AGENTBUILDER_URL=${serverUrl}
@@ -2309,15 +2495,437 @@ out
   pageTsx = pageTsx.replace(/from '\.\.\/\.\.\/src\//g, "from '../src/");
   fs3.writeFileSync(path3.join(projectPath, "app", "page.tsx"), pageTsx, "utf-8");
 }
+async function selectAgent(agents) {
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    let selectedIndex = 0;
+    const renderOptions = () => {
+      stdout.write("\x1B[?25l");
+      stdout.write(`\x1B[${agents.length + 1}A`);
+      stdout.write("\x1B[0J");
+      stdout.write("Select an agent to pack (use arrows, enter to confirm):\n");
+      agents.forEach((agent, i) => {
+        const prefix = i === selectedIndex ? "\x1B[36m\u276F\x1B[0m" : " ";
+        const highlight = i === selectedIndex ? "\x1B[36m" : "\x1B[90m";
+        stdout.write(`${prefix} ${highlight}${agent}\x1B[0m
+`);
+      });
+    };
+    stdout.write("Select an agent to pack (use arrows, enter to confirm):\n");
+    agents.forEach((agent, i) => {
+      const prefix = i === selectedIndex ? "\x1B[36m\u276F\x1B[0m" : " ";
+      const highlight = i === selectedIndex ? "\x1B[36m" : "\x1B[90m";
+      stdout.write(`${prefix} ${highlight}${agent}\x1B[0m
+`);
+    });
+    const wasRaw = stdin.isRaw;
+    if (stdin.isTTY) {
+      stdin.setRawMode(true);
+    }
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    const cleanup = () => {
+      stdin.setRawMode(wasRaw ?? false);
+      stdin.pause();
+      stdin.removeListener("data", onData);
+      stdout.write("\x1B[?25h");
+    };
+    const onData = (key) => {
+      if (key === "\x1B[A" || key === "k") {
+        selectedIndex = (selectedIndex - 1 + agents.length) % agents.length;
+        renderOptions();
+      } else if (key === "\x1B[B" || key === "j") {
+        selectedIndex = (selectedIndex + 1) % agents.length;
+        renderOptions();
+      } else if (key === "\r" || key === "\n") {
+        cleanup();
+        resolve(agents[selectedIndex]);
+      } else if (key === "") {
+        cleanup();
+        stdout.write("\n");
+        process.exit(1);
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+async function selectItemModes(items, _agentName) {
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    let selectedIndex = 0;
+    const getDisplayLines = () => {
+      const lines = [];
+      lines.push("");
+      lines.push("Remove originals? (space to toggle, enter to confirm)");
+      lines.push("");
+      for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        const isSelected = i === selectedIndex;
+        const cursor = isSelected ? "\x1B[36m\u276F\x1B[0m" : " ";
+        const modeText = item.mode === "extract" ? "\x1B[32m(extract)\x1B[0m" : "\x1B[90m(copy)\x1B[0m";
+        lines.push(`${cursor} ${item.name} \x1B[90m(${item.type})\x1B[0m ${modeText}`);
+      }
+      lines.push("");
+      return lines;
+    };
+    const render = (initial = false) => {
+      const lines = getDisplayLines();
+      if (!initial) {
+        stdout.write("\x1B[?25l");
+        stdout.write(`\x1B[${lines.length}A`);
+        stdout.write("\x1B[0J");
+      }
+      stdout.write(lines.join("\n") + "\n");
+    };
+    render(true);
+    const wasRaw = stdin.isRaw;
+    if (stdin.isTTY) {
+      stdin.setRawMode(true);
+    }
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    const cleanup = () => {
+      stdin.setRawMode(wasRaw ?? false);
+      stdin.pause();
+      stdin.removeListener("data", onData);
+      stdout.write("\x1B[?25h");
+    };
+    const onData = (key) => {
+      if (key === "\x1B[A" || key === "k") {
+        selectedIndex = (selectedIndex - 1 + items.length) % items.length;
+        render();
+      } else if (key === "\x1B[B" || key === "j") {
+        selectedIndex = (selectedIndex + 1) % items.length;
+        render();
+      } else if (key === " ") {
+        items[selectedIndex].mode = items[selectedIndex].mode === "extract" ? "copy" : "extract";
+        render();
+      } else if (key === "\r" || key === "\n") {
+        cleanup();
+        resolve(items);
+      } else if (key === "") {
+        cleanup();
+        stdout.write("\n");
+        process.exit(1);
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+function isStandardAgentsProject() {
+  if (!fs3.existsSync("agents")) {
+    return false;
+  }
+  try {
+    const pkgJson = JSON.parse(fs3.readFileSync("package.json", "utf-8"));
+    const deps = { ...pkgJson.dependencies, ...pkgJson.devDependencies };
+    return "@standardagents/builder" in deps;
+  } catch {
+    return false;
+  }
+}
+async function pack(agentName, options) {
+  logger.info("Packing agent...\n");
+  if (!isStandardAgentsProject()) {
+    logger.error("This does not appear to be a Standard Agents project.");
+    logger.info("Make sure you have @standardagents/builder installed and an agents/ directory.");
+    process.exit(1);
+  }
+  const rootDir = process.cwd();
+  let PackingService;
+  try {
+    const packing = await import('@standardagents/builder/packing');
+    PackingService = packing.PackingService;
+  } catch (err) {
+    logger.error("Failed to load packing service from @standardagents/builder");
+    logger.info("Make sure @standardagents/builder is installed and built.");
+    if (err instanceof Error) {
+      logger.info(`Error: ${err.message}`);
+    }
+    process.exit(1);
+  }
+  const packingService = new PackingService();
+  if (!agentName) {
+    const agents = packingService.listAgents(rootDir);
+    if (agents.length === 0) {
+      logger.error("No agents found in agents/agents/");
+      process.exit(1);
+    }
+    if (agents.length === 1) {
+      agentName = agents[0];
+      logger.info(`Found one agent: ${agentName}`);
+    } else {
+      console.log("");
+      agentName = await selectAgent(agents);
+      console.log("");
+    }
+  }
+  if (!agentName) {
+    logger.error("No agent selected");
+    process.exit(1);
+  }
+  const selectedAgent = agentName;
+  logger.info(`Analyzing agent: ${selectedAgent}`);
+  const analysis = await packingService.analyzeAgent(selectedAgent, rootDir);
+  if (analysis.errors.length > 0) {
+    logger.error("Analysis failed:");
+    for (const error of analysis.errors) {
+      console.log(`  - ${error}`);
+    }
+    process.exit(1);
+  }
+  console.log("");
+  logger.info("Discovered constituents:");
+  console.log(`  Agents:  ${analysis.constituents.agents.map((a) => a.name).join(", ") || "(none)"}`);
+  console.log(`  Prompts: ${analysis.constituents.prompts.map((p) => p.name).join(", ") || "(none)"}`);
+  console.log(`  Tools:   ${analysis.constituents.tools.map((t) => t.name).join(", ") || "(none)"}`);
+  console.log(`  Models:  ${analysis.constituents.models.map((m) => m.name).join(", ") || "(none)"}`);
+  console.log(`  Hooks:   ${analysis.constituents.hooks.map((h) => h.name).join(", ") || "(none)"}`);
+  if (analysis.warnings.length > 0) {
+    console.log("");
+    logger.warning("Warnings:");
+    for (const warning of analysis.warnings) {
+      console.log(`  - ${warning}`);
+    }
+  }
+  const selectionItems = [];
+  for (const agent of analysis.constituents.agents) {
+    selectionItems.push({
+      name: agent.name,
+      type: "agent",
+      filePath: agent.filePath,
+      mode: agent.sharedWith.length > 0 ? "copy" : "extract",
+      isShared: agent.sharedWith.length > 0,
+      sharedWith: agent.sharedWith
+    });
+  }
+  for (const prompt3 of analysis.constituents.prompts) {
+    selectionItems.push({
+      name: prompt3.name,
+      type: "prompt",
+      filePath: prompt3.filePath,
+      mode: prompt3.sharedWith.length > 0 ? "copy" : "extract",
+      isShared: prompt3.sharedWith.length > 0,
+      sharedWith: prompt3.sharedWith
+    });
+  }
+  for (const tool of analysis.constituents.tools) {
+    selectionItems.push({
+      name: tool.name,
+      type: "tool",
+      filePath: tool.filePath,
+      mode: tool.sharedWith.length > 0 ? "copy" : "extract",
+      isShared: tool.sharedWith.length > 0,
+      sharedWith: tool.sharedWith
+    });
+  }
+  for (const model of analysis.constituents.models) {
+    selectionItems.push({
+      name: model.name,
+      type: "model",
+      filePath: model.filePath,
+      mode: model.sharedWith.length > 0 ? "copy" : "extract",
+      isShared: model.sharedWith.length > 0,
+      sharedWith: model.sharedWith
+    });
+  }
+  for (const hook of analysis.constituents.hooks) {
+    selectionItems.push({
+      name: hook.name,
+      type: "hook",
+      filePath: hook.filePath,
+      mode: hook.sharedWith.length > 0 ? "copy" : "extract",
+      isShared: hook.sharedWith.length > 0,
+      sharedWith: hook.sharedWith
+    });
+  }
+  let itemSelections;
+  if (!options.noInteractive && process.stdin.isTTY && selectionItems.length > 0) {
+    console.log("");
+    const selections = await selectItemModes(selectionItems);
+    itemSelections = selections.map((s) => ({
+      name: s.name,
+      type: s.type,
+      filePath: s.filePath,
+      mode: s.mode
+    }));
+    console.log("");
+  }
+  const outputDir = options.output || path3.join(rootDir, "agents", "packed");
+  logger.info(`Packing to: ${outputDir}`);
+  const result = await packingService.pack({
+    agentName: selectedAgent,
+    rootDir,
+    outputDir,
+    version: options.version || "1.0.0",
+    npm: options.npm || false,
+    removeOriginals: itemSelections ? false : !options.noRemove,
+    // Let itemSelections handle removal
+    packageId: `standardagent-${selectedAgent.replace(/_/g, "-")}`,
+    itemSelections
+  });
+  if (!result.success) {
+    logger.error(`Packing failed: ${result.error}`);
+    process.exit(1);
+  }
+  console.log("");
+  logger.success("Packing complete!");
+  console.log(`  Package ID: ${result.packageId}`);
+  console.log(`  Output:     ${result.outputPath}`);
+  console.log(`  Files:      ${result.filesCreated.length} created`);
+  if (result.filesRemoved && result.filesRemoved.length > 0) {
+    console.log(`  Removed:    ${result.filesRemoved.length} original files`);
+  }
+  if (result.warnings.length > 0) {
+    console.log("");
+    logger.warning("Warnings:");
+    for (const warning of result.warnings) {
+      console.log(`  - ${warning}`);
+    }
+  }
+  if (options.npm) {
+    console.log("");
+    logger.info("NPM package structure created. To publish:");
+    console.log(`  cd ${result.outputPath}`);
+    console.log("  npm publish");
+  }
+}
+function isStandardAgentsProject2() {
+  if (!fs3.existsSync("agents")) {
+    return false;
+  }
+  try {
+    const pkgJson = JSON.parse(fs3.readFileSync("package.json", "utf-8"));
+    const deps = { ...pkgJson.dependencies, ...pkgJson.devDependencies };
+    return "@standardagents/builder" in deps;
+  } catch {
+    return false;
+  }
+}
+async function unpack(pkgIdentifier, options) {
+  logger.info("Unpacking agent...\n");
+  if (!isStandardAgentsProject2()) {
+    logger.error("This does not appear to be a Standard Agents project.");
+    logger.info("Make sure you have @standardagents/builder installed and an agents/ directory.");
+    process.exit(1);
+  }
+  const rootDir = process.cwd();
+  let UnpackingService;
+  try {
+    const builder = await import('@standardagents/builder/runtime');
+    UnpackingService = builder.UnpackingService;
+    if (!UnpackingService) {
+      const packing = await import('@standardagents/builder');
+      UnpackingService = packing.UnpackingService;
+    }
+  } catch (err) {
+    logger.error("Failed to load unpacking service from @standardagents/builder");
+    logger.info("Make sure @standardagents/builder is installed.");
+    process.exit(1);
+  }
+  const unpackingService = new UnpackingService();
+  if (!pkgIdentifier) {
+    const packages = await unpackingService.listPackages(rootDir);
+    if (packages.length === 0) {
+      logger.info("No packed agents found.");
+      logger.info("Pack an agent with: agents pack <agent-name>");
+      process.exit(0);
+    }
+    logger.info("Available packed agents:");
+    for (const pkg of packages) {
+      console.log(`  - ${pkg.packageId} (${pkg.version}) [${pkg.source}]`);
+      console.log(`    Entry: ${pkg.entryAgent}`);
+      console.log(`    Path:  ${pkg.path}`);
+      console.log("");
+    }
+    logger.info("Run: agents unpack <package-id>");
+    process.exit(0);
+  }
+  logger.info(`Unpacking: ${pkgIdentifier}`);
+  const result = await unpackingService.unpack({
+    package: pkgIdentifier,
+    rootDir,
+    keepSignatures: !options.noSignatures
+  });
+  if (!result.success) {
+    logger.error(`Unpacking failed: ${result.error}`);
+    process.exit(1);
+  }
+  console.log("");
+  logger.success("Unpacking complete!");
+  console.log(`  Package:    ${result.packageId}`);
+  console.log(`  Files:      ${result.filesCreated.length} created`);
+  if (result.filesCreated.length > 0) {
+    console.log("");
+    logger.info("Created files:");
+    for (const file of result.filesCreated) {
+      const relPath = path3.relative(rootDir, file);
+      console.log(`  - ${relPath}`);
+    }
+  }
+  if (result.warnings.length > 0) {
+    console.log("");
+    logger.warning("Warnings:");
+    for (const warning of result.warnings) {
+      console.log(`  - ${warning}`);
+    }
+  }
+  if (options.noSignatures) {
+    console.log("");
+    logger.info("Package signatures removed - files are fully editable.");
+  } else {
+    console.log("");
+    logger.info("Package signatures preserved - files are editable but marked as packed.");
+  }
+}
+async function listPacked() {
+  if (!isStandardAgentsProject2()) {
+    logger.error("This does not appear to be a Standard Agents project.");
+    logger.info("Make sure you have @standardagents/builder installed and an agents/ directory.");
+    process.exit(1);
+  }
+  const rootDir = process.cwd();
+  let UnpackingService;
+  try {
+    const builder = await import('@standardagents/builder/runtime');
+    UnpackingService = builder.UnpackingService;
+    if (!UnpackingService) {
+      const packing = await import('@standardagents/builder');
+      UnpackingService = packing.UnpackingService;
+    }
+  } catch (err) {
+    logger.error("Failed to load unpacking service from @standardagents/builder");
+    logger.info("Make sure @standardagents/builder is installed.");
+    process.exit(1);
+  }
+  const unpackingService = new UnpackingService();
+  const packages = await unpackingService.listPackages(rootDir);
+  if (packages.length === 0) {
+    logger.info("No packed agents found.");
+    logger.info("Pack an agent with: agents pack <agent-name>");
+    return;
+  }
+  logger.info("Discovered packed agents:\n");
+  for (const pkg of packages) {
+    console.log(`${pkg.packageId} (${pkg.version})`);
+    console.log(`  Source:  ${pkg.source}`);
+    console.log(`  Entry:   ${pkg.entryAgent}`);
+    console.log(`  Path:    ${pkg.path}`);
+    console.log("");
+  }
+}
 
 // src/index.ts
-var __dirname$1 = dirname(fileURLToPath(import.meta.url));
-var pkg = JSON.parse(readFileSync(resolve(__dirname$1, "../package.json"), "utf-8"));
 var program = new Command();
-program.name("agents").description("CLI tool for Standard Agents / AgentBuilder").version(pkg.version);
+program.name("agents").description("CLI tool for Standard Agents / AgentBuilder").version("0.12.0");
 program.command("init [project-name]").description("Create a new Standard Agents project (runs create vite, then scaffold)").option("-y, --yes", "Skip prompts and use defaults").option("--template <template>", "Vite template to use", "vanilla-ts").action(init);
 program.command("scaffold").description("Add Standard Agents to an existing Vite project").option("--force", "Overwrite existing configuration").action(scaffold);
 program.command("init-chat [project-name]").description("Scaffold a frontend chat application").option("-y, --yes", "Skip prompts and use defaults").option("--framework <framework>", "Framework to use (vite or nextjs)").action(initChat);
+program.command("pack [agent-name]").description("Pack an agent with all its dependencies").option("--output <dir>", "Output directory (default: agents/packed)").option("--npm", "Generate npm-ready package structure").option("--version <version>", "Package version (default: 1.0.0)").option("--no-remove", "Keep original files after packing").option("--no-interactive", "Skip interactive item mode selector").action(pack);
+program.command("unpack [package]").description("Unpack a packed agent to the local agents directory").option("--no-signatures", "Remove package signatures (fully editable)").action(unpack);
+program.command("list-packed").description("List all discovered packed agents").action(listPacked);
 program.parse();
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map