@townco/agent 0.1.87 → 0.1.98

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

@@ -0,0 +1,305 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getShedAuth } from "@townco/core/auth";
+import { tool } from "langchain";
+import { z } from "zod";
+import { createLogger } from "../../../logger.js";
+import { getSessionSandbox } from "../../e2b-sandbox-manager";
+import { getSessionContext, getToolOutputDir, hasSessionContext, } from "../../session-context";
+const logger = createLogger("e2b-tools");
+// Cached API key from Town proxy
+let _cachedApiKey = null;
+let _apiKeyFetchPromise = null;
+/**
+ * Get E2B API key from Town proxy (with caching).
+ */
+async function getTownE2BApiKey() {
+    if (_cachedApiKey) {
+        return _cachedApiKey;
+    }
+    // Prevent concurrent fetches
+    if (_apiKeyFetchPromise) {
+        return _apiKeyFetchPromise;
+    }
+    _apiKeyFetchPromise = (async () => {
+        const shedAuth = getShedAuth();
+        if (!shedAuth) {
+            throw new Error("Not logged in. Run 'town login' or set SHED_API_KEY to use the town_e2b tools.");
+        }
+        const response = await fetch(`${shedAuth.shedUrl}/api/e2b/api-key`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": shedAuth.accessToken,
+            },
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Failed to get E2B API key from Town proxy: ${text}`);
+        }
+        const { apiKey } = await response.json();
+        _cachedApiKey = apiKey;
+        return apiKey;
+    })();
+    try {
+        return await _apiKeyFetchPromise;
+    }
+    finally {
+        _apiKeyFetchPromise = null;
+    }
+}
+/**
+ * Helper to save image artifacts from code execution results.
+ */
+async function saveImageArtifact(base64Data, format) {
+    if (!hasSessionContext()) {
+        return "\n[Image generated but could not be saved - no session context]";
+    }
+    const { sessionId } = getSessionContext();
+    const toolOutputDir = getToolOutputDir("E2B");
+    await fs.mkdir(toolOutputDir, { recursive: true });
+    const timestamp = Date.now();
+    const fileName = `output-${timestamp}.${format}`;
+    const filePath = path.join(toolOutputDir, fileName);
+    const buffer = Buffer.from(base64Data, "base64");
+    await fs.writeFile(filePath, buffer);
+    // Generate URL for display
+    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-E2B/${fileName}`;
+    return `\n[Image saved: ${imageUrl}]`;
+}
+function makeE2BToolsInternal(getSandbox) {
+    // Tool 1: Run Code (Python or JavaScript)
+    const runCode = tool(async ({ code, language = "python" }) => {
+        const sandbox = await getSandbox();
+        try {
+            const result = await sandbox.runCode(code, { language });
+            // Format output
+            let output = "";
+            if (result.logs?.stdout && result.logs.stdout.length > 0) {
+                output += result.logs.stdout.join("\n");
+            }
+            if (result.logs?.stderr && result.logs.stderr.length > 0) {
+                if (output)
+                    output += "\n";
+                output += `[stderr]\n${result.logs.stderr.join("\n")}`;
+            }
+            if (result.error) {
+                if (output)
+                    output += "\n";
+                output += `[error] ${result.error.name}: ${result.error.value}`;
+            }
+            // Handle result value (charts, images, etc.)
+            if (result.results && result.results.length > 0) {
+                for (const res of result.results) {
+                    if (res.png) {
+                        output += await saveImageArtifact(res.png, "png");
+                    }
+                    else if (res.jpeg) {
+                        output += await saveImageArtifact(res.jpeg, "jpeg");
+                    }
+                    else if (res.svg) {
+                        // Save SVG as text file
+                        const toolOutputDir = getToolOutputDir("E2B");
+                        await fs.mkdir(toolOutputDir, { recursive: true });
+                        const fileName = `output-${Date.now()}.svg`;
+                        const filePath = path.join(toolOutputDir, fileName);
+                        await fs.writeFile(filePath, res.svg);
+                        output += `\n[SVG saved: ${filePath}]`;
+                    }
+                    else if (res.text) {
+                        if (output)
+                            output += "\n";
+                        output += res.text;
+                    }
+                }
+            }
+            return output.trim() || "(no output)";
+        }
+        catch (error) {
+            logger.error("Error executing code", { error });
+            return `Error executing code: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }, {
+        name: "E2B_RunCode",
+        description: "Execute Python or JavaScript code in a secure cloud sandbox. " +
+            "The sandbox persists across calls in the same session, preserving variables and state. " +
+            "Supports data analysis, file processing, and visualization. " +
+            "Generated images are automatically saved to the session's artifacts directory.",
+        schema: z.object({
+            code: z.string().describe("The code to execute"),
+            language: z
+                .enum(["python", "javascript"])
+                .optional()
+                .default("python")
+                .describe("The programming language (default: python)"),
+        }),
+    });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    runCode.prettyName = "Run Code";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    runCode.icon = "Terminal";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    runCode.verbiage = {
+        active: "Executing {language} code",
+        past: "Executed {language} code",
+        paramKey: "language",
+    };
+    // Tool 2: Run Bash Command
+    const runBash = tool(async ({ command }) => {
+        const sandbox = await getSandbox();
+        try {
+            const result = await sandbox.commands.run(command);
+            let output = "";
+            if (result.stdout) {
+                output += result.stdout;
+            }
+            if (result.stderr) {
+                if (output)
+                    output += "\n";
+                output += `[stderr]\n${result.stderr}`;
+            }
+            if (result.exitCode !== 0) {
+                output += `\n[exit code: ${result.exitCode}]`;
+            }
+            return output.trim() || "(no output)";
+        }
+        catch (error) {
+            logger.error("Error executing bash command", { error });
+            return `Error executing command: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }, {
+        name: "E2B_RunBash",
+        description: "Execute a bash command in the cloud sandbox. " +
+            "Use for system operations, package installation, file manipulation, etc. " +
+            "The sandbox filesystem persists across calls in the same session.",
+        schema: z.object({
+            command: z.string().describe("The bash command to execute"),
+        }),
+    });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    runBash.prettyName = "Run Bash";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    runBash.icon = "Terminal";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    runBash.verbiage = {
+        active: "Running: {command}",
+        past: "Ran: {command}",
+        paramKey: "command",
+    };
+    // Tool 3: Read File from Sandbox
+    const readSandboxFile = tool(async ({ path: filePath }) => {
+        const sandbox = await getSandbox();
+        try {
+            const content = await sandbox.files.read(filePath);
+            return content;
+        }
+        catch (error) {
+            logger.error("Error reading file from sandbox", { error, filePath });
+            return `Error reading file: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }, {
+        name: "E2B_ReadFile",
+        description: "Read a file from the cloud sandbox filesystem. " +
+            "Use to retrieve files created by code execution or bash commands.",
+        schema: z.object({
+            path: z.string().describe("The path to the file in the sandbox"),
+        }),
+    });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    readSandboxFile.prettyName = "Read Sandbox File";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    readSandboxFile.icon = "FileText";
+    // Tool 4: Write File to Sandbox
+    const writeSandboxFile = tool(async ({ path: filePath, content }) => {
+        const sandbox = await getSandbox();
+        try {
+            await sandbox.files.write(filePath, content);
+            return `Successfully wrote ${content.length} bytes to ${filePath}`;
+        }
+        catch (error) {
+            logger.error("Error writing file to sandbox", { error, filePath });
+            return `Error writing file: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }, {
+        name: "E2B_WriteFile",
+        description: "Write content to a file in the cloud sandbox filesystem. " +
+            "Use to create data files for code execution or save outputs.",
+        schema: z.object({
+            path: z.string().describe("The path to the file in the sandbox"),
+            content: z.string().describe("The content to write"),
+        }),
+    });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    writeSandboxFile.prettyName = "Write Sandbox File";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    writeSandboxFile.icon = "Edit";
+    // Tool 5: Download File from Sandbox to Artifacts
+    const downloadFromSandbox = tool(async ({ sandboxPath, fileName }) => {
+        if (!hasSessionContext()) {
+            throw new Error("E2B_DownloadFile requires session context");
+        }
+        const sandbox = await getSandbox();
+        const toolOutputDir = getToolOutputDir("E2B");
+        try {
+            // Read file from sandbox
+            const content = await sandbox.files.read(sandboxPath);
+            // Determine output filename
+            const outputFileName = fileName || path.basename(sandboxPath);
+            const outputPath = path.join(toolOutputDir, outputFileName);
+            // Ensure directory exists
+            await fs.mkdir(toolOutputDir, { recursive: true });
+            // Write to artifacts
+            await fs.writeFile(outputPath, content);
+            // Generate URL for display
+            const { sessionId } = getSessionContext();
+            const port = process.env.PORT || "3100";
+            const hostname = process.env.BIND_HOST || "localhost";
+            const baseUrl = process.env.AGENT_BASE_URL || `http://${hostname}:${port}`;
+            const fileUrl = `${baseUrl}/static/.sessions/${sessionId}/artifacts/tool-E2B/${outputFileName}`;
+            return `Downloaded ${sandboxPath} to artifacts.\nURL: ${fileUrl}`;
+        }
+        catch (error) {
+            logger.error("Error downloading file from sandbox", {
+                error,
+                sandboxPath,
+            });
+            return `Error downloading file: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }, {
+        name: "E2B_DownloadFile",
+        description: "Download a file from the cloud sandbox to the session's artifacts directory. " +
+            "Use to save generated files, plots, or outputs for the user to access.",
+        schema: z.object({
+            sandboxPath: z.string().describe("Path to the file in the sandbox"),
+            fileName: z
+                .string()
+                .optional()
+                .describe("Optional output filename (defaults to original name)"),
+        }),
+    });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    downloadFromSandbox.prettyName = "Download from Sandbox";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
+    downloadFromSandbox.icon = "Download";
+    return [
+        runCode,
+        runBash,
+        readSandboxFile,
+        writeSandboxFile,
+        downloadFromSandbox,
+    ];
+}
+/**
+ * Create E2B tools using Town proxy authentication.
+ * Fetches E2B API key from Town server using user credentials.
+ */
+export function makeTownE2BTools() {
+    const getSandbox = async () => {
+        const apiKey = await getTownE2BApiKey();
+        return getSessionSandbox(apiKey);
+    };
+    return makeE2BToolsInternal(getSandbox);
+}

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

@@ -219,6 +219,69 @@ export function makeFilesystemTools() {
             normalizedPath !== normalizedArtifactsDir) {
             throw new Error(`Path ${file_path} is outside the allowed artifacts directory`);
         }
+        // Check for binary file extensions before reading
+        const ext = path.extname(resolvedPath).toLowerCase();
+        const binaryExtensions = new Set([
+            // Images
+            ".jpg",
+            ".jpeg",
+            ".png",
+            ".gif",
+            ".bmp",
+            ".webp",
+            ".ico",
+            ".svg",
+            ".tiff",
+            ".tif",
+            // Audio
+            ".mp3",
+            ".wav",
+            ".ogg",
+            ".flac",
+            ".aac",
+            ".m4a",
+            // Video
+            ".mp4",
+            ".avi",
+            ".mov",
+            ".mkv",
+            ".webm",
+            ".wmv",
+            // Archives
+            ".zip",
+            ".tar",
+            ".gz",
+            ".rar",
+            ".7z",
+            ".bz2",
+            // Documents
+            ".pdf",
+            ".doc",
+            ".docx",
+            ".xls",
+            ".xlsx",
+            ".ppt",
+            ".pptx",
+            // Executables
+            ".exe",
+            ".dll",
+            ".so",
+            ".dylib",
+            ".bin",
+            // Other binary
+            ".wasm",
+            ".pyc",
+            ".class",
+            ".o",
+            ".a",
+        ]);
+        if (binaryExtensions.has(ext)) {
+            // Get file size for informative message
+            const statCmd = `stat -f%z ${shEscape(resolvedPath)} 2>/dev/null || stat -c%s ${shEscape(resolvedPath)} 2>/dev/null`;
+            const { stdout: sizeOut } = await runSandboxed(statCmd, sessionDir);
+            const fileSize = sizeOut.toString("utf8").trim();
+            return `Cannot read binary file: ${file_path} (${ext} file, ${fileSize} bytes). Binary files like images, audio, video, and archives cannot be read as text. If you need to work with this file, use it by path reference instead.`;
+        }
         // Read the file using sandboxed cat
         const cmd = `cat ${shEscape(resolvedPath)}`;
         const { stdout, stderr, code } = await runSandboxed(cmd, sessionDir);

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

@@ -1,4 +1,12 @@
+import { type CitationSource } from "../../../acp-server/adapter.js";
 import type { DirectTool } from "../../tools.js";
+/**
+ * Result returned from a subagent, including text and any citation sources.
+ */
+export interface SubagentResult {
+    text: string;
+    sources: CitationSource[];
+}
 /**
  * Name of the Task tool created by makeSubagentsTool
  */

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

@@ -5,7 +5,8 @@ import { PROTOCOL_VERSION } from "@agentclientprotocol/sdk";
 import { context, propagation, trace } from "@opentelemetry/api";
 import { createLogger as coreCreateLogger } from "@townco/core";
 import { z } from "zod";
-import { SUBAGENT_MODE_KEY } from "../../../acp-server/adapter.js";
+import { SUBAGENT_MODE_KEY, } from "../../../acp-server/adapter.js";
+import { getAbortSignal } from "../../session-context.js";
 import { findAvailablePort } from "./port-utils.js";
 import { emitSubagentConnection, emitSubagentMessages, hashQuery, } from "./subagent-connections.js";
 /**
@@ -183,6 +184,12 @@ assistant: "I'm going to use the Task tool to launch the greeting-responder agen
  * Internal function that spawns a subagent HTTP server and queries it.
  */
 async function querySubagent(agentName, agentPath, agentWorkingDirectory, query) {
+    // Get the abort signal from context (set by parent agent's cancellation)
+    const parentAbortSignal = getAbortSignal();
+    // Check if already cancelled before starting
+    if (parentAbortSignal?.aborted) {
+        throw new Error("Subagent query cancelled before starting");
+    }
     // Validate that the agent exists
     try {
         await fs.access(agentPath);
@@ -197,6 +204,24 @@ async function querySubagent(agentName, agentPath, agentWorkingDirectory, query)
     const logger = coreCreateLogger(`subagent:${port}:${agentName}`);
     let agentProcess = null;
     let sseAbortController = null;
+    let cleanupTriggered = false;
+    // Cleanup function to kill the process and abort SSE
+    const cleanup = () => {
+        if (cleanupTriggered)
+            return;
+        cleanupTriggered = true;
+        logger.info(`Cleaning up subagent on port ${port} (cancelled by parent)`);
+        if (sseAbortController) {
+            sseAbortController.abort();
+        }
+        if (agentProcess) {
+            agentProcess.kill("SIGTERM");
+        }
+    };
+    // Listen for parent abort signal
+    if (parentAbortSignal) {
+        parentAbortSignal.addEventListener("abort", cleanup, { once: true });
+    }
     try {
         // Get the parent's logs directory to pass to the subagent
         const parentLogsDir = process.env.TOWN_LOGS_DIR || path.join(process.cwd(), ".logs");
@@ -317,6 +342,8 @@ async function querySubagent(agentName, agentPath, agentWorkingDirectory, query)
         // Step 3: Connect to SSE for receiving streaming responses
         sseAbortController = new AbortController();
         let responseText = "";
+        // Track citation sources from subagent's web searches/fetches
+        const collectedSources = [];
         // Track full message structure for session storage
         const currentMessage = {
             id: `subagent-${Date.now()}`,
@@ -411,6 +438,26 @@ async function querySubagent(agentName, agentPath, agentWorkingDirectory, query)
                                         }
                                     }
                                 }
+                                // Handle sources - collect citation sources from subagent's web searches
+                                if (update.sessionUpdate === "sources" &&
+                                    Array.isArray(update.sources)) {
+                                    for (const source of update.sources) {
+                                        const citationSource = {
+                                            id: source.id,
+                                            url: source.url,
+                                            title: source.title,
+                                            toolCallId: source.toolCallId,
+                                        };
+                                        if (source.snippet)
+                                            citationSource.snippet = source.snippet;
+                                        if (source.favicon)
+                                            citationSource.favicon = source.favicon;
+                                        if (source.sourceName)
+                                            citationSource.sourceName = source.sourceName;
+                                        collectedSources.push(citationSource);
+                                    }
+                                    logger.info(`Collected ${update.sources.length} sources from subagent`);
+                                }
                             }
                             catch {
                                 // Ignore malformed SSE data
@@ -457,8 +504,26 @@ async function querySubagent(agentName, agentPath, agentWorkingDirectory, query)
                 reject(new Error(`Subagent query timed out after ${timeoutMs / 1000} seconds`));
             }, timeoutMs);
         });
-        // Wait for prompt to complete with timeout
-        await Promise.race([promptPromise, timeoutPromise, processErrorPromise]);
+        // Create cancellation promise that rejects when parent aborts
+        const cancellationPromise = parentAbortSignal
+            ? new Promise((_, reject) => {
+                if (parentAbortSignal.aborted) {
+                    reject(new Error("Subagent query cancelled"));
+                }
+                parentAbortSignal.addEventListener("abort", () => reject(new Error("Subagent query cancelled")), { once: true });
+            })
+            : new Promise(() => { }); // Never resolves if no signal
+        // Wait for prompt to complete with timeout or cancellation
+        await Promise.race([
+            promptPromise,
+            timeoutPromise,
+            processErrorPromise,
+            cancellationPromise,
+        ]);
+        // Check if cancelled before processing results
+        if (parentAbortSignal?.aborted) {
+            throw new Error("Subagent query cancelled");
+        }
         // Give SSE a moment to flush remaining messages
         await new Promise((r) => setTimeout(r, 100));
         // Abort SSE connection
@@ -472,9 +537,16 @@ async function querySubagent(agentName, agentPath, agentWorkingDirectory, query)
         if (currentMessage.content || currentMessage.toolCalls.length > 0) {
             emitSubagentMessages(queryHash, [currentMessage]);
         }
-        return responseText;
+        return {
+            text: responseText,
+            sources: collectedSources,
+        };
     }
     finally {
+        // Remove the abort listener to prevent memory leaks
+        if (parentAbortSignal) {
+            parentAbortSignal.removeEventListener("abort", cleanup);
+        }
         // Cleanup: abort SSE and kill process
         logger.info(`Shutting down subagent on port ${port}`);
         if (sseAbortController) {

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

@@ -1,4 +1,8 @@
 import { z } from "zod";
+/** Reset the web search citation counter (call at start of each session) */
+export declare function resetWebSearchCitationCounter(): void;
+/** Get the current citation counter value */
+export declare function getWebSearchCitationCounter(): number;
 /** Create web search tools using direct EXA_API_KEY */
 export declare function makeWebSearchTools(): readonly [import("langchain").DynamicStructuredTool<z.ZodObject<{
     query: z.ZodString;
@@ -6,13 +10,22 @@ export declare function makeWebSearchTools(): readonly [import("langchain").Dyna
     query: string;
 }, {
     query: string;
-}, string | import("exa-js").SearchResponse<{
-    numResults: number;
-    type: "auto";
-    text: {
-        maxCharacters: number;
-    };
-}>>, import("langchain").DynamicStructuredTool<z.ZodObject<{
+}, string | {
+    results: import("exa-js").SearchResult<{
+        numResults: number;
+        type: "auto";
+        text: {
+            maxCharacters: number;
+        };
+    }>[];
+    formattedForCitation: {
+        citationId: number;
+        url: string;
+        title: string | null;
+        text: string;
+        citationInstruction: string;
+    }[];
+}>, import("langchain").DynamicStructuredTool<z.ZodObject<{
     url: z.ZodString;
     prompt: z.ZodString;
 }, z.core.$strip>, {
@@ -29,13 +42,22 @@ export declare function makeTownWebSearchTools(): readonly [import("langchain").
     query: string;
 }, {
     query: string;
-}, string | import("exa-js").SearchResponse<{
-    numResults: number;
-    type: "auto";
-    text: {
-        maxCharacters: number;
-    };
-}>>, import("langchain").DynamicStructuredTool<z.ZodObject<{
+}, string | {
+    results: import("exa-js").SearchResult<{
+        numResults: number;
+        type: "auto";
+        text: {
+            maxCharacters: number;
+        };
+    }>[];
+    formattedForCitation: {
+        citationId: number;
+        url: string;
+        title: string | null;
+        text: string;
+        citationInstruction: string;
+    }[];
+}>, import("langchain").DynamicStructuredTool<z.ZodObject<{
     url: z.ZodString;
     prompt: z.ZodString;
 }, z.core.$strip>, {

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

@@ -30,6 +30,17 @@ function getTownExaClient() {
     _townExaClient = new Exa(shedAuth.accessToken, `${shedAuth.shedUrl}/api/exa`);
     return _townExaClient;
 }
+// Track citation counter for web search results
+// This is reset at the start of each session via resetWebSearchCitationCounter()
+let webSearchCitationCounter = 0;
+/** Reset the web search citation counter (call at start of each session) */
+export function resetWebSearchCitationCounter() {
+    webSearchCitationCounter = 0;
+}
+/** Get the current citation counter value */
+export function getWebSearchCitationCounter() {
+    return webSearchCitationCounter;
+}
 function makeWebSearchToolsInternal(getClient) {
     const webSearch = tool(async ({ query }) => {
         const client = getClient();
@@ -43,7 +54,25 @@ function makeWebSearchToolsInternal(getClient) {
         if (!result.results || result.results.length === 0) {
             return `No results found for query: ${query}`;
         }
-        return result;
+        // Format results with citation numbers so the LLM can reference them
+        // The adapter will extract sources using the same numbering
+        const formattedResults = result.results.map((r) => {
+            webSearchCitationCounter++;
+            return {
+                citationId: webSearchCitationCounter,
+                url: r.url,
+                title: r.title,
+                text: r.text,
+            };
+        });
+        // Return both the formatted results (for LLM) and raw results (for adapter extraction)
+        return {
+            results: result.results, // Raw results for adapter source extraction
+            formattedForCitation: formattedResults.map((r) => ({
+                ...r,
+                citationInstruction: `Use [[${r.citationId}]] when citing this source`,
+            })),
+        };
     }, {
         name: "WebSearch",
         description: "\n- Allows you to search the web and use the results to inform responses\n" +
@@ -51,11 +80,13 @@ function makeWebSearchToolsInternal(getClient) {
             "- Returns search result information formatted as search result blocks\n" +
             "- Use this tool for accessing information beyond your knowledge cutoff\n" +
             "- Searches are performed automatically within a single API call\n" +
+            "- Results include citation IDs - use [[N]] format to cite sources in your response\n" +
             "\n" +
             "Usage notes:\n" +
             "  - Domain filtering is supported to include or block specific websites\n" +
             "  - Web search is only available in the US\n" +
-            '  - Account for "Today\'s date" in <env>. For example, if <env> says "Today\'s date: 2025-07-01", and the user wants the latest docs, do not use 2024 in the search query. Use 2025.\n',
+            '  - Account for "Today\'s date" in <env>. For example, if <env> says "Today\'s date: 2025-07-01", and the user wants the latest docs, do not use 2024 in the search query. Use 2025.\n' +
+            "  - IMPORTANT: When using information from search results, cite the source using [[N]] format where N is the citationId\n",
         schema: z.object({
             query: z.string().describe("The search query to use"),
         }),

package/dist/runner/session-context.d.ts

@@ -10,6 +10,26 @@ export interface SessionContext {
     /** Artifacts directory: <agentDir>/.sessions/<sessionId>/artifacts */
     artifactsDir: string;
 }
+/**
+ * Run a function with an abort signal available via AsyncLocalStorage.
+ * Tools can access the signal using getAbortSignal().
+ */
+export declare function runWithAbortSignal<T>(signal: AbortSignal, fn: () => T): T;
+/**
+ * Bind an async generator to an abort signal context so that every iteration
+ * runs with the abort signal available.
+ */
+export declare function bindGeneratorToAbortSignal<T, R, N = unknown>(signal: AbortSignal, generator: AsyncGenerator<T, R, N>): AsyncGenerator<T, R, N>;
+/**
+ * Get the current abort signal.
+ * Returns undefined if called outside of an abort signal context.
+ */
+export declare function getAbortSignal(): AbortSignal | undefined;
+/**
+ * Check if the current operation has been aborted.
+ * Returns false if no abort signal is available.
+ */
+export declare function isAborted(): boolean;
 /**
  * Run a function with session context available via AsyncLocalStorage.
  * Tools can access the context using getSessionContext().