@bevel-software/platform-core-backend 0.1.0

package/dist/modules/workspace/workspace.tools.js

@@ -0,0 +1,767 @@
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { ToolError } from '../tool-helpers/tool.contract.js';
+import { BRANCH_INPUT, toolDef } from '../tool-helpers/tool-def.js';
+import { recordOntologyRead, assertOntologyWriteAllowed, assertShellAllowedWithinOntology, ONTOLOGY_BOUNDARY_NOTE, SESSION_ID_INPUT, } from './session-ontology.gate.js';
+import { requireInternalSource, requireExternalSource } from '../tool-auth/tool-auth.middleware.js';
+import { workspaceIdForBranch } from './workspace.service.js';
+// Leaf-level shared primitive (same exception `workspace.service.ts` already
+// relies on) — not a workflow service, so this stays inside the module boundary.
+import { assertValidBranchName } from '../workflow/git/branch-name.js';
+import { toKbRelative, resolveReadableMap } from '../access/kb-read-filter.js';
+/** Throw a 403 ToolError if the gate denies reading `wsPath` (a KB node). */
+async function assertCanRead(gate, wsPath) {
+    const rel = toKbRelative(wsPath, gate.kbDirName);
+    if (rel === null)
+        return; // not a KB node — not governed by read rules
+    const ok = await gate.accessControl.canRead(gate.workspaceId, gate.userEmail, rel);
+    if (!ok)
+        throw new ToolError(`You don't have permission to read "${wsPath}".`, 403);
+}
+/**
+ * Drop the file entries the caller may not read from a directory listing.
+ * Directory entries and non-KB files are always kept (a directory itself has
+ * no `read:` verdict; its restricted children are filtered when read/listed) —
+ * this is the AGENT's inclusion policy and differs from the explorer tree,
+ * which hides restricted directories outright. Uses the FULL `canReadBatch`
+ * (per-node frontmatter honoured), via the shared `resolveReadableMap`. One
+ * batched ACL load per directory.
+ */
+async function filterReadableEntries(gate, dir, entries) {
+    const fileWsPaths = [];
+    for (const e of entries) {
+        if (e.type === 'directory')
+            continue;
+        fileWsPaths.push(dir ? `${dir}/${e.name}` : e.name);
+    }
+    if (fileWsPaths.length === 0)
+        return entries;
+    const verdict = await resolveReadableMap((wid, email, rels) => gate.accessControl.canReadBatch(wid, email, rels), gate.workspaceId, gate.userEmail, gate.kbDirName, fileWsPaths);
+    return entries.filter((e) => {
+        if (e.type === 'directory')
+            return true;
+        const wsPath = dir ? `${dir}/${e.name}` : e.name;
+        return verdict.get(wsPath) === true;
+    });
+}
+/**
+ * Appended (centrally, in `mount`) to EVERY workspace tool description. A KB
+ * author can drop a `CLAUDE.md` at the workspace root to document conventions
+ * for that knowledge base; agents (ours and external) should consult it before
+ * touching files. It rides on every entrypoint — reads (grep/list_files/
+ * file_stat) included — because any of them can be a session's first touch.
+ */
+const KB_CONVENTIONS_NOTE = ' Before your first read or change in a workspace, read `CLAUDE.md` at the KB root (if it exists) — it holds the author\'s conventions for this knowledge base, and you should follow them.';
+const int = (description) => ({ type: 'integer', description });
+const str = (description) => ({ type: 'string', description });
+function asText(content) {
+    return typeof content === 'string' ? content : content.toString('utf8');
+}
+/** JS grep over the workspace tree (read methods only) — bounded by match + depth caps. */
+async function grepWalk(fs, dir, re, out, max, depth, gate, recordOntologyRead) {
+    if (out.length >= max || depth > 12)
+        return;
+    let entries;
+    try {
+        entries = (await fs.readdir(dir || '.'));
+    }
+    catch {
+        return;
+    }
+    // Filter unreadable KB nodes out of the walk so grep never opens — or leaks
+    // a line from — a file the caller may not read.
+    entries = await filterReadableEntries(gate, dir, entries);
+    for (const e of entries) {
+        if (out.length >= max)
+            return;
+        if (e.name === '.git' || e.name === 'node_modules')
+            continue;
+        const p = dir ? `${dir}/${e.name}` : e.name;
+        if (e.type === 'directory') {
+            await grepWalk(fs, p, re, out, max, depth + 1, gate, recordOntologyRead);
+        }
+        else {
+            // Opening a file under a named ontology is a read of that ontology — even
+            // for a root-level grep that resolves to a neutral root. Record it so a
+            // cross-ontology grep poisons later writes (closes the read-leak).
+            await recordOntologyRead(p);
+            let content;
+            try {
+                content = asText(await fs.readFile(p));
+            }
+            catch {
+                continue;
+            }
+            if (content.includes(String.fromCharCode(0)))
+                continue; // skip binary (NUL)
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length && out.length < max; i++) {
+                re.lastIndex = 0;
+                if (re.test(lines[i]))
+                    out.push({ path: p, line: i + 1, text: lines[i].slice(0, 300) });
+            }
+        }
+    }
+}
+/**
+ * Workspace domain tools: the file primitives (replacing Mastra's auto-injected
+ * Workspace tools) + unzip. Most just re-expose the SAME `LocalFilesystem`
+ * methods Mastra's tools call (via `ctx.getFilesystem(a.branch as string)`), so behaviour is
+ * identical and write-side ops still flow through the lock/commit pipeline.
+ * `edit_file`, `grep`, and `execute_command` are tool-level (no filesystem
+ * method), so they're implemented here. File ops are `both`; `execute_command`
+ * is INTERNAL-only (arbitrary shell as the caller is too dangerous to expose).
+ */
+export function registerWorkspaceTools(registry, router, toolAuth, toolHandler, spillStore, accessControl, kbDirName, sessionOntologyGate, writePolicy, sessionSink) {
+    /** Build the per-call read gate from the tool's branch input + caller identity. */
+    const readGateFor = (branch, ctx) => ({
+        accessControl,
+        kbDirName,
+        workspaceId: workspaceIdForBranch(branch),
+        userEmail: ctx.user.email,
+    });
+    const mount = (spec) => {
+        const path = `/api/agent/tools/${spec.name}`;
+        const def = toolDef({
+            name: spec.name,
+            // Every workspace entrypoint carries the CLAUDE.md reminder, appended once
+            // here so no tool (especially the read-only ones a session hits first) can
+            // miss it.
+            description: spec.description + KB_CONVENTIONS_NOTE,
+            path,
+            inputs: spec.inputs,
+            outputs: spec.outputs,
+            tags: spec.write ? ['workspace', 'write'] : ['workspace'],
+        });
+        registry.registerInternalTool(def);
+        if (!spec.internalOnly)
+            registry.registerExternalTool(def);
+        // Internal-only tools (e.g. `execute_command`) keep their route mounted —
+        // our agent calls it over the same loopback — but gate it to internal-source
+        // callers so an external connection key can't invoke it by name.
+        router.post(path.slice('/api'.length), toolAuth, ...(spec.internalOnly ? [requireInternalSource] : []), toolHandler(spec.handler, { write: spec.write }));
+    };
+    // ── session bootstrap (external agents) ─────────────────────────────────
+    // Every read/write tool below scopes the ontology-session boundary off a
+    // `sessionId`. The in-process agent carries its thread id, but an external
+    // agent has no ambient run id and so cannot satisfy the gate until it has
+    // one. This mints that id up front (called ONCE); the MCP proxy then threads
+    // it onto every later gated call via its sessionId-output continuity
+    // convention. EXTERNAL-ONLY (not registered internal): the in-process agent
+    // already supplies its session id and ignores any body value.
+    //
+    // WHAT the minted id is backed by is the `ISessionSink` port's business
+    // (session-sink.ts). In the enterprise app it is a REAL chat-thread id, so
+    // the SAME id works end to end: KB reads scope the ontology boundary under
+    // it, AND `ask` accepts it (its sessionId IS a chat thread, resolved via
+    // getThread) — that unification is what stops a caller reading from one
+    // ontology and then having `ask` write into another. In a core-only
+    // deployment (no chat/ask) the default sink mints a bare id, which is all
+    // the ontology gate needs.
+    const startSessionDef = toolDef({
+        name: 'start_session',
+        description: 'Mint the KnowledgeBase session id this run needs to read or write the knowledge ontologies. Call this ONCE, before any other KnowledgeBase tool, and only once per run — every gated tool needs the `sessionId` it returns to enforce the one-ontology-per-conversation boundary, and minting a new id mid-run resets that boundary. The id is also a chat session in the app, so you can hand the SAME id to the `ask` tool: reads and ask then share one ontology boundary. Pass the returned id explicitly as `sessionId` on every subsequent KnowledgeBase tool call (direct MCP calls and inside `call_tool_chain` alike). Returns `{ sessionId }`.',
+        path: '/api/agent/tools/start_session',
+        inputs: { type: 'object', properties: {}, additionalProperties: false },
+        outputs: {
+            type: 'object',
+            properties: { sessionId: str('The minted session id — pass it as `sessionId` on subsequent KnowledgeBase tool calls and to `ask`.') },
+            required: ['sessionId'],
+        },
+        tags: ['workspace'],
+    });
+    registry.registerExternalTool(startSessionDef);
+    // Mint the session id via the sink and return it (see comment above: one id
+    // spans start_session -> reads -> ask, closing the ontology-pollution gap).
+    router.post('/agent/tools/start_session', toolAuth, 
+    // External-only: an internal token already carries its run's sessionId, so
+    // minting a new thread mid-run would reset the ontology boundary. Note
+    // "external" includes the MCP proxy's `externalProxy` loopback tokens
+    // (OAuth/JWT MCP sessions) — the verifier resolves those to
+    // `source: 'external'`, and one such session may legitimately mint several
+    // per-chat sessionIds over its lifetime.
+    requireExternalSource, toolHandler(async (_args, ctx) => {
+        const { sessionId } = await sessionSink.createSession(ctx.user.id, new Date());
+        return { sessionId };
+    }));
+    // ── reads ──────────────────────────────────────────────────────────────
+    mount({
+        name: 'read_file',
+        description: 'Read a workspace file as text. Returns `{ path, content }`. Optional `offset`/`limit` slice the content (characters for a file, bytes for a `__tool_chain_spill__/…` ref) — use them to page through large files or a `call_tool_chain` spill rather than reading multi-MB in full. A spill ref is workspace-independent: `branch` is ignored for it.' +
+            ONTOLOGY_BOUNDARY_NOTE,
+        inputs: {
+            type: 'object',
+            properties: {
+                branch: BRANCH_INPUT,
+                path: str('Workspace-relative path, or a `__tool_chain_spill__/…` ref from a truncated `call_tool_chain`.'),
+                offset: int('Start character index (default 0).'),
+                limit: int('Max characters to return from `offset`.'),
+                sessionId: SESSION_ID_INPUT,
+            },
+            required: ['branch', 'path'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            properties: { path: str('The path that was read (echoes the input).'), content: str('File (or spill) content, sliced if offset/limit were given.') },
+            required: ['path', 'content'],
+        },
+        write: false,
+        handler: async (a, ctx) => {
+            const p = a.path;
+            const offset = typeof a.offset === 'number' ? a.offset : undefined;
+            const limit = typeof a.limit === 'number' ? a.limit : undefined;
+            if (spillStore.isSpillRef(p)) {
+                return { path: p, content: await spillStore.read(p, offset, limit) };
+            }
+            await recordOntologyRead(sessionOntologyGate, ctx, p);
+            await assertCanRead(readGateFor(a.branch, ctx), p);
+            const fs = await ctx.getFilesystem(a.branch);
+            const content = asText(await fs.readFile(p));
+            const start = offset && offset > 0 ? offset : 0;
+            const sliced = offset !== undefined || limit !== undefined
+                ? content.slice(start, limit !== undefined ? start + limit : undefined)
+                : content;
+            return { path: p, content: sliced };
+        },
+    });
+    mount({
+        name: 'list_files',
+        description: 'List a directory. Returns `{ path, entries: [{ name, type, size? }] }`. Omit `path` for the workspace root.' +
+            ONTOLOGY_BOUNDARY_NOTE,
+        inputs: {
+            type: 'object',
+            properties: {
+                branch: BRANCH_INPUT,
+                path: str('Workspace-relative directory (default: root).'),
+                sessionId: SESSION_ID_INPUT,
+            },
+            required: ['branch'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            properties: {
+                path: str('The directory listed (empty string for the root).'),
+                entries: {
+                    type: 'array',
+                    description: 'Directory entries.',
+                    items: {
+                        type: 'object',
+                        properties: { name: str('Entry name.'), type: str('`file` or `directory`.'), size: int('Size in bytes (files only).') },
+                        required: ['name', 'type'],
+                    },
+                },
+            },
+            required: ['path', 'entries'],
+        },
+        write: false,
+        handler: async (a, ctx) => {
+            const dir = a.path || '';
+            await recordOntologyRead(sessionOntologyGate, ctx, dir);
+            const fs = await ctx.getFilesystem(a.branch);
+            const entries = (await fs.readdir(dir || '.'));
+            const filtered = await filterReadableEntries(readGateFor(a.branch, ctx), dir, entries);
+            return { path: a.path ?? '', entries: filtered };
+        },
+    });
+    mount({
+        name: 'file_stat',
+        description: 'Get a file/directory\'s metadata (name, type, size, …) without reading content.' +
+            ONTOLOGY_BOUNDARY_NOTE,
+        inputs: {
+            type: 'object',
+            properties: {
+                branch: BRANCH_INPUT,
+                path: str('Workspace-relative path.'),
+                sessionId: SESSION_ID_INPUT,
+            },
+            required: ['branch', 'path'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            description: "The filesystem entry's metadata.",
+            properties: { name: str('Entry name.'), type: str('`file` or `directory`.'), size: int('Size in bytes.') },
+            additionalProperties: true,
+        },
+        write: false,
+        handler: async (a, ctx) => {
+            const p = a.path;
+            await recordOntologyRead(sessionOntologyGate, ctx, p);
+            await assertCanRead(readGateFor(a.branch, ctx), p);
+            return (await ctx.getFilesystem(a.branch)).stat(p);
+        },
+    });
+    mount({
+        name: 'grep',
+        description: 'Regex content search across the workspace. Returns `{ matches: [{ path, line, text }] }` (capped). Use to find where something is defined/referenced.' +
+            ONTOLOGY_BOUNDARY_NOTE,
+        inputs: {
+            type: 'object',
+            properties: {
+                branch: BRANCH_INPUT,
+                pattern: str('JavaScript regular expression.'),
+                path: str('Subtree to search (default: whole workspace).'),
+                ignore_case: { type: 'boolean', description: 'Case-insensitive match.' },
+                max_results: { type: 'integer', minimum: 1, maximum: 1000, description: 'Cap on matches (default 200).' },
+                sessionId: SESSION_ID_INPUT,
+            },
+            required: ['branch', 'pattern'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            properties: {
+                matches: {
+                    type: 'array',
+                    description: 'Matching lines (capped by `max_results`).',
+                    items: {
+                        type: 'object',
+                        properties: { path: str('Workspace-relative file path.'), line: int('1-based line number.'), text: str('The matching line (truncated to 300 chars).') },
+                        required: ['path', 'line', 'text'],
+                    },
+                },
+                truncated: { type: 'boolean', description: 'True if the match cap was hit and results may be incomplete.' },
+            },
+            required: ['matches', 'truncated'],
+        },
+        write: false,
+        handler: async (a, ctx) => {
+            let re;
+            try {
+                re = new RegExp(a.pattern, a.ignore_case ? 'i' : '');
+            }
+            catch (err) {
+                throw new ToolError(`Invalid regex: ${err.message}`, 400);
+            }
+            const searchRoot = typeof a.path === 'string' ? a.path : '';
+            // The search root itself is checked here (fail-closed for an agent grep on
+            // a named subtree with no sessionId); each file the walk actually opens is
+            // recorded per-file below, so a root-level grep that reaches into multiple
+            // ontologies still records each one (and can poison later writes).
+            await recordOntologyRead(sessionOntologyGate, ctx, searchRoot);
+            const out = [];
+            const max = typeof a.max_results === 'number' ? Math.min(a.max_results, 1000) : 200;
+            await grepWalk(await ctx.getFilesystem(a.branch), searchRoot, re, out, max, 0, readGateFor(a.branch, ctx), (p) => recordOntologyRead(sessionOntologyGate, ctx, p));
+            return { matches: out, truncated: out.length >= max };
+        },
+    });
+    // ── writes (through the lock/commit pipeline) ───────────────────────────
+    mount({
+        name: 'write_file',
+        description: 'Write (create or overwrite) a workspace file. The change is committed + pushed as you. Returns `{ path, bytes }`.' +
+            ONTOLOGY_BOUNDARY_NOTE,
+        inputs: {
+            type: 'object',
+            properties: {
+                branch: BRANCH_INPUT,
+                path: str('Workspace-relative path.'),
+                content: str('Full file content.'),
+                sessionId: SESSION_ID_INPUT,
+            },
+            required: ['branch', 'path', 'content'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            properties: { path: str('The path written (echoes the input).'), bytes: int('Number of bytes written.') },
+            required: ['path', 'bytes'],
+        },
+        write: true,
+        handler: async (a, ctx) => {
+            // NB: this is a no-op for chat + `ontology_ingest` — it only bites when a
+            // routine executor has explicitly restricted THIS session's `ctx.sessionId`
+            // (today only `watchlist_check`, to `.html`). Unrestricted sessions pass straight
+            // through (see `assertPathWritable`), so it does not limit other agents.
+            writePolicy.assertPathWritable(ctx.sessionId, a.path);
+            await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.path);
+            const fs = await ctx.getFilesystem(a.branch);
+            await fs.writeFile(a.path, a.content);
+            return { path: a.path, bytes: Buffer.byteLength(a.content, 'utf8') };
+        },
+    });
+    mount({
+        name: 'write_files',
+        description: 'Batch-write many files in ONE commit — far faster than calling write_file once per file when ' +
+            'creating many files at once (e.g. seeding a knowledge base). Each entry is `{ path, content }`; all ' +
+            'are created/overwritten and committed + pushed together as you. Prefer this over many write_file ' +
+            'calls. All files must be in the SAME ontology (the boundary below applies to the batch). Returns `{ count }`.' +
+            ONTOLOGY_BOUNDARY_NOTE,
+        inputs: {
+            type: 'object',
+            properties: {
+                branch: BRANCH_INPUT,
+                files: {
+                    type: 'array',
+                    description: 'Files to write; each created or overwritten.',
+                    items: {
+                        type: 'object',
+                        properties: { path: str('Workspace-relative path.'), content: str('Full file content.') },
+                        required: ['path', 'content'],
+                        additionalProperties: false,
+                    },
+                },
+                sessionId: SESSION_ID_INPUT,
+            },
+            required: ['branch', 'files'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            properties: { count: int('Number of files written.') },
+            required: ['count'],
+        },
+        write: true,
+        handler: async (a, ctx) => {
+            const files = a.files ?? [];
+            if (files.length === 0)
+                return { count: 0 };
+            // Gate every path first (records ontology touches; a cross-ontology batch
+            // is blocked exactly like the per-file write tools).
+            for (const f of files)
+                writePolicy.assertPathWritable(ctx.sessionId, f.path);
+            for (const f of files)
+                await assertOntologyWriteAllowed(sessionOntologyGate, ctx, f.path);
+            // `write: true` guarantees a LockingFilesystem here; `writeFiles` lands the
+            // whole batch as one commit. Structural cast avoids a workflow-internal import.
+            const fs = (await ctx.getFilesystem(a.branch));
+            await fs.writeFiles(files.map((f) => ({ path: f.path, content: f.content })), `Write ${files.length} file(s)`);
+            return { count: files.length };
+        },
+    });
+    mount({
+        name: 'edit_file',
+        description: 'Replace an exact string in a workspace file. `old_string` must appear exactly once unless `replace_all`. Committed + pushed as you.' +
+            ONTOLOGY_BOUNDARY_NOTE,
+        inputs: {
+            type: 'object',
+            properties: {
+                branch: BRANCH_INPUT,
+                path: str('Workspace-relative path.'),
+                old_string: str('Exact text to replace (include enough context to be unique).'),
+                new_string: str('Replacement text.'),
+                replace_all: { type: 'boolean', description: 'Replace every occurrence instead of requiring a unique match.' },
+                sessionId: SESSION_ID_INPUT,
+            },
+            required: ['branch', 'path', 'old_string', 'new_string'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            properties: { path: str('The path edited (echoes the input).'), replaced: int('Number of occurrences replaced.') },
+            required: ['path', 'replaced'],
+        },
+        write: true,
+        handler: async (a, ctx) => {
+            writePolicy.assertPathWritable(ctx.sessionId, a.path);
+            await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.path);
+            const fs = await ctx.getFilesystem(a.branch);
+            const path = a.path;
+            const oldStr = a.old_string;
+            const newStr = a.new_string;
+            const content = asText(await fs.readFile(path));
+            const count = oldStr ? content.split(oldStr).length - 1 : 0;
+            if (count === 0)
+                throw new ToolError('old_string not found in the file.', 400);
+            if (count > 1 && a.replace_all !== true) {
+                throw new ToolError(`old_string appears ${count} times — add more context to make it unique, or set replace_all.`, 400);
+            }
+            const updated = a.replace_all === true ? content.split(oldStr).join(newStr) : content.replace(oldStr, newStr);
+            await fs.writeFile(path, updated);
+            return { path, replaced: a.replace_all === true ? count : 1 };
+        },
+    });
+    mount({
+        name: 'delete_file',
+        description: 'Delete a workspace file. Committed + pushed as you.' + ONTOLOGY_BOUNDARY_NOTE,
+        inputs: {
+            type: 'object',
+            properties: {
+                branch: BRANCH_INPUT,
+                path: str('Workspace-relative path.'),
+                sessionId: SESSION_ID_INPUT,
+            },
+            required: ['branch', 'path'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            properties: { path: str('The path deleted (echoes the input).'), deleted: { type: 'boolean', description: 'Always true on success.' } },
+            required: ['path', 'deleted'],
+        },
+        write: true,
+        handler: async (a, ctx) => {
+            // A delete propagates no cross-ontology information (it removes a node, it
+            // doesn't carry bytes from elsewhere), so it is NOT ontology-write-gated — it
+            // only records the ontology it touched, like a read. The extension policy
+            // DOES apply though: a dashboard-only run must not delete graph `.md` nodes.
+            writePolicy.assertPathWritable(ctx.sessionId, a.path);
+            await recordOntologyRead(sessionOntologyGate, ctx, a.path);
+            await (await ctx.getFilesystem(a.branch)).deleteFile(a.path);
+            return { path: a.path, deleted: true };
+        },
+    });
+    mount({
+        name: 'mkdir',
+        description: 'Create a directory (recursive). An empty dir gets a `.gitkeep` so it persists in git.' + ONTOLOGY_BOUNDARY_NOTE,
+        inputs: {
+            type: 'object',
+            properties: {
+                branch: BRANCH_INPUT,
+                path: str('Workspace-relative directory.'),
+                sessionId: SESSION_ID_INPUT,
+            },
+            required: ['branch', 'path'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            properties: { path: str('The directory created (echoes the input).'), created: { type: 'boolean', description: 'Always true on success.' } },
+            required: ['path', 'created'],
+        },
+        write: true,
+        handler: async (a, ctx) => {
+            writePolicy.assertPathWritable(ctx.sessionId, a.path);
+            await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.path);
+            await (await ctx.getFilesystem(a.branch)).mkdir(a.path, { recursive: true });
+            return { path: a.path, created: true };
+        },
+    });
+    mount({
+        name: 'move_file',
+        description: 'Move/rename a workspace file. Lands as a delete + create. Committed + pushed as you.' + ONTOLOGY_BOUNDARY_NOTE,
+        inputs: {
+            type: 'object',
+            properties: {
+                branch: BRANCH_INPUT,
+                src: str('Source path.'),
+                dest: str('Destination path.'),
+                sessionId: SESSION_ID_INPUT,
+            },
+            required: ['branch', 'src', 'dest'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            properties: { src: str('Source path (echoes the input).'), dest: str('Destination path (echoes the input).'), moved: { type: 'boolean', description: 'Always true on success.' } },
+            required: ['src', 'dest', 'moved'],
+        },
+        write: true,
+        handler: async (a, ctx) => {
+            // A move CARRIES the source content into the destination — a genuine
+            // cross-ontology flow if the two differ — so BOTH endpoints are write-gated
+            // (unlike a plain delete, which moves no content). Check both BEFORE
+            // touching disk so a blocked endpoint can't leave the source already deleted.
+            writePolicy.assertPathWritable(ctx.sessionId, a.src);
+            writePolicy.assertPathWritable(ctx.sessionId, a.dest);
+            await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.src);
+            await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.dest);
+            await (await ctx.getFilesystem(a.branch)).moveFile(a.src, a.dest);
+            return { src: a.src, dest: a.dest, moved: true };
+        },
+    });
+    mount({
+        name: 'copy_file',
+        description: 'Copy a workspace file to a new path. Committed + pushed as you.' + ONTOLOGY_BOUNDARY_NOTE,
+        inputs: {
+            type: 'object',
+            properties: {
+                branch: BRANCH_INPUT,
+                src: str('Source path.'),
+                dest: str('Destination path.'),
+                sessionId: SESSION_ID_INPUT,
+            },
+            required: ['branch', 'src', 'dest'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            properties: { src: str('Source path (echoes the input).'), dest: str('Destination path (echoes the input).'), copied: { type: 'boolean', description: 'Always true on success.' } },
+            required: ['src', 'dest', 'copied'],
+        },
+        write: true,
+        handler: async (a, ctx) => {
+            // A copy CARRIES the source content into the destination — a genuine
+            // cross-ontology flow if the two differ — so BOTH endpoints are write-gated.
+            // Check both before touching disk.
+            writePolicy.assertPathWritable(ctx.sessionId, a.src);
+            writePolicy.assertPathWritable(ctx.sessionId, a.dest);
+            await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.src);
+            await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.dest);
+            await (await ctx.getFilesystem(a.branch)).copyFile(a.src, a.dest);
+            return { src: a.src, dest: a.dest, copied: true };
+        },
+    });
+    mount({
+        name: 'unzip',
+        description: 'Extract a .zip already in the workspace (defaults to the zip\'s parent). Returns extracted files + skipped entries. Existing files are overwritten.' +
+            ONTOLOGY_BOUNDARY_NOTE,
+        inputs: {
+            type: 'object',
+            properties: {
+                branch: BRANCH_INPUT,
+                path: str('Workspace-relative .zip path.'),
+                destination: str("Directory to extract into (default: the zip's parent)."),
+                sessionId: SESSION_ID_INPUT,
+            },
+            required: ['branch', 'path'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            properties: {
+                destination: str('Directory the archive was extracted into.'),
+                extracted: { type: 'array', items: { type: 'string' }, description: 'Workspace-relative paths of the files written.' },
+                skipped: {
+                    type: 'array',
+                    description: 'Entries that were not extracted, with the reason.',
+                    items: {
+                        type: 'object',
+                        properties: { path: str('Entry path inside the archive.'), reason: str('Why it was skipped (e.g. unsafe path, size cap).') },
+                        required: ['path', 'reason'],
+                    },
+                },
+            },
+            required: ['destination', 'extracted', 'skipped'],
+        },
+        write: true,
+        handler: async (a, ctx) => {
+            const zipPath = a.path;
+            // Reading the source archive pins/records the source ontology, so a session
+            // can't unzip from ontology A into ontology B without the A read counting.
+            await recordOntologyRead(sessionOntologyGate, ctx, zipPath);
+            return ctx.workspaceService.unzipFile(workspaceIdForBranch(a.branch), zipPath, typeof a.destination === 'string' ? a.destination : undefined, 
+            // Each extracted file is a write: a cross-ontology or write-blocked entry
+            // is skipped (not extracted), so an archive can't bypass the boundary — the
+            // extension policy applies per entry too, so a restricted run can't unzip a
+            // `.md` into the graph.
+            (wsRelPath) => {
+                writePolicy.assertPathWritable(ctx.sessionId, wsRelPath);
+                return assertOntologyWriteAllowed(sessionOntologyGate, ctx, wsRelPath);
+            });
+        },
+    });
+    // ── shell (internal-only) ───────────────────────────────────────────────
+    mount({
+        name: 'execute_command',
+        description: 'Run a shell command in the workspace directory. Returns `{ stdout, stderr, exitCode }` (output capped). Use for git status/log, grep/rg, build/test commands.' +
+            ONTOLOGY_BOUNDARY_NOTE,
+        internalOnly: true,
+        inputs: {
+            type: 'object',
+            properties: {
+                branch: BRANCH_INPUT,
+                command: str('The shell command line to run.'),
+                timeout_ms: { type: 'integer', minimum: 1000, maximum: 120000, description: 'Timeout in ms (default 30000).' },
+                sessionId: SESSION_ID_INPUT,
+            },
+            required: ['branch', 'command'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            properties: {
+                stdout: str('Captured standard output (truncated to 50,000 chars).'),
+                stderr: str('Captured standard error (truncated to 50,000 chars).'),
+                exitCode: int('Process exit code; -1 if it was killed (timeout/abort) or failed to spawn.'),
+            },
+            required: ['stdout', 'stderr', 'exitCode'],
+        },
+        write: true,
+        handler: async (a, ctx) => {
+            // Refuse a missing branch FIRST — before the policy gates below — so a
+            // malformed call always gets the 400 that names what is missing, rather
+            // than a 403 from a restricted session masking it. Unlike the file tools
+            // (which route through `getOrCreateForUser` and fall back to the default
+            // branch), execute_command turns `branch` straight into a workspace — so
+            // an absent value would `encodeURIComponent(undefined)` to the string
+            // "undefined", then try to CLONE a branch literally named "undefined",
+            // 500ing and leaving an `<workspaces>/undefined/` shell behind. Fail with
+            // a clear 4xx naming the missing context instead.
+            const branch = a.branch;
+            if (typeof branch !== 'string' || branch.trim().length === 0) {
+                throw new ToolError('execute_command requires a `branch`: pass the branch (draft) whose workspace to run the command in — the one you are currently working on.', 400);
+            }
+            // Then the SHAPE of the value, via the one canonical validator every other
+            // branch path uses — no hand-maintained list of suspicious literals here,
+            // which would both miss malformed refs (`..`, `-x`, `foo/.lock`) and
+            // reserve names git considers perfectly valid. Note this runs on the RAW
+            // string: a whitespace-padded `" main "` is refused rather than silently
+            // trimmed into a different branch than the caller passed.
+            try {
+                assertValidBranchName(branch);
+            }
+            catch (err) {
+                throw new ToolError(`execute_command got an invalid \`branch\`: ${err.message} — ` +
+                    'pass the exact branch (draft) whose workspace to run the command in.', 400);
+            }
+            // Shell is a write path with no single target path to check, so enforce the
+            // boundary at the session level: refuse once the run is already write-blocked,
+            // or when the run is restricted to a file type (shell could write anything).
+            writePolicy.assertUnrestricted(ctx.sessionId);
+            await assertShellAllowedWithinOntology(sessionOntologyGate, ctx);
+            // Canonical per-branch bootstrap entry point — it owns the workspace-id
+            // encoding and the single-flight clone, so the shell never derives a
+            // workspace path by hand.
+            const cwd = (await ctx.workspaceService.getOrCreateForBranch(branch)).absolutePath;
+            const timeoutMs = typeof a.timeout_ms === 'number' ? a.timeout_ms : 30_000;
+            // cwd is the workspace ROOT so shell paths match the workspace-relative
+            // paths every other file tool uses — but the git clone lives one level
+            // deeper, at <workspace>/<kbDirName>/.git. For a bare `git status` /
+            // `git diff` (what the agent prompt teaches) point git there explicitly so
+            // it resolves the KB clone instead of failing with "not a git repository".
+            //
+            // Because the command runs under `shell: true`, GIT_DIR/GIT_WORK_TREE
+            // apply to the WHOLE shell, so restrict the override to a *standalone* bare
+            // `git …` invocation. Otherwise the KB repo context would (a) leak into a
+            // chained step that spawns its own git — `git commit && npm ci` — and (b)
+            // override a caller's explicit `git -C …` / `--git-dir` / `--work-tree`.
+            const command = a.command.trim();
+            const isStandaloneGit = /^git(\s|$)/.test(command) &&
+                !/[;&|`\n]|\$\(/.test(command) &&
+                !/(?:^|\s)(?:-C|--git-dir|--work-tree)(?:[=\s]|$)/.test(command);
+            const env = isStandaloneGit
+                ? {
+                    ...process.env,
+                    GIT_DIR: join(cwd, kbDirName, '.git'),
+                    GIT_WORK_TREE: join(cwd, kbDirName),
+                }
+                : process.env;
+            return new Promise((resolve) => {
+                const child = spawn(a.command, { cwd, shell: true, env });
+                let stdout = '';
+                let stderr = '';
+                const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
+                // If the caller disconnects (request aborted), kill the child instead of
+                // letting it run to the timeout; the resulting `close`/`error` settles
+                // the promise through `finish`.
+                const onAbort = () => child.kill('SIGKILL');
+                ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+                const finish = (value) => {
+                    clearTimeout(timer);
+                    ctx.abortSignal.removeEventListener('abort', onAbort);
+                    resolve(value);
+                };
+                // Cap accumulation while streaming so a verbose command can't exhaust
+                // memory before `close`; the final slice keeps the output bound.
+                const OUTPUT_CAP = 50_000;
+                child.stdout.on('data', (d) => {
+                    if (stdout.length < OUTPUT_CAP)
+                        stdout += d.toString();
+                });
+                child.stderr.on('data', (d) => {
+                    if (stderr.length < OUTPUT_CAP)
+                        stderr += d.toString();
+                });
+                child.on('close', (code) => {
+                    finish({ stdout: stdout.slice(0, 50_000), stderr: stderr.slice(0, 50_000), exitCode: code ?? -1 });
+                });
+                child.on('error', (err) => {
+                    finish({ stdout, stderr: `${stderr}\n${String(err)}`.slice(0, 50_000), exitCode: -1 });
+                });
+            });
+        },
+    });
+}
+//# sourceMappingURL=workspace.tools.js.map