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): ship cognitive runtime p1

Rahman919a3317a096
diff --git a/bin/mso b/bin/mso
index 669e7fd2..023d479d 100755
--- a/bin/mso
+++ b/bin/mso
@@ -42,7 +42,7 @@
# status Public service status (no session needed)
# health Is this CLI's session valid?
# doctor [--fix] Check deps, HTTPS/login origin, service, session, device; --fix repairs safe local issues
-# agent [--continue|--resume <query>|--yolo|-yolo] Interactive MSO Agent; resume durable sessions
+# agent [--continue|--resume <query>|--yolo|-yolo] Interactive MSO Agent; --oneshot <prompt> for autonomous non-TTY runs
# chat Alias for agent
# model [ref] Select active model from a connected provider
# onboard [-y] Guided setup: AI, apps, infrastructure, skills
@@ -464,7 +464,7 @@ ensure_local_cli_device() {
esac
if ! dev_script --is-approved "$d" >/dev/null 2>&1; then
dev_script "$d" "mso cli" >/dev/null
- echo " ✓ approved this local CLI device"
+ [ "${MSO_CLI_QUIET:-0}" = "1" ] || echo " ✓ approved this local CLI device"
fi
}
@@ -474,7 +474,7 @@ ensure_onboard_runtime() {
MSO_GATEWAY_ROOT="$ROOT" MSO_GATEWAY_ENV="$ENVF" MSO_GATEWAY_LOCAL_URL="$B" \
"$ROOT/scripts/mso-gateway" local-start >/dev/null \
|| die "local MSO runtime is not ready. Run: mso update ; then: mso web"
- echo " ✓ verified local MSO runtime at $B" ;;
+ [ "${MSO_CLI_QUIET:-0}" = "1" ] || echo " ✓ verified local MSO runtime at $B" ;;
*) return 0 ;;
esac
}
@@ -674,7 +674,7 @@ U_gateway="gateway start [--config <cloudflared.yml> --tunnel <name|uuid>]|stop|
U_doctor="doctor [--fix]"
U_provider="provider list|show <id>|set <dokploy|cloudflare|hostinger>|rm <id>|doctor [id]|projects|zones"
U_model="model [current|list [provider]|set <provider> <model>|set <provider/model>|<model-or-ref>]"
-U_agent="agent [--continue|-c|--resume|-r <latest|index|id|title>|--yolo|-yolo]"
+U_agent="agent [--continue|-c|--resume|-r <latest|index|id|title>|--yolo|-yolo] | agent --oneshot <prompt> [--json] [--approve-scope read|write|exec]"
U_mapp="mapp list|show|logs|backups|jobs|job <id> <jobId>|pending <id>|install|update|power <id> <act>|cancel <id> <jobId>"
U_term="term open [cwd] [cols] [rows]|input <id> <text>|resize <id> <cols> <rows>|stream <id>|close <id>"
U_device="device list|pending|approve <id> [label] [--role viewer|operator|owner]|role <id> <role>|revoke <id>|revoke all --yes"
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 4bd18248..56cc6e04 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` ship cognitive runtime p1
- `agent` humanize sessions and add yolo mode
- `mcp` ship cognitive runtime p0
- `agent` add interrupt-safe terminal controls
diff --git a/docs/CHATGPT-PLUGIN.md b/docs/CHATGPT-PLUGIN.md
index 7084e806..c2011098 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.1 tools=46 read=24 write=17 exec=5 -->
+<!-- mcp-toolset: server=1.6.0 version=2026.09.02.2 tools=47 read=25 write=17 exec=5 -->
-MSO currently exposes MCP server **1.6.0**, toolset **2026.09.02.1**: **47 transport tools** total; **46 model/operator tools**
-(24 read, 17 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.2**: **48 transport tools** total; **47 model/operator tools**
+(25 read, 17 write, 5 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,9 +141,10 @@ 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` — 24 model/operator tools
+### `read` — 25 model/operator tools
- `agent_memory_read`
+- `agent_memory_search`
- `agent_session_current`
- `agent_session_resume`
- `agent_sessions_list`
@@ -221,7 +222,7 @@ Settings → MCP:
```text
server: 1.6.0
-toolset: 2026.09.02.1
+toolset: 2026.09.02.2
hash: <live schema hash>
count: 46 model/operator tools (+ 1 app-only bridge)
```
diff --git a/docs/CLI.md b/docs/CLI.md
index aa7bad47..42285949 100644
--- a/docs/CLI.md
+++ b/docs/CLI.md
@@ -82,7 +82,7 @@ Commands:
status Public service status (no session needed)
health Is this CLI's session valid?
doctor [--fix] Check deps, HTTPS/login origin, service, session, device; --fix repairs safe local issues
- agent [--continue|--resume <query>|--yolo|-yolo] Interactive MSO Agent; resume durable sessions
+ agent [--continue|--resume <query>|--yolo|-yolo] Interactive MSO Agent; --oneshot <prompt> for autonomous non-TTY runs
chat Alias for agent
model [ref] Select active model from a connected provider
onboard [-y] Guided setup: AI, apps, infrastructure, skills
diff --git a/docs/COGNITIVE-RUNTIME.md b/docs/COGNITIVE-RUNTIME.md
index cbfddfe8..fb93e2b4 100644
--- a/docs/COGNITIVE-RUNTIME.md
+++ b/docs/COGNITIVE-RUNTIME.md
@@ -4,7 +4,7 @@ MSO treats the LLM as a replaceable reasoning engine. The durable product advant
**provider-neutral harness** around it: conversation identity, context budgeting, memory, tool discovery,
permissions, verification, learned workflows, and reproducible evaluation.
-This document is the current contract for the MCP-first P0 runtime. Provider-specific features may be
+This document is the current contract for the MCP-first Cognitive Runtime through P1. Provider-specific features may be
used when available, but correctness must not depend on OpenAI-, Anthropic-, Google-, Qwen-, GLM-,
DeepSeek-, or other vendor-specific hidden state.
@@ -93,34 +93,38 @@ Oversized results return a parseable `msoTruncated` envelope containing original
preview, and a narrowing hint. Explicit MCP Apps structured projections remain separate. The correct
recovery is a narrower read/search/grep/tail, not silently increasing the context flood.
-## Memory planes in P0
+## Memory planes in P1
-P0 intentionally keeps two proven memory layers rather than inventing one universal store:
+P1 keeps the two proven planes but upgrades stable agent memory from untyped Markdown into a structured, backward-compatible ledger:
-- **Agent memory** (`USER.md` / `MEMORY.md`) — stable client-principal facts, frozen into each new session.
-- **Experience memory** — successful/failed workflow trajectories, redacted replayable step shape,
- semantic embedding, success rate, fastest/average duration, and last-use evidence.
+- **Agent memory ledger** — private `records-v1.json` claims keyed by client principal, with semantic/episodic/procedural kind, confidence, sensitivity, temporal validity, provenance authority/channel, supersession/retraction and conflict evidence.
+- **Markdown compatibility projection** — `USER.md` / `MEMORY.md` remain the resolved materialized view consumed by older CLI/session code. Existing installations are read unchanged; the first structured mutation seeds the ledger from legacy `## key` sections instead of deleting or rewriting history.
+- **Experience memory** — verified workflow trajectories remain client-scoped and now accumulate P1 quality telemetry: completed/failed/denied/rate-limited/invalid-argument steps, retries, rollback/restore evidence and timed-step latency.
-The next memory revision may introduce typed semantic/episodic/procedural records with provenance,
-confidence, temporal validity, supersession, and conflict resolution. That is P1/P2 work and must beat the
-P0 retrieval/evaluation baseline before becoming the default.
+Resolution is deterministic at a requested timestamp: only effective claims participate, then authority (`explicit > observed > inferred > migration`), confidence, observation recency, creation recency and stable id break ties. `mode=replace` supersedes the currently resolved claim from its `valid_from`; `mode=claim` keeps parallel evidence so disagreement remains inspectable. A future replacement therefore does **not** erase the fact that is still valid today.
+
+`agent_memory_search` is the model-facing typed retrieval surface. Normal reads return resolved claims plus conflict evidence; `include_history=true` is explicit because superseded/retracted material should not silently bloat context. MCP provenance stores only a short SHA-256 digest of the internal durable session id—not the raw OpenAI conversation id or bearer identity. New sessions still freeze the resolved Markdown snapshot, so memory cannot mutate underneath an active session.
## Benchmark contract
Run:
```bash
-bun run bench:cognitive
-bun scripts/bench-cognitive-runtime.mjs --json
+bun run bench:cognitive # routing/schema + typed-memory gates
+bun run bench:memory # deterministic retrieval/temporal/conflict suite
+bun run bench:quality -- --live # learned workflow success + P1 telemetry coverage
+bun run bench:agents -- --model gpt-5.6-terra # dry-run cross-agent plan
+bun run bench:agents -- --model gpt-5.6-terra --run # scratch-only external smoke
```
-The P0 benchmark is deterministic and provider-neutral. Its checked scenarios cover application logs,
+The core benchmark is deterministic and provider-neutral. Its checked scenarios cover application logs,
server health, safe file editing, long/short execution, project functions, Cloudflare/Hostinger/Dokploy,
browser/screenshots, memory, session resume, and Skills.
Release gates require:
- **100% required-tool recall** on the checked scenarios;
+- **100% typed-memory retrieval, temporal-resolution and conflict-resolution accuracy** on the deterministic fixture suite;
- deterministic selection for identical input;
- lower active schema bytes than the full MSO catalog;
- when Hermes' installed CLI exposes `hermes prompt-size`, lower active tool-schema bytes than that exact
@@ -132,36 +136,38 @@ 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 P0 baseline
+## Current P1 baseline
-On the development host at implementation time:
+On the development host after P1 implementation:
-| Metric | MSO P0 | Hermes local baseline |
+| Metric | MSO P1 | Hermes local baseline |
|---|---:|---:|
-| Full MSO transport catalog | 47 tools | — |
-| Full MSO schema bytes | 31,212 | — |
-| Average MSO active tools / turn | 14.6 | — |
-| Average active schema bytes / turn | 11,074 | 44,758 tool-schema bytes |
-| MSO schema reduction vs full catalog | 64.5% | — |
+| Full MSO transport catalog | 48 tools | — |
+| Full MSO schema bytes | 32,969 | — |
+| Average MSO active tools / turn | 14.5 | — |
+| Average active schema bytes / turn | 11,125 | 44,758 tool-schema bytes |
+| MSO schema reduction vs full catalog | 66.3% | — |
| Required-tool routing recall | 100% | not the same benchmark |
-| Deterministic routing | yes | 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 |
+
+The existing learned-recipe store currently reports **179 successful / 186 total workflows (96.2%)**, but those recipes predate the P1 quality schema, so step-level telemetry coverage correctly starts at **0%** rather than fabricating historical tool-error/retry data. New or re-learned recipes carry `qualityVersion: 1`; coverage grows naturally from real post-P1 executions.
+
+A non-interactive full MSO tool loop is now available as `mso agent --oneshot <prompt> --json`. It defaults to read-only autonomous approval; write/exec require explicit `--approve-scope write|exec`. The cross-agent harness uses a private scratch read task whose nonce and values exist only in a file. A first smoke proved MSO on `openai-codex/gpt-5.6-terra`; Hermes failed because its local configuration does not expose an `openai` provider and OpenClaw rejected that model override for agent `main`, so the harness correctly returned **`comparable=false`**. That is connectivity/configuration evidence, not a ranking.
+
+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.
-These numbers are a reproducible **harness-footprint baseline**, not an overall quality leaderboard. Re-run
-the benchmark after catalog/router changes; do not copy the numbers into marketing claims without a fresh
-measurement and comparable evaluation.
+## P1 status and next direction
-## P1 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 should build on these invariants rather than replace them:
+The next phase should build on those measured primitives rather than add opaque autonomy:
-1. typed memory records with provenance, confidence, sensitivity, temporal validity, and supersession;
-2. retrieval evaluation before adding graph complexity;
-3. Tool/Skill quality telemetry (success, latency, cost, invalid arguments, retries, rollback);
-4. an eval-gated **Tool Forge** that may propose project functions/Skills from repeated verified workflows,
- but cannot promote generated code directly to trusted execution;
-5. optional programmatic read-only orchestration for bulk filtering/aggregation, still constrained by the
- caller's scope and normal host guards;
-6. task-success benchmarks shared with Hermes/OpenClaw where equivalent non-interactive contracts exist.
+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.
## Security notes
diff --git a/docs/CONNECTORS-GATEWAY-INTEGRATION.md b/docs/CONNECTORS-GATEWAY-INTEGRATION.md
index 1197337a..921457c3 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.1 tools=46 read=24 write=17 exec=5 -->
+<!-- mcp-toolset: server=1.6.0 version=2026.09.02.2 tools=47 read=25 write=17 exec=5 -->
-MSO currently exposes MCP server **1.6.0**, toolset **2026.09.02.1**: **47 tools**
-(25 read, 17 write, 5 exec). `GET /mcp` exposes the live names, version/hash and scoped
+MSO currently exposes MCP server **1.6.0**, toolset **2026.09.02.2**: **48 transport tools** total; **47 model/operator tools**
+(25 read, 17 write, 5 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,9 +33,9 @@ Before changing an MCP tool name:
## Current MSO catalog
-### Read (24 model/operator)
+### Read (25 model/operator)
-`agent_memory_read`, `agent_session_current`, `agent_session_resume`, `agent_sessions_list`,
+`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`,
diff --git a/docs/MCP.md b/docs/MCP.md
index 92c593e4..46118f72 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -75,7 +75,7 @@ Picked per token, on the consent screen, capped by `OS_MCP_MAX_SCOPE`. The highe
| Scope | Tools |
|---|---|
-| `read` | `agent_memory_read` `agent_session_current` `agent_session_resume` `agent_sessions_list` `fs_list` `fs_read` `fs_search` `fs_usage` `sys_stats` `sys_processes` `apps_list` `apps_logs` `projects_list` `project_capabilities` `skills_list` `skills_read` `skills_search` `screen_capture` `browser_status` `exec_job_status` `infra_providers_list` `infra_provider_doctor` `dokploy_projects_list` `cloudflare_zones_list` |
+| `read` | `agent_memory_read` `agent_memory_search` `agent_session_current` `agent_session_resume` `agent_sessions_list` `fs_list` `fs_read` `fs_search` `fs_usage` `sys_stats` `sys_processes` `apps_list` `apps_logs` `projects_list` `project_capabilities` `skills_list` `skills_read` `skills_search` `screen_capture` `browser_status` `exec_job_status` `infra_providers_list` `infra_provider_doctor` `dokploy_projects_list` `cloudflare_zones_list` |
| `write` | + `agent_memory_forget` `agent_memory_remember` `agent_session_note` `agent_session_rename` `workflow_start` `workflow_cancel` `workflow_finish` `fs_write` `fs_upload_file` `fs_mkdir` `fs_move` `fs_copy` `fs_delete` `apps_power` `dokploy_project_ensure` `cloudflare_dns_upsert` `hostinger_dns_upsert` |
| `exec` | + `project_function_call` `exec_run` `exec_job_start` `exec_job_cancel` `browser_power` |
@@ -124,11 +124,14 @@ 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.1 tools=46 read=24 write=17 exec=5 -->
+<!-- mcp-toolset: server=1.6.0 version=2026.09.02.2 tools=47 read=25 write=17 exec=5 -->
-Current transport catalog: **47 tools**, server `1.6.0` / toolset `2026.09.02.1`.
-The model/operator catalog is **46 tools** (24 read, 17 write, 5 exec); `workflow_status` is the
-one app-only MCP Apps bridge used by the progress widget and is documented separately. Session/memory tools add durable conversation context without creating
+Current transport catalog: **48 tools**, server `1.6.0` / toolset `2026.09.02.2`.
+The model/operator catalog is **47 tools** (25 read, 17 write, 5 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.
+
+Session/memory tools add durable conversation context without creating
dynamic per-project tool names; `project_capabilities` and `project_function_call` remain the
stable project-automation seam.
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 64ba29f6..8d0b2056 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -2,6 +2,16 @@
Running log of what shipped each phase. Newest at top.
+## 2026-09-02 — Cognitive Runtime P1: typed memory + measurable agent quality — SHIPPED
+
+P1 upgrades durable agent memory without breaking the existing `USER.md` / `MEMORY.md` contract. Each client principal can now persist a private `records-v1.json` ledger of semantic/episodic/procedural claims carrying confidence, sensitivity, validity windows, provenance authority/channel, supersession/retraction and competing-claim evidence. Legacy Markdown remains readable until the first structured mutation, then seeds the ledger and becomes a resolved compatibility projection. Resolution is deterministic by temporal effectiveness → authority → confidence → recency; future facts do not erase still-current facts early. MCP adds read-only `agent_memory_search`; raw ChatGPT conversation ids are never persisted in provenance.
+
+Workflow learning now records P1 quality telemetry rather than only success and duration: completed/failed/denied/rate-limited/invalid-argument steps, retry count, rollback/restore signals and tool latency. Legacy recipes remain valid for aggregate workflow success but carry no `qualityVersion`, so the baseline correctly reports **0% step-telemetry coverage** instead of pretending historical data exists. The current real recipe store is **179/186 successful workflows (96.2%)**; P1 telemetry coverage will grow only from executions observed after this release.
+
+Benchmarking is now layered. `bench:memory` passes **8/8** deterministic retrieval/temporal/conflict fixtures; `bench:cognitive` reports **48 transport tools / 32,969 schema bytes**, **14.5 selected tools / 11,125 bytes average**, **66.3% reduction**, 100% required-tool recall and 100% typed-memory fixture accuracy. `bench:quality` validates telemetry accounting and can summarize the live learned-recipe store. `mso agent --oneshot <prompt> --json` exposes the same autonomous tool loop without a TTY, read-only by default and requiring explicit `--approve-scope` for write/exec. `bench:agents` uses that runner plus Hermes/OpenClaw on a scratch-only read task and refuses comparison when model/provider evidence does not match. The first smoke passed MSO on GPT-5.6 Terra, while the local Hermes/OpenClaw configurations could not run the equivalent override, therefore `comparable=false`; no overall ranking is claimed.
+
+The P1 smoke also caught a semantic tool-contract defect: `sys_stats` exposed uptime as an ambiguous numeric `uptime` field in milliseconds, which GPT-5.6 Terra described as days. The model-facing tool now emits explicit `uptimeMs` and `uptimeSeconds` fields and removes the ambiguous field while the existing REST/UI `SysStats.uptime` contract remains unchanged.
+
## 2026-09-02 — Human-first session picker + durable prompt history — SHIPPED
MSO CLI **1.6.1** removes the duplicate session navigation UI. `/session` and bare `/resume` now open exactly one native picker instead of printing a recent-session list and then rendering a second completion list. Sessions are sorted by `updatedAt` descending, the human title is the primary/only identity shown in the normal UI, and each row carries compact `modified just now / Xm / Xh / Xd / YYYY-MM-DD` metadata. The internal durable id remains the hidden selection value and an accepted exact query for automation/debugging. The Agent header, Runtime row, compact status bar, `/session`, and exit summary are title-first as well; `/status` deliberately retains the exact id for diagnostics.
diff --git a/lib/agent/memory-ledger.ts b/lib/agent/memory-ledger.ts
new file mode 100644
index 00000000..afb3bce0
--- /dev/null
+++ b/lib/agent/memory-ledger.ts
@@ -0,0 +1,72 @@
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants, promises as fs } from "node:fs";
+import path from "node:path";
+import { resolveMemoryLedger } from "./memory-resolution";
+import type { AgentMemoryDocument, AgentMemoryLedger, AgentMemoryRecord } from "./memory-types";
+
+const LEDGER_NAME = "records-v1.json";
+const MAX_LEDGER_BYTES = 2 * 1024 * 1024;
+export const MAX_MEMORY_RECORDS = 2000;
+
+export function ledgerFile(dir: string): string { return path.join(dir, LEDGER_NAME); }
+
+export async function readMemoryLedger(dir: string): Promise<AgentMemoryLedger | null> {
+ const file = ledgerFile(dir);
+ let handle: Awaited<ReturnType<typeof fs.open>> | null = null;
+ try {
+ handle = await fs.open(file, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+ const stat = await handle.stat();
+ if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_LEDGER_BYTES) throw new Error("agent memory ledger has an invalid file shape");
+ if ((stat.mode & 0o077) !== 0) throw new Error("agent memory ledger permissions are too broad; expected 0600");
+ if (typeof process.getuid === "function" && stat.uid !== process.getuid()) throw new Error("agent memory ledger is not owned by the MSO user");
+ const parsed = JSON.parse(await handle.readFile("utf8")) as AgentMemoryLedger;
+ if (parsed?.schemaVersion !== 1 || !Array.isArray(parsed.records)) throw new Error("agent memory ledger has an invalid schema");
+ return parsed;
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+ throw error;
+ } finally { await handle?.close().catch(() => undefined); }
+}
+
+export async function writeMemoryLedger(dir: string, ledger: AgentMemoryLedger): Promise<void> {
+ if (ledger.records.length > MAX_MEMORY_RECORDS) throw new Error(`agent memory ledger exceeds ${MAX_MEMORY_RECORDS} records`);
+ await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+ await fs.chmod(dir, 0o700).catch(() => undefined);
+ const file = ledgerFile(dir), tmp = `${file}.${randomUUID()}.tmp`;
+ const body = JSON.stringify(ledger, null, 2);
+ if (Buffer.byteLength(body, "utf8") > MAX_LEDGER_BYTES) throw new Error("agent memory ledger exceeds 2 MiB");
+ await fs.writeFile(tmp, body, { encoding: "utf8", mode: 0o600, flag: "wx" });
+ await fs.chmod(tmp, 0o600); await fs.rename(tmp, file); await fs.chmod(file, 0o600);
+}
+
+export function parseLegacyDocument(document: AgentMemoryDocument, source: string, now: string): AgentMemoryRecord[] {
+ const lines = source.replace(/\r\n/g, "\n").split("\n");
+ const out: AgentMemoryRecord[] = [];
+ for (let i = 0; i < lines.length; i++) {
+ if (!lines[i].startsWith("## ")) continue;
+ const key = lines[i].slice(3).trim();
+ const value: string[] = [];
+ for (i += 1; i < lines.length && !lines[i].startsWith("## "); i++) value.push(lines[i]);
+ i -= 1;
+ const body = value.join("\n").trim();
+ if (!key || !body) continue;
+ out.push({
+ id: `mem_${randomUUID()}`, document, key, value: body, kind: "semantic", confidence: 1,
+ sensitivity: "normal", validFrom: now, createdAt: now,
+ provenance: { authority: "migration", channel: "legacy", observedAt: now },
+ });
+ }
+ return out;
+}
+
+export function seedLedger(user: string, memory: string, now = new Date().toISOString()): AgentMemoryLedger {
+ return { schemaVersion: 1, updatedAt: now, records: [
+ ...parseLegacyDocument("USER.md", user, now), ...parseLegacyDocument("MEMORY.md", memory, now),
+ ] };
+}
+
+export function materializeDocuments(ledger: AgentMemoryLedger, at = new Date().toISOString()): Record<AgentMemoryDocument, string> {
+ const grouped: Record<AgentMemoryDocument, string[]> = { "USER.md": [], "MEMORY.md": [] };
+ for (const { record } of resolveMemoryLedger(ledger, at)) grouped[record.document].push(`## ${record.key}\n${record.value}`);
+ return { "USER.md": grouped["USER.md"].length ? `${grouped["USER.md"].join("\n\n")}\n` : "", "MEMORY.md": grouped["MEMORY.md"].length ? `${grouped["MEMORY.md"].join("\n\n")}\n` : "" };
+}
diff --git a/lib/agent/memory-query.ts b/lib/agent/memory-query.ts
new file mode 100644
index 00000000..723fc087
--- /dev/null
+++ b/lib/agent/memory-query.ts
@@ -0,0 +1,31 @@
+import { resolveMemoryLedger } from "./memory-resolution";
+import type { AgentMemoryLedger, AgentMemoryQuery, AgentMemoryRecord } from "./memory-types";
+
+export function memoryQueryTime(value = new Date().toISOString()): string {
+ const parsed = Date.parse(value);
+ if (!Number.isFinite(parsed)) throw new Error("at must be ISO-8601");
+ return new Date(parsed).toISOString();
+}
+
+function searchScore(record: AgentMemoryRecord, query: string): number {
+ if (!query) return 1;
+ const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+ const key = record.key.toLowerCase(), value = record.value.toLowerCase();
+ return tokens.reduce((score, token) => score + (key.includes(token) ? 4 : 0) + (value.includes(token) ? 1 : 0), 0);
+}
+
+export function queryMemoryLedger(ledger: AgentMemoryLedger, query: AgentMemoryQuery = {}) {
+ const at = memoryQueryTime(query.at), needle = (query.query ?? "").trim();
+ const limit = Math.max(1, Math.min(100, Math.trunc(query.limit ?? 20) || 20));
+ const resolved = resolveMemoryLedger(ledger, at)
+ .filter(({ record }) => (!query.document || record.document === query.document) && (!query.kind || record.kind === query.kind));
+ let rows = query.includeHistory
+ ? ledger.records.filter((record) => (!query.document || record.document === query.document) && (!query.kind || record.kind === query.kind))
+ .map((record) => ({ record, conflicts: [] as AgentMemoryRecord[] }))
+ : resolved;
+ rows = rows.map((row) => ({ ...row, score: searchScore(row.record, needle) }))
+ .filter((row) => !needle || row.score > 0)
+ .sort((a, b) => b.score - a.score || Date.parse(b.record.provenance.observedAt) - Date.parse(a.record.provenance.observedAt) || a.record.key.localeCompare(b.record.key))
+ .slice(0, limit);
+ return { at, schemaVersion: 1 as const, total: rows.length, records: rows };
+}
diff --git a/lib/agent/memory-resolution.ts b/lib/agent/memory-resolution.ts
new file mode 100644
index 00000000..2b8b7252
--- /dev/null
+++ b/lib/agent/memory-resolution.ts
@@ -0,0 +1,55 @@
+import type { AgentMemoryLedger, AgentMemoryRecord, AgentMemoryResolvedRecord } from "./memory-types";
+
+const AUTHORITY_RANK = { explicit: 4, observed: 3, inferred: 2, migration: 1 } as const;
+
+function ms(value: string | undefined): number {
+ if (!value) return Number.POSITIVE_INFINITY;
+ const parsed = Date.parse(value);
+ return Number.isFinite(parsed) ? parsed : Number.NaN;
+}
+
+export function recordEffectiveAt(record: AgentMemoryRecord, at: string): boolean {
+ const target = Date.parse(at);
+ if (!Number.isFinite(target)) throw new Error("memory query time must be ISO-8601");
+ const validFrom = ms(record.validFrom);
+ const validUntil = ms(record.validUntil);
+ const retractedAt = ms(record.retractedAt);
+ const supersededAt = ms(record.supersededAt);
+ return validFrom <= target && target < validUntil && target < retractedAt && target < supersededAt;
+}
+
+function compare(a: AgentMemoryRecord, b: AgentMemoryRecord): number {
+ const authority = AUTHORITY_RANK[b.provenance.authority] - AUTHORITY_RANK[a.provenance.authority];
+ if (authority) return authority;
+ if (b.confidence !== a.confidence) return b.confidence - a.confidence;
+ const observed = Date.parse(b.provenance.observedAt) - Date.parse(a.provenance.observedAt);
+ if (observed) return observed;
+ const created = Date.parse(b.createdAt) - Date.parse(a.createdAt);
+ if (created) return created;
+ return a.id.localeCompare(b.id);
+}
+
+export function resolveMemoryKey(
+ ledger: AgentMemoryLedger,
+ document: AgentMemoryRecord["document"],
+ key: string,
+ at = new Date().toISOString(),
+): AgentMemoryResolvedRecord | null {
+ const candidates = ledger.records
+ .filter((record) => record.document === document && record.key === key && recordEffectiveAt(record, at))
+ .sort(compare);
+ const winner = candidates[0];
+ if (!winner) return null;
+ return { record: winner, conflicts: candidates.slice(1).filter((record) => record.value !== winner.value) };
+}
+
+export function resolveMemoryLedger(ledger: AgentMemoryLedger, at = new Date().toISOString()): AgentMemoryResolvedRecord[] {
+ const pairs = new Set(ledger.records.map((record) => `${record.document}\u0000${record.key}`));
+ const out: AgentMemoryResolvedRecord[] = [];
+ for (const pair of pairs) {
+ const [document, key] = pair.split("\u0000") as [AgentMemoryRecord["document"], string];
+ const resolved = resolveMemoryKey(ledger, document, key, at);
+ if (resolved) out.push(resolved);
+ }
+ return out.sort((a, b) => a.record.document.localeCompare(b.record.document) || a.record.key.localeCompare(b.record.key));
+}
diff --git a/lib/agent/memory-store.test.ts b/lib/agent/memory-store.test.ts
new file mode 100644
index 00000000..eaa98418
--- /dev/null
+++ b/lib/agent/memory-store.test.ts
@@ -0,0 +1,91 @@
+import { afterAll, describe, expect, it, vi } from "vitest";
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const root = await fs.mkdtemp(path.join(os.tmpdir(), "mso-agent-memory-p1-"));
+process.env.OS_AGENT_MEMORY_DIR = root;
+afterAll(async () => { delete process.env.OS_AGENT_MEMORY_DIR; await fs.rm(root, { recursive: true, force: true }); });
+vi.resetModules();
+const store = await import("./memory-store");
+
+function dirFor(principal: string) {
+ const key = createHash("sha256").update(principal).digest("hex").slice(0, 32);
+ return path.join(root, key);
+}
+
+async function writeLegacy(principal: string, document: "USER.md" | "MEMORY.md", body: string) {
+ const dir = dirFor(principal); await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+ await fs.writeFile(path.join(dir, document), body, { mode: 0o600 });
+}
+
+describe("typed provenance-aware agent memory", () => {
+ it("keeps legacy Markdown readable and seeds it into the structured ledger on first write", async () => {
+ const principal = "memory:legacy";
+ await writeLegacy(principal, "USER.md", "## Locale\nIndonesia\n\n## Editor\nVS Code\n");
+ const before = await store.readAgentMemory(principal);
+ expect(before.user).toContain("## Locale\nIndonesia");
+ expect(before.schemaVersion).toBeUndefined();
+
+ const after = await store.rememberAgentMemory(principal, "MEMORY.md", "Deploy rule", "Verify before ship", {
+ kind: "procedural", provenance: { authority: "explicit", channel: "mcp" },
+ });
+ expect(after.schemaVersion).toBe(1);
+ expect(after.user).toContain("## Editor\nVS Code");
+ expect(after.memory).toContain("## Deploy rule\nVerify before ship");
+ const ledger = JSON.parse(await fs.readFile(path.join(dirFor(principal), "records-v1.json"), "utf8"));
+ expect(ledger.records).toHaveLength(3);
+ expect(ledger.records[0].provenance.authority).toBe("migration");
+ });
+
+ it("supersedes a resolved value while preserving provenance/history", async () => {
+ const principal = "memory:replace";
+ await store.rememberAgentMemory(principal, "USER.md", "Primary stack", "Next.js", { provenance: { authority: "explicit", channel: "mcp", sessionHash: "abc123" } });
+ await store.rememberAgentMemory(principal, "USER.md", "Primary stack", "SvelteKit", { kind: "semantic", confidence: 0.95, provenance: { authority: "explicit", channel: "mcp", sessionHash: "def456" } });
+ const current = await store.queryAgentMemory(principal, { query: "primary stack" });
+ expect(current.records).toHaveLength(1);
+ expect(current.records[0].record.value).toBe("SvelteKit");
+ expect(current.records[0].record.provenance.sessionHash).toBe("def456");
+ const history = await store.queryAgentMemory(principal, { query: "stack", includeHistory: true, limit: 10 });
+ expect(history.records).toHaveLength(2);
+ expect(history.records.some((row) => row.record.supersededBy)).toBe(true);
+ expect((await store.readAgentMemory(principal)).user).toContain("## Primary stack\nSvelteKit");
+ });
+
+ it("keeps parallel claims and resolves conflicts by authority, confidence, then recency", async () => {
+ const principal = "memory:conflict";
+ await store.rememberAgentMemory(principal, "MEMORY.md", "Release region", "Singapore", { mode: "claim", confidence: 0.7, provenance: { authority: "observed", channel: "system" } });
+ await store.rememberAgentMemory(principal, "MEMORY.md", "Release region", "Jakarta", { mode: "claim", confidence: 0.6, provenance: { authority: "explicit", channel: "mcp" } });
+ const result = await store.queryAgentMemory(principal, { query: "release region" });
+ expect(result.records[0].record.value).toBe("Jakarta");
+ expect(result.records[0].conflicts.map((row) => row.value)).toContain("Singapore");
+ });
+
+ it("resolves future supersession without erasing the currently valid fact early", async () => {
+ const principal = "memory:temporal";
+ const now = new Date(); const tomorrow = new Date(now.getTime() + 86_400_000); const later = new Date(now.getTime() + 2 * 86_400_000);
+ await store.rememberAgentMemory(principal, "USER.md", "Office", "Jakarta", { validFrom: new Date(now.getTime() - 60_000).toISOString() });
+ await store.rememberAgentMemory(principal, "USER.md", "Office", "Singapore", { validFrom: tomorrow.toISOString() });
+ const before = await store.queryAgentMemory(principal, { query: "office", at: now.toISOString() });
+ const after = await store.queryAgentMemory(principal, { query: "office", at: later.toISOString() });
+ expect(before.records[0].record.value).toBe("Jakarta");
+ expect(after.records[0].record.value).toBe("Singapore");
+ });
+
+ it("retracts active claims on forget and keeps ledger/doc permissions private", async () => {
+ const principal = "memory:forget";
+ await store.rememberAgentMemory(principal, "MEMORY.md", "Temporary note", "Delete me");
+ await store.forgetAgentMemory(principal, "MEMORY.md", "Temporary note");
+ expect((await store.queryAgentMemory(principal, { query: "temporary" })).records).toHaveLength(0);
+ expect((await store.readAgentMemory(principal)).memory).not.toContain("Temporary note");
+ for (const name of ["records-v1.json", "MEMORY.md"]) {
+ const stat = await fs.stat(path.join(dirFor(principal), name)); expect(stat.mode & 0o777).toBe(0o600);
+ }
+ });
+
+ it("rejects invalid confidence and invalid temporal windows", async () => {
+ await expect(store.rememberAgentMemory("memory:bad", "MEMORY.md", "Bad", "x", { confidence: 1.2 })).rejects.toThrow(/confidence/);
+ await expect(store.rememberAgentMemory("memory:bad", "MEMORY.md", "Bad", "x", { validFrom: "2026-09-02T00:00:00Z", validUntil: "2026-09-01T00:00:00Z" })).rejects.toThrow(/valid_until/);
+ });
+});
diff --git a/lib/agent/memory-store.ts b/lib/agent/memory-store.ts
index 436ec8d1..81d57d1f 100644
--- a/lib/agent/memory-store.ts
+++ b/lib/agent/memory-store.ts
@@ -3,13 +3,13 @@ import { constants as fsConstants, promises as fs } from "node:fs";
import os from "node:os";
import path from "node:path";
import { withSecurityStoreLock } from "@/lib/security-store-lock";
+import { ledgerFile, materializeDocuments, readMemoryLedger, seedLedger, writeMemoryLedger } from "./memory-ledger";
+import { queryMemoryLedger } from "./memory-query";
+import { recordEffectiveAt } from "./memory-resolution";
+import type { AgentMemoryDocument, AgentMemoryLedger, AgentMemoryQuery, AgentMemoryRecord, AgentMemoryWriteOptions } from "./memory-types";
-export type AgentMemoryDocument = "USER.md" | "MEMORY.md";
-export interface AgentMemorySnapshot {
- capturedAt: string;
- user: string;
- memory: string;
-}
+export type { AgentMemoryDocument, AgentMemoryKind, AgentMemoryQuery, AgentMemoryRecord, AgentMemorySensitivity, AgentMemoryWriteOptions } from "./memory-types";
+export interface AgentMemorySnapshot { capturedAt: string; user: string; memory: string; schemaVersion?: 1; recordCount?: number; }
const ROOT = path.resolve(process.env.OS_AGENT_MEMORY_DIR || path.join(os.homedir(), ".mso", "agent-memory"));
const MAX_DOC_BYTES = 64 * 1024;
@@ -19,118 +19,110 @@ function principalKey(principal: string): string {
if (!principal || principal.length > 512) throw new Error("invalid agent memory principal");
return createHash("sha256").update(principal).digest("hex").slice(0, 32);
}
-
-function dirFor(principal: string): string {
- return path.join(ROOT, principalKey(principal));
-}
-
-function fileFor(principal: string, document: AgentMemoryDocument): string {
- if (document !== "USER.md" && document !== "MEMORY.md") throw new Error("invalid memory document");
- return path.join(dirFor(principal), document);
-}
+function dirFor(principal: string): string { return path.join(ROOT, principalKey(principal)); }
+function fileFor(principal: string, document: AgentMemoryDocument): string { return path.join(dirFor(principal), document); }
async function readDocument(principal: string, document: AgentMemoryDocument): Promise<string> {
- const file = fileFor(principal, document);
let handle: Awaited<ReturnType<typeof fs.open>> | null = null;
try {
- handle = await fs.open(file, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+ handle = await fs.open(fileFor(principal, document), fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
const stat = await handle.stat();
- if (!stat.isFile()) throw new Error("agent memory must be a regular file");
- if (stat.size > MAX_DOC_BYTES) throw new Error("agent memory document is too large");
+ if (!stat.isFile() || stat.size > MAX_DOC_BYTES) throw new Error("agent memory document has an invalid file shape");
if ((stat.mode & 0o077) !== 0) throw new Error("agent memory permissions are too broad; expected 0600");
if (typeof process.getuid === "function" && stat.uid !== process.getuid()) throw new Error("agent memory is not owned by the MSO user");
return await handle.readFile("utf8");
} catch (error) {
if ((error as NodeJS.ErrnoException).code === "ENOENT") return "";
throw error;
- } finally {
- await handle?.close().catch(() => undefined);
- }
+ } finally { await handle?.close().catch(() => undefined); }
}
async function writeDocument(principal: string, document: AgentMemoryDocument, content: string): Promise<void> {
if (Buffer.byteLength(content, "utf8") > MAX_DOC_BYTES) throw new Error("agent memory document exceeds 64 KiB");
- const file = fileFor(principal, document);
- const dir = path.dirname(file);
+ const file = fileFor(principal, document), dir = path.dirname(file), tmp = `${file}.${randomUUID()}.tmp`;
await fs.mkdir(dir, { recursive: true, mode: 0o700 });
- await fs.chmod(ROOT, 0o700).catch(() => undefined);
- await fs.chmod(dir, 0o700).catch(() => undefined);
- const tmp = `${file}.${randomUUID()}.tmp`;
+ await fs.chmod(ROOT, 0o700).catch(() => undefined); await fs.chmod(dir, 0o700).catch(() => undefined);
await fs.writeFile(tmp, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
- await fs.chmod(tmp, 0o600);
- await fs.rename(tmp, file);
- await fs.chmod(file, 0o600);
+ await fs.chmod(tmp, 0o600); await fs.rename(tmp, file); await fs.chmod(file, 0o600);
}
function cleanKey(key: string): string {
- const normalized = key.trim();
- if (!KEY_RE.test(normalized) || normalized.startsWith("#")) throw new Error("memory key must be one line, 1-80 characters");
- return normalized;
+ const value = key.trim();
+ if (!KEY_RE.test(value) || value.startsWith("#")) throw new Error("memory key must be one line, 1-80 characters");
+ return value;
}
-
function cleanValue(value: string): string {
- const normalized = value.trim();
- if (!normalized || Buffer.byteLength(normalized, "utf8") > 8 * 1024) throw new Error("memory value must be 1-8192 bytes");
- return normalized;
+ const clean = value.trim();
+ if (!clean || Buffer.byteLength(clean, "utf8") > 8 * 1024) throw new Error("memory value must be 1-8192 bytes");
+ return clean;
+}
+function iso(value: string | undefined, fallback: string, field: string): string {
+ if (!value) return fallback;
+ const parsed = Date.parse(value);
+ if (!Number.isFinite(parsed)) throw new Error(`${field} must be ISO-8601`);
+ return new Date(parsed).toISOString();
+}
+function confidence(value: number | undefined): number {
+ const n = value ?? 1;
+ if (!Number.isFinite(n) || n < 0 || n > 1) throw new Error("memory confidence must be between 0 and 1");
+ return Math.round(n * 1000) / 1000;
}
-function replaceSection(source: string, key: string, value: string | null): string {
- const lines = source.replace(/\r\n/g, "\n").split("\n");
- const heading = `## ${key}`;
- const start = lines.findIndex((line) => line === heading);
- let next = lines.length;
- if (start >= 0) {
- for (let i = start + 1; i < lines.length; i++) {
- if (lines[i].startsWith("## ")) { next = i; break; }
- }
- lines.splice(start, next - start);
- }
- if (value !== null) {
- while (lines.length && !lines.at(-1)?.trim()) lines.pop();
- if (lines.length) lines.push("");
- lines.push(heading, value, "");
- }
- return lines.join("\n").trim() ? `${lines.join("\n").trim()}\n` : "";
+async function legacyDocs(principal: string) { const [user, memory] = await Promise.all([readDocument(principal, "USER.md"), readDocument(principal, "MEMORY.md")]); return { user, memory }; }
+async function ledgerForRead(principal: string): Promise<AgentMemoryLedger> {
+ const ledger = await readMemoryLedger(dirFor(principal));
+ if (ledger) return ledger;
+ const docs = await legacyDocs(principal); return seedLedger(docs.user, docs.memory);
+}
+function snapshotFromLedger(ledger: AgentMemoryLedger, capturedAt = new Date().toISOString()): AgentMemorySnapshot {
+ const docs = materializeDocuments(ledger, capturedAt);
+ return { capturedAt, user: docs["USER.md"], memory: docs["MEMORY.md"], schemaVersion: 1, recordCount: ledger.records.length };
+}
+async function persistProjection(principal: string, ledger: AgentMemoryLedger, at: string): Promise<void> {
+ const docs = materializeDocuments(ledger, at);
+ await writeDocument(principal, "USER.md", docs["USER.md"]); await writeDocument(principal, "MEMORY.md", docs["MEMORY.md"]);
}
export async function snapshotAgentMemory(principal: string): Promise<AgentMemorySnapshot> {
- const [user, memory] = await Promise.all([
- readDocument(principal, "USER.md"),
- readDocument(principal, "MEMORY.md"),
- ]);
- return { capturedAt: new Date().toISOString(), user, memory };
+ const stored = await readMemoryLedger(dirFor(principal));
+ if (stored) return snapshotFromLedger(stored);
+ const docs = await legacyDocs(principal); return { capturedAt: new Date().toISOString(), ...docs };
}
+export const readAgentMemory = snapshotAgentMemory;
-export async function readAgentMemory(principal: string): Promise<AgentMemorySnapshot> {
- return snapshotAgentMemory(principal);
+export async function rememberAgentMemory(principal: string, document: AgentMemoryDocument, key: string, value: string, options: AgentMemoryWriteOptions = {}): Promise<AgentMemorySnapshot> {
+ const safeKey = cleanKey(key), safeValue = cleanValue(value), now = new Date().toISOString();
+ const validFrom = iso(options.validFrom, now, "valid_from"), validUntil = options.validUntil ? iso(options.validUntil, now, "valid_until") : undefined;
+ if (validUntil && Date.parse(validUntil) <= Date.parse(validFrom)) throw new Error("valid_until must be after valid_from");
+ const record: AgentMemoryRecord = {
+ id: `mem_${randomUUID()}`, document, key: safeKey, value: safeValue, kind: options.kind ?? "semantic",
+ confidence: confidence(options.confidence), sensitivity: options.sensitivity ?? "normal", validFrom,
+ ...(validUntil ? { validUntil } : {}), createdAt: now,
+ provenance: { authority: options.provenance?.authority ?? "explicit", channel: options.provenance?.channel ?? "system", observedAt: iso(options.provenance?.observedAt, now, "observed_at"), ...(options.provenance?.sessionHash ? { sessionHash: options.provenance.sessionHash } : {}) },
+ };
+ let result!: AgentMemoryLedger;
+ await withSecurityStoreLock(ledgerFile(dirFor(principal)), async () => {
+ const current = await readMemoryLedger(dirFor(principal)) ?? await (async () => { const docs = await legacyDocs(principal); return seedLedger(docs.user, docs.memory, now); })();
+ if ((options.mode ?? "replace") === "replace") {
+ const superseded = current.records.filter((row) => row.document === document && row.key === safeKey && recordEffectiveAt(row, validFrom));
+ if (superseded.length) record.supersedes = superseded.map((row) => row.id);
+ for (const row of superseded) { row.supersededAt = validFrom; row.supersededBy = record.id; }
+ }
+ current.records.push(record); current.updatedAt = now; await writeMemoryLedger(dirFor(principal), current); await persistProjection(principal, current, now); result = current;
+ });
+ return snapshotFromLedger(result, now);
}
-export async function rememberAgentMemory(
- principal: string,
- document: AgentMemoryDocument,
- key: string,
- value: string,
-): Promise<AgentMemorySnapshot> {
- const safeKey = cleanKey(key);
- const safeValue = cleanValue(value);
- const file = fileFor(principal, document);
- await withSecurityStoreLock(file, async () => {
- const current = await readDocument(principal, document);
- await writeDocument(principal, document, replaceSection(current, safeKey, safeValue));
+export async function forgetAgentMemory(principal: string, document: AgentMemoryDocument, key: string): Promise<AgentMemorySnapshot> {
+ const safeKey = cleanKey(key), now = new Date().toISOString(); let result!: AgentMemoryLedger;
+ await withSecurityStoreLock(ledgerFile(dirFor(principal)), async () => {
+ const current = await readMemoryLedger(dirFor(principal)) ?? await (async () => { const docs = await legacyDocs(principal); return seedLedger(docs.user, docs.memory, now); })();
+ for (const row of current.records) if (row.document === document && row.key === safeKey && recordEffectiveAt(row, now)) row.retractedAt = now;
+ current.updatedAt = now; await writeMemoryLedger(dirFor(principal), current); await persistProjection(principal, current, now); result = current;
});
- return snapshotAgentMemory(principal);
+ return snapshotFromLedger(result, now);
}
-export async function forgetAgentMemory(
- principal: string,
- document: AgentMemoryDocument,
- key: string,
-): Promise<AgentMemorySnapshot> {
- const safeKey = cleanKey(key);
- const file = fileFor(principal, document);
- await withSecurityStoreLock(file, async () => {
- const current = await readDocument(principal, document);
- await writeDocument(principal, document, replaceSection(current, safeKey, null));
- });
- return snapshotAgentMemory(principal);
+export async function queryAgentMemory(principal: string, query: AgentMemoryQuery = {}) {
+ return queryMemoryLedger(await ledgerForRead(principal), query);
}
diff --git a/lib/agent/memory-types.ts b/lib/agent/memory-types.ts
new file mode 100644
index 00000000..75b336b2
--- /dev/null
+++ b/lib/agent/memory-types.ts
@@ -0,0 +1,60 @@
+export type AgentMemoryDocument = "USER.md" | "MEMORY.md";
+export type AgentMemoryKind = "semantic" | "episodic" | "procedural";
+export type AgentMemorySensitivity = "normal" | "private" | "restricted";
+export type AgentMemoryAuthority = "explicit" | "observed" | "inferred" | "migration";
+export type AgentMemoryChannel = "mcp" | "cli" | "alfa" | "system" | "legacy";
+
+export interface AgentMemoryProvenance {
+ authority: AgentMemoryAuthority;
+ channel: AgentMemoryChannel;
+ observedAt: string;
+ sessionHash?: string;
+}
+
+export interface AgentMemoryRecord {
+ id: string;
+ document: AgentMemoryDocument;
+ key: string;
+ value: string;
+ kind: AgentMemoryKind;
+ confidence: number;
+ sensitivity: AgentMemorySensitivity;
+ validFrom: string;
+ validUntil?: string;
+ createdAt: string;
+ provenance: AgentMemoryProvenance;
+ supersedes?: string[];
+ supersededAt?: string;
+ supersededBy?: string;
+ retractedAt?: string;
+}
+
+export interface AgentMemoryLedger {
+ schemaVersion: 1;
+ updatedAt: string;
+ records: AgentMemoryRecord[];
+}
+
+export interface AgentMemoryWriteOptions {
+ kind?: AgentMemoryKind;
+ confidence?: number;
+ sensitivity?: AgentMemorySensitivity;
+ validFrom?: string;
+ validUntil?: string;
+ mode?: "replace" | "claim";
+ provenance?: Partial<AgentMemoryProvenance>;
+}
+
+export interface AgentMemoryQuery {
+ query?: string;
+ document?: AgentMemoryDocument;
+ kind?: AgentMemoryKind;
+ at?: string;
+ limit?: number;
+ includeHistory?: boolean;
+}
+
+export interface AgentMemoryResolvedRecord {
+ record: AgentMemoryRecord;
+ conflicts: AgentMemoryRecord[];
+}
diff --git a/lib/mcp/activity.ts b/lib/mcp/activity.ts
index f2d2ea5d..13dacc05 100644
--- a/lib/mcp/activity.ts
+++ b/lib/mcp/activity.ts
@@ -3,7 +3,7 @@ import os from "os";
import path from "path";
import { randomUUID } from "crypto";
-export type McpActivityState = "started" | "completed" | "failed" | "denied" | "rate_limited";
+export type McpActivityState = "started" | "completed" | "failed" | "denied" | "rate_limited" | "invalid_args";
export interface McpActivityEntry {
id: string;
diff --git a/lib/mcp/dispatch-tools.ts b/lib/mcp/dispatch-tools.ts
index da186a5b..862b7557 100644
--- a/lib/mcp/dispatch-tools.ts
+++ b/lib/mcp/dispatch-tools.ts
@@ -33,7 +33,14 @@ export async function dispatchToolCall(req: RpcRequest, scope: Scope, actor?: st
}
for (const key of tool.inputSchema.required ?? []) {
- if (args[key] == null) return rpcFail(id, -32602, `${name} needs { ${(tool.inputSchema.required ?? []).join(", ")} }`);
+ if (args[key] != null) continue;
+ const activityId = newActivityId(), detail = `${name} needs { ${(tool.inputSchema.required ?? []).join(", ")} }`;
+ if (!workflowProbe) {
+ void recordMcpActivity({ id: activityId, actor, tool: name, state: "invalid_args", scope, ...initialFlow, target, detail });
+ await recordWorkflowStep(flowActor, activeWorkflow?.id, { id: activityId, tool: name, state: "invalid_args", target, args, ts: new Date().toISOString() });
+ await recordAgentEvent(context, name, "invalid_args", args, activeWorkflow?.id, target);
+ }
+ return rpcFail(id, -32602, detail);
}
if (requestedWorkflowId && !lifecycle && !workflowProbe && name !== "workflow_start" && name !== "skills_search" && !activeWorkflow) {
const activityId = newActivityId(), message = "workflow_id was not found for this MSO session";
diff --git a/lib/mcp/dispatch.test.ts b/lib/mcp/dispatch.test.ts
index d76b9b34..cb8e0963 100644
--- a/lib/mcp/dispatch.test.ts
+++ b/lib/mcp/dispatch.test.ts
@@ -132,6 +132,17 @@ describe("tools/call enforces scope even when the tool was never listed", () =>
expect((await dispatch(call("fs_read", {}), "read")).error).toMatchObject({ code: -32602 });
});
+
+ it("records missing required arguments as invalid_args inside the exact workflow", async () => {
+ const actor = "mcp:invalid-args";
+ const started = await dispatch(call("workflow_start", { intent: "test invalid argument telemetry" }), "write", actor);
+ const workflowId = (JSON.parse((started.result as { content: { text: string }[] }).content[0].text) as { workflow: { id: string } }).workflow.id;
+ const bad = await dispatch(call("fs_write", { path: "/tmp/test", workflow_id: workflowId }), "write", actor);
+ expect(bad.error).toMatchObject({ code: -32602 });
+ expect((await activeWorkflowForActor(actor, workflowId))?.steps.at(-1)).toMatchObject({ tool: "fs_write", state: "invalid_args" });
+ await dispatch(call("workflow_cancel", { workflow_id: workflowId, reason: "test cleanup" }), "write", actor);
+ });
+
it("returns a handler failure as isError text, never as a protocol error", async () => {
// Outside every read root → lib/host refuses. The point is the SHAPE.
const r = await dispatch(call("fs_read", { path: "/proc/1/environ" }), "read");
diff --git a/lib/mcp/parity.test.ts b/lib/mcp/parity.test.ts
index 8ab94097..0b94ac9d 100644
--- a/lib/mcp/parity.test.ts
+++ b/lib/mcp/parity.test.ts
@@ -48,6 +48,7 @@ const MCP_ONLY: Record<string, string> = {
"agent.session.rename": "durable MCP/terminal session titles are metadata in the isolated agent-session store; Alfa keeps its separate in-app thread/title lifecycle",
"agent.session.note": "durable operational notes belong to the MCP client's isolated MSO session store; Alfa has a separate owner-scoped conversation/memory store",
"agent.memory.read": "MCP clients use isolated USER.md/MEMORY.md-style agent memory snapshots; Alfa intentionally keeps its existing owner recall instead of sharing external-client memory",
+ "agent.memory.search": "typed provenance/temporal retrieval belongs to that same isolated MCP/terminal memory ledger; exposing it as Alfa owner recall would collapse the deliberate principal boundary",
"agent.memory.remember": "same isolated MCP memory store; sharing it with Alfa would collapse two trust/ownership boundaries",
"agent.memory.forget": "same isolated MCP memory store; deletion remains scoped to the external MCP client principal",
"exec.job.start": "external MCP requests have a hard request-time budget and need a bounded resumable shell job; in-shell Alfa can keep using its interactive Terminal/approved exec.run surfaces",
diff --git a/lib/mcp/tools-agent.test.ts b/lib/mcp/tools-agent.test.ts
new file mode 100644
index 00000000..0c45519f
--- /dev/null
+++ b/lib/mcp/tools-agent.test.ts
@@ -0,0 +1,35 @@
+import { afterAll, describe, expect, it, vi } from "vitest";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const root = await fs.mkdtemp(path.join(os.tmpdir(), "mso-tools-agent-p1-"));
+process.env.OS_AGENT_MEMORY_DIR = root;
+afterAll(async () => { delete process.env.OS_AGENT_MEMORY_DIR; await fs.rm(root, { recursive: true, force: true }); });
+vi.resetModules();
+const { AGENT_TOOLS } = await import("./tools-agent");
+
+function tool(name: string) {
+ const found = AGENT_TOOLS.find((row) => row.name === name);
+ if (!found) throw new Error(`missing tool ${name}`);
+ return found;
+}
+
+describe("typed MCP agent memory tools", () => {
+ it("hashes conversation provenance and exposes typed conflict evidence without the raw session id", async () => {
+ const context = { principal: "mcp-client:test", sessionId: "raw-openai-conversation-id-must-not-persist", scope: "exec" as const };
+ await tool("agent_memory_remember").run({ document: "MEMORY.md", key: "Region", value: "Singapore", mode: "claim", confidence: 0.9 }, context);
+ await tool("agent_memory_remember").run({ document: "MEMORY.md", key: "Region", value: "Jakarta", mode: "claim", confidence: 0.8 }, context);
+ const result = await tool("agent_memory_search").run({ query: "region" }, context) as { records: Array<{ record: { provenance: { sessionHash?: string } }, conflicts: unknown[] }> };
+ expect(result.records).toHaveLength(1);
+ expect(result.records[0].conflicts).toHaveLength(1);
+ expect(result.records[0].record.provenance.sessionHash).toMatch(/^[a-f0-9]{24}$/);
+ const persisted = (await Promise.all((await fs.readdir(root, { withFileTypes: true })).filter((row) => row.isDirectory()).map(async (row) => fs.readFile(path.join(root, row.name, "records-v1.json"), "utf8"))))[0];
+ expect(persisted).not.toContain(context.sessionId);
+ });
+
+ it("validates typed metadata instead of accepting arbitrary labels", async () => {
+ const context = { principal: "mcp-client:bad", sessionId: "session", scope: "exec" as const };
+ expect(() => tool("agent_memory_remember").run({ document: "MEMORY.md", key: "x", value: "y", kind: "graph" }, context)).toThrow(/kind must be one of/);
+ });
+});
diff --git a/lib/mcp/tools-agent.ts b/lib/mcp/tools-agent.ts
index f2501edd..83541e5a 100644
--- a/lib/mcp/tools-agent.ts
+++ b/lib/mcp/tools-agent.ts
@@ -1,4 +1,5 @@
-import { forgetAgentMemory, readAgentMemory, rememberAgentMemory, type AgentMemoryDocument } from "@/lib/agent/memory-store";
+import { createHash } from "node:crypto";
+import { forgetAgentMemory, queryAgentMemory, readAgentMemory, rememberAgentMemory, type AgentMemoryDocument, type AgentMemoryKind, type AgentMemorySensitivity } from "@/lib/agent/memory-store";
import { agentSessionSummary, appendAgentSessionEvent, getAgentSession, listAgentSessions, renameAgentSession, resumeAgentSession } from "@/lib/agent/session-store";
import { type McpTool, S, str } from "./tool-kit";
@@ -11,6 +12,17 @@ function document(a: Record<string, unknown>): AgentMemoryDocument {
if (value !== "USER.md" && value !== "MEMORY.md") throw new Error("document must be USER.md or MEMORY.md");
return value;
}
+function optionalString(a: Record<string, unknown>, key: string): string | undefined {
+ const value = a[key]; return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function enumValue<T extends string>(a: Record<string, unknown>, key: string, allowed: readonly T[]): T | undefined {
+ const value = optionalString(a, key); if (!value) return undefined;
+ if (!allowed.includes(value as T)) throw new Error(`${key} must be one of ${allowed.join(", ")}`);
+ return value as T;
+}
+function sessionHash(sessionId?: string): string | undefined {
+ return sessionId ? createHash("sha256").update(sessionId).digest("hex").slice(0, 24) : undefined;
+}
export const AGENT_TOOLS: McpTool[] = [
{
@@ -63,16 +75,50 @@ export const AGENT_TOOLS: McpTool[] = [
},
{
name: "agent_memory_read",
- description: "Read this MCP client's persistent USER.md and MEMORY.md. New sessions capture a frozen snapshot.",
+ description: "Read this MCP client's resolved persistent USER.md and MEMORY.md compatibility view. New sessions capture a frozen snapshot.",
scope: "read", annotations: { readOnlyHint: true, idempotentHint: true }, inputSchema: S({}),
run: (_a, context) => readAgentMemory(principal(context)),
},
+ {
+ name: "agent_memory_search",
+ description: "Search typed persistent memory claims with provenance, confidence, temporal validity and conflict evidence. Defaults to currently resolved records; include_history=true also returns superseded/retracted claims.",
+ scope: "read", annotations: { readOnlyHint: true, idempotentHint: true },
+ inputSchema: S({
+ query: { type: "string", description: "Optional keywords matched against memory key/value." },
+ document: { type: "string", enum: ["USER.md", "MEMORY.md"] },
+ kind: { type: "string", enum: ["semantic", "episodic", "procedural"] },
+ at: { type: "string", description: "Optional ISO-8601 time for temporal resolution; defaults to now." },
+ limit: { type: "number", description: "Maximum records, 1-100 (default 20)." },
+ include_history: { type: "boolean", description: "Also return superseded/retracted claims instead of only resolved records." },
+ }),
+ run: (a, context) => queryAgentMemory(principal(context), {
+ query: optionalString(a, "query"),
+ document: optionalString(a, "document") as AgentMemoryDocument | undefined,
+ kind: enumValue<AgentMemoryKind>(a, "kind", ["semantic", "episodic", "procedural"]),
+ at: optionalString(a, "at"), limit: Number(a.limit) || undefined, includeHistory: a.include_history === true,
+ }),
+ },
{
name: "agent_memory_remember",
- description: "Create/replace a keyed entry in this MCP client's USER.md or MEMORY.md. Never store secrets.",
+ description: "Persist one typed memory claim. replace (default) supersedes the currently resolved value for the key; claim keeps parallel evidence so conflicts remain inspectable. Never store secrets.",
scope: "write", limit: { key: "agent.memory", max: 30, windowMs: 60_000 }, audit: { action: "agent.memory", targetArg: "key" },
- inputSchema: S({ document: { type: "string", enum: ["USER.md", "MEMORY.md"] }, key: { type: "string" }, value: { type: "string" } }, ["document", "key", "value"]),
- run: (a, context) => rememberAgentMemory(principal(context), document(a), str(a, "key"), str(a, "value")),
+ inputSchema: S({
+ document: { type: "string", enum: ["USER.md", "MEMORY.md"] }, key: { type: "string" }, value: { type: "string" },
+ kind: { type: "string", enum: ["semantic", "episodic", "procedural"] },
+ confidence: { type: "number", minimum: 0, maximum: 1 },
+ sensitivity: { type: "string", enum: ["normal", "private", "restricted"] },
+ valid_from: { type: "string", description: "Optional ISO-8601 validity start; defaults to now." },
+ valid_until: { type: "string", description: "Optional ISO-8601 validity end." },
+ mode: { type: "string", enum: ["replace", "claim"], description: "replace supersedes the current resolved claim; claim preserves parallel evidence." },
+ }, ["document", "key", "value"]),
+ run: (a, context) => rememberAgentMemory(principal(context), document(a), str(a, "key"), str(a, "value"), {
+ kind: enumValue<AgentMemoryKind>(a, "kind", ["semantic", "episodic", "procedural"]),
+ confidence: a.confidence === undefined ? undefined : Number(a.confidence),
+ sensitivity: enumValue<AgentMemorySensitivity>(a, "sensitivity", ["normal", "private", "restricted"]),
+ validFrom: optionalString(a, "valid_from"), validUntil: optionalString(a, "valid_until"),
+ mode: enumValue(a, "mode", ["replace", "claim"] as const),
+ provenance: { authority: "explicit", channel: "mcp", sessionHash: sessionHash(context.sessionId) },
+ }),
},
{
name: "agent_memory_forget",
diff --git a/lib/mcp/tools-learning.ts b/lib/mcp/tools-learning.ts
index 3338355d..6031b33d 100644
--- a/lib/mcp/tools-learning.ts
+++ b/lib/mcp/tools-learning.ts
@@ -27,7 +27,7 @@ const WORKFLOW_PROGRESS_OUTPUT = {
type: "object",
properties: {
tool: { type: "string" },
- state: { type: "string", enum: ["completed", "failed", "denied", "rate_limited"] },
+ state: { type: "string", enum: ["completed", "failed", "denied", "rate_limited", "invalid_args"] },
durationMs: { type: "number" },
ts: { type: "string" },
},
@@ -42,7 +42,7 @@ const WORKFLOW_PROGRESS_OUTPUT = {
type WorkflowProgressStep = {
tool: string;
- state: "completed" | "failed" | "denied" | "rate_limited";
+ state: "completed" | "failed" | "denied" | "rate_limited" | "invalid_args";
durationMs?: number;
ts: string;
};
@@ -62,7 +62,7 @@ function workflowSteps(value: unknown): WorkflowProgressStep[] {
const step = candidate as Record<string, unknown>;
const state = step.state;
if (typeof step.tool !== "string" || typeof step.ts !== "string") continue;
- if (state !== "completed" && state !== "failed" && state !== "denied" && state !== "rate_limited") continue;
+ if (state !== "completed" && state !== "failed" && state !== "denied" && state !== "rate_limited" && state !== "invalid_args") continue;
out.push({
tool: step.tool.slice(0, 100),
state,
diff --git a/lib/mcp/tools-read-stats.test.ts b/lib/mcp/tools-read-stats.test.ts
new file mode 100644
index 00000000..ccfb10a5
--- /dev/null
+++ b/lib/mcp/tools-read-stats.test.ts
@@ -0,0 +1,15 @@
+import { describe, expect, it, vi } from "vitest";
+vi.mock("server-only", () => ({}));
+const { READ_TOOLS } = await import("./tools-read");
+
+describe("sys_stats model contract", () => {
+ it("returns uptime with explicit units and no ambiguous uptime field", async () => {
+ const tool = READ_TOOLS.find((row) => row.name === "sys_stats");
+ expect(tool?.description).toContain("uptimeMs");
+ const result = await tool!.run({}, { scope: "read" }) as Record<string, unknown>;
+ expect(result.uptime).toBeUndefined();
+ expect(result.uptimeMs).toEqual(expect.any(Number));
+ expect(result.uptimeSeconds).toEqual(expect.any(Number));
+ expect(Number(result.uptimeMs)).toBeGreaterThan(Number(result.uptimeSeconds));
+ });
+});
diff --git a/lib/mcp/tools-read.ts b/lib/mcp/tools-read.ts
index 126f052c..5aba3c48 100644
--- a/lib/mcp/tools-read.ts
+++ b/lib/mcp/tools-read.ts
@@ -61,12 +61,15 @@ export const READ_TOOLS: McpTool[] = [
{
name: "sys_stats",
description:
- "Live VPS health: CPU load, memory, disk, uptime. USE THIS for 'how is the server doing' — " +
- "it is one cheap call and needs no shell scope.",
+ "Live VPS health: CPU load, memory, disk and uptime. Uptime is returned with explicit units as uptimeMs and uptimeSeconds — never interpret either as days. " +
+ "USE THIS for 'how is the server doing'; it is one cheap call and needs no shell scope.",
scope: "read",
annotations: READ_ONLY,
inputSchema: S({}),
- run: () => stats(),
+ run: async () => {
+ const { uptime, ...health } = await stats();
+ return { ...health, uptimeMs: Math.round(uptime), uptimeSeconds: Math.round(uptime / 1000) };
+ },
},
{
name: "sys_processes",
diff --git a/lib/mcp/toolset.ts b/lib/mcp/toolset.ts
index 4e3ab7cb..996de57e 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.1";
-export const MCP_TOOLSET_CHANGED_AT = "2026-09-01T18:01:00Z";
+export const MCP_TOOLSET_VERSION = "2026.09.02.2";
+export const MCP_TOOLSET_CHANGED_AT = "2026-09-01T20:10:00Z";
export type McpToolsetInfo = {
serverVersion: string;
diff --git a/lib/mcp/ui-resources.ts b/lib/mcp/ui-resources.ts
index 79bea1cc..76735f64 100644
--- a/lib/mcp/ui-resources.ts
+++ b/lib/mcp/ui-resources.ts
@@ -30,7 +30,7 @@ const workflowProgressHtml = String.raw`<main class="mso-workflow" aria-live="po
li:first-child { border-top: 0; }
.dot { width: 7px; height: 7px; border-radius: 50%; background: color-mix(in srgb, CanvasText 35%, transparent); }
.dot.completed { background: #22c55e; }
- .dot.failed, .dot.denied, .dot.rate_limited { background: #ef4444; }
+ .dot.failed, .dot.denied, .dot.rate_limited, .dot.invalid_args { background: #ef4444; }
.tool { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
.duration { color: color-mix(in srgb, CanvasText 50%, transparent); font-variant-numeric: tabular-nums; }
.empty { padding: 8px 0 10px; color: color-mix(in srgb, CanvasText 52%, transparent); font-size: 11px; }
diff --git a/lib/skills/memory-quality.test.ts b/lib/skills/memory-quality.test.ts
new file mode 100644
index 00000000..9e467c67
--- /dev/null
+++ b/lib/skills/memory-quality.test.ts
@@ -0,0 +1,30 @@
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const dir = await fs.mkdtemp(path.join(os.tmpdir(), "mso-skill-quality-"));
+process.env.OS_SKILL_MEMORY_STORE = path.join(dir, "memory.json");
+const memory = await import("./memory");
+
+describe("learned workflow quality telemetry", () => {
+ beforeEach(async () => { await fs.rm(process.env.OS_SKILL_MEMORY_STORE!, { force: true }); memory.resetSkillMemoryCache(); });
+ afterAll(async () => { await fs.rm(dir, { recursive: true, force: true }); });
+
+ it("tracks retries, invalid args, failures, denials, rollback signals and latency", async () => {
+ const started = await memory.startWorkflow({ actor: "mcp:quality", intent: "recover a failed deployment with a verified restore" });
+ const now = new Date().toISOString();
+ await memory.recordWorkflowStep("mcp:quality", started.workflow.id, { id: "bad-args", tool: "exec_run", state: "invalid_args", target: "bun", ts: now });
+ await memory.recordWorkflowStep("mcp:quality", started.workflow.id, { id: "failed", tool: "exec_run", state: "failed", target: "bun", durationMs: 30, ts: now });
+ await memory.recordWorkflowStep("mcp:quality", started.workflow.id, { id: "retry", tool: "exec_run", state: "completed", target: "bun", durationMs: 20, ts: now });
+ await memory.recordWorkflowStep("mcp:quality", started.workflow.id, { id: "restore", tool: "exec_run", state: "completed", target: "restore backup", durationMs: 10, ts: now });
+ await memory.recordWorkflowStep("mcp:quality", started.workflow.id, { id: "denied", tool: "fs_write", state: "denied", target: "/srv/app", ts: now });
+ const done = await memory.finishWorkflow({ actor: "mcp:quality", workflowId: started.workflow.id, summary: "restored and verified", success: true });
+ expect(done.recipe.qualityVersion).toBe(1);
+ expect(done.recipe.lastQuality).toMatchObject({
+ stepAttempts: 5, completedSteps: 2, failedSteps: 1, deniedSteps: 1, invalidArgSteps: 1,
+ retries: 2, rollbackSignals: 1, timedSteps: 3, totalStepDurationMs: 60, averageStepDurationMs: 20,
+ });
+ expect(done.recipe.quality).toEqual(done.recipe.lastQuality);
+ });
+});
diff --git a/lib/skills/memory.test.ts b/lib/skills/memory.test.ts
index d11cb551..3e5501c8 100644
--- a/lib/skills/memory.test.ts
+++ b/lib/skills/memory.test.ts
@@ -232,4 +232,5 @@ describe("learned workflow recipes", () => {
expect(recipe.bestSteps[1].args).toEqual({ path: "/srv/app/.env" });
});
+
});
diff --git a/lib/skills/memory.ts b/lib/skills/memory.ts
index 731660da..ce3b3241 100644
--- a/lib/skills/memory.ts
+++ b/lib/skills/memory.ts
@@ -6,7 +6,7 @@ import path from "path";
import { embedSkillText, hybridSemanticScore, normalizeSemanticText, SKILL_EMBEDDING_VERSION } from "./semantic";
import { allows, type Scope } from "@/lib/mcp/scope";
-export type WorkflowStepState = "completed" | "failed" | "denied" | "rate_limited";
+export type WorkflowStepState = "completed" | "failed" | "denied" | "rate_limited" | "invalid_args";
export type WorkflowStep = {
id: string;
@@ -32,6 +32,12 @@ export type ActiveWorkflow = {
steps: WorkflowStep[];
};
+export type WorkflowQuality = {
+ stepAttempts: number; completedSteps: number; failedSteps: number; deniedSteps: number;
+ rateLimitedSteps: number; invalidArgSteps: number; retries: number; rollbackSignals: number;
+ timedSteps: number; totalStepDurationMs: number; averageStepDurationMs: number;
+};
+
export type LearnedRecipe = {
id: string;
actor: string;
@@ -52,6 +58,9 @@ export type LearnedRecipe = {
lastDurationMs: number;
averageWallDurationMs: number;
lastWallDurationMs: number;
+ quality: WorkflowQuality;
+ lastQuality: WorkflowQuality;
+ qualityVersion?: 1;
createdAt: string;
updatedAt: string;
lastUsedAt?: string;
@@ -155,6 +164,9 @@ function normalizeRecipes(value: unknown): Record<string, LearnedRecipe> {
lastSteps: Array.isArray(row.lastSteps)
? row.lastSteps.map(sanitizeStoredStep).filter((step): step is WorkflowStep => Boolean(step))
: [],
+ quality: normalizeQuality(row.quality),
+ lastQuality: normalizeQuality(row.lastQuality),
+ ...(row.qualityVersion === 1 ? { qualityVersion: 1 as const } : {}),
};
}
return out;
@@ -297,7 +309,7 @@ function sanitizeStoredStep(value: unknown): WorkflowStep | null {
if (!value || typeof value !== "object") return null;
const row = value as Partial<WorkflowStepInput>;
if (typeof row.id !== "string" || typeof row.tool !== "string" ||
- !["completed", "failed", "denied", "rate_limited"].includes(String(row.state)) ||
+ !["completed", "failed", "denied", "rate_limited", "invalid_args"].includes(String(row.state)) ||
typeof row.ts !== "string") return null;
const durationMs = typeof row.durationMs === "number" && Number.isFinite(row.durationMs)
? Math.max(0, Math.min(86_400_000, Math.round(row.durationMs)))
@@ -313,6 +325,37 @@ function sanitizeStoredStep(value: unknown): WorkflowStep | null {
};
}
+
+function emptyQuality(): WorkflowQuality {
+ return { stepAttempts: 0, completedSteps: 0, failedSteps: 0, deniedSteps: 0, rateLimitedSteps: 0, invalidArgSteps: 0, retries: 0, rollbackSignals: 0, timedSteps: 0, totalStepDurationMs: 0, averageStepDurationMs: 0 };
+}
+function normalizeQuality(value: unknown): WorkflowQuality {
+ const base = emptyQuality(); if (!value || typeof value !== "object") return base;
+ const row = value as Partial<WorkflowQuality>;
+ for (const key of Object.keys(base) as Array<keyof WorkflowQuality>) {
+ const n = Number(row[key]); if (Number.isFinite(n) && n >= 0) base[key] = Math.round(n) as never;
+ }
+ base.averageStepDurationMs = base.timedSteps ? Math.round(base.totalStepDurationMs / base.timedSteps) : 0;
+ return base;
+}
+export function summarizeWorkflowQuality(steps: WorkflowStep[]): WorkflowQuality {
+ const out = emptyQuality(), pending = new Set<string>();
+ for (const step of steps) {
+ out.stepAttempts += 1;
+ if (pending.has(step.tool)) { out.retries += 1; pending.delete(step.tool); }
+ if (step.state === "completed") out.completedSteps += 1;
+ else { pending.add(step.tool); if (step.state === "failed") out.failedSteps += 1; else if (step.state === "denied") out.deniedSteps += 1; else if (step.state === "rate_limited") out.rateLimitedSteps += 1; else out.invalidArgSteps += 1; }
+ if (typeof step.durationMs === "number") { out.timedSteps += 1; out.totalStepDurationMs += step.durationMs; }
+ if (step.state === "completed" && /\b(rollback|restore|revert)\b/i.test(JSON.stringify([step.tool, step.target, step.args]))) out.rollbackSignals += 1;
+ }
+ out.averageStepDurationMs = out.timedSteps ? Math.round(out.totalStepDurationMs / out.timedSteps) : 0;
+ return out;
+}
+function mergeQuality(a: WorkflowQuality, b: WorkflowQuality): WorkflowQuality {
+ const out = emptyQuality();
+ for (const key of ["stepAttempts", "completedSteps", "failedSteps", "deniedSteps", "rateLimitedSteps", "invalidArgSteps", "retries", "rollbackSignals", "timedSteps", "totalStepDurationMs"] as const) out[key] = a[key] + b[key];
+ out.averageStepDurationMs = out.timedSteps ? Math.round(out.totalStepDurationMs / out.timedSteps) : 0; return out;
+}
function enrichBestSteps(best: WorkflowStep[], current: WorkflowStep[]): WorkflowStep[] {
if (best.length !== current.length || best.some((step, i) => step.tool !== current[i]?.tool)) return best;
return best.map((step, i) => ({
@@ -509,6 +552,7 @@ export async function finishWorkflow(input: {
const vector = embedSkillText(recipeText(workflow.intent, workflow.project, summary));
const timestamp = now.toISOString();
const compactSteps = compactRecipeSteps(workflow.steps);
+ const currentQuality = summarizeWorkflowQuality(workflow.steps);
let recipe: LearnedRecipe;
if (existing) {
@@ -536,6 +580,9 @@ export async function finishWorkflow(input: {
lastDurationMs: durationMs,
averageWallDurationMs: Math.round((existing.averageWallDurationMs * existing.attempts + wallMs) / attempts),
lastWallDurationMs: wallMs,
+ quality: mergeQuality(existing.quality, currentQuality),
+ lastQuality: currentQuality,
+ qualityVersion: 1,
updatedAt: timestamp,
};
} else {
@@ -559,6 +606,9 @@ export async function finishWorkflow(input: {
lastDurationMs: durationMs,
averageWallDurationMs: wallMs,
lastWallDurationMs: wallMs,
+ quality: currentQuality,
+ lastQuality: currentQuality,
+ qualityVersion: 1,
createdAt: timestamp,
updatedAt: timestamp,
};
diff --git a/package.json b/package.json
index da5b0b8b..a8750f20 100644
--- a/package.json
+++ b/package.json
@@ -26,7 +26,10 @@
"skill:new": "node scripts/create-skill-flow.mjs",
"skill:check": "node scripts/check-skill-flows.mjs",
"comparison": "node scripts/gen-comparison.mjs",
- "bench:cognitive": "bun scripts/bench-cognitive-runtime.mjs"
+ "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"
},
"dependencies": {
"@anthropic-ai/sdk": "^0.120.0",
diff --git a/scripts/bench-agent-comparison.mjs b/scripts/bench-agent-comparison.mjs
new file mode 100644
index 00000000..de5ca128
--- /dev/null
+++ b/scripts/bench-agent-comparison.mjs
@@ -0,0 +1,123 @@
+#!/usr/bin/env bun
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+function modelFamily(value = "") {
+ const raw = String(value).toLowerCase().trim();
+ return raw.split("/").at(-1)?.replace(/^models\//, "") || raw;
+}
+export function sameModelFamily(reported, requested) { return modelFamily(reported) === modelFamily(requested); }
+
+export function benchmarkPrompt(file) {
+ return [
+ "READ-ONLY benchmark. You must use a filesystem/read tool to inspect the JSON file at:", file,
+ "Do not modify any file and do not use information from the prompt as a substitute for reading the file.",
+ "From the file, read nonce, alpha, beta, gamma. Compute alpha*2 + beta*3 + gamma.",
+ "Reply with exactly BENCH:<nonce>:<integer> and no other text.",
+ ].join("\n");
+}
+
+export function expectedAnswer(fixture) { return `BENCH:${fixture.nonce}:${fixture.alpha * 2 + fixture.beta * 3 + fixture.gamma}`; }
+
+function strings(value, out = []) {
+ if (typeof value === "string") out.push(value);
+ else if (Array.isArray(value)) value.forEach((v) => strings(v, out));
+ else if (value && typeof value === "object") Object.values(value).forEach((v) => strings(v, out));
+ return out;
+}
+function jsonMaybe(text) {
+ try { return JSON.parse(text); } catch {}
+ const lines = String(text).trim().split(/\r?\n/).reverse();
+ for (const line of lines) { try { return JSON.parse(line); } catch {} }
+ return null;
+}
+function reportedModel(value) {
+ if (!value || typeof value !== "object") return null;
+ for (const [key, candidate] of Object.entries(value)) {
+ if (["model", "modelId", "model_id"].includes(key) && typeof candidate === "string") return candidate;
+ const nested = reportedModel(candidate); if (nested) return nested;
+ }
+ return null;
+}
+function tokenUsage(value) {
+ if (!value || typeof value !== "object") return null;
+ const obj = value;
+ const input = Number(obj.inputTokens ?? obj.input_tokens ?? obj.prompt_tokens);
+ const output = Number(obj.outputTokens ?? obj.output_tokens ?? obj.completion_tokens);
+ const total = Number(obj.totalTokens ?? obj.total_tokens);
+ if ([input, output, total].some(Number.isFinite)) return { inputTokens: Number.isFinite(input) ? input : undefined, outputTokens: Number.isFinite(output) ? output : undefined, totalTokens: Number.isFinite(total) ? total : (Number.isFinite(input) && Number.isFinite(output) ? input + output : undefined) };
+ for (const candidate of Object.values(obj)) { const nested = tokenUsage(candidate); if (nested) return nested; }
+ return null;
+}
+
+function run(command, args, cwd, timeoutMs = 180_000) {
+ const start = performance.now();
+ const result = spawnSync(command, args, { cwd, encoding: "utf8", timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024, env: process.env });
+ return { command, args, code: result.status, signal: result.signal, stdout: result.stdout || "", stderr: result.stderr || "", latencyMs: Math.round(performance.now() - start), error: result.error?.message };
+}
+
+function scoreRun(agent, raw, expected, requestedModel, usageFile = null) {
+ const parsed = jsonMaybe(raw.stdout.trim());
+ let usage = parsed ? tokenUsage(parsed) : null;
+ let model = parsed ? reportedModel(parsed) : null;
+ if (usageFile) {
+ try { const report = JSON.parse(readFileSync(usageFile, "utf8")); usage = tokenUsage(report) ?? usage; model = reportedModel(report) ?? model; } catch {}
+ }
+ const textPool = [raw.stdout, ...(parsed ? strings(parsed) : [])];
+ const matched = textPool.some((text) => text.includes(expected));
+ return {
+ agent, success: raw.code === 0 && matched, matched, exitCode: raw.code, signal: raw.signal,
+ latencyMs: raw.latencyMs, reportedModel: model, modelFamilyMatch: model ? sameModelFamily(model, requestedModel) : null,
+ usage, ...(raw.error ? { error: raw.error } : {}),
+ ...(raw.code !== 0 ? { stderrTail: raw.stderr.slice(-700) } : {}),
+ };
+}
+
+export function buildRunnerPlan({ prompt, model, cwd, usageFile }) {
+ return {
+ mso: { command: path.join(cwd, "bin/mso"), args: ["agent", "--oneshot", prompt, "--json"] },
+ hermes: { command: "hermes", args: ["--oneshot", prompt, "--model", `openai/${model}`, "--provider", "openai", "--usage-file", usageFile] },
+ openclaw: { command: "openclaw", args: ["agent", "--local", "--message", prompt, "--model", `openai/${model}`, "--json", "--session-id", `mso-bench-${Date.now()}`] },
+ };
+}
+
+async function main() {
+ const args = process.argv.slice(2), runIt = args.includes("--run"), json = args.includes("--json");
+ const mi = args.indexOf("--model"), model = mi >= 0 ? args[mi + 1] : "gpt-5.6-terra";
+ if (!model || model.startsWith("-")) throw new Error("--model requires a model family such as gpt-5.6-terra");
+ const scratch = path.join(os.homedir(), ".cache", "mso-benchmarks", `agent-compare-${Date.now()}-${randomBytes(3).toString("hex")}`);
+ mkdirSync(scratch, { recursive: true, mode: 0o700 });
+ const fixture = { nonce: randomBytes(6).toString("hex"), alpha: 17, beta: 29, gamma: 41 };
+ const file = path.join(scratch, "fixture.json"); writeFileSync(file, `${JSON.stringify(fixture)}\n`, { mode: 0o600 });
+ const prompt = benchmarkPrompt(file), expected = expectedAnswer(fixture), usageFile = path.join(scratch, "hermes-usage.json");
+ const cwd = process.cwd(), plan = buildRunnerPlan({ prompt, model, cwd, usageFile });
+ if (!runIt) {
+ const result = { run: false, model, scratchOnly: true, promptContract: "read file via tool; exact validated answer", runners: Object.fromEntries(Object.entries(plan).map(([name, row]) => [name, { command: path.basename(row.command), args: row.args.map((v) => v === prompt ? "<prompt>" : v) }])) };
+ console.log(json ? JSON.stringify(result, null, 2) : `MSO cross-agent benchmark plan\n model ${model}\n runners ${Object.keys(plan).join(", ")}\n add --run to execute the scratch-only read task`);
+ rmSync(scratch, { recursive: true, force: true }); return;
+ }
+ const rows = [];
+ try {
+ for (const [agent, cfg] of Object.entries(plan)) rows.push(scoreRun(agent, run(cfg.command, cfg.args, cwd), expected, model, agent === "hermes" ? usageFile : null));
+ const successful = rows.filter((row) => row.success);
+ const allModelEvidenceMatches = successful.every((row) => row.modelFamilyMatch !== false);
+ const result = {
+ run: true, model, scratchOnly: true, expectedMatchedAgents: successful.length,
+ comparable: successful.length >= 2 && allModelEvidenceMatches,
+ rows,
+ latencyOrder: successful.slice().sort((a, b) => a.latencyMs - b.latencyMs).map((row) => row.agent),
+ note: "Latency order is not an overall-agent ranking. Overall claims require multiple task classes and identical model/provider evidence.",
+ };
+ if (json) console.log(JSON.stringify(result, null, 2));
+ else {
+ console.log(`MSO cross-agent read-task benchmark · model=${model}`);
+ for (const row of rows) console.log(` ${row.success ? "PASS" : "FAIL"} ${row.agent.padEnd(8)} ${row.latencyMs}ms${row.reportedModel ? ` · ${row.reportedModel}` : ""}${row.usage?.totalTokens ? ` · ${row.usage.totalTokens} tokens` : ""}`);
+ console.log(` comparable=${result.comparable} · successful=${successful.length}/3`);
+ console.log(` ${result.note}`);
+ }
+ } finally { rmSync(scratch, { recursive: true, force: true }); }
+}
+if (import.meta.main) await main();
diff --git a/scripts/bench-agent-comparison.test.ts b/scripts/bench-agent-comparison.test.ts
new file mode 100644
index 00000000..811641b3
--- /dev/null
+++ b/scripts/bench-agent-comparison.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { benchmarkPrompt, buildRunnerPlan, expectedAnswer, sameModelFamily } from "./bench-agent-comparison.mjs";
+
+describe("cross-agent benchmark contract", () => {
+ it("requires the answer to depend on file-only values", () => {
+ const prompt = benchmarkPrompt("/tmp/private-fixture.json");
+ expect(prompt).toContain("filesystem/read tool");
+ expect(prompt).not.toContain("17");
+ expect(expectedAnswer({ nonce: "abc", alpha: 17, beta: 29, gamma: 41 })).toBe("BENCH:abc:162");
+ });
+ it("normalizes provider prefixes but not model families", () => {
+ expect(sameModelFamily("openai/gpt-5.6-terra", "gpt-5.6-terra")).toBe(true);
+ expect(sameModelFamily("openai-codex/gpt-5.6-terra", "gpt-5.6-terra")).toBe(true);
+ expect(sameModelFamily("openai/gpt-5.6-sol", "gpt-5.6-terra")).toBe(false);
+ });
+ it("keeps MSO autonomous approval read-only in the benchmark plan", () => {
+ const plan = buildRunnerPlan({ prompt: "p", model: "gpt-5.6-terra", cwd: "/repo", usageFile: "/tmp/u.json" });
+ expect(plan.mso.args).not.toContain("--approve-scope");
+ expect(plan.hermes.args).toContain("--usage-file");
+ expect(plan.openclaw.args).toContain("--local");
+ });
+});
diff --git a/scripts/bench-cognitive-runtime.mjs b/scripts/bench-cognitive-runtime.mjs
index 0e86b1f6..2c2cf925 100755
--- a/scripts/bench-cognitive-runtime.mjs
+++ b/scripts/bench-cognitive-runtime.mjs
@@ -2,6 +2,7 @@
import { execFileSync } from "node:child_process";
import { mock } from "bun:test";
import { selectToolsForTurn } from "./mso-agent-tool-router.mjs";
+import { runMemoryRetrievalBenchmark } from "./bench-memory-retrieval.mjs";
mock.module("server-only", () => ({}));
const { TOOLS } = await import("../lib/mcp/tools.ts");
@@ -19,6 +20,7 @@ const scenarios = [
{ id: "browser", prompt: "Check the Camoufox browser state and start it if it is stopped.", required: ["browser_status", "browser_power"] },
{ id: "screenshot", prompt: "Take a screenshot of the MSO desktop so I can inspect the UI.", required: ["screen_capture"] },
{ id: "memory", prompt: "Read my agent memory and remember this project convention for later sessions.", required: ["agent_memory_read", "agent_memory_remember"] },
+ { 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"] },
];
@@ -52,6 +54,7 @@ const hermes = hermesBaseline();
const avgSelectedBytes = Math.round(selectedBytes / scenarios.length);
const avgActiveTools = Math.round((selectedCount / scenarios.length) * 10) / 10;
const routingRecall = requiredTotal ? requiredHit / requiredTotal : 0;
+const memoryBenchmark = runMemoryRetrievalBenchmark();
const result = {
generatedAt: new Date().toISOString(),
providerNeutral: true,
@@ -64,6 +67,7 @@ const result = {
routingRecallPct: Math.round(routingRecall * 1000) / 10,
deterministic,
scenarios: rows,
+ memory: memoryBenchmark,
},
hermes: hermes ? {
version: version("hermes"), toolCount: hermes.tools?.count ?? null,
@@ -82,15 +86,20 @@ result.gates = {
deterministicRouting: deterministic,
activeSchemaSmallerThanFull: avgSelectedBytes < fullBytes,
beatsHermesToolSchemaBytes: Boolean(hermes?.tools?.json_bytes && avgSelectedBytes < hermes.tools.json_bytes),
+ memoryRetrieval100: memoryBenchmark.retrieval.accuracyPct === 100,
+ memoryTemporal100: memoryBenchmark.temporal.accuracyPct === 100,
+ memoryConflict100: memoryBenchmark.conflict.accuracyPct === 100,
+ memoryDeterministic: memoryBenchmark.deterministic,
};
result.passed = Object.values(result.gates).every(Boolean);
if (process.argv.includes("--json")) console.log(JSON.stringify(result, null, 2));
else {
- console.log("MSO Cognitive Runtime P0 benchmark");
+ console.log("MSO Cognitive Runtime benchmark");
console.log(` full catalog ${TOOLS.length} tools · ${fullBytes.toLocaleString()} schema bytes`);
console.log(` active per turn ${avgActiveTools} tools avg · ${avgSelectedBytes.toLocaleString()} bytes avg · ${result.mso.schemaReductionPct}% reduction`);
console.log(` routing ${result.mso.routingRecallPct}% required-tool recall · deterministic=${deterministic}`);
+ console.log(` typed memory ${memoryBenchmark.overallAccuracyPct}% retrieval/temporal/conflict · deterministic=${memoryBenchmark.deterministic}`);
if (hermes?.tools) console.log(` Hermes baseline ${hermes.tools.count} tools · ${Number(hermes.tools.json_bytes).toLocaleString()} schema bytes`);
else console.log(" Hermes baseline unavailable");
console.log(` OpenClaw ${result.openclaw.version || "unavailable"} · no comparable offline prompt-size probe`);
diff --git a/scripts/bench-memory-retrieval.mjs b/scripts/bench-memory-retrieval.mjs
new file mode 100644
index 00000000..3210232b
--- /dev/null
+++ b/scripts/bench-memory-retrieval.mjs
@@ -0,0 +1,85 @@
+#!/usr/bin/env bun
+import { queryMemoryLedger } from "../lib/agent/memory-query.ts";
+
+const T = {
+ jan: "2026-01-01T00:00:00.000Z", may: "2026-05-01T00:00:00.000Z",
+ jun: "2026-06-01T00:00:00.000Z", jul: "2026-07-01T00:00:00.000Z",
+};
+let seq = 0;
+function rec({ key, value, authority = "explicit", confidence = 1, observedAt = T.jan, validFrom = T.jan, ...rest }) {
+ seq += 1;
+ return {
+ id: `bench_${seq}`, document: "MEMORY.md", key, value, kind: "semantic", confidence,
+ sensitivity: "normal", validFrom, createdAt: observedAt,
+ provenance: { authority, channel: authority === "migration" ? "legacy" : "system", observedAt }, ...rest,
+ };
+}
+function ledger(records) { return { schemaVersion: 1, updatedAt: T.jul, records }; }
+
+const scenarios = [
+ {
+ id: "keyword-key", category: "retrieval", query: { query: "deployment rollback", at: T.jul },
+ ledger: ledger([rec({ key: "Deployment rollback policy", value: "Always verify before rollback" }), rec({ key: "UI preference", value: "Compact sidebar" })]),
+ expect: (r) => r.records[0]?.record.key === "Deployment rollback policy",
+ },
+ {
+ id: "keyword-value", category: "retrieval", query: { query: "SvelteKit runes", at: T.jul },
+ ledger: ledger([rec({ key: "Frontend rule", value: "Use SvelteKit 5 runes for reactive state" }), rec({ key: "Deploy rule", value: "Use safe build" })]),
+ expect: (r) => r.records[0]?.record.key === "Frontend rule",
+ },
+ {
+ id: "temporal-before", category: "temporal", query: { query: "office", at: T.may },
+ ledger: ledger([rec({ key: "Office", value: "Jakarta", supersededAt: T.jun, supersededBy: "new" }), rec({ key: "Office", value: "Singapore", validFrom: T.jun, observedAt: T.jun, supersedes: ["bench_old"] })]),
+ expect: (r) => r.records[0]?.record.value === "Jakarta",
+ },
+ {
+ id: "temporal-after", category: "temporal", query: { query: "office", at: T.jul },
+ ledger: ledger([rec({ key: "Office", value: "Jakarta", supersededAt: T.jun, supersededBy: "new" }), rec({ key: "Office", value: "Singapore", validFrom: T.jun, observedAt: T.jun })]),
+ expect: (r) => r.records[0]?.record.value === "Singapore",
+ },
+ {
+ id: "authority", category: "conflict", query: { query: "region", at: T.jul },
+ ledger: ledger([rec({ key: "Region", value: "Singapore", authority: "observed", confidence: 1, observedAt: T.jun }), rec({ key: "Region", value: "Jakarta", authority: "explicit", confidence: 0.5, observedAt: T.jan })]),
+ expect: (r) => r.records[0]?.record.value === "Jakarta" && r.records[0]?.conflicts.length === 1,
+ },
+ {
+ id: "confidence", category: "conflict", query: { query: "runtime", at: T.jul },
+ ledger: ledger([rec({ key: "Runtime", value: "Bun", authority: "observed", confidence: 0.9, observedAt: T.jan }), rec({ key: "Runtime", value: "Node", authority: "observed", confidence: 0.6, observedAt: T.jun })]),
+ expect: (r) => r.records[0]?.record.value === "Bun" && r.records[0]?.conflicts.length === 1,
+ },
+ {
+ id: "recency", category: "conflict", query: { query: "branch", at: T.jul },
+ ledger: ledger([rec({ key: "Branch", value: "develop", authority: "observed", confidence: 0.8, observedAt: T.jan }), rec({ key: "Branch", value: "main", authority: "observed", confidence: 0.8, observedAt: T.jun })]),
+ expect: (r) => r.records[0]?.record.value === "main" && r.records[0]?.conflicts.length === 1,
+ },
+ {
+ id: "retracted", category: "temporal", query: { query: "temporary", at: T.jul },
+ ledger: ledger([rec({ key: "Temporary", value: "obsolete", retractedAt: T.jun })]),
+ expect: (r) => r.records.length === 0,
+ },
+];
+
+export function runMemoryRetrievalBenchmark() {
+ const rows = scenarios.map((scenario) => {
+ const first = queryMemoryLedger(scenario.ledger, scenario.query);
+ const second = queryMemoryLedger(scenario.ledger, scenario.query);
+ return { id: scenario.id, category: scenario.category, pass: scenario.expect(first), deterministic: JSON.stringify(first) === JSON.stringify(second), top: first.records[0]?.record.value ?? null, conflicts: first.records[0]?.conflicts.length ?? 0 };
+ });
+ const byCategory = Object.fromEntries(["retrieval", "temporal", "conflict"].map((category) => {
+ const subset = rows.filter((row) => row.category === category);
+ return [category, { passed: subset.filter((row) => row.pass).length, total: subset.length, accuracyPct: subset.length ? Math.round(subset.filter((row) => row.pass).length / subset.length * 1000) / 10 : 100 }];
+ }));
+ return { scenarios: rows, deterministic: rows.every((row) => row.deterministic), overallAccuracyPct: Math.round(rows.filter((row) => row.pass).length / rows.length * 1000) / 10, ...byCategory };
+}
+
+if (import.meta.main) {
+ const result = runMemoryRetrievalBenchmark();
+ if (process.argv.includes("--json")) console.log(JSON.stringify(result, null, 2));
+ else {
+ console.log("MSO typed-memory retrieval benchmark");
+ console.log(` overall ${result.overallAccuracyPct}% · deterministic=${result.deterministic}`);
+ for (const category of ["retrieval", "temporal", "conflict"]) console.log(` ${category.padEnd(9)} ${result[category].accuracyPct}% (${result[category].passed}/${result[category].total})`);
+ for (const row of result.scenarios) console.log(` ${row.pass && row.deterministic ? "PASS" : "FAIL"} ${row.id}`);
+ }
+ if (!result.deterministic || result.overallAccuracyPct !== 100) process.exitCode = 1;
+}
diff --git a/scripts/bench-task-quality.mjs b/scripts/bench-task-quality.mjs
new file mode 100644
index 00000000..925670b1
--- /dev/null
+++ b/scripts/bench-task-quality.mjs
@@ -0,0 +1,87 @@
+#!/usr/bin/env bun
+import { summarizeWorkflowQuality, listLearnedRecipes } from "../lib/skills/memory.ts";
+
+function pct(n, d) { return d ? Math.round((n / d) * 1000) / 10 : 0; }
+
+export function aggregateTaskQuality(recipes = []) {
+ const totals = {
+ recipes: recipes.length, attempts: 0, successes: 0, failures: 0,
+ stepAttempts: 0, completedSteps: 0, failedSteps: 0, deniedSteps: 0,
+ rateLimitedSteps: 0, invalidArgSteps: 0, retries: 0, rollbackSignals: 0,
+ timedSteps: 0, totalStepDurationMs: 0,
+ };
+ let telemetryRecipes = 0;
+ for (const recipe of recipes) {
+ totals.attempts += Number(recipe.attempts) || 0;
+ totals.successes += Number(recipe.successes) || 0;
+ totals.failures += Number(recipe.failures) || 0;
+ const q = recipe.quality;
+ if (recipe.qualityVersion !== 1 || !q || typeof q !== "object") continue;
+ telemetryRecipes += 1;
+ for (const key of ["stepAttempts", "completedSteps", "failedSteps", "deniedSteps", "rateLimitedSteps", "invalidArgSteps", "retries", "rollbackSignals", "timedSteps", "totalStepDurationMs"]) totals[key] += Number(q[key]) || 0;
+ }
+ return {
+ ...totals,
+ telemetryRecipes,
+ telemetryCoveragePct: pct(telemetryRecipes, totals.recipes),
+ workflowSuccessPct: pct(totals.successes, totals.attempts),
+ toolCompletionPct: pct(totals.completedSteps, totals.stepAttempts),
+ toolFailurePct: pct(totals.failedSteps, totals.stepAttempts),
+ policyDenialPct: pct(totals.deniedSteps, totals.stepAttempts),
+ invalidArgPct: pct(totals.invalidArgSteps, totals.stepAttempts),
+ rateLimitPct: pct(totals.rateLimitedSteps, totals.stepAttempts),
+ retryPct: pct(totals.retries, totals.stepAttempts),
+ averageStepDurationMs: totals.timedSteps ? Math.round(totals.totalStepDurationMs / totals.timedSteps) : 0,
+ };
+}
+
+const now = "2026-09-01T00:00:00.000Z";
+const fixtureSteps = [
+ { id: "1", tool: "fs_read", state: "completed", durationMs: 10, ts: now },
+ { id: "2", tool: "fs_write", state: "invalid_args", ts: now },
+ { id: "3", tool: "fs_write", state: "failed", durationMs: 30, ts: now },
+ { id: "4", tool: "fs_write", state: "completed", durationMs: 20, ts: now },
+ { id: "5", tool: "exec_run", state: "completed", target: "restore backup", durationMs: 40, ts: now },
+];
+const expectedFixture = {
+ stepAttempts: 5, completedSteps: 3, failedSteps: 1, deniedSteps: 0, rateLimitedSteps: 0,
+ invalidArgSteps: 1, retries: 2, rollbackSignals: 1, timedSteps: 4, totalStepDurationMs: 100, averageStepDurationMs: 25,
+};
+
+export function runTaskQualityFixture() {
+ const quality = summarizeWorkflowQuality(fixtureSteps);
+ const deterministic = JSON.stringify(quality) === JSON.stringify(summarizeWorkflowQuality(fixtureSteps));
+ const exact = Object.entries(expectedFixture).every(([key, value]) => quality[key] === value);
+ return { exact, deterministic, quality, passed: exact && deterministic };
+}
+
+export const externalAgentContract = {
+ requiresSameModel: true,
+ sideEffectsAllowedOnlyInScratchFixture: true,
+ metrics: ["taskSuccess", "toolErrors", "invalidArgs", "retries", "policyDenials", "latencyMs", "inputTokens", "outputTokens", "estimatedCost"],
+ runners: {
+ mso: { comparable: true, invocation: "mso agent --oneshot <prompt> --json --approve-scope <scope>", safety: "read by default; write/exec require explicit approval scope" },
+ hermes: { comparable: true, invocation: "hermes --oneshot <prompt> --model <same-model> --usage-file <file>" },
+ openclaw: { comparable: true, invocation: "openclaw agent --local --message <prompt> --model <same-model> --json" },
+ },
+};
+
+async function main() {
+ const fixture = runTaskQualityFixture();
+ const live = process.argv.includes("--live") ? aggregateTaskQuality(await listLearnedRecipes({ ownerView: true })) : null;
+ const result = { generatedAt: new Date().toISOString(), fixture, live, externalAgentContract };
+ if (process.argv.includes("--json")) console.log(JSON.stringify(result, null, 2));
+ else {
+ console.log("MSO task-quality benchmark");
+ console.log(` fixture ${fixture.passed ? "PASS" : "FAIL"} · deterministic=${fixture.deterministic}`);
+ if (live) {
+ console.log(` learned recipes ${live.recipes} · telemetry coverage ${live.telemetryCoveragePct}%`);
+ console.log(` workflow success ${live.workflowSuccessPct}% (${live.successes}/${live.attempts})`);
+ console.log(` tool completion ${live.toolCompletionPct}% · failure ${live.toolFailurePct}% · invalid args ${live.invalidArgPct}% · retries ${live.retryPct}%`);
+ console.log(` avg tool latency ${live.averageStepDurationMs}ms across ${live.timedSteps} timed steps`);
+ }
+ console.log(" cross-agent contract ready; all runners expose non-interactive agent turns, but ranking still requires the same model + scratch-only scenarios");
+ }
+ if (!fixture.passed) process.exitCode = 1;
+}
+if (import.meta.main) await main();
diff --git a/scripts/bench-task-quality.test.ts b/scripts/bench-task-quality.test.ts
new file mode 100644
index 00000000..f28ae6e0
--- /dev/null
+++ b/scripts/bench-task-quality.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it, vi } from "vitest";
+vi.mock("server-only", () => ({}));
+const { aggregateTaskQuality, externalAgentContract, runTaskQualityFixture } = await import("./bench-task-quality.mjs");
+
+describe("task quality benchmark", () => {
+ it("scores the deterministic telemetry fixture exactly", () => {
+ expect(runTaskQualityFixture()).toMatchObject({ passed: true, deterministic: true, quality: { retries: 2, invalidArgSteps: 1, rollbackSignals: 1, averageStepDurationMs: 25 } });
+ });
+ it("aggregates recipe outcomes and telemetry without inventing coverage for legacy recipes", () => {
+ const result = aggregateTaskQuality([
+ { attempts: 3, successes: 2, failures: 1, qualityVersion: 1, quality: { stepAttempts: 10, completedSteps: 8, failedSteps: 1, deniedSteps: 0, rateLimitedSteps: 0, invalidArgSteps: 1, retries: 2, rollbackSignals: 1, timedSteps: 4, totalStepDurationMs: 80, averageStepDurationMs: 20 } },
+ { attempts: 1, successes: 1, failures: 0 },
+ ]);
+ expect(result).toMatchObject({ recipes: 2, telemetryRecipes: 1, telemetryCoveragePct: 50, workflowSuccessPct: 75, toolCompletionPct: 80, invalidArgPct: 10, retryPct: 20, averageStepDurationMs: 20 });
+ });
+ it("requires the same model and exposes non-interactive runners for all agents", () => {
+ expect(externalAgentContract.requiresSameModel).toBe(true);
+ expect(externalAgentContract.runners.mso.comparable).toBe(true);
+ expect(externalAgentContract.runners.hermes.comparable).toBe(true);
+ expect(externalAgentContract.runners.openclaw.comparable).toBe(true);
+ });
+});
diff --git a/scripts/mso-agent-oneshot.mjs b/scripts/mso-agent-oneshot.mjs
new file mode 100644
index 00000000..718056d8
--- /dev/null
+++ b/scripts/mso-agent-oneshot.mjs
@@ -0,0 +1,29 @@
+const SCOPE_RANK = { read: 0, write: 1, exec: 2 };
+
+export function parseOneShot(argv = []) {
+ let index = argv.indexOf("--oneshot"); if (index < 0) index = argv.indexOf("-z");
+ if (index < 0) return null;
+ const prompt = argv[index + 1];
+ if (!prompt || prompt.startsWith("-")) throw new Error("--oneshot requires a prompt argument");
+ let approvalScope = "read";
+ const scopeIndex = argv.indexOf("--approve-scope");
+ if (scopeIndex >= 0) {
+ approvalScope = argv[scopeIndex + 1];
+ if (!["read", "write", "exec"].includes(approvalScope)) throw new Error("--approve-scope must be read, write, or exec");
+ }
+ return { prompt, json: argv.includes("--json"), approvalScope };
+}
+
+export function oneShotApproves(approvalScope, toolScope) {
+ return Number.isInteger(SCOPE_RANK[approvalScope]) && Number.isInteger(SCOPE_RANK[toolScope]) && SCOPE_RANK[approvalScope] >= SCOPE_RANK[toolScope];
+}
+
+export function oneShotHelp() {
+ return [
+ "Usage: mso agent [--continue|--resume <query>]",
+ " mso agent --oneshot <prompt> [--json] [--approve-scope read|write|exec]",
+ "",
+ "One-shot runs the same autonomous MSO Agent tool loop without a TTY.",
+ "Default approval scope is read; write/exec require an explicit --approve-scope.",
+ ].join("\n");
+}
diff --git a/scripts/mso-agent-oneshot.test.ts b/scripts/mso-agent-oneshot.test.ts
new file mode 100644
index 00000000..208f756b
--- /dev/null
+++ b/scripts/mso-agent-oneshot.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { oneShotApproves, oneShotHelp, parseOneShot } from "./mso-agent-oneshot.mjs";
+
+describe("MSO Agent one-shot CLI contract", () => {
+ it("defaults autonomous runs to read-only approvals", () => {
+ expect(parseOneShot(["--oneshot", "inspect health", "--json"])).toEqual({ prompt: "inspect health", json: true, approvalScope: "read" });
+ expect(oneShotApproves("read", "read")).toBe(true);
+ expect(oneShotApproves("read", "write")).toBe(false);
+ expect(oneShotApproves("read", "exec")).toBe(false);
+ });
+ it("requires an explicit scope before autonomous write/exec calls", () => {
+ expect(parseOneShot(["-z", "run fixture", "--approve-scope", "write"])?.approvalScope).toBe("write");
+ expect(oneShotApproves("write", "write")).toBe(true);
+ expect(oneShotApproves("write", "exec")).toBe(false);
+ expect(oneShotApproves("exec", "exec")).toBe(true);
+ expect(() => parseOneShot(["-z", "x", "--approve-scope", "root"])).toThrow(/read, write, or exec/);
+ });
+ it("documents that one-shot uses the autonomous agent loop", () => {
+ expect(oneShotHelp()).toContain("same autonomous MSO Agent tool loop");
+ expect(oneShotHelp()).toContain("Default approval scope is read");
+ });
+});
diff --git a/scripts/mso-agent-runtime.mjs b/scripts/mso-agent-runtime.mjs
index f3f6f6dc..ff751eb6 100644
--- a/scripts/mso-agent-runtime.mjs
+++ b/scripts/mso-agent-runtime.mjs
@@ -129,7 +129,7 @@ function toolForModel(tool) {
* @param {any} [skillContext]
* @param {AbortSignal | undefined} [signal]
*/
-export async function streamTurn(messages, tools, agentSession, skillContext = null, signal = undefined, contextWindow = undefined) {
+export async function streamTurn(messages, tools, agentSession, skillContext = null, signal = undefined, contextWindow = undefined, output = process.stdout) {
const projected = projectHistoryForModel(messages, contextWindow);
const activeTools = selectToolsForTurn(tools, projected.messages, skillContext);
const res = await fetch(`${BASE}/api/assistant`, {
@@ -159,7 +159,7 @@ export async function streamTurn(messages, tools, agentSession, skillContext = n
}
if (!data) continue;
if (event === "delta") {
- const chunk = JSON.parse(data); text += chunk; process.stdout.write(chunk);
+ const chunk = JSON.parse(data); text += chunk; output?.write?.(chunk);
} else if (event === "tool_use") toolUses.push(JSON.parse(data));
else if (event === "done") {
const done = JSON.parse(data);
@@ -169,6 +169,6 @@ export async function streamTurn(messages, tools, agentSession, skillContext = n
else if (event === "error") throw new Error(JSON.parse(data));
}
}
- if (text && !text.endsWith("\n")) process.stdout.write("\n");
+ if (text && !text.endsWith("\n")) output?.write?.("\n");
return { text, toolUses, stopReason, usage };
}
diff --git a/scripts/mso-agent-tool-router.mjs b/scripts/mso-agent-tool-router.mjs
index e2ee9ae0..2a541e85 100644
--- a/scripts/mso-agent-tool-router.mjs
+++ b/scripts/mso-agent-tool-router.mjs
@@ -15,7 +15,8 @@ const DEPENDENCIES = new Map([
const ALIASES = new Map([
["logs", ["log", "journal", "error", "crash", "down"]],
- ["processes", ["process", "cpu", "memory", "ram", "load"]],
+ ["processes", ["process", "cpu", "ram", "load"]],
+ ["memory", ["memory", "remember", "recall", "forget", "fact", "preference", "provenance", "conflict", "temporal"]],
["stats", ["health", "cpu", "memory", "ram", "disk", "uptime", "server", "vps"]],
["projects", ["project", "repo", "repository", "checkout", "workspace"]],
["skills", ["skill", "capability", "recipe", "workflow", "how"]],
diff --git a/scripts/mso-agent.mjs b/scripts/mso-agent.mjs
index 66cdc223..754ac451 100644
--- a/scripts/mso-agent.mjs
+++ b/scripts/mso-agent.mjs
@@ -10,8 +10,9 @@ import { persistSession, resumeArg, startupSession, syncPromptHistory } from "./
import { C, api, printBanner, state, streamTurn } from "./mso-agent-runtime.mjs";
import { handleSlash } from "./mso-agent-commands.mjs";
import { approvesTool, nextPermissionMode } from "./mso-agent-permissions.mjs";
+import { oneShotApproves, oneShotHelp, parseOneShot } from "./mso-agent-oneshot.mjs";
-async function executeTool(rl, tool, call, agentSession, permission = "ask", signal = undefined, onInterrupt = null) {
+async function executeTool(rl, tool, call, agentSession, permission = "ask", signal = undefined, onInterrupt = null, options = {}) {
if (!tool) return { ok: false, result: `unknown tool requested by model: ${call.name}` };
const needsApprovalDigest = tool.scope !== "read";
let approval = null;
@@ -19,20 +20,26 @@ async function executeTool(rl, tool, call, agentSession, permission = "ask", sig
try { approval = canonicalAgentApproval(tool.name, call.input || {}); }
catch (error) { return { ok: false, result: `cannot safely approve tool call: ${error instanceof Error ? error.message : String(error)}` }; }
}
- let approved = approvesTool(permission, tool.scope);
+ let approved = options.approvalScope
+ ? oneShotApproves(options.approvalScope, tool.scope)
+ : approvesTool(permission, tool.scope);
if (!approved) {
+ // Autonomous one-shot mode must never fall back to an interactive prompt.
+ // Its default approval scope is read, so write/exec fail closed unless the
+ // caller explicitly chose --approve-scope write|exec.
+ if (options.approvalScope) return { ok: false, result: "denied by user" };
console.log(`${C.warn}${C.bold}[${tool.scope.toUpperCase()}] exact tool call${C.reset}`);
console.log(approval.display);
console.log(`${C.dim}sha256 ${approval.digest} · ${approval.bytes} bytes${C.reset}`);
const answer = String(await rl.question(" allow this exact call? [y/N]: ", { history: false, onCancel: onInterrupt }) ?? "").trim().toLowerCase();
if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error("turn interrupted");
if (answer === "y" || answer === "yes") approved = true;
- } else if (needsApprovalDigest) {
+ } else if (needsApprovalDigest && !options.quiet && !options.approvalScope) {
const mode = permission === "yolo" ? "YOLO" : "AUTO-WRITE";
console.log(`${C.c}${C.bold}[${tool.scope.toUpperCase()} · ${mode}]${C.reset} ${tool.name}`);
}
if (!approved) return { ok: false, result: "denied by user" };
- process.stdout.write(`${C.dim} ↳ ${tool.name}…${C.reset}`);
+ if (!options.quiet) process.stdout.write(`${C.dim} ↳ ${tool.name}…${C.reset}`);
try {
const input = approval ? approval.payload.input : (call.input || {});
const out = await api("/api/v1/agent-tools", {
@@ -45,36 +52,42 @@ async function executeTool(rl, tool, call, agentSession, permission = "ask", sig
}),
signal,
});
- process.stdout.write(`\r${C.c} ✓ ${tool.name}${C.reset}\n`);
+ if (!options.quiet) process.stdout.write(`\r${C.c} ✓ ${tool.name}${C.reset}\n`);
if (!out.ok) return { ok: false, result: out.result || "tool failed" };
return { ok: true, result: String(out.result ?? "ok") };
} catch (error) {
if (signal?.aborted || isAbortError(error)) throw error;
- process.stdout.write(`\r${C.err} ✗ ${tool.name}${C.reset}\n`);
+ if (!options.quiet) process.stdout.write(`\r${C.err} ✗ ${tool.name}${C.reset}\n`);
return { ok: false, result: (error instanceof Error ? error.message : String(error)).slice(0, 2000) };
}
}
-async function agentRound(rl, session, skillContext = null, signal = undefined, onInterrupt = null) {
+async function agentRound(rl, session, skillContext = null, signal = undefined, onInterrupt = null, options = {}) {
const startedAt = Date.now();
const historyCheckpoint = Math.max(0, session.history.length - 1);
+ const calls = [];
+ let finalText = "", rounds = 0;
beginSkillInvocation(session, skillContext, C);
try {
for (let turn = 0; turn < 10; turn++) {
- const result = await streamTurn(session.history, session.state.tools, session.agentSession, skillContext, signal, session.state.modelMeta?.context); if (skillContext) session.lastInvokedSkill = skillContext;
+ rounds = turn + 1;
+ const result = await streamTurn(session.history, session.state.tools, session.agentSession, skillContext, signal, session.state.modelMeta?.context, options.quiet ? null : process.stdout); if (skillContext) session.lastInvokedSkill = skillContext;
+ finalText = result.text;
session.usage = addUsage(session.usage, result.usage);
session.lastElapsedMs = Date.now() - startedAt;
session.history.push({ role: "assistant", text: result.text, toolUses: result.toolUses });
- if (!result.toolUses.length) return;
+ if (!result.toolUses.length) return { text: finalText, calls, rounds, usage: session.usage, elapsedMs: session.lastElapsedMs };
const results = [];
for (const call of result.toolUses) {
const tool = session.state.tools.find((row) => row.name === call.name);
- const outcome = await executeTool(rl, tool, call, session.agentSession, session.permission, signal, onInterrupt);
+ const outcome = await executeTool(rl, tool, call, session.agentSession, session.permission, signal, onInterrupt, options);
+ calls.push({ name: call.name, ok: outcome.ok });
results.push({ id: call.id, content: outcome.result, isError: !outcome.ok });
}
session.history.push({ role: "tool", results });
}
- console.log(`${C.warn}turn limit reached; ask to continue if needed.${C.reset}`);
+ if (!options.quiet) console.log(`${C.warn}turn limit reached; ask to continue if needed.${C.reset}`);
+ return { text: finalText, calls, rounds, usage: session.usage, elapsedMs: session.lastElapsedMs, turnLimitReached: true };
} catch (error) {
if (signal?.aborted || isAbortError(error)) session.history.splice(historyCheckpoint);
throw error;
@@ -98,12 +111,41 @@ async function runInteractiveRound(rl, session, skillContext, interrupts) {
}
+async function runOneShot(opts) {
+ const requested = resumeArg(process.argv.slice(2));
+ const [s, agentSession] = await Promise.all([state(), startupSession(requested)]);
+ if (!agentSession || agentSession.source !== "cli") throw new Error("could not establish a CLI MSO Agent session");
+ const session = {
+ state: s, agentSession, history: Array.isArray(agentSession.history) ? agentSession.history : [],
+ pendingSkill: null, activeSkill: null, lastInvokedSkill: null,
+ titleOverride: requested ? (agentSession.title || null) : null,
+ usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, lastElapsedMs: 0, statusBar: false,
+ permission: "ask",
+ };
+ session.history.push({ role: "user", text: opts.prompt });
+ const result = await agentRound(null, session, null, undefined, null, { quiet: true, approvalScope: opts.approvalScope });
+ await persistSession(session);
+ const payload = {
+ ok: true, sessionId: session.agentSession.id,
+ model: `${s.config?.provider || ""}/${s.config?.model || ""}`.replace(/^\//, ""),
+ approvalScope: opts.approvalScope, text: result?.text || "", rounds: result?.rounds || 0,
+ toolCalls: result?.calls || [], usage: result?.usage || session.usage, elapsedMs: result?.elapsedMs || session.lastElapsedMs,
+ ...(result?.turnLimitReached ? { turnLimitReached: true } : {}),
+ };
+ if (opts.json) process.stdout.write(`${JSON.stringify(payload)}\n`);
+ else process.stdout.write(`${payload.text}${payload.text.endsWith("\n") || !payload.text ? "" : "\n"}`);
+}
+
+
async function main() {
+ const argv = process.argv.slice(2);
+ if (argv.includes("--help") || argv.includes("-h")) { process.stdout.write(`${oneShotHelp()}\n`); return; }
+ const oneShot = parseOneShot(argv);
+ if (oneShot) return runOneShot(oneShot);
if (!process.stdin.isTTY || !process.stdout.isTTY) {
- console.error("mso agent needs an interactive terminal. For one-shot automation use: mso ai <prompt>");
+ console.error("mso agent needs an interactive terminal. For autonomous one-shot use: mso agent --oneshot \"<prompt>\" [--json]");
process.exit(2);
}
- const argv = process.argv.slice(2);
const requested = resumeArg(argv);
const forcedPermission = argv.some((arg) => ["--yolo", "-yolo", "-y"].includes(arg)) ? "yolo" : "ask";
const [s, agentSession] = await Promise.all([
diff --git a/scripts/mso-cli-agent.sh b/scripts/mso-cli-agent.sh
index 76458563..661acddb 100755
--- a/scripts/mso-cli-agent.sh
+++ b/scripts/mso-cli-agent.sh
@@ -408,8 +408,12 @@ process.stdout.write(JSON.stringify({ id, values }));
}
run_agent() {
- local cfg
- tty_ok || die "interactive agent needs a terminal; use: mso ai <prompt> for a one-shot request"
+ local cfg oneshot=0 arg MSO_CLI_QUIET=0
+ for arg in "$@"; do
+ [ "$arg" = "--json" ] && MSO_CLI_QUIET=1
+ [ "$arg" = "--oneshot" ] || [ "$arg" = "-z" ] || continue; oneshot=1
+ done
+ [ "$oneshot" = "1" ] || tty_ok || die "interactive agent needs a terminal; use: mso agent --oneshot \"<prompt>\" [--json]"
ensure_local_cli_device
ensure_onboard_runtime
jget "/api/auth/me" >/dev/null