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.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
refactor: separate workflow and memory ownership
Rahmanead080bc8816
diff --git a/app/api/assistant/route.ts b/app/api/assistant/route.tsindex 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.tsindex 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.tsindex 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.jsonindex 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.tssimilarity index 96%rename from lib/ai/memory.test.tsrename to lib/agent/legacy-owner-memory.test.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tssimilarity index 97%rename from lib/skills/memory-contention.test.tsrename to lib/workflow/contention.test.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tssimilarity index 95%rename from lib/skills/memory-quality.test.tsrename to lib/workflow/quality.test.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tssimilarity index 98%rename from lib/skills/memory.test.tsrename to lib/workflow/store.test.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mjsindex 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)) {