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(cognitive): add bounded replay and candidate reuse

Rahmanfa0af264efef
diff --git a/.env.example b/.env.example
index 6f6c616c..11ff9cca 100644
--- a/.env.example
+++ b/.env.example
@@ -364,6 +364,9 @@ OS_MCP_MAX_SCOPE=exec
# (0600). Embeddings are deterministic and local — no API key, model download or
# network call is required.
# OS_SKILL_MEMORY_STORE=/home/you/.mso/skill-memory.json
+# Optional private owner-local cache for the bounded project path/skill candidate index.
+# Defaults to ~/.mso/cache/candidate-index-v1.
+# MSO_CANDIDATE_INDEX_DIR=/home/you/.mso/cache/candidate-index-v1
# Optional live MCP activity log shown in Assistant → MCP. Default
# ~/.mso/mcp-activity.log. This is separate from the forensic audit trail and
# records tool lifecycle (started/completed/failed), including bounded reads.
diff --git a/app/api/v1/projects/candidates/route.test.ts b/app/api/v1/projects/candidates/route.test.ts
new file mode 100644
index 00000000..b36e4c9b
--- /dev/null
+++ b/app/api/v1/projects/candidates/route.test.ts
@@ -0,0 +1,86 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+ session: vi.fn(),
+ limited: vi.fn(),
+ resolve: vi.fn(),
+ inspect: vi.fn(),
+ revision: vi.fn(),
+ search: vi.fn(),
+}));
+
+vi.mock("@/lib/auth/require-session", () => ({ getSessionContext: mocks.session }));
+vi.mock("@/lib/host/limits-api", () => ({ rateLimited: mocks.limited }));
+vi.mock("@/lib/host/projects-api", () => ({
+ resolveProjectHint: mocks.resolve,
+ inspectProject: mocks.inspect,
+}));
+vi.mock("@/lib/host/project-candidate-index", () => ({
+ projectCandidateRevision: mocks.revision,
+ searchProjectCandidateIndex: mocks.search,
+}));
+
+const { GET } = await import("./route");
+
+describe("GET /api/v1/projects/candidates", () => {
+ beforeEach(() => {
+ mocks.session.mockReset().mockResolvedValue({
+ role: "viewer",
+ session: { device_id: "device-1" },
+ });
+ mocks.limited.mockReset().mockReturnValue(false);
+ mocks.resolve.mockReset().mockResolvedValue({
+ id: "root/mso",
+ name: "mso",
+ path: "/srv/mso",
+ });
+ mocks.inspect.mockReset().mockResolvedValue({ git: { head: { sha: "abc" }, changes: [] } });
+ mocks.revision.mockReset().mockReturnValue("revision-1");
+ mocks.search.mockReset().mockResolvedValue({
+ revision: "revision-1",
+ rebuilt: false,
+ reusedSeed: false,
+ indexedEntries: 3,
+ candidates: [{ path: "lib/workflow/replay.ts", kind: "path", size: 100, score: 1 }],
+ matches: [{ path: "lib/workflow/replay.ts", line: 1, preview: "bounded replay" }],
+ truncated: false,
+ truncationReasons: [],
+ });
+ });
+
+ it("requires an authenticated session", async () => {
+ mocks.session.mockResolvedValue(null);
+ const res = await GET(new Request("http://mso.test/api/v1/projects/candidates?project=mso&q=replay"));
+ expect(res.status).toBe(401);
+ expect(mocks.search).not.toHaveBeenCalled();
+ });
+
+ it("shares the 30/min read bound with the MCP capability", async () => {
+ mocks.limited.mockReturnValue(true);
+ const res = await GET(new Request("http://mso.test/api/v1/projects/candidates?project=mso&q=replay"));
+ expect(res.status).toBe(429);
+ expect(mocks.limited).toHaveBeenCalledWith("projects.candidates:device-1", 30, 60_000);
+ expect(mocks.search).not.toHaveBeenCalled();
+ });
+
+ it("resolves the project and delegates to the same bounded candidate primitive", async () => {
+ const res = await GET(new Request(
+ "http://mso.test/api/v1/projects/candidates?project=root%2Fmso&q=bounded+replay&limit=999&cursor=next",
+ ));
+ expect(res.status).toBe(200);
+ expect(mocks.resolve).toHaveBeenCalledWith("root/mso");
+ expect(mocks.revision).toHaveBeenCalled();
+ expect(mocks.search).toHaveBeenCalledWith({
+ projectPath: "/srv/mso",
+ query: "bounded replay",
+ revision: "revision-1",
+ limit: 40,
+ cursor: "next",
+ });
+ await expect(res.json()).resolves.toMatchObject({
+ project: { id: "root/mso", name: "mso", path: "/srv/mso" },
+ candidates: [{ path: "lib/workflow/replay.ts" }],
+ });
+ expect(res.headers.get("cache-control")).toBe("no-store");
+ });
+});
diff --git a/app/api/v1/projects/candidates/route.ts b/app/api/v1/projects/candidates/route.ts
new file mode 100644
index 00000000..dde29e78
--- /dev/null
+++ b/app/api/v1/projects/candidates/route.ts
@@ -0,0 +1,46 @@
+import { NextResponse } from "next/server";
+import { getSessionContext } from "@/lib/auth/require-session";
+import { rateLimited } from "@/lib/host/limits-api";
+import { projectCandidateRevision, searchProjectCandidateIndex } from "@/lib/host/project-candidate-index";
+import { inspectProject, resolveProjectHint } from "@/lib/host/projects-api";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export async function GET(req: Request) {
+ const context = await getSessionContext();
+ if (!context?.session.device_id) {
+ return NextResponse.json({ error: "unauthorized" }, { status: 401 });
+ }
+ if (rateLimited(`projects.candidates:${context.session.device_id}`, 30, 60_000)) {
+ return NextResponse.json({ error: "rate_limited" }, { status: 429 });
+ }
+
+ const q = new URL(req.url).searchParams;
+ const projectHint = (q.get("project") ?? "").trim();
+ const query = (q.get("q") ?? "").trim();
+ const cursor = (q.get("cursor") ?? "").trim() || undefined;
+ const requestedLimit = Number(q.get("limit") ?? "16");
+ const limit = Number.isFinite(requestedLimit)
+ ? Math.min(Math.max(Math.round(requestedLimit), 1), 40)
+ : 16;
+ if (!projectHint || !query) {
+ return NextResponse.json({ error: "project_and_query_required" }, { status: 400 });
+ }
+
+ const project = await resolveProjectHint(projectHint).catch(() => null);
+ if (!project) return NextResponse.json({ error: "project_not_found" }, { status: 404 });
+
+ const repository = await inspectProject(project, { includeGitStatus: true }).catch(() => undefined);
+ const result = await searchProjectCandidateIndex({
+ projectPath: project.path,
+ query,
+ revision: projectCandidateRevision(repository),
+ limit,
+ cursor,
+ });
+ return NextResponse.json(
+ { project: { id: project.id, name: project.name, path: project.path }, ...result },
+ { headers: { "Cache-Control": "no-store" } },
+ );
+}
diff --git a/bin/mso b/bin/mso
index d866d14b..2a722749 100755
--- a/bin/mso
+++ b/bin/mso
@@ -29,6 +29,7 @@
# zip <base> <name…> Zip entries of <base> to stdout (redirect it to a .zip)
# upload <local> <dst> Upload a local file into <dst> (the dir must already exist)
# search <q> [root] Find DIRECTORIES whose name matches (not contents; use exec+grep)
+# project-candidates <project> <query> [limit] [cursor] Search bounded project path/content candidates
# usage [path] Disk usage
#
# Host
diff --git a/docs/AGENT-BOOTSTRAP.md b/docs/AGENT-BOOTSTRAP.md
index 74a43b70..80b43083 100644
--- a/docs/AGENT-BOOTSTRAP.md
+++ b/docs/AGENT-BOOTSTRAP.md
@@ -41,6 +41,20 @@ Copy this. Do not skip to `exec_run`.
Then verify independently and call `workflow_finish` with the same id (or
`workflow_cancel` to abandon). A recipe is guidance, not permission.
+## Context-economy behavior
+
+The sequence above is unchanged. `workflow_start` now performs provider-neutral bounded
+replay/candidate reuse internally when a compatible learned pool exists; an agent does
+**not** add another bootstrap call just to use it. For explicit repo discovery,
+`project_candidate_search` is a read-only two-stage path/content search with cursors and
+truncation. Replay handles point back to existing bounded read/job/artifact surfaces
+instead of embedding old tool dumps in the next prompt.
+
+Authorization is deliberately outside the reuse layer: current identity, project
+resolution, scope, confirmation, and host policy are checked again on every call. Full
+design and parity details are in
+[`COGNITIVE-RUNTIME.md#bounded-replay-and-sparse-candidate-reuse`](./COGNITIVE-RUNTIME.md#bounded-replay-and-sparse-candidate-reuse).
+
## Hard constraints
- Do **not** hide callable tools from ChatGPT `tools/list` to compress context.
@@ -79,15 +93,13 @@ Legend: **Reach** = how this surface performs the capability. **Gap** = accident
| Doctor / health | `mso doctor`, `sys_stats`, `vps_status`, `infra_provider_doctor` | `vps_status`, `sys_stats`, `infra_provider_doctor` | same | Monitor app + `sys.stats` |
| Deploys | `mso-deploy` skill / `bun run ship` / Dokploy tools | same tools + skill | same; Page is not a deploy button | owner UI / CLI; no extra Alfa deploy primitive (**Intentional**) |
-Presentation differences (ChatGPT 56-character descriptions, terminal pack routing,
+Presentation differences (compact ChatGPT descriptions, terminal pack routing,
Alfa `dot.case` names) are **not** capability holes.
## Follow-ups (not in this change)
These remain designed-not-shipped. They must not block agents from the sequence above.
-- Host file index / replay-by-handle for DRY results across turns.
-- Deeper ChatGPT context compression that does **not** hide callable tools.
- Closing an Alfa in-shell identity boundary only when a shared principal exists.
## Related contracts
diff --git a/docs/CLI.md b/docs/CLI.md
index fb11f2d3..d33e1509 100644
--- a/docs/CLI.md
+++ b/docs/CLI.md
@@ -69,6 +69,7 @@ Commands:
zip <base> <name…> Zip entries of <base> to stdout (redirect it to a .zip)
upload <local> <dst> Upload a local file into <dst> (the dir must already exist)
search <q> [root] Find DIRECTORIES whose name matches (not contents; use exec+grep)
+ project-candidates <project> <query> [limit] [cursor] Search bounded project path/content candidates
usage [path] Disk usage
Host
diff --git a/docs/COGNITIVE-RUNTIME.md b/docs/COGNITIVE-RUNTIME.md
index b2ec55f5..9ba2f677 100644
--- a/docs/COGNITIVE-RUNTIME.md
+++ b/docs/COGNITIVE-RUNTIME.md
@@ -89,6 +89,44 @@ Environment overrides are documented in `.env.example`:
`OS_AGENT_SESSION_COMPACT_TOKENS`, `OS_AGENT_SESSION_RECENT_TOKENS`,
`OS_AGENT_SESSION_ARCHIVE_DIR`, and `OS_AGENT_SESSION_ARCHIVE_DAYS`.
+## Bounded replay and sparse candidate reuse
+
+MSO applies input-heavy-agent lessons at the **control-plane** boundary only. The naming is
+an analogy to DeepSeek-V4.1-Flash (arXiv:2609.19969), not a runtime dependency. There is no
+vendor runtime, model layer, KV implementation, precision mode, or architecture-specific
+dependency in this design.
+
+- **Bounded Replay** — workflow steps persist only sanitized execution metadata plus up to
+ six durable replay handles (`path` + optional SHA-256, job id, artifact id, or cursor).
+ Raw tool bodies/stdout are not copied into learned recipes. `workflow_status` exposes at
+ most the recent step window and four handles per step; callers re-read explicitly with
+ `read_pipeline`, `exec_job_status`, `session_artifacts`, or the candidate-search cursor.
+ Cold session/archive content stays cold unless explicitly requested.
+- **Owner-local candidate index** — `project_candidate_search` is a `read`-scoped,
+ bounded two-stage lookup. The private cache lives under
+ `~/.mso/cache/candidate-index-v1` (or `MSO_CANDIDATE_INDEX_DIR`), stores path/skill
+ metadata rather than a repository mirror, excludes Git/dependency/build/credential
+ paths and symlinks, and invalidates on the supplied repository revision or a bounded
+ directory-structure fingerprint. Stage two reads content only inside the ranked page.
+ Pagination is cursored and truncation is explicit.
+- **Candidate-pool reuse** — successful recipes may carry only redacted path, skill-id,
+ connection-id, and MCP-alias candidates. A later `workflow_start` for the same recipe
+ owner, compatible scope, and exact project may validate/reuse that pool instead of
+ repeating global skill/path discovery. Reuse never supplies credentials and never
+ bypasses current identity, project resolution, tool visibility, scope checks,
+ confirmations, rate limits, or host guards.
+- **Descriptor flattening** — ChatGPT still receives every callable MSO tool in
+ `tools/list`. Its compact profile removes repeated property-description prose while
+ preserving names, types, required fields, enums, limits, security metadata and output
+ contracts. `workflow_start` also returns bounded `activePack` orientation metadata;
+ that is a hint, not an allowlist.
+
+These primitives are shared below presentation adapters. Terminal `mso`, generic MCP
+clients (Cursor/Grok/Claude/etc.), ChatGPT, and Alfa-via-`mso`-gateway therefore retain
+the same maximum host capabilities and policy boundaries; only schema/presentation cost
+differs. The bootstrap sequence remains unchanged; see
+[`AGENT-BOOTSTRAP.md`](./AGENT-BOOTSTRAP.md).
+
## Deferred capability selection
The external MCP server keeps a stable, complete scope-filtered catalog for standards interoperability.
diff --git a/docs/generated/MCP-CATALOG.md b/docs/generated/MCP-CATALOG.md
index fbe76fee..56718f3e 100644
--- a/docs/generated/MCP-CATALOG.md
+++ b/docs/generated/MCP-CATALOG.md
@@ -4,21 +4,21 @@
## Full MSO catalog
-<!-- mcp-toolset: server=1.15.1 version=2026.09.19.2 tools=111 read=54 write=35 exec=22 -->
+<!-- mcp-toolset: server=1.15.1 version=2026.09.19.3 tools=112 read=55 write=35 exec=22 -->
| Fact | Current source value |
|---|---:|
| MCP server | `1.15.1` |
-| Toolset | `2026.09.19.2` |
-| Toolset changed at | `2026-09-19T16:47:44+07:00` |
-| Transport tools | **113** |
-| Model/operator tools | **111** |
-| Read | **54** |
+| Toolset | `2026.09.19.3` |
+| Toolset changed at | `2026-09-19T19:11:32+07:00` |
+| Transport tools | **114** |
+| Model/operator tools | **112** |
+| Read | **55** |
| Write | **35** |
| Exec | **22** |
| App-only bridges | **2** |
-### Read (54)
+### Read (55)
- `a2a_agent_discover`
- `a2a_agents_list`
@@ -54,6 +54,7 @@
- `mso_surface_apps_list`
- `organization_chart`
- `project_agent_status`
+- `project_candidate_search`
- `project_capabilities`
- `project_changes_list`
- `project_diff`
@@ -145,20 +146,20 @@
## ChatGPT model profile
-<!-- mcp-chatgpt-profile: server=1.15.1 version=2026.09.19.2 tools=111 read=54 write=35 exec=22 app-only=2 total=113 -->
+<!-- mcp-chatgpt-profile: server=1.15.1 version=2026.09.19.3 tools=112 read=55 write=35 exec=22 app-only=2 total=114 -->
The ChatGPT profile automatically projects the complete MSO-owned generic model/operator catalog. OAuth scope is still enforced independently; app-only compatibility bridges stay app-only, and project-owned MCP tool names remain dynamic data behind the generic project bridge.
| Fact | Current source value |
|---|---:|
-| ChatGPT transport tools | **113** |
-| ChatGPT model/operator tools | **111** |
-| Read | **54** |
+| ChatGPT transport tools | **114** |
+| ChatGPT model/operator tools | **112** |
+| Read | **55** |
| Write | **35** |
| Exec | **22** |
| App-only bridges | **2** |
-### ChatGPT read (54)
+### ChatGPT read (55)
- `a2a_agent_discover`
- `a2a_agents_list`
@@ -194,6 +195,7 @@ The ChatGPT profile automatically projects the complete MSO-owned generic model/
- `mso_surface_apps_list`
- `organization_chart`
- `project_agent_status`
+- `project_candidate_search`
- `project_capabilities`
- `project_changes_list`
- `project_diff`
diff --git a/frontend/slices/assistant/host-tools/catalog.ts b/frontend/slices/assistant/host-tools/catalog.ts
index d3a90752..06e2487e 100644
--- a/frontend/slices/assistant/host-tools/catalog.ts
+++ b/frontend/slices/assistant/host-tools/catalog.ts
@@ -1,4 +1,4 @@
-import { clip, obj, str } from "./schema";
+import { clip, num, obj, str } from "./schema";
import { MUTATE_TOOLS } from "./catalog-mutate";
import { SKILL_TOOLS } from "./catalog-skills";
import type { HostTool } from "./types";
@@ -53,6 +53,29 @@ const READ_TOOLS: HostTool[] = [
return hits.length ? hits.map((h) => h.path).join("\n") : "no matches";
},
},
+ {
+ name: "project.candidate.search",
+ group: "files",
+ label: "Project candidates",
+ effect: "read",
+ description:
+ "Search one validated project through MSO's bounded owner-local path/skill candidate index. It ranks path metadata first, then searches content only inside that bounded pool; results are cursored/truncated and never grant authorization.",
+ parameters: obj({
+ "project!": str("Exact project id/path/name/alias"),
+ "query!": str("Path/content search terms"),
+ limit: num("Candidate page size", { min: 1, max: 40 }),
+ cursor: str("Cursor returned by a truncated prior call"),
+ }),
+ run: async (api, a) => {
+ const result = await api.projects.candidateSearch(
+ String(a.project ?? ""),
+ String(a.query ?? ""),
+ typeof a.limit === "number" ? a.limit : undefined,
+ typeof a.cursor === "string" && a.cursor ? a.cursor : undefined,
+ );
+ return clip(JSON.stringify(result));
+ },
+ },
{
name: "sys.stats",
group: "system",
diff --git a/frontend/slices/assistant/host-tools/registry.test.ts b/frontend/slices/assistant/host-tools/registry.test.ts
index 1c5f25b6..20f0fb3e 100644
--- a/frontend/slices/assistant/host-tools/registry.test.ts
+++ b/frontend/slices/assistant/host-tools/registry.test.ts
@@ -15,7 +15,7 @@ import { findHostTool, HOST_AI_TOOLS, HOST_SYSTEM } from "./registry";
describe("host-tools registry", () => {
it("classifies reads as read; fs mutations + exec as mutate", () => {
const eff = (n: string) => findHostTool(n)?.effect;
- for (const n of ["fs.list", "fs.read", "fs.search", "fs.usage", "sys.stats", "sys.processes", "apps.list", "apps.logs", "browser.status", "skills.list", "skills.read"]) expect(eff(n)).toBe("read");
+ for (const n of ["fs.list", "fs.read", "fs.search", "fs.usage", "sys.stats", "sys.processes", "apps.list", "apps.logs", "browser.status", "skills.list", "skills.read", "project.candidate.search"]) expect(eff(n)).toBe("read");
for (const n of ["fs.write", "fs.mkdir", "fs.move", "fs.copy", "fs.delete", "exec.run", "memory.remember", "memory.forget", "apps.power", "browser.power"]) expect(eff(n)).toBe("mutate");
});
diff --git a/frontend/slices/assistant/host-tools/registry.ts b/frontend/slices/assistant/host-tools/registry.ts
index 72699e43..41200eee 100644
--- a/frontend/slices/assistant/host-tools/registry.ts
+++ b/frontend/slices/assistant/host-tools/registry.ts
@@ -28,7 +28,7 @@ export const HOST_AI_TOOLS: AiTool[] = HOST_TOOLS.map((t) => ({
export const HOST_SYSTEM = [
"You are Alfa, operating a real headless VPS through MSO tools.",
"You are a harness agent: inspect available skills/capabilities, choose the smallest useful tool chain, and use approved host commands to do real work.",
- "READ tools (fs.*, sys.*, apps.list, skills.*) run immediately.",
+ "READ tools (fs.*, sys.*, apps.list, skills.*, project.candidate.search) run immediately.",
"Use memory.remember only for lasting user-authored facts or preferences, not tool output or one-off task details; the exact text requires owner approval and may be recalled to a future selected provider.",
"WRITE tools (fs.write, fs.mkdir, fs.move, fs.copy, fs.delete), memory changes, and exec.run require the user to APPROVE each call, and may be DENIED.",
"Skills across ALL of the owner's projects — not just the current one — are discoverable with skills.list/skills.search/skills.read; execute their shell steps only through approved exec.run calls.",
diff --git a/lib/capabilities/execute.ts b/lib/capabilities/execute.ts
index a166ca99..ac5eda48 100644
--- a/lib/capabilities/execute.ts
+++ b/lib/capabilities/execute.ts
@@ -2,7 +2,7 @@ import { capabilityReportedFailure } from "./result-outcome";
import { audit } from "@/lib/host/audit-api";
import { maybeAutoTitleAgentSession } from "@/lib/agent/session-store";
import { touchLocalAgentPresence } from "@/lib/agent/local-agent-presence";
-import { activeWorkflowForActor, recordWorkflowStep } from "@/lib/workflow";
+import { activeWorkflowForActor, recordWorkflowStep, replayHandlesFromResult } from "@/lib/workflow";
import { allows, type Scope } from "./scope";
import type { CapabilityRuntime } from "./runtime";
import type { CapabilityTool } from "./tool";
@@ -127,9 +127,13 @@ export async function executeCapabilityCall(input: {
void audit({ action: outcome?.action ?? trail.action, actor, target: auditTarget, ok: !reportedFailure, detail: outcome?.detail, meta: { via: "mcp", scope } });
}
const durationMs = Date.now() - startedAt, completedWorkflow = workflowFromResult(result) ?? activeWorkflow;
+ const replay = replayHandlesFromResult(result);
if (!workflowProbe) {
void recordCapabilityActivity({ id: activityId, actor, tool: name, state: completedState, scope, ...flowFields(completedWorkflow), target, durationMs });
- await recordWorkflowStep(flowActor, completedWorkflow?.id, { id: activityId, tool: name, state: completedState, target, args, durationMs, ts: new Date().toISOString() });
+ await recordWorkflowStep(flowActor, completedWorkflow?.id, {
+ id: activityId, tool: name, state: completedState, target, args, durationMs, ts: new Date().toISOString(),
+ ...(replay.length ? { replay } : {}),
+ });
await recordAgentEvent(context, name, completedState, args, completedWorkflow?.id, target);
}
if (presence)
diff --git a/lib/contracts/os-api.ts b/lib/contracts/os-api.ts
index 07709e79..74356405 100644
--- a/lib/contracts/os-api.ts
+++ b/lib/contracts/os-api.ts
@@ -42,6 +42,25 @@ export type AppManifest = { name: string; slug: string; runtime: string; entry:
export type ManagedAppSummary = { id: string; name: string; installed: boolean; running: boolean };
export type ManagedAppAction = "start" | "stop" | "restart" | "backup";
export type BrowserState = { installed: boolean; running: boolean; autostart: boolean };
+export type ProjectCandidateRow = {
+ path: string;
+ kind: "path" | "skill";
+ size: number;
+ score: number;
+};
+export type ProjectCandidateContentMatch = { path: string; line: number; preview: string };
+export type ProjectCandidateSearchResult = {
+ project: { id: string; name: string; path: string };
+ revision: string;
+ rebuilt: boolean;
+ reusedSeed: boolean;
+ indexedEntries: number;
+ candidates: ProjectCandidateRow[];
+ matches: ProjectCandidateContentMatch[];
+ truncated: boolean;
+ truncationReasons: string[];
+ cursor?: string;
+};
export type OsApi = {
mode: "mock" | "live";
@@ -78,4 +97,7 @@ export type OsApi = {
power: (id: string, action: ManagedAppAction) => Promise<ManagedAppSummary>;
};
browser: { status: () => Promise<BrowserState>; power: (on: boolean) => Promise<BrowserState> };
+ projects: {
+ candidateSearch: (project: string, query: string, limit?: number, cursor?: string) => Promise<ProjectCandidateSearchResult>;
+ };
};
diff --git a/lib/host/project-candidate-index-cache.ts b/lib/host/project-candidate-index-cache.ts
new file mode 100644
index 00000000..fa04c9dc
--- /dev/null
+++ b/lib/host/project-candidate-index-cache.ts
@@ -0,0 +1,178 @@
+import { createHash } from "node:crypto";
+import { constants, promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const INDEX_VERSION = 1;
+const MAX_INDEX_ENTRIES = 8_000;
+const MAX_DIRS = 2_500;
+const MAX_DEPTH = 14;
+
+export type CandidateKind = "path" | "skill";
+export type CandidateEntry = { path: string; kind: CandidateKind; size: number };
+export type CandidateIndex = {
+ version: 1;
+ projectRoot: string;
+ revision: string;
+ entries: CandidateEntry[];
+ directories: Array<{ path: string; mtimeMs: number }>;
+ truncated: boolean;
+ truncationReasons: string[];
+ createdAt: string;
+};
+
+export type ProjectCandidate = CandidateEntry & { score: number };
+export type ProjectCandidateMatch = { path: string; line: number; preview: string };
+
+const IGNORED_DIRS = new Set([
+ ".git", "node_modules", ".next", ".svelte-kit", ".turbo", "dist", "build", "coverage",
+ ".cache", ".parcel-cache", ".vite", "__pycache__", ".venv", "venv",
+]);
+
+function cacheRoot(): string {
+ return process.env.MSO_CANDIDATE_INDEX_DIR
+ ? path.resolve(process.env.MSO_CANDIDATE_INDEX_DIR)
+ : path.join(os.homedir(), ".mso", "cache", "candidate-index-v1");
+}
+
+function cacheFile(projectPath: string): string {
+ const key = createHash("sha256").update(path.resolve(projectPath)).digest("hex").slice(0, 24);
+ return path.join(cacheRoot(), `${key}.json`);
+}
+
+function ignoredFile(name: string, rel: string): boolean {
+ const lower = name.toLowerCase();
+ if (/^\.env(?:\.|$)/i.test(name)) return true;
+ if ([".npmrc", ".pypirc", "id_rsa", "id_ed25519", "cookies.json", "credentials.json", "auth.json"].includes(lower)) return true;
+ if (/\.(?:pem|key|p12|pfx)$/i.test(name)) return true;
+ if (rel.startsWith(".mso/") && !rel.startsWith(".mso/skills/") && rel !== ".mso/KNOWLEDGE.md") return true;
+ return false;
+}
+
+function allowedDir(name: string, rel: string): boolean {
+ if (IGNORED_DIRS.has(name)) return false;
+ if (name === ".mso") return true;
+ if (rel.startsWith(".mso/") && rel !== ".mso/skills" && !rel.startsWith(".mso/skills/")) return false;
+ return true;
+}
+
+async function atomicWrite(file: string, value: unknown): Promise<void> {
+ await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+ const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+ await fs.writeFile(temp, JSON.stringify(value), { mode: 0o600 });
+ await fs.rename(temp, file);
+ await fs.chmod(file, 0o600).catch(() => undefined);
+}
+
+async function buildIndex(projectPath: string, revision: string): Promise<CandidateIndex> {
+ const root = await fs.realpath(projectPath);
+ const entries: CandidateEntry[] = [];
+ const directories: Array<{ path: string; mtimeMs: number }> = [];
+ const truncationReasons: string[] = [];
+ let dirCount = 0;
+
+ const walk = async (dir: string, relDir: string, depth: number): Promise<void> => {
+ if (entries.length >= MAX_INDEX_ENTRIES) {
+ if (!truncationReasons.includes("maxEntries")) truncationReasons.push("maxEntries");
+ return;
+ }
+ if (dirCount >= MAX_DIRS) {
+ if (!truncationReasons.includes("maxDirectories")) truncationReasons.push("maxDirectories");
+ return;
+ }
+ if (depth > MAX_DEPTH) {
+ if (!truncationReasons.includes("maxDepth")) truncationReasons.push("maxDepth");
+ return;
+ }
+ dirCount += 1;
+ const directoryStat = await fs.stat(dir).catch(() => null);
+ if (!directoryStat?.isDirectory()) return;
+ directories.push({ path: relDir.split(path.sep).join("/"), mtimeMs: directoryStat.mtimeMs });
+ const dirents = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+ for (const dirent of dirents) {
+ if (entries.length >= MAX_INDEX_ENTRIES) {
+ if (!truncationReasons.includes("maxEntries")) truncationReasons.push("maxEntries");
+ break;
+ }
+ if (dirent.isSymbolicLink()) continue;
+ const rel = relDir ? `${relDir}/${dirent.name}` : dirent.name;
+ const absolute = path.join(dir, dirent.name);
+ if (dirent.isDirectory()) {
+ if (!allowedDir(dirent.name, rel)) continue;
+ await walk(absolute, rel, depth + 1);
+ continue;
+ }
+ if (!dirent.isFile() || ignoredFile(dirent.name, rel)) continue;
+ const stat = await fs.stat(absolute).catch(() => null);
+ if (!stat?.isFile()) continue;
+ entries.push({ path: rel.replace(/\\/g, "/"), kind: dirent.name === "SKILL.md" ? "skill" : "path", size: stat.size });
+ }
+ };
+
+ await walk(root, "", 0);
+ return {
+ version: INDEX_VERSION,
+ projectRoot: root,
+ revision,
+ entries,
+ directories,
+ truncated: truncationReasons.length > 0,
+ truncationReasons,
+ createdAt: new Date().toISOString(),
+ };
+}
+
+async function directoryStructureMatches(projectPath: string, directories: CandidateIndex["directories"]): Promise<boolean> {
+ const root = await fs.realpath(projectPath);
+ for (const directory of directories.slice(0, MAX_DIRS)) {
+ const absolute = directory.path ? path.resolve(root, directory.path) : root;
+ if (absolute !== root && !absolute.startsWith(root + path.sep)) return false;
+ const stat = await fs.stat(absolute).catch(() => null);
+ if (!stat?.isDirectory() || stat.mtimeMs !== directory.mtimeMs) return false;
+ }
+ return directories.length > 0;
+}
+
+export async function loadCandidateIndex(projectPath: string, revision: string): Promise<{ index: CandidateIndex; rebuilt: boolean }> {
+ const file = cacheFile(projectPath);
+ const raw = await fs.readFile(file, "utf8").catch(() => "");
+ if (raw) {
+ try {
+ const parsed = JSON.parse(raw) as CandidateIndex;
+ if (
+ parsed?.version === INDEX_VERSION &&
+ parsed.revision === revision &&
+ parsed.projectRoot === await fs.realpath(projectPath) &&
+ Array.isArray(parsed.entries) &&
+ Array.isArray(parsed.directories) &&
+ await directoryStructureMatches(projectPath, parsed.directories)
+ ) return { index: parsed, rebuilt: false };
+ } catch { /* rebuild */ }
+ }
+ const index = await buildIndex(projectPath, revision);
+ await atomicWrite(file, index);
+ return { index, rebuilt: true };
+}
+
+
+export async function candidateEntriesFromSeed(projectPath: string, seedPaths: string[]): Promise<CandidateEntry[]> {
+ const root = await fs.realpath(projectPath);
+ const out: CandidateEntry[] = [];
+ for (const relRaw of seedPaths.slice(0, 64)) {
+ const rel = relRaw.replace(/\\/g, "/").replace(/^\.\//, "");
+ if (!rel || rel.startsWith("../") || path.isAbsolute(rel) || ignoredFile(path.basename(rel), rel)) continue;
+ const absolute = path.resolve(root, rel);
+ const real = await fs.realpath(absolute).catch(() => "");
+ if (!real || (real !== root && !real.startsWith(root + path.sep))) continue;
+ const handle = await fs.open(real, constants.O_RDONLY | constants.O_NOFOLLOW).catch(() => null);
+ if (!handle) continue;
+ try {
+ const stat = await handle.stat();
+ if (!stat.isFile()) continue;
+ out.push({ path: rel, kind: path.basename(rel) === "SKILL.md" ? "skill" : "path", size: stat.size });
+ } finally {
+ await handle.close();
+ }
+ }
+ return out;
+}
diff --git a/lib/host/project-candidate-index.test.ts b/lib/host/project-candidate-index.test.ts
new file mode 100644
index 00000000..58aeb3a1
--- /dev/null
+++ b/lib/host/project-candidate-index.test.ts
@@ -0,0 +1,80 @@
+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 root = await fs.mkdtemp(path.join(os.tmpdir(), "mso-candidate-index-"));
+const cache = path.join(root, "cache");
+process.env.MSO_CANDIDATE_INDEX_DIR = cache;
+const { searchProjectCandidateIndex } = await import("./project-candidate-index");
+
+async function resetProject() {
+ const project = path.join(root, "project");
+ await fs.rm(project, { recursive: true, force: true });
+ await fs.mkdir(path.join(project, "lib", "workflow"), { recursive: true });
+ await fs.mkdir(path.join(project, "skills", "deploy"), { recursive: true });
+ await fs.mkdir(path.join(project, "node_modules", "ignored"), { recursive: true });
+ await fs.writeFile(path.join(project, "lib", "workflow", "bounded-replay.ts"), "export const replay = 'bounded replay needle';\n");
+ await fs.writeFile(path.join(project, "lib", "workflow", "workflow-index.ts"), "export const index = 'workflow sparse needle';\n");
+ await fs.writeFile(path.join(project, "skills", "deploy", "SKILL.md"), "# Deploy\nworkflow deployment skill needle\n");
+ await fs.writeFile(path.join(project, ".env"), "SECRET=must-not-index\n");
+ await fs.writeFile(path.join(project, "node_modules", "ignored", "workflow-secret.ts"), "must-not-index\n");
+ return project;
+}
+
+describe("project candidate index", () => {
+ beforeEach(async () => {
+ await fs.rm(cache, { recursive: true, force: true });
+ });
+ afterAll(async () => {
+ delete process.env.MSO_CANDIDATE_INDEX_DIR;
+ await fs.rm(root, { recursive: true, force: true });
+ });
+
+ it("builds a revision-invalidated owner-local sparse index and searches content only inside the path pool", async () => {
+ const project = await resetProject();
+ const first = await searchProjectCandidateIndex({
+ projectPath: project, query: "workflow replay", revision: "rev-a", limit: 1,
+ });
+ expect(first.rebuilt).toBe(true);
+ expect(first.candidates).toHaveLength(1);
+ expect(first.candidates[0].path).toBe("lib/workflow/bounded-replay.ts");
+ expect(first.matches).toEqual(expect.arrayContaining([
+ expect.objectContaining({ path: "lib/workflow/bounded-replay.ts", preview: expect.stringContaining("bounded replay needle") }),
+ ]));
+ expect(first.matches.every((match) => first.candidates.some((candidate) => candidate.path === match.path))).toBe(true);
+ expect(JSON.stringify(first)).not.toContain("must-not-index");
+ expect(first.truncated).toBe(true);
+ expect(first.cursor).toBeTruthy();
+
+ const second = await searchProjectCandidateIndex({
+ projectPath: project, query: "workflow replay", revision: "rev-a", limit: 1, cursor: first.cursor,
+ });
+ expect(second.rebuilt).toBe(false);
+ expect(second.candidates[0]?.path).not.toBe(first.candidates[0].path);
+
+ const changedRevision = await searchProjectCandidateIndex({
+ projectPath: project, query: "workflow replay", revision: "rev-b", limit: 2,
+ });
+ expect(changedRevision.rebuilt).toBe(true);
+ });
+
+ it("reuses only caller-supplied safe seed paths and does not fall back to a global walk", async () => {
+ const project = await resetProject();
+ await fs.writeFile(path.join(project, "lib", "workflow", "workflow-extra.ts"), "workflow extra global candidate\n");
+ const reused = await searchProjectCandidateIndex({
+ projectPath: project,
+ query: "workflow",
+ revision: "rev-reuse",
+ seedPaths: ["lib/workflow/bounded-replay.ts", "../escape", ".env"],
+ reuseOnly: true,
+ limit: 20,
+ });
+ expect(reused.reusedSeed).toBe(true);
+ expect(reused.rebuilt).toBe(false);
+ expect(reused.indexedEntries).toBe(1);
+ expect(reused.candidates.map((candidate) => candidate.path)).toEqual(["lib/workflow/bounded-replay.ts"]);
+ expect(JSON.stringify(reused)).not.toContain("workflow-extra.ts");
+ expect(JSON.stringify(reused)).not.toContain("SECRET=");
+ });
+});
diff --git a/lib/host/project-candidate-index.ts b/lib/host/project-candidate-index.ts
new file mode 100644
index 00000000..ba1fbfe1
--- /dev/null
+++ b/lib/host/project-candidate-index.ts
@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { readBoundedRegularFile } from "./bounded-read";
+import { candidateEntriesFromSeed, loadCandidateIndex, type CandidateEntry } from "./project-candidate-index-cache";
+
+const MAX_CONTENT_BYTES = 128 * 1024;
+const MAX_MATCHES = 16;
+
+export type ProjectCandidate = CandidateEntry & { score: number };
+export type ProjectCandidateMatch = { path: string; line: number; preview: string };
+
+export function projectCandidateRevision(repository: {
+ git?: { head?: { sha?: string }; branch?: string; changes?: unknown[] };
+} | undefined): string {
+ return createHash("sha256").update(JSON.stringify({
+ head: repository?.git?.head?.sha ?? null,
+ branch: repository?.git?.branch ?? null,
+ changes: repository?.git?.changes ?? [],
+ })).digest("hex");
+}
+function queryTokens(query: string): string[] {
+ return [...new Set(query.toLowerCase().split(/[^a-z0-9_.@/-]+/).filter((token) => token.length >= 2))].slice(0, 32);
+}
+
+function rank(entry: CandidateEntry, tokens: string[]): number {
+ const value = entry.path.toLowerCase();
+ const base = path.basename(value);
+ let score = entry.kind === "skill" ? 0.08 : 0;
+ for (const token of tokens) {
+ if (base === token) score += 0.65;
+ else if (base.includes(token)) score += 0.36;
+ else if (value.includes(token)) score += 0.18;
+ }
+ return Math.round(Math.min(1, score) * 1000) / 1000;
+}
+
+function cursorHash(value: string): string {
+ return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+
+function encodeCursor(revision: string, query: string, offset: number): string {
+ return Buffer.from(JSON.stringify({ v: 1, r: cursorHash(revision), q: cursorHash(query), o: offset }), "utf8").toString("base64url");
+}
+
+function decodeCursor(cursor: string | undefined, revision: string, query: string): number {
+ if (!cursor) return 0;
+ if (cursor.length > 512) throw new Error("candidate cursor is too large");
+ try {
+ const row = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as { v?: number; r?: string; q?: string; o?: number };
+ if (row.v !== 1 || row.r !== cursorHash(revision) || row.q !== cursorHash(query) || !Number.isSafeInteger(row.o) || Number(row.o) < 0)
+ throw new Error("candidate cursor does not match this project revision/query");
+ return Number(row.o);
+ } catch (error) {
+ if (error instanceof Error && error.message.startsWith("candidate cursor")) throw error;
+ throw new Error("invalid candidate cursor");
+ }
+}
+
+async function contentMatches(projectPath: string, candidates: ProjectCandidate[], query: string): Promise<ProjectCandidateMatch[]> {
+ const root = await fs.realpath(projectPath);
+ const tokens = queryTokens(query);
+ if (!tokens.length) return [];
+ const matches: ProjectCandidateMatch[] = [];
+ for (const candidate of candidates) {
+ if (matches.length >= MAX_MATCHES) break;
+ const absolute = path.resolve(root, candidate.path);
+ const real = await fs.realpath(absolute).catch(() => "");
+ if (!real || (real !== root && !real.startsWith(root + path.sep))) continue;
+ const content = await readBoundedRegularFile(real, MAX_CONTENT_BYTES);
+ if (content == null || content.includes("\u0000")) continue;
+ const lines = content.split(/\r?\n/);
+ let perFile = 0;
+ for (let index = 0; index < lines.length && perFile < 3 && matches.length < MAX_MATCHES; index += 1) {
+ const lower = lines[index].toLowerCase();
+ if (!tokens.some((token) => lower.includes(token))) continue;
+ const preview = lines[index].trim().replace(/\s+/g, " ").slice(0, 220);
+ if (!preview) continue;
+ matches.push({ path: candidate.path, line: index + 1, preview });
+ perFile += 1;
+ }
+ }
+ return matches;
+}
+
+export async function searchProjectCandidateIndex(input: {
+ projectPath: string;
+ query: string;
+ revision: string;
+ limit?: number;
+ cursor?: string;
+ seedPaths?: string[];
+ reuseOnly?: boolean;
+}): Promise<{
+ revision: string;
+ rebuilt: boolean;
+ reusedSeed: boolean;
+ indexedEntries: number;
+ candidates: ProjectCandidate[];
+ matches: ProjectCandidateMatch[];
+ truncated: boolean;
+ truncationReasons: string[];
+ cursor?: string;
+}> {
+ const limit = Math.min(Math.max(Math.round(input.limit ?? 16), 1), 40);
+ const query = input.query.slice(0, 4096);
+ const reuseOnly = input.reuseOnly === true;
+ const seeded = input.seedPaths?.length ? await candidateEntriesFromSeed(input.projectPath, input.seedPaths) : [];
+ const loaded = reuseOnly
+ ? { index: { version: 1 as const, projectRoot: await fs.realpath(input.projectPath), revision: input.revision, entries: seeded, directories: [], truncated: false, truncationReasons: [], createdAt: new Date().toISOString() }, rebuilt: false }
+ : await loadCandidateIndex(input.projectPath, input.revision);
+ const source = reuseOnly ? seeded : loaded.index.entries;
+ const tokens = queryTokens(query);
+ const ranked = source
+ .map((entry) => ({ ...entry, score: rank(entry, tokens) }))
+ .filter((entry) => reuseOnly || tokens.length === 0 || entry.score > 0)
+ .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+ const offset = decodeCursor(input.cursor, input.revision, query);
+ const candidates = ranked.slice(offset, offset + limit);
+ const matches = await contentMatches(input.projectPath, candidates, query);
+ const hasMore = offset + candidates.length < ranked.length;
+ const truncated = loaded.index.truncated || hasMore;
+ const truncationReasons = [...loaded.index.truncationReasons, ...(hasMore ? ["page"] : [])];
+ return {
+ revision: input.revision,
+ rebuilt: loaded.rebuilt,
+ reusedSeed: reuseOnly,
+ indexedEntries: source.length,
+ candidates,
+ matches,
+ truncated,
+ truncationReasons: [...new Set(truncationReasons)],
+ ...(hasMore ? { cursor: encodeCursor(input.revision, query, offset + candidates.length) } : {}),
+ };
+}
diff --git a/lib/mcp/chatgpt-profile.test.ts b/lib/mcp/chatgpt-profile.test.ts
index d71c4916..163ce945 100644
--- a/lib/mcp/chatgpt-profile.test.ts
+++ b/lib/mcp/chatgpt-profile.test.ts
@@ -32,12 +32,13 @@ describe("ChatGPT full generic MCP profile", () => {
const bytes = Buffer.byteLength(JSON.stringify(tools));
if (process.env.MSO_PROFILE_METRICS === "1") console.info(`CHATGPT_PROFILE_METRICS tools=${tools.length} bytes=${bytes} roughTokens4=${Math.ceil(bytes/4)} maxToolBytes=${Math.max(...tools.map((tool)=>Buffer.byteLength(JSON.stringify(tool))))}`);
- expect(bytes).toBeLessThan(96 * 1024);
+ expect(bytes).toBeLessThan(92 * 1024);
const start = tools.find((tool) => tool.name === "workflow_start") as { description?: string };
expect(String(start?.description)).toMatch(/First call for multi-step work/i);
const search = tools.find((tool) => tool.name === "skills_search") as { description?: string };
expect(String(search?.description)).toContain("mso-agent-bootstrap");
expect(tools.some((tool) => tool.name === "local_agent_inbox")).toBe(true);
+ expect(tools.some((tool) => tool.name === "project_candidate_search")).toBe(true);
expect(tools.some((tool) => tool.name === "project_mcp_tools")).toBe(true);
expect(tools.some((tool) => tool.name === "project_mcp_call")).toBe(true);
expect(tools.some((tool) => tool.name === "tool_forge_promote")).toBe(true);
diff --git a/lib/mcp/parity.test.ts b/lib/mcp/parity.test.ts
index 41221556..ff59bec0 100644
--- a/lib/mcp/parity.test.ts
+++ b/lib/mcp/parity.test.ts
@@ -193,6 +193,7 @@ describe("MCP rate limits mirror the routes", () => {
"exec.job.cancel": 30,
// Global discovery reads use independent bounded buckets.
"projects.list": 30,
+ "projects.candidates": 30,
"projects.capabilities": 60,
"projects.function": 60,
"projects.mcp.read": 30,
diff --git a/lib/mcp/tool-contract.ts b/lib/mcp/tool-contract.ts
index 44fe10b1..1708d514 100644
--- a/lib/mcp/tool-contract.ts
+++ b/lib/mcp/tool-contract.ts
@@ -115,7 +115,7 @@ function compactSchema(value: unknown): unknown {
for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
if (key === "additionalProperties" && item === true || key === "required" && Array.isArray(item) && item.length === 0) continue;
if (key === "workflow_id" && item && typeof item === "object") out[key] = { type:"string" };
- else if (key === "description" && typeof item === "string") out[key] = compactText(item, 16);
+ else if (key === "description") continue;
else out[key] = compactSchema(item);
}
return out;
@@ -133,7 +133,7 @@ export function toolDescriptor(tool: McpTool, profile: McpToolProfile = "full")
return {
name: tool.name,
title: tool.title ?? toolTitle(tool.name),
- description: compact ? compactText(tool.chatgptDescription ?? tool.description, 56) : tool.description,
+ description: compact ? compactText(tool.chatgptDescription ?? tool.description, 48) : tool.description,
inputSchema: compact ? compactSchema(tool.inputSchema) : tool.inputSchema,
...(outputSchema ? { outputSchema: compact ? compactSchema(outputSchema) : outputSchema } : {}),
securitySchemes,
diff --git a/lib/mcp/tools-discovery.ts b/lib/mcp/tools-discovery.ts
index 5ab6d950..7a021883 100644
--- a/lib/mcp/tools-discovery.ts
+++ b/lib/mcp/tools-discovery.ts
@@ -1,4 +1,5 @@
-import { listProjects, projectCapabilities, publicProjectMcpServers, readProjectMcpServers, resolveProjectHint, PROJECT_LIMITS } from "@/lib/host/projects-api";
+import { listProjects, inspectProject, projectCapabilities, publicProjectMcpServers, readProjectMcpServers, resolveProjectHint, PROJECT_LIMITS } from "@/lib/host/projects-api";
+import { projectCandidateRevision, searchProjectCandidateIndex } from "@/lib/host/project-candidate-index";
import { catalogSkillsDetailed, resolveSkill, readSkillFile, skillIsExecutableByDefault, SKILL_SCAN_LIMITS } from "@/lib/skills/catalog";
import { compactSkillContract } from "@/lib/skills/skill-contract";
import { type McpTool, str, opt, S, READ_ONLY } from "./tool-kit";
@@ -21,6 +22,7 @@ const page = (a: Record<string, unknown>, max: number, fallback: number) => ({
offset: Math.max(Math.round(typeof a.offset === "number" ? a.offset : 0), 0),
});
+
export const DISCOVERY_TOOLS: McpTool[] = [
{
name: "project_capabilities",
@@ -44,6 +46,36 @@ export const DISCOVERY_TOOLS: McpTool[] = [
return { project: { id: project.id, name: project.name, path: project.path }, capabilities };
},
},
+ {
+ name: "project_candidate_search",
+ description:
+ "Search a bounded owner-local candidate index for ONE validated project. Stage one ranks only path/skill metadata; stage two searches file content only inside the returned candidate pool. " +
+ "The index is revision-invalidated, excludes Git/build/dependency/credential paths, returns truncation/cursor state, and is never an authorization or source-control authority.",
+ chatgptDescription: "Search bounded project path candidates, then content only inside that pool.",
+ scope: "read",
+ annotations: READ_ONLY,
+ limit: { key: "projects.candidates", max: 30, windowMs: 60_000 },
+ inputSchema: S({
+ project: { type: "string", description: "Exact project id/path/name/alias." },
+ query: { type: "string", description: "Path/content terms." },
+ limit: { type: "number", minimum: 1, maximum: 40, description: "Candidate page size. Default 16." },
+ cursor: { type: "string", description: "Cursor from a truncated previous page." },
+ }, ["project", "query"]),
+ run: async (a) => {
+ const project = await resolveProjectHint(str(a, "project"));
+ if (!project) throw new Error(`project not found: ${String(a.project)}`);
+ const repository = await inspectProject(project, { includeGitStatus: true }).catch(() => undefined);
+ const revision = projectCandidateRevision(repository);
+ const result = await searchProjectCandidateIndex({
+ projectPath: project.path,
+ query: str(a, "query"),
+ revision,
+ limit: typeof a.limit === "number" ? a.limit : undefined,
+ cursor: opt(a, "cursor"),
+ });
+ return { project: { id: project.id, name: project.name, path: project.path }, ...result };
+ },
+ },
{
name: "projects_list",
description:
diff --git a/lib/mcp/tools-learning-shared.ts b/lib/mcp/tools-learning-shared.ts
index 302e391d..fddc26bf 100644
--- a/lib/mcp/tools-learning-shared.ts
+++ b/lib/mcp/tools-learning-shared.ts
@@ -46,6 +46,18 @@ export const WORKFLOW_PROGRESS_OUTPUT = {
tool: { type: "string" },
state: { type: "string", enum: ["completed", "failed", "denied", "rate_limited", "invalid_args"] },
durationMs: { type: "number" }, ts: { type: "string" },
+ replay: {
+ type: "array", maxItems: 4, items: {
+ type: "object",
+ properties: {
+ kind: { type: "string", enum: ["file", "job", "artifact", "cursor"] },
+ path: { type: "string" }, sha256: { type: "string" }, jobId: { type: "string" },
+ artifactId: { type: "string" }, cursor: { type: "string" }, truncated: { type: "boolean" },
+ rereadWith: { type: "string", enum: ["fs_read", "read_pipeline", "exec_job_status", "session_artifacts", "project_candidate_search"] },
+ },
+ required: ["kind"], additionalProperties: false,
+ },
+ },
},
required: ["tool", "state", "ts"], additionalProperties: false,
},
@@ -56,6 +68,10 @@ export const WORKFLOW_PROGRESS_OUTPUT = {
type WorkflowProgressStep = {
tool: string; state: "completed" | "failed" | "denied" | "rate_limited" | "invalid_args"; durationMs?: number; ts: string;
+ replay?: Array<{
+ kind: "file" | "job" | "artifact" | "cursor"; path?: string; sha256?: string; jobId?: string;
+ artifactId?: string; cursor?: string; truncated?: boolean; rereadWith?: string;
+ }>;
};
function projectLabel(value: unknown): string | undefined {
@@ -74,8 +90,28 @@ function workflowSteps(value: unknown): WorkflowProgressStep[] {
const state = step.state;
if (typeof step.tool !== "string" || typeof step.ts !== "string") continue;
if (state !== "completed" && state !== "failed" && state !== "denied" && state !== "rate_limited" && state !== "invalid_args") continue;
+ const replay: NonNullable<WorkflowProgressStep["replay"]> = [];
+ if (Array.isArray(step.replay)) {
+ for (const value of step.replay.slice(-4)) {
+ if (!value || typeof value !== "object") continue;
+ const row = value as Record<string, unknown>;
+ const kind = row.kind;
+ if (kind !== "file" && kind !== "job" && kind !== "artifact" && kind !== "cursor") continue;
+ replay.push({
+ kind,
+ ...(typeof row.path === "string" ? { path: row.path.slice(0, 512) } : {}),
+ ...(typeof row.sha256 === "string" ? { sha256: row.sha256.slice(0, 80) } : {}),
+ ...(typeof row.jobId === "string" ? { jobId: row.jobId.slice(0, 160) } : {}),
+ ...(typeof row.artifactId === "string" ? { artifactId: row.artifactId.slice(0, 160) } : {}),
+ ...(typeof row.cursor === "string" ? { cursor: row.cursor.slice(0, 512) } : {}),
+ ...(row.truncated === true ? { truncated: true } : {}),
+ ...(typeof row.rereadWith === "string" ? { rereadWith: row.rereadWith.slice(0, 40) } : {}),
+ });
+ }
+ }
out.push({ tool: step.tool.slice(0, 100), state,
- ...(typeof step.durationMs === "number" && Number.isFinite(step.durationMs) ? { durationMs: Math.max(0, step.durationMs) } : {}), ts: step.ts });
+ ...(typeof step.durationMs === "number" && Number.isFinite(step.durationMs) ? { durationMs: Math.max(0, step.durationMs) } : {}),
+ ts: step.ts, ...(replay.length ? { replay } : {}) });
}
return out;
}
diff --git a/lib/mcp/tools-learning.test.ts b/lib/mcp/tools-learning.test.ts
index 10f6e2c6..138f7d5f 100644
--- a/lib/mcp/tools-learning.test.ts
+++ b/lib/mcp/tools-learning.test.ts
@@ -25,10 +25,12 @@ const previous = {
read: process.env.OS_FS_READ_ROOTS,
write: process.env.OS_FS_WRITE_ROOTS,
memory: process.env.OS_SKILL_MEMORY_STORE,
+ candidateIndex: process.env.MSO_CANDIDATE_INDEX_DIR,
};
process.env.OS_FS_READ_ROOTS = dir;
process.env.OS_FS_WRITE_ROOTS = dir;
process.env.OS_SKILL_MEMORY_STORE = path.join(dir, "memory.json");
+process.env.MSO_CANDIDATE_INDEX_DIR = path.join(dir, "candidate-cache");
const { resetWorkflowStoreCache } = await import("@/lib/workflow");
const { projectRefFor } = await import("@/lib/skills/project-skills");
const { LEARNING_TOOLS } = await import("./tools-learning");
@@ -49,6 +51,8 @@ describe("workflow_start bootstrap", () => {
else process.env.OS_FS_WRITE_ROOTS = previous.write;
if (previous.memory === undefined) delete process.env.OS_SKILL_MEMORY_STORE;
else process.env.OS_SKILL_MEMORY_STORE = previous.memory;
+ if (previous.candidateIndex === undefined) delete process.env.MSO_CANDIDATE_INDEX_DIR;
+ else process.env.MSO_CANDIDATE_INDEX_DIR = previous.candidateIndex;
resetWorkflowStoreCache();
await fs.rm(dir, { recursive: true, force: true });
});
@@ -126,6 +130,57 @@ describe("workflow_start bootstrap", () => {
expect(result.bootstrap.trace.some((line) => line.startsWith("[Discovery]"))).toBe(false);
});
+
+
+ it("reuses the prior redacted candidate pool instead of repeating global skill/path discovery", async () => {
+ await fs.writeFile(path.join(project, "workflow-reuse.md"), "workflow reuse candidate\n");
+ const start = LEARNING_TOOLS.find((tool) => tool.name === "workflow_start")!;
+ const finish = LEARNING_TOOLS.find((tool) => tool.name === "workflow_finish")!;
+ const context = { actor: "mcp:reuse-bootstrap", scope: "write" as const };
+ const first = await start.run({
+ intent: "workflow reuse candidate",
+ project,
+ }, context) as {
+ workflow: { id: string };
+ search: { engine: string };
+ bootstrap: { discovery: { candidatePool?: { source: string; candidates: Array<{ path: string }> } } };
+ };
+ expect(first.search.engine).not.toBe("candidate-pool-reuse-v1");
+ expect(first.bootstrap.discovery.candidatePool?.source).toBe("host-index");
+ expect(first.bootstrap.discovery.candidatePool?.candidates.map((row) => row.path)).toContain("workflow-reuse.md");
+ const { recordWorkflowStep } = await import("@/lib/workflow");
+ await recordWorkflowStep(context.actor, first.workflow.id, {
+ id: "mcp-candidate", tool: "project_mcp_tools", state: "completed",
+ args: { project: "mso", server: "si-coder" }, ts: new Date().toISOString(),
+ });
+ await recordWorkflowStep(context.actor, first.workflow.id, {
+ id: "connection-candidate", tool: "integration_query", state: "completed",
+ args: { connection: "github-main", provider: "github" }, ts: new Date().toISOString(),
+ });
+ await finish.run({ workflow_id: first.workflow.id, summary: "verified reusable candidate pool", success: true }, context);
+
+ const second = await start.run({
+ intent: "workflow reuse candidate",
+ project,
+ }, context) as {
+ workflow: { id: string };
+ search: { engine: string; recommendedRecipe?: unknown };
+ bootstrap: { discovery: { candidatePool?: {
+ source: string; reused: boolean; candidates: Array<{ path: string }>;
+ hints?: { paths: string[]; skillIds: string[]; connectionIds: string[]; mcpAliases: string[] };
+ } } };
+ };
+ expect(second.search.engine).toBe("candidate-pool-reuse-v1");
+ expect(second.search.recommendedRecipe).toBeUndefined();
+ expect(second.bootstrap.discovery.candidatePool).toMatchObject({ source: "recipe-reuse", reused: true });
+ expect(second.bootstrap.discovery.candidatePool?.candidates.map((row) => row.path)).toContain("workflow-reuse.md");
+ expect(second.bootstrap.discovery.candidatePool?.hints).toMatchObject({
+ paths: expect.arrayContaining(["workflow-reuse.md"]),
+ connectionIds: ["github-main"],
+ mcpAliases: ["si-coder"],
+ });
+ });
+
it("supports parallel conversations and exposes explicit cancel/finish ids", async () => {
const start = LEARNING_TOOLS.find((tool) => tool.name === "workflow_start")!;
const cancel = LEARNING_TOOLS.find((tool) => tool.name === "workflow_cancel")!;
diff --git a/lib/mcp/tools-workflow-lifecycle.ts b/lib/mcp/tools-workflow-lifecycle.ts
index 6b963034..7fd9c49a 100644
--- a/lib/mcp/tools-workflow-lifecycle.ts
+++ b/lib/mcp/tools-workflow-lifecycle.ts
@@ -160,7 +160,7 @@ export const WORKFLOW_LIFECYCLE_TOOLS: McpTool[] = [
await writePortableRecipe(project.path, {
schemaVersion: 1, id: finished.recipe.id, intent: finished.recipe.intent, summary: finished.recipe.summary,
stage: automation.stage, attempts: finished.recipe.attempts, successes: finished.recipe.successes, failures: finished.recipe.failures,
- successRate: automation.successRate, bestSteps: finished.recipe.bestSteps, quality: finished.recipe.quality, updatedAt: finished.recipe.updatedAt,
+ successRate: automation.successRate, bestSteps: finished.recipe.bestSteps, candidatePool: finished.recipe.candidatePool, quality: finished.recipe.quality, updatedAt: finished.recipe.updatedAt,
}, finished.recipe.id);
}
if (automation.scriptCandidate) {
diff --git a/lib/mcp/tools-workflow-start.ts b/lib/mcp/tools-workflow-start.ts
index 7d436e22..cd855e74 100644
--- a/lib/mcp/tools-workflow-start.ts
+++ b/lib/mcp/tools-workflow-start.ts
@@ -2,31 +2,26 @@ import { ownedArtifactSession, prepareSessionArtifacts } from "@/lib/agent/artif
import { inspectProject, readProjectKnowledge, resolveProjectHint } from "@/lib/host/projects-api";
import { listLearnedRecipes, markRecipeUsed, startWorkflow, summarizeProjectContention } from "@/lib/workflow";
import { ensureLearnedWorkflowGraph, findMatchingWorkflowGraph } from "@/lib/workflow/graph-store";
-import { searchSkillMemory } from "@/lib/skills/search";
import { progressiveVerification } from "@/lib/orchestration/automation";
import { routeIntentText } from "@/lib/orchestration/capability-catalog.mjs";
import { classifyTask, gitChangedPaths } from "@/lib/orchestration/classifier";
import { searchRepoMemory } from "@/lib/orchestration/repo-memory";
import { readAutomationScript } from "@/lib/orchestration/repo-memory-artifacts";
import type { WorkflowOrchestrationSnapshot } from "@/lib/orchestration/types";
-import type { McpTool } from "./tool-kit";
-import { opt, S, str } from "./tool-kit";
+import { type McpTool, opt, S, str } from "./tool-kit";
import { toolsetInfo } from "./toolset";
import { optionalStringList, visibleTools, WORKFLOW_PROGRESS_OUTPUT, workflowProgress } from "./tools-learning-shared";
import { AGENT_BOOTSTRAP_SKILL, workflowOrientation, workflowStartPolicy } from "./instructions";
-
-export const WORKFLOW_START_TOOL: McpTool =
- {
+import { workflowStartCandidateContext } from "./workflow-start-candidates";
+export const WORKFLOW_START_TOOL: McpTool = {
name: "workflow_start",
description: "First call for multi-step work: resolve project context, search trusted skills/recipes/graphs, and return workflow_id. Carry that exact id on later steps. Read official skill mso-agent-bootstrap when learning the MSO map.",
chatgptDescription: "First call for multi-step work; keep workflow_id.",
scope: "write",
annotations: { idempotentHint: false },
outputSchema: WORKFLOW_PROGRESS_OUTPUT,
- toStructuredContent: (result) => {
- if (!result || typeof result !== "object") return undefined;
- return workflowProgress((result as { workflow?: unknown }).workflow, true);
- },
+ toStructuredContent: (result) => result && typeof result === "object"
+ ? workflowProgress((result as { workflow?: unknown }).workflow, true) : undefined,
limit: { key: "workflow.memory", max: 30, windowMs: 60_000 },
audit: { action: "workflow.start" as const, targetArg: "project" },
inputSchema: S({
@@ -46,23 +41,17 @@ export const WORKFLOW_START_TOOL: McpTool =
const project = projectHint ? await resolveProjectHint(projectHint).catch(() => null) : null;
const tools = await visibleTools(context.scope, context.toolProfile);
const intentRoute = routeIntentText(intent);
- const routedTools = intentRoute.catalogMatched
- ? tools.filter((tool) => intentRoute.tools.includes(tool.name) || tool.name === "workflow_start")
- : tools;
- const search = await searchSkillMemory(intent, {
- topK: intentRoute.catalogMatched ? 5 : 7,
- recipeAccess: { actor: recipeOwner, scope: context.scope },
- toolDocs: routedTools.map((tool) => ({
- name: tool.name, description: tool.description, scope: tool.scope, inputSchema: tool.inputSchema,
- })),
- });
- const [repository, projectKnowledge] = project
- ? await Promise.all([
- inspectProject(project, { includeGitStatus: context.scope === "exec" }).catch(() => undefined),
- readProjectKnowledge(project.path).catch(() => undefined),
- ])
- : [undefined, undefined] as const;
+ const routedTools = intentRoute.catalogMatched ? tools.filter((tool) =>
+ intentRoute.tools.includes(tool.name) || tool.name === "workflow_start") : tools;
+ const [repository, projectKnowledge] = project ? await Promise.all([
+ inspectProject(project, { includeGitStatus: context.scope === "exec" }).catch(() => undefined),
+ readProjectKnowledge(project.path).catch(() => undefined),
+ ]) : [undefined, undefined] as const;
const changedPaths = gitChangedPaths(repository?.git.changes ?? []);
+ const { search, reusablePool, candidateSearch, candidatePool } = await workflowStartCandidateContext({
+ intent, recipeOwner, scope: context.scope, project, projectHint, repository,
+ catalogMatched: intentRoute.catalogMatched, routedTools,
+ });
const affectedPaths = optionalStringList(a.affected_paths, 80);
const reservedResources = optionalStringList(a.reserved_resources, 40);
const contention = project
@@ -75,16 +64,15 @@ export const WORKFLOW_START_TOOL: McpTool =
});
const memoryLimit = classification.memoryRelevance === "high" ? 5 : classification.memoryRelevance === "medium" ? 3 : 0;
const repoMemory = project && memoryLimit > 0
- ? await searchRepoMemory(project.path, { query: intent, limit: memoryLimit }).catch(() => [])
- : [];
+ ? await searchRepoMemory(project.path, { query: intent, limit: memoryLimit }).catch(() => []) : [];
const reusableScript = project && search.recommendedRecipe
? await readAutomationScript(project.path, `script_${search.recommendedRecipe.id}`).catch(() => null)
: null;
const projectKeys = [project?.id, project?.path, project?.name, projectHint].filter((value): value is string => Boolean(value));
let graphAutomation = await findMatchingWorkflowGraph(recipeOwner, intent, projectKeys).catch(() => null);
if (!graphAutomation && search.recommendedRecipe) {
- const fullRecipe = (await listLearnedRecipes({ actor: recipeOwner, scope: context.scope }))
- .find((recipe) => recipe.id === search.recommendedRecipe?.id);
+ const fullRecipe = (await listLearnedRecipes({ actor: recipeOwner, scope: context.scope })).find(
+ (recipe) => recipe.id === search.recommendedRecipe?.id);
if (fullRecipe) graphAutomation = await ensureLearnedWorkflowGraph(fullRecipe).catch(() => null);
}
const recipePlan = search.recommendedRecipe ? {
@@ -92,9 +80,8 @@ export const WORKFLOW_START_TOOL: McpTool =
attempts: search.recommendedRecipe.attempts ?? 0,
successRate: search.recommendedRecipe.successRate ?? 0,
maturity: search.recommendedRecipe.maturity ?? "candidate",
- steps: (search.recommendedRecipe.steps ?? []).slice(0, 12).map((step) => ({
- tool: step.tool, target: step.target, args: step.args,
- })),
+ steps: (search.recommendedRecipe.steps ?? []).slice(0, 12).map((step) => (
+ { tool: step.tool, target: step.target, args: step.args })),
instruction: reusableScript
? (reusableScript.status === "tested" ? "Prefer the tested script path below when current evidence is compatible." : "A script candidate exists; verify it before treating the route as tested.")
: search.recommendedRecipe.maturity === "verified"
@@ -120,6 +107,7 @@ export const WORKFLOW_START_TOOL: McpTool =
intent,
...(projectKnowledge?.content ? [projectKnowledge.content] : []),
...repoMemory.map((hit) => `${hit.record.title} ${hit.record.summary}`),
+ ...(candidateSearch?.matches ?? []).map((match) => `${match.path}:${match.line} ${match.preview}`),
compactSearch.recommendedRecipe?.description ?? "",
].join("\n").length / 4);
const orchestration: WorkflowOrchestrationSnapshot = {
@@ -136,10 +124,26 @@ export const WORKFLOW_START_TOOL: McpTool =
...(search.recommendedRecipe ? { recipeUsed: search.recommendedRecipe.id } : {}),
createdAt: new Date().toISOString(),
};
- const toolset = toolsetInfo(tools, context.scope, context.toolProfile);
+ const toolset = {
+ ...toolsetInfo(tools, context.scope, context.toolProfile),
+ activePack: { source: intentRoute.catalogMatched ? "catalog" : "semantic-fallback",
+ count: routedTools.length, names: routedTools.map((tool) => tool.name).slice(0, 20) },
+ };
const discovery = {
catalog: search.catalog,
- complete: !search.catalog.truncated,
+ complete: !search.catalog.truncated && !(candidateSearch?.truncated ?? false),
+ candidatePool: candidateSearch || candidatePool ? {
+ source: reusablePool ? "recipe-reuse" : "host-index",
+ reused: candidateSearch?.reusedSeed ?? Boolean(reusablePool),
+ revision: candidateSearch?.revision ?? candidatePool?.revision,
+ candidates: candidateSearch?.candidates.slice(0, 12) ?? [],
+ matches: candidateSearch?.matches.slice(0, 12) ?? [],
+ truncated: candidateSearch?.truncated ?? candidatePool?.truncated ?? false,
+ truncationReasons: candidateSearch?.truncationReasons ?? [],
+ hints: candidatePool ? { paths: candidatePool.paths.slice(0, 12), skillIds: candidatePool.skillIds.slice(0, 12),
+ connectionIds: candidatePool.connectionIds.slice(0, 12), mcpAliases: candidatePool.mcpAliases.slice(0, 12) } : undefined,
+ ...(candidateSearch?.cursor ? { cursor: candidateSearch.cursor } : candidatePool?.cursor ? { cursor: candidatePool.cursor } : {}),
+ } : undefined,
};
const started = await startWorkflow({
actor,
@@ -148,6 +152,7 @@ export const WORKFLOW_START_TOOL: McpTool =
project: project?.path ?? projectHint,
constraints: opt(a, "constraints"),
orchestration,
+ candidatePool,
});
if (search.recommendedRecipe) {
await markRecipeUsed(search.recommendedRecipe.id, { actor: recipeOwner, scope: context.scope }).catch(() => undefined);
@@ -198,7 +203,8 @@ export const WORKFLOW_START_TOOL: McpTool =
...(graphAutomation ? [`[Workflow graph] ${graphAutomation.status} · ${graphAutomation.name} · ${graphAutomation.metadata.provenance ?? "private"}`] : [`[Workflow graph] no matching private graph; successful completion will seed a learned draft`]),
...(reusableScript ? [`[Automation] ${reusableScript.status} script ${reusableScript.id} available`] : []),
...(contention.conflictingWorkflowCount ? [`[Collision] ${contention.conflictingWorkflowCount} workflow(s) overlap declared paths/resources`] : []),
- ...(discovery.complete ? [] : [`[Discovery] partial scan — ${search.catalog.truncationReasons.join(", ")}; do not conclude something is absent`]),
+ ...(candidateSearch ? [`[Candidates] ${candidateSearch.reusedSeed ? "reused recipe pool" : "host index"} · ${candidateSearch.candidates.length} path candidate(s) · ${candidateSearch.matches.length} bounded content hit(s)`] : []),
+ ...(discovery.complete ? [] : [`[Discovery] partial scan — ${[...search.catalog.truncationReasons, ...(candidateSearch?.truncationReasons ?? [])].join(", ")}; do not conclude something is absent`]),
`[Orient] follow ${AGENT_BOOTSTRAP_SKILL} then the discover→act loop`,
"[Plan] classify → retrieve minimal memory → isolate if required → execute → progressive verify → learn → workflow_finish",
],
diff --git a/lib/mcp/toolset.ts b/lib/mcp/toolset.ts
index 7ca13e1a..dfcdd588 100644
--- a/lib/mcp/toolset.ts
+++ b/lib/mcp/toolset.ts
@@ -4,8 +4,8 @@ import type { McpTool } from "./tool-kit";
import { toolDescriptor, type McpToolProfile } from "./tool-contract";
export const MCP_SERVER_VERSION = "1.15.1";
-export const MCP_TOOLSET_VERSION = "2026.09.19.2";
-export const MCP_TOOLSET_CHANGED_AT = "2026-09-19T16:47:44+07:00";
+export const MCP_TOOLSET_VERSION = "2026.09.19.3";
+export const MCP_TOOLSET_CHANGED_AT = "2026-09-19T19:11:32+07:00";
export type McpToolsetInfo = {
serverVersion: string;
diff --git a/lib/mcp/workflow-start-candidates.ts b/lib/mcp/workflow-start-candidates.ts
new file mode 100644
index 00000000..27fdbd8a
--- /dev/null
+++ b/lib/mcp/workflow-start-candidates.ts
@@ -0,0 +1,96 @@
+import type { Scope } from "@/lib/capabilities/scope";
+import { projectCandidateRevision, searchProjectCandidateIndex } from "@/lib/host/project-candidate-index";
+import { inspectProject, type ProjectResolution } from "@/lib/host/projects-api";
+import { findReusableRecipe, recipeMaturity, type WorkflowCandidatePool } from "@/lib/workflow";
+import { searchSkillMemory } from "@/lib/skills/search";
+import type { McpTool } from "./tool-kit";
+export async function workflowStartCandidateContext(input: {
+ intent: string;
+ recipeOwner: string;
+ scope: Scope;
+ project: ProjectResolution | null;
+ projectHint?: string;
+ repository?: Awaited<ReturnType<typeof inspectProject>>;
+ catalogMatched: boolean;
+ routedTools: McpTool[];
+}) {
+ const { intent, recipeOwner, scope, project, projectHint, repository, catalogMatched, routedTools } = input;
+ const recipeProject = project?.path ?? projectHint;
+ const reusableRecipe = recipeProject
+ ? await findReusableRecipe({ actor: recipeOwner, scope: scope, intent, project: recipeProject }).catch(() => undefined)
+ : undefined;
+ const reusablePool = reusableRecipe?.candidatePool;
+ let search: Awaited<ReturnType<typeof searchSkillMemory>>;
+ if (reusableRecipe && reusablePool) {
+ const availableTools = new Set(routedTools.map((tool) => tool.name));
+ const missingTools = [...new Set(reusableRecipe.bestSteps.map((step) => step.tool).filter((tool) => !availableTools.has(tool)))];
+ const maturity = recipeMaturity(reusableRecipe).maturity;
+ const recipeHit = {
+ kind: "recipe" as const,
+ id: reusableRecipe.id,
+ name: reusableRecipe.intent,
+ score: 1,
+ description: reusableRecipe.summary,
+ source: "learned",
+ trust: "local",
+ successRate: reusableRecipe.attempts ? Math.round((reusableRecipe.successes / reusableRecipe.attempts) * 1000) / 10 : 0,
+ fastestDurationMs: reusableRecipe.fastestDurationMs,
+ attempts: reusableRecipe.attempts,
+ maturity,
+ steps: reusableRecipe.bestSteps.map((step) => ({
+ tool: step.tool, target: step.target, args: step.args, durationMs: step.durationMs,
+ })),
+ ...(missingTools.length ? { missingTools } : {}),
+ };
+ search = {
+ engine: "candidate-pool-reuse-v1",
+ query: intent,
+ hits: [
+ recipeHit,
+ ...reusablePool.skillIds.slice(0, 4).map((id) => ({
+ kind: "skill" as const,
+ id,
+ name: id,
+ score: 0.5,
+ description: "Reused candidate skill id. Read the current trusted skill before using its instructions.",
+ source: "recipe-pool",
+ trust: "local",
+ })),
+ ],
+ catalog: { truncated: false, truncationReasons: [], scannedRoots: 0, scannedProjects: 0 },
+ ...(maturity === "observed" ? {} : { recommendedRecipe: recipeHit }),
+ };
+ } else {
+ search = await searchSkillMemory(intent, {
+ topK: catalogMatched ? 5 : 7,
+ recipeAccess: { actor: recipeOwner, scope: scope },
+ toolDocs: routedTools.map((tool) => ({
+ name: tool.name, description: tool.description, scope: tool.scope, inputSchema: tool.inputSchema,
+ })),
+ });
+ }
+ const candidateRevision = project ? projectCandidateRevision(repository) : undefined;
+ const candidateSearch = project && candidateRevision
+ ? await searchProjectCandidateIndex({
+ projectPath: project.path,
+ query: intent,
+ revision: candidateRevision,
+ limit: 12,
+ ...(reusablePool?.paths.length ? { seedPaths: reusablePool.paths, reuseOnly: true } : {}),
+ }).catch(() => undefined)
+ : undefined;
+ const discoveredPool: WorkflowCandidatePool | undefined = project && candidateRevision ? {
+ version: 1,
+ revision: candidateRevision,
+ paths: candidateSearch?.candidates.map((candidate) => candidate.path).slice(0, 24) ?? [],
+ skillIds: search.hits.filter((hit) => hit.kind === "skill").map((hit) => hit.id).slice(0, 16),
+ connectionIds: reusablePool?.connectionIds.slice(0, 16) ?? [],
+ mcpAliases: reusablePool?.mcpAliases.slice(0, 16) ?? [],
+ ...(candidateSearch?.truncated ? { truncated: true } : {}),
+ ...(candidateSearch?.cursor ? { cursor: candidateSearch.cursor } : {}),
+ ...(reusableRecipe ? { reusedFromRecipe: reusableRecipe.id } : {}),
+ } : undefined;
+ // A live seed pass validates reused paths. Do not merge stale path strings back in.
+ const candidatePool = discoveredPool ?? reusablePool;
+ return { search, reusablePool, candidateSearch, candidatePool };
+}
diff --git a/lib/os-api/http-adapter.test.ts b/lib/os-api/http-adapter.test.ts
index 1f87102e..9a888913 100644
--- a/lib/os-api/http-adapter.test.ts
+++ b/lib/os-api/http-adapter.test.ts
@@ -73,3 +73,32 @@ describe("HttpAdapter — managed apps", () => {
await expect(api.apps.power("hermes", "restart")).rejects.toThrow("managed application operation failed");
});
});
+
+
+describe("HttpAdapter — project candidates", () => {
+ const api = HttpAdapter({ url: "" });
+
+ it("uses the bounded read route and preserves cursor/truncation metadata", async () => {
+ const payload = {
+ project: { id: "root/mso", name: "mso", path: "/srv/mso" },
+ revision: "rev",
+ rebuilt: false,
+ reusedSeed: false,
+ indexedEntries: 12,
+ candidates: [{ path: "lib/workflow/replay.ts", kind: "path", size: 120, score: 1 }],
+ matches: [{ path: "lib/workflow/replay.ts", line: 10, preview: "bounded replay" }],
+ truncated: true,
+ truncationReasons: ["page"],
+ cursor: "next-page",
+ };
+ const f = mockFetch(payload);
+ const result = await api.projects.candidateSearch("root/mso", "bounded replay", 12, "cursor-1");
+ const url = String(f.mock.calls[0]?.[0] ?? "");
+ expect(url).toContain("/api/v1/projects/candidates?");
+ expect(url).toContain("project=root%2Fmso");
+ expect(url).toContain("q=bounded+replay");
+ expect(url).toContain("limit=12");
+ expect(url).toContain("cursor=cursor-1");
+ expect(result).toEqual(payload);
+ });
+});
diff --git a/lib/os-api/http-adapter.ts b/lib/os-api/http-adapter.ts
index 9b280559..370bbe5c 100644
--- a/lib/os-api/http-adapter.ts
+++ b/lib/os-api/http-adapter.ts
@@ -146,5 +146,15 @@ export function HttpAdapter(cfg: { url?: string; role?: Exclude<HostAccessRole,
status: () => req("GET", "/camoufox/service"),
power: (on) => req("POST", "/camoufox/service", { body: { action: on ? "start" : "stop" } }),
},
+ projects: {
+ candidateSearch: (project, query, limit = 16, cursor) => req("GET", "/projects/candidates", {
+ query: {
+ project,
+ q: query,
+ limit: String(Math.min(Math.max(Math.round(limit), 1), 40)),
+ ...(cursor ? { cursor } : {}),
+ },
+ }),
+ },
};
}
diff --git a/lib/os-api/mock-adapter.ts b/lib/os-api/mock-adapter.ts
index 7ccb696e..7a5ed7e1 100644
--- a/lib/os-api/mock-adapter.ts
+++ b/lib/os-api/mock-adapter.ts
@@ -103,5 +103,18 @@ export function MockAdapter(): OsApi {
status: () => delay({ installed: true, running: false, autostart: false }),
power: (on) => delay({ installed: true, running: on, autostart: false }, 400),
},
+ projects: {
+ candidateSearch: (project, query) => delay({
+ project: { id: `mock/${project || "demo"}`, name: project || "demo", path: `/mock/projects/${project || "demo"}` },
+ revision: "mock",
+ rebuilt: false,
+ reusedSeed: false,
+ indexedEntries: 1,
+ candidates: query ? [{ path: "src/demo.ts", kind: "path" as const, size: 128, score: 1 }] : [],
+ matches: query ? [{ path: "src/demo.ts", line: 1, preview: `mock candidate for ${query}` }] : [],
+ truncated: false,
+ truncationReasons: [],
+ }),
+ },
};
}
diff --git a/lib/os-api/types.ts b/lib/os-api/types.ts
index a189e1b0..64b44942 100644
--- a/lib/os-api/types.ts
+++ b/lib/os-api/types.ts
@@ -4,5 +4,6 @@ export type {
Unsub, HostAccessRole, HostAccess, SysStats, FsEntry, FsRoot, FsList, FsUsage, FsHit,
UploadFile, UploadResult, UploadProgress, ExecResult, Process, ServiceScope, ServiceAction,
SystemService, ServiceInventory, ServiceLogs, PackageUpdate, PackageUpdateSummary, AppManifest,
- ManagedAppSummary, ManagedAppAction, BrowserState, OsApi,
+ ManagedAppSummary, ManagedAppAction, BrowserState, ProjectCandidateRow, ProjectCandidateContentMatch,
+ ProjectCandidateSearchResult, OsApi,
} from "@/lib/contracts/os-api";
diff --git a/lib/workflow/candidate-pool.ts b/lib/workflow/candidate-pool.ts
new file mode 100644
index 00000000..48b7a47d
--- /dev/null
+++ b/lib/workflow/candidate-pool.ts
@@ -0,0 +1,75 @@
+import path from "node:path";
+import { safeMemoryText, sanitizeCandidatePool } from "./sanitize";
+import { safeReplayPathText } from "./replay-sanitize";
+import type { WorkflowCandidatePool, WorkflowReplayHandle, WorkflowStepInput } from "./types";
+
+const EMPTY = (): WorkflowCandidatePool => ({
+ version: 1,
+ paths: [],
+ skillIds: [],
+ connectionIds: [],
+ mcpAliases: [],
+});
+
+function addUnique(target: string[], value: string | undefined, max: number): void {
+ if (!value || target.includes(value) || target.length >= max) return;
+ target.push(value);
+}
+
+function candidatePath(value: unknown, project?: string): string | undefined {
+ if (typeof value !== "string" || !value.trim()) return undefined;
+ let safe = safeReplayPathText(value, 240)?.replace(/\\/g, "/");
+ if (!safe) return undefined;
+ if (project && path.isAbsolute(safe) && path.isAbsolute(project)) {
+ const rel = path.relative(project, safe).replace(/\\/g, "/");
+ if (!rel || rel.startsWith("../") || path.isAbsolute(rel)) return undefined;
+ safe = rel;
+ }
+ safe = safe.replace(/^\.\//, "");
+ if (!safe || safe.startsWith("../") || path.isAbsolute(safe) || safe.split("/").includes("..")) return undefined;
+ return safe.slice(0, 240);
+}
+
+function simpleId(value: unknown, max = 120): string | undefined {
+ if (typeof value !== "string") return undefined;
+ const safe = safeMemoryText(value, max);
+ if (!safe || safe.includes("[redacted]") || safe.includes("[opaque-id]")) return undefined;
+ if (!/^[A-Za-z0-9_.:@/-]+$/.test(safe)) return undefined;
+ return safe;
+}
+
+export function mergeCandidatePools(...values: Array<WorkflowCandidatePool | undefined>): WorkflowCandidatePool | undefined {
+ const out = EMPTY();
+ let seen = false;
+ for (const value of values) {
+ const pool = sanitizeCandidatePool(value);
+ if (!pool) continue;
+ seen = true;
+ out.revision ??= pool.revision;
+ out.reusedFromRecipe ??= pool.reusedFromRecipe;
+ out.truncated = out.truncated === true || pool.truncated === true || undefined;
+ out.cursor ??= pool.cursor;
+ for (const item of pool.paths) addUnique(out.paths, item, 24);
+ for (const item of pool.skillIds) addUnique(out.skillIds, item, 16);
+ for (const item of pool.connectionIds) addUnique(out.connectionIds, item, 16);
+ for (const item of pool.mcpAliases) addUnique(out.mcpAliases, item, 16);
+ }
+ return seen ? out : undefined;
+}
+
+export function candidatePoolFromStep(
+ step: WorkflowStepInput,
+ project?: string,
+ replay: WorkflowReplayHandle[] = [],
+): WorkflowCandidatePool | undefined {
+ const out = EMPTY();
+ const args = step.args ?? {};
+ for (const key of ["path", "from", "to", "cwd"]) addUnique(out.paths, candidatePath(args[key], project), 24);
+ for (const handle of replay) {
+ if (handle.kind === "file") addUnique(out.paths, candidatePath(handle.path, project), 24);
+ }
+ if (step.tool === "skills_read") addUnique(out.skillIds, simpleId(args.name, 240), 16);
+ addUnique(out.connectionIds, simpleId(args.connection), 16);
+ if (step.tool.startsWith("project_mcp_")) addUnique(out.mcpAliases, simpleId(args.server), 16);
+ return out.paths.length || out.skillIds.length || out.connectionIds.length || out.mcpAliases.length ? out : undefined;
+}
diff --git a/lib/workflow/index.ts b/lib/workflow/index.ts
index 3c745127..df10972c 100644
--- a/lib/workflow/index.ts
+++ b/lib/workflow/index.ts
@@ -1,11 +1,13 @@
export { startWorkflow, activeWorkflowForActor, recordWorkflowStep, cancelWorkflow } from "./lifecycle";
export { summarizeProjectContention, countActiveWorkflowsForProject } from "./contention";
-export { finishWorkflow, listLearnedRecipes, listArchivedRecipes, markRecipeUsed } from "./learning";
+export { finishWorkflow, findReusableRecipe, listLearnedRecipes, listArchivedRecipes, markRecipeUsed } from "./learning";
export { resetWorkflowStoreCache } from "./storage";
export { summarizeWorkflowQuality } from "./quality";
export { recipeMaturity } from "./maturity";
export { workflowStepProvenance } from "./session-provenance";
+export { replayHandlesFromResult } from "./replay";
+export { mergeCandidatePools } from "./candidate-pool";
export type {
- WorkflowStepState, WorkflowStep, WorkflowStepProvenance, RecipeMaturity, ActiveWorkflow, WorkflowQuality, LearnedRecipe,
+ WorkflowStepState, WorkflowStep, WorkflowStepProvenance, WorkflowReplayHandle, WorkflowCandidatePool, RecipeMaturity, ActiveWorkflow, WorkflowQuality, LearnedRecipe,
FinishWorkflowResult, CancelWorkflowResult, RecipeAccess, ProjectContentionSummary,
} from "./types";
diff --git a/lib/workflow/learning.ts b/lib/workflow/learning.ts
index fae2c831..4fab7304 100644
--- a/lib/workflow/learning.ts
+++ b/lib/workflow/learning.ts
@@ -1,6 +1,6 @@
import { createHash, randomUUID } from "node:crypto";
import { allows } from "@/lib/capabilities/scope";
-import { embedSkillText, normalizeSemanticText, SKILL_EMBEDDING_VERSION } from "@/lib/skills/semantic";
+import { embedSkillText, hybridSemanticScore, normalizeSemanticText, SKILL_EMBEDDING_VERSION } from "@/lib/skills/semantic";
import { compactRecipeSteps, elapsedMs, enrichBestSteps, mergeQuality, summarizeWorkflowQuality } from "./quality";
import { closestRecipe, recipeText } from "./recipes";
import { safeMemoryText } from "./sanitize";
@@ -9,6 +9,7 @@ import { loadWorkflowStore, persistWorkflowStore } from "./storage";
import type { FinishWorkflowResult, LearnedRecipe, RecipeAccess, WorkflowStepProvenance } from "./types";
import { ensureLearnedWorkflowGraph } from "./graph-store";
import { archiveLearnedRecipes, listArchivedLearnedRecipes } from "./recipe-archive";
+import { mergeCandidatePools } from "./candidate-pool";
import { rememberAgentMemory } from "@/lib/agent/memory-store";
export async function finishWorkflow(input: {
@@ -43,6 +44,9 @@ export async function finishWorkflow(input: {
const successes = existing.successes + (input.success ? 1 : 0);
const failures = existing.failures + (input.success ? 0 : 1);
const faster = input.success && (existing.fastestDurationMs == null || durationMs < existing.fastestDurationMs);
+ const candidatePool = input.success
+ ? mergeCandidatePools(existing.candidatePool, workflow.candidatePool)
+ : existing.candidatePool;
recipe = {
...existing,
actor: recipeOwner,
@@ -55,6 +59,7 @@ export async function finishWorkflow(input: {
embedding: vector,
lastSteps: learnedSteps,
bestSteps: faster ? compactSteps : (input.success ? enrichBestSteps(existing.bestSteps, compactSteps) : existing.bestSteps),
+ ...(candidatePool ? { candidatePool } : {}),
attempts,
successes,
failures,
@@ -74,6 +79,7 @@ export async function finishWorkflow(input: {
normalizedIntent: normalizeSemanticText(workflow.intent), project: workflow.project, summary,
embeddingVersion: SKILL_EMBEDDING_VERSION, embedding: vector,
bestSteps: input.success ? compactSteps : [], lastSteps: learnedSteps,
+ ...(input.success && workflow.candidatePool ? { candidatePool: workflow.candidatePool } : {}),
attempts: 1, successes: input.success ? 1 : 0, failures: input.success ? 0 : 1,
averageDurationMs: durationMs, fastestDurationMs: input.success ? durationMs : undefined, lastDurationMs: durationMs,
averageWallDurationMs: wallMs, lastWallDurationMs: wallMs,
@@ -119,6 +125,30 @@ export async function finishWorkflow(input: {
};
}
+
+
+export async function findReusableRecipe(input: {
+ actor: string;
+ scope: import("@/lib/capabilities/scope").Scope;
+ intent: string;
+ project?: string;
+}): Promise<LearnedRecipe | undefined> {
+ const store = await loadWorkflowStore();
+ const prepared = recipeText(input.intent, input.project);
+ let best: { recipe: LearnedRecipe; score: number } | undefined;
+ for (const recipe of Object.values(store.recipes)) {
+ if (recipe.actor !== input.actor || !allows(input.scope, recipe.scope) || recipe.successes < 1 || !recipe.candidatePool) continue;
+ if ((recipe.project ?? "") !== (input.project ?? "")) continue;
+ const score = hybridSemanticScore(
+ prepared,
+ recipeText(recipe.intent, recipe.project, recipe.summary),
+ recipe.embeddingVersion === SKILL_EMBEDDING_VERSION ? recipe.embedding : undefined,
+ ) + (recipe.normalizedIntent === normalizeSemanticText(input.intent) ? 0.2 : 0);
+ if (!best || score > best.score) best = { recipe, score };
+ }
+ return best && best.score >= 0.48 ? best.recipe : undefined;
+}
+
export async function listLearnedRecipes(access: RecipeAccess): Promise<LearnedRecipe[]> {
const store = await loadWorkflowStore();
const recipes = Object.values(store.recipes);
diff --git a/lib/workflow/lifecycle.ts b/lib/workflow/lifecycle.ts
index 89cd8c73..0e55af34 100644
--- a/lib/workflow/lifecycle.ts
+++ b/lib/workflow/lifecycle.ts
@@ -1,10 +1,11 @@
import { randomUUID } from "node:crypto";
import type { Scope } from "@/lib/capabilities/scope";
import type { WorkflowOrchestrationSnapshot } from "@/lib/contracts/orchestration";
-import { safeMemoryText, sanitizeOrchestration, sanitizeStoredStep } from "./sanitize";
+import { safeMemoryText, sanitizeCandidatePool, sanitizeOrchestration, sanitizeStoredStep } from "./sanitize";
+import { candidatePoolFromStep, mergeCandidatePools } from "./candidate-pool";
import { actorKey, pruneStaleWorkflows, removeActiveWorkflow, workflowFor } from "./state";
import { loadWorkflowStore, persistWorkflowStore } from "./storage";
-import type { ActiveWorkflow, CancelWorkflowResult, WorkflowStepInput } from "./types";
+import type { ActiveWorkflow, CancelWorkflowResult, WorkflowCandidatePool, WorkflowStepInput } from "./types";
const MAX_ACTIVE_PER_ACTOR = 20;
@@ -15,6 +16,7 @@ export async function startWorkflow(input: {
project?: string;
constraints?: string;
orchestration?: WorkflowOrchestrationSnapshot;
+ candidatePool?: WorkflowCandidatePool;
}): Promise<{ workflow: ActiveWorkflow; activeWorkflowCount: number }> {
const actor = actorKey(input.actor);
const scope: Scope = input.scope ?? "read";
@@ -30,6 +32,7 @@ export async function startWorkflow(input: {
project: input.project ? safeMemoryText(input.project, 240) || undefined : undefined,
constraints: input.constraints ? safeMemoryText(input.constraints, 500) || undefined : undefined,
orchestration: sanitizeOrchestration(input.orchestration),
+ ...(sanitizeCandidatePool(input.candidatePool) ? { candidatePool: sanitizeCandidatePool(input.candidatePool) } : {}),
startedAt: new Date().toISOString(), steps: [],
};
(store.active[actor] ??= {})[workflow.id] = workflow;
@@ -55,6 +58,10 @@ export async function recordWorkflowStep(actor: string | undefined, workflowId:
const sanitized = sanitizeStoredStep(step);
if (!sanitized) return;
workflow.steps.push(sanitized);
+ workflow.candidatePool = mergeCandidatePools(
+ workflow.candidatePool,
+ candidatePoolFromStep(step, workflow.project, sanitized.replay ?? []),
+ );
if (workflow.steps.length > 300) workflow.steps.splice(0, workflow.steps.length - 300);
await persistWorkflowStore(store, true);
}
diff --git a/lib/workflow/replay-candidate.test.ts b/lib/workflow/replay-candidate.test.ts
new file mode 100644
index 00000000..f72d320f
--- /dev/null
+++ b/lib/workflow/replay-candidate.test.ts
@@ -0,0 +1,156 @@
+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-replay-candidate-"));
+process.env.OS_SKILL_MEMORY_STORE = path.join(dir, "memory.json");
+const memory = await import("./index");
+
+describe("bounded replay and workflow candidate reuse", () => {
+ beforeEach(async () => {
+ await fs.rm(process.env.OS_SKILL_MEMORY_STORE!, { force: true });
+ memory.resetWorkflowStoreCache();
+ });
+ afterAll(async () => {
+ await fs.rm(dir, { recursive: true, force: true });
+ });
+
+ it("extracts only durable replay handles and never result bodies", () => {
+ const sha256 = "a".repeat(64);
+ const handles = memory.replayHandlesFromResult({
+ path: "/repo/lib/a.ts",
+ sha256,
+ content: "token=raw-secret must-not-persist",
+ job_id: "job_123",
+ artifact_id: "artifact_123",
+ nextCursor: "cursor_123",
+ truncated: true,
+ });
+ expect(handles).toEqual(expect.arrayContaining([
+ expect.objectContaining({ kind: "file", path: "/repo/lib/a.ts", sha256, truncated: true, rereadWith: "read_pipeline" }),
+ expect.objectContaining({ kind: "job", jobId: "job_123", rereadWith: "exec_job_status" }),
+ expect.objectContaining({ kind: "artifact", artifactId: "artifact_123", rereadWith: "session_artifacts" }),
+ ]));
+ expect(JSON.stringify(handles)).not.toContain("raw-secret");
+ expect(handles.length).toBeLessThanOrEqual(6);
+
+ const hashedPath = `/repo/cache/${"f".repeat(64)}.json`;
+ const exact = memory.replayHandlesFromResult({ path: hashedPath, sha256 });
+ const startedPath = memory.startWorkflow({
+ actor: "mcp:path-hash", scope: "read", intent: "retain content addressed path", project: "/repo",
+ });
+ expect(exact[0]).toMatchObject({ path: hashedPath });
+ return startedPath.then(async ({ workflow }) => {
+ await memory.recordWorkflowStep("mcp:path-hash", workflow.id, {
+ id: "hash-read", tool: "fs_read", state: "completed", args: { path: hashedPath }, replay: exact,
+ ts: new Date().toISOString(),
+ });
+ const active = await memory.activeWorkflowForActor("mcp:path-hash", workflow.id);
+ expect(active?.steps[0]?.replay?.[0]?.path).toBe(hashedPath);
+ await memory.cancelWorkflow({ actor: "mcp:path-hash", workflowId: workflow.id });
+ });
+ });
+
+ it("does not let a failed run poison a previously successful reusable pool", async () => {
+ const good = await memory.startWorkflow({
+ actor: "mcp:pool-quality", scope: "write", intent: "update bounded replay", project: "/repo",
+ candidatePool: { version: 1, paths: ["lib/good.ts"], skillIds: [], connectionIds: [], mcpAliases: [] },
+ });
+ const first = await memory.finishWorkflow({
+ actor: "mcp:pool-quality", workflowId: good.workflow.id, summary: "verified", success: true,
+ });
+ expect(first.recipe.candidatePool?.paths).toEqual(["lib/good.ts"]);
+
+ const failed = await memory.startWorkflow({
+ actor: "mcp:pool-quality", scope: "write", intent: "update bounded replay", project: "/repo",
+ candidatePool: { version: 1, paths: ["lib/bad-attempt.ts"], skillIds: [], connectionIds: [], mcpAliases: [] },
+ });
+ const second = await memory.finishWorkflow({
+ actor: "mcp:pool-quality", workflowId: failed.workflow.id, summary: "failed verification", success: false,
+ });
+ expect(second.recipe.candidatePool?.paths).toEqual(["lib/good.ts"]);
+ expect(JSON.stringify(second.recipe.candidatePool)).not.toContain("bad-attempt");
+ });
+
+ it("persists a bounded redacted candidate pool with a recipe and reuses it only for the same owner/scope/project", async () => {
+ const started = await memory.startWorkflow({
+ actor: "mcp:owner-a",
+ scope: "exec",
+ intent: "update workflow replay handling",
+ project: "/repo",
+ candidatePool: {
+ version: 1,
+ revision: "rev-1",
+ paths: ["lib/workflow/start.ts"],
+ skillIds: ["mso-repo-work"],
+ connectionIds: [],
+ mcpAliases: [],
+ },
+ });
+ await memory.recordWorkflowStep("mcp:owner-a", started.workflow.id, {
+ id: "read",
+ tool: "fs_read",
+ state: "completed",
+ target: "/repo/lib/workflow/replay.ts",
+ args: { path: "/repo/lib/workflow/replay.ts" },
+ replay: [{
+ kind: "file",
+ path: "/repo/lib/workflow/replay.ts",
+ sha256: "b".repeat(64),
+ rereadWith: "read_pipeline",
+ }],
+ ts: new Date().toISOString(),
+ });
+ await memory.recordWorkflowStep("mcp:owner-a", started.workflow.id, {
+ id: "skill",
+ tool: "skills_read",
+ state: "completed",
+ args: { name: "mso-mcp-feature-engineering" },
+ ts: new Date().toISOString(),
+ });
+ await memory.recordWorkflowStep("mcp:owner-a", started.workflow.id, {
+ id: "mcp",
+ tool: "project_mcp_tools",
+ state: "completed",
+ args: { project: "mso", server: "si-coder" },
+ ts: new Date().toISOString(),
+ });
+ await memory.recordWorkflowStep("mcp:owner-a", started.workflow.id, {
+ id: "connection",
+ tool: "integration_query",
+ state: "completed",
+ args: { connection: "github-main", provider: "github", token: "must-not-persist" },
+ ts: new Date().toISOString(),
+ });
+
+ const done = await memory.finishWorkflow({
+ actor: "mcp:owner-a",
+ workflowId: started.workflow.id,
+ summary: "verified",
+ success: true,
+ });
+ expect(done.recipe.candidatePool).toMatchObject({
+ version: 1,
+ paths: expect.arrayContaining(["lib/workflow/start.ts", "lib/workflow/replay.ts"]),
+ skillIds: expect.arrayContaining(["mso-repo-work", "mso-mcp-feature-engineering"]),
+ connectionIds: ["github-main"],
+ mcpAliases: ["si-coder"],
+ });
+ expect(JSON.stringify(done.recipe)).not.toContain("must-not-persist");
+
+ const same = await memory.findReusableRecipe({
+ actor: "mcp:owner-a", scope: "exec", intent: "update workflow replay handling", project: "/repo",
+ });
+ expect(same?.id).toBe(done.recipe.id);
+ await expect(memory.findReusableRecipe({
+ actor: "mcp:owner-b", scope: "exec", intent: "update workflow replay handling", project: "/repo",
+ })).resolves.toBeUndefined();
+ await expect(memory.findReusableRecipe({
+ actor: "mcp:owner-a", scope: "read", intent: "update workflow replay handling", project: "/repo",
+ })).resolves.toBeUndefined();
+ await expect(memory.findReusableRecipe({
+ actor: "mcp:owner-a", scope: "exec", intent: "update workflow replay handling", project: "/other",
+ })).resolves.toBeUndefined();
+ });
+});
diff --git a/lib/workflow/replay-sanitize.ts b/lib/workflow/replay-sanitize.ts
new file mode 100644
index 00000000..6ac2c113
--- /dev/null
+++ b/lib/workflow/replay-sanitize.ts
@@ -0,0 +1,111 @@
+import os from "node:os";
+import path from "node:path";
+import type { WorkflowCandidatePool, WorkflowReplayHandle } from "./types";
+
+function secretSafeText(value: string, max: number): string {
+ const out = value
+ .replace(/([?&](?:token|key|secret|password|code)=)[^&\s]+/gi, "$1[redacted]")
+ .replace(/\b(password|token|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[redacted]")
+ .replace(/\b(?:bearer\s+)?(?:sk|pk|ghp|mso_mcp)_[a-z0-9_-]{8,}\b/gi, "[redacted]")
+ .trim();
+ return out.length > max ? `${out.slice(0, max)}…` : out;
+}
+
+export function safeReplayPathText(value: unknown, max = 240): string | undefined {
+ if (typeof value !== "string" || !value.trim()) return undefined;
+ const safe = secretSafeText(value, max);
+ return safe && !safe.includes("[redacted]") ? safe : undefined;
+}
+
+function replayPath(value: unknown): string | undefined {
+ let out = safeReplayPathText(value, 240);
+ if (!out) return undefined;
+ const home = os.homedir();
+ if (out === home) out = "~";
+ else if (out.startsWith(`${home}${path.sep}`)) out = `~${out.slice(home.length)}`;
+ return out.length > 160 ? `${out.slice(0, 160)}…` : out;
+}
+export function safeMemoryText(value: string, max: number): string {
+ const out = value
+ .replace(/([?&](?:token|key|secret|password|code)=)[^&\s]+/gi, "$1[redacted]")
+ .replace(/\b(password|token|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[redacted]")
+ .replace(/\b(?:bearer\s+)?(?:sk|pk|ghp|mso_mcp)_[a-z0-9_-]{8,}\b/gi, "[redacted]")
+ .replace(/\b[a-f0-9]{48,}\b/gi, "[opaque-id]")
+ .trim();
+ return out.length > max ? `${out.slice(0, max)}…` : out;
+}
+
+export function sanitizeReplayHandles(value: unknown): WorkflowReplayHandle[] | undefined {
+ if (!Array.isArray(value)) return undefined;
+ const out: WorkflowReplayHandle[] = [];
+ for (const item of value.slice(0, 6)) {
+ if (!item || typeof item !== "object") continue;
+ const row = item as Partial<WorkflowReplayHandle>;
+ const kind = row.kind;
+ if (kind !== "file" && kind !== "job" && kind !== "artifact" && kind !== "cursor") continue;
+ const pathValue = replayPath(row.path);
+ const sha256 = typeof row.sha256 === "string" && /^[a-f0-9]{64}$/i.test(row.sha256) ? row.sha256.toLowerCase() : undefined;
+ const jobId = typeof row.jobId === "string" && /^[A-Za-z0-9_.:@/-]{1,160}$/.test(row.jobId) ? row.jobId : undefined;
+ const artifactId = typeof row.artifactId === "string" && /^[A-Za-z0-9_.:@/-]{1,160}$/.test(row.artifactId) ? row.artifactId : undefined;
+ const cursor = typeof row.cursor === "string" ? safeMemoryText(row.cursor, 512) : undefined;
+ const rereadWith = row.rereadWith === "fs_read" || row.rereadWith === "read_pipeline" || row.rereadWith === "exec_job_status" ||
+ row.rereadWith === "session_artifacts" || row.rereadWith === "project_candidate_search" ? row.rereadWith : undefined;
+ if (kind === "file" && !pathValue) continue;
+ if (kind === "job" && !jobId) continue;
+ if (kind === "artifact" && !artifactId) continue;
+ if (kind === "cursor" && !cursor) continue;
+ out.push({
+ kind,
+ ...(pathValue ? { path: pathValue } : {}),
+ ...(sha256 ? { sha256 } : {}),
+ ...(jobId ? { jobId } : {}),
+ ...(artifactId ? { artifactId } : {}),
+ ...(cursor ? { cursor } : {}),
+ ...(row.truncated === true ? { truncated: true } : {}),
+ ...(rereadWith ? { rereadWith } : {}),
+ });
+ }
+ return out.length ? out : undefined;
+}
+
+export function sanitizeCandidatePool(value: unknown): WorkflowCandidatePool | undefined {
+ if (!value || typeof value !== "object") return undefined;
+ const row = value as Partial<WorkflowCandidatePool>;
+ const unique = (candidate: unknown, maxItems: number, maxLen: number) => {
+ if (!Array.isArray(candidate)) return [] as string[];
+ const out: string[] = [];
+ for (const item of candidate) {
+ if (typeof item !== "string") continue;
+ const safe = safeMemoryText(item, maxLen);
+ if (!safe || safe.includes("[redacted]") || safe.includes("[opaque-id]") || out.includes(safe)) continue;
+ out.push(safe);
+ if (out.length >= maxItems) break;
+ }
+ return out;
+ };
+ const paths = Array.isArray(row.paths)
+ ? [...new Set(row.paths
+ .map((item) => safeReplayPathText(item, 240))
+ .filter((item): item is string => Boolean(item))
+ .map((item) => item.replace(/\\/g, "/").replace(/^\.\//, ""))
+ .filter((item) => item && !path.isAbsolute(item) && !item.startsWith("../") && !item.split("/").includes("..")))]
+ .slice(0, 24)
+ : [];
+ const skillIds = unique(row.skillIds, 16, 240);
+ const connectionIds = unique(row.connectionIds, 16, 120).filter((item) => /^[A-Za-z0-9_.:@/-]+$/.test(item));
+ const mcpAliases = unique(row.mcpAliases, 16, 120).filter((item) => /^[A-Za-z0-9_.:@/-]+$/.test(item));
+ const revision = typeof row.revision === "string" ? safeMemoryText(row.revision, 160) : undefined;
+ const cursor = typeof row.cursor === "string" ? safeMemoryText(row.cursor, 512) : undefined;
+ const reusedFromRecipe = typeof row.reusedFromRecipe === "string" ? safeMemoryText(row.reusedFromRecipe, 120) : undefined;
+ return {
+ version: 1,
+ paths,
+ skillIds,
+ connectionIds,
+ mcpAliases,
+ ...(revision ? { revision } : {}),
+ ...(row.truncated === true ? { truncated: true } : {}),
+ ...(cursor ? { cursor } : {}),
+ ...(reusedFromRecipe ? { reusedFromRecipe } : {}),
+ };
+}
diff --git a/lib/workflow/replay.ts b/lib/workflow/replay.ts
new file mode 100644
index 00000000..5a04711d
--- /dev/null
+++ b/lib/workflow/replay.ts
@@ -0,0 +1,70 @@
+import type { WorkflowReplayHandle } from "./types";
+
+const MAX_HANDLES = 6;
+const MAX_NODES = 96;
+
+function text(value: unknown, max = 512): string | undefined {
+ if (typeof value !== "string") return undefined;
+ const out = value.trim();
+ return out ? out.slice(0, max) : undefined;
+}
+
+function pushUnique(out: WorkflowReplayHandle[], handle: WorkflowReplayHandle): void {
+ const key = JSON.stringify(handle);
+ if (!out.some((row) => JSON.stringify(row) === key)) out.push(handle);
+}
+
+export function replayHandlesFromResult(result: unknown): WorkflowReplayHandle[] {
+ const out: WorkflowReplayHandle[] = [];
+ let nodes = 0;
+
+ const visit = (value: unknown, depth: number): void => {
+ if (out.length >= MAX_HANDLES || nodes >= MAX_NODES || depth > 3 || value == null) return;
+ nodes += 1;
+ if (Array.isArray(value)) {
+ for (const item of value.slice(0, 16)) visit(item, depth + 1);
+ return;
+ }
+ if (typeof value !== "object") return;
+ const row = value as Record<string, unknown>;
+ const path = text(row.path, 512);
+ const sha256 = text(row.sha256, 80);
+ const cursor = text(row.cursor, 512) ?? text(row.nextCursor, 512);
+ const truncated = row.truncated === true || row.msoTruncated === true;
+
+ if (path) {
+ pushUnique(out, {
+ kind: "file",
+ path,
+ ...(sha256 && /^[a-f0-9]{64}$/i.test(sha256) ? { sha256: sha256.toLowerCase() } : {}),
+ ...(truncated ? { truncated: true } : {}),
+ ...(cursor ? { cursor } : {}),
+ rereadWith: "read_pipeline",
+ });
+ }
+
+ const jobId = text(row.job_id, 160) ?? text(row.jobId, 160);
+ if (jobId) pushUnique(out, { kind: "job", jobId, rereadWith: "exec_job_status" });
+
+ const artifactId = text(row.artifact_id, 160) ?? text(row.artifactId, 160);
+ if (artifactId) pushUnique(out, { kind: "artifact", artifactId, rereadWith: "session_artifacts" });
+
+ if (!path && cursor) {
+ pushUnique(out, {
+ kind: "cursor",
+ cursor,
+ ...(truncated ? { truncated: true } : {}),
+ rereadWith: "project_candidate_search",
+ });
+ }
+
+ for (const [key, child] of Object.entries(row)) {
+ if (["content", "stdout", "stderr", "text", "body", "data", "buffer", "bytes"].includes(key)) continue;
+ if (typeof child === "object" && child !== null) visit(child, depth + 1);
+ if (out.length >= MAX_HANDLES || nodes >= MAX_NODES) break;
+ }
+ };
+
+ visit(result, 0);
+ return out.slice(0, MAX_HANDLES);
+}
diff --git a/lib/workflow/sanitize.ts b/lib/workflow/sanitize.ts
index f4172291..0f0c8744 100644
--- a/lib/workflow/sanitize.ts
+++ b/lib/workflow/sanitize.ts
@@ -13,16 +13,8 @@ import type {
WorkflowStepProvenance,
} from "./types";
-export function safeMemoryText(value: string, max: number): string {
- const out = value
- .replace(/([?&](?:token|key|secret|password|code)=)[^&\s]+/gi, "$1[redacted]")
- .replace(/\b(password|token|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[redacted]")
- .replace(/\b(?:bearer\s+)?(?:sk|pk|ghp|mso_mcp)_[a-z0-9_-]{8,}\b/gi, "[redacted]")
- .replace(/\b[a-f0-9]{48,}\b/gi, "[opaque-id]")
- .trim();
- return out.length > max ? `${out.slice(0, max)}…` : out;
-}
-
+import { safeMemoryText, sanitizeCandidatePool, sanitizeReplayHandles } from "./replay-sanitize";
+export { safeMemoryText, sanitizeCandidatePool, sanitizeReplayHandles } from "./replay-sanitize";
export function sanitizeOrchestration(value: unknown): WorkflowOrchestrationSnapshot | undefined {
if (!value || typeof value !== "object") return undefined;
const row = value as Partial<WorkflowOrchestrationSnapshot>;
@@ -139,6 +131,7 @@ export function sanitizeStoredStep(value: unknown): WorkflowStep | null {
target: safeTarget(row.tool, row.target), args: safeArgs(row.tool, row.args),
...(durationMs != null ? { durationMs } : {}),
ts: Number.isFinite(Date.parse(row.ts)) ? new Date(row.ts).toISOString() : new Date(0).toISOString(),
+ ...(sanitizeReplayHandles(row.replay) ? { replay: sanitizeReplayHandles(row.replay) } : {}),
...(safeProvenance(row.provenance) ? { provenance: safeProvenance(row.provenance) } : {}),
};
}
@@ -161,6 +154,7 @@ export function normalizeActive(value: unknown): ActiveWorkflowBuckets {
project: candidate.project ? safeMemoryText(candidate.project, 240) || undefined : undefined,
constraints: candidate.constraints ? safeMemoryText(candidate.constraints, 500) || undefined : undefined,
orchestration: sanitizeOrchestration(candidate.orchestration),
+ ...(sanitizeCandidatePool(candidate.candidatePool) ? { candidatePool: sanitizeCandidatePool(candidate.candidatePool) } : {}),
steps: candidate.steps.map(sanitizeStoredStep).filter((step): step is WorkflowStep => Boolean(step)),
};
continue;
@@ -174,6 +168,7 @@ export function normalizeActive(value: unknown): ActiveWorkflowBuckets {
project: workflow.project ? safeMemoryText(workflow.project, 240) || undefined : undefined,
constraints: workflow.constraints ? safeMemoryText(workflow.constraints, 500) || undefined : undefined,
orchestration: sanitizeOrchestration(workflow.orchestration),
+ ...(sanitizeCandidatePool(workflow.candidatePool) ? { candidatePool: sanitizeCandidatePool(workflow.candidatePool) } : {}),
steps: workflow.steps.map(sanitizeStoredStep).filter((step): step is WorkflowStep => Boolean(step)),
};
}
@@ -197,6 +192,7 @@ export function normalizeRecipes(value: unknown): Record<string, LearnedRecipe>
summary: safeMemoryText(typeof row.summary === "string" ? row.summary : "completed", 1200) || "completed",
bestSteps: row.bestSteps.map(sanitizeStoredStep).filter((step): step is WorkflowStep => Boolean(step)),
lastSteps: Array.isArray(row.lastSteps) ? row.lastSteps.map(sanitizeStoredStep).filter((step): step is WorkflowStep => Boolean(step)) : [],
+ ...(sanitizeCandidatePool(row.candidatePool) ? { candidatePool: sanitizeCandidatePool(row.candidatePool) } : {}),
quality: normalizeQuality(row.quality), lastQuality: normalizeQuality(row.lastQuality),
...(row.qualityVersion === 1 ? { qualityVersion: 1 as const } : {}),
};
diff --git a/lib/workflow/types.ts b/lib/workflow/types.ts
index 49f26ccf..fba19844 100644
--- a/lib/workflow/types.ts
+++ b/lib/workflow/types.ts
@@ -4,6 +4,29 @@ import type { WorkflowOrchestrationSnapshot } from "@/lib/contracts/orchestratio
export type WorkflowStepState = "completed" | "failed" | "denied" | "rate_limited" | "invalid_args";
export type RecipeMaturity = "observed" | "candidate" | "verified";
+export type WorkflowReplayHandle = {
+ kind: "file" | "job" | "artifact" | "cursor";
+ path?: string;
+ sha256?: string;
+ jobId?: string;
+ artifactId?: string;
+ cursor?: string;
+ truncated?: boolean;
+ rereadWith?: "fs_read" | "read_pipeline" | "exec_job_status" | "session_artifacts" | "project_candidate_search";
+};
+
+export type WorkflowCandidatePool = {
+ version: 1;
+ revision?: string;
+ paths: string[];
+ skillIds: string[];
+ connectionIds: string[];
+ mcpAliases: string[];
+ truncated?: boolean;
+ cursor?: string;
+ reusedFromRecipe?: string;
+};
+
export type WorkflowStepProvenance = {
/** Human-readable session label only; internal session ids never enter learned recipes. */
sessionLabel: string;
@@ -22,6 +45,7 @@ export type WorkflowStep = {
args?: Record<string, string | number | boolean>;
durationMs?: number;
ts: string;
+ replay?: WorkflowReplayHandle[];
provenance?: WorkflowStepProvenance;
};
@@ -35,6 +59,7 @@ export type ActiveWorkflow = {
project?: string;
constraints?: string;
orchestration?: WorkflowOrchestrationSnapshot;
+ candidatePool?: WorkflowCandidatePool;
startedAt: string;
steps: WorkflowStep[];
};
@@ -57,6 +82,7 @@ export type LearnedRecipe = {
embedding: number[];
bestSteps: WorkflowStep[];
lastSteps: WorkflowStep[];
+ candidatePool?: WorkflowCandidatePool;
attempts: number;
successes: number;
failures: number;
diff --git a/scripts/cli/commands-host.sh b/scripts/cli/commands-host.sh
index 072226b4..468ad30a 100755
--- a/scripts/cli/commands-host.sh
+++ b/scripts/cli/commands-host.sh
@@ -18,6 +18,11 @@ case "$cmd" in
share) reqraw "$B/api/v1/temp-share/$(enc "${1:?temporary link id}")?download=1"; exit 0 ;;
usage) jget "/api/v1/fs/usage?path=$(enc "${1:-~}")" ;;
search) jget "/api/v1/fs/search?q=$(enc "${1:?query}")${2:+"&root=$(enc "$2")"}" ;;
+ project-candidates)
+ project="${1:?project}"; query="${2:?query}"; limit="${3:-16}"; cursor="${4:-}"
+ case "$limit" in (*[!0-9]*|'') die "limit must be an integer from 1 to 40" ;; esac
+ [ "$limit" -ge 1 ] && [ "$limit" -le 40 ] || die "limit must be an integer from 1 to 40"
+ jget "/api/v1/projects/candidates?project=$(enc "$project")&q=$(enc "$query")&limit=$(enc "$limit")${cursor:+"&cursor=$(enc "$cursor")"}" ;;
write) jpost "/api/v1/fs/write" "$(jq -n --arg p "${1:?path}" --arg c "${2-}" '{path:$p,content:$c}')" ;;
mkdir) jpost "/api/v1/fs/mkdir" "$(jq -n --arg p "${1:?path}" '{path:$p}')" ;;
rm) jdel "/api/v1/fs/delete" "$(jq -n --arg p "${1:?path}" '{path:$p}')" ;;
diff --git a/scripts/cli/commands.sh b/scripts/cli/commands.sh
index b2c32f0a..ae3819a5 100755
--- a/scripts/cli/commands.sh
+++ b/scripts/cli/commands.sh
@@ -91,7 +91,7 @@ mso_cli_main() {
if [ "$cmd" = agent ] || [ "$cmd" = chat ]; then set -- "${AGENT_START_ARGS[@]}" "$@"; fi
case "$cmd" in
- version|--version|-V|-v|ls|cat|raw|share|usage|search|write|mkdir|rm|mv|cp|zip|upload|exec|stats|ps|units|unit|packages|cleanup|status|health|doctor)
+ version|--version|-V|-v|ls|cat|raw|share|usage|search|project-candidates|write|mkdir|rm|mv|cp|zip|upload|exec|stats|ps|units|unit|packages|cleanup|status|health|doctor)
mso_cmd_host "$cmd" "$@" ;;
agent|chat|model|setup|onboard|provider|providers|integrations|flow|workflow|gateway|web|camoufox|apps|mapp|term)
mso_cmd_runtime "$cmd" "$@" ;;
diff --git a/scripts/mso-agent-context.mjs b/scripts/mso-agent-context.mjs
index 817d04c2..5d379d63 100644
--- a/scripts/mso-agent-context.mjs
+++ b/scripts/mso-agent-context.mjs
@@ -8,6 +8,131 @@ function estimateContextTokens(value) {
return Math.ceil(Buffer.byteLength(raw, "utf8") / 4);
}
+
+const MAX_REPLAY_HANDLES = 4;
+const MAX_REPLAY_SCAN_NODES = 64;
+
+function compactId(value, max = 512) {
+ if (typeof value !== "string") return "";
+ return value.trim().replace(/[\r\n\t]+/g, " ").slice(0, max);
+}
+
+function compactReplayPath(value, max = 512) {
+ const clean = compactId(value, max)
+ .replace(/([?&](?:token|key|secret|password|code)=)[^&\s]+/gi, "$1[redacted]")
+ .replace(/\b(password|token|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[redacted]")
+ .replace(/\b(?:bearer\s+)?(?:sk|pk|ghp|mso_mcp)_[a-z0-9_-]{8,}\b/gi, "[redacted]");
+ return clean.includes("[redacted]") ? "" : clean;
+}
+
+function replayHandleKey(handle) {
+ try { return JSON.stringify(handle); } catch { return String(handle?.kind || ""); }
+}
+
+function replayHandleFromCall(call) {
+ const input = call?.input && typeof call.input === "object" ? call.input : {};
+ const name = String(call?.name || "");
+ if (typeof input.path === "string" && input.path.trim()) {
+ return compactReplayPath(input.path) ? { kind: "file", path: compactReplayPath(input.path), rereadWith: name === "fs_read" ? "read_pipeline" : name } : null;
+ }
+ const jobId = compactId(input.job_id ?? input.jobId, 160);
+ if (jobId) return { kind: "job", jobId, rereadWith: "exec_job_status" };
+ const artifactId = compactId(input.artifact_id ?? input.artifactId, 160);
+ if (artifactId) return { kind: "artifact", artifactId, rereadWith: "session_artifacts" };
+ const cursor = compactId(input.cursor, 512);
+ if (cursor) return { kind: "cursor", cursor, rereadWith: name === "project_candidate_search" ? "project_candidate_search" : name };
+ return null;
+}
+
+function replayHandlesFromContent(content, call) {
+ const out = [];
+ const seen = new Set();
+ const add = (handle) => {
+ if (!handle || out.length >= MAX_REPLAY_HANDLES) return;
+ const key = replayHandleKey(handle);
+ if (seen.has(key)) return;
+ seen.add(key);
+ out.push(handle);
+ };
+ add(replayHandleFromCall(call));
+
+ const raw = String(content ?? "");
+ let parsed;
+ if (raw.length <= 128 * 1024 && /^[\s]*[\[{]/.test(raw)) {
+ try { parsed = JSON.parse(raw); } catch { parsed = undefined; }
+ }
+ let nodes = 0;
+ const visit = (value, depth = 0) => {
+ if (out.length >= MAX_REPLAY_HANDLES || nodes >= MAX_REPLAY_SCAN_NODES || depth > 3 || value == null) return;
+ nodes += 1;
+ if (Array.isArray(value)) {
+ for (const item of value.slice(0, 12)) visit(item, depth + 1);
+ return;
+ }
+ if (typeof value !== "object") return;
+ const pathValue = compactReplayPath(value.path, 512);
+ const sha256 = compactId(value.sha256, 80);
+ const cursor = compactId(value.cursor ?? value.nextCursor, 512);
+ const jobId = compactId(value.job_id ?? value.jobId, 160);
+ const artifactId = compactId(value.artifact_id ?? value.artifactId, 160);
+ const truncated = value.truncated === true || value.msoTruncated === true;
+ if (pathValue) add({
+ kind: "file",
+ path: pathValue,
+ ...(/^[a-f0-9]{64}$/i.test(sha256) ? { sha256: sha256.toLowerCase() } : {}),
+ ...(cursor ? { cursor } : {}),
+ ...(truncated ? { truncated: true } : {}),
+ rereadWith: "read_pipeline",
+ });
+ if (jobId) add({ kind: "job", jobId, rereadWith: "exec_job_status" });
+ if (artifactId) add({ kind: "artifact", artifactId, rereadWith: "session_artifacts" });
+ if (!pathValue && cursor) add({ kind: "cursor", cursor, ...(truncated ? { truncated: true } : {}), rereadWith: "project_candidate_search" });
+ for (const [key, child] of Object.entries(value)) {
+ if (["content", "stdout", "stderr", "text", "body", "data", "buffer", "bytes"].includes(key)) continue;
+ if (child && typeof child === "object") visit(child, depth + 1);
+ if (out.length >= MAX_REPLAY_HANDLES || nodes >= MAX_REPLAY_SCAN_NODES) break;
+ }
+ };
+ visit(parsed);
+ return out;
+}
+
+export function compactConsumedReadToolResults(history, tools) {
+ if (!Array.isArray(history) || !Array.isArray(tools)) return 0;
+ const scopes = new Map(tools.map((tool) => [String(tool?.name || ""), String(tool?.scope || "read")]));
+ let compacted = 0;
+ for (let index = 1; index < history.length; index += 1) {
+ const row = history[index];
+ const assistant = history[index - 1];
+ if (row?.role !== "tool" || assistant?.role !== "assistant" || !Array.isArray(row.results) || !Array.isArray(assistant.toolUses)) continue;
+ const calls = new Map(assistant.toolUses.map((call) => [String(call?.id || ""), call]));
+ row.results = row.results.map((result) => {
+ if (!result || typeof result !== "object" || result.msoReplay === true) return result;
+ const call = calls.get(String(result.id || ""));
+ if (!call || scopes.get(String(call.name || "")) !== "read") return result;
+ const raw = String(result.content ?? "");
+ const rawResultBytes = Buffer.byteLength(raw, "utf8");
+ const handles = replayHandlesFromContent(raw, call);
+ compacted += 1;
+ return {
+ id: result.id,
+ isError: Boolean(result.isError),
+ msoReplay: true,
+ content: JSON.stringify({
+ msoReplay: true,
+ rawResultBytes,
+ handles,
+ ...(handles.length ? {} : { truncated: true }),
+ instruction: handles.length
+ ? "Re-read only the needed handle with the bounded read/status surface."
+ : "The consumed read result was compacted. Re-run the exact prior read call only if details are needed.",
+ }),
+ };
+ });
+ }
+ return compacted;
+}
+
export function modelHistoryBudget(contextWindow, requestedBudget = 0) {
const limit = Number(contextWindow || 0);
const base = !Number.isFinite(limit) || limit <= 0
diff --git a/scripts/mso-agent-context.test.ts b/scripts/mso-agent-context.test.ts
index 120300a3..fa70909c 100644
--- a/scripts/mso-agent-context.test.ts
+++ b/scripts/mso-agent-context.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
-import { modelHistoryBudget, projectHistoryForModel } from "./mso-agent-context.mjs";
+import { compactConsumedReadToolResults, modelHistoryBudget, projectHistoryForModel } from "./mso-agent-context.mjs";
describe("MSO model context projection", () => {
it("reserves provider-neutral headroom instead of filling the whole context window", () => {
@@ -26,4 +26,51 @@ describe("MSO model context projection", () => {
const out = projectHistoryForModel([...old, call, result], 32_000);
expect(out.messages.slice(-2)).toEqual([call, result]);
});
+
+ it("compacts consumed read results into replay handles but leaves write receipts intact", () => {
+ const readCall = {
+ role: "assistant",
+ text: "",
+ toolUses: [{ id: "r1", name: "fs_read", input: { path: "/repo/src/app.ts" } }],
+ };
+ const secret = "raw-secret-that-must-not-survive";
+ const readResult = {
+ role: "tool",
+ results: [{
+ id: "r1",
+ content: JSON.stringify({
+ path: "/repo/src/app.ts",
+ sha256: "a".repeat(64),
+ content: secret,
+ }),
+ }],
+ };
+ const writeCall = {
+ role: "assistant",
+ text: "",
+ toolUses: [{ id: "w1", name: "fs_write", input: { path: "/repo/src/app.ts", content: "new" } }],
+ };
+ const writeResult = { role: "tool", results: [{ id: "w1", content: "write-receipt" }] };
+ const history = [readCall, readResult, writeCall, writeResult];
+ const compacted = compactConsumedReadToolResults(history, [
+ { name: "fs_read", scope: "read" },
+ { name: "fs_write", scope: "write" },
+ ]);
+
+ expect(compacted).toBe(1);
+ const envelope = JSON.parse(String(readResult.results[0].content));
+ expect(envelope).toMatchObject({
+ msoReplay: true,
+ handles: expect.arrayContaining([
+ expect.objectContaining({ kind: "file", path: "/repo/src/app.ts", rereadWith: "read_pipeline" }),
+ ]),
+ });
+ expect(JSON.stringify(readResult)).not.toContain(secret);
+ expect(writeResult.results[0].content).toBe("write-receipt");
+ expect(compactConsumedReadToolResults(history, [
+ { name: "fs_read", scope: "read" },
+ { name: "fs_write", scope: "write" },
+ ])).toBe(0);
+ });
+
});
diff --git a/scripts/mso-agent-turn.mjs b/scripts/mso-agent-turn.mjs
index feb769fc..14842f0e 100644
--- a/scripts/mso-agent-turn.mjs
+++ b/scripts/mso-agent-turn.mjs
@@ -7,6 +7,7 @@ import { beginSkillInvocation, endSkillInvocation } from "./mso-agent-skills.mjs
import { isAbortError } from "./mso-agent-interrupt.mjs";
import { approvesTool } from "./mso-agent-permissions.mjs";
import { api, C, streamTurn } from "./mso-agent-runtime.mjs";
+import { compactConsumedReadToolResults } from "./mso-agent-context.mjs";
import { persistSession } from "./mso-agent-session-ui.mjs";
import { addUsage } from "./mso-agent-status.mjs";
import { oneShotApproves } from "./mso-agent-oneshot.mjs";
@@ -95,6 +96,10 @@ export async function agentRound(rl, session, skillContext = null, signal = unde
session.history, session.state.tools, session.agentSession, skillContext, signal,
session.state.modelMeta?.context, lazyAssistantOutput(session, options),
);
+ // The current model round has consumed all prior read-tool payloads that were
+ // still inside its projected context. Persist only bounded replay envelopes
+ // afterwards; write/exec receipts remain untouched.
+ compactConsumedReadToolResults(session.history, session.state.tools);
if (skillContext) session.lastInvokedSkill = skillContext;
finalText = result.text;
session.usage = addUsage(session.usage, result.usage);