Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

feat(agent): surgical edit, content search, glob and a todo list (#173)

Abdurrahman Fakhrula9d7a3116f87
diff --git a/docs/AGENT-CODING-PLAN.md b/docs/AGENT-CODING-PLAN.md
new file mode 100644
index 00000000..6ad45ecb
--- /dev/null
+++ b/docs/AGENT-CODING-PLAN.md
@@ -0,0 +1,78 @@
+# MSO Agent: coding capability plan
+
+Written before implementation. Audited against what MSO already has, not against wishes.
+
+## Audit: what already exists
+
+113 MCP tools are registered. For "agent that can code", most of the substrate is present:
+
+| Capability | MSO today | Verdict |
+|---|---|---|
+| Read file | `fs_read`, `read_pipeline` (bounded) | exists |
+| Write whole file | `fs_write` | exists |
+| List dir | `fs_list`, `fs_stat` | exists |
+| Shell command | `exec_run` (30s), `exec_job_start`/`status`/`cancel` (bounded async) | exists |
+| Subagent | `agent_subagent_run` (foreground, isolated context, server-capped turns) | exists |
+| Session/handoff | `agent_session_*`, `local_agent_*`, A2A v1 | exists |
+| Skills | `skills_list/read/search` | exists |
+| Project awareness | `projects_list`, `project_*` | exists |
+| PTY | `mso term open/input/resize/stream/close` (CLI only, not an agent tool) | partial |
+
+## The real gaps, ranked by how much they block coding
+
+### GAP-1 (blocker): no surgical edit tool
+
+There is no `oldString`/`newString` edit. An agent must rewrite a whole file with `fs_write`
+to change one line. That is the single biggest difference from Claude Code and opencode,
+and it is also the most dangerous: a full rewrite loses everything the agent did not
+re-read, and a large file may exceed the bounded write.
+
+### GAP-2 (blocker): search cannot see file contents
+
+`searchFs` returns directories whose NAME matches. There is no content search, no glob, no
+"where is this symbol defined". An agent working in a 200k-LOC repo is blind.
+
+### GAP-3 (high): no background/parallel subagents
+
+`agent_subagent_run` is foreground only. Claude Code runs subagents in parallel and the
+parent keeps working. MSO blocks on one worker.
+
+### GAP-4 (high): no todo/plan checklist
+
+Nothing tracks multi-step work as a visible list. Long tasks drift.
+
+### GAP-5 (medium): no shell-out PTY or interactive command for the agent
+
+`exec_run` is one-shot, 30s, no interactivity. Long builds need `exec_job_start` (exists) but
+an interactive process cannot be driven.
+
+### GAP-6 (medium): the TUI cannot show a diff before writing
+
+`/diff` renders the server's historical artifact diff. There is no preview of a pending edit.
+
+## What I will build, in this order
+
+| # | Item | Seam it uses | Why this order |
+|---|---|---|---|
+| 1 | `fs_edit` tool: exact `oldString` → `newString`, unique-match required, `expected_sha256` to refuse stale writes | existing `fs_write` plumbing + `fs_stat` hash | unblocks all real editing |
+| 2 | `fs_grep` tool: content regex over a bounded tree, returns path:line, respects read roots and size caps | new leaf beside `fs_search` | unblocks navigation |
+| 3 | `fs_glob` tool: path glob (`**/*.ts`) bounded by root | same leaf | cheap once grep exists |
+| 4 | `todo_write` tool: session-scoped checklist the TUI renders | session store | keeps long tasks honest |
+| 5 | Background subagent: `agent_subagent_start` + `agent_subagent_status` | existing subagent runner + `exec_job_*` lifecycle pattern | enables parallelism |
+| 6 | TUI: render todo list, and `fs_edit` preview | `mso-agent-layout.mjs` section helpers | visibility |
+
+## Non-negotiable constraints
+
+- Every new tool is bounded: max bytes, max matches, max depth, abort signal.
+- Every write tool keeps the read-root/write-root guard and the credential denylist.
+- No tool may read `~/.mso`, `~/.ssh`, or any store path.
+- New tools go through the same audit trail as `fs_write`.
+- Ratchets hold. No file over the limits; split instead.
+- `fs_edit` refuses when the match is not unique, and refuses when `expected_sha256` does
+ not match. A silent wrong edit is worse than a failed one.
+
+## Explicitly not in scope
+
+- A new TUI renderer. That is the separate Phase 2 item in `docs/TUI-PARITY-PLAN.md`.
+- Auto-commit, auto-push, or any git mutation. The agent may propose; the owner ships.
+- Porting opencode's exact UI. The goal is capability parity for coding, not visual cloning.
diff --git a/docs/BENCH-BEFORE.md b/docs/BENCH-BEFORE.md
new file mode 100644
index 00000000..12300b86
--- /dev/null
+++ b/docs/BENCH-BEFORE.md
@@ -0,0 +1,101 @@
+# Phase 4/5 comparison: before
+
+Baseline captured on `062fe18`, host idle (**load average 0.15–0.42**), 2026-10-29.
+Every number here is measured, not estimated. "After" columns stay empty until the work lands.
+
+Regenerate with the commands named under each table.
+
+## 1. Bundle (deterministic, from build output)
+
+`node scripts/check-bundle.mjs --json`
+
+| Part | Raw bytes | Gzip bytes | Gzip KiB | Files |
+|---|---|---|---|---|
+| initial | 870,887 | 277,248 | 270.8 | 18 |
+| entry | 426,778 | 144,578 | 141.2 | 13 |
+| runtime (framework) | 444,109 | 132,670 | **129.6** | 5 |
+| css | 188,715 | 30,721 | 30.0 | 2 |
+| fonts | 69,652 | 69,695 | 68.1 | 1 |
+
+Heavy eager modules (`ReactFlow`, `Konva`, `Xterm`, `ONNX`) leaking into the first-load graph: **0**.
+Next version measured: 16.4.2.
+
+Framework share of the initial bundle: 132,670 / 277,248 = **47.9 %**.
+
+## 2. Perceived performance (Slow 4G + 4× CPU, browser)
+
+`node scripts/perf-probe.mjs --json`, 3 runs. Median shown; range in brackets.
+
+| Metric | Desktop 1440×900 | Mobile 390×844 |
+|---|---|---|
+| FCP | 1,164 ms (1,160–1,168) | 1,169 ms (1,164–1,172) |
+| **LCP** | **3,152 ms** (3,152–3,232) | **2,956 ms** (2,952–3,028) |
+| **TBT** | **173 ms** (161–186) | **101 ms** (90–114) |
+| first-load JS | 910.2 KiB | 894.1 KiB |
+
+## 3. Hydration mark chain
+
+`node scripts/perf-hydration.mjs --base=http://127.0.0.1:4005`
+
+| Mark | Desktop | Mobile |
+|---|---|---|
+| FCP | 1,180 ms | 1,160 ms |
+| last JS byte | 2,804 ms | 2,746 ms |
+| shell mounted | 2,523 ms | 2,529 ms |
+| icons painted | 3,078 ms | 2,963 ms |
+| **LCP** | **3,132 ms** | **2,996 ms** |
+| LCP element | `SPAN` (menu-bar label) | `IMG` (app artwork) |
+| mount after FCP | +1,343 ms | +1,369 ms |
+| LCP after FCP | +1,952 ms | +1,836 ms |
+| LCP after last JS | +328 ms | +250 ms |
+
+The chain is the reason LCP is what it is: the shell mounts only after ~910 KiB of JS has
+arrived and executed, and LCP lands after that. LCP is **hydration-bound**, not paint-bound.
+
+## 4. Per-app open cost (4× CPU, cold context per app)
+
+`node scripts/perf-app-open.mjs --base=http://127.0.0.1:4005`
+
+| App | Open | Chunks pulled | Long task |
+|---|---|---|---|
+| Image Editor | 618 ms | 8 | 732 ms |
+| Video Editor | 566 ms | 4 | 371 ms |
+| Terminal | 219 ms | 3 | 63 ms |
+| System Monitor | 192 ms | 2 | 68 ms |
+
+## 5. Code and test surface
+
+| Measure | Value |
+|---|---|
+| TS/TSX files | 2,688 |
+| TS/TSX LOC | 204,905 |
+| `.svelte` files | **0** |
+| `lib/` LOC (framework-free since Phase 2) | 100,787 |
+| `frontend/slices` LOC | 74,209 |
+| — of which `appshell` | 20,028 |
+| Route handlers | 117 |
+| — of which > 15 LOC | **0** |
+| Static `next/*` imports in `lib/` | **0** |
+| Runtime dependencies | 33 |
+| Dev dependencies | 18 |
+| `node_modules` | 1,435 MB |
+| — of which `next` | 210 MB |
+| Test files | 873 |
+| Test wall time | **34.82 s**, 877 files / 5,730 tests, 380 MB RSS |
+
+## 6. What this baseline says about the remaining work
+
+From `docs/MSO-MIGRATION.md` §5, with the appshell inventory measured in §4 Phase 5:
+
+```
+framework floor now 132,670 B gzip (129.6 KiB, 47.9 % of initial)
+framework floor if swapped 33,070 B gzip (§2.1, measured in a real build)
+first-load JS now 910.2 KiB (browser-measured)
+first-load if swapped ~150-165 KiB (projected, app code 115-130 KiB)
+
+appshell to re-express 20,028 LOC => 166-239 days
+slices to re-express 54,181 LOC => 452-677 days
+```
+
+That is the "after" target this comparison will be measured against. It is 618–916 days of
+work, so this document tracks increments, not a single leap.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index dc40484c..af44ebb8 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,6 +8,7 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh
**Added**
+- `agent` surgical edit, content search, glob and a todo list
- `perf` hydration mark chain, and the LCP conclusion it overturns
- `tui` close the opencode TUI gap on the seams MSO already owns (#166)
@@ -33,6 +34,7 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh
**Docs**
+- `bench` capture the measured before-baseline for the Phase 4/5 comparison
- `migration` Phase 5 edge-behaviour spike, verified with curl
- `progress` record Phase 2 completion, the bun install fix and the Phase 6 no-go
- `progress` record the perf gate and the numbers it retracted
diff --git a/docs/README.md b/docs/README.md
index dc268e53..7797a843 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -31,6 +31,7 @@ evidence and review freshness. The repository quality gate runs both automatical
| [`GATEWAY.md`](./GATEWAY.md) | Provider-neutral gateway state, health, ownership, supervisor and deployment contract |
| [`COGNITIVE-RUNTIME.md`](./COGNITIVE-RUNTIME.md) | Provider-neutral MCP/session/context/tool-routing runtime and benchmark contract |
| [`AGENT-BOOTSTRAP.md`](./AGENT-BOOTSTRAP.md) | Canonical first-call sequence and capability-parity matrix across CLI, MCP, and Alfa |
+| [`AGENT-CODING-PLAN.md`](./AGENT-CODING-PLAN.md) | Audited coding-capability gaps in the MCP catalog, the four tools added to close them, and what stays out of scope |
| [`RASMIC.md`](./RASMIC.md) | Risk-aware orchestration, repo-local memory/evidence, collision detection and recipe/script promotion |
| [`MEMORY-GRAPH.md`](./MEMORY-GRAPH.md) | Owner Memory app: vault notes, project knowledge, agent memory, layouts and limits |
| [`AGENT-VAULT.md`](./AGENT-VAULT.md) | Separate private repository agent-progress vaults, source/data boundaries and Obsidian use |
@@ -121,6 +122,7 @@ source comments. They are **not current implementation contracts**.
| [`DRAWER-MENU-BYOK-PLAN.md`](./DRAWER-MENU-BYOK-PLAN.md) | Historical implementation plan; phases A–C and OpenAI Codex D1 shipped; remaining ideas are not promises |
| [`OS-SETTINGS-ICON-UPDATE-DEVICE-PLAN.md`](./OS-SETTINGS-ICON-UPDATE-DEVICE-PLAN.md) | **Open plan, not implemented**: auto-update opt-in, stable channel, Devices/Server merge, account icon picker, upload→WebP/ICO pipeline |
| [`MSO-MIGRATION.md`](./MSO-MIGRATION.md) | **Open plan, not implemented**: measured baseline plus phased Next→Svelte/Bun/Rust migration with a decision gate before any rewrite |
+| [`BENCH-BEFORE.md`](./BENCH-BEFORE.md) | **Measured baseline, 2026-10-29**: bundle, LCP/TBT, hydration chain, per-app open cost and code surface, captured on an idle host as the "before" side of the Phase 4/5 comparison |
| [`MIGRATION-GATE-PLAN.md`](./MIGRATION-GATE-PLAN.md) | Executed migration-gate work: which §3 items landed with measurements, which were blocked and why, and the `lib/` framework-import debt |
## Marketing/demo collateral
diff --git a/docs/generated/MCP-CATALOG.md b/docs/generated/MCP-CATALOG.md
index 9b3d06fe..269e8797 100644
--- a/docs/generated/MCP-CATALOG.md
+++ b/docs/generated/MCP-CATALOG.md
@@ -4,21 +4,21 @@
## Full MSO catalog
-<!-- mcp-toolset: server=1.17.0 version=2026.10.18.3 tools=119 read=59 write=37 exec=23 -->
+<!-- mcp-toolset: server=1.17.0 version=2026.10.18.3 tools=123 read=61 write=39 exec=23 -->
| Fact | Current source value |
|---|---:|
| MCP server | `1.17.0` |
| Toolset | `2026.10.18.3` |
| Toolset changed at | `2026-10-18T13:24:00+00:00` |
-| Transport tools | **121** |
-| Model/operator tools | **119** |
-| Read | **59** |
-| Write | **37** |
+| Transport tools | **125** |
+| Model/operator tools | **123** |
+| Read | **61** |
+| Write | **39** |
| Exec | **23** |
| App-only bridges | **2** |
-### Read (59)
+### Read (61)
- `a2a_agent_discover`
- `a2a_agents_list`
@@ -41,6 +41,8 @@
- `flow_catalog`
- `flow_status`
- `fs_export_file`
+- `fs_glob`
+- `fs_grep`
- `fs_list`
- `fs_read`
- `fs_search`
@@ -80,7 +82,7 @@
- `tool_forge_candidates`
- `vps_status`
-### Write (37)
+### Write (39)
- `a2a_agent_register`
- `a2a_agent_remove`
@@ -96,6 +98,7 @@
- `flow_manage`
- `fs_copy`
- `fs_delete`
+- `fs_edit`
- `fs_mkdir`
- `fs_move`
- `fs_upload_file`
@@ -115,6 +118,7 @@
- `project_script_run`
- `session_artifact_register`
- `session_artifacts_cleanup`
+- `todo_write`
- `tool_forge_propose`
- `workflow_cancel`
- `workflow_finish`
@@ -153,20 +157,20 @@
## ChatGPT model profile
-<!-- mcp-chatgpt-profile: server=1.17.0 version=2026.10.18.3 tools=119 read=59 write=37 exec=23 app-only=2 total=121 -->
+<!-- mcp-chatgpt-profile: server=1.17.0 version=2026.10.18.3 tools=123 read=61 write=39 exec=23 app-only=2 total=125 -->
The ChatGPT profile automatically projects the complete MSO-owned generic model/operator catalog. OAuth scope is still enforced independently; app-only compatibility bridges stay app-only, and project-owned MCP tool names remain dynamic data behind the generic project bridge.
| Fact | Current source value |
|---|---:|
-| ChatGPT transport tools | **121** |
-| ChatGPT model/operator tools | **119** |
-| Read | **59** |
-| Write | **37** |
+| ChatGPT transport tools | **125** |
+| ChatGPT model/operator tools | **123** |
+| Read | **61** |
+| Write | **39** |
| Exec | **23** |
| App-only bridges | **2** |
-### ChatGPT read (59)
+### ChatGPT read (61)
- `a2a_agent_discover`
- `a2a_agents_list`
@@ -189,6 +193,8 @@ The ChatGPT profile automatically projects the complete MSO-owned generic model/
- `flow_catalog`
- `flow_status`
- `fs_export_file`
+- `fs_glob`
+- `fs_grep`
- `fs_list`
- `fs_read`
- `fs_search`
@@ -228,7 +234,7 @@ The ChatGPT profile automatically projects the complete MSO-owned generic model/
- `tool_forge_candidates`
- `vps_status`
-### ChatGPT write (37)
+### ChatGPT write (39)
- `a2a_agent_register`
- `a2a_agent_remove`
@@ -244,6 +250,7 @@ The ChatGPT profile automatically projects the complete MSO-owned generic model/
- `flow_manage`
- `fs_copy`
- `fs_delete`
+- `fs_edit`
- `fs_mkdir`
- `fs_move`
- `fs_upload_file`
@@ -263,6 +270,7 @@ The ChatGPT profile automatically projects the complete MSO-owned generic model/
- `project_script_run`
- `session_artifact_register`
- `session_artifacts_cleanup`
+- `todo_write`
- `tool_forge_propose`
- `workflow_cancel`
- `workflow_finish`
diff --git a/lib/agent/todos.test.ts b/lib/agent/todos.test.ts
new file mode 100644
index 00000000..413c0447
--- /dev/null
+++ b/lib/agent/todos.test.ts
@@ -0,0 +1,116 @@
+import { afterAll, describe, expect, it, vi } from "vitest";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { AgentTodoItem, AgentTodoSummary } from "./todos";
+
+const root = await fs.mkdtemp(path.join(os.tmpdir(), "mso-agent-todos-p0-"));
+const sessions = path.join(root, "sessions");
+process.env.OS_AGENT_SESSIONS_DIR = sessions;
+process.env.OS_AGENT_MEMORY_DIR = path.join(root, "memory");
+process.env.OS_AGENT_SESSION_ARCHIVE_DIR = path.join(root, "archives");
+process.env.OS_AGENT_SESSION_PRESERVATION_DIR = path.join(root, "preservation");
+process.env.OS_AGENT_SESSION_COMPACT_TOKENS = "10000";
+process.env.OS_AGENT_SESSION_RECENT_TOKENS = "5000";
+process.env.OS_AGENT_SESSION_ARCHIVE_DAYS = "30";
+
+afterAll(async () => {
+ for (const k of ["OS_AGENT_SESSIONS_DIR", "OS_AGENT_MEMORY_DIR", "OS_AGENT_SESSION_ARCHIVE_DIR", "OS_AGENT_SESSION_PRESERVATION_DIR", "OS_AGENT_SESSION_COMPACT_TOKENS", "OS_AGENT_SESSION_RECENT_TOKENS", "OS_AGENT_SESSION_ARCHIVE_DAYS"]) delete process.env[k];
+ await fs.rm(root, { recursive: true, force: true });
+});
+
+vi.resetModules();
+const store = await import("./session-store");
+const todos = await import("./todos");
+const { AGENT_TOOLS } = await import("@/lib/mcp/tools-agent");
+
+describe("todo_write contract and session persistence", () => {
+ it("writing a list persists it and a re-read returns the same list", async () => {
+ const session = await store.createAgentSession("principal:t1", "cli", { title: "Persist" });
+ const items: AgentTodoItem[] = [
+ { content: "Read code", status: "completed" },
+ { content: "Implement todo tool", status: "in_progress", activeForm: "implementing" },
+ { content: "Run tests", status: "pending" },
+ ];
+ const res = await todos.writeAgentSessionTodos("principal:t1", session.id, items);
+ expect(res).toEqual({ ok: true, count: 3, inProgress: "Implement todo tool", completed: 1, pending: 1 });
+ const reloaded = await store.getAgentSession("principal:t1", session.id);
+ expect((reloaded as any)?.todos).toEqual(items);
+ expect(await todos.readAgentSessionTodos("principal:t1", session.id)).toEqual(items);
+ const note = reloaded?.events.find((e) => e.kind === "note" && e.detail?.includes("Implement todo tool"));
+ expect(note?.detail).toMatch(/Todos: 3 items \(1 completed, in progress: Implement todo tool\)/);
+ });
+
+ it("a second write REPLACES rather than appends", async () => {
+ const session = await store.createAgentSession("principal:t2", "cli", { title: "Replace" });
+ await todos.writeAgentSessionTodos("principal:t2", session.id, [
+ { content: "Task 1", status: "pending" },
+ { content: "Task 2", status: "pending" },
+ ]);
+ expect(await todos.readAgentSessionTodos("principal:t2", session.id)).toHaveLength(2);
+ const next: AgentTodoItem[] = [{ content: "Replaced task", status: "completed" }];
+ await todos.writeAgentSessionTodos("principal:t2", session.id, next);
+ const reloaded = await todos.readAgentSessionTodos("principal:t2", session.id);
+ expect(reloaded).toEqual(next);
+ });
+
+ it("over 50 items is refused", async () => {
+ const session = await store.createAgentSession("principal:t3", "cli", { title: "Cap" });
+ const tooMany = Array.from({ length: 51 }, (_, i) => ({ content: `T${i}`, status: "pending" as const }));
+ await expect(todos.writeAgentSessionTodos("principal:t3", session.id, tooMany)).rejects.toThrow(/cannot exceed 50 items/i);
+ });
+
+ it("an invalid status is refused", async () => {
+ const session = await store.createAgentSession("principal:t4", "cli", { title: "Invalid status" });
+ await expect(todos.writeAgentSessionTodos("principal:t4", session.id, [{ content: "Bad", status: "done" as any }]))
+ .rejects.toThrow(/status must be one of/i);
+ });
+
+ it("empty content is refused", async () => {
+ const session = await store.createAgentSession("principal:t5", "cli", { title: "Empty content" });
+ await expect(todos.writeAgentSessionTodos("principal:t5", session.id, [{ content: "", status: "pending" }]))
+ .rejects.toThrow(/content cannot be empty/i);
+ await expect(todos.writeAgentSessionTodos("principal:t5", session.id, [{ content: " ", status: "pending" }]))
+ .rejects.toThrow(/content cannot be empty/i);
+ });
+
+ it("the returned summary counts are correct and inProgress names the single in-progress item (null when none)", async () => {
+ const session = await store.createAgentSession("principal:t6", "cli", { title: "Summary" });
+ const s1 = await todos.writeAgentSessionTodos("principal:t6", session.id, [
+ { content: "C1", status: "completed" },
+ { content: "C2", status: "completed" },
+ { content: "Active task", status: "in_progress" },
+ { content: "P1", status: "pending" },
+ ]);
+ expect(s1).toEqual({ ok: true, count: 4, inProgress: "Active task", completed: 2, pending: 1 });
+ const s2 = await todos.writeAgentSessionTodos("principal:t6", session.id, [
+ { content: "C1", status: "completed" },
+ { content: "P1", status: "pending" },
+ ]);
+ expect(s2).toEqual({ ok: true, count: 2, inProgress: null, completed: 1, pending: 1 });
+ });
+
+ it("old session records without the field still load", async () => {
+ const session = await store.createAgentSession("principal:t7", "cli", { title: "Legacy" });
+ const loaded = await store.getAgentSession("principal:t7", session.id);
+ expect(loaded).not.toBeNull();
+ expect((loaded as any)?.todos).toBeUndefined();
+ expect(await todos.readAgentSessionTodos("principal:t7", session.id)).toEqual([]);
+ const updated = await todos.writeAgentSessionTodos("principal:t7", session.id, [{ content: "New", status: "pending" }]);
+ expect(updated.count).toBe(1);
+ expect(await todos.readAgentSessionTodos("principal:t7", session.id)).toHaveLength(1);
+ });
+
+ it("tool todo_write respects session scope and writes checklist", async () => {
+ const session = await store.createAgentSession("principal:mcp", "mcp", { title: "Tool test" });
+ const tool = AGENT_TOOLS.find((row) => row.name === "todo_write");
+ expect(tool).toBeDefined();
+ await expect(tool!.run({ todos: [{ content: "x", status: "pending" }] }, { principal: "principal:mcp", scope: "write" }))
+ .rejects.toThrow(/no conversation-bound MSO session/i);
+ await expect(tool!.run({ todos: [{ content: "x", status: "pending" }], session_id: "other" }, { principal: "principal:mcp", sessionId: session.id, scope: "write" }))
+ .rejects.toThrow(/session_id must match the active agent session/i);
+ const res = (await tool!.run({ todos: [{ content: "Step 1", status: "in_progress" }], session_id: session.id }, { principal: "principal:mcp", sessionId: session.id, scope: "write" })) as AgentTodoSummary;
+ expect(res).toEqual({ ok: true, count: 1, inProgress: "Step 1", completed: 0, pending: 0 });
+ expect(await todos.readAgentSessionTodos("principal:mcp", session.id)).toEqual([{ content: "Step 1", status: "in_progress" }]);
+ });
+});
diff --git a/lib/agent/todos.ts b/lib/agent/todos.ts
new file mode 100644
index 00000000..9b93c3cb
--- /dev/null
+++ b/lib/agent/todos.ts
@@ -0,0 +1,169 @@
+import { withSecurityStoreLock } from "@/lib/security-store-lock";
+import { sessionLockTarget, writeSessionFile } from "./session-files";
+import { requireOwned } from "./session-record";
+import { appendAgentSessionEvent } from "./session-mutations";
+import { getAgentSession } from "./session-store";
+import type { AgentSession } from "./session-types";
+
+export type AgentTodoStatus = "pending" | "in_progress" | "completed";
+
+export interface AgentTodoItem {
+ content: string;
+ status: AgentTodoStatus;
+ activeForm?: string;
+}
+
+export type AgentSessionWithTodos = AgentSession & {
+ todos?: AgentTodoItem[];
+};
+
+export interface AgentTodoSummary {
+ ok: true;
+ count: number;
+ inProgress: string | null;
+ completed: number;
+ pending: number;
+}
+
+export const MAX_TODO_ITEMS = 50;
+export const MAX_TODO_CONTENT_LENGTH = 200;
+export const VALID_TODO_STATUSES: readonly AgentTodoStatus[] = [
+ "pending",
+ "in_progress",
+ "completed",
+] as const;
+
+export function isValidTodoStatus(value: unknown): value is AgentTodoStatus {
+ return typeof value === "string" && VALID_TODO_STATUSES.includes(value as AgentTodoStatus);
+}
+
+export function validateTodoItem(item: unknown, index?: number): AgentTodoItem {
+ const prefix = index !== undefined ? `todo item at index ${index}` : "todo item";
+ if (!item || typeof item !== "object" || Array.isArray(item)) {
+ throw new Error(`${prefix} must be an object`);
+ }
+ const raw = item as Record<string, unknown>;
+
+ if (typeof raw.content !== "string") {
+ throw new Error(`${prefix} content must be a string`);
+ }
+ const content = raw.content.trim();
+ if (content.length === 0) {
+ throw new Error(`${prefix} content cannot be empty`);
+ }
+ if (content.length > MAX_TODO_CONTENT_LENGTH) {
+ throw new Error(
+ `${prefix} content exceeds maximum length of ${MAX_TODO_CONTENT_LENGTH} characters`,
+ );
+ }
+
+ if (!isValidTodoStatus(raw.status)) {
+ throw new Error(
+ `${prefix} status must be one of: ${VALID_TODO_STATUSES.join(", ")}`,
+ );
+ }
+
+ const result: AgentTodoItem = {
+ content,
+ status: raw.status,
+ };
+
+ if (raw.activeForm !== undefined) {
+ if (typeof raw.activeForm !== "string") {
+ throw new Error(`${prefix} activeForm must be a string if provided`);
+ }
+ result.activeForm = raw.activeForm;
+ }
+
+ return result;
+}
+
+export function validateTodoList(input: unknown): AgentTodoItem[] {
+ if (!Array.isArray(input)) {
+ throw new Error("todos must be an array");
+ }
+ if (input.length > MAX_TODO_ITEMS) {
+ throw new Error(
+ `todos list cannot exceed ${MAX_TODO_ITEMS} items (received ${input.length})`,
+ );
+ }
+ return input.map((item, index) => validateTodoItem(item, index));
+}
+
+export function summarizeTodos(
+ todos: readonly AgentTodoItem[],
+): Omit<AgentTodoSummary, "ok"> {
+ let completed = 0;
+ let pending = 0;
+ let singleInProgress: string | null = null;
+ let inProgressCount = 0;
+
+ for (const item of todos) {
+ if (item.status === "completed") {
+ completed += 1;
+ } else if (item.status === "pending") {
+ pending += 1;
+ } else if (item.status === "in_progress") {
+ inProgressCount += 1;
+ if (inProgressCount === 1) {
+ singleInProgress = item.content;
+ }
+ }
+ }
+
+ return {
+ count: todos.length,
+ inProgress: singleInProgress,
+ completed,
+ pending,
+ };
+}
+
+export function formatTodoNoteDetail(
+ summary: Omit<AgentTodoSummary, "ok">,
+): string {
+ if (summary.inProgress) {
+ return `Todos: ${summary.count} items (${summary.completed} completed, in progress: ${summary.inProgress})`;
+ }
+ return `Todos: ${summary.count} items (${summary.completed} completed, none in progress)`;
+}
+
+export async function writeAgentSessionTodos(
+ principal: string,
+ id: string,
+ rawTodos: unknown,
+): Promise<AgentTodoSummary> {
+ const validated = validateTodoList(rawTodos);
+ const summary = summarizeTodos(validated);
+
+ await withSecurityStoreLock(sessionLockTarget(id), async () => {
+ const record = (await requireOwned(principal, id)) as AgentSessionWithTodos;
+ record.todos = validated;
+ record.updatedAt = new Date().toISOString();
+ await writeSessionFile(record);
+ });
+
+ const detail = formatTodoNoteDetail(summary);
+ await appendAgentSessionEvent(principal, id, {
+ kind: "note",
+ detail,
+ });
+
+ return {
+ ok: true,
+ ...summary,
+ };
+}
+
+export async function readAgentSessionTodos(
+ principal: string,
+ id: string,
+): Promise<AgentTodoItem[]> {
+ const record = (await getAgentSession(principal, id)) as AgentSessionWithTodos | null;
+ if (!record) {
+ throw new Error("agent session not found for this client");
+ }
+ return record.todos ? [...record.todos] : [];
+}
+
+export const getAgentSessionTodos = readAgentSessionTodos;
diff --git a/lib/host/fs-edit.ts b/lib/host/fs-edit.ts
new file mode 100644
index 00000000..51902259
--- /dev/null
+++ b/lib/host/fs-edit.ts
@@ -0,0 +1,91 @@
+import { HostError } from "./host-error";
+import { readFile, statReadableMeta } from "./fs";
+import { writeFileGuarded } from "./guarded-write";
+import { utf8Bytes } from "./hash";
+
+const MAX_READ_BYTES = 2 * 1024 * 1024; // 2 MiB
+const MAX_WRITE_BYTES = 8 * 1024 * 1024; // 8 MiB
+
+export interface EditFileInput {
+ path: string;
+ oldString: string;
+ newString: string;
+ replaceAll?: boolean;
+ expectedSha256?: string;
+}
+
+export interface EditFileResult {
+ ok: true;
+ path: string;
+ replacements: number;
+ bytes: number;
+ sha256: string;
+ previousSha256?: string;
+}
+
+function countOccurrences(content: string, search: string): number {
+ let count = 0;
+ let pos = 0;
+ while ((pos = content.indexOf(search, pos)) !== -1) {
+ count++;
+ pos += search.length;
+ }
+ return count;
+}
+
+export async function editFileGuarded(input: EditFileInput): Promise<EditFileResult> {
+ const { path, oldString, newString, replaceAll = false, expectedSha256 } = input;
+
+ if (oldString === "") {
+ throw new HostError("old_string must not be empty");
+ }
+
+ const meta = await statReadableMeta(path);
+ if (meta.kind !== "file") {
+ throw new HostError("Not a regular file");
+ }
+ if (meta.sizeBytes > MAX_READ_BYTES) {
+ throw new HostError(`File too large to edit (max ${MAX_READ_BYTES} bytes, file is ${meta.sizeBytes} bytes)`);
+ }
+
+ const currentContent = await readFile(path);
+ const occurrences = countOccurrences(currentContent, oldString);
+
+ if (occurrences === 0) {
+ throw new HostError(`old_string not found in ${path}`);
+ }
+
+ if (occurrences > 1 && !replaceAll) {
+ throw new HostError(
+ `Found ${occurrences} occurrences of old_string in ${path}. Pass more surrounding context or set replace_all to true.`,
+ );
+ }
+
+ let nextContent: string;
+ if (replaceAll) {
+ nextContent = currentContent.split(oldString).join(newString);
+ } else {
+ const idx = currentContent.indexOf(oldString);
+ nextContent = currentContent.slice(0, idx) + newString + currentContent.slice(idx + oldString.length);
+ }
+
+ const nextBytes = utf8Bytes(nextContent);
+ if (nextBytes > MAX_WRITE_BYTES) {
+ throw new HostError(`Replacement would push file over limit (max ${MAX_WRITE_BYTES} bytes, resulting file is ${nextBytes} bytes)`);
+ }
+
+ const writeResult = await writeFileGuarded({
+ path,
+ content: nextContent,
+ expectedSha256,
+ });
+
+ return {
+ ok: true,
+ path: writeResult.path,
+ replacements: occurrences,
+ bytes: writeResult.bytes,
+ sha256: writeResult.sha256,
+ ...(writeResult.previousSha256 ? { previousSha256: writeResult.previousSha256 } : {}),
+ };
+}
diff --git a/lib/host/fs-glob.ts b/lib/host/fs-glob.ts
new file mode 100644
index 00000000..a61c6540
--- /dev/null
+++ b/lib/host/fs-glob.ts
@@ -0,0 +1,127 @@
+import { promises as fs } from "node:fs";
+import type { Dirent } from "node:fs";
+import path from "node:path";
+import { HostError } from "./host-error";
+import { isCredentialPath, resolveReadable } from "./paths";
+
+const DEFAULT_MAX_RESULTS = 200;
+const HARD_CAP_MAX_RESULTS = 1000;
+const SKIP_DIRS = new Set(["node_modules", ".git", ".next", "coverage"]);
+
+export interface GlobResult {
+ paths: string[];
+ truncated: boolean;
+ reason?: string;
+}
+
+export interface GlobInput {
+ pattern: string;
+ path?: string;
+ max_results?: number;
+ maxResults?: number;
+}
+
+/**
+ * Minimal glob-to-RegExp converter.
+ *
+ * Supported syntax:
+ * - `*`: matches any characters within one path segment (stops at `/`)
+ * - `**`: matches zero or more path segments across `/`
+ * - `?`: matches any single character except `/`
+ * - `[...]`: character classes (e.g. `[a-z]`, `[0-9]`), including negation `[!abc]` or `[^abc]`
+ *
+ * NOT supported syntax:
+ * - Brace expansion (e.g. `{ts,tsx}`)
+ * - Extended globbing (e.g. `+(...)`, `@(...)`, `!(...)`, `?(...)`)
+ * - Multi-segment wildcards embedded in words (e.g. `a**b`)
+ * - Escaped backslash literals
+ */
+export function globToRegExp(pattern: string): RegExp {
+ const p = pattern.replace(/\\/g, "/").replace(/^\.\//, "");
+ let s = "^", i = 0;
+ while (i < p.length) {
+ const c = p[i];
+ if (c === "*") {
+ if (p[i + 1] === "*") {
+ i += 2;
+ if (p[i] === "/") { s += "(?:.*\\/)?"; i++; }
+ else s += ".*";
+ } else { s += "[^\\/]*"; i++; }
+ } else if (c === "?") { s += "[^\\/]"; i++; }
+ else if (c === "[") {
+ let j = i + 1, content = "";
+ if (j < p.length && (p[j] === "!" || p[j] === "^")) { content += "^"; j++; }
+ if (j < p.length && p[j] === "]") { content += "\\]"; j++; }
+ while (j < p.length && p[j] !== "]") content += p[j] === "\\" ? (j++, "\\" + (p[j++] ?? "")) : p[j++];
+ if (j < p.length) { s += `[${content}]`; i = j + 1; }
+ else { s += "\\["; i++; }
+ } else if ("/.^$+(){}[]|\\".includes(c)) { s += "\\" + c; i++; }
+ else { s += c; i++; }
+ }
+ return new RegExp(s + "$");
+}
+
+export async function walkFiles(root: string, onFile: (filePath: string) => Promise<boolean>): Promise<void> {
+ async function walk(dir: string): Promise<boolean> {
+ let entries: Dirent[];
+ try {
+ entries = await fs.readdir(dir, { withFileTypes: true });
+ } catch {
+ return true;
+ }
+ entries.sort((a, b) => a.name.localeCompare(b.name));
+ for (const entry of entries) {
+ const child = path.join(dir, entry.name);
+ if (isCredentialPath(child)) continue;
+ if (entry.isDirectory()) {
+ if (!SKIP_DIRS.has(entry.name) && !(await walk(child))) return false;
+ } else if (entry.isFile()) {
+ if (!(await onFile(child))) return false;
+ } else if (entry.isSymbolicLink()) {
+ const stat = await fs.stat(child).catch(() => null);
+ if (stat?.isFile()) {
+ const readable = await resolveReadable(child).catch(() => null);
+ if (readable && !isCredentialPath(readable) && !(await onFile(child))) return false;
+ }
+ }
+ }
+ return true;
+ }
+ const stat = await fs.stat(root);
+ if (stat.isFile()) await onFile(root);
+ else if (stat.isDirectory()) await walk(root);
+}
+
+export async function globFs(input: GlobInput): Promise<GlobResult> {
+ const { pattern, path: requestedPath } = input;
+ const rawMax = input.max_results ?? input.maxResults ?? DEFAULT_MAX_RESULTS;
+ const maxResults = Math.max(1, Math.min(HARD_CAP_MAX_RESULTS, Number.isFinite(rawMax) ? Math.trunc(rawMax) : DEFAULT_MAX_RESULTS));
+
+ if (!pattern || typeof pattern !== "string") {
+ throw new HostError("pattern must be a non-empty string");
+ }
+
+ const targetRoot = requestedPath && requestedPath.trim() ? requestedPath.trim() : process.cwd();
+ const resolvedRoot = await resolveReadable(targetRoot);
+
+ const regex = globToRegExp(pattern);
+ const paths: string[] = [];
+ let truncated = false;
+ let reason: string | undefined;
+
+ await walkFiles(resolvedRoot, async (filePath) => {
+ const relPath = path.relative(resolvedRoot, filePath).replace(/\\/g, "/");
+ if (regex.test(relPath)) {
+ paths.push(filePath);
+ if (paths.length >= maxResults) {
+ truncated = true;
+ reason = "max_results limit reached";
+ return false;
+ }
+ }
+ return true;
+ });
+
+ paths.sort((a, b) => a.localeCompare(b));
+ return { paths, truncated, ...(reason ? { reason } : {}) };
+}
diff --git a/lib/host/fs-grep.ts b/lib/host/fs-grep.ts
new file mode 100644
index 00000000..cd802cba
--- /dev/null
+++ b/lib/host/fs-grep.ts
@@ -0,0 +1,122 @@
+import { constants, promises as fs } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import path from "node:path";
+import { globFs, globToRegExp, type GlobInput, type GlobResult, walkFiles } from "./fs-glob";
+import { resolveReadable } from "./paths";
+
+export { globFs, globToRegExp, type GlobInput, type GlobResult };
+
+const MAX_FILE_SIZE = 1024 * 1024; // 1 MiB
+const MAX_TOTAL_BYTES = 64 * 1024 * 1024; // 64 MiB
+const BINARY_CHECK_BYTES = 8192; // 8 KiB
+const DEFAULT_MAX_MATCHES = 200;
+const HARD_CAP_MAX_MATCHES = 1000;
+
+export interface GrepMatch {
+ path: string;
+ line: number;
+ text: string;
+}
+
+export interface GrepResult {
+ matches: GrepMatch[];
+ truncated: boolean;
+ filesScanned: number;
+ reason?: string;
+ error?: string;
+}
+
+export interface GrepInput {
+ pattern: string;
+ path?: string;
+ glob?: string;
+ max_matches?: number;
+ maxMatches?: number;
+ case_sensitive?: boolean;
+ caseSensitive?: boolean;
+}
+
+export async function grepFs(input: GrepInput): Promise<GrepResult> {
+ const { pattern, path: requestedPath, glob: globFilter } = input;
+ const caseSensitive = input.case_sensitive ?? input.caseSensitive ?? true;
+ const rawMax = input.max_matches ?? input.maxMatches ?? DEFAULT_MAX_MATCHES;
+ const maxMatches = Math.max(1, Math.min(HARD_CAP_MAX_MATCHES, Number.isFinite(rawMax) ? Math.trunc(rawMax) : DEFAULT_MAX_MATCHES));
+
+ if (!pattern || typeof pattern !== "string") {
+ return { error: "pattern must be a non-empty string", matches: [], truncated: false, filesScanned: 0 };
+ }
+
+ let regex: RegExp;
+ try {
+ regex = new RegExp(pattern, caseSensitive ? "" : "i");
+ } catch (err) {
+ return {
+ error: `Invalid regular expression: ${err instanceof Error ? err.message : String(err)}`,
+ matches: [],
+ truncated: false,
+ filesScanned: 0,
+ };
+ }
+
+ let globRegex: RegExp | undefined;
+ if (globFilter && typeof globFilter === "string") {
+ try { globRegex = globToRegExp(globFilter); } catch {}
+ }
+
+ const targetRoot = requestedPath && requestedPath.trim() ? requestedPath.trim() : process.cwd();
+ const resolvedRoot = await resolveReadable(targetRoot);
+
+ const matches: GrepMatch[] = [];
+ let truncated = false;
+ let reason: string | undefined;
+ let totalBytesScanned = 0;
+ let filesScanned = 0;
+
+ await walkFiles(resolvedRoot, async (filePath) => {
+ const relPath = path.relative(resolvedRoot, filePath).replace(/\\/g, "/");
+ if (globRegex && !globRegex.test(relPath)) return true;
+
+ let handle: FileHandle | undefined;
+ try {
+ handle = await fs.open(filePath, constants.O_RDONLY);
+ const stat = await handle.stat();
+ if (!stat.isFile() || stat.size > MAX_FILE_SIZE) return true;
+
+ if (totalBytesScanned + stat.size > MAX_TOTAL_BYTES) {
+ truncated = true;
+ reason = "total_bytes_scanned limit reached (64 MiB)";
+ return false;
+ }
+
+ const previewLength = Math.min(stat.size, BINARY_CHECK_BYTES);
+ const preview = Buffer.alloc(previewLength);
+ const { bytesRead } = await handle.read(preview, 0, previewLength, 0);
+ if (preview.subarray(0, bytesRead).includes(0)) return true;
+
+ const content = await handle.readFile({ encoding: "utf8" });
+ totalBytesScanned += stat.size;
+ filesScanned++;
+
+ const lines = content.split(/\r?\n/);
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i];
+ if (regex.test(line)) {
+ const cleanLine = line.endsWith("\r") ? line.slice(0, -1) : line;
+ matches.push({ path: filePath, line: i + 1, text: cleanLine.slice(0, 400) });
+ if (matches.length >= maxMatches) {
+ truncated = true;
+ reason = "max_matches limit reached";
+ return false;
+ }
+ }
+ }
+ } catch {
+ return true;
+ } finally {
+ await handle?.close().catch(() => undefined);
+ }
+ return true;
+ });
+
+ return { matches, truncated, filesScanned, ...(reason ? { reason } : {}) };
+}
diff --git a/lib/mcp/chatgpt-profile.test.ts b/lib/mcp/chatgpt-profile.test.ts
index 3a7f72c0..f7a279b5 100644
--- a/lib/mcp/chatgpt-profile.test.ts
+++ b/lib/mcp/chatgpt-profile.test.ts
@@ -33,7 +33,11 @@ describe("ChatGPT full generic MCP profile", () => {
const bytes = Buffer.byteLength(JSON.stringify(tools));
if (process.env.MSO_PROFILE_METRICS === "1") console.info(`CHATGPT_PROFILE_METRICS tools=${tools.length} bytes=${bytes} roughTokens4=${Math.ceil(bytes/4)} maxToolBytes=${Math.max(...tools.map((tool)=>Buffer.byteLength(JSON.stringify(tool))))}`);
- expect(bytes).toBeLessThan(92 * 1024);
+ // Ceiling raised 92 -> 100 KiB when four coding tools landed (fs_edit, fs_grep,
+ // fs_glob, todo_write). The alternative was to stop advertising tools to ChatGPT,
+ // which silently removes capability. The largest single descriptor is 2.8 KiB, so
+ // there is no fat left to trim: 125 tools at ~770 B average is the actual shape.
+ expect(bytes).toBeLessThan(100 * 1024);
const start = tools.find((tool) => tool.name === "workflow_start") as { description?: string };
expect(String(start?.description)).toMatch(/First call.*multi-step/i);
const search = tools.find((tool) => tool.name === "skills_search") as { description?: string };
diff --git a/lib/mcp/fs-edit.test.ts b/lib/mcp/fs-edit.test.ts
new file mode 100644
index 00000000..8498f3e8
--- /dev/null
+++ b/lib/mcp/fs-edit.test.ts
@@ -0,0 +1,191 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { CapabilityTool } from "@/lib/capabilities/tool";
+import type { Scope } from "@/lib/capabilities/scope";
+import { EDIT_TOOLS } from "./tools-edit";
+import { READ_TOOLS } from "./tools-read";
+import { sha256Text } from "@/lib/host/fs-api";
+
+vi.mock("server-only", () => ({}));
+vi.mock("@/lib/host/audit-api", async (original) => {
+ const actual = (await original()) as typeof import("@/lib/host/audit-api");
+ return { ...actual, audit: vi.fn(async () => {}) };
+});
+vi.mock("@/lib/agent/session-store", async (original) => {
+ const actual = (await original()) as typeof import("@/lib/agent/session-store");
+ return { ...actual, maybeAutoTitleAgentSession: vi.fn(async () => {}), appendAgentSessionEvent: vi.fn(async () => {}) };
+});
+
+const { executeCapabilityCall } = await import("@/lib/capabilities/execute");
+
+const edit = EDIT_TOOLS.find((tool) => tool.name === "fs_edit")!;
+const read = READ_TOOLS.find((tool) => tool.name === "fs_read")!;
+const actor = "mcp:fs-edit-test";
+const owner = { principal: "test-client", sessionId: "session-edit" };
+
+const call = (tool: CapabilityTool, args: Record<string, unknown>, scope: Scope = "write", context = owner) =>
+ executeCapabilityCall({ tool, args, scope, actor, context });
+
+describe("fs_edit tool", () => {
+ let base: string;
+ let filePath: string;
+
+ beforeEach(async () => {
+ base = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "mso-fs-edit-test-")));
+ filePath = path.join(base, "sample.txt");
+ vi.stubEnv("OS_FS_READ_ROOTS", base);
+ vi.stubEnv("OS_FS_WRITE_ROOTS", base);
+ vi.stubEnv("OS_MCP_ACTIVITY_LOG", "");
+ });
+
+ afterEach(async () => {
+ vi.restoreAllMocks();
+ vi.unstubAllEnvs();
+ await fs.rm(base, { recursive: true, force: true });
+ });
+
+ it("1. unique match replaces exactly once and returns the new sha256 that fs_read would compute", async () => {
+ const original = "Hello World\nLine 2\nLine 3\n";
+ await fs.writeFile(filePath, original, "utf8");
+
+ const res = await call(edit, { path: filePath, old_string: "World", new_string: "MSO" });
+ expect(res).toMatchObject({
+ kind: "success",
+ result: { ok: true, path: filePath, replacements: 1 },
+ });
+
+ const expectedContent = "Hello MSO\nLine 2\nLine 3\n";
+ const readResult = await call(read, { path: filePath }, "read");
+ expect(readResult).toMatchObject({
+ kind: "success",
+ result: { content: expectedContent, sha256: sha256Text(expectedContent) },
+ });
+
+ const editOutput = (res as { result: { sha256: string; bytes: number } }).result;
+ expect(editOutput.sha256).toBe(sha256Text(expectedContent));
+ expect(editOutput.bytes).toBe(Buffer.byteLength(expectedContent, "utf8"));
+ });
+
+ it("2. two matches without replace_all FAILS and leaves the file byte-identical", async () => {
+ const original = "foo bar foo baz\n";
+ await fs.writeFile(filePath, original, "utf8");
+
+ const res = await call(edit, { path: filePath, old_string: "foo", new_string: "qux" });
+ expect(res).toMatchObject({
+ kind: "error",
+ message: expect.stringMatching(/Found 2 occurrences of old_string.*Pass more surrounding context or set replace_all/i),
+ });
+
+ const onDisk = await fs.readFile(filePath, "utf8");
+ expect(onDisk).toBe(original);
+ });
+
+ it("3. two matches with replace_all: true replaces both", async () => {
+ const original = "apple orange apple pear\n";
+ await fs.writeFile(filePath, original, "utf8");
+
+ const res = await call(edit, {
+ path: filePath,
+ old_string: "apple",
+ new_string: "grape",
+ replace_all: true,
+ });
+
+ const expected = "grape orange grape pear\n";
+ expect(res).toMatchObject({
+ kind: "success",
+ result: { ok: true, path: filePath, replacements: 2, sha256: sha256Text(expected) },
+ });
+
+ const onDisk = await fs.readFile(filePath, "utf8");
+ expect(onDisk).toBe(expected);
+ });
+
+ it("4. zero matches FAILS, file unchanged", async () => {
+ const original = "first line\nsecond line\n";
+ await fs.writeFile(filePath, original, "utf8");
+
+ const res = await call(edit, { path: filePath, old_string: "third line", new_string: "replacement" });
+ expect(res).toMatchObject({
+ kind: "error",
+ message: expect.stringMatching(/old_string not found/i),
+ });
+
+ const onDisk = await fs.readFile(filePath, "utf8");
+ expect(onDisk).toBe(original);
+ });
+
+ it("5. empty old_string FAILS", async () => {
+ const original = "hello world\n";
+ await fs.writeFile(filePath, original, "utf8");
+
+ const res = await call(edit, { path: filePath, old_string: "", new_string: "something" });
+ expect(res).toMatchObject({
+ kind: "error",
+ message: expect.stringMatching(/must be a non-empty string|old_string must not be empty/i),
+ });
+
+ const onDisk = await fs.readFile(filePath, "utf8");
+ expect(onDisk).toBe(original);
+ });
+
+ it("6. stale expected_sha256 FAILS and does not write", async () => {
+ const original = "current file contents\n";
+ await fs.writeFile(filePath, original, "utf8");
+
+ const staleHash = "0000000000000000000000000000000000000000000000000000000000000000";
+ const res = await call(edit, {
+ path: filePath,
+ old_string: "current",
+ new_string: "modified",
+ expected_sha256: staleHash,
+ });
+
+ expect(res).toMatchObject({
+ kind: "error",
+ message: expect.stringMatching(/File changed since fs_read/i),
+ });
+
+ const onDisk = await fs.readFile(filePath, "utf8");
+ expect(onDisk).toBe(original);
+ });
+
+ it("7. correct expected_sha256 succeeds", async () => {
+ const original = "version 1.0\nstable\n";
+ await fs.writeFile(filePath, original, "utf8");
+ const currentHash = sha256Text(original);
+
+ const res = await call(edit, {
+ path: filePath,
+ old_string: "version 1.0",
+ new_string: "version 2.0",
+ expected_sha256: currentHash,
+ });
+
+ const expected = "version 2.0\nstable\n";
+ expect(res).toMatchObject({
+ kind: "success",
+ result: {
+ ok: true,
+ path: filePath,
+ replacements: 1,
+ sha256: sha256Text(expected),
+ previousSha256: currentHash,
+ },
+ });
+
+ const onDisk = await fs.readFile(filePath, "utf8");
+ expect(onDisk).toBe(expected);
+ });
+
+ it("8. a path outside the write roots is refused (whatever refusal the existing guard produces)", async () => {
+ const outsidePath = "/etc/hosts";
+ const res = await call(edit, { path: outsidePath, old_string: "localhost", new_string: "remotehost" });
+ expect(res).toMatchObject({
+ kind: "error",
+ message: expect.stringMatching(/outside writable roots|outside readable roots/i),
+ });
+ });
+});
diff --git a/lib/mcp/fs-grep.test.ts b/lib/mcp/fs-grep.test.ts
new file mode 100644
index 00000000..4a233c5e
--- /dev/null
+++ b/lib/mcp/fs-grep.test.ts
@@ -0,0 +1,137 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { NAVIGATE_TOOLS } from "./tools-navigate";
+import type { GrepResult, GlobResult } from "@/lib/host/fs-grep";
+
+vi.mock("server-only", () => ({}));
+
+const grepTool = NAVIGATE_TOOLS.find((t) => t.name === "fs_grep")!;
+const globTool = NAVIGATE_TOOLS.find((t) => t.name === "fs_glob")!;
+const mockContext = { scope: "read" as const };
+
+describe("fs_grep and fs_glob navigation tools", () => {
+ let tempBase: string;
+
+ beforeEach(async () => {
+ tempBase = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "mso-fs-grep-test-")));
+ vi.stubEnv("OS_FS_READ_ROOTS", tempBase);
+ });
+
+ afterEach(async () => {
+ vi.restoreAllMocks();
+ vi.unstubAllEnvs();
+ await fs.rm(tempBase, { recursive: true, force: true });
+ });
+
+ it("1. grep finds a symbol across two files and reports correct 1-based lines", async () => {
+ const fileA = path.join(tempBase, "alpha.ts");
+ const subDir = path.join(tempBase, "nested");
+ await fs.mkdir(subDir, { recursive: true });
+ const fileB = path.join(subDir, "beta.ts");
+
+ await fs.writeFile(fileA, "first line\nconst SYMBOL_ONE = 1;\nthird line\n", "utf8");
+ await fs.writeFile(fileB, "import { SYMBOL_ONE } from './alpha';\nconst val = SYMBOL_ONE;\n", "utf8");
+
+ const res = (await grepTool.run({ pattern: "SYMBOL_ONE", path: tempBase }, mockContext)) as GrepResult;
+ expect(res.truncated).toBe(false);
+ expect(res.matches.length).toBe(3);
+
+ const matchA = res.matches.filter((m) => m.path === fileA);
+ expect(matchA).toHaveLength(1);
+ expect(matchA[0].line).toBe(2);
+ expect(matchA[0].text).toBe("const SYMBOL_ONE = 1;");
+
+ const matchB = res.matches.filter((m) => m.path === fileB);
+ expect(matchB).toHaveLength(2);
+ expect(matchB[0].line).toBe(1);
+ expect(matchB[1].line).toBe(2);
+ });
+
+ it("2. grep respects glob filtering", async () => {
+ await fs.writeFile(path.join(tempBase, "code.ts"), "const SHARED_KEY = 100;\n", "utf8");
+ await fs.writeFile(path.join(tempBase, "code.js"), "const SHARED_KEY = 100;\n", "utf8");
+
+ const res = (await grepTool.run(
+ { pattern: "SHARED_KEY", path: tempBase, glob: "**/*.ts" },
+ mockContext,
+ )) as GrepResult;
+
+ expect(res.matches.length).toBe(1);
+ expect(res.matches[0].path.endsWith("code.ts")).toBe(true);
+ });
+
+ it("3. grep skips node_modules even when the pattern matches there", async () => {
+ const nodeModulesDir = path.join(tempBase, "node_modules", "some-lib");
+ const srcDir = path.join(tempBase, "src");
+ await fs.mkdir(nodeModulesDir, { recursive: true });
+ await fs.mkdir(srcDir, { recursive: true });
+
+ await fs.writeFile(path.join(nodeModulesDir, "index.ts"), "export const SECRET_FN = 1;\n", "utf8");
+ await fs.writeFile(path.join(srcDir, "index.ts"), "export const SECRET_FN = 2;\n", "utf8");
+
+ const res = (await grepTool.run({ pattern: "SECRET_FN", path: tempBase }, mockContext)) as GrepResult;
+ expect(res.matches.length).toBe(1);
+ expect(res.matches[0].path).toBe(path.join(srcDir, "index.ts"));
+ });
+
+ it("4. grep skips a file containing a NUL byte in the first 8 KiB", async () => {
+ const binaryFile = path.join(tempBase, "blob.bin");
+ const textFile = path.join(tempBase, "doc.txt");
+
+ const binBuf = Buffer.concat([Buffer.from("abc\0def"), Buffer.from("MATCH_NUL_TEST")]);
+ await fs.writeFile(binaryFile, binBuf);
+ await fs.writeFile(textFile, "MATCH_NUL_TEST in plain text\n", "utf8");
+
+ const res = (await grepTool.run({ pattern: "MATCH_NUL_TEST", path: tempBase }, mockContext)) as GrepResult;
+ expect(res.matches.length).toBe(1);
+ expect(res.matches[0].path).toBe(textFile);
+ });
+
+ it("5. grep truncates at max_matches and sets truncated with a reason", async () => {
+ const file = path.join(tempBase, "lines.txt");
+ const content = ["hit 1", "hit 2", "hit 3", "hit 4"].join("\n");
+ await fs.writeFile(file, content, "utf8");
+
+ const res = (await grepTool.run({ pattern: "hit", path: tempBase, max_matches: 2 }, mockContext)) as GrepResult;
+ expect(res.truncated).toBe(true);
+ expect(res.matches.length).toBe(2);
+ expect(res.reason).toContain("max_matches");
+ });
+
+ it("6. invalid regex returns an error result, does not throw", async () => {
+ const res = (await grepTool.run({ pattern: "[unclosed", path: tempBase }, mockContext)) as GrepResult;
+ expect(res).toHaveProperty("error");
+ expect(typeof res.error).toBe("string");
+ expect(res.matches).toEqual([]);
+ expect(res.truncated).toBe(false);
+ });
+
+ it("7. glob **/*.ts matches nested files but not *.js", async () => {
+ const nestedDir = path.join(tempBase, "a", "b");
+ await fs.mkdir(nestedDir, { recursive: true });
+
+ await fs.writeFile(path.join(tempBase, "root.ts"), "");
+ await fs.writeFile(path.join(nestedDir, "nested.ts"), "");
+ await fs.writeFile(path.join(tempBase, "root.js"), "");
+ await fs.writeFile(path.join(nestedDir, "nested.js"), "");
+
+ const res = (await globTool.run({ pattern: "**/*.ts", path: tempBase }, mockContext)) as GlobResult;
+ expect(res.truncated).toBe(false);
+ expect(res.paths.length).toBe(2);
+ expect(res.paths[0].endsWith("root.ts") || res.paths[0].endsWith("nested.ts")).toBe(true);
+ expect(res.paths.every((p) => p.endsWith(".ts"))).toBe(true);
+ });
+
+ it("8. glob truncates at max_results", async () => {
+ for (let i = 1; i <= 5; i++) {
+ await fs.writeFile(path.join(tempBase, `file-${i}.txt`), "");
+ }
+
+ const res = (await globTool.run({ pattern: "*.txt", path: tempBase, max_results: 2 }, mockContext)) as GlobResult;
+ expect(res.truncated).toBe(true);
+ expect(res.paths.length).toBe(2);
+ expect(res.reason).toContain("max_results");
+ });
+});
diff --git a/lib/mcp/mcp-only-reasons.ts b/lib/mcp/mcp-only-reasons.ts
new file mode 100644
index 00000000..4398b6ee
--- /dev/null
+++ b/lib/mcp/mcp-only-reasons.ts
@@ -0,0 +1,109 @@
+/** Deliberately one-sided, each with the reason.
+ * Every entry is a place MCP and Alfa disagree on exposed capabilities.
+ * If a reason stops being true, delete the entry and add the capability.
+ */
+export const MCP_ONLY: Record<string, string> = {
+ "jev.action": "JEV action arbitration belongs to the external/terminal capability authority so selected actions re-enter MCP scope, allowlist, workflow and audit enforcement instead of bypassing them through Alfa browser identity.",
+ "mso.native.ui.probe": "Static ChatGPT MCP Apps host-mount diagnostic; Alfa already runs inside the native MSO browser shell and has no equivalent external host-renderer boundary to probe.",
+ "workflow.graph": "Native Workflows UI has its own authenticated principal; external MCP graph CRUD/run/status must stay principal-scoped instead of inheriting an unrelated browser identity.",
+ "organization.chart": "MSO already exposes the owner-private Organization registry through Alfa’s dedicated Organization tab/API; external MCP needs a bounded programmatic read surface without duplicating that registry into conversational Alfa host tools.",
+ "organization.manage": "Organization mutations belong to the dedicated owner Organization UI/API with revision checks; external MCP gets the same store under write scope/audit, while Alfa conversation does not gain a second parallel mutation surface.",
+ "flow.catalog": "Project API/MCP automation belongs to the external/CLI session context; Alfa has its own browser workflow identity.",
+ "flow.run": "Provider mutations require the durable external principal, exact connection, and idempotency receipt; owner CLI shares this executor.",
+ "flow.status": "Flow receipts belong to their authenticated external/CLI principal; Alfa must not inherit that principal.",
+ "flow.manage": "Project-local automation definitions configure the external/CLI executor, not an Alfa browser thread.",
+ "agent.session.open": "Provider-neutral bootstrap for the external durable session store; Alfa already owns a separate browser thread.",
+ "project.mcp.manage": "External MCP and native owner Integrations share project binding CRUD; Alfa delegates to that owner surface.",
+ "project.asset.attach": "Source artifacts are owned by a durable external/CLI session and cannot be claimed by Alfa's browser identity.",
+ "integration.query": "Native credential profiles are managed by owner browser/CLI and external agents; Alfa has no independent credential-owner identity and must not invent one",
+ "integration.manage": "Same credential-owner boundary; browser and CLI use the shared native action service with confirmation rather than duplicating it in Alfa",
+ "integration.execute": "External deployment agents require explicit account selection; the native owner UI/CLI share the executor without exposing keys to Alfa",
+
+ "session.artifacts": "CLI/MCP durable-session artifact records use the authenticated client principal; Alfa browser threads have a separate identity and must not inherit another session's files",
+ "session.artifact.register": "same durable-session boundary; external browser producers stage files under session context rather than accepting arbitrary paths",
+ "session.artifacts.cleanup": "same session store; bounded retention is controlled by the authenticated external/CLI principal, not unrelated Alfa thread state",
+ "integration.setup.open": "ChatGPT needs a write-scoped UI-only capability; native owner browser and CLI use the same secure setup service without exposing secrets to Alfa tools",
+ "screen.capture": "external MCP clients need visual proof of the rendered OS; in-shell Alfa already runs inside that browser UI",
+ "projects.list": "an MCP client has no sidebar and no Files window, so it needs an explicit bounded enumeration of every project container; in-shell Alfa reads the same roots through fs.list and the Files app",
+ "project.capabilities": "external harnesses need a stable generic discovery seam for project-owned MCP/functions; Alfa can inspect the same project files through its existing fs/skills tools without changing its cached tool array",
+ "project.function.call": "external MCP clients need one no-shell bridge into project-declared functions; Alfa already has per-call-approved exec.run and must not receive a dynamic per-project tool catalog",
+ "project.mcp.tools": "external MCP clients discover one selected project MCP lazily; dynamic project tool names never enter either global catalog",
+ "project.mcp.call": "external MCP clients execute one exact dynamically-discovered project MCP tool under exec scope; Alfa can use its approved exec path and must not import project MCP catalogs",
+ "fs.upload.file": "external ChatGPT connectors need openai/fileParams to move conversation-generated files onto the VPS; in-shell Alfa already has direct host filesystem access",
+ "fs.export.file": "external MCP clients need an authenticated original-byte download bridge; in-shell Alfa already has direct host filesystem access",
+ "fs.stat": "external MCP clients need a true size/mtime without reading binary content",
+ "fs.edit": "surgical old_string/new_string editing exists for an external coding agent that must not rewrite a whole file to change one line; in-shell Alfa edits through its own approved exec/fs path and must not gain a second, parallel mutation surface",
+ "fs.grep": "content search over a bounded tree is what an external coding agent needs to navigate a large repo; Alfa reads specific files through fs.list/fs.read and has no need for a second search surface",
+ "fs.glob": "path globbing serves the same external navigation need as fs.grep; Alfa already knows its target paths from the in-app Files surface",
+ "todo.write": "a session-scoped checklist exists so a long external agent run stays visible across turns; Alfa owns its browser thread and its own progress surface, so a second checklist would be a competing source of truth",
+ "workflow.start": "the external connector needs an actor-scoped task boundary; Alfa already owns an in-app conversation/run boundary",
+ "workflow.status": "app-only MCP Apps bridge used by the ChatGPT progress component; Alfa already owns its in-shell run state and must not poll the external workflow store",
+ "workflow.cancel": "same actor-scoped boundary; external runs need explicit recovery from an interrupted task",
+ "workflow.finish": "same actor-scoped learning loop; Alfa recipes can use the session route later without weakening MCP scope semantics",
+ "project.memory.search": "repo-local RASMIC orchestration memory belongs to the terminal/external workflow harness; Alfa intentionally keeps its separate owner recall and must not collapse those memory principals",
+ "project.memory.upsert": "same repo-local RASMIC ledger; writes are workflow-scoped/audited for external agents rather than shared with Alfa owner recall",
+ "project.script.run": "RASMIC script replay is an external/terminal orchestration primitive that revalidates bounded read-only steps and may promote candidate metadata; Alfa has no matching workflow/script lifecycle",
+ "agent.session.current": "external MCP clients need a stable durable MSO session id they can quote from a later ChatGPT conversation; in-shell Alfa already owns its conversation identity",
+ "agent.session.flow": "semantic flow lookup reads the external durable AgentSession ledger used by MCP/terminal agents; Alfa browser threads intentionally keep a separate conversation identity, while the owner can inspect the same projection in the native Workflows Sessions UI",
+ "agent.session.action.resolve": "stable semantic action resolution belongs to the same external durable AgentSession ledger and preserves owner isolation; Alfa browser threads keep their separate conversation identity",
+ "agent.sessions.list": "external MCP clients need explicit cross-conversation session discovery; Alfa's in-app thread UI already provides its own conversation list",
+ "agent.session.resume": "external MCP clients must reconstruct only the safe MSO resume packet across ChatGPT conversations; Alfa can reopen its own persisted in-app thread directly",
+ "agent.session.rename": "durable MCP/terminal session titles are metadata in the isolated agent-session store; Alfa keeps its separate in-app thread/title lifecycle",
+ "agent.session.note": "durable operational notes belong to the MCP client's isolated MSO session store; Alfa has a separate owner-scoped conversation/memory store",
+ "agent.memory.read": "MCP clients use isolated USER.md/MEMORY.md-style agent memory snapshots; Alfa intentionally keeps its existing owner recall instead of sharing external-client memory",
+ "agent.memory.search": "typed provenance/temporal retrieval belongs to that same isolated MCP/terminal memory ledger; exposing it as Alfa owner recall would collapse the deliberate principal boundary",
+ "agent.memory.remember": "same isolated MCP memory store; sharing it with Alfa would collapse two trust/ownership boundaries",
+ "agent.memory.forget": "same isolated MCP memory store; deletion remains scoped to the external MCP client principal",
+ "exec.job.start": "external MCP requests have a hard request-time budget and need a bounded resumable shell job; in-shell Alfa can keep using its interactive Terminal/approved exec.run surfaces",
+ "exec.job.status": "status exists only to resume an MCP async exec job; Alfa has no corresponding external request timeout to recover from",
+ "exec.job.cancel": "cancellation is paired with the MCP-only async exec lifecycle and remains actor/workflow-bound",
+ "infra.providers.list": "MSO Agent and external connectors need a credential-free infrastructure capability inventory; in-shell Alfa has dedicated Dokploy/Cloudflare feature apps instead",
+ "infra.provider.doctor": "provider credentials stay server-side and the terminal/external agent needs a bounded live verification tool; Alfa has no reason to receive infrastructure secrets or duplicate these clients",
+ "dokploy.projects.list": "MSO Agent deploy workflows need a bounded Dokploy discovery seam; in-shell Alfa can delegate deployment through the dedicated infrastructure feature instead of duplicating this provider catalog",
+ "dokploy.applications.list": "external deployment workflows need a secret-free project-to-application resolver; Alfa delegates infrastructure discovery to the native integrations surface instead of duplicating Dokploy application state",
+ "dokploy.application.public.env.upsert": "public build-env mutation is intentionally external/terminal-agent-only: it is prefix-restricted, audited, rate-limited, and keeps server/secret env values out of Alfa's static host catalog",
+ "dokploy.project.ensure": "terminal/external deployment workflows need one idempotent Dokploy mutation with scope/approval; in-shell Alfa does not own infrastructure deployment credentials",
+ "cloudflare.zones.list": "terminal/external deployment workflows need bounded zone discovery while credentials stay server-side; in-shell Alfa has the Cloudflare feature app",
+ "cloudflare.dns.upsert": "DNS automation is intentionally MCP/terminal-agent-only so it inherits scope, approval, audit and workflow semantics without teaching generic in-shell Alfa to mutate public DNS",
+ "hostinger.dns.upsert": "external DNS mutation remains an explicitly approved deployment-agent capability; MSO sends one exact Hostinger name/type RR-set and keeps credentials server-side rather than adding a generic Alfa provider primitive",
+ "local.agents.list": "native Local Agents address durable CLI/MCP AgentSession principals; Alfa browser threads use a separate thread lifecycle and do not own a compatible durable session receiver",
+ "local.agent.message.send": "same durable-session boundary; adding this to Alfa without first unifying its browser-thread identity would let one UI thread claim another principal's local receiver",
+ "local.agent.inbox": "the inbox is keyed to the exact durable AgentSession principal/id; Alfa currently has a separate owner-thread store rather than that receiver identity",
+ "local.agent.inbox.acknowledge": "acknowledgement changes the exact durable AgentSession mailbox; Alfa browser threads do not own that receiver identity",
+ "a2a.agents.list": "A2A is an external-agent interoperability surface for MCP/terminal agents; in-shell Alfa has no remote-agent registry yet",
+ "a2a.agent.discover": "public Agent Card discovery is intentionally available to the MCP/terminal agent harness and does not expose owner UI state",
+ "a2a.agent.register": "remote A2A registry mutation inherits MCP write approval/audit semantics; Alfa has no matching registry surface",
+ "a2a.agent.remove": "paired with the MCP/terminal A2A registry and therefore intentionally absent from Alfa",
+ "a2a.message.send": "A2A peer messaging is a provider-neutral external-agent capability; Alfa remains an in-shell assistant rather than a network agent orchestrator",
+ "a2a.task.get": "A2A task polling exists only for remote tasks created through the MCP/terminal A2A client",
+ "a2a.task.cancel": "A2A remote task cancellation stays approval-gated in the external agent harness",
+ "a2a.handoff": "explicit agent-to-agent delegation is intentionally MCP/terminal-only until Alfa receives its own scoped orchestration model",
+ "agent.subagent.run": "same-session isolated subagent orchestration belongs to the terminal/MCP agent runtime; Alfa browser threads do not yet share durable AgentSession identity or its approval boundary",
+ "local.agent.reply": "correlated replies belong to the durable Local Agents session mailbox; Alfa browser threads do not share that session identity or inbox",
+ "local.agent.request.wait": "bounded request observation is tied to the durable Local Agents mailbox/correlation ledger; Alfa browser threads do not own that AgentSession sender identity",
+ "local.agent.request": "fresh-worker execution from another durable AgentSession context belongs to the terminal/MCP orchestration runtime; Alfa browser threads neither share that isolated session store nor its exec delegation boundary",
+ "local.agent.standby": "durable standby is bound to an external/CLI AgentSession plus exact active workflow; Alfa browser threads do not share that durable session/workflow identity, while Cockpit only observes its safe projected status",
+ "tool.forge.candidates": "Tool Forge is the external/terminal cognitive-runtime promotion pipeline; Alfa has a separate in-app lifecycle and must not implicitly expose generated project capabilities",
+ "tool.forge.propose": "same Forge boundary; creating an inert candidate depends on learned external workflow recipes rather than Alfa owner recall",
+ "tool.forge.evaluate": "Forge evaluation may execute project-owned fixtures only inside the dedicated sandbox and therefore stays on the scoped external/terminal automation surface",
+ "tool.forge.promote": "explicit Forge promotion mutates project capability metadata and remains an exec-scoped audited external/terminal action",
+ "read.pipeline": "external/terminal agents can batch already-authorized read tools and compact their data server-side; Alfa already owns an in-process tool loop and does not need a second orchestration surface",
+ "project.get": "external MCP/ChatGPT clients need one canonical bounded project snapshot and MCP App bootstrap; in-shell Alfa already has project/Files UI plus existing host inspection primitives",
+ "project.changes.list": "external project operators need bounded Git edit history without arbitrary shell; Alfa already works inside the project shell/Files surfaces and does not need a duplicate cached history action",
+ "project.diff": "external clients need portable bounded Git evidence and an inline diff summary; Alfa can inspect changes through its existing terminal/project surfaces without another global catalog entry",
+ "project.knowledge.get": "always-on .mso project knowledge belongs to the external/terminal workflow context layer; Alfa keeps separate in-app conversation/memory context so the stores are not silently conflated",
+ "project.knowledge.set": "same project-knowledge boundary; external writes use SHA compare-and-swap plus MCP write audit while Alfa keeps its separate context lifecycle",
+ "connections.list": "external operators need one secret-free inventory spanning infrastructure, project MCP aliases and Convex readiness; Alfa already has dedicated integration/provider feature surfaces",
+ "project.database.status": "the Convex project database adapter starts project code through the official project-installed MCP CLI and therefore belongs to the exec-gated external/terminal project runtime",
+ "project.database.tools": "Convex schemas are discovered dynamically for the selected project and must not inflate either global catalog; Alfa can stay on its existing approved execution/project surfaces",
+ "project.database.call": "dynamic Convex execution is an exec-scoped project runtime seam; Alfa must not import provider-specific dynamic tool names into its static host catalog",
+ "project.database.query": "read-only Convex one-off query still launches project code, so it remains on the exec-gated external/terminal adapter rather than pretending to be an Alfa read primitive",
+ "project.agent.run": "project-agent execution wraps the durable MCP/terminal AgentSession subagent runtime; Alfa browser threads have a separate lifecycle and approval identity",
+ "project.agent.status": "status belongs to project-agent message ids owned by the external MCP principal/session; Alfa has no compatible project-agent task ledger",
+ "vps.status": "this is an aggregate MCP Apps operator card over existing bounded host/app/browser/infra primitives; Alfa already renders equivalent in-shell operational surfaces",
+ "mso.surface.apps.list": "the reviewed ChatGPT Page app catalog is MCP-App presentation metadata; Alfa already owns its in-shell app registry and must not inherit ChatGPT frame allowlists",
+ "render.mso.list": "the compact List is a ChatGPT MCP Apps presentation target for model-selected collections; Alfa already has native project/file/session/workflow/app lists and does not need a second presentation-only host tool",
+ "render.mso.block": "the compact Block is a ChatGPT MCP Apps presentation target for validation/action/CRUD handoff; Alfa already has native forms and approval cards",
+ "render.mso.page": "the full Page is a ChatGPT MCP Apps presentation target; Alfa already is an MSO presentation target and does not render another copy of itself",
+ "render.mso.surface": "app-only compatibility alias for cached pre-Page widgets; Alfa has no reason to expose the retired presentation name",
+};
diff --git a/lib/mcp/parity.test.ts b/lib/mcp/parity.test.ts
index 60d020c0..d6ec9ea6 100644
--- a/lib/mcp/parity.test.ts
+++ b/lib/mcp/parity.test.ts
@@ -1,4 +1,5 @@
import { describe, it, expect, vi } from "vitest";
+import { MCP_ONLY } from "./mcp-only-reasons";
vi.mock("server-only", () => ({}));
const { TOOLS } = await import("./tools");
@@ -20,108 +21,6 @@ const ALFA_ONLY: Record<string, string> = {
"memory.forget": "same store; an MCP client has its own memory",
};
-const MCP_ONLY: Record<string, string> = {
- "jev.action": "JEV action arbitration belongs to the external/terminal capability authority so selected actions re-enter MCP scope, allowlist, workflow and audit enforcement instead of bypassing them through Alfa browser identity.",
- "mso.native.ui.probe": "Static ChatGPT MCP Apps host-mount diagnostic; Alfa already runs inside the native MSO browser shell and has no equivalent external host-renderer boundary to probe.",
- "workflow.graph": "Native Workflows UI has its own authenticated principal; external MCP graph CRUD/run/status must stay principal-scoped instead of inheriting an unrelated browser identity.",
- "organization.chart": "MSO already exposes the owner-private Organization registry through Alfa’s dedicated Organization tab/API; external MCP needs a bounded programmatic read surface without duplicating that registry into conversational Alfa host tools.",
- "organization.manage": "Organization mutations belong to the dedicated owner Organization UI/API with revision checks; external MCP gets the same store under write scope/audit, while Alfa conversation does not gain a second parallel mutation surface.",
- "flow.catalog": "Project API/MCP automation belongs to the external/CLI session context; Alfa has its own browser workflow identity.",
- "flow.run": "Provider mutations require the durable external principal, exact connection, and idempotency receipt; owner CLI shares this executor.",
- "flow.status": "Flow receipts belong to their authenticated external/CLI principal; Alfa must not inherit that principal.",
- "flow.manage": "Project-local automation definitions configure the external/CLI executor, not an Alfa browser thread.",
- "agent.session.open": "Provider-neutral bootstrap for the external durable session store; Alfa already owns a separate browser thread.",
- "project.mcp.manage": "External MCP and native owner Integrations share project binding CRUD; Alfa delegates to that owner surface.",
- "project.asset.attach": "Source artifacts are owned by a durable external/CLI session and cannot be claimed by Alfa's browser identity.",
- "integration.query":"Native credential profiles are managed by owner browser/CLI and external agents; Alfa has no independent credential-owner identity and must not invent one",
- "integration.manage":"Same credential-owner boundary; browser and CLI use the shared native action service with confirmation rather than duplicating it in Alfa",
- "integration.execute":"External deployment agents require explicit account selection; the native owner UI/CLI share the executor without exposing keys to Alfa",
-
- "session.artifacts": "CLI/MCP durable-session artifact records use the authenticated client principal; Alfa browser threads have a separate identity and must not inherit another session's files",
- "session.artifact.register": "same durable-session boundary; external browser producers stage files under session context rather than accepting arbitrary paths",
- "session.artifacts.cleanup": "same session store; bounded retention is controlled by the authenticated external/CLI principal, not unrelated Alfa thread state",
- "integration.setup.open": "ChatGPT needs a write-scoped UI-only capability; native owner browser and CLI use the same secure setup service without exposing secrets to Alfa tools",
- "screen.capture": "external MCP clients need visual proof of the rendered OS; in-shell Alfa already runs inside that browser UI",
- "projects.list": "an MCP client has no sidebar and no Files window, so it needs an explicit bounded enumeration of every project container; in-shell Alfa reads the same roots through fs.list and the Files app",
- "project.capabilities": "external harnesses need a stable generic discovery seam for project-owned MCP/functions; Alfa can inspect the same project files through its existing fs/skills tools without changing its cached tool array",
- "project.function.call": "external MCP clients need one no-shell bridge into project-declared functions; Alfa already has per-call-approved exec.run and must not receive a dynamic per-project tool catalog",
- "project.mcp.tools": "external MCP clients discover one selected project MCP lazily; dynamic project tool names never enter either global catalog",
- "project.mcp.call": "external MCP clients execute one exact dynamically-discovered project MCP tool under exec scope; Alfa can use its approved exec path and must not import project MCP catalogs",
- "fs.upload.file": "external ChatGPT connectors need openai/fileParams to move conversation-generated files onto the VPS; in-shell Alfa already has direct host filesystem access",
- "fs.export.file": "external MCP clients need an authenticated original-byte download bridge; in-shell Alfa already has direct host filesystem access",
- "fs.stat": "external MCP clients need a true size/mtime without reading binary content",
- "workflow.start": "the external connector needs an actor-scoped task boundary; Alfa already owns an in-app conversation/run boundary",
- "workflow.status": "app-only MCP Apps bridge used by the ChatGPT progress component; Alfa already owns its in-shell run state and must not poll the external workflow store",
- "workflow.cancel": "same actor-scoped boundary; external runs need explicit recovery from an interrupted task",
- "workflow.finish": "same actor-scoped learning loop; Alfa recipes can use the session route later without weakening MCP scope semantics",
- "project.memory.search": "repo-local RASMIC orchestration memory belongs to the terminal/external workflow harness; Alfa intentionally keeps its separate owner recall and must not collapse those memory principals",
- "project.memory.upsert": "same repo-local RASMIC ledger; writes are workflow-scoped/audited for external agents rather than shared with Alfa owner recall",
- "project.script.run": "RASMIC script replay is an external/terminal orchestration primitive that revalidates bounded read-only steps and may promote candidate metadata; Alfa has no matching workflow/script lifecycle",
- "agent.session.current": "external MCP clients need a stable durable MSO session id they can quote from a later ChatGPT conversation; in-shell Alfa already owns its conversation identity",
- "agent.session.flow": "semantic flow lookup reads the external durable AgentSession ledger used by MCP/terminal agents; Alfa browser threads intentionally keep a separate conversation identity, while the owner can inspect the same projection in the native Workflows Sessions UI",
- "agent.session.action.resolve": "stable semantic action resolution belongs to the same external durable AgentSession ledger and preserves owner isolation; Alfa browser threads keep their separate conversation identity",
- "agent.sessions.list": "external MCP clients need explicit cross-conversation session discovery; Alfa's in-app thread UI already provides its own conversation list",
- "agent.session.resume": "external MCP clients must reconstruct only the safe MSO resume packet across ChatGPT conversations; Alfa can reopen its own persisted in-app thread directly",
- "agent.session.rename": "durable MCP/terminal session titles are metadata in the isolated agent-session store; Alfa keeps its separate in-app thread/title lifecycle",
- "agent.session.note": "durable operational notes belong to the MCP client's isolated MSO session store; Alfa has a separate owner-scoped conversation/memory store",
- "agent.memory.read": "MCP clients use isolated USER.md/MEMORY.md-style agent memory snapshots; Alfa intentionally keeps its existing owner recall instead of sharing external-client memory",
- "agent.memory.search": "typed provenance/temporal retrieval belongs to that same isolated MCP/terminal memory ledger; exposing it as Alfa owner recall would collapse the deliberate principal boundary",
- "agent.memory.remember": "same isolated MCP memory store; sharing it with Alfa would collapse two trust/ownership boundaries",
- "agent.memory.forget": "same isolated MCP memory store; deletion remains scoped to the external MCP client principal",
- "exec.job.start": "external MCP requests have a hard request-time budget and need a bounded resumable shell job; in-shell Alfa can keep using its interactive Terminal/approved exec.run surfaces",
- "exec.job.status": "status exists only to resume an MCP async exec job; Alfa has no corresponding external request timeout to recover from",
- "exec.job.cancel": "cancellation is paired with the MCP-only async exec lifecycle and remains actor/workflow-bound",
- "infra.providers.list": "MSO Agent and external connectors need a credential-free infrastructure capability inventory; in-shell Alfa has dedicated Dokploy/Cloudflare feature apps instead",
- "infra.provider.doctor": "provider credentials stay server-side and the terminal/external agent needs a bounded live verification tool; Alfa has no reason to receive infrastructure secrets or duplicate these clients",
- "dokploy.projects.list": "MSO Agent deploy workflows need a bounded Dokploy discovery seam; in-shell Alfa can delegate deployment through the dedicated infrastructure feature instead of duplicating this provider catalog",
- "dokploy.applications.list": "external deployment workflows need a secret-free project-to-application resolver; Alfa delegates infrastructure discovery to the native integrations surface instead of duplicating Dokploy application state",
- "dokploy.application.public.env.upsert": "public build-env mutation is intentionally external/terminal-agent-only: it is prefix-restricted, audited, rate-limited, and keeps server/secret env values out of Alfa's static host catalog",
- "dokploy.project.ensure": "terminal/external deployment workflows need one idempotent Dokploy mutation with scope/approval; in-shell Alfa does not own infrastructure deployment credentials",
- "cloudflare.zones.list": "terminal/external deployment workflows need bounded zone discovery while credentials stay server-side; in-shell Alfa has the Cloudflare feature app",
- "cloudflare.dns.upsert": "DNS automation is intentionally MCP/terminal-agent-only so it inherits scope, approval, audit and workflow semantics without teaching generic in-shell Alfa to mutate public DNS",
- "hostinger.dns.upsert": "external DNS mutation remains an explicitly approved deployment-agent capability; MSO sends one exact Hostinger name/type RR-set and keeps credentials server-side rather than adding a generic Alfa provider primitive",
- "local.agents.list": "native Local Agents address durable CLI/MCP AgentSession principals; Alfa browser threads use a separate thread lifecycle and do not own a compatible durable session receiver",
- "local.agent.message.send": "same durable-session boundary; adding this to Alfa without first unifying its browser-thread identity would let one UI thread claim another principal's local receiver",
- "local.agent.inbox": "the inbox is keyed to the exact durable AgentSession principal/id; Alfa currently has a separate owner-thread store rather than that receiver identity",
- "local.agent.inbox.acknowledge": "acknowledgement changes the exact durable AgentSession mailbox; Alfa browser threads do not own that receiver identity",
- "a2a.agents.list": "A2A is an external-agent interoperability surface for MCP/terminal agents; in-shell Alfa has no remote-agent registry yet",
- "a2a.agent.discover": "public Agent Card discovery is intentionally available to the MCP/terminal agent harness and does not expose owner UI state",
- "a2a.agent.register": "remote A2A registry mutation inherits MCP write approval/audit semantics; Alfa has no matching registry surface",
- "a2a.agent.remove": "paired with the MCP/terminal A2A registry and therefore intentionally absent from Alfa",
- "a2a.message.send": "A2A peer messaging is a provider-neutral external-agent capability; Alfa remains an in-shell assistant rather than a network agent orchestrator",
- "a2a.task.get": "A2A task polling exists only for remote tasks created through the MCP/terminal A2A client",
- "a2a.task.cancel": "A2A remote task cancellation stays approval-gated in the external agent harness",
- "a2a.handoff": "explicit agent-to-agent delegation is intentionally MCP/terminal-only until Alfa receives its own scoped orchestration model",
- "agent.subagent.run": "same-session isolated subagent orchestration belongs to the terminal/MCP agent runtime; Alfa browser threads do not yet share durable AgentSession identity or its approval boundary",
- "local.agent.reply": "correlated replies belong to the durable Local Agents session mailbox; Alfa browser threads do not share that session identity or inbox",
- "local.agent.request.wait": "bounded request observation is tied to the durable Local Agents mailbox/correlation ledger; Alfa browser threads do not own that AgentSession sender identity",
- "local.agent.request": "fresh-worker execution from another durable AgentSession context belongs to the terminal/MCP orchestration runtime; Alfa browser threads neither share that isolated session store nor its exec delegation boundary",
- "local.agent.standby": "durable standby is bound to an external/CLI AgentSession plus exact active workflow; Alfa browser threads do not share that durable session/workflow identity, while Cockpit only observes its safe projected status",
- "tool.forge.candidates": "Tool Forge is the external/terminal cognitive-runtime promotion pipeline; Alfa has a separate in-app lifecycle and must not implicitly expose generated project capabilities",
- "tool.forge.propose": "same Forge boundary; creating an inert candidate depends on learned external workflow recipes rather than Alfa owner recall",
- "tool.forge.evaluate": "Forge evaluation may execute project-owned fixtures only inside the dedicated sandbox and therefore stays on the scoped external/terminal automation surface",
- "tool.forge.promote": "explicit Forge promotion mutates project capability metadata and remains an exec-scoped audited external/terminal action",
- "read.pipeline": "external/terminal agents can batch already-authorized read tools and compact their data server-side; Alfa already owns an in-process tool loop and does not need a second orchestration surface",
- "project.get": "external MCP/ChatGPT clients need one canonical bounded project snapshot and MCP App bootstrap; in-shell Alfa already has project/Files UI plus existing host inspection primitives",
- "project.changes.list": "external project operators need bounded Git edit history without arbitrary shell; Alfa already works inside the project shell/Files surfaces and does not need a duplicate cached history action",
- "project.diff": "external clients need portable bounded Git evidence and an inline diff summary; Alfa can inspect changes through its existing terminal/project surfaces without another global catalog entry",
- "project.knowledge.get": "always-on .mso project knowledge belongs to the external/terminal workflow context layer; Alfa keeps separate in-app conversation/memory context so the stores are not silently conflated",
- "project.knowledge.set": "same project-knowledge boundary; external writes use SHA compare-and-swap plus MCP write audit while Alfa keeps its separate context lifecycle",
- "connections.list": "external operators need one secret-free inventory spanning infrastructure, project MCP aliases and Convex readiness; Alfa already has dedicated integration/provider feature surfaces",
- "project.database.status": "the Convex project database adapter starts project code through the official project-installed MCP CLI and therefore belongs to the exec-gated external/terminal project runtime",
- "project.database.tools": "Convex schemas are discovered dynamically for the selected project and must not inflate either global catalog; Alfa can stay on its existing approved execution/project surfaces",
- "project.database.call": "dynamic Convex execution is an exec-scoped project runtime seam; Alfa must not import provider-specific dynamic tool names into its static host catalog",
- "project.database.query": "read-only Convex one-off query still launches project code, so it remains on the exec-gated external/terminal adapter rather than pretending to be an Alfa read primitive",
- "project.agent.run": "project-agent execution wraps the durable MCP/terminal AgentSession subagent runtime; Alfa browser threads have a separate lifecycle and approval identity",
- "project.agent.status": "status belongs to project-agent message ids owned by the external MCP principal/session; Alfa has no compatible project-agent task ledger",
- "vps.status": "this is an aggregate MCP Apps operator card over existing bounded host/app/browser/infra primitives; Alfa already renders equivalent in-shell operational surfaces",
- "mso.surface.apps.list": "the reviewed ChatGPT Page app catalog is MCP-App presentation metadata; Alfa already owns its in-shell app registry and must not inherit ChatGPT frame allowlists",
- "render.mso.list": "the compact List is a ChatGPT MCP Apps presentation target for model-selected collections; Alfa already has native project/file/session/workflow/app lists and does not need a second presentation-only host tool",
- "render.mso.block": "the compact Block is a ChatGPT MCP Apps presentation target for validation/action/CRUD handoff; Alfa already has native forms and approval cards",
- "render.mso.page": "the full Page is a ChatGPT MCP Apps presentation target; Alfa already is an MSO presentation target and does not render another copy of itself",
- "render.mso.surface": "app-only compatibility alias for cached pre-Page widgets; Alfa has no reason to expose the retired presentation name",
-};
-
describe("Alfa ↔ MCP capability parity", () => {
const alfa = new Set(HOST_TOOLS.map((t) => capability(t.name)));
const mcp = new Set(TOOLS.map((t) => capability(t.name)));
@@ -172,7 +71,7 @@ describe("MCP rate limits mirror the routes", () => {
// Numbers lifted from the route files. The route is the authority; MCP may be
// stricter, never laxer.
const ROUTE_LIMITS: Record<string, number> = {
- "fs.write": 120, "fs.mkdir": 120, "fs.move": 120, "fs.copy": 60,
+ "fs.write": 120, "fs.edit": 120, "fs.mkdir": 120, "fs.move": 120, "fs.copy": 60,
"fs.delete": 60, "fs.upload": 20, "exec": 60, "managed-app": 12, "camoufox": 12,
};
const MCP_NATIVE_LIMITS: Record<string, number> = {
diff --git a/lib/mcp/tools-agent.ts b/lib/mcp/tools-agent.ts
index 126430ef..b68e935a 100644
--- a/lib/mcp/tools-agent.ts
+++ b/lib/mcp/tools-agent.ts
@@ -8,6 +8,7 @@ import { semanticSessionFlow } from "@/lib/agent/session-flow";
import { resolveHistoricalSessionAction } from "@/lib/agent/session-action-history";
import { resolveHistoricalSessionArtifact } from "@/lib/agent/session-artifact-resolver";
import { AGENT_SESSION_RESUME_TOOL } from "./tools-agent-recovery";
+import { writeAgentSessionTodos } from "@/lib/agent/todos";
function principal(context: { principal?: string }): string {
if (!context.principal) throw new Error("agent session principal is unavailable");
@@ -124,6 +125,40 @@ export const AGENT_TOOLS: McpTool[] = [
return { ok: true, sessionId: context.sessionId };
},
},
+ {
+ name: "todo_write",
+ description: "Replace the session todo list with a full updated list, never merge or append: send every pending, in_progress and completed item each time. Keeps long multi-step work visible.",
+ scope: "write",
+ limit: { key: "agent.session", max: 30, windowMs: 60_000 },
+ audit: { action: "agent.session", targetArg: "session_id" },
+ inputSchema: S({
+ todos: {
+ type: "array",
+ description: "Full list of todo items. This call REPLACES the entire todo list, it does not append or merge. Always send the full list with updated statuses.",
+ items: {
+ type: "object",
+ required: ["content", "status"],
+ properties: {
+ content: { type: "string", description: "Description of the task, non-empty, max 200 characters." },
+ status: { type: "string", enum: ["pending", "in_progress", "completed"], description: "Current status of the task." },
+ activeForm: { type: "string", description: "Optional present-tense description while in progress." },
+ },
+ },
+ },
+ session_id: {
+ type: "string",
+ description: "Optional session ID. If provided, it must match the active conversation session.",
+ },
+ }, ["todos"]),
+ run: async (a, context) => {
+ if (!context.sessionId) throw new Error("this tool call has no conversation-bound MSO session");
+ const explicitId = optionalString(a, "session_id");
+ if (explicitId && explicitId !== context.sessionId) {
+ throw new Error("session_id must match the active agent session");
+ }
+ return writeAgentSessionTodos(principal(context), context.sessionId, a.todos);
+ },
+ },
{
name: "agent_memory_read",
description: "Read this MCP client's resolved persistent USER.md and MEMORY.md compatibility view. New sessions capture a frozen snapshot.",
diff --git a/lib/mcp/tools-edit.ts b/lib/mcp/tools-edit.ts
new file mode 100644
index 00000000..b28adec4
--- /dev/null
+++ b/lib/mcp/tools-edit.ts
@@ -0,0 +1,39 @@
+import { assertDelegatedWritePath } from "@/lib/host/fs-api";
+import { editFileGuarded } from "@/lib/host/fs-edit";
+import { type McpTool, opt, PATH_P, S, str } from "./tool-kit";
+import { requireWorkflowMutationPath } from "./workflow-workspace-guard";
+
+async function requireDelegatedPath(context: Parameters<McpTool["run"]>[1], target: string) {
+ if (context.scope !== "exec") await assertDelegatedWritePath(target);
+}
+
+export const EDIT_TOOLS: McpTool[] = [
+ {
+ name: "fs_edit",
+ limit: { key: "fs.edit", max: 120, windowMs: 60_000 },
+ audit: { action: "fs.write" as const, targetArg: "path" },
+ description: "Edit a file by replacing exact old_string occurrences with new_string. Fails on zero matches or on multiple matches unless replace_all is true. Read first, pass its SHA-256 as expected_sha256 to refuse stale edits. Bounded to OS_FS_WRITE_ROOTS.",
+ scope: "write",
+ annotations: { idempotentHint: true },
+ actionContract: { phase: "mutate", target: "filesystem-text", sourceOfTruth: "live", discover: ["fs_read"], validators: ["path-policy", "sha256-cas"], verify: ["fs_read"], confirmation: "contextual", concurrency: "hash", presentation: "structured" },
+ inputSchema: S({
+ ...PATH_P,
+ old_string: { type: "string", description: "Exact text to find and replace. Must not be empty." },
+ new_string: { type: "string", description: "Replacement text." },
+ replace_all: { type: "boolean", description: "Replace all occurrences when true. Default false requires exactly one match." },
+ expected_sha256: { type: "string", description: "Optional SHA-256 returned by fs_read; refuse if the current file no longer matches." },
+ }, ["path", "old_string", "new_string"]),
+ run: async (a, context) => {
+ const target = str(a, "path");
+ await requireWorkflowMutationPath(context, target);
+ await requireDelegatedPath(context, target);
+ return editFileGuarded({
+ path: target,
+ oldString: typeof a.old_string === "string" ? a.old_string : str(a, "old_string"),
+ newString: typeof a.new_string === "string" ? a.new_string : "",
+ replaceAll: a.replace_all === true,
+ expectedSha256: opt(a, "expected_sha256"),
+ });
+ },
+ },
+];
diff --git a/lib/mcp/tools-mutate.ts b/lib/mcp/tools-mutate.ts
index db65e744..495c290e 100644
--- a/lib/mcp/tools-mutate.ts
+++ b/lib/mcp/tools-mutate.ts
@@ -15,20 +15,12 @@ export const MUTATE_TOOLS: McpTool[] = [
scope: "write",
annotations: { idempotentHint: true },
actionContract: { phase: "mutate", target: "filesystem-text", sourceOfTruth: "live", discover: ["fs_read"], validators: ["path-policy", "sha256-cas"], verify: ["fs_read"], confirmation: "contextual", concurrency: "hash", presentation: "structured" },
- inputSchema: S({
- ...PATH_P,
- content: { type: "string" },
- expected_sha256: { type: "string", description: "Optional SHA-256 returned by fs_read; refuse if the current file no longer matches." },
- }, ["path", "content"]),
+ inputSchema: S({ ...PATH_P, content: { type: "string" }, expected_sha256: { type: "string", description: "Optional SHA-256 returned by fs_read; refuse if the current file no longer matches." } }, ["path", "content"]),
run: async (a, context) => {
const target = str(a, "path");
await requireWorkflowMutationPath(context, target);
await requireDelegatedPath(context, target);
- return { ok: true, ...(await writeFileGuarded({
- path: target,
- content: typeof a.content === "string" ? a.content : "",
- expectedSha256: opt(a, "expected_sha256"),
- })) };
+ return { ok: true, ...(await writeFileGuarded({ path: target, content: typeof a.content === "string" ? a.content : "", expectedSha256: opt(a, "expected_sha256") })) };
},
},
{
@@ -41,20 +33,7 @@ export const MUTATE_TOOLS: McpTool[] = [
actionContract: { phase: "mutate", target: "artifact-ingress", sourceOfTruth: "provider", validators: ["openai-file-provenance", "content-type", "content-size", "content-structure", "destination-policy"], verify: ["fs_read"], confirmation: "contextual", concurrency: "hash", presentation: "structured" },
meta: { "openai/fileParams": ["file"] },
inputSchema: S({
- file: {
- type: "object",
- description: "ChatGPT-provided file reference. Select or attach exactly one PNG, WebP, JPEG, JSON or ZIP file.",
- properties: {
- download_url: { type: "string" },
- file_id: { type: "string" },
- mime_type: { type: "string" },
- file_name: { type: "string" },
- name: { type: "string" },
- size: { type: "number" },
- },
- required: ["download_url", "file_id"],
- additionalProperties: true,
- },
+ file: { type: "object", description: "ChatGPT-provided file reference. Select or attach exactly one PNG, WebP, JPEG, JSON or ZIP file.", properties: { download_url: { type: "string" }, file_id: { type: "string" }, mime_type: { type: "string" }, file_name: { type: "string" }, name: { type: "string" }, size: { type: "number" } }, required: ["download_url", "file_id"], additionalProperties: true },
dest: { type: "string", description: "Existing destination directory on the VPS, within OS_FS_WRITE_ROOTS." },
filename: { type: "string", description: "Optional safe destination basename; extension must match the validated file type." },
conflict: { type: "string", enum: ["error", "rename", "replace"], description: "Default error. rename chooses a deterministic content-hash suffix. replace requires expected_sha256." },
@@ -64,11 +43,7 @@ export const MUTATE_TOOLS: McpTool[] = [
const dest = str(a, "dest");
await requireWorkflowMutationPath(context, dest);
await requireDelegatedPath(context, dest);
- return importOpenAiProvidedFile({
- file: a.file, dest, filename: opt(a, "filename"),
- conflict: opt(a, "conflict") as "error" | "rename" | "replace" | undefined,
- expectedSha256: opt(a, "expected_sha256"),
- });
+ return importOpenAiProvidedFile({ file: a.file, dest, filename: opt(a, "filename"), conflict: opt(a, "conflict") as "error" | "rename" | "replace" | undefined, expectedSha256: opt(a, "expected_sha256") });
},
},
{
diff --git a/lib/mcp/tools-navigate.ts b/lib/mcp/tools-navigate.ts
new file mode 100644
index 00000000..2c136030
--- /dev/null
+++ b/lib/mcp/tools-navigate.ts
@@ -0,0 +1,57 @@
+import { type McpTool, str, opt, S, PATH_P, READ_ONLY } from "./tool-kit";
+import { grepFs, globFs } from "@/lib/host/fs-grep";
+
+export const NAVIGATE_TOOLS: McpTool[] = [
+ {
+ name: "fs_grep",
+ description:
+ "Search file contents across a directory tree using a JavaScript regular expression. " +
+ "Bounded to OS_FS_READ_ROOTS, skips files > 1 MiB, binary files, node_modules, .git, .next, coverage, and credential paths. " +
+ "Returns matching lines with 1-based line numbers.",
+ scope: "read",
+ annotations: READ_ONLY,
+ result: {
+ maxTextBytes: 64 * 1024,
+ overflowHint: "Narrow search with a more specific pattern, path, or glob filter.",
+ },
+ inputSchema: S({
+ pattern: { type: "string", description: "JavaScript regular expression to match against file contents line by line." },
+ ...PATH_P,
+ glob: { type: "string", description: "Optional glob pattern to filter files (e.g. '**/*.ts', 'src/**/*.tsx')." },
+ max_matches: { type: "number", description: "Maximum matching lines to return. Default 200, hard cap 1000." },
+ case_sensitive: { type: "boolean", description: "Whether the regex match is case-sensitive. Default true." },
+ }, ["pattern"]),
+ run: (a) =>
+ grepFs({
+ pattern: str(a, "pattern"),
+ path: opt(a, "path"),
+ glob: opt(a, "glob"),
+ max_matches: typeof a.max_matches === "number" ? a.max_matches : undefined,
+ case_sensitive: typeof a.case_sensitive === "boolean" ? a.case_sensitive : undefined,
+ }),
+ },
+ {
+ name: "fs_glob",
+ description:
+ "Find files matching a glob pattern across a directory tree. " +
+ "Bounded to OS_FS_READ_ROOTS, skips node_modules, .git, .next, coverage, and credential paths. " +
+ "Returns sorted file paths.",
+ scope: "read",
+ annotations: READ_ONLY,
+ result: {
+ maxTextBytes: 64 * 1024,
+ overflowHint: "Narrow search with a more specific glob pattern or path.",
+ },
+ inputSchema: S({
+ pattern: { type: "string", description: "Glob pattern to match file paths (e.g. '**/*.test.ts', 'src/**/*.ts')." },
+ ...PATH_P,
+ max_results: { type: "number", description: "Maximum matching paths to return. Default 200, hard cap 1000." },
+ }, ["pattern"]),
+ run: (a) =>
+ globFs({
+ pattern: str(a, "pattern"),
+ path: opt(a, "path"),
+ max_results: typeof a.max_results === "number" ? a.max_results : undefined,
+ }),
+ },
+];
diff --git a/lib/mcp/tools.ts b/lib/mcp/tools.ts
index 5ba3b6f4..97ec1a17 100644
--- a/lib/mcp/tools.ts
+++ b/lib/mcp/tools.ts
@@ -26,6 +26,8 @@ import { SUBAGENT_TOOLS } from "./tools-subagents";
import { BLOCK_TOOLS, LIST_TOOLS, NATIVE_UI_PROBE_TOOLS, SURFACE_TOOLS } from "./tools-ui";
import type { McpTool } from "./tool-kit";
+import { EDIT_TOOLS } from "./tools-edit";
import { MUTATE_TOOLS } from "./tools-mutate";
+import { NAVIGATE_TOOLS } from "./tools-navigate";
-export const TOOLS: McpTool[] = [...AGENT_VAULT_TOOLS, ...FLOW_TOOLS, ...AGENT_OPEN_TOOLS, ...PROJECT_ASSET_TOOLS, ...PROJECT_MCP_MANAGE_TOOLS, ...SESSION_ARTIFACT_TOOLS, ...READ_TOOLS, ...FILE_TRANSFER_READ_TOOLS, ...DISCOVERY_TOOLS, ...LEARNING_TOOLS, ...JEV_TOOLS, ...AGENT_TOOLS, ...LOCAL_AGENT_TOOLS, ...SUBAGENT_TOOLS, ...A2A_TOOLS, ...FORGE_TOOLS, ...READ_PIPELINE_TOOLS, ...PROJECT_MCP_TOOLS, ...PROJECT_EXPERIENCE_TOOLS, ...ORGANIZATION_TOOLS, ...OPERATOR_DASHBOARD_TOOLS, ...NATIVE_UI_PROBE_TOOLS, ...BLOCK_TOOLS, ...LIST_TOOLS, ...SURFACE_TOOLS, ...INFRA_TOOLS, ...INTEGRATION_TOOLS, ...MUTATE_TOOLS, ...POWER_TOOLS].map(withWorkflowContext); export const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
+export const TOOLS: McpTool[] = [...AGENT_VAULT_TOOLS, ...FLOW_TOOLS, ...AGENT_OPEN_TOOLS, ...PROJECT_ASSET_TOOLS, ...PROJECT_MCP_MANAGE_TOOLS, ...SESSION_ARTIFACT_TOOLS, ...READ_TOOLS, ...NAVIGATE_TOOLS, ...FILE_TRANSFER_READ_TOOLS, ...DISCOVERY_TOOLS, ...LEARNING_TOOLS, ...JEV_TOOLS, ...AGENT_TOOLS, ...LOCAL_AGENT_TOOLS, ...SUBAGENT_TOOLS, ...A2A_TOOLS, ...FORGE_TOOLS, ...READ_PIPELINE_TOOLS, ...PROJECT_MCP_TOOLS, ...PROJECT_EXPERIENCE_TOOLS, ...ORGANIZATION_TOOLS, ...OPERATOR_DASHBOARD_TOOLS, ...NATIVE_UI_PROBE_TOOLS, ...BLOCK_TOOLS, ...LIST_TOOLS, ...SURFACE_TOOLS, ...INFRA_TOOLS, ...INTEGRATION_TOOLS, ...EDIT_TOOLS, ...MUTATE_TOOLS, ...POWER_TOOLS].map(withWorkflowContext); export const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));