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(mcp): add bounded async exec jobs

Rahman5da80da47e5c
diff --git a/CLAUDE.md b/CLAUDE.md
index d51db59d..10cb7614 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -313,7 +313,7 @@ setup/diagrams use `docs/CHATGPT-PLUGIN.md`.
it AND `tools/call` re-checks it — a client can call a name it was never shown.
- **Tool names are a cross-repo contract.** `rahmanef63/connectors-gateway` registered
mso as a connector on 2026-08-17 and historically pinned a subset of the MCP names as
- literal `x-upstream` strings. MSO itself currently exposes 28 tools (15 read, 10 write,
+ literal `x-upstream` strings. MSO itself currently exposes 31 tools (16 read, 10 write,
3 exec); `GET /mcp` plus `_meta.toolset` expose the current version/hash/name manifest.
Treat the gateway mapping as a separate cross-repo contract and verify it before renaming. Renaming or removing
a tool here breaks it with **no error in either repo** — `parity.test.ts` guards the
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 997063c2..39d49d0e 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -134,7 +134,7 @@ park a visible Approve/Deny card. The complete semantic contract is
**MCP** is for external clients such as ChatGPT, Claude.ai and Cursor. Its catalog lives in
`lib/mcp/`; access is controlled by the OAuth token scope rather than Alfa approval cards.
-At the current toolset it exposes 28 tools: 15 read, 10 write and 3 exec. Project-specific
+At the current toolset it exposes 31 tools: 16 read, 10 write and 5 exec. Project-specific
function names remain data behind `project_capabilities` / `project_function_call`, so one
project cannot dynamically rewrite the global MCP tool prefix.
diff --git a/docs/CHATGPT-PLUGIN.md b/docs/CHATGPT-PLUGIN.md
index a7e91f1f..c4cb92bb 100644
--- a/docs/CHATGPT-PLUGIN.md
+++ b/docs/CHATGPT-PLUGIN.md
@@ -10,10 +10,10 @@
> plus OAuth metadata documented here. OpenAI's current overview is:
> <https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt-beta>
-<!-- mcp-toolset: server=1.6.0 version=2026.08.21.1 tools=28 read=15 write=10 exec=3 -->
+<!-- mcp-toolset: server=1.6.0 version=2026.08.28.1 tools=31 read=16 write=10 exec=5 -->
-MSO currently exposes MCP server **1.6.0**, toolset **2026.08.21.1**: **28 tools**
-(15 read, 10 write, 3 exec). Use `GET /mcp` or Settings → MCP as the live authority if
+MSO currently exposes MCP server **1.6.0**, toolset **2026.08.28.1**: **31 tools**
+(16 read, 10 write, 5 exec). Use `GET /mcp` or Settings → MCP as the live authority if
this document and a deployed instance ever disagree.
## 1. What this connection does
@@ -372,3 +372,8 @@ Project and skill discovery are deliberately bounded.
- `docs/CONNECTORS-GATEWAY-INTEGRATION.md` — cross-repo action-name contract
- `docs/MODELS-INTEGRATION.md` — Alfa model credentials and the separate Codex OAuth flow
- `SECURITY.md` — deployment/security posture
+
+
+### Bounded asynchronous execution
+
+`exec_job_start` starts a client/workflow-bound command that may run up to 20 minutes; `exec_job_status` reads its bounded output and final exit state; `exec_job_cancel` stops a still-running job. Use this trio for test/build pipelines instead of wrapping `exec_run` in host-specific background-process plumbing.
diff --git a/docs/CONNECTORS-GATEWAY-INTEGRATION.md b/docs/CONNECTORS-GATEWAY-INTEGRATION.md
index c64e5c58..55b33208 100644
--- a/docs/CONNECTORS-GATEWAY-INTEGRATION.md
+++ b/docs/CONNECTORS-GATEWAY-INTEGRATION.md
@@ -4,10 +4,10 @@
> can evolve independently, so do not claim its mapping count is current without checking
> that repository at the time of the change.
-<!-- mcp-toolset: server=1.6.0 version=2026.08.21.1 tools=28 read=15 write=10 exec=3 -->
+<!-- mcp-toolset: server=1.6.0 version=2026.08.28.1 tools=31 read=16 write=10 exec=5 -->
-MSO currently exposes MCP server **1.6.0**, toolset **2026.08.21.1**: **28 tools**
-(15 read, 10 write, 3 exec). `GET /mcp` exposes the live names, version/hash and scoped
+MSO currently exposes MCP server **1.6.0**, toolset **2026.08.28.1**: **31 tools**
+(16 read, 10 write, 5 exec). `GET /mcp` exposes the live names, version/hash and scoped
manifest and is the machine-readable parity source.
## Why this contract matters
@@ -105,3 +105,8 @@ GET https://<mso-origin>/mcp
Then run MSO's MCP parity/global-tool tests and the gateway's own connector-contract tests.
Do not infer external-gateway parity merely because MSO's internal tests are green.
+
+
+### Bounded asynchronous execution
+
+`exec_job_start` starts a client/workflow-bound command that may run up to 20 minutes; `exec_job_status` reads its bounded output and final exit state; `exec_job_cancel` stops a still-running job. Use this trio for test/build pipelines instead of wrapping `exec_run` in host-specific background-process plumbing.
diff --git a/docs/MCP.md b/docs/MCP.md
index 050a2efa..82850fe1 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -64,9 +64,9 @@ Picked per token, on the consent screen, capped by `OS_MCP_MAX_SCOPE`. The highe
| Scope | Tools |
|---|---|
-| `read` | `fs_list` `fs_read` `fs_search` `fs_usage` `sys_stats` `sys_processes` `apps_list` `apps_logs` `projects_list` `project_capabilities` `skills_list` `skills_read` `skills_search` `screen_capture` `browser_status` |
+| `read` | `fs_list` `fs_read` `fs_search` `fs_usage` `sys_stats` `sys_processes` `apps_list` `apps_logs` `projects_list` `project_capabilities` `skills_list` `skills_read` `skills_search` `screen_capture` `browser_status` `exec_job_status` |
| `write` | + `workflow_start` `workflow_cancel` `workflow_finish` `fs_write` `fs_upload_file` `fs_mkdir` `fs_move` `fs_copy` `fs_delete` `apps_power` |
-| `exec` | + `project_function_call` `exec_run` `browser_power` |
+| `exec` | + `project_function_call` `exec_run` `exec_job_start` `exec_job_cancel` `browser_power` |
Alfa — the in-app assistant — has the same host capabilities under dot.case names,
and `lib/mcp/parity.test.ts` fails if one surface gains a tool the other lacks
@@ -109,10 +109,10 @@ The catalog has a stable server version plus a schema-derived toolset signature.
Settings → MCP shows the current version/hash/count and stores a browser-local acknowledgement when the operator marks ChatGPT refreshed. A later signature change becomes an explicit stale-snapshot warning. This does not mutate ChatGPT remotely; it makes the required refresh visible instead of relying on memory.
-<!-- mcp-toolset: server=1.6.0 version=2026.08.21.1 tools=28 read=15 write=10 exec=3 -->
+<!-- mcp-toolset: server=1.6.0 version=2026.08.28.1 tools=31 read=16 write=10 exec=5 -->
-Current catalog: **28 tools** (15 read, 10 write, 3 exec), server `1.6.0` / toolset
-`2026.08.21.1`. `project_capabilities` and `project_function_call` add one stable
+Current catalog: **31 tools** (16 read, 10 write, 5 exec), server `1.6.0` / toolset
+`2026.08.28.1`. `project_capabilities` and `project_function_call` add one stable
project-automation seam without creating a dynamic MCP tool catalog; existing tool names
remain unchanged.
@@ -572,3 +572,8 @@ app/.well-known/* RFC 9728 + RFC 8414 discovery
cannot prove same-origin, and an MCP client is cross-origin by definition. The
CSRF gate is not the control here — the bearer is, and a browser never attaches
one on its own the way it does a cookie.
+
+
+### Bounded asynchronous execution
+
+`exec_job_start` starts a client/workflow-bound command that may run up to 20 minutes; `exec_job_status` reads its bounded output and final exit state; `exec_job_cancel` stops a still-running job. Use this trio for test/build pipelines instead of wrapping `exec_run` in host-specific background-process plumbing.
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index f61f807f..7b066db1 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -9,6 +9,10 @@ Running log of what shipped each phase. Newest at top.
> [`docs/README.md`](./README.md) and [`docs/ARCHITECTURE.md`](./ARCHITECTURE.md); keep old
> entries intact as historical evidence even when their commands/counts have been superseded.
+## 2026-08-28 (mcp) — bounded async exec jobs (DONE)
+
+Added `exec_job_start`, `exec_job_status`, and `exec_job_cancel` so long test/build pipelines no longer need `systemd-run`/sentinel-file orchestration around the 30-second `exec_run` request limit. Jobs reuse the cwd jail and destructive-command filter, are actor/workflow-bound, capped at 20 minutes and four concurrent jobs per actor, cap each output stream at 1 MiB, and retain completed state for 30 minutes. Toolset is now `1.6.0` / `2026.08.28.1`: **31 tools** (16 read, 10 write, 5 exec).
+
## 2026-08-25 — 9Router configured-domain UI + official icon correction (DONE)
The first public-IP fallback pass made the fallback the preference: because every managed
@@ -201,7 +205,7 @@ verifies the real secret. There is no project/product name or webhook path compi
MSO. Tests pin both sides: stock MSO remains closed, malformed/off-box/wildcard routes fail
closed, `.mso` symlinks are ignored, project commands cannot interpolate caller strings
into a shell, and project function execution remains exec-only. Toolset advances to
-`1.6.0` / `2026.08.21.1`: **28 tools** (15 read, 10 write, 3 exec).
+`1.6.0` / `2026.08.28.1`: **31 tools** (16 read, 10 write, 5 exec).
## 2026-08-20 — lossless continuation and exact-id project resolution (DONE)
diff --git a/lib/host/audit.ts b/lib/host/audit.ts
index ce6aaf7c..c8c21cb5 100644
--- a/lib/host/audit.ts
+++ b/lib/host/audit.ts
@@ -12,6 +12,8 @@ import path from "path";
export type AuditAction =
| "exec.run"
| "exec.blocked"
+ | "exec.job.start"
+ | "exec.job.cancel"
| "term.open"
| "term.close"
| "fs.write"
diff --git a/lib/host/exec-jobs.test.ts b/lib/host/exec-jobs.test.ts
new file mode 100644
index 00000000..75d69bbc
--- /dev/null
+++ b/lib/host/exec-jobs.test.ts
@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { cancelExecJob, getExecJob, startExecJob } from "./exec-jobs";
+
+const ids: string[] = [];
+
+afterEach(() => {
+ for (const id of ids.splice(0)) {
+ try {
+ cancelExecJob(id, "mcp:test", "w1");
+ } catch {
+ // A refused/completed job can already be gone only after retention cleanup.
+ }
+ }
+});
+
+async function start(command: string, actor = "mcp:test") {
+ const job = await startExecJob({ command, actor, workflowId: "w1" });
+ ids.push(job.id);
+ return job;
+}
+
+async function wait(id: string, actor = "mcp:test") {
+ for (let index = 0; index < 100; index += 1) {
+ const job = getExecJob(id, actor, "w1");
+ if (job.state !== "running") return job;
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ }
+ throw new Error("job did not finish");
+}
+
+describe("bounded asynchronous exec jobs", () => {
+ it("returns immediately and later exposes captured output", async () => {
+ const job = await start("sleep 0.05; printf hello");
+ expect(job.state).toBe("running");
+
+ const done = await wait(job.id);
+ expect(done).toMatchObject({
+ state: "completed",
+ code: 0,
+ stdout: "hello",
+ workflowId: "w1",
+ outputTruncated: false,
+ });
+ });
+
+ it("binds status and cancellation to the creating MCP actor", async () => {
+ const job = await start("sleep 2");
+ expect(() => getExecJob(job.id, "mcp:other", "w1")).toThrow("Unknown exec job");
+ expect(() => getExecJob(job.id, "mcp:test", "w2")).toThrow("Unknown exec job");
+ expect(cancelExecJob(job.id, "mcp:test", "w1").state).toBe("cancelled");
+ });
+
+ it("uses the same catastrophic-command refusal as exec_run", async () => {
+ const dangerous = ["dd if=/dev/zero", "of=/dev/sda"].join(" ");
+ const job = await start(dangerous);
+ expect(job).toMatchObject({ state: "refused", code: 126 });
+ expect(job.stderr).toContain("refused:");
+ });
+
+ it("reports non-zero exits without converting them to completed", async () => {
+ const job = await start("printf problem >&2; exit 7");
+ const done = await wait(job.id);
+ expect(done).toMatchObject({ state: "failed", code: 7, stderr: "problem" });
+ });
+});
diff --git a/lib/host/exec-jobs.ts b/lib/host/exec-jobs.ts
new file mode 100644
index 00000000..3cbca63a
--- /dev/null
+++ b/lib/host/exec-jobs.ts
@@ -0,0 +1,178 @@
+// SERVER-ONLY. Bounded asynchronous shell jobs for MCP operations that legitimately
+// outlive exec_run's 30s request budget (tests/builds). Jobs are process-local,
+// owner/workflow-bound, output-capped, runtime-capped, and disappear on restart.
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { childEnv } from "./child-env";
+import { destructiveReason, resolveCwd } from "./exec";
+import { HostError } from "./host-error";
+
+const MAX_RUNTIME_MS = 20 * 60_000;
+const MAX_OUTPUT_BYTES = 1_000_000;
+const MAX_ACTIVE_PER_ACTOR = 4;
+const RETAIN_MS = 30 * 60_000;
+const SHELL = process.platform === "win32" ? process.env.ComSpec || "cmd.exe" : "/bin/bash";
+
+type JobState = "running" | "completed" | "failed" | "cancelled" | "refused";
+
+type ExecJob = {
+ id: string;
+ actor: string;
+ workflowId?: string;
+ cwd: string;
+ state: JobState;
+ startedAt: string;
+ finishedAt?: string;
+ code?: number;
+ signal?: string;
+ stdout: string;
+ stderr: string;
+ stdoutBytes: number;
+ stderrBytes: number;
+ outputTruncated: boolean;
+ child?: ChildProcessWithoutNullStreams;
+ timer?: NodeJS.Timeout;
+};
+
+const jobs = new Map<string, ExecJob>();
+const ownerKey = (actor?: string) => actor || "mcp:anonymous";
+
+function cleanup(now = Date.now()) {
+ for (const [id, job] of jobs) {
+ if (job.state === "running" || !job.finishedAt) continue;
+ if (now - Date.parse(job.finishedAt) > RETAIN_MS) jobs.delete(id);
+ }
+}
+
+function append(job: ExecJob, stream: "stdout" | "stderr", chunk: Buffer) {
+ const bytesKey = stream === "stdout" ? "stdoutBytes" : "stderrBytes";
+ const current = job[bytesKey];
+ const remaining = Math.max(0, MAX_OUTPUT_BYTES - current);
+ if (remaining > 0) job[stream] += chunk.subarray(0, remaining).toString("utf8");
+ job[bytesKey] = current + chunk.byteLength;
+ if (chunk.byteLength > remaining) job.outputTruncated = true;
+}
+
+function publicJob(job: ExecJob) {
+ return {
+ id: job.id,
+ state: job.state,
+ cwd: job.cwd,
+ workflowId: job.workflowId,
+ startedAt: job.startedAt,
+ finishedAt: job.finishedAt,
+ code: job.code,
+ signal: job.signal,
+ stdout: job.stdout,
+ stderr: job.stderr,
+ outputTruncated: job.outputTruncated,
+ };
+}
+
+function ownedJob(id: string, actor?: string, workflowId?: string): ExecJob {
+ cleanup();
+ const job = jobs.get(id);
+ if (
+ !job ||
+ job.actor !== ownerKey(actor) ||
+ (job.workflowId !== undefined && job.workflowId !== workflowId)
+ ) {
+ throw new HostError("Unknown exec job");
+ }
+ return job;
+}
+
+function terminate(job: ExecJob) {
+ const child = job.child;
+ if (!child) return;
+ if (process.platform !== "win32" && child.pid) {
+ try {
+ process.kill(-child.pid, "SIGTERM");
+ setTimeout(() => {
+ if (!job.child || job.state === "completed") return;
+ try { process.kill(-child.pid!, "SIGKILL"); } catch {}
+ }, 2_000).unref();
+ return;
+ } catch {}
+ }
+ child.kill("SIGTERM");
+}
+
+export async function startExecJob(input: {
+ command: string;
+ cwd?: string;
+ actor?: string;
+ workflowId?: string;
+}) {
+ cleanup();
+ if (!input.command.trim()) throw new HostError("Empty command");
+ const actor = ownerKey(input.actor);
+ const active = [...jobs.values()].filter((job) => job.actor === actor && job.state === "running").length;
+ if (active >= MAX_ACTIVE_PER_ACTOR) {
+ throw new HostError(`Too many active exec jobs (max ${MAX_ACTIVE_PER_ACTOR})`);
+ }
+ const cwd = await resolveCwd(input.cwd);
+ const blocked = destructiveReason(input.command);
+ const job: ExecJob = {
+ id: randomUUID(),
+ actor,
+ workflowId: input.workflowId,
+ cwd,
+ state: blocked ? "refused" : "running",
+ startedAt: new Date().toISOString(),
+ stdout: "",
+ stderr: blocked ? `refused: ${blocked}` : "",
+ stdoutBytes: 0,
+ stderrBytes: 0,
+ outputTruncated: false,
+ };
+ jobs.set(job.id, job);
+ if (blocked) {
+ job.code = 126;
+ job.finishedAt = new Date().toISOString();
+ return publicJob(job);
+ }
+
+ const child = spawn(input.command, {
+ cwd,
+ env: childEnv() as NodeJS.ProcessEnv,
+ shell: SHELL,
+ stdio: "pipe",
+ detached: process.platform !== "win32",
+ });
+ job.child = child;
+ child.stdout.on("data", (chunk: Buffer) => append(job, "stdout", chunk));
+ child.stderr.on("data", (chunk: Buffer) => append(job, "stderr", chunk));
+ job.timer = setTimeout(() => {
+ if (job.state !== "running") return;
+ job.state = "failed";
+ job.stderr += `${job.stderr ? "\n" : ""}[timed out after ${MAX_RUNTIME_MS / 60_000}m]`;
+ terminate(job);
+ }, MAX_RUNTIME_MS);
+ child.on("error", (error) => {
+ if (job.state === "running") job.state = "failed";
+ job.stderr += `${job.stderr ? "\n" : ""}${error.message}`;
+ });
+ child.on("close", (code, signal) => {
+ if (job.timer) clearTimeout(job.timer);
+ job.child = undefined;
+ job.timer = undefined;
+ job.code = typeof code === "number" ? code : job.state === "cancelled" ? 130 : 1;
+ job.signal = signal || undefined;
+ if (job.state === "running") job.state = job.code === 0 ? "completed" : "failed";
+ job.finishedAt = new Date().toISOString();
+ });
+ return publicJob(job);
+}
+
+export function getExecJob(id: string, actor?: string, workflowId?: string) {
+ return publicJob(ownedJob(id, actor, workflowId));
+}
+
+export function cancelExecJob(id: string, actor?: string, workflowId?: string) {
+ const job = ownedJob(id, actor, workflowId);
+ if (job.state !== "running" || !job.child) return publicJob(job);
+ job.state = "cancelled";
+ terminate(job);
+ return publicJob(job);
+}
diff --git a/lib/host/index.ts b/lib/host/index.ts
index c7140442..1824b16a 100644
--- a/lib/host/index.ts
+++ b/lib/host/index.ts
@@ -8,6 +8,7 @@ export { zipStream } from "./fs-zip";
export { parseMultipart, boundaryFromContentType, UploadTooLargeError } from "./multipart";
export type { MultipartPart } from "./multipart";
export { runCommand } from "./exec";
+export { startExecJob, getExecJob, cancelExecJob } from "./exec-jobs";
export { sha256Text, utf8Bytes } from "./hash";
export { writeFileGuarded } from "./guarded-write";
export { resolveProjectHint, inspectProject } from "./projects";
diff --git a/lib/mcp/dispatch.ts b/lib/mcp/dispatch.ts
index bcad8a86..4c020ee8 100644
--- a/lib/mcp/dispatch.ts
+++ b/lib/mcp/dispatch.ts
@@ -39,7 +39,7 @@ function instructions(scope: Scope): string {
const startup = scope === "read"
? "This token is read-only: use skills_search for capability discovery, then bounded read tools. Verify the answer without attempting workflow memory writes."
: "For any task needing two or more operational calls, call workflow_start directly as the ONE startup call; it already searches trusted skills and recipes, resolves the project, and reports the current toolset. Multiple workflows may run in parallel on one token. Use workflow_finish or workflow_cancel with the exact id, and pass that workflow_id on every operational call in its run; omit it for standalone work. Verify before workflow_finish.";
- return `${startup} Prefer bounded tools for one or two direct operations. At exec scope, use one narrow exec_run batch for repository-wide search, git, tests, builds, or three or more related checks. Show concise progress using badges such as [Skills], [Files], [Terminal], [Git], [Build], [Verify], and [Screenshot]; never expose private chain-of-thought.`;
+ return `${startup} Prefer bounded tools for one or two direct operations. At exec scope, use one narrow exec_run batch for short repository-wide search/git checks; use exec_job_start + exec_job_status for tests/builds that may exceed 30 seconds. Show concise progress using badges such as [Skills], [Files], [Terminal], [Git], [Build], [Verify], and [Screenshot]; never expose private chain-of-thought.`;
}
function flowFields(workflow: ActiveWorkflow | null | undefined) {
diff --git a/lib/mcp/parity.test.ts b/lib/mcp/parity.test.ts
index 920fb9ce..329da6dd 100644
--- a/lib/mcp/parity.test.ts
+++ b/lib/mcp/parity.test.ts
@@ -41,6 +41,9 @@ const MCP_ONLY: Record<string, string> = {
"workflow.start": "the external connector needs an actor-scoped task boundary; Alfa already owns an in-app conversation/run boundary",
"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",
+ "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",
};
describe("Alfa ↔ MCP capability parity", () => {
@@ -101,6 +104,9 @@ describe("MCP rate limits mirror the routes", () => {
// MCP clients and is expensive enough to deserve a much smaller bucket.
"screen.capture": 10,
"workflow.memory": 30,
+ "exec.job.start": 12,
+ "exec.job.status": 120,
+ "exec.job.cancel": 30,
// Global discovery reads: no HTTP route mirrors them, and each one walks
// every configured container, so they get their own small buckets.
"projects.list": 30,
diff --git a/lib/mcp/tools-learning.ts b/lib/mcp/tools-learning.ts
index 2c6fc3c0..9b0d3591 100644
--- a/lib/mcp/tools-learning.ts
+++ b/lib/mcp/tools-learning.ts
@@ -76,7 +76,7 @@ export const LEARNING_TOOLS: McpTool[] = [
],
policy: {
simple: "Use bounded tools for one or two direct operations.",
- repository: "For repository-wide search, git, tests, builds, or 3+ related checks, use one narrow exec_run batch when exec scope is available.",
+ repository: "For short repository-wide search/git checks use one narrow exec_run batch; for tests/builds that may exceed 30 seconds use exec_job_start and poll exec_job_status.",
progress: "Show only high-level feature/tool badges and outcomes; never private chain-of-thought.",
finish: "Call workflow_finish with this exact workflow id only after independent verification; use workflow_cancel for an abandoned run.",
},
diff --git a/lib/mcp/tools.ts b/lib/mcp/tools.ts
index c9d06287..013068e1 100644
--- a/lib/mcp/tools.ts
+++ b/lib/mcp/tools.ts
@@ -1,4 +1,4 @@
-import { writeFileGuarded, makeDir, remove, move, copy, runCommand, resolveProjectHint, runProjectFunction } from "@/lib/host";
+import { writeFileGuarded, makeDir, remove, move, copy, runCommand, startExecJob, getExecJob, cancelExecJob, resolveProjectHint, runProjectFunction } from "@/lib/host";
import { type McpTool, str, opt, S, PATH_P } from "./tool-kit";
import { importOpenAiProvidedFile } from "./openai-file-upload";
import { READ_TOOLS } from "./tools-read";
@@ -134,6 +134,52 @@ const MUTATE_TOOLS: McpTool[] = [
return runProjectFunction(project.path, str(a, "name"), a.input);
},
},
+ {
+ name: "exec_job_start",
+ limit: { key: "exec.job.start", max: 12, windowMs: 60_000 },
+ audit: {
+ action: "exec.job.start" as const,
+ targetArg: "command",
+ outcome: (r) => {
+ const row = r as { state: string };
+ const refused = row.state === "refused";
+ return { ok: !refused, action: refused ? "exec.blocked" : "exec.job.start", detail: refused ? "refused" : "started" };
+ },
+ },
+ description:
+ "Start one bounded asynchronous shell job for legitimate test/build pipelines that exceed exec_run's 30s request budget. " +
+ "The job is client/workflow-bound, capped at 20 minutes and 1 MiB per output stream, limited to four concurrent jobs per client, and uses the same cwd jail and catastrophic-command filter as exec_run. Use exec_job_status to read it and exec_job_cancel to stop it.",
+ scope: "exec",
+ annotations: { destructiveHint: true, openWorldHint: true },
+ inputSchema: S({
+ command: { type: "string", description: "The shell command line to run asynchronously." },
+ cwd: { type: "string", description: "Working directory. Defaults to the owner's home." },
+ }, ["command"]),
+ run: (a, context) => startExecJob({
+ command: str(a, "command"), cwd: opt(a, "cwd"), actor: context.actor, workflowId: context.workflowId,
+ }),
+ },
+ {
+ name: "exec_job_status",
+ limit: { key: "exec.job.status", max: 120, windowMs: 60_000 },
+ description:
+ "Read one asynchronous exec job owned by this MCP client. Returns state, bounded stdout/stderr, exit code when finished, and whether output was truncated.",
+ scope: "read",
+ annotations: { readOnlyHint: true, idempotentHint: true },
+ inputSchema: S({ job_id: { type: "string", description: "Exact id returned by exec_job_start." } }, ["job_id"]),
+ run: (a, context) => Promise.resolve(getExecJob(str(a, "job_id"), context.actor, context.workflowId)),
+ },
+ {
+ name: "exec_job_cancel",
+ limit: { key: "exec.job.cancel", max: 30, windowMs: 60_000 },
+ audit: { action: "exec.job.cancel" as const, targetArg: "job_id" },
+ description:
+ "Cancel one still-running asynchronous exec job owned by this MCP client. Repeated cancellation is idempotent.",
+ scope: "exec",
+ annotations: { destructiveHint: true, idempotentHint: true },
+ inputSchema: S({ job_id: { type: "string", description: "Exact id returned by exec_job_start." } }, ["job_id"]),
+ run: (a, context) => Promise.resolve(cancelExecJob(str(a, "job_id"), context.actor, context.workflowId)),
+ },
{
name: "exec_run",
limit: { key: "exec", max: 60, windowMs: 60_000 },
diff --git a/lib/mcp/toolset.ts b/lib/mcp/toolset.ts
index a607eaab..657eca91 100644
--- a/lib/mcp/toolset.ts
+++ b/lib/mcp/toolset.ts
@@ -3,8 +3,8 @@ import type { Scope } from "./scope";
import type { McpTool } from "./tool-kit";
export const MCP_SERVER_VERSION = "1.6.0";
-export const MCP_TOOLSET_VERSION = "2026.08.21.1";
-export const MCP_TOOLSET_CHANGED_AT = "2026-08-21T13:45:00Z";
+export const MCP_TOOLSET_VERSION = "2026.08.28.1";
+export const MCP_TOOLSET_CHANGED_AT = "2026-08-28T07:02:00Z";
export type McpToolsetInfo = {
serverVersion: string;