@townco/agent 0.1.81 → 0.1.83

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

@@ -5,32 +5,7 @@ import * as path from "node:path";
 import { SandboxManager, } from "@anthropic-ai/sandbox-runtime";
 import { tool } from "langchain";
 import { z } from "zod";
-/**
- * Lazily initialize Sandbox Runtime with write access limited to workingDirectory.
- * Read access defaults to Sandbox Runtime's defaults (read allowed everywhere),
- * but commands run with cwd=workingDirectory, so rg/reads are scoped naturally.
- */
-let initialized = false;
-async function ensureSandbox(workingDirectory) {
-    if (initialized)
-        return;
-    const cfg = {
-        network: {
-            // No outbound network needed for Grep/Read/Write; block by default.
-            allowedDomains: [],
-            deniedDomains: [],
-        },
-        filesystem: {
-            // Allow writes only within the configured sandbox directory.
-            allowWrite: [workingDirectory],
-            denyWrite: [],
-            // Optional: harden reads a bit (deny common sensitive dirs)
-            denyRead: ["~/.ssh", "~/.gnupg", "/etc/ssh"],
-        },
-    };
-    await SandboxManager.initialize(cfg);
-    initialized = true;
-}
+import { getSessionContext, getToolOutputDir, hasSessionContext, } from "../../session-context";
 /** Small shell-escape for args that we pass via `shell: true`. */
 function shEscape(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
@@ -50,38 +25,65 @@ async function runSandboxed(cmd, cwd) {
         code: code ?? 1,
     };
 }
+/**
+ * Lazily initialize Sandbox Runtime with write access limited to session directory.
+ * Sandbox is initialized per-session based on the current session context.
+ */
+const initializedSessions = new Set();
+async function ensureSandbox(sessionDir) {
+    if (initializedSessions.has(sessionDir))
+        return;
+    const cfg = {
+        network: {
+            // No outbound network needed for Grep/Read/Write; block by default.
+            allowedDomains: [],
+            deniedDomains: [],
+        },
+        filesystem: {
+            // Allow writes only within the session directory.
+            allowWrite: [sessionDir],
+            denyWrite: [],
+            // Deny common sensitive dirs for reads
+            denyRead: ["~/.ssh", "~/.gnupg", "/etc/ssh"],
+        },
+    };
+    await SandboxManager.initialize(cfg);
+    initializedSessions.add(sessionDir);
+}
 /** Check that ripgrep is available inside the sandbox. Throw with a helpful note if not. */
-async function assertRipgrep(workingDirectory) {
-    const { code } = await runSandboxed("rg --version", workingDirectory);
+async function assertRipgrep(sessionDir) {
+    const { code } = await runSandboxed("rg --version", sessionDir);
     if (code !== 0) {
         throw new Error("ripgrep (rg) is required for the Grep tool. Please install it (e.g., `brew install ripgrep` on macOS or your distro package on Linux).");
     }
 }
-/** Validate that a path is absolute */
-function assertAbsolutePath(filePath, paramName) {
-    if (!path.isAbsolute(filePath)) {
-        throw new Error(`${paramName} must be an absolute path, got: ${filePath}`);
-    }
-}
-/** Validate that a path is within the working directory bounds */
-function assertWithinWorkingDirectory(filePath, workingDirectory) {
-    const resolved = path.resolve(filePath);
-    const normalizedWd = path.resolve(workingDirectory);
-    if (!resolved.startsWith(normalizedWd + path.sep) &&
-        resolved !== normalizedWd) {
-        throw new Error(`Path ${filePath} is outside the allowed working directory ${workingDirectory}`);
-    }
-}
-export function makeFilesystemTools(workingDirectory) {
-    const resolvedWd = path.resolve(workingDirectory);
+/**
+ * Create filesystem tools that are scoped to the current session.
+ * Tools use session context (via AsyncLocalStorage) to determine the session directory.
+ */
+export function makeFilesystemTools() {
     const grep = tool(async ({ pattern, path: searchPath, glob, output_mode, "-B": before, "-A": after, "-C": context, "-n": lineNumbers, "-i": ignoreCase, type: fileType, head_limit, multiline, }) => {
-        await ensureSandbox(resolvedWd);
-        await assertRipgrep(resolvedWd);
-        let target = resolvedWd;
+        if (!hasSessionContext()) {
+            throw new Error("Grep tool requires session context. Ensure the tool is called within a session.");
+        }
+        const { sessionDir, artifactsDir } = getSessionContext();
+        await ensureSandbox(sessionDir);
+        await assertRipgrep(sessionDir);
+        // Default to searching artifacts dir (where Write tool saves files)
+        let target = artifactsDir;
         if (searchPath) {
-            assertAbsolutePath(searchPath, "path");
-            assertWithinWorkingDirectory(searchPath, resolvedWd);
-            target = path.resolve(searchPath);
+            // searchPath can be relative to artifacts dir or absolute (but must be within artifacts)
+            const resolvedPath = path.isAbsolute(searchPath)
+                ? searchPath
+                : path.join(artifactsDir, searchPath);
+            // Restrict access to only within artifactsDir
+            const normalizedPath = path.resolve(resolvedPath);
+            const normalizedArtifactsDir = path.resolve(artifactsDir);
+            if (!normalizedPath.startsWith(normalizedArtifactsDir + path.sep) &&
+                normalizedPath !== normalizedArtifactsDir) {
+                throw new Error(`Path ${searchPath} is outside the allowed artifacts directory`);
+            }
+            target = resolvedPath;
         }
         // Build rg command
         const parts = ["rg"];
@@ -124,7 +126,7 @@ export function makeFilesystemTools(workingDirectory) {
         if (head_limit !== undefined) {
             cmd = `${cmd} | head -n ${head_limit}`;
         }
-        const { stdout, stderr, code } = await runSandboxed(cmd, resolvedWd);
+        const { stdout, stderr, code } = await runSandboxed(cmd, sessionDir);
         // rg returns non-zero on "no matches" — treat as empty results
         if (code !== 0 && stdout.length === 0) {
             const err = stderr.toString("utf8");
@@ -137,7 +139,7 @@ export function makeFilesystemTools(workingDirectory) {
         return stdout.toString("utf8");
     }, {
         name: "Grep",
-        description: 'A powerful search tool built on ripgrep\n\n  Usage:\n  - ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.\n  - Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")\n  - Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")\n  - Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts\n  - Use Task tool for open-ended searches requiring multiple rounds\n  - Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\\{\\}` to find `interface{}` in Go code)\n  - Multiline matching: By default patterns match within single lines only. For cross-line patterns like `struct \\{[\\s\\S]*?field`, use `multiline: true`\n',
+        description: 'A powerful search tool built on ripgrep, scoped to the current session directory.\n\n  Usage:\n  - ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command.\n  - Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")\n  - Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")\n  - Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts\n  - Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping\n  - Multiline matching: By default patterns match within single lines only. For cross-line patterns, use `multiline: true`\n',
         schema: z.object({
             pattern: z
                 .string()
@@ -145,7 +147,7 @@ export function makeFilesystemTools(workingDirectory) {
             path: z
                 .string()
                 .optional()
-                .describe("File or directory to search in (rg PATH). Defaults to current working directory."),
+                .describe("File or directory to search in (relative to session directory or absolute within session). Defaults to session directory."),
             glob: z
                 .string()
                 .optional()
@@ -153,23 +155,23 @@ export function makeFilesystemTools(workingDirectory) {
             output_mode: z
                 .enum(["content", "files_with_matches", "count"])
                 .optional()
-                .describe('Output mode: "content" shows matching lines (supports -A/-B/-C context, -n line numbers, head_limit), "files_with_matches" shows file paths (supports head_limit), "count" shows match counts (supports head_limit). Defaults to "files_with_matches".'),
+                .describe('Output mode: "content" shows matching lines, "files_with_matches" shows file paths (default), "count" shows match counts.'),
             "-B": z
                 .number()
                 .optional()
-                .describe('Number of lines to show before each match (rg -B). Requires output_mode: "content", ignored otherwise.'),
+                .describe('Number of lines to show before each match (rg -B). Requires output_mode: "content".'),
             "-A": z
                 .number()
                 .optional()
-                .describe('Number of lines to show after each match (rg -A). Requires output_mode: "content", ignored otherwise.'),
+                .describe('Number of lines to show after each match (rg -A). Requires output_mode: "content".'),
             "-C": z
                 .number()
                 .optional()
-                .describe('Number of lines to show before and after each match (rg -C). Requires output_mode: "content", ignored otherwise.'),
+                .describe('Number of lines to show before and after each match (rg -C). Requires output_mode: "content".'),
             "-n": z
                 .boolean()
                 .optional()
-                .describe('Show line numbers in output (rg -n). Requires output_mode: "content", ignored otherwise.'),
+                .describe('Show line numbers in output (rg -n). Requires output_mode: "content".'),
             "-i": z
                 .boolean()
                 .optional()
@@ -177,32 +179,49 @@ export function makeFilesystemTools(workingDirectory) {
             type: z
                 .string()
                 .optional()
-                .describe("File type to search (rg --type). Common types: js, py, rust, go, java, etc. More efficient than include for standard file types."),
+                .describe("File type to search (rg --type). Common types: js, py, rust, go, java, etc."),
             head_limit: z
                 .number()
                 .optional()
-                .describe('Limit output to first N lines/entries, equivalent to "| head -N". Works across all output modes: content (limits output lines), files_with_matches (limits file paths), count (limits count entries). When unspecified, shows all results from ripgrep.'),
+                .describe('Limit output to first N lines/entries, equivalent to "| head -N".'),
             multiline: z
                 .boolean()
                 .optional()
                 .describe("Enable multiline mode where . matches newlines and patterns can span lines (rg -U --multiline-dotall). Default: false."),
         }),
     });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     grep.prettyName = "Codebase Search";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     grep.icon = "Search";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     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");
-        assertWithinWorkingDirectory(file_path, resolvedWd);
-        const target = path.resolve(file_path);
+        if (!hasSessionContext()) {
+            throw new Error("Read tool requires session context. Ensure the tool is called within a session.");
+        }
+        const { sessionDir, artifactsDir } = getSessionContext();
+        await ensureSandbox(sessionDir);
+        // Resolve file path relative to artifacts dir (where Write tool saves files)
+        // All relative paths are resolved from artifactsDir
+        // Absolute paths must also be within artifactsDir for security
+        const resolvedPath = path.isAbsolute(file_path)
+            ? file_path
+            : path.join(artifactsDir, file_path);
+        // Restrict access to only within artifactsDir (not full sessionDir)
+        const normalizedPath = path.resolve(resolvedPath);
+        const normalizedArtifactsDir = path.resolve(artifactsDir);
+        if (!normalizedPath.startsWith(normalizedArtifactsDir + path.sep) &&
+            normalizedPath !== normalizedArtifactsDir) {
+            throw new Error(`Path ${file_path} is outside the allowed artifacts directory`);
+        }
         // Read the file using sandboxed cat
-        const cmd = `cat ${shEscape(target)}`;
-        const { stdout, stderr, code } = await runSandboxed(cmd, resolvedWd);
+        const cmd = `cat ${shEscape(resolvedPath)}`;
+        const { stdout, stderr, code } = await runSandboxed(cmd, sessionDir);
         if (code !== 0) {
             throw new Error(`Read failed for ${file_path}:\n${stderr.toString("utf8") || "Unknown error"}`);
         }
@@ -224,9 +243,11 @@ export function makeFilesystemTools(workingDirectory) {
         return formatted;
     }, {
         name: "Read",
-        description: "Reads a file from the local filesystem. You can access any file directly by using this tool.\nAssume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.\n\nUsage:\n- The file_path parameter must be an absolute path, not a relative path\n- By default, it reads up to 2000 lines starting from the beginning of the file\n- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters\n- Any lines longer than 2000 characters will be truncated\n- Results are returned using cat -n format, with line numbers starting at 1\n- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.\n- This tool can read PDF files (.pdf). PDFs are processed page by page, extracting both text and visual content for analysis.\n- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.\n- This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.\n- You can call multiple tools in a single response. It is always better to speculatively read multiple potentially useful files in parallel.\n- You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.\n- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.",
+        description: "Reads a file from the session directory.\n\nUsage:\n- The file_path can be relative to the session directory or an absolute path within the session\n- By default, it reads up to 2000 lines starting from the beginning of the file\n- You can optionally specify a line offset and limit (especially handy for long files)\n- Any lines longer than 2000 characters will be truncated\n- Results are returned with line numbers",
         schema: z.object({
-            file_path: z.string().describe("The absolute path to the file to read"),
+            file_path: z
+                .string()
+                .describe("The path to the file to read (relative to session directory or absolute within session)"),
             offset: z
                 .number()
                 .optional()
@@ -237,42 +258,57 @@ export function makeFilesystemTools(workingDirectory) {
                 .describe("The number of lines to read. Only provide if the file is too large to read at once."),
         }),
     });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     read.prettyName = "Read File";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     read.icon = "FileText";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     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");
-        assertWithinWorkingDirectory(file_path, resolvedWd);
-        const target = path.resolve(file_path);
+        if (!hasSessionContext()) {
+            throw new Error("Write tool requires session context. Ensure the tool is called within a session.");
+        }
+        const { sessionDir } = getSessionContext();
+        const toolOutputDir = getToolOutputDir("Write");
+        await ensureSandbox(sessionDir);
+        // Ensure tool output directory exists
+        await fs.mkdir(toolOutputDir, { recursive: true });
+        // Resolve file path - Write always writes to tool-Write/ subdirectory
+        // If absolute path given, extract just the filename
+        const fileName = path.isAbsolute(file_path)
+            ? path.basename(file_path)
+            : file_path;
+        const target = path.join(toolOutputDir, fileName);
         const dir = path.dirname(target);
-        // Make sure parent exists (in *parent* process, just for convenience of here-doc).
-        // This does not write file contents; the write itself happens inside the sandbox.
+        // Make sure parent exists
         await fs.mkdir(dir, { recursive: true });
-        // Safe here-doc to avoid shell interpolation
-        const cmd = `bash -c 'mkdir -p ${shEscape(dir)} && cat > ${shEscape(target)} <<'EOF'\n` +
-            `${content}\nEOF\n'`;
-        const { stderr, code } = await runSandboxed(cmd, resolvedWd);
+        // Use base64 encoding to safely pass content through shell without escaping issues
+        const base64Content = Buffer.from(content, "utf8").toString("base64");
+        const cmd = `mkdir -p ${shEscape(dir)} && echo ${shEscape(base64Content)} | base64 -d > ${shEscape(target)}`;
+        const { stderr, code } = await runSandboxed(cmd, sessionDir);
         if (code !== 0) {
             throw new Error(`Write failed for ${file_path}:\n${stderr.toString("utf8") || "Unknown error"}`);
         }
-        return `Successfully wrote ${Buffer.byteLength(content, "utf8")} bytes to ${file_path}`;
+        return `Successfully wrote ${Buffer.byteLength(content, "utf8")} bytes to ${target}`;
     }, {
         name: "Write",
-        description: "Writes a file to the local filesystem.\n\nUsage:\n- This tool will overwrite the existing file if there is one at the provided path.\n- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.\n- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\n- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.",
+        description: "Writes a file to the session's tool-Write/ directory.\n\nUsage:\n- Files are written to the session-scoped tool-Write/ directory\n- Provide a filename (or relative path) - the file will be created in the session's output directory\n- This tool will overwrite any existing file with the same name\n- The full path where the file was written will be returned",
         schema: z.object({
             file_path: z
                 .string()
-                .describe("The absolute path to the file to write (must be absolute, not relative)"),
+                .describe("The filename or relative path for the file to write (will be placed in session's tool-Write/ directory)"),
             content: z.string().describe("The content to write to the file"),
         }),
     });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     write.prettyName = "Write File";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     write.icon = "Edit";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     write.verbiage = {
         active: "Writing {file}",
         past: "Wrote {file}",

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

@@ -8,6 +8,7 @@ interface GenerateImageResult {
     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<{
@@ -25,4 +26,22 @@ export declare function makeGenerateImageTool(): import("langchain").DynamicStru
     prompt: string;
     aspectRatio?: "1:1" | "3:4" | "4:3" | "9:16" | "16:9" | "5:4" | 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<{
+        "1:1": "1:1";
+        "3:4": "3:4";
+        "4:3": "4:3";
+        "9:16": "9:16";
+        "16:9": "16:9";
+        "5:4": "5:4";
+    }>>>;
+}, z.core.$strip>, {
+    prompt: string;
+    aspectRatio: "1:1" | "3:4" | "4:3" | "9:16" | "16:9" | "5:4";
+}, {
+    prompt: string;
+    aspectRatio?: "1:1" | "3:4" | "4:3" | "9:16" | "16:9" | "5:4" | undefined;
+}, GenerateImageResult>;
 export {};

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

@@ -1,25 +1,53 @@
 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";
-let _genaiClient = null;
-function getGenAIClient() {
-    if (_genaiClient) {
-        return _genaiClient;
+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.");
     }
-    _genaiClient = new GoogleGenAI({ apiKey });
-    return _genaiClient;
+    _directGenaiClient = new GoogleGenAI({ apiKey });
+    return _directGenaiClient;
 }
-export function makeGenerateImageTool() {
+/** 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 {
-            const client = getGenAIClient();
+            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
@@ -73,21 +101,23 @@ export function makeGenerateImageTool() {
                     ...(textResponse ? { textResponse } : {}),
                 };
             }
-            // Save image to disk in generated-images directory (relative to cwd)
-            const outputDir = join(process.cwd(), "generated-images");
-            await mkdir(outputDir, { recursive: true });
+            // 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(outputDir, fileName);
+            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 imageUrl = `http://localhost:${port}/static/generated-images/${fileName}`;
+            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,
@@ -116,7 +146,7 @@ export function makeGenerateImageTool() {
             "\n" +
             "Usage notes:\n" +
             "  - Provide detailed, specific prompts for best results\n" +
-            "  - The generated image is saved and served via URL\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
@@ -129,7 +159,17 @@ export function makeGenerateImageTool() {
                 .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/subagent.js

@@ -35,7 +35,7 @@ async function waitForServerReady(port, timeoutMs = 30000) {
         catch {
             // Server not ready yet
         }
-        await new Promise((r) => setTimeout(r, baseDelay * Math.pow(1.5, attempt)));
+        await new Promise((r) => setTimeout(r, baseDelay * 1.5 ** attempt));
         attempt++;
     }
     throw new Error(`Subagent server at port ${port} did not become ready within ${timeoutMs}ms`);
@@ -330,7 +330,7 @@ async function querySubagent(agentName, agentPath, agentWorkingDirectory, query)
             try {
                 const sseResponse = await fetch(`${baseUrl}/events`, {
                     headers: { "X-Session-ID": sessionId },
-                    signal: sseAbortController.signal,
+                    signal: sseAbortController?.signal,
                 });
                 if (!sseResponse.ok || !sseResponse.body) {
                     throw new Error(`SSE connection failed: HTTP ${sseResponse.status}`);

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

@@ -80,8 +80,11 @@ When in doubt, use this tool. Being proactive with task management demonstrates
         }),
     });
     // Add metadata to the tool instance
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     todoWriteTool.prettyName = "Todo List";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     todoWriteTool.icon = "CheckSquare";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     todoWriteTool.verbiage = {
         active: "Updating to-do's",
         past: "Updated to-do's",

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

@@ -60,8 +60,11 @@ function makeWebSearchToolsInternal(getClient) {
             query: z.string().describe("The search query to use"),
         }),
     });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     webSearch.prettyName = "Web Search";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     webSearch.icon = "Globe";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     webSearch.verbiage = {
         active: "Searching the web for {query}",
         past: "Searched the web for {query}",
@@ -138,8 +141,11 @@ function makeWebSearchToolsInternal(getClient) {
             prompt: z.string().describe("The prompt to run on the fetched content"),
         }),
     });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     webFetch.prettyName = "Web Fetch";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     webFetch.icon = "Link";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     webFetch.verbiage = {
         active: "Fetching {url}",
         past: "Fetched {url}",

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

@@ -0,0 +1,40 @@
+/**
+ * Session context available to tools during agent execution.
+ * This provides deterministic, session-scoped file storage.
+ */
+export interface SessionContext {
+    /** The unique session identifier */
+    sessionId: string;
+    /** Root directory for this session: <agentDir>/.sessions/<sessionId> */
+    sessionDir: string;
+    /** Artifacts directory: <agentDir>/.sessions/<sessionId>/artifacts */
+    artifactsDir: string;
+}
+/**
+ * Run a function with session context available via AsyncLocalStorage.
+ * Tools can access the context using getSessionContext().
+ */
+export declare function runWithSessionContext<T>(ctx: SessionContext, fn: () => T): T;
+/**
+ * Bind an async generator to a session context so that every iteration
+ * runs with the session context available.
+ */
+export declare function bindGeneratorToSessionContext<T, R, N = unknown>(ctx: SessionContext, generator: AsyncGenerator<T, R, N>): AsyncGenerator<T, R, N>;
+/**
+ * Get the current session context.
+ * Throws if called outside of a session context (e.g., tool called without session).
+ */
+export declare function getSessionContext(): SessionContext;
+/**
+ * Check if session context is available.
+ * Useful for tools that can operate with or without session context.
+ */
+export declare function hasSessionContext(): boolean;
+/**
+ * Get the output directory for a specific tool.
+ * Creates a deterministic path: <agentDir>/.sessions/<sessionId>/artifacts/tool-<ToolName>/
+ *
+ * @param toolName - The name of the tool (e.g., "Write", "GenerateImage")
+ * @returns Absolute path to the tool's output directory
+ */
+export declare function getToolOutputDir(toolName: string): string;

package/dist/runner/session-context.js

@@ -0,0 +1,69 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as path from "node:path";
+const sessionStorage = new AsyncLocalStorage();
+/**
+ * Run a function with session context available via AsyncLocalStorage.
+ * Tools can access the context using getSessionContext().
+ */
+export function runWithSessionContext(ctx, fn) {
+    return sessionStorage.run(ctx, fn);
+}
+/**
+ * Bind an async generator to a session context so that every iteration
+ * runs with the session context available.
+ */
+export function bindGeneratorToSessionContext(ctx, generator) {
+    const boundNext = (value) => sessionStorage.run(ctx, () => generator.next(value));
+    const boundReturn = generator.return
+        ? (value) => sessionStorage.run(ctx, () => generator.return?.(value))
+        : undefined;
+    const boundThrow = generator.throw
+        ? (e) => sessionStorage.run(ctx, () => generator.throw?.(e))
+        : undefined;
+    // Create the bound generator with all required properties
+    const boundGenerator = {
+        next: boundNext,
+        return: boundReturn,
+        throw: boundThrow,
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+        // Add Symbol.asyncDispose if supported (ES2023+)
+        [Symbol.asyncDispose]: async () => {
+            // Cleanup if needed - delegate to original generator if it has asyncDispose
+            if (Symbol.asyncDispose in generator) {
+                await generator[Symbol.asyncDispose]();
+            }
+        },
+    };
+    return boundGenerator;
+}
+/**
+ * Get the current session context.
+ * Throws if called outside of a session context (e.g., tool called without session).
+ */
+export function getSessionContext() {
+    const ctx = sessionStorage.getStore();
+    if (!ctx) {
+        throw new Error("No session context available - tool called outside of session execution");
+    }
+    return ctx;
+}
+/**
+ * Check if session context is available.
+ * Useful for tools that can operate with or without session context.
+ */
+export function hasSessionContext() {
+    return sessionStorage.getStore() !== undefined;
+}
+/**
+ * Get the output directory for a specific tool.
+ * Creates a deterministic path: <agentDir>/.sessions/<sessionId>/artifacts/tool-<ToolName>/
+ *
+ * @param toolName - The name of the tool (e.g., "Write", "GenerateImage")
+ * @returns Absolute path to the tool's output directory
+ */
+export function getToolOutputDir(toolName) {
+    const ctx = getSessionContext();
+    return path.join(ctx.artifactsDir, `tool-${toolName}`);
+}