@townco/agent 0.1.54 → 0.1.56

package/dist/runner/langchain/tools/subagent.js

@@ -1,15 +1,44 @@
 import { spawn } from "node:child_process";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { Readable, Writable } from "node:stream";
-import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from "@agentclientprotocol/sdk";
+import { PROTOCOL_VERSION } from "@agentclientprotocol/sdk";
 import { context, propagation, trace } from "@opentelemetry/api";
+import { createLogger as coreCreateLogger } from "@townco/core";
 import { z } from "zod";
 import { SUBAGENT_MODE_KEY } from "../../../acp-server/adapter.js";
+import { findAvailablePort } from "./port-utils.js";
 /**
  * Name of the Task tool created by makeSubagentsTool
  */
 export const SUBAGENT_TOOL_NAME = "subagent";
+/**
+ * Base port for subagent HTTP servers (avoid conflict with main agents at 3100+)
+ */
+const SUBAGENT_BASE_PORT = 4000;
+/**
+ * Wait for HTTP server to be ready by polling health endpoint
+ */
+async function waitForServerReady(port, timeoutMs = 30000) {
+    const startTime = Date.now();
+    const baseDelay = 50;
+    let attempt = 0;
+    while (Date.now() - startTime < timeoutMs) {
+        try {
+            const response = await fetch(`http://localhost:${port}/health`, {
+                signal: AbortSignal.timeout(1000),
+            });
+            if (response.ok) {
+                return;
+            }
+        }
+        catch {
+            // Server not ready yet
+        }
+        await new Promise((r) => setTimeout(r, baseDelay * Math.pow(1.5, attempt)));
+        attempt++;
+    }
+    throw new Error(`Subagent server at port ${port} did not become ready within ${timeoutMs}ms`);
+}
 /**
  * Creates a DirectTool that delegates work to one of multiple configured subagents.
  *
@@ -145,14 +174,14 @@ assistant: "I'm going to use the Task tool to launch the greeting-responder agen
             if (!agent) {
                 throw new Error(`Unknown agent: ${agentName}`);
             }
-            return await querySubagent(agent.agentPath, agent.agentDir, query);
+            return await querySubagent(agentName, agent.agentPath, agent.agentDir, query);
         },
     };
 }
 /**
- * Internal function that spawns a subagent process and collects its response.
+ * Internal function that spawns a subagent HTTP server and queries it.
  */
-async function querySubagent(agentPath, agentWorkingDirectory, query) {
+async function querySubagent(agentName, agentPath, agentWorkingDirectory, query) {
     // Validate that the agent exists
     try {
         await fs.access(agentPath);
@@ -160,153 +189,227 @@ async function querySubagent(agentPath, agentWorkingDirectory, query) {
     catch (_error) {
         throw new Error(`Agent not found at ${agentPath}. Make sure the agent exists and has an index.ts file.`);
     }
+    // Find an available port for this subagent
+    const port = await findAvailablePort(SUBAGENT_BASE_PORT, 100);
+    // Create a logger for this subagent instance with port prefix
+    // Use core logger directly since service name already identifies the subagent
+    const logger = coreCreateLogger(`subagent:${port}:${agentName}`);
     let agentProcess = null;
-    let connection = null;
+    let sseAbortController = null;
     try {
-        // Spawn the agent process
-        agentProcess = spawn("bun", [agentPath], {
+        // Get the parent's logs directory to pass to the subagent
+        const parentLogsDir = process.env.TOWN_LOGS_DIR || path.join(process.cwd(), ".logs");
+        // Spawn the agent process in HTTP mode
+        agentProcess = spawn("bun", [agentPath, "http"], {
             cwd: agentWorkingDirectory,
-            env: { ...process.env },
+            env: {
+                ...process.env,
+                PORT: String(port),
+                TOWN_LOGS_DIR: parentLogsDir,
+                TOWN_SUBAGENT_NAME: agentName,
+            },
             stdio: ["pipe", "pipe", "pipe"],
         });
-        if (!agentProcess.stdin || !agentProcess.stdout || !agentProcess.stderr) {
-            throw new Error("Failed to create stdio pipes for agent process");
+        if (!agentProcess.stderr) {
+            throw new Error("Failed to create stderr pipe for agent process");
         }
-        // Convert Node.js streams to Web streams
-        const outputStream = Writable.toWeb(agentProcess.stdin);
-        const inputStream = Readable.toWeb(agentProcess.stdout);
-        // Create the bidirectional stream using ndJsonStream
-        const stream = ndJsonStream(outputStream, inputStream);
-        // Track accumulated response text
-        let responseText = "";
-        // Create ACP client implementation factory
-        const clientFactory = (_agent) => {
-            return {
-                async requestPermission(_params) {
-                    // Deny all permission requests from the subagent
-                    return { outcome: { outcome: "cancelled" } };
-                },
-                async sessionUpdate(params) {
-                    // Handle session updates from the agent
-                    const paramsExtended = params;
-                    const update = paramsExtended.update;
-                    // Reset accumulated text when a tool call starts (marks a new message boundary)
-                    if (update?.sessionUpdate === "tool_call") {
-                        responseText = "";
-                    }
-                    // Accumulate agent_message_chunk text content
-                    if (update?.sessionUpdate === "agent_message_chunk") {
-                        const content = update.content;
-                        if (content &&
-                            content.type === "text" &&
-                            typeof content.text === "string") {
-                            responseText += content.text;
-                        }
-                    }
-                },
-                async writeTextFile() {
-                    // Subagents should not write files outside their scope
-                    throw new Error("Subagent attempted to write files, which is not allowed");
-                },
-                async readTextFile() {
-                    // Subagents should not read files outside their scope
-                    throw new Error("Subagent attempted to read files, which is not allowed");
-                },
-            };
-        };
-        // Create the client-side connection
-        connection = new ClientSideConnection(clientFactory, stream);
-        // Set up timeout for the entire operation
-        const timeoutMs = 5 * 60 * 1000; // 5 minutes
-        const timeoutPromise = new Promise((_resolve, reject) => {
-            setTimeout(() => {
-                reject(new Error(`Subagent query timed out after ${timeoutMs / 1000} seconds`));
-            }, timeoutMs);
-        });
-        // Handle process errors and exit
-        const processExitPromise = new Promise((_resolve, reject) => {
-            agentProcess?.on("exit", (code, signal) => {
-                if (code !== 0 && code !== null) {
-                    reject(new Error(`Agent process exited with code ${code} and signal ${signal}`));
+        // Capture stdout and forward to logger
+        if (agentProcess.stdout) {
+            agentProcess.stdout.on("data", (data) => {
+                const lines = data
+                    .toString()
+                    .split("\n")
+                    .filter((line) => line.trim());
+                for (const line of lines) {
+                    logger.info(line);
                 }
             });
+        }
+        // Capture stderr and forward to logger as errors
+        agentProcess.stderr.on("data", (data) => {
+            const lines = data
+                .toString()
+                .split("\n")
+                .filter((line) => line.trim());
+            for (const line of lines) {
+                logger.error(line);
+            }
+        });
+        // Handle process errors
+        const processErrorPromise = new Promise((_, reject) => {
             agentProcess?.on("error", (error) => {
+                logger.error(`Process error: ${error.message}`);
                 reject(new Error(`Agent process error: ${error.message}`));
             });
+            agentProcess?.on("exit", (code, signal) => {
+                if (code !== 0 && code !== null) {
+                    logger.error(`Process exited with code ${code}, signal ${signal}`);
+                    reject(new Error(`Agent process exited unexpectedly with code ${code}, signal ${signal}`));
+                }
+            });
         });
-        // Run the query with timeout and error handling
-        const queryPromise = (async () => {
-            // Initialize the connection
-            await connection?.initialize({
-                protocolVersion: PROTOCOL_VERSION,
-                clientCapabilities: {
-                    fs: {
-                        readTextFile: false,
-                        writeTextFile: false,
+        logger.info(`Starting subagent HTTP server on port ${port}`);
+        // Wait for server to be ready
+        await Promise.race([waitForServerReady(port), processErrorPromise]);
+        logger.info(`Subagent server ready on port ${port}`);
+        const baseUrl = `http://localhost:${port}`;
+        // Step 1: Initialize ACP connection
+        const initResponse = await fetch(`${baseUrl}/rpc`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: "init-1",
+                method: "initialize",
+                params: {
+                    protocolVersion: PROTOCOL_VERSION,
+                    clientCapabilities: {
+                        fs: { readTextFile: false, writeTextFile: false },
                     },
                 },
-            });
-            // Prepare OpenTelemetry trace context to propagate to the subagent.
-            // We inject from the current active context so the subagent's root
-            // invocation span can be a child of whatever span is active when
-            // this Task tool runs (ideally the agent.tool_call span).
-            if (process.env.DEBUG_TELEMETRY === "true") {
-                console.log(`[querySubagent] Tool function executing for agent: ${agentPath}`);
-            }
-            const otelCarrier = {};
-            const activeCtx = context.active();
-            const activeSpan = trace.getSpan(activeCtx);
-            if (process.env.DEBUG_TELEMETRY === "true") {
-                console.log(`[querySubagent] Active span when tool executes:`, activeSpan?.spanContext());
-            }
-            const ctxForInjection = activeSpan
-                ? trace.setSpan(activeCtx, activeSpan)
-                : activeCtx;
+            }),
+        });
+        if (!initResponse.ok) {
+            throw new Error(`Initialize failed: HTTP ${initResponse.status}`);
+        }
+        // Step 2: Create new session with subagent mode and OTEL context
+        // Prepare OpenTelemetry trace context to propagate to the subagent
+        const otelCarrier = {};
+        const activeCtx = context.active();
+        const activeSpan = trace.getSpan(activeCtx);
+        if (process.env.DEBUG_TELEMETRY === "true") {
+            console.log(`[querySubagent] Active span when tool executes:`, activeSpan?.spanContext());
+        }
+        if (activeSpan) {
+            const ctxForInjection = trace.setSpan(activeCtx, activeSpan);
             propagation.inject(ctxForInjection, otelCarrier);
-            const hasOtelContext = Object.keys(otelCarrier).length > 0;
-            // Create a new session with subagent mode flag and OTEL trace context
-            const sessionResponse = await connection?.newSession({
-                cwd: agentWorkingDirectory,
-                mcpServers: [],
-                _meta: {
-                    [SUBAGENT_MODE_KEY]: true,
-                    ...(hasOtelContext ? { otelTraceContext: otelCarrier } : {}),
+        }
+        const hasOtelContext = Object.keys(otelCarrier).length > 0;
+        const sessionResponse = await fetch(`${baseUrl}/rpc`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: "session-1",
+                method: "session/new",
+                params: {
+                    cwd: agentWorkingDirectory,
+                    mcpServers: [],
+                    _meta: {
+                        [SUBAGENT_MODE_KEY]: true,
+                        ...(hasOtelContext ? { otelTraceContext: otelCarrier } : {}),
+                    },
                 },
+            }),
+        });
+        if (!sessionResponse.ok) {
+            throw new Error(`Session creation failed: HTTP ${sessionResponse.status}`);
+        }
+        const sessionResult = (await sessionResponse.json());
+        const sessionId = sessionResult.result?.sessionId;
+        if (!sessionId) {
+            throw new Error("No sessionId in session/new response");
+        }
+        // Step 3: Connect to SSE for receiving streaming responses
+        sseAbortController = new AbortController();
+        let responseText = "";
+        const ssePromise = (async () => {
+            const sseResponse = await fetch(`${baseUrl}/events`, {
+                headers: { "X-Session-ID": sessionId },
+                signal: sseAbortController.signal,
             });
-            // Send the prompt
-            await connection?.prompt({
-                sessionId: sessionResponse.sessionId,
-                prompt: [
-                    {
-                        type: "text",
-                        text: query,
+            if (!sseResponse.ok || !sseResponse.body) {
+                throw new Error(`SSE connection failed: HTTP ${sseResponse.status}`);
+            }
+            const reader = sseResponse.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = "";
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop() || "";
+                for (const line of lines) {
+                    if (line.startsWith("data:")) {
+                        const data = line.substring(5).trim();
+                        if (!data)
+                            continue;
+                        try {
+                            const message = JSON.parse(data);
+                            // Handle session/update notifications for agent_message_chunk
+                            if (message.method === "session/update" &&
+                                message.params?.update?.sessionUpdate === "agent_message_chunk") {
+                                const content = message.params.update.content;
+                                if (content?.type === "text" &&
+                                    typeof content.text === "string") {
+                                    responseText += content.text;
+                                }
+                            }
+                            // Reset on tool_call (marks new message boundary)
+                            if (message.params?.update?.sessionUpdate === "tool_call") {
+                                responseText = "";
+                            }
+                        }
+                        catch {
+                            // Ignore malformed SSE data
+                        }
+                    }
+                }
+            }
+        })();
+        // Step 4: Send the prompt with timeout
+        const timeoutMs = 5 * 60 * 1000; // 5 minutes
+        const promptPromise = (async () => {
+            const promptResponse = await fetch(`${baseUrl}/rpc`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: "prompt-1",
+                    method: "session/prompt",
+                    params: {
+                        sessionId,
+                        prompt: [{ type: "text", text: query }],
                     },
-                ],
+                }),
             });
-            return responseText;
+            if (!promptResponse.ok) {
+                throw new Error(`Prompt failed: HTTP ${promptResponse.status}`);
+            }
+            // Wait for prompt to complete (this blocks until agent finishes processing)
+            const promptResult = (await promptResponse.json());
+            if (promptResult.error) {
+                throw new Error(`Prompt error: ${promptResult.error.message || JSON.stringify(promptResult.error)}`);
+            }
         })();
-        // Race between query execution, timeout, and process exit
-        return await Promise.race([
-            queryPromise,
-            timeoutPromise,
-            processExitPromise,
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(`Subagent query timed out after ${timeoutMs / 1000} seconds`));
+            }, timeoutMs);
+        });
+        // Wait for prompt to complete with timeout
+        await Promise.race([promptPromise, timeoutPromise, processErrorPromise]);
+        // Give SSE a moment to flush remaining messages
+        await new Promise((r) => setTimeout(r, 100));
+        // Abort SSE connection
+        sseAbortController.abort();
+        // Wait for SSE to finish (with timeout)
+        await Promise.race([
+            ssePromise.catch(() => { }), // Ignore abort errors
+            new Promise((r) => setTimeout(r, 1000)),
         ]);
+        return responseText;
     }
     finally {
-        // Cleanup: kill process and close connection
+        // Cleanup: abort SSE and kill process
+        logger.info(`Shutting down subagent on port ${port}`);
+        if (sseAbortController) {
+            sseAbortController.abort();
+        }
         if (agentProcess) {
             agentProcess.kill();
         }
-        if (connection) {
-            try {
-                await Promise.race([
-                    connection.closed,
-                    new Promise((resolve) => setTimeout(resolve, 1000)),
-                ]);
-            }
-            catch {
-                // Ignore cleanup errors
-            }
-        }
     }
 }

package/dist/runner/tools.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 /** Built-in tool types. */
-export declare const zBuiltInToolType: z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"filesystem">, z.ZodLiteral<"generate_image">]>;
+export declare const zBuiltInToolType: z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"filesystem">, z.ZodLiteral<"generate_image">, z.ZodLiteral<"browser">]>;
 /** Subagent configuration schema for Task tools. */
 export declare const zSubagentConfig: z.ZodObject<{
     agentName: z.ZodString;
@@ -23,7 +23,7 @@ declare const zDirectTool: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 /** Tool type - can be a built-in tool string or custom tool object. */
-export declare const zToolType: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"filesystem">, z.ZodLiteral<"generate_image">]>, z.ZodObject<{
+export declare const zToolType: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"filesystem">, z.ZodLiteral<"generate_image">, z.ZodLiteral<"browser">]>, z.ZodObject<{
     type: z.ZodLiteral<"custom">;
     modulePath: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{

package/dist/runner/tools.js

@@ -6,6 +6,7 @@ export const zBuiltInToolType = z.union([
     z.literal("web_search"),
     z.literal("filesystem"),
     z.literal("generate_image"),
+    z.literal("browser"),
 ]);
 /** Custom tool schema (loaded from module path). */
 const zCustomTool = z.object({

package/dist/scaffold/index.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { mkdir, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { generateBinTs, generateIndexTs, getTemplateVars } from "../templates";
+import { generateBinTs, generateEnvExample, generateIndexTs, generateReadme, getTemplateVars, } from "../templates";
 import { copyGuiApp } from "./copy-gui";
 import { copyTuiApp } from "./copy-tui";
 /**
@@ -34,7 +34,13 @@ export async function scaffoldAgent(options) {
         const files = [
             { path: "index.ts", content: await generateIndexTs(vars) },
             { path: "bin.ts", content: generateBinTs(), executable: true },
+            { path: "README.md", content: generateReadme(vars) },
         ];
+        // Add .env.example if needed
+        const envExample = generateEnvExample(vars);
+        if (envExample) {
+            files.push({ path: ".env.example", content: envExample });
+        }
         // Write all files
         for (const file of files) {
             const filePath = join(agentPath, file.path);

package/dist/scaffold/templates/dot-claude/CLAUDE-append.md

@@ -9,6 +9,8 @@ The following built-in tools are available:
 - `todo_write`: Task management and planning tool
 - `web_search`: Exa-powered web search (requires EXA_API_KEY)
 - `filesystem`: Read, write, and search files in the project directory
+- `generate_image`: Image generation using Google Gemini (requires GEMINI_API_KEY or GOOGLE_API_KEY)
+- `browser`: Cloud browser automation using Kernel (requires KERNEL_API_KEY)
 
 To use built-in tools, simply add them to the `tools` array in your agent definition:
 ```

package/dist/storage/index.js

@@ -1,7 +1,7 @@
 import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { createLogger } from "@townco/core";
+import { createLogger } from "../logger.js";
 const AGENTS_DIR = join(homedir(), ".config", "town", "agents");
 const logger = createLogger("storage");
 /**

package/dist/telemetry/index.d.ts

@@ -23,6 +23,11 @@ declare class AgentTelemetry {
     private serviceName;
     private baseAttributes;
     configure(config: TelemetryConfig): void;
+    /**
+     * Update base attributes that will be added to all future spans
+     * @param attributes - Attributes to merge with existing base attributes
+     */
+    setBaseAttributes(attributes: Record<string, string | number>): void;
     /**
      * Start a new span
      * @param name - Span name

package/dist/telemetry/index.js

@@ -30,6 +30,16 @@ class AgentTelemetry {
             }
         }
     }
+    /**
+     * Update base attributes that will be added to all future spans
+     * @param attributes - Attributes to merge with existing base attributes
+     */
+    setBaseAttributes(attributes) {
+        this.baseAttributes = {
+            ...this.baseAttributes,
+            ...attributes,
+        };
+    }
     /**
      * Start a new span
      * @param name - Span name

package/dist/templates/index.d.ts

@@ -20,6 +20,8 @@ export interface TemplateVars {
     }>;
     systemPrompt: string | null;
     hasWebSearch: boolean;
+    hasGenerateImage: boolean;
+    hasBrowser: boolean;
     hooks?: Array<{
         type: "context_size";
         setting?: {

package/dist/templates/index.js

@@ -7,6 +7,8 @@ export function getTemplateVars(name, definition) {
         tools,
         systemPrompt: definition.systemPrompt,
         hasWebSearch: tools.some((tool) => typeof tool === "string" && tool === "web_search"),
+        hasGenerateImage: tools.some((tool) => typeof tool === "string" && tool === "generate_image"),
+        hasBrowser: tools.some((tool) => typeof tool === "string" && tool === "browser"),
         hooks: definition.hooks,
     };
     if (definition.displayName) {
@@ -74,8 +76,8 @@ export async function generateIndexTs(vars) {
     }
     return prettier.format(`import { makeHttpTransport, makeStdioTransport } from "@townco/agent/acp-server";
 import type { AgentDefinition } from "@townco/agent/definition";
+import { createLogger } from "@townco/agent/logger";
 import { basename } from "node:path";
-import { createLogger } from "@townco/core";
 
 const logger = createLogger("agent-index");
 
@@ -148,9 +150,15 @@ export function generateReadme(vars) {
         })
             .join(", ")
         : "None";
-    const envVars = vars.hasWebSearch
-        ? "\n- `EXA_API_KEY`: Required for web_search tool"
-        : "";
+    const envVars = [
+        vars.hasWebSearch ? "- `EXA_API_KEY`: Required for web_search tool" : "",
+        vars.hasGenerateImage
+            ? "- `GEMINI_API_KEY` (or `GOOGLE_API_KEY`): Required for generate_image tool"
+            : "",
+        vars.hasBrowser ? "- `KERNEL_API_KEY`: Required for browser tool" : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
     return `# ${vars.name}
 
 Agent created with \`town create\`.
@@ -211,10 +219,24 @@ bun run build
 `;
 }
 export function generateEnvExample(vars) {
-    if (!vars.hasWebSearch) {
+    const envs = [];
+    if (vars.hasWebSearch) {
+        envs.push("# Required for web_search tool");
+        envs.push("EXA_API_KEY=your_exa_api_key_here");
+        envs.push("");
+    }
+    if (vars.hasGenerateImage) {
+        envs.push("# Required for generate_image tool");
+        envs.push("GEMINI_API_KEY=your_gemini_api_key_here");
+        envs.push("");
+    }
+    if (vars.hasBrowser) {
+        envs.push("# Required for browser tool");
+        envs.push("KERNEL_API_KEY=your_kernel_api_key_here");
+        envs.push("");
+    }
+    if (envs.length === 0) {
         return null;
     }
-    return `# Required for web_search tool
-EXA_API_KEY=your_exa_api_key_here
-`;
+    return envs.join("\n");
 }