@townco/agent 0.1.122 → 0.1.123

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

@@ -0,0 +1,474 @@
+/**
+ * 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 { createClient } from "@townco/apiclient";
+import { getShedAuth } from "@townco/core/auth";
+import { tool } from "langchain";
+import { z } from "zod";
+// ============================================================================
+// 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;
+    // Check for valid prefix (not empty, not just quotes from env parsing)
+    if (explicitPrefix &&
+        explicitPrefix !== '""' &&
+        explicitPrefix.trim() !== "") {
+        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");
+    }
+}
+// ============================================================================
+// Supabase Storage Operation Helpers
+// ============================================================================
+/**
+ * Upload a file to Supabase Storage using signed URL
+ */
+async function uploadToSupabase(storageKey, localPath) {
+    const auth = getShedAuth();
+    if (auth === null)
+        throw new Error(`agent/artifacts: could not fetch shed auth`);
+    const { shedUrl, accessToken } = auth;
+    // Get signed upload URL from server
+    const signedUrl = await createClient({
+        shedUrl,
+        accessToken,
+    }).getArtifactUrl.query({
+        kind: "user",
+        key: storageKey,
+        upload: true,
+    });
+    // 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";
+    // Upload using signed URL
+    const response = await fetch(signedUrl, {
+        method: "PUT",
+        body: fileContent,
+        headers: {
+            "Content-Type": contentType,
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to upload to Supabase Storage: ${response.status} ${response.statusText}`);
+    }
+}
+/**
+ * Download a file from Supabase Storage using signed URL
+ */
+async function downloadFromSupabase(storageKey, localPath) {
+    const auth = getShedAuth();
+    if (auth === null)
+        throw new Error(`agent/artifacts: could not fetch shed auth`);
+    const { shedUrl, accessToken } = auth;
+    // Get signed download URL from server
+    const signedUrl = await createClient({
+        shedUrl,
+        accessToken,
+    }).getArtifactUrl.query({
+        kind: "user",
+        key: storageKey,
+        upload: false,
+    });
+    // Download file using signed URL
+    const response = await fetch(signedUrl);
+    if (!response.ok) {
+        throw new Error(`Failed to download from Supabase Storage: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.arrayBuffer();
+    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 ArrayBuffer to Buffer and write
+    const buffer = Buffer.from(data);
+    await fs.writeFile(localPath, buffer);
+}
+/**
+ * Delete a file from Supabase Storage
+ */
+async function deleteFromSupabase(storageKey) {
+    const auth = getShedAuth();
+    if (auth === null)
+        throw new Error(`agent/artifacts: could not fetch shed auth`);
+    const { shedUrl, accessToken } = auth;
+    // Call the delete API endpoint
+    await createClient({ shedUrl, accessToken }).deleteArtifact.mutate({
+        kind: "user",
+        key: storageKey,
+    });
+}
+/**
+ * List files in Supabase Storage with optional prefix and recursion
+ */
+async function listFilesInSupabase(sessionId, relativePath, recursive = false) {
+    const auth = getShedAuth();
+    if (auth === null)
+        throw new Error(`agent/artifacts: could not fetch shed auth`);
+    const { shedUrl, accessToken } = auth;
+    return await createClient({ shedUrl, accessToken }).listArtifacts.query({
+        kind: "user",
+        key: buildStorageKey(sessionId, relativePath ?? ""),
+        recursive,
+    });
+}
+/**
+ * Generate a signed URL for a Supabase Storage object
+ */
+const generateSignedUrl = async (storageKey) => {
+    const shedAuth = getShedAuth();
+    if (shedAuth === null)
+        throw new Error("agent/artifacts: could not fetch shed auth");
+    const { accessToken, shedUrl } = shedAuth;
+    return await createClient({ shedUrl, accessToken }).getArtifactUrl.query({
+        kind: "user",
+        key: storageKey,
+    });
+};
+// ============================================================================
+// 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, }) => {
+    try {
+        validateStoragePath(path);
+        const storageKey = buildStorageKey(session_id, path);
+        const url = await generateSignedUrl(storageKey);
+        return `Signed URL for ${path}:\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
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic metadata assignment to tool objects
+artifactsCp.prettyName = "Copy Artifact";
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic metadata assignment to tool objects
+artifactsCp.icon = "Upload";
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic metadata assignment to tool objects
+artifactsCp.verbiage = {
+    active: "Copying artifact to {destination}",
+    past: "Copied artifact to {destination}",
+    paramKey: "destination",
+};
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic metadata assignment to tool objects
+artifactsDel.prettyName = "Delete Artifact";
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic metadata assignment to tool objects
+artifactsDel.icon = "Trash";
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic metadata assignment to tool objects
+artifactsDel.verbiage = {
+    active: "Deleting artifact {path}",
+    past: "Deleted artifact {path}",
+    paramKey: "path",
+};
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic metadata assignment to tool objects
+artifactsLs.prettyName = "List Artifacts";
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic metadata assignment to tool objects
+artifactsLs.icon = "List";
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic metadata assignment to tool objects
+artifactsLs.verbiage = {
+    active: "Listing artifacts",
+    past: "Listed artifacts",
+};
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic metadata assignment to tool objects
+artifactsUrl.prettyName = "Generate Artifact URL";
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic metadata assignment to tool objects
+artifactsUrl.icon = "Link";
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic metadata assignment to tool objects
+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/conversation_search.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export declare const CONVERSATION_SEARCH_TOOL_NAME = "conversation_search";
+/**
+ * Creates a conversation search tool that searches past agent chat sessions.
+ * @param agentDir - The directory of the current agent (e.g., agents/researcher)
+ */
+export declare function makeConversationSearchTool(agentDir: string): import("langchain").DynamicStructuredTool<z.ZodObject<{
+    query: z.ZodString;
+    date_from: z.ZodOptional<z.ZodString>;
+    date_to: z.ZodOptional<z.ZodString>;
+    max_results: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, {
+    query: string;
+    date_from?: string | undefined;
+    date_to?: string | undefined;
+    max_results?: number | undefined;
+}, {
+    query: string;
+    date_from?: string | undefined;
+    date_to?: string | undefined;
+    max_results?: number | undefined;
+}, string>;

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

@@ -0,0 +1,137 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tool } from "langchain";
+import { z } from "zod";
+export const CONVERSATION_SEARCH_TOOL_NAME = "conversation_search";
+const conversationSearchSchema = z.object({
+    query: z
+        .string()
+        .min(1)
+        .describe("The text to search for in conversation messages (case-insensitive)"),
+    date_from: z
+        .string()
+        .optional()
+        .describe("ISO date string to filter conversations from this date onwards"),
+    date_to: z
+        .string()
+        .optional()
+        .describe("ISO date string to filter conversations up to this date"),
+    max_results: z
+        .number()
+        .optional()
+        .describe("Maximum number of matching conversations to return (default: 10)"),
+});
+/**
+ * Creates a conversation search tool that searches past agent chat sessions.
+ * @param agentDir - The directory of the current agent (e.g., agents/researcher)
+ */
+export function makeConversationSearchTool(agentDir) {
+    const conversationSearch = tool(async ({ query, date_from, date_to, max_results = 10 }) => {
+        const results = [];
+        const queryLower = query.toLowerCase();
+        const dateFromParsed = date_from ? new Date(date_from) : null;
+        const dateToParsed = date_to ? new Date(date_to) : null;
+        const sessionsDir = join(agentDir, ".sessions");
+        if (!existsSync(sessionsDir)) {
+            return `No conversations found matching "${query}".`;
+        }
+        let sessionFiles;
+        try {
+            sessionFiles = readdirSync(sessionsDir).filter((f) => f.endsWith(".json") && !f.endsWith(".tmp"));
+        }
+        catch {
+            return `No conversations found matching "${query}".`;
+        }
+        for (const file of sessionFiles) {
+            if (results.length >= max_results)
+                break;
+            try {
+                const content = readFileSync(join(sessionsDir, file), "utf-8");
+                const session = JSON.parse(content);
+                // Date filtering
+                const sessionDate = new Date(session.metadata.updatedAt);
+                if (dateFromParsed && sessionDate < dateFromParsed)
+                    continue;
+                if (dateToParsed && sessionDate > dateToParsed)
+                    continue;
+                // Search messages
+                const matches = [];
+                for (let i = 0; i < session.messages.length; i++) {
+                    const msg = session.messages[i];
+                    if (!msg)
+                        continue;
+                    const textBlocks = msg.content.filter((c) => c.type === "text");
+                    for (const block of textBlocks) {
+                        if (block.text.toLowerCase().includes(queryLower)) {
+                            // Extract matched snippet with surrounding context
+                            const matchIndex = block.text.toLowerCase().indexOf(queryLower);
+                            const snippetStart = Math.max(0, matchIndex - 50);
+                            const snippetEnd = Math.min(block.text.length, matchIndex + query.length + 50);
+                            const matchedText = block.text.slice(snippetStart, snippetEnd);
+                            matches.push({
+                                messageIndex: i,
+                                role: msg.role,
+                                timestamp: msg.timestamp,
+                                matchedText: (snippetStart > 0 ? "..." : "") +
+                                    matchedText +
+                                    (snippetEnd < block.text.length ? "..." : ""),
+                            });
+                            break; // One match per message is enough
+                        }
+                    }
+                }
+                if (matches.length > 0) {
+                    results.push({
+                        sessionId: session.sessionId,
+                        agentName: session.metadata.agentName,
+                        createdAt: session.metadata.createdAt,
+                        updatedAt: session.metadata.updatedAt,
+                        matches,
+                    });
+                }
+            }
+            catch {
+                // Skip invalid session files
+                continue;
+            }
+        }
+        if (results.length === 0) {
+            return `No conversations found matching "${query}".`;
+        }
+        // Format results as readable string
+        let output = `Found ${results.length} conversation(s) matching "${query}":\n\n`;
+        for (const result of results) {
+            output += `=== Session: ${result.sessionId} (${result.agentName}) ===\n`;
+            output += `Created: ${result.createdAt} | Updated: ${result.updatedAt}\n\n`;
+            for (const match of result.matches) {
+                output += `[Message ${match.messageIndex + 1} - ${match.role} @ ${match.timestamp}]\n`;
+                output += `"${match.matchedText}"\n\n`;
+            }
+            output += "---\n\n";
+        }
+        return output;
+    }, {
+        name: CONVERSATION_SEARCH_TOOL_NAME,
+        description: `Search across past chat conversations to find previous discussions on specific topics.
+
+Use this tool to:
+- Find previous conversations that discussed specific topics
+- Recall information from past sessions
+- Search for patterns or recurring themes across conversations
+
+Parameters:
+- query: The text to search for (case-insensitive)
+- date_from: (optional) Only search conversations from this date onwards (ISO format, e.g., "2025-01-01")
+- date_to: (optional) Only search conversations up to this date (ISO format)
+- max_results: (optional) Maximum results to return (default: 10)`,
+        schema: conversationSearchSchema,
+    });
+    conversationSearch.prettyName = "Conversation Search";
+    conversationSearch.icon = "MessageSquare";
+    conversationSearch.verbiage = {
+        active: "Searching conversations for {query}",
+        past: "Searched conversations for {query}",
+        paramKey: "query",
+    };
+    return conversationSearch;
+}

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

@@ -37,7 +37,7 @@ const documentExtract = tool(async ({ session_id, file_path, query, target_token
             parsedContent = { content };
         }
         // Count tokens in the document
-        const documentTokens = countTokens(content);
+        const documentTokens = await countTokens(content);
         logger.info("Document extraction requested", {
             filePath: file_path,
             documentTokens,