@townco/agent 0.1.23 → 0.1.25

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/claude-scaffold.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Initialize Claude Code workspace integration by creating AGENTS.town.md
+ * and adding references to it in CLAUDE.md and AGENTS.md.
+ *
+ * @param targetPath - The root directory of the Town project
+ * @throws Error if target path doesn't exist
+ */
+export declare function initForClaudeCode(targetPath: string): Promise<void>;

package/dist/scaffold/claude-scaffold.js

@@ -0,0 +1,58 @@
+import { existsSync } from "node:fs";
+import { appendFile, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Initialize Claude Code workspace integration by creating AGENTS.town.md
+ * and adding references to it in CLAUDE.md and AGENTS.md.
+ *
+ * @param targetPath - The root directory of the Town project
+ * @throws Error if target path doesn't exist
+ */
+export async function initForClaudeCode(targetPath) {
+    // Verify target path exists
+    if (!existsSync(targetPath)) {
+        throw new Error(`Target path does not exist: ${targetPath}`);
+    }
+    // Source template directory (dot-claude in the scaffold package)
+    const templateDir = join(__dirname, "templates", "dot-claude");
+    const appendTemplatePath = join(templateDir, "CLAUDE-append.md");
+    if (!existsSync(appendTemplatePath)) {
+        throw new Error(`Claude template not found: ${appendTemplatePath}. This is a bug in the Town CLI.`);
+    }
+    // Handle AGENTS.town.md and references
+    const claudeMdPath = join(targetPath, "CLAUDE.md");
+    const agentsMdPath = join(targetPath, "AGENTS.md");
+    const agentsTownMdPath = join(targetPath, "AGENTS.town.md");
+    const townContent = await readFile(appendTemplatePath, "utf-8");
+    // Create AGENTS.town.md with the Town-specific content
+    await writeFile(agentsTownMdPath, townContent, "utf-8");
+    console.log("✓ Created AGENTS.town.md");
+    // Add reference to AGENTS.town.md in both CLAUDE.md and AGENTS.md
+    const referenceText = "\n\nThis repo uses the Town agent SDK -- please reference @AGENTS.town.md for more information\n";
+    // Handle CLAUDE.md
+    if (existsSync(claudeMdPath)) {
+        // CLAUDE.md exists, append reference
+        await appendFile(claudeMdPath, referenceText);
+        console.log("✓ Added Town SDK reference to CLAUDE.md");
+    }
+    else {
+        // CLAUDE.md doesn't exist, create it with just the reference
+        await writeFile(claudeMdPath, `${referenceText.trim()}\n`, "utf-8");
+        console.log("✓ Created CLAUDE.md with Town SDK reference");
+    }
+    // Handle AGENTS.md
+    if (existsSync(agentsMdPath)) {
+        // AGENTS.md exists, append reference
+        await appendFile(agentsMdPath, referenceText);
+        console.log("✓ Added Town SDK reference to AGENTS.md");
+    }
+    else {
+        // AGENTS.md doesn't exist, create it with just the reference
+        await writeFile(agentsMdPath, `${referenceText.trim()}\n`, "utf-8");
+        console.log("✓ Created AGENTS.md with Town SDK reference");
+    }
+    console.log("✓ Claude Code workspace initialized");
+}

package/dist/scaffold/index.d.ts

@@ -16,4 +16,5 @@ export interface ScaffoldResult {
  * Scaffold a new agent package
  */
 export declare function scaffoldAgent(options: ScaffoldOptions): Promise<ScaffoldResult>;
+export { initForClaudeCode } from "./claude-scaffold";
 export { scaffoldProject } from "./project-scaffold";

package/dist/scaffold/index.js

@@ -94,5 +94,6 @@ function runBunInstall(agentPath) {
         });
     });
 }
+export { initForClaudeCode } from "./claude-scaffold";
 // Export project scaffolding
 export { scaffoldProject } from "./project-scaffold";

package/dist/scaffold/project-scaffold.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { initForClaudeCode } from "./claude-scaffold.js";
 /**
  * Generate project package.json
  */
@@ -299,6 +300,8 @@ export async function scaffoldProject(options) {
         }
         // Run bun install
         await runBunInstall(projectPath);
+        // Initialize Claude Code workspace integration
+        await initForClaudeCode(projectPath);
         return {
             success: true,
             path: projectPath,

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

@@ -0,0 +1,99 @@
+# Town Agent SDK
+This project has code for agents developed using the Town agent SDK. The
+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 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';
+
+export const schema = z.object({
+  a: z.number().describe("First number"),
+  b: z.number().describe("Second number"),
+});
+
+export const name = "add_two_numbers";
+export const description = "Add two numbers together and return the result";
+
+export default function addTwoNumbers(input: unknown) {
+  const { a, b } = input as { a: number; b: number };
+  return { result: a + b };
+}
+```
+where
+- `schema` is a zod schema for the tool input
+- `name` is the name of the tool (given to the LLM)
+- `description` describes the tool (given to the LLM)
+- default-exported function containing the body of the function
+
+2. Modify the agent code to import the `createTool` utility and the new tool
+```
+import { createTool } from '@townco/agent/utils';
+import * as newCoolTool from '../../tools/new-cool-tool';
+```
+and modify the agent's tools list
+```
+const agent: AgentDefinition = {
+  model: "claude-sonnet-4-5-20250929",
+  systemPrompt: "You are a helpful assistant.\n",
+  tools: ["todo_write", "web_search", createTool(newCoolTool)],
+};
+```
+
+## Configuring MCPs
+You may configure stdio and streamable HTTP-based MCPs. Here is an example:
+```
+const agent: AgentDefinition = {
+  model: "claude-sonnet-4-5-20250929",
+  systemPrompt: "You are a helpful assistant.\n",
+  tools: ["todo_write", "web_search"],
+  mcps: [
+    {
+      transport: "http",
+      name: "foobar",
+      url: "http://town.com:8080/mcp",
+      headers: {
+        'Authorization': `Bearer ${process.env.MCP_API_KEY}`
+      },
+    },
+    {
+      transport: 'stdio',
+      name: 'local-mcp',
+      command: 'node',
+      args: ['path/to/local/mcp.js'],
+    },
+  ],
+};
+```