@townco/agent 0.1.73 → 0.1.74

package/dist/runner/langchain/otel-callbacks.js

@@ -5,11 +5,15 @@ import { telemetry } from "../../telemetry/index.js";
  * Creates spans for each LLM request to track model invocations and token usage.
  */
 /**
- * Map to store active spans by their LangChain run ID
+ * Map to store active chat spans by their LangChain run ID
  *
  * There's a memory leak opportunity here, but we are OK with that for now.
  */
 const spansByRunId = new Map();
+/**
+ * Map to store active iteration spans by their LangChain run ID
+ */
+const iterationSpansByRunId = new Map();
 /**
  * Serializes LangChain messages to a JSON string for span attributes.
  * Extracts role and content from each message.
@@ -88,19 +92,41 @@ function serializeOutput(output) {
  * @returns CallbackHandlerMethods object that can be passed to LangChain
  */
 export function makeOtelCallbacks(opts) {
+    // Track the iteration span for this specific invocation
+    let localIterationSpan = null;
+    let currentIterationContext = opts.parentContext;
     return {
         /**
          * Called when a chat model/LLM request starts.
-         * Creates a new OTEL span for this LLM request.
+         * Creates iteration span first, then chat span as its child.
          */
         async handleChatModelStart(_llm, messages, runId, _parentRunId, _extraParams, tags, _metadata) {
             // Extract system prompt and serialize messages
             const systemPrompt = extractSystemPrompt(messages);
             const serializedMessages = serializeMessages(messages);
-            // Create span within the parent context (invocation span)
+            // Close previous iteration span if it exists (tools from previous iteration are done)
+            if (localIterationSpan) {
+                telemetry.endSpan(localIterationSpan);
+                localIterationSpan = null;
+            }
+            // Create iteration span within the parent context (invocation span)
+            const iterationIndex = opts.iterationIndexRef.current;
+            const iterationSpan = context.with(opts.parentContext, () => telemetry.startSpan("agent.iteration", {
+                "agent.iteration.index": iterationIndex,
+                "langchain.run_id": runId,
+            }));
+            // Track as current iteration span (will be closed when next iteration starts or invocation ends)
+            localIterationSpan = iterationSpan;
+            // Create context with iteration span as active
+            const iterationContext = iterationSpan
+                ? trace.setSpan(opts.parentContext, iterationSpan)
+                : opts.parentContext;
+            // Store current iteration context so tools can use it
+            currentIterationContext = iterationContext;
+            // Create chat span as child of iteration span
             // Following OpenTelemetry GenAI semantic conventions:
             // https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/
-            const span = context.with(opts.parentContext, () => telemetry.startSpan(`chat ${opts.model}`, {
+            const chatSpan = context.with(iterationContext, () => telemetry.startSpan(`chat ${opts.model}`, {
                 "gen_ai.operation.name": "chat",
                 "gen_ai.provider.name": opts.provider,
                 "gen_ai.request.model": opts.model,
@@ -114,10 +140,14 @@ export function makeOtelCallbacks(opts) {
                     ? { "langchain.tags": tags.join(",") }
                     : {}),
             }));
-            if (span) {
-                spansByRunId.set(runId, span);
+            // Store both spans
+            if (iterationSpan) {
+                iterationSpansByRunId.set(runId, iterationSpan);
+            }
+            if (chatSpan) {
+                spansByRunId.set(runId, chatSpan);
                 // Emit log for LLM request with trace context
-                const spanContext = span.spanContext();
+                const spanContext = chatSpan.spanContext();
                 telemetry.log("info", "LLM Request", {
                     "gen_ai.operation.name": "chat",
                     "gen_ai.provider.name": opts.provider,
@@ -129,14 +159,16 @@ export function makeOtelCallbacks(opts) {
                     span_id: spanContext.spanId,
                 });
             }
+            // Increment iteration index for next LLM call
+            opts.iterationIndexRef.current++;
         },
         /**
          * Called when an LLM request completes successfully.
-         * Records token usage and ends the span.
+         * Records token usage and ends both chat and iteration spans.
          */
         async handleLLMEnd(output, runId) {
-            const span = spansByRunId.get(runId);
-            if (!span)
+            const chatSpan = spansByRunId.get(runId);
+            if (!chatSpan)
                 return;
             // Extract token usage from LLM output
             // The structure varies by provider but LangChain normalizes it
@@ -147,15 +179,15 @@ export function makeOtelCallbacks(opts) {
                     (tokenUsage.totalTokens != null
                         ? tokenUsage.totalTokens - inputTokens
                         : 0);
-                telemetry.recordTokenUsage(inputTokens, outputTokens, span);
+                telemetry.recordTokenUsage(inputTokens, outputTokens, chatSpan);
             }
             // Serialize output and attach to span
             const serializedOutput = serializeOutput(output);
-            telemetry.setSpanAttributes(span, {
+            telemetry.setSpanAttributes(chatSpan, {
                 "gen_ai.output.messages": serializedOutput,
             });
             // Emit log for LLM response with trace context
-            const spanContext = span.spanContext();
+            const spanContext = chatSpan.spanContext();
             telemetry.log("info", "LLM Response", {
                 "gen_ai.operation.name": "chat",
                 "gen_ai.output.messages": serializedOutput,
@@ -171,19 +203,47 @@ export function makeOtelCallbacks(opts) {
                 trace_id: spanContext.traceId,
                 span_id: spanContext.spanId,
             });
-            telemetry.endSpan(span);
+            // End chat span
+            telemetry.endSpan(chatSpan);
             spansByRunId.delete(runId);
+            // DON'T close iteration span here - tools will execute after this
+            // The iteration span will be closed when:
+            // 1. Next iteration starts (in handleChatModelStart)
+            // 2. Invocation ends (caller must close remaining span)
+            iterationSpansByRunId.delete(runId);
         },
         /**
          * Called when an LLM request fails with an error.
-         * Records the error and ends the span with error status.
+         * Records the error and ends both chat and iteration spans.
          */
         async handleLLMError(error, runId) {
-            const span = spansByRunId.get(runId);
-            if (!span)
-                return;
-            telemetry.endSpan(span, error instanceof Error ? error : new Error(String(error)));
-            spansByRunId.delete(runId);
+            const chatSpan = spansByRunId.get(runId);
+            if (chatSpan) {
+                telemetry.endSpan(chatSpan, error instanceof Error ? error : new Error(String(error)));
+                spansByRunId.delete(runId);
+            }
+            // Close iteration span on error
+            if (localIterationSpan) {
+                telemetry.endSpan(localIterationSpan, error instanceof Error ? error : new Error(String(error)));
+                localIterationSpan = null;
+            }
+            iterationSpansByRunId.delete(runId);
+        },
+        /**
+         * Get the current iteration context for tool span creation
+         */
+        getCurrentIterationContext() {
+            return currentIterationContext;
+        },
+        /**
+         * Cleanup function to close any remaining iteration span
+         * Should be called when invocation completes
+         */
+        cleanup() {
+            if (localIterationSpan) {
+                telemetry.endSpan(localIterationSpan);
+                localIterationSpan = null;
+            }
         },
     };
 }

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

@@ -190,6 +190,11 @@ export function makeFilesystemTools(workingDirectory) {
     });
     grep.prettyName = "Codebase Search";
     grep.icon = "Search";
+    grep.verbiage = {
+        active: "Searching for {query}",
+        past: "Searched for {query}",
+        paramKey: "pattern",
+    };
     const read = tool(async ({ file_path, offset, limit }) => {
         await ensureSandbox(resolvedWd);
         assertAbsolutePath(file_path, "file_path");
@@ -234,6 +239,11 @@ export function makeFilesystemTools(workingDirectory) {
     });
     read.prettyName = "Read File";
     read.icon = "FileText";
+    read.verbiage = {
+        active: "Reading {file}",
+        past: "Read {file}",
+        paramKey: "file_path",
+    };
     const write = tool(async ({ file_path, content }) => {
         await ensureSandbox(resolvedWd);
         assertAbsolutePath(file_path, "file_path");
@@ -263,5 +273,10 @@ export function makeFilesystemTools(workingDirectory) {
     });
     write.prettyName = "Write File";
     write.icon = "Edit";
+    write.verbiage = {
+        active: "Writing {file}",
+        past: "Wrote {file}",
+        paramKey: "file_path",
+    };
     return [grep, read, write];
 }

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

@@ -78,3 +78,7 @@ When in doubt, use this tool. Being proactive with task management demonstrates
 });
 todoWrite.prettyName = "Todo List";
 todoWrite.icon = "CheckSquare";
+todoWrite.verbiage = {
+    active: "Updating to-do's",
+    past: "Updated to-do's",
+};

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+/** Create web search tools using direct EXA_API_KEY */
 export declare function makeWebSearchTools(): readonly [import("langchain").DynamicStructuredTool<z.ZodObject<{
     query: z.ZodString;
 }, z.core.$strip>, {
@@ -21,3 +22,26 @@ export declare function makeWebSearchTools(): readonly [import("langchain").Dyna
     url: string;
     prompt: string;
 }, string>];
+/** Create web search tools using Town proxy */
+export declare function makeTownWebSearchTools(): readonly [import("langchain").DynamicStructuredTool<z.ZodObject<{
+    query: z.ZodString;
+}, z.core.$strip>, {
+    query: string;
+}, {
+    query: string;
+}, string | import("exa-js").SearchResponse<{
+    numResults: number;
+    type: "auto";
+    text: {
+        maxCharacters: number;
+    };
+}>>, import("langchain").DynamicStructuredTool<z.ZodObject<{
+    url: z.ZodString;
+    prompt: z.ZodString;
+}, z.core.$strip>, {
+    url: string;
+    prompt: string;
+}, {
+    url: string;
+    prompt: string;
+}, string>];

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

@@ -1,24 +1,38 @@
 import Anthropic from "@anthropic-ai/sdk";
+import { getShedAuth } from "@townco/core/auth";
 import Exa from "exa-js";
 import { tool } from "langchain";
 import { z } from "zod";
-let _exaClient = null;
-function getExaClient() {
-    if (_exaClient) {
-        return _exaClient;
+let _directExaClient = null;
+let _townExaClient = null;
+/** Get Exa client using direct EXA_API_KEY environment variable */
+function getDirectExaClient() {
+    if (_directExaClient) {
+        return _directExaClient;
     }
     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");
     }
-    _exaClient = new Exa(apiKey);
-    return _exaClient;
+    _directExaClient = new Exa(apiKey);
+    return _directExaClient;
 }
-export function makeWebSearchTools() {
-    // WebSearch tool - search the web
+/** Get Exa client using Town proxy with authenticated credentials */
+function getTownExaClient() {
+    if (_townExaClient) {
+        return _townExaClient;
+    }
+    const shedAuth = getShedAuth();
+    if (!shedAuth) {
+        throw new Error("Not logged in. Run 'town login' or set SHED_API_KEY to use the town_web_search tool.");
+    }
+    _townExaClient = new Exa(shedAuth.accessToken, `${shedAuth.shedUrl}/api/exa`);
+    return _townExaClient;
+}
+function makeWebSearchToolsInternal(getClient) {
     const webSearch = tool(async ({ query }) => {
-        const client = getExaClient();
+        const client = getClient();
         const result = await client.searchAndContents(query, {
             numResults: 5,
             type: "auto",
@@ -48,9 +62,13 @@ export function makeWebSearchTools() {
     });
     webSearch.prettyName = "Web Search";
     webSearch.icon = "Globe";
-    // WebFetch tool - get contents of specific URLs
+    webSearch.verbiage = {
+        active: "Searching the web for {query}",
+        past: "Searched the web for {query}",
+        paramKey: "query",
+    };
     const webFetch = tool(async ({ url, prompt }) => {
-        const client = getExaClient();
+        const client = getClient();
         try {
             const result = await client.getContents([url], {
                 text: true,
@@ -122,8 +140,21 @@ export function makeWebSearchTools() {
     });
     webFetch.prettyName = "Web Fetch";
     webFetch.icon = "Link";
+    webFetch.verbiage = {
+        active: "Fetching {url}",
+        past: "Fetched {url}",
+        paramKey: "url",
+    };
     return [webSearch, webFetch];
 }
+/** Create web search tools using direct EXA_API_KEY */
+export function makeWebSearchTools() {
+    return makeWebSearchToolsInternal(getDirectExaClient);
+}
+/** Create web search tools using Town proxy */
+export function makeTownWebSearchTools() {
+    return makeWebSearchToolsInternal(getTownExaClient);
+}
 function buildWebFetchUserMessage(pageContent, prompt) {
     return `Web page content:
 ---

package/dist/runner/tool-loader.d.ts

@@ -6,6 +6,11 @@ export type CustomToolModule = {
     description: string;
     prettyName?: string;
     icon?: string;
+    verbiage?: {
+        active: string;
+        past: string;
+        paramKey?: string;
+    };
 };
 export type ResolvedCustomTool = {
     fn: (input: unknown) => unknown | Promise<unknown>;
@@ -14,5 +19,10 @@ export type ResolvedCustomTool = {
     description: string;
     prettyName?: string;
     icon?: string;
+    verbiage?: {
+        active: string;
+        past: string;
+        paramKey?: string;
+    };
 };
 export declare function loadCustomToolModule(modulePath: string): Promise<ResolvedCustomTool>;

package/dist/runner/tool-loader.js

@@ -37,6 +37,7 @@ export async function loadCustomToolModule(modulePath) {
         description: mod.description,
         ...(mod.prettyName && { prettyName: mod.prettyName }),
         ...(mod.icon && { icon: mod.icon }),
+        ...(mod.verbiage && { verbiage: mod.verbiage }),
     };
     // Cache the resolved tool
     customToolCache.set(modulePath, resolved);

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">, z.ZodLiteral<"browser">]>;
+export declare const zBuiltInToolType: z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"town_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.ZodLiteral<"browser">]>, 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<"town_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

@@ -4,6 +4,7 @@ export const zBuiltInToolType = z.union([
     z.literal("todo_write"),
     z.literal("get_weather"),
     z.literal("web_search"),
+    z.literal("town_web_search"),
     z.literal("filesystem"),
     z.literal("generate_image"),
     z.literal("browser"),

package/dist/telemetry/index.d.ts

@@ -28,6 +28,11 @@ declare class AgentTelemetry {
      * @param attributes - Attributes to merge with existing base attributes
      */
     setBaseAttributes(attributes: Record<string, string | number>): void;
+    /**
+     * Remove a base attribute
+     * @param key - Attribute key to remove
+     */
+    clearBaseAttribute(key: string): void;
     /**
      * Start a new span
      * @param name - Span name

package/dist/telemetry/index.js

@@ -40,6 +40,14 @@ class AgentTelemetry {
             ...attributes,
         };
     }
+    /**
+     * Remove a base attribute
+     * @param key - Attribute key to remove
+     */
+    clearBaseAttribute(key) {
+        const { [key]: _, ...rest } = this.baseAttributes;
+        this.baseAttributes = rest;
+    }
     /**
      * Start a new span
      * @param name - Span name

package/dist/telemetry/setup.js

@@ -68,10 +68,12 @@ export function initializeOpenTelemetry(options = {}) {
                     // false "Request timed out" errors. The export usually succeeds anyway.
                     // Only log non-timeout errors as actual errors.
                     const errorMsg = result.error?.message ?? "";
-                    if (errorMsg.includes("timed out")) {
+                    if (errorMsg.includes("timed out") ||
+                        errorMsg.includes("Request timed out")) {
                         if (debug) {
-                            console.log(`⚠️  Export reported timeout (Bun http bug - data likely sent successfully)`);
+                            console.log(`⚠️  Export reported timeout (Bun http bug - data successfully sent)`);
                         }
+                        // Don't log timeout errors at all - they're false positives
                     }
                     else {
                         console.error(`❌ Failed to export spans:`, result.error);
@@ -141,7 +143,12 @@ export function initializeOpenTelemetry(options = {}) {
             }
         }
         catch (error) {
-            console.error("Error flushing telemetry:", error);
+            // Filter out Bun HTTP timeout errors - they're false positives
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            if (!errorMsg.includes("timed out") &&
+                !errorMsg.includes("Request timed out")) {
+                console.error("Error flushing telemetry:", error);
+            }
         }
     };
     return { provider, loggerProvider, shutdown };