@townco/agent 0.1.82 → 0.1.83

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

@@ -0,0 +1,469 @@
+/**
+ * Supabase Storage-backed artifacts tool for agent backend
+ *
+ * Provides file storage capabilities using Supabase Storage with the following operations:
+ * - artifacts_cp: Copy files to/from Supabase Storage
+ * - artifacts_del: Delete files from Supabase Storage
+ * - artifacts_ls: List files in Supabase Storage
+ * - artifacts_url: Generate signed URLs
+ *
+ * Storage keys are scoped by: <deploying_user>/<agent_name>/<session_id>/<file_path>
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { createSecretKeyClient } from "@townco/supabase/server";
+import { tool } from "langchain";
+import { z } from "zod";
+// ============================================================================
+// Supabase Client and Bucket Configuration
+// ============================================================================
+function getSupabaseClient() {
+    return createSecretKeyClient();
+}
+function getBucketName() {
+    return "town-builder-artifacts";
+}
+// ============================================================================
+// Storage Key Prefix Logic
+// ============================================================================
+/**
+ * Generates the storage key prefix based on environment and configuration.
+ *
+ * Priority order:
+ * 1. Explicit ARTIFACTS_KEY_PREFIX env var (highest priority)
+ * 2. Parse username from AGENT_NAME (deployment mode: "username-agentname")
+ * 3. Local mode fallback: "local/agentname" or "local/unknown"
+ *
+ * @returns Prefix string without trailing slash (e.g., "alice/my-agent" or "local/my-agent")
+ */
+function getArtifactsKeyPrefix() {
+    // 1. Explicit override (highest priority)
+    const explicitPrefix = process.env.ARTIFACTS_KEY_PREFIX;
+    if (explicitPrefix) {
+        return explicitPrefix.replace(/\/+$/, ""); // Remove trailing slashes
+    }
+    // 2. Check deployment vs local mode
+    const agentName = process.env.AGENT_NAME;
+    if (!agentName) {
+        return "local/unknown";
+    }
+    // 3. Parse username from AGENT_NAME (format: "username-agentname")
+    // In deployment, AGENT_NAME follows pattern "username-agentname"
+    const parts = agentName.split("-");
+    if (parts.length >= 2) {
+        const username = parts[0];
+        const agentNamePart = parts.slice(1).join("-");
+        return `${username}/${agentNamePart}`;
+    }
+    // Local mode fallback
+    return `local/${agentName}`;
+}
+/**
+ * Builds the full storage key for a file.
+ *
+ * @param sessionId Current session ID
+ * @param filePath Relative file path within the session
+ * @returns Full storage key (e.g., "alice/my-agent/sess-123/data/output.json")
+ */
+function buildStorageKey(sessionId, filePath) {
+    // Validate session ID is provided
+    if (!sessionId || sessionId.trim() === "") {
+        throw new Error("FATAL: session_id is required but was not provided. " +
+            "This is a system error - session_id should be automatically injected. " +
+            "Please report this bug.");
+    }
+    const prefix = getArtifactsKeyPrefix();
+    // Normalize file path (remove leading slashes)
+    const normalizedPath = filePath.replace(/^\/+/, "");
+    return `${prefix}/${sessionId}/${normalizedPath}`;
+}
+// ============================================================================
+// Path Validation
+// ============================================================================
+function validateLocalPath(path) {
+    if (!path.startsWith("/")) {
+        throw new Error(`Local paths must be absolute. Got: ${path}\n` +
+            "Hint: Use an absolute path starting with '/'");
+    }
+}
+function validateStoragePath(path) {
+    if (path.startsWith("/")) {
+        throw new Error(`Storage paths must be relative (no leading slash). Got: ${path}\n` +
+            "Hint: Use a relative path like 'data/file.json'");
+    }
+    if (path.includes("..")) {
+        throw new Error(`Storage paths cannot contain '..' for security reasons. Got: ${path}`);
+    }
+    // Check for empty path
+    if (!path || path.trim() === "") {
+        throw new Error("Storage path cannot be empty");
+    }
+}
+function validateExpiration(expiresIn) {
+    // Supabase supports up to 365 days (31536000 seconds)
+    if (expiresIn < 1 || expiresIn > 31536000) {
+        throw new Error(`URL expiration must be between 1 and 31536000 seconds (365 days). Got: ${expiresIn}`);
+    }
+}
+// ============================================================================
+// Supabase Storage Operation Helpers
+// ============================================================================
+/**
+ * Upload a file to Supabase Storage
+ */
+async function uploadToSupabase(storageKey, localPath) {
+    const supabase = getSupabaseClient();
+    const bucket = getBucketName();
+    // Read file content
+    const fileContent = await fs.readFile(localPath);
+    // Determine content type based on file extension
+    const ext = path.extname(localPath).toLowerCase();
+    const contentTypeMap = {
+        ".json": "application/json",
+        ".txt": "text/plain",
+        ".html": "text/html",
+        ".css": "text/css",
+        ".js": "application/javascript",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".svg": "image/svg+xml",
+        ".pdf": "application/pdf",
+        ".zip": "application/zip",
+    };
+    const contentType = contentTypeMap[ext] || "application/octet-stream";
+    const { error } = await supabase.storage
+        .from(bucket)
+        .upload(storageKey, fileContent, {
+        contentType,
+        upsert: true, // Allow overwriting
+    });
+    if (error) {
+        throw new Error(`Failed to upload to Supabase Storage: ${error.message}`);
+    }
+}
+/**
+ * Download a file from Supabase Storage
+ */
+async function downloadFromSupabase(storageKey, localPath) {
+    const supabase = getSupabaseClient();
+    const bucket = getBucketName();
+    const { data, error } = await supabase.storage
+        .from(bucket)
+        .download(storageKey);
+    if (error) {
+        throw new Error(`Failed to download from Supabase Storage: ${error.message}`);
+    }
+    if (!data) {
+        throw new Error("Supabase Storage response body is empty");
+    }
+    // Ensure parent directory exists
+    const dir = path.dirname(localPath);
+    await fs.mkdir(dir, { recursive: true });
+    // Convert Blob to Buffer and write
+    const arrayBuffer = await data.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+    await fs.writeFile(localPath, buffer);
+}
+/**
+ * Delete a file from Supabase Storage
+ */
+async function deleteFromSupabase(storageKey) {
+    const supabase = getSupabaseClient();
+    const bucket = getBucketName();
+    const { error } = await supabase.storage.from(bucket).remove([storageKey]);
+    if (error) {
+        throw new Error(`Failed to delete from Supabase Storage: ${error.message}`);
+    }
+}
+/**
+ * List files in Supabase Storage with optional prefix and recursion
+ */
+async function listFilesInSupabase(sessionId, relativePath, recursive = false) {
+    const supabase = getSupabaseClient();
+    const bucket = getBucketName();
+    // Build the prefix for listing
+    const basePath = relativePath
+        ? buildStorageKey(sessionId, relativePath)
+        : buildStorageKey(sessionId, "");
+    // For Supabase, we list at the base path
+    // If recursive, we'll need to handle it differently
+    const options = recursive
+        ? undefined
+        : {
+            limit: 100,
+            offset: 0,
+            sortBy: { column: "name", order: "asc" },
+        };
+    const { data, error } = await supabase.storage
+        .from(bucket)
+        .list(basePath, options);
+    if (error) {
+        throw new Error(`Failed to list files in Supabase Storage: ${error.message}`);
+    }
+    return data || [];
+}
+/**
+ * Generate a signed URL for a Supabase Storage object
+ */
+async function generateSignedUrl(storageKey, expiresIn) {
+    const supabase = getSupabaseClient();
+    const bucket = getBucketName();
+    const { data, error } = await supabase.storage
+        .from(bucket)
+        .createSignedUrl(storageKey, expiresIn);
+    if (error) {
+        throw new Error(`Failed to generate signed URL: ${error.message}`);
+    }
+    if (!data?.signedUrl) {
+        throw new Error("Signed URL not returned from Supabase Storage");
+    }
+    return data.signedUrl;
+}
+// ============================================================================
+// Error Handling Helpers
+// ============================================================================
+/**
+ * Maps Supabase Storage errors to user-friendly error messages
+ */
+function handleStorageError(error, context) {
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        if (message.includes("object not found") || message.includes("not found")) {
+            return `Error: File not found in storage. ${context}`;
+        }
+        if (message.includes("bucket not found")) {
+            return `Error: Artifacts bucket not configured. Please create the 'artifacts' bucket in Supabase. ${context}`;
+        }
+        if (message.includes("invalid jwt") || message.includes("jwt")) {
+            return `Error: Authentication error. Please check Supabase credentials. ${context}`;
+        }
+        if (message.includes("enoent")) {
+            return `Error: Local file not found. ${context}\n${error.message}`;
+        }
+        if (message.includes("eacces")) {
+            return `Error: Permission denied accessing local file. ${context}\n${error.message}`;
+        }
+        return `Error: ${error.message}. ${context}`;
+    }
+    return `Error: Unknown error occurred. ${context}`;
+}
+// ============================================================================
+// Tool Implementations
+// ============================================================================
+/**
+ * Tool 1: artifacts_cp - Copy files to/from Supabase Storage
+ */
+const artifactsCp = tool(async ({ session_id, source, destination, direction, }) => {
+    try {
+        if (direction === "upload") {
+            // Upload: local file -> Storage
+            validateLocalPath(source);
+            validateStoragePath(destination);
+            const storageKey = buildStorageKey(session_id, destination);
+            await uploadToSupabase(storageKey, source);
+            return `Successfully uploaded ${source} to storage at ${destination}`;
+        }
+        else {
+            // Download: Storage -> local file
+            validateStoragePath(source);
+            validateLocalPath(destination);
+            const storageKey = buildStorageKey(session_id, source);
+            await downloadFromSupabase(storageKey, destination);
+            return `Successfully downloaded ${source} from storage to ${destination}`;
+        }
+    }
+    catch (error) {
+        return handleStorageError(error, direction === "upload"
+            ? `Failed to upload ${source} to ${destination}`
+            : `Failed to download ${source} to ${destination}`);
+    }
+}, {
+    name: "artifacts_cp",
+    description: "Copy files between local filesystem and Supabase Storage-backed artifact storage. " +
+        "Use direction='upload' to copy from local to storage, or direction='download' to copy from storage to local. " +
+        "Local paths must be absolute (e.g., '/tmp/file.txt'), storage paths must be relative (e.g., 'data/file.txt').",
+    schema: z.object({
+        session_id: z
+            .string()
+            .optional()
+            .describe("INTERNAL USE ONLY - Auto-injected by system"),
+        source: z
+            .string()
+            .describe("Source path: absolute path if local, relative path if storage"),
+        destination: z
+            .string()
+            .describe("Destination path: absolute path if local, relative path if storage"),
+        direction: z
+            .enum(["upload", "download"])
+            .describe("Direction: 'upload' (local to storage) or 'download' (storage to local)"),
+    }),
+});
+/**
+ * Tool 2: artifacts_del - Delete files from Supabase Storage
+ */
+const artifactsDel = tool(async ({ session_id, path, }) => {
+    try {
+        validateStoragePath(path);
+        const storageKey = buildStorageKey(session_id, path);
+        await deleteFromSupabase(storageKey);
+        return `Successfully deleted ${path} from storage`;
+    }
+    catch (error) {
+        return handleStorageError(error, `Failed to delete ${path}`);
+    }
+}, {
+    name: "artifacts_del",
+    description: "Delete a file from Supabase Storage-backed artifact storage. " +
+        "The path must be relative (e.g., 'data/file.txt').",
+    schema: z.object({
+        session_id: z
+            .string()
+            .optional()
+            .describe("INTERNAL USE ONLY - Auto-injected by system"),
+        path: z
+            .string()
+            .describe("Relative path to the file to delete in storage"),
+    }),
+});
+/**
+ * Tool 3: artifacts_ls - List files in Supabase Storage
+ */
+const artifactsLs = tool(async ({ session_id, path, recursive = false, }) => {
+    try {
+        if (path) {
+            validateStoragePath(path);
+        }
+        const files = await listFilesInSupabase(session_id, path, recursive);
+        if (files.length === 0) {
+            return path
+                ? `No files found in ${path}`
+                : "No files found in this session";
+        }
+        // Format the file list
+        const fileList = files
+            .map((file) => {
+            const size = file.metadata?.size || 0;
+            const lastModified = file.updated_at || file.created_at || "unknown";
+            // Format size in human-readable format
+            let sizeStr;
+            if (size < 1024) {
+                sizeStr = `${size} B`;
+            }
+            else if (size < 1024 * 1024) {
+                sizeStr = `${(size / 1024).toFixed(2)} KB`;
+            }
+            else if (size < 1024 * 1024 * 1024) {
+                sizeStr = `${(size / (1024 * 1024)).toFixed(2)} MB`;
+            }
+            else {
+                sizeStr = `${(size / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+            }
+            return `${file.name}\t${sizeStr}\t${lastModified}`;
+        })
+            .join("\n");
+        const header = path
+            ? `Files in ${path} (${files.length} total):\n`
+            : `Files in session (${files.length} total):\n`;
+        return `${header}Name\tSize\tLast Modified\n${fileList}`;
+    }
+    catch (error) {
+        return handleStorageError(error, `Failed to list files${path ? ` in ${path}` : ""}`);
+    }
+}, {
+    name: "artifacts_ls",
+    description: "List files in Supabase Storage-backed artifact storage for the current session. " +
+        "Optionally specify a relative directory path to list. " +
+        "Use recursive=true to list files recursively in subdirectories.",
+    schema: z.object({
+        session_id: z
+            .string()
+            .optional()
+            .describe("INTERNAL USE ONLY - Auto-injected by system"),
+        path: z
+            .string()
+            .optional()
+            .describe("Optional relative directory path to list (e.g., 'data/'). If omitted, lists session root."),
+        recursive: z
+            .boolean()
+            .optional()
+            .describe("Whether to list files recursively in subdirectories (default: false)"),
+    }),
+});
+/**
+ * Tool 4: artifacts_url - Generate signed URL
+ */
+const artifactsUrl = tool(async ({ session_id, path, expires_in = 3600, }) => {
+    try {
+        validateStoragePath(path);
+        validateExpiration(expires_in);
+        const storageKey = buildStorageKey(session_id, path);
+        const url = await generateSignedUrl(storageKey, expires_in);
+        const expiryHours = expires_in / 3600;
+        const expiryStr = expiryHours >= 1
+            ? `${expiryHours.toFixed(1)} hour(s)`
+            : `${expires_in} second(s)`;
+        return `Signed URL for ${path} (expires in ${expiryStr}):\n${url}`;
+    }
+    catch (error) {
+        return handleStorageError(error, `Failed to generate URL for ${path}`);
+    }
+}, {
+    name: "artifacts_url",
+    description: "Generate a signed URL for accessing an artifact in Supabase Storage. " +
+        "The URL will be valid for the specified duration (default: 1 hour, max: 365 days). " +
+        "Anyone with this URL can access the file until it expires.",
+    schema: z.object({
+        session_id: z
+            .string()
+            .optional()
+            .describe("INTERNAL USE ONLY - Auto-injected by system"),
+        path: z.string().describe("Relative path to the artifact in storage"),
+        expires_in: z
+            .number()
+            .optional()
+            .describe("Expiration time in seconds (1-31536000). Default: 3600 (1 hour)"),
+    }),
+});
+// ============================================================================
+// Tool Metadata
+// ============================================================================
+// Add metadata for UI display
+artifactsCp.prettyName = "Copy Artifact";
+artifactsCp.icon = "Upload";
+artifactsCp.verbiage = {
+    active: "Copying artifact to {destination}",
+    past: "Copied artifact to {destination}",
+    paramKey: "destination",
+};
+artifactsDel.prettyName = "Delete Artifact";
+artifactsDel.icon = "Trash";
+artifactsDel.verbiage = {
+    active: "Deleting artifact {path}",
+    past: "Deleted artifact {path}",
+    paramKey: "path",
+};
+artifactsLs.prettyName = "List Artifacts";
+artifactsLs.icon = "List";
+artifactsLs.verbiage = {
+    active: "Listing artifacts",
+    past: "Listed artifacts",
+};
+artifactsUrl.prettyName = "Generate Artifact URL";
+artifactsUrl.icon = "Link";
+artifactsUrl.verbiage = {
+    active: "Generating URL for {path}",
+    past: "Generated URL for {path}",
+    paramKey: "path",
+};
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Factory function to create the artifacts tools
+ * Returns an array of all four artifact management tools
+ */
+export function makeArtifactsTools() {
+    return [artifactsCp, artifactsDel, artifactsLs, artifactsUrl];
+}

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

@@ -59,9 +59,9 @@ export function makeBrowserTools() {
         try {
             const { liveViewUrl } = await ensureBrowserSession();
             const code = `
-          await page.goto('${url.replace(/'/g, "\\'")}', { 
+          await page.goto('${url.replace(/'/g, "\\'")}', {
             waitUntil: '${waitUntil}',
-            timeout: 30000 
+            timeout: 30000
           });
           return { url: page.url(), title: await page.title() };
         `;
@@ -103,7 +103,9 @@ export function makeBrowserTools() {
                 .describe("When to consider navigation complete"),
         }),
     });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     browserNavigate.prettyName = "Browser Navigate";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     browserNavigate.icon = "Globe";
     // Browser Screenshot tool
     const browserScreenshot = tool(async ({ fullPage = false, selector, }) => {
@@ -180,7 +182,9 @@ export function makeBrowserTools() {
                 .describe("CSS selector of element to screenshot (captures whole page if not provided)"),
         }),
     });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     browserScreenshot.prettyName = "Browser Screenshot";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     browserScreenshot.icon = "Camera";
     // Browser Extract Content tool
     const browserExtract = tool(async ({ selector, extractType = "text", }) => {
@@ -270,14 +274,16 @@ export function makeBrowserTools() {
                 .describe("Type of content to extract"),
         }),
     });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     browserExtract.prettyName = "Browser Extract";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     browserExtract.icon = "FileText";
     // Browser Click tool
     const browserClick = tool(async ({ selector, button = "left" }) => {
         try {
             const { liveViewUrl } = await ensureBrowserSession();
             const code = `
-          await page.click('${selector.replace(/'/g, "\\'")}', { 
+          await page.click('${selector.replace(/'/g, "\\'")}', {
             button: '${button}',
             timeout: 10000,
           });
@@ -318,7 +324,9 @@ export function makeBrowserTools() {
                 .describe("Which mouse button to use"),
         }),
     });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     browserClick.prettyName = "Browser Click";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     browserClick.icon = "MousePointer";
     // Browser Type tool
     const browserType = tool(async ({ selector, text, pressEnter = false, }) => {
@@ -364,7 +372,9 @@ export function makeBrowserTools() {
                 .describe("Whether to press Enter after typing"),
         }),
     });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     browserType.prettyName = "Browser Type";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     browserType.icon = "Type";
     // Browser Close tool
     const browserClose = tool(async () => {
@@ -399,7 +409,9 @@ export function makeBrowserTools() {
             "  - Calling this when no browser is active has no effect\n",
         schema: z.object({}),
     });
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     browserClose.prettyName = "Browser Close";
+    // biome-ignore lint/suspicious/noExplicitAny: Need to add custom properties to LangChain tool
     browserClose.icon = "X";
     return [
         browserNavigate,

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

@@ -1,12 +1,16 @@
 import { z } from "zod";
-export declare function makeFilesystemTools(workingDirectory: string): readonly [import("langchain").DynamicStructuredTool<z.ZodObject<{
+/**
+ * Create filesystem tools that are scoped to the current session.
+ * Tools use session context (via AsyncLocalStorage) to determine the session directory.
+ */
+export declare function makeFilesystemTools(): readonly [import("langchain").DynamicStructuredTool<z.ZodObject<{
     pattern: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
     glob: z.ZodOptional<z.ZodString>;
     output_mode: z.ZodOptional<z.ZodEnum<{
         content: "content";
-        count: "count";
         files_with_matches: "files_with_matches";
+        count: "count";
     }>>;
     "-B": z.ZodOptional<z.ZodNumber>;
     "-A": z.ZodOptional<z.ZodNumber>;
@@ -20,7 +24,7 @@ export declare function makeFilesystemTools(workingDirectory: string): readonly
     pattern: string;
     path?: string | undefined;
     glob?: string | undefined;
-    output_mode?: "content" | "count" | "files_with_matches" | undefined;
+    output_mode?: "content" | "files_with_matches" | "count" | undefined;
     "-B"?: number | undefined;
     "-A"?: number | undefined;
     "-C"?: number | undefined;
@@ -33,7 +37,7 @@ export declare function makeFilesystemTools(workingDirectory: string): readonly
     pattern: string;
     path?: string | undefined;
     glob?: string | undefined;
-    output_mode?: "content" | "count" | "files_with_matches" | undefined;
+    output_mode?: "content" | "files_with_matches" | "count" | undefined;
     "-B"?: number | undefined;
     "-A"?: number | undefined;
     "-C"?: number | undefined;