@standardagents/cli 0.11.0-next.5d2e71b → 0.11.0-next.7005954

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,30 +116,32 @@ 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;
+  const threadId = flow.threadId;
+  const { messages } = await flow.getMessages();
   // ...
 });
 \`\`\`
@@ -525,12 +527,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 +541,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 +564,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 +610,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 +623,8 @@ export default defineTool(
         error: \`Failed to fetch user: \${error.message}\`,
       };
     }
-  }
-);
+  },
+});
 \`\`\`
 
 ## Queueing Additional Tools
@@ -631,21 +634,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 +658,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 +722,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
 
@@ -1046,9 +1093,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 {
     }
@@ -1433,15 +1480,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);
@@ -1462,7 +1509,7 @@ async function promptPassword(question) {
           stdin.pause();
           stdin.removeListener("data", onData);
           stdout.write("\n");
-          resolve2(password);
+          resolve(password);
           break;
         case "":
           stdout.write("\n");
@@ -1488,7 +1535,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",
@@ -1496,7 +1543,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}`));
       }
@@ -1520,25 +1567,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.11.0-next.7005954";
 }
 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;
@@ -1584,7 +1622,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");
@@ -1670,34 +1708,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",
-      "wrangler"
-    ], projectPath);
-    await runCommand(pm, [
-      installCmd,
-      `@standardagents/builder${builderVersion}`,
-      "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 = "";
@@ -1732,6 +1743,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",
@@ -1788,10 +1837,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];
@@ -1802,23 +1851,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",
@@ -1826,7 +1875,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}`));
       }
@@ -1850,7 +1899,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;
@@ -1896,7 +1945,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");
@@ -1911,7 +1960,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;
@@ -1955,7 +2004,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");
@@ -1975,20 +2024,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);
     });
@@ -2212,21 +2261,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}
@@ -2281,21 +2330,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}
@@ -2317,10 +2366,8 @@ out
 }
 
 // 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.11.0-next.7005954");
 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);