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.

refactor: separate workflow and memory ownership

Rahmanead080bc8816
diff --git a/app/api/assistant/route.ts b/app/api/assistant/route.ts
index f9c837f3..d73f1bbd 100644
--- a/app/api/assistant/route.ts
+++ b/app/api/assistant/route.ts
@@ -6,7 +6,7 @@ import {
streamPreparedSelectedModel,
} from "@/lib/ai/selected-model-stream";
import type { OaMsg as InMsg, OaTool as Tool } from "@/lib/ai/openai-stream";
-import { recall } from "@/lib/ai/memory";
+import { recall } from "@/lib/agent/legacy-owner-memory";
import { rateLimited } from "@/lib/host/rate-limit";
import { IS_DEMO } from "@/lib/demo";
diff --git a/app/api/memory/route.ts b/app/api/memory/route.ts
index 3c2939cb..794b6f70 100644
--- a/app/api/memory/route.ts
+++ b/app/api/memory/route.ts
@@ -1,6 +1,6 @@
import { NextRequest, NextResponse } from "next/server";
import { requireSession } from "@/lib/auth/require-session";
-import { listMemories, addMemory, removeMemory } from "@/lib/ai/memory";
+import { listMemories, addMemory, removeMemory } from "@/lib/agent/legacy-owner-memory";
export const runtime = "nodejs";
export const dynamic = "force-dynamic";
diff --git a/app/api/skills/route.ts b/app/api/skills/route.ts
index 39a1917f..55b31229 100644
--- a/app/api/skills/route.ts
+++ b/app/api/skills/route.ts
@@ -2,7 +2,7 @@ import { NextRequest, NextResponse } from "next/server";
import { requireSession } from "@/lib/auth/require-session";
import { IS_DEMO } from "@/lib/demo";
import { catalogSkillsDetailed, resolveSkill, readSkillFile, type SkillInfo } from "@/lib/skills/catalog";
-import { listLearnedRecipes } from "@/lib/skills/memory";
+import { listLearnedRecipes } from "@/lib/workflow";
import { searchSkillMemory } from "@/lib/skills/search";
export const runtime = "nodejs";
diff --git a/architecture.boundaries.json b/architecture.boundaries.json
index 6b89d1d2..1dbd63cf 100644
--- a/architecture.boundaries.json
+++ b/architecture.boundaries.json
@@ -3,12 +3,13 @@
"ratchets": {
"structuralCycles": 0,
"crossDomainCycles": 0,
- "filesOver220": 55,
- "filesOver500": 2,
+ "filesOver220": 54,
+ "filesOver500": 1,
"serverFrontendImports": 6,
"appshellSelfBarrelImports": 0,
"nonMcpMcpImports": 0,
- "crossProtocolCycles": 0
+ "crossProtocolCycles": 0,
+ "legacyWorkflowFacadeImports": 0
},
"notes": {
"policy": "Ratchets may only stay equal or decrease. Raise a baseline only with an explicit architecture decision.",
diff --git a/lib/ai/memory.test.ts b/lib/agent/legacy-owner-memory.test.ts
similarity index 96%
rename from lib/ai/memory.test.ts
rename to lib/agent/legacy-owner-memory.test.ts
index a86d2938..b24dafb9 100644
--- a/lib/ai/memory.test.ts
+++ b/lib/agent/legacy-owner-memory.test.ts
@@ -3,7 +3,7 @@ import os from "node:os";
import path from "node:path";
process.env.OS_MEMORY_STORE = path.join(os.tmpdir(), `mso-memory-test-${process.pid}.json`);
-const { addMemory, recall, listMemories, removeMemory } = await import("./memory");
+const { addMemory, recall, listMemories, removeMemory } = await import("./legacy-owner-memory");
describe("memory store + recall", () => {
it("adds, recalls by word overlap, and removes", async () => {
diff --git a/lib/agent/legacy-owner-memory.ts b/lib/agent/legacy-owner-memory.ts
new file mode 100644
index 00000000..3170c443
--- /dev/null
+++ b/lib/agent/legacy-owner-memory.ts
@@ -0,0 +1,61 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Durable cross-session facts recalled into Alfa's system prompt. One JSON file in
+// ~/.mso (small structured records, chmod 600). Recall is substring scoring for
+// now. ponytail: substring recall — swap for embeddings if it gets noisy at scale.
+export interface Memory {
+ id: string;
+ text: string;
+ createdAt: number;
+}
+
+const FILE = process.env.OS_MEMORY_STORE || path.join(os.homedir(), ".mso", "memory.json");
+
+async function read(): Promise<Memory[]> {
+ try {
+ const j = JSON.parse(await fs.readFile(FILE, "utf8"));
+ return Array.isArray(j) ? j : [];
+ } catch {
+ return [];
+ }
+}
+
+async function write(list: Memory[]): Promise<void> {
+ await fs.mkdir(path.dirname(FILE), { recursive: true, mode: 0o700 });
+ const tmp = `${FILE}.tmp`;
+ await fs.writeFile(tmp, JSON.stringify(list, null, 2), { encoding: "utf8", mode: 0o600 });
+ await fs.rename(tmp, FILE);
+}
+
+export async function listMemories(): Promise<Memory[]> {
+ return (await read()).sort((a, b) => b.createdAt - a.createdAt);
+}
+
+export async function addMemory(text: string): Promise<Memory> {
+ const m: Memory = { id: `mem_${Date.now().toString(36)}`, text: text.trim().slice(0, 500), createdAt: Date.now() };
+ const list = await read();
+ list.push(m);
+ await write(list);
+ return m;
+}
+
+export async function removeMemory(id: string): Promise<void> {
+ await write((await read()).filter((m) => m.id !== id));
+}
+
+// Recall facts relevant to `query` (scored by how many of its ≥3-char words appear),
+// capped. No query signal → the most recent facts.
+export async function recall(query: string, limit = 8): Promise<Memory[]> {
+ const all = await read();
+ if (all.length === 0) return [];
+ const words = query.toLowerCase().match(/[a-z0-9]{3,}/g) ?? [];
+ if (words.length === 0) return all.slice(-limit);
+ return all
+ .map((m) => ({ m, hits: words.filter((w) => m.text.toLowerCase().includes(w)).length }))
+ .filter((s) => s.hits > 0)
+ .sort((a, b) => b.hits - a.hits)
+ .slice(0, limit)
+ .map((s) => s.m);
+}
diff --git a/lib/ai/memory.ts b/lib/ai/memory.ts
index 3170c443..2ec6c8f5 100644
--- a/lib/ai/memory.ts
+++ b/lib/ai/memory.ts
@@ -1,61 +1,5 @@
-import { promises as fs } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-// Durable cross-session facts recalled into Alfa's system prompt. One JSON file in
-// ~/.mso (small structured records, chmod 600). Recall is substring scoring for
-// now. ponytail: substring recall — swap for embeddings if it gets noisy at scale.
-export interface Memory {
- id: string;
- text: string;
- createdAt: number;
-}
-
-const FILE = process.env.OS_MEMORY_STORE || path.join(os.homedir(), ".mso", "memory.json");
-
-async function read(): Promise<Memory[]> {
- try {
- const j = JSON.parse(await fs.readFile(FILE, "utf8"));
- return Array.isArray(j) ? j : [];
- } catch {
- return [];
- }
-}
-
-async function write(list: Memory[]): Promise<void> {
- await fs.mkdir(path.dirname(FILE), { recursive: true, mode: 0o700 });
- const tmp = `${FILE}.tmp`;
- await fs.writeFile(tmp, JSON.stringify(list, null, 2), { encoding: "utf8", mode: 0o600 });
- await fs.rename(tmp, FILE);
-}
-
-export async function listMemories(): Promise<Memory[]> {
- return (await read()).sort((a, b) => b.createdAt - a.createdAt);
-}
-
-export async function addMemory(text: string): Promise<Memory> {
- const m: Memory = { id: `mem_${Date.now().toString(36)}`, text: text.trim().slice(0, 500), createdAt: Date.now() };
- const list = await read();
- list.push(m);
- await write(list);
- return m;
-}
-
-export async function removeMemory(id: string): Promise<void> {
- await write((await read()).filter((m) => m.id !== id));
-}
-
-// Recall facts relevant to `query` (scored by how many of its ≥3-char words appear),
-// capped. No query signal → the most recent facts.
-export async function recall(query: string, limit = 8): Promise<Memory[]> {
- const all = await read();
- if (all.length === 0) return [];
- const words = query.toLowerCase().match(/[a-z0-9]{3,}/g) ?? [];
- if (words.length === 0) return all.slice(-limit);
- return all
- .map((m) => ({ m, hits: words.filter((w) => m.text.toLowerCase().includes(w)).length }))
- .filter((s) => s.hits > 0)
- .sort((a, b) => b.hits - a.hits)
- .slice(0, limit)
- .map((s) => s.m);
-}
+// Compatibility path for the original Alfa owner-global memory API.
+// New agent/session memory is principal-scoped in lib/agent/memory-store.ts; do
+// not merge these identities implicitly.
+export { listMemories, addMemory, removeMemory, recall } from "@/lib/agent/legacy-owner-memory";
+export type { Memory } from "@/lib/agent/legacy-owner-memory";
diff --git a/lib/capabilities/execute.ts b/lib/capabilities/execute.ts
index 4b4e6b9e..22e6e43e 100644
--- a/lib/capabilities/execute.ts
+++ b/lib/capabilities/execute.ts
@@ -1,7 +1,7 @@
import { audit } from "@/lib/host";
import { maybeAutoTitleAgentSession } from "@/lib/agent/session-store";
import { touchLocalAgentPresence } from "@/lib/agent/local-agent-presence";
-import { activeWorkflowForActor, recordWorkflowStep } from "@/lib/skills/memory";
+import { activeWorkflowForActor, recordWorkflowStep } from "@/lib/workflow";
import { allows, type Scope } from "./scope";
import type { CapabilityRuntime } from "./runtime";
import type { CapabilityTool } from "./tool";
diff --git a/lib/capabilities/execution-support.ts b/lib/capabilities/execution-support.ts
index 977e0d35..b59f8aff 100644
--- a/lib/capabilities/execution-support.ts
+++ b/lib/capabilities/execution-support.ts
@@ -1,5 +1,5 @@
import { appendAgentSessionEvent } from "@/lib/agent/session-store";
-import type { ActiveWorkflow } from "@/lib/skills/memory";
+import type { ActiveWorkflow } from "@/lib/workflow";
import type { CapabilityAgentContext } from "./actors";
export function sessionDetail(name: string, args: Record<string, unknown>, target?: string): string | undefined {
diff --git a/lib/contracts/orchestration.ts b/lib/contracts/orchestration.ts
new file mode 100644
index 00000000..c2e3572b
--- /dev/null
+++ b/lib/contracts/orchestration.ts
@@ -0,0 +1,36 @@
+export type RiskLevel = "low" | "medium" | "high";
+export type ComplexityLevel = "light" | "medium" | "heavy";
+export type ContentionLevel = "none" | "possible" | "high";
+export type MemoryRelevance = "low" | "medium" | "high";
+export type IsolationMode = "direct" | "optional-worktree" | "isolated-worktree";
+export type VerificationLevel = "targeted" | "affected" | "full";
+export type CleanupState = "not-required" | "pending" | "complete";
+
+export type TaskClassification = {
+ risk: RiskLevel;
+ complexity: ComplexityLevel;
+ contention: ContentionLevel;
+ memoryRelevance: MemoryRelevance;
+ isolation: IsolationMode;
+ verification: VerificationLevel;
+ reasons: string[];
+ sharedResourceWarnings: string[];
+};
+
+export type WorkflowOrchestrationSnapshot = TaskClassification & {
+ baseCommit?: string;
+ baseBranch?: string;
+ changedPaths: string[];
+ affectedPaths: string[];
+ reservedResources: string[];
+ overlappingPaths: string[];
+ overlappingResources: string[];
+ activeProjectWorkflows: number;
+ conflictingWorkflowCount: number;
+ memoryHits: number;
+ contextEstimateTokens: number;
+ cleanupState: CleanupState;
+ workspacePath?: string;
+ recipeUsed?: string;
+ createdAt: string;
+};
diff --git a/lib/forge/forge.test.ts b/lib/forge/forge.test.ts
index 93edbd62..d03e65c8 100644
--- a/lib/forge/forge.test.ts
+++ b/lib/forge/forge.test.ts
@@ -2,7 +2,7 @@ import { existsSync, promises as fs } from "node:fs";
import { spawnSync } from "node:child_process";
import path from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
-import type { LearnedRecipe, WorkflowQuality } from "@/lib/skills/memory";
+import type { LearnedRecipe, WorkflowQuality } from "@/lib/workflow";
import { projectSkillTrust } from "@/lib/skills/project-skills";
import { readProjectFunctionsManifest } from "@/lib/host/project-function-manifest";
import { runProjectFunction } from "@/lib/host/project-function-runner";
diff --git a/lib/forge/proposal.ts b/lib/forge/proposal.ts
index ee572a4a..efdad971 100644
--- a/lib/forge/proposal.ts
+++ b/lib/forge/proposal.ts
@@ -1,4 +1,4 @@
-import type { LearnedRecipe } from "@/lib/skills/memory";
+import type { LearnedRecipe } from "@/lib/workflow";
import { createForgeCandidate, forgeOwnerHash, newForgeCandidateId } from "./store";
import type { ForgeCandidate, ForgeFixture, ForgeFunctionSpec, ForgeKind, ForgeRecipeSnapshot } from "./types";
diff --git a/lib/forge/types.ts b/lib/forge/types.ts
index d76187d5..e2b39075 100644
--- a/lib/forge/types.ts
+++ b/lib/forge/types.ts
@@ -1,5 +1,5 @@
import type { Scope } from "@/lib/capabilities/scope";
-import type { WorkflowQuality, WorkflowStep } from "@/lib/skills/memory";
+import type { WorkflowQuality, WorkflowStep } from "@/lib/workflow";
export const FORGE_VERSION = 1 as const;
export type ForgeKind = "skill" | "project_function";
diff --git a/lib/mcp/dispatch.test.ts b/lib/mcp/dispatch.test.ts
index 81a7a604..88bcce7f 100644
--- a/lib/mcp/dispatch.test.ts
+++ b/lib/mcp/dispatch.test.ts
@@ -18,7 +18,7 @@ vi.mock("@/lib/host", async (orig) => {
const { dispatch, isNotification } = await import("./dispatch");
const { TOOLS } = await import("./tools");
const { MCP_SERVER_VERSION } = await import("./toolset");
-const { activeWorkflowForActor } = await import("@/lib/skills/memory");
+const { activeWorkflowForActor } = await import("@/lib/workflow");
const call = (name: string, args: Record<string, unknown> = {}) =>
({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } });
diff --git a/lib/mcp/session-workflow-isolation.test.ts b/lib/mcp/session-workflow-isolation.test.ts
index 883b4768..a77c8f8d 100644
--- a/lib/mcp/session-workflow-isolation.test.ts
+++ b/lib/mcp/session-workflow-isolation.test.ts
@@ -5,18 +5,18 @@ import path from "node:path";
const file = path.join(os.tmpdir(), `mso-session-flow-${process.pid}.json`);
process.env.OS_SKILL_MEMORY_STORE = file;
-const memory = await import("@/lib/skills/memory");
+const memory = await import("@/lib/workflow");
const { searchSkillMemory } = await import("@/lib/skills/search");
const { recipeActor, workflowActor } = await import("./dispatch-actors");
beforeEach(async () => {
await fs.rm(file, { force: true });
- memory.resetSkillMemoryCache();
+ memory.resetWorkflowStoreCache();
});
afterAll(async () => {
await fs.rm(file, { force: true });
delete process.env.OS_SKILL_MEMORY_STORE;
- memory.resetSkillMemoryCache();
+ memory.resetWorkflowStoreCache();
});
describe("conversation-scoped workflow ownership", () => {
diff --git a/lib/mcp/tools-forge.test.ts b/lib/mcp/tools-forge.test.ts
index ad8ec68f..e4620b0d 100644
--- a/lib/mcp/tools-forge.test.ts
+++ b/lib/mcp/tools-forge.test.ts
@@ -13,7 +13,7 @@ const mocks = vi.hoisted(() => ({
}));
vi.mock("@/lib/host", () => ({ resolveProjectHint: mocks.resolveProjectHint }));
-vi.mock("@/lib/skills/memory", () => ({ listLearnedRecipes: mocks.listLearnedRecipes }));
+vi.mock("@/lib/workflow", () => ({ listLearnedRecipes: mocks.listLearnedRecipes }));
vi.mock("@/lib/forge/proposal", () => ({ proposeForgeCandidate: mocks.proposeForgeCandidate }));
vi.mock("@/lib/forge/evaluate", () => ({ evaluateForgeCandidate: mocks.evaluateForgeCandidate }));
vi.mock("@/lib/forge/promote", () => ({ promoteForgeCandidate: mocks.promoteForgeCandidate }));
diff --git a/lib/mcp/tools-forge.ts b/lib/mcp/tools-forge.ts
index c69e8c7c..989006be 100644
--- a/lib/mcp/tools-forge.ts
+++ b/lib/mcp/tools-forge.ts
@@ -3,7 +3,7 @@ import { evaluateForgeCandidate } from "@/lib/forge/evaluate";
import { promoteForgeCandidate } from "@/lib/forge/promote";
import { proposeForgeCandidate } from "@/lib/forge/proposal";
import { getForgeCandidate, listForgeCandidates, publicForgeCandidate, updateForgeCandidate } from "@/lib/forge/store";
-import { listLearnedRecipes } from "@/lib/skills/memory";
+import { listLearnedRecipes } from "@/lib/workflow";
import { type McpTool, S, str, opt } from "./tool-kit";
import { toolsetInfo } from "./toolset";
diff --git a/lib/mcp/tools-learning.test.ts b/lib/mcp/tools-learning.test.ts
index 10d3668a..20de4e3a 100644
--- a/lib/mcp/tools-learning.test.ts
+++ b/lib/mcp/tools-learning.test.ts
@@ -29,7 +29,7 @@ const previous = {
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");
-const { resetSkillMemoryCache } = await import("@/lib/skills/memory");
+const { resetWorkflowStoreCache } = await import("@/lib/workflow");
const { projectRefFor } = await import("@/lib/skills/project-skills");
const { LEARNING_TOOLS } = await import("./tools-learning");
@@ -40,7 +40,7 @@ const siblingSkillId = async () =>
describe("workflow_start bootstrap", () => {
beforeEach(async () => {
await fs.rm(process.env.OS_SKILL_MEMORY_STORE!, { force: true });
- resetSkillMemoryCache();
+ resetWorkflowStoreCache();
});
afterAll(async () => {
if (previous.read === undefined) delete process.env.OS_FS_READ_ROOTS;
@@ -49,7 +49,7 @@ 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;
- resetSkillMemoryCache();
+ resetWorkflowStoreCache();
await fs.rm(dir, { recursive: true, force: true });
});
@@ -149,7 +149,7 @@ describe("workflow_start bootstrap", () => {
const start = LEARNING_TOOLS.find((tool) => tool.name === "workflow_start")!;
const context = { actor: "mcp:preflight", scope: "write" as const };
await expect(start.run({ intent: "", project }, context)).rejects.toThrow("intent");
- const { activeWorkflowForActor } = await import("@/lib/skills/memory");
+ const { activeWorkflowForActor } = await import("@/lib/workflow");
await expect(activeWorkflowForActor(context.actor)).resolves.toBeNull();
});
@@ -172,7 +172,7 @@ describe("workflow_start bootstrap", () => {
await expect(finish.run({
workflow_id: started.workflow.id, summary: "done", success: true,
}, context)).rejects.toThrow(/requires explicit/i);
- const { activeWorkflowForActor } = await import("@/lib/skills/memory");
+ const { activeWorkflowForActor } = await import("@/lib/workflow");
await expect(activeWorkflowForActor(context.actor, started.workflow.id)).resolves.toMatchObject({ id: started.workflow.id });
const done = await finish.run({
diff --git a/lib/mcp/tools-workflow-lifecycle.ts b/lib/mcp/tools-workflow-lifecycle.ts
index 2e8c63b4..07e0b53c 100644
--- a/lib/mcp/tools-workflow-lifecycle.ts
+++ b/lib/mcp/tools-workflow-lifecycle.ts
@@ -1,5 +1,5 @@
import { inspectProject, resolveProjectHint } from "@/lib/host";
-import { activeWorkflowForActor, cancelWorkflow, finishWorkflow } from "@/lib/skills/memory";
+import { activeWorkflowForActor, cancelWorkflow, finishWorkflow } from "@/lib/workflow";
import { assessAutomationPromotion, buildAutomationScriptManifest, workflowCleanupGuidance } from "@/lib/orchestration/automation";
import { classifyTask } from "@/lib/orchestration/classifier";
import { buildEvidenceReceipt, validateEvidenceReceipt } from "@/lib/orchestration/evidence";
diff --git a/lib/mcp/tools-workflow-start.ts b/lib/mcp/tools-workflow-start.ts
index 22eb79b7..003132cc 100644
--- a/lib/mcp/tools-workflow-start.ts
+++ b/lib/mcp/tools-workflow-start.ts
@@ -1,5 +1,5 @@
import { inspectProject, readProjectKnowledge, resolveProjectHint } from "@/lib/host";
-import { markRecipeUsed, startWorkflow, summarizeProjectContention } from "@/lib/skills/memory";
+import { markRecipeUsed, startWorkflow, summarizeProjectContention } from "@/lib/workflow";
import { searchSkillMemory } from "@/lib/skills/search";
import { progressiveVerification } from "@/lib/orchestration/automation";
import { routeIntentText } from "@/lib/orchestration/capability-catalog.mjs";
diff --git a/lib/mcp/ui-resources.test.ts b/lib/mcp/ui-resources.test.ts
index e821cf0a..67c1d5ad 100644
--- a/lib/mcp/ui-resources.test.ts
+++ b/lib/mcp/ui-resources.test.ts
@@ -5,7 +5,7 @@ vi.mock("server-only", () => ({}));
const { dispatch } = await import("./dispatch");
const { MCP_APP_MIME_TYPE, WORKFLOW_PROGRESS_URI, PROJECT_STATUS_URI, DIFF_VIEW_URI, VPS_STATUS_URI } = await import("./ui-resources");
const { MCP_UI_DOMAIN } = await import("./ui-config");
-const { activeWorkflowForActor } = await import("@/lib/skills/memory");
+const { activeWorkflowForActor } = await import("@/lib/workflow");
const call = (name: string, args: Record<string, unknown> = {}) =>
({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } });
diff --git a/lib/orchestration/automation.ts b/lib/orchestration/automation.ts
index 50f8128c..3fc8c261 100644
--- a/lib/orchestration/automation.ts
+++ b/lib/orchestration/automation.ts
@@ -1,4 +1,4 @@
-import type { LearnedRecipe, WorkflowStep } from "@/lib/skills/memory";
+import type { LearnedRecipe, WorkflowStep } from "@/lib/workflow";
import type { AutomationAssessment, AutomationScriptManifest } from "./types";
export const REPLAY_SAFE_TOOLS = new Set([
diff --git a/lib/orchestration/evidence-automation.test.ts b/lib/orchestration/evidence-automation.test.ts
index f9eba4ec..c927be9f 100644
--- a/lib/orchestration/evidence-automation.test.ts
+++ b/lib/orchestration/evidence-automation.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
-import type { ActiveWorkflow, LearnedRecipe, WorkflowStep } from "@/lib/skills/memory";
+import type { ActiveWorkflow, LearnedRecipe, WorkflowStep } from "@/lib/workflow";
import { assessAutomationPromotion, buildAutomationScriptManifest, progressiveVerification, reviewLoopDecision } from "./automation";
import { buildEvidenceReceipt, validateEvidenceReceipt } from "./evidence";
diff --git a/lib/orchestration/evidence.ts b/lib/orchestration/evidence.ts
index 37291898..5a24cc37 100644
--- a/lib/orchestration/evidence.ts
+++ b/lib/orchestration/evidence.ts
@@ -1,4 +1,4 @@
-import type { ActiveWorkflow } from "@/lib/skills/memory";
+import type { ActiveWorkflow } from "@/lib/workflow";
import { redactStrings, redactText } from "./redaction";
import type { EvidenceInput, EvidenceItem, EvidenceReceipt, RiskLevel } from "./types";
diff --git a/lib/orchestration/types.ts b/lib/orchestration/types.ts
index 35d3e562..85824798 100644
--- a/lib/orchestration/types.ts
+++ b/lib/orchestration/types.ts
@@ -1,39 +1,14 @@
-export type RiskLevel = "low" | "medium" | "high";
-export type ComplexityLevel = "light" | "medium" | "heavy";
-export type ContentionLevel = "none" | "possible" | "high";
-export type MemoryRelevance = "low" | "medium" | "high";
-export type IsolationMode = "direct" | "optional-worktree" | "isolated-worktree";
-export type VerificationLevel = "targeted" | "affected" | "full";
-export type CleanupState = "not-required" | "pending" | "complete";
-
-export type TaskClassification = {
- risk: RiskLevel;
- complexity: ComplexityLevel;
- contention: ContentionLevel;
- memoryRelevance: MemoryRelevance;
- isolation: IsolationMode;
- verification: VerificationLevel;
- reasons: string[];
- sharedResourceWarnings: string[];
-};
-
-export type WorkflowOrchestrationSnapshot = TaskClassification & {
- baseCommit?: string;
- baseBranch?: string;
- changedPaths: string[];
- affectedPaths: string[];
- reservedResources: string[];
- overlappingPaths: string[];
- overlappingResources: string[];
- activeProjectWorkflows: number;
- conflictingWorkflowCount: number;
- memoryHits: number;
- contextEstimateTokens: number;
- cleanupState: CleanupState;
- workspacePath?: string;
- recipeUsed?: string;
- createdAt: string;
-};
+export type {
+ RiskLevel,
+ ComplexityLevel,
+ ContentionLevel,
+ MemoryRelevance,
+ IsolationMode,
+ VerificationLevel,
+ CleanupState,
+ TaskClassification,
+ WorkflowOrchestrationSnapshot,
+} from "@/lib/contracts/orchestration";
export type EvidenceStatus = "pass" | "fail" | "warn" | "not-run";
diff --git a/lib/skills/memory-compat.test.ts b/lib/skills/memory-compat.test.ts
new file mode 100644
index 00000000..f14e910f
--- /dev/null
+++ b/lib/skills/memory-compat.test.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import * as compat from "./memory";
+import * as workflow from "@/lib/workflow";
+
+describe("legacy skills memory compatibility surface", () => {
+ it("re-exports the workflow owner without duplicating implementation", () => {
+ expect(compat.startWorkflow).toBe(workflow.startWorkflow);
+ expect(compat.finishWorkflow).toBe(workflow.finishWorkflow);
+ expect(compat.listLearnedRecipes).toBe(workflow.listLearnedRecipes);
+ expect(compat.summarizeWorkflowQuality).toBe(workflow.summarizeWorkflowQuality);
+ });
+});
diff --git a/lib/skills/memory.ts b/lib/skills/memory.ts
index d21935be..15a08726 100644
--- a/lib/skills/memory.ts
+++ b/lib/skills/memory.ts
@@ -1,767 +1,26 @@
-/* eslint-disable max-lines -- the atomic store, redaction policy and recipe merge must evolve together; splitting them would expose partially-safe persistence helpers. */
-import { randomUUID } from "crypto";
-import { promises as fs } from "fs";
-import os from "os";
-import path from "path";
-import { embedSkillText, hybridSemanticScore, normalizeSemanticText, SKILL_EMBEDDING_VERSION } from "./semantic";
-import { allows, type Scope } from "@/lib/capabilities/scope";
-import type { WorkflowOrchestrationSnapshot } from "@/lib/orchestration/types";
-
-export type WorkflowStepState = "completed" | "failed" | "denied" | "rate_limited" | "invalid_args";
-
-export type WorkflowStep = {
- id: string;
- tool: string;
- state: WorkflowStepState;
- target?: string;
- /** Replayable, explicitly allowlisted scalar arguments. Never raw payloads. */
- args?: Record<string, string | number | boolean>;
- durationMs?: number;
- ts: string;
-};
-
-type WorkflowStepInput = Omit<WorkflowStep, "args"> & { args?: Record<string, unknown> };
-
-export type ActiveWorkflow = {
- id: string;
- actor: string;
- scope: Scope;
- intent: string;
- project?: string;
- constraints?: string;
- orchestration?: WorkflowOrchestrationSnapshot;
- startedAt: string;
- steps: WorkflowStep[];
-};
-
-export type WorkflowQuality = {
- stepAttempts: number; completedSteps: number; failedSteps: number; deniedSteps: number;
- rateLimitedSteps: number; invalidArgSteps: number; retries: number; rollbackSignals: number;
- timedSteps: number; totalStepDurationMs: number; averageStepDurationMs: number;
-};
-
-export type LearnedRecipe = {
- id: string;
- actor: string;
- scope: Scope;
- intent: string;
- normalizedIntent: string;
- project?: string;
- summary: string;
- embeddingVersion: string;
- embedding: number[];
- bestSteps: WorkflowStep[];
- lastSteps: WorkflowStep[];
- attempts: number;
- successes: number;
- failures: number;
- averageDurationMs: number;
- fastestDurationMs?: number;
- lastDurationMs: number;
- averageWallDurationMs: number;
- lastWallDurationMs: number;
- quality: WorkflowQuality;
- lastQuality: WorkflowQuality;
- qualityVersion?: 1;
- createdAt: string;
- updatedAt: string;
- lastUsedAt?: string;
-};
-
-type ActiveWorkflowBuckets = Record<string, Record<string, ActiveWorkflow>>;
-
-type SkillMemoryStore = {
- version: 3;
- active: ActiveWorkflowBuckets;
- recipes: Record<string, LearnedRecipe>;
-};
-
-export type FinishWorkflowResult = {
- workflow: ActiveWorkflow;
- recipe: LearnedRecipe;
- currentDurationMs: number;
- previousFastestMs?: number;
- improvedByMs?: number;
- improvedPct?: number;
-};
-
-export type CancelWorkflowResult = {
- workflow: ActiveWorkflow;
- reason?: string;
-};
-
-const EMPTY = (): SkillMemoryStore => ({ version: 3, active: {}, recipes: {} });
-let cache: SkillMemoryStore | null = null;
-let cachePath = "";
-const loadInFlight = new Map<string, Promise<SkillMemoryStore>>();
-let writeChain: Promise<unknown> = Promise.resolve();
-
-function storePath(): string {
- const env = process.env.OS_SKILL_MEMORY_STORE?.trim();
- if (process.env.VITEST && !env) return path.join(os.tmpdir(), `mso-skill-memory-test-${process.pid}.json`);
- return (env || path.join(os.homedir(), ".mso", "skill-memory.json")).replace(/^~(?=$|\/)/, os.homedir());
-}
-
-function sanitizeOrchestration(value: unknown): WorkflowOrchestrationSnapshot | undefined {
- if (!value || typeof value !== "object") return undefined;
- const row = value as Partial<WorkflowOrchestrationSnapshot>;
- const risks = ["low", "medium", "high"] as const;
- const complexities = ["light", "medium", "heavy"] as const;
- const contentions = ["none", "possible", "high"] as const;
- const relevances = ["low", "medium", "high"] as const;
- const isolations = ["direct", "optional-worktree", "isolated-worktree"] as const;
- const verifications = ["targeted", "affected", "full"] as const;
- if (!risks.includes(row.risk as never) || !complexities.includes(row.complexity as never) ||
- !contentions.includes(row.contention as never) || !relevances.includes(row.memoryRelevance as never) ||
- !isolations.includes(row.isolation as never) || !verifications.includes(row.verification as never)) return undefined;
- const strings = (candidate: unknown, maxItems: number, maxLen: number) => Array.isArray(candidate)
- ? candidate.filter((item): item is string => typeof item === "string").map((item) => safeMemoryText(item, maxLen)).filter(Boolean).slice(0, maxItems)
- : [];
- return {
- risk: row.risk!, complexity: row.complexity!, contention: row.contention!, memoryRelevance: row.memoryRelevance!,
- isolation: row.isolation!, verification: row.verification!, reasons: strings(row.reasons, 12, 240),
- sharedResourceWarnings: strings(row.sharedResourceWarnings, 12, 240), changedPaths: strings(row.changedPaths, 80, 240),
- affectedPaths: strings(row.affectedPaths, 80, 240), reservedResources: strings(row.reservedResources, 40, 160),
- overlappingPaths: strings(row.overlappingPaths, 80, 240), overlappingResources: strings(row.overlappingResources, 40, 160),
- activeProjectWorkflows: Math.max(0, Math.min(100, Math.round(Number(row.activeProjectWorkflows) || 0))),
- conflictingWorkflowCount: Math.max(0, Math.min(100, Math.round(Number(row.conflictingWorkflowCount) || 0))),
- memoryHits: Math.max(0, Math.min(100, Math.round(Number(row.memoryHits) || 0))),
- contextEstimateTokens: Math.max(0, Math.min(1_000_000, Math.round(Number(row.contextEstimateTokens) || 0))),
- cleanupState: row.cleanupState === "pending" || row.cleanupState === "complete" ? row.cleanupState : "not-required",
- ...(typeof row.workspacePath === "string" ? { workspacePath: safeMemoryText(row.workspacePath, 240) } : {}),
- ...(typeof row.baseCommit === "string" ? { baseCommit: safeMemoryText(row.baseCommit, 80) } : {}),
- ...(typeof row.baseBranch === "string" ? { baseBranch: safeMemoryText(row.baseBranch, 160) } : {}),
- ...(typeof row.recipeUsed === "string" ? { recipeUsed: safeMemoryText(row.recipeUsed, 120) } : {}),
- createdAt: typeof row.createdAt === "string" && Number.isFinite(Date.parse(row.createdAt)) ? new Date(row.createdAt).toISOString() : new Date(0).toISOString(),
- };
-}
-
-function isActiveWorkflow(value: unknown): value is ActiveWorkflow {
- if (!value || typeof value !== "object") return false;
- const row = value as Partial<ActiveWorkflow>;
- return typeof row.id === "string" && typeof row.actor === "string" &&
- typeof row.intent === "string" && typeof row.startedAt === "string" && Array.isArray(row.steps);
-}
-
-/** Migrate v1's one-workflow-per-actor map and accept v2 buckets. The current
- * production workflow must survive the deployment that introduces v2. */
-function normalizeActive(value: unknown): ActiveWorkflowBuckets {
- if (!value || typeof value !== "object") return {};
- const active: ActiveWorkflowBuckets = {};
- for (const [legacyActor, candidate] of Object.entries(value as Record<string, unknown>)) {
- if (isActiveWorkflow(candidate)) {
- const actor = candidate.actor || legacyActor;
- (active[actor] ??= {})[candidate.id] = {
- ...candidate,
- scope: candidate.scope ?? "read",
- intent: safeMemoryText(candidate.intent, 1000),
- project: candidate.project ? safeMemoryText(candidate.project, 240) || undefined : undefined,
- constraints: candidate.constraints ? safeMemoryText(candidate.constraints, 500) || undefined : undefined,
- orchestration: sanitizeOrchestration(candidate.orchestration),
- steps: candidate.steps.map(sanitizeStoredStep).filter((step): step is WorkflowStep => Boolean(step)),
- };
- continue;
- }
- if (!candidate || typeof candidate !== "object") continue;
- for (const workflow of Object.values(candidate as Record<string, unknown>)) {
- if (!isActiveWorkflow(workflow)) continue;
- const actor = workflow.actor || legacyActor;
- (active[actor] ??= {})[workflow.id] = {
- ...workflow,
- scope: workflow.scope ?? "read",
- intent: safeMemoryText(workflow.intent, 1000),
- project: workflow.project ? safeMemoryText(workflow.project, 240) || undefined : undefined,
- constraints: workflow.constraints ? safeMemoryText(workflow.constraints, 500) || undefined : undefined,
- orchestration: sanitizeOrchestration(workflow.orchestration),
- steps: workflow.steps.map(sanitizeStoredStep).filter((step): step is WorkflowStep => Boolean(step)),
- };
- }
- }
- return active;
-}
-
-function normalizeRecipes(value: unknown): Record<string, LearnedRecipe> {
- if (!value || typeof value !== "object") return {};
- const out: Record<string, LearnedRecipe> = {};
- for (const [id, candidate] of Object.entries(value as Record<string, unknown>)) {
- if (!candidate || typeof candidate !== "object") continue;
- const row = candidate as Partial<LearnedRecipe>;
- if (typeof row.id !== "string" || typeof row.intent !== "string" || !Array.isArray(row.bestSteps)) continue;
- const scope: Scope = row.scope === "write" || row.scope === "exec" ? row.scope : "read";
- const intent = safeMemoryText(row.intent, 1000);
- if (!intent) continue;
- out[id] = {
- ...(row as LearnedRecipe),
- // Legacy global recipes remain owner-visible but are never replayed to an MCP token.
- actor: typeof row.actor === "string" && row.actor ? row.actor : "legacy:owner",
- scope,
- intent,
- project: row.project ? safeMemoryText(row.project, 240) || undefined : undefined,
- 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))
- : [],
- quality: normalizeQuality(row.quality),
- lastQuality: normalizeQuality(row.lastQuality),
- ...(row.qualityVersion === 1 ? { qualityVersion: 1 as const } : {}),
- };
- }
- return out;
-}
-
-export type RecipeAccess =
- | { actor: string; scope: Scope; ownerView?: false }
- | { ownerView: true; actor?: never; scope?: never };
-
-async function loadStore(): Promise<SkillMemoryStore> {
- const file = storePath();
- if (cache && cachePath === file) return cache;
- const current = loadInFlight.get(file);
- if (current) return current;
-
- const pending = (async () => {
- let raw: string;
- try {
- raw = await fs.readFile(file, "utf8");
- } catch (e) {
- if ((e as NodeJS.ErrnoException).code === "ENOENT") {
- cache = EMPTY();
- cachePath = file;
- return cache;
- }
- throw e;
- }
- const parsed = JSON.parse(raw) as { active?: unknown; recipes?: unknown };
- cache = {
- version: 3,
- active: normalizeActive(parsed.active),
- recipes: normalizeRecipes(parsed.recipes),
- };
- cachePath = file;
- return cache;
- })();
- loadInFlight.set(file, pending);
- try {
- return await pending;
- } finally {
- if (loadInFlight.get(file) === pending) loadInFlight.delete(file);
- }
-}
-
-async function persist(store: SkillMemoryStore): Promise<void> {
- const file = storePath();
- const snapshot = JSON.stringify(store, null, 2);
- const run = writeChain.then(async () => {
- await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
- const tmp = `${file}.tmp`;
- await fs.writeFile(tmp, snapshot, { encoding: "utf8", mode: 0o600 });
- await fs.rename(tmp, file);
- });
- writeChain = run.catch(() => undefined);
- await run;
-}
-
-function actorKey(actor?: string): string {
- if (!actor) throw new Error("workflow memory needs an authenticated MCP actor");
- return actor;
-}
-
-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;
-}
-
-function safeCommandShape(command: string): string | undefined {
- const programs: string[] = [];
- for (const segment of command.replace(/[\r\n]+/g, " ").split(/&&|\|\||[;|]/)) {
- const tokens = segment.trim().split(/\s+/).filter(Boolean);
- let program: string | undefined;
- for (const token of tokens) {
- if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token)) continue;
- if (!/^[A-Za-z0-9_./@+-]+$/.test(token) || token.startsWith("-")) continue;
- program = path.basename(token).slice(0, 64);
- break;
- }
- if (program && !programs.includes(program)) programs.push(program);
- if (programs.length >= 8) break;
- }
- return programs.length ? programs.join(" → ") : undefined;
-}
-
-function safeTarget(tool: string, target?: string): string | undefined {
- if (!target) return undefined;
- if (tool === "exec_run") return safeCommandShape(target);
- let out = target
- .replace(/([?&](?:token|key|secret|password|code)=)[^&\s]+/gi, "$1[redacted]")
- .replace(/\b(?:bearer\s+)?(?:sk|pk|ghp|mso_mcp)_[a-z0-9_-]{8,}\b/gi, "[redacted]")
- .replace(/\b(password|token|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[redacted]");
- out = out.replace(new RegExp(`^${os.homedir().replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`), "~");
- return out.length > 160 ? `${out.slice(0, 160)}…` : out;
-}
-
-const SAFE_TOOL_ARGS: Record<string, readonly string[]> = {
- fs_list: ["path", "includeHidden"],
- fs_read: ["path"],
- fs_search: ["query", "root"],
- fs_usage: ["path"],
- apps_logs: ["id"],
- projects_list: ["query", "limit", "offset"],
- project_capabilities: ["project"],
- project_function_call: ["project", "name"],
- project_memory_search: ["project", "query", "kind", "limit", "include_history"],
- project_memory_upsert: ["project", "kind", "source", "result", "status"],
- skills_list: ["project", "trust", "limit", "offset"],
- skills_read: ["name"],
- screen_capture: ["shell", "width", "height"],
- fs_write: ["path"], // content is intentionally impossible to persist
- fs_mkdir: ["path"],
- fs_move: ["from", "to"],
- fs_copy: ["from", "to"],
- fs_delete: ["path"],
- apps_power: ["id", "action"],
- exec_run: ["cwd"],
- browser_power: ["on"],
-};
-
-function safeArgs(tool: string, args?: Record<string, unknown>): Record<string, string | number | boolean> | undefined {
- if (!args) return undefined;
- const keys = SAFE_TOOL_ARGS[tool];
- if (!keys) return undefined;
- const out: Record<string, string | number | boolean> = {};
- for (const key of keys) {
- const value = args[key];
- if (typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value))) out[key] = value;
- else if (typeof value === "string" && value) {
- const safe = safeMemoryText(value, 240);
- if (safe) out[key] = safe;
- }
- }
- return Object.keys(out).length ? out : undefined;
-}
-
-function sanitizeStoredStep(value: unknown): WorkflowStep | null {
- if (!value || typeof value !== "object") return null;
- const row = value as Partial<WorkflowStepInput>;
- if (typeof row.id !== "string" || typeof row.tool !== "string" ||
- !["completed", "failed", "denied", "rate_limited", "invalid_args"].includes(String(row.state)) ||
- typeof row.ts !== "string") return null;
- const durationMs = typeof row.durationMs === "number" && Number.isFinite(row.durationMs)
- ? Math.max(0, Math.min(86_400_000, Math.round(row.durationMs)))
- : undefined;
- return {
- id: safeMemoryText(row.id, 160),
- tool: safeMemoryText(row.tool, 120),
- state: row.state as WorkflowStepState,
- 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(),
- };
-}
-
-
-function emptyQuality(): WorkflowQuality {
- return { stepAttempts: 0, completedSteps: 0, failedSteps: 0, deniedSteps: 0, rateLimitedSteps: 0, invalidArgSteps: 0, retries: 0, rollbackSignals: 0, timedSteps: 0, totalStepDurationMs: 0, averageStepDurationMs: 0 };
-}
-function normalizeQuality(value: unknown): WorkflowQuality {
- const base = emptyQuality(); if (!value || typeof value !== "object") return base;
- const row = value as Partial<WorkflowQuality>;
- for (const key of Object.keys(base) as Array<keyof WorkflowQuality>) {
- const n = Number(row[key]); if (Number.isFinite(n) && n >= 0) base[key] = Math.round(n) as never;
- }
- base.averageStepDurationMs = base.timedSteps ? Math.round(base.totalStepDurationMs / base.timedSteps) : 0;
- return base;
-}
-export function summarizeWorkflowQuality(steps: WorkflowStep[]): WorkflowQuality {
- const out = emptyQuality(), pending = new Set<string>();
- for (const step of steps) {
- out.stepAttempts += 1;
- if (pending.has(step.tool)) { out.retries += 1; pending.delete(step.tool); }
- if (step.state === "completed") out.completedSteps += 1;
- else { pending.add(step.tool); if (step.state === "failed") out.failedSteps += 1; else if (step.state === "denied") out.deniedSteps += 1; else if (step.state === "rate_limited") out.rateLimitedSteps += 1; else out.invalidArgSteps += 1; }
- if (typeof step.durationMs === "number") { out.timedSteps += 1; out.totalStepDurationMs += step.durationMs; }
- if (step.state === "completed" && /\b(rollback|restore|revert)\b/i.test(JSON.stringify([step.tool, step.target, step.args]))) out.rollbackSignals += 1;
- }
- out.averageStepDurationMs = out.timedSteps ? Math.round(out.totalStepDurationMs / out.timedSteps) : 0;
- return out;
-}
-function mergeQuality(a: WorkflowQuality, b: WorkflowQuality): WorkflowQuality {
- const out = emptyQuality();
- for (const key of ["stepAttempts", "completedSteps", "failedSteps", "deniedSteps", "rateLimitedSteps", "invalidArgSteps", "retries", "rollbackSignals", "timedSteps", "totalStepDurationMs"] as const) out[key] = a[key] + b[key];
- out.averageStepDurationMs = out.timedSteps ? Math.round(out.totalStepDurationMs / out.timedSteps) : 0; return out;
-}
-function enrichBestSteps(best: WorkflowStep[], current: WorkflowStep[]): WorkflowStep[] {
- if (best.length !== current.length || best.some((step, i) => step.tool !== current[i]?.tool)) return best;
- return best.map((step, i) => ({
- ...step,
- args: step.args ?? current[i]?.args,
- target: step.target ?? current[i]?.target,
- }));
-}
-
-const MAX_RECIPE_STEPS = 24;
-const IMPORTANT_RECIPE_TOOLS = new Set([
- "fs_write", "fs_mkdir", "fs_move", "fs_copy", "fs_delete",
- "apps_power", "browser_power", "exec_run", "screen_capture",
-]);
-
-/** Keep the recipe replayable without teaching the next run to repeat every
- * exploratory read. Full redacted evidence stays in lastSteps; bestSteps is a
- * compact successful route with mutations, terminal batches and final proof. */
-function compactRecipeSteps(steps: WorkflowStep[]): WorkflowStep[] {
- const unique: Array<{ index: number; step: WorkflowStep }> = [];
- const seen = new Set<string>();
- for (const [index, step] of steps.entries()) {
- if (step.state !== "completed") continue;
- const signature = JSON.stringify([step.tool, step.target ?? "", step.args ?? {}]);
- if (seen.has(signature)) continue;
- seen.add(signature);
- unique.push({ index, step });
- }
- if (unique.length <= MAX_RECIPE_STEPS) return unique.map(({ step }) => step);
-
- const selected = new Set<number>();
- const add = (rows: Array<{ index: number }>) => rows.forEach(({ index }) => selected.add(index));
- add(unique.slice(0, 6));
- add(unique.slice(-6));
- const important = unique.filter(({ step }) => IMPORTANT_RECIPE_TOOLS.has(step.tool));
- add(important.length <= 12 ? important : [...important.slice(0, 6), ...important.slice(-6)]);
-
- const remaining = MAX_RECIPE_STEPS - selected.size;
- for (let slot = 1; slot <= remaining; slot += 1) {
- const row = unique[Math.round((slot * (unique.length - 1)) / (remaining + 1))];
- if (row) selected.add(row.index);
- }
- if (selected.size < MAX_RECIPE_STEPS) {
- for (const { index } of unique) {
- selected.add(index);
- if (selected.size >= MAX_RECIPE_STEPS) break;
- }
- }
- return unique.filter(({ index }) => selected.has(index)).slice(0, MAX_RECIPE_STEPS).map(({ step }) => step);
-}
-
-function elapsedMs(steps: WorkflowStep[], wallMs: number): number {
- const sum = steps.reduce((n, s) => n + (s.durationMs ?? 0), 0);
- return sum > 0 ? sum : wallMs;
-}
-
-function recipeText(intent: string, project?: string, summary?: string): string {
- return [intent, project, summary].filter(Boolean).join("\n");
-}
-
-function closestRecipe(store: SkillMemoryStore, actor: string, scope: Scope, intent: string, project?: string): LearnedRecipe | undefined {
- let best: { recipe: LearnedRecipe; score: number } | undefined;
- for (const recipe of Object.values(store.recipes)) {
- if (recipe.actor !== actor || recipe.scope !== scope) continue;
- const semantic = hybridSemanticScore(recipeText(intent, project), recipeText(recipe.intent, recipe.project));
- const exact = recipe.normalizedIntent === normalizeSemanticText(intent) ? 0.2 : 0;
- const projectBonus = project && recipe.project && normalizeSemanticText(project) === normalizeSemanticText(recipe.project) ? 0.08 : 0;
- const score = semantic + exact + projectBonus;
- if (!best || score > best.score) best = { recipe, score };
- }
- return best && best.score >= 0.48 ? best.recipe : undefined;
-}
-
-const WORKFLOW_LEASE_MS = 6 * 60 * 60_000;
-const MAX_ACTIVE_PER_ACTOR = 20;
-const workflowIsStale = (workflow: ActiveWorkflow): boolean =>
- Date.now() - new Date(workflow.startedAt).getTime() > WORKFLOW_LEASE_MS;
-
-function pruneStaleWorkflows(store: SkillMemoryStore, actor: string): boolean {
- const bucket = store.active[actor];
- if (!bucket) return false;
- let changed = false;
- for (const [id, workflow] of Object.entries(bucket)) {
- if (!workflowIsStale(workflow)) continue;
- delete bucket[id];
- changed = true;
- }
- if (!Object.keys(bucket).length) delete store.active[actor];
- return changed;
-}
-
-function workflowFor(store: SkillMemoryStore, actor: string, workflowId: string): ActiveWorkflow | undefined {
- return store.active[actor]?.[workflowId];
-}
-
-function removeActiveWorkflow(store: SkillMemoryStore, actor: string, workflowId: string): void {
- const bucket = store.active[actor];
- if (!bucket) return;
- delete bucket[workflowId];
- if (!Object.keys(bucket).length) delete store.active[actor];
-}
-
-export async function startWorkflow(input: {
- actor?: string;
- scope?: Scope;
- intent: string;
- project?: string;
- constraints?: string;
- orchestration?: WorkflowOrchestrationSnapshot;
-}): Promise<{ workflow: ActiveWorkflow; activeWorkflowCount: number }> {
- const actor = actorKey(input.actor);
- const scope: Scope = input.scope ?? "read";
- const intent = safeMemoryText(input.intent, 1000);
- if (!intent) throw new Error("intent must be a non-empty string");
- const store = await loadStore();
- pruneStaleWorkflows(store, actor);
- const bucket = store.active[actor] ?? {};
- if (Object.keys(bucket).length >= MAX_ACTIVE_PER_ACTOR) {
- throw new Error(`this MCP client already has ${MAX_ACTIVE_PER_ACTOR} active workflows; finish or cancel an exact workflow_id first`);
- }
- const workflow: ActiveWorkflow = {
- id: randomUUID(),
- actor,
- scope,
- intent,
- project: input.project ? safeMemoryText(input.project, 240) || undefined : undefined,
- constraints: input.constraints ? safeMemoryText(input.constraints, 500) || undefined : undefined,
- orchestration: sanitizeOrchestration(input.orchestration),
- startedAt: new Date().toISOString(),
- steps: [],
- };
- (store.active[actor] ??= {})[workflow.id] = workflow;
- await persist(store);
- return { workflow, activeWorkflowCount: Object.keys(store.active[actor]).length };
-}
-
-export type ProjectContentionSummary = {
- activeWorkflowCount: number;
- conflictingWorkflowCount: number;
- overlappingPaths: string[];
- overlappingResources: string[];
-};
-
-const normalizedProject = (value?: string) => value?.trim().replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase() ?? "";
-const pathScopeOverlaps = (a: string, b: string): boolean => {
- const left = a.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
- const right = b.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
- return Boolean(left && right && (left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)));
-};
-
-export async function summarizeProjectContention(
- project?: string, affectedPaths: string[] = [], reservedResources: string[] = [],
-): Promise<ProjectContentionSummary> {
- const key = normalizedProject(project);
- if (!key) return { activeWorkflowCount: 0, conflictingWorkflowCount: 0, overlappingPaths: [], overlappingResources: [] };
- const store = await loadStore();
- let changed = false, activeWorkflowCount = 0, conflictingWorkflowCount = 0;
- const overlappingPaths = new Set<string>(), overlappingResources = new Set<string>();
- const resources = reservedResources.map((value) => value.trim().toLowerCase()).filter(Boolean);
- for (const actor of Object.keys(store.active)) {
- changed = pruneStaleWorkflows(store, actor) || changed;
- for (const workflow of Object.values(store.active[actor] ?? {})) {
- if (normalizedProject(workflow.project) !== key) continue;
- activeWorkflowCount += 1;
- let conflict = false;
- for (const requested of affectedPaths) {
- if ((workflow.orchestration?.affectedPaths ?? []).some((active) => pathScopeOverlaps(requested, active))) {
- overlappingPaths.add(requested); conflict = true;
- }
- }
- const activeResources = (workflow.orchestration?.reservedResources ?? []).map((value) => value.trim().toLowerCase());
- for (const requested of resources) {
- if (activeResources.includes(requested)) { overlappingResources.add(requested); conflict = true; }
- }
- if (conflict) conflictingWorkflowCount += 1;
- }
- }
- if (changed) await persist(store);
- return {
- activeWorkflowCount, conflictingWorkflowCount,
- overlappingPaths: [...overlappingPaths].slice(0, 80),
- overlappingResources: [...overlappingResources].slice(0, 40),
- };
-}
-
-export async function countActiveWorkflowsForProject(project?: string): Promise<number> {
- return (await summarizeProjectContention(project)).activeWorkflowCount;
-}
-
-export async function activeWorkflowForActor(actor?: string, workflowId?: string): Promise<ActiveWorkflow | null> {
- if (!actor) return null;
- const store = await loadStore();
- const changed = pruneStaleWorkflows(store, actor);
- const bucket = store.active[actor];
- const workflow = workflowId
- ? bucket?.[workflowId] ?? null
- : (bucket && Object.keys(bucket).length === 1 ? Object.values(bucket)[0] : null);
- if (changed) await persist(store);
- return workflow;
-}
-
-export async function recordWorkflowStep(actor: string | undefined, workflowId: string | undefined, step: WorkflowStepInput): Promise<void> {
- if (!actor || !workflowId) return;
- const store = await loadStore();
- const workflow = workflowFor(store, actor, workflowId);
- if (!workflow) return;
- if (["skills_search", "workflow_start", "workflow_finish", "workflow_cancel"].includes(step.tool)) return;
- const sanitized = sanitizeStoredStep(step);
- if (!sanitized) return;
- workflow.steps.push(sanitized);
- if (workflow.steps.length > 300) workflow.steps.splice(0, workflow.steps.length - 300);
- await persist(store);
-}
-
-export async function cancelWorkflow(input: {
- actor?: string;
- workflowId: string;
- reason?: string;
-}): Promise<CancelWorkflowResult> {
- const actor = actorKey(input.actor);
- const store = await loadStore();
- const workflow = workflowFor(store, actor, input.workflowId);
- if (!workflow) throw new Error("workflow_id was not found for this MSO session");
- removeActiveWorkflow(store, actor, input.workflowId);
- await persist(store);
- const reason = input.reason ? safeMemoryText(input.reason, 500) || undefined : undefined;
- return { workflow, ...(reason ? { reason } : {}) };
-}
-
-export async function finishWorkflow(input: {
- actor?: string;
- recipeActor?: string;
- workflowId: string;
- summary: string;
- success: boolean;
-}): Promise<FinishWorkflowResult> {
- const actor = actorKey(input.actor);
- const recipeOwner = actorKey(input.recipeActor ?? input.actor);
- const store = await loadStore();
- const workflow = workflowFor(store, actor, input.workflowId);
- if (!workflow) throw new Error("workflow_id was not found for this MSO session");
-
- const now = new Date();
- const wallMs = Math.max(0, now.getTime() - new Date(workflow.startedAt).getTime());
- const durationMs = elapsedMs(workflow.steps, wallMs);
- const existing = closestRecipe(store, recipeOwner, workflow.scope, workflow.intent, workflow.project);
- const previousFastestMs = existing?.fastestDurationMs;
- const summary = safeMemoryText(input.summary, 1200) || (input.success ? "completed" : "failed");
- const vector = embedSkillText(recipeText(workflow.intent, workflow.project, summary));
- const timestamp = now.toISOString();
- const compactSteps = compactRecipeSteps(workflow.steps);
- const currentQuality = summarizeWorkflowQuality(workflow.steps);
-
- let recipe: LearnedRecipe;
- if (existing) {
- const attempts = existing.attempts + 1;
- 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);
- recipe = {
- ...existing,
- actor: recipeOwner,
- scope: workflow.scope,
- intent: workflow.intent,
- normalizedIntent: normalizeSemanticText(workflow.intent),
- project: workflow.project,
- summary,
- embeddingVersion: SKILL_EMBEDDING_VERSION,
- embedding: vector,
- lastSteps: workflow.steps,
- bestSteps: faster ? compactSteps : (input.success ? enrichBestSteps(existing.bestSteps, compactSteps) : existing.bestSteps),
- attempts,
- successes,
- failures,
- averageDurationMs: Math.round((existing.averageDurationMs * existing.attempts + durationMs) / attempts),
- fastestDurationMs: input.success ? Math.min(existing.fastestDurationMs ?? durationMs, durationMs) : existing.fastestDurationMs,
- lastDurationMs: durationMs,
- averageWallDurationMs: Math.round((existing.averageWallDurationMs * existing.attempts + wallMs) / attempts),
- lastWallDurationMs: wallMs,
- quality: mergeQuality(existing.quality, currentQuality),
- lastQuality: currentQuality,
- qualityVersion: 1,
- updatedAt: timestamp,
- };
- } else {
- recipe = {
- id: randomUUID(),
- actor: recipeOwner,
- scope: workflow.scope,
- intent: workflow.intent,
- normalizedIntent: normalizeSemanticText(workflow.intent),
- project: workflow.project,
- summary,
- embeddingVersion: SKILL_EMBEDDING_VERSION,
- embedding: vector,
- bestSteps: input.success ? compactSteps : [],
- lastSteps: workflow.steps,
- 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,
- quality: currentQuality,
- lastQuality: currentQuality,
- qualityVersion: 1,
- createdAt: timestamp,
- updatedAt: timestamp,
- };
- }
-
- store.recipes[recipe.id] = recipe;
- removeActiveWorkflow(store, actor, input.workflowId);
- const recipes = Object.values(store.recipes);
- if (recipes.length > 200) {
- recipes
- .sort((a, b) => {
- const qa = a.successes * 10 - a.failures + new Date(a.lastUsedAt ?? a.updatedAt).getTime() / 1e13;
- const qb = b.successes * 10 - b.failures + new Date(b.lastUsedAt ?? b.updatedAt).getTime() / 1e13;
- return qa - qb;
- })
- .slice(0, recipes.length - 200)
- .forEach((r) => delete store.recipes[r.id]);
- }
- await persist(store);
-
- const improvedByMs = input.success && previousFastestMs != null && durationMs < previousFastestMs
- ? previousFastestMs - durationMs
- : undefined;
- return {
- workflow,
- recipe,
- currentDurationMs: durationMs,
- ...(previousFastestMs != null ? { previousFastestMs } : {}),
- ...(improvedByMs != null
- ? { improvedByMs, improvedPct: Math.round((improvedByMs / previousFastestMs!) * 1000) / 10 }
- : {}),
- };
-}
-
-export async function listLearnedRecipes(access: RecipeAccess): Promise<LearnedRecipe[]> {
- const store = await loadStore();
- const recipes = Object.values(store.recipes);
- const visible = access.ownerView
- ? recipes
- : recipes.filter((recipe) => recipe.actor === access.actor && allows(access.scope, recipe.scope));
- return visible.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
-}
-
-export async function markRecipeUsed(id: string, access: RecipeAccess): Promise<void> {
- const store = await loadStore();
- const recipe = store.recipes[id];
- if (!recipe) return;
- if (!access.ownerView) {
- if (recipe.actor !== access.actor || !allows(access.scope, recipe.scope)) return;
- }
- recipe.lastUsedAt = new Date().toISOString();
- await persist(store);
-}
-
-/** Test-only cache reset; harmless in production and avoids module-reset tricks. */
-export function resetSkillMemoryCache(): void {
- cache = null;
- cachePath = "";
- loadInFlight.clear();
- writeChain = Promise.resolve();
-}
+// Compatibility facade. Workflow lifecycle/recipes are owned by lib/workflow;
+// skill discovery consumes them but no longer owns their persistence.
+export {
+ startWorkflow,
+ summarizeProjectContention,
+ countActiveWorkflowsForProject,
+ activeWorkflowForActor,
+ recordWorkflowStep,
+ cancelWorkflow,
+ finishWorkflow,
+ listLearnedRecipes,
+ markRecipeUsed,
+ resetWorkflowStoreCache as resetSkillMemoryCache,
+ summarizeWorkflowQuality,
+} from "@/lib/workflow";
+export type {
+ WorkflowStepState,
+ WorkflowStep,
+ ActiveWorkflow,
+ WorkflowQuality,
+ LearnedRecipe,
+ FinishWorkflowResult,
+ CancelWorkflowResult,
+ RecipeAccess,
+ ProjectContentionSummary,
+} from "@/lib/workflow";
diff --git a/lib/skills/search.ts b/lib/skills/search.ts
index 6e281dfa..5504cea3 100644
--- a/lib/skills/search.ts
+++ b/lib/skills/search.ts
@@ -1,5 +1,5 @@
import { catalogSkillsDetailed, readSkillFile, type ProjectRef, type SkillInfo, type SkillScanReport } from "./catalog";
-import { listLearnedRecipes, type LearnedRecipe, type RecipeAccess } from "./memory";
+import { listLearnedRecipes, type LearnedRecipe, type RecipeAccess } from "@/lib/workflow";
import { embedSkillText, hybridSemanticScore, prepareSemanticQuery, SKILL_EMBEDDING_VERSION } from "./semantic";
export type SkillSearchToolDoc = {
diff --git a/lib/skills/memory-contention.test.ts b/lib/workflow/contention.test.ts
similarity index 97%
rename from lib/skills/memory-contention.test.ts
rename to lib/workflow/contention.test.ts
index 066a0517..3e0bbbcc 100644
--- a/lib/skills/memory-contention.test.ts
+++ b/lib/workflow/contention.test.ts
@@ -5,7 +5,7 @@ import path from "node:path";
const dir = await fs.mkdtemp(path.join(os.tmpdir(), "mso-contention-memory-"));
process.env.OS_SKILL_MEMORY_STORE = path.join(dir, "memory.json");
-const memory = await import("./memory");
+const memory = await import("./index");
const orchestration = (affectedPaths: string[], reservedResources: string[]) => ({
risk: "medium" as const,
@@ -33,7 +33,7 @@ const orchestration = (affectedPaths: string[], reservedResources: string[]) =>
describe("workflow scope collision metadata", () => {
beforeEach(async () => {
await fs.rm(process.env.OS_SKILL_MEMORY_STORE!, { force: true });
- memory.resetSkillMemoryCache();
+ memory.resetWorkflowStoreCache();
});
afterAll(async () => { await fs.rm(dir, { recursive: true, force: true }); });
diff --git a/lib/workflow/contention.ts b/lib/workflow/contention.ts
new file mode 100644
index 00000000..af0802f2
--- /dev/null
+++ b/lib/workflow/contention.ts
@@ -0,0 +1,51 @@
+import { pruneStaleWorkflows } from "./state";
+import { loadWorkflowStore, persistWorkflowStore } from "./storage";
+import type { ProjectContentionSummary } from "./types";
+
+const normalizedProject = (value?: string) => value?.trim().replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase() ?? "";
+const pathScopeOverlaps = (a: string, b: string): boolean => {
+ const left = a.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+ const right = b.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+ return Boolean(left && right && (left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)));
+};
+
+export async function summarizeProjectContention(
+ project?: string,
+ affectedPaths: string[] = [],
+ reservedResources: string[] = [],
+): Promise<ProjectContentionSummary> {
+ const key = normalizedProject(project);
+ if (!key) return { activeWorkflowCount: 0, conflictingWorkflowCount: 0, overlappingPaths: [], overlappingResources: [] };
+ const store = await loadWorkflowStore();
+ let changed = false, activeWorkflowCount = 0, conflictingWorkflowCount = 0;
+ const overlappingPaths = new Set<string>(), overlappingResources = new Set<string>();
+ const resources = reservedResources.map((value) => value.trim().toLowerCase()).filter(Boolean);
+ for (const actor of Object.keys(store.active)) {
+ changed = pruneStaleWorkflows(store, actor) || changed;
+ for (const workflow of Object.values(store.active[actor] ?? {})) {
+ if (normalizedProject(workflow.project) !== key) continue;
+ activeWorkflowCount += 1;
+ let conflict = false;
+ for (const requested of affectedPaths) {
+ if ((workflow.orchestration?.affectedPaths ?? []).some((active) => pathScopeOverlaps(requested, active))) {
+ overlappingPaths.add(requested); conflict = true;
+ }
+ }
+ const activeResources = (workflow.orchestration?.reservedResources ?? []).map((value) => value.trim().toLowerCase());
+ for (const requested of resources) {
+ if (activeResources.includes(requested)) { overlappingResources.add(requested); conflict = true; }
+ }
+ if (conflict) conflictingWorkflowCount += 1;
+ }
+ }
+ if (changed) await persistWorkflowStore(store);
+ return {
+ activeWorkflowCount, conflictingWorkflowCount,
+ overlappingPaths: [...overlappingPaths].slice(0, 80),
+ overlappingResources: [...overlappingResources].slice(0, 40),
+ };
+}
+
+export async function countActiveWorkflowsForProject(project?: string): Promise<number> {
+ return (await summarizeProjectContention(project)).activeWorkflowCount;
+}
diff --git a/lib/workflow/index.ts b/lib/workflow/index.ts
new file mode 100644
index 00000000..f37c2588
--- /dev/null
+++ b/lib/workflow/index.ts
@@ -0,0 +1,9 @@
+export { startWorkflow, activeWorkflowForActor, recordWorkflowStep, cancelWorkflow } from "./lifecycle";
+export { summarizeProjectContention, countActiveWorkflowsForProject } from "./contention";
+export { finishWorkflow, listLearnedRecipes, markRecipeUsed } from "./learning";
+export { resetWorkflowStoreCache } from "./storage";
+export { summarizeWorkflowQuality } from "./quality";
+export type {
+ WorkflowStepState, WorkflowStep, ActiveWorkflow, WorkflowQuality, LearnedRecipe,
+ FinishWorkflowResult, CancelWorkflowResult, RecipeAccess, ProjectContentionSummary,
+} from "./types";
diff --git a/lib/workflow/learning.ts b/lib/workflow/learning.ts
new file mode 100644
index 00000000..b445cf8a
--- /dev/null
+++ b/lib/workflow/learning.ts
@@ -0,0 +1,118 @@
+import { randomUUID } from "node:crypto";
+import { allows } from "@/lib/capabilities/scope";
+import { embedSkillText, 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";
+import { actorKey, removeActiveWorkflow, workflowFor } from "./state";
+import { loadWorkflowStore, persistWorkflowStore } from "./storage";
+import type { FinishWorkflowResult, LearnedRecipe, RecipeAccess } from "./types";
+
+export async function finishWorkflow(input: {
+ actor?: string;
+ recipeActor?: string;
+ workflowId: string;
+ summary: string;
+ success: boolean;
+}): Promise<FinishWorkflowResult> {
+ const actor = actorKey(input.actor);
+ const recipeOwner = actorKey(input.recipeActor ?? input.actor);
+ const store = await loadWorkflowStore();
+ const workflow = workflowFor(store, actor, input.workflowId);
+ if (!workflow) throw new Error("workflow_id was not found for this MSO session");
+
+ const now = new Date();
+ const wallMs = Math.max(0, now.getTime() - new Date(workflow.startedAt).getTime());
+ const durationMs = elapsedMs(workflow.steps, wallMs);
+ const existing = closestRecipe(store, recipeOwner, workflow.scope, workflow.intent, workflow.project);
+ const previousFastestMs = existing?.fastestDurationMs;
+ const summary = safeMemoryText(input.summary, 1200) || (input.success ? "completed" : "failed");
+ const vector = embedSkillText(recipeText(workflow.intent, workflow.project, summary));
+ const timestamp = now.toISOString();
+ const compactSteps = compactRecipeSteps(workflow.steps);
+ const currentQuality = summarizeWorkflowQuality(workflow.steps);
+
+ let recipe: LearnedRecipe;
+ if (existing) {
+ const attempts = existing.attempts + 1;
+ 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);
+ recipe = {
+ ...existing,
+ actor: recipeOwner,
+ scope: workflow.scope,
+ intent: workflow.intent,
+ normalizedIntent: normalizeSemanticText(workflow.intent),
+ project: workflow.project,
+ summary,
+ embeddingVersion: SKILL_EMBEDDING_VERSION,
+ embedding: vector,
+ lastSteps: workflow.steps,
+ bestSteps: faster ? compactSteps : (input.success ? enrichBestSteps(existing.bestSteps, compactSteps) : existing.bestSteps),
+ attempts,
+ successes,
+ failures,
+ averageDurationMs: Math.round((existing.averageDurationMs * existing.attempts + durationMs) / attempts),
+ fastestDurationMs: input.success ? Math.min(existing.fastestDurationMs ?? durationMs, durationMs) : existing.fastestDurationMs,
+ lastDurationMs: durationMs,
+ averageWallDurationMs: Math.round((existing.averageWallDurationMs * existing.attempts + wallMs) / attempts),
+ lastWallDurationMs: wallMs,
+ quality: mergeQuality(existing.quality, currentQuality),
+ lastQuality: currentQuality,
+ qualityVersion: 1,
+ updatedAt: timestamp,
+ };
+ } else {
+ recipe = {
+ id: randomUUID(), actor: recipeOwner, scope: workflow.scope, intent: workflow.intent,
+ normalizedIntent: normalizeSemanticText(workflow.intent), project: workflow.project, summary,
+ embeddingVersion: SKILL_EMBEDDING_VERSION, embedding: vector,
+ bestSteps: input.success ? compactSteps : [], lastSteps: workflow.steps,
+ 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,
+ quality: currentQuality, lastQuality: currentQuality, qualityVersion: 1,
+ createdAt: timestamp, updatedAt: timestamp,
+ };
+ }
+
+ store.recipes[recipe.id] = recipe;
+ removeActiveWorkflow(store, actor, input.workflowId);
+ const recipes = Object.values(store.recipes);
+ if (recipes.length > 200) {
+ recipes
+ .sort((a, b) => {
+ const qa = a.successes * 10 - a.failures + new Date(a.lastUsedAt ?? a.updatedAt).getTime() / 1e13;
+ const qb = b.successes * 10 - b.failures + new Date(b.lastUsedAt ?? b.updatedAt).getTime() / 1e13;
+ return qa - qb;
+ })
+ .slice(0, recipes.length - 200)
+ .forEach((row) => delete store.recipes[row.id]);
+ }
+ await persistWorkflowStore(store);
+
+ const improvedByMs = input.success && previousFastestMs != null && durationMs < previousFastestMs
+ ? previousFastestMs - durationMs : undefined;
+ return {
+ workflow, recipe, currentDurationMs: durationMs,
+ ...(previousFastestMs != null ? { previousFastestMs } : {}),
+ ...(improvedByMs != null ? { improvedByMs, improvedPct: Math.round((improvedByMs / previousFastestMs!) * 1000) / 10 } : {}),
+ };
+}
+
+export async function listLearnedRecipes(access: RecipeAccess): Promise<LearnedRecipe[]> {
+ const store = await loadWorkflowStore();
+ const recipes = Object.values(store.recipes);
+ const visible = access.ownerView ? recipes : recipes.filter((recipe) => recipe.actor === access.actor && allows(access.scope, recipe.scope));
+ return visible.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+}
+
+export async function markRecipeUsed(id: string, access: RecipeAccess): Promise<void> {
+ const store = await loadWorkflowStore();
+ const recipe = store.recipes[id];
+ if (!recipe) return;
+ if (!access.ownerView && (recipe.actor !== access.actor || !allows(access.scope, recipe.scope))) return;
+ recipe.lastUsedAt = new Date().toISOString();
+ await persistWorkflowStore(store);
+}
diff --git a/lib/workflow/lifecycle.ts b/lib/workflow/lifecycle.ts
new file mode 100644
index 00000000..0088e897
--- /dev/null
+++ b/lib/workflow/lifecycle.ts
@@ -0,0 +1,71 @@
+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 { actorKey, pruneStaleWorkflows, removeActiveWorkflow, workflowFor } from "./state";
+import { loadWorkflowStore, persistWorkflowStore } from "./storage";
+import type { ActiveWorkflow, CancelWorkflowResult, WorkflowStepInput } from "./types";
+
+const MAX_ACTIVE_PER_ACTOR = 20;
+
+export async function startWorkflow(input: {
+ actor?: string;
+ scope?: Scope;
+ intent: string;
+ project?: string;
+ constraints?: string;
+ orchestration?: WorkflowOrchestrationSnapshot;
+}): Promise<{ workflow: ActiveWorkflow; activeWorkflowCount: number }> {
+ const actor = actorKey(input.actor);
+ const scope: Scope = input.scope ?? "read";
+ const intent = safeMemoryText(input.intent, 1000);
+ if (!intent) throw new Error("intent must be a non-empty string");
+ const store = await loadWorkflowStore();
+ pruneStaleWorkflows(store, actor);
+ const bucket = store.active[actor] ?? {};
+ if (Object.keys(bucket).length >= MAX_ACTIVE_PER_ACTOR)
+ throw new Error(`this MCP client already has ${MAX_ACTIVE_PER_ACTOR} active workflows; finish or cancel an exact workflow_id first`);
+ const workflow: ActiveWorkflow = {
+ id: randomUUID(), actor, scope, intent,
+ project: input.project ? safeMemoryText(input.project, 240) || undefined : undefined,
+ constraints: input.constraints ? safeMemoryText(input.constraints, 500) || undefined : undefined,
+ orchestration: sanitizeOrchestration(input.orchestration),
+ startedAt: new Date().toISOString(), steps: [],
+ };
+ (store.active[actor] ??= {})[workflow.id] = workflow;
+ await persistWorkflowStore(store);
+ return { workflow, activeWorkflowCount: Object.keys(store.active[actor]).length };
+}
+
+export async function activeWorkflowForActor(actor?: string, workflowId?: string): Promise<ActiveWorkflow | null> {
+ if (!actor) return null;
+ const store = await loadWorkflowStore();
+ const changed = pruneStaleWorkflows(store, actor);
+ const bucket = store.active[actor];
+ const workflow = workflowId ? bucket?.[workflowId] ?? null : (bucket && Object.keys(bucket).length === 1 ? Object.values(bucket)[0] : null);
+ if (changed) await persistWorkflowStore(store);
+ return workflow;
+}
+
+export async function recordWorkflowStep(actor: string | undefined, workflowId: string | undefined, step: WorkflowStepInput): Promise<void> {
+ if (!actor || !workflowId) return;
+ const store = await loadWorkflowStore();
+ const workflow = workflowFor(store, actor, workflowId);
+ if (!workflow || ["skills_search", "workflow_start", "workflow_finish", "workflow_cancel"].includes(step.tool)) return;
+ const sanitized = sanitizeStoredStep(step);
+ if (!sanitized) return;
+ workflow.steps.push(sanitized);
+ if (workflow.steps.length > 300) workflow.steps.splice(0, workflow.steps.length - 300);
+ await persistWorkflowStore(store);
+}
+
+export async function cancelWorkflow(input: { actor?: string; workflowId: string; reason?: string }): Promise<CancelWorkflowResult> {
+ const actor = actorKey(input.actor);
+ const store = await loadWorkflowStore();
+ const workflow = workflowFor(store, actor, input.workflowId);
+ if (!workflow) throw new Error("workflow_id was not found for this MSO session");
+ removeActiveWorkflow(store, actor, input.workflowId);
+ await persistWorkflowStore(store);
+ const reason = input.reason ? safeMemoryText(input.reason, 500) || undefined : undefined;
+ return { workflow, ...(reason ? { reason } : {}) };
+}
diff --git a/lib/skills/memory-quality.test.ts b/lib/workflow/quality.test.ts
similarity index 95%
rename from lib/skills/memory-quality.test.ts
rename to lib/workflow/quality.test.ts
index 9e467c67..639fc447 100644
--- a/lib/skills/memory-quality.test.ts
+++ b/lib/workflow/quality.test.ts
@@ -5,10 +5,10 @@ import path from "node:path";
const dir = await fs.mkdtemp(path.join(os.tmpdir(), "mso-skill-quality-"));
process.env.OS_SKILL_MEMORY_STORE = path.join(dir, "memory.json");
-const memory = await import("./memory");
+const memory = await import("./index");
describe("learned workflow quality telemetry", () => {
- beforeEach(async () => { await fs.rm(process.env.OS_SKILL_MEMORY_STORE!, { force: true }); memory.resetSkillMemoryCache(); });
+ 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("tracks retries, invalid args, failures, denials, rollback signals and latency", async () => {
diff --git a/lib/workflow/quality.ts b/lib/workflow/quality.ts
new file mode 100644
index 00000000..1eea8aa4
--- /dev/null
+++ b/lib/workflow/quality.ts
@@ -0,0 +1,92 @@
+import type { WorkflowQuality, WorkflowStep } from "./types";
+
+export function emptyQuality(): WorkflowQuality {
+ return { stepAttempts: 0, completedSteps: 0, failedSteps: 0, deniedSteps: 0, rateLimitedSteps: 0, invalidArgSteps: 0, retries: 0, rollbackSignals: 0, timedSteps: 0, totalStepDurationMs: 0, averageStepDurationMs: 0 };
+}
+
+export function normalizeQuality(value: unknown): WorkflowQuality {
+ const base = emptyQuality();
+ if (!value || typeof value !== "object") return base;
+ const row = value as Partial<WorkflowQuality>;
+ for (const key of Object.keys(base) as Array<keyof WorkflowQuality>) {
+ const n = Number(row[key]);
+ if (Number.isFinite(n) && n >= 0) base[key] = Math.round(n) as never;
+ }
+ base.averageStepDurationMs = base.timedSteps ? Math.round(base.totalStepDurationMs / base.timedSteps) : 0;
+ return base;
+}
+
+export function summarizeWorkflowQuality(steps: WorkflowStep[]): WorkflowQuality {
+ const out = emptyQuality(), pending = new Set<string>();
+ for (const step of steps) {
+ out.stepAttempts += 1;
+ if (pending.has(step.tool)) { out.retries += 1; pending.delete(step.tool); }
+ if (step.state === "completed") out.completedSteps += 1;
+ else {
+ pending.add(step.tool);
+ if (step.state === "failed") out.failedSteps += 1;
+ else if (step.state === "denied") out.deniedSteps += 1;
+ else if (step.state === "rate_limited") out.rateLimitedSteps += 1;
+ else out.invalidArgSteps += 1;
+ }
+ if (typeof step.durationMs === "number") { out.timedSteps += 1; out.totalStepDurationMs += step.durationMs; }
+ if (step.state === "completed" && /\b(rollback|restore|revert)\b/i.test(JSON.stringify([step.tool, step.target, step.args]))) out.rollbackSignals += 1;
+ }
+ out.averageStepDurationMs = out.timedSteps ? Math.round(out.totalStepDurationMs / out.timedSteps) : 0;
+ return out;
+}
+
+export function mergeQuality(a: WorkflowQuality, b: WorkflowQuality): WorkflowQuality {
+ const out = emptyQuality();
+ for (const key of ["stepAttempts", "completedSteps", "failedSteps", "deniedSteps", "rateLimitedSteps", "invalidArgSteps", "retries", "rollbackSignals", "timedSteps", "totalStepDurationMs"] as const)
+ out[key] = a[key] + b[key];
+ out.averageStepDurationMs = out.timedSteps ? Math.round(out.totalStepDurationMs / out.timedSteps) : 0;
+ return out;
+}
+
+export function enrichBestSteps(best: WorkflowStep[], current: WorkflowStep[]): WorkflowStep[] {
+ if (best.length !== current.length || best.some((step, i) => step.tool !== current[i]?.tool)) return best;
+ return best.map((step, i) => ({ ...step, args: step.args ?? current[i]?.args, target: step.target ?? current[i]?.target }));
+}
+
+const MAX_RECIPE_STEPS = 24;
+const IMPORTANT_RECIPE_TOOLS = new Set([
+ "fs_write", "fs_mkdir", "fs_move", "fs_copy", "fs_delete",
+ "apps_power", "browser_power", "exec_run", "screen_capture",
+]);
+
+export function compactRecipeSteps(steps: WorkflowStep[]): WorkflowStep[] {
+ const unique: Array<{ index: number; step: WorkflowStep }> = [];
+ const seen = new Set<string>();
+ for (const [index, step] of steps.entries()) {
+ if (step.state !== "completed") continue;
+ const signature = JSON.stringify([step.tool, step.target ?? "", step.args ?? {}]);
+ if (seen.has(signature)) continue;
+ seen.add(signature);
+ unique.push({ index, step });
+ }
+ if (unique.length <= MAX_RECIPE_STEPS) return unique.map(({ step }) => step);
+ const selected = new Set<number>();
+ const add = (rows: Array<{ index: number }>) => rows.forEach(({ index }) => selected.add(index));
+ add(unique.slice(0, 6));
+ add(unique.slice(-6));
+ const important = unique.filter(({ step }) => IMPORTANT_RECIPE_TOOLS.has(step.tool));
+ add(important.length <= 12 ? important : [...important.slice(0, 6), ...important.slice(-6)]);
+ const remaining = MAX_RECIPE_STEPS - selected.size;
+ for (let slot = 1; slot <= remaining; slot += 1) {
+ const row = unique[Math.round((slot * (unique.length - 1)) / (remaining + 1))];
+ if (row) selected.add(row.index);
+ }
+ if (selected.size < MAX_RECIPE_STEPS) {
+ for (const { index } of unique) {
+ selected.add(index);
+ if (selected.size >= MAX_RECIPE_STEPS) break;
+ }
+ }
+ return unique.filter(({ index }) => selected.has(index)).slice(0, MAX_RECIPE_STEPS).map(({ step }) => step);
+}
+
+export function elapsedMs(steps: WorkflowStep[], wallMs: number): number {
+ const sum = steps.reduce((n, step) => n + (step.durationMs ?? 0), 0);
+ return sum > 0 ? sum : wallMs;
+}
diff --git a/lib/workflow/recipes.ts b/lib/workflow/recipes.ts
new file mode 100644
index 00000000..57b9ab3f
--- /dev/null
+++ b/lib/workflow/recipes.ts
@@ -0,0 +1,26 @@
+import type { Scope } from "@/lib/capabilities/scope";
+import { hybridSemanticScore, normalizeSemanticText } from "@/lib/skills/semantic";
+import type { LearnedRecipe, WorkflowStoreState } from "./types";
+
+export function recipeText(intent: string, project?: string, summary?: string): string {
+ return [intent, project, summary].filter(Boolean).join("\n");
+}
+
+export function closestRecipe(
+ store: WorkflowStoreState,
+ actor: string,
+ scope: Scope,
+ intent: string,
+ project?: string,
+): LearnedRecipe | undefined {
+ let best: { recipe: LearnedRecipe; score: number } | undefined;
+ for (const recipe of Object.values(store.recipes)) {
+ if (recipe.actor !== actor || recipe.scope !== scope) continue;
+ const semantic = hybridSemanticScore(recipeText(intent, project), recipeText(recipe.intent, recipe.project));
+ const exact = recipe.normalizedIntent === normalizeSemanticText(intent) ? 0.2 : 0;
+ const projectBonus = project && recipe.project && normalizeSemanticText(project) === normalizeSemanticText(recipe.project) ? 0.08 : 0;
+ const score = semantic + exact + projectBonus;
+ if (!best || score > best.score) best = { recipe, score };
+ }
+ return best && best.score >= 0.48 ? best.recipe : undefined;
+}
diff --git a/lib/workflow/sanitize.ts b/lib/workflow/sanitize.ts
new file mode 100644
index 00000000..85feac1a
--- /dev/null
+++ b/lib/workflow/sanitize.ts
@@ -0,0 +1,188 @@
+import os from "node:os";
+import path from "node:path";
+import type { Scope } from "@/lib/capabilities/scope";
+import type { WorkflowOrchestrationSnapshot } from "@/lib/contracts/orchestration";
+import { normalizeQuality } from "./quality";
+import type {
+ ActiveWorkflow,
+ ActiveWorkflowBuckets,
+ LearnedRecipe,
+ WorkflowStep,
+ WorkflowStepInput,
+ WorkflowStepState,
+} 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;
+}
+
+export function sanitizeOrchestration(value: unknown): WorkflowOrchestrationSnapshot | undefined {
+ if (!value || typeof value !== "object") return undefined;
+ const row = value as Partial<WorkflowOrchestrationSnapshot>;
+ const risks = ["low", "medium", "high"] as const;
+ const complexities = ["light", "medium", "heavy"] as const;
+ const contentions = ["none", "possible", "high"] as const;
+ const relevances = ["low", "medium", "high"] as const;
+ const isolations = ["direct", "optional-worktree", "isolated-worktree"] as const;
+ const verifications = ["targeted", "affected", "full"] as const;
+ if (!risks.includes(row.risk as never) || !complexities.includes(row.complexity as never) ||
+ !contentions.includes(row.contention as never) || !relevances.includes(row.memoryRelevance as never) ||
+ !isolations.includes(row.isolation as never) || !verifications.includes(row.verification as never)) return undefined;
+ const strings = (candidate: unknown, maxItems: number, maxLen: number) => Array.isArray(candidate)
+ ? candidate.filter((item): item is string => typeof item === "string").map((item) => safeMemoryText(item, maxLen)).filter(Boolean).slice(0, maxItems)
+ : [];
+ return {
+ risk: row.risk!, complexity: row.complexity!, contention: row.contention!, memoryRelevance: row.memoryRelevance!,
+ isolation: row.isolation!, verification: row.verification!, reasons: strings(row.reasons, 12, 240),
+ sharedResourceWarnings: strings(row.sharedResourceWarnings, 12, 240), changedPaths: strings(row.changedPaths, 80, 240),
+ affectedPaths: strings(row.affectedPaths, 80, 240), reservedResources: strings(row.reservedResources, 40, 160),
+ overlappingPaths: strings(row.overlappingPaths, 80, 240), overlappingResources: strings(row.overlappingResources, 40, 160),
+ activeProjectWorkflows: Math.max(0, Math.min(100, Math.round(Number(row.activeProjectWorkflows) || 0))),
+ conflictingWorkflowCount: Math.max(0, Math.min(100, Math.round(Number(row.conflictingWorkflowCount) || 0))),
+ memoryHits: Math.max(0, Math.min(100, Math.round(Number(row.memoryHits) || 0))),
+ contextEstimateTokens: Math.max(0, Math.min(1_000_000, Math.round(Number(row.contextEstimateTokens) || 0))),
+ cleanupState: row.cleanupState === "pending" || row.cleanupState === "complete" ? row.cleanupState : "not-required",
+ ...(typeof row.workspacePath === "string" ? { workspacePath: safeMemoryText(row.workspacePath, 240) } : {}),
+ ...(typeof row.baseCommit === "string" ? { baseCommit: safeMemoryText(row.baseCommit, 80) } : {}),
+ ...(typeof row.baseBranch === "string" ? { baseBranch: safeMemoryText(row.baseBranch, 160) } : {}),
+ ...(typeof row.recipeUsed === "string" ? { recipeUsed: safeMemoryText(row.recipeUsed, 120) } : {}),
+ createdAt: typeof row.createdAt === "string" && Number.isFinite(Date.parse(row.createdAt)) ? new Date(row.createdAt).toISOString() : new Date(0).toISOString(),
+ };
+}
+
+function safeCommandShape(command: string): string | undefined {
+ const programs: string[] = [];
+ for (const segment of command.replace(/[\r\n]+/g, " ").split(/&&|\|\||[;|]/)) {
+ const tokens = segment.trim().split(/\s+/).filter(Boolean);
+ let program: string | undefined;
+ for (const token of tokens) {
+ if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token)) continue;
+ if (!/^[A-Za-z0-9_./@+-]+$/.test(token) || token.startsWith("-")) continue;
+ program = path.basename(token).slice(0, 64);
+ break;
+ }
+ if (program && !programs.includes(program)) programs.push(program);
+ if (programs.length >= 8) break;
+ }
+ return programs.length ? programs.join(" → ") : undefined;
+}
+
+function safeTarget(tool: string, target?: string): string | undefined {
+ if (!target) return undefined;
+ if (tool === "exec_run") return safeCommandShape(target);
+ let out = target
+ .replace(/([?&](?:token|key|secret|password|code)=)[^&\s]+/gi, "$1[redacted]")
+ .replace(/\b(?:bearer\s+)?(?:sk|pk|ghp|mso_mcp)_[a-z0-9_-]{8,}\b/gi, "[redacted]")
+ .replace(/\b(password|token|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[redacted]");
+ out = out.replace(new RegExp(`^${os.homedir().replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`), "~");
+ return out.length > 160 ? `${out.slice(0, 160)}…` : out;
+}
+
+const SAFE_TOOL_ARGS: Record<string, readonly string[]> = {
+ fs_list: ["path", "includeHidden"], fs_read: ["path"], fs_search: ["query", "root"], fs_usage: ["path"],
+ apps_logs: ["id"], projects_list: ["query", "limit", "offset"], project_capabilities: ["project"],
+ project_function_call: ["project", "name"], project_memory_search: ["project", "query", "kind", "limit", "include_history"],
+ project_memory_upsert: ["project", "kind", "source", "result", "status"], skills_list: ["project", "trust", "limit", "offset"],
+ skills_read: ["name"], screen_capture: ["shell", "width", "height"], fs_write: ["path"], fs_mkdir: ["path"],
+ fs_move: ["from", "to"], fs_copy: ["from", "to"], fs_delete: ["path"], apps_power: ["id", "action"],
+ exec_run: ["cwd"], browser_power: ["on"],
+};
+
+function safeArgs(tool: string, args?: Record<string, unknown>): Record<string, string | number | boolean> | undefined {
+ if (!args) return undefined;
+ const keys = SAFE_TOOL_ARGS[tool];
+ if (!keys) return undefined;
+ const out: Record<string, string | number | boolean> = {};
+ for (const key of keys) {
+ const value = args[key];
+ if (typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value))) out[key] = value;
+ else if (typeof value === "string" && value) {
+ const safe = safeMemoryText(value, 240);
+ if (safe) out[key] = safe;
+ }
+ }
+ return Object.keys(out).length ? out : undefined;
+}
+
+export function sanitizeStoredStep(value: unknown): WorkflowStep | null {
+ if (!value || typeof value !== "object") return null;
+ const row = value as Partial<WorkflowStepInput>;
+ if (typeof row.id !== "string" || typeof row.tool !== "string" ||
+ !["completed", "failed", "denied", "rate_limited", "invalid_args"].includes(String(row.state)) ||
+ typeof row.ts !== "string") return null;
+ const durationMs = typeof row.durationMs === "number" && Number.isFinite(row.durationMs)
+ ? Math.max(0, Math.min(86_400_000, Math.round(row.durationMs))) : undefined;
+ return {
+ id: safeMemoryText(row.id, 160), tool: safeMemoryText(row.tool, 120), state: row.state as WorkflowStepState,
+ 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(),
+ };
+}
+
+function isActiveWorkflow(value: unknown): value is ActiveWorkflow {
+ if (!value || typeof value !== "object") return false;
+ const row = value as Partial<ActiveWorkflow>;
+ return typeof row.id === "string" && typeof row.actor === "string" && typeof row.intent === "string" &&
+ typeof row.startedAt === "string" && Array.isArray(row.steps);
+}
+
+export function normalizeActive(value: unknown): ActiveWorkflowBuckets {
+ if (!value || typeof value !== "object") return {};
+ const active: ActiveWorkflowBuckets = {};
+ for (const [legacyActor, candidate] of Object.entries(value as Record<string, unknown>)) {
+ if (isActiveWorkflow(candidate)) {
+ const actor = candidate.actor || legacyActor;
+ (active[actor] ??= {})[candidate.id] = {
+ ...candidate, scope: candidate.scope ?? "read", intent: safeMemoryText(candidate.intent, 1000),
+ project: candidate.project ? safeMemoryText(candidate.project, 240) || undefined : undefined,
+ constraints: candidate.constraints ? safeMemoryText(candidate.constraints, 500) || undefined : undefined,
+ orchestration: sanitizeOrchestration(candidate.orchestration),
+ steps: candidate.steps.map(sanitizeStoredStep).filter((step): step is WorkflowStep => Boolean(step)),
+ };
+ continue;
+ }
+ if (!candidate || typeof candidate !== "object") continue;
+ for (const workflow of Object.values(candidate as Record<string, unknown>)) {
+ if (!isActiveWorkflow(workflow)) continue;
+ const actor = workflow.actor || legacyActor;
+ (active[actor] ??= {})[workflow.id] = {
+ ...workflow, scope: workflow.scope ?? "read", intent: safeMemoryText(workflow.intent, 1000),
+ project: workflow.project ? safeMemoryText(workflow.project, 240) || undefined : undefined,
+ constraints: workflow.constraints ? safeMemoryText(workflow.constraints, 500) || undefined : undefined,
+ orchestration: sanitizeOrchestration(workflow.orchestration),
+ steps: workflow.steps.map(sanitizeStoredStep).filter((step): step is WorkflowStep => Boolean(step)),
+ };
+ }
+ }
+ return active;
+}
+
+export function normalizeRecipes(value: unknown): Record<string, LearnedRecipe> {
+ if (!value || typeof value !== "object") return {};
+ const out: Record<string, LearnedRecipe> = {};
+ for (const [id, candidate] of Object.entries(value as Record<string, unknown>)) {
+ if (!candidate || typeof candidate !== "object") continue;
+ const row = candidate as Partial<LearnedRecipe>;
+ if (typeof row.id !== "string" || typeof row.intent !== "string" || !Array.isArray(row.bestSteps)) continue;
+ const scope: Scope = row.scope === "write" || row.scope === "exec" ? row.scope : "read";
+ const intent = safeMemoryText(row.intent, 1000);
+ if (!intent) continue;
+ out[id] = {
+ ...(row as LearnedRecipe), actor: typeof row.actor === "string" && row.actor ? row.actor : "legacy:owner",
+ scope, intent, project: row.project ? safeMemoryText(row.project, 240) || undefined : undefined,
+ 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)) : [],
+ quality: normalizeQuality(row.quality), lastQuality: normalizeQuality(row.lastQuality),
+ ...(row.qualityVersion === 1 ? { qualityVersion: 1 as const } : {}),
+ };
+ }
+ return out;
+}
diff --git a/lib/workflow/state.ts b/lib/workflow/state.ts
new file mode 100644
index 00000000..54a6f6b5
--- /dev/null
+++ b/lib/workflow/state.ts
@@ -0,0 +1,35 @@
+import type { ActiveWorkflow, WorkflowStoreState } from "./types";
+
+const WORKFLOW_LEASE_MS = 6 * 60 * 60_000;
+
+export function actorKey(actor?: string): string {
+ if (!actor) throw new Error("workflow memory needs an authenticated MCP actor");
+ return actor;
+}
+
+const workflowIsStale = (workflow: ActiveWorkflow): boolean =>
+ Date.now() - new Date(workflow.startedAt).getTime() > WORKFLOW_LEASE_MS;
+
+export function pruneStaleWorkflows(store: WorkflowStoreState, actor: string): boolean {
+ const bucket = store.active[actor];
+ if (!bucket) return false;
+ let changed = false;
+ for (const [id, workflow] of Object.entries(bucket)) {
+ if (!workflowIsStale(workflow)) continue;
+ delete bucket[id];
+ changed = true;
+ }
+ if (!Object.keys(bucket).length) delete store.active[actor];
+ return changed;
+}
+
+export function workflowFor(store: WorkflowStoreState, actor: string, workflowId: string): ActiveWorkflow | undefined {
+ return store.active[actor]?.[workflowId];
+}
+
+export function removeActiveWorkflow(store: WorkflowStoreState, actor: string, workflowId: string): void {
+ const bucket = store.active[actor];
+ if (!bucket) return;
+ delete bucket[workflowId];
+ if (!Object.keys(bucket).length) delete store.active[actor];
+}
diff --git a/lib/workflow/storage.ts b/lib/workflow/storage.ts
new file mode 100644
index 00000000..5d486334
--- /dev/null
+++ b/lib/workflow/storage.ts
@@ -0,0 +1,70 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { normalizeActive, normalizeRecipes } from "./sanitize";
+import type { WorkflowStoreState } from "./types";
+
+const EMPTY = (): WorkflowStoreState => ({ version: 3, active: {}, recipes: {} });
+let cache: WorkflowStoreState | null = null;
+let cachePath = "";
+const loadInFlight = new Map<string, Promise<WorkflowStoreState>>();
+let writeChain: Promise<unknown> = Promise.resolve();
+
+function storePath(): string {
+ const env = process.env.OS_SKILL_MEMORY_STORE?.trim();
+ if (process.env.VITEST && !env) return path.join(os.tmpdir(), `mso-skill-memory-test-${process.pid}.json`);
+ return (env || path.join(os.homedir(), ".mso", "skill-memory.json")).replace(/^~(?=$|\/)/, os.homedir());
+}
+
+/** The only module that reads/writes the workflow/recipe persistence file. */
+export async function loadWorkflowStore(): Promise<WorkflowStoreState> {
+ const file = storePath();
+ if (cache && cachePath === file) return cache;
+ const current = loadInFlight.get(file);
+ if (current) return current;
+
+ const pending = (async () => {
+ let raw: string;
+ try {
+ raw = await fs.readFile(file, "utf8");
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+ cache = EMPTY();
+ cachePath = file;
+ return cache;
+ }
+ throw error;
+ }
+ const parsed = JSON.parse(raw) as { active?: unknown; recipes?: unknown };
+ cache = { version: 3, active: normalizeActive(parsed.active), recipes: normalizeRecipes(parsed.recipes) };
+ cachePath = file;
+ return cache;
+ })();
+ loadInFlight.set(file, pending);
+ try {
+ return await pending;
+ } finally {
+ if (loadInFlight.get(file) === pending) loadInFlight.delete(file);
+ }
+}
+
+export async function persistWorkflowStore(store: WorkflowStoreState): Promise<void> {
+ const file = storePath();
+ const snapshot = JSON.stringify(store, null, 2);
+ const run = writeChain.then(async () => {
+ await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+ const tmp = `${file}.tmp`;
+ await fs.writeFile(tmp, snapshot, { encoding: "utf8", mode: 0o600 });
+ await fs.rename(tmp, file);
+ });
+ writeChain = run.catch(() => undefined);
+ await run;
+}
+
+/** Test-only cache reset; public compatibility maps the historical name. */
+export function resetWorkflowStoreCache(): void {
+ cache = null;
+ cachePath = "";
+ loadInFlight.clear();
+ writeChain = Promise.resolve();
+}
diff --git a/lib/skills/memory.test.ts b/lib/workflow/store.test.ts
similarity index 98%
rename from lib/skills/memory.test.ts
rename to lib/workflow/store.test.ts
index 3e5501c8..4dfb677d 100644
--- a/lib/skills/memory.test.ts
+++ b/lib/workflow/store.test.ts
@@ -2,16 +2,16 @@ import { afterAll, beforeEach, describe, expect, it } from "vitest";
import { promises as fs } from "fs";
import os from "os";
import path from "path";
-import type { ActiveWorkflow } from "./memory";
+import type { ActiveWorkflow } from "./index";
const dir = await fs.mkdtemp(path.join(os.tmpdir(), "mso-skill-memory-"));
process.env.OS_SKILL_MEMORY_STORE = path.join(dir, "memory.json");
-const memory = await import("./memory");
+const memory = await import("./index");
describe("learned workflow recipes", () => {
beforeEach(async () => {
await fs.rm(process.env.OS_SKILL_MEMORY_STORE!, { force: true });
- memory.resetSkillMemoryCache();
+ memory.resetWorkflowStoreCache();
});
afterAll(async () => { await fs.rm(dir, { recursive: true, force: true }); });
@@ -127,7 +127,7 @@ describe("learned workflow recipes", () => {
await fs.writeFile(process.env.OS_SKILL_MEMORY_STORE!, JSON.stringify({
version: 1, active: { "mcp:legacy": legacy }, recipes: {},
}));
- memory.resetSkillMemoryCache();
+ memory.resetWorkflowStoreCache();
await expect(memory.activeWorkflowForActor("mcp:legacy", legacy.id)).resolves.toMatchObject({ id: legacy.id });
const current = await memory.startWorkflow({ actor: "mcp:legacy", intent: "new parallel task" });
@@ -223,7 +223,7 @@ describe("learned workflow recipes", () => {
},
},
}), { mode: 0o600 });
- memory.resetSkillMemoryCache();
+ memory.resetWorkflowStoreCache();
const [recipe] = await memory.listLearnedRecipes({ actor: "mcp:legacy", scope: "exec" });
const serialized = JSON.stringify(recipe);
expect(serialized).not.toContain("raw-secret");
diff --git a/lib/workflow/store.ts b/lib/workflow/store.ts
new file mode 100644
index 00000000..17ea6c4d
--- /dev/null
+++ b/lib/workflow/store.ts
@@ -0,0 +1,6 @@
+// Internal compatibility module for the pre-split workflow store. Persistence is
+// exclusively owned by storage.ts; lifecycle/contention/learning own behavior.
+export { startWorkflow, activeWorkflowForActor, recordWorkflowStep, cancelWorkflow } from "./lifecycle";
+export { summarizeProjectContention, countActiveWorkflowsForProject } from "./contention";
+export { finishWorkflow, listLearnedRecipes, markRecipeUsed } from "./learning";
+export { resetWorkflowStoreCache } from "./storage";
diff --git a/lib/workflow/types.ts b/lib/workflow/types.ts
new file mode 100644
index 00000000..65f08c9a
--- /dev/null
+++ b/lib/workflow/types.ts
@@ -0,0 +1,90 @@
+import type { Scope } from "@/lib/capabilities/scope";
+import type { WorkflowOrchestrationSnapshot } from "@/lib/contracts/orchestration";
+
+export type WorkflowStepState = "completed" | "failed" | "denied" | "rate_limited" | "invalid_args";
+
+export type WorkflowStep = {
+ id: string;
+ tool: string;
+ state: WorkflowStepState;
+ target?: string;
+ args?: Record<string, string | number | boolean>;
+ durationMs?: number;
+ ts: string;
+};
+
+export type WorkflowStepInput = Omit<WorkflowStep, "args"> & { args?: Record<string, unknown> };
+
+export type ActiveWorkflow = {
+ id: string;
+ actor: string;
+ scope: Scope;
+ intent: string;
+ project?: string;
+ constraints?: string;
+ orchestration?: WorkflowOrchestrationSnapshot;
+ startedAt: string;
+ steps: WorkflowStep[];
+};
+
+export type WorkflowQuality = {
+ stepAttempts: number; completedSteps: number; failedSteps: number; deniedSteps: number;
+ rateLimitedSteps: number; invalidArgSteps: number; retries: number; rollbackSignals: number;
+ timedSteps: number; totalStepDurationMs: number; averageStepDurationMs: number;
+};
+
+export type LearnedRecipe = {
+ id: string;
+ actor: string;
+ scope: Scope;
+ intent: string;
+ normalizedIntent: string;
+ project?: string;
+ summary: string;
+ embeddingVersion: string;
+ embedding: number[];
+ bestSteps: WorkflowStep[];
+ lastSteps: WorkflowStep[];
+ attempts: number;
+ successes: number;
+ failures: number;
+ averageDurationMs: number;
+ fastestDurationMs?: number;
+ lastDurationMs: number;
+ averageWallDurationMs: number;
+ lastWallDurationMs: number;
+ quality: WorkflowQuality;
+ lastQuality: WorkflowQuality;
+ qualityVersion?: 1;
+ createdAt: string;
+ updatedAt: string;
+ lastUsedAt?: string;
+};
+
+export type ActiveWorkflowBuckets = Record<string, Record<string, ActiveWorkflow>>;
+export type WorkflowStoreState = {
+ version: 3;
+ active: ActiveWorkflowBuckets;
+ recipes: Record<string, LearnedRecipe>;
+};
+
+export type FinishWorkflowResult = {
+ workflow: ActiveWorkflow;
+ recipe: LearnedRecipe;
+ currentDurationMs: number;
+ previousFastestMs?: number;
+ improvedByMs?: number;
+ improvedPct?: number;
+};
+
+export type CancelWorkflowResult = { workflow: ActiveWorkflow; reason?: string };
+export type RecipeAccess =
+ | { actor: string; scope: Scope; ownerView?: false }
+ | { ownerView: true; actor?: never; scope?: never };
+
+export type ProjectContentionSummary = {
+ activeWorkflowCount: number;
+ conflictingWorkflowCount: number;
+ overlappingPaths: string[];
+ overlappingResources: string[];
+};
diff --git a/scripts/check-architecture.mjs b/scripts/check-architecture.mjs
index a2cb9a84..9975b0a3 100755
--- a/scripts/check-architecture.mjs
+++ b/scripts/check-architecture.mjs
@@ -26,11 +26,15 @@ const nonMcpMcpImports = imports.filter((row) => {
const from = rel(ROOT, row.from);
return from.startsWith("lib/") && !from.startsWith("lib/mcp/") && row.spec.startsWith("@/lib/mcp/");
}).length;
+const legacyWorkflowFacadeImports = imports.filter((row) => {
+ const from = rel(ROOT, row.from);
+ return row.spec === "@/lib/skills/memory" && from !== "lib/skills/memory-compat.test.ts";
+}).length;
const crossProtocol = structural.filter(({ ring }) => {
const domains = new Set(ring.slice(0, -1).map(domain));
return domains.has("lib/mcp") && (domains.has("lib/a2a") || domains.has("lib/agent"));
});
-const metrics = { structuralCycles: structural.length, crossDomainCycles: crossDomain.length, crossProtocolCycles: crossProtocol.length, filesOver220, filesOver500, serverFrontendImports, appshellSelfBarrelImports, nonMcpMcpImports };
+const metrics = { structuralCycles: structural.length, crossDomainCycles: crossDomain.length, crossProtocolCycles: crossProtocol.length, filesOver220, filesOver500, serverFrontendImports, appshellSelfBarrelImports, nonMcpMcpImports, legacyWorkflowFacadeImports };
let failed = false;
console.log("Architecture health");
for (const [key, current] of Object.entries(metrics)) {