@townco/agent 0.1.0

package/dist/runner/langchain/index.d.ts

@@ -0,0 +1,15 @@
+import type { PromptResponse, SessionNotification } from "@agentclientprotocol/sdk";
+import { type DynamicStructuredTool, type Tool } from "langchain";
+import type { AgentRunner, CreateAgentRunnerParams, InvokeRequest } from "../agent-runner";
+import type { ToolType } from "../tools";
+type LangchainTool = DynamicStructuredTool | Tool;
+/** Lazily-loaded langchain tools */
+type LazyLangchainTool = MakeLazy<LangchainTool>;
+type MakeLazy<T> = T extends LangchainTool ? () => T : never;
+export declare const TOOL_REGISTRY: Record<ToolType, LangchainTool | LazyLangchainTool>;
+export declare class LangchainAgent implements AgentRunner {
+    definition: CreateAgentRunnerParams;
+    constructor(params: CreateAgentRunnerParams);
+    invoke(req: InvokeRequest): AsyncGenerator<SessionNotification["update"], PromptResponse, undefined>;
+}
+export {};

package/dist/runner/langchain/index.js

@@ -0,0 +1,227 @@
+import { MultiServerMCPClient } from "@langchain/mcp-adapters";
+import { AIMessageChunk, createAgent, ToolMessage, tool, } from "langchain";
+import { z } from "zod";
+import { todoItemSchema, todoWrite } from "./tools/todo";
+import { makeWebSearchTool } from "./tools/web_search";
+const getWeather = tool(({ city }) => `It's always sunny in ${city}!`, {
+    name: "get_weather",
+    description: "Get the weather for a given city",
+    schema: z.object({
+        city: z.string(),
+    }),
+});
+export const TOOL_REGISTRY = {
+    todo_write: todoWrite,
+    get_weather: getWeather,
+    web_search: makeWebSearchTool,
+};
+export class LangchainAgent {
+    definition;
+    constructor(params) {
+        this.definition = params;
+    }
+    async *invoke(req) {
+        // Track todo_write tool call IDs to suppress their tool_call notifications
+        const todoWriteToolCallIds = new Set();
+        const enabledTools = (this.definition.tools ?? []).map((name) => {
+            const tool = TOOL_REGISTRY[name];
+            if (typeof tool === "function") {
+                return tool();
+            }
+            return tool;
+        });
+        if ((this.definition.mcps?.length ?? 0) > 0) {
+            enabledTools.push(...(await makeMcpToolsClient(this.definition.mcps).getTools()));
+        }
+        const agentConfig = {
+            model: this.definition.model,
+            tools: enabledTools,
+        };
+        if (this.definition.systemPrompt) {
+            agentConfig.systemPrompt = this.definition.systemPrompt;
+        }
+        const agent = createAgent(agentConfig);
+        const stream = agent.stream({
+            messages: req.prompt
+                .filter((promptMsg) => promptMsg.type === "text")
+                .map((promptMsg) => ({
+                type: "human",
+                content: promptMsg.text,
+            })),
+        }, {
+            streamMode: ["updates", "messages"],
+        });
+        for await (const [streamMode, chunk] of await stream) {
+            if (streamMode === "updates") {
+                const updatesChunk = modelRequestSchema.safeParse(chunk);
+                if (!updatesChunk.success) {
+                    // Other kinds of updates are either handled in the 'messages'
+                    // streamMode (tool calls), or we don't care about them so far (not
+                    // known yet).
+                    continue;
+                }
+                const updatesMessages = updatesChunk.data.model_request.messages;
+                if (!updatesMessages.every((m) => m instanceof AIMessageChunk)) {
+                    throw new Error(`Unhandled updates message chunk types: ${JSON.stringify(updatesMessages)}`);
+                }
+                for (const msg of updatesMessages) {
+                    for (const toolCall of msg.tool_calls ?? []) {
+                        if (toolCall.id == null) {
+                            throw new Error(`Tool call is missing id: ${JSON.stringify(toolCall)}`);
+                        }
+                        // If this is a todo_write tool call, yield an agent-plan update
+                        if (toolCall.name === "todo_write" && toolCall.args?.todos) {
+                            const entries = toolCall.args.todos.flatMap((todo) => {
+                                const validation = todoItemSchema.safeParse(todo);
+                                if (!validation.success) {
+                                    // Invalid todo - filter it out
+                                    return [];
+                                }
+                                return [
+                                    {
+                                        content: validation.data.content,
+                                        status: validation.data.status,
+                                        priority: "medium",
+                                    },
+                                ];
+                            });
+                            yield {
+                                sessionUpdate: "plan",
+                                entries: entries,
+                            };
+                            // Track this tool call ID to suppress tool_call notifications
+                            todoWriteToolCallIds.add(toolCall.id);
+                            continue;
+                        }
+                        yield {
+                            sessionUpdate: "tool_call",
+                            toolCallId: toolCall.id,
+                            title: toolCall.name,
+                            kind: "other",
+                            status: "pending",
+                            rawInput: toolCall.args,
+                        };
+                        yield {
+                            sessionUpdate: "tool_call_update",
+                            toolCallId: toolCall.id,
+                            status: "in_progress",
+                        };
+                    }
+                }
+            }
+            else if (streamMode === "messages") {
+                const aiMessage = chunk[0];
+                if (aiMessage instanceof AIMessageChunk) {
+                    if (typeof aiMessage.content === "string") {
+                        yield {
+                            sessionUpdate: "agent_message_chunk",
+                            content: {
+                                type: "text",
+                                text: aiMessage.content,
+                            },
+                        };
+                    }
+                    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,
+                                    },
+                                };
+                            }
+                            else if (part.type === "tool_use") {
+                                // We don't care about tool use chunks -- do nothing
+                            }
+                            else if (part.type === "input_json_delta") {
+                                // We don't care about tool use input delta chunks -- do nothing
+                            }
+                            else {
+                                throw new Error(`Unhandled AIMessageChunk content block type: ${part.type}\n${JSON.stringify(part)}`);
+                            }
+                        }
+                    }
+                    else {
+                        throw new Error(`Unhandled AIMessageChunk content type: ${typeof aiMessage.content}`);
+                    }
+                }
+                else if (aiMessage instanceof ToolMessage) {
+                    if (typeof aiMessage.content === "string") {
+                        if (todoWriteToolCallIds.has(aiMessage.tool_call_id)) {
+                            // Skip tool_call_update for todo_write tools
+                            continue;
+                        }
+                        yield {
+                            sessionUpdate: "tool_call_update",
+                            toolCallId: aiMessage.tool_call_id,
+                            status: "completed",
+                            content: [
+                                {
+                                    type: "content",
+                                    content: {
+                                        type: "text",
+                                        text: aiMessage.content,
+                                    },
+                                },
+                            ],
+                            rawOutput: { content: aiMessage.content },
+                        };
+                    }
+                    else {
+                        throw new Error(`Unhandled ToolMessage content type: ${typeof aiMessage.content}`);
+                    }
+                }
+                else {
+                    throw new Error(`Unhandled message chunk type: ${JSON.stringify(aiMessage)}`);
+                }
+            }
+            else {
+                throw new Error(`Unhandled stream mode: ${streamMode}`);
+            }
+        }
+        return {
+            stopReason: "end_turn",
+        };
+    }
+}
+const modelRequestSchema = z.object({
+    model_request: z.object({
+        messages: z.array(z.any()),
+    }),
+});
+const makeMcpToolsClient = (mcpConfigs) => {
+    const mcpServers = mcpConfigs?.map((config) => {
+        if (config.transport === "http") {
+            return [
+                config.name,
+                {
+                    url: config.url,
+                },
+            ];
+        }
+        return [
+            config.name,
+            {
+                transport: "stdio",
+                command: config.command,
+                args: config.args,
+            },
+        ];
+    });
+    const client = new MultiServerMCPClient({
+        // Global tool configuration options
+        // Whether to throw on errors if a tool fails to load (optional, default: true)
+        throwOnLoadError: true,
+        // Whether to prefix tool names with the server name (optional, default: false)
+        prefixToolNameWithServerName: false,
+        // Optional additional prefix for tool names (optional, default: "")
+        additionalToolNamePrefix: "",
+        // Use standardized content block format in tool outputs
+        useStandardContentBlocks: true,
+        // Server configuration
+        mcpServers: Object.fromEntries(mcpServers ?? []),
+    });
+    return client;
+};

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

@@ -0,0 +1,33 @@
+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/runner/langchain/tools/todo.js

@@ -0,0 +1,77 @@
+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/runner/langchain/tools/web_search.d.ts

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

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

@@ -0,0 +1,23 @@
+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/runner/tools.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+export declare const zToolType: z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">]>;
+export type ToolType = z.infer<typeof zToolType>;

package/dist/runner/tools.js

@@ -0,0 +1,6 @@
+import { z } from "zod";
+export const zToolType = z.union([
+    z.literal("todo_write"),
+    z.literal("get_weather"),
+    z.literal("web_search"),
+]);

package/dist/scaffold/bundle.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Copy necessary files from @townco/agent to the agent directory
+ */
+export declare function bundleAgentDependencies(agentPath: string): Promise<void>;

package/dist/scaffold/bundle.js

@@ -0,0 +1,28 @@
+import { cp, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Get the source packages/agent directory
+ */
+function getAgentPackageDir() {
+    const currentFile = fileURLToPath(import.meta.url);
+    // scaffold/bundle.ts -> scaffold -> packages/agent
+    return join(dirname(currentFile), "..");
+}
+/**
+ * Copy necessary files from @townco/agent to the agent directory
+ */
+export async function bundleAgentDependencies(agentPath) {
+    const sourceDir = getAgentPackageDir();
+    // Create lib directory in the agent
+    const libDir = join(agentPath, "lib");
+    await mkdir(libDir, { recursive: true });
+    // Directories to copy
+    const dirsToCopy = ["acp-server", "definition", "runner"];
+    for (const dir of dirsToCopy) {
+        const sourceSubDir = join(sourceDir, dir);
+        const targetSubDir = join(libDir, dir);
+        // Copy the directory recursively
+        await cp(sourceSubDir, targetSubDir, { recursive: true });
+    }
+}

package/dist/scaffold/copy-gui.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Copy GUI app to the agent directory
+ */
+export declare function copyGuiApp(agentPath: string): Promise<void>;

package/dist/scaffold/copy-gui.js

@@ -0,0 +1,210 @@
+import { cp, mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Get the source apps/gui directory
+ */
+function getGuiSourceDir() {
+    const currentFile = fileURLToPath(import.meta.url);
+    // When running from compiled dist:
+    // dist/scaffold/copy-gui.js -> dist/scaffold -> dist -> packages/agent -> packages -> root -> apps/gui
+    return join(dirname(currentFile), "..", "..", "..", "..", "apps", "gui");
+}
+/**
+ * Get the source packages/ui directory
+ */
+function getUiSourceDir() {
+    const currentFile = fileURLToPath(import.meta.url);
+    // When running from compiled dist:
+    // dist/scaffold/copy-gui.js -> dist/scaffold -> dist -> packages/agent -> packages -> ui
+    return join(dirname(currentFile), "..", "..", "..", "ui");
+}
+/**
+ * Copy GUI app to the agent directory
+ */
+export async function copyGuiApp(agentPath) {
+    const sourceDir = getGuiSourceDir();
+    const guiDir = join(agentPath, "gui");
+    // Create gui directory
+    await mkdir(guiDir, { recursive: true });
+    // Copy everything except node_modules and dist (exclude tsconfig.json as we'll generate it)
+    const itemsToCopy = ["src", "index.html", "postcss.config.js"];
+    for (const item of itemsToCopy) {
+        const sourcePath = join(sourceDir, item);
+        const targetPath = join(guiDir, item);
+        try {
+            await cp(sourcePath, targetPath, { recursive: true });
+        }
+        catch (error) {
+            // Item might not exist, that's okay
+            console.warn(`Warning: Could not copy ${item}:`, error);
+        }
+    }
+    // Create a standalone tsconfig.json for the GUI (can't extend from workspace tsconfig)
+    const guiTsConfig = {
+        compilerOptions: {
+            allowArbitraryExtensions: true,
+            allowUnreachableCode: false,
+            allowUnusedLabels: false,
+            declaration: true,
+            emitDecoratorMetadata: true,
+            esModuleInterop: true,
+            exactOptionalPropertyTypes: true,
+            experimentalDecorators: true,
+            jsx: "react-jsx",
+            lib: ["DOM", "ESNext"],
+            module: "ESNext",
+            moduleResolution: "bundler",
+            noFallthroughCasesInSwitch: true,
+            noImplicitAny: true,
+            noImplicitOverride: true,
+            noImplicitReturns: true,
+            noUncheckedIndexedAccess: true,
+            noUncheckedSideEffectImports: true,
+            noUnusedLocals: false,
+            noUnusedParameters: true,
+            resolveJsonModule: true,
+            skipLibCheck: true,
+            strict: true,
+            stripInternal: true,
+            target: "ESNext",
+            verbatimModuleSyntax: true,
+            outDir: "./dist",
+            rootDir: "./src",
+        },
+        include: ["src/**/*"],
+        exclude: ["node_modules", "dist"],
+    };
+    await writeFile(join(guiDir, "tsconfig.json"), JSON.stringify(guiTsConfig, null, 2));
+    // Create a custom vite.config.ts with path aliases
+    const viteConfig = `import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { resolve } from "path";
+
+export default defineConfig({
+	plugins: [react()],
+	resolve: {
+		alias: {
+			"@townco/ui": resolve(__dirname, "./ui/src"),
+			// Exclude Node.js-only modules from browser bundle
+			"node:child_process": resolve(__dirname, "./polyfills/child_process.js"),
+			"node:stream": resolve(__dirname, "./polyfills/stream.js"),
+		},
+	},
+	optimizeDeps: {
+		exclude: ["node:child_process", "node:stream"],
+	},
+});
+`;
+    await writeFile(join(guiDir, "vite.config.ts"), viteConfig);
+    // Create polyfills directory with stub modules for Node.js-only imports
+    const polyfillsDir = join(guiDir, "polyfills");
+    await mkdir(polyfillsDir, { recursive: true });
+    // Provide stub exports for child_process module
+    const childProcessPolyfill = `// Polyfill for node:child_process (browser-incompatible)
+export const spawn = () => {
+	throw new Error('child_process.spawn is not available in the browser');
+};
+export class ChildProcess {}
+export default { spawn, ChildProcess };
+`;
+    await writeFile(join(polyfillsDir, "child_process.js"), childProcessPolyfill);
+    // Provide stub exports for stream module
+    const streamPolyfill = `// Polyfill for node:stream (browser-incompatible)
+export class Readable {
+	constructor() {
+		throw new Error('stream.Readable is not available in the browser');
+	}
+}
+export class Writable {
+	constructor() {
+		throw new Error('stream.Writable is not available in the browser');
+	}
+}
+export class Duplex {
+	constructor() {
+		throw new Error('stream.Duplex is not available in the browser');
+	}
+}
+export class Transform {
+	constructor() {
+		throw new Error('stream.Transform is not available in the browser');
+	}
+}
+export default { Readable, Writable, Duplex, Transform };
+`;
+    await writeFile(join(polyfillsDir, "stream.js"), streamPolyfill);
+    // Generate a custom package.json for the GUI
+    const packageJson = {
+        name: "agent-gui",
+        version: "0.0.1",
+        type: "module",
+        private: true,
+        scripts: {
+            dev: "vite",
+            build: "vite build",
+            preview: "vite preview",
+        },
+        dependencies: {
+            "@agentclientprotocol/sdk": "^0.5.1",
+            "@radix-ui/react-dialog": "^1.1.15",
+            "@radix-ui/react-label": "^2.1.8",
+            "@radix-ui/react-select": "^2.2.6",
+            "@radix-ui/react-slot": "^1.2.4",
+            "@radix-ui/react-tabs": "^1.1.13",
+            "class-variance-authority": "^0.7.1",
+            clsx: "^2.1.1",
+            "lucide-react": "^0.552.0",
+            react: "^19.2.0",
+            "react-dom": "^19.2.0",
+            "react-markdown": "^10.1.0",
+            "remark-gfm": "^4.0.1",
+            "tailwind-merge": "^3.3.1",
+            zod: "^4.1.12",
+            zustand: "^5.0.8",
+        },
+        devDependencies: {
+            "@tailwindcss/postcss": "^4.1.17",
+            "@types/react": "^19.2.2",
+            "@types/react-dom": "^19.2.2",
+            "@vitejs/plugin-react": "^5.1.0",
+            autoprefixer: "^10.4.21",
+            postcss: "^8.5.6",
+            tailwindcss: "^4.1.17",
+            typescript: "^5.9.3",
+            vite: "^7.2.1",
+        },
+    };
+    await writeFile(join(guiDir, "package.json"), JSON.stringify(packageJson, null, 2));
+    // Copy UI package components and styles
+    const uiSourceDir = getUiSourceDir();
+    const uiTargetDir = join(guiDir, "ui");
+    await mkdir(uiTargetDir, { recursive: true });
+    // Copy the entire UI src directory (which includes styles)
+    const sourcePath = join(uiSourceDir, "src");
+    const targetPath = join(uiTargetDir, "src");
+    try {
+        await cp(sourcePath, targetPath, { recursive: true });
+    }
+    catch (error) {
+        console.warn(`Warning: Could not copy UI src:`, error);
+    }
+    // Create a tsconfig for the ui directory
+    const uiTsConfig = {
+        compilerOptions: {
+            target: "ESNext",
+            module: "ESNext",
+            jsx: "react-jsx",
+            moduleResolution: "bundler",
+            lib: ["ESNext", "DOM", "DOM.Iterable"],
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            forceConsistentCasingInFileNames: true,
+            resolveJsonModule: true,
+            allowSyntheticDefaultImports: true,
+        },
+        include: ["**/*.ts", "**/*.tsx"],
+    };
+    await writeFile(join(uiTargetDir, "tsconfig.json"), JSON.stringify(uiTsConfig, null, 2));
+}

package/dist/scaffold/index.d.ts

@@ -0,0 +1,16 @@
+import type { AgentDefinition } from "../definition";
+export interface ScaffoldOptions {
+    name: string;
+    definition: AgentDefinition;
+    overwrite?: boolean;
+    includeGui?: boolean;
+}
+export interface ScaffoldResult {
+    success: boolean;
+    path: string;
+    error?: string;
+}
+/**
+ * Scaffold a new agent package
+ */
+export declare function scaffoldAgent(options: ScaffoldOptions): Promise<ScaffoldResult>;