@townco/agent 0.1.28 → 0.1.29

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

@@ -0,0 +1,278 @@
+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 { z } from "zod";
+import { SUBAGENT_MODE_KEY } from "../../../acp-server/adapter.js";
+/**
+ * Name of the Task tool created by makeSubagentsTool
+ */
+export const TASK_TOOL_NAME = "Task";
+/**
+ * Creates a DirectTool that delegates work to one of multiple configured subagents.
+ *
+ * @param configs - Array of subagent configurations
+ * @returns A DirectTool named "Task" that can route to any configured subagent
+ *
+ * @example
+ * ```typescript
+ * import { makeSubagentsTool } from "@townco/agent/utils";
+ *
+ * const agent: AgentDefinition = {
+ *   model: "claude-sonnet-4-5-20250929",
+ *   systemPrompt: "You are a coordinator.",
+ *   tools: [
+ *     makeSubagentsTool([
+ *       { agentName: "researcher", description: "Use this agent to research topics", cwd: "/path/to/agents" },
+ *       { agentName: "writer", description: "Use this agent to write content", path: "/absolute/path/to/writer/index.ts" },
+ *     ]),
+ *   ]
+ * };
+ * ```
+ */
+export function makeSubagentsTool(configs) {
+    if (configs.length === 0) {
+        throw new Error("makeSubagentsTool requires at least one subagent configuration");
+    }
+    // Build a map from agentName to resolved paths
+    const agentMap = new Map();
+    for (const config of configs) {
+        const { agentName } = config;
+        let agentPath;
+        let agentDir;
+        if ("path" in config) {
+            // Direct path variant
+            agentPath = config.path;
+            agentDir = path.dirname(agentPath);
+        }
+        else {
+            // Agent name + cwd variant
+            const { cwd: workingDirectory } = config;
+            const resolvedWorkingDirectory = workingDirectory ?? path.resolve("agents", agentName, "..", "..");
+            agentDir = path.join(resolvedWorkingDirectory, "agents", agentName);
+            agentPath = path.join(agentDir, "index.ts");
+        }
+        agentMap.set(agentName, { agentPath, agentDir });
+    }
+    // Build the tool description with all subagent descriptions
+    const agentDescriptions = configs
+        .map((config) => `"${config.agentName}": ${config.description}`)
+        .join("\n");
+    const agentNames = configs.map((c) => c.agentName);
+    return {
+        type: "direct",
+        name: TASK_TOOL_NAME,
+        description: `Launch a new agent to handle complex, multi-step tasks autonomously.
+
+The Task tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+
+Available agent types and the tools they have access to:
+${agentDescriptions}
+
+When NOT to use the Task tool:
+- If you want to read a specific file path, use the Read or Glob tool instead of the Task tool, to find the match more quickly
+- If you are searching for a specific class definition like "class Foo", use the Glob tool instead, to find the match more quickly
+- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Task tool, to find the match more quickly
+- Other tasks that are not related to the agent descriptions above
+
+
+Usage notes:
+- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+- Each agent invocation is stateless. You will not be able to send additional messages to the agent, nor will the agent be able to communicate with you outside of its final report. Therefore, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
+- The agent's outputs should generally be trusted
+- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
+- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
+- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple Task tool use content blocks. For example, if you need to launch both a code-reviewer agent and a test-runner agent in parallel, send a single message with both tool calls.
+
+Example usage:
+
+<example_agent_descriptions>
+"code-reviewer": use this agent after you are done writing a signficant piece of code
+"greeting-responder": use this agent when to respond to user greetings with a friendly joke
+</example_agent_description>
+
+<example>
+user: "Please write a function that checks if a number is prime"
+assistant: Sure let me write a function that checks if a number is prime
+assistant: First let me use the Write tool to write a function that checks if a number is prime
+assistant: I'm going to use the Write tool to write the following code:
+<code>
+function isPrime(n) {
+  if (n <= 1) return false
+  for (let i = 2; i * i <= n; i++) {
+    if (n % i === 0) return false
+  }
+  return true
+}
+</code>
+<commentary>
+Since a signficant piece of code was written and the task was completed, now use the code-reviewer agent to review the code
+</commentary>
+assistant: Now let me use the code-reviewer agent to review the code
+assistant: Uses the Task tool to launch the code-reviewer agent
+</example>
+
+<example>
+user: "Hello"
+<commentary>
+Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
+</commentary>
+assistant: "I'm going to use the Task tool to launch the greeting-responder agent"
+</example>
+`,
+        schema: z.object({
+            agentName: z
+                .enum(agentNames)
+                .describe("The name of the subagent to use"),
+            query: z.string().describe("The query or task to send to the subagent"),
+        }),
+        fn: async (input) => {
+            const { agentName, query } = input;
+            const agent = agentMap.get(agentName);
+            if (!agent) {
+                throw new Error(`Unknown agent: ${agentName}`);
+            }
+            return await querySubagent(agent.agentPath, agent.agentDir, query);
+        },
+    };
+}
+/**
+ * Internal function that spawns a subagent process and collects its response.
+ */
+async function querySubagent(agentPath, agentWorkingDirectory, query) {
+    // Validate that the agent exists
+    try {
+        await fs.access(agentPath);
+    }
+    catch (_error) {
+        throw new Error(`Agent not found at ${agentPath}. Make sure the agent exists and has an index.ts file.`);
+    }
+    let agentProcess = null;
+    let connection = null;
+    try {
+        // Spawn the agent process
+        agentProcess = spawn("bun", [agentPath], {
+            cwd: agentWorkingDirectory,
+            env: { ...process.env },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        if (!agentProcess.stdin || !agentProcess.stdout || !agentProcess.stderr) {
+            throw new Error("Failed to create stdio pipes 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;
+                    // 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}`));
+                }
+            });
+            agentProcess?.on("error", (error) => {
+                reject(new Error(`Agent process error: ${error.message}`));
+            });
+        });
+        // 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,
+                    },
+                },
+            });
+            // Create a new session with subagent mode flag
+            const sessionResponse = await connection?.newSession({
+                cwd: agentWorkingDirectory,
+                mcpServers: [],
+                _meta: {
+                    [SUBAGENT_MODE_KEY]: true,
+                },
+            });
+            // Send the prompt
+            await connection?.prompt({
+                sessionId: sessionResponse.sessionId,
+                prompt: [
+                    {
+                        type: "text",
+                        text: query,
+                    },
+                ],
+            });
+            return responseText;
+        })();
+        // Race between query execution, timeout, and process exit
+        return await Promise.race([
+            queryPromise,
+            timeoutPromise,
+            processExitPromise,
+        ]);
+    }
+    finally {
+        // Cleanup: kill process and close connection
+        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/langchain/tools/todo.d.ts

@@ -1,49 +1,34 @@
 import { z } from "zod";
-export declare const todoItemSchema: z.ZodObject<
-	{
-		content: z.ZodString;
-		status: z.ZodEnum<{
-			pending: "pending";
-			in_progress: "in_progress";
-			completed: "completed";
-		}>;
-		activeForm: z.ZodString;
-	},
-	z.core.$strip
->;
-export declare const todoWrite: import("langchain").DynamicStructuredTool<
-	z.ZodObject<
-		{
-			todos: z.ZodArray<
-				z.ZodObject<
-					{
-						content: z.ZodString;
-						status: z.ZodEnum<{
-							pending: "pending";
-							in_progress: "in_progress";
-							completed: "completed";
-						}>;
-						activeForm: z.ZodString;
-					},
-					z.core.$strip
-				>
-			>;
-		},
-		z.core.$strip
-	>,
-	{
-		todos: {
-			content: string;
-			status: "pending" | "in_progress" | "completed";
-			activeForm: string;
-		}[];
-	},
-	{
-		todos: {
-			content: string;
-			status: "pending" | "in_progress" | "completed";
-			activeForm: string;
-		}[];
-	},
-	string
->;
+export declare const TODO_WRITE_TOOL_NAME = "todo_write";
+export declare const todoItemSchema: z.ZodObject<{
+    content: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        in_progress: "in_progress";
+        completed: "completed";
+    }>;
+    activeForm: z.ZodString;
+}, z.core.$strip>;
+export declare const todoWrite: import("langchain").DynamicStructuredTool<z.ZodObject<{
+    todos: z.ZodArray<z.ZodObject<{
+        content: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            in_progress: "in_progress";
+            completed: "completed";
+        }>;
+        activeForm: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>, {
+    todos: {
+        content: string;
+        status: "pending" | "in_progress" | "completed";
+        activeForm: string;
+    }[];
+}, {
+    todos: {
+        content: string;
+        status: "pending" | "in_progress" | "completed";
+        activeForm: string;
+    }[];
+}, string>;

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

@@ -1,5 +1,6 @@
 import { tool } from "langchain";
 import { z } from "zod";
+export const TODO_WRITE_TOOL_NAME = "todo_write";
 export const todoItemSchema = z.object({
     content: z.string().min(1),
     status: z.enum(["pending", "in_progress", "completed"]),
@@ -9,7 +10,7 @@ export const todoWrite = tool(({ todos }) => {
     // Simple implementation that confirms the todos were written
     return `Successfully updated todo list with ${todos.length} items`;
 }, {
-    name: "todo_write",
+    name: TODO_WRITE_TOOL_NAME,
     description: `Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
 It also helps the user understand the progress of the task and overall progress of their requests.
 

package/dist/runner/langchain/tools/web_search.d.ts

@@ -13,8 +13,11 @@ export declare function makeWebSearchTools(): readonly [import("langchain").Dyna
     };
 }>>, import("langchain").DynamicStructuredTool<z.ZodObject<{
     url: z.ZodString;
+    prompt: z.ZodString;
 }, z.core.$strip>, {
     url: string;
+    prompt: string;
 }, {
     url: string;
+    prompt: string;
 }, string>];

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

@@ -1,3 +1,4 @@
+import Anthropic from "@anthropic-ai/sdk";
 import Exa from "exa-js";
 import { tool } from "langchain";
 import { z } from "zod";
@@ -46,7 +47,7 @@ export function makeWebSearchTools() {
         }),
     });
     // WebFetch tool - get contents of specific URLs
-    const webFetch = tool(async ({ url }) => {
+    const webFetch = tool(async ({ url, prompt }) => {
         const client = getExaClient();
         try {
             const result = await client.getContents([url], {
@@ -60,16 +61,32 @@ export function makeWebSearchTools() {
             if (!page) {
                 return `No content found for URL: ${url}`;
             }
-            let output = `Title: ${page.title}\n`;
-            output += `URL: ${page.url}\n`;
-            if (page.author) {
-                output += `Author: ${page.author}\n`;
+            const pageContent = page.text || "(No text content available)";
+            // Process the content with Anthropic API
+            const apiKey = process.env.ANTHROPIC_API_KEY;
+            if (!apiKey) {
+                throw new Error("ANTHROPIC_API_KEY environment variable is required to use the WebFetch tool. " +
+                    "Please set it to your Anthropic API key.");
             }
-            if (page.publishedDate) {
-                output += `Published: ${page.publishedDate}\n`;
+            const anthropicClient = new Anthropic({ apiKey });
+            const userMessage = buildWebFetchUserMessage(pageContent, prompt);
+            const response = await anthropicClient.messages.create({
+                model: "claude-haiku-4-5-20251001",
+                max_tokens: 1024,
+                system: "You are a helpful assistant",
+                messages: [
+                    {
+                        role: "user",
+                        content: userMessage,
+                    },
+                ],
+            });
+            // Extract text from response
+            const textContent = response.content.find((block) => block.type === "text");
+            if (!textContent || textContent.type !== "text") {
+                return "Error: No text response from AI model";
             }
-            output += `\nContent:\n${page.text || "(No text content available)"}`;
-            return output;
+            return textContent.text;
         }
         catch (error) {
             if (error instanceof Error) {
@@ -79,16 +96,41 @@ export function makeWebSearchTools() {
         }
     }, {
         name: "WebFetch",
-        description: "Fetches the full text content of a specific webpage using its URL. " +
-            "Returns the page title, URL, author (if available), published date (if available), and full text content. " +
-            "Use this tool when you need to read the complete contents of a webpage that you already know the URL for. " +
-            "For finding URLs, use the WebSearch tool first.",
+        description: "- Fetches content from a specified URL and processes it using an AI model\n" +
+            "- Takes a URL and a prompt as input\n" +
+            "- Fetches the URL content, converts HTML to markdown\n" +
+            "- Processes the content with the prompt using a small, fast model\n" +
+            "- Returns the model's response about the content\n" +
+            "- Use this tool when you need to retrieve and analyze web content\n" +
+            "\n" +
+            "Usage notes:\n" +
+            "  - The URL must be a fully-formed valid URL\n" +
+            "  - HTTP URLs will be automatically upgraded to HTTPS\n" +
+            "  - The prompt should describe what information you want to extract from the page\n" +
+            "  - This tool is read-only and does not modify any files\n" +
+            "  - Results may be summarized if the content is very large\n" +
+            "  - When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL to fetch the content.\n",
         schema: z.object({
             url: z
                 .string()
                 .url()
                 .describe("The URL of the webpage to fetch content from"),
+            prompt: z.string().describe("The prompt to run on the fetched content"),
         }),
     });
     return [webSearch, webFetch];
 }
+function buildWebFetchUserMessage(pageContent, prompt) {
+    return `Web page content:
+---
+${pageContent}
+---
+
+${prompt}
+
+Provide a concise response based only on the content above. In your response:
+ - Enforce a strict 125-character maximum for quotes from any source document. Open Source Software is ok as long as we respect the license.
+ - Use quotation marks for exact language from articles; any language outside of the quotation should never be word-for-word the same.
+ - You are not a lawyer and never comment on the legality of your own prompts and responses.
+ - Never produce or reproduce exact song lyrics.`;
+}

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

@@ -97,3 +97,76 @@ const agent: AgentDefinition = {
   ],
 };
 ```
+
+## Adding Subagents
+Subagents allow you to delegate complex, multi-step tasks to specialized agents. The `makeSubagentsTool` utility creates a "Task" tool that can route work to different subagents based on their capabilities.
+
+### Configuration
+Import `makeSubagentsTool` and add it to your agent's tools:
+
+```typescript
+import { makeSubagentsTool } from '@townco/agent/utils';
+
+const agent: AgentDefinition = {
+  model: "claude-sonnet-4-5-20250929",
+  systemPrompt: "You are a coordinator agent.",
+  tools: [
+    "todo_write",
+    "filesystem",
+    makeSubagentsTool([
+      {
+        agentName: "researcher",
+        description: "Use this agent to research topics and gather information",
+      },
+      {
+        agentName: "code-reviewer",
+        description: "Use this agent to review code for bugs and improvements",
+        path: "/absolute/path/to/code-reviewer/index.ts",
+      },
+    ]),
+  ],
+};
+```
+
+### Configuration options
+Each subagent config supports two variants:
+
+**1. Adding an agent in the current workspace:**
+This should be used for agents that are in the current Town workspace (in the
+same `agents/` directory).
+```typescript
+{
+  agentName: "researcher",
+  description: "Agent description for the LLM",
+}
+```
+This expects the agent at `{workspace_dir}/agents/{agentName}/index.ts`
+
+**2. Using `path` (direct path):**
+```typescript
+{
+  agentName: "code-reviewer",
+  description: "Agent description for the LLM",
+  path: "/absolute/path/to/agent/index.ts",
+}
+```
+This uses the exact path specified (this is useful for agents outside the
+standard location -- this is rarely the case)
+
+### Usage example
+Once configured, the parent agent can delegate tasks:
+```typescript
+// The agent will see a "Task" tool with these parameters:
+// - agentName: enum of ["researcher", "code-reviewer"]
+// - query: string describing the task
+
+// Example prompt that triggers the Task tool:
+// "Please research the latest best practices for React hooks"
+// -> Agent uses Task tool with agentName="researcher"
+```
+
+### Best practices
+- Give each subagent a clear, specific description of its purpose
+- Keep subagent responsibilities focused and non-overlapping
+- Use descriptive agent names that indicate their role
+- Remember that subagents cannot use the Task tool (no nested subagents)