@townco/agent 0.1.22 → 0.1.24

package/dist/scaffold/copy-tui.js

@@ -1,4 +1,4 @@
-import { cp, mkdir, writeFile } from "node:fs/promises";
+import { cp, mkdir } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 const require = createRequire(import.meta.url);
@@ -29,68 +29,4 @@ export async function copyTuiApp(agentPath) {
         const targetPath = join(tuiDir, item);
         await cp(sourcePath, targetPath, { recursive: true });
     }
-    // Create a standalone tsconfig.json for the TUI
-    const tuiTsConfig = {
-        compilerOptions: {
-            allowArbitraryExtensions: true,
-            allowUnreachableCode: false,
-            allowUnusedLabels: false,
-            declaration: true,
-            emitDecoratorMetadata: true,
-            esModuleInterop: true,
-            exactOptionalPropertyTypes: true,
-            experimentalDecorators: true,
-            jsx: "react-jsx",
-            lib: ["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(tuiDir, "tsconfig.json"), JSON.stringify(tuiTsConfig, null, 2));
-    // Generate a custom package.json for the TUI
-    const packageJson = {
-        name: "agent-tui",
-        version: "0.0.1",
-        type: "module",
-        private: true,
-        bin: {
-            "agent-tui": "./dist/index.js",
-        },
-        scripts: {
-            build: "tsc",
-            start: "bun dist/index.js",
-        },
-        dependencies: {
-            "@townco/ui": "^0.1.0",
-            "@optique/core": "^0.6.2",
-            "@optique/run": "^0.6.2",
-            ink: "^6.4.0",
-            "ink-text-input": "^6.0.0",
-            react: "^19.2.0",
-        },
-        devDependencies: {
-            "@types/node": "^24.10.0",
-            "@types/react": "^19.2.2",
-            typescript: "^5.9.3",
-        },
-    };
-    await writeFile(join(tuiDir, "package.json"), JSON.stringify(packageJson, null, 2));
 }

package/dist/scaffold/index.d.ts

@@ -5,6 +5,7 @@ export interface ScaffoldOptions {
     overwrite?: boolean;
     includeGui?: boolean;
     includeTui?: boolean;
+    agentsDir: string;
 }
 export interface ScaffoldResult {
     success: boolean;
@@ -15,3 +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

@@ -1,52 +1,47 @@
 import { spawn } from "node:child_process";
-import { chmod, mkdir, writeFile } from "node:fs/promises";
+import { mkdir, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { agentExists, ensureAgentsDir, getAgentPath } from "../storage";
-import { generateAgentJson, generateBinTs, generateEnvExample, generateGitignore, generateIndexTs, generatePackageJson, generateReadme, generateTsConfig, getTemplateVars, } from "../templates";
+import { generateBinTs, generateIndexTs, getTemplateVars } from "../templates";
 import { copyGuiApp } from "./copy-gui";
 import { copyTuiApp } from "./copy-tui";
 /**
  * Scaffold a new agent package
  */
 export async function scaffoldAgent(options) {
-    const { name, definition, overwrite = false, includeGui = true, includeTui = true, } = options;
+    const { name, definition, overwrite = false, includeGui = true, includeTui = true, agentsDir, } = options;
     try {
-        // Ensure base directory exists
-        await ensureAgentsDir();
+        // Ensure the agents directory exists
+        await mkdir(agentsDir, { recursive: true });
         // Check if agent already exists
-        const exists = await agentExists(name);
-        if (exists && !overwrite) {
-            return {
-                success: false,
-                path: getAgentPath(name),
-                error: `Agent "${name}" already exists. Use overwrite option to replace it.`,
-            };
+        const agentPath = join(agentsDir, name);
+        try {
+            const agentStat = await stat(agentPath);
+            if (agentStat.isDirectory() && !overwrite) {
+                return {
+                    success: false,
+                    path: agentPath,
+                    error: `Agent "${name}" already exists. Use overwrite option to replace it.`,
+                };
+            }
+        }
+        catch {
+            // Agent doesn't exist, which is fine
         }
-        const agentPath = getAgentPath(name);
         // Create the agent directory
         await mkdir(agentPath, { recursive: true });
         const vars = getTemplateVars(name, definition);
-        // Generate all template files
+        // Generate template files - just the essentials
         const files = [
-            { path: "package.json", content: generatePackageJson(vars) },
-            { path: "agent.json", content: generateAgentJson(vars) },
-            { path: "index.ts", content: generateIndexTs() },
+            { path: "index.ts", content: await generateIndexTs(vars) },
             { path: "bin.ts", content: generateBinTs(), executable: true },
-            { path: "tsconfig.json", content: generateTsConfig() },
-            { path: "README.md", content: generateReadme(vars) },
-            { path: ".gitignore", content: generateGitignore() },
         ];
-        // 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);
             await writeFile(filePath, file.content, "utf-8");
-            // Make executable if needed
-            if (file.executable) {
+            // Make executable if specified
+            if ("executable" in file && file.executable) {
+                const { chmod } = await import("node:fs/promises");
                 await chmod(filePath, 0o755);
             }
         }
@@ -64,8 +59,6 @@ export async function scaffoldAgent(options) {
             const tuiPath = join(agentPath, "tui");
             await runBunInstall(tuiPath);
         }
-        // Run bun install in agent root to fetch dependencies from npm
-        await runBunInstall(agentPath);
         return {
             success: true,
             path: agentPath,
@@ -74,7 +67,7 @@ export async function scaffoldAgent(options) {
     catch (error) {
         return {
             success: false,
-            path: getAgentPath(name),
+            path: join(agentsDir, name),
             error: error instanceof Error ? error.message : String(error),
         };
     }
@@ -101,3 +94,6 @@ function runBunInstall(agentPath) {
         });
     });
 }
+export { initForClaudeCode } from "./claude-scaffold";
+// Export project scaffolding
+export { scaffoldProject } from "./project-scaffold";

package/dist/scaffold/project-scaffold.d.ts

@@ -0,0 +1,12 @@
+export interface ScaffoldProjectOptions {
+    path: string;
+}
+export interface ScaffoldProjectResult {
+    success: boolean;
+    path: string;
+    error?: string;
+}
+/**
+ * Scaffold a new standalone project
+ */
+export declare function scaffoldProject(options: ScaffoldProjectOptions): Promise<ScaffoldProjectResult>;

package/dist/scaffold/project-scaffold.js

@@ -0,0 +1,317 @@
+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
+ */
+function generateProjectPackageJson() {
+    const pkg = {
+        name: "town-agents-project",
+        version: "0.1.0",
+        type: "module",
+        private: true,
+        scripts: {},
+        dependencies: {
+            "@agentclientprotocol/sdk": "^0.5.1",
+            "@optique/core": "^0.6.2",
+            "@optique/run": "^0.6.2",
+            "@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",
+            "@townco/ui": "^0.1.0",
+            "@townco/agent": "^0.1.20",
+            "class-variance-authority": "^0.7.1",
+            clsx: "^2.1.1",
+            "ink-text-input": "^6.0.0",
+            ink: "^6.4.0",
+            "lucide-react": "^0.552.0",
+            "react-dom": "^19.2.0",
+            "react-markdown": "^10.1.0",
+            react: "^19.2.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",
+        },
+    };
+    return JSON.stringify(pkg, null, 2);
+}
+/**
+ * Generate add-two-numbers tool
+ */
+function generateAddTwoNumbersTool() {
+    return `// biome-ignore lint/suspicious/noExplicitAny: .
+export const schema = (z: any) =>
+  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 };
+}
+`;
+}
+/**
+ * Generate project tsconfig.json
+ */
+function generateProjectTsConfig() {
+    const config = {
+        compilerOptions: {
+            target: "ESNext",
+            module: "ESNext",
+            moduleResolution: "bundler",
+            lib: ["ESNext"],
+            outDir: "./dist",
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            forceConsistentCasingInFileNames: true,
+            resolveJsonModule: true,
+            allowSyntheticDefaultImports: true,
+        },
+        include: ["agents/**/*.ts", "tools/**/*.ts"],
+        exclude: ["node_modules", "dist"],
+    };
+    return JSON.stringify(config, null, 2);
+}
+/**
+ * Generate project README.md
+ */
+function generateProjectReadme() {
+    return `# Town Agents Project
+
+A standalone project for developing Town agents with custom tools.
+
+## Project Structure
+
+\`\`\`
+.
+├── agents/          # Agent implementations (created with 'town create')
+├── tools/           # Custom tools
+│   └── add-two-numbers.ts  # Example tool
+├── package.json     # Project dependencies
+└── tsconfig.json    # TypeScript configuration
+\`\`\`
+
+## Getting Started
+
+1. Install dependencies (if not already done):
+
+\`\`\`bash
+bun install
+\`\`\`
+
+2. Create your first agent:
+
+\`\`\`bash
+town create
+\`\`\`
+
+This will launch an interactive wizard to create a new agent in the \`agents/\` directory.
+The agent will include GUI and TUI interfaces for interaction.
+
+## Creating Agents
+
+Run \`town create\` inside your project directory to create new agents.
+Each agent will be placed in \`agents/<agent-name>/\` with the following structure:
+
+\`\`\`
+agents/my-agent/
+├── agent.json       # Agent configuration
+├── index.ts         # Agent entry point
+├── gui/             # Web-based GUI interface
+└── tui/             # Terminal UI interface
+\`\`\`
+
+## Running Agents
+
+Each agent can be run in different modes:
+
+\`\`\`bash
+# CLI mode (stdio)
+bun agents/<agent-name>/index.ts stdio
+
+# HTTP server mode
+PORT=3100 bun agents/<agent-name>/index.ts http
+\`\`\`
+
+## Creating Custom Tools
+
+Tools are defined in the \`tools/\` directory. Each tool exports:
+
+- \`schema\`: A Zod schema factory function
+- \`name\`: The tool name
+- \`description\`: Tool description
+- \`default\`: The tool implementation function
+
+Example:
+
+\`\`\`typescript
+export const schema = (z: any) =>
+  z.object({
+    input: z.string(),
+  });
+
+export const name = "my_tool";
+export const description = "My custom tool";
+
+export default function myTool(input: unknown) {
+  // Implementation
+  return { result: "success" };
+}
+\`\`\`
+
+To use a tool in an agent, import it in the agent's \`index.ts\`:
+
+\`\`\`typescript
+import myTool, { name, description, schema } from "../../tools/my-tool.js";
+
+const agent: AgentDefinition = {
+  // ...
+  tools: [
+    {
+      type: "direct",
+      name,
+      description,
+      fn: myTool,
+      schema: schema(z),
+    },
+  ],
+};
+\`\`\`
+`;
+}
+/**
+ * Generate .gitignore
+ */
+function generateProjectGitignore() {
+    return `node_modules
+dist
+.env
+*.log
+`;
+}
+/**
+ * Run bun install
+ */
+function runBunInstall(projectPath) {
+    return new Promise((resolve, reject) => {
+        const bunInstall = spawn("bun", ["install"], {
+            cwd: projectPath,
+            stdio: "pipe",
+        });
+        let stdout = "";
+        let stderr = "";
+        // Capture stdout
+        bunInstall.stdout?.on("data", (data) => {
+            stdout += data.toString();
+        });
+        // Capture stderr
+        bunInstall.stderr?.on("data", (data) => {
+            stderr += data.toString();
+        });
+        bunInstall.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                // Print captured output on failure
+                if (stdout) {
+                    process.stdout.write(stdout);
+                }
+                if (stderr) {
+                    process.stderr.write(stderr);
+                }
+                reject(new Error(`bun install failed with code ${code}`));
+            }
+        });
+        bunInstall.on("error", (error) => {
+            // Print captured output on error
+            if (stdout) {
+                process.stdout.write(stdout);
+            }
+            if (stderr) {
+                process.stderr.write(stderr);
+            }
+            reject(error);
+        });
+    });
+}
+/**
+ * Scaffold a new standalone project
+ */
+export async function scaffoldProject(options) {
+    const { path: projectPath } = options;
+    try {
+        // Create project root directory
+        await mkdir(projectPath, { recursive: true });
+        // Create agents directory (empty, to be populated by 'town create')
+        const agentsDir = join(projectPath, "agents");
+        await mkdir(agentsDir, { recursive: true });
+        // Create tools directory
+        const toolsDir = join(projectPath, "tools");
+        await mkdir(toolsDir, { recursive: true });
+        // Generate and write files
+        const files = [
+            {
+                path: "package.json",
+                content: generateProjectPackageJson(),
+            },
+            {
+                path: "tsconfig.json",
+                content: generateProjectTsConfig(),
+            },
+            {
+                path: ".gitignore",
+                content: generateProjectGitignore(),
+            },
+            {
+                path: "README.md",
+                content: generateProjectReadme(),
+            },
+            {
+                path: join("tools", "add-two-numbers.ts"),
+                content: generateAddTwoNumbersTool(),
+            },
+        ];
+        // Write all files
+        for (const file of files) {
+            const filePath = join(projectPath, file.path);
+            await writeFile(filePath, file.content, "utf-8");
+        }
+        // Run bun install
+        await runBunInstall(projectPath);
+        // Initialize Claude Code workspace integration
+        await initForClaudeCode(projectPath);
+        return {
+            success: true,
+            path: projectPath,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            path: projectPath,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

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

@@ -0,0 +1,71 @@
+# 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
+
+## 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:
+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'],
+    },
+  ],
+};
+```

package/dist/storage/index.d.ts

@@ -22,3 +22,8 @@ export declare function deleteAgent(name: string): Promise<void>;
  * Ensure the agents directory exists
  */
 export declare function ensureAgentsDir(): Promise<void>;
+/**
+ * Check if we're inside a Town project by looking for project markers
+ * Returns the project root path if found, null otherwise
+ */
+export declare function isInsideTownProject(startPath?: string): Promise<string | null>;