@townco/agent 0.1.24 → 0.1.26

package/dist/acp-server/adapter.d.ts

@@ -2,14 +2,18 @@ import * as acp from "@agentclientprotocol/sdk";
 import type { AgentRunner } from "../runner";
 /** Adapts an Agent to speak the ACP protocol */
 export declare class AgentAcpAdapter implements acp.Agent {
-    private connection;
-    private sessions;
-    private agent;
-    constructor(agent: AgentRunner, connection: acp.AgentSideConnection);
-    initialize(_params: acp.InitializeRequest): Promise<acp.InitializeResponse>;
-    newSession(_params: acp.NewSessionRequest): Promise<acp.NewSessionResponse>;
-    authenticate(_params: acp.AuthenticateRequest): Promise<acp.AuthenticateResponse | undefined>;
-    setSessionMode(_params: acp.SetSessionModeRequest): Promise<acp.SetSessionModeResponse>;
-    prompt(params: acp.PromptRequest): Promise<acp.PromptResponse>;
-    cancel(params: acp.CancelNotification): Promise<void>;
+	private connection;
+	private sessions;
+	private agent;
+	constructor(agent: AgentRunner, connection: acp.AgentSideConnection);
+	initialize(_params: acp.InitializeRequest): Promise<acp.InitializeResponse>;
+	newSession(_params: acp.NewSessionRequest): Promise<acp.NewSessionResponse>;
+	authenticate(
+		_params: acp.AuthenticateRequest,
+	): Promise<acp.AuthenticateResponse | undefined>;
+	setSessionMode(
+		_params: acp.SetSessionModeRequest,
+	): Promise<acp.SetSessionModeResponse>;
+	prompt(params: acp.PromptRequest): Promise<acp.PromptResponse>;
+	cancel(params: acp.CancelNotification): Promise<void>;
 }

package/dist/acp-server/adapter.js

@@ -56,6 +56,16 @@ export class AgentAcpAdapter {
                 sessionId: params.sessionId,
                 messageId,
             })) {
+                // Debug: log if this is an agent_message_chunk with tokenUsage in _meta
+                if ("sessionUpdate" in msg &&
+                    msg.sessionUpdate === "agent_message_chunk") {
+                    if ("_meta" in msg &&
+                        msg._meta &&
+                        typeof msg._meta === "object" &&
+                        "tokenUsage" in msg._meta) {
+                        console.error("DEBUG adapter: sending agent_message_chunk with tokenUsage in _meta:", JSON.stringify(msg._meta.tokenUsage));
+                    }
+                }
                 // The agent may emit extended types (like tool_output) that aren't in ACP SDK yet
                 // The http transport will handle routing these appropriately
                 this.connection.sessionUpdate({

package/dist/acp-server/cli.d.ts

@@ -1,3 +1,5 @@
 import type { AgentDefinition } from "../definition";
 import { type AgentRunner } from "../runner";
-export declare function makeStdioTransport(agent: AgentRunner | AgentDefinition): void;
+export declare function makeStdioTransport(
+	agent: AgentRunner | AgentDefinition,
+): void;

package/dist/acp-server/cli.js

@@ -3,9 +3,13 @@ import * as acp from "@agentclientprotocol/sdk";
 import { makeRunnerFromDefinition } from "../runner";
 import { AgentAcpAdapter } from "./adapter";
 export function makeStdioTransport(agent) {
-    const agentRunner = "definition" in agent ? agent : makeRunnerFromDefinition(agent);
-    const input = Writable.toWeb(process.stdout);
-    const output = Readable.toWeb(process.stdin);
-    const stream = acp.ndJsonStream(input, output);
-    new acp.AgentSideConnection((conn) => new AgentAcpAdapter(agentRunner, conn), stream);
+	const agentRunner =
+		"definition" in agent ? agent : makeRunnerFromDefinition(agent);
+	const input = Writable.toWeb(process.stdout);
+	const output = Readable.toWeb(process.stdin);
+	const stream = acp.ndJsonStream(input, output);
+	new acp.AgentSideConnection(
+		(conn) => new AgentAcpAdapter(agentRunner, conn),
+		stream,
+	);
 }

package/dist/acp-server/http.d.ts

@@ -1,3 +1,5 @@
 import type { AgentDefinition } from "../definition";
 import { type AgentRunner } from "../runner";
-export declare function makeHttpTransport(agent: AgentRunner | AgentDefinition): void;
+export declare function makeHttpTransport(
+	agent: AgentRunner | AgentDefinition,
+): void;

package/dist/definition/tools/todo.d.ts

@@ -0,0 +1,49 @@
+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
+>;

package/dist/definition/tools/todo.js

@@ -0,0 +1,80 @@
+import { tool } from "langchain";
+import { z } from "zod";
+export const todoItemSchema = z.object({
+	content: z.string().min(1),
+	status: z.enum(["pending", "in_progress", "completed"]),
+	activeForm: z.string().min(1),
+});
+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",
+		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.
+
+## When to Use This Tool
+Use this tool proactively in these scenarios:
+
+1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+3. User explicitly requests todo list - When the user directly asks you to use the todo list
+4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
+5. After receiving new instructions - Immediately capture user requirements as todos
+6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time
+7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+
+## When NOT to Use This Tool
+
+Skip using this tool when:
+1. There is only a single, straightforward task
+2. The task is trivial and tracking it provides no organizational benefit
+3. The task can be completed in less than 3 trivial steps
+4. The task is purely conversational or informational
+
+NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
+
+## Task States and Management
+
+1. **Task States**: Use these states to track progress:
+   - pending: Task not yet started
+   - in_progress: Currently working on (limit to ONE task at a time)
+   - completed: Task finished successfully
+
+   **IMPORTANT**: Task descriptions must have two forms:
+   - content: The imperative form describing what needs to be done (e.g., "Run tests", "Build the project")
+   - activeForm: The present continuous form shown during execution (e.g., "Running tests", "Building the project")
+
+2. **Task Management**:
+   - Update task status in real-time as you work
+   - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
+   - Exactly ONE task must be in_progress at any time (not less, not more)
+   - Complete current tasks before starting new ones
+   - Remove tasks that are no longer relevant from the list entirely
+
+3. **Task Completion Requirements**:
+   - ONLY mark a task as completed when you have FULLY accomplished it
+   - If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+   - When blocked, create a new task describing what needs to be resolved
+   - Never mark a task as completed if:
+     - Tests are failing
+     - Implementation is partial
+     - You encountered unresolved errors
+     - You couldn't find necessary files or dependencies
+
+4. **Task Breakdown**:
+   - Create specific, actionable items
+   - Break complex tasks into smaller, manageable steps
+   - Use clear, descriptive task names
+   - Always provide both forms:
+     - content: "Fix authentication bug"
+     - activeForm: "Fixing authentication bug"
+
+When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.`,
+		schema: z.object({
+			todos: z.array(todoItemSchema),
+		}),
+	},
+);

package/dist/definition/tools/web_search.d.ts

@@ -0,0 +1,4 @@
+import { ExaSearchResults } from "@langchain/exa";
+export declare function makeWebSearchTool(): ExaSearchResults<{
+	text: true;
+}>;

package/dist/definition/tools/web_search.js

@@ -0,0 +1,26 @@
+import { ExaSearchResults } from "@langchain/exa";
+import Exa from "exa-js";
+
+let _webSearchInstance = null;
+export function makeWebSearchTool() {
+	if (_webSearchInstance) {
+		return _webSearchInstance;
+	}
+	const apiKey = process.env.EXA_API_KEY;
+	if (!apiKey) {
+		throw new Error(
+			"EXA_API_KEY environment variable is required to use the web_search tool. " +
+				"Please set it to your Exa API key from https://exa.ai",
+		);
+	}
+	const client = new Exa(apiKey);
+	_webSearchInstance = new ExaSearchResults({
+		client,
+		searchArgs: {
+			numResults: 5,
+			type: "auto",
+			text: true,
+		},
+	});
+	return _webSearchInstance;
+}

package/dist/dev-agent/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/dev-agent/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env bun
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { makeHttpTransport, makeStdioTransport } from "../acp-server/index";
+// Load agent definition from JSON file
+const configPath = join(import.meta.dir, "agent.json");
+const agent = JSON.parse(readFileSync(configPath, "utf-8"));
+const transport = process.argv[2] || "stdio";
+if (transport === "http") {
+    makeHttpTransport(agent);
+}
+else if (transport === "stdio") {
+    makeStdioTransport(agent);
+}
+else {
+    console.error(`Invalid transport: ${transport}`);
+    process.exit(1);
+}

package/dist/example.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/example.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+import { makeHttpTransport, makeStdioTransport } from "./acp-server/index.js";
+
+const exampleAgent = {
+	model: "claude-sonnet-4-5-20250929",
+	systemPrompt: "You are a helpful assistant.",
+	tools: ["todo_write", "get_weather", "web_search"],
+};
+// Parse transport type from command line argument
+const transport = process.argv[2] || "stdio";
+if (transport === "http") {
+	makeHttpTransport(exampleAgent);
+} else if (transport === "stdio") {
+	makeStdioTransport(exampleAgent);
+} else {
+	console.error(`Invalid transport: ${transport}`);
+	console.error("Usage: bun run example.ts [stdio|http]");
+	process.exit(1);
+}

package/dist/index.js

@@ -6,7 +6,10 @@ const exampleAgent = {
         "todo_write",
         "get_weather",
         "web_search",
-        { type: "filesystem", working_directory: "/Users/michael/code/town" },
+        {
+            type: "filesystem",
+            //working_directory: "/Users/<user>/town"
+        },
     ],
     mcps: [],
 };

package/dist/runner/agent-runner.d.ts

@@ -32,6 +32,22 @@ export type CreateAgentRunnerParams = z.infer<typeof zAgentRunnerParams>;
 export type InvokeRequest = Omit<PromptRequest, "_meta"> & {
     messageId: string;
 };
+export interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+export interface AgentMessageChunkWithTokens {
+    sessionUpdate: "agent_message_chunk";
+    content: {
+        type: "text";
+        text: string;
+    };
+    _meta?: {
+        tokenUsage?: TokenUsage;
+        [key: string]: unknown;
+    };
+}
 export type ExtendedSessionUpdate = SessionNotification["update"] | {
     sessionUpdate: "tool_output";
     toolCallId: string;
@@ -43,7 +59,7 @@ export type ExtendedSessionUpdate = SessionNotification["update"] | {
     _meta?: {
         messageId?: string;
     };
-};
+} | AgentMessageChunkWithTokens;
 /** Describes an object that can run an agent definition */
 export interface AgentRunner {
     definition: CreateAgentRunnerParams;

package/dist/runner/index.d.ts

@@ -1,4 +1,6 @@
 import type { AgentDefinition } from "../definition";
 import { type AgentRunner } from "./agent-runner";
 export type { AgentRunner };
-export declare const makeRunnerFromDefinition: (definition: AgentDefinition) => AgentRunner;
+export declare const makeRunnerFromDefinition: (
+	definition: AgentDefinition,
+) => AgentRunner;

package/dist/runner/index.js

@@ -1,18 +1,22 @@
 import { zAgentRunnerParams } from "./agent-runner";
 import { LangchainAgent } from "./langchain";
 export const makeRunnerFromDefinition = (definition) => {
-    const agentRunnerParams = zAgentRunnerParams.safeParse(definition);
-    if (!agentRunnerParams.success) {
-        throw new Error(`Invalid agent definition: ${agentRunnerParams.error.message}`);
-    }
-    switch (definition.harnessImplementation) {
-        case undefined:
-        case "langchain": {
-            return new LangchainAgent(agentRunnerParams.data);
-        }
-        default: {
-            const _exhaustiveCheck = definition.harnessImplementation;
-            throw new Error(`Unsupported harness implementation: ${definition.harnessImplementation}`);
-        }
-    }
+	const agentRunnerParams = zAgentRunnerParams.safeParse(definition);
+	if (!agentRunnerParams.success) {
+		throw new Error(
+			`Invalid agent definition: ${agentRunnerParams.error.message}`,
+		);
+	}
+	switch (definition.harnessImplementation) {
+		case undefined:
+		case "langchain": {
+			return new LangchainAgent(agentRunnerParams.data);
+		}
+		default: {
+			const _exhaustiveCheck = definition.harnessImplementation;
+			throw new Error(
+				`Unsupported harness implementation: ${definition.harnessImplementation}`,
+			);
+		}
+	}
 };

package/dist/runner/langchain/index.js

@@ -152,7 +152,6 @@ export class LangchainAgent {
                             totalTokens: msg.usage_metadata.total_tokens,
                         }
                         : undefined;
-                    logger.debug("Token usage:", tokenUsage);
                     for (const toolCall of msg.tool_calls ?? []) {
                         if (toolCall.id == null) {
                             throw new Error(`Tool call is missing id: ${JSON.stringify(toolCall)}`);
@@ -206,25 +205,89 @@ export class LangchainAgent {
             else if (streamMode === "messages") {
                 const aiMessage = chunk[0];
                 if (aiMessage instanceof AIMessageChunk) {
-                    if (typeof aiMessage.content === "string") {
-                        yield {
+                    // Extract token usage metadata if available
+                    const messageTokenUsage = aiMessage.usage_metadata
+                        ? {
+                            inputTokens: aiMessage.usage_metadata.input_tokens,
+                            outputTokens: aiMessage.usage_metadata.output_tokens,
+                            totalTokens: aiMessage.usage_metadata.total_tokens,
+                        }
+                        : undefined;
+                    if (messageTokenUsage) {
+                        const contentType = typeof aiMessage.content;
+                        const contentIsArray = Array.isArray(aiMessage.content);
+                        const contentLength = contentIsArray
+                            ? aiMessage.content.length
+                            : typeof aiMessage.content === "string"
+                                ? aiMessage.content.length
+                                : -1;
+                        console.error("DEBUG agent: messageTokenUsage:", JSON.stringify(messageTokenUsage), "contentType:", contentType, "isArray:", contentIsArray, "length:", contentLength);
+                    }
+                    // If we have tokenUsage but no content, send a token-only chunk
+                    if (messageTokenUsage &&
+                        (typeof aiMessage.content === "string"
+                            ? aiMessage.content === ""
+                            : Array.isArray(aiMessage.content) &&
+                                aiMessage.content.length === 0)) {
+                        console.error("DEBUG agent: sending token-only chunk:", JSON.stringify(messageTokenUsage));
+                        const msgToYield = {
                             sessionUpdate: "agent_message_chunk",
                             content: {
                                 type: "text",
-                                text: aiMessage.content,
+                                text: "", // Empty text, just carrying tokenUsage
+                            },
+                            _meta: {
+                                tokenUsage: messageTokenUsage,
                             },
                         };
+                        yield msgToYield;
+                        continue; // Skip the rest of the processing for this chunk
+                    }
+                    if (typeof aiMessage.content === "string") {
+                        const msgToYield = messageTokenUsage
+                            ? {
+                                sessionUpdate: "agent_message_chunk",
+                                content: {
+                                    type: "text",
+                                    text: aiMessage.content,
+                                },
+                                _meta: {
+                                    tokenUsage: messageTokenUsage,
+                                },
+                            }
+                            : {
+                                sessionUpdate: "agent_message_chunk",
+                                content: {
+                                    type: "text",
+                                    text: aiMessage.content,
+                                },
+                            };
+                        console.error("DEBUG agent: yielding message (string content):", JSON.stringify(msgToYield));
+                        yield msgToYield;
                     }
                     else if (Array.isArray(aiMessage.content)) {
                         for (const part of aiMessage.content) {
                             if (part.type === "text" && typeof part.text === "string") {
-                                yield {
-                                    sessionUpdate: "agent_message_chunk",
-                                    content: {
-                                        type: "text",
-                                        text: part.text,
-                                    },
-                                };
+                                const msgToYield = messageTokenUsage
+                                    ? {
+                                        sessionUpdate: "agent_message_chunk",
+                                        content: {
+                                            type: "text",
+                                            text: part.text,
+                                        },
+                                        _meta: {
+                                            tokenUsage: messageTokenUsage,
+                                        },
+                                    }
+                                    : {
+                                        sessionUpdate: "agent_message_chunk",
+                                        content: {
+                                            type: "text",
+                                            text: part.text,
+                                        },
+                                    };
+                                console.error("DEBUG agent: yielding message (array content):", JSON.stringify(msgToYield));
+                                yield msgToYield;
                             }
                             else if (part.type === "tool_use") {
                                 // We don't care about tool use chunks -- do nothing

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

@@ -1,33 +1,49 @@
 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 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/web_search.d.ts

@@ -1,4 +1,6 @@
 import { ExaSearchResults } from "@langchain/exa";
 export declare function makeWebSearchTool(): ExaSearchResults<{
-    text: true;
+    text: {
+        maxCharacters: number;
+    };
 }>;

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

@@ -16,7 +16,9 @@ export function makeWebSearchTool() {
         searchArgs: {
             numResults: 5,
             type: "auto",
-            text: true,
+            text: {
+                maxCharacters: 7500,
+            },
         },
     });
     return _webSearchInstance;

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

@@ -4,9 +4,37 @@ structure of this repository is:
 - `agents/`: code for main agent loop and configuration
 - `tools/`: code for function-based tools that are shared by agents
 
+## Built-in tools
+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
+
+To use built-in tools, simply add them to the `tools` array in your agent definition:
+```
+const agent: AgentDefinition = {
+  model: "claude-sonnet-4-5-20250929",
+  systemPrompt: "You are a helpful assistant.\n",
+  tools: ["todo_write", "web_search", "filesystem"],
+};
+```
+
+The `filesystem` tool can also be configured with a custom working directory:
+```
+const agent: AgentDefinition = {
+  model: "claude-sonnet-4-5-20250929",
+  systemPrompt: "You are a helpful assistant.\n",
+  tools: [
+    "todo_write",
+    "web_search",
+    { type: "filesystem", working_directory: "./src" }
+  ],
+};
+```
+
 ## Writing custom tools
-You may add one of the built-in tools to the agent SDK (e.g. `web_search`), or
-you may implement your own. To do this:
+You may add one of the built-in tools listed above, or
+you may implement your own custom tools. To do this:
 1. add a file `tools/<tool-name>.ts` with the following structure:
 ```
 import * as z from 'zod';