@agent-native/core 0.46.0 → 0.48.1

package/dist/workspace-files/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/workspace-files/store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Workspace-files store.\n *\n * Provides read/write/append/list/delete/grep operations over the\n * `workspace_files` table. All writes enforce per-file (2 MB) and per-scope\n * (200 MB) caps. The table is lazily migrated on first use.\n */\n\nimport crypto from \"node:crypto\";\nimport { getDbExec } from \"../db/client.js\";\nimport {\n  WORKSPACE_FILES_CREATE_SQL,\n  WORKSPACE_FILES_INDEX_SQL,\n} from \"./schema.js\";\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/** Max content size per file (bytes). */\nexport const MAX_FILE_BYTES = 2 * 1024 * 1024; // 2 MB\n\n/** Max total content size across all files in one scope (bytes). */\nexport const MAX_SCOPE_BYTES = 200 * 1024 * 1024; // 200 MB\n\n/** Max content size when saving via saveToFile from provider-api / fetch tool (bytes). */\nexport const SAVE_TO_FILE_MAX_BYTES = 20 * 1024 * 1024; // 20 MB\n\n// ---------------------------------------------------------------------------\n// Lazy table init\n// ---------------------------------------------------------------------------\n\nlet _tableReady = false;\n\nasync function ensureTable(): Promise<void> {\n  if (_tableReady) return;\n  const db = getDbExec();\n  await db.execute(WORKSPACE_FILES_CREATE_SQL);\n  await db.execute(WORKSPACE_FILES_INDEX_SQL);\n  _tableReady = true;\n}\n\n// ---------------------------------------------------------------------------\n// Scope helpers\n// ---------------------------------------------------------------------------\n\nexport interface WorkspaceFilesScope {\n  scope: \"user\" | \"org\";\n  scopeId: string;\n}\n\n/**\n * Validate a workspace file path.\n * - Non-empty, no leading slash, no \"..\" components, no null bytes.\n */\nexport function validatePath(path: string): string | null {\n  if (!path || typeof path !== \"string\") return \"path is required\";\n  if (path.startsWith(\"/\")) return 'path must not start with \"/\"';\n  if (path.includes(\"\\0\")) return \"path must not contain null bytes\";\n  const parts = path.split(\"/\");\n  for (const part of parts) {\n    if (part === \"..\") return 'path must not contain \"..\" components';\n    if (part === \"\")\n      return 'path must not contain empty segments (\"//\" or trailing \"/\")';\n  }\n  return null;\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport interface WorkspaceFile {\n  id: string;\n  scope: string;\n  scopeId: string;\n  path: string;\n  content: string;\n  contentType: string;\n  sizeBytes: number;\n  createdAt: string;\n  updatedAt: string;\n}\n\nexport interface WorkspaceFileMeta {\n  id: string;\n  path: string;\n  contentType: string;\n  sizeBytes: number;\n  createdAt: string;\n  updatedAt: string;\n}\n\n// ---------------------------------------------------------------------------\n// Store operations\n// ---------------------------------------------------------------------------\n\n/**\n * Write (create or overwrite) a workspace file.\n * Enforces per-file (2 MB default; `saveToFile` callers may raise it up to\n * 20 MB via `opts.maxFileBytes`) and per-scope (200 MB) caps.\n */\nexport async function writeWorkspaceFile(\n  scope: WorkspaceFilesScope,\n  path: string,\n  content: string,\n  contentType = \"text/plain\",\n  opts?: { maxFileBytes?: number },\n): Promise<WorkspaceFileMeta> {\n  const pathErr = validatePath(path);\n  if (pathErr) throw new Error(`Invalid path: ${pathErr}`);\n\n  const maxFileBytes = Math.min(\n    opts?.maxFileBytes ?? MAX_FILE_BYTES,\n    SAVE_TO_FILE_MAX_BYTES,\n  );\n  const bytes = Buffer.byteLength(content, \"utf8\");\n  if (bytes > maxFileBytes) {\n    throw new Error(\n      `File \"${path}\" would be ${(bytes / 1024 / 1024).toFixed(2)} MB, which exceeds the ${(maxFileBytes / 1024 / 1024).toFixed(0)} MB per-file limit.`,\n    );\n  }\n\n  await ensureTable();\n  const db = getDbExec();\n\n  // Check scope total (excluding current file's existing bytes).\n  const existing = await getWorkspaceFileMeta(scope, path);\n  const existingBytes = existing?.sizeBytes ?? 0;\n  const scopeTotal = await getScopeTotalBytes(scope);\n  const newTotal = scopeTotal - existingBytes + bytes;\n  if (newTotal > MAX_SCOPE_BYTES) {\n    throw new Error(\n      `Writing \"${path}\" would bring the workspace total to ${(newTotal / 1024 / 1024).toFixed(1)} MB, exceeding the 200 MB limit.`,\n    );\n  }\n\n  const now = new Date().toISOString();\n\n  if (existing) {\n    await db.execute({\n      sql: `UPDATE workspace_files SET content = ?, content_type = ?, size_bytes = ?, updated_at = ? WHERE scope = ? AND scope_id = ? AND path = ?`,\n      args: [\n        content,\n        contentType,\n        bytes,\n        now,\n        scope.scope,\n        scope.scopeId,\n        path,\n      ],\n    });\n    return {\n      ...existing,\n      content: undefined as any,\n      contentType,\n      sizeBytes: bytes,\n      updatedAt: now,\n    } as unknown as WorkspaceFileMeta;\n  }\n\n  const id = crypto.randomUUID();\n  await db.execute({\n    sql: `INSERT INTO workspace_files (id, scope, scope_id, path, content, content_type, size_bytes, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n    args: [\n      id,\n      scope.scope,\n      scope.scopeId,\n      path,\n      content,\n      contentType,\n      bytes,\n      now,\n      now,\n    ],\n  });\n  return {\n    id,\n    path,\n    contentType,\n    sizeBytes: bytes,\n    createdAt: now,\n    updatedAt: now,\n  };\n}\n\n/**\n * Append text to an existing workspace file, or create it if it doesn't exist.\n */\nexport async function appendWorkspaceFile(\n  scope: WorkspaceFilesScope,\n  path: string,\n  text: string,\n  contentType = \"text/plain\",\n): Promise<WorkspaceFileMeta> {\n  const pathErr = validatePath(path);\n  if (pathErr) throw new Error(`Invalid path: ${pathErr}`);\n\n  await ensureTable();\n  const existing = await readWorkspaceFile(scope, path);\n  const newContent = existing ? existing.content + text : text;\n  return writeWorkspaceFile(scope, path, newContent, contentType);\n}\n\n/**\n * Read a workspace file's content (with optional offset and maxChars for paging).\n * Returns null if the file doesn't exist.\n */\nexport async function readWorkspaceFile(\n  scope: WorkspaceFilesScope,\n  path: string,\n  opts?: { offset?: number; maxChars?: number },\n): Promise<WorkspaceFile | null> {\n  const pathErr = validatePath(path);\n  if (pathErr) throw new Error(`Invalid path: ${pathErr}`);\n\n  await ensureTable();\n  const db = getDbExec();\n  const result = await db.execute({\n    sql: `SELECT id, scope, scope_id, path, content, content_type, size_bytes, created_at, updated_at FROM workspace_files WHERE scope = ? AND scope_id = ? AND path = ?`,\n    args: [scope.scope, scope.scopeId, path],\n  });\n\n  const row = result.rows[0];\n  if (!row) return null;\n\n  let content = String(row[4] ?? \"\");\n  if (opts?.offset || opts?.maxChars) {\n    const off = opts.offset ?? 0;\n    content = content.slice(\n      off,\n      opts.maxChars !== undefined ? off + opts.maxChars : undefined,\n    );\n  }\n\n  return {\n    id: String(row[0]),\n    scope: String(row[1]),\n    scopeId: String(row[2]),\n    path: String(row[3]),\n    content,\n    contentType: String(row[5] ?? \"text/plain\"),\n    sizeBytes: Number(row[6] ?? 0),\n    createdAt: String(row[7]),\n    updatedAt: String(row[8]),\n  };\n}\n\n/**\n * Get file metadata without loading content.\n */\nexport async function getWorkspaceFileMeta(\n  scope: WorkspaceFilesScope,\n  path: string,\n): Promise<WorkspaceFileMeta | null> {\n  await ensureTable();\n  const db = getDbExec();\n  const result = await db.execute({\n    sql: `SELECT id, path, content_type, size_bytes, created_at, updated_at FROM workspace_files WHERE scope = ? AND scope_id = ? AND path = ?`,\n    args: [scope.scope, scope.scopeId, path],\n  });\n\n  const row = result.rows[0];\n  if (!row) return null;\n\n  return {\n    id: String(row[0]),\n    path: String(row[1]),\n    contentType: String(row[2] ?? \"text/plain\"),\n    sizeBytes: Number(row[3] ?? 0),\n    createdAt: String(row[4]),\n    updatedAt: String(row[5]),\n  };\n}\n\n/**\n * List workspace files, optionally filtered by path prefix.\n * Returns metadata only (no content).\n */\nexport async function listWorkspaceFiles(\n  scope: WorkspaceFilesScope,\n  prefix?: string,\n): Promise<WorkspaceFileMeta[]> {\n  await ensureTable();\n  const db = getDbExec();\n\n  if (prefix) {\n    // Allow a trailing slash on list prefixes, but reject traversal and\n    // other invalid path shapes before they reach the LIKE pattern.\n    const normalizedPrefix = prefix.endsWith(\"/\")\n      ? prefix.slice(0, -1)\n      : prefix;\n    const pathErr = validatePath(normalizedPrefix);\n    if (pathErr) {\n      throw new Error(pathErr);\n    }\n    const result = await db.execute({\n      sql: `SELECT id, path, content_type, size_bytes, created_at, updated_at FROM workspace_files WHERE scope = ? AND scope_id = ? AND (path = ? OR path LIKE ? ESCAPE '\\\\') ORDER BY path ASC`,\n      args: [\n        scope.scope,\n        scope.scopeId,\n        normalizedPrefix,\n        `${normalizedPrefix.replace(/\\\\/g, \"\\\\\\\\\").replace(/%/g, \"\\\\%\").replace(/_/g, \"\\\\_\")}/%`,\n      ],\n    });\n    return result.rows.map(rowToMeta);\n  }\n\n  const result = await db.execute({\n    sql: `SELECT id, path, content_type, size_bytes, created_at, updated_at FROM workspace_files WHERE scope = ? AND scope_id = ? ORDER BY path ASC`,\n    args: [scope.scope, scope.scopeId],\n  });\n  return result.rows.map(rowToMeta);\n}\n\n/**\n * Delete a workspace file. Returns true if deleted, false if not found.\n */\nexport async function deleteWorkspaceFile(\n  scope: WorkspaceFilesScope,\n  path: string,\n): Promise<boolean> {\n  const pathErr = validatePath(path);\n  if (pathErr) throw new Error(`Invalid path: ${pathErr}`);\n\n  await ensureTable();\n  const db = getDbExec();\n  const result = await db.execute({\n    sql: `DELETE FROM workspace_files WHERE scope = ? AND scope_id = ? AND path = ?`,\n    args: [scope.scope, scope.scopeId, path],\n  });\n  return result.rowsAffected > 0;\n}\n\n/**\n * Search file contents for a substring or regex pattern.\n * Returns matching lines with path context.\n */\nexport async function grepWorkspaceFiles(\n  scope: WorkspaceFilesScope,\n  pattern: string,\n  opts?: {\n    pathPrefix?: string;\n    useRegex?: boolean;\n    maxMatchesPerFile?: number;\n    maxFiles?: number;\n  },\n): Promise<Array<{ path: string; lineNumber: number; line: string }>> {\n  const files = await listWorkspaceFiles(scope, opts?.pathPrefix);\n  const limited = files.slice(0, opts?.maxFiles ?? 50);\n\n  let regex: RegExp;\n  try {\n    regex = opts?.useRegex\n      ? new RegExp(pattern, \"i\")\n      : new RegExp(pattern.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\"), \"i\");\n  } catch {\n    throw new Error(`Invalid regex pattern: ${pattern}`);\n  }\n\n  const results: Array<{ path: string; lineNumber: number; line: string }> = [];\n  const maxPerFile = opts?.maxMatchesPerFile ?? 20;\n\n  for (const meta of limited) {\n    const file = await readWorkspaceFile(scope, meta.path);\n    if (!file) continue;\n    const lines = file.content.split(\"\\n\");\n    let matchCount = 0;\n    for (let i = 0; i < lines.length; i++) {\n      if (regex.test(lines[i])) {\n        results.push({ path: meta.path, lineNumber: i + 1, line: lines[i] });\n        matchCount++;\n        if (matchCount >= maxPerFile) break;\n      }\n    }\n  }\n\n  return results;\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nasync function getScopeTotalBytes(scope: WorkspaceFilesScope): Promise<number> {\n  const db = getDbExec();\n  const result = await db.execute({\n    sql: `SELECT COALESCE(SUM(size_bytes), 0) as total FROM workspace_files WHERE scope = ? AND scope_id = ?`,\n    args: [scope.scope, scope.scopeId],\n  });\n  return Number(result.rows[0]?.[0] ?? 0);\n}\n\nfunction rowToMeta(row: any[]): WorkspaceFileMeta {\n  return {\n    id: String(row[0]),\n    path: String(row[1]),\n    contentType: String(row[2] ?? \"text/plain\"),\n    sizeBytes: Number(row[3] ?? 0),\n    createdAt: String(row[4]),\n    updatedAt: String(row[5]),\n  };\n}\n"]}

package/dist/workspace-files/tool.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `workspace-files` agent tool.
+ *
+ * A single tool with an `action` discriminator covering write, append, read,
+ * list, delete, and grep. Files persist across conversations; the agent uses
+ * them to stage large intermediate results (fetched pages, per-item memos)
+ * and then read back selectively for synthesis.
+ *
+ * Scope is automatically resolved from the active request context:
+ *  - org scope when a request orgId is present (shared across users in the org)
+ *  - user scope otherwise (personal to the requesting user's email)
+ */
+import type { ActionEntry } from "../agent/production-agent.js";
+export declare function createWorkspaceFilesTool(): Record<string, ActionEntry>;
+//# sourceMappingURL=tool.d.ts.map

package/dist/workspace-files/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/workspace-files/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AA2BhE,wBAAgB,wBAAwB,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAgOtE"}

package/dist/workspace-files/tool.js

@@ -0,0 +1,225 @@
+/**
+ * `workspace-files` agent tool.
+ *
+ * A single tool with an `action` discriminator covering write, append, read,
+ * list, delete, and grep. Files persist across conversations; the agent uses
+ * them to stage large intermediate results (fetched pages, per-item memos)
+ * and then read back selectively for synthesis.
+ *
+ * Scope is automatically resolved from the active request context:
+ *  - org scope when a request orgId is present (shared across users in the org)
+ *  - user scope otherwise (personal to the requesting user's email)
+ */
+import { getRequestOrgId, getRequestUserEmail, } from "../server/request-context.js";
+import { writeWorkspaceFile, appendWorkspaceFile, readWorkspaceFile, listWorkspaceFiles, deleteWorkspaceFile, grepWorkspaceFiles, } from "./store.js";
+const MAX_READ_CHARS = 100_000;
+const DEFAULT_READ_CHARS = 40_000;
+/** Resolve scope from the current request context (org-preferred). */
+function resolveScope() {
+    const orgId = getRequestOrgId();
+    if (orgId)
+        return { scope: "org", scopeId: orgId };
+    const email = getRequestUserEmail();
+    if (email)
+        return { scope: "user", scopeId: email };
+    return null;
+}
+export function createWorkspaceFilesTool() {
+    return {
+        "workspace-files": {
+            readOnly: false,
+            tool: {
+                description: [
+                    "Durable scratch-file storage for the agent. Files persist across conversations and are scoped to the current org/user.",
+                    "Use this to stage large intermediate results (fetched pages, per-item analysis memos, API payloads) so they don't consume context window, then read them back selectively for synthesis.",
+                    "",
+                    "Typical fusion-style workflow:",
+                    "  1. Fan out: for each item, fetch data and `write` a per-item memo file.",
+                    "  2. Synthesize: `list` files, then `read` each memo (with offset/maxChars to page large ones).",
+                    "  3. Optionally `grep` across all memos to find patterns.",
+                    "  4. `delete` temp files when no longer needed.",
+                    "",
+                    "Actions:",
+                    "  write   — create or overwrite a file. Max 2 MB per file, 200 MB total.",
+                    "  append  — append text to a file (or create if absent).",
+                    "  read    — read content, optionally with offset/maxChars for paging large files.",
+                    "  list    — list files (with optional path prefix filter) showing name, size, updated.",
+                    "  delete  — delete a file by path.",
+                    "  grep    — search content across files for a substring or regex.",
+                ].join("\n"),
+                parameters: {
+                    type: "object",
+                    properties: {
+                        action: {
+                            type: "string",
+                            enum: ["write", "append", "read", "list", "delete", "grep"],
+                            description: "Operation to perform.",
+                        },
+                        path: {
+                            type: "string",
+                            description: 'File path relative to the scope root, e.g. "analysis/q2-memos/acme.md". Required for write/append/read/delete. Optional for list/grep (acts as prefix filter).',
+                        },
+                        content: {
+                            type: "string",
+                            description: "Text content to write or append. Required for write/append.",
+                        },
+                        contentType: {
+                            type: "string",
+                            description: 'MIME type for new files. Default: "text/plain". Use "application/json" for JSON, "text/markdown" for Markdown.',
+                        },
+                        offset: {
+                            type: "number",
+                            description: "Character offset to start reading from (for paging large files). Default: 0.",
+                        },
+                        maxChars: {
+                            type: "number",
+                            description: `Maximum characters to return when reading. Default: ${DEFAULT_READ_CHARS}. Max: ${MAX_READ_CHARS}.`,
+                        },
+                        pattern: {
+                            type: "string",
+                            description: "Search pattern for grep. Required for grep action. A plain substring by default; set useRegex to true for a regex.",
+                        },
+                        useRegex: {
+                            type: "boolean",
+                            description: "When true, treat `pattern` as a JavaScript regex (case-insensitive). Default: false.",
+                        },
+                    },
+                    required: ["action"],
+                },
+            },
+            run: async (args) => {
+                const scope = resolveScope();
+                if (!scope) {
+                    return "Error: workspace-files requires an authenticated request context.";
+                }
+                const action = String(args.action ?? "").trim();
+                try {
+                    switch (action) {
+                        case "write": {
+                            const path = String(args.path ?? "").trim();
+                            if (!path)
+                                return "Error: path is required for write.";
+                            const content = String(args.content ?? "");
+                            const contentType = String(args.contentType ?? "text/plain");
+                            const meta = await writeWorkspaceFile(scope, path, content, contentType);
+                            return JSON.stringify({
+                                ok: true,
+                                action: "write",
+                                path: meta.path,
+                                sizeBytes: meta.sizeBytes,
+                                updatedAt: meta.updatedAt,
+                            });
+                        }
+                        case "append": {
+                            const path = String(args.path ?? "").trim();
+                            if (!path)
+                                return "Error: path is required for append.";
+                            const content = String(args.content ?? "");
+                            const contentType = String(args.contentType ?? "text/plain");
+                            const meta = await appendWorkspaceFile(scope, path, content, contentType);
+                            return JSON.stringify({
+                                ok: true,
+                                action: "append",
+                                path: meta.path,
+                                sizeBytes: meta.sizeBytes,
+                                updatedAt: meta.updatedAt,
+                            });
+                        }
+                        case "read": {
+                            const path = String(args.path ?? "").trim();
+                            if (!path)
+                                return "Error: path is required for read.";
+                            const rawOffset = Number(args.offset);
+                            const offset = Number.isFinite(rawOffset) && rawOffset > 0 ? rawOffset : 0;
+                            const rawMax = Number(args.maxChars);
+                            const maxChars = Number.isFinite(rawMax) && rawMax > 0
+                                ? Math.min(rawMax, MAX_READ_CHARS)
+                                : DEFAULT_READ_CHARS;
+                            const file = await readWorkspaceFile(scope, path, {
+                                offset,
+                                maxChars,
+                            });
+                            if (!file) {
+                                return JSON.stringify({
+                                    ok: false,
+                                    error: `File not found: "${path}"`,
+                                });
+                            }
+                            const truncated = file.content.length >= maxChars;
+                            return JSON.stringify({
+                                ok: true,
+                                path: file.path,
+                                contentType: file.contentType,
+                                sizeBytes: file.sizeBytes,
+                                updatedAt: file.updatedAt,
+                                content: file.content,
+                                ...(truncated
+                                    ? {
+                                        truncated: true,
+                                        nextOffset: offset + file.content.length,
+                                        hint: `File has more content. Call again with offset: ${offset + file.content.length}`,
+                                    }
+                                    : {}),
+                            });
+                        }
+                        case "list": {
+                            const prefix = args.path ? String(args.path).trim() : undefined;
+                            const files = await listWorkspaceFiles(scope, prefix || undefined);
+                            return JSON.stringify({
+                                ok: true,
+                                count: files.length,
+                                files: files.map((f) => ({
+                                    path: f.path,
+                                    sizeBytes: f.sizeBytes,
+                                    contentType: f.contentType,
+                                    updatedAt: f.updatedAt,
+                                })),
+                            });
+                        }
+                        case "delete": {
+                            const path = String(args.path ?? "").trim();
+                            if (!path)
+                                return "Error: path is required for delete.";
+                            const deleted = await deleteWorkspaceFile(scope, path);
+                            return JSON.stringify({
+                                ok: true,
+                                deleted,
+                                path,
+                            });
+                        }
+                        case "grep": {
+                            const pattern = String(args.pattern ?? "").trim();
+                            if (!pattern)
+                                return "Error: pattern is required for grep.";
+                            const prefix = args.path ? String(args.path).trim() : undefined;
+                            const useRegex = args.useRegex === true || String(args.useRegex) === "true";
+                            const matches = await grepWorkspaceFiles(scope, pattern, {
+                                pathPrefix: prefix || undefined,
+                                useRegex,
+                                maxMatchesPerFile: 20,
+                                maxFiles: 50,
+                            });
+                            return JSON.stringify({
+                                ok: true,
+                                pattern,
+                                matchCount: matches.length,
+                                matches: matches.map((m) => ({
+                                    path: m.path,
+                                    line: m.lineNumber,
+                                    text: m.line,
+                                })),
+                            });
+                        }
+                        default:
+                            return `Error: unknown action "${action}". Valid actions: write, append, read, list, delete, grep.`;
+                    }
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return JSON.stringify({ ok: false, error: msg });
+                }
+            },
+        },
+    };
+}
+//# sourceMappingURL=tool.js.map

package/dist/workspace-files/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/workspace-files/tool.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `workspace-files` agent tool.\n *\n * A single tool with an `action` discriminator covering write, append, read,\n * list, delete, and grep. Files persist across conversations; the agent uses\n * them to stage large intermediate results (fetched pages, per-item memos)\n * and then read back selectively for synthesis.\n *\n * Scope is automatically resolved from the active request context:\n *  - org scope when a request orgId is present (shared across users in the org)\n *  - user scope otherwise (personal to the requesting user's email)\n */\n\nimport type { ActionEntry } from \"../agent/production-agent.js\";\nimport {\n  getRequestOrgId,\n  getRequestUserEmail,\n} from \"../server/request-context.js\";\nimport {\n  writeWorkspaceFile,\n  appendWorkspaceFile,\n  readWorkspaceFile,\n  listWorkspaceFiles,\n  deleteWorkspaceFile,\n  grepWorkspaceFiles,\n  type WorkspaceFilesScope,\n} from \"./store.js\";\n\nconst MAX_READ_CHARS = 100_000;\nconst DEFAULT_READ_CHARS = 40_000;\n\n/** Resolve scope from the current request context (org-preferred). */\nfunction resolveScope(): WorkspaceFilesScope | null {\n  const orgId = getRequestOrgId();\n  if (orgId) return { scope: \"org\", scopeId: orgId };\n  const email = getRequestUserEmail();\n  if (email) return { scope: \"user\", scopeId: email };\n  return null;\n}\n\nexport function createWorkspaceFilesTool(): Record<string, ActionEntry> {\n  return {\n    \"workspace-files\": {\n      readOnly: false,\n      tool: {\n        description: [\n          \"Durable scratch-file storage for the agent. Files persist across conversations and are scoped to the current org/user.\",\n          \"Use this to stage large intermediate results (fetched pages, per-item analysis memos, API payloads) so they don't consume context window, then read them back selectively for synthesis.\",\n          \"\",\n          \"Typical fusion-style workflow:\",\n          \"  1. Fan out: for each item, fetch data and `write` a per-item memo file.\",\n          \"  2. Synthesize: `list` files, then `read` each memo (with offset/maxChars to page large ones).\",\n          \"  3. Optionally `grep` across all memos to find patterns.\",\n          \"  4. `delete` temp files when no longer needed.\",\n          \"\",\n          \"Actions:\",\n          \"  write   — create or overwrite a file. Max 2 MB per file, 200 MB total.\",\n          \"  append  — append text to a file (or create if absent).\",\n          \"  read    — read content, optionally with offset/maxChars for paging large files.\",\n          \"  list    — list files (with optional path prefix filter) showing name, size, updated.\",\n          \"  delete  — delete a file by path.\",\n          \"  grep    — search content across files for a substring or regex.\",\n        ].join(\"\\n\"),\n        parameters: {\n          type: \"object\",\n          properties: {\n            action: {\n              type: \"string\",\n              enum: [\"write\", \"append\", \"read\", \"list\", \"delete\", \"grep\"],\n              description: \"Operation to perform.\",\n            },\n            path: {\n              type: \"string\",\n              description:\n                'File path relative to the scope root, e.g. \"analysis/q2-memos/acme.md\". Required for write/append/read/delete. Optional for list/grep (acts as prefix filter).',\n            },\n            content: {\n              type: \"string\",\n              description:\n                \"Text content to write or append. Required for write/append.\",\n            },\n            contentType: {\n              type: \"string\",\n              description:\n                'MIME type for new files. Default: \"text/plain\". Use \"application/json\" for JSON, \"text/markdown\" for Markdown.',\n            },\n            offset: {\n              type: \"number\",\n              description:\n                \"Character offset to start reading from (for paging large files). Default: 0.\",\n            },\n            maxChars: {\n              type: \"number\",\n              description: `Maximum characters to return when reading. Default: ${DEFAULT_READ_CHARS}. Max: ${MAX_READ_CHARS}.`,\n            },\n            pattern: {\n              type: \"string\",\n              description:\n                \"Search pattern for grep. Required for grep action. A plain substring by default; set useRegex to true for a regex.\",\n            },\n            useRegex: {\n              type: \"boolean\",\n              description:\n                \"When true, treat `pattern` as a JavaScript regex (case-insensitive). Default: false.\",\n            },\n          },\n          required: [\"action\"],\n        },\n      },\n\n      run: async (args: Record<string, unknown>): Promise<string> => {\n        const scope = resolveScope();\n        if (!scope) {\n          return \"Error: workspace-files requires an authenticated request context.\";\n        }\n\n        const action = String(args.action ?? \"\").trim();\n\n        try {\n          switch (action) {\n            case \"write\": {\n              const path = String(args.path ?? \"\").trim();\n              if (!path) return \"Error: path is required for write.\";\n              const content = String(args.content ?? \"\");\n              const contentType = String(args.contentType ?? \"text/plain\");\n              const meta = await writeWorkspaceFile(\n                scope,\n                path,\n                content,\n                contentType,\n              );\n              return JSON.stringify({\n                ok: true,\n                action: \"write\",\n                path: meta.path,\n                sizeBytes: meta.sizeBytes,\n                updatedAt: meta.updatedAt,\n              });\n            }\n\n            case \"append\": {\n              const path = String(args.path ?? \"\").trim();\n              if (!path) return \"Error: path is required for append.\";\n              const content = String(args.content ?? \"\");\n              const contentType = String(args.contentType ?? \"text/plain\");\n              const meta = await appendWorkspaceFile(\n                scope,\n                path,\n                content,\n                contentType,\n              );\n              return JSON.stringify({\n                ok: true,\n                action: \"append\",\n                path: meta.path,\n                sizeBytes: meta.sizeBytes,\n                updatedAt: meta.updatedAt,\n              });\n            }\n\n            case \"read\": {\n              const path = String(args.path ?? \"\").trim();\n              if (!path) return \"Error: path is required for read.\";\n              const rawOffset = Number(args.offset);\n              const offset =\n                Number.isFinite(rawOffset) && rawOffset > 0 ? rawOffset : 0;\n              const rawMax = Number(args.maxChars);\n              const maxChars =\n                Number.isFinite(rawMax) && rawMax > 0\n                  ? Math.min(rawMax, MAX_READ_CHARS)\n                  : DEFAULT_READ_CHARS;\n\n              const file = await readWorkspaceFile(scope, path, {\n                offset,\n                maxChars,\n              });\n              if (!file) {\n                return JSON.stringify({\n                  ok: false,\n                  error: `File not found: \"${path}\"`,\n                });\n              }\n\n              const truncated = file.content.length >= maxChars;\n              return JSON.stringify({\n                ok: true,\n                path: file.path,\n                contentType: file.contentType,\n                sizeBytes: file.sizeBytes,\n                updatedAt: file.updatedAt,\n                content: file.content,\n                ...(truncated\n                  ? {\n                      truncated: true,\n                      nextOffset: offset + file.content.length,\n                      hint: `File has more content. Call again with offset: ${offset + file.content.length}`,\n                    }\n                  : {}),\n              });\n            }\n\n            case \"list\": {\n              const prefix = args.path ? String(args.path).trim() : undefined;\n              const files = await listWorkspaceFiles(\n                scope,\n                prefix || undefined,\n              );\n              return JSON.stringify({\n                ok: true,\n                count: files.length,\n                files: files.map((f) => ({\n                  path: f.path,\n                  sizeBytes: f.sizeBytes,\n                  contentType: f.contentType,\n                  updatedAt: f.updatedAt,\n                })),\n              });\n            }\n\n            case \"delete\": {\n              const path = String(args.path ?? \"\").trim();\n              if (!path) return \"Error: path is required for delete.\";\n              const deleted = await deleteWorkspaceFile(scope, path);\n              return JSON.stringify({\n                ok: true,\n                deleted,\n                path,\n              });\n            }\n\n            case \"grep\": {\n              const pattern = String(args.pattern ?? \"\").trim();\n              if (!pattern) return \"Error: pattern is required for grep.\";\n              const prefix = args.path ? String(args.path).trim() : undefined;\n              const useRegex =\n                args.useRegex === true || String(args.useRegex) === \"true\";\n              const matches = await grepWorkspaceFiles(scope, pattern, {\n                pathPrefix: prefix || undefined,\n                useRegex,\n                maxMatchesPerFile: 20,\n                maxFiles: 50,\n              });\n              return JSON.stringify({\n                ok: true,\n                pattern,\n                matchCount: matches.length,\n                matches: matches.map((m) => ({\n                  path: m.path,\n                  line: m.lineNumber,\n                  text: m.line,\n                })),\n              });\n            }\n\n            default:\n              return `Error: unknown action \"${action}\". Valid actions: write, append, read, list, delete, grep.`;\n          }\n        } catch (err) {\n          const msg = err instanceof Error ? err.message : String(err);\n          return JSON.stringify({ ok: false, error: msg });\n        }\n      },\n    },\n  };\n}\n"]}

package/docs/content/a2a-protocol.md

@@ -94,6 +94,8 @@ The card endpoint is public, so the framework redacts skills whose IDs reveal pe
 }
 ```
 
+_(Version may differ; fetch your app's live card at `/.well-known/agent-card.json` for the current `protocolVersion`.)_
+
 When `A2A_SECRET` is set (the recommended path), the card advertises a
 `jwtBearer` scheme as above. The `apiKey` scheme is only added when a legacy
 `apiKeyEnv` is also configured, so a card with just `A2A_SECRET` set publishes
@@ -303,18 +305,22 @@ A mail agent needs analytics data. The analytics agent exposes a "run-query" ski
 
 ```ts
 // In the mail agent's actions/get-analytics.ts
+import { defineAction } from "@agent-native/core/server";
 import { callAgent } from "@agent-native/core/a2a";
-
-export default async function (args: string[]) {
-  const response = await callAgent(
-    "https://analytics.example.com",
-    "How many emails were sent last week by category?",
-    { apiKey: process.env.ANALYTICS_API_KEY },
-  );
-
-  console.log(response);
-  // The mail agent can now use this data in its response
-}
+import { z } from "zod";
+
+export default defineAction({
+  description: "Ask the analytics agent a question.",
+  schema: z.object({ question: z.string() }),
+  async run({ question }) {
+    const response = await callAgent(
+      "https://analytics.example.com",
+      question,
+      { apiKey: process.env.ANALYTICS_API_KEY },
+    );
+    return { answer: response };
+  },
+});
 ```
 
-The analytics agent receives the message, runs the query via its handler, and returns the result. The mail agent's script gets the text response back. No shared database, no direct API calls — just agent-to-agent communication.
+The analytics agent receives the message, runs the query via its handler, and returns the result. The mail action gets the text response back. No shared database, no direct API calls — just agent-to-agent communication.

package/docs/content/actions.md

@@ -15,7 +15,7 @@ Actions are the single source of truth for anything your app does. Define an act
 - **An A2A tool** — called by other agent-native apps over A2A.
 - **A CLI command** — `pnpm action <name>` for scripting and dev loops.
 
-One definition, six consumers. This is rung 3 of the [ladder](/docs/what-is-agent-native#the-ladder).
+One definition, seven consumers. This is rung 3 of the [ladder](/docs/what-is-agent-native#the-ladder).
 
 ## Defining an action {#defining}
 
@@ -57,15 +57,17 @@ By default every action is exposed as `POST /_agent-native/actions/<name>`. Over
 export default defineAction({
   description: "Get details for a lead.",
   schema: z.object({ leadId: z.string() }),
-  http: { method: "GET", path: "leads/:leadId" }, // optional override
+  http: { method: "GET" },
   run: async ({ leadId }) => {
     return await db.select().from(leads).where(eq(leads.id, leadId));
   },
 });
 ```
 
+For a `GET` action, `leadId` is passed as a query param: `/_agent-native/actions/get-lead?leadId=abc`.
+
 - **`http: { method: "GET" | "POST" | "PUT" | "DELETE" }`** — default `POST`. `GET` actions are auto-marked `readOnly` so successful calls don't trigger a UI poll-refresh.
-- **`http: { path: "..." }`** — override the route path under `/_agent-native/actions/`. Defaults to the filename.
+- **`http: { path: "..." }`** — override the mounted URL under `/_agent-native/actions/`. Defaults to the filename. **Path overrides change the URL only for direct HTTP callers** — `useActionQuery`, `useActionMutation`, and `callAction` always call `/_agent-native/actions/<name>` regardless of this override, so overriding the path makes those hooks 404. Use path overrides only for external HTTP callers. Note also that `:param` route segments in the override path are **not** parsed into `run()` args — only query-string params and JSON body fields are.
 - **`http: false`** — disable the HTTP endpoint entirely. Agent + CLI only.
 - **`readOnly: true`** — explicitly skip the poll-refresh even for POST actions that don't mutate.
 - **`parallelSafe: true`** — allow a mutating action to run concurrently with other same-turn tool calls. Only set this when the action is internally concurrency-safe and order-independent; mutating actions serialize by default.
@@ -133,7 +135,7 @@ export default defineAction({
 | `false`     | Explicit deny. The extension bridge returns 403; the action is still callable normally from the UI, agent, CLI, MCP, and A2A.                                                                                                                     |
 | `undefined` | **Default-allow.** Extensions are intra-org and typically authored by trusted teammates, so the default trusts the org-level access controls. Set `false` only for genuinely auth-adjacent operations (account deletion, org membership changes). |
 
-Enforcement: the parent host (`ToolViewer.tsx` / `EmbeddedTool.tsx` — physical class names retained) tags every outbound action call from an extension iframe with the header `X-Agent-Native-Tool-Bridge: 1`. The action route layer reads this header and applies the rule above. Regular UI/agent/CLI/A2A calls do not carry the header and are unaffected. The header is set by the React host; the iframe's user-authored content cannot spoof it because the bridge sanitizes iframe-supplied headers.
+Enforcement: the parent host tags every outbound action call from an extension iframe with the header `X-Agent-Native-Tool-Bridge: 1`. The action route layer reads this header and applies the rule above. Regular UI/agent/CLI/A2A calls do not carry the header and are unaffected. The header is set by the React host; the iframe's user-authored content cannot spoof it because the bridge sanitizes iframe-supplied headers.
 
 Set `toolCallable: false` for actions that:
 
@@ -169,12 +171,13 @@ export default defineAction({
 
 `ActionRunContext` fields:
 
-| Field       | Type                  | Notes                                                                                                                                                           |
-| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `userEmail` | `string \| undefined` | Resolved request user. **Never defaulted to a dev identity** — `undefined` when the request has no authenticated user. Apply your own fallback if you need one. |
-| `orgId`     | `string \| null`      | Resolved org id, or `null` when the request has no org.                                                                                                         |
-| `caller`    | `ActionCaller`        | How the action was invoked (see below).                                                                                                                         |
-| `send`      | `(event) => void`     | Optional. Emit an SSE event to the client. Only present inside the agent tool loop (`caller: "tool"`); `undefined` elsewhere.                                   |
+| Field         | Type                    | Notes                                                                                                                                                           |
+| ------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `userEmail`   | `string \| undefined`   | Resolved request user. **Never defaulted to a dev identity** — `undefined` when the request has no authenticated user. Apply your own fallback if you need one. |
+| `orgId`       | `string \| null`        | Resolved org id, or `null` when the request has no org.                                                                                                         |
+| `caller`      | `ActionCaller`          | How the action was invoked (see below).                                                                                                                         |
+| `send`        | `(event) => void`       | Optional. Emit an SSE event to the client. Only present inside the agent tool loop (`caller: "tool"`); `undefined` elsewhere.                                   |
+| `attachments` | `AgentChatAttachment[]` | Files, images, and pasted text blocks submitted with the current agent turn. Populated only when `caller: "tool"`; `undefined` on all other surfaces.           |
 
 `caller` is the union `"tool" | "http" | "frontend" | "cli" | "mcp" | "a2a"`:
 
@@ -189,6 +192,35 @@ export default defineAction({
 
 `run` stays backward compatible: existing 1-argument handlers and handlers that only destructure `{ send }` continue to work unchanged.
 
+### Access control in actions {#access-control}
+
+User-owned tables must scope reads through `accessFilter` and writes through `assertAccess` — the same helpers the framework's sharing system uses. Here is a complete, paste-ready example:
+
+```ts
+// actions/create-lead.ts
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { getDb } from "../server/db/index.js";
+import * as schema from "../server/db/schema.js";
+
+export default defineAction({
+  description: "Create a lead in the CRM.",
+  schema: z.object({ name: z.string(), company: z.string() }),
+  run: async ({ name, company }, ctx) => {
+    const db = getDb();
+    await db.insert(schema.leads).values({
+      id: crypto.randomUUID(),
+      name,
+      company,
+      ownerEmail: ctx?.userEmail ?? "system",
+    });
+    return { ok: true };
+  },
+});
+```
+
+For list and read actions, use `accessFilter` to scope the query to the current user and org. For actions that update or delete a specific row, use `assertAccess` to confirm the caller is allowed before writing. See [Security](/docs/security#access-guards) and [Sharing](/docs/sharing) for the full helper API.
+
 ## Calling it from the UI {#ui}
 
 Two hooks, both in `@agent-native/core/client`. Types are inferred from your `defineAction` schemas — no manual type declarations.

package/docs/content/agent-mentions.md

@@ -65,23 +65,20 @@ Agents become available for mentioning through several mechanisms:
 
 ### Custom workspace agents
 
-Custom agents are Markdown resources:
+Custom agents are Markdown files stored in the workspace:
 
 ```markdown
 ---
 name: Design
-description: >-
-  Reviews layouts, product UX, and visual direction.
+description: Reviews layouts, product UX, and visual direction.
 model: inherit
-tools: inherit
-delegate-default: false
 ---
 
-# Role
-
 You are a focused design agent.
 ```
 
+See [Workspace — Custom Agents](/docs/workspace#custom-agents) for the full format (including `tools`, `delegate-default`, and model overrides).
+
 You can create them from the Workspace tab using:
 
 - `Create Agent` -> `Describe It`
@@ -102,7 +99,9 @@ Remote A2A agents still use JSON manifests:
 }
 ```
 
-## Custom mention providers {#custom-mention-providers}
+---
+
+## For developers: extending mentions {#extending-mentions}
 
 Templates can register custom mention providers to add domain-specific mentionable items beyond agents and files. A mention provider implements the `MentionProvider` interface:
 

package/docs/content/agent-teams.md

@@ -9,6 +9,8 @@ The agent chat is an **orchestrator**, not a monolith. When the main agent hits
 
 This keeps the main thread focused, lets sub-agents run in parallel, and gives you a clean audit trail for any delegated work.
 
+Agent Teams runs on the core run-manager: events stream and persist, aborts propagate through SQL, and tasks survive serverless cold starts.
+
 ## The mental model {#mental-model}
 
 - **Main chat** — the orchestrator. Reads your request, delegates. Rarely does heavy work itself.
@@ -18,23 +20,6 @@ This keeps the main thread focused, lets sub-agents run in parallel, and gives y
 
 Sub-agent state is persisted in the `application_state` SQL table (under `agent-task:<taskId>`), so tasks survive serverless cold starts and work across multiple processes.
 
-Agent Teams runs on the same core `run-manager` as hosted
-agent chat: events are streamed and persisted, aborts propagate through SQL,
-heartbeats mark active work, and stale runs can be reaped consistently. New
-background-agent UIs should reuse `run-manager` or `spawnTask()` instead of
-introducing a separate runner with its own lifecycle rules.
-
-Agent-Native Code is the sibling local surface, not a second hosted-agent
-lifecycle. Code currently keeps long-running local sessions in the file-backed
-Code run store and exposes them through the shared background-run foundation.
-The CLI commands (`agent-native`, `agent-native code`, `resume`, `status`,
-`stop`, `ui`), the Desktop Code tab, background sessions, and sub-agent
-sessions should present the same run model even when their persistence layer is
-different. When a new surface needs both hosted sub-agents and local Code
-sessions, adapt those sources into the shared background-run/run-manager
-vocabulary instead of adding another queue, transcript model, or process
-tracker.
-
 ## When to spawn a sub-agent {#when-to-spawn}
 
 Spawn when the task:
@@ -58,7 +43,17 @@ Custom agents live in the workspace at `agents/<slug>.md` — a Markdown file wi
 
 ### 2. The main agent delegates automatically {#auto-delegate}
 
-The framework gives the main agent a `delegate-to-agent` tool. When the model decides a task fits a registered sub-agent profile, it calls the tool. A chip appears; the sub-agent runs. The main agent waits (or moves on in parallel) and incorporates the result when the sub-agent finishes.
+The framework gives the main agent an `agent-teams` tool. When the model decides a task fits a registered sub-agent profile, it calls the tool with `action: "spawn"` and an optional `agent` parameter naming a profile from `agents/*.md`. A chip appears; the sub-agent runs. The main agent waits (or moves on in parallel) and incorporates the result when the sub-agent finishes.
+
+The full `agent-teams` action set is:
+
+| Action        | Purpose                              |
+| ------------- | ------------------------------------ |
+| `spawn`       | Start a new sub-agent task           |
+| `status`      | Check a running sub-agent's progress |
+| `read-result` | Get a finished sub-agent's output    |
+| `send`        | Message a running sub-agent          |
+| `list`        | See all tasks for the current user   |
 
 ### 3. Programmatic spawn {#programmatic-spawn}
 
@@ -73,12 +68,13 @@ const task = await spawnTask({
   ownerEmail: user.email,
   systemPrompt: mailAgentSystemPrompt,
   actions: mailActions,
-  apiKey: process.env.ANTHROPIC_API_KEY!,
+  // Pass either apiKey or engine — engine takes precedence.
+  apiKey: process.env.ANTHROPIC_API_KEY, // optional if engine is provided
   parentSend: emit, // streaming sender for the parent chat response
 });
 ```
 
-Most app code won't call this directly — the framework does it under the hood for `@mentions` and for the `delegate-to-agent` tool. Reach for `spawnTask()` only when you're wiring a new entry point (e.g., a button that kicks off a background job that runs as a sub-agent).
+Most app code won't call this directly — the framework does it under the hood for `@mentions` and for the `agent-teams` tool. Reach for `spawnTask()` only when you're wiring a new entry point (e.g., a button that kicks off a background job that runs as a sub-agent).
 
 ## Task lifecycle {#lifecycle}
 
@@ -112,7 +108,7 @@ const task = await getTask(taskId); // single task
 const tasks = await listTasks(); // all tasks for the user (sorted newest first)
 ```
 
-`AgentTask` shape:
+`AgentTask` key fields:
 
 ```ts
 interface AgentTask {
@@ -124,36 +120,26 @@ interface AgentTask {
   summary: string; // full summary once completed
   currentStep: string; // latest step label (updated while running)
   createdAt: number;
+  // Additional fields: parentThreadId, name, updatedAt, startedAt,
+  // completedAt, runId, error
 }
 ```
 
 ## Custom agent profiles {#profiles}
 
-A custom agent is a Markdown file in the workspace:
+A custom agent is a Markdown file in the workspace. Minimal example:
 
 ```markdown
 ---
 name: Code Review
-description: >-
-  Reviews TypeScript PRs with a focus on correctness, type safety, and API design.
+description: Reviews TypeScript PRs for correctness and type safety.
 model: inherit
-tools: inherit
-delegate-default: true
 ---
 
-# Role
-
-You are a meticulous code reviewer. Focus on correctness, subtle type errors,
-and the public API surface. Be terse and concrete — cite file:line wherever
-you can.
-
-## Rules
-
-- Prefer "here's the bug" over "here's why this pattern is wrong."
-- Never LGTM silently; always summarize what you checked.
+You are a meticulous code reviewer. Be terse and concrete — cite file:line wherever you can.
 ```
 
-Store at `agents/code-review.md` in the workspace. It appears in the `@mention` dropdown and is available to the main agent as a delegation target. See [Workspace — Custom Agents](/docs/workspace#custom-agents) for the full format.
+Store at `agents/code-review.md` in the workspace. It appears in the `@mention` dropdown and is available to the main agent as a delegation target. See [Workspace — Custom Agents](/docs/workspace#custom-agents) for the full format including `tools`, `delegate-default`, and model overrides.
 
 ## What's next