@townco/agent 0.1.118 → 0.1.120

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

@@ -403,8 +403,8 @@ function makeE2BToolsInternal(getSandbox) {
     shareSandboxFile.prettyName = "Share from Sandbox";
     // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     shareSandboxFile.icon = "Share";
-    // Tool 6: Upload Library Document to Sandbox
-    const uploadLibraryDocument = tool(async ({ document_id }) => {
+    // Tool 6: Load Library Documents to Sandbox
+    const loadLibraryDocuments = tool(async ({ document_ids }) => {
         const sandbox = await getSandbox();
         try {
             const libraryApiUrl = process.env.LIBRARY_API_URL;
@@ -412,14 +412,14 @@ function makeE2BToolsInternal(getSandbox) {
             if (!libraryApiUrl || !libraryApiKey) {
                 throw new Error("LIBRARY_API_URL and LIBRARY_API_KEY environment variables are required");
             }
-            const response = await fetch(`${libraryApiUrl}/sandbox/upload_document_to_sandbox`, {
+            const response = await fetch(`${libraryApiUrl}/sandbox/upload_documents_to_sandbox`, {
                 method: "POST",
                 headers: {
                     "Content-Type": "application/json",
                     Authorization: `Bearer ${libraryApiKey}`,
                 },
                 body: JSON.stringify({
-                    document_id,
+                    document_ids,
                     sandbox_id: sandbox.sandboxId,
                 }),
             });
@@ -428,34 +428,50 @@ function makeE2BToolsInternal(getSandbox) {
                 throw new Error(`Library API error: ${response.status} - ${text}`);
             }
             const result = await response.json();
-            return result.path;
+            // Format the response
+            const successfulUploads = result.results
+                .filter((r) => r.status === "success")
+                .map((r) => r.file_path);
+            const failedUploads = result.results
+                .filter((r) => r.status === "error")
+                .map((r) => `${r.document_id}: ${r.error}`);
+            let output = `Status: ${result.status}\n`;
+            output += `Uploaded ${result.successful_uploads}/${result.total_requested} documents\n`;
+            if (successfulUploads.length > 0) {
+                output += `\nSuccessful uploads:\n${successfulUploads.join("\n")}`;
+            }
+            if (failedUploads.length > 0) {
+                output += `\nFailed uploads:\n${failedUploads.join("\n")}`;
+            }
+            return output;
         }
         catch (error) {
-            logger.error("Error uploading library document to sandbox", {
+            logger.error("Error loading library documents to sandbox", {
                 error,
-                document_id,
+                document_ids,
             });
-            return `Error uploading document: ${error instanceof Error ? error.message : String(error)}`;
+            return `Error loading documents: ${error instanceof Error ? error.message : String(error)}`;
         }
     }, {
-        name: "Sandbox_UploadLibraryDocument",
-        description: "Upload a document from the library to the cloud sandbox. " +
-            "Use this to make library documents available for processing in the sandbox environment.",
+        name: "Sandbox_LoadLibraryDocuments",
+        description: "Load multiple documents from the library to the cloud sandbox. " +
+            "Use this to make library documents available for processing in the sandbox environment. " +
+            "Supports batch uploads - some documents may succeed while others fail.",
         schema: z.object({
-            document_id: z
-                .string()
-                .describe("The ID of the document to upload from the library"),
+            document_ids: z
+                .array(z.string())
+                .describe("The IDs of the documents to load from the library"),
         }),
     });
     // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
-    uploadLibraryDocument.prettyName = "Upload Library Document";
+    loadLibraryDocuments.prettyName = "Load Library Documents";
     // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
-    uploadLibraryDocument.icon = "Upload";
+    loadLibraryDocuments.icon = "FileText";
     // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
-    uploadLibraryDocument.verbiage = {
-        active: "Uploading document {document_id}",
-        past: "Uploaded document {document_id}",
-        paramKey: "document_id",
+    loadLibraryDocuments.verbiage = {
+        active: "Loading {document_ids.length} documents",
+        past: "Loaded {document_ids.length} documents",
+        paramKey: "document_ids",
     };
     // Tool 7: Generate Image in Sandbox
     const generateImage = tool(async ({ prompt }) => {
@@ -634,7 +650,7 @@ generateImage();
         readSandboxFile,
         writeSandboxFile,
         shareSandboxFile,
-        uploadLibraryDocument,
+        loadLibraryDocuments,
         generateImage,
     ];
 }

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

@@ -0,0 +1,47 @@
+import { z } from "zod";
+interface GenerateImageResult {
+    success: boolean;
+    filePath?: string | undefined;
+    fileName?: string | undefined;
+    imageUrl?: string | undefined;
+    textResponse?: string | undefined;
+    mimeType?: string | undefined;
+    error?: string | undefined;
+}
+/** Create generate image tool using direct GEMINI_API_KEY/GOOGLE_API_KEY */
+export declare function makeGenerateImageTool(): import("langchain").DynamicStructuredTool<z.ZodObject<{
+    prompt: z.ZodString;
+    aspectRatio: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        "16:9": "16:9";
+        "1:1": "1:1";
+        "3:4": "3:4";
+        "4:3": "4:3";
+        "5:4": "5:4";
+        "9:16": "9:16";
+    }>>>;
+}, z.core.$strip>, {
+    prompt: string;
+    aspectRatio: "16:9" | "1:1" | "3:4" | "4:3" | "5:4" | "9:16";
+}, {
+    prompt: string;
+    aspectRatio?: "16:9" | "1:1" | "3:4" | "4:3" | "5:4" | "9:16" | undefined;
+}, GenerateImageResult>;
+/** Create generate image tool using Town proxy */
+export declare function makeTownGenerateImageTool(): import("langchain").DynamicStructuredTool<z.ZodObject<{
+    prompt: z.ZodString;
+    aspectRatio: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        "16:9": "16:9";
+        "1:1": "1:1";
+        "3:4": "3:4";
+        "4:3": "4:3";
+        "5:4": "5:4";
+        "9:16": "9:16";
+    }>>>;
+}, z.core.$strip>, {
+    prompt: string;
+    aspectRatio: "16:9" | "1:1" | "3:4" | "4:3" | "5:4" | "9:16";
+}, {
+    prompt: string;
+    aspectRatio?: "16:9" | "1:1" | "3:4" | "4:3" | "5:4" | "9:16" | undefined;
+}, GenerateImageResult>;
+export {};

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

@@ -0,0 +1,175 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { GoogleGenAI } from "@google/genai";
+import { getShedAuth } from "@townco/core/auth";
+import { tool } from "langchain";
+import { z } from "zod";
+import { getSessionContext, getToolOutputDir, hasSessionContext, } from "../../session-context";
+let _directGenaiClient = null;
+let _townGenaiClient = null;
+/** Get Google GenAI client using direct GEMINI_API_KEY/GOOGLE_API_KEY environment variable */
+function getDirectGenAIClient() {
+    if (_directGenaiClient) {
+        return _directGenaiClient;
+    }
+    const apiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
+    if (!apiKey) {
+        throw new Error("GEMINI_API_KEY or GOOGLE_API_KEY environment variable is required to use the generate_image tool. " +
+            "Please set one of them to your Google AI API key.");
+    }
+    _directGenaiClient = new GoogleGenAI({ apiKey });
+    return _directGenaiClient;
+}
+/** Get Google GenAI client using Town proxy with authenticated credentials */
+function getTownGenAIClient() {
+    if (_townGenaiClient) {
+        return _townGenaiClient;
+    }
+    const shedAuth = getShedAuth();
+    if (!shedAuth) {
+        throw new Error("Not logged in. Run 'town login' or set SHED_API_KEY to use the town_generate_image tool.");
+    }
+    // Configure the client to use shed as proxy
+    // The SDK will send requests to {shedUrl}/api/gemini/{apiVersion}/{path}
+    _townGenaiClient = new GoogleGenAI({
+        apiKey: shedAuth.accessToken,
+        httpOptions: {
+            baseUrl: `${shedAuth.shedUrl}/api/gemini/`,
+        },
+    });
+    return _townGenaiClient;
+}
+function makeGenerateImageToolInternal(getClient) {
+    const generateImage = tool(async ({ prompt, aspectRatio = "1:1" }) => {
+        try {
+            if (!hasSessionContext()) {
+                throw new Error("GenerateImage tool requires session context. Ensure the tool is called within a session.");
+            }
+            const { sessionId } = getSessionContext();
+            const toolOutputDir = getToolOutputDir("GenerateImage");
+            const client = getClient();
+            // Use Gemini 3 Pro Image for image generation
+            // Note: imageConfig is a valid API option but not yet in the TypeScript types
+            // biome-ignore lint/suspicious/noExplicitAny: imageConfig not yet typed in @google/genai
+            const config = {
+                responseModalities: ["TEXT", "IMAGE"],
+                imageConfig: {
+                    aspectRatio: aspectRatio,
+                },
+            };
+            const response = await client.models.generateContent({
+                model: "gemini-3-pro-image-preview",
+                contents: [{ text: prompt }],
+                config,
+            });
+            if (!response.candidates || response.candidates.length === 0) {
+                return {
+                    success: false,
+                    error: "No response from the model. The request may have been filtered.",
+                };
+            }
+            const candidate = response.candidates[0];
+            if (!candidate) {
+                return {
+                    success: false,
+                    error: "No candidate in the response.",
+                };
+            }
+            const parts = candidate.content?.parts;
+            if (!parts || parts.length === 0) {
+                return {
+                    success: false,
+                    error: "No content parts in the response.",
+                };
+            }
+            let imageData;
+            let textResponse;
+            let mimeType;
+            for (const part of parts) {
+                if (part.text) {
+                    textResponse = part.text;
+                }
+                else if (part.inlineData) {
+                    imageData = part.inlineData.data;
+                    mimeType = part.inlineData.mimeType || "image/png";
+                }
+            }
+            if (!imageData) {
+                return {
+                    success: false,
+                    error: "No image was generated in the response.",
+                    ...(textResponse ? { textResponse } : {}),
+                };
+            }
+            // Save image to session-scoped tool output directory
+            await mkdir(toolOutputDir, { recursive: true });
+            // Generate unique filename
+            const timestamp = Date.now();
+            const extension = mimeType === "image/jpeg" ? "jpg" : "png";
+            const fileName = `image-${timestamp}.${extension}`;
+            const filePath = join(toolOutputDir, fileName);
+            // Save image to file
+            const buffer = Buffer.from(imageData, "base64");
+            await writeFile(filePath, buffer);
+            // Create URL for the static file server
+            // The agent HTTP server serves static files from the agent directory
+            // Use AGENT_BASE_URL if set (for production), otherwise construct from BIND_HOST/PORT
+            const port = process.env.PORT || "3100";
+            const hostname = process.env.BIND_HOST || "localhost";
+            const baseUrl = process.env.AGENT_BASE_URL || `http://${hostname}:${port}`;
+            const imageUrl = `${baseUrl}/static/.sessions/${sessionId}/artifacts/tool-GenerateImage/${fileName}`;
+            return {
+                success: true,
+                filePath,
+                fileName,
+                imageUrl,
+                ...(mimeType ? { mimeType } : {}),
+                ...(textResponse ? { textResponse } : {}),
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                success: false,
+                error: `Image generation failed: ${errorMessage}`,
+            };
+        }
+    }, {
+        name: "GenerateImage",
+        description: "Generate an image based on a text prompt using Google's Gemini image generation model. " +
+            "Returns an imageUrl that can be displayed to the user. After calling this tool, " +
+            "include the imageUrl in your response as a markdown image like ![Description](imageUrl) " +
+            "so the user can see the generated image.\n" +
+            "- Creates images from detailed text descriptions\n" +
+            "- Supports various aspect ratios for different use cases\n" +
+            "- Be specific in prompts about style, composition, colors, and subjects\n" +
+            "\n" +
+            "Usage notes:\n" +
+            "  - Provide detailed, specific prompts for best results\n" +
+            "  - The generated image is saved to the session directory and served via URL\n" +
+            "  - Always display the result using markdown: ![description](imageUrl)\n",
+        schema: z.object({
+            prompt: z
+                .string()
+                .describe("A detailed description of the image to generate. Be specific about style, composition, colors, and subjects."),
+            aspectRatio: z
+                .enum(["1:1", "3:4", "4:3", "9:16", "16:9", "5:4"])
+                .optional()
+                .default("1:1")
+                .describe("The aspect ratio of the generated image."),
+        }),
+    });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    generateImage.prettyName = "Generate Image";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    generateImage.icon = "Image";
+    return generateImage;
+}
+/** Create generate image tool using direct GEMINI_API_KEY/GOOGLE_API_KEY */
+export function makeGenerateImageTool() {
+    return makeGenerateImageToolInternal(getDirectGenAIClient);
+}
+/** Create generate image tool using Town proxy */
+export function makeTownGenerateImageTool() {
+    return makeGenerateImageToolInternal(getTownGenAIClient);
+}

package/dist/runner/langchain/tools/port-utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Check if a port is available
+ */
+export declare function isPortAvailable(port: number): Promise<boolean>;
+/**
+ * Find the next available port starting from the given port
+ */
+export declare function findAvailablePort(startPort: number, maxAttempts?: number): Promise<number>;

package/dist/runner/langchain/tools/port-utils.js

@@ -0,0 +1,35 @@
+import { createServer } from "node:net";
+/**
+ * Check if a port is available
+ */
+export async function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                resolve(false);
+            }
+            else {
+                resolve(false);
+            }
+        });
+        server.once("listening", () => {
+            server.close();
+            resolve(true);
+        });
+        server.listen(port);
+    });
+}
+/**
+ * Find the next available port starting from the given port
+ */
+export async function findAvailablePort(startPort, maxAttempts = 100) {
+    for (let i = 0; i < maxAttempts; i++) {
+        const port = startPort + i;
+        const available = await isPortAvailable(port);
+        if (available) {
+            return port;
+        }
+    }
+    throw new Error(`Could not find an available port between ${startPort} and ${startPort + maxAttempts - 1}`);
+}

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

@@ -28,6 +28,12 @@ export interface SubagentMessage {
     content: string;
     contentBlocks: SubagentContentBlock[];
     toolCalls: SubagentToolCall[];
+    _meta?: {
+        semanticName?: string;
+        agentDefinitionName?: string;
+        currentActivity?: string;
+        statusGenerating?: boolean;
+    };
 }
 /**
  * Maps query hash to toolCallId.

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

@@ -2,6 +2,7 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs/promises";
 import { mkdir } from "node:fs/promises";
 import * as path from "node:path";
+import { ChatAnthropic } from "@langchain/anthropic";
 import { context, propagation, trace } from "@opentelemetry/api";
 import { createLogger } from "@townco/core";
 import { z } from "zod";
@@ -10,6 +11,58 @@ import { makeRunnerFromDefinition } from "../../index.js";
 import { bindGeneratorToSessionContext, getAbortSignal, } from "../../session-context.js";
 import { emitSubagentMessages, hashQuery, } from "./subagent-connections.js";
 const logger = createLogger("subagent-tool", "debug");
+/**
+ * Generate status message using Haiku (fast, cheap model)
+ */
+async function generateStatusMessage(recentContent, toolCalls) {
+    try {
+        const activeTool = toolCalls.find((tc) => tc.status === "in_progress");
+        const model = new ChatAnthropic({
+            modelName: "claude-3-haiku-20240307",
+            temperature: 0.3,
+            maxTokens: 30,
+        });
+        const prompt = `Summarize the current activity in 5-7 words for a progress indicator:
+
+Recent output: ${recentContent.slice(-500)}
+${activeTool ? `Active tool: ${activeTool.prettyName || activeTool.title}` : ""}
+
+Requirements:
+- Use present continuous tense (e.g., "Searching for...", "Analyzing...")
+- Be specific but concise
+- Focus on user-visible progress
+- Return ONLY the status, no explanation
+
+Status:`;
+        const response = await model.invoke(prompt);
+        const status = response.content.toString().trim().slice(0, 80);
+        return status;
+    }
+    catch (error) {
+        logger.warn("Failed to generate status message", { error });
+        return extractHeuristicStatus(recentContent, toolCalls);
+    }
+}
+/**
+ * Heuristic status extraction (fallback when LLM fails)
+ */
+function extractHeuristicStatus(content, toolCalls) {
+    // Priority 1: Active tool
+    const activeTool = toolCalls.find((tc) => tc.status === "in_progress");
+    if (activeTool) {
+        return `${activeTool.prettyName || activeTool.title}...`;
+    }
+    // Priority 2: First complete sentence from recent content
+    if (content.length > 50) {
+        const lastAdded = content.slice(-200);
+        const firstSentence = lastAdded.match(/[^.!?]+[.!?]/)?.[0];
+        if (firstSentence && firstSentence.length > 10) {
+            return firstSentence.trim().slice(0, 80);
+        }
+    }
+    // Priority 3: Generic fallback
+    return "Processing...";
+}
 /**
  * Helper to derive favicon URL from a domain
  */
@@ -311,23 +364,26 @@ assistant: "I'm going to use the Task tool to launch the greeting-responder agen
                 .enum(agentNames)
                 .describe("The name of the subagent to use"),
             query: z.string().describe("The query or task to send to the subagent"),
+            taskName: z
+                .string()
+                .describe("A concise 3-5 word name describing this specific task (e.g., 'Searching for React patterns', 'Analyzing API responses'). IMPORTANT: Be specific and action-oriented!"),
         }),
         // Expose subagent configs for metadata extraction by the adapter
         subagentConfigs,
         fn: async (input) => {
-            const { agentName, query } = input;
+            const { agentName, query, taskName } = input;
             const agent = agentMap.get(agentName);
             if (!agent) {
                 throw new Error(`Unknown agent: ${agentName}`);
             }
-            return await querySubagent(agentName, agent.agentPath, agent.agentDir, query);
+            return await querySubagent(agentName, agent.agentPath, agent.agentDir, query, taskName);
         },
     };
 }
 /**
  * Internal function that runs a subagent in-process and queries it.
  */
-async function querySubagent(agentName, agentPath, agentWorkingDirectory, query) {
+async function querySubagent(agentName, agentPath, agentWorkingDirectory, query, taskName) {
     // Get the abort signal from context (set by parent agent's cancellation)
     const parentAbortSignal = getAbortSignal();
     // Check if already cancelled before starting
@@ -358,6 +414,11 @@ async function querySubagent(agentName, agentPath, agentWorkingDirectory, query)
     const otelCarrier = {};
     if (activeSpan) {
         propagation.inject(trace.setSpan(activeCtx, activeSpan), otelCarrier);
+        // Set span attributes for observability
+        activeSpan.setAttributes({
+            "subagent.semantic_name": taskName,
+            "subagent.agent_definition": agentName,
+        });
     }
     // Create invoke request
     const invokeRequest = {
@@ -386,10 +447,37 @@ async function querySubagent(agentName, agentPath, agentWorkingDirectory, query)
         content: "",
         contentBlocks: [],
         toolCalls: [],
+        _meta: {
+            semanticName: taskName,
+            agentDefinitionName: agentName,
+            statusGenerating: true,
+        },
     };
     const toolCallMap = new Map();
     const toolNameMap = new Map(); // Map toolCallId -> toolName
     const queryHash = hashQuery(query);
+    // Emit initial message with semantic name immediately
+    emitSubagentMessages(queryHash, [currentMessage]);
+    // Track status updates for periodic generation
+    let lastStatusUpdate = Date.now();
+    let statusUpdateInProgress = false;
+    const STATUS_UPDATE_INTERVAL = 5000; // 5 seconds
+    // Fire async initial status generation (don't await)
+    generateStatusMessage(query, [])
+        .then((status) => {
+        if (currentMessage._meta) {
+            currentMessage._meta.currentActivity = status;
+            currentMessage._meta.statusGenerating = false;
+        }
+        // Emit update with status
+        emitSubagentMessages(queryHash, [currentMessage]);
+    })
+        .catch((error) => {
+        logger.warn("Initial status generation failed", { error });
+        if (currentMessage._meta) {
+            currentMessage._meta.statusGenerating = false;
+        }
+    });
     logger.info("[DEBUG] Starting subagent generator loop", {
         agentName,
         queryHash,
@@ -507,6 +595,29 @@ async function querySubagent(agentName, agentPath, agentWorkingDirectory, query)
                 }
                 shouldEmit = true; // Emit when sources are added
             }
+            // Periodic status update check
+            const now = Date.now();
+            const shouldUpdateStatus = !statusUpdateInProgress &&
+                now - lastStatusUpdate > STATUS_UPDATE_INTERVAL &&
+                currentMessage.content.length > 100; // Only if there's meaningful content
+            if (shouldUpdateStatus) {
+                statusUpdateInProgress = true;
+                lastStatusUpdate = now;
+                // Fire async status update (don't await)
+                generateStatusMessage(currentMessage.content, currentMessage.toolCalls)
+                    .then((status) => {
+                    if (currentMessage._meta) {
+                        currentMessage._meta.currentActivity = status;
+                    }
+                    // Emit update
+                    emitSubagentMessages(queryHash, [currentMessage]);
+                    statusUpdateInProgress = false;
+                })
+                    .catch((error) => {
+                    logger.warn("Status update failed", { error });
+                    statusUpdateInProgress = false;
+                });
+            }
             // Emit incremental update to parent (for live streaming)
             if (shouldEmit) {
                 logger.debug("[SUBAGENT-ACCUMULATION] Emitting incremental update", {

package/dist/templates/index.d.ts

@@ -1,4 +1,6 @@
-import type { AgentDefinition } from "../definition";
+import type { z } from "zod";
+import type { AgentDefinition, McpConfigSchema } from "../definition";
+type McpConfig = z.infer<typeof McpConfigSchema>;
 export interface TemplateVars {
     name: string;
     model: string;
@@ -18,6 +20,7 @@ export interface TemplateVars {
         fn: any;
         schema: unknown;
     }>;
+    mcps?: McpConfig[];
     systemPrompt: string | null;
     hasWebSearch: boolean;
     hasGenerateImage: boolean;
@@ -44,3 +47,4 @@ export declare function generateGitignore(): string;
 export declare function generateTsConfig(): string;
 export declare function generateReadme(vars: TemplateVars): string;
 export declare function generateEnvExample(vars: TemplateVars): string | null;
+export {};

package/dist/templates/index.js

@@ -20,6 +20,9 @@ export function getTemplateVars(name, definition) {
     if (definition.suggestedPrompts) {
         result.suggestedPrompts = definition.suggestedPrompts;
     }
+    if (definition.mcps && definition.mcps.length > 0) {
+        result.mcps = definition.mcps;
+    }
     return result;
 }
 export function generatePackageJson(vars) {
@@ -71,6 +74,9 @@ export async function generateIndexTs(vars) {
     }
     agentDef.systemPrompt = vars.systemPrompt;
     agentDef.tools = vars.tools;
+    if (vars.mcps && vars.mcps.length > 0) {
+        agentDef.mcps = vars.mcps;
+    }
     if (vars.hooks) {
         agentDef.hooks = vars.hooks;
     }