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): add eval-gated tool forge

Rahman86078f597ef6
diff --git a/.env.example b/.env.example
index c97f3b54..b89d3d97 100644
--- a/.env.example
+++ b/.env.example
@@ -205,6 +205,8 @@ OS_SESSION_SECRET=
# OS_THREADS_DIR=~/.mso/threads # Alfa assistant chat threads (one file each)
# OS_AGENT_MEMORY_DIR=~/.mso/agent-memory # isolated MSO Agent USER.md/MEMORY.md stores
# OS_AGENT_SESSIONS_DIR=~/.mso/agent-sessions # durable CLI/MCP agent session records
+# OS_TOOL_FORGE_DIR=~/.mso/tool-forge # private inert Tool Forge candidate/evaluation records
+# OS_TOOL_FORGE_NODE_IMAGE=mso-forge-sandbox:node22-v1 # labelled cached Docker image used only for executable Forge fixtures
# OS_A2A_STORE=~/.mso/private/a2a-agents.json # public A2A Agent Card registry; no credentials
# Session context is estimated provider-neutrally and compacted when it reaches this
# threshold. Raw/older context is first written as a SANITIZED gzip backup; secrets
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index ba0168d7..519c24e8 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,6 +8,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.
**Added**
+- `agent` add eval-gated tool forge
- `agent` add interactive permissions and a2a v1
## 2026-09-01
diff --git a/docs/CHATGPT-PLUGIN.md b/docs/CHATGPT-PLUGIN.md
index 5cf14436..6ac42fef 100644
--- a/docs/CHATGPT-PLUGIN.md
+++ b/docs/CHATGPT-PLUGIN.md
@@ -12,10 +12,10 @@
> <https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt-beta>
> and <https://help.openai.com/en/articles/20001256-plugins-in-chatgpt-and-codex>.
-<!-- mcp-toolset: server=1.6.0 version=2026.09.02.3 tools=55 read=28 write=22 exec=5 -->
+<!-- mcp-toolset: server=1.6.0 version=2026.09.02.4 tools=59 read=29 write=23 exec=7 -->
-MSO currently exposes MCP server **1.6.0**, toolset **2026.09.02.3**: **56 transport tools** total; **55 model/operator tools**
-(28 read, 22 write, 5 exec) plus app-only `workflow_status` for the progress widget. Use `GET /mcp` or Settings → MCP as the live authority if
+MSO currently exposes MCP server **1.6.0**, toolset **2026.09.02.4**: **60 transport tools** total; **59 model/operator tools**
+(29 read, 23 write, 7 exec) plus app-only `workflow_status` for the progress widget. Use `GET /mcp` or Settings → MCP as the live authority if
this document and a deployed instance ever disagree.
## 1. What this connection does
@@ -141,7 +141,7 @@ A token sees a scope prefix; there is no per-project or per-agent hidden tool fi
`tools/list` filters the catalog and `tools/call` independently re-checks the required
scope.
-### `read` — 28 model/operator tools
+### `read` — 29 model/operator tools
- `a2a_agent_discover`
- `a2a_agents_list`
@@ -171,7 +171,8 @@ scope.
- `skills_search`
- `sys_processes`
- `sys_stats`
-### `write` — read + 22 tools
+- `tool_forge_candidates`
+### `write` — read + 23 tools
- `a2a_agent_register`
- `a2a_agent_remove`
@@ -192,23 +193,33 @@ scope.
- `fs_upload_file`
- `fs_write`
- `hostinger_dns_upsert`
+- `tool_forge_propose`
- `workflow_cancel`
- `workflow_finish`
- `workflow_start`
-### `exec` — write + 5 tools
+### `exec` — write + 7 tools
- `browser_power`
- `exec_job_cancel`
- `exec_job_start`
- `exec_run`
- `project_function_call`
+- `tool_forge_evaluate`
+- `tool_forge_promote`
`exec_run` is full host shell power as the MSO service user. The command filter is an
accident tripwire, not a sandbox. Grant `exec` only to a ChatGPT app/workspace you trust
with the same care as a remote shell.
+
+### Tool Forge approval model
+
+`tool_forge_propose` creates only inert candidates from repeated verified workflow recipes. Skill candidates are guidance only; a project-function candidate must point to an existing project-owned Node script and must come from an exec-scope verified recipe. Generated shell/code, credential-like fixture data, and implicit scope escalation are rejected.
+
+`tool_forge_evaluate` runs executable fixtures only in the labelled local MSO Forge Docker sandbox. `tool_forge_promote` requires exact `PROMOTE <candidate_id>` confirmation and a fresh passing evaluation immediately before mutation. Candidate hash, target manifest, current toolset, project source SHA-256 and exact sandbox image evidence are checked again, and existing Skills/functions are never overwritten. Provision the local sandbox explicitly with `bun run forge:sandbox`; evaluation never auto-pulls an image.
+
### Infrastructure-provider actions
The infrastructure tools never accept API tokens as arguments. ChatGPT sees masked provider
@@ -242,7 +253,7 @@ Settings → MCP:
server: 1.6.0
toolset: 2026.09.02.3
hash: <live schema hash>
-count: 55 model/operator tools (+ 1 app-only bridge)
+count: 59 model/operator tools (+ 1 app-only bridge)
```
Use this sequence after an MSO MCP change:
diff --git a/docs/COGNITIVE-RUNTIME.md b/docs/COGNITIVE-RUNTIME.md
index 00a5cc43..f1b2603f 100644
--- a/docs/COGNITIVE-RUNTIME.md
+++ b/docs/COGNITIVE-RUNTIME.md
@@ -136,17 +136,17 @@ probe. Overall product superiority also cannot be inferred from a prompt-size re
must add equivalent task-success, tool-error, token-per-success, latency-per-success, and policy-compliance
scenarios before making that claim.
-## Current P1 + A2A baseline
+## Current P2 + A2A baseline
-On the development host after P1 implementation:
+On the development host after P2 + outbound A2A integration:
-| Metric | MSO P1 | Hermes local baseline |
+| Metric | MSO P2 + A2A | Hermes local baseline |
|---|---:|---:|
-| Full MSO transport catalog | 56 tools | — |
-| Full MSO schema bytes | 37,904 | — |
-| Average MSO active tools / turn | 15.5 | — |
-| Average active schema bytes / turn | 11,582 | 44,758 tool-schema bytes |
-| MSO schema reduction vs full catalog | 69.4% | — |
+| Full MSO transport catalog | 60 tools | — |
+| Full MSO schema bytes | 41,519 | — |
+| Average MSO active tools / turn | 15.4 | — |
+| Average active schema bytes / turn | 11,614 | 44,758 tool-schema bytes |
+| MSO schema reduction vs full catalog | 72.0% | — |
| Required-tool routing recall | 100% | not the same benchmark |
| Typed-memory fixture accuracy | 100% (8/8) | not implemented in this harness |
| Deterministic routing / memory resolution | yes / yes | not the same benchmark |
@@ -157,17 +157,20 @@ A non-interactive full MSO tool loop is now available as `mso agent --oneshot <p
These numbers are reproducible harness baselines, not an overall quality leaderboard. Cross-agent ranking is permitted only when at least two runners complete the same task with matching model-family evidence; one-task latency order is explicitly not an overall-agent claim.
-## P1 status and next direction
+## P2 status and next direction
-P1 now implements the first three planned runtime layers: typed/provenance-aware temporal memory, deterministic retrieval evaluation, and workflow/tool quality telemetry. It also adds the non-interactive MSO Agent runner and a fail-closed cross-agent scratch harness.
+P1 supplies typed/provenance-aware temporal memory, deterministic retrieval evaluation, workflow/tool quality telemetry, the non-interactive MSO Agent runner, and a fail-closed cross-agent scratch harness. P2 adds the first self-improvement primitive without granting opaque autonomy: an **eval-gated Tool Forge**.
-The next phase should build on those measured primitives rather than add opaque autonomy:
+Forge only creates inert candidates from repeated high-quality recipes. Skill candidates are deterministic redacted guidance; executable project-function candidates require an exec-scope verified recipe and may reference only existing project-owned Node code. Fixtures run in the dedicated cached Docker sandbox with no network and a read-only project mount. Evaluation records current toolset, candidate/target state, source SHA-256 and exact sandbox image evidence; promotion requires literal confirmation and immediately repeats the checks. A candidate cannot silently raise scope, overwrite an existing capability, or turn generated text into host-executable code.
-1. **Eval-gated Tool Forge** — repeated verified workflows may propose project functions/Skills, but generated code stays untrusted until static checks, sandboxed fixture tests, scope review and explicit promotion pass.
-2. **Programmatic read-only orchestration** — bulk filtering/aggregation may reduce model round-trips while remaining constrained by caller scope and normal host guards.
-3. **Benchmark corpus expansion** — add multiple read/write/recovery/security task classes and configure Hermes/OpenClaw with an actually equivalent model/provider path before any overall comparison.
-4. **Memory calibration** — grow post-P1 quality telemetry and test confidence/authority policy against real corrections before introducing graph-memory complexity.
-5. **Cost-per-success accounting** — normalize provider usage reports only where token/cost semantics are comparable; missing usage must remain unknown, never zero.
+Outbound A2A v1 remains orthogonal: it adds remote-agent delegation, while Forge turns repeated **local verified procedures** into reviewed project capabilities. The combined routing benchmark covers both surfaces with 100% required-tool recall while selecting only 15.4 of 60 tools on average.
+
+The next phase should continue from measured primitives:
+
+1. **Programmatic read-only orchestration** — bulk filtering/aggregation may reduce model round-trips while remaining constrained by caller scope and normal host guards.
+2. **Benchmark corpus expansion** — add multiple read/write/recovery/security task classes and configure Hermes/OpenClaw with an actually equivalent model/provider path before any overall comparison.
+3. **Memory calibration** — grow post-P1 quality telemetry and test confidence/authority policy against real corrections before introducing graph-memory complexity.
+4. **Cost-per-success accounting** — normalize provider usage reports only where token/cost semantics are comparable; missing usage must remain unknown, never zero.
## Security notes
@@ -175,6 +178,7 @@ The next phase should build on those measured primitives rather than add opaque
- Persistent memory is data, never an instruction or permission source.
- A discovered Skill or recipe cannot grant a tool the caller's token does not already permit.
- Untrusted Skills keep their instructions withheld until promoted through the existing trust process.
+- Tool Forge candidates are inert. Executable fixtures require the labelled local Docker sandbox; evaluation never auto-pulls an image or executes generated shell/code.
- `exec_run` remains full service-user shell power at `exec` scope; cognitive routing is not a sandbox.
- Never expose raw ChatGPT conversation ids, tokens, credentials, hidden chain-of-thought, or unrestricted
tool output in memory/recipes/archives.
diff --git a/docs/CONNECTORS-GATEWAY-INTEGRATION.md b/docs/CONNECTORS-GATEWAY-INTEGRATION.md
index fa3f488e..9ea5ddce 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.09.02.3 tools=55 read=28 write=22 exec=5 -->
+<!-- mcp-toolset: server=1.6.0 version=2026.09.02.4 tools=59 read=29 write=23 exec=7 -->
-MSO currently exposes MCP server **1.6.0**, toolset **2026.09.02.3**: **56 transport tools** total; **55 model/operator tools**
-(28 read, 22 write, 5 exec) plus app-only `workflow_status`. `GET /mcp` exposes the live names, version/hash and scoped
+MSO currently exposes MCP server **1.6.0**, toolset **2026.09.02.4**: **60 transport tools** total; **59 model/operator tools**
+(29 read, 23 write, 7 exec) plus app-only `workflow_status`. `GET /mcp` exposes the live names, version/hash and scoped
manifest and is the machine-readable parity source.
## Why this contract matters
@@ -33,25 +33,25 @@ Before changing an MCP tool name:
## Current MSO catalog
-### Read (28 model/operator)
+### Read (29 model/operator)
`a2a_agent_discover`, `a2a_agents_list`, `a2a_task_get`, `agent_memory_read`, `agent_memory_search`, `agent_session_current`, `agent_session_resume`, `agent_sessions_list`,
`apps_list`, `apps_logs`, `browser_status`, `cloudflare_zones_list`, `dokploy_projects_list`,
`exec_job_status`, `fs_list`, `fs_read`, `fs_search`, `fs_usage`, `infra_provider_doctor`,
`infra_providers_list`, `project_capabilities`, `projects_list`, `screen_capture`, `skills_list`,
-`skills_read`, `skills_search`, `sys_processes`, `sys_stats`.
+`skills_read`, `skills_search`, `sys_processes`, `sys_stats`, `tool_forge_candidates`.
-### Write (22 beyond read)
+### Write (23 beyond read)
`a2a_agent_register`, `a2a_agent_remove`, `a2a_message_send`, `a2a_task_cancel`, `a2a_handoff`,
`agent_memory_forget`, `agent_memory_remember`, `agent_session_note`, `agent_session_rename`,
`apps_power`, `cloudflare_dns_upsert`, `dokploy_project_ensure`, `fs_copy`, `fs_delete`,
`fs_mkdir`, `fs_move`, `fs_upload_file`, `fs_write`, `hostinger_dns_upsert`,
-`workflow_cancel`, `workflow_finish`, `workflow_start`.
+`tool_forge_propose`, `workflow_cancel`, `workflow_finish`, `workflow_start`.
-### Exec (5 beyond write)
+### Exec (7 beyond write)
-`browser_power`, `exec_job_cancel`, `exec_job_start`, `exec_run`, `project_function_call`.
+`browser_power`, `exec_job_cancel`, `exec_job_start`, `exec_run`, `project_function_call`, `tool_forge_evaluate`, `tool_forge_promote`.
### App-only bridge (1)
@@ -73,6 +73,9 @@ that field can still call the tools, but those calls are standalone and will not
MSO learned workflow. For multi-step orchestration, expose the workflow trio and propagate
the exact id returned by `workflow_start`.
+
+Tool Forge remains a stable global action family as well: gateways should expose the four generic `tool_forge_*` names, never synthesize one action per generated candidate. Candidate ids are data. Executable evaluation is server-side in the dedicated local Docker sandbox, and promotion remains exec-scope with exact confirmation.
+
## Project functions are data, not dynamic MCP names
A project may publish `.mso/functions.json`. The gateway does not need a new MSO action for
@@ -99,6 +102,7 @@ Treat these as particularly important in any external approval layer:
- `exec_run` — host shell as the MSO user;
- `browser_power` — starts a browser profile with live logged-in sessions;
- `project_function_call` — executes project-owned fixed argv and is always exec-scope;
+- `tool_forge_evaluate` / `tool_forge_promote` — sandbox-evaluate and explicitly promote inert learned-workflow candidates; promotion requires a fresh passing evaluation and literal confirmation;
- `dokploy_project_ensure` / `cloudflare_dns_upsert` / `hostinger_dns_upsert` — mutate external infrastructure with provider credentials kept server-side; Hostinger receives only the requested name/type RR-set (`overwrite:true`), never an MSO-generated full-zone snapshot.
External policy supplements MSO's own scope/path/audit/rate-limit checks; it does not replace
diff --git a/docs/MCP.md b/docs/MCP.md
index 54257d18..72e42f7e 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -124,10 +124,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.09.02.3 tools=55 read=28 write=22 exec=5 -->
+<!-- mcp-toolset: server=1.6.0 version=2026.09.02.4 tools=59 read=29 write=23 exec=7 -->
-Current transport catalog: **56 tools**, server `1.6.0` / toolset `2026.09.02.3`.
-The model/operator catalog is **55 tools** (28 read, 22 write, 5 exec); `workflow_status` is the
+Current transport catalog: **60 tools**, server `1.6.0` / toolset `2026.09.02.4`.
+The model/operator catalog is **59 tools** (29 read, 23 write, 7 exec); `workflow_status` is the
one app-only MCP Apps bridge used by the progress widget and is documented separately.
`agent_memory_search` is the typed-memory retrieval surface. It resolves semantic/episodic/procedural claims at an optional point in time, returns confidence/provenance and competing effective claims, and can expose superseded/retracted history when explicitly requested. `agent_memory_remember` remains the write surface and now accepts typed metadata; raw ChatGPT conversation ids are never stored as provenance.
@@ -148,6 +148,17 @@ fails closed when an Agent Card requires credentials. A normal message transmits
message/context/task arguments; a handoff never auto-attaches the caller's hidden transcript,
memory or raw session/workflow ids. See [`A2A.md`](./A2A.md) for the transport and trust contract.
+
+### Eval-gated Tool Forge
+
+Tool Forge is a **candidate pipeline**, not a self-authorizing code generator. `tool_forge_propose` accepts only learned recipes with P1 quality telemetry, at least two verified successes, at least 90% workflow success, and a fully-completed best trace. `tool_forge_candidates` exposes reviewable metadata while redacting fixed argv, fixture payloads, and internal workflow targets. Candidates are inert until explicit evaluation and promotion.
+
+Skill candidates contain only deterministic redacted tool guidance. Project-function candidates do **not** generate executable code and cannot escalate a read/write recipe: they require an exec-scope verified recipe and may reference only an existing regular project-owned Node script. Credential-like schema fields, fixture payloads, and fixed argv are rejected.
+
+`tool_forge_evaluate` re-checks the current tool catalog/scope and runs 1–8 executable fixtures only in the dedicated cached Docker sandbox. The sandbox uses no network, a read-only root and project mount, all Linux capabilities dropped, `no-new-privileges`, non-root execution, and CPU/memory/PID limits. `bun run forge:sandbox` provisions the labelled local image from the host's already-trusted Node binary and shared libraries; evaluation never pulls from a registry and records the exact image ID plus project source SHA-256.
+
+`tool_forge_promote` is exec-scope and requires literal confirmation `PROMOTE <candidate_id>`. Promotion immediately re-runs evaluation, rejects candidate/target/toolset/source/image drift, never overwrites an existing Skill/function, writes atomically, and verifies the resulting project capability. A promoted project function still requires normal `project_function_call` exec scope and approval.
+
## Opt-in project MCP/function capabilities
MSO itself stays generic. A project opts into extra automation by placing files inside
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index ff7ddb38..3adfb376 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -2,6 +2,14 @@
Running log of what shipped each phase. Newest at top.
+## 2026-09-02 — Eval-gated Tool Forge P2 — SHIPPED
+
+Cognitive Runtime P2 adds a self-improvement path without turning learned workflows into self-authorizing code. Four MCP primitives expose a private candidate lifecycle: `tool_forge_candidates` (read), `tool_forge_propose` (write), `tool_forge_evaluate` (exec), and `tool_forge_promote` (exec). Proposal requires P1 quality telemetry, at least two verified successes, at least 90% success, and a fully-completed best trace. Skill candidates contain only deterministic redacted tool guidance. Project-function candidates cannot generate shell/code or escalate a lower-scope recipe: they require an exec-scope verified recipe and may reference only an existing regular project-owned Node script; credential-like schema fields, fixture inputs, and fixed argv are rejected.
+
+Executable fixtures run only in a dedicated **local-only Docker sandbox**: no registry pull, `--network none`, read-only root/project mounts, all capabilities dropped, `no-new-privileges`, non-root execution, and bounded CPU/memory/PIDs. `bun run forge:sandbox` constructs the minimal sandbox from the already-trusted host Node binary plus its shared libraries and labels it as MSO Forge v1. Evaluation rejects missing/unlabelled images and records the exact image ID plus project source SHA-256. Regression coverage proves fixture network access and project writes are blocked.
+
+Promotion is intentionally high-friction: the caller must send literal `PROMOTE <candidate_id>`, MSO immediately re-runs the complete evaluation, candidate/target/toolset/source/image drift fails closed, existing Skills/functions are never overwritten, writes are atomic, and the resulting project capability is independently parsed/trust-checked. Combined with outbound A2A v1, MCP toolset **2026.09.02.4** contains **60 transport / 59 model tools** (29 read, 23 write, 7 exec). `bench:cognitive` still reaches **100% required-tool routing recall** while averaging **15.4 active tools / 11,614 schema bytes**, a **72.0% reduction** from the full catalog.
+
## 2026-09-02 — Interactive permission badge + outbound A2A v1 — SHIPPED
MSO CLI **1.7.0** makes permission state part of the interactive prompt instead of terminal scrollback. The bottom-left prompt is now a persistent color-coded badge (`ask` cyan, `auto` amber, `yolo` red); Tab on an empty prompt cycles `ask → auto → yolo` by repainting the same row with zero added LF/newline. The compact status line no longer duplicates permission. `/permission` remains the explicit picker/command surface, and the existing exact-call digest/server authorization semantics are unchanged. A live PTY regression proves three Tab transitions emit no scrollback line.
diff --git a/lib/forge/evaluate.ts b/lib/forge/evaluate.ts
new file mode 100644
index 00000000..28f2bab2
--- /dev/null
+++ b/lib/forge/evaluate.ts
@@ -0,0 +1,130 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import type { Scope } from "@/lib/mcp/scope";
+import { runForgeFixture, validateForgeCommand } from "./sandbox";
+import type { ForgeCandidate, ForgeCheck, ForgeEvaluation, ForgeFixture, ForgeFunctionSpec } from "./types";
+
+const SCOPE_RANK: Record<Scope, number> = { read: 0, write: 1, exec: 2 };
+const MAX_SKILL_BYTES = 24 * 1024;
+
+function hashJson(value: unknown): string {
+ return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+export function forgeCandidateHash(candidate: ForgeCandidate): string {
+ return hashJson({
+ version: candidate.version, id: candidate.id, ownerHash: candidate.ownerHash, kind: candidate.kind,
+ projectPath: candidate.projectPath, recipe: candidate.recipe, requiredScope: candidate.requiredScope,
+ skill: candidate.skill, function: candidate.function,
+ });
+}
+
+function pass(checks: ForgeCheck[], id: string, detail: string): void { checks.push({ id, state: "pass", detail }); }
+function fail(checks: ForgeCheck[], id: string, detail: string): void { checks.push({ id, state: "fail", detail }); }
+
+async function regularProject(projectPath: string): Promise<string | null> {
+ const stat = await fs.lstat(projectPath).catch(() => null);
+ if (!stat?.isDirectory() || stat.isSymbolicLink()) return null;
+ const real = await fs.realpath(projectPath).catch(() => null);
+ return real === path.resolve(projectPath) ? real : null;
+}
+
+async function currentTargetHash(candidate: ForgeCandidate): Promise<string> {
+ const target = candidate.kind === "skill"
+ ? path.join(candidate.projectPath, ".mso", "skills", candidate.skill!.name, "SKILL.md")
+ : path.join(candidate.projectPath, ".mso", "functions.json");
+ const stat = await fs.lstat(target).catch(() => null);
+ if (!stat) return "absent";
+ if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 512 * 1024) return "invalid";
+ return createHash("sha256").update(await fs.readFile(target)).digest("hex");
+}
+
+function recipeChecks(candidate: ForgeCandidate, checks: ForgeCheck[]): void {
+ const recipe = candidate.recipe, successRate = recipe.attempts > 0 ? recipe.successes / recipe.attempts : 0;
+ if (recipe.qualityVersion === 1) pass(checks, "recipe.telemetry", "P1 quality telemetry present");
+ else fail(checks, "recipe.telemetry", "recipe lacks P1 quality telemetry");
+ if (recipe.successes >= 2) pass(checks, "recipe.repetition", `${recipe.successes} verified successes`);
+ else fail(checks, "recipe.repetition", "requires at least two verified successes");
+ if (successRate >= 0.9) pass(checks, "recipe.success_rate", `${Math.round(successRate * 1000) / 10}% success`);
+ else fail(checks, "recipe.success_rate", `success rate ${Math.round(successRate * 1000) / 10}% is below 90%`);
+ if (recipe.bestSteps.length > 0 && recipe.bestSteps.every((step) => step.state === "completed")) pass(checks, "recipe.trace", "best trace is fully completed");
+ else fail(checks, "recipe.trace", "best trace contains non-completed steps");
+}
+
+function toolChecks(candidate: ForgeCandidate, knownTools: Map<string, Scope>, checks: ForgeCheck[]): void {
+ for (const step of candidate.recipe.bestSteps) {
+ const scope = knownTools.get(step.tool);
+ if (!scope) { fail(checks, `tool.${step.tool}`, "tool no longer exists in the current catalog"); continue; }
+ if (SCOPE_RANK[scope] > SCOPE_RANK[candidate.requiredScope]) {
+ fail(checks, `tool.${step.tool}`, `tool now needs ${scope}, above candidate ${candidate.requiredScope} scope`);
+ } else pass(checks, `tool.${step.tool}`, `current scope ${scope}`);
+ }
+}
+
+function fixturePass(fixture: ForgeFixture, result: { code: number; stdout: string; stderr: string }): string | null {
+ const expected = fixture.expect ?? {}, code = expected.code ?? 0;
+ if (result.code !== code) { const note = result.stderr.trim().replace(/\s+/g, " ").slice(0, 180); return `exit ${result.code}, expected ${code}${note ? `: ${note}` : ""}`; }
+ if (expected.stdoutIncludes && !result.stdout.includes(expected.stdoutIncludes)) return "stdout did not contain required marker";
+ if (expected.stderrExcludes && result.stderr.includes(expected.stderrExcludes)) return "stderr contained forbidden marker";
+ return null;
+}
+
+type ForgeFixtureRunner = (projectPath: string, spec: ForgeFunctionSpec, fixture: ForgeFixture) => Promise<{ code: number; stdout: string; stderr: string; sandboxImageId?: string }>;
+
+async function functionChecks(candidate: ForgeCandidate, checks: ForgeCheck[], runner: ForgeFixtureRunner): Promise<{ count: number; sandboxImageId?: string; sourceHash?: string }> {
+ const spec = candidate.function!;
+ let sourceHash: string | undefined;
+ try { const resolved = await validateForgeCommand(candidate.projectPath, spec); sourceHash = createHash("sha256").update(await fs.readFile(resolved.script)).digest("hex"); pass(checks, "function.command", "fixed argv resolves only to approved project-owned Node code"); }
+ catch (error) { fail(checks, "function.command", error instanceof Error ? error.message : String(error)); return { count: 0 }; }
+ if (!spec.fixtures.length) { fail(checks, "function.fixtures", "at least one fixture is required"); return { count: 0 }; }
+ let ran = 0, sandboxImageId: string | undefined;
+ for (const fixture of spec.fixtures) {
+ const result = await runner(candidate.projectPath, spec, fixture); ran++;
+ const evidence = result as typeof result & { sandboxImageId?: string }; if (evidence.sandboxImageId) sandboxImageId = evidence.sandboxImageId;
+ const reason = fixturePass(fixture, result);
+ if (reason) fail(checks, `fixture.${fixture.name}`, reason);
+ else pass(checks, `fixture.${fixture.name}`, "sandbox fixture passed");
+ }
+ return { count: ran, ...(sandboxImageId ? { sandboxImageId } : {}), ...(sourceHash ? { sourceHash } : {}) };
+}
+
+export async function evaluateForgeCandidate(input: {
+ candidate: ForgeCandidate;
+ knownTools: Map<string, Scope>;
+ toolsetHash?: string;
+ fixtureRunner?: ForgeFixtureRunner;
+}): Promise<ForgeEvaluation> {
+ const checks: ForgeCheck[] = [];
+ const projectReal = await regularProject(input.candidate.projectPath);
+ if (projectReal) pass(checks, "project.containment", "project is a regular non-symlink directory");
+ else fail(checks, "project.containment", "project path is missing, symlinked, or no longer canonical");
+ recipeChecks(input.candidate, checks);
+ toolChecks(input.candidate, input.knownTools, checks);
+
+ let fixtureCount = 0, sandboxImageId: string | undefined, sourceHash: string | undefined;
+ if (input.candidate.kind === "skill") {
+ const bytes = Buffer.byteLength(input.candidate.skill?.content ?? "");
+ if (bytes > 0 && bytes <= MAX_SKILL_BYTES) pass(checks, "skill.size", `${bytes} bytes`);
+ else fail(checks, "skill.size", `Skill must be 1-${MAX_SKILL_BYTES} bytes`);
+ const target = await currentTargetHash(input.candidate);
+ if (target === "absent") pass(checks, "skill.target", "destination does not already exist");
+ else fail(checks, "skill.target", "destination already exists or is unsafe; forge never overwrites a Skill");
+ } else if (projectReal) {
+ const fixtures = await functionChecks(input.candidate, checks, input.fixtureRunner ?? runForgeFixture); fixtureCount = fixtures.count; sandboxImageId = fixtures.sandboxImageId; sourceHash = fixtures.sourceHash;
+ }
+
+ const targetHash = await currentTargetHash(input.candidate);
+ return {
+ version: 1,
+ candidateHash: forgeCandidateHash(input.candidate),
+ passed: checks.every((check) => check.state !== "fail"),
+ evaluatedAt: new Date().toISOString(),
+ checks,
+ targetHash,
+ ...(input.toolsetHash ? { toolsetHash: input.toolsetHash } : {}),
+ fixtureCount,
+ ...(sandboxImageId ? { sandboxImageId } : {}),
+ ...(sourceHash ? { sourceHash } : {}),
+ };
+}
diff --git a/lib/forge/forge.test.ts b/lib/forge/forge.test.ts
new file mode 100644
index 00000000..93edbd62
--- /dev/null
+++ b/lib/forge/forge.test.ts
@@ -0,0 +1,157 @@
+import { existsSync, promises as fs } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { LearnedRecipe, WorkflowQuality } from "@/lib/skills/memory";
+import { projectSkillTrust } from "@/lib/skills/project-skills";
+import { readProjectFunctionsManifest } from "@/lib/host/project-function-manifest";
+import { runProjectFunction } from "@/lib/host/project-function-runner";
+import { evaluateForgeCandidate } from "./evaluate";
+import { promoteForgeCandidate } from "./promote";
+import { proposeForgeCandidate } from "./proposal";
+
+const QUALITY: WorkflowQuality = {
+ stepAttempts: 2, completedSteps: 2, failedSteps: 0, deniedSteps: 0, rateLimitedSteps: 0,
+ invalidArgSteps: 0, retries: 0, rollbackSignals: 0, timedSteps: 2, totalStepDurationMs: 20, averageStepDurationMs: 10,
+};
+
+function recipe(overrides: Partial<LearnedRecipe> = {}): LearnedRecipe {
+ const now = "2026-09-02T05:00:00.000Z";
+ return {
+ id: "recipe-1", actor: "mcp-client:test", scope: "read", intent: "inspect project health", normalizedIntent: "inspect project health",
+ project: "/tmp/project", summary: "verified project health", embeddingVersion: "test", embedding: [],
+ bestSteps: [
+ { id: "1", tool: "projects_list", state: "completed", target: "project", ts: now },
+ { id: "2", tool: "sys_stats", state: "completed", target: "server", ts: now },
+ ],
+ lastSteps: [], attempts: 2, successes: 2, failures: 0, averageDurationMs: 10, fastestDurationMs: 9,
+ lastDurationMs: 9, averageWallDurationMs: 12, lastWallDurationMs: 11, quality: QUALITY, lastQuality: QUALITY,
+ qualityVersion: 1, createdAt: now, updatedAt: now, ...overrides,
+ };
+}
+
+async function tempProject(): Promise<{ root: string; project: string; forge: string }> {
+ const root = await fs.mkdtemp(path.join(process.cwd(), ".mso-forge-test-"));
+ const project = path.join(root, "project"), forge = path.join(root, "forge");
+ await fs.mkdir(project, { recursive: true });
+ process.env.OS_TOOL_FORGE_DIR = forge;
+ return { root, project, forge };
+}
+
+
+const dockerSandboxAvailable = existsSync("/usr/bin/docker") && spawnSync(
+ "/usr/bin/docker", ["image", "inspect", "mso-forge-sandbox:node22-v1"], { stdio: "ignore", timeout: 3000 },
+).status === 0;
+
+const roots: string[] = [];
+afterEach(async () => {
+ delete process.env.OS_TOOL_FORGE_DIR;
+ await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })));
+ vi.restoreAllMocks();
+});
+
+describe("eval-gated Tool Forge", () => {
+ it("refuses to forge from a one-off workflow without repeated verified success", async () => {
+ const { root, project } = await tempProject(); roots.push(root);
+ await expect(proposeForgeCandidate({ owner: "owner", recipe: recipe({ attempts: 1, successes: 1 }), kind: "skill", projectPath: project }))
+ .rejects.toThrow(/at least two verified successful runs/i);
+ });
+
+ it("generates a bounded Skill, evaluates current tool references, promotes once, and refuses overwrite", async () => {
+ const { root, project } = await tempProject(); roots.push(root);
+ const candidate = await proposeForgeCandidate({ owner: "owner", recipe: recipe(), kind: "skill", projectPath: project, name: "project-health" });
+ const evaluation = await evaluateForgeCandidate({
+ candidate,
+ knownTools: new Map([["projects_list", "read"], ["sys_stats", "read"]]),
+ toolsetHash: "toolset-test",
+ });
+ expect(evaluation.passed).toBe(true);
+ const evaluated = { ...candidate, state: "evaluated" as const, evaluation };
+ const promotion = await promoteForgeCandidate(evaluated);
+ const skillDir = path.dirname(promotion.path);
+ expect(await projectSkillTrust(skillDir, project)).toBe("local");
+ await expect(promoteForgeCandidate(evaluated)).rejects.toThrow(/overwrite an existing Skill/i);
+ });
+
+ it("refuses to turn a read-scope recipe into an executable project function", async () => {
+ const { root, project } = await tempProject(); roots.push(root);
+ await expect(proposeForgeCandidate({
+ owner: "owner", recipe: recipe({ scope: "read" }), kind: "project_function", projectPath: project, name: "scope-escalation",
+ command: [process.execPath, "tool.mjs"], inputSchema: { type: "object", properties: {} }, fixtures: [{ name: "x", input: {} }],
+ })).rejects.toThrow(/exec-scope verified recipe/i);
+ });
+
+ it("rejects credential-like project-function inputs and fixtures", async () => {
+ const { root, project } = await tempProject(); roots.push(root);
+ await expect(proposeForgeCandidate({
+ owner: "owner", recipe: recipe({ scope: "exec" }), kind: "project_function", projectPath: project, name: "secret-input",
+ command: [process.execPath, "tool.mjs"], inputSchema: { type: "object", properties: { apiKey: { type: "string" } } },
+ fixtures: [{ name: "secret", input: { token: "sk-example-secret-value" } }],
+ })).rejects.toThrow(/credential-like/i);
+ });
+
+ it("rejects shell-inline project functions before any fixture runs", async () => {
+ const { root, project } = await tempProject(); roots.push(root);
+ const candidate = await proposeForgeCandidate({
+ owner: "owner", recipe: recipe({ scope: "exec" }), kind: "project_function", projectPath: project, name: "bad-shell",
+ command: ["/bin/bash", "-c", "echo unsafe"], inputSchema: { type: "object", properties: {} }, fixtures: [{ name: "nope", input: {} }],
+ });
+ const evaluation = await evaluateForgeCandidate({ candidate, knownTools: new Map([["projects_list", "read"], ["sys_stats", "read"]]) });
+ expect(evaluation.passed).toBe(false);
+ expect(evaluation.checks.find((row) => row.id === "function.command")?.state).toBe("fail");
+ expect(evaluation.fixtureCount).toBe(0);
+ });
+
+ it.runIf(dockerSandboxAvailable)("runs fixtures in the Docker sandbox before promoting an existing project-owned Node function", async () => {
+ const { root, project } = await tempProject(); roots.push(root);
+ const script = path.join(project, "echo-function.mjs");
+ await fs.writeFile(script, `let s=""; for await (const c of process.stdin) s+=c; const v=JSON.parse(s); console.log("OK:"+v.value);\n`, { mode: 0o700 });
+ const candidate = await proposeForgeCandidate({
+ owner: "owner", recipe: recipe({ scope: "exec" }), kind: "project_function", projectPath: project, name: "echo-payload",
+ description: "Echo a validated fixture payload", command: [process.execPath, "echo-function.mjs"],
+ inputSchema: { type: "object", properties: { value: { type: "string" } }, required: ["value"], additionalProperties: false },
+ fixtures: [{ name: "basic", input: { value: "fixture" }, expect: { code: 0, stdoutIncludes: "OK:fixture" } }],
+ });
+ const evaluation = await evaluateForgeCandidate({ candidate, knownTools: new Map([["projects_list", "read"], ["sys_stats", "read"]]) });
+ expect(evaluation.passed).toBe(true);
+ expect(evaluation.fixtureCount).toBe(1);
+ const evaluated = { ...candidate, state: "evaluated" as const, evaluation };
+ await promoteForgeCandidate(evaluated);
+ const manifest = await readProjectFunctionsManifest(project);
+ expect(manifest.found && manifest.functions?.some((row) => row.name === "echo-payload")).toBe(true);
+ const result = await runProjectFunction(project, "echo-payload", { value: "runtime" });
+ expect(result).toMatchObject({ code: 0 });
+ expect(result.stdout).toContain("OK:runtime");
+ });
+
+ it.runIf(dockerSandboxAvailable)("refuses promotion when project-owned source changes after evaluation", async () => {
+ const { root, project } = await tempProject(); roots.push(root);
+ const script = path.join(project, "drift.mjs");
+ await fs.writeFile(script, `console.log("v1");\n`, { mode: 0o700 });
+ const candidate = await proposeForgeCandidate({
+ owner: "owner", recipe: recipe({ scope: "exec" }), kind: "project_function", projectPath: project, name: "drift-proof",
+ command: [process.execPath, "drift.mjs"], inputSchema: { type: "object", properties: {}, additionalProperties: false },
+ fixtures: [{ name: "v1", input: {}, expect: { stdoutIncludes: "v1" } }],
+ });
+ const evaluation = await evaluateForgeCandidate({ candidate, knownTools: new Map([["projects_list", "read"], ["sys_stats", "read"]]) });
+ expect(evaluation.passed).toBe(true);
+ await fs.writeFile(script, `console.log("v2");\n`, { mode: 0o700 });
+ await expect(promoteForgeCandidate({ ...candidate, state: "evaluated", evaluation })).rejects.toThrow(/source changed after evaluation/i);
+ });
+
+ it.runIf(dockerSandboxAvailable)("keeps the project mount read-only and network disabled inside Forge fixtures", async () => {
+ const { root, project } = await tempProject(); roots.push(root);
+ const script = path.join(project, "sandbox-proof.mjs");
+ await fs.writeFile(script, `import fs from "node:fs"; let ro=false, net=false; try { fs.writeFileSync("forge-escape.txt", "x"); } catch { ro=true; } try { await fetch("http://127.0.0.1:4005", { signal: AbortSignal.timeout(500) }); } catch { net=true; } console.log("RO:"+ro+" NET:"+net);\n`, { mode: 0o700 });
+ const candidate = await proposeForgeCandidate({
+ owner: "owner", recipe: recipe({ scope: "exec" }), kind: "project_function", projectPath: project, name: "sandbox-proof",
+ command: [process.execPath, "sandbox-proof.mjs"], inputSchema: { type: "object", properties: {}, additionalProperties: false },
+ fixtures: [{ name: "isolation", input: {}, expect: { code: 0, stdoutIncludes: "RO:true NET:true" } }],
+ });
+ const evaluation = await evaluateForgeCandidate({ candidate, knownTools: new Map([["projects_list", "read"], ["sys_stats", "read"]]) });
+ expect(evaluation.passed).toBe(true);
+ expect(evaluation.sandboxImageId).toMatch(/^sha256:/);
+ expect(await fs.lstat(path.join(project, "forge-escape.txt")).catch(() => null)).toBeNull();
+ });
+
+});
diff --git a/lib/forge/promote.ts b/lib/forge/promote.ts
new file mode 100644
index 00000000..a70226ba
--- /dev/null
+++ b/lib/forge/promote.ts
@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { projectSkillTrust } from "@/lib/skills/project-skills";
+import { readProjectFunctionsManifest } from "@/lib/host/project-function-manifest";
+import { forgeCandidateHash } from "./evaluate";
+import { validateForgeCommand } from "./sandbox";
+import type { ForgeCandidate, ForgePromotion } from "./types";
+
+function hash(data: Buffer | string): string { return createHash("sha256").update(data).digest("hex"); }
+function inside(root: string, child: string): boolean {
+ const rel = path.relative(root, child); return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+async function safeMsoDir(projectPath: string): Promise<string> {
+ const projectReal = await fs.realpath(projectPath);
+ const mso = path.join(projectReal, ".mso"), stat = await fs.lstat(mso).catch(() => null);
+ if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new Error("project .mso must be a regular directory");
+ if (!stat) await fs.mkdir(mso, { mode: 0o700 });
+ const real = await fs.realpath(mso);
+ if (!inside(projectReal, real) || real !== mso) throw new Error("project .mso escapes project containment");
+ return real;
+}
+
+async function targetHash(file: string): Promise<string> {
+ const stat = await fs.lstat(file).catch(() => null);
+ if (!stat) return "absent";
+ if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 512 * 1024) return "invalid";
+ return hash(await fs.readFile(file));
+}
+
+function assertEvaluated(candidate: ForgeCandidate): void {
+ const evaluation = candidate.evaluation;
+ if (!evaluation?.passed) throw new Error("forge candidate has not passed evaluation");
+ if (evaluation.candidateHash !== forgeCandidateHash(candidate)) throw new Error("forge candidate changed after evaluation; evaluate again");
+}
+
+async function promoteSkill(candidate: ForgeCandidate): Promise<ForgePromotion> {
+ const mso = await safeMsoDir(candidate.projectPath), root = path.join(mso, "skills"), dir = path.join(root, candidate.skill!.name);
+ await fs.mkdir(root, { recursive: true, mode: 0o700 });
+ const existing = await fs.lstat(dir).catch(() => null); if (existing) throw new Error("forge refuses to overwrite an existing Skill");
+ await fs.mkdir(dir, { mode: 0o700 });
+ const file = path.join(dir, "SKILL.md");
+ try {
+ await fs.writeFile(file, candidate.skill!.content, { mode: 0o600, flag: "wx" });
+ const trust = await projectSkillTrust(dir, candidate.projectPath);
+ if (trust !== "local") throw new Error(`promoted Skill did not earn local trust (${trust})`);
+ return { at: new Date().toISOString(), path: file, verification: "projectSkillTrust=local" };
+ } catch (error) {
+ await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined); throw error;
+ }
+}
+
+async function promoteFunction(candidate: ForgeCandidate): Promise<ForgePromotion> {
+ const source = await validateForgeCommand(candidate.projectPath, candidate.function!);
+ const sourceHash = hash(await fs.readFile(source.script));
+ if (!candidate.evaluation?.sourceHash || candidate.evaluation.sourceHash !== sourceHash) throw new Error("project function source changed after evaluation; evaluate again");
+ const mso = await safeMsoDir(candidate.projectPath), file = path.join(mso, "functions.json");
+ const expected = candidate.evaluation?.targetHash ?? "";
+ if (await targetHash(file) !== expected) throw new Error("project functions manifest changed after evaluation; evaluate again");
+ const current = await readProjectFunctionsManifest(candidate.projectPath);
+ if (current.found && !current.functions) throw new Error(current.error ?? "existing functions manifest is invalid");
+ const functions = current.found ? (current.functions ?? []) : [];
+ if (functions.some((row) => row.name === candidate.function!.name)) throw new Error("forge refuses to overwrite an existing project function");
+ const next = [...functions, {
+ name: candidate.function!.name,
+ description: candidate.function!.description,
+ inputSchema: candidate.function!.inputSchema,
+ command: candidate.function!.command,
+ timeoutMs: candidate.function!.timeoutMs,
+ }];
+ if (next.length > 32) throw new Error("project function manifest would exceed 32 functions");
+ const tmp = `${file}.${process.pid}.forge.tmp`;
+ await fs.writeFile(tmp, `${JSON.stringify({ version: 1, functions: next }, null, 2)}\n`, { mode: 0o600 });
+ await fs.rename(tmp, file);
+ const verified = await readProjectFunctionsManifest(candidate.projectPath);
+ const verifiedFunctions = verified.found ? verified.functions : undefined;
+ if (!verifiedFunctions?.some((row) => row.name === candidate.function!.name)) throw new Error("promoted function failed manifest verification");
+ return { at: new Date().toISOString(), path: file, verification: "functions.json parsed and candidate present" };
+}
+
+export async function promoteForgeCandidate(candidate: ForgeCandidate): Promise<ForgePromotion> {
+ assertEvaluated(candidate);
+ return candidate.kind === "skill" ? promoteSkill(candidate) : promoteFunction(candidate);
+}
diff --git a/lib/forge/proposal.ts b/lib/forge/proposal.ts
new file mode 100644
index 00000000..ee572a4a
--- /dev/null
+++ b/lib/forge/proposal.ts
@@ -0,0 +1,139 @@
+import type { LearnedRecipe } from "@/lib/skills/memory";
+import { createForgeCandidate, forgeOwnerHash, newForgeCandidateId } from "./store";
+import type { ForgeCandidate, ForgeFixture, ForgeFunctionSpec, ForgeKind, ForgeRecipeSnapshot } from "./types";
+
+const NAME_RE = /^[a-z][a-z0-9_.-]{0,63}$/;
+const SECRETISH = /(password|passwd|secret|token|authorization|bearer|api[_-]?key)/i;
+const plainObject = (value: unknown): value is Record<string, unknown> => Boolean(value && typeof value === "object" && !Array.isArray(value));
+
+function cleanText(value: string, max: number): string {
+ return value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim().slice(0, max);
+}
+
+function slug(value: string): string {
+ const base = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 56);
+ return /^[a-z]/.test(base) ? base : `workflow-${base || "candidate"}`;
+}
+
+function candidateName(value: string | undefined, recipe: LearnedRecipe): string {
+ const name = cleanText(value || slug(recipe.intent), 64).toLowerCase();
+ if (!NAME_RE.test(name)) throw new Error("forge candidate name must match ^[a-z][a-z0-9_.-]{0,63}$");
+ return name;
+}
+
+function recipeSnapshot(recipe: LearnedRecipe): ForgeRecipeSnapshot {
+ return {
+ id: recipe.id,
+ scope: recipe.scope,
+ intent: cleanText(recipe.intent, 1000),
+ summary: cleanText(recipe.summary, 1200),
+ attempts: recipe.attempts,
+ successes: recipe.successes,
+ failures: recipe.failures,
+ ...(recipe.qualityVersion === 1 ? { qualityVersion: 1 as const } : {}),
+ quality: recipe.quality,
+ bestSteps: recipe.bestSteps.map((step) => ({ tool: step.tool, state: step.state, ...(step.target ? { target: cleanText(step.target, 160) } : {}) })),
+ updatedAt: recipe.updatedAt,
+ };
+}
+
+export function assertRecipeForgeEligible(recipe: LearnedRecipe): void {
+ if (recipe.qualityVersion !== 1) throw new Error("recipe has no P1 quality telemetry; run and verify it again before forging");
+ if (recipe.successes < 2) throw new Error("tool forge requires at least two verified successful runs");
+ const rate = recipe.attempts > 0 ? recipe.successes / recipe.attempts : 0;
+ if (rate < 0.9) throw new Error("tool forge requires at least 90% workflow success");
+ if (!recipe.bestSteps.length || recipe.bestSteps.some((step) => step.state !== "completed")) {
+ throw new Error("tool forge requires a fully completed best workflow trace");
+ }
+}
+
+function skillContent(name: string, recipe: ForgeRecipeSnapshot): string {
+ const description = cleanText(`Verified procedure for ${recipe.intent}`, 220);
+ const steps = recipe.bestSteps.map((step, index) => `${index + 1}. Use \`${step.tool}\` under the caller's normal scope/approval guards.`).join("\n");
+ return `---\nname: ${name}\ndescription: ${JSON.stringify(description)}\nuser-invocable: false\nmetadata:\n mso:\n forged: true\n recipe: ${recipe.id}\n required-scope: ${recipe.scope}\n---\n\n# ${name}\n\nGenerated from a repeated, verified MSO workflow. This Skill is guidance only: it never grants permissions and every tool call still uses the caller's normal scope/approval guards.\n\n## Verified procedure\n\n${steps}\n\n## Verification\n\nRe-check the requested outcome independently before reporting success. For multi-step MCP work, keep the exact workflow id and finish only after verification.\n`;
+}
+
+function inputSchema(value: unknown): ForgeFunctionSpec["inputSchema"] {
+ if (value === undefined) return { type: "object", properties: {}, additionalProperties: false };
+ if (!plainObject(value) || value.type !== "object" || !plainObject(value.properties)) throw new Error("input_schema must be an object JSON Schema");
+ const secretProperty = Object.keys(value.properties).find((key) => SECRETISH.test(key));
+ if (secretProperty) throw new Error(`input_schema may not expose credential-like field ${secretProperty}; use server-side project configuration`);
+ const required = value.required;
+ if (required !== undefined && (!Array.isArray(required) || !required.every((row) => typeof row === "string"))) throw new Error("input_schema.required must be a string array");
+ if (value.additionalProperties !== undefined && typeof value.additionalProperties !== "boolean") throw new Error("input_schema.additionalProperties must be boolean");
+ return {
+ type: "object",
+ properties: value.properties,
+ ...(required ? { required: [...new Set(required)] } : {}),
+ ...(typeof value.additionalProperties === "boolean" ? { additionalProperties: value.additionalProperties } : {}),
+ };
+}
+
+function containsSecretLikePayload(value: unknown, depth = 0): boolean {
+ if (depth > 8) return true;
+ if (Array.isArray(value)) return value.some((row) => containsSecretLikePayload(row, depth + 1));
+ if (!plainObject(value)) return typeof value === "string" && /^(?:Bearer\s+|sk-[A-Za-z0-9_-]{12,})/i.test(value.trim());
+ return Object.entries(value).some(([key, row]) => SECRETISH.test(key) || containsSecretLikePayload(row, depth + 1));
+}
+
+function fixtures(value: unknown): ForgeFixture[] {
+ if (!Array.isArray(value) || value.length === 0 || value.length > 8) throw new Error("project-function candidates require 1-8 fixtures");
+ return value.map((row, index) => {
+ if (!plainObject(row) || !plainObject(row.input)) throw new Error(`fixtures[${index}] must contain an object input`);
+ if (containsSecretLikePayload(row.input)) throw new Error(`fixtures[${index}] contains credential-like input; Forge fixtures must use non-secret synthetic data`);
+ const expect = plainObject(row.expect) ? row.expect : undefined;
+ return {
+ name: cleanText(typeof row.name === "string" ? row.name : `fixture-${index + 1}`, 80),
+ input: row.input,
+ ...(expect ? { expect: {
+ ...(Number.isInteger(expect.code) ? { code: Number(expect.code) } : {}),
+ ...(typeof expect.stdoutIncludes === "string" ? { stdoutIncludes: cleanText(expect.stdoutIncludes, 240) } : {}),
+ ...(typeof expect.stderrExcludes === "string" ? { stderrExcludes: cleanText(expect.stderrExcludes, 240) } : {}),
+ } } : {}),
+ };
+ });
+}
+
+export async function proposeForgeCandidate(input: {
+ owner: string;
+ recipe: LearnedRecipe;
+ kind: ForgeKind;
+ projectPath: string;
+ name?: string;
+ description?: string;
+ command?: unknown;
+ inputSchema?: unknown;
+ fixtures?: unknown;
+ timeoutMs?: number;
+}): Promise<ForgeCandidate> {
+ assertRecipeForgeEligible(input.recipe);
+ const name = candidateName(input.name, input.recipe), recipe = recipeSnapshot(input.recipe);
+ const now = new Date().toISOString();
+ const base = {
+ version: 1 as const,
+ id: newForgeCandidateId(),
+ ownerHash: forgeOwnerHash(input.owner),
+ kind: input.kind,
+ state: "draft" as const,
+ projectPath: input.projectPath,
+ recipe,
+ requiredScope: recipe.scope,
+ createdAt: now,
+ updatedAt: now,
+ };
+ if (input.kind === "skill") return createForgeCandidate({ ...base, skill: { name, content: skillContent(name, recipe) } });
+
+ if (input.recipe.scope !== "exec") throw new Error("project-function Forge candidates require an exec-scope verified recipe; read/write recipes cannot be promoted into executable capabilities");
+ if (!Array.isArray(input.command) || input.command.length < 1 || !input.command.every((row) => typeof row === "string")) {
+ throw new Error("project-function candidate command must be a fixed argv string array");
+ }
+ const fn: ForgeFunctionSpec = {
+ name,
+ description: cleanText(input.description || `Forged project function for ${recipe.intent}`, 600),
+ inputSchema: inputSchema(input.inputSchema),
+ command: input.command.slice(0, 16) as string[],
+ timeoutMs: Number.isInteger(input.timeoutMs) ? Math.max(1000, Math.min(30_000, Number(input.timeoutMs))) : 10_000,
+ fixtures: fixtures(input.fixtures),
+ };
+ return createForgeCandidate({ ...base, requiredScope: "exec", function: fn });
+}
diff --git a/lib/forge/sandbox.ts b/lib/forge/sandbox.ts
new file mode 100644
index 00000000..55d94694
--- /dev/null
+++ b/lib/forge/sandbox.ts
@@ -0,0 +1,103 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { spawn, spawnSync, type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { ForgeFixture, ForgeFunctionSpec } from "./types";
+
+const SECRETISH = /(password|passwd|secret|token|authorization|bearer|api[_-]?key)/i;
+const MAX_CAPTURE = 64 * 1024;
+const DEFAULT_NODE_IMAGE = "mso-forge-sandbox:node22-v1";
+
+function inside(root: string, child: string): boolean {
+ const rel = path.relative(root, child);
+ return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+async function regularProjectFile(projectReal: string, value: string): Promise<string | null> {
+ const candidate = path.resolve(projectReal, value);
+ const real = await fs.realpath(candidate).catch(() => null);
+ if (!real || !inside(projectReal, real)) return null;
+ const stat = await fs.lstat(candidate).catch(() => null);
+ if (!stat?.isFile() || stat.isSymbolicLink()) return null;
+ return real;
+}
+
+export type ForgeCommandResolution = {
+ interpreter: "node";
+ script: string;
+ fixedArgs: string[];
+};
+
+export async function validateForgeCommand(projectPath: string, spec: ForgeFunctionSpec): Promise<ForgeCommandResolution> {
+ const projectReal = await fs.realpath(projectPath).catch(() => null);
+ if (!projectReal) throw new Error("forge project no longer exists");
+ if (!spec.command.length || spec.command.length > 16 || spec.command.some((arg) => arg.length > 512 || arg.includes("\0"))) {
+ throw new Error("forge command must contain 1-16 bounded fixed argv strings");
+ }
+ if (spec.command.some((arg) => SECRETISH.test(arg))) throw new Error("forge command contains secret-like fixed argv; use project-owned runtime configuration instead");
+
+ const head = path.basename(spec.command[0]!);
+ if (head !== "node") throw new Error("P2 forged project functions support only Node scripts; arbitrary executables and shell interpreters are not accepted");
+ if (spec.command.length < 2 || spec.command[1]!.startsWith("-")) throw new Error("node forge functions must name a project-owned script as argv[1]");
+ const script = await regularProjectFile(projectReal, spec.command[1]!);
+ if (!script) throw new Error("forge Node target must be a regular non-symlink file inside the project");
+ return { interpreter: "node", script, fixedArgs: spec.command.slice(2) };
+}
+
+function sandboxImage(): string {
+ return process.env.OS_TOOL_FORGE_NODE_IMAGE?.trim() || DEFAULT_NODE_IMAGE;
+}
+
+export function forgeSandboxImageEvidence(): { image: string; imageId: string } {
+ const image = sandboxImage();
+ // `docker image inspect` is intentionally local-only. Evaluation never pulls an image or hits a registry.
+ const format = '{{.Id}}|{{ index .Config.Labels "org.mso.tool-forge.version" }}|{{ index .Config.Labels "org.mso.tool-forge.runtime" }}';
+ const found = spawnSync("/usr/bin/docker", ["image", "inspect", "--format", format, image], {
+ encoding: "utf8", timeout: 5_000, env: { PATH: "/usr/bin:/bin" } as unknown as NodeJS.ProcessEnv,
+ });
+ const [imageId, version, runtime] = String(found.stdout).trim().split("|");
+ if (found.status !== 0 || !imageId) {
+ throw new Error(`Tool Forge sandbox image is not cached locally: ${image}; run scripts/provision-forge-sandbox.sh explicitly`);
+ }
+ if (version !== "1" || runtime !== "node") {
+ throw new Error(`Tool Forge sandbox image ${image} lacks the required MSO Forge v1/node provenance labels; reprovision it before evaluation`);
+ }
+ return { image, imageId };
+}
+
+export async function runForgeFixture(projectPath: string, spec: ForgeFunctionSpec, fixture: ForgeFixture): Promise<{ code: number; stdout: string; stderr: string; sandboxImageId: string }> {
+ const resolved = await validateForgeCommand(projectPath, spec);
+ const projectReal = await fs.realpath(projectPath);
+ const { image, imageId } = forgeSandboxImageEvidence();
+ const relScript = path.relative(projectReal, resolved.script);
+ if (!relScript || relScript.startsWith("..") || path.isAbsolute(relScript)) throw new Error("forge script escaped project snapshot");
+ const sandboxScript = `/workspace/${relScript.split(path.sep).join("/")}`;
+ const uid = typeof process.getuid === "function" ? process.getuid() : 65534;
+ const gid = typeof process.getgid === "function" ? process.getgid() : 65534;
+ const runtimeSec = Math.max(1, Math.ceil(Math.min(spec.timeoutMs, 5_000) / 1000));
+ const args = [
+ "run", "--rm", "-i", "--network", "none", "--read-only", "--cap-drop", "ALL",
+ "--security-opt", "no-new-privileges", "--pids-limit", "64", "--memory", "256m", "--cpus", "1",
+ "--user", `${uid}:${gid}`, "--workdir", "/workspace", "--env", "HOME=/tmp", "--env", "TMPDIR=/tmp",
+ "--tmpfs", "/tmp:rw,noexec,nosuid,nodev,size=32m",
+ "--mount", `type=bind,src=${projectReal},dst=/workspace,readonly`,
+ "--entrypoint", "/usr/bin/node", imageId, sandboxScript, ...resolved.fixedArgs,
+ ];
+ const payload = JSON.stringify(fixture.input);
+ return new Promise((resolve) => {
+ const child = spawn("/usr/bin/docker", args, {
+ stdio: ["pipe", "pipe", "pipe"], env: { PATH: "/usr/bin:/bin" } as unknown as NodeJS.ProcessEnv,
+ }) as ChildProcessWithoutNullStreams;
+ let stdout = "", stderr = "", finished = false;
+ const append = (current: string, chunk: Buffer) => (current + chunk.toString("utf8")).slice(0, MAX_CAPTURE);
+ child.stdout.on("data", (chunk: Buffer) => { stdout = append(stdout, chunk); });
+ child.stderr.on("data", (chunk: Buffer) => { stderr = append(stderr, chunk); });
+ const timer = setTimeout(() => { if (!finished) child.kill("SIGKILL"); }, (runtimeSec + 2) * 1000);
+ child.on("error", (error: Error) => {
+ if (!finished) { finished = true; clearTimeout(timer); resolve({ code: 1, stdout, stderr: `${stderr}${error.message}`, sandboxImageId: imageId }); }
+ });
+ child.on("close", (code: number | null) => {
+ if (!finished) { finished = true; clearTimeout(timer); resolve({ code: code ?? 1, stdout, stderr, sandboxImageId: imageId }); }
+ });
+ child.stdin.end(payload);
+ });
+}
diff --git a/lib/forge/store.ts b/lib/forge/store.ts
new file mode 100644
index 00000000..3ab594f4
--- /dev/null
+++ b/lib/forge/store.ts
@@ -0,0 +1,115 @@
+import { createHash, randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { withSecurityStoreLock } from "@/lib/security-store-lock";
+import type { ForgeCandidate, PublicForgeCandidate } from "./types";
+
+const ID_RE = /^forge_[0-9]{8}_[0-9]{6}_[a-f0-9]{12}$/;
+
+function forgeRoot(): string {
+ const raw = process.env.OS_TOOL_FORGE_DIR?.trim();
+ return path.resolve((raw || path.join(os.homedir(), ".mso", "tool-forge")).replace(/^~(?=$|\/)/, os.homedir()));
+}
+
+function candidatesDir(): string { return path.join(forgeRoot(), "candidates"); }
+function candidatePath(id: string): string {
+ if (!ID_RE.test(id)) throw new Error("invalid forge candidate id");
+ return path.join(candidatesDir(), `${id}.json`);
+}
+
+export function forgeOwnerHash(owner: string): string {
+ return createHash("sha256").update(owner).digest("hex");
+}
+
+export function newForgeCandidateId(now = new Date()): string {
+ const stamp = now.toISOString().replace(/[-:]/g, "").replace("T", "_").slice(0, 15);
+ return `forge_${stamp}_${randomUUID().replace(/-/g, "").slice(0, 12)}`;
+}
+
+async function ensureRoot(): Promise<void> {
+ await fs.mkdir(candidatesDir(), { recursive: true, mode: 0o700 });
+ await fs.chmod(forgeRoot(), 0o700).catch(() => undefined);
+ await fs.chmod(candidatesDir(), 0o700).catch(() => undefined);
+}
+
+async function readCandidateFile(file: string): Promise<ForgeCandidate | null> {
+ const stat = await fs.lstat(file).catch(() => null);
+ if (!stat) return null;
+ if (!stat.isFile() || stat.isSymbolicLink() || stat.size <= 0 || stat.size > 256 * 1024) throw new Error("invalid forge candidate file");
+ return JSON.parse(await fs.readFile(file, "utf8")) as ForgeCandidate;
+}
+
+async function writeCandidateFile(file: string, candidate: ForgeCandidate): Promise<void> {
+ await ensureRoot();
+ const tmp = `${file}.${process.pid}.tmp`;
+ await fs.writeFile(tmp, `${JSON.stringify(candidate, null, 2)}\n`, { mode: 0o600 });
+ await fs.rename(tmp, file);
+ await fs.chmod(file, 0o600).catch(() => undefined);
+}
+
+export async function createForgeCandidate(candidate: ForgeCandidate): Promise<ForgeCandidate> {
+ await ensureRoot();
+ const file = candidatePath(candidate.id);
+ const exists = await fs.lstat(file).catch(() => null);
+ if (exists) throw new Error("forge candidate id collision");
+ await writeCandidateFile(file, candidate);
+ return candidate;
+}
+
+export async function getForgeCandidate(id: string, owner: string): Promise<ForgeCandidate | null> {
+ const row = await readCandidateFile(candidatePath(id));
+ if (!row) return null;
+ if (row.ownerHash !== forgeOwnerHash(owner)) return null;
+ return row;
+}
+
+export async function listForgeCandidates(owner: string): Promise<ForgeCandidate[]> {
+ await ensureRoot();
+ const ownerHash = forgeOwnerHash(owner);
+ const names = await fs.readdir(candidatesDir()).catch(() => [] as string[]);
+ const rows: ForgeCandidate[] = [];
+ for (const name of names.sort()) {
+ if (!/^forge_[0-9]{8}_[0-9]{6}_[a-f0-9]{12}\.json$/.test(name)) continue;
+ const row = await readCandidateFile(path.join(candidatesDir(), name)).catch(() => null);
+ if (row?.ownerHash === ownerHash) rows.push(row);
+ }
+ return rows.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+export async function updateForgeCandidate(
+ id: string,
+ owner: string,
+ mutate: (candidate: ForgeCandidate) => ForgeCandidate | Promise<ForgeCandidate>,
+): Promise<ForgeCandidate> {
+ const file = candidatePath(id);
+ return withSecurityStoreLock(file, async () => {
+ const current = await readCandidateFile(file);
+ if (!current || current.ownerHash !== forgeOwnerHash(owner)) throw new Error("forge candidate not found");
+ const next = await mutate(current);
+ await writeCandidateFile(file, next);
+ return next;
+ });
+}
+
+export function publicForgeCandidate(candidate: ForgeCandidate): PublicForgeCandidate {
+ const { ownerHash: _ownerHash, function: fn, ...rest } = candidate;
+ return {
+ ...rest,
+ recipe: { ...rest.recipe, bestSteps: rest.recipe.bestSteps.map(({ tool, state }) => ({ tool, state })) },
+ ...(fn ? {
+ function: {
+ name: fn.name,
+ description: fn.description,
+ inputSchema: fn.inputSchema,
+ timeoutMs: fn.timeoutMs,
+ fixtureCount: fn.fixtures.length,
+ command: fn.command.length ? { executable: path.basename(fn.command[0]!), argvCount: fn.command.length } : undefined,
+ },
+ } : {}),
+ };
+}
+
+export function resetForgeStoreForTests(): void {
+ // Store is intentionally file-backed with no module cache. Kept for symmetry and future migrations.
+}
diff --git a/lib/forge/types.ts b/lib/forge/types.ts
new file mode 100644
index 00000000..e527b4f7
--- /dev/null
+++ b/lib/forge/types.ts
@@ -0,0 +1,101 @@
+import type { Scope } from "@/lib/mcp/scope";
+import type { WorkflowQuality, WorkflowStep } from "@/lib/skills/memory";
+
+export const FORGE_VERSION = 1 as const;
+export type ForgeKind = "skill" | "project_function";
+export type ForgeState = "draft" | "evaluated" | "promoted";
+export type ForgeCheckState = "pass" | "fail" | "warn";
+
+export type ForgeCheck = {
+ id: string;
+ state: ForgeCheckState;
+ detail: string;
+};
+
+export type ForgeFixtureExpectation = {
+ code?: number;
+ stdoutIncludes?: string;
+ stderrExcludes?: string;
+};
+
+export type ForgeFixture = {
+ name: string;
+ input: Record<string, unknown>;
+ expect?: ForgeFixtureExpectation;
+};
+
+export type ForgeRecipeSnapshot = {
+ id: string;
+ scope: Scope;
+ intent: string;
+ summary: string;
+ attempts: number;
+ successes: number;
+ failures: number;
+ qualityVersion?: 1;
+ quality: WorkflowQuality;
+ bestSteps: Pick<WorkflowStep, "tool" | "state" | "target">[];
+ updatedAt: string;
+};
+
+export type ForgeSkillSpec = {
+ name: string;
+ content: string;
+};
+
+export type ForgeFunctionSpec = {
+ name: string;
+ description: string;
+ inputSchema: {
+ type: "object";
+ properties: Record<string, unknown>;
+ required?: string[];
+ additionalProperties?: boolean;
+ };
+ command: string[];
+ timeoutMs: number;
+ fixtures: ForgeFixture[];
+};
+
+export type ForgeEvaluation = {
+ version: 1;
+ candidateHash: string;
+ passed: boolean;
+ evaluatedAt: string;
+ checks: ForgeCheck[];
+ targetHash?: string;
+ toolsetHash?: string;
+ fixtureCount: number;
+ sandboxImageId?: string;
+ sourceHash?: string;
+};
+
+export type ForgePromotion = {
+ at: string;
+ path: string;
+ verification: string;
+};
+
+export type ForgeCandidate = {
+ version: 1;
+ id: string;
+ ownerHash: string;
+ kind: ForgeKind;
+ state: ForgeState;
+ projectPath: string;
+ recipe: ForgeRecipeSnapshot;
+ requiredScope: Scope;
+ createdAt: string;
+ updatedAt: string;
+ skill?: ForgeSkillSpec;
+ function?: ForgeFunctionSpec;
+ evaluation?: ForgeEvaluation;
+ promotion?: ForgePromotion;
+};
+
+export type PublicForgeCandidate = Omit<ForgeCandidate, "ownerHash" | "function"> & {
+ function?: Omit<ForgeFunctionSpec, "command" | "fixtures"> & {
+ command?: { executable: string; argvCount: number };
+ fixtureCount: number;
+ };
+};
diff --git a/lib/host/audit.ts b/lib/host/audit.ts
index eb121ddf..fb85307d 100644
--- a/lib/host/audit.ts
+++ b/lib/host/audit.ts
@@ -35,6 +35,9 @@ export type AuditAction =
| "workflow.finish"
| "agent.session"
| "agent.memory"
+ | "tool.forge.propose"
+ | "tool.forge.evaluate"
+ | "tool.forge.promote"
| "a2a.registry"
| "a2a.send"
| "a2a.cancel"
diff --git a/lib/mcp/parity.test.ts b/lib/mcp/parity.test.ts
index e64e6f9a..4e770424 100644
--- a/lib/mcp/parity.test.ts
+++ b/lib/mcp/parity.test.ts
@@ -69,6 +69,10 @@ const MCP_ONLY: Record<string, string> = {
"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",
+ "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",
};
describe("Alfa ↔ MCP capability parity", () => {
@@ -153,6 +157,9 @@ describe("MCP rate limits mirror the routes", () => {
"a2a.send": 30,
"a2a.task": 60,
"a2a.cancel": 30,
+ "tool.forge.propose": 20,
+ "tool.forge.evaluate": 10,
+ "tool.forge.promote": 6,
};
for (const t of TOOLS) {
if (!t.limit) continue;
diff --git a/lib/mcp/tools-forge.test.ts b/lib/mcp/tools-forge.test.ts
new file mode 100644
index 00000000..ad8ec68f
--- /dev/null
+++ b/lib/mcp/tools-forge.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+ resolveProjectHint: vi.fn(async () => ({ path: "/tmp/project", id: "root/project", hint: "project", matchedBy: "name" })),
+ listLearnedRecipes: vi.fn(async () => [{ id: "recipe-1", scope: "read", intent: "x", summary: "x", attempts: 2, successes: 2, failures: 0, qualityVersion: 1, quality: {}, bestSteps: [], updatedAt: "2026-09-02T00:00:00Z" }]),
+ proposeForgeCandidate: vi.fn(async (input) => ({ version: 1, id: "forge_20260902_000000_aaaaaaaaaaaa", ownerHash: "h", kind: input.kind, state: "draft", projectPath: input.projectPath, recipe: { id: input.recipe.id }, requiredScope: "read", createdAt: "x", updatedAt: "x", skill: { name: "x", content: "x" } })),
+ getForgeCandidate: vi.fn(async () => ({ version: 1, id: "forge_20260902_000000_aaaaaaaaaaaa", ownerHash: "h", kind: "skill", state: "draft", projectPath: "/tmp/project", recipe: { id: "recipe-1", bestSteps: [], quality: {}, attempts: 2, successes: 2, failures: 0, scope: "read", intent: "x", summary: "x", updatedAt: "x" }, requiredScope: "read", createdAt: "x", updatedAt: "x", skill: { name: "x", content: "x" } })),
+ listForgeCandidates: vi.fn(async () => []),
+ publicForgeCandidate: vi.fn((candidate) => ({ id: candidate.id, state: candidate.state, kind: candidate.kind })),
+ updateForgeCandidate: vi.fn(async (_id, _owner, mutate) => mutate(await mocks.getForgeCandidate())),
+ evaluateForgeCandidate: vi.fn(async () => ({ version: 1, candidateHash: "hash", passed: true, evaluatedAt: "x", checks: [], targetHash: "absent", fixtureCount: 0 })),
+ promoteForgeCandidate: vi.fn(async () => ({ at: "x", path: "/tmp/project/.mso/skills/x/SKILL.md", verification: "local" })),
+}));
+
+vi.mock("@/lib/host", () => ({ resolveProjectHint: mocks.resolveProjectHint }));
+vi.mock("@/lib/skills/memory", () => ({ listLearnedRecipes: mocks.listLearnedRecipes }));
+vi.mock("@/lib/forge/proposal", () => ({ proposeForgeCandidate: mocks.proposeForgeCandidate }));
+vi.mock("@/lib/forge/evaluate", () => ({ evaluateForgeCandidate: mocks.evaluateForgeCandidate }));
+vi.mock("@/lib/forge/promote", () => ({ promoteForgeCandidate: mocks.promoteForgeCandidate }));
+vi.mock("@/lib/forge/store", () => ({
+ getForgeCandidate: mocks.getForgeCandidate, listForgeCandidates: mocks.listForgeCandidates,
+ publicForgeCandidate: mocks.publicForgeCandidate, updateForgeCandidate: mocks.updateForgeCandidate,
+}));
+
+const { FORGE_TOOLS } = await import("./tools-forge");
+const tool = (name: string) => {
+ const found = FORGE_TOOLS.find((row) => row.name === name);
+ if (!found) throw new Error(`missing ${name}`);
+ return found;
+};
+const context = { actor: "mcp:token", recipeActor: "mcp-client:stable", scope: "exec" as const };
+
+describe("MCP Tool Forge wrappers", () => {
+ it("proposes only from the stable recipe owner and resolved project", async () => {
+ const result = await tool("tool_forge_propose").run({ recipe_id: "recipe-1", kind: "skill", project: "project", name: "health" }, context) as { id: string };
+ expect(result.id).toMatch(/^forge_/);
+ expect(mocks.listLearnedRecipes).toHaveBeenCalledWith({ actor: "mcp-client:stable", scope: "exec" });
+ expect(mocks.proposeForgeCandidate).toHaveBeenCalledWith(expect.objectContaining({ owner: "mcp-client:stable", projectPath: "/tmp/project", kind: "skill" }));
+ });
+
+ it("requires the exact explicit promotion phrase before any evaluation/promotion", async () => {
+ await expect(tool("tool_forge_promote").run({ candidate_id: "forge_20260902_000000_aaaaaaaaaaaa", confirmation: "yes" }, context))
+ .rejects.toThrow(/PROMOTE forge_20260902_000000_aaaaaaaaaaaa/);
+ expect(mocks.evaluateForgeCandidate).not.toHaveBeenCalled();
+ expect(mocks.promoteForgeCandidate).not.toHaveBeenCalled();
+ });
+});
diff --git a/lib/mcp/tools-forge.ts b/lib/mcp/tools-forge.ts
new file mode 100644
index 00000000..c69e8c7c
--- /dev/null
+++ b/lib/mcp/tools-forge.ts
@@ -0,0 +1,138 @@
+import { resolveProjectHint } from "@/lib/host";
+import { evaluateForgeCandidate } from "@/lib/forge/evaluate";
+import { promoteForgeCandidate } from "@/lib/forge/promote";
+import { proposeForgeCandidate } from "@/lib/forge/proposal";
+import { getForgeCandidate, listForgeCandidates, publicForgeCandidate, updateForgeCandidate } from "@/lib/forge/store";
+import { listLearnedRecipes } from "@/lib/skills/memory";
+import { type McpTool, S, str, opt } from "./tool-kit";
+import { toolsetInfo } from "./toolset";
+
+function forgeOwner(context: { recipeActor?: string; actor?: string }): string {
+ const owner = context.recipeActor ?? context.actor;
+ if (!owner) throw new Error("Tool Forge needs an authenticated client owner");
+ return owner;
+}
+
+function kind(a: Record<string, unknown>): "skill" | "project_function" {
+ const value = str(a, "kind");
+ if (value !== "skill" && value !== "project_function") throw new Error("kind must be skill or project_function");
+ return value;
+}
+
+async function currentToolEvidence() {
+ const { TOOLS } = await import("./tools");
+ return {
+ scopes: new Map(TOOLS.map((tool) => [tool.name, tool.scope])),
+ toolset: toolsetInfo(TOOLS),
+ };
+}
+
+async function freshEvaluation(candidate: Awaited<ReturnType<typeof getForgeCandidate>>) {
+ if (!candidate) throw new Error("forge candidate not found");
+ const evidence = await currentToolEvidence();
+ return evaluateForgeCandidate({ candidate, knownTools: evidence.scopes, toolsetHash: evidence.toolset.hash });
+}
+
+export const FORGE_TOOLS: McpTool[] = [
+ {
+ name: "tool_forge_candidates",
+ description:
+ "List this MCP client's private Tool Forge candidates, or inspect one exact candidate id. Commands and fixture payloads stay redacted. " +
+ "A candidate is inert until explicit evaluation and promotion.",
+ scope: "read",
+ annotations: { readOnlyHint: true, idempotentHint: true },
+ inputSchema: S({ candidate_id: { type: "string", description: "Optional exact forge candidate id." } }),
+ run: async (a, context) => {
+ const owner = forgeOwner(context), id = opt(a, "candidate_id");
+ if (id) {
+ const candidate = await getForgeCandidate(id, owner);
+ if (!candidate) throw new Error("forge candidate not found");
+ return publicForgeCandidate(candidate);
+ }
+ return { candidates: (await listForgeCandidates(owner)).map(publicForgeCandidate) };
+ },
+ },
+ {
+ name: "tool_forge_propose",
+ description:
+ "Create an INERT Tool Forge candidate from one repeated verified learned workflow. Requires P1 quality telemetry, at least two successful runs, >=90% success, and a fully-completed best trace. " +
+ "Skill candidates contain only redacted tool guidance. Project-function candidates must point to an existing project-owned Node script; Tool Forge never generates executable code.",
+ scope: "write",
+ annotations: { idempotentHint: false },
+ limit: { key: "tool.forge.propose", max: 20, windowMs: 60_000 },
+ audit: { action: "tool.forge.propose" as const, targetArg: "project" },
+ inputSchema: S({
+ recipe_id: { type: "string", description: "Exact learned recipe id from workflow learning/search output." },
+ kind: { type: "string", enum: ["skill", "project_function"] },
+ project: { type: "string", description: "Exact project id/path/name resolvable by projects_list." },
+ name: { type: "string", description: "Optional candidate name; lowercase safe identifier." },
+ description: { type: "string", description: "Project-function description." },
+ command: { type: "array", items: { type: "string" }, description: "Project-function fixed argv. P2 accepts Node + a project-owned script only." },
+ input_schema: { type: "object", description: "Project-function JSON input schema." },
+ fixtures: { type: "array", description: "1-8 sandbox fixtures for project-function candidates." },
+ timeout_ms: { type: "number", description: "Project-function timeout, 1000-30000ms." },
+ }, ["recipe_id", "kind", "project"]),
+ run: async (a, context) => {
+ const owner = forgeOwner(context), project = await resolveProjectHint(str(a, "project"));
+ if (!project) throw new Error(`project not found: ${String(a.project)}`);
+ const recipes = await listLearnedRecipes({ actor: owner, scope: context.scope });
+ const recipe = recipes.find((row) => row.id === str(a, "recipe_id"));
+ if (!recipe) throw new Error("learned recipe not found for this client/scope");
+ const candidate = await proposeForgeCandidate({
+ owner, recipe, kind: kind(a), projectPath: project.path, name: opt(a, "name"), description: opt(a, "description"),
+ command: a.command, inputSchema: a.input_schema, fixtures: a.fixtures,
+ timeoutMs: a.timeout_ms === undefined ? undefined : Number(a.timeout_ms),
+ });
+ return publicForgeCandidate(candidate);
+ },
+ },
+ {
+ name: "tool_forge_evaluate",
+ description:
+ "Evaluate one inert Tool Forge candidate against the CURRENT tool catalog and target state. Project-function fixtures execute only in the configured cached Docker sandbox: network none, read-only root/project, no capabilities, no-new-privileges, bounded CPU/memory/PIDs. " +
+ "Evaluation never promotes or executes the candidate on the host.",
+ scope: "exec",
+ annotations: { destructiveHint: false, openWorldHint: false },
+ limit: { key: "tool.forge.evaluate", max: 10, windowMs: 60_000 },
+ audit: { action: "tool.forge.evaluate" as const, targetArg: "candidate_id" },
+ inputSchema: S({ candidate_id: { type: "string", description: "Exact forge candidate id." } }, ["candidate_id"]),
+ run: async (a, context) => {
+ const owner = forgeOwner(context), id = str(a, "candidate_id"), current = await getForgeCandidate(id, owner);
+ const evaluation = await freshEvaluation(current);
+ const updated = await updateForgeCandidate(id, owner, (candidate) => ({
+ ...candidate, state: evaluation.passed ? "evaluated" : "draft", evaluation, updatedAt: new Date().toISOString(),
+ }));
+ return publicForgeCandidate(updated);
+ },
+ },
+ {
+ name: "tool_forge_promote",
+ description:
+ "Explicitly promote one Tool Forge candidate into its project. Requires confirmation exactly `PROMOTE <candidate_id>`. MSO re-runs the complete evaluation immediately before promotion, refuses target/tool/image drift, never overwrites existing Skills/functions, and verifies the promoted artifact afterward. " +
+ "Use only after reviewing tool_forge_candidates/evaluation evidence.",
+ scope: "exec",
+ annotations: { destructiveHint: true, openWorldHint: false },
+ limit: { key: "tool.forge.promote", max: 6, windowMs: 60_000 },
+ audit: { action: "tool.forge.promote" as const, targetArg: "candidate_id" },
+ inputSchema: S({
+ candidate_id: { type: "string", description: "Exact forge candidate id." },
+ confirmation: { type: "string", description: "Must exactly equal PROMOTE <candidate_id>." },
+ }, ["candidate_id", "confirmation"]),
+ run: async (a, context) => {
+ const owner = forgeOwner(context), id = str(a, "candidate_id");
+ if (str(a, "confirmation") !== `PROMOTE ${id}`) throw new Error(`promotion confirmation must exactly equal PROMOTE ${id}`);
+ const current = await getForgeCandidate(id, owner);
+ if (!current) throw new Error("forge candidate not found");
+ if (current.state === "promoted") throw new Error("forge candidate is already promoted");
+ const evaluation = await freshEvaluation(current);
+ if (!evaluation.passed) {
+ await updateForgeCandidate(id, owner, (candidate) => ({ ...candidate, state: "draft", evaluation, updatedAt: new Date().toISOString() }));
+ throw new Error("fresh Tool Forge evaluation failed; inspect the candidate before retrying promotion");
+ }
+ const evaluated = { ...current, state: "evaluated" as const, evaluation, updatedAt: new Date().toISOString() };
+ const promotion = await promoteForgeCandidate(evaluated);
+ const promoted = await updateForgeCandidate(id, owner, () => ({ ...evaluated, state: "promoted", promotion, updatedAt: promotion.at }));
+ return publicForgeCandidate(promoted);
+ },
+ },
+];
diff --git a/lib/mcp/tools.ts b/lib/mcp/tools.ts
index caea6169..3f1f3752 100644
--- a/lib/mcp/tools.ts
+++ b/lib/mcp/tools.ts
@@ -8,6 +8,7 @@ import { POWER_TOOLS } from "./tools-power";
import { INFRA_TOOLS } from "./tools-infra";
import { AGENT_TOOLS } from "./tools-agent";
import { A2A_TOOLS } from "./tools-a2a";
+import { FORGE_TOOLS } from "./tools-forge";
import { withWorkflowContext } from "./tool-context";
// The write and exec tiers. Each carries an `audit` descriptor — the dispatcher,
@@ -217,4 +218,4 @@ const MUTATE_TOOLS: McpTool[] = [
},
];
-export const TOOLS: McpTool[] = [...READ_TOOLS, ...DISCOVERY_TOOLS, ...LEARNING_TOOLS, ...AGENT_TOOLS, ...A2A_TOOLS, ...INFRA_TOOLS, ...MUTATE_TOOLS, ...POWER_TOOLS].map(withWorkflowContext); export const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
+export const TOOLS: McpTool[] = [...READ_TOOLS, ...DISCOVERY_TOOLS, ...LEARNING_TOOLS, ...AGENT_TOOLS, ...A2A_TOOLS, ...FORGE_TOOLS, ...INFRA_TOOLS, ...MUTATE_TOOLS, ...POWER_TOOLS].map(withWorkflowContext); export const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
diff --git a/lib/mcp/toolset.ts b/lib/mcp/toolset.ts
index 891ac327..67d7c26b 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.09.02.3";
-export const MCP_TOOLSET_CHANGED_AT = "2026-09-02T05:24:00Z";
+export const MCP_TOOLSET_VERSION = "2026.09.02.4";
+export const MCP_TOOLSET_CHANGED_AT = "2026-09-02T05:58:15Z";
export type McpToolsetInfo = {
serverVersion: string;
diff --git a/package.json b/package.json
index a8750f20..f55a58ed 100644
--- a/package.json
+++ b/package.json
@@ -29,7 +29,8 @@
"bench:cognitive": "bun scripts/bench-cognitive-runtime.mjs",
"bench:memory": "bun scripts/bench-memory-retrieval.mjs",
"bench:quality": "bun scripts/bench-task-quality.mjs",
- "bench:agents": "bun scripts/bench-agent-comparison.mjs"
+ "bench:agents": "bun scripts/bench-agent-comparison.mjs",
+ "forge:sandbox": "bash scripts/provision-forge-sandbox.sh"
},
"dependencies": {
"@anthropic-ai/sdk": "^0.120.0",
diff --git a/scripts/bench-cognitive-runtime.mjs b/scripts/bench-cognitive-runtime.mjs
index 2c2cf925..c98278ca 100755
--- a/scripts/bench-cognitive-runtime.mjs
+++ b/scripts/bench-cognitive-runtime.mjs
@@ -23,6 +23,7 @@ const scenarios = [
{ id: "memory-retrieval", prompt: "Search my persistent memory for a prior deployment rule and inspect conflicting or temporal claims.", required: ["agent_memory_search"] },
{ id: "resume", prompt: "List previous agent sessions and resume the deployment session.", required: ["agent_sessions_list", "agent_session_resume"] },
{ id: "skills", prompt: "Find the best trusted skill for a repository security review and read its instructions.", required: ["skills_search", "skills_read"] },
+ { id: "tool-forge", prompt: "Turn this repeated verified workflow into a Tool Forge candidate, evaluate it in the sandbox, review the candidate, then explicitly promote it.", required: ["tool_forge_candidates", "tool_forge_propose", "tool_forge_evaluate", "tool_forge_promote"] },
];
const toolShape = (tool) => ({ name: tool.name, description: tool.description, input_schema: tool.inputSchema });
diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs
index 18619188..2bafa8ba 100755
--- a/scripts/check-docs.mjs
+++ b/scripts/check-docs.mjs
@@ -23,6 +23,7 @@ const toolFiles = [
"lib/mcp/tools-power.ts",
"lib/mcp/tools-agent.ts",
"lib/mcp/tools-a2a.ts",
+ "lib/mcp/tools-forge.ts",
];
const tools = new Map();
for (const file of toolFiles) {
diff --git a/scripts/mso-agent-tool-router.mjs b/scripts/mso-agent-tool-router.mjs
index cc62b1b4..a08ad2bc 100644
--- a/scripts/mso-agent-tool-router.mjs
+++ b/scripts/mso-agent-tool-router.mjs
@@ -13,6 +13,8 @@ const DEPENDENCIES = new Map([
["agent_session_resume", ["agent_sessions_list"]],
["a2a_message_send", ["a2a_agents_list", "a2a_agent_discover"]],
["a2a_handoff", ["a2a_agents_list", "a2a_agent_discover", "a2a_task_get"]],
+ ["tool_forge_evaluate", ["tool_forge_candidates"]],
+ ["tool_forge_promote", ["tool_forge_candidates", "tool_forge_evaluate"]],
]);
const ALIASES = new Map([
@@ -32,6 +34,7 @@ const ALIASES = new Map([
["hostinger", ["hostinger", "dns", "domain", "record"]],
["apps", ["app", "service", "hermes", "openclaw", "install", "restart", "status"]],
["a2a", ["a2a", "delegate", "delegation", "handoff", "peer", "collaborate"]],
+ ["forge", ["forge", "candidate", "promotion", "promote", "self-improve", "self-improving", "generate tool", "tool creator"]],
]);
function words(value) {
diff --git a/scripts/mso-agent-tool-router.test.ts b/scripts/mso-agent-tool-router.test.ts
index 439d535b..a8e35b99 100644
--- a/scripts/mso-agent-tool-router.test.ts
+++ b/scripts/mso-agent-tool-router.test.ts
@@ -16,6 +16,8 @@ const catalog = [
tool("cloudflare_zones_list", "List Cloudflare DNS zones"), tool("hostinger_dns_upsert", "Update Hostinger DNS record"),
tool("a2a_agents_list", "List registered A2A peer agents"), tool("a2a_agent_discover", "Discover public A2A Agent Card"),
tool("a2a_message_send", "Send a message to an A2A peer"), tool("a2a_handoff", "Delegate explicit objective to A2A peer"), tool("a2a_task_get", "Read A2A task status"),
+ tool("tool_forge_candidates", "List Tool Forge candidates"), tool("tool_forge_propose", "Propose a Tool Forge candidate from a repeated recipe"),
+ tool("tool_forge_evaluate", "Evaluate a Tool Forge candidate in the sandbox"), tool("tool_forge_promote", "Promote an evaluated Tool Forge candidate"),
];
describe("MSO per-turn tool router", () => {
@@ -46,6 +48,18 @@ describe("MSO per-turn tool router", () => {
expect(out.selectedNames).toContain("a2a_task_get");
});
+ it("does not load Forge schemas for an unrelated app-log task", () => {
+ const out = selectToolsForTurn(catalog, [{ role: "user", text: "why is hermes down? inspect its logs" }]);
+ expect(out.selectedNames.some((name) => name.startsWith("tool_forge_"))).toBe(false);
+ });
+
+ it("loads Forge evaluation/promotion companions only for a Forge turn", () => {
+ const out = selectToolsForTurn(catalog, [{ role: "user", text: "evaluate and promote this tool forge candidate" }]);
+ expect(out.selectedNames).toContain("tool_forge_candidates");
+ expect(out.selectedNames).toContain("tool_forge_evaluate");
+ expect(out.selectedNames).toContain("tool_forge_promote");
+ });
+
it("keeps long-job companions when build work selects exec_job_start", () => {
const out = selectToolsForTurn(catalog, [{ role: "user", text: "run the full build and test pipeline" }]);
expect(out.selectedNames).toContain("exec_job_start");
diff --git a/scripts/mso-gateway-lifecycle.test.ts b/scripts/mso-gateway-lifecycle.test.ts
index 8241226b..33d25f3a 100644
--- a/scripts/mso-gateway-lifecycle.test.ts
+++ b/scripts/mso-gateway-lifecycle.test.ts
@@ -72,6 +72,15 @@ function asyncStart(env: NodeJS.ProcessEnv) {
});
}
+async function waitUntil(predicate: () => boolean, timeoutMs = 8_000, intervalMs = 25): Promise<boolean> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (predicate()) return true;
+ await new Promise((resolve) => setTimeout(resolve, intervalMs));
+ }
+ return predicate();
+}
+
afterEach(() => {
for (const pid of pids) if (alive(pid)) try { process.kill(pid, "SIGTERM"); } catch {}
pids.clear(); for (const dir of roots.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
@@ -139,13 +148,18 @@ esac
`, { mode: 0o700 });
const env = { ...f.env, MSO_GATEWAY_CURL: curl, MSO_GATEWAY_SKIP_PUBLIC_PROBE: "0", MSO_GATEWAY_PUBLIC_READY_SECONDS: "10" };
const child = spawn(GATEWAY, ["start"], { env, stdio: ["ignore", "pipe", "pipe"] });
- for (let i = 0; i < 100 && !fs.existsSync(f.startFile); i++) await new Promise((r) => setTimeout(r, 20));
- expect(fs.existsSync(f.startFile)).toBe(true);
+ let stdout = "", stderr = "";
+ child.stdout.on("data", (value) => stdout += value);
+ child.stderr.on("data", (value) => stderr += value);
+ const closed = new Promise<number | null>((resolve) => child.once("close", resolve));
+ const spawned = await waitUntil(() => fs.existsSync(f.startFile) || child.exitCode !== null);
+ expect(spawned && fs.existsSync(f.startFile), `gateway did not spawn fixture tunnel before exit=${child.exitCode}; stdout=${stdout.slice(-400)}; stderr=${stderr.slice(-800)}`).toBe(true);
const tunnelPid = Number(fs.readFileSync(f.startFile, "utf8").trim().split(/\n+/).at(-1));
pids.add(tunnelPid);
+ expect(alive(tunnelPid)).toBe(true);
child.kill("SIGTERM");
- await new Promise<void>((resolve) => child.once("close", () => resolve()));
- for (let i = 0; i < 50 && alive(tunnelPid); i++) await new Promise((r) => setTimeout(r, 20));
+ await Promise.race([closed, new Promise((_, reject) => setTimeout(() => reject(new Error(`gateway launcher did not close after SIGTERM; stdout=${stdout.slice(-400)}; stderr=${stderr.slice(-800)}`)), 5_000))]);
+ await waitUntil(() => !alive(tunnelPid), 5_000);
expect(alive(tunnelPid)).toBe(false);
expect(fs.existsSync(path.join(f.state, "state.json"))).toBe(false);
});
diff --git a/scripts/provision-forge-sandbox.sh b/scripts/provision-forge-sandbox.sh
new file mode 100755
index 00000000..743c0377
--- /dev/null
+++ b/scripts/provision-forge-sandbox.sh
@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Build the Tool Forge Node fixture sandbox from THIS host's already-trusted Node runtime.
+# No registry access, package install, curl, or Dockerfile base image is involved.
+set -euo pipefail
+umask 077
+IMAGE="${OS_TOOL_FORGE_NODE_IMAGE:-mso-forge-sandbox:node22-v1}"
+NODE_BIN="$(command -v node || true)"
+[ -n "$NODE_BIN" ] && [ -x "$NODE_BIN" ] || { echo "Tool Forge: node is required" >&2; exit 1; }
+command -v docker >/dev/null || { echo "Tool Forge: docker is required for executable fixture isolation" >&2; exit 1; }
+docker info >/dev/null 2>&1 || { echo "Tool Forge: docker daemon is unavailable to this user" >&2; exit 1; }
+NODE_BIN="$(readlink -f "$NODE_BIN")"
+ROOT="$(mktemp -d "${TMPDIR:-/tmp}/mso-forge-rootfs.XXXXXX")"
+cleanup() {
+ find "$ROOT" -type f -delete 2>/dev/null || true
+ find "$ROOT" -depth -type d -empty -delete 2>/dev/null || true
+}
+trap cleanup EXIT HUP INT TERM
+install -Dm755 "$NODE_BIN" "$ROOT/usr/bin/node"
+# ldd output has two useful forms: `name => /abs/path (...)` and `/abs/loader (...)`.
+mapfile -t LIBS < <(ldd "$NODE_BIN" | awk '/=> \/[^ ]+/ {print $3} /^\s*\/[^ ]+/ {print $1}' | sort -u)
+[ "${#LIBS[@]}" -gt 0 ] || { echo "Tool Forge: could not resolve Node shared libraries" >&2; exit 1; }
+for lib in "${LIBS[@]}"; do
+ [ -f "$lib" ] || { echo "Tool Forge: missing shared library $lib" >&2; exit 1; }
+ install -Dm755 "$lib" "$ROOT$lib"
+done
+mkdir -p "$ROOT/tmp" "$ROOT/workspace"
+chmod 1777 "$ROOT/tmp"
+NODE_VERSION="$(node --version)"
+tar -C "$ROOT" -cf - . | docker import \
+ --change 'ENTRYPOINT ["/usr/bin/node"]' \
+ --change 'ENV PATH=/usr/bin' \
+ --change 'LABEL org.mso.tool-forge.version="1"' \
+ --change 'LABEL org.mso.tool-forge.runtime="node"' \
+ --change "LABEL org.mso.tool-forge.node-version=\"$NODE_VERSION\"" \
+ - "$IMAGE" >/dev/null
+ID="$(docker image inspect --format '{{.Id}}' "$IMAGE")"
+VERSION="$(docker run --rm --network none --read-only --cap-drop ALL --security-opt no-new-privileges --entrypoint /usr/bin/node "$IMAGE" --version)"
+[ "$VERSION" = "$NODE_VERSION" ] || { echo "Tool Forge: sandbox Node verification failed" >&2; exit 1; }
+printf 'Tool Forge sandbox ready: %s\nnode=%s\nimageId=%s\n' "$IMAGE" "$VERSION" "$ID"
+trap - EXIT HUP INT TERM
+cleanup