@townco/agent 0.1.55 → 0.1.57

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

@@ -0,0 +1,412 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import Kernel from "@onkernel/sdk";
+import { tool } from "langchain";
+import { z } from "zod";
+let _kernelClient = null;
+let _sessionId = null;
+let _liveViewUrl = null;
+function getKernelClient() {
+    if (_kernelClient) {
+        return _kernelClient;
+    }
+    const apiKey = process.env.KERNEL_API_KEY;
+    if (!apiKey) {
+        throw new Error("KERNEL_API_KEY environment variable is required to use the browser tool. " +
+            "Please set it to your Kernel API key from https://onkernel.com");
+    }
+    _kernelClient = new Kernel({ apiKey });
+    return _kernelClient;
+}
+async function ensureBrowserSession() {
+    if (_sessionId && _liveViewUrl) {
+        return { sessionId: _sessionId, liveViewUrl: _liveViewUrl };
+    }
+    const kernel = getKernelClient();
+    let kernelBrowser;
+    try {
+        kernelBrowser = await kernel.browsers.create();
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to create Kernel browser. Check KERNEL_API_KEY is valid. Error: ${msg}`);
+    }
+    _sessionId = kernelBrowser.session_id;
+    // biome-ignore lint/suspicious/noExplicitAny: browser_live_view_url not yet typed in @onkernel/sdk
+    _liveViewUrl = kernelBrowser.browser_live_view_url;
+    if (!_sessionId) {
+        throw new Error("Kernel browser created but no session_id returned.");
+    }
+    if (!_liveViewUrl) {
+        throw new Error("Kernel browser created but no browser_live_view_url returned.");
+    }
+    return { sessionId: _sessionId, liveViewUrl: _liveViewUrl };
+}
+// biome-ignore lint/suspicious/noExplicitAny: Kernel SDK playwright.execute not yet typed
+async function executePlaywright(code) {
+    const kernel = getKernelClient();
+    const { sessionId } = await ensureBrowserSession();
+    // biome-ignore lint/suspicious/noExplicitAny: playwright.execute not yet typed in @onkernel/sdk
+    const response = await kernel.browsers.playwright.execute(sessionId, {
+        code,
+        timeout_sec: 60,
+    });
+    return response;
+}
+export function makeBrowserTools() {
+    // Browser Navigate tool
+    const browserNavigate = tool(async ({ url, waitUntil = "domcontentloaded", }) => {
+        try {
+            const { liveViewUrl } = await ensureBrowserSession();
+            const code = `
+          await page.goto('${url.replace(/'/g, "\\'")}', { 
+            waitUntil: '${waitUntil}',
+            timeout: 30000 
+          });
+          return { url: page.url(), title: await page.title() };
+        `;
+            const response = await executePlaywright(code);
+            return {
+                success: true,
+                url: response.result?.url,
+                title: response.result?.title,
+                liveViewUrl,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                success: false,
+                error: `Navigation failed: ${errorMessage}`,
+                ...(_liveViewUrl ? { liveViewUrl: _liveViewUrl } : {}),
+            };
+        }
+    }, {
+        name: "BrowserNavigate",
+        description: "Navigate a cloud browser to a specified URL using Kernel's browser-as-a-service.\n" +
+            "- Opens web pages in a cloud-hosted browser\n" +
+            "- Returns the final URL (after redirects), page title, and a liveViewUrl\n" +
+            "- The liveViewUrl allows viewing the browser session in real-time\n" +
+            "- Browser session persists across tool calls\n" +
+            "\n" +
+            "Usage notes:\n" +
+            "  - First call creates a new browser session\n" +
+            "  - Subsequent calls reuse the same browser\n" +
+            "  - Share the liveViewUrl with users so they can watch the browser\n" +
+            "  - Use BrowserClose when done to release resources\n",
+        schema: z.object({
+            url: z.string().url().describe("The URL to navigate to"),
+            waitUntil: z
+                .enum(["load", "domcontentloaded", "networkidle"])
+                .optional()
+                .default("domcontentloaded")
+                .describe("When to consider navigation complete"),
+        }),
+    });
+    browserNavigate.prettyName = "Browser Navigate";
+    browserNavigate.icon = "Globe";
+    // Browser Screenshot tool
+    const browserScreenshot = tool(async ({ fullPage = false, selector, }) => {
+        try {
+            const { liveViewUrl } = await ensureBrowserSession();
+            let code;
+            if (selector) {
+                code = `
+            const element = await page.$('${selector.replace(/'/g, "\\'")}');
+            if (!element) {
+              return { error: 'Element not found: ${selector.replace(/'/g, "\\'")}' };
+            }
+            const screenshot = await element.screenshot({ type: 'png' });
+            return { screenshot: screenshot.toString('base64') };
+          `;
+            }
+            else {
+                code = `
+            const screenshot = await page.screenshot({ type: 'png', fullPage: ${fullPage} });
+            return { screenshot: screenshot.toString('base64') };
+          `;
+            }
+            const response = await executePlaywright(code);
+            if (response.result?.error) {
+                return {
+                    success: false,
+                    error: response.result.error,
+                    liveViewUrl,
+                };
+            }
+            // Save screenshot to local file instead of returning base64
+            const screenshotsDir = join(process.cwd(), "screenshots");
+            await mkdir(screenshotsDir, { recursive: true });
+            const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+            const filename = `screenshot-${timestamp}.png`;
+            const filepath = join(screenshotsDir, filename);
+            const imageBuffer = Buffer.from(response.result?.screenshot, "base64");
+            await Bun.write(filepath, imageBuffer);
+            return {
+                success: true,
+                screenshotPath: filepath,
+                liveViewUrl,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                success: false,
+                error: `Screenshot failed: ${errorMessage}`,
+                ...(_liveViewUrl ? { liveViewUrl: _liveViewUrl } : {}),
+            };
+        }
+    }, {
+        name: "BrowserScreenshot",
+        description: "Take a screenshot of the current browser page or a specific element.\n" +
+            "- Captures the current viewport or full page\n" +
+            "- Can target specific elements using CSS selectors\n" +
+            "- Saves the screenshot to a local file and returns the file path\n" +
+            "\n" +
+            "Usage notes:\n" +
+            "  - Use fullPage=true to capture the entire scrollable page\n" +
+            "  - Use selector to capture a specific element\n" +
+            "  - Requires an active browser session (call BrowserNavigate first)\n" +
+            "  - Screenshots are saved in the 'screenshots' folder in the current working directory\n",
+        schema: z.object({
+            fullPage: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Whether to capture the full scrollable page"),
+            selector: z
+                .string()
+                .optional()
+                .describe("CSS selector of element to screenshot (captures whole page if not provided)"),
+        }),
+    });
+    browserScreenshot.prettyName = "Browser Screenshot";
+    browserScreenshot.icon = "Camera";
+    // Browser Extract Content tool
+    const browserExtract = tool(async ({ selector, extractType = "text", }) => {
+        try {
+            const { liveViewUrl } = await ensureBrowserSession();
+            let code;
+            if (selector) {
+                if (extractType === "html") {
+                    code = `
+              const element = await page.$('${selector.replace(/'/g, "\\'")}');
+              if (!element) {
+                return { error: 'Element not found: ${selector.replace(/'/g, "\\'")}' };
+              }
+              const content = await element.innerHTML();
+              return { content, url: page.url(), title: await page.title() };
+            `;
+                }
+                else {
+                    code = `
+              const element = await page.$('${selector.replace(/'/g, "\\'")}');
+              if (!element) {
+                return { error: 'Element not found: ${selector.replace(/'/g, "\\'")}' };
+              }
+              const content = await element.innerText();
+              return { content, url: page.url(), title: await page.title() };
+            `;
+                }
+            }
+            else {
+                if (extractType === "html") {
+                    code = `
+              const content = await page.content();
+              return { content, url: page.url(), title: await page.title() };
+            `;
+                }
+                else {
+                    code = `
+              const content = await page.innerText('body');
+              return { content, url: page.url(), title: await page.title() };
+            `;
+                }
+            }
+            const response = await executePlaywright(code);
+            if (response.result?.error) {
+                return {
+                    success: false,
+                    error: response.result.error,
+                    liveViewUrl,
+                };
+            }
+            return {
+                success: true,
+                content: response.result?.content,
+                url: response.result?.url,
+                title: response.result?.title,
+                liveViewUrl,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                success: false,
+                error: `Content extraction failed: ${errorMessage}`,
+                ...(_liveViewUrl ? { liveViewUrl: _liveViewUrl } : {}),
+            };
+        }
+    }, {
+        name: "BrowserExtract",
+        description: "Extract text or HTML content from the current page or a specific element.\n" +
+            "- Gets readable text content from web pages\n" +
+            "- Can extract HTML for structured data\n" +
+            "- Supports CSS selectors for targeting specific elements\n" +
+            "\n" +
+            "Usage notes:\n" +
+            "  - Default extracts text from the entire page body\n" +
+            "  - Use selector to target specific page sections\n" +
+            "  - Use extractType='html' when you need the raw HTML structure\n",
+        schema: z.object({
+            selector: z
+                .string()
+                .optional()
+                .describe("CSS selector of element to extract from (extracts from body if not provided)"),
+            extractType: z
+                .enum(["text", "html"])
+                .optional()
+                .default("text")
+                .describe("Type of content to extract"),
+        }),
+    });
+    browserExtract.prettyName = "Browser Extract";
+    browserExtract.icon = "FileText";
+    // Browser Click tool
+    const browserClick = tool(async ({ selector, button = "left" }) => {
+        try {
+            const { liveViewUrl } = await ensureBrowserSession();
+            const code = `
+          await page.click('${selector.replace(/'/g, "\\'")}', { 
+            button: '${button}',
+            timeout: 10000,
+          });
+          await page.waitForTimeout(500);
+          return { success: true };
+        `;
+            await executePlaywright(code);
+            return {
+                success: true,
+                message: `Clicked element: ${selector}`,
+                liveViewUrl,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                success: false,
+                error: `Click failed: ${errorMessage}`,
+                ...(_liveViewUrl ? { liveViewUrl: _liveViewUrl } : {}),
+            };
+        }
+    }, {
+        name: "BrowserClick",
+        description: "Click on an element in the current browser page.\n" +
+            "- Supports left, right, and middle mouse buttons\n" +
+            "- Waits for the element to be visible before clicking\n" +
+            "- Useful for interacting with buttons, links, and other clickable elements\n" +
+            "\n" +
+            "Usage notes:\n" +
+            "  - Provide a CSS selector to identify the target element\n" +
+            "  - The tool waits briefly after clicking for page updates\n",
+        schema: z.object({
+            selector: z.string().describe("CSS selector of the element to click"),
+            button: z
+                .enum(["left", "right", "middle"])
+                .optional()
+                .default("left")
+                .describe("Which mouse button to use"),
+        }),
+    });
+    browserClick.prettyName = "Browser Click";
+    browserClick.icon = "MousePointer";
+    // Browser Type tool
+    const browserType = tool(async ({ selector, text, pressEnter = false, }) => {
+        try {
+            const { liveViewUrl } = await ensureBrowserSession();
+            const code = `
+          await page.fill('${selector.replace(/'/g, "\\'")}', '${text.replace(/'/g, "\\'")}', { timeout: 10000 });
+          ${pressEnter ? `await page.press('${selector.replace(/'/g, "\\'")}', 'Enter'); await page.waitForTimeout(500);` : ""}
+          return { success: true };
+        `;
+            await executePlaywright(code);
+            return {
+                success: true,
+                message: `Typed text into element: ${selector}${pressEnter ? " (pressed Enter)" : ""}`,
+                liveViewUrl,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                success: false,
+                error: `Type failed: ${errorMessage}`,
+                ...(_liveViewUrl ? { liveViewUrl: _liveViewUrl } : {}),
+            };
+        }
+    }, {
+        name: "BrowserType",
+        description: "Type text into an input field in the current browser page.\n" +
+            "- Fills text into input fields, textareas, and contenteditable elements\n" +
+            "- Can optionally press Enter after typing (useful for search forms)\n" +
+            "- Clears existing content before typing\n" +
+            "\n" +
+            "Usage notes:\n" +
+            "  - Provide a CSS selector to identify the input element\n" +
+            "  - Set pressEnter=true to submit forms after typing\n",
+        schema: z.object({
+            selector: z.string().describe("CSS selector of the input element"),
+            text: z.string().describe("The text to type into the element"),
+            pressEnter: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Whether to press Enter after typing"),
+        }),
+    });
+    browserType.prettyName = "Browser Type";
+    browserType.icon = "Type";
+    // Browser Close tool
+    const browserClose = tool(async () => {
+        try {
+            if (_sessionId) {
+                const kernel = getKernelClient();
+                await kernel.browsers.deleteByID(_sessionId);
+            }
+            _sessionId = null;
+            _liveViewUrl = null;
+            return {
+                success: true,
+                message: "Browser session closed successfully",
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                success: false,
+                error: `Close failed: ${errorMessage}`,
+            };
+        }
+    }, {
+        name: "BrowserClose",
+        description: "Close the current browser session and release cloud resources.\n" +
+            "- Terminates the active browser connection\n" +
+            "- Frees up cloud browser resources\n" +
+            "- Call this when done with browser automation\n" +
+            "\n" +
+            "Usage notes:\n" +
+            "  - A new browser session will be created on the next BrowserNavigate call\n" +
+            "  - Calling this when no browser is active has no effect\n",
+        schema: z.object({}),
+    });
+    browserClose.prettyName = "Browser Close";
+    browserClose.icon = "X";
+    return [
+        browserNavigate,
+        browserScreenshot,
+        browserExtract,
+        browserClick,
+        browserType,
+        browserClose,
+    ];
+}

package/dist/runner/langchain/tools/subagent-connections.d.ts

@@ -0,0 +1,28 @@
+import { EventEmitter } from "node:events";
+/**
+ * Registry for subagent connection info.
+ * Maps query hash to connection info so the runner can emit tool_call_update.
+ */
+export interface SubagentConnectionInfo {
+    port: number;
+    sessionId: string;
+}
+/**
+ * Event emitter for subagent connection events.
+ * The runner listens to these events and emits tool_call_update.
+ */
+export declare const subagentEvents: EventEmitter<[never]>;
+/**
+ * Maps query hash to toolCallId.
+ * Set by the runner when it sees a subagent tool_call.
+ */
+export declare const queryToToolCallId: Map<string, string>;
+/**
+ * Generate a hash from the query string for correlation.
+ */
+export declare function hashQuery(query: string): string;
+/**
+ * Called by the subagent tool when connection is established.
+ * Emits an event that the runner can listen to.
+ */
+export declare function emitSubagentConnection(queryHash: string, connectionInfo: SubagentConnectionInfo): void;

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

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { createLogger } from "@townco/core";
+const logger = createLogger("subagent-connections");
+/**
+ * Event emitter for subagent connection events.
+ * The runner listens to these events and emits tool_call_update.
+ */
+export const subagentEvents = new EventEmitter();
+/**
+ * Maps query hash to toolCallId.
+ * Set by the runner when it sees a subagent tool_call.
+ */
+export const queryToToolCallId = new Map();
+/**
+ * Generate a hash from the query string for correlation.
+ */
+export function hashQuery(query) {
+    const hash = createHash("sha256").update(query).digest("hex").slice(0, 16);
+    logger.debug("Generated query hash", {
+        queryPreview: query.slice(0, 50),
+        hash,
+    });
+    return hash;
+}
+/**
+ * Called by the subagent tool when connection is established.
+ * Emits an event that the runner can listen to.
+ */
+export function emitSubagentConnection(queryHash, connectionInfo) {
+    logger.info("emitSubagentConnection called", {
+        queryHash,
+        port: connectionInfo.port,
+        sessionId: connectionInfo.sessionId,
+        registeredHashes: Array.from(queryToToolCallId.keys()),
+    });
+    const toolCallId = queryToToolCallId.get(queryHash);
+    if (toolCallId) {
+        logger.info("Found toolCallId for queryHash, emitting connection event", {
+            queryHash,
+            toolCallId,
+            port: connectionInfo.port,
+            sessionId: connectionInfo.sessionId,
+        });
+        subagentEvents.emit("connection", {
+            toolCallId,
+            ...connectionInfo,
+        });
+        // Clean up the mapping
+        queryToToolCallId.delete(queryHash);
+    }
+    else {
+        logger.warn("No toolCallId found for queryHash", {
+            queryHash,
+            registeredHashes: Array.from(queryToToolCallId.keys()),
+        });
+    }
+}

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

@@ -7,6 +7,7 @@ import { createLogger as coreCreateLogger } from "@townco/core";
 import { z } from "zod";
 import { SUBAGENT_MODE_KEY } from "../../../acp-server/adapter.js";
 import { findAvailablePort } from "./port-utils.js";
+import { emitSubagentConnection, hashQuery } from "./subagent-connections.js";
 /**
  * Name of the Task tool created by makeSubagentsTool
  */
@@ -100,7 +101,7 @@ export function makeSubagentsTool(configs) {
         type: "direct",
         name: SUBAGENT_TOOL_NAME,
         prettyName: "Subagent",
-        icon: "BrainCircuit",
+        icon: "CircleDot",
         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.
@@ -310,6 +311,9 @@ async function querySubagent(agentName, agentPath, agentWorkingDirectory, query)
         if (!sessionId) {
             throw new Error("No sessionId in session/new response");
         }
+        // Emit connection info so the GUI can connect directly to this subagent's SSE
+        const queryHash = hashQuery(query);
+        emitSubagentConnection(queryHash, { port, sessionId });
         // Step 3: Connect to SSE for receiving streaming responses
         sseAbortController = new AbortController();
         let responseText = "";

package/dist/runner/tools.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 /** Built-in tool types. */
-export declare const zBuiltInToolType: z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"filesystem">, z.ZodLiteral<"generate_image">]>;
+export declare const zBuiltInToolType: z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"filesystem">, z.ZodLiteral<"generate_image">, z.ZodLiteral<"browser">]>;
 /** Subagent configuration schema for Task tools. */
 export declare const zSubagentConfig: z.ZodObject<{
     agentName: z.ZodString;
@@ -23,7 +23,7 @@ declare const zDirectTool: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 /** Tool type - can be a built-in tool string or custom tool object. */
-export declare const zToolType: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"filesystem">, z.ZodLiteral<"generate_image">]>, z.ZodObject<{
+export declare const zToolType: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"filesystem">, z.ZodLiteral<"generate_image">, z.ZodLiteral<"browser">]>, z.ZodObject<{
     type: z.ZodLiteral<"custom">;
     modulePath: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{

package/dist/runner/tools.js

@@ -6,6 +6,7 @@ export const zBuiltInToolType = z.union([
     z.literal("web_search"),
     z.literal("filesystem"),
     z.literal("generate_image"),
+    z.literal("browser"),
 ]);
 /** Custom tool schema (loaded from module path). */
 const zCustomTool = z.object({

package/dist/scaffold/index.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { mkdir, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { generateBinTs, generateIndexTs, getTemplateVars } from "../templates";
+import { generateBinTs, generateEnvExample, generateIndexTs, generateReadme, getTemplateVars, } from "../templates";
 import { copyGuiApp } from "./copy-gui";
 import { copyTuiApp } from "./copy-tui";
 /**
@@ -34,7 +34,13 @@ export async function scaffoldAgent(options) {
         const files = [
             { path: "index.ts", content: await generateIndexTs(vars) },
             { path: "bin.ts", content: generateBinTs(), executable: true },
+            { path: "README.md", content: generateReadme(vars) },
         ];
+        // 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);

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

@@ -9,6 +9,8 @@ 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
+- `generate_image`: Image generation using Google Gemini (requires GEMINI_API_KEY or GOOGLE_API_KEY)
+- `browser`: Cloud browser automation using Kernel (requires KERNEL_API_KEY)
 
 To use built-in tools, simply add them to the `tools` array in your agent definition:
 ```

package/dist/telemetry/index.d.ts

@@ -23,6 +23,11 @@ declare class AgentTelemetry {
     private serviceName;
     private baseAttributes;
     configure(config: TelemetryConfig): void;
+    /**
+     * Update base attributes that will be added to all future spans
+     * @param attributes - Attributes to merge with existing base attributes
+     */
+    setBaseAttributes(attributes: Record<string, string | number>): void;
     /**
      * Start a new span
      * @param name - Span name

package/dist/telemetry/index.js

@@ -30,6 +30,16 @@ class AgentTelemetry {
             }
         }
     }
+    /**
+     * Update base attributes that will be added to all future spans
+     * @param attributes - Attributes to merge with existing base attributes
+     */
+    setBaseAttributes(attributes) {
+        this.baseAttributes = {
+            ...this.baseAttributes,
+            ...attributes,
+        };
+    }
     /**
      * Start a new span
      * @param name - Span name

package/dist/templates/index.d.ts

@@ -20,6 +20,8 @@ export interface TemplateVars {
     }>;
     systemPrompt: string | null;
     hasWebSearch: boolean;
+    hasGenerateImage: boolean;
+    hasBrowser: boolean;
     hooks?: Array<{
         type: "context_size";
         setting?: {