From cfd3badeb5fd121e5d1de0e1a9e057758e33303b Mon Sep 17 00:00:00 2001 From: wrightpt Date: Thu, 9 Jul 2026 23:28:48 -0400 Subject: [PATCH 01/43] feat: harden session context and workstation tool surface --- AGENTS.md | 6 +- INSTALL_FOR_AGENTS.md | 2 +- README.md | 7 +- plugin/scripts/notification.mjs | 100 ++++++++++-- plugin/scripts/post-commit.mjs | 5 +- plugin/scripts/post-tool-failure.mjs | 101 ++++++++++-- plugin/scripts/post-tool-use.mjs | 117 +++++++++++--- plugin/scripts/pre-compact.mjs | 99 ++++++++++-- plugin/scripts/pre-tool-use.mjs | 4 +- plugin/scripts/prompt-submit.mjs | 114 +++++++++++--- plugin/scripts/session-end.mjs | 4 +- plugin/scripts/session-start.mjs | 102 +++++++++--- plugin/scripts/stop.mjs | 4 +- plugin/scripts/subagent-start.mjs | 100 ++++++++++-- plugin/scripts/subagent-stop.mjs | 100 ++++++++++-- plugin/scripts/task-completed.mjs | 100 ++++++++++-- .../skills/agentmemory-mcp-tools/REFERENCE.md | 2 +- src/cli.ts | 15 +- src/functions/observe.ts | 55 ++++++- src/functions/session-context.ts | 94 +++++++++++ src/functions/session-list.ts | 148 ++++++++++++++++++ src/hooks/_project.ts | 131 ++++++++++++++-- src/hooks/notification.ts | 6 +- src/hooks/post-tool-failure.ts | 10 +- src/hooks/post-tool-use.ts | 33 +++- src/hooks/prompt-submit.ts | 21 ++- src/hooks/session-start.ts | 7 +- src/hooks/subagent-start.ts | 6 +- src/hooks/subagent-stop.ts | 6 +- src/hooks/task-completed.ts | 6 +- src/index.ts | 4 +- src/mcp/server.ts | 15 +- src/mcp/standalone.ts | 42 ++++- src/mcp/tools-registry.ts | 73 +++++++-- src/triggers/api.ts | 127 +++++++++++++-- src/triggers/events.ts | 26 ++- src/types.ts | 13 ++ src/viewer/index.html | 10 +- test/hook-project.test.ts | 41 ++++- test/mcp-standalone-proxy.test.ts | 4 +- test/mcp-standalone.test.ts | 5 + test/mcp-surface-default.test.ts | 30 +++- test/observe-implicit-session.test.ts | 16 +- test/session-context.test.ts | 112 +++++++++++++ test/session-list.test.ts | 96 ++++++++++++ test/tool-count-consistency.test.ts | 2 +- 46 files changed, 1845 insertions(+), 276 deletions(-) create mode 100644 src/functions/session-context.ts create mode 100644 src/functions/session-list.ts create mode 100644 test/session-context.test.ts create mode 100644 test/session-list.test.ts diff --git a/AGENTS.md b/AGENTS.md index 873ef10fc1..a608ee9c41 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,10 +114,10 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). - Test files go in `test/` with `.test.ts` extension - Follow existing patterns in `test/crystallize.test.ts` for function tests -## Current Stats (v0.9.16) +## Current Stats (v0.9.27) -- 53 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all) -- 128 REST endpoints +- 53 MCP tools (`all` by default; 7 safe essentials in `core`; curated coordination in `workstation`) +- 129 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 15 skills - 50+ iii functions diff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.md index f368220b3a..f5d56c2678 100644 --- a/INSTALL_FOR_AGENTS.md +++ b/INSTALL_FOR_AGENTS.md @@ -128,7 +128,7 @@ These are off by default because they spend tokens. Enable them only if the user ## Tool surface -The MCP server exposes 53 tools by default (`--tools all`). Use `--tools core` (or `AGENTMEMORY_TOOLS=core`) for a lean 8-tool set on hosts with tight tool limits. The 8 core tools cover save, recall, consolidate, smart search, sessions, diagnose, lesson save, and reflect. +The MCP server exposes 53 tools by default (`--tools all`). Use `--tools core` (or `AGENTMEMORY_TOOLS=core`) for a lean 7-tool set on hosts with tight tool limits. The 7 core tools cover save, recall, smart search, sessions, diagnose, lesson save, and lesson recall. `AGENTMEMORY_TOOLS=workstation` adds actions, leases, and signals without exposing disabled LLM workflows. ## Lifecycle commands diff --git a/README.md b/README.md index d04da3712f..b0c04619a8 100644 --- a/README.md +++ b/README.md @@ -961,7 +961,7 @@ npm install @xenova/transformers 53 tools, 6 resources, 3 prompts, and 15 skills, the most comprehensive MCP memory toolkit for any agent. -> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the full 53-tool surface **only when it can reach a running agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). The `AGENTMEMORY_TOOLS=core|all` env var is a *server-side* flag — setting it in the shim's `env` block has no effect. If you see only 7 tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`. +> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the running server's selected tool profile **only when it can reach an agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). `AGENTMEMORY_TOOLS=core|workstation|all` is evaluated by the running server; set it in the server service environment. If you see only 7 local-fallback tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`. ### 53 Tools @@ -1493,15 +1493,16 @@ Create `~/.agentmemory/.env`: # USER_ID= # TEAM_MODE=private -# Tool visibility: "core" (8 tools, lean fallback) or "all" (53 tools) +# Tool visibility: "core" (7), "workstation" (curated coordination), "all" (53), or a comma-separated allowlist # AGENTMEMORY_TOOLS=core +# AGENTMEMORY_DISABLE_LLM_TOOLS=true ``` ---

API

-128 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers. +129 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
Key endpoints diff --git a/plugin/scripts/notification.mjs b/plugin/scripts/notification.mjs index 3967158c92..bc70d713fc 100755 --- a/plugin/scripts/notification.mjs +++ b/plugin/scripts/notification.mjs @@ -1,15 +1,12 @@ #!/usr/bin/env node -import { execSync } from "node:child_process"; -import { basename } from "node:path"; - +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts -function resolveProject(cwd) { - const explicit = process.env["AGENTMEMORY_PROJECT_NAME"]; - if (explicit && explicit.trim()) return explicit.trim(); - const dir = cwd && cwd.trim() ? cwd : process.cwd(); +function git(cwd, args) { try { - const top = execSync("git rev-parse --show-toplevel", { - cwd: dir, + return execFileSync("git", args, { + cwd, stdio: [ "ignore", "pipe", @@ -17,11 +14,80 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); - } catch {} - return basename(dir); + } catch { + return ""; + } +} +function nearestProjectFile(cwd, boundary) { + let current = resolve(cwd); + const root = boundary ? resolve(boundary) : parse(current).root; + while (true) { + const candidate = resolve(current, ".agentmemory", "project.json"); + if (existsSync(candidate)) return candidate; + if (current === root) return void 0; + current = dirname(current); + } +} +function readProjectFile(cwd, boundary) { + const file = nearestProjectFile(cwd, boundary); + if (!file) return void 0; + try { + return { + file, + data: JSON.parse(readFileSync(file, "utf8")) + }; + } catch { + return; + } +} +function remoteProjectName(remote) { + const normalized = remote.trim().replace(/\/$/, "").replace(/\.git$/, ""); + if (!normalized) return ""; + return normalized.split(/[/:]/).filter(Boolean).at(-1) || ""; +} +function nonEmpty(value) { + return typeof value === "string" && value.trim() ? value.trim() : void 0; +} +function resolveProjectContext(cwd) { + const rawDir = cwd && cwd.trim() ? cwd.trim() : process.cwd(); + if (process.platform !== "win32" && (/^[A-Za-z]:[\\/]/.test(rawDir) || rawDir.startsWith("\\\\"))) { + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + return { + project: explicitProject || basename(rawDir), + cwd: rawDir, + repoRoot: nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]) || rawDir, + scopeType: nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) || "directory", + ...taskSlug ? { taskSlug } : {} + }; + } + const dir = resolve(rawDir); + const gitTop = git(dir, ["rev-parse", "--show-toplevel"]); + const projectFile = readProjectFile(dir, gitTop || void 0); + const remoteName = remoteProjectName(git(dir, [ + "config", + "--get", + "remote.origin.url" + ])); + const fileProject = projectFile ? nonEmpty(projectFile.data.project_id) ?? nonEmpty(projectFile.data.projectId) : void 0; + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const rawRepoRoot = projectFile ? nonEmpty(projectFile.data.repo_root) ?? nonEmpty(projectFile.data.repoRoot) : void 0; + const configuredRepoRoot = nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]); + const projectFileRoot = projectFile ? dirname(dirname(projectFile.file)) : void 0; + const repoRoot = configuredRepoRoot ? resolve(configuredRepoRoot) : rawRepoRoot ? resolve(projectFileRoot || dir, rawRepoRoot) : gitTop || dir; + const scopeType = nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) ?? (projectFile ? nonEmpty(projectFile.data.scope_type) ?? nonEmpty(projectFile.data.scopeType) : void 0) ?? (gitTop ? "repo" : "directory"); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + const branch = gitTop ? git(dir, ["branch", "--show-current"]) : ""; + return { + project: (explicitProject ?? fileProject ?? remoteName) || basename(gitTop || dir), + cwd: dir, + repoRoot, + scopeType, + ...gitTop ? { worktree: gitTop } : {}, + ...branch ? { branch } : {}, + ...taskSlug ? { taskSlug } : {} + }; } - //#endregion //#region src/hooks/notification.ts function isSdkChildContext(payload) { @@ -50,14 +116,14 @@ async function main() { if (notificationType !== "permission_prompt") return; const rawSessionId = data.session_id ?? data.sessionId; const sessionId = typeof rawSessionId === "string" && rawSessionId.length > 0 ? rawSessionId : "unknown"; + const context = resolveProjectContext(data.cwd); fetch(`${REST_URL}/agentmemory/observe`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ hookType: "notification", sessionId, - project: resolveProject(data.cwd), - cwd: data.cwd || process.cwd(), + ...context, timestamp: (/* @__PURE__ */ new Date()).toISOString(), data: { notification_type: notificationType, @@ -70,7 +136,7 @@ async function main() { setTimeout(() => process.exit(0), 500).unref(); } main(); - //#endregion -export { }; +export {}; + //# sourceMappingURL=notification.mjs.map \ No newline at end of file diff --git a/plugin/scripts/post-commit.mjs b/plugin/scripts/post-commit.mjs index 8552cd614e..5318184f85 100755 --- a/plugin/scripts/post-commit.mjs +++ b/plugin/scripts/post-commit.mjs @@ -1,7 +1,6 @@ #!/usr/bin/env node import { execFile } from "node:child_process"; import { promisify } from "node:util"; - //#region src/hooks/post-commit.ts const exec = promisify(execFile); function isSdkChildContext(payload) { @@ -96,7 +95,7 @@ async function main() { } catch {} } main(); - //#endregion -export { }; +export {}; + //# sourceMappingURL=post-commit.mjs.map \ No newline at end of file diff --git a/plugin/scripts/post-tool-failure.mjs b/plugin/scripts/post-tool-failure.mjs index 6fdad8d9d9..45b2f6f7ed 100755 --- a/plugin/scripts/post-tool-failure.mjs +++ b/plugin/scripts/post-tool-failure.mjs @@ -1,15 +1,12 @@ #!/usr/bin/env node -import { execSync } from "node:child_process"; -import { basename } from "node:path"; - +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts -function resolveProject(cwd) { - const explicit = process.env["AGENTMEMORY_PROJECT_NAME"]; - if (explicit && explicit.trim()) return explicit.trim(); - const dir = cwd && cwd.trim() ? cwd : process.cwd(); +function git(cwd, args) { try { - const top = execSync("git rev-parse --show-toplevel", { - cwd: dir, + return execFileSync("git", args, { + cwd, stdio: [ "ignore", "pipe", @@ -17,11 +14,80 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); - } catch {} - return basename(dir); + } catch { + return ""; + } +} +function nearestProjectFile(cwd, boundary) { + let current = resolve(cwd); + const root = boundary ? resolve(boundary) : parse(current).root; + while (true) { + const candidate = resolve(current, ".agentmemory", "project.json"); + if (existsSync(candidate)) return candidate; + if (current === root) return void 0; + current = dirname(current); + } +} +function readProjectFile(cwd, boundary) { + const file = nearestProjectFile(cwd, boundary); + if (!file) return void 0; + try { + return { + file, + data: JSON.parse(readFileSync(file, "utf8")) + }; + } catch { + return; + } +} +function remoteProjectName(remote) { + const normalized = remote.trim().replace(/\/$/, "").replace(/\.git$/, ""); + if (!normalized) return ""; + return normalized.split(/[/:]/).filter(Boolean).at(-1) || ""; +} +function nonEmpty(value) { + return typeof value === "string" && value.trim() ? value.trim() : void 0; +} +function resolveProjectContext(cwd) { + const rawDir = cwd && cwd.trim() ? cwd.trim() : process.cwd(); + if (process.platform !== "win32" && (/^[A-Za-z]:[\\/]/.test(rawDir) || rawDir.startsWith("\\\\"))) { + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + return { + project: explicitProject || basename(rawDir), + cwd: rawDir, + repoRoot: nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]) || rawDir, + scopeType: nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) || "directory", + ...taskSlug ? { taskSlug } : {} + }; + } + const dir = resolve(rawDir); + const gitTop = git(dir, ["rev-parse", "--show-toplevel"]); + const projectFile = readProjectFile(dir, gitTop || void 0); + const remoteName = remoteProjectName(git(dir, [ + "config", + "--get", + "remote.origin.url" + ])); + const fileProject = projectFile ? nonEmpty(projectFile.data.project_id) ?? nonEmpty(projectFile.data.projectId) : void 0; + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const rawRepoRoot = projectFile ? nonEmpty(projectFile.data.repo_root) ?? nonEmpty(projectFile.data.repoRoot) : void 0; + const configuredRepoRoot = nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]); + const projectFileRoot = projectFile ? dirname(dirname(projectFile.file)) : void 0; + const repoRoot = configuredRepoRoot ? resolve(configuredRepoRoot) : rawRepoRoot ? resolve(projectFileRoot || dir, rawRepoRoot) : gitTop || dir; + const scopeType = nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) ?? (projectFile ? nonEmpty(projectFile.data.scope_type) ?? nonEmpty(projectFile.data.scopeType) : void 0) ?? (gitTop ? "repo" : "directory"); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + const branch = gitTop ? git(dir, ["branch", "--show-current"]) : ""; + return { + project: (explicitProject ?? fileProject ?? remoteName) || basename(gitTop || dir), + cwd: dir, + repoRoot, + scopeType, + ...gitTop ? { worktree: gitTop } : {}, + ...branch ? { branch } : {}, + ...taskSlug ? { taskSlug } : {} + }; } - //#endregion //#region src/hooks/post-tool-failure.ts function isSdkChildContext(payload) { @@ -49,16 +115,17 @@ async function main() { if (data.is_interrupt || data.isInterrupt) return; const sessionId = data.session_id || data.sessionId || "unknown"; const toolName = data.tool_name ?? data.toolName; + if (typeof toolName === "string" && (toolName.toLowerCase().startsWith("mcp__agentmemory__") || toolName.toLowerCase().startsWith("memory_"))) return; const toolInput = data.tool_input ?? data.toolArgs; const error = data.error ?? data.errorMessage; + const context = resolveProjectContext(data.cwd); fetch(`${REST_URL}/agentmemory/observe`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ hookType: "post_tool_failure", sessionId, - project: resolveProject(data.cwd), - cwd: data.cwd || process.cwd(), + ...context, timestamp: (/* @__PURE__ */ new Date()).toISOString(), data: { tool_name: toolName, @@ -71,7 +138,7 @@ async function main() { setTimeout(() => process.exit(0), 500).unref(); } main(); - //#endregion -export { }; +export {}; + //# sourceMappingURL=post-tool-failure.mjs.map \ No newline at end of file diff --git a/plugin/scripts/post-tool-use.mjs b/plugin/scripts/post-tool-use.mjs index b4aef9c942..c73037000e 100755 --- a/plugin/scripts/post-tool-use.mjs +++ b/plugin/scripts/post-tool-use.mjs @@ -1,15 +1,12 @@ #!/usr/bin/env node -import { execSync } from "node:child_process"; -import { basename } from "node:path"; - +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts -function resolveProject(cwd) { - const explicit = process.env["AGENTMEMORY_PROJECT_NAME"]; - if (explicit && explicit.trim()) return explicit.trim(); - const dir = cwd && cwd.trim() ? cwd : process.cwd(); +function git(cwd, args) { try { - const top = execSync("git rev-parse --show-toplevel", { - cwd: dir, + return execFileSync("git", args, { + cwd, stdio: [ "ignore", "pipe", @@ -17,11 +14,80 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); - } catch {} - return basename(dir); + } catch { + return ""; + } +} +function nearestProjectFile(cwd, boundary) { + let current = resolve(cwd); + const root = boundary ? resolve(boundary) : parse(current).root; + while (true) { + const candidate = resolve(current, ".agentmemory", "project.json"); + if (existsSync(candidate)) return candidate; + if (current === root) return void 0; + current = dirname(current); + } +} +function readProjectFile(cwd, boundary) { + const file = nearestProjectFile(cwd, boundary); + if (!file) return void 0; + try { + return { + file, + data: JSON.parse(readFileSync(file, "utf8")) + }; + } catch { + return; + } +} +function remoteProjectName(remote) { + const normalized = remote.trim().replace(/\/$/, "").replace(/\.git$/, ""); + if (!normalized) return ""; + return normalized.split(/[/:]/).filter(Boolean).at(-1) || ""; +} +function nonEmpty(value) { + return typeof value === "string" && value.trim() ? value.trim() : void 0; +} +function resolveProjectContext(cwd) { + const rawDir = cwd && cwd.trim() ? cwd.trim() : process.cwd(); + if (process.platform !== "win32" && (/^[A-Za-z]:[\\/]/.test(rawDir) || rawDir.startsWith("\\\\"))) { + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + return { + project: explicitProject || basename(rawDir), + cwd: rawDir, + repoRoot: nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]) || rawDir, + scopeType: nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) || "directory", + ...taskSlug ? { taskSlug } : {} + }; + } + const dir = resolve(rawDir); + const gitTop = git(dir, ["rev-parse", "--show-toplevel"]); + const projectFile = readProjectFile(dir, gitTop || void 0); + const remoteName = remoteProjectName(git(dir, [ + "config", + "--get", + "remote.origin.url" + ])); + const fileProject = projectFile ? nonEmpty(projectFile.data.project_id) ?? nonEmpty(projectFile.data.projectId) : void 0; + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const rawRepoRoot = projectFile ? nonEmpty(projectFile.data.repo_root) ?? nonEmpty(projectFile.data.repoRoot) : void 0; + const configuredRepoRoot = nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]); + const projectFileRoot = projectFile ? dirname(dirname(projectFile.file)) : void 0; + const repoRoot = configuredRepoRoot ? resolve(configuredRepoRoot) : rawRepoRoot ? resolve(projectFileRoot || dir, rawRepoRoot) : gitTop || dir; + const scopeType = nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) ?? (projectFile ? nonEmpty(projectFile.data.scope_type) ?? nonEmpty(projectFile.data.scopeType) : void 0) ?? (gitTop ? "repo" : "directory"); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + const branch = gitTop ? git(dir, ["branch", "--show-current"]) : ""; + return { + project: (explicitProject ?? fileProject ?? remoteName) || basename(gitTop || dir), + cwd: dir, + repoRoot, + scopeType, + ...gitTop ? { worktree: gitTop } : {}, + ...branch ? { branch } : {}, + ...taskSlug ? { taskSlug } : {} + }; } - //#endregion //#region src/hooks/post-tool-use.ts function isSdkChildContext(payload) { @@ -49,6 +115,9 @@ async function main() { const sessionId = data.session_id || data.sessionId || "unknown"; const toolName = data.tool_name ?? data.toolName; const toolInput = data.tool_input ?? data.toolArgs; + if (shouldSkipTool(toolName)) return; + const context = resolveProjectContext(data.cwd); + const maxChars = maxCaptureChars(); const { imageData, cleanOutput } = extractImageData(toolOutput(data)); fetch(`${REST_URL}/agentmemory/observe`, { method: "POST", @@ -56,13 +125,12 @@ async function main() { body: JSON.stringify({ hookType: "post_tool_use", sessionId, - project: resolveProject(data.cwd), - cwd: data.cwd || process.cwd(), + ...context, timestamp: (/* @__PURE__ */ new Date()).toISOString(), data: { tool_name: toolName, - tool_input: toolInput, - tool_output: truncate(cleanOutput, 8e3), + tool_input: truncate(toolInput, maxChars), + tool_output: truncate(cleanOutput, maxChars), ...imageData ? { image_data: imageData } : {} } }), @@ -70,6 +138,17 @@ async function main() { }).catch(() => {}); setTimeout(() => process.exit(0), 500).unref(); } +function shouldSkipTool(value) { + const name = typeof value === "string" ? value.trim().toLowerCase() : ""; + if (!name) return false; + if (name.startsWith("mcp__agentmemory__") || name.startsWith("memory_")) return true; + return (process.env["AGENTMEMORY_SKIP_TOOLS"] || "").split(",").map((item) => item.trim().toLowerCase()).filter(Boolean).some((pattern) => pattern.endsWith("*") ? name.startsWith(pattern.slice(0, -1)) : name === pattern); +} +function maxCaptureChars() { + const value = Number(process.env["AGENTMEMORY_MAX_TOOL_CAPTURE_CHARS"] || "8000"); + if (!Number.isFinite(value) || value < 0) return 8e3; + return Math.min(Math.floor(value), 32e3); +} function toolOutput(data) { if (data.tool_response !== void 0) return data.tool_response; if (data.tool_output !== void 0) return data.tool_output; @@ -116,7 +195,7 @@ function truncate(value, max) { return value; } main(); - //#endregion -export { }; +export {}; + //# sourceMappingURL=post-tool-use.mjs.map \ No newline at end of file diff --git a/plugin/scripts/pre-compact.mjs b/plugin/scripts/pre-compact.mjs index 0afdcb0b4e..917818485c 100755 --- a/plugin/scripts/pre-compact.mjs +++ b/plugin/scripts/pre-compact.mjs @@ -1,15 +1,12 @@ #!/usr/bin/env node -import { execSync } from "node:child_process"; -import { basename } from "node:path"; - +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts -function resolveProject(cwd) { - const explicit = process.env["AGENTMEMORY_PROJECT_NAME"]; - if (explicit && explicit.trim()) return explicit.trim(); - const dir = cwd && cwd.trim() ? cwd : process.cwd(); +function git(cwd, args) { try { - const top = execSync("git rev-parse --show-toplevel", { - cwd: dir, + return execFileSync("git", args, { + cwd, stdio: [ "ignore", "pipe", @@ -17,11 +14,83 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); - } catch {} - return basename(dir); + } catch { + return ""; + } +} +function nearestProjectFile(cwd, boundary) { + let current = resolve(cwd); + const root = boundary ? resolve(boundary) : parse(current).root; + while (true) { + const candidate = resolve(current, ".agentmemory", "project.json"); + if (existsSync(candidate)) return candidate; + if (current === root) return void 0; + current = dirname(current); + } +} +function readProjectFile(cwd, boundary) { + const file = nearestProjectFile(cwd, boundary); + if (!file) return void 0; + try { + return { + file, + data: JSON.parse(readFileSync(file, "utf8")) + }; + } catch { + return; + } +} +function remoteProjectName(remote) { + const normalized = remote.trim().replace(/\/$/, "").replace(/\.git$/, ""); + if (!normalized) return ""; + return normalized.split(/[/:]/).filter(Boolean).at(-1) || ""; +} +function nonEmpty(value) { + return typeof value === "string" && value.trim() ? value.trim() : void 0; +} +function resolveProjectContext(cwd) { + const rawDir = cwd && cwd.trim() ? cwd.trim() : process.cwd(); + if (process.platform !== "win32" && (/^[A-Za-z]:[\\/]/.test(rawDir) || rawDir.startsWith("\\\\"))) { + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + return { + project: explicitProject || basename(rawDir), + cwd: rawDir, + repoRoot: nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]) || rawDir, + scopeType: nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) || "directory", + ...taskSlug ? { taskSlug } : {} + }; + } + const dir = resolve(rawDir); + const gitTop = git(dir, ["rev-parse", "--show-toplevel"]); + const projectFile = readProjectFile(dir, gitTop || void 0); + const remoteName = remoteProjectName(git(dir, [ + "config", + "--get", + "remote.origin.url" + ])); + const fileProject = projectFile ? nonEmpty(projectFile.data.project_id) ?? nonEmpty(projectFile.data.projectId) : void 0; + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const rawRepoRoot = projectFile ? nonEmpty(projectFile.data.repo_root) ?? nonEmpty(projectFile.data.repoRoot) : void 0; + const configuredRepoRoot = nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]); + const projectFileRoot = projectFile ? dirname(dirname(projectFile.file)) : void 0; + const repoRoot = configuredRepoRoot ? resolve(configuredRepoRoot) : rawRepoRoot ? resolve(projectFileRoot || dir, rawRepoRoot) : gitTop || dir; + const scopeType = nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) ?? (projectFile ? nonEmpty(projectFile.data.scope_type) ?? nonEmpty(projectFile.data.scopeType) : void 0) ?? (gitTop ? "repo" : "directory"); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + const branch = gitTop ? git(dir, ["branch", "--show-current"]) : ""; + return { + project: (explicitProject ?? fileProject ?? remoteName) || basename(gitTop || dir), + cwd: dir, + repoRoot, + scopeType, + ...gitTop ? { worktree: gitTop } : {}, + ...branch ? { branch } : {}, + ...taskSlug ? { taskSlug } : {} + }; +} +function resolveProject(cwd) { + return resolveProjectContext(cwd).project; } - //#endregion //#region src/hooks/pre-compact.ts function isSdkChildContext(payload) { @@ -74,7 +143,7 @@ async function main() { } catch {} } main(); - //#endregion -export { }; +export {}; + //# sourceMappingURL=pre-compact.mjs.map \ No newline at end of file diff --git a/plugin/scripts/pre-tool-use.mjs b/plugin/scripts/pre-tool-use.mjs index d70c166ed2..a0d6e95832 100755 --- a/plugin/scripts/pre-tool-use.mjs +++ b/plugin/scripts/pre-tool-use.mjs @@ -78,7 +78,7 @@ async function main() { } catch {} } main(); - //#endregion -export { }; +export {}; + //# sourceMappingURL=pre-tool-use.mjs.map \ No newline at end of file diff --git a/plugin/scripts/prompt-submit.mjs b/plugin/scripts/prompt-submit.mjs index 1a4147e6ab..b019cc19e2 100755 --- a/plugin/scripts/prompt-submit.mjs +++ b/plugin/scripts/prompt-submit.mjs @@ -1,15 +1,12 @@ #!/usr/bin/env node -import { execSync } from "node:child_process"; -import { basename } from "node:path"; - +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts -function resolveProject(cwd) { - const explicit = process.env["AGENTMEMORY_PROJECT_NAME"]; - if (explicit && explicit.trim()) return explicit.trim(); - const dir = cwd && cwd.trim() ? cwd : process.cwd(); +function git(cwd, args) { try { - const top = execSync("git rev-parse --show-toplevel", { - cwd: dir, + return execFileSync("git", args, { + cwd, stdio: [ "ignore", "pipe", @@ -17,11 +14,80 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); - } catch {} - return basename(dir); + } catch { + return ""; + } +} +function nearestProjectFile(cwd, boundary) { + let current = resolve(cwd); + const root = boundary ? resolve(boundary) : parse(current).root; + while (true) { + const candidate = resolve(current, ".agentmemory", "project.json"); + if (existsSync(candidate)) return candidate; + if (current === root) return void 0; + current = dirname(current); + } +} +function readProjectFile(cwd, boundary) { + const file = nearestProjectFile(cwd, boundary); + if (!file) return void 0; + try { + return { + file, + data: JSON.parse(readFileSync(file, "utf8")) + }; + } catch { + return; + } +} +function remoteProjectName(remote) { + const normalized = remote.trim().replace(/\/$/, "").replace(/\.git$/, ""); + if (!normalized) return ""; + return normalized.split(/[/:]/).filter(Boolean).at(-1) || ""; +} +function nonEmpty(value) { + return typeof value === "string" && value.trim() ? value.trim() : void 0; +} +function resolveProjectContext(cwd) { + const rawDir = cwd && cwd.trim() ? cwd.trim() : process.cwd(); + if (process.platform !== "win32" && (/^[A-Za-z]:[\\/]/.test(rawDir) || rawDir.startsWith("\\\\"))) { + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + return { + project: explicitProject || basename(rawDir), + cwd: rawDir, + repoRoot: nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]) || rawDir, + scopeType: nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) || "directory", + ...taskSlug ? { taskSlug } : {} + }; + } + const dir = resolve(rawDir); + const gitTop = git(dir, ["rev-parse", "--show-toplevel"]); + const projectFile = readProjectFile(dir, gitTop || void 0); + const remoteName = remoteProjectName(git(dir, [ + "config", + "--get", + "remote.origin.url" + ])); + const fileProject = projectFile ? nonEmpty(projectFile.data.project_id) ?? nonEmpty(projectFile.data.projectId) : void 0; + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const rawRepoRoot = projectFile ? nonEmpty(projectFile.data.repo_root) ?? nonEmpty(projectFile.data.repoRoot) : void 0; + const configuredRepoRoot = nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]); + const projectFileRoot = projectFile ? dirname(dirname(projectFile.file)) : void 0; + const repoRoot = configuredRepoRoot ? resolve(configuredRepoRoot) : rawRepoRoot ? resolve(projectFileRoot || dir, rawRepoRoot) : gitTop || dir; + const scopeType = nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) ?? (projectFile ? nonEmpty(projectFile.data.scope_type) ?? nonEmpty(projectFile.data.scopeType) : void 0) ?? (gitTop ? "repo" : "directory"); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + const branch = gitTop ? git(dir, ["branch", "--show-current"]) : ""; + return { + project: (explicitProject ?? fileProject ?? remoteName) || basename(gitTop || dir), + cwd: dir, + repoRoot, + scopeType, + ...gitTop ? { worktree: gitTop } : {}, + ...branch ? { branch } : {}, + ...taskSlug ? { taskSlug } : {} + }; } - //#endregion //#region src/hooks/prompt-submit.ts function isSdkChildContext(payload) { @@ -47,23 +113,35 @@ async function main() { } if (isSdkChildContext(data)) return; const sessionId = data.session_id || data.sessionId || "unknown"; + const context = resolveProjectContext(data.cwd); + const promptData = promptCapture(data.prompt ?? data.userPrompt); fetch(`${REST_URL}/agentmemory/observe`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ hookType: "prompt_submit", sessionId, - project: resolveProject(data.cwd), - cwd: data.cwd || process.cwd(), + ...context, timestamp: (/* @__PURE__ */ new Date()).toISOString(), - data: { prompt: data.prompt ?? data.userPrompt } + data: promptData }), signal: AbortSignal.timeout(3e3) }).catch(() => {}); setTimeout(() => process.exit(0), 500).unref(); } +function promptCapture(value) { + const text = typeof value === "string" ? value : ""; + const mode = (process.env["AGENTMEMORY_CAPTURE_PROMPTS"] || "full").toLowerCase(); + if (mode === "off" || mode === "metadata") return { + prompt_length: text.length, + prompt_capture: mode + }; + const max = Number(process.env["AGENTMEMORY_MAX_PROMPT_CAPTURE_CHARS"] || "4000"); + const limit = Number.isFinite(max) && max >= 0 ? Math.min(Math.floor(max), 16e3) : 4e3; + return { prompt: text.slice(0, limit) }; +} main(); - //#endregion -export { }; +export {}; + //# sourceMappingURL=prompt-submit.mjs.map \ No newline at end of file diff --git a/plugin/scripts/session-end.mjs b/plugin/scripts/session-end.mjs index 019149c309..0ba564be58 100755 --- a/plugin/scripts/session-end.mjs +++ b/plugin/scripts/session-end.mjs @@ -54,7 +54,7 @@ async function main() { setTimeout(() => process.exit(0), 1500).unref(); } main(); - //#endregion -export { }; +export {}; + //# sourceMappingURL=session-end.mjs.map \ No newline at end of file diff --git a/plugin/scripts/session-start.mjs b/plugin/scripts/session-start.mjs index 51b70eb4c2..449e1b27c4 100755 --- a/plugin/scripts/session-start.mjs +++ b/plugin/scripts/session-start.mjs @@ -1,15 +1,12 @@ #!/usr/bin/env node -import { execSync } from "node:child_process"; -import { basename } from "node:path"; - +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts -function resolveProject(cwd) { - const explicit = process.env["AGENTMEMORY_PROJECT_NAME"]; - if (explicit && explicit.trim()) return explicit.trim(); - const dir = cwd && cwd.trim() ? cwd : process.cwd(); +function git(cwd, args) { try { - const top = execSync("git rev-parse --show-toplevel", { - cwd: dir, + return execFileSync("git", args, { + cwd, stdio: [ "ignore", "pipe", @@ -17,11 +14,80 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); - } catch {} - return basename(dir); + } catch { + return ""; + } +} +function nearestProjectFile(cwd, boundary) { + let current = resolve(cwd); + const root = boundary ? resolve(boundary) : parse(current).root; + while (true) { + const candidate = resolve(current, ".agentmemory", "project.json"); + if (existsSync(candidate)) return candidate; + if (current === root) return void 0; + current = dirname(current); + } +} +function readProjectFile(cwd, boundary) { + const file = nearestProjectFile(cwd, boundary); + if (!file) return void 0; + try { + return { + file, + data: JSON.parse(readFileSync(file, "utf8")) + }; + } catch { + return; + } +} +function remoteProjectName(remote) { + const normalized = remote.trim().replace(/\/$/, "").replace(/\.git$/, ""); + if (!normalized) return ""; + return normalized.split(/[/:]/).filter(Boolean).at(-1) || ""; +} +function nonEmpty(value) { + return typeof value === "string" && value.trim() ? value.trim() : void 0; +} +function resolveProjectContext(cwd) { + const rawDir = cwd && cwd.trim() ? cwd.trim() : process.cwd(); + if (process.platform !== "win32" && (/^[A-Za-z]:[\\/]/.test(rawDir) || rawDir.startsWith("\\\\"))) { + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + return { + project: explicitProject || basename(rawDir), + cwd: rawDir, + repoRoot: nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]) || rawDir, + scopeType: nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) || "directory", + ...taskSlug ? { taskSlug } : {} + }; + } + const dir = resolve(rawDir); + const gitTop = git(dir, ["rev-parse", "--show-toplevel"]); + const projectFile = readProjectFile(dir, gitTop || void 0); + const remoteName = remoteProjectName(git(dir, [ + "config", + "--get", + "remote.origin.url" + ])); + const fileProject = projectFile ? nonEmpty(projectFile.data.project_id) ?? nonEmpty(projectFile.data.projectId) : void 0; + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const rawRepoRoot = projectFile ? nonEmpty(projectFile.data.repo_root) ?? nonEmpty(projectFile.data.repoRoot) : void 0; + const configuredRepoRoot = nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]); + const projectFileRoot = projectFile ? dirname(dirname(projectFile.file)) : void 0; + const repoRoot = configuredRepoRoot ? resolve(configuredRepoRoot) : rawRepoRoot ? resolve(projectFileRoot || dir, rawRepoRoot) : gitTop || dir; + const scopeType = nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) ?? (projectFile ? nonEmpty(projectFile.data.scope_type) ?? nonEmpty(projectFile.data.scopeType) : void 0) ?? (gitTop ? "repo" : "directory"); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + const branch = gitTop ? git(dir, ["branch", "--show-current"]) : ""; + return { + project: (explicitProject ?? fileProject ?? remoteName) || basename(gitTop || dir), + cwd: dir, + repoRoot, + scopeType, + ...gitTop ? { worktree: gitTop } : {}, + ...branch ? { branch } : {}, + ...taskSlug ? { taskSlug } : {} + }; } - //#endregion //#region src/hooks/session-start.ts function isSdkChildContext(payload) { @@ -50,16 +116,14 @@ async function main() { } if (isSdkChildContext(data)) return; const sessionId = data.session_id || data.sessionId || `ses_${Date.now().toString(36)}`; - const cwd = data.cwd || process.cwd(); - const project = resolveProject(data.cwd); + const context = resolveProjectContext(data.cwd); const url = `${REST_URL}/agentmemory/session/start`; const init = { method: "POST", headers: authHeaders(), body: JSON.stringify({ sessionId, - project, - cwd + ...context }) }; if (!INJECT_CONTEXT) { @@ -81,7 +145,7 @@ async function main() { } catch {} } main(); - //#endregion -export { }; +export {}; + //# sourceMappingURL=session-start.mjs.map \ No newline at end of file diff --git a/plugin/scripts/stop.mjs b/plugin/scripts/stop.mjs index 03d30c64f3..63051c8309 100755 --- a/plugin/scripts/stop.mjs +++ b/plugin/scripts/stop.mjs @@ -38,7 +38,7 @@ async function main() { setTimeout(() => process.exit(0), 1500).unref(); } main(); - //#endregion -export { }; +export {}; + //# sourceMappingURL=stop.mjs.map \ No newline at end of file diff --git a/plugin/scripts/subagent-start.mjs b/plugin/scripts/subagent-start.mjs index 2359a1c62f..baa032a192 100755 --- a/plugin/scripts/subagent-start.mjs +++ b/plugin/scripts/subagent-start.mjs @@ -1,15 +1,12 @@ #!/usr/bin/env node -import { execSync } from "node:child_process"; -import { basename } from "node:path"; - +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts -function resolveProject(cwd) { - const explicit = process.env["AGENTMEMORY_PROJECT_NAME"]; - if (explicit && explicit.trim()) return explicit.trim(); - const dir = cwd && cwd.trim() ? cwd : process.cwd(); +function git(cwd, args) { try { - const top = execSync("git rev-parse --show-toplevel", { - cwd: dir, + return execFileSync("git", args, { + cwd, stdio: [ "ignore", "pipe", @@ -17,11 +14,80 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); - } catch {} - return basename(dir); + } catch { + return ""; + } +} +function nearestProjectFile(cwd, boundary) { + let current = resolve(cwd); + const root = boundary ? resolve(boundary) : parse(current).root; + while (true) { + const candidate = resolve(current, ".agentmemory", "project.json"); + if (existsSync(candidate)) return candidate; + if (current === root) return void 0; + current = dirname(current); + } +} +function readProjectFile(cwd, boundary) { + const file = nearestProjectFile(cwd, boundary); + if (!file) return void 0; + try { + return { + file, + data: JSON.parse(readFileSync(file, "utf8")) + }; + } catch { + return; + } +} +function remoteProjectName(remote) { + const normalized = remote.trim().replace(/\/$/, "").replace(/\.git$/, ""); + if (!normalized) return ""; + return normalized.split(/[/:]/).filter(Boolean).at(-1) || ""; +} +function nonEmpty(value) { + return typeof value === "string" && value.trim() ? value.trim() : void 0; +} +function resolveProjectContext(cwd) { + const rawDir = cwd && cwd.trim() ? cwd.trim() : process.cwd(); + if (process.platform !== "win32" && (/^[A-Za-z]:[\\/]/.test(rawDir) || rawDir.startsWith("\\\\"))) { + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + return { + project: explicitProject || basename(rawDir), + cwd: rawDir, + repoRoot: nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]) || rawDir, + scopeType: nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) || "directory", + ...taskSlug ? { taskSlug } : {} + }; + } + const dir = resolve(rawDir); + const gitTop = git(dir, ["rev-parse", "--show-toplevel"]); + const projectFile = readProjectFile(dir, gitTop || void 0); + const remoteName = remoteProjectName(git(dir, [ + "config", + "--get", + "remote.origin.url" + ])); + const fileProject = projectFile ? nonEmpty(projectFile.data.project_id) ?? nonEmpty(projectFile.data.projectId) : void 0; + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const rawRepoRoot = projectFile ? nonEmpty(projectFile.data.repo_root) ?? nonEmpty(projectFile.data.repoRoot) : void 0; + const configuredRepoRoot = nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]); + const projectFileRoot = projectFile ? dirname(dirname(projectFile.file)) : void 0; + const repoRoot = configuredRepoRoot ? resolve(configuredRepoRoot) : rawRepoRoot ? resolve(projectFileRoot || dir, rawRepoRoot) : gitTop || dir; + const scopeType = nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) ?? (projectFile ? nonEmpty(projectFile.data.scope_type) ?? nonEmpty(projectFile.data.scopeType) : void 0) ?? (gitTop ? "repo" : "directory"); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + const branch = gitTop ? git(dir, ["branch", "--show-current"]) : ""; + return { + project: (explicitProject ?? fileProject ?? remoteName) || basename(gitTop || dir), + cwd: dir, + repoRoot, + scopeType, + ...gitTop ? { worktree: gitTop } : {}, + ...branch ? { branch } : {}, + ...taskSlug ? { taskSlug } : {} + }; } - //#endregion //#region src/hooks/subagent-start.ts function isSdkChildContext(payload) { @@ -50,14 +116,14 @@ async function main() { const sessionId = data.session_id || data.sessionId || "unknown"; const agentId = data.agent_id || data.agentName; const agentType = data.agent_type || data.agentDisplayName || data.agentName; + const context = resolveProjectContext(data.cwd); fetch(`${REST_URL}/agentmemory/observe`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ hookType: "subagent_start", sessionId, - project: resolveProject(data.cwd), - cwd: data.cwd || process.cwd(), + ...context, timestamp: (/* @__PURE__ */ new Date()).toISOString(), data: { agent_id: agentId, @@ -69,7 +135,7 @@ async function main() { setTimeout(() => process.exit(0), 500).unref(); } main(); - //#endregion -export { }; +export {}; + //# sourceMappingURL=subagent-start.mjs.map \ No newline at end of file diff --git a/plugin/scripts/subagent-stop.mjs b/plugin/scripts/subagent-stop.mjs index 2ba1b002c9..082a12b5d7 100755 --- a/plugin/scripts/subagent-stop.mjs +++ b/plugin/scripts/subagent-stop.mjs @@ -1,15 +1,12 @@ #!/usr/bin/env node -import { execSync } from "node:child_process"; -import { basename } from "node:path"; - +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts -function resolveProject(cwd) { - const explicit = process.env["AGENTMEMORY_PROJECT_NAME"]; - if (explicit && explicit.trim()) return explicit.trim(); - const dir = cwd && cwd.trim() ? cwd : process.cwd(); +function git(cwd, args) { try { - const top = execSync("git rev-parse --show-toplevel", { - cwd: dir, + return execFileSync("git", args, { + cwd, stdio: [ "ignore", "pipe", @@ -17,11 +14,80 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); - } catch {} - return basename(dir); + } catch { + return ""; + } +} +function nearestProjectFile(cwd, boundary) { + let current = resolve(cwd); + const root = boundary ? resolve(boundary) : parse(current).root; + while (true) { + const candidate = resolve(current, ".agentmemory", "project.json"); + if (existsSync(candidate)) return candidate; + if (current === root) return void 0; + current = dirname(current); + } +} +function readProjectFile(cwd, boundary) { + const file = nearestProjectFile(cwd, boundary); + if (!file) return void 0; + try { + return { + file, + data: JSON.parse(readFileSync(file, "utf8")) + }; + } catch { + return; + } +} +function remoteProjectName(remote) { + const normalized = remote.trim().replace(/\/$/, "").replace(/\.git$/, ""); + if (!normalized) return ""; + return normalized.split(/[/:]/).filter(Boolean).at(-1) || ""; +} +function nonEmpty(value) { + return typeof value === "string" && value.trim() ? value.trim() : void 0; +} +function resolveProjectContext(cwd) { + const rawDir = cwd && cwd.trim() ? cwd.trim() : process.cwd(); + if (process.platform !== "win32" && (/^[A-Za-z]:[\\/]/.test(rawDir) || rawDir.startsWith("\\\\"))) { + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + return { + project: explicitProject || basename(rawDir), + cwd: rawDir, + repoRoot: nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]) || rawDir, + scopeType: nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) || "directory", + ...taskSlug ? { taskSlug } : {} + }; + } + const dir = resolve(rawDir); + const gitTop = git(dir, ["rev-parse", "--show-toplevel"]); + const projectFile = readProjectFile(dir, gitTop || void 0); + const remoteName = remoteProjectName(git(dir, [ + "config", + "--get", + "remote.origin.url" + ])); + const fileProject = projectFile ? nonEmpty(projectFile.data.project_id) ?? nonEmpty(projectFile.data.projectId) : void 0; + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const rawRepoRoot = projectFile ? nonEmpty(projectFile.data.repo_root) ?? nonEmpty(projectFile.data.repoRoot) : void 0; + const configuredRepoRoot = nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]); + const projectFileRoot = projectFile ? dirname(dirname(projectFile.file)) : void 0; + const repoRoot = configuredRepoRoot ? resolve(configuredRepoRoot) : rawRepoRoot ? resolve(projectFileRoot || dir, rawRepoRoot) : gitTop || dir; + const scopeType = nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) ?? (projectFile ? nonEmpty(projectFile.data.scope_type) ?? nonEmpty(projectFile.data.scopeType) : void 0) ?? (gitTop ? "repo" : "directory"); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + const branch = gitTop ? git(dir, ["branch", "--show-current"]) : ""; + return { + project: (explicitProject ?? fileProject ?? remoteName) || basename(gitTop || dir), + cwd: dir, + repoRoot, + scopeType, + ...gitTop ? { worktree: gitTop } : {}, + ...branch ? { branch } : {}, + ...taskSlug ? { taskSlug } : {} + }; } - //#endregion //#region src/hooks/subagent-stop.ts function isSdkChildContext(payload) { @@ -50,14 +116,14 @@ async function main() { const agentId = data.agent_id || data.agentName; const agentType = data.agent_type || data.agentDisplayName || data.agentName; const lastMsg = typeof data.last_assistant_message === "string" ? data.last_assistant_message.slice(0, 4e3) : ""; + const context = resolveProjectContext(data.cwd); fetch(`${REST_URL}/agentmemory/observe`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ hookType: "subagent_stop", sessionId, - project: resolveProject(data.cwd), - cwd: data.cwd || process.cwd(), + ...context, timestamp: (/* @__PURE__ */ new Date()).toISOString(), data: { agent_id: agentId, @@ -70,7 +136,7 @@ async function main() { setTimeout(() => process.exit(0), 500).unref(); } main(); - //#endregion -export { }; +export {}; + //# sourceMappingURL=subagent-stop.mjs.map \ No newline at end of file diff --git a/plugin/scripts/task-completed.mjs b/plugin/scripts/task-completed.mjs index 478f0688e8..40c2427c70 100755 --- a/plugin/scripts/task-completed.mjs +++ b/plugin/scripts/task-completed.mjs @@ -1,15 +1,12 @@ #!/usr/bin/env node -import { execSync } from "node:child_process"; -import { basename } from "node:path"; - +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts -function resolveProject(cwd) { - const explicit = process.env["AGENTMEMORY_PROJECT_NAME"]; - if (explicit && explicit.trim()) return explicit.trim(); - const dir = cwd && cwd.trim() ? cwd : process.cwd(); +function git(cwd, args) { try { - const top = execSync("git rev-parse --show-toplevel", { - cwd: dir, + return execFileSync("git", args, { + cwd, stdio: [ "ignore", "pipe", @@ -17,11 +14,80 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); - } catch {} - return basename(dir); + } catch { + return ""; + } +} +function nearestProjectFile(cwd, boundary) { + let current = resolve(cwd); + const root = boundary ? resolve(boundary) : parse(current).root; + while (true) { + const candidate = resolve(current, ".agentmemory", "project.json"); + if (existsSync(candidate)) return candidate; + if (current === root) return void 0; + current = dirname(current); + } +} +function readProjectFile(cwd, boundary) { + const file = nearestProjectFile(cwd, boundary); + if (!file) return void 0; + try { + return { + file, + data: JSON.parse(readFileSync(file, "utf8")) + }; + } catch { + return; + } +} +function remoteProjectName(remote) { + const normalized = remote.trim().replace(/\/$/, "").replace(/\.git$/, ""); + if (!normalized) return ""; + return normalized.split(/[/:]/).filter(Boolean).at(-1) || ""; +} +function nonEmpty(value) { + return typeof value === "string" && value.trim() ? value.trim() : void 0; +} +function resolveProjectContext(cwd) { + const rawDir = cwd && cwd.trim() ? cwd.trim() : process.cwd(); + if (process.platform !== "win32" && (/^[A-Za-z]:[\\/]/.test(rawDir) || rawDir.startsWith("\\\\"))) { + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + return { + project: explicitProject || basename(rawDir), + cwd: rawDir, + repoRoot: nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]) || rawDir, + scopeType: nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) || "directory", + ...taskSlug ? { taskSlug } : {} + }; + } + const dir = resolve(rawDir); + const gitTop = git(dir, ["rev-parse", "--show-toplevel"]); + const projectFile = readProjectFile(dir, gitTop || void 0); + const remoteName = remoteProjectName(git(dir, [ + "config", + "--get", + "remote.origin.url" + ])); + const fileProject = projectFile ? nonEmpty(projectFile.data.project_id) ?? nonEmpty(projectFile.data.projectId) : void 0; + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const rawRepoRoot = projectFile ? nonEmpty(projectFile.data.repo_root) ?? nonEmpty(projectFile.data.repoRoot) : void 0; + const configuredRepoRoot = nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]); + const projectFileRoot = projectFile ? dirname(dirname(projectFile.file)) : void 0; + const repoRoot = configuredRepoRoot ? resolve(configuredRepoRoot) : rawRepoRoot ? resolve(projectFileRoot || dir, rawRepoRoot) : gitTop || dir; + const scopeType = nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) ?? (projectFile ? nonEmpty(projectFile.data.scope_type) ?? nonEmpty(projectFile.data.scopeType) : void 0) ?? (gitTop ? "repo" : "directory"); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + const branch = gitTop ? git(dir, ["branch", "--show-current"]) : ""; + return { + project: (explicitProject ?? fileProject ?? remoteName) || basename(gitTop || dir), + cwd: dir, + repoRoot, + scopeType, + ...gitTop ? { worktree: gitTop } : {}, + ...branch ? { branch } : {}, + ...taskSlug ? { taskSlug } : {} + }; } - //#endregion //#region src/hooks/task-completed.ts function isSdkChildContext(payload) { @@ -47,14 +113,14 @@ async function main() { } if (isSdkChildContext(data)) return; const sessionId = data.session_id || "unknown"; + const context = resolveProjectContext(data.cwd); fetch(`${REST_URL}/agentmemory/observe`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ hookType: "task_completed", sessionId, - project: resolveProject(data.cwd), - cwd: data.cwd || process.cwd(), + ...context, timestamp: (/* @__PURE__ */ new Date()).toISOString(), data: { task_id: data.task_id, @@ -69,7 +135,7 @@ async function main() { setTimeout(() => process.exit(0), 500).unref(); } main(); - //#endregion -export { }; +export {}; + //# sourceMappingURL=task-completed.mjs.map \ No newline at end of file diff --git a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md index 0c556fc77f..ebe4bb912b 100644 --- a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md +++ b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md @@ -3,7 +3,7 @@ Generated from `src/mcp/tools-registry.ts`. Do not edit the block below by hand; run `npm run skills:gen` after changing the registry. -agentmemory exposes 53 MCP tools. 8 are in the lean core set (`--tools core` or `AGENTMEMORY_TOOLS=core`); the rest load with `--tools all` (default). +agentmemory exposes 53 MCP tools. Seven non-LLM essentials are in the lean core set (`--tools core` or `AGENTMEMORY_TOOLS=core`); the rest load with `--tools all` (default). `AGENTMEMORY_TOOLS=workstation` adds lessons, actions, leases, and signals while omitting LLM-backed tools. | Tool | Core | Parameters | Purpose | | --- | --- | --- | --- | diff --git a/src/cli.ts b/src/cli.ts index 93b907491d..6165f45989 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -190,7 +190,8 @@ Options: --help, -h Show this help --verbose, -v Show engine stderr, boot log, and diagnostic info --reset Wipe ~/.agentmemory/preferences.json and re-run onboarding - --tools all|core Tool visibility (default: all = ${ALL_TOOLS_COUNT} tools; core = ${CORE_TOOLS_COUNT} essentials) + --tools all|core|workstation + Tool visibility (default: all = ${ALL_TOOLS_COUNT}; core = ${CORE_TOOLS_COUNT}; workstation = curated coordination set) --no-engine Skip auto-starting iii-engine --port Override REST port (default: 3111). Streams (N+1), viewer (N+2), and iii engine (N+46023) auto-derive from N so a @@ -224,12 +225,14 @@ Quick start: const toolsIdx = args.indexOf("--tools"); if (toolsIdx !== -1 && args[toolsIdx + 1]) { const toolsMode = args[toolsIdx + 1]!; - if (toolsMode !== "all" && toolsMode !== "core") { + if (!["all", "core", "workstation"].includes(toolsMode) && !toolsMode.includes(",")) { p.log.warn( - `Unknown --tools value "${toolsMode}" (valid: all, core); falling back to all.`, + `Unknown --tools value "${toolsMode}" (valid: all, core, workstation, or a comma-separated allowlist); falling back to the safe core set.`, ); + process.env["AGENTMEMORY_TOOLS"] = "core"; + } else { + process.env["AGENTMEMORY_TOOLS"] = toolsMode; } - process.env["AGENTMEMORY_TOOLS"] = toolsMode; } const portIdx = args.indexOf("--port"); @@ -1397,7 +1400,7 @@ async function runStatus() { try { const [healthRes, sessionsRes, graphRes, memoriesRes, flagsRes, followupRes] = await Promise.all([ apiFetch(base, "health"), - apiFetch(base, "sessions"), + apiFetch(base, "sessions?limit=500&format=compact"), apiFetch(base, "graph/stats"), apiFetch(base, "memories?count=true"), apiFetch(base, "config/flags"), @@ -1411,7 +1414,7 @@ async function runStatus() { const status = healthRes?.status || "unknown"; const version = healthRes?.version || "?"; const sessionList = Array.isArray(sessionsRes?.sessions) ? sessionsRes.sessions : []; - const sessions = sessionList.length; + const sessions = sessionsRes?.pagination?.total ?? sessionList.length; const nodes = Number(graphRes?.totalNodes ?? graphRes?.nodes ?? graphRes?.nodeCount ?? 0); const edges = Number(graphRes?.totalEdges ?? graphRes?.edges ?? graphRes?.edgeCount ?? 0); const cb = healthRes?.circuitBreaker?.state || "closed"; diff --git a/src/functions/observe.ts b/src/functions/observe.ts index 8ad4ba0ff5..43f7d26efd 100644 --- a/src/functions/observe.ts +++ b/src/functions/observe.ts @@ -1,5 +1,5 @@ import { TriggerAction, type ISdk } from "iii-sdk"; -import type { RawObservation, HookPayload } from "../types.js"; +import type { RawObservation, HookPayload, Session } from "../types.js"; import { KV, STREAM, generateId } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; import { stripPrivateData } from "./privacy.js"; @@ -11,6 +11,17 @@ import { getSearchIndex, vectorIndexAddGuarded } from "./search.js"; import { getAgentId } from "../config.js"; import { logger } from "../logger.js"; import { saveImageToDisk } from "../utils/image-store.js"; +import { safeAudit } from "./audit.js"; + +const SESSION_CONTEXT_FIELDS = [ + "project", + "cwd", + "repoRoot", + "scopeType", + "worktree", + "branch", + "taskSlug", +] as const; export function extractImage(d: unknown): string | undefined { if (!d) return undefined; @@ -139,11 +150,7 @@ export function registerObserveFunction( // undefined). Env AGENT_ID only fires when no session row // exists yet — otherwise an unscoped session would get // retroactively scoped by a later AGENT_ID export. - const existingSession = await kv.get<{ - agentId?: string; - observationCount?: number; - firstPrompt?: string; - }>(KV.sessions, payload.sessionId); + const existingSession = await kv.get(KV.sessions, payload.sessionId); const inheritedAgentId = existingSession ? existingSession.agentId : getAgentId(); @@ -227,14 +234,34 @@ export function registerObserveFunction( const session = existingSession; if (session) { + const updatedAt = new Date().toISOString(); + const changedContext: string[] = []; const updates: Array<{ type: "set"; path: string; value: unknown }> = [ - { type: "set", path: "updatedAt", value: new Date().toISOString() }, + { type: "set", path: "updatedAt", value: updatedAt }, { type: "set", path: "observationCount", value: (session.observationCount || 0) + 1, }, ]; + for (const field of SESSION_CONTEXT_FIELDS) { + const value = payload[field]; + if (typeof value !== "string" || !value.trim()) continue; + const normalized = value.trim(); + if (session[field] === normalized) continue; + updates.push({ type: "set", path: field, value: normalized }); + changedContext.push(field); + } + if (changedContext.includes("project") && session.project) { + const aliases = new Set(session.projectAliases ?? []); + aliases.add(session.project); + aliases.delete(payload.project.trim()); + updates.push({ + type: "set", + path: "projectAliases", + value: [...aliases].sort(), + }); + } if (!session.firstPrompt && typeof raw.userPrompt === "string") { const trimmed = raw.userPrompt.replace(/\s+/g, " ").trim(); if (trimmed.length > 0) { @@ -246,6 +273,15 @@ export function registerObserveFunction( } } await kv.update(KV.sessions, payload.sessionId, updates); + if (changedContext.length > 0) { + await safeAudit( + kv, + "session_context_update", + "mem::observe", + [payload.sessionId], + { changed: changedContext }, + ); + } } else if ( typeof payload.project === "string" && payload.project.trim().length > 0 && @@ -269,6 +305,11 @@ export function registerObserveFunction( id: payload.sessionId, project: payload.project, cwd: payload.cwd, + ...(payload.repoRoot ? { repoRoot: payload.repoRoot } : {}), + ...(payload.scopeType ? { scopeType: payload.scopeType } : {}), + ...(payload.worktree ? { worktree: payload.worktree } : {}), + ...(payload.branch ? { branch: payload.branch } : {}), + ...(payload.taskSlug ? { taskSlug: payload.taskSlug } : {}), startedAt: payload.timestamp ?? ts, updatedAt: ts, status: "active", diff --git a/src/functions/session-context.ts b/src/functions/session-context.ts new file mode 100644 index 0000000000..10dcf51f42 --- /dev/null +++ b/src/functions/session-context.ts @@ -0,0 +1,94 @@ +import type { ISdk } from "iii-sdk"; +import type { Session } from "../types.js"; +import { KV } from "../state/schema.js"; +import type { StateKV } from "../state/kv.js"; +import { withKeyedLock } from "../state/keyed-mutex.js"; +import { recordAudit } from "./audit.js"; + +export interface SessionContextInput { + sessionId: string; + project?: string; + cwd?: string; + repoRoot?: string; + scopeType?: string; + worktree?: string; + branch?: string; + taskSlug?: string; +} + +const CONTEXT_FIELDS = [ + "project", + "cwd", + "repoRoot", + "scopeType", + "worktree", + "branch", + "taskSlug", +] as const; + +function contextView(session: Session) { + return { + id: session.id, + project: session.project, + cwd: session.cwd, + repoRoot: session.repoRoot, + scopeType: session.scopeType, + worktree: session.worktree, + branch: session.branch, + taskSlug: session.taskSlug, + projectAliases: session.projectAliases, + updatedAt: session.updatedAt, + }; +} + +export function registerSessionContextFunction(sdk: ISdk, kv: StateKV): void { + sdk.registerFunction("mem::session-context-update", async (data: SessionContextInput) => { + if (!data?.sessionId || typeof data.sessionId !== "string") { + return { success: false, error: "sessionId is required" }; + } + return withKeyedLock(`session-context:${data.sessionId}`, async () => { + const session = await kv.get(KV.sessions, data.sessionId); + if (!session) { + return { success: false, error: "session not found", sessionId: data.sessionId }; + } + + const updates: Array<{ type: "set"; path: string; value: unknown }> = []; + const changed: string[] = []; + for (const field of CONTEXT_FIELDS) { + const value = data[field]; + if (typeof value !== "string" || !value.trim()) continue; + const normalized = value.trim(); + if (session[field] === normalized) continue; + updates.push({ type: "set", path: field, value: normalized }); + changed.push(field); + } + + if (changed.includes("project") && session.project) { + const aliases = new Set(session.projectAliases ?? []); + aliases.add(session.project); + aliases.delete(data.project?.trim() ?? ""); + updates.push({ type: "set", path: "projectAliases", value: [...aliases].sort() }); + } + if (updates.length === 0) { + return { success: true, changed: [], context: contextView(session) }; + } + + const updatedAt = new Date().toISOString(); + updates.push({ type: "set", path: "updatedAt", value: updatedAt }); + await kv.update(KV.sessions, data.sessionId, updates); + await recordAudit( + kv, + "session_context_update", + "mem::session-context-update", + [data.sessionId], + { changed }, + ); + const updated = await kv.get(KV.sessions, data.sessionId); + return { + success: true, + changed, + context: updated ? contextView(updated) : null, + }; + }); + }); +} diff --git a/src/functions/session-list.ts b/src/functions/session-list.ts new file mode 100644 index 0000000000..d3db68e351 --- /dev/null +++ b/src/functions/session-list.ts @@ -0,0 +1,148 @@ +import type { Session } from "../types.js"; + +export interface SessionListOptions { + limit?: number; + cursor?: string; + project?: string; + status?: Session["status"]; + since?: string; + format?: "compact" | "full"; + includePrompt?: boolean; + includeMalformed?: boolean; +} + +export interface SessionPage { + sessions: Array & Pick & { issues?: string[] }>; + pagination: { + total: number; + limit: number; + nextCursor: string | null; + hasMore: boolean; + malformedExcluded: number; + }; +} + +const DEFAULT_LIMIT = 50; +const MAX_LIMIT = 500; + +function encodeCursor(offset: number): string { + return Buffer.from(String(offset), "utf8").toString("base64url"); +} + +function decodeCursor(cursor?: string): number { + if (!cursor) return 0; + try { + const raw = Buffer.from(cursor, "base64url").toString("utf8"); + const offset = Number(raw); + if (!Number.isInteger(offset) || offset < 0) throw new Error("invalid offset"); + return offset; + } catch { + throw new Error("cursor must be a valid session-page cursor"); + } +} + +function normalizedLimit(value?: number): number { + if (!Number.isFinite(value) || !value || value < 1) return DEFAULT_LIMIT; + return Math.min(Math.floor(value), MAX_LIMIT); +} + +function sessionTimestamp(session: Session): string { + return session.updatedAt || session.startedAt || ""; +} + +export function sessionIssues(session: Session): string[] { + const issues: string[] = []; + if (typeof session?.id !== "string" || !session.id.trim()) issues.push("missing_id"); + if (typeof session?.project !== "string" || !session.project.trim()) issues.push("missing_project"); + if (typeof session?.cwd !== "string" || !session.cwd.trim()) issues.push("missing_cwd"); + if (typeof session?.startedAt !== "string" || Number.isNaN(Date.parse(session.startedAt))) { + issues.push("invalid_started_at"); + } + if (!["active", "completed", "abandoned"].includes(session?.status)) issues.push("invalid_status"); + return issues; +} + +function compactSession(session: Session): SessionPage["sessions"][number] { + const issues = sessionIssues(session); + return { + id: typeof session.id === "string" ? session.id : "", + project: typeof session.project === "string" ? session.project : "", + status: ["active", "completed", "abandoned"].includes(session.status) + ? session.status + : "abandoned", + observationCount: session.observationCount, + startedAt: session.startedAt, + updatedAt: session.updatedAt, + endedAt: session.endedAt, + agentId: session.agentId, + repoRoot: session.repoRoot, + scopeType: session.scopeType, + worktree: session.worktree, + branch: session.branch, + taskSlug: session.taskSlug, + ...(issues.length > 0 ? { issues } : {}), + }; +} + +function fullSession(session: Session, includePrompt: boolean): Session { + if (includePrompt) return { ...session }; + const { firstPrompt: _firstPrompt, ...safe } = session; + return safe as Session; +} + +export function selectSessionPage( + input: Session[], + options: SessionListOptions = {}, +): SessionPage { + const limit = normalizedLimit(options.limit); + const offset = decodeCursor(options.cursor); + const format = options.format ?? "compact"; + if (format !== "compact" && format !== "full") { + throw new Error("format must be compact or full"); + } + if (options.status && !["active", "completed", "abandoned"].includes(options.status)) { + throw new Error("status must be active, completed, or abandoned"); + } + const sinceMs = options.since ? Date.parse(options.since) : null; + if (options.since && Number.isNaN(sinceMs)) { + throw new Error("since must be a valid ISO timestamp"); + } + + const malformed = input.filter((session) => sessionIssues(session).length > 0); + const candidates = options.includeMalformed + ? input + : input.filter((session) => sessionIssues(session).length === 0); + const filtered = candidates + .filter((session) => { + if ( + options.project && + session.project !== options.project && + !(Array.isArray(session.projectAliases) && session.projectAliases.includes(options.project)) + ) { + return false; + } + if (options.status && session.status !== options.status) return false; + if (sinceMs !== null && Date.parse(sessionTimestamp(session)) < sinceMs) return false; + return true; + }) + .sort((left, right) => { + const byTime = sessionTimestamp(right).localeCompare(sessionTimestamp(left)); + return byTime || String(right.id || "").localeCompare(String(left.id || "")); + }); + + const page = filtered.slice(offset, offset + limit); + const nextOffset = offset + page.length; + const hasMore = nextOffset < filtered.length; + return { + sessions: page.map((session) => + format === "full" ? fullSession(session, options.includePrompt === true) : compactSession(session), + ), + pagination: { + total: filtered.length, + limit, + nextCursor: hasMore ? encodeCursor(nextOffset) : null, + hasMore, + malformedExcluded: options.includeMalformed ? 0 : malformed.length, + }, + }; +} diff --git a/src/hooks/_project.ts b/src/hooks/_project.ts index 35364ea3bb..cdd83294dc 100644 --- a/src/hooks/_project.ts +++ b/src/hooks/_project.ts @@ -1,20 +1,127 @@ -import { execSync } from "node:child_process"; -import { basename } from "node:path"; +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { basename, dirname, parse, resolve } from "node:path"; -// Resolution order: AGENTMEMORY_PROJECT_NAME env → git toplevel basename → cwd basename. -export function resolveProject(cwd?: string): string { - const explicit = process.env["AGENTMEMORY_PROJECT_NAME"]; - if (explicit && explicit.trim()) return explicit.trim(); - const dir = cwd && cwd.trim() ? cwd : process.cwd(); +export interface ProjectContext { + project: string; + cwd: string; + repoRoot: string; + scopeType: string; + worktree?: string; + branch?: string; + taskSlug?: string; +} + +interface ProjectFile { + project_id?: unknown; + projectId?: unknown; + repo_root?: unknown; + repoRoot?: unknown; + scope_type?: unknown; + scopeType?: unknown; +} + +function git(cwd: string, args: string[]): string { try { - const top = execSync("git rev-parse --show-toplevel", { - cwd: dir, + return execFileSync("git", args, { + cwd, stdio: ["ignore", "pipe", "ignore"], timeout: 500, }) .toString() .trim(); - if (top) return basename(top); - } catch {} - return basename(dir); + } catch { + return ""; + } +} + +function nearestProjectFile(cwd: string, boundary?: string): string | undefined { + let current = resolve(cwd); + const root = boundary ? resolve(boundary) : parse(current).root; + while (true) { + const candidate = resolve(current, ".agentmemory", "project.json"); + if (existsSync(candidate)) return candidate; + if (current === root) return undefined; + current = dirname(current); + } +} + +function readProjectFile(cwd: string, boundary?: string): { file: string; data: ProjectFile } | undefined { + const file = nearestProjectFile(cwd, boundary); + if (!file) return undefined; + try { + const data = JSON.parse(readFileSync(file, "utf8")) as ProjectFile; + return { file, data }; + } catch { + return undefined; + } +} + +function remoteProjectName(remote: string): string { + const normalized = remote.trim().replace(/\/$/, "").replace(/\.git$/, ""); + if (!normalized) return ""; + const tail = normalized.split(/[/:]/).filter(Boolean).at(-1); + return tail || ""; +} + +function nonEmpty(value: unknown): string | undefined { + return typeof value === "string" && value.trim() ? value.trim() : undefined; +} + +export function resolveProjectContext(cwd?: string): ProjectContext { + const rawDir = cwd && cwd.trim() ? cwd.trim() : process.cwd(); + // Copilot can forward a Windows cwd to a hook running under WSL or a + // POSIX test harness. node:path would otherwise turn `C:\\repo` into a + // child of the current POSIX directory and inherit an unrelated manifest. + if (process.platform !== "win32" && (/^[A-Za-z]:[\\/]/.test(rawDir) || rawDir.startsWith("\\\\"))) { + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + return { + project: explicitProject || basename(rawDir), + cwd: rawDir, + repoRoot: nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]) || rawDir, + scopeType: nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) || "directory", + ...(taskSlug ? { taskSlug } : {}), + }; + } + const dir = resolve(rawDir); + const gitTop = git(dir, ["rev-parse", "--show-toplevel"]); + const projectFile = readProjectFile(dir, gitTop || undefined); + const remoteName = remoteProjectName(git(dir, ["config", "--get", "remote.origin.url"])); + const fileProject = projectFile + ? nonEmpty(projectFile.data.project_id) ?? nonEmpty(projectFile.data.projectId) + : undefined; + const explicitProject = nonEmpty(process.env["AGENTMEMORY_PROJECT_NAME"]); + const rawRepoRoot = projectFile + ? nonEmpty(projectFile.data.repo_root) ?? nonEmpty(projectFile.data.repoRoot) + : undefined; + const configuredRepoRoot = nonEmpty(process.env["AGENTMEMORY_REPO_ROOT"]); + const projectFileRoot = projectFile ? dirname(dirname(projectFile.file)) : undefined; + const repoRoot = configuredRepoRoot + ? resolve(configuredRepoRoot) + : rawRepoRoot + ? resolve(projectFileRoot || dir, rawRepoRoot) + : gitTop || dir; + const scopeType = + nonEmpty(process.env["AGENTMEMORY_SCOPE_TYPE"]) ?? + (projectFile + ? nonEmpty(projectFile.data.scope_type) ?? nonEmpty(projectFile.data.scopeType) + : undefined) ?? + (gitTop ? "repo" : "directory"); + const taskSlug = nonEmpty(process.env["AGENTMEMORY_TASK_SLUG"]); + const branch = gitTop ? git(dir, ["branch", "--show-current"]) : ""; + + return { + project: (explicitProject ?? fileProject ?? remoteName) || basename(gitTop || dir), + cwd: dir, + repoRoot, + scopeType, + ...(gitTop ? { worktree: gitTop } : {}), + ...(branch ? { branch } : {}), + ...(taskSlug ? { taskSlug } : {}), + }; +} + +export function resolveProject(cwd?: string): string { + return resolveProjectContext(cwd).project; } diff --git a/src/hooks/notification.ts b/src/hooks/notification.ts index 9ad7704239..bf6b062724 100644 --- a/src/hooks/notification.ts +++ b/src/hooks/notification.ts @@ -1,5 +1,5 @@ #!/usr/bin/env node -import { resolveProject } from "./_project.js"; +import { resolveProjectContext } from "./_project.js"; function isSdkChildContext(payload: unknown): boolean { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; @@ -38,6 +38,7 @@ async function main() { typeof rawSessionId === "string" && rawSessionId.length > 0 ? rawSessionId : "unknown"; + const context = resolveProjectContext(data.cwd as string | undefined); fetch(`${REST_URL}/agentmemory/observe`, { method: "POST", @@ -45,8 +46,7 @@ async function main() { body: JSON.stringify({ hookType: "notification", sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), + ...context, timestamp: new Date().toISOString(), data: { notification_type: notificationType, diff --git a/src/hooks/post-tool-failure.ts b/src/hooks/post-tool-failure.ts index f0295b3e62..65ae09c18c 100644 --- a/src/hooks/post-tool-failure.ts +++ b/src/hooks/post-tool-failure.ts @@ -1,5 +1,5 @@ #!/usr/bin/env node -import { resolveProject } from "./_project.js"; +import { resolveProjectContext } from "./_project.js"; function isSdkChildContext(payload: unknown): boolean { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; @@ -34,8 +34,13 @@ async function main() { const sessionId = ((data.session_id || data.sessionId) as string) || "unknown"; const toolName = data.tool_name ?? data.toolName; + if (typeof toolName === "string" && ( + toolName.toLowerCase().startsWith("mcp__agentmemory__") || + toolName.toLowerCase().startsWith("memory_") + )) return; const toolInput = data.tool_input ?? data.toolArgs; const error = data.error ?? data.errorMessage; + const context = resolveProjectContext(data.cwd as string | undefined); fetch(`${REST_URL}/agentmemory/observe`, { method: "POST", @@ -43,8 +48,7 @@ async function main() { body: JSON.stringify({ hookType: "post_tool_failure", sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), + ...context, timestamp: new Date().toISOString(), data: { tool_name: toolName, diff --git a/src/hooks/post-tool-use.ts b/src/hooks/post-tool-use.ts index c68a7731d3..e3696850ef 100644 --- a/src/hooks/post-tool-use.ts +++ b/src/hooks/post-tool-use.ts @@ -1,5 +1,5 @@ #!/usr/bin/env node -import { resolveProject } from "./_project.js"; +import { resolveProjectContext } from "./_project.js"; function isSdkChildContext(payload: unknown): boolean { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; @@ -34,6 +34,9 @@ async function main() { const sessionId = ((data.session_id || data.sessionId) as string) || "unknown"; const toolName = data.tool_name ?? data.toolName; const toolInput = data.tool_input ?? data.toolArgs; + if (shouldSkipTool(toolName)) return; + const context = resolveProjectContext(data.cwd as string | undefined); + const maxChars = maxCaptureChars(); const { imageData, cleanOutput } = extractImageData(toolOutput(data)); @@ -43,13 +46,12 @@ async function main() { body: JSON.stringify({ hookType: "post_tool_use", sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), + ...context, timestamp: new Date().toISOString(), data: { tool_name: toolName, - tool_input: toolInput, - tool_output: truncate(cleanOutput, 8000), + tool_input: truncate(toolInput, maxChars), + tool_output: truncate(cleanOutput, maxChars), ...(imageData ? { image_data: imageData } : {}), }, }), @@ -58,6 +60,27 @@ async function main() { setTimeout(() => process.exit(0), 500).unref(); } +function shouldSkipTool(value: unknown): boolean { + const name = typeof value === "string" ? value.trim().toLowerCase() : ""; + if (!name) return false; + if (name.startsWith("mcp__agentmemory__") || name.startsWith("memory_")) { + return true; + } + const configured = (process.env["AGENTMEMORY_SKIP_TOOLS"] || "") + .split(",") + .map((item) => item.trim().toLowerCase()) + .filter(Boolean); + return configured.some((pattern) => + pattern.endsWith("*") ? name.startsWith(pattern.slice(0, -1)) : name === pattern, + ); +} + +function maxCaptureChars(): number { + const value = Number(process.env["AGENTMEMORY_MAX_TOOL_CAPTURE_CHARS"] || "8000"); + if (!Number.isFinite(value) || value < 0) return 8000; + return Math.min(Math.floor(value), 32_000); +} + function toolOutput(data: Record): unknown { if (data.tool_response !== undefined) return data.tool_response; if (data.tool_output !== undefined) return data.tool_output; diff --git a/src/hooks/prompt-submit.ts b/src/hooks/prompt-submit.ts index 2da8ea6a41..2850c78866 100644 --- a/src/hooks/prompt-submit.ts +++ b/src/hooks/prompt-submit.ts @@ -1,5 +1,5 @@ #!/usr/bin/env node -import { resolveProject } from "./_project.js"; +import { resolveProjectContext } from "./_project.js"; function isSdkChildContext(payload: unknown): boolean { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; @@ -32,6 +32,9 @@ async function main() { if (isSdkChildContext(data)) return; const sessionId = ((data.session_id || data.sessionId) as string) || "unknown"; + const context = resolveProjectContext(data.cwd as string | undefined); + const prompt = data.prompt ?? data.userPrompt; + const promptData = promptCapture(prompt); fetch(`${REST_URL}/agentmemory/observe`, { method: "POST", @@ -39,14 +42,24 @@ async function main() { body: JSON.stringify({ hookType: "prompt_submit", sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), + ...context, timestamp: new Date().toISOString(), - data: { prompt: data.prompt ?? data.userPrompt }, + data: promptData, }), signal: AbortSignal.timeout(3000), }).catch(() => {}); setTimeout(() => process.exit(0), 500).unref(); } +function promptCapture(value: unknown): Record { + const text = typeof value === "string" ? value : ""; + const mode = (process.env["AGENTMEMORY_CAPTURE_PROMPTS"] || "full").toLowerCase(); + if (mode === "off" || mode === "metadata") { + return { prompt_length: text.length, prompt_capture: mode }; + } + const max = Number(process.env["AGENTMEMORY_MAX_PROMPT_CAPTURE_CHARS"] || "4000"); + const limit = Number.isFinite(max) && max >= 0 ? Math.min(Math.floor(max), 16_000) : 4000; + return { prompt: text.slice(0, limit) }; +} + main(); diff --git a/src/hooks/session-start.ts b/src/hooks/session-start.ts index 573c092b14..80505a6ef8 100644 --- a/src/hooks/session-start.ts +++ b/src/hooks/session-start.ts @@ -1,5 +1,5 @@ #!/usr/bin/env node -import { resolveProject } from "./_project.js"; +import { resolveProjectContext } from "./_project.js"; // Inlined from ./sdk-guard so each hook bundles to a single self-contained // .mjs (matches the pattern used by every other hook entry in tsdown.config). @@ -52,14 +52,13 @@ async function main() { const sessionId = ((data.session_id || data.sessionId) as string) || `ses_${Date.now().toString(36)}`; - const cwd = (data.cwd as string) || process.cwd(); - const project = resolveProject(data.cwd as string | undefined); + const context = resolveProjectContext(data.cwd as string | undefined); const url = `${REST_URL}/agentmemory/session/start`; const init: RequestInit = { method: "POST", headers: authHeaders(), - body: JSON.stringify({ sessionId, project, cwd }), + body: JSON.stringify({ sessionId, ...context }), }; if (!INJECT_CONTEXT) { diff --git a/src/hooks/subagent-start.ts b/src/hooks/subagent-start.ts index 44c87c85e9..d9f46a56f9 100644 --- a/src/hooks/subagent-start.ts +++ b/src/hooks/subagent-start.ts @@ -1,5 +1,5 @@ #!/usr/bin/env node -import { resolveProject } from "./_project.js"; +import { resolveProjectContext } from "./_project.js"; // Inlined from ./sdk-guard so each hook bundles to a single self-contained // .mjs (matches the pattern used by every other hook entry in tsdown.config). @@ -42,6 +42,7 @@ async function main() { const sessionId = ((data.session_id || data.sessionId) as string) || "unknown"; const agentId = data.agent_id || data.agentName; const agentType = data.agent_type || data.agentDisplayName || data.agentName; + const context = resolveProjectContext(data.cwd as string | undefined); fetch(`${REST_URL}/agentmemory/observe`, { method: "POST", @@ -49,8 +50,7 @@ async function main() { body: JSON.stringify({ hookType: "subagent_start", sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), + ...context, timestamp: new Date().toISOString(), data: { agent_id: agentId, diff --git a/src/hooks/subagent-stop.ts b/src/hooks/subagent-stop.ts index 5a437c9fd4..931b989185 100644 --- a/src/hooks/subagent-stop.ts +++ b/src/hooks/subagent-stop.ts @@ -1,5 +1,5 @@ #!/usr/bin/env node -import { resolveProject } from "./_project.js"; +import { resolveProjectContext } from "./_project.js"; function isSdkChildContext(payload: unknown): boolean { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; @@ -38,6 +38,7 @@ async function main() { typeof data.last_assistant_message === "string" ? data.last_assistant_message.slice(0, 4000) : ""; + const context = resolveProjectContext(data.cwd as string | undefined); fetch(`${REST_URL}/agentmemory/observe`, { method: "POST", @@ -45,8 +46,7 @@ async function main() { body: JSON.stringify({ hookType: "subagent_stop", sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), + ...context, timestamp: new Date().toISOString(), data: { agent_id: agentId, diff --git a/src/hooks/task-completed.ts b/src/hooks/task-completed.ts index dbdf815ac8..63733abd81 100644 --- a/src/hooks/task-completed.ts +++ b/src/hooks/task-completed.ts @@ -1,5 +1,5 @@ #!/usr/bin/env node -import { resolveProject } from "./_project.js"; +import { resolveProjectContext } from "./_project.js"; function isSdkChildContext(payload: unknown): boolean { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; @@ -32,6 +32,7 @@ async function main() { if (isSdkChildContext(data)) return; const sessionId = (data.session_id as string) || "unknown"; + const context = resolveProjectContext(data.cwd as string | undefined); fetch(`${REST_URL}/agentmemory/observe`, { method: "POST", @@ -39,8 +40,7 @@ async function main() { body: JSON.stringify({ hookType: "task_completed", sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), + ...context, timestamp: new Date().toISOString(), data: { task_id: data.task_id, diff --git a/src/index.ts b/src/index.ts index 1e623eae81..d89fddf7e8 100644 --- a/src/index.ts +++ b/src/index.ts @@ -88,6 +88,7 @@ import { registerTemporalGraphFunctions } from "./functions/temporal-graph.js"; import { registerRetentionFunctions } from "./functions/retention.js"; import { registerCompressFileFunction } from "./functions/compress-file.js"; import { registerReplayFunctions } from "./functions/replay.js"; +import { registerSessionContextFunction } from "./functions/session-context.js"; import { registerApiTriggers } from "./triggers/api.js"; import { registerEventTriggers } from "./triggers/events.js"; import { registerMcpEndpoints } from "./mcp/server.js"; @@ -332,6 +333,7 @@ async function main() { registerRetentionFunctions(sdk, kv); registerCompressFileFunction(sdk, kv, provider); registerReplayFunctions(sdk, kv); + registerSessionContextFunction(sdk, kv); bootLog( `v0.6 advanced retrieval: sliding-window, query-expansion, temporal-graph, retention-scoring`, ); @@ -518,7 +520,7 @@ async function main() { `Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`, ); bootLog( - `REST API: 128 endpoints at http://localhost:${config.restPort}/agentmemory/*`, + `REST API: 129 endpoints at http://localhost:${config.restPort}/agentmemory/*`, ); bootLog( `MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`, diff --git a/src/mcp/server.ts b/src/mcp/server.ts index dbca07d9b8..838e572e67 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -11,6 +11,7 @@ import type { import { getVisibleTools } from "./tools-registry.js"; import { timingSafeCompare } from "../auth.js"; import { getAgentId, isAgentScopeIsolated } from "../config.js"; +import { selectSessionPage } from "../functions/session-list.js"; type McpResponse = { status_code: number; @@ -253,12 +254,22 @@ export function registerMcpEndpoints( } case "memory_sessions": { - const sessions = await kv.list(KV.sessions); + const sessions = await kv.list(KV.sessions); + const page = selectSessionPage(sessions, { + limit: asNumber(args.limit, 20), + cursor: asNonEmptyString(args.cursor), + project: asNonEmptyString(args.project), + status: asNonEmptyString(args.status) as Session["status"] | undefined, + since: asNonEmptyString(args.since), + format: (asNonEmptyString(args.format) ?? "compact") as "compact" | "full", + includePrompt: args.includePrompt === true, + includeMalformed: args.includeMalformed === true, + }); return { status_code: 200, body: { content: [ - { type: "text", text: JSON.stringify({ sessions }, null, 2) }, + { type: "text", text: JSON.stringify(page, null, 2) }, ], }, }; diff --git a/src/mcp/standalone.ts b/src/mcp/standalone.ts index dd66ecb1dd..5ed47367f1 100644 --- a/src/mcp/standalone.ts +++ b/src/mcp/standalone.ts @@ -6,6 +6,8 @@ import { getAllTools } from "./tools-registry.js"; import { getStandalonePersistPath } from "../config.js"; import { VERSION } from "../version.js"; import { generateId } from "../state/schema.js"; +import { selectSessionPage } from "../functions/session-list.js"; +import type { Session } from "../types.js"; import { resolveHandle, invalidateHandle, @@ -105,6 +107,12 @@ interface Validated { tokenBudget?: number; memoryIds?: string[]; reason?: string; + cursor?: string; + project?: string; + status?: string; + since?: string; + includePrompt?: boolean; + includeMalformed?: boolean; } function validate(toolName: string, args: Record): Validated { @@ -147,6 +155,13 @@ function validate(toolName: string, args: Record): Validated { } case "memory_sessions": { v.limit = parseLimit(args["limit"], 20); + if (typeof args["cursor"] === "string") v.cursor = args["cursor"].trim(); + if (typeof args["project"] === "string") v.project = args["project"].trim(); + if (typeof args["status"] === "string") v.status = args["status"].trim(); + if (typeof args["since"] === "string") v.since = args["since"].trim(); + if (typeof args["format"] === "string") v.format = args["format"].trim().toLowerCase(); + v.includePrompt = args["includePrompt"] === true; + v.includeMalformed = args["includeMalformed"] === true; return v; } case "memory_governance_delete": { @@ -208,8 +223,18 @@ async function handleProxy( return textResponse(result, true); } case "memory_sessions": { + const params = new URLSearchParams({ + limit: String(v.limit), + format: v.format ?? "compact", + }); + if (v.cursor) params.set("cursor", v.cursor); + if (v.project) params.set("project", v.project); + if (v.status) params.set("status", v.status); + if (v.since) params.set("since", v.since); + if (v.includePrompt) params.set("includePrompt", "true"); + if (v.includeMalformed) params.set("includeMalformed", "true"); const result = await handle.call( - `/agentmemory/sessions?limit=${v.limit}`, + `/agentmemory/sessions?${params.toString()}`, { method: "GET" }, ); return textResponse(result, true); @@ -289,9 +314,18 @@ async function handleLocal( case "memory_sessions": { const sessions = - await kvInstance.list>("mem:sessions"); - const limit = v.limit ?? 20; - return textResponse({ sessions: sessions.slice(0, limit) }, true); + await kvInstance.list("mem:sessions"); + const page = selectSessionPage(sessions, { + limit: v.limit, + cursor: v.cursor, + project: v.project, + status: v.status as Session["status"] | undefined, + since: v.since, + format: (v.format ?? "compact") as "compact" | "full", + includePrompt: v.includePrompt, + includeMalformed: v.includeMalformed, + }); + return textResponse(page, true); } case "memory_governance_delete": { diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts index c4df3499c7..4891177e99 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -115,8 +115,20 @@ export const CORE_TOOLS: McpToolDef[] = [ { name: "memory_sessions", description: - "List recent sessions with their status and observation counts.", - inputSchema: { type: "object", properties: {} }, + "List recent sessions with bounded pagination. Compact output omits prompts by default.", + inputSchema: { + type: "object", + properties: { + limit: { type: "number", description: "Page size (default 20, maximum 500)" }, + cursor: { type: "string", description: "Opaque nextCursor from the previous page" }, + project: { type: "string", description: "Canonical project id or a recorded alias" }, + status: { type: "string", description: "active, completed, or abandoned" }, + since: { type: "string", description: "Only sessions updated at or after this ISO timestamp" }, + format: { type: "string", description: "compact (default) or full" }, + includePrompt: { type: "boolean", description: "Include firstPrompt in full output (default false)" }, + includeMalformed: { type: "boolean", description: "Include malformed legacy session rows with issue labels (default false)" }, + }, + }, }, { name: "memory_smart_search", @@ -928,11 +940,29 @@ export const V010_SLOTS_TOOLS: McpToolDef[] = [ export const ESSENTIAL_TOOLS = new Set([ "memory_save", "memory_recall", - "memory_consolidate", "memory_smart_search", "memory_sessions", "memory_diagnose", "memory_lesson_save", + "memory_lesson_recall", +]); + +export const WORKSTATION_TOOLS = new Set([ + ...ESSENTIAL_TOOLS, + "memory_file_history", + "memory_action_create", + "memory_action_update", + "memory_frontier", + "memory_next", + "memory_lease", + "memory_signal_send", + "memory_signal_read", +]); + +export const LLM_BACKED_TOOLS = new Set([ + "memory_compress_file", + "memory_consolidate", + "memory_crystallize", "memory_reflect", ]); @@ -949,13 +979,36 @@ export function getAllTools(): McpToolDef[] { ]; } -// default switched from "core" (8 essential tools) to "all" -// (full 53-tool surface). README and plugin manifests have always -// advertised 53 tools "in proxy mode"; the old default left OpenCode / -// Claude Code users seeing 8 with no indication the other tools existed. -// Users who want the lean essentials can still set AGENTMEMORY_TOOLS=core. export function getVisibleTools(): McpToolDef[] { const mode = process.env["AGENTMEMORY_TOOLS"] || "all"; - if (mode === "core") return getAllTools().filter((t) => ESSENTIAL_TOOLS.has(t.name)); - return getAllTools(); + const all = getAllTools(); + let selected: McpToolDef[]; + if (mode === "all") { + selected = all; + } else if (mode === "core") { + selected = all.filter((tool) => ESSENTIAL_TOOLS.has(tool.name)); + } else if (mode === "workstation") { + selected = all.filter((tool) => WORKSTATION_TOOLS.has(tool.name)); + } else { + const allow = new Set( + mode + .split(",") + .map((name) => name.trim()) + .filter(Boolean), + ); + selected = all.filter((tool) => allow.has(tool.name)); + if (selected.length === 0) { + selected = all.filter((tool) => ESSENTIAL_TOOLS.has(tool.name)); + } + } + const disabled = new Set( + (process.env["AGENTMEMORY_DISABLED_TOOLS"] || "") + .split(",") + .map((name) => name.trim()) + .filter(Boolean), + ); + const noLlm = process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"] === "true"; + return selected.filter( + (tool) => !disabled.has(tool.name) && !(noLlm && LLM_BACKED_TOOLS.has(tool.name)), + ); } diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 7b6c2bf2b8..82fbb02deb 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -13,6 +13,7 @@ import { renderViewerDocument } from "../viewer/document.js"; import { getBoundViewerPort, getViewerSkipped } from "../viewer/server.js"; import { MAX_FILES_UPPER_BOUND } from "../functions/replay.js"; import { logger } from "../logger.js"; +import { selectSessionPage } from "../functions/session-list.js"; import { isGraphExtractionEnabled, isConsolidationEnabled, @@ -116,6 +117,21 @@ function asNonEmptyString(value: unknown): string | null { return trimmed ? trimmed : null; } +function sessionContextFields(body: Record): Partial { + const result: Partial = {}; + for (const field of [ + "repoRoot", + "scopeType", + "worktree", + "branch", + "taskSlug", + ] as const) { + const value = asNonEmptyString(body[field]); + if (value) result[field] = value.slice(0, 4096); + } + return result; +} + function parseOptionalFiniteNumber(value: unknown): number | undefined | null { if (value === undefined || value === null) return undefined; if (typeof value === "number") return Number.isFinite(value) ? value : null; @@ -264,6 +280,9 @@ export function registerApiTriggers( status, service: "agentmemory", version: VERSION, + buildId: process.env["AGENTMEMORY_BUILD_ID"] || null, + toolProfile: process.env["AGENTMEMORY_TOOLS"] || "all", + llmToolsDisabled: process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"] === "true", health: health || null, functionMetrics, circuitBreaker, @@ -307,6 +326,7 @@ export function registerApiTriggers( cwd, timestamp, data: body.data, + ...sessionContextFields(body), }; const result = await sdk.trigger({ function_id: "mem::observe", payload }); return { status_code: 201, body: result }; @@ -559,7 +579,16 @@ export function registerApiTriggers( sdk.registerFunction("api::session::start", async ( - req: ApiRequest<{ sessionId: string; project: string; cwd: string }>, + req: ApiRequest<{ + sessionId: string; + project: string; + cwd: string; + repoRoot?: string; + scopeType?: string; + worktree?: string; + branch?: string; + taskSlug?: string; + }>, ): Promise => { const body = (req.body ?? {}) as Record; const sessionId = asNonEmptyString(body.sessionId); @@ -582,11 +611,14 @@ export function registerApiTriggers( ? body.agentId.trim().slice(0, 128) : undefined; const agentId = requestAgentId ?? getAgentId(); + const startedAt = new Date().toISOString(); const session: Session = { id: sessionId, project, cwd, - startedAt: new Date().toISOString(), + ...sessionContextFields(body), + startedAt, + updatedAt: startedAt, status: "active", observationCount: 0, ...(title ? { summary: title.slice(0, 200) } : {}), @@ -614,6 +646,45 @@ export function registerApiTriggers( }, }); + sdk.registerFunction("api::session::context", + async (req: ApiRequest): Promise => { + const body = (req.body ?? {}) as Record; + const sessionId = asNonEmptyString(body.sessionId); + if (!sessionId) { + return { status_code: 400, body: { error: "sessionId is required" } }; + } + const context = sessionContextFields(body); + const project = asNonEmptyString(body.project); + const cwd = asNonEmptyString(body.cwd); + const payload = { + sessionId, + ...(project ? { project: project.slice(0, 512) } : {}), + ...(cwd ? { cwd: cwd.slice(0, 4096) } : {}), + ...context, + }; + if (Object.keys(payload).length === 1) { + return { status_code: 400, body: { error: "at least one context field is required" } }; + } + const result = await sdk.trigger({ + function_id: "mem::session-context-update", + payload, + }) as { success?: boolean; error?: string }; + if (!result.success && result.error === "session not found") { + return { status_code: 404, body: result }; + } + return { status_code: result.success ? 200 : 400, body: result }; + }, + ); + sdk.registerTrigger({ + type: "http", + function_id: "api::session::context", + config: { + api_path: "/agentmemory/session/context", + http_method: "POST", + middleware_function_ids: ["middleware::api-auth"], + }, + }); + sdk.registerFunction("api::session::end", async (req: ApiRequest<{ sessionId: string }>): Promise => { const sessionId = asNonEmptyString((req.body as Record)?.sessionId); @@ -655,6 +726,15 @@ export function registerApiTriggers( sdk.registerFunction("api::summarize", async (req: ApiRequest<{ sessionId: string }>): Promise => { + if (detectLlmProviderKind() === "noop") { + return { + status_code: 503, + body: { + error: "summarization requires a configured LLM provider", + disabled: true, + }, + }; + } const sessionId = asNonEmptyString((req.body as Record)?.sessionId); if (!sessionId) { return { status_code: 400, body: { error: "sessionId is required" } }; @@ -820,18 +900,41 @@ export function registerApiTriggers( ? undefined : explicitAgentId ?? (isAgentScopeIsolated() ? getAgentId() : undefined); - const filtered = filterAgentId + const agentSessions = filterAgentId ? sessions.filter((s) => s.agentId === filterAgentId) : sessions; - const summaries = await Promise.all( - filtered.map((s) => - kv.get(KV.summaries, s.id).catch(() => null), - ), - ); - const withSummary = filtered.map((s, i) => - summaries[i] ? { ...s, summary: summaries[i] } : s, - ); - return { status_code: 200, body: { sessions: withSummary } }; + const rawLimit = parseOptionalInt(req.query_params?.["limit"]); + if (rawLimit !== undefined && rawLimit < 1) { + return { status_code: 400, body: { error: "limit must be a positive integer" } }; + } + try { + const page = selectSessionPage(agentSessions, { + limit: rawLimit, + cursor: asNonEmptyString(req.query_params?.["cursor"]) ?? undefined, + project: asNonEmptyString(req.query_params?.["project"]) ?? undefined, + status: asNonEmptyString(req.query_params?.["status"]) as Session["status"] | undefined, + since: asNonEmptyString(req.query_params?.["since"]) ?? undefined, + format: (asNonEmptyString(req.query_params?.["format"]) ?? "compact") as "compact" | "full", + includePrompt: req.query_params?.["includePrompt"] === "true", + includeMalformed: req.query_params?.["includeMalformed"] === "true", + }); + if (req.query_params?.["includeSummary"] === "true") { + const summaries = await Promise.all( + page.sessions.map((session) => + kv.get(KV.summaries, session.id).catch(() => null), + ), + ); + page.sessions = page.sessions.map((session, index) => + summaries[index] ? { ...session, summary: summaries[index] } : session, + ); + } + return { status_code: 200, body: page }; + } catch (error) { + return { + status_code: 400, + body: { error: error instanceof Error ? error.message : String(error) }, + }; + } }, ); sdk.registerTrigger({ diff --git a/src/triggers/events.ts b/src/triggers/events.ts index e38b58db4d..598d79babc 100644 --- a/src/triggers/events.ts +++ b/src/triggers/events.ts @@ -3,18 +3,34 @@ import type { CompressedObservation, HookPayload, Session } from "../types.js"; import { KV, STREAM } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; import { isReflectEnabled } from "../functions/slots.js"; -import { isGraphExtractionEnabled } from "../config.js"; +import { detectLlmProviderKind, isGraphExtractionEnabled } from "../config.js"; import { logger } from "../logger.js"; export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { sdk.registerFunction( "event::session::started", - async (data: { sessionId: string; project: string; cwd: string }) => { + async (data: { + sessionId: string; + project: string; + cwd: string; + repoRoot?: string; + scopeType?: string; + worktree?: string; + branch?: string; + taskSlug?: string; + }) => { + const startedAt = new Date().toISOString(); const session: Session = { id: data.sessionId, project: data.project, cwd: data.cwd, - startedAt: new Date().toISOString(), + ...(data.repoRoot ? { repoRoot: data.repoRoot } : {}), + ...(data.scopeType ? { scopeType: data.scopeType } : {}), + ...(data.worktree ? { worktree: data.worktree } : {}), + ...(data.branch ? { branch: data.branch } : {}), + ...(data.taskSlug ? { taskSlug: data.taskSlug } : {}), + startedAt, + updatedAt: startedAt, status: "active", observationCount: 0, }; @@ -45,7 +61,9 @@ export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { }); sdk.registerFunction("event::session::stopped", async (data: { sessionId: string }) => { - const summary = await sdk.trigger({ function_id: "mem::summarize", payload: data }); + const summary = detectLlmProviderKind() === "noop" + ? { success: true, skipped: "no_llm_provider" } + : await sdk.trigger({ function_id: "mem::summarize", payload: data }); if (isReflectEnabled()) { try { sdk.trigger({ diff --git a/src/types.ts b/src/types.ts index 6797dfaf99..888e8ef8c4 100644 --- a/src/types.ts +++ b/src/types.ts @@ -2,7 +2,14 @@ export interface Session { id: string; project: string; cwd: string; + repoRoot?: string; + scopeType?: string; + worktree?: string; + branch?: string; + taskSlug?: string; + projectAliases?: string[]; startedAt: string; + updatedAt?: string; endedAt?: string; status: "active" | "completed" | "abandoned"; observationCount: number; @@ -135,6 +142,11 @@ export interface HookPayload { sessionId: string; project: string; cwd: string; + repoRoot?: string; + scopeType?: string; + worktree?: string; + branch?: string; + taskSlug?: string; timestamp: string; data: unknown; } @@ -563,6 +575,7 @@ export interface AuditEntry { timestamp: string; operation: | "observe" + | "session_context_update" | "compress" | "remember" | "forget" diff --git a/src/viewer/index.html b/src/viewer/index.html index 305397e935..7c392a7234 100644 --- a/src/viewer/index.html +++ b/src/viewer/index.html @@ -1345,7 +1345,7 @@

agentmemory

try { var results = await Promise.all([ apiGet('health'), - apiGet('sessions'), + apiGet('sessions?limit=500&format=compact'), apiGet('memories?latest=true&limit=500'), apiGet('graph/stats'), apiGet('audit?limit=5'), @@ -2534,7 +2534,7 @@

agentmemory

async function loadTimeline() { var el = document.getElementById('view-timeline'); el.innerHTML = '
Loading timeline...
'; - var sessResult = await apiGet('sessions'); + var sessResult = await apiGet('sessions?limit=500&format=compact'); var sessions = (sessResult && sessResult.sessions) || []; state.timeline.loaded = true; @@ -2761,7 +2761,7 @@

agentmemory

var el = document.getElementById('view-activity'); el.innerHTML = '
Loading activity...
'; var results = await Promise.all([ - apiGet('sessions'), + apiGet('sessions?limit=500&format=compact'), apiGet('audit?limit=200') ]); var sessions = (results[0] && results[0].sessions) || []; @@ -2897,7 +2897,7 @@

agentmemory

async function loadSessions() { var el = document.getElementById('view-sessions'); el.innerHTML = '
Loading sessions...
'; - var result = await apiGet('sessions'); + var result = await apiGet('sessions?limit=500&format=full&includeSummary=true'); state.sessions.items = (result && result.sessions) || []; state.sessions.loaded = true; renderSessions(); @@ -3376,7 +3376,7 @@

agentmemory

async function loadProfile() { var el = document.getElementById('view-profile'); el.innerHTML = '
Loading profile...
'; - var sessResult = await apiGet('sessions'); + var sessResult = await apiGet('sessions?limit=500&format=compact'); var sessions = (sessResult && sessResult.sessions) || []; var projects = {}; diff --git a/test/hook-project.test.ts b/test/hook-project.test.ts index 66e25f181f..c0479691ce 100644 --- a/test/hook-project.test.ts +++ b/test/hook-project.test.ts @@ -1,8 +1,9 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest"; -import { mkdtempSync, rmSync } from "node:fs"; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; -import { resolveProject } from "../src/hooks/_project.js"; +import { execFileSync } from "node:child_process"; +import { resolveProject, resolveProjectContext } from "../src/hooks/_project.js"; describe("resolveProject — hook project basename resolver", () => { const originalEnv = process.env.AGENTMEMORY_PROJECT_NAME; @@ -63,4 +64,40 @@ describe("resolveProject — hook project basename resolver", () => { expect(resolveProject("")).toBe("agentmemory"); expect(resolveProject(" ")).toBe("agentmemory"); }); + + it("prefers canonical snake_case project scope over worktree and remote names", () => { + const dir = mkdtempSync(join(tmpdir(), "amem-scope-")); + try { + mkdirSync(join(dir, ".agentmemory")); + writeFileSync( + join(dir, ".agentmemory", "project.json"), + JSON.stringify({ + project_id: "canonical-project", + repo_root: "/canonical/root", + scope_type: "repo", + }), + ); + const nested = join(dir, "nested"); + mkdirSync(nested); + expect(resolveProjectContext(nested)).toMatchObject({ + project: "canonical-project", + repoRoot: "/canonical/root", + scopeType: "repo", + }); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); + + it("uses the remote repository name instead of a worktree directory name", () => { + const dir = mkdtempSync(join(tmpdir(), "amem-worktree-name-")); + try { + execFileSync("git", ["init", "-q", dir]); + execFileSync("git", ["-C", dir, "remote", "add", "origin", "git@github.com:owner/stable-project.git"]); + expect(resolveProject(dir)).toBe("stable-project"); + expect(resolveProjectContext(dir).worktree).toBe(dir); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); }); diff --git a/test/mcp-standalone-proxy.test.ts b/test/mcp-standalone-proxy.test.ts index dc08a024ee..c74732d994 100644 --- a/test/mcp-standalone-proxy.test.ts +++ b/test/mcp-standalone-proxy.test.ts @@ -50,7 +50,9 @@ describe("@agentmemory/mcp standalone — server proxy (issue #159)", () => { const body = JSON.parse(res.content[0].text); expect(body.sessions).toHaveLength(1); expect(body.sessions[0].id).toBe("sess-1"); - expect(calls.find((c) => c.url.includes("/sessions"))).toBeDefined(); + const sessionsCall = calls.find((c) => c.url.includes("/sessions")); + expect(sessionsCall?.url).toContain("limit=5"); + expect(sessionsCall?.url).toContain("format=compact"); }); it("proxies memory_smart_search to POST /agentmemory/smart-search", async () => { diff --git a/test/mcp-standalone.test.ts b/test/mcp-standalone.test.ts index b48eade966..82bc3333c8 100644 --- a/test/mcp-standalone.test.ts +++ b/test/mcp-standalone.test.ts @@ -343,6 +343,10 @@ describe("handleToolCall", () => { await kv.set("mem:sessions", `ses_${i}`, { id: `ses_${i}`, project: "demo", + cwd: "/demo", + startedAt: `2026-07-0${i + 1}T00:00:00Z`, + status: "completed", + observationCount: i, }); } const result = await handleToolCall( @@ -352,6 +356,7 @@ describe("handleToolCall", () => { ); const parsed = JSON.parse(result.content[0].text); expect(parsed.sessions).toHaveLength(2); + expect(parsed.pagination).toMatchObject({ total: 5, hasMore: true }); }); it("parseLimit clamps bad/malicious limit values to a safe range", async () => { diff --git a/test/mcp-surface-default.test.ts b/test/mcp-surface-default.test.ts index 07fa235bbf..af159ffefe 100644 --- a/test/mcp-surface-default.test.ts +++ b/test/mcp-surface-default.test.ts @@ -3,11 +3,12 @@ import { readFileSync } from "node:fs"; import { getAllTools, getVisibleTools, + WORKSTATION_TOOLS, } from "../src/mcp/tools-registry.js"; // plugin manifests and README advertise 51 MCP tools. The old // default was AGENTMEMORY_TOOLS=core which silently capped the surface -// at 8 essentials with no indication the other 43 existed. Default +// at a lean subset with no indication the other tools existed. Default // flipped to "all"; the lean set is still accessible via // AGENTMEMORY_TOOLS=core. describe("MCP tool surface default (#553)", () => { @@ -32,24 +33,43 @@ describe("MCP tool surface default (#553)", () => { expect(getVisibleTools().length).toBe(getAllTools().length); }); - it("AGENTMEMORY_TOOLS=core returns the 8 essential tools", () => { + it("AGENTMEMORY_TOOLS=core returns the non-LLM essentials", () => { process.env["AGENTMEMORY_TOOLS"] = "core"; const names = new Set(getVisibleTools().map((t) => t.name)); - expect(names.size).toBe(8); + expect(names.size).toBe(7); for (const t of [ "memory_save", "memory_recall", - "memory_consolidate", "memory_smart_search", "memory_sessions", "memory_diagnose", "memory_lesson_save", - "memory_reflect", + "memory_lesson_recall", ]) { expect(names.has(t)).toBe(true); } }); + it("AGENTMEMORY_TOOLS=workstation exposes coordination without dead LLM tools", () => { + process.env["AGENTMEMORY_TOOLS"] = "workstation"; + const names = new Set(getVisibleTools().map((tool) => tool.name)); + expect(names).toEqual(WORKSTATION_TOOLS); + expect(names.has("memory_action_create")).toBe(true); + expect(names.has("memory_lease")).toBe(true); + expect(names.has("memory_signal_send")).toBe(true); + expect(names.has("memory_consolidate")).toBe(false); + expect(names.has("memory_reflect")).toBe(false); + }); + + it("supports custom allowlists and explicit disabled tools", () => { + process.env["AGENTMEMORY_TOOLS"] = "memory_recall,memory_sessions,memory_reflect"; + process.env["AGENTMEMORY_DISABLED_TOOLS"] = "memory_sessions"; + process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"] = "true"; + expect(getVisibleTools().map((tool) => tool.name)).toEqual(["memory_recall"]); + delete process.env["AGENTMEMORY_DISABLED_TOOLS"]; + delete process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"]; + }); + it("plugin .mcp.json provides default env interpolation so CC parse never fails (#510)", () => { const raw = readFileSync("plugin/.mcp.json", "utf-8"); const cfg = JSON.parse(raw) as { diff --git a/test/observe-implicit-session.test.ts b/test/observe-implicit-session.test.ts index b0272bc778..515d353f8d 100644 --- a/test/observe-implicit-session.test.ts +++ b/test/observe-implicit-session.test.ts @@ -108,7 +108,7 @@ describe("observe implicit session create (#638)", () => { expect(sessionScope?.get("ses_no_project")).toBeUndefined(); }); - it("does not overwrite an existing session when one already exists", async () => { + it("refreshes canonical context without replacing existing session history", async () => { const { registerObserveFunction } = await import("../src/functions/observe.js"); const sdk = mockSdk(); const kv = mockKV(); @@ -128,14 +128,24 @@ describe("observe implicit session create (#638)", () => { sessionId: "ses_existing", project: "/different/project", cwd: "/different/cwd", + repoRoot: "/different/project", + scopeType: "repo", + worktree: "/different/worktree", + branch: "feature/context", + taskSlug: "context-refresh", hookType: "post_tool_use", timestamp: new Date().toISOString(), data: { tool_name: "Read" }, }); const session = kv.store.get("mem:sessions")!.get("ses_existing") as Record; - // Original project + firstPrompt preserved - expect(session.project).toBe("/orig/project"); + expect(session.project).toBe("/different/project"); + expect(session.cwd).toBe("/different/cwd"); + expect(session.repoRoot).toBe("/different/project"); + expect(session.worktree).toBe("/different/worktree"); + expect(session.branch).toBe("feature/context"); + expect(session.taskSlug).toBe("context-refresh"); + expect(session.projectAliases).toEqual(["/orig/project"]); expect(session.firstPrompt).toBe("original first prompt"); // Counter bumped, updatedAt refreshed expect(session.observationCount).toBe(8); diff --git a/test/session-context.test.ts b/test/session-context.test.ts new file mode 100644 index 0000000000..79a8dae1a4 --- /dev/null +++ b/test/session-context.test.ts @@ -0,0 +1,112 @@ +import { describe, expect, it } from "vitest"; +import { registerSessionContextFunction } from "../src/functions/session-context.js"; + +function mockKV() { + const store = new Map>(); + return { + store, + get: async (scope: string, key: string): Promise => + (store.get(scope)?.get(key) as T) ?? null, + set: async (scope: string, key: string, value: T): Promise => { + if (!store.has(scope)) store.set(scope, new Map()); + store.get(scope)!.set(key, value); + return value; + }, + update: async (scope: string, key: string, updates: Array<{ path: string; value: unknown }>) => { + const value = (store.get(scope)?.get(key) as Record) ?? {}; + for (const update of updates) value[update.path] = update.value; + if (!store.has(scope)) store.set(scope, new Map()); + store.get(scope)!.set(key, value); + }, + list: async (scope: string): Promise => + Array.from(store.get(scope)?.values() ?? []) as T[], + }; +} + +function mockSdk() { + const handlers = new Map(); + return { + handlers, + registerFunction: (id: string, handler: Function) => handlers.set(id, handler), + trigger: async (input: { function_id: string; payload: unknown }) => { + const handler = handlers.get(input.function_id); + if (!handler) throw new Error(`missing handler ${input.function_id}`); + return handler(input.payload); + }, + }; +} + +describe("session context updates", () => { + it("updates context, keeps the old project as an alias, and writes an audit row", async () => { + const kv = mockKV(); + const sdk = mockSdk(); + registerSessionContextFunction(sdk as never, kv as never); + await kv.set("mem:sessions", "ses_1", { + id: "ses_1", + project: "/legacy/path", + cwd: "/legacy/path", + startedAt: "2026-01-01T00:00:00Z", + status: "active", + observationCount: 2, + }); + + const result = await sdk.trigger({ + function_id: "mem::session-context-update", + payload: { + sessionId: "ses_1", + project: "canonical-project", + cwd: "/repo/worktree", + repoRoot: "/repo/main", + worktree: "/repo/worktree", + branch: "feat/context", + taskSlug: "context-v1", + }, + }) as { success: boolean; changed: string[]; context: Record }; + + expect(result.success).toBe(true); + expect(result.changed).toContain("project"); + expect(result.context).toMatchObject({ + project: "canonical-project", + cwd: "/repo/worktree", + repoRoot: "/repo/main", + worktree: "/repo/worktree", + branch: "feat/context", + taskSlug: "context-v1", + projectAliases: ["/legacy/path"], + }); + expect((await kv.list("mem:audit"))).toHaveLength(1); + }); + + it("is idempotent when context is unchanged", async () => { + const kv = mockKV(); + const sdk = mockSdk(); + registerSessionContextFunction(sdk as never, kv as never); + await kv.set("mem:sessions", "ses_1", { + id: "ses_1", + project: "canonical-project", + cwd: "/repo", + startedAt: "2026-01-01T00:00:00Z", + status: "active", + observationCount: 0, + }); + + const result = await sdk.trigger({ + function_id: "mem::session-context-update", + payload: { sessionId: "ses_1", project: "canonical-project", cwd: "/repo" }, + }) as { success: boolean; changed: string[] }; + + expect(result).toMatchObject({ success: true, changed: [] }); + expect((await kv.list("mem:audit"))).toHaveLength(0); + }); + + it("returns a typed miss instead of creating a malformed session", async () => { + const kv = mockKV(); + const sdk = mockSdk(); + registerSessionContextFunction(sdk as never, kv as never); + const result = await sdk.trigger({ + function_id: "mem::session-context-update", + payload: { sessionId: "missing", project: "canonical-project" }, + }) as { success: boolean; error: string }; + expect(result).toEqual({ success: false, error: "session not found", sessionId: "missing" }); + }); +}); diff --git a/test/session-list.test.ts b/test/session-list.test.ts new file mode 100644 index 0000000000..5249de06e9 --- /dev/null +++ b/test/session-list.test.ts @@ -0,0 +1,96 @@ +import { describe, expect, it } from "vitest"; +import { selectSessionPage } from "../src/functions/session-list.js"; +import type { Session } from "../src/types.js"; + +function session( + id: string, + project: string, + status: Session["status"], + updatedAt: string, +): Session { + return { + id, + project, + cwd: `/repo/${project}`, + startedAt: updatedAt, + updatedAt, + status, + observationCount: 3, + firstPrompt: `private prompt ${id}`, + summary: `summary ${id}`, + }; +} + +describe("bounded session listing", () => { + const sessions = [ + session("ses_1", "alpha", "completed", "2026-07-01T00:00:00Z"), + session("ses_2", "alpha", "active", "2026-07-03T00:00:00Z"), + session("ses_3", "beta", "active", "2026-07-02T00:00:00Z"), + ]; + sessions[2].projectAliases = ["beta-legacy"]; + + it("sorts newest first and returns an opaque next cursor", () => { + const first = selectSessionPage(sessions, { limit: 2 }); + expect(first.sessions.map((item) => item.id)).toEqual(["ses_2", "ses_3"]); + expect(first.pagination).toMatchObject({ total: 3, hasMore: true }); + expect(first.pagination.malformedExcluded).toBe(0); + expect(first.pagination.nextCursor).toBeTruthy(); + + const second = selectSessionPage(sessions, { + limit: 2, + cursor: first.pagination.nextCursor!, + }); + expect(second.sessions.map((item) => item.id)).toEqual(["ses_1"]); + expect(second.pagination.hasMore).toBe(false); + }); + + it("filters by canonical project, recorded alias, status, and since", () => { + expect(selectSessionPage(sessions, { project: "alpha" }).pagination.total).toBe(2); + expect(selectSessionPage(sessions, { project: "beta-legacy" }).sessions[0].id).toBe("ses_3"); + expect(selectSessionPage(sessions, { status: "completed" }).sessions[0].id).toBe("ses_1"); + expect( + selectSessionPage(sessions, { since: "2026-07-02T12:00:00Z" }).sessions.map((item) => item.id), + ).toEqual(["ses_2"]); + }); + + it("omits prompts in compact and full output unless explicitly requested", () => { + const compact = selectSessionPage(sessions, { limit: 1, format: "compact" }).sessions[0]; + expect(compact).not.toHaveProperty("firstPrompt"); + expect(compact).not.toHaveProperty("summary"); + + const full = selectSessionPage(sessions, { limit: 1, format: "full" }).sessions[0]; + expect(full).not.toHaveProperty("firstPrompt"); + expect(full).toHaveProperty("summary"); + + const withPrompt = selectSessionPage(sessions, { + limit: 1, + format: "full", + includePrompt: true, + }).sessions[0]; + expect(withPrompt.firstPrompt).toContain("private prompt"); + }); + + it("does not trust malformed projectAliases values", () => { + const badAliases = { ...sessions[0], projectAliases: { alpha: true } } as unknown as Session; + expect(selectSessionPage([badAliases], { project: "missing" }).pagination.total).toBe(0); + }); + + it("rejects invalid cursors, statuses, formats, and timestamps", () => { + expect(() => selectSessionPage(sessions, { cursor: "not-a-cursor" })).toThrow("cursor"); + expect(() => selectSessionPage(sessions, { status: "stuck" as never })).toThrow("status"); + expect(() => selectSessionPage(sessions, { format: "huge" as never })).toThrow("format"); + expect(() => selectSessionPage(sessions, { since: "yesterday-ish" })).toThrow("since"); + }); + + it("excludes malformed legacy sessions by default and labels them on request", () => { + const malformed = { project: "legacy", status: "active" } as Session; + const safe = selectSessionPage([...sessions, malformed]); + expect(safe.pagination.malformedExcluded).toBe(1); + expect(safe.pagination.total).toBe(3); + + const included = selectSessionPage([...sessions, malformed], { includeMalformed: true }); + expect(included.pagination.malformedExcluded).toBe(0); + expect(included.pagination.total).toBe(4); + expect(included.sessions.find((item) => item.project === "legacy")?.issues).toContain("missing_id"); + }); +}); diff --git a/test/tool-count-consistency.test.ts b/test/tool-count-consistency.test.ts index 6e845df064..433de175e3 100644 --- a/test/tool-count-consistency.test.ts +++ b/test/tool-count-consistency.test.ts @@ -24,7 +24,7 @@ describe("Tool count consistency", () => { const cli = readText("src/cli.ts"); expect(cli).toContain("const ALL_TOOLS_COUNT = getAllTools().length;"); expect(cli).toContain( - "(default: all = ${ALL_TOOLS_COUNT} tools; core = ${CORE_TOOLS_COUNT} essentials)", + "Tool visibility (default: all = ${ALL_TOOLS_COUNT}; core = ${CORE_TOOLS_COUNT}; workstation = curated coordination set)", ); expect(cli).not.toMatch(/all\s*=\s*51 tools/); }); From ea0776081bf393f2b5b3bc8eaf6b0d53f0de9e43 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Thu, 9 Jul 2026 23:32:33 -0400 Subject: [PATCH 02/43] fix: preserve session activity time during context migration --- src/functions/session-context.ts | 8 ++++++-- src/functions/session-list.ts | 1 + src/types.ts | 1 + test/session-context.test.ts | 3 +++ 4 files changed, 11 insertions(+), 2 deletions(-) diff --git a/src/functions/session-context.ts b/src/functions/session-context.ts index 10dcf51f42..cf7ff979a0 100644 --- a/src/functions/session-context.ts +++ b/src/functions/session-context.ts @@ -38,6 +38,7 @@ function contextView(session: Session) { taskSlug: session.taskSlug, projectAliases: session.projectAliases, updatedAt: session.updatedAt, + contextUpdatedAt: session.contextUpdatedAt, }; } @@ -73,8 +74,11 @@ export function registerSessionContextFunction(sdk: ISdk, kv: StateKV): void { return { success: true, changed: [], context: contextView(session) }; } - const updatedAt = new Date().toISOString(); - updates.push({ type: "set", path: "updatedAt", value: updatedAt }); + updates.push({ + type: "set", + path: "contextUpdatedAt", + value: new Date().toISOString(), + }); await kv.update(KV.sessions, data.sessionId, updates); await recordAudit( kv, diff --git a/src/functions/session-list.ts b/src/functions/session-list.ts index d3db68e351..c45ba594f3 100644 --- a/src/functions/session-list.ts +++ b/src/functions/session-list.ts @@ -73,6 +73,7 @@ function compactSession(session: Session): SessionPage["sessions"][number] { observationCount: session.observationCount, startedAt: session.startedAt, updatedAt: session.updatedAt, + contextUpdatedAt: session.contextUpdatedAt, endedAt: session.endedAt, agentId: session.agentId, repoRoot: session.repoRoot, diff --git a/src/types.ts b/src/types.ts index 888e8ef8c4..e76f190c22 100644 --- a/src/types.ts +++ b/src/types.ts @@ -10,6 +10,7 @@ export interface Session { projectAliases?: string[]; startedAt: string; updatedAt?: string; + contextUpdatedAt?: string; endedAt?: string; status: "active" | "completed" | "abandoned"; observationCount: number; diff --git a/test/session-context.test.ts b/test/session-context.test.ts index 79a8dae1a4..40f1a7ca26 100644 --- a/test/session-context.test.ts +++ b/test/session-context.test.ts @@ -46,6 +46,7 @@ describe("session context updates", () => { project: "/legacy/path", cwd: "/legacy/path", startedAt: "2026-01-01T00:00:00Z", + updatedAt: "2026-01-02T00:00:00Z", status: "active", observationCount: 2, }); @@ -73,7 +74,9 @@ describe("session context updates", () => { branch: "feat/context", taskSlug: "context-v1", projectAliases: ["/legacy/path"], + updatedAt: "2026-01-02T00:00:00Z", }); + expect(result.context.contextUpdatedAt).toEqual(expect.any(String)); expect((await kv.list("mem:audit"))).toHaveLength(1); }); From 029ca6d7964fd4ed4dbc8ead0c7c49d97e857bf3 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Thu, 9 Jul 2026 23:55:09 -0400 Subject: [PATCH 03/43] feat: expose deployment source revision in health --- src/triggers/api.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 82fbb02deb..fcf62946db 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -281,6 +281,7 @@ export function registerApiTriggers( service: "agentmemory", version: VERSION, buildId: process.env["AGENTMEMORY_BUILD_ID"] || null, + sourceRevision: process.env["AGENTMEMORY_SOURCE_REVISION"] || null, toolProfile: process.env["AGENTMEMORY_TOOLS"] || "all", llmToolsDisabled: process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"] === "true", health: health || null, From bbdb80215ced36c23f2d2c19dc55484b860ac493 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Fri, 10 Jul 2026 00:59:52 -0400 Subject: [PATCH 04/43] fix: keep viewer stream updates transient --- src/functions/observe.ts | 6 ++++-- test/auto-compress.test.ts | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/src/functions/observe.ts b/src/functions/observe.ts index 43f7d26efd..816de9d9ba 100644 --- a/src/functions/observe.ts +++ b/src/functions/observe.ts @@ -359,17 +359,19 @@ export function registerObserveFunction( }, }); await sdk.trigger({ - function_id: "stream::set", + function_id: "stream::send", payload: { stream_name: STREAM.name, group_id: STREAM.viewerGroup, - item_id: obsId, + id: `compressed-${obsId}`, + type: "compressed_observation", data: { type: "compressed", observation: synthetic, sessionId: payload.sessionId, }, }, + action: TriggerAction.Void(), }); } diff --git a/test/auto-compress.test.ts b/test/auto-compress.test.ts index fdcced8fe3..9afe57431a 100644 --- a/test/auto-compress.test.ts +++ b/test/auto-compress.test.ts @@ -131,6 +131,39 @@ describe("mem::observe auto-compress gate (#138)", () => { expect(obs.confidence).toBe(0.3); }); + it("default: keeps viewer updates transient while retaining the session stream", async () => { + const { registerObserveFunction } = await import( + "../src/functions/observe.js" + ); + const sdk = mockSdk(); + const kv = mockKV(); + registerObserveFunction(sdk as never, kv as never); + + await sdk.trigger("mem::observe", validPayload()); + + const callsForGroup = (groupId: string) => + sdk.triggered.filter( + (call) => + (call.data as { group_id?: string } | undefined)?.group_id === groupId, + ); + const viewerCalls = callsForGroup("viewer"); + expect(viewerCalls.map((call) => call.id)).toEqual([ + "stream::send", + "stream::send", + ]); + expect( + viewerCalls.map( + (call) => (call.data as { type?: string } | undefined)?.type, + ), + ).toEqual(["raw_observation", "compressed_observation"]); + + const sessionCalls = callsForGroup("ses_test"); + expect(sessionCalls.map((call) => call.id)).toEqual([ + "stream::set", + "stream::set", + ]); + }); + it("AGENTMEMORY_AUTO_COMPRESS=true: fires mem::compress exactly once", async () => { process.env["AGENTMEMORY_AUTO_COMPRESS"] = "true"; const { registerObserveFunction } = await import( From d4a32ce975fa06a74fe69257bbfb7e5f8182e719 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Fri, 10 Jul 2026 07:41:53 -0400 Subject: [PATCH 05/43] fix action list pagination --- src/functions/actions.ts | 27 ++++++++++-- src/triggers/api.ts | 23 +++++++++++ test/actions-api-pagination.test.ts | 64 +++++++++++++++++++++++++++++ test/actions.test.ts | 54 +++++++++++++++++++++++- 4 files changed, 163 insertions(+), 5 deletions(-) create mode 100644 test/actions-api-pagination.test.ts diff --git a/src/functions/actions.ts b/src/functions/actions.ts index 12d12df39b..2cc3d79af7 100644 --- a/src/functions/actions.ts +++ b/src/functions/actions.ts @@ -208,6 +208,7 @@ export function registerActionsFunction(sdk: ISdk, kv: StateKV): void { parentId?: string; tags?: string[]; limit?: number; + offset?: number; }) => { let actions = await kv.list(KV.actions); @@ -227,12 +228,30 @@ export function registerActionsFunction(sdk: ISdk, kv: StateKV): void { } actions.sort( - (a, b) => - new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(), + (a, b) => { + const updatedAtDifference = + new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(); + return updatedAtDifference || a.id.localeCompare(b.id); + }, ); - const limit = data.limit || 50; - return { success: true, actions: actions.slice(0, limit) }; + const total = actions.length; + const limit = + Number.isInteger(data.limit) && data.limit! > 0 + ? Math.min(data.limit!, 500) + : 50; + const offset = + Number.isInteger(data.offset) && data.offset! >= 0 ? data.offset! : 0; + const page = actions.slice(offset, offset + limit); + + return { + success: true, + actions: page, + total, + limit, + offset, + hasMore: offset + page.length < total, + }; }, ); diff --git a/src/triggers/api.ts b/src/triggers/api.ts index fcf62946db..21fab951ff 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -151,6 +151,13 @@ function parseOptionalPositiveInt(value: unknown): number | undefined | null { return parsed; } +function parseOptionalNonNegativeInt(value: unknown): number | undefined | null { + const parsed = parseOptionalFiniteNumber(value); + if (parsed === undefined || parsed === null) return parsed; + if (!Number.isInteger(parsed) || parsed < 0) return null; + return parsed; +} + export function registerApiTriggers( sdk: ISdk, kv: StateKV, @@ -2371,10 +2378,26 @@ export function registerApiTriggers( async (req: ApiRequest): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; + const limit = parseOptionalPositiveInt(req.query_params?.["limit"]); + if (limit === null) { + return { + status_code: 400, + body: { error: "limit must be a positive integer" }, + }; + } + const offset = parseOptionalNonNegativeInt(req.query_params?.["offset"]); + if (offset === null) { + return { + status_code: 400, + body: { error: "offset must be a non-negative integer" }, + }; + } const result = await sdk.trigger({ function_id: "mem::action-list", payload: { status: req.query_params?.["status"], project: req.query_params?.["project"], parentId: req.query_params?.["parentId"], + limit, + offset, } }); return { status_code: 200, body: result }; }, diff --git a/test/actions-api-pagination.test.ts b/test/actions-api-pagination.test.ts new file mode 100644 index 0000000000..f0626cace0 --- /dev/null +++ b/test/actions-api-pagination.test.ts @@ -0,0 +1,64 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { registerActionsFunction } from "../src/functions/actions.js"; +import { registerApiTriggers } from "../src/triggers/api.js"; +import type { Action } from "../src/types.js"; +import { mockKV, mockSdk } from "./helpers/mocks.js"; + +describe("Actions REST pagination", () => { + let sdk: ReturnType; + let kv: ReturnType; + + beforeEach(async () => { + sdk = mockSdk(); + kv = mockKV(); + registerActionsFunction(sdk as never, kv as never); + registerApiTriggers(sdk as never, kv as never); + + for (let index = 0; index < 75; index += 1) { + await sdk.trigger("mem::action-create", { title: `Task ${index}` }); + } + }); + + it("forwards limit and offset and returns page metadata", async () => { + const response = (await sdk.trigger("api::action-list", { + headers: {}, + query_params: { limit: "50", offset: "50" }, + })) as { + status_code: number; + body: { + actions: Action[]; + total: number; + limit: number; + offset: number; + hasMore: boolean; + }; + }; + + expect(response.status_code).toBe(200); + expect(response.body.actions).toHaveLength(25); + expect(response.body.total).toBe(75); + expect(response.body.limit).toBe(50); + expect(response.body.offset).toBe(50); + expect(response.body.hasMore).toBe(false); + }); + + it.each([ + [{ limit: "0" }, "limit must be a positive integer"], + [{ limit: "not-a-number" }, "limit must be a positive integer"], + [{ offset: "-1" }, "offset must be a non-negative integer"], + [{ offset: "1.5" }, "offset must be a non-negative integer"], + ])("rejects invalid pagination parameters", async (queryParams, error) => { + const response = (await sdk.trigger("api::action-list", { + headers: {}, + query_params: queryParams, + })) as { status_code: number; body: { error: string } }; + + expect(response.status_code).toBe(400); + expect(response.body.error).toBe(error); + }); +}); diff --git a/test/actions.test.ts b/test/actions.test.ts index 156ba795db..24715b3d05 100644 --- a/test/actions.test.ts +++ b/test/actions.test.ts @@ -386,10 +386,62 @@ describe("Actions Functions", () => { it("respects limit", async () => { const result = (await sdk.trigger("mem::action-list", { limit: 2, - })) as { success: boolean; actions: Action[] }; + })) as { + success: boolean; + actions: Action[]; + total: number; + limit: number; + offset: number; + hasMore: boolean; + }; expect(result.success).toBe(true); expect(result.actions.length).toBe(2); + expect(result.total).toBe(3); + expect(result.limit).toBe(2); + expect(result.offset).toBe(0); + expect(result.hasMore).toBe(true); + }); + + it("returns complete, non-overlapping pages beyond the legacy 50-action cap", async () => { + for (let index = 0; index < 72; index += 1) { + await sdk.trigger("mem::action-create", { + title: `Bulk task ${index}`, + }); + } + + const first = (await sdk.trigger("mem::action-list", { + limit: 50, + })) as { + actions: Action[]; + total: number; + hasMore: boolean; + }; + const second = (await sdk.trigger("mem::action-list", { + limit: 50, + offset: 50, + })) as { + actions: Action[]; + total: number; + hasMore: boolean; + }; + + expect(first.total).toBe(75); + expect(second.total).toBe(75); + expect(first.actions).toHaveLength(50); + expect(second.actions).toHaveLength(25); + expect(first.hasMore).toBe(true); + expect(second.hasMore).toBe(false); + expect(new Set([...first.actions, ...second.actions].map((a) => a.id)).size).toBe(75); + }); + + it("clamps oversized pages to 500 actions", async () => { + const result = (await sdk.trigger("mem::action-list", { + limit: 100_000, + })) as { limit: number; offset: number }; + + expect(result.limit).toBe(500); + expect(result.offset).toBe(0); }); }); From 2a443c664f9eaa6200b84c746c435628d10e1fff Mon Sep 17 00:00:00 2001 From: wrightpt Date: Fri, 10 Jul 2026 12:19:13 -0400 Subject: [PATCH 06/43] chore add AgentMemory project scope --- .agentmemory/project.json | 12 ++++++++++++ test/project-manifest.test.ts | 17 +++++++++++++++++ 2 files changed, 29 insertions(+) create mode 100644 .agentmemory/project.json create mode 100644 test/project-manifest.test.ts diff --git a/.agentmemory/project.json b/.agentmemory/project.json new file mode 100644 index 0000000000..8f2a70752a --- /dev/null +++ b/.agentmemory/project.json @@ -0,0 +1,12 @@ +{ + "project_id": "agentmemory", + "scope_type": "repo", + "repo_root": "/home/cp/repos/agent-infra/agentmemory", + "memory_policy": "default-isolated", + "related_projects": [ + "workstation", + "agent-workspace-config", + "agent-skills", + "repo-brain" + ] +} diff --git a/test/project-manifest.test.ts b/test/project-manifest.test.ts new file mode 100644 index 0000000000..40b1fac054 --- /dev/null +++ b/test/project-manifest.test.ts @@ -0,0 +1,17 @@ +import { readFile } from "node:fs/promises"; +import { describe, expect, it } from "vitest"; + +describe("AgentMemory project manifest", () => { + it("keeps canonical cross-agent scope stable in every worktree", async () => { + const manifest = JSON.parse( + await readFile(new URL("../.agentmemory/project.json", import.meta.url), "utf8"), + ) as Record; + + expect(manifest).toMatchObject({ + project_id: "agentmemory", + scope_type: "repo", + repo_root: "/home/cp/repos/agent-infra/agentmemory", + memory_policy: "default-isolated", + }); + }); +}); From 8e5ad1f14f6a7b2341ab75dd1cc257376ffacc23 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Mon, 13 Jul 2026 19:59:39 -0400 Subject: [PATCH 07/43] Decouple hook capture from synchronous observe --- AGENTS.md | 2 +- README.md | 5 +- plugin/scripts/notification.mjs | 2 +- plugin/scripts/post-tool-failure.mjs | 2 +- plugin/scripts/post-tool-use.mjs | 2 +- plugin/scripts/prompt-submit.mjs | 2 +- plugin/scripts/subagent-start.mjs | 2 +- plugin/scripts/subagent-stop.mjs | 2 +- plugin/scripts/task-completed.mjs | 2 +- plugin/skills/agentmemory-config/REFERENCE.md | 13 ++- .../skills/agentmemory-mcp-tools/REFERENCE.md | 10 +- .../skills/agentmemory-rest-api/REFERENCE.md | 4 +- src/hooks/notification.ts | 2 +- src/hooks/post-tool-failure.ts | 2 +- src/hooks/post-tool-use.ts | 2 +- src/hooks/prompt-submit.ts | 2 +- src/hooks/subagent-start.ts | 2 +- src/hooks/subagent-stop.ts | 2 +- src/hooks/task-completed.ts | 2 +- src/index.ts | 2 +- src/triggers/api.ts | 96 ++++++++++++++----- test/api-observe-async.test.ts | 82 ++++++++++++++++ test/copilot-plugin.test.ts | 6 +- 23 files changed, 195 insertions(+), 53 deletions(-) create mode 100644 test/api-observe-async.test.ts diff --git a/AGENTS.md b/AGENTS.md index a608ee9c41..1a5beb0ad9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -117,7 +117,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). ## Current Stats (v0.9.27) - 53 MCP tools (`all` by default; 7 safe essentials in `core`; curated coordination in `workstation`) -- 129 REST endpoints +- 130 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 15 skills - 50+ iii functions diff --git a/README.md b/README.md index b0c04619a8..6b9fedc6f9 100644 --- a/README.md +++ b/README.md @@ -1502,7 +1502,7 @@ Create `~/.agentmemory/.env`:

API

-129 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers. +130 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
Key endpoints @@ -1512,7 +1512,8 @@ Create `~/.agentmemory/.env`: | `GET` | `/agentmemory/health` | Health check (always public) | | `POST` | `/agentmemory/session/start` | Start session + get context | | `POST` | `/agentmemory/session/end` | End session | -| `POST` | `/agentmemory/observe` | Capture observation | +| `POST` | `/agentmemory/observe` | Capture observation synchronously | +| `POST` | `/agentmemory/observe/async` | Accept hook observation for asynchronous capture (`202`) | | `POST` | `/agentmemory/smart-search` | Hybrid search | | `POST` | `/agentmemory/context` | Generate context | | `POST` | `/agentmemory/remember` | Save to long-term memory | diff --git a/plugin/scripts/notification.mjs b/plugin/scripts/notification.mjs index bc70d713fc..06dcc9efc1 100755 --- a/plugin/scripts/notification.mjs +++ b/plugin/scripts/notification.mjs @@ -117,7 +117,7 @@ async function main() { const rawSessionId = data.session_id ?? data.sessionId; const sessionId = typeof rawSessionId === "string" && rawSessionId.length > 0 ? rawSessionId : "unknown"; const context = resolveProjectContext(data.cwd); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/plugin/scripts/post-tool-failure.mjs b/plugin/scripts/post-tool-failure.mjs index 45b2f6f7ed..705b1dae59 100755 --- a/plugin/scripts/post-tool-failure.mjs +++ b/plugin/scripts/post-tool-failure.mjs @@ -119,7 +119,7 @@ async function main() { const toolInput = data.tool_input ?? data.toolArgs; const error = data.error ?? data.errorMessage; const context = resolveProjectContext(data.cwd); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/plugin/scripts/post-tool-use.mjs b/plugin/scripts/post-tool-use.mjs index c73037000e..7bc50fb01b 100755 --- a/plugin/scripts/post-tool-use.mjs +++ b/plugin/scripts/post-tool-use.mjs @@ -119,7 +119,7 @@ async function main() { const context = resolveProjectContext(data.cwd); const maxChars = maxCaptureChars(); const { imageData, cleanOutput } = extractImageData(toolOutput(data)); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/plugin/scripts/prompt-submit.mjs b/plugin/scripts/prompt-submit.mjs index b019cc19e2..ca113b71f6 100755 --- a/plugin/scripts/prompt-submit.mjs +++ b/plugin/scripts/prompt-submit.mjs @@ -115,7 +115,7 @@ async function main() { const sessionId = data.session_id || data.sessionId || "unknown"; const context = resolveProjectContext(data.cwd); const promptData = promptCapture(data.prompt ?? data.userPrompt); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/plugin/scripts/subagent-start.mjs b/plugin/scripts/subagent-start.mjs index baa032a192..964317469b 100755 --- a/plugin/scripts/subagent-start.mjs +++ b/plugin/scripts/subagent-start.mjs @@ -117,7 +117,7 @@ async function main() { const agentId = data.agent_id || data.agentName; const agentType = data.agent_type || data.agentDisplayName || data.agentName; const context = resolveProjectContext(data.cwd); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/plugin/scripts/subagent-stop.mjs b/plugin/scripts/subagent-stop.mjs index 082a12b5d7..4ce660abb0 100755 --- a/plugin/scripts/subagent-stop.mjs +++ b/plugin/scripts/subagent-stop.mjs @@ -117,7 +117,7 @@ async function main() { const agentType = data.agent_type || data.agentDisplayName || data.agentName; const lastMsg = typeof data.last_assistant_message === "string" ? data.last_assistant_message.slice(0, 4e3) : ""; const context = resolveProjectContext(data.cwd); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/plugin/scripts/task-completed.mjs b/plugin/scripts/task-completed.mjs index 40c2427c70..aec9a5470b 100755 --- a/plugin/scripts/task-completed.mjs +++ b/plugin/scripts/task-completed.mjs @@ -114,7 +114,7 @@ async function main() { if (isSdkChildContext(data)) return; const sessionId = data.session_id || "unknown"; const context = resolveProjectContext(data.cwd); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md index 08c873a444..ea5f2f0f33 100644 --- a/plugin/skills/agentmemory-config/REFERENCE.md +++ b/plugin/skills/agentmemory-config/REFERENCE.md @@ -3,15 +3,19 @@ Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded. -Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 34 recognized variables: +Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 45 recognized variables: - `AGENTMEMORY_AGENT_SCOPE` - `AGENTMEMORY_ALLOW_AGENT_SDK` - `AGENTMEMORY_AUTO_COMPRESS` +- `AGENTMEMORY_BUILD_ID` +- `AGENTMEMORY_CAPTURE_PROMPTS` - `AGENTMEMORY_COMMIT_SHA` - `AGENTMEMORY_COPILOT_MCP_BLOCK` - `AGENTMEMORY_CWD` - `AGENTMEMORY_DEBUG` +- `AGENTMEMORY_DISABLED_TOOLS` +- `AGENTMEMORY_DISABLE_LLM_TOOLS` - `AGENTMEMORY_DROP_STALE_INDEX` - `AGENTMEMORY_EXPORT_ROOT` - `AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS` @@ -23,16 +27,23 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e - `AGENTMEMORY_IMAGE_STORE_MAX_BYTES` - `AGENTMEMORY_INJECT_CONTEXT` - `AGENTMEMORY_LLM_TIMEOUT_MS` +- `AGENTMEMORY_MAX_PROMPT_CAPTURE_CHARS` +- `AGENTMEMORY_MAX_TOOL_CAPTURE_CHARS` - `AGENTMEMORY_MCP_BLOCK` - `AGENTMEMORY_PROBE_TIMEOUT_MS` - `AGENTMEMORY_PROJECT_NAME` - `AGENTMEMORY_PROVIDER` - `AGENTMEMORY_REFLECT` +- `AGENTMEMORY_REPO_ROOT` +- `AGENTMEMORY_SCOPE_TYPE` - `AGENTMEMORY_SDK_CHILD` - `AGENTMEMORY_SECRET` - `AGENTMEMORY_SESSION_ID` +- `AGENTMEMORY_SKIP_TOOLS` - `AGENTMEMORY_SLOTS` +- `AGENTMEMORY_SOURCE_REVISION` - `AGENTMEMORY_SUPPRESS_COST_WARNING` +- `AGENTMEMORY_TASK_SLUG` - `AGENTMEMORY_TOOLS` - `AGENTMEMORY_URL` - `AGENTMEMORY_USE_DOCKER` diff --git a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md index ebe4bb912b..6f07b67ebf 100644 --- a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md +++ b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md @@ -3,7 +3,7 @@ Generated from `src/mcp/tools-registry.ts`. Do not edit the block below by hand; run `npm run skills:gen` after changing the registry. -agentmemory exposes 53 MCP tools. Seven non-LLM essentials are in the lean core set (`--tools core` or `AGENTMEMORY_TOOLS=core`); the rest load with `--tools all` (default). `AGENTMEMORY_TOOLS=workstation` adds lessons, actions, leases, and signals while omitting LLM-backed tools. +agentmemory exposes 53 MCP tools. 7 are in the lean core set (`--tools core` or `AGENTMEMORY_TOOLS=core`); the rest load with `--tools all` (default). | Tool | Core | Parameters | Purpose | | --- | --- | --- | --- | @@ -15,7 +15,7 @@ agentmemory exposes 53 MCP tools. Seven non-LLM essentials are in the lean core | `memory_commit_lookup` | | `sha`*: string | Look up the agent session(s) that produced a specific git commit, given its SHA. Returns the commit metadata and linked sessions. | | `memory_commits` | | `branch`: string, `repo`: string, `limit`: number | List recent commits linked to agent sessions, optionally filtered by branch or repo. | | `memory_compress_file` | | `filePath`*: string | Compress a markdown file to reduce token usage while preserving headings, URLs, and code blocks. Creates a .original.md backup before writing. | -| `memory_consolidate` | yes | `tier`: string | Run the 4-tier memory consolidation pipeline (working -> episodic -> semantic -> procedural). | +| `memory_consolidate` | | `tier`: string | Run the 4-tier memory consolidation pipeline (working -> episodic -> semantic -> procedural). | | `memory_crystallize` | | `actionIds`*: string, `project`: string, `sessionId`: string | Compress completed action chains into compact crystal digests using LLM summarization. Extracts narrative, key outcomes, files affected, and lessons. | | `memory_diagnose` | yes | `categories`: string | Run health checks across all subsystems (actions, leases, sentinels, sketches, signals, sessions, memories, mesh). Identifies stuck, orphaned, and inconsistent state. | | `memory_export` | | none | Export all memory data as JSON. | @@ -28,7 +28,7 @@ agentmemory exposes 53 MCP tools. Seven non-LLM essentials are in the lean core | `memory_heal` | | `categories`: string, `dryRun`: string | Auto-fix all fixable issues found by diagnostics. Unblocks stuck actions, expires stale leases, cleans up orphaned data. | | `memory_insight_list` | | `project`: string, `minConfidence`: number, `limit`: number | List synthesized insights, higher-order observations derived from patterns across memories, lessons, and crystals. | | `memory_lease` | | `actionId`*: string, `agentId`*: string, `operation`*: string, `result`: string, `ttlMs`: number | Acquire, release, or renew an exclusive lease on an action. Prevents multiple agents from working on the same thing. | -| `memory_lesson_recall` | | `query`*: string, `project`: string, `minConfidence`: number, `limit`: number | Search lessons by query. Returns lessons sorted by confidence and recency. Use to check what the agent has learned before making decisions. | +| `memory_lesson_recall` | yes | `query`*: string, `project`: string, `minConfidence`: number, `limit`: number | Search lessons by query. Returns lessons sorted by confidence and recency. Use to check what the agent has learned before making decisions. | | `memory_lesson_save` | yes | `content`*: string, `context`: string, `confidence`: number, `project`: string, `tags`: string | Save a lesson learned from this session. Lessons have confidence scores that strengthen when reinforced and decay when not used. Duplicate content auto-strengthens the existing lesson. | | `memory_mesh_sync` | | `peerId`: string, `direction`: string | Sync memories and actions with peer agentmemory instances for multi-agent collaboration. | | `memory_next` | | `project`: string, `agentId`: string | Get the single most important next action to work on. Combines dependency resolution, priority, and recency into a score. | @@ -36,13 +36,13 @@ agentmemory exposes 53 MCP tools. Seven non-LLM essentials are in the lean core | `memory_patterns` | | `project`: string | Detect recurring patterns across sessions. | | `memory_profile` | | `project`*: string, `refresh`: string | User/project profile with top concepts and file patterns. | | `memory_recall` | yes | `query`*: string, `limit`: number, `format`: string, `token_budget`: number | Search past session observations for relevant context. Use when you need to recall what happened in previous sessions, find past decisions, or look up how a file was modified before. | -| `memory_reflect` | yes | `project`: string, `maxClusters`: number | Traverse the knowledge graph, group related memories by concept clusters, and synthesize higher-order insights via LLM. Returns new and reinforced insights. | +| `memory_reflect` | | `project`: string, `maxClusters`: number | Traverse the knowledge graph, group related memories by concept clusters, and synthesize higher-order insights via LLM. Returns new and reinforced insights. | | `memory_relations` | | `memoryId`*: string, `maxHops`: number, `minConfidence`: number | Query the memory relationship graph. | | `memory_routine_run` | | `routineId`*: string, `project`: string, `initiatedBy`: string | Instantiate a frozen workflow routine, creating actions for each step with proper dependencies. | | `memory_save` | yes | `content`*: string, `type`: string, `concepts`: string, `files`: string, `project`: string | Explicitly save an important insight, decision, or pattern to long-term memory. | | `memory_sentinel_create` | | `name`*: string, `type`*: string, `config`: string, `linkedActionIds`: string, `expiresInMs`: number | Create an event-driven sentinel that watches for conditions (webhook, timer, threshold, pattern, approval) and auto-unblocks gated actions when triggered. | | `memory_sentinel_trigger` | | `sentinelId`*: string, `result`: string | Externally fire a sentinel, providing an optional result payload. Unblocks any gated actions. | -| `memory_sessions` | yes | none | List recent sessions with their status and observation counts. | +| `memory_sessions` | yes | `limit`: number, `cursor`: string, `project`: string, `status`: string, `since`: string, `format`: string, `includePrompt`: boolean, `includeMalformed`: boolean | List recent sessions with bounded pagination. Compact output omits prompts by default. | | `memory_signal_read` | | `agentId`*: string, `unreadOnly`: string, `threadId`: string, `limit`: number | Read messages for an agent. Marks delivered messages as read. | | `memory_signal_send` | | `from`*: string, `to`: string, `content`*: string, `type`: string, `replyTo`: string | Send a message to another agent or broadcast. Supports threading, typed messages, and TTL expiration. | | `memory_sketch_create` | | `title`*: string, `description`: string, `expiresInMs`: number, `project`: string | Create an ephemeral action graph for exploratory work. Auto-expires after TTL. Can be promoted to permanent actions or discarded. | diff --git a/plugin/skills/agentmemory-rest-api/REFERENCE.md b/plugin/skills/agentmemory-rest-api/REFERENCE.md index d36171defe..598a3332ee 100644 --- a/plugin/skills/agentmemory-rest-api/REFERENCE.md +++ b/plugin/skills/agentmemory-rest-api/REFERENCE.md @@ -5,7 +5,7 @@ Generated from `src/triggers/api.ts`. Do not edit the block below by hand; run ` The REST API is the primary surface. All paths are under `http://localhost:3111` (override with `--port`). When `AGENTMEMORY_SECRET` is set, send `Authorization: Bearer $AGENTMEMORY_SECRET`; localhost is otherwise open. -117 registered endpoints: +119 registered endpoints: | Method | Path | | --- | --- | @@ -77,6 +77,7 @@ The REST API is the primary surface. All paths are under `http://localhost:3111` | GET | `/agentmemory/next` | | GET | `/agentmemory/observations` | | POST | `/agentmemory/observe` | +| POST | `/agentmemory/observe/async` | | POST | `/agentmemory/obsidian/export` | | POST | `/agentmemory/patterns` | | GET | `/agentmemory/procedural` | @@ -98,6 +99,7 @@ The REST API is the primary surface. All paths are under `http://localhost:3111` | POST | `/agentmemory/sentinels/trigger` | | GET | `/agentmemory/session/by-commit` | | POST | `/agentmemory/session/commit` | +| POST | `/agentmemory/session/context` | | POST | `/agentmemory/session/end` | | POST | `/agentmemory/session/start` | | GET | `/agentmemory/sessions` | diff --git a/src/hooks/notification.ts b/src/hooks/notification.ts index bf6b062724..57926595be 100644 --- a/src/hooks/notification.ts +++ b/src/hooks/notification.ts @@ -40,7 +40,7 @@ async function main() { : "unknown"; const context = resolveProjectContext(data.cwd as string | undefined); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/src/hooks/post-tool-failure.ts b/src/hooks/post-tool-failure.ts index 65ae09c18c..aa3ce66065 100644 --- a/src/hooks/post-tool-failure.ts +++ b/src/hooks/post-tool-failure.ts @@ -42,7 +42,7 @@ async function main() { const error = data.error ?? data.errorMessage; const context = resolveProjectContext(data.cwd as string | undefined); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/src/hooks/post-tool-use.ts b/src/hooks/post-tool-use.ts index e3696850ef..eac2cd512f 100644 --- a/src/hooks/post-tool-use.ts +++ b/src/hooks/post-tool-use.ts @@ -40,7 +40,7 @@ async function main() { const { imageData, cleanOutput } = extractImageData(toolOutput(data)); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/src/hooks/prompt-submit.ts b/src/hooks/prompt-submit.ts index 2850c78866..69bb83a094 100644 --- a/src/hooks/prompt-submit.ts +++ b/src/hooks/prompt-submit.ts @@ -36,7 +36,7 @@ async function main() { const prompt = data.prompt ?? data.userPrompt; const promptData = promptCapture(prompt); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/src/hooks/subagent-start.ts b/src/hooks/subagent-start.ts index d9f46a56f9..dc73a235b6 100644 --- a/src/hooks/subagent-start.ts +++ b/src/hooks/subagent-start.ts @@ -44,7 +44,7 @@ async function main() { const agentType = data.agent_type || data.agentDisplayName || data.agentName; const context = resolveProjectContext(data.cwd as string | undefined); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/src/hooks/subagent-stop.ts b/src/hooks/subagent-stop.ts index 931b989185..e8059a46b1 100644 --- a/src/hooks/subagent-stop.ts +++ b/src/hooks/subagent-stop.ts @@ -40,7 +40,7 @@ async function main() { : ""; const context = resolveProjectContext(data.cwd as string | undefined); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/src/hooks/task-completed.ts b/src/hooks/task-completed.ts index 63733abd81..facb34f531 100644 --- a/src/hooks/task-completed.ts +++ b/src/hooks/task-completed.ts @@ -34,7 +34,7 @@ async function main() { const sessionId = (data.session_id as string) || "unknown"; const context = resolveProjectContext(data.cwd as string | undefined); - fetch(`${REST_URL}/agentmemory/observe`, { + fetch(`${REST_URL}/agentmemory/observe/async`, { method: "POST", headers: authHeaders(), body: JSON.stringify({ diff --git a/src/index.ts b/src/index.ts index d89fddf7e8..873bbf2dc0 100644 --- a/src/index.ts +++ b/src/index.ts @@ -520,7 +520,7 @@ async function main() { `Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`, ); bootLog( - `REST API: 129 endpoints at http://localhost:${config.restPort}/agentmemory/*`, + `REST API: 130 endpoints at http://localhost:${config.restPort}/agentmemory/*`, ); bootLog( `MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`, diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 21fab951ff..3c93ff6e78 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -132,6 +132,39 @@ function sessionContextFields(body: Record): Partial, +): { payload: HookPayload } | { error: Response } { + const body = (req.body ?? {}) as Record; + const hookType = asNonEmptyString(body.hookType); + const sessionId = asNonEmptyString(body.sessionId); + const project = asNonEmptyString(body.project); + const cwd = asNonEmptyString(body.cwd); + const timestamp = asNonEmptyString(body.timestamp); + if (!hookType || !sessionId || !project || !cwd || !timestamp) { + return { + error: { + status_code: 400, + body: { + error: + "hookType, sessionId, project, cwd, and timestamp are required strings", + }, + }, + }; + } + return { + payload: { + hookType: hookType as HookPayload["hookType"], + sessionId, + project, + cwd, + timestamp, + data: body.data, + ...sessionContextFields(body), + }, + }; +} + function parseOptionalFiniteNumber(value: unknown): number | undefined | null { if (value === undefined || value === null) return undefined; if (typeof value === "number") return Number.isFinite(value) ? value : null; @@ -312,31 +345,12 @@ export function registerApiTriggers( sdk.registerFunction("api::observe", async (req: ApiRequest): Promise => { - const body = (req.body ?? {}) as Record; - const hookType = asNonEmptyString(body.hookType); - const sessionId = asNonEmptyString(body.sessionId); - const project = asNonEmptyString(body.project); - const cwd = asNonEmptyString(body.cwd); - const timestamp = asNonEmptyString(body.timestamp); - if (!hookType || !sessionId || !project || !cwd || !timestamp) { - return { - status_code: 400, - body: { - error: - "hookType, sessionId, project, cwd, and timestamp are required strings", - }, - }; - } - const payload: HookPayload = { - hookType: hookType as HookPayload["hookType"], - sessionId, - project, - cwd, - timestamp, - data: body.data, - ...sessionContextFields(body), - }; - const result = await sdk.trigger({ function_id: "mem::observe", payload }); + const parsed = parseObserveRequest(req); + if ("error" in parsed) return parsed.error; + const result = await sdk.trigger({ + function_id: "mem::observe", + payload: parsed.payload, + }); return { status_code: 201, body: result }; }, ); @@ -350,6 +364,38 @@ export function registerApiTriggers( }, }); + sdk.registerFunction("api::observe::async", + async (req: ApiRequest): Promise => { + const parsed = parseObserveRequest(req); + if ("error" in parsed) return parsed.error; + + // Desktop hooks intentionally have a very small process lifetime. Do not + // couple their HTTP caller to the full persistence/index/stream pipeline: + // if a hook exits while a synchronous invocation is still running, iii + // loses the caller but continues tracking the downstream invocation. + // Void acknowledges dispatch, then lets mem::observe finish under the + // engine's ownership instead of the hook process's lifetime. + await sdk.trigger({ + function_id: "mem::observe", + payload: parsed.payload, + action: TriggerAction.Void(), + }); + return { + status_code: 202, + body: { accepted: true, sessionId: parsed.payload.sessionId }, + }; + }, + ); + sdk.registerTrigger({ + type: "http", + function_id: "api::observe::async", + config: { + api_path: "/agentmemory/observe/async", + http_method: "POST", + middleware_function_ids: ["middleware::api-auth"], + }, + }); + sdk.registerFunction("api::context", async ( req: ApiRequest<{ sessionId: string; project: string; budget?: number }>, diff --git a/test/api-observe-async.test.ts b/test/api-observe-async.test.ts new file mode 100644 index 0000000000..a3ee246064 --- /dev/null +++ b/test/api-observe-async.test.ts @@ -0,0 +1,82 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { registerApiTriggers } from "../src/triggers/api.js"; +import { mockKV, mockSdk } from "./helpers/mocks.js"; + +describe("Observe REST ingestion", () => { + let sdk: ReturnType; + let dispatched: Array<{ + function_id: string; + payload: unknown; + action?: unknown; + }>; + + beforeEach(() => { + sdk = mockSdk(); + dispatched = []; + const invokeRegistered = sdk.trigger.bind(sdk); + sdk.trigger = vi.fn(async (request, data?: unknown) => { + if ( + typeof request !== "string" && + request.function_id === "mem::observe" + ) { + dispatched.push(request); + // Model iii's acknowledgement of a void invocation. The observation + // pipeline itself is deliberately not part of the HTTP response path. + return undefined; + } + return invokeRegistered(request, data); + }) as typeof sdk.trigger; + + registerApiTriggers(sdk as never, mockKV() as never); + }); + + it("acknowledges after dispatching observation work as a void invocation", async () => { + const response = (await sdk.trigger("api::observe::async", { + headers: {}, + body: { + hookType: "post_tool_use", + sessionId: "session-123", + project: "agentmemory", + cwd: "/repo/agentmemory", + timestamp: "2026-07-13T23:00:00Z", + data: { tool_name: "Read" }, + }, + })) as { + status_code: number; + body: { accepted: boolean; sessionId: string }; + }; + + expect(response).toEqual({ + status_code: 202, + body: { accepted: true, sessionId: "session-123" }, + }); + expect(dispatched).toHaveLength(1); + expect(dispatched[0]).toMatchObject({ + function_id: "mem::observe", + action: { type: "void" }, + }); + }); + + it("keeps the original observe endpoint synchronous for API callers", async () => { + const response = (await sdk.trigger("api::observe", { + headers: {}, + body: { + hookType: "prompt_submit", + sessionId: "session-sync", + project: "agentmemory", + cwd: "/repo/agentmemory", + timestamp: "2026-07-13T23:00:00Z", + data: { prompt: "remember this" }, + }, + })) as { status_code: number }; + + expect(response.status_code).toBe(201); + expect(dispatched).toHaveLength(1); + expect(dispatched[0].action).toBeUndefined(); + }); +}); diff --git a/test/copilot-plugin.test.ts b/test/copilot-plugin.test.ts index cd01b2d872..77bcf00b96 100644 --- a/test/copilot-plugin.test.ts +++ b/test/copilot-plugin.test.ts @@ -328,7 +328,7 @@ describe("Copilot hook scripts", () => { userPrompt: "remember this prompt", }); - expect(result.requests[0]?.path).toBe("/agentmemory/observe"); + expect(result.requests[0]?.path).toBe("/agentmemory/observe/async"); expect(result.requests[0]?.body).toMatchObject({ hookType: "prompt_submit", sessionId: "copilot-session", @@ -345,7 +345,7 @@ describe("Copilot hook scripts", () => { errorMessage: "failed", }); - expect(result.requests[0]?.path).toBe("/agentmemory/observe"); + expect(result.requests[0]?.path).toBe("/agentmemory/observe/async"); expect(result.requests[0]?.body).toMatchObject({ hookType: "post_tool_failure", sessionId: "copilot-session", @@ -366,7 +366,7 @@ describe("Copilot hook scripts", () => { message: "Approve edit", }); - expect(result.requests[0]?.path).toBe("/agentmemory/observe"); + expect(result.requests[0]?.path).toBe("/agentmemory/observe/async"); expect(result.requests[0]?.body).toMatchObject({ hookType: "notification", sessionId: "copilot-session", From 909ae07d1ee140486d346ef0cef3374c38b25fca Mon Sep 17 00:00:00 2001 From: wrightpt Date: Mon, 13 Jul 2026 20:35:27 -0400 Subject: [PATCH 08/43] Await asynchronous hook transport acknowledgements --- AGENTS.md | 3 +- README.md | 2 +- plugin/scripts/notification.mjs | 63 +++++++------ plugin/scripts/post-tool-failure.mjs | 62 +++++++------ plugin/scripts/post-tool-use.mjs | 63 +++++++------ plugin/scripts/prompt-submit.mjs | 53 ++++++----- plugin/scripts/subagent-start.mjs | 61 +++++++------ plugin/scripts/subagent-stop.mjs | 62 +++++++------ plugin/scripts/task-completed.mjs | 67 ++++++++------ plugin/skills/agentmemory-config/REFERENCE.md | 3 +- src/hooks/_observe.ts | 38 ++++++++ src/hooks/notification.ts | 38 +++----- src/hooks/post-tool-failure.ts | 50 ++++------- src/hooks/post-tool-use.ts | 40 +++------ src/hooks/prompt-submit.ts | 30 ++----- src/hooks/subagent-start.ts | 42 +++------ src/hooks/subagent-stop.ts | 38 +++----- src/hooks/task-completed.ts | 46 ++++------ test/hook-observation-client.test.ts | 89 +++++++++++++++++++ 19 files changed, 479 insertions(+), 371 deletions(-) create mode 100644 src/hooks/_observe.ts create mode 100644 test/hook-observation-client.test.ts diff --git a/AGENTS.md b/AGENTS.md index 1a5beb0ad9..bec145e63e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -94,7 +94,8 @@ case "memory_your_tool": { Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). They read JSON from stdin, make HTTP calls to the REST API, and exit. There are two patterns depending on whether Claude Code consumes the script's stdout: - **Context-injecting hooks** (`pre-tool-use`, `pre-compact`, `session-start`) write recalled context to stdout for Claude Code to inject. These MUST use `try/catch` with `await fetch(..., { signal: AbortSignal.timeout(N) })` — the script has to wait for the response before exiting, and the timeout is the only bound on hang time. -- **Telemetry-only hooks** (`notification`, `post-tool-failure`, `post-tool-use`, `prompt-submit`, `stop`, `session-end`, `subagent-start`, `subagent-stop`, `task-completed`) write nothing to stdout. These MUST use fire-and-forget `fetch(..., { signal: AbortSignal.timeout(N) }).catch(() => {})` paired with `setTimeout(() => process.exit(0), 500).unref()`. The unawaited fetch dispatches the request; the unref'd `setTimeout` force-exits the process after the request has been flushed to the local daemon's socket buffer (~500ms is enough for single-request hooks; use 1500ms for multi-request hooks like `stop` and `session-end` so all fetches have time to start, especially when `AGENTMEMORY_URL` points to a remote daemon). Without the `setTimeout` Node keeps the event loop alive waiting for any in-flight fetch to settle, which means the hook still blocks Claude Code's next-prompt boundary for up to the AbortSignal duration — exactly the bug fire-and-forget is meant to fix. +- **Observation telemetry hooks** (`notification`, `post-tool-failure`, `post-tool-use`, `prompt-submit`, `subagent-start`, `subagent-stop`, `task-completed`) MUST call and await the shared `submitObservation()` helper. The REST endpoint returns `202` after a void dispatch, so this waits only for the small transport acknowledgement and response body, not persistence/indexing. The helper's bounded timeout defaults to 500ms and failures stay silent. Do not reintroduce unawaited `fetch()` plus hard `process.exit()`: terminating the client before the response lifecycle completes can strand iii invocation bookkeeping. +- **Multi-request telemetry hooks** (`stop`, `session-end`) still use fire-and-forget requests with a 1500ms exit bound because they dispatch several independent lifecycle calls, not only the asynchronous observation endpoint. ## Coding Standards diff --git a/README.md b/README.md index 6b9fedc6f9..963298d2d0 100644 --- a/README.md +++ b/README.md @@ -1513,7 +1513,7 @@ Create `~/.agentmemory/.env`: | `POST` | `/agentmemory/session/start` | Start session + get context | | `POST` | `/agentmemory/session/end` | End session | | `POST` | `/agentmemory/observe` | Capture observation synchronously | -| `POST` | `/agentmemory/observe/async` | Accept hook observation for asynchronous capture (`202`) | +| `POST` | `/agentmemory/observe/async` | Acknowledge hook transport (`202`); capture continues asynchronously | | `POST` | `/agentmemory/smart-search` | Hybrid search | | `POST` | `/agentmemory/context` | Generate context | | `POST` | `/agentmemory/remember` | Save to long-term memory | diff --git a/plugin/scripts/notification.mjs b/plugin/scripts/notification.mjs index 06dcc9efc1..68ae166345 100755 --- a/plugin/scripts/notification.mjs +++ b/plugin/scripts/notification.mjs @@ -89,19 +89,38 @@ function resolveProjectContext(cwd) { }; } //#endregion +//#region src/hooks/_observe.ts +const DEFAULT_ACK_TIMEOUT_MS = 500; +const MAX_ACK_TIMEOUT_MS = 5e3; +function ackTimeoutMs() { + const configured = Number(process.env["AGENTMEMORY_HOOK_ACK_TIMEOUT_MS"] ?? DEFAULT_ACK_TIMEOUT_MS); + if (!Number.isFinite(configured) || configured <= 0) return DEFAULT_ACK_TIMEOUT_MS; + return Math.max(1, Math.min(Math.floor(configured), MAX_ACK_TIMEOUT_MS)); +} +function authHeaders() { + const headers = { "Content-Type": "application/json" }; + const secret = process.env["AGENTMEMORY_SECRET"] || ""; + if (secret) headers["Authorization"] = `Bearer ${secret}`; + return headers; +} +async function submitObservation(payload) { + const restUrl = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; + try { + await (await fetch(`${restUrl}/agentmemory/observe/async`, { + method: "POST", + headers: authHeaders(), + body: JSON.stringify(payload), + signal: AbortSignal.timeout(ackTimeoutMs()) + })).arrayBuffer(); + } catch {} +} +//#endregion //#region src/hooks/notification.ts function isSdkChildContext(payload) { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; if (!payload || typeof payload !== "object") return false; return payload.entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; -function authHeaders() { - const h = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} async function main() { let input = ""; for await (const chunk of process.stdin) input += chunk; @@ -115,25 +134,17 @@ async function main() { const notificationType = data.notification_type ?? data.notificationType; if (notificationType !== "permission_prompt") return; const rawSessionId = data.session_id ?? data.sessionId; - const sessionId = typeof rawSessionId === "string" && rawSessionId.length > 0 ? rawSessionId : "unknown"; - const context = resolveProjectContext(data.cwd); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "notification", - sessionId, - ...context, - timestamp: (/* @__PURE__ */ new Date()).toISOString(), - data: { - notification_type: notificationType, - title: data.title, - message: data.message - } - }), - signal: AbortSignal.timeout(2e3) - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "notification", + sessionId: typeof rawSessionId === "string" && rawSessionId.length > 0 ? rawSessionId : "unknown", + ...resolveProjectContext(data.cwd), + timestamp: (/* @__PURE__ */ new Date()).toISOString(), + data: { + notification_type: notificationType, + title: data.title, + message: data.message + } + }); } main(); //#endregion diff --git a/plugin/scripts/post-tool-failure.mjs b/plugin/scripts/post-tool-failure.mjs index 705b1dae59..d9dbeb7d71 100755 --- a/plugin/scripts/post-tool-failure.mjs +++ b/plugin/scripts/post-tool-failure.mjs @@ -89,19 +89,38 @@ function resolveProjectContext(cwd) { }; } //#endregion +//#region src/hooks/_observe.ts +const DEFAULT_ACK_TIMEOUT_MS = 500; +const MAX_ACK_TIMEOUT_MS = 5e3; +function ackTimeoutMs() { + const configured = Number(process.env["AGENTMEMORY_HOOK_ACK_TIMEOUT_MS"] ?? DEFAULT_ACK_TIMEOUT_MS); + if (!Number.isFinite(configured) || configured <= 0) return DEFAULT_ACK_TIMEOUT_MS; + return Math.max(1, Math.min(Math.floor(configured), MAX_ACK_TIMEOUT_MS)); +} +function authHeaders() { + const headers = { "Content-Type": "application/json" }; + const secret = process.env["AGENTMEMORY_SECRET"] || ""; + if (secret) headers["Authorization"] = `Bearer ${secret}`; + return headers; +} +async function submitObservation(payload) { + const restUrl = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; + try { + await (await fetch(`${restUrl}/agentmemory/observe/async`, { + method: "POST", + headers: authHeaders(), + body: JSON.stringify(payload), + signal: AbortSignal.timeout(ackTimeoutMs()) + })).arrayBuffer(); + } catch {} +} +//#endregion //#region src/hooks/post-tool-failure.ts function isSdkChildContext(payload) { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; if (!payload || typeof payload !== "object") return false; return payload.entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; -function authHeaders() { - const h = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} async function main() { let input = ""; for await (const chunk of process.stdin) input += chunk; @@ -118,24 +137,17 @@ async function main() { if (typeof toolName === "string" && (toolName.toLowerCase().startsWith("mcp__agentmemory__") || toolName.toLowerCase().startsWith("memory_"))) return; const toolInput = data.tool_input ?? data.toolArgs; const error = data.error ?? data.errorMessage; - const context = resolveProjectContext(data.cwd); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "post_tool_failure", - sessionId, - ...context, - timestamp: (/* @__PURE__ */ new Date()).toISOString(), - data: { - tool_name: toolName, - tool_input: typeof toolInput === "string" ? toolInput.slice(0, 4e3) : JSON.stringify(toolInput ?? "").slice(0, 4e3), - error: typeof error === "string" ? error.slice(0, 4e3) : JSON.stringify(error ?? "").slice(0, 4e3) - } - }), - signal: AbortSignal.timeout(3e3) - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "post_tool_failure", + sessionId, + ...resolveProjectContext(data.cwd), + timestamp: (/* @__PURE__ */ new Date()).toISOString(), + data: { + tool_name: toolName, + tool_input: typeof toolInput === "string" ? toolInput.slice(0, 4e3) : JSON.stringify(toolInput ?? "").slice(0, 4e3), + error: typeof error === "string" ? error.slice(0, 4e3) : JSON.stringify(error ?? "").slice(0, 4e3) + } + }); } main(); //#endregion diff --git a/plugin/scripts/post-tool-use.mjs b/plugin/scripts/post-tool-use.mjs index 7bc50fb01b..12538c2aa8 100755 --- a/plugin/scripts/post-tool-use.mjs +++ b/plugin/scripts/post-tool-use.mjs @@ -89,19 +89,38 @@ function resolveProjectContext(cwd) { }; } //#endregion +//#region src/hooks/_observe.ts +const DEFAULT_ACK_TIMEOUT_MS = 500; +const MAX_ACK_TIMEOUT_MS = 5e3; +function ackTimeoutMs() { + const configured = Number(process.env["AGENTMEMORY_HOOK_ACK_TIMEOUT_MS"] ?? DEFAULT_ACK_TIMEOUT_MS); + if (!Number.isFinite(configured) || configured <= 0) return DEFAULT_ACK_TIMEOUT_MS; + return Math.max(1, Math.min(Math.floor(configured), MAX_ACK_TIMEOUT_MS)); +} +function authHeaders() { + const headers = { "Content-Type": "application/json" }; + const secret = process.env["AGENTMEMORY_SECRET"] || ""; + if (secret) headers["Authorization"] = `Bearer ${secret}`; + return headers; +} +async function submitObservation(payload) { + const restUrl = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; + try { + await (await fetch(`${restUrl}/agentmemory/observe/async`, { + method: "POST", + headers: authHeaders(), + body: JSON.stringify(payload), + signal: AbortSignal.timeout(ackTimeoutMs()) + })).arrayBuffer(); + } catch {} +} +//#endregion //#region src/hooks/post-tool-use.ts function isSdkChildContext(payload) { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; if (!payload || typeof payload !== "object") return false; return payload.entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; -function authHeaders() { - const h = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} async function main() { let input = ""; for await (const chunk of process.stdin) input += chunk; @@ -119,24 +138,18 @@ async function main() { const context = resolveProjectContext(data.cwd); const maxChars = maxCaptureChars(); const { imageData, cleanOutput } = extractImageData(toolOutput(data)); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "post_tool_use", - sessionId, - ...context, - timestamp: (/* @__PURE__ */ new Date()).toISOString(), - data: { - tool_name: toolName, - tool_input: truncate(toolInput, maxChars), - tool_output: truncate(cleanOutput, maxChars), - ...imageData ? { image_data: imageData } : {} - } - }), - signal: AbortSignal.timeout(3e3) - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "post_tool_use", + sessionId, + ...context, + timestamp: (/* @__PURE__ */ new Date()).toISOString(), + data: { + tool_name: toolName, + tool_input: truncate(toolInput, maxChars), + tool_output: truncate(cleanOutput, maxChars), + ...imageData ? { image_data: imageData } : {} + } + }); } function shouldSkipTool(value) { const name = typeof value === "string" ? value.trim().toLowerCase() : ""; diff --git a/plugin/scripts/prompt-submit.mjs b/plugin/scripts/prompt-submit.mjs index ca113b71f6..289ed52de3 100755 --- a/plugin/scripts/prompt-submit.mjs +++ b/plugin/scripts/prompt-submit.mjs @@ -89,19 +89,38 @@ function resolveProjectContext(cwd) { }; } //#endregion +//#region src/hooks/_observe.ts +const DEFAULT_ACK_TIMEOUT_MS = 500; +const MAX_ACK_TIMEOUT_MS = 5e3; +function ackTimeoutMs() { + const configured = Number(process.env["AGENTMEMORY_HOOK_ACK_TIMEOUT_MS"] ?? DEFAULT_ACK_TIMEOUT_MS); + if (!Number.isFinite(configured) || configured <= 0) return DEFAULT_ACK_TIMEOUT_MS; + return Math.max(1, Math.min(Math.floor(configured), MAX_ACK_TIMEOUT_MS)); +} +function authHeaders() { + const headers = { "Content-Type": "application/json" }; + const secret = process.env["AGENTMEMORY_SECRET"] || ""; + if (secret) headers["Authorization"] = `Bearer ${secret}`; + return headers; +} +async function submitObservation(payload) { + const restUrl = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; + try { + await (await fetch(`${restUrl}/agentmemory/observe/async`, { + method: "POST", + headers: authHeaders(), + body: JSON.stringify(payload), + signal: AbortSignal.timeout(ackTimeoutMs()) + })).arrayBuffer(); + } catch {} +} +//#endregion //#region src/hooks/prompt-submit.ts function isSdkChildContext(payload) { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; if (!payload || typeof payload !== "object") return false; return payload.entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; -function authHeaders() { - const h = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} async function main() { let input = ""; for await (const chunk of process.stdin) input += chunk; @@ -115,19 +134,13 @@ async function main() { const sessionId = data.session_id || data.sessionId || "unknown"; const context = resolveProjectContext(data.cwd); const promptData = promptCapture(data.prompt ?? data.userPrompt); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "prompt_submit", - sessionId, - ...context, - timestamp: (/* @__PURE__ */ new Date()).toISOString(), - data: promptData - }), - signal: AbortSignal.timeout(3e3) - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "prompt_submit", + sessionId, + ...context, + timestamp: (/* @__PURE__ */ new Date()).toISOString(), + data: promptData + }); } function promptCapture(value) { const text = typeof value === "string" ? value : ""; diff --git a/plugin/scripts/subagent-start.mjs b/plugin/scripts/subagent-start.mjs index 964317469b..c2a17e3c5c 100755 --- a/plugin/scripts/subagent-start.mjs +++ b/plugin/scripts/subagent-start.mjs @@ -89,20 +89,38 @@ function resolveProjectContext(cwd) { }; } //#endregion +//#region src/hooks/_observe.ts +const DEFAULT_ACK_TIMEOUT_MS = 500; +const MAX_ACK_TIMEOUT_MS = 5e3; +function ackTimeoutMs() { + const configured = Number(process.env["AGENTMEMORY_HOOK_ACK_TIMEOUT_MS"] ?? DEFAULT_ACK_TIMEOUT_MS); + if (!Number.isFinite(configured) || configured <= 0) return DEFAULT_ACK_TIMEOUT_MS; + return Math.max(1, Math.min(Math.floor(configured), MAX_ACK_TIMEOUT_MS)); +} +function authHeaders() { + const headers = { "Content-Type": "application/json" }; + const secret = process.env["AGENTMEMORY_SECRET"] || ""; + if (secret) headers["Authorization"] = `Bearer ${secret}`; + return headers; +} +async function submitObservation(payload) { + const restUrl = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; + try { + await (await fetch(`${restUrl}/agentmemory/observe/async`, { + method: "POST", + headers: authHeaders(), + body: JSON.stringify(payload), + signal: AbortSignal.timeout(ackTimeoutMs()) + })).arrayBuffer(); + } catch {} +} +//#endregion //#region src/hooks/subagent-start.ts function isSdkChildContext(payload) { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; if (!payload || typeof payload !== "object") return false; return payload.entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; -const TIMEOUT_MS = 800; -function authHeaders() { - const h = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} async function main() { let input = ""; for await (const chunk of process.stdin) input += chunk; @@ -116,23 +134,16 @@ async function main() { const sessionId = data.session_id || data.sessionId || "unknown"; const agentId = data.agent_id || data.agentName; const agentType = data.agent_type || data.agentDisplayName || data.agentName; - const context = resolveProjectContext(data.cwd); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "subagent_start", - sessionId, - ...context, - timestamp: (/* @__PURE__ */ new Date()).toISOString(), - data: { - agent_id: agentId, - agent_type: agentType - } - }), - signal: AbortSignal.timeout(TIMEOUT_MS) - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "subagent_start", + sessionId, + ...resolveProjectContext(data.cwd), + timestamp: (/* @__PURE__ */ new Date()).toISOString(), + data: { + agent_id: agentId, + agent_type: agentType + } + }); } main(); //#endregion diff --git a/plugin/scripts/subagent-stop.mjs b/plugin/scripts/subagent-stop.mjs index 4ce660abb0..243438ce00 100755 --- a/plugin/scripts/subagent-stop.mjs +++ b/plugin/scripts/subagent-stop.mjs @@ -89,19 +89,38 @@ function resolveProjectContext(cwd) { }; } //#endregion +//#region src/hooks/_observe.ts +const DEFAULT_ACK_TIMEOUT_MS = 500; +const MAX_ACK_TIMEOUT_MS = 5e3; +function ackTimeoutMs() { + const configured = Number(process.env["AGENTMEMORY_HOOK_ACK_TIMEOUT_MS"] ?? DEFAULT_ACK_TIMEOUT_MS); + if (!Number.isFinite(configured) || configured <= 0) return DEFAULT_ACK_TIMEOUT_MS; + return Math.max(1, Math.min(Math.floor(configured), MAX_ACK_TIMEOUT_MS)); +} +function authHeaders() { + const headers = { "Content-Type": "application/json" }; + const secret = process.env["AGENTMEMORY_SECRET"] || ""; + if (secret) headers["Authorization"] = `Bearer ${secret}`; + return headers; +} +async function submitObservation(payload) { + const restUrl = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; + try { + await (await fetch(`${restUrl}/agentmemory/observe/async`, { + method: "POST", + headers: authHeaders(), + body: JSON.stringify(payload), + signal: AbortSignal.timeout(ackTimeoutMs()) + })).arrayBuffer(); + } catch {} +} +//#endregion //#region src/hooks/subagent-stop.ts function isSdkChildContext(payload) { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; if (!payload || typeof payload !== "object") return false; return payload.entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; -function authHeaders() { - const h = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} async function main() { let input = ""; for await (const chunk of process.stdin) input += chunk; @@ -116,24 +135,17 @@ async function main() { const agentId = data.agent_id || data.agentName; const agentType = data.agent_type || data.agentDisplayName || data.agentName; const lastMsg = typeof data.last_assistant_message === "string" ? data.last_assistant_message.slice(0, 4e3) : ""; - const context = resolveProjectContext(data.cwd); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "subagent_stop", - sessionId, - ...context, - timestamp: (/* @__PURE__ */ new Date()).toISOString(), - data: { - agent_id: agentId, - agent_type: agentType, - last_message: lastMsg - } - }), - signal: AbortSignal.timeout(2e3) - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "subagent_stop", + sessionId, + ...resolveProjectContext(data.cwd), + timestamp: (/* @__PURE__ */ new Date()).toISOString(), + data: { + agent_id: agentId, + agent_type: agentType, + last_message: lastMsg + } + }); } main(); //#endregion diff --git a/plugin/scripts/task-completed.mjs b/plugin/scripts/task-completed.mjs index aec9a5470b..d6078fd638 100755 --- a/plugin/scripts/task-completed.mjs +++ b/plugin/scripts/task-completed.mjs @@ -89,19 +89,38 @@ function resolveProjectContext(cwd) { }; } //#endregion +//#region src/hooks/_observe.ts +const DEFAULT_ACK_TIMEOUT_MS = 500; +const MAX_ACK_TIMEOUT_MS = 5e3; +function ackTimeoutMs() { + const configured = Number(process.env["AGENTMEMORY_HOOK_ACK_TIMEOUT_MS"] ?? DEFAULT_ACK_TIMEOUT_MS); + if (!Number.isFinite(configured) || configured <= 0) return DEFAULT_ACK_TIMEOUT_MS; + return Math.max(1, Math.min(Math.floor(configured), MAX_ACK_TIMEOUT_MS)); +} +function authHeaders() { + const headers = { "Content-Type": "application/json" }; + const secret = process.env["AGENTMEMORY_SECRET"] || ""; + if (secret) headers["Authorization"] = `Bearer ${secret}`; + return headers; +} +async function submitObservation(payload) { + const restUrl = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; + try { + await (await fetch(`${restUrl}/agentmemory/observe/async`, { + method: "POST", + headers: authHeaders(), + body: JSON.stringify(payload), + signal: AbortSignal.timeout(ackTimeoutMs()) + })).arrayBuffer(); + } catch {} +} +//#endregion //#region src/hooks/task-completed.ts function isSdkChildContext(payload) { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; if (!payload || typeof payload !== "object") return false; return payload.entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; -function authHeaders() { - const h = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} async function main() { let input = ""; for await (const chunk of process.stdin) input += chunk; @@ -112,27 +131,19 @@ async function main() { return; } if (isSdkChildContext(data)) return; - const sessionId = data.session_id || "unknown"; - const context = resolveProjectContext(data.cwd); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "task_completed", - sessionId, - ...context, - timestamp: (/* @__PURE__ */ new Date()).toISOString(), - data: { - task_id: data.task_id, - task_subject: data.task_subject, - task_description: typeof data.task_description === "string" ? data.task_description.slice(0, 2e3) : "", - teammate_name: data.teammate_name, - team_name: data.team_name - } - }), - signal: AbortSignal.timeout(2e3) - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "task_completed", + sessionId: data.session_id || "unknown", + ...resolveProjectContext(data.cwd), + timestamp: (/* @__PURE__ */ new Date()).toISOString(), + data: { + task_id: data.task_id, + task_subject: data.task_subject, + task_description: typeof data.task_description === "string" ? data.task_description.slice(0, 2e3) : "", + teammate_name: data.teammate_name, + team_name: data.team_name + } + }); } main(); //#endregion diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md index ea5f2f0f33..e0757e6619 100644 --- a/plugin/skills/agentmemory-config/REFERENCE.md +++ b/plugin/skills/agentmemory-config/REFERENCE.md @@ -3,7 +3,7 @@ Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded. -Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 45 recognized variables: +Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 46 recognized variables: - `AGENTMEMORY_AGENT_SCOPE` - `AGENTMEMORY_ALLOW_AGENT_SDK` @@ -21,6 +21,7 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e - `AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS` - `AGENTMEMORY_FORCE_PROXY` - `AGENTMEMORY_GRAPH_WEIGHT` +- `AGENTMEMORY_HOOK_ACK_TIMEOUT_MS` - `AGENTMEMORY_III_CONFIG` - `AGENTMEMORY_III_VERSION` - `AGENTMEMORY_IMAGE_EMBEDDINGS` diff --git a/src/hooks/_observe.ts b/src/hooks/_observe.ts new file mode 100644 index 0000000000..0adf1597fb --- /dev/null +++ b/src/hooks/_observe.ts @@ -0,0 +1,38 @@ +const DEFAULT_ACK_TIMEOUT_MS = 500; +const MAX_ACK_TIMEOUT_MS = 5_000; + +function ackTimeoutMs(): number { + const configured = Number( + process.env["AGENTMEMORY_HOOK_ACK_TIMEOUT_MS"] ?? DEFAULT_ACK_TIMEOUT_MS, + ); + if (!Number.isFinite(configured) || configured <= 0) { + return DEFAULT_ACK_TIMEOUT_MS; + } + return Math.max(1, Math.min(Math.floor(configured), MAX_ACK_TIMEOUT_MS)); +} + +function authHeaders(): Record { + const headers: Record = { + "Content-Type": "application/json", + }; + const secret = process.env["AGENTMEMORY_SECRET"] || ""; + if (secret) headers["Authorization"] = `Bearer ${secret}`; + return headers; +} + +export async function submitObservation( + payload: Record, +): Promise { + const restUrl = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; + try { + const response = await fetch(`${restUrl}/agentmemory/observe/async`, { + method: "POST", + headers: authHeaders(), + body: JSON.stringify(payload), + signal: AbortSignal.timeout(ackTimeoutMs()), + }); + await response.arrayBuffer(); + } catch { + // Hook capture is best-effort and must never fail the host agent session. + } +} diff --git a/src/hooks/notification.ts b/src/hooks/notification.ts index 57926595be..23d0153e97 100644 --- a/src/hooks/notification.ts +++ b/src/hooks/notification.ts @@ -1,5 +1,6 @@ #!/usr/bin/env node import { resolveProjectContext } from "./_project.js"; +import { submitObservation } from "./_observe.js"; function isSdkChildContext(payload: unknown): boolean { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; @@ -7,15 +8,6 @@ function isSdkChildContext(payload: unknown): boolean { return (payload as { entrypoint?: unknown }).entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; - -function authHeaders(): Record { - const h: Record = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} - async function main() { let input = ""; for await (const chunk of process.stdin) { @@ -40,23 +32,17 @@ async function main() { : "unknown"; const context = resolveProjectContext(data.cwd as string | undefined); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "notification", - sessionId, - ...context, - timestamp: new Date().toISOString(), - data: { - notification_type: notificationType, - title: data.title, - message: data.message, - }, - }), - signal: AbortSignal.timeout(2000), - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "notification", + sessionId, + ...context, + timestamp: new Date().toISOString(), + data: { + notification_type: notificationType, + title: data.title, + message: data.message, + }, + }); } main(); diff --git a/src/hooks/post-tool-failure.ts b/src/hooks/post-tool-failure.ts index aa3ce66065..b50bc15ee7 100644 --- a/src/hooks/post-tool-failure.ts +++ b/src/hooks/post-tool-failure.ts @@ -1,5 +1,6 @@ #!/usr/bin/env node import { resolveProjectContext } from "./_project.js"; +import { submitObservation } from "./_observe.js"; function isSdkChildContext(payload: unknown): boolean { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; @@ -7,15 +8,6 @@ function isSdkChildContext(payload: unknown): boolean { return (payload as { entrypoint?: unknown }).entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; - -function authHeaders(): Record { - const h: Record = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} - async function main() { let input = ""; for await (const chunk of process.stdin) { @@ -42,29 +34,23 @@ async function main() { const error = data.error ?? data.errorMessage; const context = resolveProjectContext(data.cwd as string | undefined); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "post_tool_failure", - sessionId, - ...context, - timestamp: new Date().toISOString(), - data: { - tool_name: toolName, - tool_input: - typeof toolInput === "string" - ? toolInput.slice(0, 4000) - : JSON.stringify(toolInput ?? "").slice(0, 4000), - error: - typeof error === "string" - ? error.slice(0, 4000) - : JSON.stringify(error ?? "").slice(0, 4000), - }, - }), - signal: AbortSignal.timeout(3000), - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "post_tool_failure", + sessionId, + ...context, + timestamp: new Date().toISOString(), + data: { + tool_name: toolName, + tool_input: + typeof toolInput === "string" + ? toolInput.slice(0, 4000) + : JSON.stringify(toolInput ?? "").slice(0, 4000), + error: + typeof error === "string" + ? error.slice(0, 4000) + : JSON.stringify(error ?? "").slice(0, 4000), + }, + }); } main(); diff --git a/src/hooks/post-tool-use.ts b/src/hooks/post-tool-use.ts index eac2cd512f..d561f689f2 100644 --- a/src/hooks/post-tool-use.ts +++ b/src/hooks/post-tool-use.ts @@ -1,5 +1,6 @@ #!/usr/bin/env node import { resolveProjectContext } from "./_project.js"; +import { submitObservation } from "./_observe.js"; function isSdkChildContext(payload: unknown): boolean { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; @@ -7,15 +8,6 @@ function isSdkChildContext(payload: unknown): boolean { return (payload as { entrypoint?: unknown }).entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; - -function authHeaders(): Record { - const h: Record = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} - async function main() { let input = ""; for await (const chunk of process.stdin) { @@ -40,24 +32,18 @@ async function main() { const { imageData, cleanOutput } = extractImageData(toolOutput(data)); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "post_tool_use", - sessionId, - ...context, - timestamp: new Date().toISOString(), - data: { - tool_name: toolName, - tool_input: truncate(toolInput, maxChars), - tool_output: truncate(cleanOutput, maxChars), - ...(imageData ? { image_data: imageData } : {}), - }, - }), - signal: AbortSignal.timeout(3000), - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "post_tool_use", + sessionId, + ...context, + timestamp: new Date().toISOString(), + data: { + tool_name: toolName, + tool_input: truncate(toolInput, maxChars), + tool_output: truncate(cleanOutput, maxChars), + ...(imageData ? { image_data: imageData } : {}), + }, + }); } function shouldSkipTool(value: unknown): boolean { diff --git a/src/hooks/prompt-submit.ts b/src/hooks/prompt-submit.ts index 69bb83a094..5e3946cba0 100644 --- a/src/hooks/prompt-submit.ts +++ b/src/hooks/prompt-submit.ts @@ -1,5 +1,6 @@ #!/usr/bin/env node import { resolveProjectContext } from "./_project.js"; +import { submitObservation } from "./_observe.js"; function isSdkChildContext(payload: unknown): boolean { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; @@ -7,15 +8,6 @@ function isSdkChildContext(payload: unknown): boolean { return (payload as { entrypoint?: unknown }).entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; - -function authHeaders(): Record { - const h: Record = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} - async function main() { let input = ""; for await (const chunk of process.stdin) { @@ -36,19 +28,13 @@ async function main() { const prompt = data.prompt ?? data.userPrompt; const promptData = promptCapture(prompt); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "prompt_submit", - sessionId, - ...context, - timestamp: new Date().toISOString(), - data: promptData, - }), - signal: AbortSignal.timeout(3000), - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "prompt_submit", + sessionId, + ...context, + timestamp: new Date().toISOString(), + data: promptData, + }); } function promptCapture(value: unknown): Record { diff --git a/src/hooks/subagent-start.ts b/src/hooks/subagent-start.ts index dc73a235b6..bf7c66f29c 100644 --- a/src/hooks/subagent-start.ts +++ b/src/hooks/subagent-start.ts @@ -1,5 +1,6 @@ #!/usr/bin/env node import { resolveProjectContext } from "./_project.js"; +import { submitObservation } from "./_observe.js"; // Inlined from ./sdk-guard so each hook bundles to a single self-contained // .mjs (matches the pattern used by every other hook entry in tsdown.config). @@ -9,21 +10,6 @@ function isSdkChildContext(payload: unknown): boolean { return (payload as { entrypoint?: unknown }).entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; - -// Passive telemetry only — nothing reads the response, so the previous -// `await` was pure latency. Tightened from 2000ms to a defensive cap so a -// slow/unreachable server can't stack onto every concurrent subagent -// startup (#221). -const TIMEOUT_MS = 800; - -function authHeaders(): Record { - const h: Record = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} - async function main() { let input = ""; for await (const chunk of process.stdin) { @@ -44,22 +30,16 @@ async function main() { const agentType = data.agent_type || data.agentDisplayName || data.agentName; const context = resolveProjectContext(data.cwd as string | undefined); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "subagent_start", - sessionId, - ...context, - timestamp: new Date().toISOString(), - data: { - agent_id: agentId, - agent_type: agentType, - }, - }), - signal: AbortSignal.timeout(TIMEOUT_MS), - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "subagent_start", + sessionId, + ...context, + timestamp: new Date().toISOString(), + data: { + agent_id: agentId, + agent_type: agentType, + }, + }); } main(); diff --git a/src/hooks/subagent-stop.ts b/src/hooks/subagent-stop.ts index e8059a46b1..73562da847 100644 --- a/src/hooks/subagent-stop.ts +++ b/src/hooks/subagent-stop.ts @@ -1,5 +1,6 @@ #!/usr/bin/env node import { resolveProjectContext } from "./_project.js"; +import { submitObservation } from "./_observe.js"; function isSdkChildContext(payload: unknown): boolean { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; @@ -7,15 +8,6 @@ function isSdkChildContext(payload: unknown): boolean { return (payload as { entrypoint?: unknown }).entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; - -function authHeaders(): Record { - const h: Record = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} - async function main() { let input = ""; for await (const chunk of process.stdin) { @@ -40,23 +32,17 @@ async function main() { : ""; const context = resolveProjectContext(data.cwd as string | undefined); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "subagent_stop", - sessionId, - ...context, - timestamp: new Date().toISOString(), - data: { - agent_id: agentId, - agent_type: agentType, - last_message: lastMsg, - }, - }), - signal: AbortSignal.timeout(2000), - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "subagent_stop", + sessionId, + ...context, + timestamp: new Date().toISOString(), + data: { + agent_id: agentId, + agent_type: agentType, + last_message: lastMsg, + }, + }); } main(); diff --git a/src/hooks/task-completed.ts b/src/hooks/task-completed.ts index facb34f531..c937f757e8 100644 --- a/src/hooks/task-completed.ts +++ b/src/hooks/task-completed.ts @@ -1,5 +1,6 @@ #!/usr/bin/env node import { resolveProjectContext } from "./_project.js"; +import { submitObservation } from "./_observe.js"; function isSdkChildContext(payload: unknown): boolean { if (process.env["AGENTMEMORY_SDK_CHILD"] === "1") return true; @@ -7,15 +8,6 @@ function isSdkChildContext(payload: unknown): boolean { return (payload as { entrypoint?: unknown }).entrypoint === "sdk-ts"; } -const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; -const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; - -function authHeaders(): Record { - const h: Record = { "Content-Type": "application/json" }; - if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; - return h; -} - async function main() { let input = ""; for await (const chunk of process.stdin) { @@ -34,27 +26,21 @@ async function main() { const sessionId = (data.session_id as string) || "unknown"; const context = resolveProjectContext(data.cwd as string | undefined); - fetch(`${REST_URL}/agentmemory/observe/async`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "task_completed", - sessionId, - ...context, - timestamp: new Date().toISOString(), - data: { - task_id: data.task_id, - task_subject: data.task_subject, - task_description: typeof data.task_description === "string" - ? data.task_description.slice(0, 2000) - : "", - teammate_name: data.teammate_name, - team_name: data.team_name, - }, - }), - signal: AbortSignal.timeout(2000), - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + await submitObservation({ + hookType: "task_completed", + sessionId, + ...context, + timestamp: new Date().toISOString(), + data: { + task_id: data.task_id, + task_subject: data.task_subject, + task_description: typeof data.task_description === "string" + ? data.task_description.slice(0, 2000) + : "", + teammate_name: data.teammate_name, + team_name: data.team_name, + }, + }); } main(); diff --git a/test/hook-observation-client.test.ts b/test/hook-observation-client.test.ts new file mode 100644 index 0000000000..fccbdc0218 --- /dev/null +++ b/test/hook-observation-client.test.ts @@ -0,0 +1,89 @@ +import { readFileSync } from "node:fs"; +import { resolve } from "node:path"; +import { afterEach, describe, expect, it, vi } from "vitest"; + +import { submitObservation } from "../src/hooks/_observe.js"; + +const OBSERVATION_HOOKS = [ + "notification", + "post-tool-failure", + "post-tool-use", + "prompt-submit", + "subagent-start", + "subagent-stop", + "task-completed", +]; + +afterEach(() => { + vi.unstubAllGlobals(); + vi.unstubAllEnvs(); +}); + +describe("hook observation transport", () => { + it("waits until the acknowledgement body is consumed", async () => { + let releaseBody!: () => void; + const bodyConsumed = new Promise((resolveBody) => { + releaseBody = resolveBody; + }); + const arrayBuffer = vi.fn(async () => { + await bodyConsumed; + return new ArrayBuffer(0); + }); + const fetchMock = vi.fn(async () => ({ arrayBuffer }) as unknown as Response); + vi.stubGlobal("fetch", fetchMock); + + let settled = false; + const pending = submitObservation({ sessionId: "session-1" }).then(() => { + settled = true; + }); + await vi.waitFor(() => expect(arrayBuffer).toHaveBeenCalledOnce()); + + expect(settled).toBe(false); + releaseBody(); + await pending; + expect(settled).toBe(true); + }); + + it("uses the configured endpoint and bearer secret", async () => { + vi.stubEnv("AGENTMEMORY_URL", "http://127.0.0.1:3999"); + vi.stubEnv("AGENTMEMORY_SECRET", "test-secret"); + const fetchMock = vi.fn(async () => + ({ arrayBuffer: vi.fn(async () => new ArrayBuffer(0)) }) as unknown as Response + ); + vi.stubGlobal("fetch", fetchMock); + + await submitObservation({ sessionId: "session-2" }); + + expect(fetchMock).toHaveBeenCalledWith( + "http://127.0.0.1:3999/agentmemory/observe/async", + expect.objectContaining({ + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer test-secret", + }, + }), + ); + }); + + it("keeps transport failures silent", async () => { + vi.stubGlobal("fetch", vi.fn(async () => { + throw new Error("offline"); + })); + + await expect( + submitObservation({ sessionId: "session-3" }), + ).resolves.toBeUndefined(); + }); + + it.each(OBSERVATION_HOOKS)("%s awaits the shared acknowledgement helper", (name) => { + const source = readFileSync( + resolve(__dirname, "..", "src", "hooks", `${name}.ts`), + "utf8", + ); + + expect(source).toContain("await submitObservation("); + expect(source).not.toContain("setTimeout(() => process.exit(0), 500)"); + expect(source).not.toContain("fetch(`${REST_URL}/agentmemory/observe/async`"); + }); +}); From 1597995d604997219265e48b9178c7bc6b91d948 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Mon, 13 Jul 2026 21:45:38 -0400 Subject: [PATCH 09/43] fix: make observation ingestion durable --- .env.example | 1 + AGENTS.md | 2 +- README.md | 15 +++- iii-config.docker.yaml | 10 +++ iii-config.yaml | 10 +++ src/config.ts | 35 ++++++++- src/eval/metrics-store.ts | 125 +++++++++++++++++++++++-------- src/functions/compress.ts | 27 +++++++ src/functions/observe.ts | 110 +++++++++++++++++++-------- src/functions/summarize.ts | 37 ++++++--- src/providers/noop.ts | 1 + src/providers/resilient.ts | 2 + src/triggers/api.ts | 78 ++++++++++++------- src/triggers/events.ts | 9 ++- src/types.ts | 6 ++ src/viewer/index.html | 16 ++-- test/api-llm-state.test.ts | 69 +++++++++++++++++ test/api-observe-async.test.ts | 54 +++++++++++-- test/auto-compress.test.ts | 87 +++++++++++++++++++++ test/compress-disabled.test.ts | 55 ++++++++++++++ test/env-loader.test.ts | 1 + test/llm-execution-state.test.ts | 39 ++++++++++ test/metrics-store.test.ts | 57 ++++++++++++++ test/queue-config.test.ts | 18 +++++ test/summarize.test.ts | 34 ++++++++- 25 files changed, 767 insertions(+), 131 deletions(-) create mode 100644 test/api-llm-state.test.ts create mode 100644 test/compress-disabled.test.ts create mode 100644 test/llm-execution-state.test.ts create mode 100644 test/metrics-store.test.ts create mode 100644 test/queue-config.test.ts diff --git a/.env.example b/.env.example index 77ca0f3a38..9ff441a298 100644 --- a/.env.example +++ b/.env.example @@ -106,6 +106,7 @@ # ----------------------------------------------------------------------------- # AGENTMEMORY_AUTO_COMPRESS=true # Run LLM compression on every observation batch (requires a provider key). Default off — synthetic compression handles most cases. +# AGENTMEMORY_DISABLE_LLM_TOOLS=true # Disable LLM-backed execution. Calls return skipped_disabled and increment skippedCount instead of failureCount. # AGENTMEMORY_INJECT_CONTEXT=true # Inject recalled memories back into agent prompts (#143). Default off — hooks capture observations but do not modify conversation. # CONSOLIDATION_ENABLED=true # Run the 4-tier consolidation pipeline (memories → semantic → procedural). Default off — opt in once you've measured the LLM cost. # CONSOLIDATION_DECAY_DAYS=30 # Age (days) after which non-reinforced memories decay during consolidation diff --git a/AGENTS.md b/AGENTS.md index bec145e63e..b5ea4f027a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -94,7 +94,7 @@ case "memory_your_tool": { Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). They read JSON from stdin, make HTTP calls to the REST API, and exit. There are two patterns depending on whether Claude Code consumes the script's stdout: - **Context-injecting hooks** (`pre-tool-use`, `pre-compact`, `session-start`) write recalled context to stdout for Claude Code to inject. These MUST use `try/catch` with `await fetch(..., { signal: AbortSignal.timeout(N) })` — the script has to wait for the response before exiting, and the timeout is the only bound on hang time. -- **Observation telemetry hooks** (`notification`, `post-tool-failure`, `post-tool-use`, `prompt-submit`, `subagent-start`, `subagent-stop`, `task-completed`) MUST call and await the shared `submitObservation()` helper. The REST endpoint returns `202` after a void dispatch, so this waits only for the small transport acknowledgement and response body, not persistence/indexing. The helper's bounded timeout defaults to 500ms and failures stay silent. Do not reintroduce unawaited `fetch()` plus hard `process.exit()`: terminating the client before the response lifecycle completes can strand iii invocation bookkeeping. +- **Observation telemetry hooks** (`notification`, `post-tool-failure`, `post-tool-use`, `prompt-submit`, `subagent-start`, `subagent-stop`, `task-completed`) MUST call and await the shared `submitObservation()` helper. The REST endpoint returns `202` only after iii's file-backed `agentmemory-observations` queue returns a receipt, so this waits for durable acceptance rather than full persistence/indexing. The helper's bounded timeout defaults to 500ms and failures stay silent. Do not reintroduce unawaited `fetch()` plus hard `process.exit()`: terminating the client before the response lifecycle completes can strand iii invocation bookkeeping. - **Multi-request telemetry hooks** (`stop`, `session-end`) still use fire-and-forget requests with a 1500ms exit bound because they dispatch several independent lifecycle calls, not only the asynchronous observation endpoint. ## Coding Standards diff --git a/README.md b/README.md index 963298d2d0..a71d1a8c3e 100644 --- a/README.md +++ b/README.md @@ -1172,6 +1172,13 @@ If you want to export to Jaeger/Honeycomb/Grafana Tempo instead, change `exporte agentmemory is **already a running [iii](https://iii.dev) instance**. Three primitives — worker, function, trigger — compose the runtime; KV state, streams, and OTEL traces come from iii-state, iii-stream, and iii-observability workers that ship with iii. You didn't install Postgres, Redis, Express, pm2, or Prometheus, because iii replaces them. +Hook observations use the named `agentmemory-observations` queue. The default +single-instance configuration stores that queue under `data/queue_store`, +retries failed delivery up to five times, and retains exhausted jobs in the +queue DLQ. `/agentmemory/observe/async` returns `202` only after the queue +returns a receipt; the response includes both `messageReceiptId` and the stable +`observationId` used to make a completed redelivery idempotent. + That means one more command extends agentmemory with an entire new capability. ### Extend agentmemory with one command @@ -1192,7 +1199,7 @@ Each `iii worker add` registers new functions and triggers into the same engine |---|---| | [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | Multi-instance memory: every `remember` fans out, every `search` reads the union | | [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | Scheduled lifecycle — nightly consolidation, weekly snapshots, decay on a fixed clock | -| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | Durable retries: failed embedding + compression jobs survive restart, no lost observations | +| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | File-backed hook ingestion with receipts, retries, and dead-letter recovery | | [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | OTEL traces, metrics, logs on every function — wired in `iii-config.yaml` from day one | | [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Code that came out of `memory_recall` runs inside a throwaway VM, not your shell | | [`iii-database`](https://workers.iii.dev/workers/iii-database) | SQL-backed state adapter when you outgrow the in-memory KV defaults | @@ -1495,7 +1502,7 @@ Create `~/.agentmemory/.env`: # Tool visibility: "core" (7), "workstation" (curated coordination), "all" (53), or a comma-separated allowlist # AGENTMEMORY_TOOLS=core -# AGENTMEMORY_DISABLE_LLM_TOOLS=true +# AGENTMEMORY_DISABLE_LLM_TOOLS=true # reports skipped_disabled, not failure ``` --- @@ -1509,11 +1516,11 @@ Create `~/.agentmemory/.env`: | Method | Path | Description | |--------|------|-------------| -| `GET` | `/agentmemory/health` | Health check (always public) | +| `GET` | `/agentmemory/health` | Health check with LLM execution state and success/failure/skipped metrics (always public) | | `POST` | `/agentmemory/session/start` | Start session + get context | | `POST` | `/agentmemory/session/end` | End session | | `POST` | `/agentmemory/observe` | Capture observation synchronously | -| `POST` | `/agentmemory/observe/async` | Acknowledge hook transport (`202`); capture continues asynchronously | +| `POST` | `/agentmemory/observe/async` | Return `202` after file-backed queue acceptance; includes queue receipt + stable observation ID | | `POST` | `/agentmemory/smart-search` | Hybrid search | | `POST` | `/agentmemory/context` | Generate context | | `POST` | `/agentmemory/remember` | Save to long-term memory | diff --git a/iii-config.docker.yaml b/iii-config.docker.yaml index 682236ec37..f8d46dcfde 100644 --- a/iii-config.docker.yaml +++ b/iii-config.docker.yaml @@ -16,8 +16,18 @@ workers: file_path: /data/state_store.db - name: iii-queue config: + queue_configs: + agentmemory-observations: + max_retries: 5 + concurrency: 4 + type: standard + backoff_ms: 250 + poll_interval_ms: 50 adapter: name: builtin + config: + store_method: file_based + file_path: /data/queue_store - name: iii-pubsub config: adapter: diff --git a/iii-config.yaml b/iii-config.yaml index 62892f5143..25770e26b4 100644 --- a/iii-config.yaml +++ b/iii-config.yaml @@ -16,8 +16,18 @@ workers: file_path: ./data/state_store.db - name: iii-queue config: + queue_configs: + agentmemory-observations: + max_retries: 5 + concurrency: 4 + type: standard + backoff_ms: 250 + poll_interval_ms: 50 adapter: name: builtin + config: + store_method: file_based + file_path: ./data/queue_store - name: iii-pubsub config: adapter: diff --git a/src/config.ts b/src/config.ts index 3348ac2267..17b9e0c723 100644 --- a/src/config.ts +++ b/src/config.ts @@ -9,6 +9,7 @@ import type { FallbackConfig, ClaudeBridgeConfig, TeamConfig, + MemoryProvider, } from "./types.js"; function safeParseInt(value: string | undefined, fallback: number): number { @@ -208,13 +209,39 @@ export function detectLlmProviderKind(): "llm" | "noop" { hasRealValue(env["OPENROUTER_API_KEY"]) || hasRealValue(env["MINIMAX_API_KEY"]) || (hasRealValue(env["OPENAI_API_KEY"]) && - env["OPENAI_API_KEY_FOR_LLM"] !== "false") + env["OPENAI_API_KEY_FOR_LLM"] !== "false") || + env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true" ) { return "llm"; } return "noop"; } +export type LlmExecutionState = "enabled" | "disabled" | "unavailable"; + +export const LLM_METRIC_FUNCTION_IDS = new Set([ + "mem::compress", + "mem::summarize", +]); + +export function isLlmToolsDisabled(): boolean { + return getMergedEnv()["AGENTMEMORY_DISABLE_LLM_TOOLS"] === "true"; +} + +export function getLlmExecutionState( + provider?: Pick, +): LlmExecutionState { + if (isLlmToolsDisabled()) return "disabled"; + if (provider) { + const providerIsNoop = + provider.kind === "noop" || + provider.name === "noop" || + provider.name.endsWith("(noop)"); + return providerIsNoop ? "unavailable" : "enabled"; + } + return detectLlmProviderKind() === "llm" ? "enabled" : "unavailable"; +} + export function loadEmbeddingConfig(): EmbeddingConfig { const env = getMergedEnv(); let bm25Weight = parseFloat(env["BM25_WEIGHT"] || "0.4"); @@ -349,6 +376,7 @@ export function getFollowupWindowSeconds(): number { export function isConsolidationEnabled(): boolean { const env = getMergedEnv(); + if (env["AGENTMEMORY_DISABLE_LLM_TOOLS"] === "true") return false; const explicit = env["CONSOLIDATION_ENABLED"]; if (explicit === "false" || explicit === "0") return false; if (explicit === "true" || explicit === "1") return true; @@ -380,7 +408,10 @@ function hasLLMProviderConfigured(env: Record): bool // ~/.agentmemory/.env — but should expect their Claude API token usage to // climb proportionally with session tool-use frequency. export function isAutoCompressEnabled(): boolean { - return getMergedEnv()["AGENTMEMORY_AUTO_COMPRESS"] === "true"; + return ( + getMergedEnv()["AGENTMEMORY_AUTO_COMPRESS"] === "true" && + getLlmExecutionState() === "enabled" + ); } // Hook-level context injection into Claude Code's conversation is OFF by diff --git a/src/eval/metrics-store.ts b/src/eval/metrics-store.ts index 1d381ff95b..c926e22924 100644 --- a/src/eval/metrics-store.ts +++ b/src/eval/metrics-store.ts @@ -1,6 +1,15 @@ import type { FunctionMetrics } from "../types.js"; import type { StateKV } from "../state/kv.js"; import { KV } from "../state/schema.js"; +import { withKeyedLock } from "../state/keyed-mutex.js"; + +type FunctionOutcome = + | "success" + | "failure" + | "skipped_disabled" + | "skipped_unavailable"; + +type SkipReason = "llm_tools_disabled" | "no_llm_provider"; export class MetricsStore { private cache = new Map(); @@ -8,49 +17,99 @@ export class MetricsStore { constructor(private kv: StateKV) {} - async record( - functionId: string, - latencyMs: number, - success: boolean, - qualityScore?: number, - ): Promise { - let m = this.cache.get(functionId); - if (!m) { - m = (await this.kv.get(KV.metrics, functionId)) ?? { + private normalize(metric: FunctionMetrics): FunctionMetrics { + return { + ...metric, + skippedCount: metric.skippedCount ?? 0, + }; + } + + private async load(functionId: string): Promise { + const cached = this.cache.get(functionId); + if (cached) return this.normalize(cached); + const stored = await this.kv.get(KV.metrics, functionId); + return this.normalize( + stored ?? { functionId, totalCalls: 0, successCount: 0, failureCount: 0, + skippedCount: 0, avgLatencyMs: 0, avgQualityScore: 0, - }; - } + }, + ); + } + + private async recordOutcome( + functionId: string, + latencyMs: number, + outcome: FunctionOutcome, + qualityScore?: number, + skipReason?: SkipReason, + ): Promise { + await withKeyedLock(`metrics:${functionId}`, async () => { + const previous = await this.load(functionId); + const metric: FunctionMetrics = { ...previous }; + const previousCalls = metric.totalCalls; + metric.totalCalls += 1; + metric.avgLatencyMs = + (metric.avgLatencyMs * previousCalls + latencyMs) / metric.totalCalls; + metric.lastOutcome = outcome; + if (outcome === "success") metric.successCount += 1; + if (outcome === "failure") metric.failureCount += 1; + if (outcome === "skipped_disabled" || outcome === "skipped_unavailable") { + metric.skippedCount += 1; + metric.lastSkipReason = skipReason; + } + if (qualityScore !== undefined) { + const previousQualityCalls = this.qualityCallCounts.get(functionId) || 0; + metric.avgQualityScore = + (metric.avgQualityScore * previousQualityCalls + qualityScore) / + (previousQualityCalls + 1); + this.qualityCallCounts.set(functionId, previousQualityCalls + 1); + } + + this.cache.set(functionId, metric); + await this.kv.set(KV.metrics, functionId, metric).catch(() => {}); + }); + } - const prev = m.totalCalls; - m.totalCalls += 1; - m.avgLatencyMs = (m.avgLatencyMs * prev + latencyMs) / m.totalCalls; - if (success) { - m.successCount += 1; - } else { - m.failureCount += 1; - } - if (qualityScore !== undefined) { - const prevQualityCalls = this.qualityCallCounts.get(functionId) || 0; - m.avgQualityScore = - (m.avgQualityScore * prevQualityCalls + qualityScore) / - (prevQualityCalls + 1); - this.qualityCallCounts.set(functionId, prevQualityCalls + 1); - } + async record( + functionId: string, + latencyMs: number, + success: boolean, + qualityScore?: number, + ): Promise { + await this.recordOutcome( + functionId, + latencyMs, + success ? "success" : "failure", + qualityScore, + ); + } - this.cache.set(functionId, m); - await this.kv.set(KV.metrics, functionId, m).catch(() => {}); + async recordSkipped( + functionId: string, + latencyMs: number, + reason: SkipReason, + ): Promise { + await this.recordOutcome( + functionId, + latencyMs, + reason === "llm_tools_disabled" + ? "skipped_disabled" + : "skipped_unavailable", + undefined, + reason, + ); } async get(functionId: string): Promise { - return ( + const metric = this.cache.get(functionId) ?? - (await this.kv.get(KV.metrics, functionId)) - ); + (await this.kv.get(KV.metrics, functionId)); + return metric ? this.normalize(metric) : null; } async getAll(): Promise { @@ -58,8 +117,8 @@ export class MetricsStore { .list(KV.metrics) .catch(() => []); const merged = new Map(); - for (const m of kvMetrics) merged.set(m.functionId, m); - for (const [id, m] of this.cache) merged.set(id, m); + for (const m of kvMetrics) merged.set(m.functionId, this.normalize(m)); + for (const [id, m] of this.cache) merged.set(id, this.normalize(m)); return Array.from(merged.values()); } } diff --git a/src/functions/compress.ts b/src/functions/compress.ts index 0569555e06..f868f0ce3f 100644 --- a/src/functions/compress.ts +++ b/src/functions/compress.ts @@ -22,6 +22,7 @@ import { scoreCompression } from "../eval/quality.js"; import { compressWithRetry } from "../eval/self-correct.js"; import type { MetricsStore } from "../eval/metrics-store.js"; import { logger } from "../logger.js"; +import { getLlmExecutionState } from "../config.js"; const VALID_TYPES = new Set([ "file_read", @@ -77,6 +78,32 @@ export function registerCompressFunction( raw: RawObservation; }) => { const startMs = Date.now(); + const llmExecutionState = getLlmExecutionState(provider); + if (llmExecutionState !== "enabled") { + const skipped = + llmExecutionState === "disabled" + ? "llm_tools_disabled" + : "no_llm_provider"; + if (metricsStore) { + await metricsStore.recordSkipped( + "mem::compress", + Date.now() - startMs, + skipped, + ); + } + logger.info("Compression skipped", { + observationId: data.observationId, + skipped, + }); + return { + success: true, + outcome: + llmExecutionState === "disabled" + ? "skipped_disabled" + : "skipped_unavailable", + skipped, + }; + } let imageDescription: string | undefined; const hasImage = data.raw.modality === "image" || data.raw.modality === "mixed"; diff --git a/src/functions/observe.ts b/src/functions/observe.ts index 816de9d9ba..128694b7de 100644 --- a/src/functions/observe.ts +++ b/src/functions/observe.ts @@ -70,7 +70,12 @@ export function registerObserveFunction( }; } - const obsId = generateId("obs"); + const requestedObservationId = + typeof payload.observationId === "string" && + /^obs_[a-z0-9_]{1,96}$/i.test(payload.observationId.trim()) + ? payload.observationId.trim() + : undefined; + const obsId = requestedObservationId ?? generateId("obs"); let dedupHash: string | undefined; if (dedupMap) { @@ -84,9 +89,6 @@ export function registerObserveFunction( toolName, d["tool_input"], ); - if (dedupMap.isDuplicate(dedupHash)) { - return { deduplicated: true, sessionId: payload.sessionId }; - } } let sanitizedRaw: unknown = payload.data; @@ -136,9 +138,38 @@ export function registerObserveFunction( const pendingImageData = extractedImage; return withKeyedLock(`obs:${payload.sessionId}`, async () => { + const observationScope = KV.observations(payload.sessionId); + const existingObservation = requestedObservationId + ? await kv.get( + observationScope, + obsId, + ) + : null; + if (existingObservation && "title" in existingObservation) { + return { + observationId: obsId, + deduplicated: true, + durableRetry: true, + }; + } + if (existingObservation) { + Object.assign(raw, existingObservation); + } + if ( + !existingObservation && + dedupMap && + dedupHash && + dedupMap.isDuplicate(dedupHash) + ) { + return { deduplicated: true, sessionId: payload.sessionId }; + } + if (maxObservationsPerSession && maxObservationsPerSession > 0) { - const existing = await kv.list(KV.observations(payload.sessionId)); - if (existing.length >= maxObservationsPerSession) { + const existing = await kv.list(observationScope); + if ( + !existingObservation && + existing.length >= maxObservationsPerSession + ) { return { success: false, error: `Session observation limit reached (${maxObservationsPerSession})`, @@ -150,7 +181,10 @@ export function registerObserveFunction( // undefined). Env AGENT_ID only fires when no session row // exists yet — otherwise an unscoped session would get // retroactively scoped by a later AGENT_ID export. - const existingSession = await kv.get(KV.sessions, payload.sessionId); + const existingSession = await kv.get( + KV.sessions, + payload.sessionId, + ); const inheritedAgentId = existingSession ? existingSession.agentId : getAgentId(); @@ -158,7 +192,13 @@ export function registerObserveFunction( raw.agentId = inheritedAgentId; } - if (pendingImageData && (pendingImageData.startsWith("data:image/") || pendingImageData.startsWith("iVBORw0KGgo") || pendingImageData.startsWith("/9j/"))) { + if ( + !existingObservation && + pendingImageData && + (pendingImageData.startsWith("data:image/") || + pendingImageData.startsWith("iVBORw0KGgo") || + pendingImageData.startsWith("/9j/")) + ) { const { filePath, bytesWritten } = await saveImageToDisk(pendingImageData); raw.imageData = filePath; const { incrementImageRef } = await import("./image-refs.js"); @@ -182,9 +222,9 @@ export function registerObserveFunction( } try { - - await kv.set(KV.observations(payload.sessionId), obsId, raw); - + if (!existingObservation) { + await kv.set(observationScope, obsId, raw); + } } catch (error) { if (raw.imageData) { // Roll back the ref taken above. decrementImageRef deletes the file @@ -206,31 +246,33 @@ export function registerObserveFunction( throw error; } - if (dedupMap && dedupHash) { + if (!existingObservation && dedupMap && dedupHash) { dedupMap.record(dedupHash); } - await sdk.trigger({ - function_id: "stream::set", - payload: { - stream_name: STREAM.name, - group_id: STREAM.group(payload.sessionId), - item_id: obsId, - data: { type: "raw", observation: raw }, - }, - }); + if (!existingObservation) { + await sdk.trigger({ + function_id: "stream::set", + payload: { + stream_name: STREAM.name, + group_id: STREAM.group(payload.sessionId), + item_id: obsId, + data: { type: "raw", observation: raw }, + }, + }); - await sdk.trigger({ - function_id: "stream::send", - payload: { - stream_name: STREAM.name, - group_id: STREAM.viewerGroup, - id: `raw-${obsId}`, - type: "raw_observation", - data: { type: "raw", observation: raw, sessionId: payload.sessionId }, - }, - action: TriggerAction.Void(), - }); + await sdk.trigger({ + function_id: "stream::send", + payload: { + stream_name: STREAM.name, + group_id: STREAM.viewerGroup, + id: `raw-${obsId}`, + type: "raw_observation", + data: { type: "raw", observation: raw, sessionId: payload.sessionId }, + }, + action: TriggerAction.Void(), + }); + } const session = existingSession; if (session) { @@ -241,7 +283,9 @@ export function registerObserveFunction( { type: "set", path: "observationCount", - value: (session.observationCount || 0) + 1, + value: requestedObservationId + ? (await kv.list(observationScope)).length + : (session.observationCount || 0) + 1, }, ]; for (const field of SESSION_CONTEXT_FIELDS) { diff --git a/src/functions/summarize.ts b/src/functions/summarize.ts index 4c501ca8cf..d51b3f273b 100644 --- a/src/functions/summarize.ts +++ b/src/functions/summarize.ts @@ -20,6 +20,7 @@ import { scoreSummary } from "../eval/quality.js"; import type { MetricsStore } from "../eval/metrics-store.js"; import { safeAudit } from "./audit.js"; import { logger } from "../logger.js"; +import { getLlmExecutionState } from "../config.js"; // Per-chunk observation budget when a session is too large to fit in one // LLM call. Default ≈ 50k input tokens per chunk at ~110 tok/obs — fits @@ -240,6 +241,30 @@ export function registerSummarizeFunction( } const sessionId = data.sessionId.trim(); + const llmExecutionState = getLlmExecutionState(provider); + if (llmExecutionState !== "enabled") { + const skipped = + llmExecutionState === "disabled" + ? "llm_tools_disabled" + : "no_llm_provider"; + if (metricsStore) { + await metricsStore.recordSkipped( + "mem::summarize", + Date.now() - startMs, + skipped, + ); + } + logger.info("Summarize skipped", { sessionId, skipped }); + return { + success: true, + outcome: + llmExecutionState === "disabled" + ? "skipped_disabled" + : "skipped_unavailable", + skipped, + }; + } + const session = await kv.get(KV.sessions, sessionId); if (!session) { logger.warn("Session not found for summarize", { @@ -260,18 +285,6 @@ export function registerSummarizeFunction( return { success: false, error: "no_observations" }; } - if (provider.name === "noop") { - logger.info("Summarize skipped — no LLM provider configured", { - sessionId, - }); - return { - success: false, - error: "no_provider", - reason: - "No LLM provider key set; Summarize is a no-op. Set ANTHROPIC_API_KEY (or GEMINI/OPENROUTER/MINIMAX) in ~/.agentmemory/.env to enable.", - }; - } - try { // #783: chunk-level produceSummaryXml retries internally, but // the final merge used to parse once and bail. Wrap the diff --git a/src/providers/noop.ts b/src/providers/noop.ts index 6e74f9aa75..326610c4a5 100644 --- a/src/providers/noop.ts +++ b/src/providers/noop.ts @@ -9,6 +9,7 @@ import type { MemoryProvider } from "../types.js"; */ export class NoopProvider implements MemoryProvider { name = "noop"; + kind = "noop" as const; async compress(): Promise { return ""; diff --git a/src/providers/resilient.ts b/src/providers/resilient.ts index 95ece40c96..10d6718eb6 100644 --- a/src/providers/resilient.ts +++ b/src/providers/resilient.ts @@ -4,9 +4,11 @@ import { CircuitBreaker } from "./circuit-breaker.js"; export class ResilientProvider implements MemoryProvider { private breaker = new CircuitBreaker(); name: string; + kind: "llm" | "noop"; constructor(private inner: MemoryProvider) { this.name = `resilient(${inner.name})`; + this.kind = inner.kind ?? (inner.name === "noop" ? "noop" : "llm"); } private async call(fn: () => Promise): Promise { diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 3c93ff6e78..2b2886f5f2 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -1,7 +1,7 @@ -import { TriggerAction, type ISdk, type ApiRequest } from "iii-sdk"; +import { TriggerAction, type ISdk, type ApiRequest, type EnqueueResult } from "iii-sdk"; import type { Session, CompressedObservation, HookPayload, CommitLink, SessionSummary } from "../types.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; -import { KV } from "../state/schema.js"; +import { KV, generateId } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; import { getLatestHealth } from "../health/monitor.js"; import type { MetricsStore } from "../eval/metrics-store.js"; @@ -21,6 +21,8 @@ import { isContextInjectionEnabled, detectEmbeddingProvider, detectLlmProviderKind, + getLlmExecutionState, + LLM_METRIC_FUNCTION_IDS, getAgentId, isAgentScopeIsolated, } from "../config.js"; @@ -31,6 +33,8 @@ type Response = { body: unknown; }; +export const OBSERVATION_QUEUE = "agentmemory-observations"; + function parseOptionalInt(raw: unknown): number | undefined { if (raw === undefined || raw === null || raw === "") return undefined; const n = typeof raw === "number" ? raw : parseInt(String(raw), 10); @@ -196,7 +200,7 @@ export function registerApiTriggers( kv: StateKV, secret?: string, metricsStore?: MetricsStore, - provider?: ResilientProvider | { circuitState?: unknown }, + provider?: ResilientProvider, ): void { sdk.registerFunction( "middleware::api-auth", @@ -236,6 +240,7 @@ export function registerApiTriggers( const authErr = checkAuth(req, secret); if (authErr) return authErr; const providerKind = detectLlmProviderKind(); + const llmExecutionState = getLlmExecutionState(provider); const embeddingProvider = detectEmbeddingProvider() ? "embeddings" : "none"; const flags = [ { @@ -288,6 +293,7 @@ export function registerApiTriggers( body: { version: VERSION, provider: providerKind, + llmExecutionState, embeddingProvider, flags, }, @@ -307,7 +313,14 @@ export function registerApiTriggers( sdk.registerFunction("api::health", async (req: ApiRequest): Promise => { const health = await getLatestHealth(kv); - const functionMetrics = metricsStore ? await metricsStore.getAll() : []; + const llmExecutionState = getLlmExecutionState(provider); + const functionMetrics = metricsStore + ? (await metricsStore.getAll()).map((metric) => + LLM_METRIC_FUNCTION_IDS.has(metric.functionId) + ? { ...metric, runtimeState: llmExecutionState } + : metric, + ) + : []; const circuitBreaker = provider && "circuitState" in provider ? provider.circuitState : null; @@ -324,6 +337,8 @@ export function registerApiTriggers( sourceRevision: process.env["AGENTMEMORY_SOURCE_REVISION"] || null, toolProfile: process.env["AGENTMEMORY_TOOLS"] || "all", llmToolsDisabled: process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"] === "true", + llmExecutionState, + llmProvider: provider?.name ?? null, health: health || null, functionMetrics, circuitBreaker, @@ -369,21 +384,37 @@ export function registerApiTriggers( const parsed = parseObserveRequest(req); if ("error" in parsed) return parsed.error; - // Desktop hooks intentionally have a very small process lifetime. Do not - // couple their HTTP caller to the full persistence/index/stream pipeline: - // if a hook exits while a synchronous invocation is still running, iii - // loses the caller but continues tracking the downstream invocation. - // Void acknowledges dispatch, then lets mem::observe finish under the - // engine's ownership instead of the hook process's lifetime. - await sdk.trigger({ - function_id: "mem::observe", - payload: parsed.payload, - action: TriggerAction.Void(), - }); - return { - status_code: 202, - body: { accepted: true, sessionId: parsed.payload.sessionId }, - }; + const observationId = generateId("obs"); + try { + const receipt = await sdk.trigger({ + function_id: "mem::observe", + payload: { ...parsed.payload, observationId }, + action: TriggerAction.Enqueue({ queue: OBSERVATION_QUEUE }), + }); + return { + status_code: 202, + body: { + accepted: true, + sessionId: parsed.payload.sessionId, + observationId, + messageReceiptId: receipt.messageReceiptId, + }, + }; + } catch (error) { + logger.error("Observation queue acceptance failed", { + sessionId: parsed.payload.sessionId, + observationId, + error: error instanceof Error ? error.message : String(error), + }); + return { + status_code: 503, + body: { + accepted: false, + retryable: true, + error: "observation_queue_unavailable", + }, + }; + } }, ); sdk.registerTrigger({ @@ -780,15 +811,6 @@ export function registerApiTriggers( sdk.registerFunction("api::summarize", async (req: ApiRequest<{ sessionId: string }>): Promise => { - if (detectLlmProviderKind() === "noop") { - return { - status_code: 503, - body: { - error: "summarization requires a configured LLM provider", - disabled: true, - }, - }; - } const sessionId = asNonEmptyString((req.body as Record)?.sessionId); if (!sessionId) { return { status_code: 400, body: { error: "sessionId is required" } }; diff --git a/src/triggers/events.ts b/src/triggers/events.ts index 598d79babc..c33d633d11 100644 --- a/src/triggers/events.ts +++ b/src/triggers/events.ts @@ -3,7 +3,7 @@ import type { CompressedObservation, HookPayload, Session } from "../types.js"; import { KV, STREAM } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; import { isReflectEnabled } from "../functions/slots.js"; -import { detectLlmProviderKind, isGraphExtractionEnabled } from "../config.js"; +import { isGraphExtractionEnabled } from "../config.js"; import { logger } from "../logger.js"; export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { @@ -61,9 +61,10 @@ export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { }); sdk.registerFunction("event::session::stopped", async (data: { sessionId: string }) => { - const summary = detectLlmProviderKind() === "noop" - ? { success: true, skipped: "no_llm_provider" } - : await sdk.trigger({ function_id: "mem::summarize", payload: data }); + const summary = await sdk.trigger({ + function_id: "mem::summarize", + payload: data, + }); if (isReflectEnabled()) { try { sdk.trigger({ diff --git a/src/types.ts b/src/types.ts index e76f190c22..9bbf01323b 100644 --- a/src/types.ts +++ b/src/types.ts @@ -141,6 +141,7 @@ export type HookType = export interface HookPayload { hookType: HookType; sessionId: string; + observationId?: string; project: string; cwd: string; repoRoot?: string; @@ -164,6 +165,7 @@ export type ProviderType = "agent-sdk" | "anthropic" | "gemini" | "openrouter" | export interface MemoryProvider { name: string; + kind?: "llm" | "noop"; compress(systemPrompt: string, userPrompt: string): Promise; summarize(systemPrompt: string, userPrompt: string): Promise; describeImage?(imageData: string, mimeType: string, prompt: string): Promise; @@ -207,8 +209,12 @@ export interface FunctionMetrics { totalCalls: number; successCount: number; failureCount: number; + skippedCount: number; avgLatencyMs: number; avgQualityScore: number; + lastOutcome?: "success" | "failure" | "skipped_disabled" | "skipped_unavailable"; + lastSkipReason?: "llm_tools_disabled" | "no_llm_provider"; + runtimeState?: "enabled" | "disabled" | "unavailable"; } export interface HealthSnapshot { diff --git a/src/viewer/index.html b/src/viewer/index.html index 7c392a7234..8053896350 100644 --- a/src/viewer/index.html +++ b/src/viewer/index.html @@ -1536,16 +1536,20 @@

agentmemory

if (fMetrics.length > 0) { var sorted = fMetrics.slice().sort(function(a, b) { return (b.totalCalls || 0) - (a.totalCalls || 0); }); html += '
Function Metrics (OTel)
'; - html += ''; + html += '
FunctionCallsSuccessFailAvg LatencyQuality
'; sorted.forEach(function(m) { - var successRate = m.totalCalls > 0 ? Math.round((m.successCount / m.totalCalls) * 100) : 0; - var rateColor = successRate >= 95 ? 'var(--green)' : successRate >= 80 ? 'var(--yellow)' : 'var(--red)'; + var executedCalls = (m.successCount || 0) + (m.failureCount || 0); + var successRate = executedCalls > 0 ? Math.round((m.successCount / executedCalls) * 100) : null; + var runtimeState = m.runtimeState || 'enabled'; + var stateMuted = runtimeState !== 'enabled'; + var rateColor = stateMuted || successRate === null ? 'var(--ink-faint)' : successRate >= 95 ? 'var(--green)' : successRate >= 80 ? 'var(--yellow)' : 'var(--red)'; var latencyColor = m.avgLatencyMs > 1000 ? 'var(--red)' : m.avgLatencyMs > 200 ? 'var(--yellow)' : 'var(--green)'; html += ''; - html += ''; + html += ''; html += ''; - html += ''; - html += ''; + html += ''; + html += ''; + html += ''; html += ''; html += ''; html += ''; diff --git a/test/api-llm-state.test.ts b/test/api-llm-state.test.ts new file mode 100644 index 0000000000..367f239b5f --- /dev/null +++ b/test/api-llm-state.test.ts @@ -0,0 +1,69 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { MetricsStore } from "../src/eval/metrics-store.js"; +import { registerSummarizeFunction } from "../src/functions/summarize.js"; +import { NoopProvider } from "../src/providers/noop.js"; +import { ResilientProvider } from "../src/providers/resilient.js"; +import { registerApiTriggers } from "../src/triggers/api.js"; +import { mockKV, mockSdk } from "./helpers/mocks.js"; + +const ORIGINAL_ENV = { ...process.env }; + +afterEach(() => { + process.env = { ...ORIGINAL_ENV }; +}); + +describe("LLM runtime state APIs", () => { + it("marks LLM metrics disabled and returns summarize as a non-error skip", async () => { + process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"] = "true"; + const sdk = mockSdk(); + const kv = mockKV(); + const metrics = new MetricsStore(kv as never); + await metrics.recordSkipped( + "mem::summarize", + 1, + "llm_tools_disabled", + ); + const provider = new ResilientProvider(new NoopProvider()); + registerSummarizeFunction(sdk as never, kv as never, provider, metrics); + registerApiTriggers( + sdk as never, + kv as never, + undefined, + metrics, + provider, + ); + + const health = (await sdk.trigger("api::health", { + headers: {}, + })) as { body: Record }; + const functionMetrics = health.body["functionMetrics"] as Array< + Record + >; + expect(health.body).toMatchObject({ + llmToolsDisabled: true, + llmExecutionState: "disabled", + llmProvider: "resilient(noop)", + }); + expect(functionMetrics).toContainEqual( + expect.objectContaining({ + functionId: "mem::summarize", + failureCount: 0, + skippedCount: 1, + runtimeState: "disabled", + }), + ); + + const summarize = await sdk.trigger("api::summarize", { + headers: {}, + body: { sessionId: "ses_disabled" }, + }); + expect(summarize).toEqual({ + status_code: 200, + body: { + success: true, + outcome: "skipped_disabled", + skipped: "llm_tools_disabled", + }, + }); + }); +}); diff --git a/test/api-observe-async.test.ts b/test/api-observe-async.test.ts index a3ee246064..08ae53d8e7 100644 --- a/test/api-observe-async.test.ts +++ b/test/api-observe-async.test.ts @@ -14,10 +14,12 @@ describe("Observe REST ingestion", () => { payload: unknown; action?: unknown; }>; + let rejectQueue: boolean; beforeEach(() => { sdk = mockSdk(); dispatched = []; + rejectQueue = false; const invokeRegistered = sdk.trigger.bind(sdk); sdk.trigger = vi.fn(async (request, data?: unknown) => { if ( @@ -25,8 +27,10 @@ describe("Observe REST ingestion", () => { request.function_id === "mem::observe" ) { dispatched.push(request); - // Model iii's acknowledgement of a void invocation. The observation - // pipeline itself is deliberately not part of the HTTP response path. + if (request.action && (request.action as { type?: string }).type === "enqueue") { + if (rejectQueue) throw new Error("queue store unavailable"); + return { messageReceiptId: "receipt-123" }; + } return undefined; } return invokeRegistered(request, data); @@ -35,7 +39,7 @@ describe("Observe REST ingestion", () => { registerApiTriggers(sdk as never, mockKV() as never); }); - it("acknowledges after dispatching observation work as a void invocation", async () => { + it("acknowledges only after the durable observation queue returns a receipt", async () => { const response = (await sdk.trigger("api::observe::async", { headers: {}, body: { @@ -48,17 +52,53 @@ describe("Observe REST ingestion", () => { }, })) as { status_code: number; - body: { accepted: boolean; sessionId: string }; + body: { + accepted: boolean; + sessionId: string; + observationId: string; + messageReceiptId: string; + }; }; - expect(response).toEqual({ + expect(response).toMatchObject({ status_code: 202, - body: { accepted: true, sessionId: "session-123" }, + body: { + accepted: true, + sessionId: "session-123", + messageReceiptId: "receipt-123", + }, }); + expect(response.body.observationId).toMatch(/^obs_/); expect(dispatched).toHaveLength(1); expect(dispatched[0]).toMatchObject({ function_id: "mem::observe", - action: { type: "void" }, + action: { type: "enqueue", queue: "agentmemory-observations" }, + payload: { observationId: response.body.observationId }, + }); + }); + + it("returns a retryable 503 when durable queue acceptance fails", async () => { + rejectQueue = true; + + const response = (await sdk.trigger("api::observe::async", { + headers: {}, + body: { + hookType: "post_tool_use", + sessionId: "session-queue-down", + project: "agentmemory", + cwd: "/repo/agentmemory", + timestamp: "2026-07-13T23:00:00Z", + data: { tool_name: "Read" }, + }, + })) as { status_code: number; body: unknown }; + + expect(response).toEqual({ + status_code: 503, + body: { + accepted: false, + retryable: true, + error: "observation_queue_unavailable", + }, }); }); diff --git a/test/auto-compress.test.ts b/test/auto-compress.test.ts index 9afe57431a..e2d50b4bb9 100644 --- a/test/auto-compress.test.ts +++ b/test/auto-compress.test.ts @@ -1,6 +1,8 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"; import type { RawObservation } from "../src/types.js"; +const ORIGINAL_ANTHROPIC_API_KEY = process.env["ANTHROPIC_API_KEY"]; + vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, })); @@ -80,9 +82,16 @@ describe("mem::observe auto-compress gate (#138)", () => { // state from an earlier test (and vice versa). vi.resetModules(); delete process.env["AGENTMEMORY_AUTO_COMPRESS"]; + delete process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"]; }); afterEach(() => { delete process.env["AGENTMEMORY_AUTO_COMPRESS"]; + delete process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"]; + if (ORIGINAL_ANTHROPIC_API_KEY === undefined) { + delete process.env["ANTHROPIC_API_KEY"]; + } else { + process.env["ANTHROPIC_API_KEY"] = ORIGINAL_ANTHROPIC_API_KEY; + } }); it("default (AGENTMEMORY_AUTO_COMPRESS unset): does NOT fire mem::compress", async () => { @@ -164,8 +173,86 @@ describe("mem::observe auto-compress gate (#138)", () => { ]); }); + it("makes a durable queue retry idempotent after the observation is complete", async () => { + const { registerObserveFunction } = await import( + "../src/functions/observe.js" + ); + const sdk = mockSdk(); + const kv = mockKV(); + registerObserveFunction(sdk as never, kv as never); + const payload = validPayload({ observationId: "obs_durable_retry_1" }); + + const first = (await sdk.trigger("mem::observe", payload)) as { + observationId: string; + }; + const second = (await sdk.trigger("mem::observe", payload)) as { + observationId: string; + deduplicated: boolean; + durableRetry: boolean; + }; + + expect(first.observationId).toBe("obs_durable_retry_1"); + expect(second).toEqual({ + observationId: "obs_durable_retry_1", + deduplicated: true, + durableRetry: true, + }); + expect(kv.store.get("mem:obs:ses_test")?.size).toBe(1); + }); + + it("resumes a durable retry after the raw write despite the duplicate filter", async () => { + const { registerObserveFunction } = await import( + "../src/functions/observe.js" + ); + const { DedupMap } = await import("../src/functions/dedup.js"); + const sdk = mockSdk(); + const kv = mockKV(); + const dedupMap = new DedupMap(); + const payload = validPayload({ observationId: "obs_partial_retry_1" }); + const toolData = payload.data as { + tool_name: string; + tool_input: unknown; + }; + const dedupHash = dedupMap.computeHash( + payload.sessionId as string, + toolData.tool_name, + toolData.tool_input, + ); + dedupMap.record(dedupHash); + await kv.set( + `mem:obs:${payload.sessionId}`, + "obs_partial_retry_1", + { + id: "obs_partial_retry_1", + sessionId: payload.sessionId, + timestamp: payload.timestamp, + hookType: payload.hookType, + raw: payload.data, + toolName: toolData.tool_name, + toolInput: toolData.tool_input, + toolOutput: "file contents here", + }, + ); + registerObserveFunction(sdk as never, kv as never, dedupMap); + + try { + const result = (await sdk.trigger("mem::observe", payload)) as { + observationId: string; + }; + const stored = kv.store + .get("mem:obs:ses_test") + ?.get("obs_partial_retry_1") as { title?: string }; + + expect(result.observationId).toBe("obs_partial_retry_1"); + expect(stored.title).toBe("Read"); + } finally { + dedupMap.stop(); + } + }); + it("AGENTMEMORY_AUTO_COMPRESS=true: fires mem::compress exactly once", async () => { process.env["AGENTMEMORY_AUTO_COMPRESS"] = "true"; + process.env["ANTHROPIC_API_KEY"] = "test-only-key"; const { registerObserveFunction } = await import( "../src/functions/observe.js" ); diff --git a/test/compress-disabled.test.ts b/test/compress-disabled.test.ts new file mode 100644 index 0000000000..1815f4d751 --- /dev/null +++ b/test/compress-disabled.test.ts @@ -0,0 +1,55 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { registerCompressFunction } from "../src/functions/compress.js"; +import type { MemoryProvider, RawObservation } from "../src/types.js"; +import { mockKV, mockSdk } from "./helpers/mocks.js"; + +const ORIGINAL_ENV = { ...process.env }; + +afterEach(() => { + process.env = { ...ORIGINAL_ENV }; +}); + +describe("mem::compress disabled outcomes", () => { + it("does not call the provider or increment failure metrics", async () => { + process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"] = "true"; + const provider: MemoryProvider = { + name: "test-provider", + kind: "llm", + compress: vi.fn(async () => "must not run"), + summarize: vi.fn(async () => "must not run"), + }; + const metricsStore = { recordSkipped: vi.fn(async () => undefined) }; + const sdk = mockSdk(); + registerCompressFunction( + sdk as never, + mockKV() as never, + provider, + metricsStore as never, + ); + const raw: RawObservation = { + id: "obs_disabled", + sessionId: "ses_disabled", + timestamp: "2026-07-14T00:00:00Z", + hookType: "post_tool_use", + raw: {}, + }; + + const result = await sdk.trigger("mem::compress", { + observationId: raw.id, + sessionId: raw.sessionId, + raw, + }); + + expect(result).toEqual({ + success: true, + outcome: "skipped_disabled", + skipped: "llm_tools_disabled", + }); + expect(provider.compress).not.toHaveBeenCalled(); + expect(metricsStore.recordSkipped).toHaveBeenCalledWith( + "mem::compress", + expect.any(Number), + "llm_tools_disabled", + ); + }); +}); diff --git a/test/env-loader.test.ts b/test/env-loader.test.ts index 17ff6a8e41..64c58928e5 100644 --- a/test/env-loader.test.ts +++ b/test/env-loader.test.ts @@ -44,6 +44,7 @@ describe("loadEnvFile", () => { writeEnv( [ "AGENTMEMORY_AUTO_COMPRESS=true # opt in to LLM compression", + "ANTHROPIC_API_KEY=test-only-key # provider availability", "CONSOLIDATION_ENABLED=true # daily summarization", "GRAPH_EXTRACTION_ENABLED=true # entity graph", ].join("\n"), diff --git a/test/llm-execution-state.test.ts b/test/llm-execution-state.test.ts new file mode 100644 index 0000000000..3ffe3349dd --- /dev/null +++ b/test/llm-execution-state.test.ts @@ -0,0 +1,39 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { + getLlmExecutionState, + isAutoCompressEnabled, +} from "../src/config.js"; +import { NoopProvider } from "../src/providers/noop.js"; +import { ResilientProvider } from "../src/providers/resilient.js"; + +const ORIGINAL_ENV = { ...process.env }; + +afterEach(() => { + process.env = { ...ORIGINAL_ENV }; +}); + +describe("LLM execution state", () => { + it("gives the explicit disable flag precedence over a real provider", () => { + process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"] = "true"; + + expect( + getLlmExecutionState({ name: "anthropic", kind: "llm" }), + ).toBe("disabled"); + }); + + it("recognizes a noop provider through the resilient wrapper", () => { + delete process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"]; + + expect( + getLlmExecutionState(new ResilientProvider(new NoopProvider())), + ).toBe("unavailable"); + }); + + it("prevents auto-compress from invoking disabled LLM operations", () => { + process.env["AGENTMEMORY_AUTO_COMPRESS"] = "true"; + process.env["ANTHROPIC_API_KEY"] = "test-only-key"; + process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"] = "true"; + + expect(isAutoCompressEnabled()).toBe(false); + }); +}); diff --git a/test/metrics-store.test.ts b/test/metrics-store.test.ts new file mode 100644 index 0000000000..74af745e56 --- /dev/null +++ b/test/metrics-store.test.ts @@ -0,0 +1,57 @@ +import { describe, expect, it } from "vitest"; +import { MetricsStore } from "../src/eval/metrics-store.js"; +import { KV } from "../src/state/schema.js"; +import { mockKV } from "./helpers/mocks.js"; + +describe("MetricsStore outcomes", () => { + it("normalizes legacy rows and records disabled calls as skipped", async () => { + const kv = mockKV(); + await kv.set(KV.metrics, "mem::summarize", { + functionId: "mem::summarize", + totalCalls: 4, + successCount: 1, + failureCount: 3, + avgLatencyMs: 10, + avgQualityScore: 80, + }); + const metrics = new MetricsStore(kv as never); + + await metrics.recordSkipped( + "mem::summarize", + 2, + "llm_tools_disabled", + ); + + expect(await metrics.get("mem::summarize")).toMatchObject({ + totalCalls: 5, + successCount: 1, + failureCount: 3, + skippedCount: 1, + lastOutcome: "skipped_disabled", + lastSkipReason: "llm_tools_disabled", + }); + }); + + it("serializes concurrent updates so skipped counts are not lost", async () => { + const metrics = new MetricsStore(mockKV() as never); + + await Promise.all( + Array.from({ length: 20 }, () => + metrics.recordSkipped( + "mem::compress", + 1, + "no_llm_provider", + ), + ), + ); + + expect(await metrics.get("mem::compress")).toMatchObject({ + totalCalls: 20, + successCount: 0, + failureCount: 0, + skippedCount: 20, + lastOutcome: "skipped_unavailable", + lastSkipReason: "no_llm_provider", + }); + }); +}); diff --git a/test/queue-config.test.ts b/test/queue-config.test.ts new file mode 100644 index 0000000000..91d9a3af85 --- /dev/null +++ b/test/queue-config.test.ts @@ -0,0 +1,18 @@ +import { readFileSync } from "node:fs"; +import { describe, expect, it } from "vitest"; + +describe.each([ + ["iii-config.yaml", "./data/queue_store"], + ["iii-config.docker.yaml", "/data/queue_store"], +])("%s observation queue", (configPath, queueStorePath) => { + it("uses a file-backed concurrent queue with retries and a DLQ", () => { + const config = readFileSync(configPath, "utf8"); + + expect(config).toContain("agentmemory-observations:"); + expect(config).toContain("max_retries: 5"); + expect(config).toContain("concurrency: 4"); + expect(config).toContain("type: standard"); + expect(config).toContain("store_method: file_based"); + expect(config).toContain(`file_path: ${queueStorePath}`); + }); +}); diff --git a/test/summarize.test.ts b/test/summarize.test.ts index 4723da8781..3f513a52c6 100644 --- a/test/summarize.test.ts +++ b/test/summarize.test.ts @@ -125,6 +125,7 @@ async function setupHandler(opts: { sessionId: string; obsCount: number; provider: MemoryProvider; + metricsStore?: { recordSkipped: Function }; }) { const sdk = mockSdk(); const kv = mockKV(); @@ -141,7 +142,12 @@ async function setupHandler(opts: { const o = makeObs(i, opts.sessionId); await kv.set(`obs:${opts.sessionId}`, o.id, o); } - registerSummarizeFunction(sdk as any, kv as any, opts.provider); + registerSummarizeFunction( + sdk as any, + kv as any, + opts.provider, + opts.metricsStore as any, + ); const handler = sdk.functions.get("mem::summarize")!; return { handler, kv }; } @@ -158,6 +164,32 @@ describe("mem::summarize chunking", () => { process.env = { ...ORIGINAL_ENV }; }); + it("records an explicit skipped-disabled outcome without calling the provider", async () => { + process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"] = "true"; + const provider = makeProvider([summaryXml({ title: "must not run" })]); + const metricsStore = { recordSkipped: vi.fn(async () => undefined) }; + const { handler } = await setupHandler({ + sessionId: "ses_disabled", + obsCount: 1, + provider, + metricsStore, + }); + + const result = await handler({ sessionId: "ses_disabled" }); + + expect(result).toEqual({ + success: true, + outcome: "skipped_disabled", + skipped: "llm_tools_disabled", + }); + expect(provider.calls).toHaveLength(0); + expect(metricsStore.recordSkipped).toHaveBeenCalledWith( + "mem::summarize", + expect.any(Number), + "llm_tools_disabled", + ); + }); + it("small session takes the single-call path (no chunking, no reduce)", async () => { const provider = makeProvider([ summaryXml({ From 3175343980644b51a1e43c9d73f90fc52b000595 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Mon, 13 Jul 2026 21:58:48 -0400 Subject: [PATCH 10/43] build: rebuild runtime before npm pack --- package.json | 1 + test/consistency.test.ts | 5 +++++ 2 files changed, 6 insertions(+) diff --git a/package.json b/package.json index 4e2bc8c4c3..669b9e11d5 100644 --- a/package.json +++ b/package.json @@ -18,6 +18,7 @@ }, "scripts": { "build": "tsdown && (cp iii-config.yaml dist/ 2>/dev/null || true) && (cp iii-config.docker.yaml dist/ 2>/dev/null || true) && (cp docker-compose.yml dist/ 2>/dev/null || true) && (cp .env.example dist/ 2>/dev/null || true) && mkdir -p dist/viewer && cp src/viewer/index.html dist/viewer/ && cp src/viewer/favicon.svg dist/viewer/", + "prepack": "npm run build", "dev": "tsx src/index.ts", "start": "node dist/cli.mjs", "migrate": "node dist/functions/migrate.js", diff --git a/test/consistency.test.ts b/test/consistency.test.ts index e0871cbf8e..086bb61a2a 100644 --- a/test/consistency.test.ts +++ b/test/consistency.test.ts @@ -29,6 +29,11 @@ describe("Consistency checks", () => { expect(VERSION).toBe(pkg.version); }); + it("rebuilds published runtime files before packing", () => { + const pkg = JSON.parse(readText("package.json")); + expect(pkg.scripts?.prepack).toBe("npm run build"); + }); + it("plugin.json version matches package.json", () => { const pkg = JSON.parse(readText("package.json")); const plugin = JSON.parse(readText("plugin/.claude-plugin/plugin.json")); From 87fda32ac7731e401489ed5d4878daeb9cf2bea7 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Mon, 13 Jul 2026 22:27:58 -0400 Subject: [PATCH 11/43] fix: prevent duplicate worker registration --- src/cli.ts | 21 +++++++++ src/index.ts | 32 ++++++------- src/worker-pidfile.ts | 77 ++++++++++++++++++++++++++++++++ test/stop-worker-pidfile.test.ts | 16 +++++-- test/worker-pidfile.test.ts | 53 ++++++++++++++++++++++ 5 files changed, 181 insertions(+), 18 deletions(-) create mode 100644 src/worker-pidfile.ts create mode 100644 test/worker-pidfile.test.ts diff --git a/src/cli.ts b/src/cli.ts index 6165f45989..2703dc5e44 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -1200,6 +1200,27 @@ async function main() { resetPrefs(); } + if (await isAgentmemoryReady()) { + p.log.info(c.ok(`agentmemory is already running at ${getBaseUrl()}`)); + return; + } + + const existingWorkerPid = readWorkerPidfile(); + if ( + existingWorkerPid !== null && + existingWorkerPid !== process.pid && + pidAlive(existingWorkerPid) + ) { + p.log.error( + `agentmemory worker pid ${existingWorkerPid} is already running, but its livez endpoint is unavailable. Refusing to register a duplicate worker.`, + ); + p.log.info( + "Restart the existing service or run `agentmemory stop` before starting another worker.", + ); + process.exitCode = 1; + return; + } + const firstRun = isFirstRun(); const prefs = readPrefs(); // Show the splash on the first run, on --reset, or whenever the user diff --git a/src/index.ts b/src/index.ts index 873bbf2dc0..f0bcf9bf1f 100644 --- a/src/index.ts +++ b/src/index.ts @@ -100,32 +100,34 @@ import { registerHealthMonitor } from "./health/monitor.js"; import { initMetrics, OTEL_CONFIG } from "./telemetry/setup.js"; import { VERSION } from "./version.js"; import { bootLog } from "./logger.js"; -import { mkdirSync, writeFileSync, unlinkSync } from "node:fs"; -import { dirname, join } from "node:path"; +import { + acquireWorkerPidfile, + releaseWorkerPidfile, + type WorkerPidfileLease, +} from "./worker-pidfile.js"; +import { join } from "node:path"; import { homedir } from "node:os"; // #640 + #474: the worker process (this file) is spawned by iii-exec // inside the engine. When `agentmemory stop` kills only the engine pid, // this worker can survive (detached spawn, signal not propagated, or a // wrapper script keeps it running) and reconnects to the next engine as -// a duplicate worker. Write the worker pid alongside iii.pid so -// `agentmemory stop` can reap us too. +// a duplicate worker. The exclusive pidfile is acquired before the SDK +// registers anything, so a second worker cannot later unregister the live +// worker's shared function and REST trigger IDs when it exits. function workerPidfilePath(): string { return join(homedir(), ".agentmemory", "worker.pid"); } -function writeWorkerPidfile(): void { - try { - const p = workerPidfilePath(); - mkdirSync(dirname(p), { recursive: true }); - writeFileSync(p, `${process.pid}\n`, { encoding: "utf-8" }); - } catch { - // best-effort; stop still has the engine pidfile + port scan fallback - } +let workerPidfileLease: WorkerPidfileLease | null = null; +function acquireWorkerPidfileLease(): void { + workerPidfileLease = acquireWorkerPidfile(workerPidfilePath()); } function clearWorkerPidfile(): void { + if (!workerPidfileLease) return; try { - unlinkSync(workerPidfilePath()); + releaseWorkerPidfile(workerPidfileLease); } catch {} + workerPidfileLease = null; } function hasGetMeter( @@ -159,6 +161,7 @@ process.on("unhandledRejection", (reason) => { }); async function main() { + acquireWorkerPidfileLease(); const config = loadConfig(); const embeddingConfig = loadEmbeddingConfig(); const fallbackConfig = loadFallbackConfig(); @@ -215,8 +218,6 @@ async function main() { }, }); - writeWorkerPidfile(); - const kv = new StateKV(sdk); const secret = getEnvVar("AGENTMEMORY_SECRET"); const metricsStore = new MetricsStore(kv); @@ -609,6 +610,7 @@ async function main() { } main().catch((err) => { + clearWorkerPidfile(); console.error(`[agentmemory] Fatal:`, err); process.exit(1); }); diff --git a/src/worker-pidfile.ts b/src/worker-pidfile.ts new file mode 100644 index 0000000000..1002a68f9b --- /dev/null +++ b/src/worker-pidfile.ts @@ -0,0 +1,77 @@ +import { + mkdirSync, + readFileSync, + unlinkSync, + writeFileSync, +} from "node:fs"; +import { dirname } from "node:path"; + +export interface WorkerPidfileLease { + path: string; + pid: number; +} + +type IsPidAlive = (pid: number) => boolean; + +function processIsAlive(pid: number): boolean { + try { + process.kill(pid, 0); + return true; + } catch (error) { + return (error as NodeJS.ErrnoException).code === "EPERM"; + } +} + +function readPid(path: string): number | null { + try { + const pid = Number.parseInt(readFileSync(path, "utf-8").trim(), 10); + return Number.isInteger(pid) && pid > 0 ? pid : null; + } catch { + return null; + } +} + +export function acquireWorkerPidfile( + path: string, + pid = process.pid, + isPidAlive: IsPidAlive = processIsAlive, +): WorkerPidfileLease { + mkdirSync(dirname(path), { recursive: true }); + + for (let attempt = 0; attempt < 2; attempt += 1) { + try { + writeFileSync(path, `${pid}\n`, { + encoding: "utf-8", + flag: "wx", + mode: 0o600, + }); + return { path, pid }; + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; + + const existingPid = readPid(path); + if (existingPid !== null && isPidAlive(existingPid)) { + throw new Error(`agentmemory worker already running (pid ${existingPid})`); + } + + try { + unlinkSync(path); + } catch (unlinkError) { + if ((unlinkError as NodeJS.ErrnoException).code !== "ENOENT") { + throw unlinkError; + } + } + } + } + + throw new Error(`could not acquire agentmemory worker pidfile: ${path}`); +} + +export function releaseWorkerPidfile(lease: WorkerPidfileLease): void { + if (readPid(lease.path) !== lease.pid) return; + try { + unlinkSync(lease.path); + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; + } +} diff --git a/test/stop-worker-pidfile.test.ts b/test/stop-worker-pidfile.test.ts index c70aaf1af9..9fa671488c 100644 --- a/test/stop-worker-pidfile.test.ts +++ b/test/stop-worker-pidfile.test.ts @@ -4,14 +4,18 @@ import { readFileSync } from "node:fs"; // #640 + #474: stop must also kill the worker process, not just the // iii engine. We expose the worker pidfile from src/index.ts and read it // from src/cli.ts. Static check that both files agree on the path -// (~/.agentmemory/worker.pid) and that stop reads it. +// (~/.agentmemory/worker.pid), acquire it before SDK registration, and +// ensure that stop reads it. describe("stop reaps the worker process (#640, #474)", () => { - it("src/index.ts writes worker.pid alongside iii.pid", () => { + it("src/index.ts acquires worker.pid before registering with iii", () => { const source = readFileSync("src/index.ts", "utf-8"); expect(source).toMatch(/workerPidfilePath\(\)/); expect(source).toMatch(/"worker\.pid"/); - expect(source).toMatch(/writeWorkerPidfile\(\)/); + expect(source).toMatch(/acquireWorkerPidfileLease\(\)/); expect(source).toMatch(/clearWorkerPidfile\(\)/); + expect(source).toMatch( + /async function main\(\) \{\s+acquireWorkerPidfileLease\(\);[\s\S]+registerWorker\(/, + ); }); it("src/cli.ts reads worker.pid in runStop and signals it on stop", () => { @@ -32,4 +36,10 @@ describe("stop reaps the worker process (#640, #474)", () => { expect(indexSrc).toMatch(/\.agentmemory["'].*worker\.pid|"worker\.pid"/); expect(cliSrc).toMatch(/\.agentmemory["'].*worker\.pid|"worker\.pid"/); }); + + it("default CLI startup exits before importing a duplicate worker", () => { + const source = readFileSync("src/cli.ts", "utf-8"); + expect(source).toMatch(/if \(await isAgentmemoryReady\(\)\)/); + expect(source).toMatch(/Refusing to register a duplicate worker/); + }); }); diff --git a/test/worker-pidfile.test.ts b/test/worker-pidfile.test.ts new file mode 100644 index 0000000000..3a004602c4 --- /dev/null +++ b/test/worker-pidfile.test.ts @@ -0,0 +1,53 @@ +import { mkdtempSync, readFileSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { describe, expect, it } from "vitest"; +import { + acquireWorkerPidfile, + releaseWorkerPidfile, +} from "../src/worker-pidfile.js"; + +function fixturePath(): string { + return join(mkdtempSync(join(tmpdir(), "agentmemory-worker-pid-")), "worker.pid"); +} + +describe("worker pidfile singleton lease", () => { + it("acquires and releases an exclusive pidfile", () => { + const path = fixturePath(); + const lease = acquireWorkerPidfile(path, 101, () => false); + + expect(readFileSync(path, "utf-8")).toBe("101\n"); + releaseWorkerPidfile(lease); + expect(() => readFileSync(path, "utf-8")).toThrow(); + }); + + it("rejects a second live worker without overwriting its pid", () => { + const path = fixturePath(); + writeFileSync(path, "202\n"); + + expect(() => acquireWorkerPidfile(path, 303, (pid) => pid === 202)).toThrow( + "agentmemory worker already running (pid 202)", + ); + expect(readFileSync(path, "utf-8")).toBe("202\n"); + }); + + it("reclaims a stale pidfile", () => { + const path = fixturePath(); + writeFileSync(path, "404\n"); + + const lease = acquireWorkerPidfile(path, 505, () => false); + + expect(readFileSync(path, "utf-8")).toBe("505\n"); + releaseWorkerPidfile(lease); + }); + + it("does not release a pidfile that changed ownership", () => { + const path = fixturePath(); + const lease = acquireWorkerPidfile(path, 606, () => false); + writeFileSync(path, "707\n"); + + releaseWorkerPidfile(lease); + + expect(readFileSync(path, "utf-8")).toBe("707\n"); + }); +}); From 073bf47d2381c7f2c360d412ecfb12b4c0b6e967 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Mon, 13 Jul 2026 22:56:17 -0400 Subject: [PATCH 12/43] feat: add stateless Streamable HTTP MCP transport --- .env.example | 5 + README.md | 22 +++ package.json | 2 + packages/mcp/README.md | 9 +- packages/mcp/bin.mjs | 12 +- src/cli.ts | 11 ++ src/mcp/http.ts | 410 +++++++++++++++++++++++++++++++++++++++++ test/mcp-http.test.ts | 260 ++++++++++++++++++++++++++ tsdown.config.ts | 7 + 9 files changed, 735 insertions(+), 3 deletions(-) create mode 100644 src/mcp/http.ts create mode 100644 test/mcp-http.test.ts diff --git a/.env.example b/.env.example index 9ff441a298..b11ae78052 100644 --- a/.env.example +++ b/.env.example @@ -128,6 +128,11 @@ # AGENTMEMORY_URL=http://localhost:3111 # REST base URL — honored by status, doctor, MCP shim # AGENTMEMORY_VIEWER_URL=http://localhost:3113 # Override the viewer URL printed by `agentmemory status` # AGENTMEMORY_EXPORT_ROOT=~/agentmemory-backup # Default destination for `agentmemory export` +# AGENTMEMORY_MCP_HTTP_HOST=127.0.0.1 # Streamable HTTP MCP bind host +# AGENTMEMORY_MCP_HTTP_PORT=3114 # Streamable HTTP MCP port +# AGENTMEMORY_MCP_HTTP_TOKEN=your-secret # Optional bearer token for the MCP listener +# AGENTMEMORY_MCP_HTTP_ALLOWED_ORIGINS=http://127.0.0.1:7681 # Extra comma-separated browser origins +# AGENTMEMORY_MCP_HTTP_ALLOW_REMOTE=1 # Required with a bearer token for non-loopback binds # STANDALONE_MCP=1 # MCP shim only — bypass the worker and run @agentmemory/mcp in-process # STANDALONE_PERSIST_PATH=~/.agentmemory/local.db # Path used by the standalone MCP shim's local fallback store diff --git a/README.md b/README.md index a71d1a8c3e..1ca87d6734 100644 --- a/README.md +++ b/README.md @@ -1067,6 +1067,28 @@ Most agents (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI): Merge the `agentmemory` entry into your host's existing `mcpServers` object rather than replacing the file. For sandboxed clients that can't reach the host's `localhost`, add `"AGENTMEMORY_FORCE_PROXY": "1"` to the env block and set `AGENTMEMORY_URL` to a route the sandbox can reach. +#### Streamable HTTP MCP + +For clients that keep long-lived sessions, run the stateless Streamable HTTP bridge next to the full AgentMemory server: + +```bash +agentmemory mcp-http +# http://127.0.0.1:3114/mcp +``` + +The bridge creates a fresh MCP transport for every request and proxies every tool call to the existing AgentMemory REST server, so reconnects do not create a second memory store. It binds to loopback by default and validates browser origins. `AGENTMEMORY_SECRET` authenticates the bridge to the engine; the loopback MCP listener is unauthenticated unless you separately set `AGENTMEMORY_MCP_HTTP_TOKEN`. + +Codex example (`~/.codex/config.toml`): + +```toml +[mcp_servers.agentmemory] +url = "http://127.0.0.1:3114/mcp" +``` + +If you set `AGENTMEMORY_MCP_HTTP_TOKEN`, expose that same value to the client through a dedicated environment variable and add `bearer_token_env_var` to the client configuration. + +Use `AGENTMEMORY_MCP_HTTP_HOST`, `AGENTMEMORY_MCP_HTTP_PORT`, and `AGENTMEMORY_MCP_HTTP_ALLOWED_ORIGINS` to override the listener. A non-loopback bind is rejected unless `AGENTMEMORY_MCP_HTTP_ALLOW_REMOTE=1` and a bearer token are both configured. + OpenCode (`opencode.json`): ```json { diff --git a/package.json b/package.json index 669b9e11d5..8d19d3e687 100644 --- a/package.json +++ b/package.json @@ -11,6 +11,7 @@ "import": "./dist/index.mjs" }, "./dist/standalone.mjs": "./dist/standalone.mjs", + "./dist/http.mjs": "./dist/http.mjs", "./package.json": "./package.json" }, "bin": { @@ -61,6 +62,7 @@ "url": "https://github.com/rohitg00/agentmemory" }, "dependencies": { + "@modelcontextprotocol/sdk": "^1.29.0", "@anthropic-ai/claude-agent-sdk": "^0.3.142", "@anthropic-ai/sdk": "^0.100.1", "@clack/prompts": "^1.2.0", diff --git a/packages/mcp/README.md b/packages/mcp/README.md index abd57a752a..21480c6e70 100644 --- a/packages/mcp/README.md +++ b/packages/mcp/README.md @@ -13,6 +13,13 @@ without installing the full package first. npx -y @agentmemory/mcp ``` +To expose the running AgentMemory engine through a stateless Streamable HTTP endpoint instead of stdio: + +```bash +npx -y @agentmemory/mcp --http +# http://127.0.0.1:3114/mcp +``` + Or wire it into your MCP client (Claude Desktop, OpenClaw, Cursor, Codex, etc.): ```json @@ -34,7 +41,7 @@ installed, you can call the same entrypoint directly: npx @agentmemory/agentmemory mcp ``` -Both commands do the same thing. +The two stdio commands do the same thing. The `--http` form requires the full AgentMemory engine at `AGENTMEMORY_URL` and never creates a separate local fallback store. Set `AGENTMEMORY_SECRET` for bridge-to-engine authentication and, independently, `AGENTMEMORY_MCP_HTTP_TOKEN` if the MCP listener itself should require a bearer token. ## Why does this package exist? diff --git a/packages/mcp/bin.mjs b/packages/mcp/bin.mjs index 7df452d56e..971f04d9d3 100755 --- a/packages/mcp/bin.mjs +++ b/packages/mcp/bin.mjs @@ -1,7 +1,15 @@ #!/usr/bin/env node -import("@agentmemory/agentmemory/dist/standalone.mjs").catch((err) => { +const entrypoint = process.argv.slice(2).some((arg) => arg === "--http" || arg === "http") + ? "@agentmemory/agentmemory/dist/http.mjs" + : "@agentmemory/agentmemory/dist/standalone.mjs"; + +import(entrypoint).then(async (module) => { + if (entrypoint.endsWith("/http.mjs")) { + await module.runMcpHttpServer(); + } +}).catch((err) => { console.error( - "[@agentmemory/mcp] Failed to load standalone entrypoint from @agentmemory/agentmemory.", + `[@agentmemory/mcp] Failed to load ${entrypoint} from @agentmemory/agentmemory.`, ); console.error( "[@agentmemory/mcp] Try installing manually: npm i -g @agentmemory/agentmemory", diff --git a/src/cli.ts b/src/cli.ts index 2703dc5e44..bf8b6b4261 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -182,6 +182,7 @@ Commands: the engine was started natively but state file is missing). mcp Start standalone MCP shim — opt-in surface for MCP-only clients (Cursor, Gemini CLI, etc). REST always available at :3111. + mcp-http Start stateless Streamable HTTP MCP bridge on 127.0.0.1:3114/mcp. import-jsonl [p] Import Claude Code JSONL transcripts (default: ~/.claude/projects) --max-files | --max-files=: override scan cap (default 200, max 1000; out-of-range is rejected; for trees >1000 files, batch by subdirectory) @@ -203,6 +204,9 @@ Options: Environment: AGENTMEMORY_URL Full REST base URL (e.g. http://localhost:3111). Honored by status, doctor, and MCP shim commands. + AGENTMEMORY_MCP_HTTP_HOST Streamable HTTP bind host (default 127.0.0.1). + AGENTMEMORY_MCP_HTTP_PORT Streamable HTTP port (default 3114). + AGENTMEMORY_MCP_HTTP_TOKEN Optional bearer token for the MCP listener. AGENTMEMORY_USE_DOCKER=1 Prefer the bundled docker-compose path over the native iii-engine binary on first run. AGENTMEMORY_III_VERSION Override pinned iii-engine version (default ${IIPINNED_VERSION}). @@ -217,6 +221,7 @@ Quick start: npx @agentmemory/agentmemory status # health + memory count + flags npx @agentmemory/agentmemory upgrade # upgrade agentmemory + iii runtime npx @agentmemory/agentmemory mcp # standalone MCP server (no engine) + npx @agentmemory/agentmemory mcp-http # loopback Streamable HTTP MCP bridge npx @agentmemory/mcp # same as above (shim package) `); process.exit(0); @@ -2673,6 +2678,11 @@ async function runMcp(): Promise { await import("./mcp/standalone.js"); } +async function runMcpHttp(): Promise { + const { runMcpHttpServer } = await import("./mcp/http.js"); + await runMcpHttpServer(); +} + async function runConnectCmd(): Promise { const { runConnect } = await import("./cli/connect/index.js"); await runConnect(args.slice(1)); @@ -3006,6 +3016,7 @@ const commands: Record Promise> = { stop: runStop, remove: runRemove, mcp: runMcp, + "mcp-http": runMcpHttp, "import-jsonl": runImportJsonl, }; diff --git a/src/mcp/http.ts b/src/mcp/http.ts new file mode 100644 index 0000000000..a0ee592530 --- /dev/null +++ b/src/mcp/http.ts @@ -0,0 +1,410 @@ +#!/usr/bin/env node + +import { + createServer as createNodeServer, + type IncomingMessage, + type Server as NodeServer, + type ServerResponse, +} from "node:http"; +import { pathToFileURL } from "node:url"; +import { resolve } from "node:path"; +import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js"; +import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; +import { + CallToolRequestSchema, + ListToolsRequestSchema, + type CallToolResult, + type Tool, +} from "@modelcontextprotocol/sdk/types.js"; +import { timingSafeCompare } from "../auth.js"; +import { VERSION } from "../version.js"; +import { resolveEnvOrEmpty } from "./rest-proxy.js"; + +const DEFAULT_ENGINE_URL = "http://127.0.0.1:3111"; +const DEFAULT_HOST = "127.0.0.1"; +const DEFAULT_PORT = 3114; +const BACKEND_TIMEOUT_MS = 15_000; + +export interface McpHttpBackend { + health: () => Promise; + listTools: () => Promise<{ tools: Tool[] }>; + callTool: ( + name: string, + args: Record, + ) => Promise; +} + +export interface McpHttpOptions { + host?: string; + port?: number; + path?: string; + token?: string; + allowedOrigins?: string[]; + allowRemote?: boolean; + backend?: McpHttpBackend; +} + +function positivePort(value: string | undefined, fallback: number): number { + const parsed = Number(value); + return Number.isInteger(parsed) && parsed > 0 && parsed <= 65_535 + ? parsed + : fallback; +} + +function isLoopbackHost(host: string): boolean { + const normalized = host.toLowerCase().replace(/^\[|\]$/g, ""); + return ( + normalized === "localhost" || + normalized === "127.0.0.1" || + normalized === "::1" + ); +} + +function isWildcardHost(host: string): boolean { + const normalized = host.toLowerCase().replace(/^\[|\]$/g, ""); + return normalized === "0.0.0.0" || normalized === "::"; +} + +function parseAllowedOrigins(raw: string): string[] { + return raw + .split(",") + .map((value) => value.trim().replace(/\/$/, "")) + .filter(Boolean); +} + +function normalizeOptions(options: McpHttpOptions = {}): Required< + Omit +> & { backend: McpHttpBackend } { + const host = options.host ?? ( + resolveEnvOrEmpty("AGENTMEMORY_MCP_HTTP_HOST") || DEFAULT_HOST + ); + const port = options.port ?? positivePort( + resolveEnvOrEmpty("AGENTMEMORY_MCP_HTTP_PORT"), + DEFAULT_PORT, + ); + const token = options.token ?? resolveEnvOrEmpty("AGENTMEMORY_MCP_HTTP_TOKEN"); + const allowedOrigins = options.allowedOrigins ?? parseAllowedOrigins( + resolveEnvOrEmpty("AGENTMEMORY_MCP_HTTP_ALLOWED_ORIGINS"), + ); + const allowRemote = options.allowRemote ?? ["1", "true"].includes( + resolveEnvOrEmpty("AGENTMEMORY_MCP_HTTP_ALLOW_REMOTE").toLowerCase(), + ); + + if (!isLoopbackHost(host) && (!allowRemote || !token)) { + throw new Error( + "Non-loopback MCP HTTP binds require AGENTMEMORY_MCP_HTTP_ALLOW_REMOTE=1 and a bearer token", + ); + } + + return { + host, + port, + path: options.path ?? "/mcp", + token, + allowedOrigins, + allowRemote, + backend: options.backend ?? createProxyBackend(), + }; +} + +function engineHeaders(): Record { + const secret = resolveEnvOrEmpty("AGENTMEMORY_SECRET"); + return { + "content-type": "application/json", + ...(secret ? { authorization: `Bearer ${secret}` } : {}), + }; +} + +export function createProxyBackend(options: { + baseUrl?: string; + fetchImpl?: typeof fetch; +} = {}): McpHttpBackend { + const baseUrl = ( + options.baseUrl ?? ( + resolveEnvOrEmpty("AGENTMEMORY_URL") || DEFAULT_ENGINE_URL + ) + ).replace(/\/+$/, ""); + const fetchImpl = options.fetchImpl ?? fetch; + + async function request(path: string, init: RequestInit): Promise { + const response = await fetchImpl(`${baseUrl}${path}`, { + ...init, + headers: { ...engineHeaders(), ...(init.headers ?? {}) }, + signal: AbortSignal.timeout(BACKEND_TIMEOUT_MS), + }); + if (!response.ok) { + throw new Error( + `${init.method ?? "GET"} ${path} -> ${response.status} ${response.statusText}`, + ); + } + const text = await response.text(); + return text ? JSON.parse(text) : null; + } + + return { + async health() { + try { + const response = await fetchImpl(`${baseUrl}/agentmemory/livez`, { + method: "GET", + headers: engineHeaders(), + signal: AbortSignal.timeout(2_000), + }); + return response.ok; + } catch { + return false; + } + }, + async listTools() { + const result = await request("/agentmemory/mcp/tools", { method: "GET" }); + if ( + !result || + typeof result !== "object" || + !Array.isArray((result as { tools?: unknown }).tools) + ) { + throw new Error("AgentMemory returned an invalid tools/list payload"); + } + return { tools: (result as { tools: Tool[] }).tools }; + }, + async callTool(name, args) { + const result = await request("/agentmemory/mcp/call", { + method: "POST", + body: JSON.stringify({ name, arguments: args }), + }); + if ( + !result || + typeof result !== "object" || + !Array.isArray((result as { content?: unknown }).content) + ) { + throw new Error("AgentMemory returned an invalid tools/call payload"); + } + return result as CallToolResult; + }, + }; +} + +export function createProtocolServer(backend: McpHttpBackend): McpServer { + const server = new McpServer( + { name: "agentmemory", version: VERSION }, + { capabilities: { tools: { listChanged: false } } }, + ); + + server.setRequestHandler(ListToolsRequestSchema, async () => backend.listTools()); + server.setRequestHandler(CallToolRequestSchema, async (request) => { + try { + return await backend.callTool( + request.params.name, + request.params.arguments ?? {}, + ); + } catch (error) { + return { + content: [ + { + type: "text", + text: `Error: ${error instanceof Error ? error.message : String(error)}`, + }, + ], + isError: true, + }; + } + }); + + return server; +} + +function hostHeaderAllowed(hostHeader: string | undefined, host: string): boolean { + if (!hostHeader) return false; + try { + const requested = new URL(`http://${hostHeader}`).hostname; + if (isLoopbackHost(host)) return isLoopbackHost(requested); + if (isWildcardHost(host)) return true; + return requested.toLowerCase() === host.toLowerCase(); + } catch { + return false; + } +} + +function originAllowed( + origin: string | undefined, + host: string, + allowedOrigins: string[], +): boolean { + if (!origin) return true; + const normalized = origin.replace(/\/$/, ""); + if (allowedOrigins.includes(normalized)) return true; + try { + return isLoopbackHost(host) && isLoopbackHost(new URL(normalized).hostname); + } catch { + return false; + } +} + +function sendJson( + response: ServerResponse, + statusCode: number, + body: unknown, + headers: Record = {}, +): void { + response.writeHead(statusCode, { + "content-type": "application/json", + "cache-control": "no-store", + ...headers, + }); + response.end(JSON.stringify(body)); +} + +function sendProtocolError( + response: ServerResponse, + statusCode: number, + message: string, + headers: Record = {}, +): void { + sendJson( + response, + statusCode, + { + jsonrpc: "2.0", + error: { code: -32000, message }, + id: null, + }, + headers, + ); +} + +export function createMcpHttpHandler( + rawOptions: McpHttpOptions = {}, +): (request: IncomingMessage, response: ServerResponse) => Promise { + const options = normalizeOptions(rawOptions); + + return async (request, response) => { + const url = new URL(request.url ?? "/", "http://localhost"); + + if (url.pathname === "/healthz") { + const upstream = await options.backend.health(); + sendJson(response, upstream ? 200 : 503, { + status: upstream ? "ok" : "degraded", + transport: "streamable-http", + upstream, + }); + return; + } + + if (url.pathname !== options.path) { + sendProtocolError(response, 404, "Not found"); + return; + } + + if (!hostHeaderAllowed(request.headers.host, options.host)) { + sendProtocolError(response, 403, "Forbidden host"); + return; + } + + const origin = Array.isArray(request.headers.origin) + ? request.headers.origin[0] + : request.headers.origin; + if (!originAllowed(origin, options.host, options.allowedOrigins)) { + sendProtocolError(response, 403, "Forbidden origin"); + return; + } + + if (options.token) { + const authorization = request.headers.authorization ?? ""; + if (!timingSafeCompare(authorization, `Bearer ${options.token}`)) { + sendProtocolError(response, 401, "Unauthorized", { + "www-authenticate": "Bearer", + }); + return; + } + } + + if (request.method !== "POST") { + sendProtocolError(response, 405, "Method not allowed", { allow: "POST" }); + return; + } + + const protocol = createProtocolServer(options.backend); + const transport = new StreamableHTTPServerTransport({ + sessionIdGenerator: undefined, + }); + let closed = false; + const close = () => { + if (closed) return; + closed = true; + void protocol.close().catch(() => {}); + }; + response.once("close", close); + + try { + await protocol.connect(transport); + await transport.handleRequest(request, response); + } catch (error) { + close(); + if (!response.headersSent) { + sendProtocolError( + response, + 500, + error instanceof Error ? error.message : "Internal server error", + ); + } + } + }; +} + +export async function startMcpHttpServer( + rawOptions: McpHttpOptions = {}, +): Promise { + const options = normalizeOptions(rawOptions); + const handler = createMcpHttpHandler(options); + const server = createNodeServer((request, response) => { + void handler(request, response).catch((error) => { + if (!response.headersSent) { + sendProtocolError( + response, + 500, + error instanceof Error ? error.message : "Internal server error", + ); + } else { + response.destroy(error instanceof Error ? error : undefined); + } + }); + }); + + await new Promise((resolveListen, rejectListen) => { + server.once("error", rejectListen); + server.listen(options.port, options.host, () => { + server.off("error", rejectListen); + resolveListen(); + }); + }); + + return server; +} + +export async function runMcpHttpServer(): Promise { + const host = resolveEnvOrEmpty("AGENTMEMORY_MCP_HTTP_HOST") || DEFAULT_HOST; + const port = positivePort( + resolveEnvOrEmpty("AGENTMEMORY_MCP_HTTP_PORT"), + DEFAULT_PORT, + ); + const server = await startMcpHttpServer({ host, port }); + process.stderr.write( + `[@agentmemory/mcp] Streamable HTTP server v${VERSION} listening on http://${host}:${port}/mcp\n`, + ); + + const shutdown = () => { + server.close(() => process.exit(0)); + }; + process.once("SIGINT", shutdown); + process.once("SIGTERM", shutdown); +} + +const entrypoint = process.argv[1] + ? pathToFileURL(resolve(process.argv[1])).href + : ""; +if (entrypoint === import.meta.url) { + void runMcpHttpServer().catch((error) => { + process.stderr.write( + `[@agentmemory/mcp] HTTP server failed: ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`, + ); + process.exit(1); + }); +} diff --git a/test/mcp-http.test.ts b/test/mcp-http.test.ts new file mode 100644 index 0000000000..cc9b9b9047 --- /dev/null +++ b/test/mcp-http.test.ts @@ -0,0 +1,260 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import type { AddressInfo } from "node:net"; +import type { Server as NodeServer } from "node:http"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; +import { + createProxyBackend, + startMcpHttpServer, + type McpHttpBackend, +} from "../src/mcp/http.js"; + +const servers: NodeServer[] = []; + +afterEach(async () => { + await Promise.all( + servers.splice(0).map( + (server) => new Promise((resolve) => server.close(() => resolve())), + ), + ); +}); + +async function fixture(token = "test-token") { + const calls: Array<{ name: string; args: Record }> = []; + const backend: McpHttpBackend = { + health: async () => true, + listTools: async () => ({ + tools: [ + { + name: "memory_next", + description: "Read the next shared action", + inputSchema: { + type: "object", + properties: { project: { type: "string" } }, + required: ["project"], + }, + }, + ], + }), + callTool: async (name, args) => { + calls.push({ name, args }); + return { + content: [{ type: "text", text: JSON.stringify({ ok: true, name, args }) }], + }; + }, + }; + const server = await startMcpHttpServer({ + host: "127.0.0.1", + port: 0, + token, + backend, + }); + servers.push(server); + const address = server.address() as AddressInfo; + return { + calls, + baseUrl: `http://127.0.0.1:${address.port}`, + }; +} + +async function connect(baseUrl: string, token: string | null = "test-token") { + const client = new Client({ name: "agentmemory-http-test", version: "1.0.0" }); + const transport = new StreamableHTTPClientTransport( + new URL(`${baseUrl}/mcp`), + { + requestInit: token + ? { headers: { authorization: `Bearer ${token}` } } + : undefined, + }, + ); + await client.connect(transport); + return client; +} + +describe("AgentMemory Streamable HTTP transport", () => { + it("serves tools through the official stateless MCP client", async () => { + const { baseUrl, calls } = await fixture(); + const client = await connect(baseUrl); + + const listed = await client.listTools(); + expect(listed.tools.map((tool) => tool.name)).toEqual(["memory_next"]); + + const called = await client.callTool({ + name: "memory_next", + arguments: { project: "workstation" }, + }); + expect(called.isError).not.toBe(true); + expect(calls).toEqual([ + { name: "memory_next", args: { project: "workstation" } }, + ]); + + await client.close(); + }); + + it("allows a fresh client to reconnect without server session state", async () => { + const { baseUrl, calls } = await fixture(); + const first = await connect(baseUrl); + await first.callTool({ name: "memory_next", arguments: { project: "one" } }); + await first.close(); + + const second = await connect(baseUrl); + await second.callTool({ name: "memory_next", arguments: { project: "two" } }); + await second.close(); + + expect(calls.map((call) => call.args.project)).toEqual(["one", "two"]); + }); + + it("does not require listener auth when its explicit token is empty", async () => { + const { baseUrl } = await fixture(""); + const client = await connect(baseUrl, null); + + expect((await client.listTools()).tools[0]?.name).toBe("memory_next"); + + await client.close(); + }); + + it("rejects missing bearer credentials and hostile browser origins", async () => { + const { baseUrl } = await fixture(); + const body = JSON.stringify({ + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { + protocolVersion: "2025-11-25", + capabilities: {}, + clientInfo: { name: "raw-test", version: "1.0.0" }, + }, + }); + + const unauthorized = await fetch(`${baseUrl}/mcp`, { + method: "POST", + headers: { "content-type": "application/json" }, + body, + }); + expect(unauthorized.status).toBe(401); + expect(unauthorized.headers.get("www-authenticate")).toBe("Bearer"); + + const hostileOrigin = await fetch(`${baseUrl}/mcp`, { + method: "POST", + headers: { + authorization: "Bearer test-token", + "content-type": "application/json", + origin: "https://attacker.example", + }, + body, + }); + expect(hostileOrigin.status).toBe(403); + }); + + it("allows an explicitly authenticated wildcard bind without trusting hostile origins", async () => { + const calls: Array<{ name: string; args: Record }> = []; + const backend: McpHttpBackend = { + health: async () => true, + listTools: async () => ({ + tools: [{ + name: "memory_next", + description: "next", + inputSchema: { type: "object", properties: {} }, + }], + }), + callTool: async (name, args) => { + calls.push({ name, args }); + return { content: [{ type: "text", text: "ok" }] }; + }, + }; + await expect(startMcpHttpServer({ + host: "0.0.0.0", + port: 0, + allowRemote: true, + token: "", + backend, + })).rejects.toThrow(/bearer token/); + + const server = await startMcpHttpServer({ + host: "0.0.0.0", + port: 0, + allowRemote: true, + token: "remote-test-token", + backend, + }); + servers.push(server); + const address = server.address() as AddressInfo; + const baseUrl = `http://127.0.0.1:${address.port}`; + const client = await connect(baseUrl, "remote-test-token"); + + expect((await client.listTools()).tools[0]?.name).toBe("memory_next"); + await client.close(); + + const hostile = await fetch(`${baseUrl}/mcp`, { + method: "POST", + headers: { + authorization: "Bearer remote-test-token", + "content-type": "application/json", + origin: "https://attacker.example", + }, + body: "{}", + }); + expect(hostile.status).toBe(403); + expect(calls).toEqual([]); + }); + + it("keeps health separate and returns 405 for MCP GET", async () => { + const { baseUrl } = await fixture(); + const health = await fetch(`${baseUrl}/healthz`); + expect(health.status).toBe(200); + expect(await health.json()).toMatchObject({ + status: "ok", + transport: "streamable-http", + upstream: true, + }); + + const get = await fetch(`${baseUrl}/mcp`, { + headers: { authorization: "Bearer test-token" }, + }); + expect(get.status).toBe(405); + expect(get.headers.get("allow")).toBe("POST"); + }); + + it("proxies list and call requests to the existing engine surface", async () => { + const fetchImpl = vi.fn(async (url: string | URL, init?: RequestInit) => { + const path = new URL(String(url)).pathname; + if (path === "/agentmemory/livez") { + return new Response(JSON.stringify({ status: "ok" }), { status: 200 }); + } + if (path === "/agentmemory/mcp/tools") { + return new Response( + JSON.stringify({ + tools: [ + { + name: "memory_next", + description: "next", + inputSchema: { type: "object", properties: {} }, + }, + ], + }), + { status: 200 }, + ); + } + expect(path).toBe("/agentmemory/mcp/call"); + expect(init?.method).toBe("POST"); + expect(JSON.parse(String(init?.body))).toEqual({ + name: "memory_next", + arguments: { project: "workstation" }, + }); + return new Response( + JSON.stringify({ content: [{ type: "text", text: "ok" }] }), + { status: 200 }, + ); + }); + const backend = createProxyBackend({ + baseUrl: "http://127.0.0.1:3111", + fetchImpl: fetchImpl as typeof fetch, + }); + + expect(await backend.health()).toBe(true); + expect((await backend.listTools()).tools[0]?.name).toBe("memory_next"); + expect( + await backend.callTool("memory_next", { project: "workstation" }), + ).toEqual({ content: [{ type: "text", text: "ok" }] }); + }); +}); diff --git a/tsdown.config.ts b/tsdown.config.ts index 5cf108468f..17e66d2daa 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -68,6 +68,13 @@ export default defineConfig([ clean: false, sourcemap: false, }, + { + entry: ["src/mcp/http.ts"], + outDir: "dist", + ...shared, + clean: false, + sourcemap: false, + }, // One entry per config block prevents tsdown from hoisting shared // helpers into hashed chunks across hooks. ...hookEntries.map((entry) => ({ From 26b5062e7908ec59477932e8390b6afa4c478893 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Thu, 16 Jul 2026 11:26:28 -0400 Subject: [PATCH 13/43] fix invocation bookkeeping leak --- AGENTS.md | 8 +++++ src/functions/compress.ts | 3 +- src/functions/disk-size-manager.ts | 6 ++-- src/functions/image-quota-cleanup.ts | 6 ++-- src/functions/image-refs.ts | 6 ++-- src/functions/observe.ts | 34 ++++++++++---------- src/functions/remember.ts | 3 +- src/triggers/api.ts | 17 +++++----- src/triggers/events.ts | 35 ++++++++++----------- src/utils/trigger-detached.ts | 23 ++++++++++++++ test/detached-trigger.test.ts | 41 +++++++++++++++++++++++++ test/session-end-triggers-graph.test.ts | 10 +++--- 12 files changed, 129 insertions(+), 63 deletions(-) create mode 100644 src/utils/trigger-detached.ts create mode 100644 test/detached-trigger.test.ts diff --git a/AGENTS.md b/AGENTS.md index b5ea4f027a..48ecb9b013 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,6 +57,14 @@ sdk.registerFunction( ); ``` +### Detached Function Calls + +While `iii-sdk` is pinned to 0.11.2, do not use `TriggerAction.Void()`. That +engine path adds a generated ID to the worker's active invocation set, while +the SDK deliberately sends no `InvocationResult` that could remove it. Use +`triggerDetached()` from `src/utils/trigger-detached.ts` for non-blocking work; +use a normal awaited `sdk.trigger()` when the caller needs the result. + ### REST Endpoint Registration ```typescript sdk.registerFunction("api::your-endpoint", async (req: ApiRequest) => { diff --git a/src/functions/compress.ts b/src/functions/compress.ts index f868f0ce3f..1350b28d20 100644 --- a/src/functions/compress.ts +++ b/src/functions/compress.ts @@ -1,4 +1,4 @@ -import { TriggerAction, type ISdk } from "iii-sdk"; +import type { ISdk } from "iii-sdk"; import { readFileSync } from "node:fs"; import { isManagedImagePath } from "../utils/image-store.js"; import type { @@ -242,7 +242,6 @@ export function registerCompressFunction( sessionId: data.sessionId, }, }, - action: TriggerAction.Void(), }), ]); for (const result of streamResults) { diff --git a/src/functions/disk-size-manager.ts b/src/functions/disk-size-manager.ts index 0905e83c3e..682f129e96 100644 --- a/src/functions/disk-size-manager.ts +++ b/src/functions/disk-size-manager.ts @@ -1,10 +1,11 @@ -import { TriggerAction, type ISdk } from "iii-sdk"; +import type { ISdk } from "iii-sdk"; import { KV } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; import { getMaxBytes } from "../utils/image-store.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import { logger } from "../logger.js"; import type { StateScope, StateScopeKey } from "../types.js"; +import { triggerDetached } from "../utils/trigger-detached.js"; const DISK_SIZE_KEY: StateScopeKey = "system:currentDiskSize"; @@ -26,10 +27,9 @@ export function registerDiskSizeManager(sdk: ISdk, kv: StateKV): void { await kv.set(KV.state, DISK_SIZE_KEY, newTotal); if (data.deltaBytes > 0 && newTotal > getMaxBytes()) { - sdk.trigger({ + triggerDetached(sdk, { function_id: "mem::image-quota-cleanup", payload: {}, - action: TriggerAction.Void(), }); logger.info("Disk quota exceeded, cleanup triggered", { currentBytes: newTotal, diff --git a/src/functions/image-quota-cleanup.ts b/src/functions/image-quota-cleanup.ts index d07dfa9698..92028a3f85 100644 --- a/src/functions/image-quota-cleanup.ts +++ b/src/functions/image-quota-cleanup.ts @@ -1,4 +1,4 @@ -import { TriggerAction, type ISdk } from "iii-sdk"; +import type { ISdk } from "iii-sdk"; import { KV } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; import { readdir, stat } from "node:fs/promises"; @@ -6,6 +6,7 @@ import { join } from "node:path"; import { IMAGES_DIR, getMaxBytes, deleteImage } from "../utils/image-store.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import { logger } from "../logger.js"; +import { triggerDetached } from "../utils/trigger-detached.js"; const GRACE_PERIOD_MS = 30_000; @@ -75,10 +76,9 @@ export function registerImageQuotaCleanup(sdk: ISdk, kv: StateKV): void { const { deletedBytes } = await deleteImage(f.filePath); if (deletedBytes > 0) { - sdk.trigger({ + triggerDetached(sdk, { function_id: "mem::disk-size-delta", payload: { deltaBytes: -deletedBytes }, - action: TriggerAction.Void(), }); totalToFree -= deletedBytes; freedBytes += deletedBytes; diff --git a/src/functions/image-refs.ts b/src/functions/image-refs.ts index ce1661df42..60d91adf84 100644 --- a/src/functions/image-refs.ts +++ b/src/functions/image-refs.ts @@ -1,8 +1,9 @@ -import { TriggerAction, type ISdk } from "iii-sdk"; +import type { ISdk } from "iii-sdk"; import { KV } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; import { deleteImage, touchImage } from "../utils/image-store.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; +import { triggerDetached } from "../utils/trigger-detached.js"; export async function getImageRefCount(kv: StateKV, filePath: string): Promise { const count = await kv.get(KV.imageRefs, filePath); @@ -25,10 +26,9 @@ export async function decrementImageRef(kv: StateKV, sdk: ISdk, filePath: string await kv.delete(KV.imageRefs, filePath); const { deletedBytes } = await deleteImage(filePath); if (deletedBytes > 0) { - sdk.trigger({ + triggerDetached(sdk, { function_id: "mem::disk-size-delta", payload: { deltaBytes: -deletedBytes }, - action: TriggerAction.Void(), }); } } else { diff --git a/src/functions/observe.ts b/src/functions/observe.ts index 128694b7de..2ec4bde99f 100644 --- a/src/functions/observe.ts +++ b/src/functions/observe.ts @@ -1,4 +1,4 @@ -import { TriggerAction, type ISdk } from "iii-sdk"; +import type { ISdk } from "iii-sdk"; import type { RawObservation, HookPayload, Session } from "../types.js"; import { KV, STREAM, generateId } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; @@ -12,6 +12,7 @@ import { getAgentId } from "../config.js"; import { logger } from "../logger.js"; import { saveImageToDisk } from "../utils/image-store.js"; import { safeAudit } from "./audit.js"; +import { triggerDetached } from "../utils/trigger-detached.js"; const SESSION_CONTEXT_FIELDS = [ "project", @@ -203,20 +204,18 @@ export function registerObserveFunction( raw.imageData = filePath; const { incrementImageRef } = await import("./image-refs.js"); await incrementImageRef(kv, filePath); - sdk.trigger({ + triggerDetached(sdk, { function_id: "mem::disk-size-delta", payload: { deltaBytes: bytesWritten }, - action: TriggerAction.Void(), }); if (process.env["AGENTMEMORY_IMAGE_EMBEDDINGS"] === "true") { - sdk.trigger({ + triggerDetached(sdk, { function_id: "mem::vision-embed", payload: { imageRef: filePath, sessionId: payload.sessionId, observationId: obsId, }, - action: TriggerAction.Void(), }); } } @@ -261,7 +260,7 @@ export function registerObserveFunction( }, }); - await sdk.trigger({ + triggerDetached(sdk, { function_id: "stream::send", payload: { stream_name: STREAM.name, @@ -270,7 +269,6 @@ export function registerObserveFunction( type: "raw_observation", data: { type: "raw", observation: raw, sessionId: payload.sessionId }, }, - action: TriggerAction.Void(), }); } @@ -370,15 +368,18 @@ export function registerObserveFunction( // and BM25 search still work without burning the user's Claude // token allocation on every tool invocation. if (isAutoCompressEnabled()) { - await sdk.trigger({ - function_id: "mem::compress", - payload: { - observationId: obsId, - sessionId: payload.sessionId, - raw, + triggerDetached( + sdk, + { + function_id: "mem::compress", + payload: { + observationId: obsId, + sessionId: payload.sessionId, + raw, + }, }, - action: TriggerAction.Void(), - }); + { sessionId: payload.sessionId, observationId: obsId }, + ); } else { const synthetic = buildSyntheticCompression(raw); await kv.set( @@ -402,7 +403,7 @@ export function registerObserveFunction( data: { type: "compressed", observation: synthetic }, }, }); - await sdk.trigger({ + triggerDetached(sdk, { function_id: "stream::send", payload: { stream_name: STREAM.name, @@ -415,7 +416,6 @@ export function registerObserveFunction( sessionId: payload.sessionId, }, }, - action: TriggerAction.Void(), }); } diff --git a/src/functions/remember.ts b/src/functions/remember.ts index 5735b4f238..0621989486 100644 --- a/src/functions/remember.ts +++ b/src/functions/remember.ts @@ -1,4 +1,4 @@ -import { TriggerAction, type ISdk } from "iii-sdk"; +import type { ISdk } from "iii-sdk"; import type { Memory } from "../types.js"; import { KV, generateId, jaccardSimilarity } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; @@ -153,7 +153,6 @@ export function registerRememberFunction(sdk: ISdk, kv: StateKV): void { payload: { supersededMemoryId: supersededId, }, - action: TriggerAction.Void(), }); } diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 2b2886f5f2..d562e5eb11 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -14,6 +14,7 @@ import { getBoundViewerPort, getViewerSkipped } from "../viewer/server.js"; import { MAX_FILES_UPPER_BOUND } from "../functions/replay.js"; import { logger } from "../logger.js"; import { selectSessionPage } from "../functions/session-list.js"; +import { triggerDetached } from "../utils/trigger-detached.js"; import { isGraphExtractionEnabled, isConsolidationEnabled, @@ -784,18 +785,14 @@ export function registerApiTriggers( { type: "set", path: "status", value: "completed" }, ]); // Fan out session-stopped lifecycle (non-blocking). - try { - sdk.trigger({ + triggerDetached( + sdk, + { function_id: "event::session::stopped", payload: { sessionId }, - action: TriggerAction.Void(), - }); - } catch (err) { - logger.warn("event::session::stopped trigger failed", { - sessionId, - error: err instanceof Error ? err.message : String(err), - }); - } + }, + { sessionId }, + ); return { status_code: 200, body: { success: true } }; }, ); diff --git a/src/triggers/events.ts b/src/triggers/events.ts index c33d633d11..09e3d3a9b2 100644 --- a/src/triggers/events.ts +++ b/src/triggers/events.ts @@ -1,10 +1,11 @@ -import { TriggerAction, type ISdk } from "iii-sdk"; +import type { ISdk } from "iii-sdk"; import type { CompressedObservation, HookPayload, Session } from "../types.js"; import { KV, STREAM } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; import { isReflectEnabled } from "../functions/slots.js"; import { isGraphExtractionEnabled } from "../config.js"; import { logger } from "../logger.js"; +import { triggerDetached } from "../utils/trigger-detached.js"; export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { sdk.registerFunction( @@ -66,18 +67,14 @@ export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { payload: data, }); if (isReflectEnabled()) { - try { - sdk.trigger({ + triggerDetached( + sdk, + { function_id: "mem::slot-reflect", payload: { sessionId: data.sessionId }, - action: TriggerAction.Void(), - }); - } catch (err) { - logger.warn("slot-reflect trigger failed", { - sessionId: data.sessionId, - error: err instanceof Error ? err.message : String(err), - }); - } + }, + { sessionId: data.sessionId }, + ); } if (isGraphExtractionEnabled()) { try { @@ -86,11 +83,14 @@ export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { ); const compressed = observations.filter((o) => o.title); if (compressed.length > 0) { - sdk.trigger({ - function_id: "mem::graph-extract", - payload: { observations: compressed }, - action: TriggerAction.Void(), - }); + triggerDetached( + sdk, + { + function_id: "mem::graph-extract", + payload: { observations: compressed }, + }, + { sessionId: data.sessionId }, + ); } } catch (err) { logger.warn("graph-extract trigger failed", { @@ -137,7 +137,7 @@ export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { const newCount = payload.new_value?.observationCount ?? 0; if (newCount <= oldCount) return { skipped: true }; - await sdk.trigger({ + triggerDetached(sdk, { function_id: "stream::send", payload: { stream_name: STREAM.name, @@ -151,7 +151,6 @@ export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { updatedAt: payload.new_value?.updatedAt ?? new Date().toISOString(), }, }, - action: TriggerAction.Void(), }); return { emitted: true }; diff --git a/src/utils/trigger-detached.ts b/src/utils/trigger-detached.ts new file mode 100644 index 0000000000..a166990347 --- /dev/null +++ b/src/utils/trigger-detached.ts @@ -0,0 +1,23 @@ +import type { ISdk, TriggerRequest } from "iii-sdk"; +import { logger } from "../logger.js"; + +type TrackedTriggerRequest = Omit, "action"> & { + action?: never; +}; + +// iii-engine 0.11.2 tracks action:void work in the worker's invocation set but +// intentionally receives no InvocationResult to remove it. A regular trigger +// keeps the caller non-blocking while preserving the cleanup acknowledgement. +export function triggerDetached( + sdk: Pick, + request: TrackedTriggerRequest, + context: Record = {}, +): void { + void sdk.trigger(request).catch((error: unknown) => { + logger.warn("Detached trigger failed", { + functionId: request.function_id, + ...context, + error: error instanceof Error ? error.message : String(error), + }); + }); +} diff --git a/test/detached-trigger.test.ts b/test/detached-trigger.test.ts new file mode 100644 index 0000000000..e72c503424 --- /dev/null +++ b/test/detached-trigger.test.ts @@ -0,0 +1,41 @@ +import { readFileSync, readdirSync, statSync } from "node:fs"; +import { resolve } from "node:path"; +import { describe, expect, it, vi } from "vitest"; +import type { ISdk } from "iii-sdk"; + +import { triggerDetached } from "../src/utils/trigger-detached.js"; + +function sourceFiles(dir: string): string[] { + return readdirSync(dir).flatMap((entry) => { + const path = resolve(dir, entry); + return statSync(path).isDirectory() + ? sourceFiles(path) + : path.endsWith(".ts") + ? [path] + : []; + }); +} + +describe("tracked detached triggers", () => { + it("starts a normal invocation without waiting for its result", () => { + const trigger = vi.fn(async () => ({ success: true })); + + triggerDetached( + { trigger } as unknown as Pick, + { function_id: "mem::example", payload: { id: "one" } }, + ); + + expect(trigger).toHaveBeenCalledWith({ + function_id: "mem::example", + payload: { id: "one" }, + }); + }); + + it("does not allow the iii 0.11.2 void-action leak back into source", () => { + const offenders = sourceFiles(resolve(__dirname, "..", "src")).filter( + (path) => readFileSync(path, "utf8").includes("TriggerAction.Void()"), + ); + + expect(offenders).toEqual([]); + }); +}); diff --git a/test/session-end-triggers-graph.test.ts b/test/session-end-triggers-graph.test.ts index 22a780432c..ce97f6181a 100644 --- a/test/session-end-triggers-graph.test.ts +++ b/test/session-end-triggers-graph.test.ts @@ -6,9 +6,9 @@ import { readFileSync } from "node:fs"; // fix the `event::session::stopped` handler in events.ts was a dead // subscriber — no code published `agentmemory.session.stopped`, so graph // nodes / lessons / crystals never materialized despite the handler -// existing. Direct fire-and-forget trigger keeps the HTTP response fast -// (kv.update runs synchronously, downstream pipeline fan-outs without -// blocking). +// existing. A tracked detached trigger keeps the HTTP response fast while +// still returning an InvocationResult that iii-engine 0.11.2 needs to clear +// the worker's active-invocation bookkeeping. describe("api::session::end → event::session::stopped (#666)", () => { const api = readFileSync("src/triggers/api.ts", "utf-8"); @@ -24,9 +24,9 @@ describe("api::session::end → event::session::stopped (#666)", () => { ); }); - it("event::session::stopped uses TriggerAction.Void for fire-and-forget", () => { + it("event::session::stopped uses a tracked detached invocation", () => { expect(api).toMatch( - /function_id:\s*"event::session::stopped"[\s\S]*?action:\s*TriggerAction\.Void\(\)/, + /triggerDetached\([\s\S]*?function_id:\s*"event::session::stopped"/, ); }); }); From 2e0b8e6f3e3216063f045591852263443e3bf45b Mon Sep 17 00:00:00 2001 From: wrightpt Date: Thu, 16 Jul 2026 11:37:41 -0400 Subject: [PATCH 14/43] chore: refresh generated skill reference --- plugin/skills/agentmemory-config/REFERENCE.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md index e0757e6619..fded47a1ef 100644 --- a/plugin/skills/agentmemory-config/REFERENCE.md +++ b/plugin/skills/agentmemory-config/REFERENCE.md @@ -3,7 +3,7 @@ Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded. -Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 46 recognized variables: +Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 51 recognized variables: - `AGENTMEMORY_AGENT_SCOPE` - `AGENTMEMORY_ALLOW_AGENT_SDK` @@ -31,6 +31,11 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e - `AGENTMEMORY_MAX_PROMPT_CAPTURE_CHARS` - `AGENTMEMORY_MAX_TOOL_CAPTURE_CHARS` - `AGENTMEMORY_MCP_BLOCK` +- `AGENTMEMORY_MCP_HTTP_ALLOWED_ORIGINS` +- `AGENTMEMORY_MCP_HTTP_ALLOW_REMOTE` +- `AGENTMEMORY_MCP_HTTP_HOST` +- `AGENTMEMORY_MCP_HTTP_PORT` +- `AGENTMEMORY_MCP_HTTP_TOKEN` - `AGENTMEMORY_PROBE_TIMEOUT_MS` - `AGENTMEMORY_PROJECT_NAME` - `AGENTMEMORY_PROVIDER` From 2f17da8a3241586c2c8b4e38a9c5a9d6132fba35 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Thu, 16 Jul 2026 11:56:24 -0400 Subject: [PATCH 15/43] fix hooks: bound project scope traversal --- src/hooks/_project.ts | 21 ++++++++++++++++----- test/hook-project.test.ts | 22 +++++++++++++++++++++- 2 files changed, 37 insertions(+), 6 deletions(-) diff --git a/src/hooks/_project.ts b/src/hooks/_project.ts index cdd83294dc..d161177168 100644 --- a/src/hooks/_project.ts +++ b/src/hooks/_project.ts @@ -1,5 +1,5 @@ import { execFileSync } from "node:child_process"; -import { existsSync, readFileSync } from "node:fs"; +import { existsSync, readFileSync, realpathSync } from "node:fs"; import { basename, dirname, parse, resolve } from "node:path"; export interface ProjectContext { @@ -35,14 +35,25 @@ function git(cwd: string, args: string[]): string { } } +function canonicalExistingPath(path: string): string { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} + function nearestProjectFile(cwd: string, boundary?: string): string | undefined { - let current = resolve(cwd); - const root = boundary ? resolve(boundary) : parse(current).root; + let current = canonicalExistingPath(cwd); + const filesystemRoot = parse(current).root; + const root = boundary ? canonicalExistingPath(boundary) : filesystemRoot; while (true) { const candidate = resolve(current, ".agentmemory", "project.json"); if (existsSync(candidate)) return candidate; - if (current === root) return undefined; - current = dirname(current); + if (current === root || current === filesystemRoot) return undefined; + const parent = dirname(current); + if (parent === current) return undefined; + current = parent; } } diff --git a/test/hook-project.test.ts b/test/hook-project.test.ts index c0479691ce..de7101ccb4 100644 --- a/test/hook-project.test.ts +++ b/test/hook-project.test.ts @@ -1,5 +1,5 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest"; -import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { execFileSync } from "node:child_process"; @@ -100,4 +100,24 @@ describe("resolveProject — hook project basename resolver", () => { rmSync(dir, { recursive: true, force: true }); } }); + + it("handles a symlinked cwd whose git root has a canonical path", () => { + const dir = mkdtempSync(join(tmpdir(), "amem-symlink-root-")); + const repo = join(dir, "repo"); + const alias = join(dir, "repo-alias"); + try { + mkdirSync(repo); + execFileSync("git", ["init", "-q", repo]); + execFileSync("git", ["-C", repo, "remote", "add", "origin", "git@github.com:owner/stable-project.git"]); + symlinkSync(repo, alias, "dir"); + + expect(resolveProjectContext(alias)).toMatchObject({ + project: "stable-project", + repoRoot: repo, + worktree: repo, + }); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); }); From 65b233c97d2d96ab277208ec7d99749baa4cac21 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Thu, 16 Jul 2026 11:58:20 -0400 Subject: [PATCH 16/43] chore: refresh generated hook scripts --- plugin/scripts/notification.mjs | 20 +++++++++++++++----- plugin/scripts/post-tool-failure.mjs | 20 +++++++++++++++----- plugin/scripts/post-tool-use.mjs | 20 +++++++++++++++----- plugin/scripts/pre-compact.mjs | 20 +++++++++++++++----- plugin/scripts/prompt-submit.mjs | 20 +++++++++++++++----- plugin/scripts/session-start.mjs | 20 +++++++++++++++----- plugin/scripts/subagent-start.mjs | 20 +++++++++++++++----- plugin/scripts/subagent-stop.mjs | 20 +++++++++++++++----- plugin/scripts/task-completed.mjs | 20 +++++++++++++++----- 9 files changed, 135 insertions(+), 45 deletions(-) diff --git a/plugin/scripts/notification.mjs b/plugin/scripts/notification.mjs index 68ae166345..0084ea1db9 100755 --- a/plugin/scripts/notification.mjs +++ b/plugin/scripts/notification.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node import { execFileSync } from "node:child_process"; -import { existsSync, readFileSync } from "node:fs"; +import { existsSync, readFileSync, realpathSync } from "node:fs"; import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts function git(cwd, args) { @@ -18,14 +18,24 @@ function git(cwd, args) { return ""; } } +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} function nearestProjectFile(cwd, boundary) { - let current = resolve(cwd); - const root = boundary ? resolve(boundary) : parse(current).root; + let current = canonicalExistingPath(cwd); + const filesystemRoot = parse(current).root; + const root = boundary ? canonicalExistingPath(boundary) : filesystemRoot; while (true) { const candidate = resolve(current, ".agentmemory", "project.json"); if (existsSync(candidate)) return candidate; - if (current === root) return void 0; - current = dirname(current); + if (current === root || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; } } function readProjectFile(cwd, boundary) { diff --git a/plugin/scripts/post-tool-failure.mjs b/plugin/scripts/post-tool-failure.mjs index d9dbeb7d71..640c782c38 100755 --- a/plugin/scripts/post-tool-failure.mjs +++ b/plugin/scripts/post-tool-failure.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node import { execFileSync } from "node:child_process"; -import { existsSync, readFileSync } from "node:fs"; +import { existsSync, readFileSync, realpathSync } from "node:fs"; import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts function git(cwd, args) { @@ -18,14 +18,24 @@ function git(cwd, args) { return ""; } } +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} function nearestProjectFile(cwd, boundary) { - let current = resolve(cwd); - const root = boundary ? resolve(boundary) : parse(current).root; + let current = canonicalExistingPath(cwd); + const filesystemRoot = parse(current).root; + const root = boundary ? canonicalExistingPath(boundary) : filesystemRoot; while (true) { const candidate = resolve(current, ".agentmemory", "project.json"); if (existsSync(candidate)) return candidate; - if (current === root) return void 0; - current = dirname(current); + if (current === root || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; } } function readProjectFile(cwd, boundary) { diff --git a/plugin/scripts/post-tool-use.mjs b/plugin/scripts/post-tool-use.mjs index 12538c2aa8..b602c97a5a 100755 --- a/plugin/scripts/post-tool-use.mjs +++ b/plugin/scripts/post-tool-use.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node import { execFileSync } from "node:child_process"; -import { existsSync, readFileSync } from "node:fs"; +import { existsSync, readFileSync, realpathSync } from "node:fs"; import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts function git(cwd, args) { @@ -18,14 +18,24 @@ function git(cwd, args) { return ""; } } +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} function nearestProjectFile(cwd, boundary) { - let current = resolve(cwd); - const root = boundary ? resolve(boundary) : parse(current).root; + let current = canonicalExistingPath(cwd); + const filesystemRoot = parse(current).root; + const root = boundary ? canonicalExistingPath(boundary) : filesystemRoot; while (true) { const candidate = resolve(current, ".agentmemory", "project.json"); if (existsSync(candidate)) return candidate; - if (current === root) return void 0; - current = dirname(current); + if (current === root || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; } } function readProjectFile(cwd, boundary) { diff --git a/plugin/scripts/pre-compact.mjs b/plugin/scripts/pre-compact.mjs index 917818485c..c3be22d835 100755 --- a/plugin/scripts/pre-compact.mjs +++ b/plugin/scripts/pre-compact.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node import { execFileSync } from "node:child_process"; -import { existsSync, readFileSync } from "node:fs"; +import { existsSync, readFileSync, realpathSync } from "node:fs"; import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts function git(cwd, args) { @@ -18,14 +18,24 @@ function git(cwd, args) { return ""; } } +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} function nearestProjectFile(cwd, boundary) { - let current = resolve(cwd); - const root = boundary ? resolve(boundary) : parse(current).root; + let current = canonicalExistingPath(cwd); + const filesystemRoot = parse(current).root; + const root = boundary ? canonicalExistingPath(boundary) : filesystemRoot; while (true) { const candidate = resolve(current, ".agentmemory", "project.json"); if (existsSync(candidate)) return candidate; - if (current === root) return void 0; - current = dirname(current); + if (current === root || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; } } function readProjectFile(cwd, boundary) { diff --git a/plugin/scripts/prompt-submit.mjs b/plugin/scripts/prompt-submit.mjs index 289ed52de3..1a831dd6c2 100755 --- a/plugin/scripts/prompt-submit.mjs +++ b/plugin/scripts/prompt-submit.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node import { execFileSync } from "node:child_process"; -import { existsSync, readFileSync } from "node:fs"; +import { existsSync, readFileSync, realpathSync } from "node:fs"; import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts function git(cwd, args) { @@ -18,14 +18,24 @@ function git(cwd, args) { return ""; } } +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} function nearestProjectFile(cwd, boundary) { - let current = resolve(cwd); - const root = boundary ? resolve(boundary) : parse(current).root; + let current = canonicalExistingPath(cwd); + const filesystemRoot = parse(current).root; + const root = boundary ? canonicalExistingPath(boundary) : filesystemRoot; while (true) { const candidate = resolve(current, ".agentmemory", "project.json"); if (existsSync(candidate)) return candidate; - if (current === root) return void 0; - current = dirname(current); + if (current === root || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; } } function readProjectFile(cwd, boundary) { diff --git a/plugin/scripts/session-start.mjs b/plugin/scripts/session-start.mjs index 449e1b27c4..5875c3c576 100755 --- a/plugin/scripts/session-start.mjs +++ b/plugin/scripts/session-start.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node import { execFileSync } from "node:child_process"; -import { existsSync, readFileSync } from "node:fs"; +import { existsSync, readFileSync, realpathSync } from "node:fs"; import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts function git(cwd, args) { @@ -18,14 +18,24 @@ function git(cwd, args) { return ""; } } +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} function nearestProjectFile(cwd, boundary) { - let current = resolve(cwd); - const root = boundary ? resolve(boundary) : parse(current).root; + let current = canonicalExistingPath(cwd); + const filesystemRoot = parse(current).root; + const root = boundary ? canonicalExistingPath(boundary) : filesystemRoot; while (true) { const candidate = resolve(current, ".agentmemory", "project.json"); if (existsSync(candidate)) return candidate; - if (current === root) return void 0; - current = dirname(current); + if (current === root || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; } } function readProjectFile(cwd, boundary) { diff --git a/plugin/scripts/subagent-start.mjs b/plugin/scripts/subagent-start.mjs index c2a17e3c5c..9dab7f9d29 100755 --- a/plugin/scripts/subagent-start.mjs +++ b/plugin/scripts/subagent-start.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node import { execFileSync } from "node:child_process"; -import { existsSync, readFileSync } from "node:fs"; +import { existsSync, readFileSync, realpathSync } from "node:fs"; import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts function git(cwd, args) { @@ -18,14 +18,24 @@ function git(cwd, args) { return ""; } } +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} function nearestProjectFile(cwd, boundary) { - let current = resolve(cwd); - const root = boundary ? resolve(boundary) : parse(current).root; + let current = canonicalExistingPath(cwd); + const filesystemRoot = parse(current).root; + const root = boundary ? canonicalExistingPath(boundary) : filesystemRoot; while (true) { const candidate = resolve(current, ".agentmemory", "project.json"); if (existsSync(candidate)) return candidate; - if (current === root) return void 0; - current = dirname(current); + if (current === root || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; } } function readProjectFile(cwd, boundary) { diff --git a/plugin/scripts/subagent-stop.mjs b/plugin/scripts/subagent-stop.mjs index 243438ce00..d002786abf 100755 --- a/plugin/scripts/subagent-stop.mjs +++ b/plugin/scripts/subagent-stop.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node import { execFileSync } from "node:child_process"; -import { existsSync, readFileSync } from "node:fs"; +import { existsSync, readFileSync, realpathSync } from "node:fs"; import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts function git(cwd, args) { @@ -18,14 +18,24 @@ function git(cwd, args) { return ""; } } +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} function nearestProjectFile(cwd, boundary) { - let current = resolve(cwd); - const root = boundary ? resolve(boundary) : parse(current).root; + let current = canonicalExistingPath(cwd); + const filesystemRoot = parse(current).root; + const root = boundary ? canonicalExistingPath(boundary) : filesystemRoot; while (true) { const candidate = resolve(current, ".agentmemory", "project.json"); if (existsSync(candidate)) return candidate; - if (current === root) return void 0; - current = dirname(current); + if (current === root || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; } } function readProjectFile(cwd, boundary) { diff --git a/plugin/scripts/task-completed.mjs b/plugin/scripts/task-completed.mjs index d6078fd638..d1f1e6048a 100755 --- a/plugin/scripts/task-completed.mjs +++ b/plugin/scripts/task-completed.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node import { execFileSync } from "node:child_process"; -import { existsSync, readFileSync } from "node:fs"; +import { existsSync, readFileSync, realpathSync } from "node:fs"; import { basename, dirname, parse, resolve } from "node:path"; //#region src/hooks/_project.ts function git(cwd, args) { @@ -18,14 +18,24 @@ function git(cwd, args) { return ""; } } +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} function nearestProjectFile(cwd, boundary) { - let current = resolve(cwd); - const root = boundary ? resolve(boundary) : parse(current).root; + let current = canonicalExistingPath(cwd); + const filesystemRoot = parse(current).root; + const root = boundary ? canonicalExistingPath(boundary) : filesystemRoot; while (true) { const candidate = resolve(current, ".agentmemory", "project.json"); if (existsSync(candidate)) return candidate; - if (current === root) return void 0; - current = dirname(current); + if (current === root || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; } } function readProjectFile(cwd, boundary) { From 52fb63c7ab5bbb6a46e685db487311640cc3f5c3 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Thu, 16 Jul 2026 12:01:44 -0400 Subject: [PATCH 17/43] test: compare canonical project paths --- test/hook-project.test.ts | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/test/hook-project.test.ts b/test/hook-project.test.ts index de7101ccb4..8bcc8ab3f8 100644 --- a/test/hook-project.test.ts +++ b/test/hook-project.test.ts @@ -1,5 +1,12 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest"; -import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { + mkdirSync, + mkdtempSync, + realpathSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { execFileSync } from "node:child_process"; @@ -95,7 +102,7 @@ describe("resolveProject — hook project basename resolver", () => { execFileSync("git", ["init", "-q", dir]); execFileSync("git", ["-C", dir, "remote", "add", "origin", "git@github.com:owner/stable-project.git"]); expect(resolveProject(dir)).toBe("stable-project"); - expect(resolveProjectContext(dir).worktree).toBe(dir); + expect(resolveProjectContext(dir).worktree).toBe(realpathSync.native(dir)); } finally { rmSync(dir, { recursive: true, force: true }); } @@ -113,8 +120,8 @@ describe("resolveProject — hook project basename resolver", () => { expect(resolveProjectContext(alias)).toMatchObject({ project: "stable-project", - repoRoot: repo, - worktree: repo, + repoRoot: realpathSync.native(repo), + worktree: realpathSync.native(repo), }); } finally { rmSync(dir, { recursive: true, force: true }); From 27b2eeeb71c80470d4821349acb9e3b0adcdacc7 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Fri, 17 Jul 2026 01:03:05 -0400 Subject: [PATCH 18/43] fix(actions): exclude blocked work from frontier --- src/functions/frontier.ts | 2 +- test/frontier.test.ts | 34 ++++++++++++++++++++++++++++++++-- 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/src/functions/frontier.ts b/src/functions/frontier.ts index 30f43fec60..4b3a3842fc 100644 --- a/src/functions/frontier.ts +++ b/src/functions/frontier.ts @@ -45,7 +45,7 @@ export function registerFrontierFunction(sdk: ISdk, kv: StateKV): void { const frontier: FrontierItem[] = []; for (const action of actions) { - if (action.status === "done" || action.status === "cancelled") continue; + if (action.status !== "pending" && action.status !== "active") continue; if (data.project && action.project !== data.project) continue; const blockers: string[] = []; diff --git a/test/frontier.test.ts b/test/frontier.test.ts index 2be7f5ce34..f2ea975664 100644 --- a/test/frontier.test.ts +++ b/test/frontier.test.ts @@ -125,12 +125,17 @@ describe("Frontier Functions", () => { ); }); - it("excludes done and cancelled actions", async () => { + it("excludes blocked, done, and cancelled actions", async () => { const pending = makeAction({ id: "act_pending", title: "Pending", status: "pending", }); + const blocked = makeAction({ + id: "act_blocked", + title: "Blocked", + status: "blocked", + }); const done = makeAction({ id: "act_done", title: "Done", @@ -143,6 +148,7 @@ describe("Frontier Functions", () => { }); await kv.set("mem:actions", pending.id, pending); + await kv.set("mem:actions", blocked.id, blocked); await kv.set("mem:actions", done.id, done); await kv.set("mem:actions", cancelled.id, cancelled); @@ -150,12 +156,14 @@ describe("Frontier Functions", () => { success: boolean; frontier: FrontierItem[]; totalActions: number; + totalUnblocked: number; }; expect(result.success).toBe(true); expect(result.frontier.length).toBe(1); expect(result.frontier[0].action.id).toBe("act_pending"); - expect(result.totalActions).toBe(3); + expect(result.totalActions).toBe(4); + expect(result.totalUnblocked).toBe(1); }); it("excludes blocked actions with unsatisfied requires edge", async () => { @@ -419,6 +427,28 @@ describe("Frontier Functions", () => { expect(result.totalActions).toBe(1); }); + it("returns null when all actions are blocked", async () => { + const blockedAction = makeAction({ + id: "act_blocked", + title: "Waiting for approval", + status: "blocked", + priority: 10, + }); + await kv.set("mem:actions", blockedAction.id, blockedAction); + + const result = (await sdk.trigger("mem::next", {})) as { + success: boolean; + suggestion: null; + message: string; + totalActions: number; + }; + + expect(result.success).toBe(true); + expect(result.suggestion).toBeNull(); + expect(result.message).toContain("No actionable work"); + expect(result.totalActions).toBe(1); + }); + it("propagates failure when frontier fails", async () => { const originalFunctions = new Map(); From fb10d2f9a789edf7bbe796c6e6c8ee4cc1c1b2b1 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Fri, 17 Jul 2026 02:41:03 -0400 Subject: [PATCH 19/43] feat: add Actions v2 schema and migration --- AGENTS.md | 2 +- README.md | 19 +- assets/tags/light/stat-tools.svg | 4 +- assets/tags/stat-tools.svg | 4 +- .../specs/2026-07-17-actions-v2-design.md | 393 ++++++++ plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/opencode/README.md | 2 +- plugin/plugin.json | 2 +- .../skills/agentmemory-mcp-tools/REFERENCE.md | 7 +- src/functions/action-model.ts | 718 +++++++++++++ src/functions/action-query.ts | 185 ++++ src/functions/action-readiness-refresh.ts | 90 ++ src/functions/action-store.ts | 380 +++++++ src/functions/actions-v2-migration.ts | 279 ++++++ src/functions/actions.ts | 942 +++++++++++++----- src/functions/checkpoints.ts | 66 +- src/functions/crystallize.ts | 7 +- src/functions/diagnostics.ts | 41 +- src/functions/export-import.ts | 364 ++++++- src/functions/frontier.ts | 188 ++-- src/functions/leases.ts | 71 +- src/functions/mesh.ts | 41 +- src/functions/migrate.ts | 40 +- src/functions/routines.ts | 15 +- src/functions/sentinels.ts | 102 +- src/functions/sketches.ts | 62 +- src/mcp/server.ts | 92 ++ src/mcp/standalone.ts | 2 +- src/mcp/tools-registry.ts | 117 ++- src/state/schema.ts | 2 + src/triggers/api.ts | 221 +++- src/types.ts | 107 ++ test/actions-api-pagination.test.ts | 78 ++ test/actions-v2-migration.test.ts | 273 +++++ test/actions-v2.test.ts | 524 ++++++++++ test/export-import.test.ts | 224 +++++ test/leases.test.ts | 31 +- test/mcp-surface-default.test.ts | 5 +- test/tool-count-consistency.test.ts | 2 +- 40 files changed, 5107 insertions(+), 599 deletions(-) create mode 100644 docs/superpowers/specs/2026-07-17-actions-v2-design.md create mode 100644 src/functions/action-model.ts create mode 100644 src/functions/action-query.ts create mode 100644 src/functions/action-readiness-refresh.ts create mode 100644 src/functions/action-store.ts create mode 100644 src/functions/actions-v2-migration.ts create mode 100644 test/actions-v2-migration.test.ts create mode 100644 test/actions-v2.test.ts diff --git a/AGENTS.md b/AGENTS.md index 48ecb9b013..216ba2e3b5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -125,7 +125,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). ## Current Stats (v0.9.27) -- 53 MCP tools (`all` by default; 7 safe essentials in `core`; curated coordination in `workstation`) +- 54 MCP tools (`all` by default; 7 safe essentials in `core`; curated coordination in `workstation`) - 130 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 15 skills diff --git a/README.md b/README.md index 1ca87d6734..91b4235df8 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@

95.2% retrieval R@5 92% fewer tokens - 53 MCP tools + 54 MCP tools 12 auto hooks 0 external DBs 1,423+ tests passing @@ -514,7 +514,7 @@ Implementation details live in `src/cli.ts` (see `runUpgrade` around the `src/cl ### Claude Code (one block, paste it) ```text -Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 15 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. +Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 15 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. ``` #### Claude Code without the plugin install (MCP-standalone path) @@ -543,7 +543,7 @@ codex plugin add agentmemory@agentmemory The Codex plugin ships from the same `plugin/` directory as the Claude Code plugin. It registers: -- `@agentmemory/mcp` as an MCP server (proxies all 53 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable) +- `@agentmemory/mcp` as an MCP server (proxies all 54 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable) - 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop` - 8 invocable skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/commit-context`, `/commit-history`, plus 7 reference skills the agent loads on demand (MCP tools, REST API, config, agents, hooks, architecture, and the skill-authoring guide) @@ -577,7 +577,7 @@ copilot plugin install rohitg00/agentmemory:plugin

OpenClaw (paste this prompt) ```text -Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 53 memory tools: +Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools: { "mcpServers": { @@ -602,7 +602,7 @@ Full guide: [`integrations/openclaw/`](integrations/openclaw/) Hermes Agent (paste this prompt) ```text -Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 53 memory tools: +Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools: mcp_servers: agentmemory: @@ -959,11 +959,11 @@ npm install @xenova/transformers

MCP Server

-53 tools, 6 resources, 3 prompts, and 15 skills, the most comprehensive MCP memory toolkit for any agent. +54 tools, 6 resources, 3 prompts, and 15 skills, the most comprehensive MCP memory toolkit for any agent. > **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the running server's selected tool profile **only when it can reach an agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). `AGENTMEMORY_TOOLS=core|workstation|all` is evaluated by the running server; set it in the server service environment. If you see only 7 local-fallback tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`. -### 53 Tools +### 54 Tools
Core tools (always available) @@ -985,7 +985,7 @@ npm install @xenova/transformers
-Extended tools (53 total — set AGENTMEMORY_TOOLS=all) +Extended tools (54 total — set AGENTMEMORY_TOOLS=all) | Tool | Description | |------|-------------| @@ -1002,6 +1002,7 @@ npm install @xenova/transformers | `memory_snapshot_create` | Git-versioned snapshot | | `memory_action_create` | Create work items with dependencies | | `memory_action_update` | Update action status | +| `memory_action_list` | Revision-bound actionable and waiting views | | `memory_frontier` | Unblocked actions ranked by priority | | `memory_next` | Single most important next action | | `memory_lease` | Exclusive action leases (multi-agent) | @@ -1522,7 +1523,7 @@ Create `~/.agentmemory/.env`: # USER_ID= # TEAM_MODE=private -# Tool visibility: "core" (7), "workstation" (curated coordination), "all" (53), or a comma-separated allowlist +# Tool visibility: "core" (7), "workstation" (curated coordination), "all" (54), or a comma-separated allowlist # AGENTMEMORY_TOOLS=core # AGENTMEMORY_DISABLE_LLM_TOOLS=true # reports skipped_disabled, not failure ``` diff --git a/assets/tags/light/stat-tools.svg b/assets/tags/light/stat-tools.svg index e6d598532f..9ed07e9faf 100644 --- a/assets/tags/light/stat-tools.svg +++ b/assets/tags/light/stat-tools.svg @@ -1,5 +1,5 @@ - + - 53 + 54 MCP TOOLS diff --git a/assets/tags/stat-tools.svg b/assets/tags/stat-tools.svg index 2f38d7a109..57c3dc4eef 100644 --- a/assets/tags/stat-tools.svg +++ b/assets/tags/stat-tools.svg @@ -1,5 +1,5 @@ - + - 53 + 54 MCP TOOLS diff --git a/docs/superpowers/specs/2026-07-17-actions-v2-design.md b/docs/superpowers/specs/2026-07-17-actions-v2-design.md new file mode 100644 index 0000000000..cfe4fb7055 --- /dev/null +++ b/docs/superpowers/specs/2026-07-17-actions-v2-design.md @@ -0,0 +1,393 @@ +# Actions v2: Canonical Tasks, Readiness Views, and Auditable Migration + +Status: implementation approved; live deployment is out of scope + +## Goal + +Make AgentMemory actions a reliable cross-agent task system without breaking +the existing REST, MCP, `todo` CLI, import/export, lease, checkpoint, sentinel, +routine, sketch, or mesh consumers. + +Actions v2 must: + +- store a canonical project identity instead of relying on paths or tags; +- represent ownership, scheduling, human approval, blocking, and worktree + context as typed fields; +- separate lifecycle from derived readiness; +- record append-only, actor-attributed lifecycle, result, correction, and + migration events; +- expose actionable, scheduled, waiting, and blocked views; +- make paginated action reads fail closed when the collection changes; +- migrate legacy rows idempotently without deleting or silently reassigning + data; +- retain the v1 wire shape long enough for existing clients to keep working. + +## Current Evidence + +The live workstation store contained 307 actions when this design was written: + +- 106 actions stored `tags` as a comma-separated string even though the TypeScript + interface requires `string[]`; +- three actions used an absolute repository path as `project`; +- one action had no project; +- 64 actions encoded worktree context only in tags; +- scheduling and human-approval state were also tag conventions; +- `blocked` currently mixes manual blocking, dependencies, checkpoints, and + human waiting in one lifecycle value; +- offset pagination has no revision guard, so concurrent changes can reorder + pages and produce an incomplete export. + +## Non-goals + +- Replacing iii-engine or bypassing its StateModule. +- Converting all AgentMemory data to event sourcing. +- Removing v1 fields or endpoints in this change. +- Changing the meaning of existing action IDs. +- Automatically deploying or migrating the workstation store. +- Reading the workstation project registry from a hard-coded local path inside + the portable AgentMemory package. + +## Considered Designs + +### Full event sourcing + +Events become authoritative and every action is replayed into a projection. +This gives the cleanest history, but iii's KV surface has no cross-key +transaction, every existing reader would need conversion, and recovery would +become a prerequisite for ordinary reads. The migration risk is too high. + +### Parallel v1 and v2 stores + +Write both `mem:actions` and a new v2 store. Rollback is simple, but dual writes +create two sources of truth and require permanent drift detection. This is not +acceptable for the single-copy coordination queue. + +### Additive v2 projection plus append-only events + +Keep `mem:actions` as the authoritative projection, add typed v2 fields, add an +immutable action-event scope, and add a collection revision. Existing clients +continue reading v1 fields; new readers use lifecycle and readiness views. +This is the selected design. + +## Data Model + +The existing `Action` interface remains readable. V2 fields are optional at the +TypeScript boundary so old exports can be imported, but every newly normalized +or created action persists all required v2 fields. + +```ts +type ActionLifecycle = "pending" | "active" | "done" | "cancelled"; + +type ActionReadinessView = + | "actionable" + | "scheduled" + | "waiting" + | "blocked" + | "completed" + | "cancelled"; + +type ActionApprovalState = + | "not_required" + | "pending" + | "approved" + | "rejected"; + +interface ActionApproval { + state: ActionApprovalState; + requestedAt?: string; + requestedBy?: string; + decidedAt?: string; + decidedBy?: string; + note?: string; +} + +interface ActionV2Fields { + schemaVersion: 2; + revision: number; + lifecycle: ActionLifecycle; + projectId: string; + projectAliases: string[]; + owner?: string; + notBefore?: string; + dueAt?: string; + awaitingHuman: boolean; + approval?: ActionApproval; + blockedReason?: string; + repoRoot?: string; + worktree?: string; + branch?: string; + taskSlug?: string; +} +``` + +The legacy fields remain projections: + +- `project` mirrors `projectId`; +- `assignedTo` describes the current active worker or lease holder, while + `owner` is durable responsibility; +- `status` remains `pending | active | done | blocked | cancelled` for old + clients; +- `tags` remains present but is always normalized to a deduplicated array; +- `result` remains the current result projection while result events preserve + prior values. + +The canonical lifecycle never contains `blocked`. For compatibility, the +legacy `status` is `blocked` when a pending action has an explicit manual block +or is awaiting a human decision. Dependency and checkpoint code may continue +updating the legacy projection during the compatibility window, but readiness +is always recomputed from typed state and edges. + +## Canonical Project Identity + +Project selection uses this precedence: + +1. an explicit valid `projectId`; +2. an explicit migration alias map entry for the legacy `project` value; +3. one unambiguous `projectId:` legacy tag; +4. a non-path legacy `project` value; +5. the final path segment of an absolute legacy repository path, recorded as an + inferred mapping and preserved in `projectAliases`; +6. the caller-supplied migration fallback, defaulting to `workstation` only for + genuinely unscoped rows. + +Canonical IDs must be non-empty, must not be absolute paths, and may contain +letters, numbers, dots, underscores, and hyphens. All prior path/name values +are retained in `projectAliases`. The migration reports explicit, inferred, +defaulted, and conflicting mappings separately so rollout can stop on an +unexpected inference. + +New v2 callers should send `projectId`. Legacy callers may continue sending +`project`; the normalizer produces the same persisted v2 shape and includes +normalization warnings in the result when inference was necessary. + +## Typed Context Migration + +Legacy tags are retained and parsed into first-class fields when the target +field is absent: + +- `projectId:` -> `projectId`; +- `agent:` -> `owner` when no explicit owner or assignee exists; +- `due:` -> `dueAt`; +- `not-before:` -> `notBefore`; +- `worktree:` -> `worktree`; +- `branch:` -> `branch`; +- `task_slug:` or `task-slug:` -> `taskSlug`; +- `requires-confirmation`, `awaiting-human`, or `approval-required` -> + `awaitingHuman=true` and a pending approval. + +Invalid timestamps are preserved in tags and reported; they are not copied to +typed fields. If a legacy blocked action has unresolved `requires` or +`gated_by` edges, its block remains derived. If it is waiting for approval, it +becomes `waiting`. Otherwise it receives `blockedReason="Legacy blocked state"` +so no manual block disappears. + +## Append-only Events and Collection Revision + +`mem:action-events` stores immutable `ActionEvent` rows: + +```ts +type ActionEventType = + | "created" + | "fields_changed" + | "lifecycle_changed" + | "result_recorded" + | "corrected" + | "migrated" + | "deleted" + | "edge_created" + | "edge_deleted"; + +interface ActionEvent { + schemaVersion: 2; + id: string; + actionId: string; + revision: number; + type: ActionEventType; + actor: string; + timestamp: string; + reason?: string; + correctionOf?: string; + before?: Action | ActionEdge; + after?: Action | ActionEdge; +} +``` + +There is no event update/delete API. Corrections append a `corrected` event and +identify the corrected event when known. The action projection changes to the +correct value; the original event remains. + +`mem:action-state/current` stores: + +```ts +interface ActionCollectionState { + schemaVersion: 2; + revision: number; + updatedAt: string; + pending?: { revision: number; eventId: string }; +} +``` + +All action/edge projection writes use one keyed action-store lock and this +recoverable sequence: + +1. write `pending` with the next revision and event ID; +2. append the event containing the post-image; +3. write or delete the projection; +4. commit the collection revision and clear `pending`. + +If the worker stops mid-write, the next action-store operation reconciles the +pending marker. An existing event is replayed into the projection; a marker +without an event is cleared without advancing the revision. Normal reads never +observe intermediate writes because they use the same in-process lock. + +The existing audit log remains. Action events are the domain history; audit +entries remain the system-wide operational record. + +## Readiness Views + +Readiness is derived at read time in this precedence order: + +1. lifecycle `done` -> `completed`; +2. lifecycle `cancelled` -> `cancelled`; +3. explicit `blockedReason`, rejected approval, unsatisfied `requires`, failed + or pending checkpoint/sentinel `gated_by`, an active conflict, or an unavailable lease -> + `blocked`; +4. `awaitingHuman` or pending approval -> `waiting`; +5. future `notBefore` -> `scheduled`; +6. otherwise -> `actionable`. + +Each computed item includes structured blockers rather than only display +strings. `memory_frontier` remains the actionable view and excludes leases held +by other agents unless requested. `memory_next` remains the highest-ranked +actionable item. + +`dueAt` does not block readiness. It adds a bounded urgency component to the +existing priority/age score. Invalid or past `notBefore` values never crash a +read; invalid persisted values are reported as blockers until corrected. + +## API and MCP Compatibility + +Existing names, required arguments, response fields, and status values remain +valid. + +Additive changes: + +- action create accepts `projectId`, `projectAliases`, `owner`, `notBefore`, + `dueAt`, `awaitingHuman`, `approval`, `blockedReason`, `repoRoot`, `worktree`, + `branch`, `taskSlug`, and `actor`; +- action update accepts the same mutable fields plus `lifecycle`, `actor`, + `correctionOf`, and `correctionReason`; +- action list accepts `view`, `owner`, `cursor`, and `revision` and returns + `revision`, `nextCursor`, and computed view entries while retaining + `actions`, `total`, `limit`, `offset`, and `hasMore`; +- a new `memory_action_list` MCP tool exposes the same bounded views; +- frontier items gain additive `view` and structured blocker data; +- REST handlers explicitly whitelist every forwarded field. + +Legacy `status="blocked"` updates create or retain a manual block. A later +legacy `status="pending"` clears only that manual block; it does not approve a +pending human decision or bypass dependencies/checkpoints. + +## Revision-bound Pagination + +Action pages are sorted deterministically by `updatedAt DESC, id ASC`. + +The first page returns the collection `revision` and an opaque cursor encoding +the revision, offset, and a fingerprint of the filters. Subsequent requests +must either pass that cursor or the same explicit revision. A changed +collection, modified filter, malformed cursor, or mismatched revision returns +a typed `revision_conflict`/`invalid_cursor` failure instead of a partial page. + +Offset-only calls remain supported for old clients but are not advertised as a +complete snapshot mechanism. + +Checkpoint and sentinel transitions re-project their linked actions and append +an action event. This advances the same collection revision used by cursors, so +a gate changing between pages fails closed instead of silently changing the +derived readiness set. + +## Export and Import + +`ExportData` gains optional `actionEvents` and `actionSnapshot` fields. Action, +edge, event, and state reads occur under the action-store lock, so one export +contains a self-consistent action revision. + +Old exports without v2 fields still import. Imported actions are normalized +before persistence. Imported event IDs are deduplicated. A replace import also +replaces action events/state; a merge import appends non-conflicting events and +advances the local collection revision. Existing import safety limits gain +bounded action/event limits. + +An export reports action count, edge count, event count, schema version, and +revision. Import validates those counts when snapshot metadata is present and +fails before mutation on mismatch. + +## Migration + +`POST /agentmemory/migrate` gains `step="actions-v2"` with whitelisted fields: + +- `dryRun` (default true); +- `projectAliases` mapping legacy values to canonical IDs; +- `defaultProjectId` (default `workstation`); +- `limit` and opaque `cursor` for bounded batches. + +The migration: + +1. reads a deterministic page of actions; +2. normalizes tags and typed context; +3. resolves project identity and reports conflicts/inferences; +4. derives lifecycle without removing the legacy status; +5. appends one `migrated` event per changed action; +6. writes the v2 projection and collection revision; +7. returns counts, warnings, unresolved rows, revision, and next cursor. + +It skips already-normalized actions, making retries idempotent. Dry-run performs +no KV writes, events, audit writes, or revision changes. A non-dry batch stops +before mutation if any row has an invalid explicit canonical project ID or +conflicting explicit identities. Inferred/defaulted mappings are warnings and +remain reviewable in the result and event. + +## Failure Handling + +- Boundary validation rejects invalid lifecycle/status values, priorities, + approval combinations, project IDs, and timestamps. +- No raw REST request body is forwarded to an internal function. +- Migration errors identify action IDs but do not include secrets or full + descriptions/results. +- Event/state recovery is idempotent and runs before action-store mutations or + revision-bound reads. +- Existing v1 rows are normalized on read for classification, but only the + explicit migration or a mutation persists v2 fields. +- No live migration is implicit at process startup. + +## Rollout Plan + +1. Merge code and documentation with all tests passing. +2. Build a package from the exact merge commit; do not install it yet. +3. Export and stop-backup the live store. +4. Run `actions-v2` dry-run with aliases sourced by deployment tooling from the + external workspace project registry. +5. Review conflicts, inferred mappings, counts, and projected revision. +6. Install the package and restart only with explicit deployment approval. +7. Run bounded migration batches, verifying counts and revision after each. +8. Exercise old REST/MCP/CLI calls and new views against the migrated store. +9. Keep v1 fields for at least one release before considering deprecation. + +## Acceptance Criteria + +- Existing action, frontier, next, lease, export/import, checkpoint, sentinel, + routine, sketch, crystallize, mesh, diagnostics, and MCP tests still pass. +- New creates persist a complete v2 projection while old create inputs work. +- String/list tags normalize without losing tokens. +- Path aliases, tag project IDs, and unscoped rows migrate deterministically and + are reported by category. +- Dry-run is byte-for-byte non-mutating and repeated migration is idempotent. +- Every lifecycle, result, correction, and migration change appends an event + with actor and timestamp. +- Manual blocks, dependencies, approvals, schedules, leases, and terminal + lifecycle states land in the correct readiness view. +- A collection change between pages produces a revision conflict rather than + an incomplete export. +- Export action counts/events/revision are internally consistent; old exports + remain importable. +- No test or migration path touches the workstation live data store. diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index cb4e6df7b8..f351b2c8bc 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "version": "0.9.27", - "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 53 MCP tools, 8 skills, real-time viewer.", + "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 54 MCP tools, 8 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index 7c42f13094..f135276f48 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "version": "0.9.27", - "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 6 hooks, 53 MCP tools, 8 skills, real-time viewer.", + "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 6 hooks, 54 MCP tools, 8 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" diff --git a/plugin/opencode/README.md b/plugin/opencode/README.md index 60f5e5bb94..6bcc4b321e 100644 --- a/plugin/opencode/README.md +++ b/plugin/opencode/README.md @@ -9,7 +9,7 @@

- 53 MCP tools + 54 MCP tools 22 hooks 2 slash commands 95.2% R@5 diff --git a/plugin/plugin.json b/plugin/plugin.json index 9d0751a7ab..e6e34d7da6 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "version": "0.9.27", - "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 53 MCP tools, 15 skills, real-time viewer.", + "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 54 MCP tools, 15 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" diff --git a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md index 6f07b67ebf..00f1b85345 100644 --- a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md +++ b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md @@ -3,12 +3,13 @@ Generated from `src/mcp/tools-registry.ts`. Do not edit the block below by hand; run `npm run skills:gen` after changing the registry. -agentmemory exposes 53 MCP tools. 7 are in the lean core set (`--tools core` or `AGENTMEMORY_TOOLS=core`); the rest load with `--tools all` (default). +agentmemory exposes 54 MCP tools. 7 are in the lean core set (`--tools core` or `AGENTMEMORY_TOOLS=core`); the rest load with `--tools all` (default). | Tool | Core | Parameters | Purpose | | --- | --- | --- | --- | -| `memory_action_create` | | `title`*: string, `description`: string, `priority`: number, `project`: string, `tags`: string, `parentId`: string, `requires`: string | Create an actionable work item with typed dependencies. Actions track what agents need to do and how work items relate to each other. | -| `memory_action_update` | | `actionId`*: string, `status`: string, `result`: string, `priority`: number | Update an action's status, priority, or details. Set status to 'done' to complete it and unblock dependent actions. | +| `memory_action_create` | | `title`*: string, `description`: string, `priority`: number, `project`: string, `projectId`: string, `projectAliases`: string, `tags`: string, `parentId`: string, `requires`: string, `lifecycle`: string, `owner`: string, `notBefore`: string, `dueAt`: string, `awaitingHuman`: boolean, `approvalState`: string, `blockedReason`: string, `repoRoot`: string, `worktree`: string, `branch`: string, `taskSlug`: string, `actor`: string | Create an actionable work item with typed dependencies. Actions track what agents need to do and how work items relate to each other. | +| `memory_action_list` | | `project`: string, `status`: string, `view`: string, `owner`: string, `tags`: string, `agentId`: string, `limit`: number, `cursor`: string, `revision`: number | List actions through revision-bound actionable, scheduled, waiting, blocked, completed, or cancelled views. | +| `memory_action_update` | | `actionId`*: string, `status`: string, `lifecycle`: string, `title`: string, `description`: string, `result`: string, `priority`: number, `assignedTo`: string, `owner`: string, `tags`: string, `project`: string, `projectId`: string, `projectAliases`: string, `notBefore`: string, `dueAt`: string, `awaitingHuman`: boolean, `approvalState`: string, `blockedReason`: string, `repoRoot`: string, `worktree`: string, `branch`: string, `taskSlug`: string, `actor`: string, `correctionOf`: string, `correctionReason`: string | Update an action's status, priority, or details. Set status to 'done' to complete it and unblock dependent actions. | | `memory_audit` | | `operation`: string, `limit`: number | View the audit trail of memory operations. | | `memory_checkpoint` | | `operation`*: string, `name`: string, `checkpointId`: string, `status`: string, `type`: string, `linkedActionIds`: string | Create or resolve an external checkpoint (CI result, approval, deploy status) that gates action progress. | | `memory_claude_bridge_sync` | | `direction`*: string | Sync memory state to/from Claude Code's native MEMORY.md file. | diff --git a/src/functions/action-model.ts b/src/functions/action-model.ts new file mode 100644 index 0000000000..ddaeb740ab --- /dev/null +++ b/src/functions/action-model.ts @@ -0,0 +1,718 @@ +import { createHash } from "node:crypto"; +import { basename, isAbsolute, win32 } from "node:path"; +import type { + Action, + ActionApproval, + ActionApprovalState, + ActionBlocker, + ActionEdge, + ActionLifecycle, + ActionReadinessView, + ActionViewItem, + Checkpoint, + Lease, + Sentinel, +} from "../types.js"; + +export const ACTION_SCHEMA_VERSION = 2 as const; +export const DEFAULT_ACTION_PROJECT_ID = "workstation"; + +const LIFECYCLES = new Set([ + "pending", + "active", + "done", + "cancelled", +]); +const APPROVAL_STATES = new Set([ + "not_required", + "pending", + "approved", + "rejected", +]); +const HUMAN_WAIT_TAGS = new Set([ + "requires-confirmation", + "awaiting-human", + "approval-required", +]); +const PROJECT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/; + +export interface NormalizeActionOptions { + projectAliases?: Record; + defaultProjectId?: string; + hasDerivedBlockers?: boolean; + revision?: number; +} + +export interface NormalizeActionResult { + action: Action; + changed: boolean; + warnings: string[]; + conflicts: string[]; +} + +export interface ActionViewContext { + actions: Action[]; + edges: ActionEdge[]; + checkpoints: Checkpoint[]; + sentinels: Sentinel[]; + leases: Lease[]; + agentId?: string; + now?: number; +} + +interface ActionCursorPayload { + v: 1; + revision: number; + offset: number; + filter: string; + asOf: number; +} + +export function isActionLifecycle(value: unknown): value is ActionLifecycle { + return typeof value === "string" && LIFECYCLES.has(value as ActionLifecycle); +} + +export function isActionApprovalState( + value: unknown, +): value is ActionApprovalState { + return ( + typeof value === "string" && + APPROVAL_STATES.has(value as ActionApprovalState) + ); +} + +export function isCanonicalProjectId(value: unknown): value is string { + return ( + typeof value === "string" && + PROJECT_ID_PATTERN.test(value) && + !isProjectPath(value) + ); +} + +export function isValidActionTimestamp(value: unknown): value is string { + return ( + typeof value === "string" && + value.trim().length > 0 && + !Number.isNaN(Date.parse(value)) + ); +} + +export function normalizeActionTags(value: unknown): string[] { + const input = Array.isArray(value) + ? value + : typeof value === "string" + ? value.split(",") + : []; + return [ + ...new Set( + input + .filter((tag): tag is string => typeof tag === "string") + .map((tag) => tag.trim()) + .filter(Boolean), + ), + ]; +} + +export function normalizeActionV2( + input: Action, + options: NormalizeActionOptions = {}, +): NormalizeActionResult { + const raw = input as Action & { tags?: unknown }; + const warnings: string[] = []; + const conflicts: string[] = []; + const tags = normalizeActionTags(raw.tags); + if (!Array.isArray(raw.tags)) warnings.push("tags_normalized"); + + const tagProjectIds = uniqueTagValues(tags, "projectId"); + if (tagProjectIds.length > 1) conflicts.push("conflicting_project_tags"); + + const legacyProject = nonEmpty(raw.project); + const explicitProjectId = nonEmpty(raw.projectId); + const mappedProject = legacyProject + ? nonEmpty(options.projectAliases?.[legacyProject]) + : undefined; + let projectId: string | undefined; + + if (explicitProjectId) { + if (!isCanonicalProjectId(explicitProjectId)) { + conflicts.push("invalid_explicit_project_id"); + } else { + projectId = explicitProjectId; + } + } + if (mappedProject) { + if (!isCanonicalProjectId(mappedProject)) { + conflicts.push("invalid_mapped_project_id"); + } else if (projectId && mappedProject !== projectId) { + conflicts.push("conflicting_project_mapping"); + } else { + projectId = mappedProject; + warnings.push("project_resolved_from_alias_map"); + } + } + if (tagProjectIds[0]) { + if (!isCanonicalProjectId(tagProjectIds[0])) { + conflicts.push("invalid_project_tag"); + } else if (projectId && tagProjectIds[0] !== projectId) { + conflicts.push("conflicting_project_tag"); + } else { + projectId = tagProjectIds[0]; + if (!explicitProjectId && !mappedProject) { + warnings.push("project_resolved_from_tag"); + } + } + } + if (!projectId && legacyProject && !isProjectPath(legacyProject)) { + if (isCanonicalProjectId(legacyProject)) { + projectId = legacyProject; + } else { + conflicts.push("invalid_legacy_project_id"); + } + } + if (!projectId && legacyProject && isProjectPath(legacyProject)) { + const trimmedPath = legacyProject.replace(/[\\/]+$/, ""); + const inferred = win32.isAbsolute(legacyProject) + ? win32.basename(trimmedPath) + : basename(trimmedPath); + if (isCanonicalProjectId(inferred)) { + projectId = inferred; + warnings.push("project_inferred_from_path"); + } else { + conflicts.push("unresolved_project_path"); + } + } + if (!projectId) { + const fallback = options.defaultProjectId ?? DEFAULT_ACTION_PROJECT_ID; + if (isCanonicalProjectId(fallback)) { + projectId = fallback; + warnings.push("project_defaulted"); + } else { + conflicts.push("invalid_default_project_id"); + projectId = DEFAULT_ACTION_PROJECT_ID; + } + } + + const projectAliases = new Set( + normalizeStringArray(raw.projectAliases).filter( + (alias) => alias !== projectId, + ), + ); + if (legacyProject && legacyProject !== projectId) { + projectAliases.add(legacyProject); + } + + const lifecycle = isActionLifecycle(raw.lifecycle) + ? raw.lifecycle + : lifecycleFromLegacyStatus(raw.status); + + const owner = + nonEmpty(raw.owner) ?? + (raw.schemaVersion === ACTION_SCHEMA_VERSION + ? undefined + : nonEmpty(raw.assignedTo) ?? + firstTagValue(tags, "agent") ?? + (nonEmpty(raw.createdBy) === "unknown" + ? undefined + : nonEmpty(raw.createdBy))); + + const notBefore = typedOrTaggedTimestamp( + raw.notBefore, + raw.schemaVersion === ACTION_SCHEMA_VERSION + ? undefined + : firstTagValue(tags, "not-before"), + "not_before", + warnings, + conflicts, + ); + const dueAt = typedOrTaggedTimestamp( + raw.dueAt, + raw.schemaVersion === ACTION_SCHEMA_VERSION + ? undefined + : firstTagValue(tags, "due"), + "due_at", + warnings, + conflicts, + ); + + const approval = normalizeApproval(raw.approval, warnings, conflicts); + const waitTag = tags.some((tag) => HUMAN_WAIT_TAGS.has(tag.toLowerCase())); + let awaitingHuman = + typeof raw.awaitingHuman === "boolean" ? raw.awaitingHuman : waitTag; + let normalizedApproval = approval; + if (normalizedApproval?.state === "pending") awaitingHuman = true; + if ( + normalizedApproval && + normalizedApproval.state !== "pending" + ) { + awaitingHuman = false; + } + if (awaitingHuman && !normalizedApproval) { + normalizedApproval = { + state: "pending", + requestedAt: isValidActionTimestamp(raw.createdAt) + ? raw.createdAt + : undefined, + }; + warnings.push("approval_inferred_from_wait_state"); + } + + let blockedReason = nonEmpty(raw.blockedReason); + if ( + raw.schemaVersion !== ACTION_SCHEMA_VERSION && + raw.status === "blocked" && + !blockedReason && + !awaitingHuman && + !options.hasDerivedBlockers + ) { + blockedReason = "Legacy blocked state"; + warnings.push("manual_block_inferred"); + } + + const repoRoot = + nonEmpty(raw.repoRoot) ?? + (legacyProject && isProjectPath(legacyProject) + ? legacyProject + : undefined); + const worktree = + nonEmpty(raw.worktree) ?? + (raw.schemaVersion === ACTION_SCHEMA_VERSION + ? undefined + : firstTagValue(tags, "worktree")); + const branch = + nonEmpty(raw.branch) ?? + (raw.schemaVersion === ACTION_SCHEMA_VERSION + ? undefined + : firstTagValue(tags, "branch")); + const taskSlug = + nonEmpty(raw.taskSlug) ?? + (raw.schemaVersion === ACTION_SCHEMA_VERSION + ? undefined + : firstTagValue(tags, "task_slug") ?? + firstTagValue(tags, "task-slug")); + + const action: Action = { + ...raw, + schemaVersion: ACTION_SCHEMA_VERSION, + revision: + options.revision ?? + (Number.isInteger(raw.revision) && (raw.revision ?? -1) >= 0 + ? raw.revision + : 0), + lifecycle, + projectId, + project: projectId, + projectAliases: [...projectAliases].sort(), + owner, + notBefore, + dueAt, + awaitingHuman, + approval: normalizedApproval, + blockedReason, + repoRoot, + worktree, + branch, + taskSlug, + status: legacyStatusFor({ + lifecycle, + blockedReason, + awaitingHuman, + approval: normalizedApproval, + hasDerivedBlockers: options.hasDerivedBlockers === true, + }), + tags, + sourceObservationIds: normalizeStringArray(raw.sourceObservationIds), + sourceMemoryIds: normalizeStringArray(raw.sourceMemoryIds), + }; + + return { + action, + changed: JSON.stringify(action) !== JSON.stringify(input), + warnings: [...new Set(warnings)], + conflicts: [...new Set(conflicts)], + }; +} + +export function classifyAction( + input: Action, + context: ActionViewContext, +): ActionViewItem { + const now = context.now ?? Date.now(); + const actionEdges = context.edges.filter( + (edge) => + edge.sourceActionId === input.id || edge.targetActionId === input.id, + ); + const actionMap = new Map( + context.actions.map((candidate) => [candidate.id, candidate]), + ); + const checkpointMap = new Map( + context.checkpoints.map((checkpoint) => [checkpoint.id, checkpoint]), + ); + const sentinelMap = new Map( + context.sentinels.map((sentinel) => [sentinel.id, sentinel]), + ); + const hasDerivedBlockers = actionEdges.some( + (edge) => { + if (edge.sourceActionId !== input.id) return false; + if (edge.type === "requires") { + const dependency = actionMap.get(edge.targetActionId); + return (dependency?.lifecycle ?? dependency?.status) !== "done"; + } + if (edge.type === "gated_by") { + return ( + checkpointMap.get(edge.targetActionId)?.status !== "passed" && + sentinelMap.get(edge.targetActionId)?.status !== "triggered" + ); + } + return false; + }, + ); + const action = normalizeActionV2(input, { hasDerivedBlockers }).action; + const lifecycle = action.lifecycle ?? lifecycleFromLegacyStatus(action.status); + if (lifecycle === "done") { + return { action, view: "completed", blockers: [], leased: false }; + } + if (lifecycle === "cancelled") { + return { action, view: "cancelled", blockers: [], leased: false }; + } + + const blockers: ActionBlocker[] = []; + + if (action.blockedReason) { + blockers.push({ type: "manual", message: action.blockedReason }); + } + if (action.approval?.state === "rejected") { + blockers.push({ + type: "approval", + message: action.approval.note || "Human approval was rejected", + }); + } + for (const edge of actionEdges) { + if (edge.sourceActionId !== action.id) continue; + if (edge.type === "requires") { + const dependency = actionMap.get(edge.targetActionId); + const dependencyLifecycle = dependency + ? normalizeActionV2(dependency).action.lifecycle + : undefined; + if (dependencyLifecycle !== "done") { + blockers.push({ + type: "requires", + id: edge.targetActionId, + message: dependency + ? `Requires ${dependency.title}` + : `Required action ${edge.targetActionId} is missing`, + }); + } + } + if (edge.type === "gated_by") { + const checkpoint = checkpointMap.get(edge.targetActionId); + const sentinel = sentinelMap.get(edge.targetActionId); + const passed = + checkpoint?.status === "passed" || sentinel?.status === "triggered"; + if (!passed) { + blockers.push({ + type: "checkpoint", + id: edge.targetActionId, + message: checkpoint + ? `Checkpoint ${checkpoint.name} is ${checkpoint.status}` + : sentinel + ? `Sentinel ${sentinel.name} is ${sentinel.status}` + : `Gate ${edge.targetActionId} is missing`, + }); + } + } + } + for (const edge of actionEdges) { + if (edge.type !== "conflicts_with") continue; + const otherId = + edge.sourceActionId === action.id + ? edge.targetActionId + : edge.sourceActionId; + const other = actionMap.get(otherId); + const otherLifecycle = other + ? normalizeActionV2(other).action.lifecycle + : undefined; + if (other && otherLifecycle === "active") { + blockers.push({ + type: "conflict", + id: other.id, + message: `Conflicts with active action ${other.title}`, + }); + } + } + + const activeLease = context.leases.find( + (lease) => + lease.actionId === action.id && + lease.status === "active" && + Date.parse(lease.expiresAt) > now, + ); + const leased = activeLease !== undefined; + if ( + activeLease && + context.agentId && + activeLease.agentId !== context.agentId + ) { + blockers.push({ + type: "lease", + id: activeLease.id, + message: `Leased by ${activeLease.agentId}`, + }); + } + + if (blockers.length > 0) { + return { action, view: "blocked", blockers, leased }; + } + if (action.awaitingHuman || action.approval?.state === "pending") { + return { action, view: "waiting", blockers: [], leased }; + } + if (action.notBefore) { + const scheduledAt = Date.parse(action.notBefore); + if (Number.isNaN(scheduledAt)) { + return { + action, + view: "blocked", + blockers: [ + { + type: "schedule", + message: "notBefore is not a valid timestamp", + }, + ], + leased, + }; + } + if (scheduledAt > now) { + return { action, view: "scheduled", blockers: [], leased }; + } + } + return { action, view: "actionable", blockers: [], leased }; +} + +export function computeActionScore( + action: Action, + edges: ActionEdge[], + now: number, +): number { + let score = action.priority * 10; + const createdAt = Date.parse(action.createdAt); + if (!Number.isNaN(createdAt)) { + const ageHours = (now - createdAt) / (1000 * 60 * 60); + score += Math.min(Math.max(ageHours, 0) * 0.5, 20); + } + const unlockCount = edges.filter( + (edge) => edge.sourceActionId === action.id && edge.type === "unlocks", + ).length; + score += unlockCount * 5; + if ( + edges.some( + (edge) => + edge.sourceActionId === action.id && edge.type === "spawned_by", + ) + ) { + score += 3; + } + if ((action.lifecycle ?? lifecycleFromLegacyStatus(action.status)) === "active") { + score += 15; + } + if (action.dueAt) { + const dueAt = Date.parse(action.dueAt); + if (!Number.isNaN(dueAt)) { + const remainingHours = (dueAt - now) / (1000 * 60 * 60); + if (remainingHours <= 0) { + score += 20; + } else if (remainingHours <= 24) { + score += 15 * (1 - remainingHours / 24); + } + } + } + return Math.round(score * 100) / 100; +} + +export function actionFilterFingerprint(filters: Record): string { + const stable = Object.keys(filters) + .sort() + .reduce>((result, key) => { + const value = filters[key]; + if (value !== undefined) result[key] = value; + return result; + }, {}); + return createHash("sha256") + .update(JSON.stringify(stable)) + .digest("hex") + .slice(0, 16); +} + +export function encodeActionCursor( + revision: number, + offset: number, + filter: string, + asOf: number, +): string { + const payload: ActionCursorPayload = { v: 1, revision, offset, filter, asOf }; + return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url"); +} + +export function decodeActionCursor(cursor: string): ActionCursorPayload { + try { + const parsed = JSON.parse( + Buffer.from(cursor, "base64url").toString("utf8"), + ) as Partial; + if ( + parsed.v !== 1 || + !Number.isInteger(parsed.revision) || + parsed.revision! < 0 || + !Number.isInteger(parsed.offset) || + parsed.offset! < 0 || + typeof parsed.filter !== "string" || + !parsed.filter || + !Number.isFinite(parsed.asOf) || + parsed.asOf! < 0 + ) { + throw new Error("invalid payload"); + } + return parsed as ActionCursorPayload; + } catch { + throw new Error("invalid_cursor"); + } +} + +function lifecycleFromLegacyStatus(status: Action["status"]): ActionLifecycle { + if (status === "active" || status === "done" || status === "cancelled") { + return status; + } + return "pending"; +} + +function legacyStatusFor(input: { + lifecycle: ActionLifecycle; + blockedReason?: string; + awaitingHuman: boolean; + approval?: ActionApproval; + hasDerivedBlockers: boolean; +}): Action["status"] { + if (input.lifecycle !== "pending") return input.lifecycle; + if ( + input.blockedReason || + input.awaitingHuman || + input.approval?.state === "pending" || + input.approval?.state === "rejected" || + input.hasDerivedBlockers + ) { + return "blocked"; + } + return "pending"; +} + +function normalizeApproval( + value: unknown, + warnings: string[], + conflicts: string[], +): ActionApproval | undefined { + if (value === undefined || value === null) return undefined; + if (typeof value !== "object" || Array.isArray(value)) { + conflicts.push("invalid_approval"); + return undefined; + } + const approval = value as Partial; + if (!isActionApprovalState(approval.state)) { + conflicts.push("invalid_approval_state"); + return undefined; + } + const timestampFields = ["requestedAt", "decidedAt"] as const; + for (const field of timestampFields) { + const timestamp = approval[field]; + if (timestamp !== undefined && !isValidActionTimestamp(timestamp)) { + conflicts.push(`invalid_approval_${field}`); + } + } + if ( + approval.state === "pending" && + (approval.decidedAt || approval.decidedBy) + ) { + warnings.push("pending_approval_has_decision_metadata"); + } + return { + state: approval.state, + requestedAt: nonEmpty(approval.requestedAt), + requestedBy: nonEmpty(approval.requestedBy), + decidedAt: nonEmpty(approval.decidedAt), + decidedBy: nonEmpty(approval.decidedBy), + note: nonEmpty(approval.note), + }; +} + +function typedOrTaggedTimestamp( + typed: unknown, + tagged: string | undefined, + field: string, + warnings: string[], + conflicts: string[], +): string | undefined { + if (typed !== undefined) { + if (isValidActionTimestamp(typed)) return typed; + conflicts.push(`invalid_${field}`); + return typeof typed === "string" ? typed : undefined; + } + if (!tagged) return undefined; + if (isValidActionTimestamp(tagged)) { + warnings.push(`${field}_migrated_from_tag`); + return tagged; + } + warnings.push(`invalid_${field}_tag`); + return undefined; +} + +function uniqueTagValues(tags: string[], prefix: string): string[] { + return [ + ...new Set( + tags + .map((tag) => tagValue(tag, prefix)) + .filter((value): value is string => value !== undefined), + ), + ]; +} + +function firstTagValue(tags: string[], prefix: string): string | undefined { + return uniqueTagValues(tags, prefix)[0]; +} + +function tagValue(tag: string, prefix: string): string | undefined { + const marker = `${prefix}:`; + if (!tag.toLowerCase().startsWith(marker.toLowerCase())) return undefined; + return nonEmpty(tag.slice(marker.length)); +} + +function normalizeStringArray(value: unknown): string[] { + if (!Array.isArray(value)) return []; + return [ + ...new Set( + value + .filter((item): item is string => typeof item === "string") + .map((item) => item.trim()) + .filter(Boolean), + ), + ]; +} + +function isProjectPath(value: string): boolean { + return isAbsolute(value) || win32.isAbsolute(value); +} + +function nonEmpty(value: unknown): string | undefined { + return typeof value === "string" && value.trim() ? value.trim() : undefined; +} + +export function isActionReadinessView( + value: unknown, +): value is ActionReadinessView { + return ( + typeof value === "string" && + [ + "actionable", + "scheduled", + "waiting", + "blocked", + "completed", + "cancelled", + ].includes(value) + ); +} diff --git a/src/functions/action-query.ts b/src/functions/action-query.ts new file mode 100644 index 0000000000..11133f4afa --- /dev/null +++ b/src/functions/action-query.ts @@ -0,0 +1,185 @@ +import type { + Action, + ActionReadinessView, + ActionViewItem, + Checkpoint, + Lease, + Sentinel, +} from "../types.js"; +import { + actionFilterFingerprint, + classifyAction, + decodeActionCursor, + encodeActionCursor, + normalizeActionTags, +} from "./action-model.js"; +import type { ActionStoreSnapshot } from "./action-store.js"; + +const DEFAULT_ACTION_LIMIT = 50; +const MAX_ACTION_LIMIT = 500; + +export interface ActionListOptions { + status?: string; + project?: string; + parentId?: string; + tags?: string[]; + owner?: string; + view?: ActionReadinessView; + agentId?: string; + limit?: number; + offset?: number; + cursor?: string; + revision?: number; +} + +export interface ActionPage { + success: true; + actions: Action[]; + views: ActionViewItem[]; + total: number; + limit: number; + offset: number; + hasMore: boolean; + revision: number; + nextCursor: string | null; + asOf: string; +} + +export class ActionQueryError extends Error { + constructor( + readonly code: "invalid_cursor" | "revision_conflict", + message: string, + ) { + super(message); + this.name = "ActionQueryError"; + } +} + +export function selectActionPage( + snapshot: ActionStoreSnapshot, + checkpoints: Checkpoint[], + sentinels: Sentinel[], + leases: Lease[], + options: ActionListOptions = {}, +): ActionPage { + const limit = normalizedLimit(options.limit); + const filter = actionFilterFingerprint({ + status: options.status, + project: options.project, + parentId: options.parentId, + tags: options.tags ? [...options.tags].sort() : undefined, + owner: options.owner, + view: options.view, + agentId: options.agentId, + }); + let offset = normalizedOffset(options.offset); + let expectedRevision = options.revision; + let asOf = Date.now(); + if (options.cursor) { + let decoded; + try { + decoded = decodeActionCursor(options.cursor); + } catch { + throw new ActionQueryError("invalid_cursor", "cursor is invalid"); + } + if (decoded.filter !== filter) { + throw new ActionQueryError( + "invalid_cursor", + "cursor does not match the requested filters", + ); + } + offset = decoded.offset; + asOf = decoded.asOf; + if ( + expectedRevision !== undefined && + expectedRevision !== decoded.revision + ) { + throw new ActionQueryError( + "revision_conflict", + "cursor and explicit revision do not match", + ); + } + expectedRevision = decoded.revision; + } + if ( + expectedRevision !== undefined && + expectedRevision !== snapshot.state.revision + ) { + throw new ActionQueryError( + "revision_conflict", + `action collection changed from revision ${expectedRevision} to ${snapshot.state.revision}`, + ); + } + + const views = snapshot.actions + .map((action) => + classifyAction(action, { + actions: snapshot.actions, + edges: snapshot.edges, + checkpoints, + sentinels, + leases, + agentId: options.agentId, + now: asOf, + }), + ) + .filter((item) => { + const action = item.action; + if (options.status && action.status !== options.status) return false; + if (options.project && !matchesActionProject(action, options.project)) { + return false; + } + if (options.parentId && action.parentId !== options.parentId) return false; + if (options.owner && action.owner !== options.owner) return false; + if (options.view && item.view !== options.view) return false; + if (options.tags && options.tags.length > 0) { + const actionTags = normalizeActionTags(action.tags); + if (!options.tags.some((tag) => actionTags.includes(tag))) return false; + } + return true; + }) + .sort((left, right) => { + const byUpdatedAt = String(right.action.updatedAt || "").localeCompare( + String(left.action.updatedAt || ""), + ); + return byUpdatedAt || left.action.id.localeCompare(right.action.id); + }); + + const pageViews = views.slice(offset, offset + limit); + const nextOffset = offset + pageViews.length; + const hasMore = nextOffset < views.length; + return { + success: true, + actions: pageViews.map((item) => item.action), + views: pageViews, + total: views.length, + limit, + offset, + hasMore, + revision: snapshot.state.revision, + asOf: new Date(asOf).toISOString(), + nextCursor: hasMore + ? encodeActionCursor(snapshot.state.revision, nextOffset, filter, asOf) + : null, + }; +} + +export function matchesActionProject(action: Action, project: string): boolean { + return ( + action.projectId === project || + action.project === project || + (Array.isArray(action.projectAliases) && + action.projectAliases.includes(project)) + ); +} + +function normalizedLimit(value?: number): number { + if (!Number.isInteger(value) || !value || value < 1) { + return DEFAULT_ACTION_LIMIT; + } + return Math.min(value, MAX_ACTION_LIMIT); +} + +function normalizedOffset(value?: number): number { + return Number.isInteger(value) && (value ?? -1) >= 0 ? value! : 0; +} diff --git a/src/functions/action-readiness-refresh.ts b/src/functions/action-readiness-refresh.ts new file mode 100644 index 0000000000..5cbe9e548c --- /dev/null +++ b/src/functions/action-readiness-refresh.ts @@ -0,0 +1,90 @@ +import type { StateKV } from "../state/kv.js"; +import { withKeyedLock } from "../state/keyed-mutex.js"; +import { KV } from "../state/schema.js"; +import type { + Action, + ActionEdge, + Checkpoint, + Sentinel, +} from "../types.js"; +import { persistAction } from "./action-store.js"; + +/** + * Re-project linked actions after a checkpoint or sentinel changes state. + * The touch event is deliberate: readiness-view cursors are bound to the + * action collection revision, so an external gate transition must advance it. + */ +export async function refreshLinkedActionReadiness( + kv: StateKV, + actionIds: string[], + actor: string, + reason: string, +): Promise { + const uniqueActionIds = [...new Set(actionIds)]; + if (uniqueActionIds.length === 0) return 0; + const [edges, actions, checkpoints, sentinels] = await Promise.all([ + kv.list(KV.actionEdges).catch(() => []), + kv.list(KV.actions).catch(() => []), + kv.list(KV.checkpoints).catch(() => []), + kv.list(KV.sentinels).catch(() => []), + ]); + const actionMap = new Map(actions.map((action) => [action.id, action])); + const checkpointMap = new Map( + checkpoints.map((checkpoint) => [checkpoint.id, checkpoint]), + ); + const sentinelMap = new Map( + sentinels.map((sentinel) => [sentinel.id, sentinel]), + ); + let unblockedCount = 0; + + for (const actionId of uniqueActionIds) { + await withKeyedLock(`mem:action:${actionId}`, async () => { + const action = await kv.get(KV.actions, actionId); + if (!action) return; + const lifecycle = + action.lifecycle ?? + (action.status === "active" || + action.status === "done" || + action.status === "cancelled" + ? action.status + : "pending"); + if (lifecycle === "done" || lifecycle === "cancelled") return; + + const relevantEdges = edges.filter( + (edge) => edge.sourceActionId === actionId, + ); + const hasDerivedBlockers = relevantEdges.some((edge) => { + if (edge.type === "requires") { + const dependency = actionMap.get(edge.targetActionId); + return (dependency?.lifecycle ?? dependency?.status) !== "done"; + } + if (edge.type === "gated_by") { + return ( + checkpointMap.get(edge.targetActionId)?.status !== "passed" && + sentinelMap.get(edge.targetActionId)?.status !== "triggered" + ); + } + return false; + }); + + const before = structuredClone(action); + if (lifecycle === "pending") { + action.lifecycle = "pending"; + action.status = hasDerivedBlockers ? "blocked" : "pending"; + } + action.updatedAt = new Date().toISOString(); + const persisted = await persistAction(kv, action, { + actor, + before, + hasDerivedBlockers, + reason, + }); + actionMap.set(action.id, persisted.action); + if (before.status === "blocked" && persisted.action.status !== "blocked") { + unblockedCount += 1; + } + }); + } + + return unblockedCount; +} diff --git a/src/functions/action-store.ts b/src/functions/action-store.ts new file mode 100644 index 0000000000..9a37acf93a --- /dev/null +++ b/src/functions/action-store.ts @@ -0,0 +1,380 @@ +import type { StateKV } from "../state/kv.js"; +import { withKeyedLock } from "../state/keyed-mutex.js"; +import { KV, generateId } from "../state/schema.js"; +import type { + Action, + ActionCollectionState, + ActionEdge, + ActionEvent, + ActionEventType, + Checkpoint, + Sentinel, +} from "../types.js"; +import { + ACTION_SCHEMA_VERSION, + normalizeActionV2, + type NormalizeActionOptions, + type NormalizeActionResult, +} from "./action-model.js"; + +const ACTION_STATE_KEY = "current"; +const ACTION_STORE_LOCK = "mem:actions:v2"; + +export interface ActionStoreSnapshot { + state: ActionCollectionState; + actions: Action[]; + edges: ActionEdge[]; + events: ActionEvent[]; +} + +export interface PersistActionOptions extends NormalizeActionOptions { + actor?: string; + type?: ActionEventType; + reason?: string; + correctionOf?: string; + before?: Action | null; +} + +export interface PersistActionResult extends NormalizeActionResult { + event: ActionEvent; + state: ActionCollectionState; +} + +export class ActionNormalizationError extends Error { + constructor(readonly conflicts: string[]) { + super(`Action normalization failed: ${conflicts.join(", ")}`); + this.name = "ActionNormalizationError"; + } +} + +export function withActionStoreLock(fn: () => Promise): Promise { + return withKeyedLock(ACTION_STORE_LOCK, fn); +} + +export async function readActionStoreSnapshot( + kv: StateKV, + options: { includeEvents?: boolean } = {}, +): Promise { + return withActionStoreLock(async () => { + const state = await recoverActionStoreUnlocked(kv); + const [actions, edges, events] = await Promise.all([ + kv.list(KV.actions).catch(() => []), + kv.list(KV.actionEdges).catch(() => []), + options.includeEvents + ? kv.list(KV.actionEvents).catch(() => []) + : Promise.resolve([] as ActionEvent[]), + ]); + return { state, actions, edges, events }; + }); +} + +export async function persistAction( + kv: StateKV, + input: Action, + options: PersistActionOptions = {}, +): Promise { + return withActionStoreLock(() => + persistActionUnlocked(kv, input, options), + ); +} + +export async function persistActionUnlocked( + kv: StateKV, + input: Action, + options: PersistActionOptions = {}, +): Promise { + const state = await recoverActionStoreUnlocked(kv); + const before = + options.before === undefined + ? await kv.get(KV.actions, input.id) + : options.before; + const revision = state.revision + 1; + const hasDerivedBlockers = + options.hasDerivedBlockers ?? + (await actionHasUnresolvedDerivedBlockers(kv, input.id)); + const normalization = normalizeActionV2(input, { + projectAliases: options.projectAliases, + defaultProjectId: options.defaultProjectId, + hasDerivedBlockers, + revision, + }); + if (normalization.conflicts.length > 0) { + throw new ActionNormalizationError(normalization.conflicts); + } + const action = normalization.action; + const timestamp = new Date().toISOString(); + const event: ActionEvent = { + schemaVersion: ACTION_SCHEMA_VERSION, + id: generateId("aev"), + actionId: action.id, + entityType: "action", + revision, + type: + options.type ?? + inferActionEventType(before, action, options.correctionOf), + actor: + options.actor || + action.owner || + action.assignedTo || + action.createdBy || + "unknown", + timestamp, + reason: options.reason, + correctionOf: options.correctionOf, + before: before ? clone(before) : undefined, + after: clone(action), + }; + const nextState = await commitEventUnlocked(kv, state, event); + return { ...normalization, action, event, state: nextState }; +} + +export async function deleteAction( + kv: StateKV, + actionId: string, + options: { + actor?: string; + reason?: string; + correctionOf?: string; + } = {}, +): Promise<{ deleted: boolean; event?: ActionEvent; state: ActionCollectionState }> { + return withActionStoreLock(async () => { + const state = await recoverActionStoreUnlocked(kv); + const before = await kv.get(KV.actions, actionId); + if (!before) return { deleted: false, state }; + const event: ActionEvent = { + schemaVersion: ACTION_SCHEMA_VERSION, + id: generateId("aev"), + actionId, + entityType: "action", + revision: state.revision + 1, + type: "deleted", + actor: options.actor || before.owner || before.createdBy || "unknown", + timestamp: new Date().toISOString(), + reason: options.reason, + correctionOf: options.correctionOf, + before: clone(before), + }; + const nextState = await commitEventUnlocked(kv, state, event); + return { deleted: true, event, state: nextState }; + }); +} + +export async function persistActionEdge( + kv: StateKV, + edge: ActionEdge, + options: { + actor?: string; + reason?: string; + before?: ActionEdge | null; + } = {}, +): Promise<{ edge: ActionEdge; event: ActionEvent; state: ActionCollectionState }> { + return withActionStoreLock(() => + persistActionEdgeUnlocked(kv, edge, options), + ); +} + +export async function persistActionEdgeUnlocked( + kv: StateKV, + edge: ActionEdge, + options: { + actor?: string; + reason?: string; + before?: ActionEdge | null; + } = {}, +): Promise<{ edge: ActionEdge; event: ActionEvent; state: ActionCollectionState }> { + const state = await recoverActionStoreUnlocked(kv); + const before = + options.before === undefined + ? await kv.get(KV.actionEdges, edge.id) + : options.before; + const event: ActionEvent = { + schemaVersion: ACTION_SCHEMA_VERSION, + id: generateId("aev"), + actionId: edge.sourceActionId, + entityType: "edge", + revision: state.revision + 1, + type: before ? "fields_changed" : "edge_created", + actor: options.actor || "unknown", + timestamp: new Date().toISOString(), + reason: options.reason, + before: before ? clone(before) : undefined, + after: clone(edge), + }; + const nextState = await commitEventUnlocked(kv, state, event); + return { edge, event, state: nextState }; +} + +export async function deleteActionEdge( + kv: StateKV, + edgeId: string, + options: { actor?: string; reason?: string } = {}, +): Promise<{ deleted: boolean; event?: ActionEvent; state: ActionCollectionState }> { + return withActionStoreLock(async () => { + const state = await recoverActionStoreUnlocked(kv); + const before = await kv.get(KV.actionEdges, edgeId); + if (!before) return { deleted: false, state }; + const event: ActionEvent = { + schemaVersion: ACTION_SCHEMA_VERSION, + id: generateId("aev"), + actionId: before.sourceActionId, + entityType: "edge", + revision: state.revision + 1, + type: "edge_deleted", + actor: options.actor || "unknown", + timestamp: new Date().toISOString(), + reason: options.reason, + before: clone(before), + }; + const nextState = await commitEventUnlocked(kv, state, event); + return { deleted: true, event, state: nextState }; + }); +} + +export async function recoverActionStore(kv: StateKV): Promise { + return withActionStoreLock(() => recoverActionStoreUnlocked(kv)); +} + +/** Read collection metadata without repairing a pending write. */ +export async function peekActionCollectionState( + kv: StateKV, +): Promise { + return readActionCollectionState(kv); +} + +export async function recoverActionStoreUnlocked( + kv: StateKV, +): Promise { + const state = await readActionCollectionState(kv); + if (!state.pending) return state; + const event = await kv.get(KV.actionEvents, state.pending.eventId); + if (event && event.revision === state.pending.revision) { + await applyEventProjection(kv, event); + const recovered: ActionCollectionState = { + schemaVersion: ACTION_SCHEMA_VERSION, + revision: Math.max(state.revision, event.revision), + updatedAt: new Date().toISOString(), + }; + await kv.set(KV.actionState, ACTION_STATE_KEY, recovered); + return recovered; + } + const cleared: ActionCollectionState = { + schemaVersion: ACTION_SCHEMA_VERSION, + revision: state.revision, + updatedAt: new Date().toISOString(), + }; + await kv.set(KV.actionState, ACTION_STATE_KEY, cleared); + return cleared; +} + +async function commitEventUnlocked( + kv: StateKV, + state: ActionCollectionState, + event: ActionEvent, +): Promise { + const pendingState: ActionCollectionState = { + schemaVersion: ACTION_SCHEMA_VERSION, + revision: state.revision, + updatedAt: event.timestamp, + pending: { revision: event.revision, eventId: event.id }, + }; + await kv.set(KV.actionState, ACTION_STATE_KEY, pendingState); + await kv.set(KV.actionEvents, event.id, event); + await applyEventProjection(kv, event); + const committed: ActionCollectionState = { + schemaVersion: ACTION_SCHEMA_VERSION, + revision: event.revision, + updatedAt: event.timestamp, + }; + await kv.set(KV.actionState, ACTION_STATE_KEY, committed); + return committed; +} + +async function applyEventProjection( + kv: StateKV, + event: ActionEvent, +): Promise { + if (event.entityType === "action") { + if (event.after) { + await kv.set(KV.actions, event.actionId, event.after as Action); + } else { + await kv.delete(KV.actions, event.actionId); + } + return; + } + const edge = (event.after ?? event.before) as ActionEdge | undefined; + if (!edge) return; + if (event.after) { + await kv.set(KV.actionEdges, edge.id, event.after as ActionEdge); + } else { + await kv.delete(KV.actionEdges, edge.id); + } +} + +async function readActionCollectionState( + kv: StateKV, +): Promise { + const state = await kv.get(KV.actionState, ACTION_STATE_KEY); + if ( + state?.schemaVersion === ACTION_SCHEMA_VERSION && + Number.isInteger(state.revision) && + state.revision >= 0 + ) { + return state; + } + return { + schemaVersion: ACTION_SCHEMA_VERSION, + revision: 0, + updatedAt: new Date(0).toISOString(), + }; +} + +function inferActionEventType( + before: Action | null, + after: Action, + correctionOf?: string, +): ActionEventType { + if (!before) return "created"; + if (correctionOf) return "corrected"; + if (before.result !== after.result) return "result_recorded"; + if ( + before.lifecycle !== after.lifecycle || + before.status !== after.status + ) { + return "lifecycle_changed"; + } + return "fields_changed"; +} + +async function actionHasUnresolvedDerivedBlockers( + kv: StateKV, + actionId: string, +): Promise { + const edges = (await kv.list(KV.actionEdges).catch(() => [])) + .filter( + (edge) => + edge.sourceActionId === actionId && + (edge.type === "requires" || edge.type === "gated_by"), + ); + for (const edge of edges) { + if (edge.type === "requires") { + const dependency = await kv.get(KV.actions, edge.targetActionId); + if ((dependency?.lifecycle ?? dependency?.status) !== "done") return true; + continue; + } + const [checkpoint, sentinel] = await Promise.all([ + kv.get(KV.checkpoints, edge.targetActionId), + kv.get(KV.sentinels, edge.targetActionId), + ]); + if ( + checkpoint?.status !== "passed" && + sentinel?.status !== "triggered" + ) { + return true; + } + } + return false; +} + +function clone(value: T): T { + return structuredClone(value); +} diff --git a/src/functions/actions-v2-migration.ts b/src/functions/actions-v2-migration.ts new file mode 100644 index 0000000000..ef06772d19 --- /dev/null +++ b/src/functions/actions-v2-migration.ts @@ -0,0 +1,279 @@ +import type { StateKV } from "../state/kv.js"; +import { KV } from "../state/schema.js"; +import type { Action, ActionEdge, Checkpoint, Sentinel } from "../types.js"; +import { + isCanonicalProjectId, + normalizeActionV2, + type NormalizeActionResult, +} from "./action-model.js"; +import { + peekActionCollectionState, + persistActionUnlocked, + recoverActionStoreUnlocked, + withActionStoreLock, +} from "./action-store.js"; +import { safeAudit } from "./audit.js"; + +const DEFAULT_MIGRATION_LIMIT = 100; +const MAX_MIGRATION_LIMIT = 500; + +export interface ActionsV2MigrationInput { + dryRun?: boolean; + projectAliases?: Record; + defaultProjectId?: string; + limit?: number; + cursor?: string; + actor?: string; +} + +interface MigrationCandidate { + action: Action; + normalized: NormalizeActionResult; + hasDerivedBlockers: boolean; +} + +export async function migrateActionsV2( + kv: StateKV, + input: ActionsV2MigrationInput = {}, +) { + return withActionStoreLock(async () => { + const configurationErrors = validateMigrationInput(input); + if (configurationErrors.length > 0) { + return { + success: false, + step: "actions-v2", + dryRun: input.dryRun !== false, + error: "invalid_migration_config", + configurationErrors, + }; + } + const dryRun = input.dryRun !== false; + const initialState = dryRun + ? await peekActionCollectionState(kv) + : await recoverActionStoreUnlocked(kv); + const [actions, edges, checkpoints, sentinels] = await Promise.all([ + kv.list(KV.actions).catch(() => []), + kv.list(KV.actionEdges).catch(() => []), + kv.list(KV.checkpoints).catch(() => []), + kv.list(KV.sentinels).catch(() => []), + ]); + const limit = normalizeLimit(input.limit); + const afterId = decodeMigrationCursor(input.cursor); + const ordered = [...actions].sort((left, right) => + left.id.localeCompare(right.id), + ); + const eligible = afterId + ? ordered.filter((action) => action.id > afterId) + : ordered; + const page = eligible.slice(0, limit); + const candidates: MigrationCandidate[] = page.map((action) => { + const hasDerivedBlockers = hasUnresolvedDerivedBlockers( + action.id, + actions, + edges, + checkpoints, + sentinels, + ); + return { + action, + hasDerivedBlockers, + normalized: normalizeActionV2(action, { + projectAliases: input.projectAliases, + defaultProjectId: input.defaultProjectId, + hasDerivedBlockers, + }), + }; + }); + + const conflicts = candidates.filter( + (candidate) => candidate.normalized.conflicts.length > 0, + ); + const changed = candidates.filter( + (candidate) => candidate.normalized.changed, + ); + const preview = candidates.map((candidate) => ({ + actionId: candidate.action.id, + changed: candidate.normalized.changed, + warnings: candidate.normalized.warnings, + conflicts: candidate.normalized.conflicts, + projectId: candidate.normalized.action.projectId, + })); + const hasMore = eligible.length > page.length; + const nextCursor = + hasMore && page.length > 0 + ? encodeMigrationCursor(page[page.length - 1].id) + : null; + const baseResult = { + step: "actions-v2", + dryRun, + scanned: page.length, + changed: changed.length, + skipped: page.length - changed.length, + warningCount: candidates.reduce( + (count, candidate) => count + candidate.normalized.warnings.length, + 0, + ), + conflictCount: conflicts.reduce( + (count, candidate) => count + candidate.normalized.conflicts.length, + 0, + ), + unresolvedActionIds: conflicts.map((candidate) => candidate.action.id), + preview, + revisionBefore: initialState.revision, + hasMore, + nextCursor, + }; + + if (dryRun) { + return { + success: conflicts.length === 0 && !initialState.pending, + ...(initialState.pending + ? { + error: "pending_action_store_recovery", + message: + "A pending action-store write must be recovered before migration", + } + : {}), + ...baseResult, + revisionAfter: initialState.revision, + }; + } + if (conflicts.length > 0) { + return { + success: false, + error: "migration_conflict", + message: "Resolve conflicting action identities before mutation", + ...baseResult, + revisionAfter: initialState.revision, + }; + } + + let revisionAfter = initialState.revision; + for (const candidate of changed) { + const persisted = await persistActionUnlocked(kv, candidate.action, { + actor: input.actor || "migration:actions-v2", + type: "migrated", + reason: candidate.normalized.warnings.join(",") || "Actions v2 normalization", + before: candidate.action, + projectAliases: input.projectAliases, + defaultProjectId: input.defaultProjectId, + hasDerivedBlockers: candidate.hasDerivedBlockers, + }); + revisionAfter = persisted.state.revision; + } + if (changed.length > 0) { + await safeAudit( + kv, + "action_update", + "mem::migrate", + changed.map((candidate) => candidate.action.id), + { + actor: input.actor || "migration:actions-v2", + step: "actions-v2", + scanned: page.length, + changed: changed.length, + revisionBefore: initialState.revision, + revisionAfter, + }, + ); + } + return { success: true, ...baseResult, revisionAfter }; + }); +} + +function validateMigrationInput(input: ActionsV2MigrationInput): string[] { + const errors: string[] = []; + if (input.dryRun !== undefined && typeof input.dryRun !== "boolean") { + errors.push("dryRun must be boolean"); + } + if ( + input.defaultProjectId !== undefined && + !isCanonicalProjectId(input.defaultProjectId) + ) { + errors.push("defaultProjectId must be a canonical non-path identifier"); + } + if ( + input.projectAliases !== undefined && + (!input.projectAliases || + typeof input.projectAliases !== "object" || + Array.isArray(input.projectAliases)) + ) { + errors.push("projectAliases must be an object"); + } else { + for (const [alias, projectId] of Object.entries( + input.projectAliases ?? {}, + )) { + if (!alias.trim()) errors.push("projectAliases cannot contain empty keys"); + if (!isCanonicalProjectId(projectId)) { + errors.push(`projectAliases[${alias}] must map to a canonical project ID`); + } + } + } + if ( + input.limit !== undefined && + (!Number.isInteger(input.limit) || input.limit < 1) + ) { + errors.push("limit must be a positive integer"); + } + return [...new Set(errors)]; +} + +function hasUnresolvedDerivedBlockers( + actionId: string, + actions: Action[], + edges: ActionEdge[], + checkpoints: Checkpoint[], + sentinels: Sentinel[], +): boolean { + const actionMap = new Map(actions.map((action) => [action.id, action])); + const checkpointMap = new Map( + checkpoints.map((checkpoint) => [checkpoint.id, checkpoint]), + ); + const sentinelMap = new Map( + sentinels.map((sentinel) => [sentinel.id, sentinel]), + ); + return edges.some((edge) => { + if (edge.sourceActionId !== actionId) return false; + if (edge.type === "requires") { + const dependency = actionMap.get(edge.targetActionId); + return ( + (dependency?.lifecycle ?? dependency?.status) !== "done" + ); + } + if (edge.type === "gated_by") { + return ( + checkpointMap.get(edge.targetActionId)?.status !== "passed" && + sentinelMap.get(edge.targetActionId)?.status !== "triggered" + ); + } + return false; + }); +} + +function normalizeLimit(value?: number): number { + if (!Number.isInteger(value) || !value || value < 1) { + return DEFAULT_MIGRATION_LIMIT; + } + return Math.min(value, MAX_MIGRATION_LIMIT); +} + +function encodeMigrationCursor(afterId: string): string { + return Buffer.from(JSON.stringify({ v: 1, afterId }), "utf8").toString( + "base64url", + ); +} + +function decodeMigrationCursor(cursor?: string): string | undefined { + if (!cursor) return undefined; + try { + const parsed = JSON.parse( + Buffer.from(cursor, "base64url").toString("utf8"), + ) as { v?: unknown; afterId?: unknown }; + if (parsed.v !== 1 || typeof parsed.afterId !== "string" || !parsed.afterId) { + throw new Error("invalid cursor"); + } + return parsed.afterId; + } catch { + throw new Error("cursor must be a valid actions-v2 migration cursor"); + } +} diff --git a/src/functions/actions.ts b/src/functions/actions.ts index 2cc3d79af7..f580b3e26f 100644 --- a/src/functions/actions.ts +++ b/src/functions/actions.ts @@ -1,46 +1,117 @@ import type { ISdk } from "iii-sdk"; import type { StateKV } from "../state/kv.js"; import { KV, generateId } from "../state/schema.js"; -import { withKeyedLock } from "../state/keyed-mutex.js"; -import type { Action, ActionEdge } from "../types.js"; +import type { + Action, + ActionApproval, + ActionEdge, + ActionLifecycle, + ActionReadinessView, + Checkpoint, + Lease, + Sentinel, +} from "../types.js"; import { recordAudit } from "./audit.js"; +import { + isActionApprovalState, + isActionLifecycle, + isActionReadinessView, + isCanonicalProjectId, + isValidActionTimestamp, + normalizeActionTags, +} from "./action-model.js"; +import { + ActionNormalizationError, + persistActionEdgeUnlocked, + persistActionUnlocked, + readActionStoreSnapshot, + recoverActionStoreUnlocked, + withActionStoreLock, +} from "./action-store.js"; +import { + ActionQueryError, + selectActionPage, + type ActionListOptions, +} from "./action-query.js"; -export function registerActionsFunction(sdk: ISdk, kv: StateKV): void { - sdk.registerFunction("mem::action-create", - async (data: { - title: string; - description?: string; - priority?: number; - createdBy?: string; - project?: string; - tags?: string[]; - parentId?: string; - sourceObservationIds?: string[]; - sourceMemoryIds?: string[]; - edges?: Array<{ type: string; targetActionId: string }>; - }) => { - if (!data.title || typeof data.title !== "string") { - return { success: false, error: "title is required" }; - } +const VALID_EDGE_TYPES: ActionEdge["type"][] = [ + "requires", + "unlocks", + "spawned_by", + "gated_by", + "conflicts_with", +]; +const LEGACY_STATUSES = new Set([ + "pending", + "active", + "done", + "blocked", + "cancelled", +]); - return withKeyedLock("mem:actions", async () => { - const now = new Date().toISOString(); - const action: Action = { - id: generateId("act"), - title: data.title.trim(), - description: (data.description || "").trim(), - status: "pending", - priority: Math.max(1, Math.min(10, data.priority || 5)), - createdAt: now, - updatedAt: now, - createdBy: data.createdBy || "unknown", - project: data.project, - tags: data.tags || [], - sourceObservationIds: data.sourceObservationIds || [], - sourceMemoryIds: data.sourceMemoryIds || [], - parentId: data.parentId, - }; +interface ActionCreateInput { + title: string; + description?: string; + priority?: number; + createdBy?: string; + actor?: string; + project?: string; + projectId?: string; + projectAliases?: string[]; + tags?: string[] | string; + parentId?: string; + sourceObservationIds?: string[]; + sourceMemoryIds?: string[]; + edges?: Array<{ type: string; targetActionId: string }>; + lifecycle?: ActionLifecycle; + owner?: string; + notBefore?: string; + dueAt?: string; + awaitingHuman?: boolean; + approval?: ActionApproval; + blockedReason?: string; + repoRoot?: string; + worktree?: string; + branch?: string; + taskSlug?: string; +} + +interface ActionUpdateInput { + actionId: string; + status?: Action["status"]; + lifecycle?: ActionLifecycle; + title?: string; + description?: string; + priority?: number; + assignedTo?: string; + owner?: string; + result?: string; + tags?: string[] | string; + project?: string; + projectId?: string; + projectAliases?: string[]; + notBefore?: string; + dueAt?: string; + awaitingHuman?: boolean; + approval?: ActionApproval; + blockedReason?: string; + repoRoot?: string; + worktree?: string; + branch?: string; + taskSlug?: string; + actor?: string; + correctionOf?: string; + correctionReason?: string; +} + +export function registerActionsFunction(sdk: ISdk, kv: StateKV): void { + sdk.registerFunction("mem::action-create", async (data: ActionCreateInput) => { + const validationError = validateCreateInput(data); + if (validationError) return { success: false, error: validationError }; + try { + return await withActionStoreLock(async () => { + await recoverActionStoreUnlocked(kv); if (data.parentId) { const parent = await kv.get(KV.actions, data.parentId); if (!parent) { @@ -48,110 +119,170 @@ export function registerActionsFunction(sdk: ISdk, kv: StateKV): void { } } - const validEdgeTypes = [ - "requires", - "unlocks", - "spawned_by", - "gated_by", - "conflicts_with", - ]; + const now = new Date().toISOString(); const pendingEdges: ActionEdge[] = []; - let hasRequires = false; - if (data.edges && Array.isArray(data.edges)) { - for (const e of data.edges) { - if (!validEdgeTypes.includes(e.type)) { - return { success: false, error: `invalid edge type: ${e.type}` }; - } - const targetAction = await kv.get(KV.actions, e.targetActionId); - if (!targetAction) { - return { success: false, error: `target action not found: ${e.targetActionId}` }; - } - if (e.type === "requires") hasRequires = true; - pendingEdges.push({ - id: generateId("ae"), - type: e.type as ActionEdge["type"], - sourceActionId: action.id, - targetActionId: e.targetActionId, - createdAt: now, - }); + for (const requestedEdge of data.edges ?? []) { + if (!isValidEdgeType(requestedEdge.type)) { + return { + success: false, + error: `invalid edge type: ${requestedEdge.type}`, + }; } + const targetExists = + requestedEdge.type === "gated_by" + ? await actionGateExists(kv, requestedEdge.targetActionId) + : Boolean( + await kv.get( + KV.actions, + requestedEdge.targetActionId, + ), + ); + if (!targetExists) { + return { + success: false, + error: + requestedEdge.type === "gated_by" + ? `gate not found: ${requestedEdge.targetActionId}` + : `target action not found: ${requestedEdge.targetActionId}`, + }; + } + pendingEdges.push({ + id: generateId("ae"), + type: requestedEdge.type, + sourceActionId: "", + targetActionId: requestedEdge.targetActionId, + createdAt: now, + }); } - if (hasRequires) { - action.status = "blocked"; - } - - await kv.set(KV.actions, action.id, action); - await recordAudit(kv, "action_create", "mem::action-create", [action.id], { - actor: data.createdBy || "unknown", - action, - edges: pendingEdges, + const actor = data.actor || data.createdBy || data.owner || "unknown"; + const actionId = generateId("act"); + for (const edge of pendingEdges) edge.sourceActionId = actionId; + const hasDerivedBlockers = pendingEdges.some( + (edge) => edge.type === "requires" || edge.type === "gated_by", + ); + const action: Action = { + id: actionId, + title: data.title.trim(), + description: (data.description || "").trim(), + status: hasDerivedBlockers ? "blocked" : "pending", + lifecycle: data.lifecycle ?? "pending", + priority: normalizePriority(data.priority), + createdAt: now, + updatedAt: now, + createdBy: data.createdBy || actor, + project: data.project || data.projectId, + projectId: data.projectId, + projectAliases: data.projectAliases, + tags: normalizeActionTags(data.tags), + sourceObservationIds: data.sourceObservationIds || [], + sourceMemoryIds: data.sourceMemoryIds || [], + parentId: data.parentId, + owner: data.owner, + notBefore: data.notBefore, + dueAt: data.dueAt, + awaitingHuman: data.awaitingHuman, + approval: data.approval, + blockedReason: data.blockedReason, + repoRoot: data.repoRoot, + worktree: data.worktree, + branch: data.branch, + taskSlug: data.taskSlug, + }; + const persisted = await persistActionUnlocked(kv, action, { + actor, + type: "created", + hasDerivedBlockers, + before: null, }); - + let finalState = persisted.state; for (const edge of pendingEdges) { - await kv.set(KV.actionEdges, edge.id, edge); + const persistedEdge = await persistActionEdgeUnlocked(kv, edge, { + actor, + reason: "inline action dependency", + before: null, + }); + finalState = persistedEdge.state; } - - return { success: true, action, edges: pendingEdges }; + await recordAudit( + kv, + "action_create", + "mem::action-create", + [persisted.action.id], + { actor, action: persisted.action, edges: pendingEdges }, + ); + return { + success: true, + action: persisted.action, + edges: pendingEdges, + revision: finalState.revision, + warnings: persisted.warnings, + }; }); - }, - ); + } catch (error) { + return actionStoreError(error); + } + }); - sdk.registerFunction("mem::action-update", - async (data: { - actionId: string; - status?: Action["status"]; - title?: string; - description?: string; - priority?: number; - assignedTo?: string; - result?: string; - tags?: string[]; - }) => { - if (!data.actionId) { - return { success: false, error: "actionId is required" }; - } - - return withKeyedLock(`mem:action:${data.actionId}`, async () => { - const action = await kv.get(KV.actions, data.actionId); - if (!action) { - return { success: false, error: "action not found" }; - } - const before = { ...action }; + sdk.registerFunction("mem::action-update", async (data: ActionUpdateInput) => { + const validationError = validateUpdateInput(data); + if (validationError) return { success: false, error: validationError }; - if (data.status !== undefined) action.status = data.status; - if (data.title !== undefined) action.title = data.title.trim(); - if (data.description !== undefined) - action.description = data.description.trim(); - if (data.priority !== undefined) - action.priority = Math.max(1, Math.min(10, data.priority)); - if (data.assignedTo !== undefined) action.assignedTo = data.assignedTo; - if (data.result !== undefined) action.result = data.result; - if (data.tags !== undefined) action.tags = data.tags; + try { + return await withActionStoreLock(async () => { + await recoverActionStoreUnlocked(kv); + const existing = await kv.get(KV.actions, data.actionId); + if (!existing) return { success: false, error: "action not found" }; + const before = structuredClone(existing); + const edges = await kv.list(KV.actionEdges); + const hasDerivedBlockers = await hasUnsatisfiedDerivedBlockers( + kv, + existing.id, + edges, + ); + const action = applyActionUpdate(existing, data, hasDerivedBlockers); action.updatedAt = new Date().toISOString(); - - await kv.set(KV.actions, action.id, action); - await recordAudit(kv, "action_update", "mem::action-update", [action.id], { - actor: data.assignedTo || "unknown", + const actor = + data.actor || data.assignedTo || data.owner || existing.owner || "unknown"; + const persisted = await persistActionUnlocked(kv, action, { + actor, + reason: data.correctionReason, + correctionOf: data.correctionOf, before, - after: action, + hasDerivedBlockers, }); - - if (data.status === "done") { - await propagateCompletion(kv, action.id); + await recordAudit( + kv, + "action_update", + "mem::action-update", + [action.id], + { actor, before, after: persisted.action }, + ); + if (persisted.action.lifecycle === "done") { + await propagateCompletionUnlocked(kv, persisted.action.id, actor); } - - return { success: true, action }; + const finalState = await recoverActionStoreUnlocked(kv); + return { + success: true, + action: persisted.action, + event: persisted.event, + revision: finalState.revision, + warnings: persisted.warnings, + }; }); - }, - ); + } catch (error) { + return actionStoreError(error); + } + }); - sdk.registerFunction("mem::action-edge-create", + sdk.registerFunction( + "mem::action-edge-create", async (data: { sourceActionId: string; targetActionId: string; type: string; metadata?: Record; + actor?: string; }) => { if (!data.sourceActionId || !data.targetActionId || !data.type) { return { @@ -159,160 +290,473 @@ export function registerActionsFunction(sdk: ISdk, kv: StateKV): void { error: "sourceActionId, targetActionId, and type are required", }; } - - const validTypes = [ - "requires", - "unlocks", - "spawned_by", - "gated_by", - "conflicts_with", - ]; - if (!validTypes.includes(data.type)) { + if (!isValidEdgeType(data.type)) { return { success: false, - error: `type must be one of: ${validTypes.join(", ")}`, + error: `type must be one of: ${VALID_EDGE_TYPES.join(", ")}`, }; } - const sourceAction = await kv.get(KV.actions, data.sourceActionId); - if (!sourceAction) { - return { success: false, error: "source action not found" }; - } - const targetAction = await kv.get(KV.actions, data.targetActionId); - if (!targetAction) { - return { success: false, error: "target action not found" }; + try { + return await withActionStoreLock(async () => { + await recoverActionStoreUnlocked(kv); + const sourceAction = await kv.get( + KV.actions, + data.sourceActionId, + ); + if (!sourceAction) { + return { success: false, error: "source action not found" }; + } + const targetExists = + data.type === "gated_by" + ? await actionGateExists(kv, data.targetActionId) + : Boolean( + await kv.get(KV.actions, data.targetActionId), + ); + if (!targetExists) { + return { + success: false, + error: + data.type === "gated_by" + ? "gate not found" + : "target action not found", + }; + } + const edge: ActionEdge = { + id: generateId("ae"), + type: data.type, + sourceActionId: data.sourceActionId, + targetActionId: data.targetActionId, + createdAt: new Date().toISOString(), + metadata: data.metadata, + }; + const actor = data.actor || "unknown"; + const persistedEdge = await persistActionEdgeUnlocked(kv, edge, { + actor, + before: null, + }); + let finalState = persistedEdge.state; + if (edge.type === "requires" || edge.type === "gated_by") { + const before = structuredClone(sourceAction); + sourceAction.status = "blocked"; + sourceAction.lifecycle = sourceAction.lifecycle ?? "pending"; + sourceAction.updatedAt = new Date().toISOString(); + const persistedSource = await persistActionUnlocked(kv, sourceAction, { + actor, + before, + hasDerivedBlockers: true, + reason: `${edge.type} edge added`, + }); + finalState = persistedSource.state; + } + await recordAudit( + kv, + "action_create", + "mem::action-edge-create", + [edge.id], + { actor, edge }, + ); + return { + success: true, + edge, + event: persistedEdge.event, + revision: finalState.revision, + }; + }); + } catch (error) { + return actionStoreError(error); } - - const edge: ActionEdge = { - id: generateId("ae"), - type: data.type as ActionEdge["type"], - sourceActionId: data.sourceActionId, - targetActionId: data.targetActionId, - createdAt: new Date().toISOString(), - metadata: data.metadata, - }; - - await kv.set(KV.actionEdges, edge.id, edge); - await recordAudit(kv, "action_create", "mem::action-edge-create", [edge.id], { - actor: "unknown", - edge, - }); - return { success: true, edge }; }, ); - sdk.registerFunction("mem::action-list", - async (data: { - status?: string; - project?: string; - parentId?: string; - tags?: string[]; - limit?: number; - offset?: number; - }) => { - let actions = await kv.list(KV.actions); - - if (data.status) { - actions = actions.filter((a) => a.status === data.status); - } - if (data.project) { - actions = actions.filter((a) => a.project === data.project); - } - if (data.parentId) { - actions = actions.filter((a) => a.parentId === data.parentId); - } - if (data.tags && data.tags.length > 0) { - actions = actions.filter((a) => - data.tags!.some((t) => a.tags.includes(t)), - ); - } - - actions.sort( - (a, b) => { - const updatedAtDifference = - new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(); - return updatedAtDifference || a.id.localeCompare(b.id); - }, - ); - - const total = actions.length; - const limit = - Number.isInteger(data.limit) && data.limit! > 0 - ? Math.min(data.limit!, 500) - : 50; - const offset = - Number.isInteger(data.offset) && data.offset! >= 0 ? data.offset! : 0; - const page = actions.slice(offset, offset + limit); - + sdk.registerFunction("mem::action-list", async (data: ActionListOptions) => { + if (data.view !== undefined && !isActionReadinessView(data.view)) { return { - success: true, - actions: page, - total, - limit, - offset, - hasMore: offset + page.length < total, + success: false, + error: "view must be actionable, scheduled, waiting, blocked, completed, or cancelled", }; - }, - ); - - sdk.registerFunction("mem::action-get", - async (data: { actionId: string }) => { - if (!data.actionId) { - return { success: false, error: "actionId is required" }; - } - const action = await kv.get(KV.actions, data.actionId); - if (!action) { - return { success: false, error: "action not found" }; + } + if ( + data.status !== undefined && + !LEGACY_STATUSES.has(data.status as Action["status"]) + ) { + return { + success: false, + error: "status must be pending, active, done, blocked, or cancelled", + }; + } + try { + const [snapshot, checkpoints, sentinels, leases] = await Promise.all([ + readActionStoreSnapshot(kv), + kv.list(KV.checkpoints).catch(() => []), + kv.list(KV.sentinels).catch(() => []), + kv.list(KV.leases).catch(() => []), + ]); + return selectActionPage(snapshot, checkpoints, sentinels, leases, data); + } catch (error) { + if (error instanceof ActionQueryError) { + return { success: false, error: error.code, message: error.message }; } + return actionStoreError(error); + } + }); - const allEdges = await kv.list(KV.actionEdges); - const edges = allEdges.filter( - (e) => - e.sourceActionId === data.actionId || - e.targetActionId === data.actionId, - ); - - const children = (await kv.list(KV.actions)).filter( - (a) => a.parentId === data.actionId, + sdk.registerFunction("mem::action-get", async (data: { actionId: string }) => { + if (!data.actionId) { + return { success: false, error: "actionId is required" }; + } + const snapshot = await readActionStoreSnapshot(kv, { includeEvents: true }); + const action = snapshot.actions.find((candidate) => candidate.id === data.actionId); + if (!action) return { success: false, error: "action not found" }; + const edges = snapshot.edges.filter( + (edge) => + edge.sourceActionId === data.actionId || + edge.targetActionId === data.actionId, + ); + const children = snapshot.actions.filter( + (candidate) => candidate.parentId === data.actionId, + ); + const events = snapshot.events + .filter((event) => event.actionId === data.actionId) + .sort( + (left, right) => + left.revision - right.revision || + left.timestamp.localeCompare(right.timestamp) || + left.id.localeCompare(right.id), ); + return { + success: true, + action, + edges, + children, + events, + revision: snapshot.state.revision, + }; + }); +} - return { success: true, action, edges, children }; - }, +async function propagateCompletionUnlocked( + kv: StateKV, + completedActionId: string, + actor: string, +): Promise { + const allEdges = await kv.list(KV.actionEdges); + const candidates = new Set( + allEdges + .filter( + (edge) => + edge.targetActionId === completedActionId && + (edge.type === "requires" || edge.type === "unlocks"), + ) + .map((edge) => edge.sourceActionId), ); + for (const candidateId of candidates) { + const action = await kv.get(KV.actions, candidateId); + if (!action || action.lifecycle === "done" || action.lifecycle === "cancelled") { + continue; + } + const lifecycle = + action.lifecycle ?? (action.status === "active" ? "active" : "pending"); + if (lifecycle !== "pending") continue; + const stillBlocked = await hasUnsatisfiedDerivedBlockers( + kv, + action.id, + allEdges, + ); + if (stillBlocked || action.blockedReason || action.awaitingHuman) continue; + const before = structuredClone(action); + action.status = "pending"; + action.lifecycle = "pending"; + action.updatedAt = new Date().toISOString(); + await persistActionUnlocked(kv, action, { + actor, + before, + hasDerivedBlockers: false, + reason: `Dependency ${completedActionId} completed`, + }); + } } -async function propagateCompletion( +export async function propagateActionCompletion( kv: StateKV, completedActionId: string, + actor: string, ): Promise { - const allEdges = await kv.list(KV.actionEdges); - const unlockEdges = allEdges.filter( - (e) => - e.targetActionId === completedActionId && - (e.type === "requires" || e.type === "unlocks"), + await withActionStoreLock(async () => { + await recoverActionStoreUnlocked(kv); + await propagateCompletionUnlocked(kv, completedActionId, actor); + }); +} + +async function hasUnsatisfiedDerivedBlockers( + kv: StateKV, + actionId: string, + edges: ActionEdge[], +): Promise { + const relevant = edges.filter( + (edge) => + edge.sourceActionId === actionId && + (edge.type === "requires" || edge.type === "gated_by"), ); + for (const edge of relevant) { + if (edge.type === "requires") { + const dependency = await kv.get(KV.actions, edge.targetActionId); + const lifecycle = dependency?.lifecycle ?? dependency?.status; + if (lifecycle !== "done") return true; + } else { + const checkpoint = await kv.get( + KV.checkpoints, + edge.targetActionId, + ); + if (checkpoint?.status === "passed") continue; + const sentinel = await kv.get( + KV.sentinels, + edge.targetActionId, + ); + if (sentinel?.status !== "triggered") return true; + } + } + return false; +} - const allActions = await kv.list(KV.actions); - const actionMap = new Map(allActions.map((a) => [a.id, a])); +async function actionGateExists( + kv: StateKV, + targetId: string, +): Promise { + const [checkpoint, sentinel] = await Promise.all([ + kv.get(KV.checkpoints, targetId), + kv.get(KV.sentinels, targetId), + ]); + return Boolean(checkpoint || sentinel); +} - for (const edge of unlockEdges) { - const candidateId = edge.sourceActionId; - await withKeyedLock(`mem:action:${candidateId}`, async () => { - const action = await kv.get(KV.actions, candidateId); - if (action && action.status === "blocked") { - const deps = allEdges.filter( - (e) => e.sourceActionId === action.id && e.type === "requires", - ); - const allDone = deps.every((d) => { - const target = actionMap.get(d.targetActionId); - return target && target.status === "done"; - }); - if (allDone) { - action.status = "pending"; - action.updatedAt = new Date().toISOString(); - await kv.set(KV.actions, action.id, action); - } +function applyActionUpdate( + action: Action, + data: ActionUpdateInput, + hasDerivedBlockers: boolean, +): Action { + const updated = { ...action }; + if (data.title !== undefined) updated.title = data.title.trim(); + if (data.description !== undefined) { + updated.description = data.description.trim(); + } + if (data.priority !== undefined) updated.priority = normalizePriority(data.priority); + if (data.assignedTo !== undefined) updated.assignedTo = data.assignedTo || undefined; + if (data.owner !== undefined) updated.owner = data.owner || undefined; + if (data.result !== undefined) updated.result = data.result; + if (data.tags !== undefined) updated.tags = normalizeActionTags(data.tags); + if (data.project !== undefined) { + const previousProject = updated.projectId || updated.project; + updated.project = data.project; + if (data.projectId === undefined) { + updated.projectId = undefined; + updated.projectAliases = normalizeActionTags([ + ...(updated.projectAliases ?? []), + ...(previousProject ? [previousProject] : []), + ]); + } + } + if (data.projectId !== undefined) updated.projectId = data.projectId; + if (data.projectAliases !== undefined) { + updated.projectAliases = normalizeActionTags(data.projectAliases); + } + if (data.notBefore !== undefined) updated.notBefore = data.notBefore || undefined; + if (data.dueAt !== undefined) updated.dueAt = data.dueAt || undefined; + if (data.awaitingHuman !== undefined) updated.awaitingHuman = data.awaitingHuman; + if (data.approval !== undefined) updated.approval = data.approval; + if (data.blockedReason !== undefined) { + updated.blockedReason = data.blockedReason || undefined; + } + if (data.repoRoot !== undefined) updated.repoRoot = data.repoRoot || undefined; + if (data.worktree !== undefined) updated.worktree = data.worktree || undefined; + if (data.branch !== undefined) updated.branch = data.branch || undefined; + if (data.taskSlug !== undefined) updated.taskSlug = data.taskSlug || undefined; + + if (data.status !== undefined) { + updated.status = data.status; + if (data.status === "blocked") { + updated.lifecycle = "pending"; + updated.blockedReason = + data.blockedReason || + data.result || + updated.blockedReason || + (hasDerivedBlockers ? undefined : "Blocked by legacy status update"); + } else { + updated.lifecycle = data.status; + if (data.status === "pending") updated.blockedReason = undefined; + } + } + if (data.lifecycle !== undefined) { + updated.lifecycle = data.lifecycle; + if (data.lifecycle !== "pending") updated.status = data.lifecycle; + } + return updated; +} + +function validateCreateInput(data: ActionCreateInput): string | undefined { + if (!data?.title || typeof data.title !== "string" || !data.title.trim()) { + return "title is required"; + } + if (data.description !== undefined && typeof data.description !== "string") { + return "description must be a string"; + } + for (const [field, value] of [ + ["sourceObservationIds", data.sourceObservationIds], + ["sourceMemoryIds", data.sourceMemoryIds], + ] as const) { + if ( + value !== undefined && + (!Array.isArray(value) || + value.some((item) => typeof item !== "string")) + ) { + return `${field} must be an array of strings`; + } + } + if ( + data.edges !== undefined && + (!Array.isArray(data.edges) || + data.edges.some( + (edge) => + !edge || + typeof edge !== "object" || + typeof edge.type !== "string" || + typeof edge.targetActionId !== "string", + )) + ) { + return "edges must contain type and targetActionId strings"; + } + return validateSharedInput(data); +} + +function validateUpdateInput(data: ActionUpdateInput): string | undefined { + if (!data?.actionId || typeof data.actionId !== "string") { + return "actionId is required"; + } + if (data.status !== undefined && !LEGACY_STATUSES.has(data.status)) { + return "status must be pending, active, done, blocked, or cancelled"; + } + if ( + data.title !== undefined && + (typeof data.title !== "string" || !data.title.trim()) + ) { + return "title must be a non-empty string"; + } + if (data.description !== undefined && typeof data.description !== "string") { + return "description must be a string"; + } + return validateSharedInput(data); +} + +function validateSharedInput( + data: Partial, +): string | undefined { + if ( + data.priority !== undefined && + (typeof data.priority !== "number" || !Number.isFinite(data.priority)) + ) { + return "priority must be a finite number"; + } + if (data.lifecycle !== undefined && !isActionLifecycle(data.lifecycle)) { + return "lifecycle must be pending, active, done, or cancelled"; + } + if (data.projectId !== undefined && !isCanonicalProjectId(data.projectId)) { + return "projectId must be a canonical non-path identifier"; + } + if ( + data.project !== undefined && + (typeof data.project !== "string" || !data.project.trim()) + ) { + return "project must be a non-empty string"; + } + if ( + data.projectAliases !== undefined && + (!Array.isArray(data.projectAliases) || + data.projectAliases.some((alias) => typeof alias !== "string")) + ) { + return "projectAliases must be an array of strings"; + } + if ( + data.tags !== undefined && + typeof data.tags !== "string" && + (!Array.isArray(data.tags) || + data.tags.some((tag) => typeof tag !== "string")) + ) { + return "tags must be a string or an array of strings"; + } + if ( + data.awaitingHuman !== undefined && + typeof data.awaitingHuman !== "boolean" + ) { + return "awaitingHuman must be boolean"; + } + for (const [field, value] of [ + ["createdBy", data.createdBy], + ["actor", data.actor], + ["parentId", data.parentId], + ["owner", data.owner], + ["assignedTo", data.assignedTo], + ["result", data.result], + ["blockedReason", data.blockedReason], + ["repoRoot", data.repoRoot], + ["worktree", data.worktree], + ["branch", data.branch], + ["taskSlug", data.taskSlug], + ["correctionOf", data.correctionOf], + ["correctionReason", data.correctionReason], + ] as const) { + if (value !== undefined && typeof value !== "string") { + return `${field} must be a string`; + } + } + if (data.notBefore && !isValidActionTimestamp(data.notBefore)) { + return "notBefore must be a valid timestamp"; + } + if (data.dueAt && !isValidActionTimestamp(data.dueAt)) { + return "dueAt must be a valid timestamp"; + } + if ( + data.approval !== undefined && + (!data.approval || !isActionApprovalState(data.approval.state)) + ) { + return "approval.state is invalid"; + } + if (data.approval) { + for (const field of ["requestedAt", "decidedAt"] as const) { + const timestamp = data.approval[field]; + if (timestamp !== undefined && !isValidActionTimestamp(timestamp)) { + return `approval.${field} must be a valid timestamp`; } - }); + } + for (const field of ["requestedBy", "decidedBy", "note"] as const) { + const value = data.approval[field]; + if (value !== undefined && typeof value !== "string") { + return `approval.${field} must be a string`; + } + } } + return undefined; +} + +function normalizePriority(value?: number): number { + return Math.max(1, Math.min(10, value || 5)); +} + +function isValidEdgeType(value: string): value is ActionEdge["type"] { + return VALID_EDGE_TYPES.includes(value as ActionEdge["type"]); } + +function actionStoreError(error: unknown) { + if (error instanceof ActionNormalizationError) { + return { + success: false, + error: "action normalization failed", + conflicts: error.conflicts, + }; + } + return { + success: false, + error: error instanceof Error ? error.message : String(error), + }; +} + +export type { ActionListOptions, ActionReadinessView }; diff --git a/src/functions/checkpoints.ts b/src/functions/checkpoints.ts index efb3957a9c..c25d5ecf98 100644 --- a/src/functions/checkpoints.ts +++ b/src/functions/checkpoints.ts @@ -4,6 +4,8 @@ import { KV, generateId } from "../state/schema.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import type { Action, ActionEdge, Checkpoint } from "../types.js"; import { recordAudit } from "./audit.js"; +import { persistAction, persistActionEdge } from "./action-store.js"; +import { refreshLinkedActionReadiness } from "./action-readiness-refresh.js"; export function registerCheckpointsFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::checkpoint-create", @@ -62,14 +64,25 @@ export function registerCheckpointsFunction(sdk: ISdk, kv: StateKV): void { targetActionId: checkpoint.id, createdAt: now.toISOString(), }; - await kv.set(KV.actionEdges, edge.id, edge); + await persistActionEdge(kv, edge, { + actor: "checkpoint-create", + reason: `Checkpoint ${checkpoint.id} added`, + before: null, + }); const action = await kv.get(KV.actions, actionId); if (action && action.status === "pending") { const previousStatus = action.status; + const before = structuredClone(action); action.status = "blocked"; + action.lifecycle = "pending"; action.updatedAt = now.toISOString(); - await kv.set(KV.actions, action.id, action); + await persistAction(kv, action, { + actor: "checkpoint-create", + before, + hasDerivedBlockers: true, + reason: `Waiting for checkpoint ${checkpoint.id}`, + }); await recordAudit(kv, "action_update", "mem::checkpoint-create", [action.id], { action: "status-change", previousStatus, @@ -128,49 +141,12 @@ export function registerCheckpointsFunction(sdk: ISdk, kv: StateKV): void { newStatus: checkpoint.status, }); - let unblockedCount = 0; - if (data.status === "passed" && checkpoint.linkedActionIds.length > 0) { - const allEdges = await kv.list(KV.actionEdges); - const allCheckpoints = await kv.list(KV.checkpoints); - const allActions = await kv.list(KV.actions); - const cpMap = new Map(allCheckpoints.map((c) => [c.id, c])); - const actionMap = new Map(allActions.map((a) => [a.id, a])); - - for (const actionId of checkpoint.linkedActionIds) { - await withKeyedLock(`mem:action:${actionId}`, async () => { - const action = await kv.get(KV.actions, actionId); - if (action && action.status === "blocked") { - const gates = allEdges.filter( - (e) => e.sourceActionId === actionId && e.type === "gated_by", - ); - const allGatesPassed = gates.every((g) => { - const cp = cpMap.get(g.targetActionId); - return cp && cp.status === "passed"; - }); - const requires = allEdges.filter( - (e) => e.sourceActionId === actionId && e.type === "requires", - ); - const allRequiresMet = requires.every((r) => { - const dep = actionMap.get(r.targetActionId); - return dep && dep.status === "done"; - }); - if (allGatesPassed && allRequiresMet) { - const previousStatus = action.status; - action.status = "pending"; - action.updatedAt = new Date().toISOString(); - await kv.set(KV.actions, action.id, action); - await recordAudit(kv, "action_update", "mem::checkpoint-resolve", [action.id], { - action: "unblock", - checkpointId: checkpoint.id, - previousStatus, - newStatus: action.status, - }); - unblockedCount++; - } - } - }); - } - } + const unblockedCount = await refreshLinkedActionReadiness( + kv, + checkpoint.linkedActionIds, + data.resolvedBy || "checkpoint-resolve", + `Checkpoint ${checkpoint.id} resolved ${checkpoint.status}`, + ); return { success: true, checkpoint, unblockedCount }; }, diff --git a/src/functions/crystallize.ts b/src/functions/crystallize.ts index 1f0b84316d..98598c13fc 100644 --- a/src/functions/crystallize.ts +++ b/src/functions/crystallize.ts @@ -2,6 +2,7 @@ import type { ISdk } from "iii-sdk"; import type { StateKV } from "../state/kv.js"; import { KV, generateId } from "../state/schema.js"; import type { Action, ActionEdge, Crystal, MemoryProvider } from "../types.js"; +import { persistAction } from "./action-store.js"; interface CrystalDigest { narrative: string; @@ -92,7 +93,11 @@ export function registerCrystallizeFunction( for (const action of actions) { const updated = { ...action, crystallizedInto: crystal.id }; - await kv.set(KV.actions, action.id, updated); + await persistAction(kv, updated, { + actor: "crystallize", + before: action, + reason: `Crystallized into ${crystal.id}`, + }); } return { success: true, crystal }; diff --git a/src/functions/diagnostics.ts b/src/functions/diagnostics.ts index cc982883f6..c7696e66a3 100644 --- a/src/functions/diagnostics.ts +++ b/src/functions/diagnostics.ts @@ -3,6 +3,11 @@ import type { StateKV } from "../state/kv.js"; import { KV } from "../state/schema.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import { recordAudit } from "./audit.js"; +import { + deleteAction, + deleteActionEdge, + persistAction, +} from "./action-store.js"; import type { Action, ActionEdge, @@ -685,9 +690,16 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { return target && target.status === "done"; }); if (!stillAllDone) return false; + const before = structuredClone(fresh); fresh.status = "pending"; + fresh.lifecycle = "pending"; fresh.updatedAt = new Date().toISOString(); - await kv.set(KV.actions, fresh.id, fresh); + await persistAction(kv, fresh, { + actor: "heal", + before, + hasDerivedBlockers: false, + reason: "blocked dependencies completed", + }); await recordAudit(kv, "heal", "mem::heal", [fresh.id], { reason: "blocked-deps-done", previousStatus: "blocked", @@ -744,9 +756,16 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { return !target || target.status !== "done"; }); if (!stillUnsatisfied) return false; + const before = structuredClone(fresh); fresh.status = "blocked"; + fresh.lifecycle = "pending"; fresh.updatedAt = new Date().toISOString(); - await kv.set(KV.actions, fresh.id, fresh); + await persistAction(kv, fresh, { + actor: "heal", + before, + hasDerivedBlockers: true, + reason: "pending action has unsatisfied dependencies", + }); await recordAudit(kv, "heal", "mem::heal", [fresh.id], { reason: "pending-unsatisfied-deps", previousStatus: "pending", @@ -811,10 +830,16 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { action.status === "active" && action.assignedTo === fresh.agentId ) { + const before = structuredClone(action); action.status = "pending"; + action.lifecycle = "pending"; action.assignedTo = undefined; action.updatedAt = new Date().toISOString(); - await kv.set(KV.actions, action.id, action); + await persistAction(kv, action, { + actor: "heal", + before, + reason: "released expired lease", + }); await recordAudit(kv, "heal", "mem::heal", [action.id], { entityType: "action", reason: "release-expired-lease", @@ -941,7 +966,10 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { actionIdSet.has(edge.sourceActionId) || actionIdSet.has(edge.targetActionId) ) { - await kv.delete(KV.actionEdges, edge.id); + await deleteActionEdge(kv, edge.id, { + actor: "heal", + reason: `Garbage-collected discarded sketch ${fresh.id}`, + }); await recordAudit(kv, "heal", "mem::heal", [edge.id], { entityType: "actionEdge", reason: "sketch-gc-discard", @@ -950,7 +978,10 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { } } for (const actionId of fresh.actionIds) { - await kv.delete(KV.actions, actionId); + await deleteAction(kv, actionId, { + actor: "heal", + reason: `Garbage-collected discarded sketch ${fresh.id}`, + }); await recordAudit(kv, "heal", "mem::heal", [actionId], { entityType: "action", reason: "sketch-gc-discard", diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 327117b265..515d499ef9 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -12,6 +12,8 @@ import type { ProceduralMemory, Action, ActionEdge, + ActionCollectionState, + ActionEvent, Routine, Signal, Checkpoint, @@ -30,6 +32,14 @@ import { StateKV } from "../state/kv.js"; import { VERSION } from "../version.js"; import { recordAudit } from "./audit.js"; import { logger } from "../logger.js"; +import { + ACTION_SCHEMA_VERSION, + normalizeActionV2, +} from "./action-model.js"; +import { + readActionStoreSnapshot, + withActionStoreLock, +} from "./action-store.js"; export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::export", @@ -77,8 +87,7 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { graphEdges, semanticMemories, proceduralMemories, - actions, - actionEdges, + actionStore, sentinels, sketches, crystals, @@ -94,8 +103,7 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { kv.list(KV.graphEdges).catch(() => []), kv.list(KV.semantic).catch(() => []), kv.list(KV.procedural).catch(() => []), - kv.list(KV.actions).catch(() => []), - kv.list(KV.actionEdges).catch(() => []), + readActionStoreSnapshot(kv, { includeEvents: true }), kv.list(KV.sentinels).catch(() => []), kv.list(KV.sketches).catch(() => []), kv.list(KV.crystals).catch(() => []), @@ -122,8 +130,19 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { semanticMemories.length > 0 ? semanticMemories : undefined, proceduralMemories: proceduralMemories.length > 0 ? proceduralMemories : undefined, - actions: actions.length > 0 ? actions : undefined, - actionEdges: actionEdges.length > 0 ? actionEdges : undefined, + actions: + actionStore.actions.length > 0 ? actionStore.actions : undefined, + actionEdges: + actionStore.edges.length > 0 ? actionStore.edges : undefined, + actionEvents: + actionStore.events.length > 0 ? actionStore.events : undefined, + actionSnapshot: { + schemaVersion: ACTION_SCHEMA_VERSION, + revision: actionStore.state.revision, + actionCount: actionStore.actions.length, + edgeCount: actionStore.edges.length, + eventCount: actionStore.events.length, + }, sentinels: sentinels.length > 0 ? sentinels : undefined, sketches: sketches.length > 0 ? sketches : undefined, crystals: crystals.length > 0 ? crystals : undefined, @@ -190,6 +209,9 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { const MAX_OBS_PER_SESSION = 5_000; const MAX_TOTAL_OBSERVATIONS = 500_000; const MAX_ACCESS_LOGS = 50_000; + const MAX_ACTIONS = 100_000; + const MAX_ACTION_EDGES = 250_000; + const MAX_ACTION_EVENTS = 500_000; if (!Array.isArray(importData.sessions)) { return { success: false, error: "sessions must be an array" }; @@ -255,11 +277,149 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { }; } + const importedActions = Array.isArray(importData.actions) + ? importData.actions + : []; + if (importedActions.length > MAX_ACTIONS) { + return { + success: false, + error: `Too many actions (max ${MAX_ACTIONS})`, + }; + } + const normalizedImportedActions: Action[] = []; + const actionIds = new Set(); + for (const action of importedActions) { + if (!isImportableAction(action)) { + return { success: false, error: "Invalid action" }; + } + if (actionIds.has(action.id)) { + return { success: false, error: `Duplicate action: ${action.id}` }; + } + actionIds.add(action.id); + const normalized = normalizeActionV2(action); + if (normalized.conflicts.length > 0) { + return { + success: false, + error: `Invalid action ${action.id}: ${normalized.conflicts.join(", ")}`, + }; + } + normalizedImportedActions.push(normalized.action); + } + const importedActionEdges = importData.actionEdges ?? []; + if (!Array.isArray(importedActionEdges)) { + return { success: false, error: "actionEdges must be an array" }; + } + if (importedActionEdges.length > MAX_ACTION_EDGES) { + return { + success: false, + error: `Too many action edges (max ${MAX_ACTION_EDGES})`, + }; + } + const edgeIds = new Set(); + for (const edge of importedActionEdges) { + if (!isImportableActionEdge(edge)) { + return { success: false, error: "Invalid action edge" }; + } + if (edgeIds.has(edge.id)) { + return { success: false, error: `Duplicate action edge: ${edge.id}` }; + } + edgeIds.add(edge.id); + } + const importedActionEvents = importData.actionEvents ?? []; + if (!Array.isArray(importedActionEvents)) { + return { success: false, error: "actionEvents must be an array" }; + } + if (importedActionEvents.length > MAX_ACTION_EVENTS) { + return { + success: false, + error: `Too many action events (max ${MAX_ACTION_EVENTS})`, + }; + } + const eventIds = new Set(); + const validActionEventTypes = new Set([ + "created", + "fields_changed", + "lifecycle_changed", + "result_recorded", + "corrected", + "migrated", + "deleted", + "edge_created", + "edge_deleted", + ]); + for (const event of importedActionEvents) { + if ( + !event || + event.schemaVersion !== ACTION_SCHEMA_VERSION || + typeof event.id !== "string" || + !event.id || + typeof event.actionId !== "string" || + !event.actionId || + (event.entityType !== "action" && event.entityType !== "edge") || + !validActionEventTypes.has(event.type) || + typeof event.actor !== "string" || + !event.actor || + typeof event.timestamp !== "string" || + Number.isNaN(Date.parse(event.timestamp)) || + !Number.isInteger(event.revision) || + event.revision < 1 + ) { + return { success: false, error: "Invalid action event" }; + } + if (eventIds.has(event.id)) { + return { success: false, error: `Duplicate action event: ${event.id}` }; + } + eventIds.add(event.id); + if (!isValidActionEventImage(event)) { + return { success: false, error: `Invalid action event image: ${event.id}` }; + } + } + const importedActionSnapshot = importData.actionSnapshot; + if (importedActionSnapshot) { + if ( + importedActionSnapshot.schemaVersion !== ACTION_SCHEMA_VERSION || + importedActionSnapshot.actionCount !== normalizedImportedActions.length || + importedActionSnapshot.edgeCount !== importedActionEdges.length || + importedActionSnapshot.eventCount !== importedActionEvents.length || + !Number.isInteger(importedActionSnapshot.revision) || + importedActionSnapshot.revision < 0 || + importedActionSnapshot.revision < + Math.max( + 0, + ...normalizedImportedActions.map( + (action) => action.revision ?? 0, + ), + ...importedActionEvents.map((event) => event.revision), + ) + ) { + return { success: false, error: "Action snapshot counts or revision are invalid" }; + } + } + if (strategy === "merge" || strategy === "skip") { + for (const event of importedActionEvents) { + const existing = await kv + .get(KV.actionEvents, event.id) + .catch(() => null); + if ( + existing && + JSON.stringify(existing) !== JSON.stringify(event) + ) { + return { + success: false, + error: `Action event ID conflict: ${event.id}`, + }; + } + } + } + const stats = { sessions: 0, observations: 0, memories: 0, summaries: 0, + actions: 0, + actionEdges: 0, + actionEvents: 0, skipped: 0, }; @@ -282,12 +442,6 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { for (const s of existingSummaries) { await kv.delete(KV.summaries, s.sessionId); } - for (const a of await kv.list(KV.actions).catch(() => [])) { - await kv.delete(KV.actions, a.id); - } - for (const e of await kv.list(KV.actionEdges).catch(() => [])) { - await kv.delete(KV.actionEdges, e.id); - } for (const r of await kv.list(KV.routines).catch(() => [])) { await kv.delete(KV.routines, r.id); } @@ -448,24 +602,110 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { } } - if (importData.actions) { - for (const action of importData.actions) { + await withActionStoreLock(async () => { + const priorActionState = await kv + .get(KV.actionState, "current") + .catch(() => null); + let replacedExistingActionData = false; + if (strategy === "replace") { + const existingActions = await kv.list(KV.actions).catch(() => []); + const existingEdges = await kv + .list(KV.actionEdges) + .catch(() => []); + const existingEvents = await kv + .list(KV.actionEvents) + .catch(() => []); + replacedExistingActionData = Boolean( + priorActionState || + existingActions.length || + existingEdges.length || + existingEvents.length, + ); + for (const action of existingActions) { + await kv.delete(KV.actions, action.id); + } + for (const edge of existingEdges) { + await kv.delete(KV.actionEdges, edge.id); + } + for (const event of existingEvents) { + await kv.delete(KV.actionEvents, event.id); + } + await kv.delete(KV.actionState, "current").catch(() => {}); + } + + for (const action of normalizedImportedActions) { if (strategy === "skip") { - const existing = await kv.get(KV.actions, action.id).catch(() => null); - if (existing) { stats.skipped++; continue; } + const existing = await kv + .get(KV.actions, action.id) + .catch(() => null); + if (existing) { + stats.skipped++; + continue; + } } await kv.set(KV.actions, action.id, action); + stats.actions++; } - } - if (importData.actionEdges) { - for (const edge of importData.actionEdges) { + for (const edge of importedActionEdges) { if (strategy === "skip") { - const existing = await kv.get(KV.actionEdges, edge.id).catch(() => null); - if (existing) { stats.skipped++; continue; } + const existing = await kv + .get(KV.actionEdges, edge.id) + .catch(() => null); + if (existing) { + stats.skipped++; + continue; + } } await kv.set(KV.actionEdges, edge.id, edge); + stats.actionEdges++; } - } + for (const event of importedActionEvents) { + if (strategy === "skip" || strategy === "merge") { + const existing = await kv + .get(KV.actionEvents, event.id) + .catch(() => null); + if (existing) { + stats.skipped++; + continue; + } + } + await kv.set(KV.actionEvents, event.id, event); + stats.actionEvents++; + } + + const actionDataChanged = + stats.actions > 0 || + stats.actionEdges > 0 || + stats.actionEvents > 0 || + replacedExistingActionData || + (strategy === "replace" && + (normalizedImportedActions.length > 0 || + importedActionEdges.length > 0 || + importedActionEvents.length > 0)); + if (actionDataChanged || importedActionSnapshot) { + const currentActionState = await kv + .get(KV.actionState, "current") + .catch(() => null); + const importedRevision = Math.max( + importedActionSnapshot?.revision ?? 0, + ...normalizedImportedActions.map((action) => action.revision ?? 0), + ...importedActionEvents.map((event) => event.revision), + ); + const revision = + strategy === "replace" + ? replacedExistingActionData + ? Math.max(priorActionState?.revision ?? 0, importedRevision) + + 1 + : importedRevision + : Math.max(currentActionState?.revision ?? 0, importedRevision) + 1; + const nextActionState: ActionCollectionState = { + schemaVersion: ACTION_SCHEMA_VERSION, + revision, + updatedAt: new Date().toISOString(), + }; + await kv.set(KV.actionState, "current", nextActionState); + } + }); if (importData.routines) { for (const routine of importData.routines) { if (strategy === "skip") { @@ -585,3 +825,83 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { }, ); } + +function isValidActionEventImage(event: ActionEvent): boolean { + const isDeletion = event.type === "deleted" || event.type === "edge_deleted"; + if (isDeletion ? !event.before || event.after : !event.after) return false; + if ( + event.entityType === "action" && + (event.type === "edge_created" || event.type === "edge_deleted") + ) { + return false; + } + if ( + event.entityType === "edge" && + event.type !== "edge_created" && + event.type !== "edge_deleted" && + event.type !== "fields_changed" + ) { + return false; + } + for (const image of [event.before, event.after]) { + if (!image || typeof image !== "object") continue; + if (event.entityType === "action") { + if ((image as Action).id !== event.actionId) return false; + continue; + } + const edge = image as ActionEdge; + if ( + typeof edge.id !== "string" || + !edge.id || + edge.sourceActionId !== event.actionId || + typeof edge.targetActionId !== "string" || + !edge.targetActionId + ) { + return false; + } + } + return true; +} + +function isImportableAction(value: unknown): value is Action { + if (!value || typeof value !== "object" || Array.isArray(value)) return false; + const action = value as Partial; + return ( + typeof action.id === "string" && + Boolean(action.id) && + typeof action.title === "string" && + typeof action.description === "string" && + ["pending", "active", "done", "blocked", "cancelled"].includes( + String(action.status), + ) && + typeof action.priority === "number" && + Number.isFinite(action.priority) && + typeof action.createdAt === "string" && + !Number.isNaN(Date.parse(action.createdAt)) && + typeof action.updatedAt === "string" && + !Number.isNaN(Date.parse(action.updatedAt)) && + typeof action.createdBy === "string" + ); +} + +function isImportableActionEdge(value: unknown): value is ActionEdge { + if (!value || typeof value !== "object" || Array.isArray(value)) return false; + const edge = value as Partial; + return ( + typeof edge.id === "string" && + Boolean(edge.id) && + [ + "requires", + "unlocks", + "spawned_by", + "gated_by", + "conflicts_with", + ].includes(String(edge.type)) && + typeof edge.sourceActionId === "string" && + Boolean(edge.sourceActionId) && + typeof edge.targetActionId === "string" && + Boolean(edge.targetActionId) && + typeof edge.createdAt === "string" && + !Number.isNaN(Date.parse(edge.createdAt)) + ); +} diff --git a/src/functions/frontier.ts b/src/functions/frontier.ts index 4b3a3842fc..3562210070 100644 --- a/src/functions/frontier.ts +++ b/src/functions/frontier.ts @@ -1,122 +1,83 @@ import type { ISdk } from "iii-sdk"; import type { StateKV } from "../state/kv.js"; import { KV } from "../state/schema.js"; -import type { Action, ActionEdge, Checkpoint, Lease } from "../types.js"; +import type { + ActionBlocker, + ActionReadinessView, + Checkpoint, + Lease, + Sentinel, +} from "../types.js"; +import { classifyAction, computeActionScore } from "./action-model.js"; +import { matchesActionProject } from "./action-query.js"; +import { readActionStoreSnapshot } from "./action-store.js"; export interface FrontierItem { - action: Action; + action: import("../types.js").Action; score: number; - blockers: string[]; + blockers: ActionBlocker[]; leased: boolean; + view: ActionReadinessView; } export function registerFrontierFunction(sdk: ISdk, kv: StateKV): void { - sdk.registerFunction("mem::frontier", + sdk.registerFunction( + "mem::frontier", async (data: { project?: string; agentId?: string; limit?: number; includeLeasedByOthers?: boolean; }) => { - const actions = await kv.list(KV.actions); - const edges = await kv.list(KV.actionEdges); - const leases = await kv.list(KV.leases); - const checkpoints = await kv.list(KV.checkpoints); + const [snapshot, leases, checkpoints, sentinels] = await Promise.all([ + readActionStoreSnapshot(kv), + kv.list(KV.leases).catch(() => []), + kv.list(KV.checkpoints).catch(() => []), + kv.list(KV.sentinels).catch(() => []), + ]); const now = Date.now(); - - const activeLeaseMap = new Map(); - for (const lease of leases) { - if ( - lease.status === "active" && - new Date(lease.expiresAt).getTime() > now - ) { - activeLeaseMap.set(lease.actionId, lease); - } - } - - const checkpointMap = new Map(); - for (const cp of checkpoints) { - checkpointMap.set(cp.id, cp); - } - - const actionMap = new Map(); - for (const a of actions) actionMap.set(a.id, a); - - const frontier: FrontierItem[] = []; - - for (const action of actions) { - if (action.status !== "pending" && action.status !== "active") continue; - if (data.project && action.project !== data.project) continue; - - const blockers: string[] = []; - const inEdges = edges.filter( - (e) => e.sourceActionId === action.id && e.type === "requires", - ); - - for (const edge of inEdges) { - const dep = actionMap.get(edge.targetActionId); - if (dep && dep.status !== "done") { - blockers.push(`requires:${dep.id}:${dep.title}`); - } - } - - const gateEdges = edges.filter( - (e) => e.sourceActionId === action.id && e.type === "gated_by", - ); - for (const edge of gateEdges) { - const cp = checkpointMap.get(edge.targetActionId); - if (cp && cp.status !== "passed") { - blockers.push(`checkpoint:${cp.id}:${cp.name}`); - } - } - - const conflictEdges = edges.filter( - (e) => - (e.sourceActionId === action.id || - e.targetActionId === action.id) && - e.type === "conflicts_with", + const frontier = snapshot.actions + .filter( + (action) => + !data.project || matchesActionProject(action, data.project), + ) + .map((action) => + classifyAction(action, { + actions: snapshot.actions, + edges: snapshot.edges, + checkpoints, + sentinels, + leases, + agentId: data.includeLeasedByOthers ? undefined : data.agentId, + now, + }), + ) + .filter((item) => item.view === "actionable") + .map((item) => ({ + ...item, + score: computeActionScore(item.action, snapshot.edges, now), + })) + .sort( + (left, right) => + right.score - left.score || + left.action.id.localeCompare(right.action.id), ); - for (const edge of conflictEdges) { - const otherId = - edge.sourceActionId === action.id - ? edge.targetActionId - : edge.sourceActionId; - const other = actionMap.get(otherId); - if (other && other.status === "active") { - blockers.push(`conflict:${other.id}:${other.title}`); - } - } - - if (blockers.length > 0) continue; - - const lease = activeLeaseMap.get(action.id); - const leasedByOther = - lease && data.agentId && lease.agentId !== data.agentId; - if (leasedByOther && !data.includeLeasedByOthers) continue; - - const score = computeScore(action, edges, now); - - frontier.push({ - action, - score, - blockers: [], - leased: !!lease, - }); - } - - frontier.sort((a, b) => b.score - a.score); - const limit = data.limit || 20; - + const limit = + Number.isInteger(data.limit) && (data.limit ?? 0) > 0 + ? Math.min(data.limit!, 500) + : 20; return { success: true, frontier: frontier.slice(0, limit), - totalActions: actions.length, + totalActions: snapshot.actions.length, totalUnblocked: frontier.length, + revision: snapshot.state.revision, }; }, ); - sdk.registerFunction("mem::next", + sdk.registerFunction( + "mem::next", async (data: { project?: string; agentId?: string }) => { const result = await sdk.trigger< { project?: string; agentId?: string; limit?: number }, @@ -125,12 +86,12 @@ export function registerFrontierFunction(sdk: ISdk, kv: StateKV): void { frontier: FrontierItem[]; totalActions: number; totalUnblocked: number; + revision: number; } - >({ function_id: "mem::frontier", payload: { - project: data.project, - agentId: data.agentId, - limit: 1, - } }); + >({ + function_id: "mem::frontier", + payload: { project: data.project, agentId: data.agentId, limit: 1 }, + }); if (!result.success) { return { @@ -146,6 +107,8 @@ export function registerFrontierFunction(sdk: ISdk, kv: StateKV): void { suggestion: null, message: "No actionable work found", totalActions: result.totalActions || 0, + totalUnblocked: 0, + revision: result.revision, }; } @@ -159,36 +122,15 @@ export function registerFrontierFunction(sdk: ISdk, kv: StateKV): void { priority: top.action.priority, score: top.score, tags: top.action.tags, + view: top.view, + dueAt: top.action.dueAt, + owner: top.action.owner, }, message: `Suggested: ${top.action.title} (priority ${top.action.priority}, score ${top.score.toFixed(2)})`, totalActions: result.totalActions, totalUnblocked: result.totalUnblocked, + revision: result.revision, }; }, ); } - -function computeScore( - action: Action, - edges: ActionEdge[], - now: number, -): number { - let score = action.priority * 10; - - const ageHours = - (now - new Date(action.createdAt).getTime()) / (1000 * 60 * 60); - score += Math.min(ageHours * 0.5, 20); - - const unlockCount = edges.filter( - (e) => e.sourceActionId === action.id && e.type === "unlocks", - ).length; - score += unlockCount * 5; - - if (edges.some((e) => e.sourceActionId === action.id && e.type === "spawned_by")) { - score += 3; - } - - if (action.status === "active") score += 15; - - return Math.round(score * 100) / 100; -} diff --git a/src/functions/leases.ts b/src/functions/leases.ts index 1a2de33bfc..b946486137 100644 --- a/src/functions/leases.ts +++ b/src/functions/leases.ts @@ -2,8 +2,11 @@ import type { ISdk } from "iii-sdk"; import type { StateKV } from "../state/kv.js"; import { KV, generateId } from "../state/schema.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; -import type { Action, Lease } from "../types.js"; +import type { Action, Checkpoint, Lease, Sentinel } from "../types.js"; import { recordAudit } from "./audit.js"; +import { persistAction, readActionStoreSnapshot } from "./action-store.js"; +import { propagateActionCompletion } from "./actions.js"; +import { classifyAction } from "./action-model.js"; const DEFAULT_LEASE_TTL_MS = 10 * 60 * 1000; const MAX_LEASE_TTL_MS = 60 * 60 * 1000; @@ -28,18 +31,19 @@ export function registerLeasesFunction(sdk: ISdk, kv: StateKV): void { if (action.status === "done" || action.status === "cancelled") { return { success: false, error: "action already completed" }; } - if (action.status === "blocked") { - return { success: false, error: "action is blocked" }; - } - - const existingLeases = await kv.list(KV.leases); + const [snapshot, existingLeases, checkpoints, sentinels] = + await Promise.all([ + readActionStoreSnapshot(kv), + kv.list(KV.leases), + kv.list(KV.checkpoints).catch(() => []), + kv.list(KV.sentinels).catch(() => []), + ]); const activeLease = existingLeases.find( - (l) => - l.actionId === data.actionId && - l.status === "active" && - new Date(l.expiresAt).getTime() > Date.now(), + (lease) => + lease.actionId === data.actionId && + lease.status === "active" && + new Date(lease.expiresAt).getTime() > Date.now(), ); - if (activeLease) { if (activeLease.agentId === data.agentId) { return { @@ -56,6 +60,21 @@ export function registerLeasesFunction(sdk: ISdk, kv: StateKV): void { expiresAt: activeLease.expiresAt, }; } + const readiness = classifyAction(action, { + actions: snapshot.actions, + edges: snapshot.edges, + checkpoints, + sentinels, + leases: existingLeases, + agentId: data.agentId, + }); + if (readiness.view !== "actionable") { + return { + success: false, + error: `action is ${readiness.view}`, + blockers: readiness.blockers, + }; + } const now = new Date(); const lease: Lease = { @@ -76,12 +95,17 @@ export function registerLeasesFunction(sdk: ISdk, kv: StateKV): void { const before = { ...action }; action.status = "active"; + action.lifecycle = "active"; action.assignedTo = data.agentId; action.updatedAt = now.toISOString(); - await kv.set(KV.actions, action.id, action); + const persisted = await persistAction(kv, action, { + actor: data.agentId, + before, + reason: "lease acquired", + }); await recordAudit(kv, "action_update", "mem::lease-acquire", [action.id], { before, - after: action, + after: persisted.action, }); return { success: true, lease, renewed: false }; @@ -122,18 +146,27 @@ export function registerLeasesFunction(sdk: ISdk, kv: StateKV): void { const before = { ...action }; if (data.result) { action.status = "done"; + action.lifecycle = "done"; action.result = data.result; } else { action.status = "pending"; + action.lifecycle = "pending"; } action.assignedTo = undefined; action.updatedAt = new Date().toISOString(); - await kv.set(KV.actions, action.id, action); + const persisted = await persistAction(kv, action, { + actor: data.agentId, + before, + reason: data.result ? "lease released with result" : "lease released", + }); await recordAudit(kv, "action_update", "mem::lease-release", [action.id], { before, - after: action, + after: persisted.action, agentId: data.agentId, }); + if (data.result) { + await propagateActionCompletion(kv, action.id, data.agentId); + } } return { success: true, released: true }; @@ -228,10 +261,16 @@ export function registerLeasesFunction(sdk: ISdk, kv: StateKV): void { action.status === "active" && action.assignedTo === currentLease.agentId ) { + const before = structuredClone(action); action.status = "pending"; + action.lifecycle = "pending"; action.assignedTo = undefined; action.updatedAt = new Date().toISOString(); - await kv.set(KV.actions, action.id, action); + await persistAction(kv, action, { + actor: "lease-cleanup", + before, + reason: "expired lease cleanup", + }); await recordAudit(kv, "action_update", "mem::lease-cleanup", [action.id], { action: "status-change", newStatus: action.status, diff --git a/src/functions/mesh.ts b/src/functions/mesh.ts index ad52e5ea73..446d2faf0c 100644 --- a/src/functions/mesh.ts +++ b/src/functions/mesh.ts @@ -15,6 +15,7 @@ import type { } from "../types.js"; import { lookup } from "node:dns/promises"; import { isIP } from "node:net"; +import { persistAction } from "./action-store.js"; function isPrivateIP(ip: string): boolean { if (ip === "127.0.0.1" || ip === "::1" || ip === "0.0.0.0") return true; @@ -105,6 +106,42 @@ async function lwwMergeList( return count; } +async function lwwMergeActions( + kv: StateKV, + items: Action[] | undefined, +): Promise { + if (!items || !Array.isArray(items)) return 0; + let count = 0; + for (const item of items) { + if ( + !item?.id || + typeof item.id !== "string" || + typeof item.updatedAt !== "string" || + Number.isNaN(Date.parse(item.updatedAt)) + ) { + continue; + } + const wrote = await withKeyedLock(`mem:action:${item.id}`, async () => { + const existing = await kv.get(KV.actions, item.id); + if ( + existing && + Date.parse(existing.updatedAt) >= Date.parse(item.updatedAt) + ) { + return false; + } + await persistAction(kv, item, { + actor: "mesh-sync", + before: existing, + type: existing ? "fields_changed" : "created", + reason: "Last-write-wins mesh synchronization", + }); + return true; + }); + if (wrote) count++; + } + return count; +} + function graphNodeTs(node: GraphNode): string { return node.updatedAt || node.createdAt; } @@ -340,7 +377,7 @@ export function registerMeshFunction( let accepted = 0; accepted += await lwwMergeList(kv, KV.memories, data.memories, "mem:memory", "updatedAt"); - accepted += await lwwMergeList(kv, KV.actions, data.actions, "mem:action", "updatedAt"); + accepted += await lwwMergeActions(kv, data.actions); accepted += await lwwMergeList(kv, KV.semantic, data.semantic, "mem:semantic", "updatedAt"); accepted += await lwwMergeList(kv, KV.procedural, data.procedural, "mem:procedural", "updatedAt"); if (data.relations && Array.isArray(data.relations)) { @@ -461,7 +498,7 @@ async function applySyncData( applied += await lwwMergeList(kv, KV.memories, data.memories, "mem:memory", "updatedAt"); } if (scopes.includes("actions")) { - applied += await lwwMergeList(kv, KV.actions, data.actions, "mem:action", "updatedAt"); + applied += await lwwMergeActions(kv, data.actions); } if (scopes.includes("semantic")) { applied += await lwwMergeList(kv, KV.semantic, data.semantic, "mem:semantic", "updatedAt"); diff --git a/src/functions/migrate.ts b/src/functions/migrate.ts index c2039ea1c3..5963f279ed 100644 --- a/src/functions/migrate.ts +++ b/src/functions/migrate.ts @@ -10,6 +10,10 @@ import type { SessionSummary, } from "../types.js"; import { logger } from "../logger.js"; +import { + migrateActionsV2, + type ActionsV2MigrationInput, +} from "./actions-v2-migration.js"; const ALLOWED_DIRS = [resolve(homedir(), ".agentmemory")]; @@ -87,8 +91,42 @@ export async function inferMemoryProjects( export function registerMigrateFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::migrate", - async (data: { dbPath?: string; step?: string; dryRun?: boolean }) => { + async (data: { + dbPath?: string; + step?: string; + dryRun?: boolean; + projectAliases?: Record; + defaultProjectId?: string; + limit?: number; + cursor?: string; + actor?: string; + }) => { // In-place KV migration steps (no SQLite dependency). + if (data.step === "actions-v2") { + const migrationInput: ActionsV2MigrationInput = { + dryRun: data.dryRun ?? true, + projectAliases: data.projectAliases, + defaultProjectId: data.defaultProjectId, + limit: data.limit, + cursor: data.cursor, + actor: data.actor, + }; + logger.info("Migration step: actions-v2", { + dryRun: migrationInput.dryRun, + limit: migrationInput.limit, + hasCursor: Boolean(migrationInput.cursor), + aliasCount: Object.keys(migrationInput.projectAliases ?? {}).length, + }); + try { + return await migrateActionsV2(kv, migrationInput); + } catch (error) { + return { + success: false, + step: "actions-v2", + error: error instanceof Error ? error.message : String(error), + }; + } + } if (data.step === "infer-memory-projects") { const dryRun = data.dryRun ?? false; logger.info("Migration step: infer-memory-projects", { dryRun }); diff --git a/src/functions/routines.ts b/src/functions/routines.ts index d1a9135a9e..75f7d5543c 100644 --- a/src/functions/routines.ts +++ b/src/functions/routines.ts @@ -4,6 +4,7 @@ import { KV, generateId } from "../state/schema.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import type { Action, Routine, RoutineStep, RoutineRun } from "../types.js"; import { recordAudit } from "./audit.js"; +import { persistAction, persistActionEdge } from "./action-store.js"; export function registerRoutinesFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::routine-create", @@ -138,7 +139,13 @@ export function registerRoutinesFunction(sdk: ISdk, kv: StateKV): void { metadata: { routineId: routine.id, stepOrder: step.order }, }; - await kv.set(KV.actions, action.id, action); + await persistAction(kv, action, { + actor: data.initiatedBy || "routine", + type: "created", + before: null, + hasDerivedBlockers: hasDeps, + reason: `Routine ${routine.id} instantiated`, + }); stepOrderToActionId.set(step.order, action.id); actionIds.push(action.id); stepStatus[step.order] = "pending"; @@ -158,7 +165,11 @@ export function registerRoutinesFunction(sdk: ISdk, kv: StateKV): void { targetActionId: depActionId, createdAt: now, }; - await kv.set(KV.actionEdges, edge.id, edge); + await persistActionEdge(kv, edge, { + actor: data.initiatedBy || "routine", + before: null, + reason: `Routine ${routine.id} dependency`, + }); } } diff --git a/src/functions/sentinels.ts b/src/functions/sentinels.ts index ed29aee940..f70175033b 100644 --- a/src/functions/sentinels.ts +++ b/src/functions/sentinels.ts @@ -2,8 +2,10 @@ import type { ISdk } from "iii-sdk"; import type { StateKV } from "../state/kv.js"; import { KV, generateId } from "../state/schema.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; -import type { Action, ActionEdge, Checkpoint, CompressedObservation, FunctionMetrics, Sentinel, Session } from "../types.js"; +import type { Action, ActionEdge, CompressedObservation, FunctionMetrics, Sentinel, Session } from "../types.js"; import { recordAudit } from "./audit.js"; +import { persistActionEdge } from "./action-store.js"; +import { refreshLinkedActionReadiness } from "./action-readiness-refresh.js"; const VALID_TYPES: Sentinel["type"][] = [ "webhook", @@ -123,13 +125,23 @@ export function registerSentinelsFunction(sdk: ISdk, kv: StateKV): void { targetActionId: sentinel.id, createdAt: now.toISOString(), }; - await kv.set(KV.actionEdges, edge.id, edge); + await persistActionEdge(kv, edge, { + actor: "sentinel-create", + before: null, + reason: `Sentinel ${sentinel.id} gate added`, + }); await recordAudit(kv, "sentinel_create", "mem::sentinel-create", [edge.id], { action: "sentinel.create.edge", sentinelId: sentinel.id, sourceActionId: actionId, }); } + await refreshLinkedActionReadiness( + kv, + data.linkedActionIds, + "sentinel-create", + `Sentinel ${sentinel.id} gate added`, + ); } if (data.type === "timer") { @@ -148,7 +160,12 @@ export function registerSentinelsFunction(sdk: ISdk, kv: StateKV): void { reason: "timer_elapsed", durationMs, }); - await unblockLinkedActions(kv, fresh); + await refreshLinkedActionReadiness( + kv, + fresh.linkedActionIds, + "sentinel-timer", + `Sentinel ${fresh.id} triggered`, + ); }); } catch (err) { console.error("sentinel timer callback failed", sentinel.id, err); @@ -193,10 +210,12 @@ export function registerSentinelsFunction(sdk: ISdk, kv: StateKV): void { result: data.result, }); - let unblockedCount = 0; - if (sentinel.linkedActionIds.length > 0) { - unblockedCount = await unblockLinkedActions(kv, sentinel); - } + const unblockedCount = await refreshLinkedActionReadiness( + kv, + sentinel.linkedActionIds, + "sentinel-trigger", + `Sentinel ${sentinel.id} triggered`, + ); return { success: true, sentinel, unblockedCount }; }, @@ -252,7 +271,12 @@ export function registerSentinelsFunction(sdk: ISdk, kv: StateKV): void { action: "sentinel.threshold_trigger", result: fresh.result, }); - await unblockLinkedActions(kv, fresh); + await refreshLinkedActionReadiness( + kv, + fresh.linkedActionIds, + "sentinel-check", + `Sentinel ${fresh.id} threshold triggered`, + ); }, ); triggered.push(sentinel.id); @@ -304,7 +328,12 @@ export function registerSentinelsFunction(sdk: ISdk, kv: StateKV): void { action: "sentinel.pattern_trigger", result: fresh.result, }); - await unblockLinkedActions(kv, fresh); + await refreshLinkedActionReadiness( + kv, + fresh.linkedActionIds, + "sentinel-check", + `Sentinel ${fresh.id} pattern triggered`, + ); }, ); triggered.push(sentinel.id); @@ -345,6 +374,12 @@ export function registerSentinelsFunction(sdk: ISdk, kv: StateKV): void { action: "sentinel.cancel", status: "cancelled", }); + await refreshLinkedActionReadiness( + kv, + sentinel.linkedActionIds, + "sentinel-cancel", + `Sentinel ${sentinel.id} cancelled`, + ); return { success: true, sentinel }; }, @@ -399,6 +434,12 @@ export function registerSentinelsFunction(sdk: ISdk, kv: StateKV): void { action: "sentinel.expire", status: "expired", }); + await refreshLinkedActionReadiness( + kv, + fresh.linkedActionIds, + "sentinel-expire", + `Sentinel ${fresh.id} expired`, + ); return true; }, ); @@ -410,46 +451,3 @@ export function registerSentinelsFunction(sdk: ISdk, kv: StateKV): void { }, ); } - -async function unblockLinkedActions( - kv: StateKV, - sentinel: Sentinel, -): Promise { - if (sentinel.linkedActionIds.length === 0) return 0; - - const allEdges = await kv.list(KV.actionEdges); - const allSentinels = await kv.list(KV.sentinels); - const allCheckpoints = await kv.list(KV.checkpoints); - const gateMap = new Map(); - for (const s of allSentinels) gateMap.set(s.id, { status: s.status === "triggered" ? "passed" : s.status }); - for (const c of allCheckpoints) gateMap.set(c.id, { status: c.status }); - - let unblockedCount = 0; - - for (const actionId of sentinel.linkedActionIds) { - await withKeyedLock(`mem:action:${actionId}`, async () => { - const action = await kv.get(KV.actions, actionId); - if (action && action.status === "blocked") { - const gates = allEdges.filter( - (e) => e.sourceActionId === actionId && e.type === "gated_by", - ); - const allPassed = gates.every((g) => { - const gate = gateMap.get(g.targetActionId); - return gate && gate.status === "passed"; - }); - if (allPassed) { - action.status = "pending"; - action.updatedAt = new Date().toISOString(); - await kv.set(KV.actions, action.id, action); - await recordAudit(kv, "action_update", "mem::sentinel-unblock", [action.id], { - action: "action.unblocked", - sentinelId: sentinel.id, - }); - unblockedCount++; - } - } - }); - } - - return unblockedCount; -} diff --git a/src/functions/sketches.ts b/src/functions/sketches.ts index c617a29817..e1575a3ab6 100644 --- a/src/functions/sketches.ts +++ b/src/functions/sketches.ts @@ -4,6 +4,12 @@ import { KV, generateId } from "../state/schema.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import type { Action, ActionEdge, Sketch } from "../types.js"; import { safeAudit } from "./audit.js"; +import { + deleteAction, + deleteActionEdge, + persistAction, + persistActionEdge, +} from "./action-store.js"; export function registerSketchesFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::sketch-create", @@ -68,7 +74,10 @@ export function registerSketchesFunction(sdk: ISdk, kv: StateKV): void { id: generateId("act"), title: data.title.trim(), description: (data.description || "").trim(), - status: "pending", + status: + data.dependsOn && data.dependsOn.length > 0 + ? "blocked" + : "pending", priority: Math.max(1, Math.min(10, data.priority || 5)), createdAt: now, updatedAt: now, @@ -92,7 +101,13 @@ export function registerSketchesFunction(sdk: ISdk, kv: StateKV): void { } } - await kv.set(KV.actions, action.id, action); + const persistedAction = await persistAction(kv, action, { + actor: "sketch", + type: "created", + before: null, + hasDerivedBlockers: Boolean(data.dependsOn?.length), + reason: `Added to sketch ${sketch.id}`, + }); await safeAudit(kv, "sketch_create", "mem::sketch-add", [action.id], { action: "add.action", sketchId: sketch.id, @@ -108,7 +123,11 @@ export function registerSketchesFunction(sdk: ISdk, kv: StateKV): void { targetActionId: depId, createdAt: now, }; - await kv.set(KV.actionEdges, edge.id, edge); + await persistActionEdge(kv, edge, { + actor: "sketch", + before: null, + reason: `Sketch ${sketch.id} dependency`, + }); await safeAudit(kv, "sketch_create", "mem::sketch-add", [edge.id], { action: "add.edge", sketchId: sketch.id, @@ -124,7 +143,7 @@ export function registerSketchesFunction(sdk: ISdk, kv: StateKV): void { addedActionId: action.id, }); - return { success: true, action, edges: createdEdges }; + return { success: true, action: persistedAction.action, edges: createdEdges }; }); }, ); @@ -148,12 +167,25 @@ export function registerSketchesFunction(sdk: ISdk, kv: StateKV): void { for (const actionId of sketch.actionIds) { const action = await kv.get(KV.actions, actionId); if (action) { + const before = structuredClone(action); delete action.sketchId; if (data.project) { + const previousProject = action.projectId || action.project; action.project = data.project; + action.projectId = undefined; + action.projectAliases = [ + ...new Set([ + ...(action.projectAliases ?? []), + ...(previousProject ? [previousProject] : []), + ]), + ]; } action.updatedAt = new Date().toISOString(); - await kv.set(KV.actions, action.id, action); + await persistAction(kv, action, { + actor: "sketch-promote", + before, + reason: `Promoted from sketch ${sketch.id}`, + }); await safeAudit(kv, "sketch_promote", "mem::sketch-promote", [action.id], { action: "promote.action", sketchId: sketch.id, @@ -198,7 +230,10 @@ export function registerSketchesFunction(sdk: ISdk, kv: StateKV): void { actionIdSet.has(edge.sourceActionId) || actionIdSet.has(edge.targetActionId) ) { - await kv.delete(KV.actionEdges, edge.id); + await deleteActionEdge(kv, edge.id, { + actor: "sketch-discard", + reason: `Discarded sketch ${sketch.id}`, + }); await safeAudit(kv, "sketch_discard", "mem::sketch-discard", [edge.id], { action: "discard.edge", sketchId: sketch.id, @@ -207,7 +242,10 @@ export function registerSketchesFunction(sdk: ISdk, kv: StateKV): void { } for (const actionId of sketch.actionIds) { - await kv.delete(KV.actions, actionId); + await deleteAction(kv, actionId, { + actor: "sketch-discard", + reason: `Discarded sketch ${sketch.id}`, + }); await safeAudit(kv, "sketch_discard", "mem::sketch-discard", [actionId], { action: "discard.action", sketchId: sketch.id, @@ -283,7 +321,10 @@ export function registerSketchesFunction(sdk: ISdk, kv: StateKV): void { actionIdSet.has(edge.sourceActionId) || actionIdSet.has(edge.targetActionId) ) { - await kv.delete(KV.actionEdges, edge.id); + await deleteActionEdge(kv, edge.id, { + actor: "sketch-gc", + reason: `Expired sketch ${current.id}`, + }); await safeAudit(kv, "sketch_discard", "mem::sketch-gc", [edge.id], { action: "gc.edge", sketchId: current.id, @@ -292,7 +333,10 @@ export function registerSketchesFunction(sdk: ISdk, kv: StateKV): void { } for (const actionId of current.actionIds) { - await kv.delete(KV.actions, actionId); + await deleteAction(kv, actionId, { + actor: "sketch-gc", + reason: `Expired sketch ${current.id}`, + }); await safeAudit(kv, "sketch_discard", "mem::sketch-gc", [actionId], { action: "gc.action", sketchId: current.id, diff --git a/src/mcp/server.ts b/src/mcp/server.ts index 838e572e67..11b76b63eb 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -685,14 +685,39 @@ export function registerMcpEndpoints( const tags = typeof args.tags === "string" && args.tags.trim() ? args.tags.split(",").map((t: string) => t.trim()).filter(Boolean) : []; + const projectAliases = + typeof args.projectAliases === "string" && + args.projectAliases.trim() + ? args.projectAliases + .split(",") + .map((alias: string) => alias.trim()) + .filter(Boolean) + : undefined; const actionResult = await sdk.trigger({ function_id: "mem::action-create", payload: { title: args.title, description: args.description, priority: args.priority, project: args.project, + projectId: args.projectId, + projectAliases, tags, parentId: args.parentId, edges: edges.length > 0 ? edges : undefined, + lifecycle: args.lifecycle, + owner: args.owner, + notBefore: args.notBefore, + dueAt: args.dueAt, + awaitingHuman: args.awaitingHuman, + approval: + typeof args.approvalState === "string" + ? { state: args.approvalState } + : undefined, + blockedReason: args.blockedReason, + repoRoot: args.repoRoot, + worktree: args.worktree, + branch: args.branch, + taskSlug: args.taskSlug, + actor: args.actor, } }); return { status_code: 200, @@ -711,11 +736,49 @@ export function registerMcpEndpoints( body: { error: "actionId is required" }, }; } + const tags = + typeof args.tags === "string" + ? args.tags + .split(",") + .map((tag: string) => tag.trim()) + .filter(Boolean) + : undefined; + const projectAliases = + typeof args.projectAliases === "string" + ? args.projectAliases + .split(",") + .map((alias: string) => alias.trim()) + .filter(Boolean) + : undefined; const updateResult = await sdk.trigger({ function_id: "mem::action-update", payload: { actionId: args.actionId, status: args.status, + lifecycle: args.lifecycle, + title: args.title, + description: args.description, result: args.result, priority: args.priority, + assignedTo: args.assignedTo, + owner: args.owner, + tags, + project: args.project, + projectId: args.projectId, + projectAliases, + notBefore: args.notBefore, + dueAt: args.dueAt, + awaitingHuman: args.awaitingHuman, + approval: + typeof args.approvalState === "string" + ? { state: args.approvalState } + : undefined, + blockedReason: args.blockedReason, + repoRoot: args.repoRoot, + worktree: args.worktree, + branch: args.branch, + taskSlug: args.taskSlug, + actor: args.actor, + correctionOf: args.correctionOf, + correctionReason: args.correctionReason, } }); return { status_code: 200, @@ -727,6 +790,35 @@ export function registerMcpEndpoints( }; } + case "memory_action_list": { + const tags = + typeof args.tags === "string" && args.tags.trim() + ? args.tags + .split(",") + .map((tag: string) => tag.trim()) + .filter(Boolean) + : undefined; + const listResult = await sdk.trigger({ function_id: "mem::action-list", payload: { + project: args.project, + status: args.status, + view: args.view, + owner: args.owner, + tags, + agentId: args.agentId, + limit: args.limit, + cursor: args.cursor, + revision: args.revision, + } }); + return { + status_code: 200, + body: { + content: [ + { type: "text", text: JSON.stringify(listResult, null, 2) }, + ], + }, + }; + } + case "memory_frontier": { const frontierResult = await sdk.trigger({ function_id: "mem::frontier", payload: { project: args.project, diff --git a/src/mcp/standalone.ts b/src/mcp/standalone.ts index 5ed47367f1..f3aa81712d 100644 --- a/src/mcp/standalone.ts +++ b/src/mcp/standalone.ts @@ -373,7 +373,7 @@ async function handleProxyGeneric( handle: ProxyHandle, ): Promise<{ content: Array<{ type: string; text: string }> }> { // Forward to the server's full MCP surface so non-Claude clients can - // reach all 53 tools (lessons, sentinels, slots, signals, graph, …) + // reach all 54 tools (lessons, sentinels, slots, signals, graph, …) // instead of being capped at the 7 IMPLEMENTED_TOOLS set baked into // this shim. The server validates arguments per tool. const result = (await handle.call("/agentmemory/mcp/call", { diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts index 4891177e99..6f36c1aebb 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -386,7 +386,18 @@ export const V050_TOOLS: McpToolDef[] = [ type: "number", description: "Priority 1-10 (10 highest)", }, - project: { type: "string", description: "Project path" }, + project: { + type: "string", + description: "Legacy project identifier or alias", + }, + projectId: { + type: "string", + description: "Canonical non-path project identifier", + }, + projectAliases: { + type: "string", + description: "Comma-separated legacy project aliases", + }, tags: { type: "string", description: "Comma-separated tags", @@ -400,6 +411,33 @@ export const V050_TOOLS: McpToolDef[] = [ description: "Comma-separated action IDs that must complete before this", }, + lifecycle: { + type: "string", + description: "Canonical lifecycle: pending, active, done, or cancelled", + }, + owner: { type: "string", description: "Durable action owner" }, + notBefore: { + type: "string", + description: "ISO timestamp before which the action is scheduled", + }, + dueAt: { type: "string", description: "ISO due timestamp" }, + awaitingHuman: { + type: "boolean", + description: "Whether progress waits for human input", + }, + approvalState: { + type: "string", + description: "not_required, pending, approved, or rejected", + }, + blockedReason: { + type: "string", + description: "Explicit manual blocking reason", + }, + repoRoot: { type: "string", description: "Repository root context" }, + worktree: { type: "string", description: "Worktree path or label" }, + branch: { type: "string", description: "Git branch context" }, + taskSlug: { type: "string", description: "Stable task slug" }, + actor: { type: "string", description: "Agent or human making the change" }, }, required: ["title"], }, @@ -416,15 +454,91 @@ export const V050_TOOLS: McpToolDef[] = [ type: "string", description: "New status: pending, active, done, blocked, cancelled", }, + lifecycle: { + type: "string", + description: "Canonical lifecycle: pending, active, done, or cancelled", + }, + title: { type: "string", description: "Replacement action title" }, + description: { + type: "string", + description: "Replacement action description", + }, result: { type: "string", description: "Outcome description (when completing)", }, priority: { type: "number", description: "New priority 1-10" }, + assignedTo: { + type: "string", + description: "Current worker assignment", + }, + owner: { type: "string", description: "Durable action owner" }, + tags: { type: "string", description: "Comma-separated replacement tags" }, + project: { + type: "string", + description: "Legacy project identifier or alias", + }, + projectId: { + type: "string", + description: "Canonical non-path project identifier", + }, + projectAliases: { + type: "string", + description: "Comma-separated legacy project aliases", + }, + notBefore: { type: "string", description: "ISO scheduling timestamp" }, + dueAt: { type: "string", description: "ISO due timestamp" }, + awaitingHuman: { + type: "boolean", + description: "Whether progress waits for human input", + }, + approvalState: { + type: "string", + description: "not_required, pending, approved, or rejected", + }, + blockedReason: { + type: "string", + description: "Explicit manual blocking reason", + }, + repoRoot: { type: "string", description: "Repository root context" }, + worktree: { type: "string", description: "Worktree path or label" }, + branch: { type: "string", description: "Git branch context" }, + taskSlug: { type: "string", description: "Stable task slug" }, + actor: { type: "string", description: "Agent or human making the change" }, + correctionOf: { + type: "string", + description: "Event ID corrected by this append-only change", + }, + correctionReason: { + type: "string", + description: "Reason for the correction", + }, }, required: ["actionId"], }, }, + { + name: "memory_action_list", + description: + "List actions through revision-bound actionable, scheduled, waiting, blocked, completed, or cancelled views.", + inputSchema: { + type: "object", + properties: { + project: { type: "string", description: "Canonical project ID or alias" }, + status: { type: "string", description: "Legacy status filter" }, + view: { + type: "string", + description: "actionable, scheduled, waiting, blocked, completed, or cancelled", + }, + owner: { type: "string", description: "Durable owner filter" }, + tags: { type: "string", description: "Comma-separated tag filter" }, + agentId: { type: "string", description: "Agent ID for lease readiness" }, + limit: { type: "number", description: "Page size (default 50, maximum 500)" }, + cursor: { type: "string", description: "Opaque nextCursor from the prior page" }, + revision: { type: "number", description: "Expected collection revision" }, + }, + }, + }, { name: "memory_frontier", description: @@ -952,6 +1066,7 @@ export const WORKSTATION_TOOLS = new Set([ "memory_file_history", "memory_action_create", "memory_action_update", + "memory_action_list", "memory_frontier", "memory_next", "memory_lease", diff --git a/src/state/schema.ts b/src/state/schema.ts index cb29d41ad8..cb2bf262f1 100644 --- a/src/state/schema.ts +++ b/src/state/schema.ts @@ -46,6 +46,8 @@ export const KV = { audit: "mem:audit", actions: "mem:actions", actionEdges: "mem:action-edges", + actionEvents: "mem:action-events", + actionState: "mem:action-state", leases: "mem:leases", routines: "mem:routines", routineRuns: "mem:routine-runs", diff --git a/src/triggers/api.ts b/src/triggers/api.ts index d562e5eb11..08866a7538 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -122,6 +122,17 @@ function asNonEmptyString(value: unknown): string | null { return trimmed ? trimmed : null; } +function pickDefinedFields( + body: Record, + fields: readonly string[], +): Record { + const result: Record = {}; + for (const field of fields) { + if (body[field] !== undefined) result[field] = body[field]; + } + return result; +} + function sessionContextFields(body: Record): Partial { const result: Partial = {}; for (const field of [ @@ -1249,7 +1260,16 @@ export function registerApiTriggers( sdk.registerFunction("api::migrate", async ( - req: ApiRequest<{ dbPath?: string; step?: string; dryRun?: boolean }>, + req: ApiRequest<{ + dbPath?: string; + step?: string; + dryRun?: boolean; + projectAliases?: Record; + defaultProjectId?: string; + limit?: number; + cursor?: string; + actor?: string; + }>, ): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; @@ -1263,13 +1283,52 @@ export function registerApiTriggers( body: { error: "Either step (string) or dbPath (string) is required" }, }; } + const body = (req.body ?? {}) as Record; + if ( + body.dryRun !== undefined && + typeof body.dryRun !== "boolean" + ) { + return { + status_code: 400, + body: { error: "dryRun must be boolean" }, + }; + } + if ( + body.projectAliases !== undefined && + (typeof body.projectAliases !== "object" || + body.projectAliases === null || + Array.isArray(body.projectAliases) || + Object.values(body.projectAliases).some( + (value) => typeof value !== "string", + )) + ) { + return { + status_code: 400, + body: { error: "projectAliases must map strings to strings" }, + }; + } + const limit = parseOptionalPositiveInt(body.limit); + if (limit === null) { + return { + status_code: 400, + body: { error: "limit must be a positive integer" }, + }; + } const result = await sdk.trigger({ function_id: "mem::migrate", - payload: { - ...(req.body.step !== undefined && { step: req.body.step }), - ...(req.body.dbPath !== undefined && { dbPath: req.body.dbPath }), - ...(req.body.dryRun !== undefined && { dryRun: req.body.dryRun }), - }, + payload: pickDefinedFields( + { ...body, ...(limit !== undefined ? { limit } : {}) }, + [ + "step", + "dbPath", + "dryRun", + "projectAliases", + "defaultProjectId", + "limit", + "cursor", + "actor", + ], + ), }); return { status_code: 200, body: result }; }, @@ -2386,25 +2445,44 @@ export function registerApiTriggers( }); sdk.registerFunction("api::action-create", - async ( - req: ApiRequest<{ - title: string; - description?: string; - priority?: number; - createdBy?: string; - project?: string; - tags?: string[]; - parentId?: string; - edges?: Array<{ type: string; targetActionId: string }>; - }>, - ): Promise => { + async (req: ApiRequest>): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; - if (!req.body?.title) { + const body = (req.body ?? {}) as Record; + if (!asNonEmptyString(body.title)) { return { status_code: 400, body: { error: "title is required" } }; } - const result = await sdk.trigger({ function_id: "mem::action-create", payload: req.body }); - return { status_code: 201, body: result }; + const result = await sdk.trigger({ + function_id: "mem::action-create", + payload: pickDefinedFields(body, [ + "title", + "description", + "priority", + "createdBy", + "actor", + "project", + "projectId", + "projectAliases", + "tags", + "parentId", + "sourceObservationIds", + "sourceMemoryIds", + "edges", + "lifecycle", + "owner", + "notBefore", + "dueAt", + "awaitingHuman", + "approval", + "blockedReason", + "repoRoot", + "worktree", + "branch", + "taskSlug", + ]), + }); + const success = (result as { success?: boolean }).success !== false; + return { status_code: success ? 201 : 400, body: result }; }, ); sdk.registerTrigger({ @@ -2414,23 +2492,45 @@ export function registerApiTriggers( }); sdk.registerFunction("api::action-update", - async ( - req: ApiRequest<{ - actionId: string; - status?: string; - title?: string; - description?: string; - priority?: number; - result?: string; - }>, - ): Promise => { + async (req: ApiRequest>): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; - if (!req.body?.actionId) { + const body = (req.body ?? {}) as Record; + if (!asNonEmptyString(body.actionId)) { return { status_code: 400, body: { error: "actionId is required" } }; } - const result = await sdk.trigger({ function_id: "mem::action-update", payload: req.body }); - return { status_code: 200, body: result }; + const result = await sdk.trigger({ + function_id: "mem::action-update", + payload: pickDefinedFields(body, [ + "actionId", + "status", + "lifecycle", + "title", + "description", + "priority", + "assignedTo", + "owner", + "result", + "tags", + "project", + "projectId", + "projectAliases", + "notBefore", + "dueAt", + "awaitingHuman", + "approval", + "blockedReason", + "repoRoot", + "worktree", + "branch", + "taskSlug", + "actor", + "correctionOf", + "correctionReason", + ]), + }); + const success = (result as { success?: boolean }).success !== false; + return { status_code: success ? 200 : 400, body: result }; }, ); sdk.registerTrigger({ @@ -2457,14 +2557,40 @@ export function registerApiTriggers( body: { error: "offset must be a non-negative integer" }, }; } + const revision = parseOptionalNonNegativeInt( + req.query_params?.["revision"], + ); + if (revision === null) { + return { + status_code: 400, + body: { error: "revision must be a non-negative integer" }, + }; + } + const tags = asNonEmptyString(req.query_params?.["tags"]) + ?.split(",") + .map((tag) => tag.trim()) + .filter(Boolean); const result = await sdk.trigger({ function_id: "mem::action-list", payload: { status: req.query_params?.["status"], project: req.query_params?.["project"], parentId: req.query_params?.["parentId"], + owner: req.query_params?.["owner"], + view: req.query_params?.["view"], + agentId: req.query_params?.["agentId"], + cursor: req.query_params?.["cursor"], + tags, + revision, limit, offset, } }); - return { status_code: 200, body: result }; + const error = (result as { error?: string }).error; + const statusCode = + error === "revision_conflict" + ? 409 + : error + ? 400 + : 200; + return { status_code: statusCode, body: result }; }, ); sdk.registerTrigger({ @@ -2492,20 +2618,25 @@ export function registerApiTriggers( }); sdk.registerFunction("api::action-edge", - async ( - req: ApiRequest<{ - sourceActionId: string; - targetActionId: string; - type: string; - }>, - ): Promise => { + async (req: ApiRequest>): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; - if (!req.body?.sourceActionId || !req.body?.targetActionId || !req.body?.type) { + const body = (req.body ?? {}) as Record; + if (!body.sourceActionId || !body.targetActionId || !body.type) { return { status_code: 400, body: { error: "sourceActionId, targetActionId, and type are required" } }; } - const result = await sdk.trigger({ function_id: "mem::action-edge-create", payload: req.body }); - return { status_code: 201, body: result }; + const result = await sdk.trigger({ + function_id: "mem::action-edge-create", + payload: pickDefinedFields(body, [ + "sourceActionId", + "targetActionId", + "type", + "metadata", + "actor", + ]), + }); + const success = (result as { success?: boolean }).success !== false; + return { status_code: success ? 201 : 400, body: result }; }, ); sdk.registerTrigger({ diff --git a/src/types.ts b/src/types.ts index 9bbf01323b..ee7e008b71 100644 --- a/src/types.ts +++ b/src/types.ts @@ -339,6 +339,8 @@ export interface ExportData { proceduralMemories?: ProceduralMemory[]; actions?: Action[]; actionEdges?: ActionEdge[]; + actionEvents?: ActionEvent[]; + actionSnapshot?: ActionSnapshot; routines?: Routine[]; signals?: Signal[]; checkpoints?: Checkpoint[]; @@ -683,6 +685,111 @@ export interface Action { metadata?: Record; sketchId?: string; crystallizedInto?: string; + schemaVersion?: 2; + revision?: number; + lifecycle?: ActionLifecycle; + projectId?: string; + projectAliases?: string[]; + owner?: string; + notBefore?: string; + dueAt?: string; + awaitingHuman?: boolean; + approval?: ActionApproval; + blockedReason?: string; + repoRoot?: string; + worktree?: string; + branch?: string; + taskSlug?: string; +} + +export type ActionLifecycle = "pending" | "active" | "done" | "cancelled"; + +export type ActionReadinessView = + | "actionable" + | "scheduled" + | "waiting" + | "blocked" + | "completed" + | "cancelled"; + +export type ActionApprovalState = + | "not_required" + | "pending" + | "approved" + | "rejected"; + +export interface ActionApproval { + state: ActionApprovalState; + requestedAt?: string; + requestedBy?: string; + decidedAt?: string; + decidedBy?: string; + note?: string; +} + +export type ActionEventType = + | "created" + | "fields_changed" + | "lifecycle_changed" + | "result_recorded" + | "corrected" + | "migrated" + | "deleted" + | "edge_created" + | "edge_deleted"; + +export interface ActionEvent { + schemaVersion: 2; + id: string; + actionId: string; + entityType: "action" | "edge"; + revision: number; + type: ActionEventType; + actor: string; + timestamp: string; + reason?: string; + correctionOf?: string; + before?: Action | ActionEdge; + after?: Action | ActionEdge; +} + +export interface ActionCollectionState { + schemaVersion: 2; + revision: number; + updatedAt: string; + pending?: { + revision: number; + eventId: string; + }; +} + +export interface ActionSnapshot { + schemaVersion: 2; + revision: number; + actionCount: number; + edgeCount: number; + eventCount: number; +} + +export interface ActionBlocker { + type: + | "manual" + | "requires" + | "checkpoint" + | "conflict" + | "lease" + | "approval" + | "schedule"; + id?: string; + message: string; +} + +export interface ActionViewItem { + action: Action; + view: ActionReadinessView; + blockers: ActionBlocker[]; + leased: boolean; + score?: number; } export type ActionEdgeType = diff --git a/test/actions-api-pagination.test.ts b/test/actions-api-pagination.test.ts index f0626cace0..04bd3902da 100644 --- a/test/actions-api-pagination.test.ts +++ b/test/actions-api-pagination.test.ts @@ -61,4 +61,82 @@ describe("Actions REST pagination", () => { expect(response.status_code).toBe(400); expect(response.body.error).toBe(error); }); + + it("returns 409 when the collection changes between cursor pages", async () => { + const first = (await sdk.trigger("api::action-list", { + headers: {}, + query_params: { limit: "10" }, + })) as { + status_code: number; + body: { nextCursor: string; revision: number }; + }; + expect(first.status_code).toBe(200); + + await sdk.trigger("mem::action-create", { title: "Concurrent task" }); + const second = (await sdk.trigger("api::action-list", { + headers: {}, + query_params: { limit: "10", cursor: first.body.nextCursor }, + })) as { + status_code: number; + body: { success: boolean; error: string }; + }; + + expect(second.status_code).toBe(409); + expect(second.body).toMatchObject({ + success: false, + error: "revision_conflict", + }); + }); + + it("whitelists action-create fields instead of forwarding the raw body", async () => { + let received: Record | undefined; + sdk.registerFunction("mem::action-create", async (data) => { + received = data as Record; + return { success: true, action: { id: "act_whitelist" } }; + }); + + const response = (await sdk.trigger("api::action-create", { + headers: {}, + body: { + title: "Allowed", + projectId: "agentmemory", + actor: "codex", + injectedInternalFlag: true, + }, + })) as { status_code: number }; + + expect(response.status_code).toBe(201); + expect(received).toMatchObject({ + title: "Allowed", + projectId: "agentmemory", + actor: "codex", + }); + expect(received).not.toHaveProperty("injectedInternalFlag"); + }); + + it("whitelists actions-v2 migration controls", async () => { + let received: Record | undefined; + sdk.registerFunction("mem::migrate", async (data) => { + received = data as Record; + return { success: true, ...received }; + }); + + const response = (await sdk.trigger("api::migrate", { + headers: {}, + body: { + step: "actions-v2", + projectAliases: { "/legacy": "agentmemory" }, + limit: 25, + injectedInternalFlag: true, + }, + })) as { status_code: number }; + + expect(response.status_code).toBe(200); + expect(received).toMatchObject({ + step: "actions-v2", + projectAliases: { "/legacy": "agentmemory" }, + limit: 25, + }); + expect(received).not.toHaveProperty("injectedInternalFlag"); + }); }); diff --git a/test/actions-v2-migration.test.ts b/test/actions-v2-migration.test.ts new file mode 100644 index 0000000000..f8e2dd1505 --- /dev/null +++ b/test/actions-v2-migration.test.ts @@ -0,0 +1,273 @@ +import { describe, expect, it, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { migrateActionsV2 } from "../src/functions/actions-v2-migration.js"; +import type { + Action, + ActionCollectionState, + ActionEvent, +} from "../src/types.js"; +import { mockKV } from "./helpers/mocks.js"; + +function legacyAction( + id: string, + overrides: Partial & { tags?: unknown } = {}, +): Action { + return { + id, + title: `Legacy ${id}`, + description: "", + status: "pending", + priority: 5, + createdAt: "2026-07-01T00:00:00.000Z", + updatedAt: "2026-07-01T00:00:00.000Z", + createdBy: "unknown", + tags: [], + sourceObservationIds: [], + sourceMemoryIds: [], + ...overrides, + } as Action; +} + +describe("Actions v2 migration", () => { + it("rejects invalid migration configuration before reading or writing rows", async () => { + const kv = mockKV(); + await kv.set("mem:actions", "act_config", legacyAction("act_config")); + + const result = await migrateActionsV2(kv as never, { + dryRun: false, + defaultProjectId: "/not/a/project-id", + projectAliases: { "/legacy": "also/not-valid" }, + }); + + expect(result).toMatchObject({ + success: false, + error: "invalid_migration_config", + }); + expect(result.configurationErrors).toHaveLength(2); + expect(await kv.list("mem:action-events")).toEqual([]); + expect(await kv.get("mem:action-state", "current")).toBeNull(); + }); + + it("defaults to a byte-for-byte non-mutating dry run", async () => { + const kv = mockKV(); + const action = legacyAction("act_dry", { + project: "/home/cp/repos/agent-infra/agentmemory", + tags: "agent:codex,worktree:v2" as never, + }); + await kv.set("mem:actions", action.id, action); + const before = structuredClone(action); + + const result = await migrateActionsV2(kv as never); + + expect(result).toMatchObject({ + success: true, + dryRun: true, + scanned: 1, + changed: 1, + revisionBefore: 0, + revisionAfter: 0, + }); + expect(await kv.get("mem:actions", action.id)).toEqual(before); + expect(await kv.list("mem:action-events")).toEqual([]); + expect(await kv.get("mem:action-state", "current")).toBeNull(); + expect(await kv.list("mem:audit")).toEqual([]); + }); + + it("normalizes legacy identity and typed tags, then skips an identical retry", async () => { + const kv = mockKV(); + const dueAt = "2026-07-20T14:00:00.000Z"; + const repoRoot = "/home/cp/repos/trading/trading-system"; + const action = legacyAction("act_apply", { + status: "blocked", + project: repoRoot, + tags: `agent:claude,worktree:wallet-cohort,branch:feat/v2,due:${dueAt}` as never, + }); + await kv.set("mem:actions", action.id, action); + + const first = await migrateActionsV2(kv as never, { + dryRun: false, + projectAliases: { [repoRoot]: "trading-system" }, + actor: "migration-test", + }); + const migrated = await kv.get("mem:actions", action.id); + const eventsAfterFirst = await kv.list("mem:action-events"); + const second = await migrateActionsV2(kv as never, { + dryRun: false, + projectAliases: { [repoRoot]: "trading-system" }, + actor: "migration-test", + }); + + expect(first).toMatchObject({ + success: true, + dryRun: false, + scanned: 1, + changed: 1, + revisionBefore: 0, + revisionAfter: 1, + }); + expect(migrated).toMatchObject({ + schemaVersion: 2, + revision: 1, + lifecycle: "pending", + status: "blocked", + project: "trading-system", + projectId: "trading-system", + owner: "claude", + repoRoot, + worktree: "wallet-cohort", + branch: "feat/v2", + dueAt, + blockedReason: "Legacy blocked state", + awaitingHuman: false, + }); + expect(migrated?.projectAliases).toContain(repoRoot); + expect(migrated?.tags).toEqual([ + "agent:claude", + "worktree:wallet-cohort", + "branch:feat/v2", + `due:${dueAt}`, + ]); + expect(eventsAfterFirst).toHaveLength(1); + expect(eventsAfterFirst[0]).toMatchObject({ + actionId: action.id, + type: "migrated", + actor: "migration-test", + revision: 1, + }); + expect(second).toMatchObject({ + success: true, + changed: 0, + skipped: 1, + revisionBefore: 1, + revisionAfter: 1, + }); + expect(await kv.list("mem:action-events")).toHaveLength(1); + expect(await kv.list("mem:audit")).toHaveLength(1); + }); + + it("infers canonical IDs from Unix and Windows repository paths", async () => { + const kv = mockKV(); + await kv.set( + "mem:actions", + "act_unix", + legacyAction("act_unix", { project: "/srv/repos/agentmemory/" }), + ); + await kv.set( + "mem:actions", + "act_windows", + legacyAction("act_windows", { project: "C:\\repos\\trading-system\\" }), + ); + + const result = await migrateActionsV2(kv as never, { dryRun: false }); + + expect(result).toMatchObject({ success: true, changed: 2 }); + expect(await kv.get("mem:actions", "act_unix")).toMatchObject({ + projectId: "agentmemory", + }); + expect(await kv.get("mem:actions", "act_windows")).toMatchObject({ + projectId: "trading-system", + }); + }); + + it("stops before any mutation when explicit project identities conflict", async () => { + const kv = mockKV(); + const legacyPath = "/legacy/repo"; + const action = legacyAction("act_conflict", { + project: legacyPath, + projectId: "alpha", + }); + await kv.set("mem:actions", action.id, action); + const before = structuredClone(action); + + const result = await migrateActionsV2(kv as never, { + dryRun: false, + projectAliases: { [legacyPath]: "beta" }, + }); + + expect(result).toMatchObject({ + success: false, + error: "migration_conflict", + conflictCount: 1, + unresolvedActionIds: [action.id], + revisionBefore: 0, + revisionAfter: 0, + }); + expect(await kv.get("mem:actions", action.id)).toEqual(before); + expect(await kv.list("mem:action-events")).toEqual([]); + expect(await kv.get("mem:action-state", "current")).toBeNull(); + }); + + it("processes deterministic bounded batches with an opaque cursor", async () => { + const kv = mockKV(); + for (const id of ["act_001", "act_002", "act_003"]) { + await kv.set("mem:actions", id, legacyAction(id)); + } + + const first = await migrateActionsV2(kv as never, { + dryRun: false, + limit: 2, + }); + expect(first).toMatchObject({ + success: true, + scanned: 2, + changed: 2, + hasMore: true, + revisionAfter: 2, + }); + expect(first.nextCursor).toEqual(expect.any(String)); + + const second = await migrateActionsV2(kv as never, { + dryRun: false, + limit: 2, + cursor: first.nextCursor ?? undefined, + }); + expect(second).toMatchObject({ + success: true, + scanned: 1, + changed: 1, + hasMore: false, + nextCursor: null, + revisionBefore: 2, + revisionAfter: 3, + }); + expect(await kv.list("mem:action-events")).toHaveLength(3); + }); + + it("reports a pending store write during dry-run without recovering it", async () => { + const kv = mockKV(); + const pendingState: ActionCollectionState = { + schemaVersion: 2, + revision: 7, + updatedAt: "2026-07-17T06:00:00.000Z", + pending: { revision: 8, eventId: "aev_pending" }, + }; + await kv.set("mem:action-state", "current", pendingState); + const event: ActionEvent = { + schemaVersion: 2, + id: "aev_pending", + actionId: "act_pending", + entityType: "action", + revision: 8, + type: "created", + actor: "codex", + timestamp: pendingState.updatedAt, + }; + await kv.set("mem:action-events", event.id, event); + + const result = await migrateActionsV2(kv as never, { dryRun: true }); + + expect(result).toMatchObject({ + success: false, + error: "pending_action_store_recovery", + revisionBefore: 7, + revisionAfter: 7, + }); + expect(await kv.get("mem:action-state", "current")).toEqual(pendingState); + expect(await kv.get("mem:actions", "act_pending")).toBeNull(); + expect(await kv.get("mem:action-events", event.id)).toEqual(event); + }); +}); diff --git a/test/actions-v2.test.ts b/test/actions-v2.test.ts new file mode 100644 index 0000000000..d3dd44574b --- /dev/null +++ b/test/actions-v2.test.ts @@ -0,0 +1,524 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { registerActionsFunction } from "../src/functions/actions.js"; +import { registerSentinelsFunction } from "../src/functions/sentinels.js"; +import { registerCheckpointsFunction } from "../src/functions/checkpoints.js"; +import { persistAction } from "../src/functions/action-store.js"; +import { registerLeasesFunction } from "../src/functions/leases.js"; +import type { + Action, + ActionCollectionState, + ActionEvent, + ActionViewItem, + Checkpoint, + Sentinel, +} from "../src/types.js"; +import { mockKV, mockSdk } from "./helpers/mocks.js"; + +describe("Actions v2", () => { + let sdk: ReturnType; + let kv: ReturnType; + + beforeEach(() => { + sdk = mockSdk(); + kv = mockKV(); + registerActionsFunction(sdk as never, kv as never); + registerSentinelsFunction(sdk as never, kv as never); + registerCheckpointsFunction(sdk as never, kv as never); + registerLeasesFunction(sdk as never, kv as never); + }); + + it("normalizes new actions into the v2 projection and appends a creation event", async () => { + const dueAt = "2026-07-18T12:00:00.000Z"; + const result = (await sdk.trigger("mem::action-create", { + title: "Ship Actions v2", + project: "/home/cp/repos/agent-infra/agentmemory", + tags: `agent:codex,worktree:actions-v2,due:${dueAt},schema`, + actor: "codex", + })) as { success: boolean; action: Action; revision: number }; + + expect(result.success).toBe(true); + expect(result.revision).toBe(1); + expect(result.action).toMatchObject({ + schemaVersion: 2, + revision: 1, + lifecycle: "pending", + status: "pending", + project: "agentmemory", + projectId: "agentmemory", + owner: "codex", + worktree: "actions-v2", + dueAt, + awaitingHuman: false, + }); + expect(result.action.projectAliases).toContain( + "/home/cp/repos/agent-infra/agentmemory", + ); + expect(result.action.tags).toEqual([ + "agent:codex", + "worktree:actions-v2", + `due:${dueAt}`, + "schema", + ]); + + const events = await kv.list("mem:action-events"); + const state = await kv.get( + "mem:action-state", + "current", + ); + expect(events).toHaveLength(1); + expect(events[0]).toMatchObject({ + actionId: result.action.id, + entityType: "action", + revision: 1, + type: "created", + actor: "codex", + }); + expect(state).toMatchObject({ schemaVersion: 2, revision: 1 }); + expect(state?.pending).toBeUndefined(); + }); + + it.each([ + [{ title: "Bad wait", awaitingHuman: "false" }, "awaitingHuman must be boolean"], + [ + { title: "Bad aliases", projectAliases: "legacy" }, + "projectAliases must be an array of strings", + ], + [{ title: "Bad priority", priority: Number.NaN }, "priority must be a finite number"], + ])("rejects malformed typed fields at the action boundary", async (input, error) => { + const result = (await sdk.trigger("mem::action-create", input)) as { + success: boolean; + error: string; + }; + expect(result).toEqual({ success: false, error }); + }); + + it("returns the final collection revision for an action plus inline edges", async () => { + const first = (await sdk.trigger("mem::action-create", { + title: "First dependency", + })) as { action: Action }; + const second = (await sdk.trigger("mem::action-create", { + title: "Second dependency", + })) as { action: Action }; + + const result = (await sdk.trigger("mem::action-create", { + title: "Dependent action", + edges: [ + { type: "requires", targetActionId: first.action.id }, + { type: "requires", targetActionId: second.action.id }, + ], + })) as { success: boolean; revision: number }; + const state = await kv.get( + "mem:action-state", + "current", + ); + + expect(result.success).toBe(true); + expect(result.revision).toBe(5); + expect(result.revision).toBe(state?.revision); + expect(await kv.list("mem:action-events")).toHaveLength(5); + }); + + it("derives separate actionable, scheduled, waiting, blocked, and completed views", async () => { + await sdk.trigger("mem::action-create", { title: "Ready" }); + await sdk.trigger("mem::action-create", { + title: "Later", + notBefore: "2999-01-01T00:00:00.000Z", + }); + await sdk.trigger("mem::action-create", { + title: "Needs approval", + awaitingHuman: true, + }); + await sdk.trigger("mem::action-create", { + title: "Manually blocked", + blockedReason: "Waiting for an external artifact", + }); + await sdk.trigger("mem::action-create", { + title: "Finished", + lifecycle: "done", + }); + + const expected = new Map([ + ["actionable", "Ready"], + ["scheduled", "Later"], + ["waiting", "Needs approval"], + ["blocked", "Manually blocked"], + ["completed", "Finished"], + ]); + for (const [view, title] of expected) { + const page = (await sdk.trigger("mem::action-list", { view })) as { + success: boolean; + views: ActionViewItem[]; + }; + expect(page.success).toBe(true); + expect(page.views.map((item) => item.action.title)).toEqual([title]); + expect(page.views[0].view).toBe(view); + } + }); + + it.each([ + [ + { title: "Scheduled lease", notBefore: "2999-01-01T00:00:00.000Z" }, + "scheduled", + ], + [{ title: "Human-gated lease", awaitingHuman: true }, "waiting"], + ])("refuses leases for %s actions", async (input, view) => { + const created = (await sdk.trigger("mem::action-create", input)) as { + action: Action; + }; + const result = (await sdk.trigger("mem::lease-acquire", { + actionId: created.action.id, + agentId: "worker-a", + })) as { success: boolean; error: string }; + + expect(result).toMatchObject({ + success: false, + error: `action is ${view}`, + }); + expect(await kv.list("mem:leases")).toEqual([]); + }); + + it("derives sentinel gates as blocked until the sentinel triggers", async () => { + const created = (await sdk.trigger("mem::action-create", { + title: "Wait for sentinel", + })) as { action: Action }; + const sentinel = (await sdk.trigger("mem::sentinel-create", { + name: "Approval gate", + type: "approval", + linkedActionIds: [created.action.id], + })) as { success: boolean; sentinel: Sentinel }; + expect(sentinel.success).toBe(true); + + const blocked = (await sdk.trigger("mem::action-list", { + view: "blocked", + })) as { views: ActionViewItem[]; revision: number }; + expect(blocked.views).toHaveLength(1); + expect(blocked.views[0].blockers[0].message).toContain("Approval gate"); + + await sdk.trigger("mem::sentinel-trigger", { + sentinelId: sentinel.sentinel.id, + }); + const stale = (await sdk.trigger("mem::action-list", { + revision: blocked.revision, + })) as { success: boolean; error: string }; + expect(stale).toMatchObject({ + success: false, + error: "revision_conflict", + }); + const actionable = (await sdk.trigger("mem::action-list", { + view: "actionable", + })) as { actions: Action[]; revision: number }; + expect(actionable.revision).toBeGreaterThan(blocked.revision); + expect(actionable.actions.map((action) => action.id)).toContain( + created.action.id, + ); + }); + + it("invalidates readiness revisions when a checkpoint resolves", async () => { + const created = (await sdk.trigger("mem::action-create", { + title: "Wait for CI", + })) as { action: Action }; + const checkpoint = (await sdk.trigger("mem::checkpoint-create", { + name: "CI", + type: "ci", + linkedActionIds: [created.action.id], + })) as { success: boolean; checkpoint: Checkpoint }; + expect(checkpoint.success).toBe(true); + const before = (await sdk.trigger("mem::action-list", { + view: "blocked", + })) as { revision: number; actions: Action[] }; + expect(before.actions.map((action) => action.id)).toContain( + created.action.id, + ); + + await sdk.trigger("mem::checkpoint-resolve", { + checkpointId: checkpoint.checkpoint.id, + status: "passed", + resolvedBy: "ci", + }); + const stale = (await sdk.trigger("mem::action-list", { + revision: before.revision, + })) as { success: boolean; error: string }; + expect(stale).toMatchObject({ + success: false, + error: "revision_conflict", + }); + }); + + it("lets typed approval clear a migrated wait tag without inventing a manual block", async () => { + const created = (await sdk.trigger("mem::action-create", { + title: "Confirm rollout", + tags: "awaiting-human", + })) as { action: Action }; + expect(created.action.awaitingHuman).toBe(true); + expect(created.action.status).toBe("blocked"); + + const updated = (await sdk.trigger("mem::action-update", { + actionId: created.action.id, + awaitingHuman: false, + approval: { + state: "approved", + decidedAt: "2026-07-17T06:00:00.000Z", + decidedBy: "human", + }, + })) as { success: boolean; action: Action }; + + expect(updated.success).toBe(true); + expect(updated.action.tags).toContain("awaiting-human"); + expect(updated.action.awaitingHuman).toBe(false); + expect(updated.action.blockedReason).toBeUndefined(); + expect(updated.action.status).toBe("pending"); + const page = (await sdk.trigger("mem::action-list", { + view: "actionable", + })) as { actions: Action[] }; + expect(page.actions.map((action) => action.id)).toContain(created.action.id); + }); + + it("preserves append-only history for lifecycle, result, and correction changes", async () => { + const created = (await sdk.trigger("mem::action-create", { + title: "Original title", + actor: "planner", + })) as { action: Action }; + const firstEvent = ( + await kv.list("mem:action-events") + )[0]; + + await sdk.trigger("mem::action-update", { + actionId: created.action.id, + lifecycle: "active", + actor: "worker", + }); + await sdk.trigger("mem::action-update", { + actionId: created.action.id, + lifecycle: "done", + result: "Validated", + actor: "worker", + }); + await sdk.trigger("mem::action-update", { + actionId: created.action.id, + title: "Corrected title", + correctionOf: firstEvent.id, + correctionReason: "Fix the initial wording", + actor: "reviewer", + }); + + const result = (await sdk.trigger("mem::action-get", { + actionId: created.action.id, + })) as { action: Action; events: ActionEvent[]; revision: number }; + expect(result.events.map((event) => event.type)).toEqual([ + "created", + "lifecycle_changed", + "result_recorded", + "corrected", + ]); + expect(result.events.map((event) => event.revision)).toEqual([1, 2, 3, 4]); + expect(result.events[3]).toMatchObject({ + actor: "reviewer", + correctionOf: firstEvent.id, + reason: "Fix the initial wording", + }); + expect(result.events[0].after).toMatchObject({ title: "Original title" }); + expect(result.action).toMatchObject({ + title: "Corrected title", + lifecycle: "done", + result: "Validated", + }); + expect(result.revision).toBe(4); + }); + + it("paginates a stable revision and fails closed after a collection change", async () => { + for (let index = 0; index < 5; index += 1) { + await sdk.trigger("mem::action-create", { title: `Task ${index}` }); + } + + const ids = new Set(); + let cursor: string | null = null; + let revision: number | undefined; + do { + const page = (await sdk.trigger("mem::action-list", { + limit: 2, + ...(cursor ? { cursor } : {}), + })) as { + success: boolean; + actions: Action[]; + revision: number; + nextCursor: string | null; + }; + expect(page.success).toBe(true); + revision ??= page.revision; + expect(page.revision).toBe(revision); + for (const action of page.actions) ids.add(action.id); + cursor = page.nextCursor; + } while (cursor); + expect(ids.size).toBe(5); + + const firstPage = (await sdk.trigger("mem::action-list", { + limit: 2, + })) as { nextCursor: string; revision: number }; + await sdk.trigger("mem::action-create", { title: "Concurrent change" }); + const stalePage = (await sdk.trigger("mem::action-list", { + limit: 2, + cursor: firstPage.nextCursor, + })) as { success: boolean; error: string }; + expect(stalePage).toMatchObject({ + success: false, + error: "revision_conflict", + }); + }); + + it("matches canonical projects and retained aliases", async () => { + const legacyPath = "/home/cp/repos/agent-infra/agentmemory"; + const created = (await sdk.trigger("mem::action-create", { + title: "Alias-aware task", + project: legacyPath, + projectId: "agentmemory", + })) as { action: Action }; + + for (const project of ["agentmemory", legacyPath]) { + const page = (await sdk.trigger("mem::action-list", { project })) as { + actions: Action[]; + }; + expect(page.actions.map((action) => action.id)).toEqual([ + created.action.id, + ]); + } + }); + + it("keeps legacy project updates functional while retaining the old canonical ID", async () => { + const created = (await sdk.trigger("mem::action-create", { + title: "Move initiative", + projectId: "alpha", + })) as { action: Action }; + + const updated = (await sdk.trigger("mem::action-update", { + actionId: created.action.id, + project: "beta", + })) as { success: boolean; action: Action }; + + expect(updated.success).toBe(true); + expect(updated.action).toMatchObject({ + project: "beta", + projectId: "beta", + }); + expect(updated.action.projectAliases).toContain("alpha"); + }); + + it("keeps the legacy blocked projection when an unrelated writer touches a dependent action", async () => { + const dependency = (await sdk.trigger("mem::action-create", { + title: "Dependency", + })) as { action: Action }; + const dependent = (await sdk.trigger("mem::action-create", { + title: "Dependent", + edges: [{ type: "requires", targetActionId: dependency.action.id }], + })) as { action: Action }; + + const touched = { ...dependent.action, description: "Metadata touch" }; + const persisted = await persistAction(kv as never, touched, { + actor: "secondary-writer", + before: dependent.action, + }); + + expect(persisted.action).toMatchObject({ + lifecycle: "pending", + status: "blocked", + description: "Metadata touch", + }); + }); + + it("does not turn a transient v2 assignee into the durable owner", async () => { + const created = (await sdk.trigger("mem::action-create", { + title: "Unowned task", + })) as { action: Action }; + expect(created.action.owner).toBeUndefined(); + + const assigned = { ...created.action, assignedTo: "worker-a" }; + const persisted = await persistAction(kv as never, assigned, { + actor: "worker-a", + before: created.action, + }); + + expect(persisted.action.assignedTo).toBe("worker-a"); + expect(persisted.action.owner).toBeUndefined(); + }); + + it("lets typed v2 context be cleared without deleting retained legacy tags", async () => { + const dueAt = "2026-07-20T12:00:00.000Z"; + const created = (await sdk.trigger("mem::action-create", { + title: "Clear typed context", + tags: `due:${dueAt},worktree:legacy-tree`, + })) as { action: Action }; + expect(created.action).toMatchObject({ dueAt, worktree: "legacy-tree" }); + + const updated = (await sdk.trigger("mem::action-update", { + actionId: created.action.id, + dueAt: "", + worktree: "", + })) as { success: boolean; action: Action }; + + expect(updated.success).toBe(true); + expect(updated.action.dueAt).toBeUndefined(); + expect(updated.action.worktree).toBeUndefined(); + expect(updated.action.tags).toEqual([ + `due:${dueAt}`, + "worktree:legacy-tree", + ]); + }); + + it("recovers a pending event before serving a revision-bound read", async () => { + const action: Action = { + id: "act_recover", + title: "Recovered action", + description: "", + status: "pending", + lifecycle: "pending", + priority: 5, + createdAt: "2026-07-17T06:00:00.000Z", + updatedAt: "2026-07-17T06:00:00.000Z", + createdBy: "codex", + project: "agentmemory", + projectId: "agentmemory", + projectAliases: [], + tags: [], + sourceObservationIds: [], + sourceMemoryIds: [], + schemaVersion: 2, + revision: 1, + awaitingHuman: false, + }; + const event: ActionEvent = { + schemaVersion: 2, + id: "aev_recover", + actionId: action.id, + entityType: "action", + revision: 1, + type: "created", + actor: "codex", + timestamp: action.createdAt, + after: action, + }; + await kv.set("mem:action-events", event.id, event); + await kv.set("mem:action-state", "current", { + schemaVersion: 2, + revision: 0, + updatedAt: action.createdAt, + pending: { revision: 1, eventId: event.id }, + }); + + const page = (await sdk.trigger("mem::action-list", {})) as { + actions: Action[]; + revision: number; + }; + const state = await kv.get( + "mem:action-state", + "current", + ); + expect(page.actions.map((candidate) => candidate.id)).toEqual([action.id]); + expect(page.revision).toBe(1); + expect(state).toMatchObject({ revision: 1 }); + expect(state?.pending).toBeUndefined(); + }); +}); diff --git a/test/export-import.test.ts b/test/export-import.test.ts index 3949862699..5bebf0c6ae 100644 --- a/test/export-import.test.ts +++ b/test/export-import.test.ts @@ -11,6 +11,9 @@ import type { Memory, SessionSummary, ExportData, + Action, + ActionCollectionState, + ActionEvent, } from "../src/types.js"; function mockKV() { @@ -249,4 +252,225 @@ describe("Export/Import Functions", () => { expect(result.success).toBe(false); expect(result.error).toContain("Unsupported export version"); }); + + it("exports and replace-imports a coherent action snapshot and event history", async () => { + const action: Action = { + id: "act_v2", + title: "Actions v2", + description: "", + status: "active", + lifecycle: "active", + priority: 9, + createdAt: "2026-07-17T05:00:00.000Z", + updatedAt: "2026-07-17T06:00:00.000Z", + createdBy: "codex", + project: "agentmemory", + projectId: "agentmemory", + projectAliases: [], + owner: "codex", + tags: ["schema-v2"], + sourceObservationIds: [], + sourceMemoryIds: [], + schemaVersion: 2, + revision: 9, + awaitingHuman: false, + }; + const event: ActionEvent = { + schemaVersion: 2, + id: "aev_v2", + actionId: action.id, + entityType: "action", + revision: 9, + type: "lifecycle_changed", + actor: "codex", + timestamp: action.updatedAt, + after: action, + }; + await kv.set("mem:actions", action.id, action); + await kv.set("mem:action-events", event.id, event); + await kv.set("mem:action-state", "current", { + schemaVersion: 2, + revision: 9, + updatedAt: action.updatedAt, + }); + + const exported = (await sdk.trigger("mem::export", {})) as ExportData; + expect(exported.actions).toEqual([action]); + expect(exported.actionEvents).toEqual([event]); + expect(exported.actionSnapshot).toEqual({ + schemaVersion: 2, + revision: 9, + actionCount: 1, + edgeCount: 0, + eventCount: 1, + }); + + const freshKv = mockKV(); + const freshSdk = mockSdk(); + registerExportImportFunction(freshSdk as never, freshKv as never); + const imported = (await freshSdk.trigger("mem::import", { + exportData: exported, + strategy: "replace", + })) as { success: boolean; actions: number; actionEvents: number }; + expect(imported).toMatchObject({ + success: true, + actions: 1, + actionEvents: 1, + }); + expect( + await freshKv.get("mem:action-state", "current"), + ).toMatchObject({ schemaVersion: 2, revision: 9 }); + + const reExported = (await freshSdk.trigger( + "mem::export", + {}, + )) as ExportData; + expect(reExported.actionSnapshot).toEqual(exported.actionSnapshot); + expect(JSON.parse(JSON.stringify(reExported.actions))).toEqual( + JSON.parse(JSON.stringify(exported.actions)), + ); + expect(reExported.actionEvents).toEqual(exported.actionEvents); + }); + + it("normalizes actions from an old export before persistence", async () => { + const legacy = { + id: "act_legacy", + title: "Legacy export action", + description: "", + status: "pending", + priority: 5, + createdAt: "2026-07-01T00:00:00.000Z", + updatedAt: "2026-07-01T00:00:00.000Z", + createdBy: "unknown", + project: "/home/cp/repos/agent-infra/agentmemory", + tags: "agent:kimi,worktree:legacy", + sourceObservationIds: [], + sourceMemoryIds: [], + } as unknown as Action; + const exportData: ExportData = { + version: "0.9.27", + exportedAt: new Date().toISOString(), + sessions: [], + observations: {}, + memories: [], + summaries: [], + actions: [legacy], + }; + + const result = (await sdk.trigger("mem::import", { + exportData, + strategy: "merge", + })) as { success: boolean; actions: number }; + const stored = await kv.get("mem:actions", legacy.id); + + expect(result).toMatchObject({ success: true, actions: 1 }); + expect(stored).toMatchObject({ + schemaVersion: 2, + lifecycle: "pending", + project: "agentmemory", + projectId: "agentmemory", + owner: "kimi", + worktree: "legacy", + awaitingHuman: false, + }); + expect(stored?.tags).toEqual(["agent:kimi", "worktree:legacy"]); + }); + + it("rejects invalid action snapshot counts before replace mutation", async () => { + const preserved = { + id: "act_preserved", + title: "Preserve me", + description: "", + status: "pending", + priority: 5, + createdAt: "2026-07-01T00:00:00.000Z", + updatedAt: "2026-07-01T00:00:00.000Z", + createdBy: "codex", + tags: [], + sourceObservationIds: [], + sourceMemoryIds: [], + } satisfies Action; + await kv.set("mem:actions", preserved.id, preserved); + const exportData: ExportData = { + version: "0.9.27", + exportedAt: new Date().toISOString(), + sessions: [], + observations: {}, + memories: [], + summaries: [], + actions: [], + actionSnapshot: { + schemaVersion: 2, + revision: 1, + actionCount: 1, + edgeCount: 0, + eventCount: 0, + }, + }; + + const result = (await sdk.trigger("mem::import", { + exportData, + strategy: "replace", + })) as { success: boolean; error: string }; + + expect(result).toMatchObject({ + success: false, + error: "Action snapshot counts or revision are invalid", + }); + expect(await kv.get("mem:actions", preserved.id)).toEqual(preserved); + expect(await kv.get("mem:sessions", "ses_1")).toEqual(testSession); + }); + + it("advances the local revision when replace import changes an existing action collection", async () => { + const existing = { + id: "act_existing", + title: "Existing action", + description: "", + status: "pending", + priority: 5, + createdAt: "2026-07-01T00:00:00.000Z", + updatedAt: "2026-07-01T00:00:00.000Z", + createdBy: "codex", + tags: [], + sourceObservationIds: [], + sourceMemoryIds: [], + } satisfies Action; + await kv.set("mem:actions", existing.id, existing); + await kv.set("mem:action-state", "current", { + schemaVersion: 2, + revision: 9, + updatedAt: "2026-07-17T06:00:00.000Z", + }); + const emptySnapshot: ExportData = { + version: "0.9.27", + exportedAt: new Date().toISOString(), + sessions: [], + observations: {}, + memories: [], + summaries: [], + actions: [], + actionEdges: [], + actionEvents: [], + actionSnapshot: { + schemaVersion: 2, + revision: 0, + actionCount: 0, + edgeCount: 0, + eventCount: 0, + }, + }; + + const result = (await sdk.trigger("mem::import", { + exportData: emptySnapshot, + strategy: "replace", + })) as { success: boolean }; + const state = await kv.get( + "mem:action-state", + "current", + ); + + expect(result.success).toBe(true); + expect(await kv.get("mem:actions", existing.id)).toBeNull(); + expect(state?.revision).toBe(10); + }); }); diff --git a/test/leases.test.ts b/test/leases.test.ts index 95f74b5bbf..10099596d4 100644 --- a/test/leases.test.ts +++ b/test/leases.test.ts @@ -5,7 +5,7 @@ vi.mock("../src/logger.js", () => ({ })); import { registerLeasesFunction } from "../src/functions/leases.js"; -import type { Action, Lease } from "../src/types.js"; +import type { Action, ActionEdge, Lease } from "../src/types.js"; function mockKV() { const store = new Map>(); @@ -221,6 +221,35 @@ describe("Lease Functions", () => { expect(action!.assignedTo).toBeUndefined(); }); + it("unblocks dependents when a lease is released with a result", async () => { + const dependent = (await kv.get("mem:actions", "act_4"))!; + dependent.status = "blocked"; + await kv.set("mem:actions", dependent.id, dependent); + const edge: ActionEdge = { + id: "ae_lease_completion", + type: "requires", + sourceActionId: dependent.id, + targetActionId: "act_1", + createdAt: "2026-07-17T06:00:00.000Z", + }; + await kv.set("mem:action-edges", edge.id, edge); + await sdk.trigger("mem::lease-acquire", { + actionId: "act_1", + agentId: "agent-a", + }); + + await sdk.trigger("mem::lease-release", { + actionId: "act_1", + agentId: "agent-a", + result: "dependency complete", + }); + + expect(await kv.get("mem:actions", dependent.id)).toMatchObject({ + status: "pending", + lifecycle: "pending", + }); + }); + it("sets action to pending when no result is provided", async () => { await sdk.trigger("mem::lease-acquire", { actionId: "act_1", diff --git a/test/mcp-surface-default.test.ts b/test/mcp-surface-default.test.ts index af159ffefe..ebb66cc90a 100644 --- a/test/mcp-surface-default.test.ts +++ b/test/mcp-surface-default.test.ts @@ -6,7 +6,7 @@ import { WORKSTATION_TOOLS, } from "../src/mcp/tools-registry.js"; -// plugin manifests and README advertise 51 MCP tools. The old +// Plugin manifests and README advertise the full MCP surface. The old // default was AGENTMEMORY_TOOLS=core which silently capped the surface // at a lean subset with no indication the other tools existed. Default // flipped to "all"; the lean set is still accessible via @@ -21,7 +21,7 @@ describe("MCP tool surface default (#553)", () => { else process.env["AGENTMEMORY_TOOLS"] = ORIG; }); - it("default returns the full 51-tool surface, matching plugin advertising", () => { + it("default returns the full tool surface, matching plugin advertising", () => { const visible = getVisibleTools(); const all = getAllTools(); expect(visible.length).toBe(all.length); @@ -55,6 +55,7 @@ describe("MCP tool surface default (#553)", () => { const names = new Set(getVisibleTools().map((tool) => tool.name)); expect(names).toEqual(WORKSTATION_TOOLS); expect(names.has("memory_action_create")).toBe(true); + expect(names.has("memory_action_list")).toBe(true); expect(names.has("memory_lease")).toBe(true); expect(names.has("memory_signal_send")).toBe(true); expect(names.has("memory_consolidate")).toBe(false); diff --git a/test/tool-count-consistency.test.ts b/test/tool-count-consistency.test.ts index 433de175e3..4215e57c86 100644 --- a/test/tool-count-consistency.test.ts +++ b/test/tool-count-consistency.test.ts @@ -9,7 +9,7 @@ vi.mock("../src/logger.js", () => ({ import { getAllTools, ESSENTIAL_TOOLS } from "../src/mcp/tools-registry.js"; const ROOT = join(import.meta.dirname, ".."); -const EXPECTED_TOOL_COUNT = 53; +const EXPECTED_TOOL_COUNT = 54; function readText(relativePath: string): string { return readFileSync(join(ROOT, relativePath), "utf-8"); From 66986345c9f4417dc15ff0a02eb205e7b2343bd0 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Fri, 17 Jul 2026 08:06:54 -0400 Subject: [PATCH 20/43] fix: harden Actions v2 migration invariants --- .../specs/2026-07-17-actions-v2-design.md | 20 ++- src/functions/action-model.ts | 121 +++++++++++---- src/functions/action-query.ts | 20 ++- src/functions/action-store.ts | 76 +++++++++- src/functions/actions-v2-migration.ts | 40 ++--- src/functions/actions.ts | 10 ++ src/functions/diagnostics.ts | 12 ++ src/functions/export-import.ts | 61 +++++++- src/functions/frontier.ts | 31 ++-- src/functions/leases.ts | 63 ++++++-- test/actions-v2-migration.test.ts | 77 ++++++++++ test/actions-v2.test.ts | 138 +++++++++++++++++- test/export-import.test.ts | 56 +++++++ 13 files changed, 632 insertions(+), 93 deletions(-) diff --git a/docs/superpowers/specs/2026-07-17-actions-v2-design.md b/docs/superpowers/specs/2026-07-17-actions-v2-design.md index cfe4fb7055..459a5b08ba 100644 --- a/docs/superpowers/specs/2026-07-17-actions-v2-design.md +++ b/docs/superpowers/specs/2026-07-17-actions-v2-design.md @@ -143,8 +143,10 @@ Project selection uses this precedence: 1. an explicit valid `projectId`; 2. an explicit migration alias map entry for the legacy `project` value; -3. one unambiguous `projectId:` legacy tag; -4. a non-path legacy `project` value; +3. a valid non-path legacy `project` value, because this is the authoritative + queue scope used by existing `memory_next` and `todo` callers; +4. one unambiguous `projectId:` legacy tag when the action has no + authoritative queue scope; 5. the final path segment of an absolute legacy repository path, recorded as an inferred mapping and preserved in `projectAliases`; 6. the caller-supplied migration fallback, defaulting to `workstation` only for @@ -156,6 +158,13 @@ are retained in `projectAliases`. The migration reports explicit, inferred, defaulted, and conflicting mappings separately so rollout can stop on an unexpected inference. +Existing cross-repo actions may legitimately carry multiple `projectId:` +tags as repository context while their `project` is an initiative queue. When +an authoritative project is present, those tags are retained as context and +reported as warnings rather than treated as competing identities. Ambiguous or +invalid project tags remain hard conflicts only when the row has no +authoritative project from which to migrate. + New v2 callers should send `projectId`. Legacy callers may continue sending `project`; the normalizer produces the same persisted v2 shape and includes normalization warnings in the result when inference was necessary. @@ -240,6 +249,13 @@ pending marker. An existing event is replayed into the projection; a marker without an event is cleared without advancing the revision. Normal reads never observe intermediate writes because they use the same in-process lock. +Secondary action writers supply the projection they read as an optimistic base. +The store rebases non-overlapping field changes onto the current projection and +rejects same-field races with `action_revision_conflict`. This keeps checkpoint, +lease, sketch, routine, mesh, crystallization, and healing updates from silently +overwriting a concurrent action change even when their larger workflows use +different entity locks. + The existing audit log remains. Action events are the domain history; audit entries remain the system-wide operational record. diff --git a/src/functions/action-model.ts b/src/functions/action-model.ts index ddaeb740ab..b7a6b954a8 100644 --- a/src/functions/action-model.ts +++ b/src/functions/action-model.ts @@ -58,6 +58,15 @@ export interface ActionViewContext { leases: Lease[]; agentId?: string; now?: number; + index?: ActionViewIndex; +} + +export interface ActionViewIndex { + actionMap: Map; + edgesByActionId: Map; + checkpointMap: Map; + sentinelMap: Map; + activeLeaseMap: Map; } interface ActionCursorPayload { @@ -124,7 +133,10 @@ export function normalizeActionV2( if (!Array.isArray(raw.tags)) warnings.push("tags_normalized"); const tagProjectIds = uniqueTagValues(tags, "projectId"); - if (tagProjectIds.length > 1) conflicts.push("conflicting_project_tags"); + const validTagProjectIds = tagProjectIds.filter(isCanonicalProjectId); + const invalidTagProjectIds = tagProjectIds.filter( + (value) => !isCanonicalProjectId(value), + ); const legacyProject = nonEmpty(raw.project); const explicitProjectId = nonEmpty(raw.projectId); @@ -150,18 +162,6 @@ export function normalizeActionV2( warnings.push("project_resolved_from_alias_map"); } } - if (tagProjectIds[0]) { - if (!isCanonicalProjectId(tagProjectIds[0])) { - conflicts.push("invalid_project_tag"); - } else if (projectId && tagProjectIds[0] !== projectId) { - conflicts.push("conflicting_project_tag"); - } else { - projectId = tagProjectIds[0]; - if (!explicitProjectId && !mappedProject) { - warnings.push("project_resolved_from_tag"); - } - } - } if (!projectId && legacyProject && !isProjectPath(legacyProject)) { if (isCanonicalProjectId(legacyProject)) { projectId = legacyProject; @@ -169,6 +169,28 @@ export function normalizeActionV2( conflicts.push("invalid_legacy_project_id"); } } + const projectResolvedWithoutTags = projectId !== undefined; + if (!projectId) { + if (validTagProjectIds.length > 1) { + conflicts.push("conflicting_project_tags"); + } else if (validTagProjectIds[0]) { + projectId = validTagProjectIds[0]; + warnings.push("project_resolved_from_tag"); + } + if (invalidTagProjectIds.length > 0) { + conflicts.push("invalid_project_tag"); + } + } else { + const contextualProjectTags = tagProjectIds.filter( + (value) => value !== projectId, + ); + if (contextualProjectTags.length > 0) { + warnings.push("project_tags_retained_as_context"); + } + if (invalidTagProjectIds.length > 0) { + warnings.push("invalid_project_tag_ignored"); + } + } if (!projectId && legacyProject && isProjectPath(legacyProject)) { const trimmedPath = legacyProject.replace(/[\\/]+$/, ""); const inferred = win32.isAbsolute(legacyProject) @@ -192,6 +214,17 @@ export function normalizeActionV2( } } + if ( + !projectResolvedWithoutTags && + projectId && + invalidTagProjectIds.length > 0 && + conflicts.includes("invalid_project_tag") + ) { + // An invalid tag remains a hard conflict when it was part of identity + // resolution. Path inference or fallback must not silently hide it. + warnings.push("project_identity_requires_review"); + } + const projectAliases = new Set( normalizeStringArray(raw.projectAliases).filter( (alias) => alias !== projectId, @@ -337,19 +370,9 @@ export function classifyAction( context: ActionViewContext, ): ActionViewItem { const now = context.now ?? Date.now(); - const actionEdges = context.edges.filter( - (edge) => - edge.sourceActionId === input.id || edge.targetActionId === input.id, - ); - const actionMap = new Map( - context.actions.map((candidate) => [candidate.id, candidate]), - ); - const checkpointMap = new Map( - context.checkpoints.map((checkpoint) => [checkpoint.id, checkpoint]), - ); - const sentinelMap = new Map( - context.sentinels.map((sentinel) => [sentinel.id, sentinel]), - ); + const index = context.index ?? buildActionViewIndex(context); + const actionEdges = index.edgesByActionId.get(input.id) ?? []; + const { actionMap, checkpointMap, sentinelMap } = index; const hasDerivedBlockers = actionEdges.some( (edge) => { if (edge.sourceActionId !== input.id) return false; @@ -440,12 +463,7 @@ export function classifyAction( } } - const activeLease = context.leases.find( - (lease) => - lease.actionId === action.id && - lease.status === "active" && - Date.parse(lease.expiresAt) > now, - ); + const activeLease = index.activeLeaseMap.get(action.id); const leased = activeLease !== undefined; if ( activeLease && @@ -487,6 +505,45 @@ export function classifyAction( return { action, view: "actionable", blockers: [], leased }; } +export function buildActionViewIndex( + context: Omit, +): ActionViewIndex { + const now = context.now ?? Date.now(); + const edgesByActionId = new Map(); + for (const edge of context.edges) { + const sourceEdges = edgesByActionId.get(edge.sourceActionId) ?? []; + sourceEdges.push(edge); + edgesByActionId.set(edge.sourceActionId, sourceEdges); + if (edge.targetActionId !== edge.sourceActionId) { + const targetEdges = edgesByActionId.get(edge.targetActionId) ?? []; + targetEdges.push(edge); + edgesByActionId.set(edge.targetActionId, targetEdges); + } + } + const activeLeaseMap = new Map(); + for (const lease of context.leases) { + if ( + lease.status === "active" && + Date.parse(lease.expiresAt) > now + ) { + activeLeaseMap.set(lease.actionId, lease); + } + } + return { + actionMap: new Map( + context.actions.map((candidate) => [candidate.id, candidate]), + ), + edgesByActionId, + checkpointMap: new Map( + context.checkpoints.map((checkpoint) => [checkpoint.id, checkpoint]), + ), + sentinelMap: new Map( + context.sentinels.map((sentinel) => [sentinel.id, sentinel]), + ), + activeLeaseMap, + }; +} + export function computeActionScore( action: Action, edges: ActionEdge[], diff --git a/src/functions/action-query.ts b/src/functions/action-query.ts index 11133f4afa..3750e5dda0 100644 --- a/src/functions/action-query.ts +++ b/src/functions/action-query.ts @@ -8,6 +8,7 @@ import type { } from "../types.js"; import { actionFilterFingerprint, + buildActionViewIndex, classifyAction, decodeActionCursor, encodeActionCursor, @@ -111,16 +112,21 @@ export function selectActionPage( ); } + const viewContext = { + actions: snapshot.actions, + edges: snapshot.edges, + checkpoints, + sentinels, + leases, + agentId: options.agentId, + now: asOf, + }; + const index = buildActionViewIndex(viewContext); const views = snapshot.actions .map((action) => classifyAction(action, { - actions: snapshot.actions, - edges: snapshot.edges, - checkpoints, - sentinels, - leases, - agentId: options.agentId, - now: asOf, + ...viewContext, + index, }), ) .filter((item) => { diff --git a/src/functions/action-store.ts b/src/functions/action-store.ts index 9a37acf93a..2d477c4161 100644 --- a/src/functions/action-store.ts +++ b/src/functions/action-store.ts @@ -1,3 +1,4 @@ +import { isDeepStrictEqual } from "node:util"; import type { StateKV } from "../state/kv.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import { KV, generateId } from "../state/schema.js"; @@ -47,6 +48,20 @@ export class ActionNormalizationError extends Error { } } +export class ActionRevisionConflictError extends Error { + constructor( + readonly actionId: string, + readonly fields: string[], + ) { + super( + fields.length > 0 + ? `Action ${actionId} changed concurrently in: ${fields.join(", ")}` + : `Action ${actionId} changed concurrently`, + ); + this.name = "ActionRevisionConflictError"; + } +} + export function withActionStoreLock(fn: () => Promise): Promise { return withKeyedLock(ACTION_STORE_LOCK, fn); } @@ -84,15 +99,17 @@ export async function persistActionUnlocked( options: PersistActionOptions = {}, ): Promise { const state = await recoverActionStoreUnlocked(kv); - const before = + const current = await kv.get(KV.actions, input.id); + const candidate = options.before === undefined - ? await kv.get(KV.actions, input.id) - : options.before; + ? input + : rebaseActionMutation(input, options.before, current); + const before = current; const revision = state.revision + 1; const hasDerivedBlockers = options.hasDerivedBlockers ?? (await actionHasUnresolvedDerivedBlockers(kv, input.id)); - const normalization = normalizeActionV2(input, { + const normalization = normalizeActionV2(candidate, { projectAliases: options.projectAliases, defaultProjectId: options.defaultProjectId, hasDerivedBlockers, @@ -378,3 +395,54 @@ async function actionHasUnresolvedDerivedBlockers( function clone(value: T): T { return structuredClone(value); } + +function rebaseActionMutation( + input: Action, + expectedBefore: Action | null, + current: Action | null, +): Action { + if (!expectedBefore || !current) { + if (expectedBefore === current) return input; + throw new ActionRevisionConflictError(input.id, []); + } + + const managedFields = new Set([ + "schemaVersion", + "revision", + "updatedAt", + ]); + const keys = new Set([ + ...(Object.keys(expectedBefore) as Array), + ...(Object.keys(input) as Array), + ...(Object.keys(current) as Array), + ]); + const intendedFields = [...keys].filter( + (field) => + !managedFields.has(field) && + !isDeepStrictEqual(expectedBefore[field], input[field]), + ); + const conflicts = intendedFields.filter( + (field) => + !isDeepStrictEqual(expectedBefore[field], current[field]) && + !isDeepStrictEqual(input[field], current[field]), + ); + if (conflicts.length > 0) { + throw new ActionRevisionConflictError( + input.id, + conflicts.map(String).sort(), + ); + } + + const rebased = structuredClone(current) as Action & + Record; + const source = input as Action & Record; + for (const field of intendedFields) { + if (Object.prototype.hasOwnProperty.call(source, field)) { + rebased[field] = structuredClone(source[field]); + } else { + delete rebased[field]; + } + } + rebased.updatedAt = input.updatedAt; + return rebased; +} diff --git a/src/functions/actions-v2-migration.ts b/src/functions/actions-v2-migration.ts index ef06772d19..a685c967b1 100644 --- a/src/functions/actions-v2-migration.ts +++ b/src/functions/actions-v2-migration.ts @@ -66,14 +66,14 @@ export async function migrateActionsV2( ? ordered.filter((action) => action.id > afterId) : ordered; const page = eligible.slice(0, limit); + const unresolvedDerivedActionIds = collectUnresolvedDerivedActionIds( + actions, + edges, + checkpoints, + sentinels, + ); const candidates: MigrationCandidate[] = page.map((action) => { - const hasDerivedBlockers = hasUnresolvedDerivedBlockers( - action.id, - actions, - edges, - checkpoints, - sentinels, - ); + const hasDerivedBlockers = unresolvedDerivedActionIds.has(action.id); return { action, hasDerivedBlockers, @@ -218,13 +218,12 @@ function validateMigrationInput(input: ActionsV2MigrationInput): string[] { return [...new Set(errors)]; } -function hasUnresolvedDerivedBlockers( - actionId: string, +function collectUnresolvedDerivedActionIds( actions: Action[], edges: ActionEdge[], checkpoints: Checkpoint[], sentinels: Sentinel[], -): boolean { +): Set { const actionMap = new Map(actions.map((action) => [action.id, action])); const checkpointMap = new Map( checkpoints.map((checkpoint) => [checkpoint.id, checkpoint]), @@ -232,22 +231,25 @@ function hasUnresolvedDerivedBlockers( const sentinelMap = new Map( sentinels.map((sentinel) => [sentinel.id, sentinel]), ); - return edges.some((edge) => { - if (edge.sourceActionId !== actionId) return false; + const unresolved = new Set(); + for (const edge of edges) { if (edge.type === "requires") { const dependency = actionMap.get(edge.targetActionId); - return ( - (dependency?.lifecycle ?? dependency?.status) !== "done" - ); + if ((dependency?.lifecycle ?? dependency?.status) !== "done") { + unresolved.add(edge.sourceActionId); + } + continue; } if (edge.type === "gated_by") { - return ( + if ( checkpointMap.get(edge.targetActionId)?.status !== "passed" && sentinelMap.get(edge.targetActionId)?.status !== "triggered" - ); + ) { + unresolved.add(edge.sourceActionId); + } } - return false; - }); + } + return unresolved; } function normalizeLimit(value?: number): number { diff --git a/src/functions/actions.ts b/src/functions/actions.ts index f580b3e26f..28a7965a8f 100644 --- a/src/functions/actions.ts +++ b/src/functions/actions.ts @@ -22,6 +22,7 @@ import { } from "./action-model.js"; import { ActionNormalizationError, + ActionRevisionConflictError, persistActionEdgeUnlocked, persistActionUnlocked, readActionStoreSnapshot, @@ -746,6 +747,15 @@ function isValidEdgeType(value: string): value is ActionEdge["type"] { } function actionStoreError(error: unknown) { + if (error instanceof ActionRevisionConflictError) { + return { + success: false, + error: "action_revision_conflict", + actionId: error.actionId, + fields: error.fields, + message: error.message, + }; + } if (error instanceof ActionNormalizationError) { return { success: false, diff --git a/src/functions/diagnostics.ts b/src/functions/diagnostics.ts index c7696e66a3..18526a8632 100644 --- a/src/functions/diagnostics.ts +++ b/src/functions/diagnostics.ts @@ -845,6 +845,18 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { reason: "release-expired-lease", newStatus: "pending", }); + } else if ( + action && + action.status !== "done" && + action.status !== "cancelled" + ) { + const before = structuredClone(action); + action.updatedAt = new Date().toISOString(); + await persistAction(kv, action, { + actor: "heal", + before, + reason: "expired lease; readiness revision refreshed", + }); } return true; }, diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 515d499ef9..aafb04c65d 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -296,14 +296,6 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { return { success: false, error: `Duplicate action: ${action.id}` }; } actionIds.add(action.id); - const normalized = normalizeActionV2(action); - if (normalized.conflicts.length > 0) { - return { - success: false, - error: `Invalid action ${action.id}: ${normalized.conflicts.join(", ")}`, - }; - } - normalizedImportedActions.push(normalized.action); } const importedActionEdges = importData.actionEdges ?? []; if (!Array.isArray(importedActionEdges)) { @@ -325,6 +317,25 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { } edgeIds.add(edge.id); } + const importedActionsWithDerivedBlockers = + collectImportedActionsWithDerivedBlockers( + importedActions, + importedActionEdges, + Array.isArray(importData.checkpoints) ? importData.checkpoints : [], + Array.isArray(importData.sentinels) ? importData.sentinels : [], + ); + for (const action of importedActions) { + const normalized = normalizeActionV2(action, { + hasDerivedBlockers: importedActionsWithDerivedBlockers.has(action.id), + }); + if (normalized.conflicts.length > 0) { + return { + success: false, + error: `Invalid action ${action.id}: ${normalized.conflicts.join(", ")}`, + }; + } + normalizedImportedActions.push(normalized.action); + } const importedActionEvents = importData.actionEvents ?? []; if (!Array.isArray(importedActionEvents)) { return { success: false, error: "actionEvents must be an array" }; @@ -826,6 +837,40 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { ); } +function collectImportedActionsWithDerivedBlockers( + actions: Action[], + edges: ActionEdge[], + checkpoints: Checkpoint[], + sentinels: Sentinel[], +): Set { + const actionMap = new Map(actions.map((action) => [action.id, action])); + const checkpointMap = new Map( + checkpoints.map((checkpoint) => [checkpoint.id, checkpoint]), + ); + const sentinelMap = new Map( + sentinels.map((sentinel) => [sentinel.id, sentinel]), + ); + const unresolved = new Set(); + for (const edge of edges) { + if (edge.type === "requires") { + const dependency = actionMap.get(edge.targetActionId); + if ((dependency?.lifecycle ?? dependency?.status) !== "done") { + unresolved.add(edge.sourceActionId); + } + continue; + } + if (edge.type === "gated_by") { + if ( + checkpointMap.get(edge.targetActionId)?.status !== "passed" && + sentinelMap.get(edge.targetActionId)?.status !== "triggered" + ) { + unresolved.add(edge.sourceActionId); + } + } + } + return unresolved; +} + function isValidActionEventImage(event: ActionEvent): boolean { const isDeletion = event.type === "deleted" || event.type === "edge_deleted"; if (isDeletion ? !event.before || event.after : !event.after) return false; diff --git a/src/functions/frontier.ts b/src/functions/frontier.ts index 3562210070..1b39bf7e82 100644 --- a/src/functions/frontier.ts +++ b/src/functions/frontier.ts @@ -8,7 +8,11 @@ import type { Lease, Sentinel, } from "../types.js"; -import { classifyAction, computeActionScore } from "./action-model.js"; +import { + buildActionViewIndex, + classifyAction, + computeActionScore, +} from "./action-model.js"; import { matchesActionProject } from "./action-query.js"; import { readActionStoreSnapshot } from "./action-store.js"; @@ -36,6 +40,16 @@ export function registerFrontierFunction(sdk: ISdk, kv: StateKV): void { kv.list(KV.sentinels).catch(() => []), ]); const now = Date.now(); + const viewContext = { + actions: snapshot.actions, + edges: snapshot.edges, + checkpoints, + sentinels, + leases, + agentId: data.includeLeasedByOthers ? undefined : data.agentId, + now, + }; + const index = buildActionViewIndex(viewContext); const frontier = snapshot.actions .filter( (action) => @@ -43,19 +57,18 @@ export function registerFrontierFunction(sdk: ISdk, kv: StateKV): void { ) .map((action) => classifyAction(action, { - actions: snapshot.actions, - edges: snapshot.edges, - checkpoints, - sentinels, - leases, - agentId: data.includeLeasedByOthers ? undefined : data.agentId, - now, + ...viewContext, + index, }), ) .filter((item) => item.view === "actionable") .map((item) => ({ ...item, - score: computeActionScore(item.action, snapshot.edges, now), + score: computeActionScore( + item.action, + index.edgesByActionId.get(item.action.id) ?? [], + now, + ), })) .sort( (left, right) => diff --git a/src/functions/leases.ts b/src/functions/leases.ts index b946486137..de1ca03049 100644 --- a/src/functions/leases.ts +++ b/src/functions/leases.ts @@ -4,7 +4,11 @@ import { KV, generateId } from "../state/schema.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import type { Action, Checkpoint, Lease, Sentinel } from "../types.js"; import { recordAudit } from "./audit.js"; -import { persistAction, readActionStoreSnapshot } from "./action-store.js"; +import { + ActionRevisionConflictError, + persistAction, + readActionStoreSnapshot, +} from "./action-store.js"; import { propagateActionCompletion } from "./actions.js"; import { classifyAction } from "./action-model.js"; @@ -87,21 +91,33 @@ export function registerLeasesFunction(sdk: ISdk, kv: StateKV): void { }; await kv.set(KV.leases, lease.id, lease); - await recordAudit(kv, "lease_acquire", "mem::lease-acquire", [lease.id], { - actionId: data.actionId, - agentId: data.agentId, - expiresAt: lease.expiresAt, - }); - const before = { ...action }; action.status = "active"; action.lifecycle = "active"; action.assignedTo = data.agentId; action.updatedAt = now.toISOString(); - const persisted = await persistAction(kv, action, { - actor: data.agentId, - before, - reason: "lease acquired", + let persisted: Awaited>; + try { + persisted = await persistAction(kv, action, { + actor: data.agentId, + before, + reason: "lease acquired", + }); + } catch (error) { + await kv.delete(KV.leases, lease.id).catch(() => {}); + if (error instanceof ActionRevisionConflictError) { + return { + success: false, + error: "action_revision_conflict", + fields: error.fields, + }; + } + throw error; + } + await recordAudit(kv, "lease_acquire", "mem::lease-acquire", [lease.id], { + actionId: data.actionId, + agentId: data.agentId, + expiresAt: lease.expiresAt, }); await recordAudit(kv, "action_update", "mem::lease-acquire", [action.id], { before, @@ -167,6 +183,18 @@ export function registerLeasesFunction(sdk: ISdk, kv: StateKV): void { if (data.result) { await propagateActionCompletion(kv, action.id, data.agentId); } + } else if ( + action && + action.status !== "done" && + action.status !== "cancelled" + ) { + const before = structuredClone(action); + action.updatedAt = new Date().toISOString(); + await persistAction(kv, action, { + actor: data.agentId, + before, + reason: "lease released; readiness revision refreshed", + }); } return { success: true, released: true }; @@ -276,6 +304,19 @@ export function registerLeasesFunction(sdk: ISdk, kv: StateKV): void { newStatus: action.status, actionId: action.id, }); + } else if ( + action && + !otherActiveLease && + action.status !== "done" && + action.status !== "cancelled" + ) { + const before = structuredClone(action); + action.updatedAt = new Date().toISOString(); + await persistAction(kv, action, { + actor: "lease-cleanup", + before, + reason: "expired lease; readiness revision refreshed", + }); } return true; }, diff --git a/test/actions-v2-migration.test.ts b/test/actions-v2-migration.test.ts index f8e2dd1505..061100e1a9 100644 --- a/test/actions-v2-migration.test.ts +++ b/test/actions-v2-migration.test.ts @@ -173,6 +173,83 @@ describe("Actions v2 migration", () => { }); }); + it("keeps the legacy queue scope authoritative when multiple project tags are context", async () => { + const kv = mockKV(); + const action = legacyAction("act_initiative", { + project: "initiative-agent-tooling", + tags: [ + "projectId:repo-brain", + "projectId:workstation-shell", + "agent:codex", + ], + }); + await kv.set("mem:actions", action.id, action); + + const result = await migrateActionsV2(kv as never, { dryRun: false }); + const migrated = await kv.get("mem:actions", action.id); + + expect(result).toMatchObject({ + success: true, + conflictCount: 0, + changed: 1, + }); + expect(result.preview[0].warnings).toContain( + "project_tags_retained_as_context", + ); + expect(migrated).toMatchObject({ + project: "initiative-agent-tooling", + projectId: "initiative-agent-tooling", + }); + expect(migrated?.tags).toEqual(action.tags); + }); + + it("warns about an invalid contextual project tag when a valid queue scope exists", async () => { + const kv = mockKV(); + const action = legacyAction("act_selftest", { + project: "agentmemory-todo-selftest", + tags: ["projectId:/tmp"], + }); + await kv.set("mem:actions", action.id, action); + + const result = await migrateActionsV2(kv as never, { dryRun: true }); + + expect(result).toMatchObject({ + success: true, + conflictCount: 0, + changed: 1, + }); + expect(result.preview[0].warnings).toEqual( + expect.arrayContaining([ + "project_tags_retained_as_context", + "invalid_project_tag_ignored", + ]), + ); + expect(result.preview[0].projectId).toBe("agentmemory-todo-selftest"); + }); + + it("still rejects ambiguous project tags when no queue scope exists", async () => { + const kv = mockKV(); + const action = legacyAction("act_ambiguous", { + tags: ["projectId:alpha", "projectId:beta"], + }); + await kv.set("mem:actions", action.id, action); + + const result = await migrateActionsV2(kv as never, { dryRun: false }); + + expect(result).toMatchObject({ + success: false, + error: "migration_conflict", + conflictCount: 1, + unresolvedActionIds: [action.id], + revisionBefore: 0, + revisionAfter: 0, + }); + expect(result.preview[0].conflicts).toContain( + "conflicting_project_tags", + ); + expect(await kv.get("mem:actions", action.id)).toEqual(action); + }); + it("stops before any mutation when explicit project identities conflict", async () => { const kv = mockKV(); const legacyPath = "/legacy/repo"; diff --git a/test/actions-v2.test.ts b/test/actions-v2.test.ts index d3dd44574b..7666df09b2 100644 --- a/test/actions-v2.test.ts +++ b/test/actions-v2.test.ts @@ -7,7 +7,10 @@ vi.mock("../src/logger.js", () => ({ import { registerActionsFunction } from "../src/functions/actions.js"; import { registerSentinelsFunction } from "../src/functions/sentinels.js"; import { registerCheckpointsFunction } from "../src/functions/checkpoints.js"; -import { persistAction } from "../src/functions/action-store.js"; +import { + ActionRevisionConflictError, + persistAction, +} from "../src/functions/action-store.js"; import { registerLeasesFunction } from "../src/functions/leases.js"; import type { Action, @@ -15,6 +18,7 @@ import type { ActionEvent, ActionViewItem, Checkpoint, + Lease, Sentinel, } from "../src/types.js"; import { mockKV, mockSdk } from "./helpers/mocks.js"; @@ -182,6 +186,74 @@ describe("Actions v2", () => { expect(await kv.list("mem:leases")).toEqual([]); }); + it("invalidates readiness revisions when a legacy lease is released without an assignment projection", async () => { + const created = (await sdk.trigger("mem::action-create", { + title: "Legacy leased action", + })) as { action: Action }; + const lease: Lease = { + id: "lse_legacy", + actionId: created.action.id, + agentId: "worker-a", + acquiredAt: "2026-07-17T10:00:00.000Z", + expiresAt: "2999-07-17T11:00:00.000Z", + status: "active", + }; + await kv.set("mem:leases", lease.id, lease); + const before = (await sdk.trigger("mem::action-list", { + agentId: "worker-b", + })) as { revision: number }; + + const released = (await sdk.trigger("mem::lease-release", { + actionId: created.action.id, + agentId: "worker-a", + })) as { success: boolean }; + const stale = (await sdk.trigger("mem::action-list", { + agentId: "worker-b", + revision: before.revision, + })) as { success: boolean; error: string }; + + expect(released.success).toBe(true); + expect(stale).toMatchObject({ + success: false, + error: "revision_conflict", + }); + }); + + it("rolls back a lease when the action completes during acquisition", async () => { + const created = (await sdk.trigger("mem::action-create", { + title: "Racing action", + })) as { action: Action }; + const originalSet = kv.set; + let injectedCompletion = false; + kv.set = async (scope: string, key: string, value: T): Promise => { + const stored = await originalSet(scope, key, value); + if (scope === "mem:leases" && !injectedCompletion) { + injectedCompletion = true; + await sdk.trigger("mem::action-update", { + actionId: created.action.id, + lifecycle: "done", + actor: "concurrent-worker", + }); + } + return stored; + }; + + const result = (await sdk.trigger("mem::lease-acquire", { + actionId: created.action.id, + agentId: "worker-a", + })) as { success: boolean; error: string }; + + expect(result).toMatchObject({ + success: false, + error: "action_revision_conflict", + }); + expect(await kv.list("mem:leases")).toEqual([]); + expect(await kv.get("mem:actions", created.action.id)).toMatchObject({ + lifecycle: "done", + status: "done", + }); + }); + it("derives sentinel gates as blocked until the sentinel triggers", async () => { const created = (await sdk.trigger("mem::action-create", { title: "Wait for sentinel", @@ -429,6 +501,70 @@ describe("Actions v2", () => { }); }); + it("rebases a stale secondary mutation when concurrent fields do not overlap", async () => { + const created = (await sdk.trigger("mem::action-create", { + title: "Original title", + })) as { action: Action }; + const stale = structuredClone(created.action); + const concurrent = (await sdk.trigger("mem::action-update", { + actionId: created.action.id, + description: "Concurrent description", + actor: "primary-writer", + })) as { action: Action }; + + const secondaryInput = { + ...stale, + title: "Secondary title", + updatedAt: "2026-07-17T12:00:00.000Z", + }; + const persisted = await persistAction(kv as never, secondaryInput, { + actor: "secondary-writer", + before: stale, + }); + + expect(persisted.action).toMatchObject({ + title: "Secondary title", + description: "Concurrent description", + }); + expect(persisted.action.revision).toBeGreaterThan( + concurrent.action.revision ?? 0, + ); + }); + + it("rejects a stale secondary mutation when the same field changed concurrently", async () => { + const created = (await sdk.trigger("mem::action-create", { + title: "Original title", + })) as { action: Action }; + const stale = structuredClone(created.action); + const concurrent = (await sdk.trigger("mem::action-update", { + actionId: created.action.id, + title: "Primary title", + actor: "primary-writer", + })) as { action: Action }; + + const secondaryInput = { + ...stale, + title: "Secondary title", + updatedAt: "2026-07-17T12:00:00.000Z", + }; + + await expect( + persistAction(kv as never, secondaryInput, { + actor: "secondary-writer", + before: stale, + }), + ).rejects.toEqual( + expect.objectContaining({ + name: "ActionRevisionConflictError", + actionId: created.action.id, + fields: ["title"], + }), + ); + expect(await kv.get("mem:actions", created.action.id)).toEqual( + concurrent.action, + ); + }); + it("does not turn a transient v2 assignee into the durable owner", async () => { const created = (await sdk.trigger("mem::action-create", { title: "Unowned task", diff --git a/test/export-import.test.ts b/test/export-import.test.ts index 5bebf0c6ae..c9b15b86af 100644 --- a/test/export-import.test.ts +++ b/test/export-import.test.ts @@ -12,6 +12,7 @@ import type { SessionSummary, ExportData, Action, + ActionEdge, ActionCollectionState, ActionEvent, } from "../src/types.js"; @@ -376,6 +377,61 @@ describe("Export/Import Functions", () => { expect(stored?.tags).toEqual(["agent:kimi", "worktree:legacy"]); }); + it("does not turn a legacy dependency block into a permanent manual block on import", async () => { + const createdAt = "2026-07-01T00:00:00.000Z"; + const dependency = { + id: "act_dependency", + title: "Dependency", + description: "", + status: "pending", + priority: 5, + createdAt, + updatedAt: createdAt, + createdBy: "unknown", + project: "agentmemory", + tags: [], + sourceObservationIds: [], + sourceMemoryIds: [], + } satisfies Action; + const dependent = { + ...dependency, + id: "act_dependent", + title: "Dependent", + status: "blocked", + } satisfies Action; + const edge = { + id: "ae_dependency", + type: "requires", + sourceActionId: dependent.id, + targetActionId: dependency.id, + createdAt, + } satisfies ActionEdge; + const exportData: ExportData = { + version: "0.9.27", + exportedAt: new Date().toISOString(), + sessions: [], + observations: {}, + memories: [], + summaries: [], + actions: [dependency, dependent], + actionEdges: [edge], + }; + + const result = (await sdk.trigger("mem::import", { + exportData, + strategy: "replace", + })) as { success: boolean }; + const stored = await kv.get("mem:actions", dependent.id); + + expect(result.success).toBe(true); + expect(stored).toMatchObject({ + schemaVersion: 2, + lifecycle: "pending", + status: "blocked", + }); + expect(stored?.blockedReason).toBeUndefined(); + }); + it("rejects invalid action snapshot counts before replace mutation", async () => { const preserved = { id: "act_preserved", From 917ce1e2db69c0b673b0c3302fca1ac2f4891f04 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Fri, 17 Jul 2026 11:20:34 -0400 Subject: [PATCH 21/43] fix(actions): compare normalized rows semantically --- src/functions/action-model.ts | 17 ++++++++++++- test/actions-v2-migration.test.ts | 41 +++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+), 1 deletion(-) diff --git a/src/functions/action-model.ts b/src/functions/action-model.ts index b7a6b954a8..8f410a7d6b 100644 --- a/src/functions/action-model.ts +++ b/src/functions/action-model.ts @@ -359,12 +359,27 @@ export function normalizeActionV2( return { action, - changed: JSON.stringify(action) !== JSON.stringify(input), + changed: canonicalJson(action) !== canonicalJson(input), warnings: [...new Set(warnings)], conflicts: [...new Set(conflicts)], }; } +function canonicalJson(value: unknown): string { + return JSON.stringify(value, (_key, nested) => { + if (!nested || typeof nested !== "object" || Array.isArray(nested)) { + return nested; + } + return Object.fromEntries( + Object.entries(nested) + .filter(([, item]) => item !== undefined) + .sort(([left], [right]) => + left < right ? -1 : left > right ? 1 : 0, + ), + ); + }); +} + export function classifyAction( input: Action, context: ActionViewContext, diff --git a/test/actions-v2-migration.test.ts b/test/actions-v2-migration.test.ts index 061100e1a9..22cceb2614 100644 --- a/test/actions-v2-migration.test.ts +++ b/test/actions-v2-migration.test.ts @@ -149,6 +149,47 @@ describe("Actions v2 migration", () => { expect(await kv.list("mem:audit")).toHaveLength(1); }); + it("does not rewrite an approval when only its JSON key order changed", async () => { + const kv = mockKV(); + const action = legacyAction("act_approval_order", { + project: "workstation", + tags: ["requires-confirmation"], + }); + await kv.set("mem:actions", action.id, action); + + const first = await migrateActionsV2(kv as never, { + dryRun: false, + actor: "migration-test", + }); + const migrated = await kv.get("mem:actions", action.id); + expect(first).toMatchObject({ success: true, changed: 1, revisionAfter: 1 }); + expect(migrated?.approval).toMatchObject({ + state: "pending", + requestedAt: action.createdAt, + }); + + const reordered = JSON.parse(JSON.stringify(migrated)) as Action; + reordered.approval = { + requestedAt: migrated?.approval?.requestedAt, + state: "pending", + }; + await kv.set("mem:actions", action.id, reordered); + + const retry = await migrateActionsV2(kv as never, { + dryRun: false, + actor: "migration-test", + }); + + expect(retry).toMatchObject({ + success: true, + changed: 0, + skipped: 1, + revisionBefore: 1, + revisionAfter: 1, + }); + expect(await kv.list("mem:action-events")).toHaveLength(1); + }); + it("infers canonical IDs from Unix and Windows repository paths", async () => { const kv = mockKV(); await kv.set( From 5f81d4e2b0bb5f07154c2ede20baae010bc143b6 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Fri, 17 Jul 2026 17:53:17 -0400 Subject: [PATCH 22/43] fix(actions): coerce undefined state::get results to null at the StateKV boundary The iii-engine resolves state::get with undefined for missing keys, not null. rebaseActionMutation's create path compares expectedBefore === null against current with strict equality, so every mem::action-create threw action_revision_conflict while updates kept working. The in-memory test mock coerced with ?? null and hid the real engine semantics; add an engine-faithful regression test (test/state-kv.test.ts). --- src/state/kv.ts | 7 +++- test/state-kv.test.ts | 82 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 test/state-kv.test.ts diff --git a/src/state/kv.ts b/src/state/kv.ts index 0c0e6ccc12..f455bbaa87 100644 --- a/src/state/kv.ts +++ b/src/state/kv.ts @@ -4,10 +4,15 @@ export class StateKV { constructor(private sdk: ISdk) {} async get(scope: string, key: string): Promise { - return this.sdk.trigger<{ scope: string; key: string }, T | null>({ + // The iii-engine resolves `state::get` with `undefined` (an absent + // result field) for missing keys, not `null`. Normalize here so the + // declared `T | null` contract holds — callers compare against `null` + // with strict equality (e.g. rebaseActionMutation's create path). + const value = await this.sdk.trigger<{ scope: string; key: string }, T | null>({ function_id: 'state::get', payload: { scope, key }, }) + return value ?? null } async set(scope: string, key: string, value: T): Promise { diff --git a/test/state-kv.test.ts b/test/state-kv.test.ts new file mode 100644 index 0000000000..95a6144141 --- /dev/null +++ b/test/state-kv.test.ts @@ -0,0 +1,82 @@ +import { describe, expect, it, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { registerActionsFunction } from "../src/functions/actions.js"; +import { StateKV } from "../src/state/kv.js"; +import type { Action } from "../src/types.js"; +import { mockSdk } from "./helpers/mocks.js"; + +interface RawTriggerInput { + function_id: string; + payload: { scope: string; key?: string; value?: unknown }; +} + +/** + * Engine-faithful KV backing: the real iii-engine resolves `state::get` + * with `undefined` (not `null`) when a key or scope is missing. The + * in-memory test mock historically coerced to `null`, which hid the + * production regression where `mem::action-create` compared + * `expectedBefore === null` against `current === undefined` and threw + * `action_revision_conflict` for every create. + */ +function engineLikeTrigger() { + const store = new Map>(); + return async ({ function_id, payload }: RawTriggerInput) => { + if (function_id === "state::get") { + return store.get(payload.scope)?.get(payload.key as string); + } + if (function_id === "state::set") { + if (!store.has(payload.scope)) store.set(payload.scope, new Map()); + store.get(payload.scope)!.set(payload.key as string, payload.value); + return payload.value; + } + if (function_id === "state::delete") { + store.get(payload.scope)?.delete(payload.key as string); + return undefined; + } + if (function_id === "state::list") { + const entries = store.get(payload.scope); + return entries ? Array.from(entries.values()) : []; + } + throw new Error(`No function: ${function_id}`); + }; +} + +describe("StateKV engine boundary", () => { + it("coerces an undefined engine result to null for missing keys", async () => { + const kv = new StateKV({ trigger: engineLikeTrigger() } as never); + await expect(kv.get("mem:actions", "act_missing")).resolves.toBeNull(); + await expect(kv.get("mem:no-such-scope", "x")).resolves.toBeNull(); + }); + + it("returns the stored value for existing keys", async () => { + const kv = new StateKV({ trigger: engineLikeTrigger() } as never); + await kv.set("mem:actions", "act_present", { id: "act_present" }); + await expect(kv.get("mem:actions", "act_present")).resolves.toEqual({ + id: "act_present", + }); + }); + + it("creates an action when the engine reports missing keys as undefined", async () => { + const sdk = mockSdk(); + const kv = new StateKV({ trigger: engineLikeTrigger() } as never); + registerActionsFunction(sdk as never, kv as never); + + const result = (await sdk.trigger("mem::action-create", { + title: "Regression: create must tolerate undefined state::get", + actor: "kimi", + })) as { success: boolean; error?: string; action?: Action }; + + expect(result.error).toBeUndefined(); + expect(result.success).toBe(true); + expect(result.action?.title).toBe( + "Regression: create must tolerate undefined state::get", + ); + expect(await kv.get("mem:action-state", "current")).toMatchObject({ + revision: 1, + }); + }); +}); From b56bf7a1f6d23fd6ded7b05ba71d42bbeb4f2c1c Mon Sep 17 00:00:00 2001 From: wrightpt Date: Fri, 17 Jul 2026 21:49:11 -0400 Subject: [PATCH 23/43] docs: record iii-engine state semantics and workstation deploy path state::get resolves undefined for missing keys; StateKV.get is the normalizing boundary (2026-07-17 action_revision_conflict outage). Also documents the symlinked global install so deploys are build + service restart. --- AGENTS.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 216ba2e3b5..afd1bc1fdc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,8 +9,17 @@ agentmemory is a persistent memory system for AI coding agents, built on iii-eng - **Build**: TypeScript → ESM via tsdown, output to `dist/` - **Test**: vitest (`npm test` excludes integration tests) -## Consistency Rules +## iii-engine State Semantics + +- `state::get` resolves **`undefined`** (absent result field) for missing keys or scopes — not `null`. `StateKV.get` normalizes this to `null` (`value ?? null`), so `T | null` is the guaranteed contract everywhere downstream; never bypass `StateKV` to call `state::get` directly, and never compare store results with strict `=== null` upstream of it. (2026-07-17: this gap made every `mem::action-create` throw `action_revision_conflict` while updates kept working.) +- `state::list` returns `[]` for missing scopes; `state::update` reports `old_value: null`; `state::delete` returns `{}`. Only `get` has the undefined gap (probed live 2026-07-17). +- In-memory test mocks (`test/helpers/mocks.ts`) return `null` because that is the `StateKV` contract. Engine-faithful boundary coverage (undefined-returning trigger) lives in `test/state-kv.test.ts` — add new `state::*` semantics probes there. + +## Workstation Deployment +On the workstation the global package (`npm ls -g @agentmemory/agentmemory`) is a **symlink to this repo's checkout**, so a deploy is: `npm run build`, then `systemctl --user restart agentmemory.service`. The health sentinel (`agentmemory_health_sentinel.sh`, 15-min timer) verifies the running buildId/source revision against `agent-workspace-config/agentmemory-lock.json` and canaries the actions write path every run. + +## Consistency Rules **When adding or removing MCP tools, you MUST update ALL of the following:** 1. `src/mcp/tools-registry.ts` — tool definition + `getAllTools()` array 2. `src/mcp/server.ts` — handler case in the `mcp::tools::call` switch From 2fbf40b10099821b119631af977fc2d3c92f6187 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Fri, 17 Jul 2026 23:50:20 -0400 Subject: [PATCH 24/43] feat(actions): add mem::action-gc terminal-action pruning Bounds action-store growth (the 15-min write-path canary alone adds ~96 cancelled actions/day). mem::action-gc collects done/cancelled actions older than maxAgeDays (default 30) that appear in no edge, dry-run by default, revalidating each candidate before deletion and emitting one batched action_delete audit row. Exposed as POST /agentmemory/actions/gc (REST 131). --- AGENTS.md | 2 +- README.md | 2 +- src/functions/actions.ts | 74 ++++++++++++++++++++++++ src/index.ts | 2 +- src/triggers/api.ts | 24 ++++++++ src/types.ts | 1 + test/actions-gc.test.ts | 119 +++++++++++++++++++++++++++++++++++++++ 7 files changed, 221 insertions(+), 3 deletions(-) create mode 100644 test/actions-gc.test.ts diff --git a/AGENTS.md b/AGENTS.md index afd1bc1fdc..96a14f6558 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -135,7 +135,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). ## Current Stats (v0.9.27) - 54 MCP tools (`all` by default; 7 safe essentials in `core`; curated coordination in `workstation`) -- 130 REST endpoints +- 131 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 15 skills - 50+ iii functions diff --git a/README.md b/README.md index 91b4235df8..67567de1a6 100644 --- a/README.md +++ b/README.md @@ -1532,7 +1532,7 @@ Create `~/.agentmemory/.env`:

API

-130 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers. +131 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
Key endpoints diff --git a/src/functions/actions.ts b/src/functions/actions.ts index 28a7965a8f..c97fc16a5f 100644 --- a/src/functions/actions.ts +++ b/src/functions/actions.ts @@ -23,6 +23,7 @@ import { import { ActionNormalizationError, ActionRevisionConflictError, + deleteAction, persistActionEdgeUnlocked, persistActionUnlocked, readActionStoreSnapshot, @@ -434,6 +435,79 @@ export function registerActionsFunction(sdk: ISdk, kv: StateKV): void { revision: snapshot.state.revision, }; }); + + sdk.registerFunction( + "mem::action-gc", + async (data: { + maxAgeDays?: number; + dryRun?: boolean; + limit?: number; + actor?: string; + }) => { + const maxAgeDays = data.maxAgeDays ?? 30; + const dryRun = data.dryRun ?? true; + const limit = data.limit ?? 500; + if (!Number.isFinite(maxAgeDays) || maxAgeDays < 0) { + return { success: false, error: "maxAgeDays must be a non-negative number" }; + } + if (typeof dryRun !== "boolean") { + return { success: false, error: "dryRun must be a boolean" }; + } + if (!Number.isInteger(limit) || limit < 1 || limit > 5000) { + return { success: false, error: "limit must be an integer between 1 and 5000" }; + } + try { + const cutoff = Date.now() - maxAgeDays * 86_400_000; + const snapshot = await readActionStoreSnapshot(kv); + const edgeEndpoints = new Set( + snapshot.edges.flatMap((edge) => [ + edge.sourceActionId, + edge.targetActionId, + ]), + ); + const isCollectable = (action: Action): boolean => + (action.lifecycle === "done" || action.lifecycle === "cancelled") && + Date.parse(action.updatedAt) < cutoff && + !edgeEndpoints.has(action.id); + const candidates = snapshot.actions + .filter(isCollectable) + .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt)) + .slice(0, limit); + const actor = data.actor || "action-gc"; + const deleted: string[] = []; + if (!dryRun) { + for (const candidate of candidates) { + const current = await kv.get(KV.actions, candidate.id); + if (!current || !isCollectable(current)) continue; + const result = await deleteAction(kv, candidate.id, { + actor, + reason: `terminal action older than ${maxAgeDays}d`, + }); + if (result.deleted) deleted.push(candidate.id); + } + if (deleted.length > 0) { + await recordAudit( + kv, + "action_delete", + "mem::action-gc", + deleted, + { actor, maxAgeDays, dryRun: false, deleted: deleted.length }, + ); + } + } + return { + success: true, + dryRun, + maxAgeDays, + cutoff: new Date(cutoff).toISOString(), + candidates: candidates.map((action) => action.id), + deleted, + }; + } catch (error) { + return actionStoreError(error); + } + }, + ); } async function propagateCompletionUnlocked( diff --git a/src/index.ts b/src/index.ts index f0bcf9bf1f..d082430d86 100644 --- a/src/index.ts +++ b/src/index.ts @@ -521,7 +521,7 @@ async function main() { `Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`, ); bootLog( - `REST API: 130 endpoints at http://localhost:${config.restPort}/agentmemory/*`, + `REST API: 131 endpoints at http://localhost:${config.restPort}/agentmemory/*`, ); bootLog( `MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`, diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 08866a7538..9a78f35a36 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -2617,6 +2617,30 @@ export function registerApiTriggers( config: { api_path: "/agentmemory/actions/get", http_method: "GET" }, }); + sdk.registerFunction("api::action-gc", + async (req: ApiRequest>): Promise => { + const authErr = checkAuth(req, secret); + if (authErr) return authErr; + const body = (req.body ?? {}) as Record; + const result = await sdk.trigger({ + function_id: "mem::action-gc", + payload: pickDefinedFields(body, [ + "maxAgeDays", + "dryRun", + "limit", + "actor", + ]), + }); + const success = (result as { success?: boolean }).success !== false; + return { status_code: success ? 200 : 400, body: result }; + }, + ); + sdk.registerTrigger({ + type: "http", + function_id: "api::action-gc", + config: { api_path: "/agentmemory/actions/gc", http_method: "POST" }, + }); + sdk.registerFunction("api::action-edge", async (req: ApiRequest>): Promise => { const authErr = checkAuth(req, secret); diff --git a/src/types.ts b/src/types.ts index ee7e008b71..b168dec084 100644 --- a/src/types.ts +++ b/src/types.ts @@ -596,6 +596,7 @@ export interface AuditEntry { | "export" | "action_create" | "action_update" + | "action_delete" | "lease_acquire" | "lease_release" | "routine_run" diff --git a/test/actions-gc.test.ts b/test/actions-gc.test.ts new file mode 100644 index 0000000000..8fe0b16ba4 --- /dev/null +++ b/test/actions-gc.test.ts @@ -0,0 +1,119 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { registerActionsFunction } from "../src/functions/actions.js"; +import type { Action, ActionEdge, ActionEvent, AuditEntry } from "../src/types.js"; +import { mockKV, mockSdk } from "./helpers/mocks.js"; + +const DAY_MS = 86_400_000; + +function terminalAction(id: string, ageDays: number, lifecycle: Action["lifecycle"]): Action { + return { + id, + title: id, + status: lifecycle === "done" ? "done" : lifecycle === "cancelled" ? "cancelled" : lifecycle === "active" ? "active" : "pending", + lifecycle, + priority: 5, + schemaVersion: 2, + createdAt: new Date(Date.now() - (ageDays + 1) * DAY_MS).toISOString(), + updatedAt: new Date(Date.now() - ageDays * DAY_MS).toISOString(), + } as Action; +} + +describe("mem::action-gc", () => { + let sdk: ReturnType; + let kv: ReturnType; + + beforeEach(async () => { + sdk = mockSdk(); + kv = mockKV(); + registerActionsFunction(sdk as never, kv as never); + await kv.set("mem:actions", "old-done", terminalAction("old-done", 40, "done")); + await kv.set("mem:actions", "old-cancelled", terminalAction("old-cancelled", 40, "cancelled")); + await kv.set("mem:actions", "recent-done", terminalAction("recent-done", 1, "done")); + await kv.set("mem:actions", "old-pending", terminalAction("old-pending", 40, "pending")); + await kv.set("mem:actions", "old-active", terminalAction("old-active", 40, "active")); + await kv.set("mem:actions", "old-done-linked", terminalAction("old-done-linked", 40, "done")); + const edge: ActionEdge = { + id: "ae_1", + type: "requires", + sourceActionId: "old-pending", + targetActionId: "old-done-linked", + createdAt: new Date().toISOString(), + }; + await kv.set("mem:action-edges", edge.id, edge); + }); + + it("defaults to dryRun and only reports candidates", async () => { + const result = (await sdk.trigger("mem::action-gc", {})) as { + success: boolean; + dryRun: boolean; + candidates: string[]; + deleted: string[]; + }; + + expect(result.success).toBe(true); + expect(result.dryRun).toBe(true); + expect(result.candidates.sort()).toEqual(["old-cancelled", "old-done"]); + expect(result.deleted).toEqual([]); + expect(await kv.list("mem:actions")).toHaveLength(6); + expect(await kv.list("mem:action-events")).toHaveLength(0); + expect(await kv.list("mem:audit")).toHaveLength(0); + }); + + it("deletes only old terminal, edge-free actions and audits one batched row", async () => { + const result = (await sdk.trigger("mem::action-gc", { + dryRun: false, + actor: "test-gc", + })) as { success: boolean; deleted: string[] }; + + expect(result.success).toBe(true); + expect(result.deleted.sort()).toEqual(["old-cancelled", "old-done"]); + expect(await kv.get("mem:actions", "old-done")).toBeNull(); + expect(await kv.get("mem:actions", "old-cancelled")).toBeNull(); + for (const kept of ["recent-done", "old-pending", "old-active", "old-done-linked"]) { + expect(await kv.get("mem:actions", kept)).not.toBeNull(); + } + + const events = await kv.list("mem:action-events"); + expect(events).toHaveLength(2); + expect(events.every((event) => event.type === "deleted")).toBe(true); + expect(events.every((event) => event.actor === "test-gc")).toBe(true); + + const audit = await kv.list("mem:audit"); + expect(audit).toHaveLength(1); + expect(audit[0]).toMatchObject({ + operation: "action_delete", + functionId: "mem::action-gc", + }); + expect(audit[0].targetIds.sort()).toEqual(["old-cancelled", "old-done"]); + }); + + it("honors maxAgeDays and limit", async () => { + const none = (await sdk.trigger("mem::action-gc", { + maxAgeDays: 60, + })) as { candidates: string[] }; + expect(none.candidates).toEqual([]); + + const one = (await sdk.trigger("mem::action-gc", { + dryRun: false, + limit: 1, + })) as { deleted: string[] }; + expect(one.deleted).toHaveLength(1); + }); + + it.each([ + [{ maxAgeDays: -1 }, "maxAgeDays must be a non-negative number"], + [{ dryRun: "yes" }, "dryRun must be a boolean"], + [{ limit: 0 }, "limit must be an integer between 1 and 5000"], + ])("rejects invalid input %o", async (input, error) => { + const result = (await sdk.trigger("mem::action-gc", input)) as { + success: boolean; + error: string; + }; + expect(result).toEqual({ success: false, error }); + }); +}); From 4fd62a0bb463807d64fd83b213c963c8a95e0b3f Mon Sep 17 00:00:00 2001 From: wrightpt Date: Mon, 27 Jul 2026 23:33:49 -0400 Subject: [PATCH 25/43] ci: retire push/PR triggers to workflow_dispatch (local-builds quota policy) --- .github/workflows/ci.yml | 34 +++++----------------------------- 1 file changed, 5 insertions(+), 29 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ed53c6da94..d2aeed2866 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,35 +1,11 @@ name: CI -# `paths-ignore` keeps doc-only / website / README / CHANGELOG churn from -# burning runner minutes. Source / config / workflow changes always run. -# `workflow_dispatch` gives a manual re-run button for flake debugging. +# Retired to workflow_dispatch-only (2026-07-28): the GitHub account has a +# 2,000-min/month Actions quota with a $0 stop-usage budget, so push/PR +# triggers were removed (fleet local-builds policy). Run `npm test` locally +# before PR (see AGENTS.md); dispatch manually from the Actions tab when a +# hosted run is genuinely needed. on: - push: - branches: [main] - paths-ignore: - - "README.md" - - "CHANGELOG.md" - - "AGENTS.md" - - "ROADMAP.md" - - "website/**" - - "docs/**" - - "assets/**" - - "deploy/**/README.md" - - "**/*.md" - - "**/*.mdx" - pull_request: - branches: [main] - paths-ignore: - - "README.md" - - "CHANGELOG.md" - - "AGENTS.md" - - "ROADMAP.md" - - "website/**" - - "docs/**" - - "assets/**" - - "deploy/**/README.md" - - "**/*.md" - - "**/*.mdx" workflow_dispatch: # Cancel in-flight PR runs when a force-push lands. Keep push runs to From f8288ce0b58e29564d3352052bf1da53127a9a1a Mon Sep 17 00:00:00 2001 From: wrightpt Date: Wed, 29 Jul 2026 16:17:52 -0400 Subject: [PATCH 26/43] feat: add curated workstation LLM tool profile --- .env.example | 2 +- README.md | 5 ++-- src/cli.ts | 12 ++++++--- src/mcp/server.ts | 1 + src/mcp/tools-registry.ts | 7 ++++++ test/mcp-llm-tools.test.ts | 39 +++++++++++++++++++++++++++++ test/mcp-surface-default.test.ts | 13 ++++++++++ test/tool-count-consistency.test.ts | 2 +- 8 files changed, 73 insertions(+), 8 deletions(-) create mode 100644 test/mcp-llm-tools.test.ts diff --git a/.env.example b/.env.example index b11ae78052..af2588b72e 100644 --- a/.env.example +++ b/.env.example @@ -120,7 +120,7 @@ # 6. CLI / runtime knobs # ----------------------------------------------------------------------------- -# AGENTMEMORY_TOOLS=all # core (7 tools, default) | all (51 tools) — surface exposed to MCP clients +# AGENTMEMORY_TOOLS=all # core | workstation | workstation-llm (curated + 4 LLM tools) | all # AGENTMEMORY_SLOTS=memory # Comma-separated plugin slot names the CLI should claim # AGENTMEMORY_DEBUG=1 # Trace MCP shim probe + standalone fallback decisions to stderr # AGENTMEMORY_FORCE_PROXY=1 # Skip the MCP shim livez probe and trust AGENTMEMORY_URL (for sandboxed MCP clients that can't reach localhost) diff --git a/README.md b/README.md index 67567de1a6..a887b720ab 100644 --- a/README.md +++ b/README.md @@ -961,7 +961,7 @@ npm install @xenova/transformers 54 tools, 6 resources, 3 prompts, and 15 skills, the most comprehensive MCP memory toolkit for any agent. -> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the running server's selected tool profile **only when it can reach an agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). `AGENTMEMORY_TOOLS=core|workstation|all` is evaluated by the running server; set it in the server service environment. If you see only 7 local-fallback tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`. +> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the running server's selected tool profile **only when it can reach an agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). `AGENTMEMORY_TOOLS=core|workstation|workstation-llm|all` is evaluated by the running server; `workstation-llm` is the curated workstation surface plus the four LLM-backed tools. Set the profile in the server service environment. If you see only 7 local-fallback tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`. ### 54 Tools @@ -1523,7 +1523,8 @@ Create `~/.agentmemory/.env`: # USER_ID= # TEAM_MODE=private -# Tool visibility: "core" (7), "workstation" (curated coordination), "all" (54), or a comma-separated allowlist +# Tool visibility: "core" (7), "workstation" (curated coordination), +# "workstation-llm" (curated + 4 LLM-backed tools), "all" (54), or a comma-separated allowlist # AGENTMEMORY_TOOLS=core # AGENTMEMORY_DISABLE_LLM_TOOLS=true # reports skipped_disabled, not failure ``` diff --git a/src/cli.ts b/src/cli.ts index bf8b6b4261..9e9d58c300 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -191,8 +191,9 @@ Options: --help, -h Show this help --verbose, -v Show engine stderr, boot log, and diagnostic info --reset Wipe ~/.agentmemory/preferences.json and re-run onboarding - --tools all|core|workstation - Tool visibility (default: all = ${ALL_TOOLS_COUNT}; core = ${CORE_TOOLS_COUNT}; workstation = curated coordination set) + --tools all|core|workstation|workstation-llm + Tool visibility (default: all = ${ALL_TOOLS_COUNT}; core = ${CORE_TOOLS_COUNT}; + workstation = curated coordination; workstation-llm = curated + 4 LLM tools) --no-engine Skip auto-starting iii-engine --port Override REST port (default: 3111). Streams (N+1), viewer (N+2), and iii engine (N+46023) auto-derive from N so a @@ -230,9 +231,12 @@ Quick start: const toolsIdx = args.indexOf("--tools"); if (toolsIdx !== -1 && args[toolsIdx + 1]) { const toolsMode = args[toolsIdx + 1]!; - if (!["all", "core", "workstation"].includes(toolsMode) && !toolsMode.includes(",")) { + if ( + !["all", "core", "workstation", "workstation-llm"].includes(toolsMode) && + !toolsMode.includes(",") + ) { p.log.warn( - `Unknown --tools value "${toolsMode}" (valid: all, core, workstation, or a comma-separated allowlist); falling back to the safe core set.`, + `Unknown --tools value "${toolsMode}" (valid: all, core, workstation, workstation-llm, or a comma-separated allowlist); falling back to the safe core set.`, ); process.env["AGENTMEMORY_TOOLS"] = "core"; } else { diff --git a/src/mcp/server.ts b/src/mcp/server.ts index 11b76b63eb..9a876a9c79 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -491,6 +491,7 @@ export function registerMcpEndpoints( try { const result = await sdk.trigger({ function_id: "mem::consolidate-pipeline", payload: { tier: args.tier as string, + force: true, } }); return { status_code: 200, diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts index 6f36c1aebb..b4b27e5e9c 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -1081,6 +1081,11 @@ export const LLM_BACKED_TOOLS = new Set([ "memory_reflect", ]); +export const WORKSTATION_LLM_TOOLS = new Set([ + ...WORKSTATION_TOOLS, + ...LLM_BACKED_TOOLS, +]); + export function getAllTools(): McpToolDef[] { return [ ...CORE_TOOLS, @@ -1104,6 +1109,8 @@ export function getVisibleTools(): McpToolDef[] { selected = all.filter((tool) => ESSENTIAL_TOOLS.has(tool.name)); } else if (mode === "workstation") { selected = all.filter((tool) => WORKSTATION_TOOLS.has(tool.name)); + } else if (mode === "workstation-llm") { + selected = all.filter((tool) => WORKSTATION_LLM_TOOLS.has(tool.name)); } else { const allow = new Set( mode diff --git a/test/mcp-llm-tools.test.ts b/test/mcp-llm-tools.test.ts new file mode 100644 index 0000000000..3d7dd75727 --- /dev/null +++ b/test/mcp-llm-tools.test.ts @@ -0,0 +1,39 @@ +import { describe, expect, it, vi } from "vitest"; + +import { registerMcpEndpoints } from "../src/mcp/server.js"; + +function mockSdk() { + const functions = new Map(); + const trigger = vi.fn(async () => ({ success: true })); + return { + registerFunction: (idOrOpts: string | { id: string }, handler: Function) => { + const id = typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id; + functions.set(id, handler); + }, + registerTrigger: () => {}, + trigger, + getFunction: (id: string) => functions.get(id), + }; +} + +describe("MCP LLM tools", () => { + it("runs explicitly requested consolidation even when scheduling is disabled", async () => { + const sdk = mockSdk(); + registerMcpEndpoints(sdk as never, {} as never); + + const callTool = sdk.getFunction("mcp::tools::call")!; + const result = await callTool({ + headers: {}, + body: { + name: "memory_consolidate", + arguments: { tier: "semantic" }, + }, + }); + + expect(result.status_code).toBe(200); + expect(sdk.trigger).toHaveBeenCalledWith({ + function_id: "mem::consolidate-pipeline", + payload: { tier: "semantic", force: true }, + }); + }); +}); diff --git a/test/mcp-surface-default.test.ts b/test/mcp-surface-default.test.ts index ebb66cc90a..49bd22706e 100644 --- a/test/mcp-surface-default.test.ts +++ b/test/mcp-surface-default.test.ts @@ -3,6 +3,8 @@ import { readFileSync } from "node:fs"; import { getAllTools, getVisibleTools, + LLM_BACKED_TOOLS, + WORKSTATION_LLM_TOOLS, WORKSTATION_TOOLS, } from "../src/mcp/tools-registry.js"; @@ -62,6 +64,17 @@ describe("MCP tool surface default (#553)", () => { expect(names.has("memory_reflect")).toBe(false); }); + it("AGENTMEMORY_TOOLS=workstation-llm adds only the four LLM-backed tools", () => { + process.env["AGENTMEMORY_TOOLS"] = "workstation-llm"; + const names = new Set(getVisibleTools().map((tool) => tool.name)); + expect(names).toEqual(WORKSTATION_LLM_TOOLS); + expect(names.size).toBe(WORKSTATION_TOOLS.size + LLM_BACKED_TOOLS.size); + for (const tool of LLM_BACKED_TOOLS) { + expect(names.has(tool)).toBe(true); + } + expect(names.has("memory_governance_delete")).toBe(false); + }); + it("supports custom allowlists and explicit disabled tools", () => { process.env["AGENTMEMORY_TOOLS"] = "memory_recall,memory_sessions,memory_reflect"; process.env["AGENTMEMORY_DISABLED_TOOLS"] = "memory_sessions"; diff --git a/test/tool-count-consistency.test.ts b/test/tool-count-consistency.test.ts index 4215e57c86..da713d029d 100644 --- a/test/tool-count-consistency.test.ts +++ b/test/tool-count-consistency.test.ts @@ -24,7 +24,7 @@ describe("Tool count consistency", () => { const cli = readText("src/cli.ts"); expect(cli).toContain("const ALL_TOOLS_COUNT = getAllTools().length;"); expect(cli).toContain( - "Tool visibility (default: all = ${ALL_TOOLS_COUNT}; core = ${CORE_TOOLS_COUNT}; workstation = curated coordination set)", + "workstation-llm = curated + 4 LLM tools", ); expect(cli).not.toMatch(/all\s*=\s*51 tools/); }); From d586966656f7a85c0e59148fcc2532abe19b89a8 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Wed, 29 Jul 2026 16:47:00 -0400 Subject: [PATCH 27/43] fix: normalize sentence punctuation in URL checks --- src/functions/compress-file.ts | 5 ++++- test/compress-file.test.ts | 21 +++++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/src/functions/compress-file.ts b/src/functions/compress-file.ts index 0a54452b23..d473ffeb32 100644 --- a/src/functions/compress-file.ts +++ b/src/functions/compress-file.ts @@ -30,7 +30,10 @@ function stripMarkdownFence(text: string): string { } function extractUrls(text: string): string[] { - return Array.from(new Set(text.match(/https?:\/\/[^\s)]+/g) || [])); + const urls = text.match(/https?:\/\/[^\s)]+/g) || []; + return Array.from( + new Set(urls.map((url) => url.replace(/[.,;:!]+$/, ""))), + ); } function extractHeadings(text: string): string[] { diff --git a/test/compress-file.test.ts b/test/compress-file.test.ts index 9b6820b3e5..8363a03a11 100644 --- a/test/compress-file.test.ts +++ b/test/compress-file.test.ts @@ -193,6 +193,27 @@ describe("mem::compress-file", () => { expect(fileStore.get("/tmp/guide.original.md")).toBeUndefined(); }); + it("does not treat trailing sentence punctuation as part of a URL", async () => { + const path = "/tmp/guide.md"; + fileStore.set( + path, + "# Guide\n\nRead https://example.com/docs/, then continue with the detailed instructions.", + ); + summarize.mockResolvedValue( + "# Guide\n\nRead https://example.com/docs/ and continue.", + ); + + const result = (await sdk.trigger("mem::compress-file", { + filePath: path, + })) as { success: boolean }; + + expect(result.success).toBe(true); + expect(fileStore.get("/tmp/guide.original.md")).toContain( + "https://example.com/docs/,", + ); + expect(fileStore.get(path)).toContain("https://example.com/docs/"); + }); + it("uses a distinct backup path for *.original.md inputs", async () => { const path = "/tmp/notes.original.md"; fileStore.set(path, "# Title\n\nLong original body."); From 23cd3c1682f6cadb0d27fe58f38a12bd614df8af Mon Sep 17 00:00:00 2001 From: wrightpt Date: Wed, 29 Jul 2026 18:57:31 -0400 Subject: [PATCH 28/43] feat: complete workstation LLM MCP surface --- .env.example | 2 +- AGENTS.md | 4 +- CHANGELOG.md | 9 ++ README.md | 26 ++-- assets/tags/light/stat-tools.svg | 4 +- assets/tags/stat-tools.svg | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/opencode/README.md | 2 +- plugin/plugin.json | 2 +- plugin/skills/agentmemory-config/REFERENCE.md | 3 +- .../skills/agentmemory-mcp-tools/REFERENCE.md | 6 +- .../skills/agentmemory-rest-api/REFERENCE.md | 5 +- src/cli.ts | 2 +- src/functions/llm-smoke.ts | 61 +++++++++ src/index.ts | 6 +- src/mcp/server.ts | 111 ++++++++++++++++ src/mcp/standalone.ts | 2 +- src/mcp/tools-registry.ts | 66 ++++++++++ src/triggers/api.ts | 118 +++++++++++++++++- test/api-llm-state.test.ts | 3 + test/api-workstation-llm-tools.test.ts | 118 ++++++++++++++++++ test/llm-smoke.test.ts | 94 ++++++++++++++ test/mcp-llm-tools.test.ts | 79 ++++++++++++ test/mcp-surface-default.test.ts | 6 +- test/tool-count-consistency.test.ts | 4 +- 26 files changed, 707 insertions(+), 34 deletions(-) create mode 100644 src/functions/llm-smoke.ts create mode 100644 test/api-workstation-llm-tools.test.ts create mode 100644 test/llm-smoke.test.ts diff --git a/.env.example b/.env.example index af2588b72e..1ccb8dfaec 100644 --- a/.env.example +++ b/.env.example @@ -120,7 +120,7 @@ # 6. CLI / runtime knobs # ----------------------------------------------------------------------------- -# AGENTMEMORY_TOOLS=all # core | workstation | workstation-llm (curated + 4 LLM tools) | all +# AGENTMEMORY_TOOLS=all # core | workstation | workstation-llm (curated + 7 LLM tools) | all # AGENTMEMORY_SLOTS=memory # Comma-separated plugin slot names the CLI should claim # AGENTMEMORY_DEBUG=1 # Trace MCP shim probe + standalone fallback decisions to stderr # AGENTMEMORY_FORCE_PROXY=1 # Skip the MCP shim livez probe and trust AGENTMEMORY_URL (for sandboxed MCP clients that can't reach localhost) diff --git a/AGENTS.md b/AGENTS.md index 96a14f6558..b4a8aa8167 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -134,8 +134,8 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). ## Current Stats (v0.9.27) -- 54 MCP tools (`all` by default; 7 safe essentials in `core`; curated coordination in `workstation`) -- 131 REST endpoints +- 58 MCP tools (`all` by default; 7 safe essentials in `core`; curated coordination in `workstation`) +- 133 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 15 skills - 50+ iii functions diff --git a/CHANGELOG.md b/CHANGELOG.md index 3b5188fa98..fbdba60668 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), ## [Unreleased] +### Added + +- **Workstation LLM MCP completion.** Added `memory_enrich_session`, `memory_diagnostic_followup`, and `memory_flow_compress` so the existing engine functions are reachable from MCP clients. Added `memory_llm_smoke`, a fixed-input connectivity probe that reports configured provider/model evidence without persistent AgentMemory or filesystem writes. The `workstation-llm` profile now contains the curated workstation surface plus seven LLM-backed tools. +- **Safe LLM identity metadata.** `/agentmemory/health` now reports `llmConfiguredProvider` and `llmModel` without exposing base URLs or credentials. New `POST /agentmemory/llm/smoke` and `POST /agentmemory/enrich-session` REST endpoints mirror the new MCP operations. + +### Changed + +- **Surface counts:** 54 → 58 MCP tools and 131 → 133 REST endpoints. + ## [0.9.27] — 2026-06-07 Wave release closing several breaking regressions reported against v0.9.26, plus an agent-scope isolation security fix, an iii version-pin audit fix, and a benchmark scorecard correction. No breaking changes; drop-in upgrade. diff --git a/README.md b/README.md index a887b720ab..d89bc6270e 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@

95.2% retrieval R@5 92% fewer tokens - 54 MCP tools + 58 MCP tools 12 auto hooks 0 external DBs 1,423+ tests passing @@ -514,7 +514,7 @@ Implementation details live in `src/cli.ts` (see `runUpgrade` around the `src/cl ### Claude Code (one block, paste it) ```text -Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 15 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. +Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 15 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 58 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. ``` #### Claude Code without the plugin install (MCP-standalone path) @@ -543,7 +543,7 @@ codex plugin add agentmemory@agentmemory The Codex plugin ships from the same `plugin/` directory as the Claude Code plugin. It registers: -- `@agentmemory/mcp` as an MCP server (proxies all 54 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable) +- `@agentmemory/mcp` as an MCP server (proxies all 58 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable) - 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop` - 8 invocable skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/commit-context`, `/commit-history`, plus 7 reference skills the agent loads on demand (MCP tools, REST API, config, agents, hooks, architecture, and the skill-authoring guide) @@ -577,7 +577,7 @@ copilot plugin install rohitg00/agentmemory:plugin

OpenClaw (paste this prompt) ```text -Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools: +Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 58 memory tools: { "mcpServers": { @@ -602,7 +602,7 @@ Full guide: [`integrations/openclaw/`](integrations/openclaw/) Hermes Agent (paste this prompt) ```text -Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools: +Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 58 memory tools: mcp_servers: agentmemory: @@ -959,11 +959,11 @@ npm install @xenova/transformers

MCP Server

-54 tools, 6 resources, 3 prompts, and 15 skills, the most comprehensive MCP memory toolkit for any agent. +58 tools, 6 resources, 3 prompts, and 15 skills, the most comprehensive MCP memory toolkit for any agent. -> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the running server's selected tool profile **only when it can reach an agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). `AGENTMEMORY_TOOLS=core|workstation|workstation-llm|all` is evaluated by the running server; `workstation-llm` is the curated workstation surface plus the four LLM-backed tools. Set the profile in the server service environment. If you see only 7 local-fallback tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`. +> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the running server's selected tool profile **only when it can reach an agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). `AGENTMEMORY_TOOLS=core|workstation|workstation-llm|all` is evaluated by the running server; `workstation-llm` is the curated workstation surface plus the seven LLM-backed tools. Set the profile in the server service environment. If you see only 7 local-fallback tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`. -### 54 Tools +### 58 Tools
Core tools (always available) @@ -985,7 +985,7 @@ npm install @xenova/transformers
-Extended tools (54 total — set AGENTMEMORY_TOOLS=all) +Extended tools (58 total — set AGENTMEMORY_TOOLS=all) | Tool | Description | |------|-------------| @@ -1017,6 +1017,10 @@ npm install @xenova/transformers | `memory_sketch_promote` | Promote to permanent | | `memory_crystallize` | Compact action chains | | `memory_diagnose` | Health checks | +| `memory_diagnostic_followup` | Read-only follow-up-rate diagnostic | +| `memory_enrich_session` | LLM-enrich a session's observations | +| `memory_flow_compress` | Persist an LLM summary of completed actions | +| `memory_llm_smoke` | Read-only LLM provider/model connectivity probe | | `memory_heal` | Auto-fix stuck state | | `memory_facet_tag` | Dimension:value tags | | `memory_facet_query` | Query by facet tags | @@ -1524,7 +1528,7 @@ Create `~/.agentmemory/.env`: # TEAM_MODE=private # Tool visibility: "core" (7), "workstation" (curated coordination), -# "workstation-llm" (curated + 4 LLM-backed tools), "all" (54), or a comma-separated allowlist +# "workstation-llm" (curated + 7 LLM-backed tools), "all" (58), or a comma-separated allowlist # AGENTMEMORY_TOOLS=core # AGENTMEMORY_DISABLE_LLM_TOOLS=true # reports skipped_disabled, not failure ``` @@ -1533,7 +1537,7 @@ Create `~/.agentmemory/.env`:

API

-131 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers. +133 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
Key endpoints diff --git a/assets/tags/light/stat-tools.svg b/assets/tags/light/stat-tools.svg index 9ed07e9faf..e125bec965 100644 --- a/assets/tags/light/stat-tools.svg +++ b/assets/tags/light/stat-tools.svg @@ -1,5 +1,5 @@ - + - 54 + 58 MCP TOOLS diff --git a/assets/tags/stat-tools.svg b/assets/tags/stat-tools.svg index 57c3dc4eef..dd6863cdb8 100644 --- a/assets/tags/stat-tools.svg +++ b/assets/tags/stat-tools.svg @@ -1,5 +1,5 @@ - + - 54 + 58 MCP TOOLS diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index f351b2c8bc..1246a27808 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "version": "0.9.27", - "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 54 MCP tools, 8 skills, real-time viewer.", + "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 58 MCP tools, 8 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index f135276f48..0ed4efbe17 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "version": "0.9.27", - "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 6 hooks, 54 MCP tools, 8 skills, real-time viewer.", + "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 6 hooks, 58 MCP tools, 8 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" diff --git a/plugin/opencode/README.md b/plugin/opencode/README.md index 6bcc4b321e..8f863a5009 100644 --- a/plugin/opencode/README.md +++ b/plugin/opencode/README.md @@ -9,7 +9,7 @@

- 54 MCP tools + 58 MCP tools 22 hooks 2 slash commands 95.2% R@5 diff --git a/plugin/plugin.json b/plugin/plugin.json index e6e34d7da6..f0ea6b970e 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "version": "0.9.27", - "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 54 MCP tools, 15 skills, real-time viewer.", + "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 58 MCP tools, 15 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md index fded47a1ef..df803b0d85 100644 --- a/plugin/skills/agentmemory-config/REFERENCE.md +++ b/plugin/skills/agentmemory-config/REFERENCE.md @@ -3,7 +3,7 @@ Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded. -Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 51 recognized variables: +Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 52 recognized variables: - `AGENTMEMORY_AGENT_SCOPE` - `AGENTMEMORY_ALLOW_AGENT_SDK` @@ -27,6 +27,7 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e - `AGENTMEMORY_IMAGE_EMBEDDINGS` - `AGENTMEMORY_IMAGE_STORE_MAX_BYTES` - `AGENTMEMORY_INJECT_CONTEXT` +- `AGENTMEMORY_LLM_OK` - `AGENTMEMORY_LLM_TIMEOUT_MS` - `AGENTMEMORY_MAX_PROMPT_CAPTURE_CHARS` - `AGENTMEMORY_MAX_TOOL_CAPTURE_CHARS` diff --git a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md index 00f1b85345..ed498e0138 100644 --- a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md +++ b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md @@ -3,7 +3,7 @@ Generated from `src/mcp/tools-registry.ts`. Do not edit the block below by hand; run `npm run skills:gen` after changing the registry. -agentmemory exposes 54 MCP tools. 7 are in the lean core set (`--tools core` or `AGENTMEMORY_TOOLS=core`); the rest load with `--tools all` (default). +agentmemory exposes 58 MCP tools. 7 are in the lean core set (`--tools core` or `AGENTMEMORY_TOOLS=core`); the rest load with `--tools all` (default). | Tool | Core | Parameters | Purpose | | --- | --- | --- | --- | @@ -19,10 +19,13 @@ agentmemory exposes 54 MCP tools. 7 are in the lean core set (`--tools core` or | `memory_consolidate` | | `tier`: string | Run the 4-tier memory consolidation pipeline (working -> episodic -> semantic -> procedural). | | `memory_crystallize` | | `actionIds`*: string, `project`: string, `sessionId`: string | Compress completed action chains into compact crystal digests using LLM summarization. Extracts narrative, key outcomes, files affected, and lessons. | | `memory_diagnose` | yes | `categories`: string | Run health checks across all subsystems (actions, leases, sentinels, sketches, signals, sessions, memories, mesh). Identifies stuck, orphaned, and inconsistent state. | +| `memory_diagnostic_followup` | | none | Read the smart-search follow-up-rate diagnostic counters. This is a read-only directional signal and may overcount legitimate query refinement. | +| `memory_enrich_session` | | `sessionId`*: string, `lookback`: number, `lookahead`: number, `minImportance`: number | LLM-enrich qualifying observations in a session and persist enriched chunks. This is a state-changing, paid-provider operation. | | `memory_export` | | none | Export all memory data as JSON. | | `memory_facet_query` | | `matchAll`: string, `matchAny`: string, `targetType`: string | Query targets by facet tags with AND/OR logic. Find all actions tagged priority:urgent AND team:backend. | | `memory_facet_tag` | | `targetId`*: string, `targetType`*: string, `dimension`*: string, `value`*: string | Attach a structured tag (dimension:value) to an action, memory, or observation for multi-dimensional categorization. | | `memory_file_history` | | `files`*: string, `sessionId`: string | Get past observations about specific files. | +| `memory_flow_compress` | | `runId`: string, `actionIds`: string, `project`: string | LLM-summarize a completed action flow and persist it as workflow memory. Provide a run ID, comma-separated action IDs, or a project. | | `memory_frontier` | | `project`: string, `agentId`: string, `limit`: number | Get all unblocked actions ranked by priority and urgency. Returns the frontier of actionable work with no unsatisfied dependencies. | | `memory_governance_delete` | | `memoryIds`*: string, `reason`: string | Delete specific memories with audit trail. | | `memory_graph_query` | | `startNodeId`: string, `nodeType`: string, `maxDepth`: number, `query`: string | Query the knowledge graph for entities and relationships. | @@ -31,6 +34,7 @@ agentmemory exposes 54 MCP tools. 7 are in the lean core set (`--tools core` or | `memory_lease` | | `actionId`*: string, `agentId`*: string, `operation`*: string, `result`: string, `ttlMs`: number | Acquire, release, or renew an exclusive lease on an action. Prevents multiple agents from working on the same thing. | | `memory_lesson_recall` | yes | `query`*: string, `project`: string, `minConfidence`: number, `limit`: number | Search lessons by query. Returns lessons sorted by confidence and recency. Use to check what the agent has learned before making decisions. | | `memory_lesson_save` | yes | `content`*: string, `context`: string, `confidence`: number, `project`: string, `tags`: string | Save a lesson learned from this session. Lessons have confidence scores that strengthen when reinforced and decay when not used. Duplicate content auto-strengthens the existing lesson. | +| `memory_llm_smoke` | | none | Run a fixed, non-sensitive LLM connectivity probe. Returns provider/model evidence and performs no persistent AgentMemory or filesystem writes. | | `memory_mesh_sync` | | `peerId`: string, `direction`: string | Sync memories and actions with peer agentmemory instances for multi-agent collaboration. | | `memory_next` | | `project`: string, `agentId`: string | Get the single most important next action to work on. Combines dependency resolution, priority, and recency into a score. | | `memory_obsidian_export` | | `vaultDir`: string, `types`: string | Export memories, lessons, and crystals as Obsidian-compatible Markdown files with YAML frontmatter and wikilinks for graph view. | diff --git a/plugin/skills/agentmemory-rest-api/REFERENCE.md b/plugin/skills/agentmemory-rest-api/REFERENCE.md index 598a3332ee..c912e27684 100644 --- a/plugin/skills/agentmemory-rest-api/REFERENCE.md +++ b/plugin/skills/agentmemory-rest-api/REFERENCE.md @@ -5,12 +5,13 @@ Generated from `src/triggers/api.ts`. Do not edit the block below by hand; run ` The REST API is the primary surface. All paths are under `http://localhost:3111` (override with `--port`). When `AGENTMEMORY_SECRET` is set, send `Authorization: Bearer $AGENTMEMORY_SECRET`; localhost is otherwise open. -119 registered endpoints: +122 registered endpoints: | Method | Path | | --- | --- | | POST | `/agentmemory/actions` | | POST | `/agentmemory/actions/edges` | +| POST | `/agentmemory/actions/gc` | | GET | `/agentmemory/actions/get` | | POST | `/agentmemory/actions/update` | | GET | `/agentmemory/audit` | @@ -36,6 +37,7 @@ The REST API is the primary surface. All paths are under `http://localhost:3111` | GET | `/agentmemory/diagnostics/followup` | | POST | `/agentmemory/diagnostics/heal` | | POST | `/agentmemory/enrich` | +| POST | `/agentmemory/enrich-session` | | POST | `/agentmemory/evict` | | POST | `/agentmemory/evolve` | | GET | `/agentmemory/export` | @@ -67,6 +69,7 @@ The REST API is the primary surface. All paths are under `http://localhost:3111` | POST | `/agentmemory/lessons/search` | | POST | `/agentmemory/lessons/strengthen` | | GET | `/agentmemory/livez` | +| POST | `/agentmemory/llm/smoke` | | GET | `/agentmemory/memories` | | GET | `/agentmemory/memories/:id` | | GET | `/agentmemory/mesh/export` | diff --git a/src/cli.ts b/src/cli.ts index 9e9d58c300..6cea269a33 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -193,7 +193,7 @@ Options: --reset Wipe ~/.agentmemory/preferences.json and re-run onboarding --tools all|core|workstation|workstation-llm Tool visibility (default: all = ${ALL_TOOLS_COUNT}; core = ${CORE_TOOLS_COUNT}; - workstation = curated coordination; workstation-llm = curated + 4 LLM tools) + workstation = curated coordination; workstation-llm = curated + 7 LLM tools) --no-engine Skip auto-starting iii-engine --port Override REST port (default: 3111). Streams (N+1), viewer (N+2), and iii engine (N+46023) auto-derive from N so a diff --git a/src/functions/llm-smoke.ts b/src/functions/llm-smoke.ts new file mode 100644 index 0000000000..81cb00b127 --- /dev/null +++ b/src/functions/llm-smoke.ts @@ -0,0 +1,61 @@ +import { getLlmExecutionState } from "../config.js"; +import type { MemoryProvider, ProviderConfig } from "../types.js"; +import type { ISdk } from "iii-sdk"; + +const EXPECTED_TOKEN = "AGENTMEMORY_LLM_OK"; +const SYSTEM_PROMPT = + "You are an AgentMemory connectivity probe. Return only the exact token requested."; +const USER_PROMPT = `Return exactly: ${EXPECTED_TOKEN}`; +const MAX_RESPONSE_CHARS = 200; + +export type LlmSmokeMetadata = Pick; + +export function registerLlmSmokeFunction( + sdk: ISdk, + provider: MemoryProvider, + metadata: LlmSmokeMetadata, +): void { + sdk.registerFunction("mem::llm-smoke", async () => { + const llmExecutionState = getLlmExecutionState(provider); + const common = { + configuredProvider: metadata.provider, + model: metadata.model, + providerAdapter: provider.name, + persistentMutation: false, + }; + + if (llmExecutionState !== "enabled") { + return { + success: false, + error: "llm_execution_disabled", + llmExecutionState, + ...common, + }; + } + + const startedAt = Date.now(); + try { + const response = ( + await provider.summarize(SYSTEM_PROMPT, USER_PROMPT) + ).trim(); + const expectedResponseMatched = response.includes(EXPECTED_TOKEN); + return { + success: expectedResponseMatched, + expectedResponseMatched, + response: response.slice(0, MAX_RESPONSE_CHARS), + latencyMs: Date.now() - startedAt, + llmExecutionState, + ...common, + ...(expectedResponseMatched ? {} : { error: "unexpected_llm_response" }), + }; + } catch { + return { + success: false, + error: "llm_provider_call_failed", + latencyMs: Date.now() - startedAt, + llmExecutionState, + ...common, + }; + } + }); +} diff --git a/src/index.ts b/src/index.ts index d082430d86..22606f38dd 100644 --- a/src/index.ts +++ b/src/index.ts @@ -87,6 +87,7 @@ import { registerQueryExpansionFunction } from "./functions/query-expansion.js"; import { registerTemporalGraphFunctions } from "./functions/temporal-graph.js"; import { registerRetentionFunctions } from "./functions/retention.js"; import { registerCompressFileFunction } from "./functions/compress-file.js"; +import { registerLlmSmokeFunction } from "./functions/llm-smoke.js"; import { registerReplayFunctions } from "./functions/replay.js"; import { registerSessionContextFunction } from "./functions/session-context.js"; import { registerApiTriggers } from "./triggers/api.js"; @@ -333,6 +334,7 @@ async function main() { registerTemporalGraphFunctions(sdk, kv, provider); registerRetentionFunctions(sdk, kv); registerCompressFileFunction(sdk, kv, provider); + registerLlmSmokeFunction(sdk, provider, config.provider); registerReplayFunctions(sdk, kv); registerSessionContextFunction(sdk, kv); bootLog( @@ -372,7 +374,7 @@ async function main() { ); registerRecentSearchesSweepFunction(sdk, kv); - registerApiTriggers(sdk, kv, secret, metricsStore, provider); + registerApiTriggers(sdk, kv, secret, metricsStore, provider, config.provider); registerEventTriggers(sdk, kv); registerMcpEndpoints(sdk, kv, secret); @@ -521,7 +523,7 @@ async function main() { `Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`, ); bootLog( - `REST API: 131 endpoints at http://localhost:${config.restPort}/agentmemory/*`, + `REST API: 133 endpoints at http://localhost:${config.restPort}/agentmemory/*`, ); bootLog( `MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`, diff --git a/src/mcp/server.ts b/src/mcp/server.ts index 9a876a9c79..907ac3a3ce 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -166,6 +166,19 @@ export function registerMcpEndpoints( }; } + case "memory_llm_smoke": { + const result = await sdk.trigger({ + function_id: "mem::llm-smoke", + payload: {}, + }); + return { + status_code: 200, + body: { + content: [{ type: "text", text: JSON.stringify(result, null, 2) }], + }, + }; + } + case "memory_save": { if (typeof args.content !== "string" || !args.content.trim()) { return { @@ -239,6 +252,51 @@ export function registerMcpEndpoints( }; } + case "memory_enrich_session": { + const sessionId = asNonEmptyString(args.sessionId); + if (!sessionId) { + return { + status_code: 400, + body: { error: "sessionId is required for memory_enrich_session" }, + }; + } + for (const field of ["lookback", "lookahead", "minImportance"] as const) { + const value = args[field]; + if ( + value !== undefined && + (typeof value !== "number" || + !Number.isInteger(value) || + value < 0 || + (field === "minImportance" && value > 10)) + ) { + return { + status_code: 400, + body: { + error: + "lookback and lookahead must be non-negative integers; minImportance must be an integer from 0 to 10", + }, + }; + } + } + const result = await sdk.trigger({ + function_id: "mem::enrich-session", + payload: { + sessionId, + ...(args.lookback !== undefined && { lookback: args.lookback }), + ...(args.lookahead !== undefined && { lookahead: args.lookahead }), + ...(args.minImportance !== undefined && { + minImportance: args.minImportance, + }), + }, + }); + return { + status_code: 200, + body: { + content: [{ type: "text", text: JSON.stringify(result, null, 2) }], + }, + }; + } + case "memory_patterns": { const result = await sdk.trigger({ function_id: "mem::patterns", payload: { project: args.project as string, @@ -1137,6 +1195,46 @@ export function registerMcpEndpoints( return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(crysResult, null, 2) }] } }; } + case "memory_flow_compress": { + if ( + (args.runId !== undefined && typeof args.runId !== "string") || + (args.actionIds !== undefined && typeof args.actionIds !== "string") || + (args.project !== undefined && typeof args.project !== "string") + ) { + return { + status_code: 400, + body: { + error: "runId, actionIds, and project must be strings when provided", + }, + }; + } + const runId = asNonEmptyString(args.runId); + const project = asNonEmptyString(args.project); + const actionIds = parseCsvList(args.actionIds); + if (!runId && actionIds.length === 0 && !project) { + return { + status_code: 400, + body: { + error: "runId, actionIds, or project is required for memory_flow_compress", + }, + }; + } + const result = await sdk.trigger({ + function_id: "mem::flow-compress", + payload: { + ...(runId !== undefined && { runId }), + ...(actionIds.length > 0 && { actionIds }), + ...(project !== undefined && { project }), + }, + }); + return { + status_code: 200, + body: { + content: [{ type: "text", text: JSON.stringify(result, null, 2) }], + }, + }; + } + case "memory_diagnose": { const diagCats = typeof args.categories === "string" && args.categories.trim() ? args.categories.split(",").map((s: string) => s.trim()).filter(Boolean) @@ -1145,6 +1243,19 @@ export function registerMcpEndpoints( return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(diagResult, null, 2) }] } }; } + case "memory_diagnostic_followup": { + const result = await sdk.trigger({ + function_id: "mem::diagnostic::followup-stats", + payload: {}, + }); + return { + status_code: 200, + body: { + content: [{ type: "text", text: JSON.stringify(result, null, 2) }], + }, + }; + } + case "memory_heal": { const healCats = typeof args.categories === "string" && args.categories.trim() ? args.categories.split(",").map((s: string) => s.trim()).filter(Boolean) diff --git a/src/mcp/standalone.ts b/src/mcp/standalone.ts index f3aa81712d..46c8bc6221 100644 --- a/src/mcp/standalone.ts +++ b/src/mcp/standalone.ts @@ -373,7 +373,7 @@ async function handleProxyGeneric( handle: ProxyHandle, ): Promise<{ content: Array<{ type: string; text: string }> }> { // Forward to the server's full MCP surface so non-Claude clients can - // reach all 54 tools (lessons, sentinels, slots, signals, graph, …) + // reach all 58 tools (lessons, sentinels, slots, signals, graph, …) // instead of being capped at the 7 IMPLEMENTED_TOOLS set baked into // this shim. The server validates arguments per tool. const result = (await handle.call("/agentmemory/mcp/call", { diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts index b4b27e5e9c..89e6952595 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -979,6 +979,67 @@ export const V073_TOOLS: McpToolDef[] = [ }, ]; +export const V0927_WORKSTATION_TOOLS: McpToolDef[] = [ + { + name: "memory_enrich_session", + description: + "LLM-enrich qualifying observations in a session and persist enriched chunks. This is a state-changing, paid-provider operation.", + inputSchema: { + type: "object", + properties: { + sessionId: { + type: "string", + description: "Session ID whose observations should be enriched", + }, + lookback: { + type: "number", + description: "Previous observations included in each context window (default 3)", + }, + lookahead: { + type: "number", + description: "Following observations included in each context window (default 2)", + }, + minImportance: { + type: "number", + description: "Minimum observation importance from 0 to 10 (default 4)", + }, + }, + required: ["sessionId"], + }, + }, + { + name: "memory_diagnostic_followup", + description: + "Read the smart-search follow-up-rate diagnostic counters. This is a read-only directional signal and may overcount legitimate query refinement.", + inputSchema: { type: "object", properties: {} }, + }, + { + name: "memory_flow_compress", + description: + "LLM-summarize a completed action flow and persist it as workflow memory. Provide a run ID, comma-separated action IDs, or a project.", + inputSchema: { + type: "object", + properties: { + runId: { type: "string", description: "Completed routine run ID" }, + actionIds: { + type: "string", + description: "Comma-separated completed action IDs", + }, + project: { + type: "string", + description: "Project whose completed actions should be compressed", + }, + }, + }, + }, + { + name: "memory_llm_smoke", + description: + "Run a fixed, non-sensitive LLM connectivity probe. Returns provider/model evidence and performs no persistent AgentMemory or filesystem writes.", + inputSchema: { type: "object", properties: {} }, + }, +]; + export const V010_SLOTS_TOOLS: McpToolDef[] = [ { name: "memory_slot_list", @@ -1072,6 +1133,7 @@ export const WORKSTATION_TOOLS = new Set([ "memory_lease", "memory_signal_send", "memory_signal_read", + "memory_diagnostic_followup", ]); export const LLM_BACKED_TOOLS = new Set([ @@ -1079,6 +1141,9 @@ export const LLM_BACKED_TOOLS = new Set([ "memory_consolidate", "memory_crystallize", "memory_reflect", + "memory_enrich_session", + "memory_flow_compress", + "memory_llm_smoke", ]); export const WORKSTATION_LLM_TOOLS = new Set([ @@ -1095,6 +1160,7 @@ export function getAllTools(): McpToolDef[] { ...V061_TOOLS, ...V070_TOOLS, ...V073_TOOLS, + ...V0927_WORKSTATION_TOOLS, ...V010_SLOTS_TOOLS, ]; } diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 9a78f35a36..36869690c9 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -1,5 +1,12 @@ import { TriggerAction, type ISdk, type ApiRequest, type EnqueueResult } from "iii-sdk"; -import type { Session, CompressedObservation, HookPayload, CommitLink, SessionSummary } from "../types.js"; +import type { + Session, + CompressedObservation, + HookPayload, + CommitLink, + SessionSummary, + ProviderConfig, +} from "../types.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import { KV, generateId } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; @@ -213,6 +220,7 @@ export function registerApiTriggers( secret?: string, metricsStore?: MetricsStore, provider?: ResilientProvider, + providerConfig?: Pick, ): void { sdk.registerFunction( "middleware::api-auth", @@ -351,6 +359,8 @@ export function registerApiTriggers( llmToolsDisabled: process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"] === "true", llmExecutionState, llmProvider: provider?.name ?? null, + llmConfiguredProvider: providerConfig?.provider ?? null, + llmModel: providerConfig?.model ?? null, health: health || null, functionMetrics, circuitBreaker, @@ -590,6 +600,23 @@ export function registerApiTriggers( config: { api_path: "/agentmemory/compress-file", http_method: "POST" }, }); + sdk.registerFunction("api::llm-smoke", + async (req: ApiRequest): Promise => { + const authErr = checkAuth(req, secret); + if (authErr) return authErr; + const result = await sdk.trigger({ + function_id: "mem::llm-smoke", + payload: {}, + }); + return { status_code: 200, body: result }; + }, + ); + sdk.registerTrigger({ + type: "http", + function_id: "api::llm-smoke", + config: { api_path: "/agentmemory/llm/smoke", http_method: "POST" }, + }); + sdk.registerFunction("api::replay::load", async (req: ApiRequest): Promise => { const authErr = checkAuth(req, secret); @@ -1140,6 +1167,60 @@ export function registerApiTriggers( config: { api_path: "/agentmemory/enrich", http_method: "POST" }, }); + sdk.registerFunction("api::enrich-session", + async ( + req: ApiRequest<{ + sessionId: string; + lookback?: number; + lookahead?: number; + minImportance?: number; + }>, + ): Promise => { + const authErr = checkAuth(req, secret); + if (authErr) return authErr; + const body = (req.body ?? {}) as Record; + const sessionId = asNonEmptyString(body.sessionId); + if (!sessionId) { + return { + status_code: 400, + body: { error: "sessionId is required and must be a non-empty string" }, + }; + } + const lookback = parseOptionalNonNegativeInt(body.lookback); + const lookahead = parseOptionalNonNegativeInt(body.lookahead); + const minImportance = parseOptionalNonNegativeInt(body.minImportance); + if ( + lookback === null || + lookahead === null || + minImportance === null || + (minImportance !== undefined && minImportance > 10) + ) { + return { + status_code: 400, + body: { + error: + "lookback and lookahead must be non-negative integers; minImportance must be an integer from 0 to 10", + }, + }; + } + const result = await sdk.trigger({ + function_id: "mem::enrich-session", + payload: { + sessionId, + ...(lookback !== undefined && { lookback }), + ...(lookahead !== undefined && { lookahead }), + ...(minImportance !== undefined && { minImportance }), + }, + }); + return { status_code: 200, body: result }; + }, + ); + sdk.registerTrigger({ + type: "http", + function_id: "api::enrich-session", + config: { api_path: "/agentmemory/enrich-session", http_method: "POST" }, + }); + sdk.registerFunction("api::remember", async ( req: ApiRequest<{ @@ -3080,8 +3161,41 @@ export function registerApiTriggers( ): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; + const body = (req.body ?? {}) as Record; + const runId = asNonEmptyString(body.runId); + const project = asNonEmptyString(body.project); + const actionIds = + body.actionIds === undefined + ? undefined + : Array.isArray(body.actionIds) && + body.actionIds.length > 0 && + body.actionIds.every( + (actionId) => + typeof actionId === "string" && actionId.trim().length > 0, + ) + ? body.actionIds.map((actionId) => (actionId as string).trim()) + : null; + if (actionIds === null) { + return { + status_code: 400, + body: { error: "actionIds must be a non-empty array of strings" }, + }; + } + if (!runId && !actionIds && !project) { + return { + status_code: 400, + body: { error: "runId, actionIds, or project is required" }, + }; + } try { - const result = await sdk.trigger({ function_id: "mem::flow-compress", payload: req.body || {} }); + const result = await sdk.trigger({ + function_id: "mem::flow-compress", + payload: { + ...(runId !== null && { runId }), + ...(actionIds !== undefined && { actionIds }), + ...(project !== null && { project }), + }, + }); return { status_code: 200, body: result }; } catch { return { diff --git a/test/api-llm-state.test.ts b/test/api-llm-state.test.ts index 367f239b5f..c6282cc6d6 100644 --- a/test/api-llm-state.test.ts +++ b/test/api-llm-state.test.ts @@ -31,6 +31,7 @@ describe("LLM runtime state APIs", () => { undefined, metrics, provider, + { provider: "openai", model: "deepseek-v4-pro" }, ); const health = (await sdk.trigger("api::health", { @@ -43,6 +44,8 @@ describe("LLM runtime state APIs", () => { llmToolsDisabled: true, llmExecutionState: "disabled", llmProvider: "resilient(noop)", + llmConfiguredProvider: "openai", + llmModel: "deepseek-v4-pro", }); expect(functionMetrics).toContainEqual( expect.objectContaining({ diff --git a/test/api-workstation-llm-tools.test.ts b/test/api-workstation-llm-tools.test.ts new file mode 100644 index 0000000000..66e83ef13d --- /dev/null +++ b/test/api-workstation-llm-tools.test.ts @@ -0,0 +1,118 @@ +import { describe, expect, it, vi } from "vitest"; + +import { registerApiTriggers } from "../src/triggers/api.js"; +import { mockKV } from "./helpers/mocks.js"; + +function captureSdk() { + const functions = new Map(); + const trigger = vi.fn(async () => ({ success: true })); + return { + registerFunction: ( + idOrOpts: string | { id: string }, + handler: Function, + ) => { + const id = typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id; + functions.set(id, handler); + }, + registerTrigger: vi.fn(), + trigger, + getFunction: (id: string) => functions.get(id), + }; +} + +describe("workstation LLM REST tools", () => { + it("exposes a body-free LLM smoke endpoint", async () => { + const sdk = captureSdk(); + registerApiTriggers(sdk as never, mockKV() as never); + + const result = await sdk.getFunction("api::llm-smoke")!({ + headers: {}, + body: { ignored: "not forwarded" }, + }); + + expect(result).toMatchObject({ status_code: 200 }); + expect(sdk.trigger).toHaveBeenCalledWith({ + function_id: "mem::llm-smoke", + payload: {}, + }); + }); + + it("validates and whitelists session enrichment inputs", async () => { + const sdk = captureSdk(); + registerApiTriggers(sdk as never, mockKV() as never); + const enrichSession = sdk.getFunction("api::enrich-session")!; + + await expect( + enrichSession({ + headers: {}, + body: { + sessionId: "ses_123", + lookback: 2, + lookahead: 1, + minImportance: 5, + unknown: "dropped", + }, + }), + ).resolves.toMatchObject({ status_code: 200 }); + expect(sdk.trigger).toHaveBeenCalledWith({ + function_id: "mem::enrich-session", + payload: { + sessionId: "ses_123", + lookback: 2, + lookahead: 1, + minImportance: 5, + }, + }); + + sdk.trigger.mockClear(); + await expect( + enrichSession({ + headers: {}, + body: { sessionId: "ses_123", minImportance: 11 }, + }), + ).resolves.toMatchObject({ status_code: 400 }); + expect(sdk.trigger).not.toHaveBeenCalled(); + }); + + it("validates and whitelists flow-compression selectors", async () => { + const sdk = captureSdk(); + registerApiTriggers(sdk as never, mockKV() as never); + const flowCompress = sdk.getFunction("api::flow-compress")!; + + await expect( + flowCompress({ + headers: {}, + body: { + actionIds: ["act_1", "act_2"], + unknown: "dropped", + }, + }), + ).resolves.toMatchObject({ status_code: 200 }); + expect(sdk.trigger).toHaveBeenCalledWith({ + function_id: "mem::flow-compress", + payload: { actionIds: ["act_1", "act_2"] }, + }); + + sdk.trigger.mockClear(); + await expect( + flowCompress({ headers: {}, body: {} }), + ).resolves.toMatchObject({ status_code: 400 }); + expect(sdk.trigger).not.toHaveBeenCalled(); + }); + + it("keeps diagnostic follow-up read-only and argument-free", async () => { + const sdk = captureSdk(); + registerApiTriggers(sdk as never, mockKV() as never); + + await expect( + sdk.getFunction("api::diagnostic-followup")!({ + headers: {}, + body: { ignored: "not forwarded" }, + }), + ).resolves.toMatchObject({ status_code: 200 }); + expect(sdk.trigger).toHaveBeenCalledWith({ + function_id: "mem::diagnostic::followup-stats", + payload: {}, + }); + }); +}); diff --git a/test/llm-smoke.test.ts b/test/llm-smoke.test.ts new file mode 100644 index 0000000000..f9f1e4a651 --- /dev/null +++ b/test/llm-smoke.test.ts @@ -0,0 +1,94 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; + +import { registerLlmSmokeFunction } from "../src/functions/llm-smoke.js"; +import type { MemoryProvider } from "../src/types.js"; +import { mockSdk } from "./helpers/mocks.js"; + +const ORIGINAL_DISABLE_LLM_TOOLS = + process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"]; + +afterEach(() => { + if (ORIGINAL_DISABLE_LLM_TOOLS === undefined) { + delete process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"]; + } else { + process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"] = + ORIGINAL_DISABLE_LLM_TOOLS; + } +}); + +function provider(response = "AGENTMEMORY_LLM_OK"): MemoryProvider { + return { + name: "resilient(openai)", + kind: "llm", + compress: vi.fn(async () => response), + summarize: vi.fn(async () => response), + }; +} + +describe("mem::llm-smoke", () => { + it("runs a fixed prompt and reports provider/model evidence without persistence", async () => { + delete process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"]; + const sdk = mockSdk(); + const llm = provider(); + registerLlmSmokeFunction(sdk as never, llm, { + provider: "openai", + model: "deepseek-v4-pro", + }); + + const result = (await sdk.trigger("mem::llm-smoke", {})) as Record< + string, + unknown + >; + + expect(result).toMatchObject({ + success: true, + expectedResponseMatched: true, + response: "AGENTMEMORY_LLM_OK", + configuredProvider: "openai", + model: "deepseek-v4-pro", + providerAdapter: "resilient(openai)", + llmExecutionState: "enabled", + persistentMutation: false, + }); + expect(result["latencyMs"]).toEqual(expect.any(Number)); + expect(llm.summarize).toHaveBeenCalledOnce(); + expect(llm.summarize).toHaveBeenCalledWith( + expect.stringContaining("connectivity probe"), + "Return exactly: AGENTMEMORY_LLM_OK", + ); + }); + + it("does not call the provider when LLM tools are disabled", async () => { + process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"] = "true"; + const sdk = mockSdk(); + const llm = provider(); + registerLlmSmokeFunction(sdk as never, llm, { + provider: "openai", + model: "deepseek-v4-pro", + }); + + await expect(sdk.trigger("mem::llm-smoke", {})).resolves.toMatchObject({ + success: false, + error: "llm_execution_disabled", + llmExecutionState: "disabled", + persistentMutation: false, + }); + expect(llm.summarize).not.toHaveBeenCalled(); + }); + + it("fails closed when the provider response misses the expected token", async () => { + delete process.env["AGENTMEMORY_DISABLE_LLM_TOOLS"]; + const sdk = mockSdk(); + registerLlmSmokeFunction(sdk as never, provider("unexpected"), { + provider: "openai", + model: "deepseek-v4-pro", + }); + + await expect(sdk.trigger("mem::llm-smoke", {})).resolves.toMatchObject({ + success: false, + error: "unexpected_llm_response", + expectedResponseMatched: false, + persistentMutation: false, + }); + }); +}); diff --git a/test/mcp-llm-tools.test.ts b/test/mcp-llm-tools.test.ts index 3d7dd75727..0ec5aef45e 100644 --- a/test/mcp-llm-tools.test.ts +++ b/test/mcp-llm-tools.test.ts @@ -36,4 +36,83 @@ describe("MCP LLM tools", () => { payload: { tier: "semantic", force: true }, }); }); + + it("routes the workstation LLM and diagnostic tools to their engine functions", async () => { + const sdk = mockSdk(); + registerMcpEndpoints(sdk as never, {} as never); + const callTool = sdk.getFunction("mcp::tools::call")!; + + await callTool({ + headers: {}, + body: { + name: "memory_enrich_session", + arguments: { + sessionId: "ses_123", + lookback: 2, + lookahead: 1, + minImportance: 5, + }, + }, + }); + await callTool({ + headers: {}, + body: { + name: "memory_flow_compress", + arguments: { actionIds: "act_1, act_2" }, + }, + }); + await callTool({ + headers: {}, + body: { name: "memory_diagnostic_followup", arguments: {} }, + }); + await callTool({ + headers: {}, + body: { name: "memory_llm_smoke", arguments: {} }, + }); + + expect(sdk.trigger).toHaveBeenNthCalledWith(1, { + function_id: "mem::enrich-session", + payload: { + sessionId: "ses_123", + lookback: 2, + lookahead: 1, + minImportance: 5, + }, + }); + expect(sdk.trigger).toHaveBeenNthCalledWith(2, { + function_id: "mem::flow-compress", + payload: { actionIds: ["act_1", "act_2"] }, + }); + expect(sdk.trigger).toHaveBeenNthCalledWith(3, { + function_id: "mem::diagnostic::followup-stats", + payload: {}, + }); + expect(sdk.trigger).toHaveBeenNthCalledWith(4, { + function_id: "mem::llm-smoke", + payload: {}, + }); + }); + + it("rejects invalid enrich and flow-compress inputs before dispatch", async () => { + const sdk = mockSdk(); + registerMcpEndpoints(sdk as never, {} as never); + const callTool = sdk.getFunction("mcp::tools::call")!; + + await expect( + callTool({ + headers: {}, + body: { + name: "memory_enrich_session", + arguments: { sessionId: "ses_123", minImportance: 11 }, + }, + }), + ).resolves.toMatchObject({ status_code: 400 }); + await expect( + callTool({ + headers: {}, + body: { name: "memory_flow_compress", arguments: {} }, + }), + ).resolves.toMatchObject({ status_code: 400 }); + expect(sdk.trigger).not.toHaveBeenCalled(); + }); }); diff --git a/test/mcp-surface-default.test.ts b/test/mcp-surface-default.test.ts index 49bd22706e..b26498c6ad 100644 --- a/test/mcp-surface-default.test.ts +++ b/test/mcp-surface-default.test.ts @@ -64,7 +64,7 @@ describe("MCP tool surface default (#553)", () => { expect(names.has("memory_reflect")).toBe(false); }); - it("AGENTMEMORY_TOOLS=workstation-llm adds only the four LLM-backed tools", () => { + it("AGENTMEMORY_TOOLS=workstation-llm adds only the LLM-backed tools", () => { process.env["AGENTMEMORY_TOOLS"] = "workstation-llm"; const names = new Set(getVisibleTools().map((tool) => tool.name)); expect(names).toEqual(WORKSTATION_LLM_TOOLS); @@ -72,6 +72,10 @@ describe("MCP tool surface default (#553)", () => { for (const tool of LLM_BACKED_TOOLS) { expect(names.has(tool)).toBe(true); } + expect(names.has("memory_enrich_session")).toBe(true); + expect(names.has("memory_diagnostic_followup")).toBe(true); + expect(names.has("memory_flow_compress")).toBe(true); + expect(names.has("memory_llm_smoke")).toBe(true); expect(names.has("memory_governance_delete")).toBe(false); }); diff --git a/test/tool-count-consistency.test.ts b/test/tool-count-consistency.test.ts index da713d029d..e30817fb86 100644 --- a/test/tool-count-consistency.test.ts +++ b/test/tool-count-consistency.test.ts @@ -9,7 +9,7 @@ vi.mock("../src/logger.js", () => ({ import { getAllTools, ESSENTIAL_TOOLS } from "../src/mcp/tools-registry.js"; const ROOT = join(import.meta.dirname, ".."); -const EXPECTED_TOOL_COUNT = 54; +const EXPECTED_TOOL_COUNT = 58; function readText(relativePath: string): string { return readFileSync(join(ROOT, relativePath), "utf-8"); @@ -24,7 +24,7 @@ describe("Tool count consistency", () => { const cli = readText("src/cli.ts"); expect(cli).toContain("const ALL_TOOLS_COUNT = getAllTools().length;"); expect(cli).toContain( - "workstation-llm = curated + 4 LLM tools", + "workstation-llm = curated + 7 LLM tools", ); expect(cli).not.toMatch(/all\s*=\s*51 tools/); }); From e59fe655d82af948b04af645b5693e65e9e34920 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Wed, 29 Jul 2026 19:18:34 -0400 Subject: [PATCH 29/43] feat(actions): add bounded graph snapshot reads --- AGENTS.md | 2 +- README.md | 4 +- src/functions/actions.ts | 109 ++++++++++++++++++++++++++++ src/functions/lessons.ts | 54 +++++++++++++- src/index.ts | 2 +- src/triggers/api.ts | 49 +++++++++++++ test/actions-api-pagination.test.ts | 33 +++++++++ test/actions.test.ts | 75 +++++++++++++++++++ test/lessons-api-pagination.test.ts | 93 ++++++++++++++++++++++++ test/lessons.test.ts | 79 ++++++++++++++++++++ 10 files changed, 494 insertions(+), 6 deletions(-) create mode 100644 test/lessons-api-pagination.test.ts diff --git a/AGENTS.md b/AGENTS.md index b4a8aa8167..d4586c9364 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -135,7 +135,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). ## Current Stats (v0.9.27) - 58 MCP tools (`all` by default; 7 safe essentials in `core`; curated coordination in `workstation`) -- 133 REST endpoints +- 134 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 15 skills - 50+ iii functions diff --git a/README.md b/README.md index d89bc6270e..a8e3514643 100644 --- a/README.md +++ b/README.md @@ -1537,7 +1537,7 @@ Create `~/.agentmemory/.env`:

API

-133 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers. +134 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
Key endpoints @@ -1555,6 +1555,8 @@ Create `~/.agentmemory/.env`: | `POST` | `/agentmemory/forget` | Delete observations | | `POST` | `/agentmemory/enrich` | File context + memories + bugs | | `GET` | `/agentmemory/profile` | Project profile | +| `GET` | `/agentmemory/actions/graph` | Bounded action and dependency projection without event history | +| `GET` | `/agentmemory/lessons` | Bounded lesson pages with project, confidence, and recency controls | | `GET` | `/agentmemory/export` | Export all data | | `POST` | `/agentmemory/import` | Import from JSON | | `POST` | `/agentmemory/graph/query` | Knowledge graph query | diff --git a/src/functions/actions.ts b/src/functions/actions.ts index c97fc16a5f..6514ab8ab3 100644 --- a/src/functions/actions.ts +++ b/src/functions/actions.ts @@ -50,6 +50,7 @@ const LEGACY_STATUSES = new Set([ "blocked", "cancelled", ]); +const MAX_ACTION_GRAPH_ACTIONS = 5_000; interface ActionCreateInput { title: string; @@ -403,6 +404,49 @@ export function registerActionsFunction(sdk: ISdk, kv: StateKV): void { } }); + sdk.registerFunction( + "mem::action-graph-snapshot", + async (data: { limit?: number }) => { + const requestedLimit = data.limit ?? MAX_ACTION_GRAPH_ACTIONS; + if (!Number.isInteger(requestedLimit) || requestedLimit < 1) { + return { + success: false, + error: "limit must be a positive integer", + }; + } + + try { + const limit = Math.min(requestedLimit, MAX_ACTION_GRAPH_ACTIONS); + const snapshot = await readActionStoreSnapshot(kv); + const rankedActions = [...snapshot.actions].sort(compareGraphActions); + const selectedActions = rankedActions.slice(0, limit); + const selectedIds = new Set(selectedActions.map((action) => action.id)); + const selectedEdges = snapshot.edges + .filter( + (edge) => + selectedIds.has(edge.sourceActionId) && + selectedIds.has(edge.targetActionId), + ) + .sort(compareGraphEdges); + + return { + success: true, + revision: snapshot.state.revision, + actions: selectedActions.map(projectActionForGraph), + actionEdges: selectedEdges.map(projectActionEdgeForGraph), + totalActions: snapshot.actions.length, + totalEdges: snapshot.edges.length, + limit, + truncatedActions: snapshot.actions.length - selectedActions.length, + truncatedEdges: snapshot.edges.length - selectedEdges.length, + eventsIncluded: false, + }; + } catch (error) { + return actionStoreError(error); + } + }, + ); + sdk.registerFunction("mem::action-get", async (data: { actionId: string }) => { if (!data.actionId) { return { success: false, error: "actionId is required" }; @@ -820,6 +864,71 @@ function isValidEdgeType(value: string): value is ActionEdge["type"] { return VALID_EDGE_TYPES.includes(value as ActionEdge["type"]); } +function compareGraphActions(left: Action, right: Action): number { + const leftTerminal = + left.lifecycle === "done" || + left.lifecycle === "cancelled" || + left.status === "done" || + left.status === "cancelled"; + const rightTerminal = + right.lifecycle === "done" || + right.lifecycle === "cancelled" || + right.status === "done" || + right.status === "cancelled"; + return ( + Number(leftTerminal) - Number(rightTerminal) || + (right.priority ?? 0) - (left.priority ?? 0) || + timestampMs(right.updatedAt) - timestampMs(left.updatedAt) || + left.id.localeCompare(right.id) + ); +} + +function compareGraphEdges(left: ActionEdge, right: ActionEdge): number { + return ( + left.sourceActionId.localeCompare(right.sourceActionId) || + left.targetActionId.localeCompare(right.targetActionId) || + left.type.localeCompare(right.type) || + left.id.localeCompare(right.id) + ); +} + +function projectActionForGraph(action: Action) { + return { + id: action.id, + title: action.title, + status: action.status, + lifecycle: action.lifecycle, + project: action.project, + projectId: action.projectId, + parentId: action.parentId, + owner: action.owner, + assignedTo: action.assignedTo, + priority: action.priority, + tags: action.tags, + blockedReason: action.blockedReason, + repoRoot: action.repoRoot, + worktree: action.worktree, + branch: action.branch, + taskSlug: action.taskSlug, + updatedAt: action.updatedAt, + }; +} + +function projectActionEdgeForGraph(edge: ActionEdge) { + return { + id: edge.id, + type: edge.type, + sourceActionId: edge.sourceActionId, + targetActionId: edge.targetActionId, + createdAt: edge.createdAt, + }; +} + +function timestampMs(value: string | undefined): number { + const parsed = Date.parse(value ?? ""); + return Number.isFinite(parsed) ? parsed : 0; +} + function actionStoreError(error: unknown) { if (error instanceof ActionRevisionConflictError) { return { diff --git a/src/functions/lessons.ts b/src/functions/lessons.ts index 9e69f464fd..cc77a7de34 100644 --- a/src/functions/lessons.ts +++ b/src/functions/lessons.ts @@ -4,6 +4,8 @@ import { KV, fingerprintId } from "../state/schema.js"; import type { Lesson } from "../types.js"; import { recordAudit } from "./audit.js"; +const MAX_LESSON_LIST_LIMIT = 500; + function reinforceLesson(lesson: Lesson): void { const now = new Date().toISOString(); lesson.reinforcements++; @@ -156,8 +158,31 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { source?: string; minConfidence?: number; limit?: number; + offset?: number; + sortBy?: "confidence" | "recent"; }) => { - const limit = data.limit ?? 50; + const requestedLimit = data.limit ?? 50; + const offset = data.offset ?? 0; + if (!Number.isInteger(requestedLimit) || requestedLimit < 1) { + return { success: false, error: "limit must be a positive integer" }; + } + if (!Number.isInteger(offset) || offset < 0) { + return { + success: false, + error: "offset must be a non-negative integer", + }; + } + if ( + data.sortBy !== undefined && + data.sortBy !== "confidence" && + data.sortBy !== "recent" + ) { + return { + success: false, + error: "sortBy must be confidence or recent", + }; + } + const limit = Math.min(requestedLimit, MAX_LESSON_LIST_LIMIT); const minConfidence = data.minConfidence ?? 0; let lessons = await kv.list(KV.lessons); @@ -172,9 +197,27 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { lessons = lessons.filter((l) => l.source === data.source); } - lessons.sort((a, b) => b.confidence - a.confidence); + lessons.sort( + data.sortBy === "recent" + ? (a, b) => + lessonTimestampMs(b) - lessonTimestampMs(a) || + a.id.localeCompare(b.id) + : (a, b) => + b.confidence - a.confidence || a.id.localeCompare(b.id), + ); - return { success: true, lessons: lessons.slice(0, limit) }; + const total = lessons.length; + const page = lessons.slice(offset, offset + limit); + const hasMore = offset + page.length < total; + return { + success: true, + lessons: page, + total, + limit, + offset, + hasMore, + nextOffset: hasMore ? offset + page.length : null, + }; }, ); @@ -281,3 +324,8 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { }, ); } + +function lessonTimestampMs(lesson: Lesson): number { + const parsed = Date.parse(lesson.updatedAt || lesson.createdAt); + return Number.isFinite(parsed) ? parsed : 0; +} diff --git a/src/index.ts b/src/index.ts index 22606f38dd..9e47e54f14 100644 --- a/src/index.ts +++ b/src/index.ts @@ -523,7 +523,7 @@ async function main() { `Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`, ); bootLog( - `REST API: 133 endpoints at http://localhost:${config.restPort}/agentmemory/*`, + `REST API: 134 endpoints at http://localhost:${config.restPort}/agentmemory/*`, ); bootLog( `MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`, diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 36869690c9..9e8210ff6e 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -2680,6 +2680,35 @@ export function registerApiTriggers( config: { api_path: "/agentmemory/actions", http_method: "GET" }, }); + sdk.registerFunction( + "api::action-graph-snapshot", + async (req: ApiRequest): Promise => { + const authErr = checkAuth(req, secret); + if (authErr) return authErr; + const limit = parseOptionalPositiveInt(req.query_params?.["limit"]); + if (limit === null) { + return { + status_code: 400, + body: { error: "limit must be a positive integer" }, + }; + } + const result = await sdk.trigger({ + function_id: "mem::action-graph-snapshot", + payload: { limit }, + }); + const success = (result as { success?: boolean }).success !== false; + return { status_code: success ? 200 : 400, body: result }; + }, + ); + sdk.registerTrigger({ + type: "http", + function_id: "api::action-graph-snapshot", + config: { + api_path: "/agentmemory/actions/graph", + http_method: "GET", + }, + }); + sdk.registerFunction("api::action-get", async (req: ApiRequest<{ actionId: string }>): Promise => { const authErr = checkAuth(req, secret); @@ -3553,11 +3582,31 @@ export function registerApiTriggers( body: { error: "invalid numeric parameter: limit" }, }; } + const offset = parseOptionalNonNegativeInt(params.offset); + if (offset === null) { + return { + status_code: 400, + body: { error: "invalid numeric parameter: offset" }, + }; + } + const sortBy = asNonEmptyString(params.sortBy); + if ( + sortBy !== undefined && + sortBy !== "confidence" && + sortBy !== "recent" + ) { + return { + status_code: 400, + body: { error: "sortBy must be confidence or recent" }, + }; + } const result = await sdk.trigger({ function_id: "mem::lesson-list", payload: { project: params.project, source: params.source, minConfidence, limit, + offset, + sortBy, } }); return { status_code: 200, body: result }; }); diff --git a/test/actions-api-pagination.test.ts b/test/actions-api-pagination.test.ts index 04bd3902da..186c1e8bf5 100644 --- a/test/actions-api-pagination.test.ts +++ b/test/actions-api-pagination.test.ts @@ -88,6 +88,39 @@ describe("Actions REST pagination", () => { }); }); + it("serves the bounded action graph projection without event history", async () => { + const response = (await sdk.trigger("api::action-graph-snapshot", { + headers: {}, + query_params: { limit: "10" }, + })) as { + status_code: number; + body: { + success: boolean; + actions: Action[]; + actionEdges: unknown[]; + limit: number; + eventsIncluded: boolean; + }; + }; + + expect(response.status_code).toBe(200); + expect(response.body.success).toBe(true); + expect(response.body.actions).toHaveLength(10); + expect(response.body.actionEdges).toEqual([]); + expect(response.body.limit).toBe(10); + expect(response.body.eventsIncluded).toBe(false); + }); + + it("rejects an invalid action graph limit", async () => { + const response = (await sdk.trigger("api::action-graph-snapshot", { + headers: {}, + query_params: { limit: "0" }, + })) as { status_code: number; body: { error: string } }; + + expect(response.status_code).toBe(400); + expect(response.body.error).toBe("limit must be a positive integer"); + }); + it("whitelists action-create fields instead of forwarding the raw body", async () => { let received: Record | undefined; sdk.registerFunction("mem::action-create", async (data) => { diff --git a/test/actions.test.ts b/test/actions.test.ts index 24715b3d05..e3810e2f38 100644 --- a/test/actions.test.ts +++ b/test/actions.test.ts @@ -445,6 +445,81 @@ describe("Actions Functions", () => { }); }); + describe("mem::action-graph-snapshot", () => { + it("returns a bounded projection with typed edges and no events", async () => { + const source = (await sdk.trigger("mem::action-create", { + title: "Graph source", + description: "Large detail excluded from the projection", + priority: 10, + projectId: "agentmemory", + })) as { action: Action }; + const target = (await sdk.trigger("mem::action-create", { + title: "Graph target", + priority: 9, + projectId: "agentmemory", + })) as { action: Action }; + await sdk.trigger("mem::action-create", { + title: "Lower-ranked action", + priority: 1, + }); + await sdk.trigger("mem::action-edge-create", { + sourceActionId: source.action.id, + targetActionId: target.action.id, + type: "unlocks", + }); + + const result = (await sdk.trigger("mem::action-graph-snapshot", { + limit: 2, + })) as { + success: boolean; + revision: number; + actions: Array>; + actionEdges: ActionEdge[]; + totalActions: number; + totalEdges: number; + truncatedActions: number; + truncatedEdges: number; + eventsIncluded: boolean; + }; + + expect(result.success).toBe(true); + expect(result.actions.map((action) => action.id)).toEqual([ + source.action.id, + target.action.id, + ]); + expect(result.actions[0]).not.toHaveProperty("description"); + expect(result.actions[0]).not.toHaveProperty("createdBy"); + expect(result.actionEdges).toHaveLength(1); + expect(result.actionEdges[0]).toMatchObject({ + sourceActionId: source.action.id, + targetActionId: target.action.id, + type: "unlocks", + }); + expect(result.totalActions).toBe(3); + expect(result.totalEdges).toBe(1); + expect(result.truncatedActions).toBe(1); + expect(result.truncatedEdges).toBe(0); + expect(result.eventsIncluded).toBe(false); + expect(result.revision).toBeGreaterThan(0); + }); + + it("rejects invalid limits and caps oversized snapshots", async () => { + const invalid = (await sdk.trigger("mem::action-graph-snapshot", { + limit: 0, + })) as { success: boolean; error: string }; + expect(invalid).toEqual({ + success: false, + error: "limit must be a positive integer", + }); + + const capped = (await sdk.trigger("mem::action-graph-snapshot", { + limit: 100_000, + })) as { success: boolean; limit: number }; + expect(capped.success).toBe(true); + expect(capped.limit).toBe(5_000); + }); + }); + describe("mem::action-get", () => { it("returns action with edges and children", async () => { const parent = (await sdk.trigger("mem::action-create", { diff --git a/test/lessons-api-pagination.test.ts b/test/lessons-api-pagination.test.ts new file mode 100644 index 0000000000..133928e130 --- /dev/null +++ b/test/lessons-api-pagination.test.ts @@ -0,0 +1,93 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { registerLessonsFunctions } from "../src/functions/lessons.js"; +import { registerApiTriggers } from "../src/triggers/api.js"; +import type { Lesson } from "../src/types.js"; +import { mockKV, mockSdk } from "./helpers/mocks.js"; + +describe("Lessons REST pagination", () => { + let sdk: ReturnType; + let kv: ReturnType; + + beforeEach(async () => { + sdk = mockSdk(); + kv = mockKV(); + registerLessonsFunctions(sdk as never, kv as never); + registerApiTriggers(sdk as never, kv as never); + + for (const [content, confidence] of [ + ["Lesson A", 0.9], + ["Lesson B", 0.8], + ["Lesson C", 0.7], + ] as const) { + await sdk.trigger("mem::lesson-save", { + content, + confidence, + project: "agentmemory", + }); + } + }); + + it("forwards bounded pagination and sort controls", async () => { + const lessons = await kv.list("mem:lessons"); + for (const lesson of lessons) { + await kv.set("mem:lessons", lesson.id, { + ...lesson, + updatedAt: + lesson.content === "Lesson A" + ? "2026-07-20T00:00:00.000Z" + : lesson.content === "Lesson B" + ? "2026-07-22T00:00:00.000Z" + : "2026-07-21T00:00:00.000Z", + }); + } + + const response = (await sdk.trigger("api::lesson-list", { + headers: {}, + query_params: { + project: "agentmemory", + limit: "2", + offset: "1", + sortBy: "recent", + }, + })) as { + status_code: number; + body: { + lessons: Lesson[]; + total: number; + limit: number; + offset: number; + hasMore: boolean; + }; + }; + + expect(response.status_code).toBe(200); + expect(response.body.lessons.map((lesson) => lesson.content)).toEqual([ + "Lesson C", + "Lesson A", + ]); + expect(response.body).toMatchObject({ + total: 3, + limit: 2, + offset: 1, + hasMore: false, + }); + }); + + it.each([ + [{ offset: "-1" }, "invalid numeric parameter: offset"], + [{ sortBy: "random" }, "sortBy must be confidence or recent"], + ])("rejects invalid bounded-read parameters", async (queryParams, error) => { + const response = (await sdk.trigger("api::lesson-list", { + headers: {}, + query_params: queryParams, + })) as { status_code: number; body: { error: string } }; + + expect(response.status_code).toBe(400); + expect(response.body.error).toBe(error); + }); +}); diff --git a/test/lessons.test.ts b/test/lessons.test.ts index 4a55003e1a..1e85dbb40c 100644 --- a/test/lessons.test.ts +++ b/test/lessons.test.ts @@ -228,10 +228,89 @@ describe("Lessons", () => { expect(result.lessons.length).toBe(2); }); + it("can sort project lessons by most recent update", async () => { + const lessons = await kv.list("mem:lessons"); + const timestamps = new Map([ + ["Lesson A", "2026-07-20T00:00:00.000Z"], + ["Lesson B", "2026-07-19T00:00:00.000Z"], + ["Lesson C", "2026-07-21T00:00:00.000Z"], + ]); + await Promise.all( + lessons.map((lesson) => + kv.set("mem:lessons", lesson.id, { + ...lesson, + updatedAt: timestamps.get(lesson.content), + }), + ), + ); + + const result = (await sdk.trigger("mem::lesson-list", { + sortBy: "recent", + })) as { lessons: Lesson[] }; + expect(result.lessons.map((lesson) => lesson.content)).toEqual([ + "Lesson C", + "Lesson A", + "Lesson B", + ]); + }); + it("respects limit", async () => { const result = (await sdk.trigger("mem::lesson-list", { limit: 1 })) as { lessons: Lesson[] }; expect(result.lessons.length).toBe(1); }); + + it("returns stable bounded pages with metadata", async () => { + const first = (await sdk.trigger("mem::lesson-list", { + limit: 2, + })) as { + lessons: Lesson[]; + total: number; + limit: number; + offset: number; + hasMore: boolean; + nextOffset: number; + }; + const second = (await sdk.trigger("mem::lesson-list", { + limit: 2, + offset: first.nextOffset, + })) as { + lessons: Lesson[]; + total: number; + limit: number; + offset: number; + hasMore: boolean; + nextOffset: null; + }; + + expect(first.lessons).toHaveLength(2); + expect(second.lessons).toHaveLength(1); + expect(first.total).toBe(3); + expect(second.total).toBe(3); + expect(first.limit).toBe(2); + expect(second.offset).toBe(2); + expect(first.hasMore).toBe(true); + expect(second.hasMore).toBe(false); + expect(second.nextOffset).toBeNull(); + expect( + new Set([...first.lessons, ...second.lessons].map((lesson) => lesson.id)) + .size, + ).toBe(3); + }); + + it("caps oversized pages and rejects invalid offsets", async () => { + const capped = (await sdk.trigger("mem::lesson-list", { + limit: 100_000, + })) as { limit: number }; + expect(capped.limit).toBe(500); + + const invalid = (await sdk.trigger("mem::lesson-list", { + offset: -1, + })) as { success: boolean; error: string }; + expect(invalid).toEqual({ + success: false, + error: "offset must be a non-negative integer", + }); + }); }); describe("mem::lesson-strengthen", () => { From 532689d30c485e098c9548c1a6f95ab1dd435fb5 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Thu, 30 Jul 2026 06:11:36 -0400 Subject: [PATCH 30/43] fix(lessons): accept omitted sort order --- src/triggers/api.ts | 2 +- test/lessons-api-pagination.test.ts | 23 +++++++++++++++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 9e8210ff6e..d0ca02de03 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -3589,7 +3589,7 @@ export function registerApiTriggers( body: { error: "invalid numeric parameter: offset" }, }; } - const sortBy = asNonEmptyString(params.sortBy); + const sortBy = asNonEmptyString(params.sortBy) ?? undefined; if ( sortBy !== undefined && sortBy !== "confidence" && diff --git a/test/lessons-api-pagination.test.ts b/test/lessons-api-pagination.test.ts index 133928e130..3890c04b3a 100644 --- a/test/lessons-api-pagination.test.ts +++ b/test/lessons-api-pagination.test.ts @@ -78,6 +78,29 @@ describe("Lessons REST pagination", () => { }); }); + it("accepts an omitted sort order and uses the function default", async () => { + const response = (await sdk.trigger("api::lesson-list", { + headers: {}, + query_params: { limit: "2", offset: "0" }, + })) as { + status_code: number; + body: { + success: boolean; + lessons: Lesson[]; + limit: number; + offset: number; + }; + }; + + expect(response.status_code).toBe(200); + expect(response.body).toMatchObject({ + success: true, + limit: 2, + offset: 0, + }); + expect(response.body.lessons).toHaveLength(2); + }); + it.each([ [{ offset: "-1" }, "invalid numeric parameter: offset"], [{ sortBy: "random" }, "sortBy must be confidence or recent"], From cf04eaaea39a2160ffe237edde40eb06fd4c2400 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Sun, 2 Aug 2026 07:14:14 -0400 Subject: [PATCH 31/43] feat(lessons): add audited correction API (#17) Add idempotent, audited lesson deletion and supersession through the existing StateModule authority. Expose validated REST and MCP surfaces, prevent silent resurrection, regenerate interface documentation, and isolate embedding-provider tests from workstation environment state. Validated locally: npm test (1,560 passed), npm run build, npm run skills:check, git diff --check. --- AGENTS.md | 7 +- README.md | 22 +- assets/tags/light/stat-tools.svg | 4 +- assets/tags/stat-tools.svg | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/opencode/README.md | 2 +- plugin/plugin.json | 2 +- .../skills/agentmemory-mcp-tools/REFERENCE.md | 4 +- .../skills/agentmemory-rest-api/REFERENCE.md | 4 +- src/functions/lessons.ts | 436 +++++++++++++----- src/index.ts | 2 +- src/mcp/server.ts | 51 ++ src/mcp/standalone.ts | 2 +- src/mcp/tools-registry.ts | 65 +++ src/triggers/api.ts | 108 +++++ src/types.ts | 6 + test/embedding-provider.test.ts | 9 + test/lesson-corrections.test.ts | 254 ++++++++++ test/tool-count-consistency.test.ts | 2 +- 20 files changed, 840 insertions(+), 148 deletions(-) create mode 100644 test/lesson-corrections.test.ts diff --git a/AGENTS.md b/AGENTS.md index d4586c9364..6d0a5225b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,8 @@ agentmemory is a persistent memory system for AI coding agents, built on iii-engine's three primitives (Worker/Function/Trigger). Everything goes through `registerFunction`/`registerTrigger`/`sdk.trigger()` — never bypass iii-engine with standalone SQLite or in-process alternatives. - **Engine**: iii-sdk (WebSocket to iii-engine on port 49134) -- **State**: File-based SQLite via iii-engine's StateModule (`./data/state_store.db`) +- **State**: File-based KV via iii-engine's StateModule (`./data/state_store.db` + is a directory with one file per scope, not a SQLite database) - **Build**: TypeScript → ESM via tsdown, output to `dist/` - **Test**: vitest (`npm test` excludes integration tests) @@ -134,8 +135,8 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). ## Current Stats (v0.9.27) -- 58 MCP tools (`all` by default; 7 safe essentials in `core`; curated coordination in `workstation`) -- 134 REST endpoints +- 60 MCP tools (`all` by default; 7 safe essentials in `core`; curated coordination in `workstation`) +- 136 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 15 skills - 50+ iii functions diff --git a/README.md b/README.md index a8e3514643..58dfee63cf 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@

95.2% retrieval R@5 92% fewer tokens - 58 MCP tools + 60 MCP tools 12 auto hooks 0 external DBs 1,423+ tests passing @@ -514,7 +514,7 @@ Implementation details live in `src/cli.ts` (see `runUpgrade` around the `src/cl ### Claude Code (one block, paste it) ```text -Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 15 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 58 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. +Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 15 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 60 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. ``` #### Claude Code without the plugin install (MCP-standalone path) @@ -543,7 +543,7 @@ codex plugin add agentmemory@agentmemory The Codex plugin ships from the same `plugin/` directory as the Claude Code plugin. It registers: -- `@agentmemory/mcp` as an MCP server (proxies all 58 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable) +- `@agentmemory/mcp` as an MCP server (proxies all 60 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable) - 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop` - 8 invocable skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/commit-context`, `/commit-history`, plus 7 reference skills the agent loads on demand (MCP tools, REST API, config, agents, hooks, architecture, and the skill-authoring guide) @@ -577,7 +577,7 @@ copilot plugin install rohitg00/agentmemory:plugin

OpenClaw (paste this prompt) ```text -Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 58 memory tools: +Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 60 memory tools: { "mcpServers": { @@ -602,7 +602,7 @@ Full guide: [`integrations/openclaw/`](integrations/openclaw/) Hermes Agent (paste this prompt) ```text -Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 58 memory tools: +Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 60 memory tools: mcp_servers: agentmemory: @@ -959,11 +959,11 @@ npm install @xenova/transformers

MCP Server

-58 tools, 6 resources, 3 prompts, and 15 skills, the most comprehensive MCP memory toolkit for any agent. +60 tools, 6 resources, 3 prompts, and 15 skills, the most comprehensive MCP memory toolkit for any agent. > **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the running server's selected tool profile **only when it can reach an agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). `AGENTMEMORY_TOOLS=core|workstation|workstation-llm|all` is evaluated by the running server; `workstation-llm` is the curated workstation surface plus the seven LLM-backed tools. Set the profile in the server service environment. If you see only 7 local-fallback tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`. -### 58 Tools +### 60 Tools
Core tools (always available) @@ -985,7 +985,7 @@ npm install @xenova/transformers
-Extended tools (58 total — set AGENTMEMORY_TOOLS=all) +Extended tools (60 total — set AGENTMEMORY_TOOLS=all) | Tool | Description | |------|-------------| @@ -1528,7 +1528,7 @@ Create `~/.agentmemory/.env`: # TEAM_MODE=private # Tool visibility: "core" (7), "workstation" (curated coordination), -# "workstation-llm" (curated + 7 LLM-backed tools), "all" (58), or a comma-separated allowlist +# "workstation-llm" (curated + 7 LLM-backed tools), "all" (60), or a comma-separated allowlist # AGENTMEMORY_TOOLS=core # AGENTMEMORY_DISABLE_LLM_TOOLS=true # reports skipped_disabled, not failure ``` @@ -1537,7 +1537,7 @@ Create `~/.agentmemory/.env`:

API

-134 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers. +136 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
Key endpoints @@ -1557,6 +1557,8 @@ Create `~/.agentmemory/.env`: | `GET` | `/agentmemory/profile` | Project profile | | `GET` | `/agentmemory/actions/graph` | Bounded action and dependency projection without event history | | `GET` | `/agentmemory/lessons` | Bounded lesson pages with project, confidence, and recency controls | +| `DELETE` | `/agentmemory/lessons` | Tombstone a lesson (reason + optional actor; supports expectedUpdatedAt revision guard) | +| `POST` | `/agentmemory/lessons/supersede` | Tombstone a lesson and link a replacement lesson | | `GET` | `/agentmemory/export` | Export all data | | `POST` | `/agentmemory/import` | Import from JSON | | `POST` | `/agentmemory/graph/query` | Knowledge graph query | diff --git a/assets/tags/light/stat-tools.svg b/assets/tags/light/stat-tools.svg index e125bec965..0beaf179fa 100644 --- a/assets/tags/light/stat-tools.svg +++ b/assets/tags/light/stat-tools.svg @@ -1,5 +1,5 @@ - + - 58 + 60 MCP TOOLS diff --git a/assets/tags/stat-tools.svg b/assets/tags/stat-tools.svg index dd6863cdb8..136a4ecc53 100644 --- a/assets/tags/stat-tools.svg +++ b/assets/tags/stat-tools.svg @@ -1,5 +1,5 @@ - + - 58 + 60 MCP TOOLS diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 1246a27808..567945c102 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "version": "0.9.27", - "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 58 MCP tools, 8 skills, real-time viewer.", + "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 60 MCP tools, 8 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index 0ed4efbe17..3089279085 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "version": "0.9.27", - "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 6 hooks, 58 MCP tools, 8 skills, real-time viewer.", + "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 6 hooks, 60 MCP tools, 8 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" diff --git a/plugin/opencode/README.md b/plugin/opencode/README.md index 8f863a5009..8c3fe582f8 100644 --- a/plugin/opencode/README.md +++ b/plugin/opencode/README.md @@ -9,7 +9,7 @@

- 58 MCP tools + 60 MCP tools 22 hooks 2 slash commands 95.2% R@5 diff --git a/plugin/plugin.json b/plugin/plugin.json index f0ea6b970e..be1baedba1 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "version": "0.9.27", - "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 58 MCP tools, 15 skills, real-time viewer.", + "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 60 MCP tools, 15 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" diff --git a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md index ed498e0138..5107c2f8b3 100644 --- a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md +++ b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md @@ -3,7 +3,7 @@ Generated from `src/mcp/tools-registry.ts`. Do not edit the block below by hand; run `npm run skills:gen` after changing the registry. -agentmemory exposes 58 MCP tools. 7 are in the lean core set (`--tools core` or `AGENTMEMORY_TOOLS=core`); the rest load with `--tools all` (default). +agentmemory exposes 60 MCP tools. 7 are in the lean core set (`--tools core` or `AGENTMEMORY_TOOLS=core`); the rest load with `--tools all` (default). | Tool | Core | Parameters | Purpose | | --- | --- | --- | --- | @@ -32,8 +32,10 @@ agentmemory exposes 58 MCP tools. 7 are in the lean core set (`--tools core` or | `memory_heal` | | `categories`: string, `dryRun`: string | Auto-fix all fixable issues found by diagnostics. Unblocks stuck actions, expires stale leases, cleans up orphaned data. | | `memory_insight_list` | | `project`: string, `minConfidence`: number, `limit`: number | List synthesized insights, higher-order observations derived from patterns across memories, lessons, and crystals. | | `memory_lease` | | `actionId`*: string, `agentId`*: string, `operation`*: string, `result`: string, `ttlMs`: number | Acquire, release, or renew an exclusive lease on an action. Prevents multiple agents from working on the same thing. | +| `memory_lesson_delete` | | `lessonId`*: string, `reason`*: string, `project`: string, `expectedUpdatedAt`: string, `actor`: string | Soft-delete one lesson by exact ID while preserving correction metadata and an audit trail. Requires a human-readable reason. | | `memory_lesson_recall` | yes | `query`*: string, `project`: string, `minConfidence`: number, `limit`: number | Search lessons by query. Returns lessons sorted by confidence and recency. Use to check what the agent has learned before making decisions. | | `memory_lesson_save` | yes | `content`*: string, `context`: string, `confidence`: number, `project`: string, `tags`: string | Save a lesson learned from this session. Lessons have confidence scores that strengthen when reinforced and decay when not used. Duplicate content auto-strengthens the existing lesson. | +| `memory_lesson_supersede` | | `lessonId`*: string, `replacementLessonId`*: string, `reason`*: string, `project`: string, `expectedUpdatedAt`: string, `actor`: string | Soft-delete one lesson in favor of an existing replacement lesson in the same project, preserving lineage and an audit trail. | | `memory_llm_smoke` | | none | Run a fixed, non-sensitive LLM connectivity probe. Returns provider/model evidence and performs no persistent AgentMemory or filesystem writes. | | `memory_mesh_sync` | | `peerId`: string, `direction`: string | Sync memories and actions with peer agentmemory instances for multi-agent collaboration. | | `memory_next` | | `project`: string, `agentId`: string | Get the single most important next action to work on. Combines dependency resolution, priority, and recency into a score. | diff --git a/plugin/skills/agentmemory-rest-api/REFERENCE.md b/plugin/skills/agentmemory-rest-api/REFERENCE.md index c912e27684..64ef269ec8 100644 --- a/plugin/skills/agentmemory-rest-api/REFERENCE.md +++ b/plugin/skills/agentmemory-rest-api/REFERENCE.md @@ -5,7 +5,7 @@ Generated from `src/triggers/api.ts`. Do not edit the block below by hand; run ` The REST API is the primary surface. All paths are under `http://localhost:3111` (override with `--port`). When `AGENTMEMORY_SECRET` is set, send `Authorization: Bearer $AGENTMEMORY_SECRET`; localhost is otherwise open. -122 registered endpoints: +124 registered endpoints: | Method | Path | | --- | --- | @@ -13,6 +13,7 @@ The REST API is the primary surface. All paths are under `http://localhost:3111` | POST | `/agentmemory/actions/edges` | | POST | `/agentmemory/actions/gc` | | GET | `/agentmemory/actions/get` | +| GET | `/agentmemory/actions/graph` | | POST | `/agentmemory/actions/update` | | GET | `/agentmemory/audit` | | POST | `/agentmemory/auto-forget` | @@ -68,6 +69,7 @@ The REST API is the primary surface. All paths are under `http://localhost:3111` | POST | `/agentmemory/lessons` | | POST | `/agentmemory/lessons/search` | | POST | `/agentmemory/lessons/strengthen` | +| POST | `/agentmemory/lessons/supersede` | | GET | `/agentmemory/livez` | | POST | `/agentmemory/llm/smoke` | | GET | `/agentmemory/memories` | diff --git a/src/functions/lessons.ts b/src/functions/lessons.ts index cc77a7de34..7a5b4544b1 100644 --- a/src/functions/lessons.ts +++ b/src/functions/lessons.ts @@ -1,10 +1,24 @@ import type { ISdk } from "iii-sdk"; import type { StateKV } from "../state/kv.js"; import { KV, fingerprintId } from "../state/schema.js"; +import { withKeyedLock } from "../state/keyed-mutex.js"; import type { Lesson } from "../types.js"; import { recordAudit } from "./audit.js"; const MAX_LESSON_LIST_LIMIT = 500; +const MAX_CORRECTION_REASON_LENGTH = 1000; +const MAX_CORRECTION_ACTOR_LENGTH = 128; + +type LessonCorrectionData = { + lessonId: string; + reason: string; + actor?: string; + project?: string; + expectedUpdatedAt?: string; + replacementLessonId?: string; +}; + +type LessonCorrectionMode = "delete" | "supersede"; function reinforceLesson(lesson: Lesson): void { const now = new Date().toISOString(); @@ -17,6 +31,165 @@ function reinforceLesson(lesson: Lesson): void { lesson.updatedAt = now; } +function lessonLockKey(lessonId: string): string { + return `mem:lesson:${lessonId}`; +} + +function withLessonLocks( + lessonIds: string[], + fn: () => Promise, +): Promise { + const orderedIds = [...new Set(lessonIds)].sort(); + const lockNext = (index: number): Promise => { + if (index >= orderedIds.length) return fn(); + return withKeyedLock(lessonLockKey(orderedIds[index]), () => + lockNext(index + 1), + ); + }; + return lockNext(0); +} + +function correctionFailure(code: string, error: string) { + return { success: false, code, error }; +} + +async function correctLesson( + kv: StateKV, + data: LessonCorrectionData, + mode: LessonCorrectionMode, +) { + const lessonId = data.lessonId?.trim(); + const reason = data.reason?.trim(); + const actor = data.actor?.trim() || "unknown"; + const project = data.project?.trim() || undefined; + const expectedUpdatedAt = data.expectedUpdatedAt?.trim() || undefined; + const replacementLessonId = data.replacementLessonId?.trim() || undefined; + + if (!lessonId) { + return correctionFailure("invalid_request", "lessonId is required"); + } + if (!reason) { + return correctionFailure("invalid_request", "reason is required"); + } + if (reason.length > MAX_CORRECTION_REASON_LENGTH) { + return correctionFailure( + "invalid_request", + `reason must be at most ${MAX_CORRECTION_REASON_LENGTH} characters`, + ); + } + if (actor.length > MAX_CORRECTION_ACTOR_LENGTH) { + return correctionFailure( + "invalid_request", + `actor must be at most ${MAX_CORRECTION_ACTOR_LENGTH} characters`, + ); + } + if (mode === "supersede" && !replacementLessonId) { + return correctionFailure( + "invalid_request", + "replacementLessonId is required", + ); + } + if (replacementLessonId === lessonId) { + return correctionFailure( + "invalid_request", + "replacementLessonId must differ from lessonId", + ); + } + + const lockIds = replacementLessonId + ? [lessonId, replacementLessonId] + : [lessonId]; + return withLessonLocks(lockIds, async () => { + const lesson = await kv.get(KV.lessons, lessonId); + if (!lesson) { + return correctionFailure("lesson_not_found", "lesson not found"); + } + + if (lesson.deleted) { + const sameCorrection = + lesson.deleteReason === reason && + lesson.supersededByLessonId === replacementLessonId; + if (sameCorrection) { + return { + success: true, + action: + mode === "supersede" + ? "already_superseded" + : "already_deleted", + lesson, + }; + } + return correctionFailure( + "lesson_already_deleted", + "lesson is already deleted with different correction metadata", + ); + } + + if (project !== undefined && lesson.project !== project) { + return correctionFailure( + "project_mismatch", + "lesson does not belong to the requested project", + ); + } + if ( + expectedUpdatedAt !== undefined && + lesson.updatedAt !== expectedUpdatedAt + ) { + return correctionFailure( + "revision_conflict", + "lesson changed since expectedUpdatedAt", + ); + } + + if (replacementLessonId) { + const replacement = await kv.get( + KV.lessons, + replacementLessonId, + ); + if (!replacement || replacement.deleted) { + return correctionFailure( + "replacement_not_found", + "replacement lesson not found", + ); + } + if (replacement.project !== lesson.project) { + return correctionFailure( + "project_mismatch", + "replacement lesson must belong to the same project", + ); + } + } + + const timestamp = new Date().toISOString(); + lesson.deleted = true; + lesson.deletedAt = timestamp; + lesson.deletedBy = actor; + lesson.deleteReason = reason; + lesson.supersededByLessonId = replacementLessonId; + lesson.updatedAt = timestamp; + await kv.set(KV.lessons, lesson.id, lesson); + + const operation = + mode === "supersede" ? "lesson_supersede" : "lesson_delete"; + try { + await recordAudit(kv, operation, `mem::lesson-${mode}`, [lesson.id], { + actor, + reason, + project: lesson.project, + expectedUpdatedAt, + replacementLessonId, + deletedAt: timestamp, + }); + } catch {} + + return { + success: true, + action: mode === "supersede" ? "superseded" : "deleted", + lesson, + }; + }); +} + export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::lesson-save", async (data: { @@ -33,58 +206,67 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { } const fp = fingerprintId("lsn", data.content.trim().toLowerCase()); - const existing = await kv.get(KV.lessons, fp); - - if (existing && !existing.deleted) { - reinforceLesson(existing); - if (data.context && !existing.context) { - existing.context = data.context; + return withKeyedLock(lessonLockKey(fp), async () => { + const existing = await kv.get(KV.lessons, fp); + + if (existing?.deleted) { + return correctionFailure( + "lesson_deleted", + "lesson is deleted; save corrected content as a new lesson", + ); } - await kv.set(KV.lessons, existing.id, existing); - try { - await recordAudit(kv, "lesson_strengthen", "mem::lesson-save", [ - existing.id, - ]); - } catch {} + if (existing) { + reinforceLesson(existing); + if (data.context && !existing.context) { + existing.context = data.context; + } + await kv.set(KV.lessons, existing.id, existing); + + try { + await recordAudit(kv, "lesson_strengthen", "mem::lesson-save", [ + existing.id, + ]); + } catch {} + + return { + success: true, + action: "strengthened", + lesson: existing, + }; + } - return { - success: true, - action: "strengthened", - lesson: existing, + const confidence = + typeof data.confidence === "number" && + data.confidence >= 0 && + data.confidence <= 1 + ? data.confidence + : 0.5; + + const now = new Date().toISOString(); + const lesson: Lesson = { + id: fp, + content: data.content.trim(), + context: data.context?.trim() || "", + confidence, + reinforcements: 0, + source: data.source || "manual", + sourceIds: data.sourceIds || [], + project: data.project, + tags: data.tags || [], + createdAt: now, + updatedAt: now, + decayRate: 0.05, }; - } - const confidence = - typeof data.confidence === "number" && - data.confidence >= 0 && - data.confidence <= 1 - ? data.confidence - : 0.5; - - const now = new Date().toISOString(); - const lesson: Lesson = { - id: fp, - content: data.content.trim(), - context: data.context?.trim() || "", - confidence, - reinforcements: 0, - source: data.source || "manual", - sourceIds: data.sourceIds || [], - project: data.project, - tags: data.tags || [], - createdAt: now, - updatedAt: now, - decayRate: 0.05, - }; - - await kv.set(KV.lessons, lesson.id, lesson); + await kv.set(KV.lessons, lesson.id, lesson); - try { - await recordAudit(kv, "lesson_save", "mem::lesson-save", [lesson.id]); - } catch {} + try { + await recordAudit(kv, "lesson_save", "mem::lesson-save", [lesson.id]); + } catch {} - return { success: true, action: "created", lesson }; + return { success: true, action: "created", lesson }; + }); }, ); @@ -227,99 +409,109 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { return { success: false, error: "lessonId is required" }; } - const lesson = await kv.get(KV.lessons, data.lessonId); - if (!lesson || lesson.deleted) { - return { success: false, error: "lesson not found" }; - } + return withKeyedLock(lessonLockKey(data.lessonId), async () => { + const lesson = await kv.get(KV.lessons, data.lessonId); + if (!lesson || lesson.deleted) { + return { success: false, error: "lesson not found" }; + } - reinforceLesson(lesson); + reinforceLesson(lesson); - await kv.set(KV.lessons, lesson.id, lesson); + await kv.set(KV.lessons, lesson.id, lesson); - try { - await recordAudit(kv, "lesson_strengthen", "mem::lesson-strengthen", [ - lesson.id, - ]); - } catch {} + try { + await recordAudit(kv, "lesson_strengthen", "mem::lesson-strengthen", [ + lesson.id, + ]); + } catch {} - return { success: true, lesson }; + return { success: true, lesson }; + }); }, ); + sdk.registerFunction("mem::lesson-delete", async (data: LessonCorrectionData) => + correctLesson(kv, data, "delete"), + ); + + sdk.registerFunction( + "mem::lesson-supersede", + async (data: LessonCorrectionData) => + correctLesson(kv, data, "supersede"), + ); + sdk.registerFunction("mem::lesson-decay-sweep", async () => { const lessons = await kv.list(KV.lessons); - let decayed = 0; - let softDeleted = 0; const now = Date.now(); const timestamp = new Date().toISOString(); - const dirty: Lesson[] = []; - const auditEvents: Array<{ - id: string; - action: "decay" | "soft-delete"; - beforeConfidence: number; - afterConfidence: number; - beforeDeleted: boolean; - afterDeleted: boolean; - }> = []; - - for (const lesson of lessons) { - if (lesson.deleted) continue; - - const baseline = lesson.lastDecayedAt || lesson.lastReinforcedAt || lesson.createdAt; - const weeksSinceBaseline = - (now - new Date(baseline).getTime()) / (1000 * 60 * 60 * 24 * 7); - - if (weeksSinceBaseline < 1) continue; - - const decay = lesson.decayRate * weeksSinceBaseline; - const newConfidence = Math.max(0.05, lesson.confidence - decay); - - if (newConfidence !== lesson.confidence) { - const beforeConfidence = lesson.confidence; - const beforeDeleted = !!lesson.deleted; - lesson.confidence = Math.round(newConfidence * 1000) / 1000; - lesson.lastDecayedAt = timestamp; - lesson.updatedAt = timestamp; - - if (lesson.confidence <= 0.1 && lesson.reinforcements === 0) { - lesson.deleted = true; - softDeleted++; - } else { - decayed++; - } - - dirty.push(lesson); - auditEvents.push({ - id: lesson.id, - action: lesson.deleted ? "soft-delete" : "decay", - beforeConfidence, - afterConfidence: lesson.confidence, - beforeDeleted, - afterDeleted: !!lesson.deleted, - }); - } - } - - await Promise.all(dirty.map((l) => kv.set(KV.lessons, l.id, l))); - await Promise.all( - auditEvents.map((event) => - recordAudit(kv, "lesson_strengthen", "mem::lesson-decay-sweep", [event.id], { - action: event.action, - actor: "system", - reason: "decay-sweep", - before: { - confidence: event.beforeConfidence, - deleted: event.beforeDeleted, - }, - after: { - confidence: event.afterConfidence, - deleted: event.afterDeleted, - }, + const outcomes = await Promise.all( + lessons.map((listedLesson) => + withKeyedLock(lessonLockKey(listedLesson.id), async () => { + const lesson = await kv.get(KV.lessons, listedLesson.id); + if (!lesson || lesson.deleted) return null; + + const baseline = + lesson.lastDecayedAt || + lesson.lastReinforcedAt || + lesson.createdAt; + const weeksSinceBaseline = + (now - new Date(baseline).getTime()) / + (1000 * 60 * 60 * 24 * 7); + if (weeksSinceBaseline < 1) return null; + + const decay = lesson.decayRate * weeksSinceBaseline; + const newConfidence = Math.max( + 0.05, + lesson.confidence - decay, + ); + if (newConfidence === lesson.confidence) return null; + + const beforeConfidence = lesson.confidence; + lesson.confidence = Math.round(newConfidence * 1000) / 1000; + lesson.lastDecayedAt = timestamp; + lesson.updatedAt = timestamp; + const softDeleted = + lesson.confidence <= 0.1 && lesson.reinforcements === 0; + if (softDeleted) { + lesson.deleted = true; + lesson.deletedAt = timestamp; + lesson.deletedBy = "system"; + lesson.deleteReason = "decay-sweep"; + } + + await kv.set(KV.lessons, lesson.id, lesson); + try { + await recordAudit( + kv, + softDeleted ? "lesson_delete" : "lesson_strengthen", + "mem::lesson-decay-sweep", + [lesson.id], + { + action: softDeleted ? "soft-delete" : "decay", + actor: "system", + reason: "decay-sweep", + before: { + confidence: beforeConfidence, + deleted: false, + }, + after: { + confidence: lesson.confidence, + deleted: softDeleted, + }, + }, + ); + } catch {} + return softDeleted ? "soft-delete" : "decay"; }), ), ); + const decayed = outcomes.filter((outcome) => outcome === "decay").length; + const softDeleted = outcomes.filter( + (outcome) => outcome === "soft-delete", + ).length; + return { success: true, decayed, softDeleted, total: lessons.length }; }, ); diff --git a/src/index.ts b/src/index.ts index 9e47e54f14..910ffae73f 100644 --- a/src/index.ts +++ b/src/index.ts @@ -523,7 +523,7 @@ async function main() { `Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`, ); bootLog( - `REST API: 134 endpoints at http://localhost:${config.restPort}/agentmemory/*`, + `REST API: 136 endpoints at http://localhost:${config.restPort}/agentmemory/*`, ); bootLog( `MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`, diff --git a/src/mcp/server.ts b/src/mcp/server.ts index 907ac3a3ce..4e3f16c318 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -1337,6 +1337,57 @@ export function registerMcpEndpoints( return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(lessonRecallResult, null, 2) }] } }; } + case "memory_lesson_delete": { + const lessonId = asNonEmptyString(args.lessonId); + const reason = asNonEmptyString(args.reason); + if (!lessonId || !reason) { + return { + status_code: 400, + body: { error: "lessonId and reason are required" }, + }; + } + const lessonDeleteResult = await sdk.trigger({ + function_id: "mem::lesson-delete", + payload: { + lessonId, + reason, + project: asNonEmptyString(args.project), + expectedUpdatedAt: asNonEmptyString(args.expectedUpdatedAt), + actor: asNonEmptyString(args.actor) ?? getAgentId() ?? "unknown", + }, + }); + return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(lessonDeleteResult, null, 2) }] } }; + } + + case "memory_lesson_supersede": { + const lessonId = asNonEmptyString(args.lessonId); + const replacementLessonId = asNonEmptyString( + args.replacementLessonId, + ); + const reason = asNonEmptyString(args.reason); + if (!lessonId || !replacementLessonId || !reason) { + return { + status_code: 400, + body: { + error: + "lessonId, replacementLessonId, and reason are required", + }, + }; + } + const lessonSupersedeResult = await sdk.trigger({ + function_id: "mem::lesson-supersede", + payload: { + lessonId, + replacementLessonId, + reason, + project: asNonEmptyString(args.project), + expectedUpdatedAt: asNonEmptyString(args.expectedUpdatedAt), + actor: asNonEmptyString(args.actor) ?? getAgentId() ?? "unknown", + }, + }); + return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(lessonSupersedeResult, null, 2) }] } }; + } + case "memory_reflect": { const reflectResult = await sdk.trigger({ function_id: "mem::reflect", payload: { project: args.project, diff --git a/src/mcp/standalone.ts b/src/mcp/standalone.ts index 46c8bc6221..b64e147630 100644 --- a/src/mcp/standalone.ts +++ b/src/mcp/standalone.ts @@ -373,7 +373,7 @@ async function handleProxyGeneric( handle: ProxyHandle, ): Promise<{ content: Array<{ type: string; text: string }> }> { // Forward to the server's full MCP surface so non-Claude clients can - // reach all 58 tools (lessons, sentinels, slots, signals, graph, …) + // reach all 60 tools (lessons, sentinels, slots, signals, graph, …) // instead of being capped at the 7 IMPLEMENTED_TOOLS set baked into // this shim. The server validates arguments per tool. const result = (await handle.call("/agentmemory/mcp/call", { diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts index 89e6952595..7b556fa0d0 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -925,6 +925,71 @@ export const V070_TOOLS: McpToolDef[] = [ required: ["query"], }, }, + { + name: "memory_lesson_delete", + description: + "Soft-delete one lesson by exact ID while preserving correction metadata and an audit trail. Requires a human-readable reason.", + inputSchema: { + type: "object", + properties: { + lessonId: { type: "string", description: "Exact lesson ID to delete" }, + reason: { + type: "string", + description: "Why this lesson is being deleted", + }, + project: { + type: "string", + description: "Optional project guard; must match the lesson", + }, + expectedUpdatedAt: { + type: "string", + description: + "Optional optimistic concurrency guard from the lesson's updatedAt", + }, + actor: { + type: "string", + description: "Optional actor attribution; defaults to AGENT_ID", + }, + }, + required: ["lessonId", "reason"], + }, + }, + { + name: "memory_lesson_supersede", + description: + "Soft-delete one lesson in favor of an existing replacement lesson in the same project, preserving lineage and an audit trail.", + inputSchema: { + type: "object", + properties: { + lessonId: { + type: "string", + description: "Exact lesson ID being superseded", + }, + replacementLessonId: { + type: "string", + description: "Exact existing replacement lesson ID", + }, + reason: { + type: "string", + description: "Why the original lesson is being superseded", + }, + project: { + type: "string", + description: "Optional project guard; must match both lessons", + }, + expectedUpdatedAt: { + type: "string", + description: + "Optional optimistic concurrency guard from the original lesson's updatedAt", + }, + actor: { + type: "string", + description: "Optional actor attribution; defaults to AGENT_ID", + }, + }, + required: ["lessonId", "replacementLessonId", "reason"], + }, + }, { name: "memory_obsidian_export", description: diff --git a/src/triggers/api.ts b/src/triggers/api.ts index d0ca02de03..88f85d78e1 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -3632,6 +3632,114 @@ export function registerApiTriggers( }); sdk.registerTrigger({ type: "http", function_id: "api::lesson-strengthen", config: { api_path: "/agentmemory/lessons/strengthen", http_method: "POST" } }); + sdk.registerFunction("api::lesson-delete", async (req: ApiRequest) => { + const denied = checkAuth(req, secret); + if (denied) return denied; + const body = (req.body ?? {}) as Record; + const lessonId = asNonEmptyString(body.lessonId); + const reason = asNonEmptyString(body.reason); + if (!lessonId || !reason) { + return { + status_code: 400, + body: { error: "lessonId and reason are required" }, + }; + } + for (const field of ["project", "expectedUpdatedAt", "actor"] as const) { + if (body[field] !== undefined && typeof body[field] !== "string") { + return { + status_code: 400, + body: { error: `${field} must be a string` }, + }; + } + } + const result = await sdk.trigger({ + function_id: "mem::lesson-delete", + payload: { + lessonId, + reason, + project: asNonEmptyString(body.project) ?? undefined, + expectedUpdatedAt: + asNonEmptyString(body.expectedUpdatedAt) ?? undefined, + actor: asNonEmptyString(body.actor) ?? getAgentId() ?? "unknown", + }, + }); + const response = result as { success?: boolean; code?: string }; + const statusCode = + response.success !== false + ? 200 + : response.code === "lesson_not_found" + ? 404 + : response.code === "revision_conflict" || + response.code === "lesson_already_deleted" || + response.code === "project_mismatch" + ? 409 + : 400; + return { status_code: statusCode, body: result }; + }); + sdk.registerTrigger({ + type: "http", + function_id: "api::lesson-delete", + config: { api_path: "/agentmemory/lessons", http_method: "DELETE" }, + }); + + sdk.registerFunction("api::lesson-supersede", async (req: ApiRequest) => { + const denied = checkAuth(req, secret); + if (denied) return denied; + const body = (req.body ?? {}) as Record; + const lessonId = asNonEmptyString(body.lessonId); + const replacementLessonId = asNonEmptyString(body.replacementLessonId); + const reason = asNonEmptyString(body.reason); + if (!lessonId || !replacementLessonId || !reason) { + return { + status_code: 400, + body: { + error: "lessonId, replacementLessonId, and reason are required", + }, + }; + } + for (const field of ["project", "expectedUpdatedAt", "actor"] as const) { + if (body[field] !== undefined && typeof body[field] !== "string") { + return { + status_code: 400, + body: { error: `${field} must be a string` }, + }; + } + } + const result = await sdk.trigger({ + function_id: "mem::lesson-supersede", + payload: { + lessonId, + replacementLessonId, + reason, + project: asNonEmptyString(body.project) ?? undefined, + expectedUpdatedAt: + asNonEmptyString(body.expectedUpdatedAt) ?? undefined, + actor: asNonEmptyString(body.actor) ?? getAgentId() ?? "unknown", + }, + }); + const response = result as { success?: boolean; code?: string }; + const statusCode = + response.success !== false + ? 200 + : response.code === "lesson_not_found" || + response.code === "replacement_not_found" + ? 404 + : response.code === "revision_conflict" || + response.code === "lesson_already_deleted" || + response.code === "project_mismatch" + ? 409 + : 400; + return { status_code: statusCode, body: result }; + }); + sdk.registerTrigger({ + type: "http", + function_id: "api::lesson-supersede", + config: { + api_path: "/agentmemory/lessons/supersede", + http_method: "POST", + }, + }); + sdk.registerFunction("api::obsidian-export", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; diff --git a/src/types.ts b/src/types.ts index b168dec084..310188ba9a 100644 --- a/src/types.ts +++ b/src/types.ts @@ -619,6 +619,8 @@ export interface AuditEntry { | "lesson_save" | "lesson_recall" | "lesson_strengthen" + | "lesson_delete" + | "lesson_supersede" | "obsidian_export" | "reflect" | "insight_search" @@ -942,6 +944,10 @@ export interface Lesson { lastDecayedAt?: string; decayRate: number; deleted?: boolean; + deletedAt?: string; + deletedBy?: string; + deleteReason?: string; + supersededByLessonId?: string; } export interface Insight { diff --git a/test/embedding-provider.test.ts b/test/embedding-provider.test.ts index 6c2d263ec5..b7ad7cfbb6 100644 --- a/test/embedding-provider.test.ts +++ b/test/embedding-provider.test.ts @@ -1,4 +1,13 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"; + +vi.mock("node:os", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + homedir: () => "/tmp/agentmemory-embedding-provider-test-home", + }; +}); + import { createEmbeddingProvider, withDimensionGuard, diff --git a/test/lesson-corrections.test.ts b/test/lesson-corrections.test.ts new file mode 100644 index 0000000000..1248ea8244 --- /dev/null +++ b/test/lesson-corrections.test.ts @@ -0,0 +1,254 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { registerLessonsFunctions } from "../src/functions/lessons.js"; +import { registerMcpEndpoints } from "../src/mcp/server.js"; +import { getAllTools } from "../src/mcp/tools-registry.js"; +import { registerApiTriggers } from "../src/triggers/api.js"; +import type { AuditEntry, Lesson } from "../src/types.js"; +import { mockKV, mockSdk } from "./helpers/mocks.js"; + +describe("lesson corrections", () => { + let sdk: ReturnType; + let kv: ReturnType; + + beforeEach(() => { + sdk = mockSdk(); + kv = mockKV(); + registerLessonsFunctions(sdk as never, kv as never); + }); + + async function saveLesson(content: string, project = "agentmemory") { + const result = (await sdk.trigger("mem::lesson-save", { + content, + project, + confidence: 0.8, + })) as { lesson: Lesson }; + return result.lesson; + } + + it("soft-deletes by exact ID with correction metadata and audit", async () => { + const lesson = await saveLesson("Incorrect operational verdict"); + const expectedUpdatedAt = lesson.updatedAt; + + const result = (await sdk.trigger("mem::lesson-delete", { + lessonId: lesson.id, + reason: "Superseded by current evidence", + actor: "codex", + project: "agentmemory", + expectedUpdatedAt, + })) as { success: boolean; action: string; lesson: Lesson }; + + expect(result).toMatchObject({ + success: true, + action: "deleted", + lesson: { + id: lesson.id, + deleted: true, + deletedBy: "codex", + deleteReason: "Superseded by current evidence", + }, + }); + expect(result.lesson.deletedAt).toBeDefined(); + expect(result.lesson.updatedAt).toBe(result.lesson.deletedAt); + + const recall = (await sdk.trigger("mem::lesson-recall", { + query: "operational verdict", + project: "agentmemory", + })) as { lessons: Lesson[] }; + const list = (await sdk.trigger("mem::lesson-list", { + project: "agentmemory", + })) as { lessons: Lesson[] }; + expect(recall.lessons).toEqual([]); + expect(list.lessons).toEqual([]); + + const audit = await kv.list("mem:audit"); + expect(audit.filter((entry) => entry.operation === "lesson_delete")).toEqual([ + expect.objectContaining({ + functionId: "mem::lesson-delete", + targetIds: [lesson.id], + details: expect.objectContaining({ + actor: "codex", + reason: "Superseded by current evidence", + }), + }), + ]); + }); + + it("is idempotent for the same delete and blocks silent resurrection", async () => { + const lesson = await saveLesson("Do not resurrect this lesson"); + const correction = { + lessonId: lesson.id, + reason: "Incorrect", + actor: "codex", + }; + + await sdk.trigger("mem::lesson-delete", correction); + const repeated = (await sdk.trigger( + "mem::lesson-delete", + correction, + )) as { success: boolean; action: string }; + const resave = (await sdk.trigger("mem::lesson-save", { + content: lesson.content, + project: lesson.project, + })) as { success: boolean; code: string }; + + expect(repeated).toMatchObject({ + success: true, + action: "already_deleted", + }); + expect(resave).toMatchObject({ + success: false, + code: "lesson_deleted", + }); + const audit = await kv.list("mem:audit"); + expect( + audit.filter((entry) => entry.operation === "lesson_delete"), + ).toHaveLength(1); + }); + + it("records supersession lineage to an existing same-project lesson", async () => { + const original = await saveLesson("Old verdict"); + const replacement = await saveLesson("Corrected verdict"); + + const result = (await sdk.trigger("mem::lesson-supersede", { + lessonId: original.id, + replacementLessonId: replacement.id, + reason: "New evidence reversed the verdict", + actor: "codex", + project: "agentmemory", + expectedUpdatedAt: original.updatedAt, + })) as { success: boolean; action: string; lesson: Lesson }; + + expect(result).toMatchObject({ + success: true, + action: "superseded", + lesson: { + id: original.id, + deleted: true, + supersededByLessonId: replacement.id, + }, + }); + const storedReplacement = await kv.get( + "mem:lessons", + replacement.id, + ); + expect(storedReplacement?.deleted).not.toBe(true); + + const audit = await kv.list("mem:audit"); + expect( + audit.filter((entry) => entry.operation === "lesson_supersede"), + ).toEqual([ + expect.objectContaining({ + targetIds: [original.id], + details: expect.objectContaining({ + replacementLessonId: replacement.id, + }), + }), + ]); + }); + + it("rejects stale, missing, and cross-project replacements", async () => { + const original = await saveLesson("Original"); + const otherProject = await saveLesson("Other project", "trading-system"); + + const stale = await sdk.trigger("mem::lesson-delete", { + lessonId: original.id, + reason: "Stale request", + expectedUpdatedAt: "2026-01-01T00:00:00.000Z", + }); + const missing = await sdk.trigger("mem::lesson-supersede", { + lessonId: original.id, + replacementLessonId: "lsn_missing", + reason: "Missing replacement", + }); + const crossProject = await sdk.trigger("mem::lesson-supersede", { + lessonId: original.id, + replacementLessonId: otherProject.id, + reason: "Wrong project", + }); + + expect(stale).toMatchObject({ + success: false, + code: "revision_conflict", + }); + expect(missing).toMatchObject({ + success: false, + code: "replacement_not_found", + }); + expect(crossProject).toMatchObject({ + success: false, + code: "project_mismatch", + }); + }); + + it("serializes delete and strengthen so the tombstone wins", async () => { + const lesson = await saveLesson("Concurrent lesson"); + const [deleted, strengthened] = await Promise.all([ + sdk.trigger("mem::lesson-delete", { + lessonId: lesson.id, + reason: "Concurrent correction", + }), + sdk.trigger("mem::lesson-strengthen", { lessonId: lesson.id }), + ]); + + expect(deleted).toMatchObject({ success: true, action: "deleted" }); + expect(strengthened).toMatchObject({ + success: false, + error: "lesson not found", + }); + expect(await kv.get("mem:lessons", lesson.id)).toMatchObject({ + deleted: true, + deleteReason: "Concurrent correction", + }); + }); + + it("exposes validated REST and MCP correction surfaces", async () => { + registerApiTriggers(sdk as never, kv as never); + registerMcpEndpoints(sdk as never, kv as never); + const restLesson = await saveLesson("REST correction"); + const mcpOriginal = await saveLesson("MCP old"); + const mcpReplacement = await saveLesson("MCP replacement"); + + const restResponse = (await sdk.trigger("api::lesson-delete", { + headers: {}, + body: { + lessonId: restLesson.id, + reason: "REST evidence correction", + actor: "codex", + }, + })) as { status_code: number; body: { success: boolean } }; + expect(restResponse).toMatchObject({ + status_code: 200, + body: { success: true }, + }); + + const mcpResponse = (await sdk.trigger("mcp::tools::call", { + headers: {}, + body: { + name: "memory_lesson_supersede", + arguments: { + lessonId: mcpOriginal.id, + replacementLessonId: mcpReplacement.id, + reason: "MCP evidence correction", + actor: "codex", + }, + }, + })) as { + status_code: number; + body: { content: Array<{ type: string; text: string }> }; + }; + expect(mcpResponse.status_code).toBe(200); + expect(JSON.parse(mcpResponse.body.content[0].text)).toMatchObject({ + success: true, + action: "superseded", + }); + + const names = new Set(getAllTools().map((tool) => tool.name)); + expect(names.has("memory_lesson_delete")).toBe(true); + expect(names.has("memory_lesson_supersede")).toBe(true); + }); +}); diff --git a/test/tool-count-consistency.test.ts b/test/tool-count-consistency.test.ts index e30817fb86..ec6ead8995 100644 --- a/test/tool-count-consistency.test.ts +++ b/test/tool-count-consistency.test.ts @@ -9,7 +9,7 @@ vi.mock("../src/logger.js", () => ({ import { getAllTools, ESSENTIAL_TOOLS } from "../src/mcp/tools-registry.js"; const ROOT = join(import.meta.dirname, ".."); -const EXPECTED_TOOL_COUNT = 58; +const EXPECTED_TOOL_COUNT = 60; function readText(relativePath: string): string { return readFileSync(join(ROOT, relativePath), "utf-8"); From 495b051350ced8702b2d8fe6f28429a31a4a1ed2 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Sun, 2 Aug 2026 20:54:00 -0400 Subject: [PATCH 32/43] feat(lessons): add causal schema foundation --- README.md | 35 +- .../2026-08-02-causal-lesson-schema-v1.md | 187 +++ .../skills/agentmemory-mcp-tools/REFERENCE.md | 6 +- src/functions/context.ts | 20 +- src/functions/diagnostics.ts | 3 +- src/functions/export-import.ts | 57 +- src/functions/lesson-model.ts | 1111 +++++++++++++++++ src/functions/lessons.ts | 202 ++- src/functions/obsidian-export.ts | 84 +- src/functions/reflect.ts | 3 +- src/functions/replay.ts | 14 +- src/mcp/server.ts | 27 +- src/mcp/tools-registry.ts | 157 ++- src/triggers/api.ts | 68 +- src/types.ts | 100 ++ src/viewer/index.html | 4 +- test/causal-lessons-api.test.ts | 208 +++ test/context-lessons.test.ts | 54 + test/export-import.test.ts | 159 +++ test/lesson-corrections.test.ts | 99 ++ test/lesson-model.test.ts | 398 ++++++ test/lessons.test.ts | 71 +- 22 files changed, 2916 insertions(+), 151 deletions(-) create mode 100644 docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md create mode 100644 src/functions/lesson-model.ts create mode 100644 test/causal-lessons-api.test.ts create mode 100644 test/lesson-model.test.ts diff --git a/README.md b/README.md index 58dfee63cf..1af386e19e 100644 --- a/README.md +++ b/README.md @@ -1516,7 +1516,7 @@ Create `~/.agentmemory/.env`: # PostToolUse regardless of this flag. # GRAPH_EXTRACTION_ENABLED=false # CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured -# LESSON_DECAY_ENABLED=true +# LESSON_DECAY_ENABLED=true # legacy confidence decay + schema-v1 staleness scan # OBSIDIAN_AUTO_EXPORT=false # AGENTMEMORY_EXPORT_ROOT=~/.agentmemory # CLAUDE_MEMORY_BRIDGE=false @@ -1533,6 +1533,35 @@ Create `~/.agentmemory/.env`: # AGENTMEMORY_DISABLE_LLM_TOOLS=true # reports skipped_disabled, not failure ``` +### Structured causal lessons + +`memory_lesson_save` and `POST /agentmemory/lessons` remain compatible with +prose-only lessons and also accept causal schema-v1 fields: + +- canonical `mechanismId`/optional version and aliases, plus a short + falsifiable `claim`; +- evidence verdict (`supported`, `refuted`, `mixed`, `unverified`) independent + of lifecycle (`draft`, `active`, `superseded`, `retracted`); +- applicability, non-applicability, falsification conditions, and general + string-valued facets; +- at most eight durable evidence references anchored by a full commit SHA + and/or artifact digest; +- worktree/repo/initiative/domain/global scope rings and sensitivity + classification. + +Structured causal lessons require an explicit durable scope; global scope also +requires human approval metadata. Legacy lessons normalize on read to +`unverified` + `active` with an implicit worktree scope and +`sensitivity: restricted`; reads do not rewrite stored rows. Reinforcement +records reuse without increasing evidence confidence. +Supersession/retraction continue through the audited correction APIs. + +Scope and sensitivity enforcement, automatic contradiction discovery, and +hybrid/vector lesson retrieval are intentionally deferred to PR2. Until then, +sensitivity metadata is classification, not an access-control boundary. See +[Causal Lesson Schema v1](docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md) +for the complete compatibility and fingerprint contract. + ---

API

@@ -1557,8 +1586,8 @@ Create `~/.agentmemory/.env`: | `GET` | `/agentmemory/profile` | Project profile | | `GET` | `/agentmemory/actions/graph` | Bounded action and dependency projection without event history | | `GET` | `/agentmemory/lessons` | Bounded lesson pages with project, confidence, and recency controls | -| `DELETE` | `/agentmemory/lessons` | Tombstone a lesson (reason + optional actor; supports expectedUpdatedAt revision guard) | -| `POST` | `/agentmemory/lessons/supersede` | Tombstone a lesson and link a replacement lesson | +| `DELETE` | `/agentmemory/lessons` | Retract a lesson through an audited compatibility tombstone (reason + optional actor; supports expectedUpdatedAt) | +| `POST` | `/agentmemory/lessons/supersede` | Mark a lesson superseded and link an active replacement through the audited correction path | | `GET` | `/agentmemory/export` | Export all data | | `POST` | `/agentmemory/import` | Import from JSON | | `POST` | `/agentmemory/graph/query` | Knowledge graph query | diff --git a/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md b/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md new file mode 100644 index 0000000000..e254bb8d38 --- /dev/null +++ b/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md @@ -0,0 +1,187 @@ +# Causal Lesson Schema v1 + +Status: PR1 foundation + +Scope: additive lesson schema, normalization, validation, and lifecycle invariants + +Out of scope: hybrid/vector retrieval, near-duplicate ranking, sensitivity enforcement, automatic contradiction discovery, and deployment + +## Authority and compatibility + +Lessons remain in the existing iii-engine `mem:lessons` KV scope. Every write +continues through a registered AgentMemory function. This schema adds no +database, graph authority, migration worker, MCP tool, or REST endpoint. + +The JSON export envelope remains compatible with version `0.9.27`. New lesson +fields are optional in `ExportData`, so no package/export version bump is +required for this additive change. Export returns normalized schema-v1 lesson +records. Import validates and normalizes lesson records before any replace +mutation. + +Stored legacy lessons are not rewritten by reads. Recall, list, context, JSON +export, and Obsidian export normalize them in memory to: + +- `schemaVersion: 1` +- `evidenceVerdict: "unverified"` +- `lifecycle: "active"` unless correction metadata proves supersession or retraction +- `scope: { ring: "worktree" }` +- `sensitivity: "restricted"` +- empty structured arrays/maps +- a deterministic `contentFingerprint` + +The legacy `project` field remains a label and compatibility filter. It is not +used as a durable cross-repository join key for structured corrections. + +## Causal identity and claim + +A structured causal lesson uses: + +- `mechanismId`: canonical, lowercase mechanism identity +- `mechanismVersion`: optional version within that identity +- `mechanismAliases`: at most eight prior or alternate identities +- `claim`: a short falsifiable statement, separate from explanatory `content` +- `claimType`: `causal`, `predictive`, `procedural`, `constraint`, or `descriptive` + +If any causal structure is supplied, both `mechanismId` and `claim` are +required. Legacy prose-only saves remain valid. + +## Evidence verdict and lifecycle + +Evidence and lifecycle are independent: + +| Dimension | Values | Meaning | +| --- | --- | --- | +| `evidenceVerdict` | `supported`, `refuted`, `mixed`, `unverified` | Current evidence assessment | +| `lifecycle` | `draft`, `active`, `superseded`, `retracted` | Record publication/correction state | + +A refuted active lesson remains recallable negative evidence. Recall payloads +retain the verdict, and injected context labels it explicitly so refutation is +not presented as a supported instruction. Retraction means the evidence itself +is invalid. Supersession means another active lesson replaces this record. + +Normal save calls may create only draft or active records. Terminal lifecycle +changes reuse the audited correction functions: + +- `mem::lesson-supersede` sets `lifecycle: "superseded"` and preserves + `supersededByLessonId`. +- `mem::lesson-delete` is the backward-compatible retraction surface and sets + `lifecycle: "retracted"`. + +Both operations retain the legacy tombstone fields so older consumers continue +to exclude corrected lessons. + +## Applicability and facets + +The schema is domain-neutral: + +- `applicabilityConditions` +- `nonApplicabilityConditions` +- `falsificationConditions` +- `structuredFacets: Record` + +Facet dimensions are normalized to lowercase snake case. Values remain general +strings. Trading examples such as `asset`, `venue`, `horizon`, `regime`, and +`signal_family` are conventions, not hard-coded schema dimensions. + +Each condition list is bounded to 16 entries. Facets are bounded to 32 +dimensions and 16 values per dimension. + +## Durable evidence references + +`evidenceRefs` contains at most eight records. Each reference requires: + +- `kind` +- `projectId` as a label +- `repoRemoteUrl` +- at least one full immutable anchor: `commitSha` or `artifactDigest` +- `recordedAt` + +Optional fields are `path`, `validatedAt`, `evidenceKind`, and `sampleCount`. +A branch, ref, or path without a full commit SHA or artifact digest is rejected. +Supported, refuted, and mixed verdicts require at least one valid evidence +reference. + +## Scope and sensitivity + +`scope.ring` is one of: + +- `worktree` +- `repo` +- `initiative` +- `domain` +- `global` + +A structured causal lesson requires an explicit scope. A non-global scope +requires a separate durable `scope.scopeId`. `project`/`projectId` labels do +not substitute for it. Legacy prose lessons retain the fail-closed implicit +worktree scope for compatibility. + +Global scope requires: + +```json +{ + "ring": "global", + "humanApproval": { + "approvedBy": "human identity", + "approvedAt": "ISO-8601 timestamp", + "reason": "approval rationale" + } +} +``` + +Sensitivity is `public`, `internal`, `confidential`, or `restricted`, with a +fail-closed default of `restricted`. + +PR1 records and returns scope/sensitivity metadata but deliberately preserves +the existing project-based visibility behavior. Retrieval enforcement belongs +to PR2. Until that lands, callers must not treat `sensitivity` as an enforced +access-control boundary. + +## Confidence, reinforcement, staleness, and contradiction + +`confidence` remains an explicit evidence assessment. Duplicate saves and +`mem::lesson-strengthen` increment reinforcement metadata and update its +timestamp without changing confidence. + +Schema-v1 lessons are not confidence-decayed or soft-deleted by the legacy +decay sweep. `reviewAfter` computes `computedFlags.stale` at read time. The +optional `contradictedByLessonIds` relation metadata computes +`computedFlags.contradicted`. Neither flag changes lifecycle or confidence. + +Pre-schema stored lessons retain the old decay behavior until an explicit +replay/import normalizes them. This preserves backward compatibility without a +background rewrite. + +`computedFlags` is a read model only and is never persisted or accepted from +REST/MCP input. + +## Deterministic fingerprints + +Every normalized lesson returns `contentFingerprint`. + +For prose-only lessons, the fingerprint uses normalized prose. For structured +causal lessons, it uses mechanism ID/version, claim/type, applicability, +non-applicability, falsification conditions, and structured facets. Explanatory +prose, evidence verdict, evidence anchors, lifecycle, popularity, and +confidence do not alter the content fingerprint. + +Structured lesson IDs additionally include verdict, immutable evidence +references, lifecycle, scope, sensitivity, review deadline, and contradiction +links. This allows two records to share a causal content fingerprint while +preserving distinct evidence packages or verdicts for later near-duplicate +analysis. + +Object keys and unordered arrays are canonicalized before hashing. Fingerprint +comparison never relies on insertion order or raw `JSON.stringify` ordering. + +## Boundary behavior + +REST and MCP lesson-save handlers validate and whitelist structured fields +before calling `mem::lesson-save`. REST lesson search now whitelists its query +fields instead of forwarding the raw request body. + +JSON import validates all lessons, bounds the collection, rejects duplicate +lesson IDs, recomputes deterministic fingerprints, and completes validation +before a replace strategy deletes existing state. + +No retrieval or ranking engine is introduced in this PR. diff --git a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md index 5107c2f8b3..58acd2e2da 100644 --- a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md +++ b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md @@ -32,10 +32,10 @@ agentmemory exposes 60 MCP tools. 7 are in the lean core set (`--tools core` or | `memory_heal` | | `categories`: string, `dryRun`: string | Auto-fix all fixable issues found by diagnostics. Unblocks stuck actions, expires stale leases, cleans up orphaned data. | | `memory_insight_list` | | `project`: string, `minConfidence`: number, `limit`: number | List synthesized insights, higher-order observations derived from patterns across memories, lessons, and crystals. | | `memory_lease` | | `actionId`*: string, `agentId`*: string, `operation`*: string, `result`: string, `ttlMs`: number | Acquire, release, or renew an exclusive lease on an action. Prevents multiple agents from working on the same thing. | -| `memory_lesson_delete` | | `lessonId`*: string, `reason`*: string, `project`: string, `expectedUpdatedAt`: string, `actor`: string | Soft-delete one lesson by exact ID while preserving correction metadata and an audit trail. Requires a human-readable reason. | +| `memory_lesson_delete` | | `lessonId`*: string, `reason`*: string, `project`: string, `expectedUpdatedAt`: string, `actor`: string | Retract one lesson by exact ID when its evidence is invalid, preserving the legacy tombstone fields, correction metadata, and audit trail. Requires a human-readable reason. | | `memory_lesson_recall` | yes | `query`*: string, `project`: string, `minConfidence`: number, `limit`: number | Search lessons by query. Returns lessons sorted by confidence and recency. Use to check what the agent has learned before making decisions. | -| `memory_lesson_save` | yes | `content`*: string, `context`: string, `confidence`: number, `project`: string, `tags`: string | Save a lesson learned from this session. Lessons have confidence scores that strengthen when reinforced and decay when not used. Duplicate content auto-strengthens the existing lesson. | -| `memory_lesson_supersede` | | `lessonId`*: string, `replacementLessonId`*: string, `reason`*: string, `project`: string, `expectedUpdatedAt`: string, `actor`: string | Soft-delete one lesson in favor of an existing replacement lesson in the same project, preserving lineage and an audit trail. | +| `memory_lesson_save` | yes | `content`*: string, `context`: string, `confidence`: number, `project`: string, `tags`: string, `mechanismId`: string, `mechanismVersion`: string, `mechanismAliases`: array, `claim`: string, `claimType`: string, `evidenceVerdict`: string, `lifecycle`: string, `applicabilityConditions`: array, `nonApplicabilityConditions`: array, `falsificationConditions`: array, `structuredFacets`: object, `evidenceRefs`: array, `scope`: object, `sensitivity`: string, `reviewAfter`: string, `contradictedByLessonIds`: array | Save a legacy prose lesson or a structured causal lesson. Reinforcement tracks reuse without changing evidence confidence; structured inputs support verdict, lifecycle, durable evidence, scope, sensitivity, and deterministic fingerprints. | +| `memory_lesson_supersede` | | `lessonId`*: string, `replacementLessonId`*: string, `reason`*: string, `project`: string, `expectedUpdatedAt`: string, `actor`: string | Mark one lesson superseded in favor of an active replacement in the same durable scope, preserving legacy tombstone fields, lineage, and an audit trail. | | `memory_llm_smoke` | | none | Run a fixed, non-sensitive LLM connectivity probe. Returns provider/model evidence and performs no persistent AgentMemory or filesystem writes. | | `memory_mesh_sync` | | `peerId`: string, `direction`: string | Sync memories and actions with peer agentmemory instances for multi-agent collaboration. | | `memory_next` | | `project`: string, `agentId`: string | Get the single most important next action to work on. Combines dependency resolution, priority, and recency into a score. | diff --git a/src/functions/context.ts b/src/functions/context.ts index 1e6102cf37..1c1ab5825f 100644 --- a/src/functions/context.ts +++ b/src/functions/context.ts @@ -17,6 +17,10 @@ import { listPinnedSlots, renderPinnedContext, } from "./slots.js"; +import { + isLessonRecallable, + toLessonReadModel, +} from "./lesson-model.js"; function estimateTokens(text: string): number { return Math.ceil(text.length / 3); @@ -103,7 +107,12 @@ export function registerContextFunction( // 10 to keep the block bounded since the outer token-budget loop // below will drop the whole block if it doesn't fit. #457. const relevantLessons = lessons - .filter((l) => !l.deleted && (!l.project || l.project === data.project)) + .filter( + (lesson) => + isLessonRecallable(lesson) && + (!lesson.project || lesson.project === data.project), + ) + .map((lesson) => toLessonReadModel(lesson)) .sort((a, b) => { const scoreA = (a.project === data.project ? 1.5 : 1) * a.confidence; const scoreB = (b.project === data.project ? 1.5 : 1) * b.confidence; @@ -113,10 +122,11 @@ export function registerContextFunction( if (relevantLessons.length > 0) { const items = relevantLessons - .map( - (l) => - `- (${l.confidence.toFixed(2)}) ${l.content}${l.context ? ` — ${l.context}` : ""}`, - ) + .map((lesson) => { + const claim = lesson.claim ? `${lesson.claim} — ` : ""; + const context = lesson.context ? ` — ${lesson.context}` : ""; + return `- [verdict:${lesson.evidenceVerdict}] (${lesson.confidence.toFixed(2)}) ${claim}${lesson.content}${context}`; + }) .join("\n"); const lessonsContent = `## Lessons Learned\n${items}`; const mostRecent = relevantLessons.reduce((acc, l) => { diff --git a/src/functions/diagnostics.ts b/src/functions/diagnostics.ts index 18526a8632..935a5b9b2c 100644 --- a/src/functions/diagnostics.ts +++ b/src/functions/diagnostics.ts @@ -8,6 +8,7 @@ import { deleteActionEdge, persistAction, } from "./action-store.js"; +import { isLessonListable } from "./lesson-model.js"; import type { Action, ActionEdge, @@ -408,7 +409,7 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { // Catches bad confidence values that would silently break recall // scoring (memory_lesson_recall multiplies by confidence). const lessons = await kv.list(KV.lessons); - const live = lessons.filter((l) => !l.deleted); + const live = lessons.filter(isLessonListable); let lessonIssues = 0; for (const l of live) { // Number.isFinite rejects NaN / Infinity / non-numbers; a diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index aafb04c65d..ca982aadb6 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -40,6 +40,10 @@ import { readActionStoreSnapshot, withActionStoreLock, } from "./action-store.js"; +import { + normalizeLesson, + parseImportedLesson, +} from "./lesson-model.js"; export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::export", @@ -147,7 +151,10 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { sketches: sketches.length > 0 ? sketches : undefined, crystals: crystals.length > 0 ? crystals : undefined, facets: facets.length > 0 ? facets : undefined, - lessons: lessons.length > 0 ? lessons : undefined, + lessons: + lessons.length > 0 + ? lessons.map((lesson) => normalizeLesson(lesson)) + : undefined, insights: insights.length > 0 ? insights : undefined, routines: routines.length > 0 ? routines : undefined, signals: signals.length > 0 ? signals : undefined, @@ -212,6 +219,7 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { const MAX_ACTIONS = 100_000; const MAX_ACTION_EDGES = 250_000; const MAX_ACTION_EVENTS = 500_000; + const MAX_LESSONS = 100_000; if (!Array.isArray(importData.sessions)) { return { success: false, error: "sessions must be an array" }; @@ -277,6 +285,36 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { }; } + const importedLessons = importData.lessons ?? []; + if (!Array.isArray(importedLessons)) { + return { success: false, error: "lessons must be an array" }; + } + if (importedLessons.length > MAX_LESSONS) { + return { + success: false, + error: `Too many lessons (max ${MAX_LESSONS})`, + }; + } + const normalizedImportedLessons: Lesson[] = []; + const importedLessonIds = new Set(); + for (const lesson of importedLessons) { + const parsed = parseImportedLesson(lesson); + if (!parsed.success) { + return { + success: false, + error: `Invalid lesson: ${parsed.error}`, + }; + } + if (importedLessonIds.has(parsed.lesson.id)) { + return { + success: false, + error: `Duplicate lesson: ${parsed.lesson.id}`, + }; + } + importedLessonIds.add(parsed.lesson.id); + normalizedImportedLessons.push(parsed.lesson); + } + const importedActions = Array.isArray(importData.actions) ? importData.actions : []; @@ -431,6 +469,7 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { actions: 0, actionEdges: 0, actionEvents: 0, + lessons: 0, skipped: 0, }; @@ -780,14 +819,18 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { await kv.set(KV.facets, facet.id, facet); } } - if (importData.lessons) { - for (const lesson of importData.lessons) { - if (strategy === "skip") { - const existing = await kv.get(KV.lessons, lesson.id).catch(() => null); - if (existing) { stats.skipped++; continue; } + for (const lesson of normalizedImportedLessons) { + if (strategy === "skip") { + const existing = await kv + .get(KV.lessons, lesson.id) + .catch(() => null); + if (existing) { + stats.skipped++; + continue; } - await kv.set(KV.lessons, lesson.id, lesson); } + await kv.set(KV.lessons, lesson.id, lesson); + stats.lessons++; } if (importData.insights) { for (const insight of importData.insights) { diff --git a/src/functions/lesson-model.ts b/src/functions/lesson-model.ts new file mode 100644 index 0000000000..161e6a196a --- /dev/null +++ b/src/functions/lesson-model.ts @@ -0,0 +1,1111 @@ +import { fingerprintId } from "../state/schema.js"; +import type { + Lesson, + LessonClaimType, + LessonEvidenceReference, + LessonEvidenceVerdict, + LessonHumanApproval, + LessonLifecycle, + LessonReadModel, + LessonScope, + LessonScopeRing, + LessonSensitivity, + NormalizedLesson, +} from "../types.js"; + +export const LESSON_SCHEMA_VERSION = 1 as const; +export const MAX_LESSON_EVIDENCE_REFS = 8; + +const MAX_MECHANISM_ID_LENGTH = 128; +const MAX_MECHANISM_ALIASES = 8; +const MAX_CLAIM_LENGTH = 500; +const MAX_CONDITIONS = 16; +const MAX_CONDITION_LENGTH = 500; +const MAX_FACET_DIMENSIONS = 32; +const MAX_FACET_VALUES = 16; +const MAX_FACET_VALUE_LENGTH = 256; +const MAX_CONTRADICTION_IDS = 16; +const MAX_SCOPE_ID_LENGTH = 256; +const MAX_APPROVAL_REASON_LENGTH = 1000; +const MAX_EVIDENCE_KIND_LENGTH = 64; +const MAX_EVIDENCE_PROJECT_ID_LENGTH = 128; +const MAX_EVIDENCE_REMOTE_LENGTH = 2048; +const MAX_EVIDENCE_PATH_LENGTH = 1024; + +const EVIDENCE_VERDICTS = new Set([ + "supported", + "refuted", + "mixed", + "unverified", +]); +const LESSON_LIFECYCLES = new Set([ + "draft", + "active", + "superseded", + "retracted", +]); +const CLAIM_TYPES = new Set([ + "causal", + "predictive", + "procedural", + "constraint", + "descriptive", +]); +const SCOPE_RINGS = new Set([ + "worktree", + "repo", + "initiative", + "domain", + "global", +]); +const SENSITIVITIES = new Set([ + "public", + "internal", + "confidential", + "restricted", +]); + +export interface LessonSaveInput { + content: string; + context: string; + confidence?: number; + project?: string; + tags: string[]; + source: "crystal" | "manual" | "consolidation"; + sourceIds: string[]; + mechanismId?: string; + mechanismVersion?: string; + mechanismAliases: string[]; + claim?: string; + claimType?: LessonClaimType; + evidenceVerdict: LessonEvidenceVerdict; + lifecycle: LessonLifecycle; + applicabilityConditions: string[]; + nonApplicabilityConditions: string[]; + falsificationConditions: string[]; + structuredFacets: Record; + evidenceRefs: LessonEvidenceReference[]; + scope: LessonScope; + sensitivity: LessonSensitivity; + reviewAfter?: string; + contradictedByLessonIds: string[]; +} + +export type LessonInputParseResult = + | { success: true; value: LessonSaveInput } + | { success: false; error: string }; + +type LessonParseOptions = { + allowTerminalLifecycle?: boolean; + allowImplicitWorktreeScope?: boolean; + source?: "crystal" | "manual" | "consolidation"; + allowSourceMetadata?: boolean; +}; + +class LessonInputError extends Error {} + +export function parseLessonSaveInput( + raw: unknown, + options: LessonParseOptions = {}, +): LessonInputParseResult { + try { + const record = requireRecord(raw, "lesson"); + const content = requiredString(record.content, "content"); + const context = optionalString(record.context, "context") ?? ""; + const project = optionalString(record.project, "project"); + const confidence = normalizeConfidence(record.confidence); + const tags = normalizeStringArray(record.tags, "tags", { + allowCsv: true, + sort: false, + }); + const source = options.source ?? normalizeSource(record.source); + const sourceIds = + options.allowSourceMetadata === false + ? [] + : normalizeStringArray(record.sourceIds, "sourceIds", { + sort: true, + }); + + const mechanismId = normalizeMechanismId( + optionalString( + record.mechanismId, + "mechanismId", + MAX_MECHANISM_ID_LENGTH, + ), + "mechanismId", + ); + const mechanismVersion = optionalString( + record.mechanismVersion, + "mechanismVersion", + 64, + ); + const mechanismAliases = normalizeStringArray( + record.mechanismAliases, + "mechanismAliases", + { + maxItems: MAX_MECHANISM_ALIASES, + maxLength: MAX_MECHANISM_ID_LENGTH, + normalize: (value) => + normalizeMechanismId(value, "mechanismAliases") ?? "", + sort: true, + }, + ).filter((alias) => alias !== mechanismId); + const claim = optionalString(record.claim, "claim", MAX_CLAIM_LENGTH, true); + const claimType = normalizeEnum( + record.claimType, + "claimType", + CLAIM_TYPES, + ); + const evidenceVerdict = + normalizeEnum( + record.evidenceVerdict, + "evidenceVerdict", + EVIDENCE_VERDICTS, + ) ?? "unverified"; + const lifecycle = + normalizeEnum(record.lifecycle, "lifecycle", LESSON_LIFECYCLES) ?? + "active"; + if ( + !options.allowTerminalLifecycle && + (lifecycle === "superseded" || lifecycle === "retracted") + ) { + throw new LessonInputError( + "lifecycle superseded and retracted require the audited correction API", + ); + } + + const applicabilityConditions = normalizeStringArray( + record.applicabilityConditions, + "applicabilityConditions", + { + maxItems: MAX_CONDITIONS, + maxLength: MAX_CONDITION_LENGTH, + normalize: normalizeDisplayText, + sort: true, + }, + ); + const nonApplicabilityConditions = normalizeStringArray( + record.nonApplicabilityConditions, + "nonApplicabilityConditions", + { + maxItems: MAX_CONDITIONS, + maxLength: MAX_CONDITION_LENGTH, + normalize: normalizeDisplayText, + sort: true, + }, + ); + const falsificationConditions = normalizeStringArray( + record.falsificationConditions, + "falsificationConditions", + { + maxItems: MAX_CONDITIONS, + maxLength: MAX_CONDITION_LENGTH, + normalize: normalizeDisplayText, + sort: true, + }, + ); + const structuredFacets = normalizeStructuredFacets( + record.structuredFacets, + ); + const evidenceRefs = normalizeEvidenceRefs(record.evidenceRefs); + const scope = normalizeScope( + record.scope, + options.allowImplicitWorktreeScope === true, + ); + const sensitivity = + normalizeEnum( + record.sensitivity, + "sensitivity", + SENSITIVITIES, + ) ?? "restricted"; + const reviewAfter = optionalDate(record.reviewAfter, "reviewAfter"); + const contradictedByLessonIds = normalizeStringArray( + record.contradictedByLessonIds, + "contradictedByLessonIds", + { + maxItems: MAX_CONTRADICTION_IDS, + maxLength: MAX_MECHANISM_ID_LENGTH, + sort: true, + }, + ); + + const hasCausalStructure = + Boolean(mechanismId || mechanismVersion || claim || claimType) || + mechanismAliases.length > 0 || + applicabilityConditions.length > 0 || + nonApplicabilityConditions.length > 0 || + falsificationConditions.length > 0 || + Object.keys(structuredFacets).length > 0 || + evidenceRefs.length > 0; + if (hasCausalStructure && (!mechanismId || !claim)) { + throw new LessonInputError( + "structured causal lessons require both mechanismId and claim", + ); + } + if ( + hasCausalStructure && + (record.scope === undefined || record.scope === null) + ) { + throw new LessonInputError( + "structured causal lessons require an explicit durable scope", + ); + } + if ( + hasCausalStructure && + scope.ring !== "global" && + !scope.scopeId + ) { + throw new LessonInputError( + "structured causal lessons require scope.scopeId for non-global scopes", + ); + } + if (evidenceVerdict !== "unverified" && evidenceRefs.length === 0) { + throw new LessonInputError( + `${evidenceVerdict} lessons require at least one durable evidence reference`, + ); + } + + return { + success: true, + value: { + content: content.trim(), + context: context.trim(), + confidence, + project: project?.trim(), + tags, + source, + sourceIds, + mechanismId, + mechanismVersion: mechanismVersion?.trim(), + mechanismAliases, + claim, + claimType, + evidenceVerdict, + lifecycle, + applicabilityConditions, + nonApplicabilityConditions, + falsificationConditions, + structuredFacets, + evidenceRefs, + scope, + sensitivity, + reviewAfter, + contradictedByLessonIds, + }, + }; + } catch (error) { + return { + success: false, + error: error instanceof Error ? error.message : String(error), + }; + } +} + +export function lessonContentFingerprint(input: LessonSaveInput): string { + const material = + input.mechanismId && input.claim + ? { + mechanismId: input.mechanismId, + mechanismVersion: normalizeFingerprintText( + input.mechanismVersion ?? "", + ), + claim: normalizeFingerprintText(input.claim), + claimType: input.claimType ?? "", + applicabilityConditions: fingerprintStrings( + input.applicabilityConditions, + ), + nonApplicabilityConditions: fingerprintStrings( + input.nonApplicabilityConditions, + ), + falsificationConditions: fingerprintStrings( + input.falsificationConditions, + ), + structuredFacets: fingerprintFacets(input.structuredFacets), + } + : { content: normalizeFingerprintText(input.content) }; + return fingerprintId("lfp", stableStringify(material)); +} + +export function lessonIdForInput(input: LessonSaveInput): string { + if (!input.mechanismId || !input.claim) { + return fingerprintId("lsn", input.content.trim().toLowerCase()); + } + return fingerprintId( + "lsn", + stableStringify({ + contentFingerprint: lessonContentFingerprint(input), + evidenceVerdict: input.evidenceVerdict, + evidenceRefs: input.evidenceRefs, + lifecycle: input.lifecycle, + scope: input.scope, + sensitivity: input.sensitivity, + reviewAfter: input.reviewAfter, + contradictedByLessonIds: input.contradictedByLessonIds, + }), + ); +} + +export function normalizeLesson(lesson: Lesson): NormalizedLesson { + const lifecycle = deriveLifecycle(lesson); + const parsed = parseLessonSaveInput( + { + ...lesson, + lifecycle, + }, + { + allowTerminalLifecycle: true, + allowImplicitWorktreeScope: true, + }, + ); + const fallback = parseLessonSaveInput( + { + content: + typeof lesson.content === "string" && lesson.content.trim() + ? lesson.content + : lesson.id || "legacy-lesson", + context: typeof lesson.context === "string" ? lesson.context : "", + confidence: lesson.confidence, + project: lesson.project, + tags: Array.isArray(lesson.tags) ? lesson.tags : [], + source: lesson.source, + sourceIds: Array.isArray(lesson.sourceIds) ? lesson.sourceIds : [], + lifecycle, + }, + { + allowTerminalLifecycle: true, + allowImplicitWorktreeScope: true, + }, + ); + if (!fallback.success) { + throw new Error(`Invalid legacy lesson ${lesson.id}: ${fallback.error}`); + } + const value = parsed.success ? parsed.value : fallback.value; + const normalized: NormalizedLesson = { + ...lesson, + content: value.content, + context: value.context, + confidence: + typeof lesson.confidence === "number" && + Number.isFinite(lesson.confidence) + ? lesson.confidence + : value.confidence ?? 0.5, + reinforcements: + Number.isInteger(lesson.reinforcements) && lesson.reinforcements >= 0 + ? lesson.reinforcements + : 0, + source: value.source, + sourceIds: value.sourceIds, + project: value.project, + tags: value.tags, + decayRate: + typeof lesson.decayRate === "number" && + Number.isFinite(lesson.decayRate) + ? lesson.decayRate + : 0.05, + schemaVersion: LESSON_SCHEMA_VERSION, + mechanismId: value.mechanismId, + mechanismVersion: value.mechanismVersion, + mechanismAliases: value.mechanismAliases, + claim: value.claim, + claimType: value.claimType, + evidenceVerdict: value.evidenceVerdict, + lifecycle, + applicabilityConditions: value.applicabilityConditions, + nonApplicabilityConditions: value.nonApplicabilityConditions, + falsificationConditions: value.falsificationConditions, + structuredFacets: value.structuredFacets, + evidenceRefs: value.evidenceRefs, + scope: value.scope, + sensitivity: value.sensitivity, + reviewAfter: value.reviewAfter, + contradictedByLessonIds: value.contradictedByLessonIds, + contentFingerprint: lessonContentFingerprint(value), + }; + return normalized; +} + +export function toLessonReadModel( + lesson: Lesson, + now: number | string | Date = Date.now(), +): LessonReadModel { + const normalized = normalizeLesson(lesson); + const nowMs = + now instanceof Date + ? now.getTime() + : typeof now === "string" + ? Date.parse(now) + : now; + const reviewAfterMs = normalized.reviewAfter + ? Date.parse(normalized.reviewAfter) + : Number.NaN; + return { + ...normalized, + computedFlags: { + stale: + normalized.deleteReason === "decay-sweep" || + (Number.isFinite(reviewAfterMs) && + Number.isFinite(nowMs) && + nowMs >= reviewAfterMs), + contradicted: normalized.contradictedByLessonIds.length > 0, + }, + }; +} + +export function isLessonListable(lesson: Lesson): boolean { + const normalized = normalizeLesson(lesson); + return ( + !lesson.deleted && + normalized.lifecycle !== "superseded" && + normalized.lifecycle !== "retracted" + ); +} + +export function isLessonRecallable(lesson: Lesson): boolean { + const normalized = normalizeLesson(lesson); + return !lesson.deleted && normalized.lifecycle === "active"; +} + +export function parseImportedLesson( + raw: unknown, +): { success: true; lesson: NormalizedLesson } | { success: false; error: string } { + try { + const record = requireRecord(raw, "lesson"); + const id = requiredString(record.id, "lesson.id"); + const createdAt = requiredDate(record.createdAt, "lesson.createdAt"); + const updatedAt = requiredDate(record.updatedAt, "lesson.updatedAt"); + if ( + record.schemaVersion !== undefined && + record.schemaVersion !== LESSON_SCHEMA_VERSION + ) { + throw new LessonInputError( + `lesson.schemaVersion must be ${LESSON_SCHEMA_VERSION}`, + ); + } + if (record.deleted !== undefined && typeof record.deleted !== "boolean") { + throw new LessonInputError("lesson.deleted must be a boolean"); + } + const parsed = parseLessonSaveInput(record, { + allowTerminalLifecycle: true, + allowImplicitWorktreeScope: true, + }); + if (!parsed.success) throw new LessonInputError(parsed.error); + + const deletedAt = optionalDate(record.deletedAt, "lesson.deletedAt"); + const lastReinforcedAt = optionalDate( + record.lastReinforcedAt, + "lesson.lastReinforcedAt", + ); + const lastDecayedAt = optionalDate( + record.lastDecayedAt, + "lesson.lastDecayedAt", + ); + const deletedBy = optionalString(record.deletedBy, "lesson.deletedBy"); + const deleteReason = optionalString( + record.deleteReason, + "lesson.deleteReason", + 1000, + ); + const supersededByLessonId = optionalString( + record.supersededByLessonId, + "lesson.supersededByLessonId", + MAX_MECHANISM_ID_LENGTH, + ); + const terminalLifecycle = + parsed.value.lifecycle === "superseded" || + parsed.value.lifecycle === "retracted"; + if ( + (terminalLifecycle || Boolean(supersededByLessonId)) && + record.deleted !== true + ) { + throw new LessonInputError( + "terminal lessons must retain deleted=true for legacy compatibility", + ); + } + if ( + parsed.value.lifecycle === "superseded" && + !supersededByLessonId + ) { + throw new LessonInputError( + "superseded lessons require supersededByLessonId", + ); + } + if (supersededByLessonId === id) { + throw new LessonInputError( + "supersededByLessonId must differ from lesson.id", + ); + } + + const candidate: Lesson = { + id, + content: parsed.value.content, + context: parsed.value.context, + confidence: parsed.value.confidence ?? 0.5, + reinforcements: + typeof record.reinforcements === "number" && + Number.isInteger(record.reinforcements) && + record.reinforcements >= 0 + ? record.reinforcements + : 0, + source: parsed.value.source, + sourceIds: parsed.value.sourceIds, + project: parsed.value.project, + tags: parsed.value.tags, + createdAt, + updatedAt, + lastReinforcedAt, + lastDecayedAt, + decayRate: + typeof record.decayRate === "number" && + Number.isFinite(record.decayRate) + ? record.decayRate + : 0.05, + deleted: record.deleted as boolean | undefined, + deletedAt, + deletedBy, + deleteReason, + supersededByLessonId, + schemaVersion: LESSON_SCHEMA_VERSION, + mechanismId: parsed.value.mechanismId, + mechanismVersion: parsed.value.mechanismVersion, + mechanismAliases: parsed.value.mechanismAliases, + claim: parsed.value.claim, + claimType: parsed.value.claimType, + evidenceVerdict: parsed.value.evidenceVerdict, + lifecycle: parsed.value.lifecycle, + applicabilityConditions: parsed.value.applicabilityConditions, + nonApplicabilityConditions: parsed.value.nonApplicabilityConditions, + falsificationConditions: parsed.value.falsificationConditions, + structuredFacets: parsed.value.structuredFacets, + evidenceRefs: parsed.value.evidenceRefs, + scope: parsed.value.scope, + sensitivity: parsed.value.sensitivity, + reviewAfter: parsed.value.reviewAfter, + contradictedByLessonIds: parsed.value.contradictedByLessonIds, + contentFingerprint: lessonContentFingerprint(parsed.value), + }; + return { success: true, lesson: normalizeLesson(candidate) }; + } catch (error) { + return { + success: false, + error: error instanceof Error ? error.message : String(error), + }; + } +} + +export function sameLessonScope(left: Lesson, right: Lesson): boolean { + const normalizedLeft = normalizeLesson(left); + const normalizedRight = normalizeLesson(right); + const leftScope = normalizedLeft.scope; + const rightScope = normalizedRight.scope; + if (leftScope.scopeId || rightScope.scopeId) { + return ( + leftScope.ring === rightScope.ring && + leftScope.scopeId === rightScope.scopeId + ); + } + if (leftScope.ring === "global" || rightScope.ring === "global") { + return leftScope.ring === "global" && rightScope.ring === "global"; + } + if ( + normalizedLeft.mechanismId || + normalizedLeft.claim || + normalizedRight.mechanismId || + normalizedRight.claim + ) { + return false; + } + return left.project === right.project; +} + +function normalizeConfidence(value: unknown): number | undefined { + if (value === undefined || value === null) return undefined; + if (typeof value !== "number") { + throw new LessonInputError("confidence must be a number"); + } + if (!Number.isFinite(value) || value < 0 || value > 1) return undefined; + return value; +} + +function normalizeSource( + value: unknown, +): "crystal" | "manual" | "consolidation" { + if (value === undefined || value === null || value === "") return "manual"; + if ( + value === "crystal" || + value === "manual" || + value === "consolidation" + ) { + return value; + } + throw new LessonInputError( + "source must be crystal, manual, or consolidation", + ); +} + +function normalizeScope( + value: unknown, + allowImplicitWorktreeScope = false, +): LessonScope { + if (value === undefined || value === null) return { ring: "worktree" }; + const record = requireRecord(value, "scope"); + const ring = normalizeEnum(record.ring, "scope.ring", SCOPE_RINGS); + if (!ring) throw new LessonInputError("scope.ring is required"); + const scopeId = optionalString( + record.scopeId, + "scope.scopeId", + MAX_SCOPE_ID_LENGTH, + ); + if ( + ring !== "global" && + !scopeId && + !(allowImplicitWorktreeScope && ring === "worktree") + ) { + throw new LessonInputError( + "scope.scopeId is required for non-global explicit scopes", + ); + } + + let humanApproval: LessonHumanApproval | undefined; + if (record.humanApproval !== undefined && record.humanApproval !== null) { + const approval = requireRecord( + record.humanApproval, + "scope.humanApproval", + ); + humanApproval = { + approvedBy: requiredString( + approval.approvedBy, + "scope.humanApproval.approvedBy", + ), + approvedAt: requiredDate( + approval.approvedAt, + "scope.humanApproval.approvedAt", + ), + reason: requiredString( + approval.reason, + "scope.humanApproval.reason", + MAX_APPROVAL_REASON_LENGTH, + ), + }; + } + if (ring === "global" && !humanApproval) { + throw new LessonInputError( + "global scope requires explicit scope.humanApproval metadata", + ); + } + return { + ring, + scopeId: scopeId?.trim(), + humanApproval, + }; +} + +function normalizeStructuredFacets( + value: unknown, +): Record { + if (value === undefined || value === null) return {}; + const record = requireRecord(value, "structuredFacets"); + const entries = Object.entries(record); + if (entries.length > MAX_FACET_DIMENSIONS) { + throw new LessonInputError( + `structuredFacets must have at most ${MAX_FACET_DIMENSIONS} dimensions`, + ); + } + const normalized: Record = {}; + for (const [rawDimension, rawValues] of entries) { + const dimension = rawDimension + .trim() + .toLowerCase() + .replace(/[\s-]+/g, "_"); + if (!dimension || dimension.length > 64) { + throw new LessonInputError( + "structuredFacets dimensions must be 1-64 characters", + ); + } + const values = normalizeStringArray( + rawValues, + `structuredFacets.${rawDimension}`, + { + maxItems: MAX_FACET_VALUES, + maxLength: MAX_FACET_VALUE_LENGTH, + normalize: normalizeDisplayText, + sort: true, + }, + ); + const mergedValues = [ + ...new Set([...(normalized[dimension] ?? []), ...values]), + ].sort(compareText); + if (mergedValues.length > MAX_FACET_VALUES) { + throw new LessonInputError( + `structuredFacets.${dimension} must contain at most ${MAX_FACET_VALUES} values after normalization`, + ); + } + normalized[dimension] = mergedValues; + } + return Object.fromEntries( + Object.entries(normalized).sort(([left], [right]) => + compareText(left, right), + ), + ); +} + +function normalizeEvidenceRefs(value: unknown): LessonEvidenceReference[] { + if (value === undefined || value === null) return []; + if (!Array.isArray(value)) { + throw new LessonInputError("evidenceRefs must be an array"); + } + if (value.length > MAX_LESSON_EVIDENCE_REFS) { + throw new LessonInputError( + `evidenceRefs must contain at most ${MAX_LESSON_EVIDENCE_REFS} items`, + ); + } + const refs = value.map((rawRef, index) => + normalizeEvidenceRef(rawRef, index), + ); + const unique = new Map( + refs.map((ref) => [stableStringify(ref), ref] as const), + ); + return [...unique.values()].sort((left, right) => + compareText(stableStringify(left), stableStringify(right)), + ); +} + +function normalizeEvidenceRef( + value: unknown, + index: number, +): LessonEvidenceReference { + const record = requireRecord(value, `evidenceRefs[${index}]`); + const prefix = `evidenceRefs[${index}]`; + const kind = normalizeSlug( + requiredString(record.kind, `${prefix}.kind`, MAX_EVIDENCE_KIND_LENGTH), + `${prefix}.kind`, + ); + const projectId = requiredString( + record.projectId, + `${prefix}.projectId`, + MAX_EVIDENCE_PROJECT_ID_LENGTH, + ); + const repoRemoteUrl = normalizeRepoRemote( + requiredString( + record.repoRemoteUrl, + `${prefix}.repoRemoteUrl`, + MAX_EVIDENCE_REMOTE_LENGTH, + ), + `${prefix}.repoRemoteUrl`, + ); + const commitSha = normalizeCommitSha( + optionalString(record.commitSha, `${prefix}.commitSha`, 64), + `${prefix}.commitSha`, + ); + const artifactDigest = normalizeArtifactDigest( + optionalString(record.artifactDigest, `${prefix}.artifactDigest`, 256), + `${prefix}.artifactDigest`, + ); + if (!commitSha && !artifactDigest) { + throw new LessonInputError( + `${prefix} requires commitSha and/or artifactDigest; branch, ref, and path are not immutable proof`, + ); + } + const path = normalizeEvidencePath( + optionalString(record.path, `${prefix}.path`, MAX_EVIDENCE_PATH_LENGTH), + `${prefix}.path`, + ); + const recordedAt = requiredDate(record.recordedAt, `${prefix}.recordedAt`); + const validatedAt = optionalDate( + record.validatedAt, + `${prefix}.validatedAt`, + ); + const evidenceKindRaw = optionalString( + record.evidenceKind, + `${prefix}.evidenceKind`, + MAX_EVIDENCE_KIND_LENGTH, + ); + const evidenceKind = evidenceKindRaw + ? normalizeSlug(evidenceKindRaw, `${prefix}.evidenceKind`) + : undefined; + let sampleCount: number | undefined; + if (record.sampleCount !== undefined && record.sampleCount !== null) { + if ( + typeof record.sampleCount !== "number" || + !Number.isInteger(record.sampleCount) || + record.sampleCount < 0 + ) { + throw new LessonInputError( + `${prefix}.sampleCount must be a non-negative integer`, + ); + } + sampleCount = record.sampleCount; + } + return { + kind, + projectId: projectId.trim(), + repoRemoteUrl, + commitSha, + artifactDigest, + path, + recordedAt, + validatedAt, + evidenceKind, + sampleCount, + }; +} + +function normalizeRepoRemote(value: string, field: string): string { + const trimmed = value.trim(); + const urlStyle = /^(https?|ssh|git):\/\/[^\s]+$/i.test(trimmed); + const scpStyle = /^[^@\s]+@[^:\s]+:[^\s]+$/.test(trimmed); + if (!urlStyle && !scpStyle) { + throw new LessonInputError( + `${field} must be a durable http(s), ssh, git, or scp-style remote URL`, + ); + } + return trimmed.replace(/\/+$/, "").replace(/\.git$/i, ""); +} + +function normalizeCommitSha( + value: string | undefined, + field: string, +): string | undefined { + if (!value) return undefined; + const normalized = value.trim().toLowerCase(); + if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(normalized)) { + throw new LessonInputError( + `${field} must be a full 40- or 64-character hexadecimal commit SHA`, + ); + } + return normalized; +} + +function normalizeArtifactDigest( + value: string | undefined, + field: string, +): string | undefined { + if (!value) return undefined; + const normalized = value.trim().toLowerCase(); + if (!/^[a-z0-9][a-z0-9+._-]*:[a-f0-9]{32,}$/.test(normalized)) { + throw new LessonInputError( + `${field} must be an algorithm-prefixed hexadecimal digest`, + ); + } + return normalized; +} + +function normalizeEvidencePath( + value: string | undefined, + field: string, +): string | undefined { + if (!value) return undefined; + const normalized = value.replace(/\\/g, "/").replace(/^\.\//, ""); + if ( + normalized.startsWith("/") || + normalized.split("/").includes("..") || + normalized.includes("\0") + ) { + throw new LessonInputError( + `${field} must be a relative repository or artifact path`, + ); + } + return normalized; +} + +function normalizeMechanismId( + value: string | undefined, + field: string, +): string | undefined { + if (!value) return undefined; + const normalized = value.trim().toLowerCase(); + if (!/^[a-z0-9][a-z0-9._:/-]*$/.test(normalized)) { + throw new LessonInputError( + `${field} must use lowercase letters, numbers, dot, underscore, colon, slash, or hyphen`, + ); + } + return normalized; +} + +function normalizeSlug(value: string, field: string): string { + const normalized = value.trim().toLowerCase(); + if (!/^[a-z0-9][a-z0-9._-]*$/.test(normalized)) { + throw new LessonInputError( + `${field} must use letters, numbers, dot, underscore, or hyphen`, + ); + } + return normalized; +} + +function normalizeStringArray( + value: unknown, + field: string, + options: { + allowCsv?: boolean; + maxItems?: number; + maxLength?: number; + normalize?: (value: string) => string; + sort?: boolean; + } = {}, +): string[] { + if (value === undefined || value === null || value === "") return []; + const rawValues = + options.allowCsv && typeof value === "string" + ? value.split(",") + : Array.isArray(value) + ? value + : null; + if (!rawValues) { + throw new LessonInputError(`${field} must be an array of strings`); + } + if ( + options.maxItems !== undefined && + rawValues.length > options.maxItems + ) { + throw new LessonInputError( + `${field} must contain at most ${options.maxItems} items`, + ); + } + const normalized: string[] = []; + for (const item of rawValues) { + if (typeof item !== "string") { + throw new LessonInputError(`${field} must contain only strings`); + } + const valueText = (options.normalize ?? ((text: string) => text.trim()))( + item, + ); + if (!valueText) continue; + if ( + options.maxLength !== undefined && + valueText.length > options.maxLength + ) { + throw new LessonInputError( + `${field} items must be at most ${options.maxLength} characters`, + ); + } + normalized.push(valueText); + } + const unique = [...new Set(normalized)]; + return options.sort + ? unique.sort(compareText) + : unique; +} + +function normalizeEnum( + value: unknown, + field: string, + allowed: Set, +): T | undefined { + if (value === undefined || value === null || value === "") return undefined; + if (typeof value !== "string" || !allowed.has(value as T)) { + throw new LessonInputError( + `${field} must be one of: ${[...allowed].join(", ")}`, + ); + } + return value as T; +} + +function deriveLifecycle(lesson: Lesson): LessonLifecycle { + if (lesson.supersededByLessonId) return "superseded"; + if (lesson.deleted && lesson.deleteReason !== "decay-sweep") { + return "retracted"; + } + return LESSON_LIFECYCLES.has(lesson.lifecycle as LessonLifecycle) + ? (lesson.lifecycle as LessonLifecycle) + : "active"; +} + +function requireRecord(value: unknown, field: string): Record { + if (!value || typeof value !== "object" || Array.isArray(value)) { + throw new LessonInputError(`${field} must be an object`); + } + return value as Record; +} + +function requiredString( + value: unknown, + field: string, + maxLength?: number, +): string { + const normalized = optionalString(value, field, maxLength); + if (!normalized) throw new LessonInputError(`${field} is required`); + return normalized; +} + +function optionalString( + value: unknown, + field: string, + maxLength?: number, + collapseWhitespace = false, +): string | undefined { + if (value === undefined || value === null || value === "") return undefined; + if (typeof value !== "string") { + throw new LessonInputError(`${field} must be a string`); + } + const normalized = collapseWhitespace + ? normalizeDisplayText(value) + : value.trim(); + if (!normalized) return undefined; + if (maxLength !== undefined && normalized.length > maxLength) { + throw new LessonInputError( + `${field} must be at most ${maxLength} characters`, + ); + } + return normalized; +} + +function requiredDate(value: unknown, field: string): string { + const normalized = optionalDate(value, field); + if (!normalized) throw new LessonInputError(`${field} is required`); + return normalized; +} + +function optionalDate(value: unknown, field: string): string | undefined { + if (value === undefined || value === null || value === "") return undefined; + if (typeof value !== "string") { + throw new LessonInputError(`${field} must be an ISO timestamp string`); + } + const parsed = Date.parse(value); + if (!Number.isFinite(parsed)) { + throw new LessonInputError(`${field} must be a valid ISO timestamp`); + } + return new Date(parsed).toISOString(); +} + +function normalizeDisplayText(value: string): string { + return value.trim().replace(/\s+/g, " "); +} + +function normalizeFingerprintText(value: string): string { + return normalizeDisplayText(value).toLowerCase(); +} + +function fingerprintStrings(values: string[]): string[] { + return [...new Set(values.map(normalizeFingerprintText))].sort(compareText); +} + +function fingerprintFacets( + facets: Record, +): Record { + return Object.fromEntries( + Object.entries(facets) + .map(([dimension, values]) => [ + dimension.toLowerCase(), + fingerprintStrings(values), + ] as const) + .sort(([left], [right]) => compareText(left, right)), + ); +} + +function stableStringify(value: unknown): string { + return JSON.stringify(sortJsonValue(value)) ?? "null"; +} + +function sortJsonValue(value: unknown): unknown { + if (Array.isArray(value)) return value.map(sortJsonValue); + if (!value || typeof value !== "object") return value; + return Object.fromEntries( + Object.entries(value as Record) + .filter(([, item]) => item !== undefined) + .sort(([left], [right]) => compareText(left, right)) + .map(([key, item]) => [key, sortJsonValue(item)]), + ); +} + +function compareText(left: string, right: string): number { + return left < right ? -1 : left > right ? 1 : 0; +} diff --git a/src/functions/lessons.ts b/src/functions/lessons.ts index 7a5b4544b1..7f13413765 100644 --- a/src/functions/lessons.ts +++ b/src/functions/lessons.ts @@ -1,9 +1,20 @@ import type { ISdk } from "iii-sdk"; import type { StateKV } from "../state/kv.js"; -import { KV, fingerprintId } from "../state/schema.js"; +import { KV } from "../state/schema.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import type { Lesson } from "../types.js"; import { recordAudit } from "./audit.js"; +import { + LESSON_SCHEMA_VERSION, + isLessonListable, + isLessonRecallable, + lessonContentFingerprint, + lessonIdForInput, + normalizeLesson, + parseLessonSaveInput, + sameLessonScope, + toLessonReadModel, +} from "./lesson-model.js"; const MAX_LESSON_LIST_LIMIT = 500; const MAX_CORRECTION_REASON_LENGTH = 1000; @@ -23,10 +34,6 @@ type LessonCorrectionMode = "delete" | "supersede"; function reinforceLesson(lesson: Lesson): void { const now = new Date().toISOString(); lesson.reinforcements++; - lesson.confidence = Math.min( - 1.0, - lesson.confidence + 0.1 * (1 - lesson.confidence), - ); lesson.lastReinforcedAt = now; lesson.updatedAt = now; } @@ -105,10 +112,13 @@ async function correctLesson( return correctionFailure("lesson_not_found", "lesson not found"); } - if (lesson.deleted) { + const normalizedLesson = normalizeLesson(lesson); + if (!isLessonListable(lesson)) { const sameCorrection = lesson.deleteReason === reason && - lesson.supersededByLessonId === replacementLessonId; + lesson.supersededByLessonId === replacementLessonId && + normalizedLesson.lifecycle === + (mode === "supersede" ? "superseded" : "retracted"); if (sameCorrection) { return { success: true, @@ -116,7 +126,7 @@ async function correctLesson( mode === "supersede" ? "already_superseded" : "already_deleted", - lesson, + lesson: toLessonReadModel(lesson), }; } return correctionFailure( @@ -146,16 +156,24 @@ async function correctLesson( KV.lessons, replacementLessonId, ); - if (!replacement || replacement.deleted) { + if (!replacement) { return correctionFailure( "replacement_not_found", "replacement lesson not found", ); } - if (replacement.project !== lesson.project) { + if (!isLessonRecallable(replacement)) { + return correctionFailure( + "replacement_not_active", + "replacement lesson must be active", + ); + } + if (!sameLessonScope(replacement, lesson)) { return correctionFailure( - "project_mismatch", - "replacement lesson must belong to the same project", + replacement.scope?.scopeId || lesson.scope?.scopeId + ? "scope_mismatch" + : "project_mismatch", + "replacement lesson must belong to the same durable scope", ); } } @@ -166,6 +184,8 @@ async function correctLesson( lesson.deletedBy = actor; lesson.deleteReason = reason; lesson.supersededByLessonId = replacementLessonId; + lesson.lifecycle = + mode === "supersede" ? "superseded" : "retracted"; lesson.updatedAt = timestamp; await kv.set(KV.lessons, lesson.id, lesson); @@ -185,87 +205,104 @@ async function correctLesson( return { success: true, action: mode === "supersede" ? "superseded" : "deleted", - lesson, + lesson: toLessonReadModel(lesson), }; }); } export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::lesson-save", - async (data: { - content: string; - context?: string; - confidence?: number; - project?: string; - tags?: string[]; - source?: "crystal" | "manual" | "consolidation"; - sourceIds?: string[]; - }) => { - if (!data.content?.trim()) { - return { success: false, error: "content is required" }; + async (data: unknown) => { + const parsed = parseLessonSaveInput(data); + if (!parsed.success) { + return correctionFailure("invalid_request", parsed.error); } + const input = parsed.value; - const fp = fingerprintId("lsn", data.content.trim().toLowerCase()); + const fp = lessonIdForInput(input); return withKeyedLock(lessonLockKey(fp), async () => { const existing = await kv.get(KV.lessons, fp); - if (existing?.deleted) { + if (existing && !isLessonListable(existing)) { return correctionFailure( "lesson_deleted", - "lesson is deleted; save corrected content as a new lesson", + "lesson is superseded or retracted; save corrected evidence as a new lesson", ); } if (existing) { reinforceLesson(existing); - if (data.context && !existing.context) { - existing.context = data.context; + if (input.context && !existing.context) { + existing.context = input.context; } await kv.set(KV.lessons, existing.id, existing); try { - await recordAudit(kv, "lesson_strengthen", "mem::lesson-save", [ - existing.id, - ]); + await recordAudit( + kv, + "lesson_strengthen", + "mem::lesson-save", + [existing.id], + { confidenceChanged: false }, + ); } catch {} return { success: true, action: "strengthened", - lesson: existing, + lesson: toLessonReadModel(existing), }; } - const confidence = - typeof data.confidence === "number" && - data.confidence >= 0 && - data.confidence <= 1 - ? data.confidence - : 0.5; - const now = new Date().toISOString(); const lesson: Lesson = { id: fp, - content: data.content.trim(), - context: data.context?.trim() || "", - confidence, + content: input.content, + context: input.context, + confidence: input.confidence ?? 0.5, reinforcements: 0, - source: data.source || "manual", - sourceIds: data.sourceIds || [], - project: data.project, - tags: data.tags || [], + source: input.source, + sourceIds: input.sourceIds, + project: input.project, + tags: input.tags, createdAt: now, updatedAt: now, decayRate: 0.05, + schemaVersion: LESSON_SCHEMA_VERSION, + mechanismId: input.mechanismId, + mechanismVersion: input.mechanismVersion, + mechanismAliases: input.mechanismAliases, + claim: input.claim, + claimType: input.claimType, + evidenceVerdict: input.evidenceVerdict, + lifecycle: input.lifecycle, + applicabilityConditions: input.applicabilityConditions, + nonApplicabilityConditions: input.nonApplicabilityConditions, + falsificationConditions: input.falsificationConditions, + structuredFacets: input.structuredFacets, + evidenceRefs: input.evidenceRefs, + scope: input.scope, + sensitivity: input.sensitivity, + reviewAfter: input.reviewAfter, + contradictedByLessonIds: input.contradictedByLessonIds, + contentFingerprint: lessonContentFingerprint(input), }; await kv.set(KV.lessons, lesson.id, lesson); try { - await recordAudit(kv, "lesson_save", "mem::lesson-save", [lesson.id]); + await recordAudit(kv, "lesson_save", "mem::lesson-save", [lesson.id], { + contentFingerprint: lesson.contentFingerprint, + evidenceVerdict: lesson.evidenceVerdict, + lifecycle: lesson.lifecycle, + }); } catch {} - return { success: true, action: "created", lesson }; + return { + success: true, + action: "created", + lesson: toLessonReadModel(lesson), + }; }); }, ); @@ -285,11 +322,12 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { const minConfidence = data.minConfidence ?? 0.1; const limit = data.limit ?? 10; - let lessons = await kv.list(KV.lessons); + const storedLessons = await kv.list(KV.lessons); + let lessons = storedLessons + .filter(isLessonRecallable) + .map((lesson) => toLessonReadModel(lesson)); - lessons = lessons.filter( - (l) => !l.deleted && l.confidence >= minConfidence, - ); + lessons = lessons.filter((l) => l.confidence >= minConfidence); if (data.project) { lessons = lessons.filter((l) => l.project === data.project); @@ -297,7 +335,24 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { const scored = lessons .map((l) => { - const text = `${l.content} ${l.context} ${l.tags.join(" ")}`.toLowerCase(); + const facetText = Object.entries(l.structuredFacets) + .flatMap(([dimension, values]) => [dimension, ...values]) + .join(" "); + const text = [ + l.content, + l.context, + l.claim, + l.mechanismId, + ...l.mechanismAliases, + ...l.applicabilityConditions, + ...l.nonApplicabilityConditions, + ...l.falsificationConditions, + facetText, + ...l.tags, + ] + .filter(Boolean) + .join(" ") + .toLowerCase(); const terms = query.split(/\s+/).filter((t) => t.length > 1); const matchCount = terms.filter((t) => text.includes(t)).length; if (matchCount === 0) return null; @@ -366,11 +421,11 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { } const limit = Math.min(requestedLimit, MAX_LESSON_LIST_LIMIT); const minConfidence = data.minConfidence ?? 0; - let lessons = await kv.list(KV.lessons); - - lessons = lessons.filter( - (l) => !l.deleted && l.confidence >= minConfidence, - ); + const storedLessons = await kv.list(KV.lessons); + let lessons = storedLessons + .filter(isLessonListable) + .map((lesson) => toLessonReadModel(lesson)) + .filter((lesson) => lesson.confidence >= minConfidence); if (data.project) { lessons = lessons.filter((l) => l.project === data.project); @@ -411,7 +466,7 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { return withKeyedLock(lessonLockKey(data.lessonId), async () => { const lesson = await kv.get(KV.lessons, data.lessonId); - if (!lesson || lesson.deleted) { + if (!lesson || !isLessonListable(lesson)) { return { success: false, error: "lesson not found" }; } @@ -420,12 +475,16 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { await kv.set(KV.lessons, lesson.id, lesson); try { - await recordAudit(kv, "lesson_strengthen", "mem::lesson-strengthen", [ - lesson.id, - ]); + await recordAudit( + kv, + "lesson_strengthen", + "mem::lesson-strengthen", + [lesson.id], + { confidenceChanged: false }, + ); } catch {} - return { success: true, lesson }; + return { success: true, lesson: toLessonReadModel(lesson) }; }); }, ); @@ -451,6 +510,12 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { const lesson = await kv.get(KV.lessons, listedLesson.id); if (!lesson || lesson.deleted) return null; + if (lesson.schemaVersion === LESSON_SCHEMA_VERSION) { + return toLessonReadModel(lesson, now).computedFlags.stale + ? "stale" + : null; + } + const baseline = lesson.lastDecayedAt || lesson.lastReinforcedAt || @@ -511,8 +576,15 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { const softDeleted = outcomes.filter( (outcome) => outcome === "soft-delete", ).length; + const stale = outcomes.filter((outcome) => outcome === "stale").length; - return { success: true, decayed, softDeleted, total: lessons.length }; + return { + success: true, + decayed, + softDeleted, + stale, + total: lessons.length, + }; }, ); } diff --git a/src/functions/obsidian-export.ts b/src/functions/obsidian-export.ts index 0e8194813a..4058a1c1ef 100644 --- a/src/functions/obsidian-export.ts +++ b/src/functions/obsidian-export.ts @@ -11,6 +11,10 @@ import type { Session, } from "../types.js"; import { recordAudit } from "./audit.js"; +import { + isLessonListable, + toLessonReadModel, +} from "./lesson-model.js"; const DEFAULT_EXPORT_ROOT = join(homedir(), ".agentmemory"); function getExportRoot(): string { @@ -116,25 +120,43 @@ function memoryToMd(m: Memory): string { } function lessonToMd(l: Lesson): string { - const tags = safeArray(l.tags); - const sourceIds = safeArray(l.sourceIds); - const content = safeString(l.content); - const headline = content ? content.slice(0, 80) : l.id; + const lesson = toLessonReadModel(l); + const tags = safeArray(lesson.tags); + const sourceIds = safeArray(lesson.sourceIds); + const content = safeString(lesson.content); + const headline = content ? content.slice(0, 80) : lesson.id; const fm = toFrontmatter({ - id: l.id, + id: lesson.id, type: "lesson", - source: l.source, - confidence: l.confidence, - reinforcements: l.reinforcements, - created: l.createdAt, - updated: l.updatedAt, - project: l.project, + schemaVersion: lesson.schemaVersion, + source: lesson.source, + confidence: lesson.confidence, + reinforcements: lesson.reinforcements, + created: lesson.createdAt, + updated: lesson.updatedAt, + project: lesson.project, tags, - decayRate: l.decayRate, + decayRate: lesson.decayRate, + mechanismId: lesson.mechanismId, + mechanismVersion: lesson.mechanismVersion, + claimType: lesson.claimType, + evidenceVerdict: lesson.evidenceVerdict, + lifecycle: lesson.lifecycle, + scopeRing: lesson.scope.ring, + scopeId: lesson.scope.scopeId, + sensitivity: lesson.sensitivity, + contentFingerprint: lesson.contentFingerprint, }); const sourceLinks = sourceIds.map((id) => `- [[${id}]]`).join("\n"); + const evidenceLines = lesson.evidenceRefs + .map((reference) => { + const anchor = reference.commitSha ?? reference.artifactDigest; + const path = reference.path ? `:${reference.path}` : ""; + return `- ${reference.kind}: ${reference.repoRemoteUrl}@${anchor}${path}`; + }) + .join("\n"); const sections = [ fm, @@ -144,8 +166,36 @@ function lessonToMd(l: Lesson): string { content, ]; - if (l.context) { - sections.push("", "## Context", l.context); + if (lesson.claim) { + sections.push("", "## Falsifiable Claim", lesson.claim); + } + if (lesson.context) { + sections.push("", "## Context", lesson.context); + } + if (lesson.applicabilityConditions.length > 0) { + sections.push( + "", + "## Applies When", + lesson.applicabilityConditions.map((value) => `- ${value}`).join("\n"), + ); + } + if (lesson.nonApplicabilityConditions.length > 0) { + sections.push( + "", + "## Does Not Apply When", + lesson.nonApplicabilityConditions + .map((value) => `- ${value}`) + .join("\n"), + ); + } + if (lesson.falsificationConditions.length > 0) { + sections.push( + "", + "## Falsified When", + lesson.falsificationConditions + .map((value) => `- ${value}`) + .join("\n"), + ); } if (tags.length > 0) { sections.push( @@ -157,6 +207,9 @@ function lessonToMd(l: Lesson): string { if (sourceLinks) { sections.push("", "## Sources", sourceLinks); } + if (evidenceLines) { + sections.push("", "## Evidence Anchors", evidenceLines); + } return sections.join("\n"); } @@ -324,7 +377,8 @@ export function registerObsidianExportFunction( } for (const l of lessons.filter( - (l): l is Lesson & { id: string } => hasExportId(l) && !l.deleted, + (l): l is Lesson & { id: string } => + hasExportId(l) && isLessonListable(l), )) { const filename = `${sanitize(l.id)}.md`; const filepath = join(dirs.lessons, filename); diff --git a/src/functions/reflect.ts b/src/functions/reflect.ts index 3a2af82934..849fcbbd8c 100644 --- a/src/functions/reflect.ts +++ b/src/functions/reflect.ts @@ -12,6 +12,7 @@ import type { } from "../types.js"; import { recordAudit } from "./audit.js"; import { REFLECT_SYSTEM, buildReflectPrompt } from "../prompts/reflect.js"; +import { isLessonRecallable } from "./lesson-model.js"; interface ConceptCluster { concepts: string[]; @@ -180,7 +181,7 @@ export function registerReflectFunctions( kv.list(KV.crystals).catch(() => []), ]); - let activeLessons = lessons.filter((l) => !l.deleted); + let activeLessons = lessons.filter(isLessonRecallable); if (data?.project) { activeLessons = activeLessons.filter((l) => l.project === data.project); } diff --git a/src/functions/replay.ts b/src/functions/replay.ts index e44ca8cc9d..7e1ebd915c 100644 --- a/src/functions/replay.ts +++ b/src/functions/replay.ts @@ -17,6 +17,7 @@ import { safeAudit } from "./audit.js"; import { buildSyntheticCompression } from "./compress-synthetic.js"; import { getSearchIndex } from "./search.js"; import { logger } from "../logger.js"; +import { normalizeLesson } from "./lesson-model.js"; export const MAX_FILES_DEFAULT = 200; export const MAX_FILES_UPPER_BOUND = 1000; @@ -120,25 +121,26 @@ async function deriveCrystalAndLessons( try { const existing = await kv.get(KV.lessons, lessonId); if (existing) { - const existingSources = existing.sourceIds || []; + const normalizedExisting = normalizeLesson(existing); + const existingSources = normalizedExisting.sourceIds; const mergedSources = existingSources.includes(sessionId) ? existingSources : [...existingSources, sessionId]; - const existingTags = existing.tags || []; + const existingTags = normalizedExisting.tags; const mergedTags = existingTags.includes("auto-import") ? existingTags : [...existingTags, "auto-import"]; const merged: Lesson = { - ...existing, + ...normalizedExisting, sourceIds: mergedSources, tags: mergedTags, - reinforcements: (existing.reinforcements || 0) + 1, + reinforcements: normalizedExisting.reinforcements + 1, updatedAt: createdAt, lastReinforcedAt: createdAt, }; await kv.set(KV.lessons, lessonId, merged); } else { - const lesson: Lesson = { + const lesson = normalizeLesson({ id: lessonId, content, context: firstPrompt || project, @@ -151,7 +153,7 @@ async function deriveCrystalAndLessons( createdAt, updatedAt: createdAt, decayRate: 0.05, - }; + }); await kv.set(KV.lessons, lessonId, lesson); } lessonIds.push(lessonId); diff --git a/src/mcp/server.ts b/src/mcp/server.ts index 4e3f16c318..f535ab2682 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -12,6 +12,7 @@ import { getVisibleTools } from "./tools-registry.js"; import { timingSafeCompare } from "../auth.js"; import { getAgentId, isAgentScopeIsolated } from "../config.js"; import { selectSessionPage } from "../functions/session-list.js"; +import { parseLessonSaveInput } from "../functions/lesson-model.js"; type McpResponse = { status_code: number; @@ -1307,20 +1308,20 @@ export function registerMcpEndpoints( } case "memory_lesson_save": { - if (typeof args.content !== "string" || !args.content.trim()) { - return { status_code: 400, body: { error: "content is required" } }; - } - const lessonTags = typeof args.tags === "string" && args.tags.trim() - ? args.tags.split(",").map((t: string) => t.trim()).filter(Boolean) - : []; - const lessonSaveResult = await sdk.trigger({ function_id: "mem::lesson-save", payload: { - content: args.content, - context: args.context || "", - confidence: args.confidence, - project: args.project, - tags: lessonTags, + const parsed = parseLessonSaveInput(args, { source: "manual", - } }); + allowSourceMetadata: false, + }); + if (!parsed.success) { + return { + status_code: 400, + body: { error: parsed.error }, + }; + } + const lessonSaveResult = await sdk.trigger({ + function_id: "mem::lesson-save", + payload: parsed.value, + }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(lessonSaveResult, null, 2) }] } }; } diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts index 7b556fa0d0..0ec4b58f8c 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -1,9 +1,21 @@ +export type McpSchemaProperty = { + type: string; + description?: string; + enum?: string[]; + items?: McpSchemaProperty; + properties?: Record; + required?: string[]; + additionalProperties?: boolean | McpSchemaProperty; + maxItems?: number; + minimum?: number; +}; + export type McpToolDef = { name: string; description: string; inputSchema: { type: "object"; - properties: Record; + properties: Record; required?: string[]; }; }; @@ -885,7 +897,7 @@ export const V070_TOOLS: McpToolDef[] = [ { name: "memory_lesson_save", description: - "Save a lesson learned from this session. Lessons have confidence scores that strengthen when reinforced and decay when not used. Duplicate content auto-strengthens the existing lesson.", + "Save a legacy prose lesson or a structured causal lesson. Reinforcement tracks reuse without changing evidence confidence; structured inputs support verdict, lifecycle, durable evidence, scope, sensitivity, and deterministic fingerprints.", inputSchema: { type: "object", properties: { @@ -903,6 +915,143 @@ export const V070_TOOLS: McpToolDef[] = [ }, project: { type: "string", description: "Project this lesson is about" }, tags: { type: "string", description: "Comma-separated tags" }, + mechanismId: { + type: "string", + description: + "Canonical mechanism identity for a structured causal lesson", + }, + mechanismVersion: { + type: "string", + description: "Optional version within the canonical mechanism", + }, + mechanismAliases: { + type: "array", + description: "Optional prior or alternate mechanism identities", + items: { type: "string" }, + maxItems: 8, + }, + claim: { + type: "string", + description: + "Short falsifiable claim, distinct from the prose content", + }, + claimType: { + type: "string", + description: "General claim classification", + enum: [ + "causal", + "predictive", + "procedural", + "constraint", + "descriptive", + ], + }, + evidenceVerdict: { + type: "string", + description: "Evidence verdict, independent of lifecycle", + enum: ["supported", "refuted", "mixed", "unverified"], + }, + lifecycle: { + type: "string", + description: + "Initial lifecycle; superseded and retracted require correction tools", + enum: ["draft", "active"], + }, + applicabilityConditions: { + type: "array", + description: "Conditions under which the claim applies", + items: { type: "string" }, + maxItems: 16, + }, + nonApplicabilityConditions: { + type: "array", + description: "Conditions under which the claim does not apply", + items: { type: "string" }, + maxItems: 16, + }, + falsificationConditions: { + type: "array", + description: "Observable conditions that would falsify the claim", + items: { type: "string" }, + maxItems: 16, + }, + structuredFacets: { + type: "object", + description: + "General facet dimensions mapped to string values, such as asset, venue, horizon, regime, or signal_family", + additionalProperties: { + type: "array", + items: { type: "string" }, + maxItems: 16, + }, + }, + evidenceRefs: { + type: "array", + description: + "At most eight immutable evidence anchors; branch, ref, or path alone is insufficient", + maxItems: 8, + items: { + type: "object", + properties: { + kind: { type: "string" }, + projectId: { type: "string" }, + repoRemoteUrl: { type: "string" }, + commitSha: { type: "string" }, + artifactDigest: { type: "string" }, + path: { type: "string" }, + recordedAt: { type: "string" }, + validatedAt: { type: "string" }, + evidenceKind: { type: "string" }, + sampleCount: { type: "number", minimum: 0 }, + }, + required: [ + "kind", + "projectId", + "repoRemoteUrl", + "recordedAt", + ], + }, + }, + scope: { + type: "object", + description: + "Scope ring and durable scope identity; project remains only a label", + properties: { + ring: { + type: "string", + enum: ["worktree", "repo", "initiative", "domain", "global"], + }, + scopeId: { type: "string" }, + humanApproval: { + type: "object", + properties: { + approvedBy: { type: "string" }, + approvedAt: { type: "string" }, + reason: { type: "string" }, + }, + required: ["approvedBy", "approvedAt", "reason"], + }, + }, + required: ["ring"], + }, + sensitivity: { + type: "string", + description: + "Sensitivity classification; defaults fail-closed to restricted", + enum: ["public", "internal", "confidential", "restricted"], + }, + reviewAfter: { + type: "string", + description: + "Optional ISO review timestamp used to compute staleness without changing lifecycle or confidence", + }, + contradictedByLessonIds: { + type: "array", + description: + "Explicit lesson IDs used to compute contradiction state without changing confidence", + items: { type: "string" }, + maxItems: 16, + }, }, required: ["content"], }, @@ -928,7 +1077,7 @@ export const V070_TOOLS: McpToolDef[] = [ { name: "memory_lesson_delete", description: - "Soft-delete one lesson by exact ID while preserving correction metadata and an audit trail. Requires a human-readable reason.", + "Retract one lesson by exact ID when its evidence is invalid, preserving the legacy tombstone fields, correction metadata, and audit trail. Requires a human-readable reason.", inputSchema: { type: "object", properties: { @@ -957,7 +1106,7 @@ export const V070_TOOLS: McpToolDef[] = [ { name: "memory_lesson_supersede", description: - "Soft-delete one lesson in favor of an existing replacement lesson in the same project, preserving lineage and an audit trail.", + "Mark one lesson superseded in favor of an active replacement in the same durable scope, preserving legacy tombstone fields, lineage, and an audit trail.", inputSchema: { type: "object", properties: { diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 88f85d78e1..f6c970d48f 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -22,6 +22,7 @@ import { MAX_FILES_UPPER_BOUND } from "../functions/replay.js"; import { logger } from "../logger.js"; import { selectSessionPage } from "../functions/session-list.js"; import { triggerDetached } from "../utils/trigger-detached.js"; +import { parseLessonSaveInput } from "../functions/lesson-model.js"; import { isGraphExtractionEnabled, isConsolidationEnabled, @@ -3545,19 +3546,16 @@ export function registerApiTriggers( sdk.registerFunction("api::lesson-save", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; - const body = req.body as Record; - if (!body?.content || typeof body.content !== "string") return { status_code: 400, body: { error: "content is required" } }; - const tags = typeof body.tags === "string" ? (body.tags as string).split(",").map((t: string) => t.trim()).filter(Boolean) : Array.isArray(body.tags) ? body.tags : []; + const parsed = parseLessonSaveInput(req.body, { + source: "manual", + allowSourceMetadata: false, + }); + if (!parsed.success) { + return { status_code: 400, body: { error: parsed.error } }; + } const result = (await sdk.trigger({ function_id: "mem::lesson-save", - payload: { - content: body.content, - context: body.context || "", - confidence: typeof body.confidence === "number" ? body.confidence : undefined, - project: typeof body.project === "string" ? body.project : undefined, - tags, - source: "manual", - }, + payload: parsed.value, })) as { action?: string }; const statusCode = result?.action === "created" ? 201 : 200; return { status_code: statusCode, body: result }; @@ -3615,9 +3613,44 @@ export function registerApiTriggers( sdk.registerFunction("api::lesson-search", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; - const body = req.body as Record; - if (!body?.query || typeof body.query !== "string") return { status_code: 400, body: { error: "query is required" } }; - const result = await sdk.trigger({ function_id: "mem::lesson-recall", payload: body }); + const body = (req.body ?? {}) as Record; + const query = asNonEmptyString(body.query); + if (!query) { + return { status_code: 400, body: { error: "query is required" } }; + } + if (body.project !== undefined && typeof body.project !== "string") { + return { status_code: 400, body: { error: "project must be a string" } }; + } + if ( + body.minConfidence !== undefined && + (typeof body.minConfidence !== "number" || + !Number.isFinite(body.minConfidence)) + ) { + return { + status_code: 400, + body: { error: "minConfidence must be a finite number" }, + }; + } + if ( + body.limit !== undefined && + (typeof body.limit !== "number" || + !Number.isInteger(body.limit) || + body.limit < 1) + ) { + return { + status_code: 400, + body: { error: "limit must be a positive integer" }, + }; + } + const result = await sdk.trigger({ + function_id: "mem::lesson-recall", + payload: { + query, + project: asNonEmptyString(body.project), + minConfidence: body.minConfidence, + limit: body.limit, + }, + }); return { status_code: 200, body: result }; }); sdk.registerTrigger({ type: "http", function_id: "api::lesson-search", config: { api_path: "/agentmemory/lessons/search", http_method: "POST" } }); @@ -3671,7 +3704,8 @@ export function registerApiTriggers( ? 404 : response.code === "revision_conflict" || response.code === "lesson_already_deleted" || - response.code === "project_mismatch" + response.code === "project_mismatch" || + response.code === "scope_mismatch" ? 409 : 400; return { status_code: statusCode, body: result }; @@ -3726,7 +3760,9 @@ export function registerApiTriggers( ? 404 : response.code === "revision_conflict" || response.code === "lesson_already_deleted" || - response.code === "project_mismatch" + response.code === "project_mismatch" || + response.code === "scope_mismatch" || + response.code === "replacement_not_active" ? 409 : 400; return { status_code: statusCode, body: result }; diff --git a/src/types.ts b/src/types.ts index 310188ba9a..01989edcba 100644 --- a/src/types.ts +++ b/src/types.ts @@ -928,6 +928,68 @@ export interface Crystal { createdAt: string; } +export type LessonEvidenceVerdict = + | "supported" + | "refuted" + | "mixed" + | "unverified"; + +export type LessonLifecycle = + | "draft" + | "active" + | "superseded" + | "retracted"; + +export type LessonClaimType = + | "causal" + | "predictive" + | "procedural" + | "constraint" + | "descriptive"; + +export type LessonScopeRing = + | "worktree" + | "repo" + | "initiative" + | "domain" + | "global"; + +export type LessonSensitivity = + | "public" + | "internal" + | "confidential" + | "restricted"; + +export interface LessonHumanApproval { + approvedBy: string; + approvedAt: string; + reason: string; +} + +export interface LessonScope { + ring: LessonScopeRing; + scopeId?: string; + humanApproval?: LessonHumanApproval; +} + +export interface LessonEvidenceReference { + kind: string; + projectId: string; + repoRemoteUrl: string; + commitSha?: string; + artifactDigest?: string; + path?: string; + recordedAt: string; + validatedAt?: string; + evidenceKind?: string; + sampleCount?: number; +} + +export interface LessonComputedFlags { + stale: boolean; + contradicted: boolean; +} + export interface Lesson { id: string; content: string; @@ -948,6 +1010,44 @@ export interface Lesson { deletedBy?: string; deleteReason?: string; supersededByLessonId?: string; + schemaVersion?: 1; + mechanismId?: string; + mechanismVersion?: string; + mechanismAliases?: string[]; + claim?: string; + claimType?: LessonClaimType; + evidenceVerdict?: LessonEvidenceVerdict; + lifecycle?: LessonLifecycle; + applicabilityConditions?: string[]; + nonApplicabilityConditions?: string[]; + falsificationConditions?: string[]; + structuredFacets?: Record; + evidenceRefs?: LessonEvidenceReference[]; + scope?: LessonScope; + sensitivity?: LessonSensitivity; + reviewAfter?: string; + contradictedByLessonIds?: string[]; + contentFingerprint?: string; +} + +export interface NormalizedLesson extends Lesson { + schemaVersion: 1; + mechanismAliases: string[]; + evidenceVerdict: LessonEvidenceVerdict; + lifecycle: LessonLifecycle; + applicabilityConditions: string[]; + nonApplicabilityConditions: string[]; + falsificationConditions: string[]; + structuredFacets: Record; + evidenceRefs: LessonEvidenceReference[]; + scope: LessonScope; + sensitivity: LessonSensitivity; + contradictedByLessonIds: string[]; + contentFingerprint: string; +} + +export interface LessonReadModel extends NormalizedLesson { + computedFlags: LessonComputedFlags; } export interface Insight { diff --git a/src/viewer/index.html b/src/viewer/index.html index 8053896350..afbc3f0d6c 100644 --- a/src/viewer/index.html +++ b/src/viewer/index.html @@ -3087,7 +3087,7 @@

agentmemory

var html = '
'; html += '
'; - html += 'Lessons are portable heuristics — short imperative rules (always/never/prefer/avoid) extracted from past work. Auto-surface from JSONL imports (low confidence, tag auto-import), get reinforced when the agent applies them, and decay if unused. Higher confidence = more battle-tested.'; + html += 'Lessons are portable prose heuristics or structured causal claims. Reinforcement tracks reuse without changing evidence confidence. Schema-v1 lessons keep evidence verdict separate from lifecycle and compute stale/contradicted flags without automatic confidence changes; pre-schema rows retain legacy decay compatibility.'; html += '
'; html += '
'; @@ -3101,7 +3101,7 @@

agentmemory

'
No lessons yet
' + '
Lessons are confidence-scored pattern observations — things you corrected once that the agent should never do again. They persist across projects.
' + '
# Save a lesson explicitly\nmemory_lesson_save { rule, reason, confidence }\n\n# Or: Replay tab → Import JSONL auto-extracts lessons\n# from your past Claude Code sessions
' + - '' + + '' + '
'; } else { html += '
FunctionCallsSuccessFailSkippedAvg LatencyQuality
' + esc(m.functionId) + '' + esc(m.functionId) + (stateMuted ? ' ' + esc(runtimeState) + '' : '') + '' + m.totalCalls + '' + m.successCount + ' (' + successRate + '%)' + m.failureCount + '' + m.successCount + (successRate === null ? '' : ' (' + successRate + '%)') + '' + m.failureCount + '' + (m.skippedCount || 0) + '' + Math.round(m.avgLatencyMs) + ' ms' + (m.avgQualityScore > 0 ? m.avgQualityScore.toFixed(2) : '-') + '
'; diff --git a/test/causal-lessons-api.test.ts b/test/causal-lessons-api.test.ts new file mode 100644 index 0000000000..199181b562 --- /dev/null +++ b/test/causal-lessons-api.test.ts @@ -0,0 +1,208 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { registerLessonsFunctions } from "../src/functions/lessons.js"; +import { registerMcpEndpoints } from "../src/mcp/server.js"; +import { getAllTools } from "../src/mcp/tools-registry.js"; +import { registerApiTriggers } from "../src/triggers/api.js"; +import type { Lesson } from "../src/types.js"; +import { mockKV, mockSdk } from "./helpers/mocks.js"; + +function evidence(commit = "a".repeat(40)) { + return { + kind: "experiment", + projectId: "agentmemory", + repoRemoteUrl: "https://github.com/rohitg00/agentmemory", + commitSha: commit, + path: "test/causal-lessons-api.test.ts", + recordedAt: "2026-08-02T20:00:00.000Z", + evidenceKind: "unit-test", + sampleCount: 12, + }; +} + +describe("causal lesson REST and MCP boundaries", () => { + let sdk: ReturnType; + let kv: ReturnType; + + beforeEach(() => { + sdk = mockSdk(); + kv = mockKV(); + registerLessonsFunctions(sdk as never, kv as never); + registerApiTriggers(sdk as never, kv as never); + registerMcpEndpoints(sdk as never, kv as never); + }); + + it("whitelists and persists validated structured REST input", async () => { + const response = (await sdk.trigger("api::lesson-save", { + headers: {}, + body: { + content: "Queue pressure reversal evidence", + context: "Short-horizon execution research", + confidence: 0.78, + project: "agentmemory", + tags: ["causal", "microstructure"], + mechanismId: "queue-pressure/reversal", + mechanismVersion: "v1", + claim: "Negative queue pressure causes short-horizon reversal.", + claimType: "causal", + evidenceVerdict: "supported", + applicabilityConditions: ["liquid venue"], + nonApplicabilityConditions: ["auction halt"], + falsificationConditions: ["no reversal after costs"], + structuredFacets: { + asset: ["HYPE"], + venue: ["Hyperliquid"], + horizon: ["15m"], + regime: ["volatile"], + signal_family: ["order-flow"], + }, + evidenceRefs: [{ ...evidence(), branch: "main" }], + scope: { + ring: "repo", + scopeId: "repo:https://github.com/rohitg00/agentmemory", + }, + sensitivity: "confidential", + source: "crystal", + sourceIds: ["untrusted"], + deleted: true, + computedFlags: { stale: true, contradicted: true }, + }, + })) as { + status_code: number; + body: { success: boolean; action: string; lesson: Lesson }; + }; + const stored = (await kv.list("mem:lessons"))[0]; + + expect(response).toMatchObject({ + status_code: 201, + body: { + success: true, + action: "created", + lesson: { + schemaVersion: 1, + mechanismId: "queue-pressure/reversal", + evidenceVerdict: "supported", + lifecycle: "active", + sensitivity: "confidential", + project: "agentmemory", + scope: { + ring: "repo", + scopeId: "repo:https://github.com/rohitg00/agentmemory", + }, + }, + }, + }); + expect(stored.source).toBe("manual"); + expect(stored.sourceIds).toEqual([]); + expect(stored.deleted).toBeUndefined(); + expect(stored).not.toHaveProperty("computedFlags"); + expect(stored.evidenceRefs?.[0]).not.toHaveProperty("branch"); + }); + + it("accepts structured MCP input and exposes its schema", async () => { + const response = (await sdk.trigger("mcp::tools::call", { + headers: {}, + body: { + name: "memory_lesson_save", + arguments: { + content: "MCP causal lesson", + mechanismId: "state-boundary/normalization", + claim: "Boundary normalization prevents undefined/null drift.", + claimType: "causal", + evidenceVerdict: "supported", + evidenceRefs: [evidence("b".repeat(40))], + scope: { + ring: "repo", + scopeId: "repo:https://github.com/rohitg00/agentmemory", + }, + sensitivity: "restricted", + }, + }, + })) as { + status_code: number; + body: { content: Array<{ text: string }> }; + }; + const result = JSON.parse(response.body.content[0].text) as { + lesson: Lesson; + }; + const tool = getAllTools().find( + (candidate) => candidate.name === "memory_lesson_save", + ); + + expect(response.status_code).toBe(200); + expect(result.lesson).toMatchObject({ + mechanismId: "state-boundary/normalization", + evidenceVerdict: "supported", + sensitivity: "restricted", + }); + expect(tool?.inputSchema.properties).toHaveProperty("evidenceRefs"); + expect(tool?.inputSchema.properties).toHaveProperty("structuredFacets"); + expect(tool?.inputSchema.properties).toHaveProperty("scope"); + expect(tool?.inputSchema.properties).toHaveProperty("sensitivity"); + }); + + it("rejects invalid immutable evidence and unapproved global scope at both boundaries", async () => { + const rest = (await sdk.trigger("api::lesson-save", { + headers: {}, + body: { + content: "REST path-only evidence", + mechanismId: "rest/path-only", + claim: "A path is immutable proof.", + evidenceRefs: [ + { + kind: "document", + projectId: "agentmemory", + repoRemoteUrl: "https://github.com/rohitg00/agentmemory", + path: "report.md", + recordedAt: "2026-08-02T20:00:00.000Z", + }, + ], + }, + })) as { status_code: number; body: { error: string } }; + const mcp = (await sdk.trigger("mcp::tools::call", { + headers: {}, + body: { + name: "memory_lesson_save", + arguments: { + content: "Unapproved global lesson", + scope: { ring: "global" }, + }, + }, + })) as { status_code: number; body: { error: string } }; + + expect(rest.status_code).toBe(400); + expect(rest.body.error).toContain("not immutable proof"); + expect(mcp.status_code).toBe(400); + expect(mcp.body.error).toContain("humanApproval"); + expect(await kv.list("mem:lessons")).toEqual([]); + }); + + it("whitelists lesson search fields instead of forwarding the raw body", async () => { + await sdk.trigger("mem::lesson-save", { + content: "Search boundary lesson", + project: "agentmemory", + }); + + const response = (await sdk.trigger("api::lesson-search", { + headers: {}, + body: { + query: "search boundary", + project: "agentmemory", + limit: 5, + lifecycle: "retracted", + deleted: true, + }, + })) as { + status_code: number; + body: { lessons: Lesson[] }; + }; + + expect(response.status_code).toBe(200); + expect(response.body.lessons).toHaveLength(1); + expect(response.body.lessons[0].lifecycle).toBe("active"); + }); +}); diff --git a/test/context-lessons.test.ts b/test/context-lessons.test.ts index d915c9392e..5c51c401cb 100644 --- a/test/context-lessons.test.ts +++ b/test/context-lessons.test.ts @@ -60,6 +60,12 @@ function makeLesson(over: Partial = {}): Lesson { lastDecayedAt: over.lastDecayedAt, decayRate: over.decayRate ?? 0.05, deleted: over.deleted, + lifecycle: over.lifecycle, + mechanismId: over.mechanismId, + claim: over.claim, + evidenceVerdict: over.evidenceVerdict, + evidenceRefs: over.evidenceRefs, + scope: over.scope, }; } @@ -167,6 +173,54 @@ describe("mem::context — lessons auto-injection (#457)", () => { expect(result.context).not.toContain("tombstoned-lesson"); }); + it("keeps draft lessons out of injected context", async () => { + await seedLesson(kv, { + id: "lesson_draft", + content: "draft-lesson-pending-review", + project: "/tmp/proj", + confidence: 0.9, + lifecycle: "draft", + }); + + const result = await handler({ + sessionId: "ses_draft", + project: "/tmp/proj", + }); + + expect(result.context).not.toContain("draft-lesson-pending-review"); + }); + + it("labels refuted active lessons as negative evidence", async () => { + await seedLesson(kv, { + id: "lesson_refuted", + content: "The longer explanatory record", + mechanismId: "context/refuted", + claim: "This mechanism improves outcomes.", + project: "/tmp/proj", + confidence: 0.9, + lifecycle: "active", + evidenceVerdict: "refuted", + evidenceRefs: [ + { + kind: "experiment", + projectId: "agentmemory", + repoRemoteUrl: "https://github.com/rohitg00/agentmemory", + commitSha: "a".repeat(40), + recordedAt: "2026-08-02T20:00:00.000Z", + }, + ], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + }); + + const result = await handler({ + sessionId: "ses_refuted", + project: "/tmp/proj", + }); + + expect(result.context).toContain("[verdict:refuted]"); + expect(result.context).toContain("This mechanism improves outcomes."); + }); + it("caps at the top 10 lessons by confidence", async () => { for (let i = 0; i < 15; i++) { await seedLesson(kv, { diff --git a/test/export-import.test.ts b/test/export-import.test.ts index c9b15b86af..0cb965d61f 100644 --- a/test/export-import.test.ts +++ b/test/export-import.test.ts @@ -15,6 +15,7 @@ import type { ActionEdge, ActionCollectionState, ActionEvent, + Lesson, } from "../src/types.js"; function mockKV() { @@ -235,6 +236,164 @@ describe("Export/Import Functions", () => { expect(reExported.memories.length).toBe(exported.memories.length); }); + it("exports legacy lessons with normalized defaults without rewriting live state", async () => { + const legacy: Lesson = { + id: "lsn_legacy_export", + content: "Legacy export lesson", + context: "", + confidence: 0.7, + reinforcements: 0, + source: "manual", + sourceIds: [], + project: "agentmemory", + tags: ["legacy"], + createdAt: "2026-07-01T00:00:00.000Z", + updatedAt: "2026-07-01T00:00:00.000Z", + decayRate: 0.05, + }; + await kv.set("mem:lessons", legacy.id, legacy); + + const exported = (await sdk.trigger("mem::export", {})) as ExportData; + const stored = await kv.get("mem:lessons", legacy.id); + + expect(exported.lessons).toEqual([ + expect.objectContaining({ + id: legacy.id, + schemaVersion: 1, + evidenceVerdict: "unverified", + lifecycle: "active", + sensitivity: "restricted", + scope: { ring: "worktree" }, + contentFingerprint: expect.stringMatching(/^lfp_[a-f0-9]{16}$/), + }), + ]); + expect(stored).toEqual(legacy); + expect(stored?.schemaVersion).toBeUndefined(); + }); + + it("normalizes legacy lessons during explicit import and preserves structured fields", async () => { + const legacy = { + id: "lsn_legacy_import", + content: "Imported legacy lesson", + context: "", + confidence: 0.6, + reinforcements: 0, + source: "manual", + sourceIds: [], + project: "agentmemory", + tags: [], + createdAt: "2026-07-01T00:00:00.000Z", + updatedAt: "2026-07-01T00:00:00.000Z", + decayRate: 0.05, + } as Lesson; + const structured = { + ...legacy, + id: "lsn_structured_import", + content: "Structured imported lesson", + mechanismId: "import/normalization", + claim: "Explicit import produces a stable normalized lesson.", + claimType: "causal", + evidenceVerdict: "supported", + lifecycle: "active", + evidenceRefs: [ + { + kind: "experiment", + projectId: "agentmemory", + repoRemoteUrl: "https://github.com/rohitg00/agentmemory", + commitSha: "d".repeat(40), + recordedAt: "2026-08-02T20:00:00.000Z", + sampleCount: 1, + }, + ], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + sensitivity: "confidential", + } as Lesson; + const exportData: ExportData = { + version: "0.9.27", + exportedAt: new Date().toISOString(), + sessions: [], + observations: {}, + memories: [], + summaries: [], + lessons: [legacy, structured], + }; + + const result = (await sdk.trigger("mem::import", { + exportData, + strategy: "merge", + })) as { success: boolean; lessons: number }; + const storedLegacy = await kv.get( + "mem:lessons", + legacy.id, + ); + const storedStructured = await kv.get( + "mem:lessons", + structured.id, + ); + + expect(result).toMatchObject({ success: true, lessons: 2 }); + expect(storedLegacy).toMatchObject({ + schemaVersion: 1, + evidenceVerdict: "unverified", + lifecycle: "active", + sensitivity: "restricted", + }); + expect(storedStructured).toMatchObject({ + schemaVersion: 1, + mechanismId: "import/normalization", + evidenceVerdict: "supported", + lifecycle: "active", + sensitivity: "confidential", + evidenceRefs: [expect.objectContaining({ commitSha: "d".repeat(40) })], + }); + }); + + it("rejects invalid structured lessons before replace mutation", async () => { + const preserved: Lesson = { + id: "lsn_preserved", + content: "Preserve this lesson", + context: "", + confidence: 0.5, + reinforcements: 0, + source: "manual", + sourceIds: [], + tags: [], + createdAt: "2026-07-01T00:00:00.000Z", + updatedAt: "2026-07-01T00:00:00.000Z", + decayRate: 0.05, + }; + await kv.set("mem:lessons", preserved.id, preserved); + const invalid = { + ...preserved, + id: "lsn_invalid", + mechanismId: "invalid/import", + claim: "This unsupported record has no durable evidence.", + evidenceVerdict: "supported", + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + } as Lesson; + const exportData: ExportData = { + version: "0.9.27", + exportedAt: new Date().toISOString(), + sessions: [], + observations: {}, + memories: [], + summaries: [], + lessons: [invalid], + }; + + const result = (await sdk.trigger("mem::import", { + exportData, + strategy: "replace", + })) as { success: boolean; error: string }; + + expect(result).toMatchObject({ + success: false, + error: expect.stringContaining("durable evidence reference"), + }); + expect(await kv.get("mem:lessons", preserved.id)).toEqual(preserved); + expect(await kv.get("mem:sessions", "ses_1")).toEqual(testSession); + }); + it("import rejects unsupported version", async () => { const exportData = { version: "1.0.0", diff --git a/test/lesson-corrections.test.ts b/test/lesson-corrections.test.ts index 1248ea8244..788190c6d1 100644 --- a/test/lesson-corrections.test.ts +++ b/test/lesson-corrections.test.ts @@ -48,6 +48,7 @@ describe("lesson corrections", () => { lesson: { id: lesson.id, deleted: true, + lifecycle: "retracted", deletedBy: "codex", deleteReason: "Superseded by current evidence", }, @@ -129,6 +130,7 @@ describe("lesson corrections", () => { lesson: { id: original.id, deleted: true, + lifecycle: "superseded", supersededByLessonId: replacement.id, }, }); @@ -185,6 +187,103 @@ describe("lesson corrections", () => { }); }); + it("uses durable scope identity instead of project labels for structured supersession", async () => { + const base = { + project: "shared-label", + mechanismId: "scope/identity", + claim: "Durable scope identity controls correction joins.", + scope: { ring: "repo", scopeId: "repo:one" }, + }; + const original = (await sdk.trigger("mem::lesson-save", { + ...base, + content: "Original scoped lesson", + })) as { lesson: Lesson }; + const replacement = (await sdk.trigger("mem::lesson-save", { + ...base, + content: "Replacement in another repo", + mechanismId: "scope/identity-v2", + claim: "A project label is not a cross-repo join key.", + scope: { ring: "repo", scopeId: "repo:two" }, + })) as { lesson: Lesson }; + + const result = await sdk.trigger("mem::lesson-supersede", { + lessonId: original.lesson.id, + replacementLessonId: replacement.lesson.id, + reason: "Attempted cross-scope correction", + }); + + expect(result).toMatchObject({ + success: false, + code: "scope_mismatch", + }); + }); + + it("treats project as a label when structured lessons share a durable scope", async () => { + const scope = { ring: "repo", scopeId: "repo:shared-authority" }; + const original = (await sdk.trigger("mem::lesson-save", { + content: "Original label-scoped lesson", + project: "legacy-label-one", + mechanismId: "scope/shared-original", + claim: "The original scoped claim applies.", + scope, + })) as { lesson: Lesson }; + const replacement = (await sdk.trigger("mem::lesson-save", { + content: "Replacement label-scoped lesson", + project: "legacy-label-two", + mechanismId: "scope/shared-replacement", + claim: "The corrected scoped claim applies.", + scope, + })) as { lesson: Lesson }; + + const result = await sdk.trigger("mem::lesson-supersede", { + lessonId: original.lesson.id, + replacementLessonId: replacement.lesson.id, + reason: "Durable scope, not project label, authorizes lineage", + }); + + expect(result).toMatchObject({ + success: true, + action: "superseded", + }); + }); + + it("keeps refuted evidence recallable until it is explicitly retracted", async () => { + const saved = (await sdk.trigger("mem::lesson-save", { + content: "Refuted causal lesson remains negative evidence", + mechanismId: "negative/evidence", + claim: "The proposed mechanism improves outcomes.", + evidenceVerdict: "refuted", + evidenceRefs: [ + { + kind: "experiment", + projectId: "agentmemory", + repoRemoteUrl: "https://github.com/rohitg00/agentmemory", + commitSha: "c".repeat(40), + recordedAt: "2026-08-02T20:00:00.000Z", + }, + ], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + })) as { lesson: Lesson }; + const before = (await sdk.trigger("mem::lesson-recall", { + query: "refuted negative evidence", + })) as { lessons: Lesson[] }; + + await sdk.trigger("mem::lesson-delete", { + lessonId: saved.lesson.id, + reason: "Underlying evidence artifact was invalid", + }); + const after = (await sdk.trigger("mem::lesson-recall", { + query: "refuted negative evidence", + })) as { lessons: Lesson[] }; + + expect(before.lessons).toHaveLength(1); + expect(before.lessons[0]).toMatchObject({ + evidenceVerdict: "refuted", + lifecycle: "active", + }); + expect(after.lessons).toEqual([]); + }); + it("serializes delete and strengthen so the tombstone wins", async () => { const lesson = await saveLesson("Concurrent lesson"); const [deleted, strengthened] = await Promise.all([ diff --git a/test/lesson-model.test.ts b/test/lesson-model.test.ts new file mode 100644 index 0000000000..237caef246 --- /dev/null +++ b/test/lesson-model.test.ts @@ -0,0 +1,398 @@ +import { describe, expect, it } from "vitest"; +import { + lessonContentFingerprint, + lessonIdForInput, + normalizeLesson, + parseImportedLesson, + parseLessonSaveInput, + toLessonReadModel, +} from "../src/functions/lesson-model.js"; +import type { + Lesson, + LessonEvidenceReference, +} from "../src/types.js"; + +function evidence( + overrides: Partial = {}, +): LessonEvidenceReference { + return { + kind: "experiment", + projectId: "agentmemory", + repoRemoteUrl: "https://github.com/rohitg00/agentmemory", + commitSha: "a".repeat(40), + path: "test/lesson-model.test.ts", + recordedAt: "2026-08-02T20:00:00.000Z", + validatedAt: "2026-08-02T21:00:00.000Z", + evidenceKind: "unit-test", + sampleCount: 42, + ...overrides, + }; +} + +function parsedLesson( + overrides: Record = {}, +) { + const parsed = parseLessonSaveInput({ + content: "Long prose explaining the mechanism and evidence.", + mechanismId: "queue-pressure/reversal", + claim: "Negative queue pressure causes short-horizon price reversal.", + claimType: "causal", + evidenceVerdict: "supported", + evidenceRefs: [evidence()], + scope: { + ring: "repo", + scopeId: "repo:https://github.com/rohitg00/agentmemory", + }, + ...overrides, + }); + expect(parsed.success).toBe(true); + if (!parsed.success) throw new Error(parsed.error); + return parsed.value; +} + +function legacyLesson(overrides: Partial = {}): Lesson { + return { + id: "lsn_legacy", + content: "Legacy prose remains readable", + context: "", + confidence: 0.7, + reinforcements: 2, + source: "manual", + sourceIds: [], + project: "agentmemory", + tags: ["legacy"], + createdAt: "2026-07-01T00:00:00.000Z", + updatedAt: "2026-07-02T00:00:00.000Z", + decayRate: 0.05, + ...overrides, + }; +} + +describe("causal lesson model", () => { + it("normalizes a general causal claim, facets, aliases, and durable evidence", () => { + const input = parsedLesson({ + mechanismId: "Queue-Pressure/Reversal", + mechanismVersion: "v1", + mechanismAliases: ["qp-reversal", "Queue-Pressure/Reversal"], + claim: " Negative queue pressure causes short-horizon price reversal. ", + applicabilityConditions: ["Liquid venue", " Volatile regime "], + nonApplicabilityConditions: ["Auction halt"], + falsificationConditions: ["No reversal after costs"], + structuredFacets: { + "Signal Family": ["order-flow"], + Asset: ["HYPE", "BTC"], + Venue: ["Hyperliquid"], + horizon: ["15m"], + regime: ["volatile"], + }, + evidenceRefs: [ + evidence({ + repoRemoteUrl: "https://github.com/rohitg00/agentmemory.git/", + commitSha: "A".repeat(40), + }), + ], + }); + + expect(input).toMatchObject({ + mechanismId: "queue-pressure/reversal", + mechanismVersion: "v1", + mechanismAliases: ["qp-reversal"], + claim: + "Negative queue pressure causes short-horizon price reversal.", + claimType: "causal", + evidenceVerdict: "supported", + lifecycle: "active", + sensitivity: "restricted", + scope: { + ring: "repo", + scopeId: "repo:https://github.com/rohitg00/agentmemory", + }, + structuredFacets: { + asset: ["BTC", "HYPE"], + horizon: ["15m"], + regime: ["volatile"], + signal_family: ["order-flow"], + venue: ["Hyperliquid"], + }, + }); + expect(input.evidenceRefs[0]).toMatchObject({ + repoRemoteUrl: "https://github.com/rohitg00/agentmemory", + commitSha: "a".repeat(40), + recordedAt: "2026-08-02T20:00:00.000Z", + sampleCount: 42, + }); + }); + + it("normalizes legacy lessons to safe defaults without rewriting the source object", () => { + const legacy = legacyLesson(); + const before = JSON.stringify(legacy); + const normalized = normalizeLesson(legacy); + + expect(normalized).toMatchObject({ + schemaVersion: 1, + evidenceVerdict: "unverified", + lifecycle: "active", + sensitivity: "restricted", + scope: { ring: "worktree" }, + mechanismAliases: [], + applicabilityConditions: [], + nonApplicabilityConditions: [], + falsificationConditions: [], + structuredFacets: {}, + evidenceRefs: [], + contradictedByLessonIds: [], + }); + expect(normalized.contentFingerprint).toMatch(/^lfp_[a-f0-9]{16}$/); + expect(JSON.stringify(legacy)).toBe(before); + + const roundTrip = parseImportedLesson(normalized); + expect(roundTrip).toMatchObject({ + success: true, + lesson: { + scope: { ring: "worktree" }, + sensitivity: "restricted", + }, + }); + }); + + it("keeps a refuted lesson active as negative evidence", () => { + const input = parsedLesson({ + evidenceVerdict: "refuted", + evidenceRefs: [ + evidence({ + evidenceKind: "falsification", + artifactDigest: `sha256:${"b".repeat(64)}`, + commitSha: undefined, + }), + ], + }); + + expect(input.evidenceVerdict).toBe("refuted"); + expect(input.lifecycle).toBe("active"); + }); + + it("rejects non-immutable and over-bounded evidence references", () => { + const pathOnly = parseLessonSaveInput({ + content: "Path-only evidence is insufficient", + mechanismId: "path-only", + claim: "A branch path proves the result.", + evidenceVerdict: "supported", + evidenceRefs: [ + { + kind: "document", + projectId: "agentmemory", + repoRemoteUrl: "https://github.com/rohitg00/agentmemory", + path: "report.md", + recordedAt: "2026-08-02T20:00:00.000Z", + branch: "main", + }, + ], + }); + const tooMany = parseLessonSaveInput({ + content: "Too many evidence references", + mechanismId: "bounded-evidence", + claim: "Evidence lists remain bounded.", + evidenceRefs: Array.from({ length: 9 }, (_, index) => + evidence({ + commitSha: index.toString(16).padStart(40, "0"), + }), + ), + }); + + expect(pathOnly).toMatchObject({ + success: false, + error: expect.stringContaining("not immutable proof"), + }); + expect(tooMany).toMatchObject({ + success: false, + error: expect.stringContaining("at most 8"), + }); + }); + + it("requires durable scope identity and human approval for global promotion", () => { + const missingCausalScope = parseLessonSaveInput({ + content: "Unscoped causal claim", + mechanismId: "scope/required", + claim: "Structured claims require durable scope.", + }); + const missingScopeId = parseLessonSaveInput({ + content: "Explicit repo scope", + scope: { ring: "repo" }, + }); + const missingApproval = parseLessonSaveInput({ + content: "Global claim", + scope: { ring: "global" }, + }); + const approved = parseLessonSaveInput({ + content: "Human-approved global claim", + scope: { + ring: "global", + humanApproval: { + approvedBy: "patrick", + approvedAt: "2026-08-02T22:00:00Z", + reason: "Reviewed evidence and approved global promotion", + }, + }, + }); + + expect(missingCausalScope).toMatchObject({ + success: false, + error: expect.stringContaining("explicit durable scope"), + }); + expect(missingScopeId).toMatchObject({ + success: false, + error: expect.stringContaining("scope.scopeId"), + }); + expect(missingApproval).toMatchObject({ + success: false, + error: expect.stringContaining("humanApproval"), + }); + expect(approved).toMatchObject({ + success: true, + value: { + scope: { + ring: "global", + humanApproval: { + approvedBy: "patrick", + approvedAt: "2026-08-02T22:00:00.000Z", + }, + }, + }, + }); + }); + + it("requires claim and mechanism together and evidence for verified verdicts", () => { + const partial = parseLessonSaveInput({ + content: "Incomplete causal record", + mechanismId: "partial", + }); + const unsupportedVerdict = parseLessonSaveInput({ + content: "Unsupported verdict", + mechanismId: "no-anchor", + claim: "This is supported.", + evidenceVerdict: "supported", + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + }); + const terminal = parseLessonSaveInput({ + content: "Bypass correction", + lifecycle: "retracted", + }); + + expect(partial).toMatchObject({ + success: false, + error: expect.stringContaining("both mechanismId and claim"), + }); + expect(unsupportedVerdict).toMatchObject({ + success: false, + error: expect.stringContaining("durable evidence reference"), + }); + expect(terminal).toMatchObject({ + success: false, + error: expect.stringContaining("audited correction API"), + }); + }); + + it("keeps durable scope and terminal tombstone invariants during import", () => { + const imported = { + ...legacyLesson(), + mechanismId: "import/invariants", + claim: "Imported causal records retain durable scope identity.", + scope: { ring: "worktree" }, + }; + const missingScopeId = parseImportedLesson(imported); + const missingTombstone = parseImportedLesson({ + ...legacyLesson(), + supersededByLessonId: "lsn_replacement", + }); + const retracted = parseImportedLesson({ + ...legacyLesson(), + lifecycle: "retracted", + deleted: true, + deletedAt: "2026-08-02T22:00:00.000Z", + deletedBy: "operator", + deleteReason: "Evidence artifact was invalid", + }); + + expect(missingScopeId).toMatchObject({ + success: false, + error: expect.stringContaining("scope.scopeId"), + }); + expect(missingTombstone).toMatchObject({ + success: false, + error: expect.stringContaining("deleted=true"), + }); + expect(retracted).toMatchObject({ + success: true, + lesson: { + lifecycle: "retracted", + deleted: true, + deleteReason: "Evidence artifact was invalid", + }, + }); + }); + + it("produces ordering-stable fingerprints and separates evidence records", () => { + const first = parsedLesson({ + content: "First prose rendering.", + applicabilityConditions: ["Condition B", "Condition A"], + structuredFacets: { + venue: ["Venue B", "Venue A"], + asset: ["BTC"], + }, + evidenceRefs: [ + evidence({ commitSha: "b".repeat(40) }), + evidence({ commitSha: "a".repeat(40) }), + ], + }); + const reordered = parsedLesson({ + content: "A materially different prose rendering.", + applicabilityConditions: ["Condition A", "Condition B"], + structuredFacets: { + asset: ["BTC"], + venue: ["Venue A", "Venue B"], + }, + evidenceRefs: [ + evidence({ commitSha: "a".repeat(40) }), + evidence({ commitSha: "b".repeat(40) }), + ], + }); + const newEvidence = parsedLesson({ + content: "Third prose rendering.", + applicabilityConditions: ["Condition A", "Condition B"], + structuredFacets: { + asset: ["BTC"], + venue: ["Venue A", "Venue B"], + }, + evidenceRefs: [evidence({ commitSha: "c".repeat(40) })], + }); + + expect(lessonContentFingerprint(first)).toBe( + lessonContentFingerprint(reordered), + ); + expect(lessonIdForInput(first)).toBe(lessonIdForInput(reordered)); + expect(lessonContentFingerprint(first)).toBe( + lessonContentFingerprint(newEvidence), + ); + expect(lessonIdForInput(first)).not.toBe(lessonIdForInput(newEvidence)); + }); + + it("computes staleness and contradiction without mutating confidence or lifecycle", () => { + const raw = legacyLesson({ + schemaVersion: 1, + evidenceVerdict: "unverified", + lifecycle: "active", + reviewAfter: "2026-01-01T00:00:00.000Z", + contradictedByLessonIds: ["lsn_counterexample"], + confidence: 0.81, + }); + const read = toLessonReadModel(raw, "2026-08-02T00:00:00.000Z"); + + expect(read.computedFlags).toEqual({ + stale: true, + contradicted: true, + }); + expect(read.confidence).toBe(0.81); + expect(read.lifecycle).toBe("active"); + expect(raw.confidence).toBe(0.81); + }); +}); diff --git a/test/lessons.test.ts b/test/lessons.test.ts index 1e85dbb40c..f586aa4012 100644 --- a/test/lessons.test.ts +++ b/test/lessons.test.ts @@ -91,7 +91,7 @@ describe("Lessons", () => { expect(result.lesson.confidence).toBe(0.5); }); - it("strengthens existing lesson on duplicate content", async () => { + it("records duplicate reinforcement without changing confidence", async () => { const first = (await sdk.trigger("mem::lesson-save", { content: "Duplicate lesson", })) as { action: string; lesson: Lesson }; @@ -106,7 +106,7 @@ describe("Lessons", () => { expect(second.action).toBe("strengthened"); expect(second.lesson.id).toBe(originalId); expect(second.lesson.reinforcements).toBe(1); - expect(second.lesson.confidence).toBeGreaterThan(0.5); + expect(second.lesson.confidence).toBe(0.5); }); it("rejects empty content", async () => { @@ -196,6 +196,28 @@ describe("Lessons", () => { expect(result.success).toBe(false); }); + + it("keeps draft lessons listable but out of active recall", async () => { + const saved = (await sdk.trigger("mem::lesson-save", { + content: "Draft lesson pending review", + lifecycle: "draft", + })) as { lesson: Lesson }; + const recall = (await sdk.trigger("mem::lesson-recall", { + query: "draft pending review", + })) as { lessons: Lesson[] }; + const list = (await sdk.trigger("mem::lesson-list", {})) as { + lessons: Lesson[]; + }; + + expect(saved.lesson.lifecycle).toBe("draft"); + expect(recall.lessons).toEqual([]); + expect(list.lessons).toContainEqual( + expect.objectContaining({ + id: saved.lesson.id, + lifecycle: "draft", + }), + ); + }); }); describe("mem::lesson-list", () => { @@ -314,7 +336,7 @@ describe("Lessons", () => { }); describe("mem::lesson-strengthen", () => { - it("increases confidence with diminishing returns", async () => { + it("tracks reinforcement without changing evidence confidence", async () => { const saved = (await sdk.trigger("mem::lesson-save", { content: "Strengthen me", confidence: 0.5, @@ -326,11 +348,11 @@ describe("Lessons", () => { expect(result.success).toBe(true); expect(result.lesson.reinforcements).toBe(1); - expect(result.lesson.confidence).toBeCloseTo(0.55, 2); + expect(result.lesson.confidence).toBe(0.5); expect(result.lesson.lastReinforcedAt).toBeDefined(); }); - it("caps confidence at 1.0", async () => { + it("does not silently increase high confidence", async () => { const saved = (await sdk.trigger("mem::lesson-save", { content: "High confidence", confidence: 0.95, @@ -340,7 +362,7 @@ describe("Lessons", () => { lessonId: saved.lesson.id, })) as { lesson: Lesson }; - expect(result.lesson.confidence).toBeLessThanOrEqual(1.0); + expect(result.lesson.confidence).toBe(0.95); }); it("fails for missing lessonId", async () => { @@ -353,7 +375,7 @@ describe("Lessons", () => { }); describe("mem::lesson-decay-sweep", () => { - it("decays old lessons incrementally", async () => { + it("preserves incremental decay for legacy stored lessons", async () => { const saved = (await sdk.trigger("mem::lesson-save", { content: "Old lesson", confidence: 0.8, @@ -361,6 +383,7 @@ describe("Lessons", () => { const lessons = await kv.list("mem:lessons"); const lesson = lessons[0]; + delete lesson.schemaVersion; lesson.createdAt = new Date(Date.now() - 14 * 24 * 60 * 60 * 1000).toISOString(); await kv.set("mem:lessons", lesson.id, lesson); @@ -376,7 +399,7 @@ describe("Lessons", () => { expect(after!.lastDecayedAt).toBeDefined(); }); - it("does not decay lessons less than 1 week old", async () => { + it("does not decay normalized lessons without a review deadline", async () => { await sdk.trigger("mem::lesson-save", { content: "Recent lesson", confidence: 0.5, @@ -389,13 +412,14 @@ describe("Lessons", () => { expect(result.decayed).toBe(0); }); - it("soft-deletes low-confidence unreinforced lessons", async () => { + it("preserves legacy low-confidence soft deletion", async () => { const saved = (await sdk.trigger("mem::lesson-save", { content: "Weak lesson", confidence: 0.12, })) as { lesson: Lesson }; const lesson = await kv.get("mem:lessons", saved.lesson.id); + delete lesson!.schemaVersion; lesson!.createdAt = new Date(Date.now() - 21 * 24 * 60 * 60 * 1000).toISOString(); await kv.set("mem:lessons", lesson!.id, lesson!); @@ -409,13 +433,14 @@ describe("Lessons", () => { expect(after!.deleted).toBe(true); }); - it("uses lastDecayedAt for incremental delta (not full age)", async () => { + it("uses lastDecayedAt for legacy incremental delta", async () => { const saved = (await sdk.trigger("mem::lesson-save", { content: "Incremental decay", confidence: 0.8, })) as { lesson: Lesson }; const lesson = await kv.get("mem:lessons", saved.lesson.id); + delete lesson!.schemaVersion; lesson!.createdAt = new Date(Date.now() - 28 * 24 * 60 * 60 * 1000).toISOString(); lesson!.lastDecayedAt = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(); lesson!.confidence = 0.6; @@ -427,5 +452,31 @@ describe("Lessons", () => { expect(after!.confidence).toBeCloseTo(0.55, 2); expect(after!.confidence).toBeGreaterThan(0.4); }); + + it("computes schema-v1 staleness without mutating confidence or lifecycle", async () => { + const saved = (await sdk.trigger("mem::lesson-save", { + content: "Review this evidence later", + confidence: 0.8, + reviewAfter: "2020-01-01T00:00:00.000Z", + })) as { lesson: Lesson }; + + const result = (await sdk.trigger("mem::lesson-decay-sweep", {})) as { + stale: number; + decayed: number; + softDeleted: number; + }; + const after = await kv.get("mem:lessons", saved.lesson.id); + + expect(result).toMatchObject({ + stale: 1, + decayed: 0, + softDeleted: 0, + }); + expect(after).toMatchObject({ + confidence: 0.8, + lifecycle: "active", + }); + expect(after?.deleted).not.toBe(true); + }); }); }); From 36806e7006971392adb47d38b03996f042a31cf8 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Sun, 2 Aug 2026 22:06:13 -0400 Subject: [PATCH 33/43] fix: harden causal lesson schema invariants --- README.md | 21 +- .../2026-08-02-causal-lesson-schema-v1.md | 120 ++- src/functions/diagnostics.ts | 18 +- src/functions/export-import.ts | 388 +++++++++- src/functions/lesson-locks.ts | 29 + src/functions/lesson-model.ts | 695 ++++++++++++++++-- src/functions/lessons.ts | 261 ++++--- src/functions/reflect.ts | 89 ++- src/functions/replay.ts | 87 ++- src/functions/smart-search.ts | 47 +- src/mcp/tools-registry.ts | 47 +- src/prompts/reflect.ts | 45 +- src/types.ts | 49 +- test/causal-lessons-api.test.ts | 89 +++ test/diagnostics.test.ts | 35 + test/export-import.test.ts | 576 ++++++++++++++- test/lesson-corrections.test.ts | 5 + test/lesson-model.test.ts | 312 ++++++++ test/reflect.test.ts | 157 +++- test/replay-import-key.test.ts | 92 ++- test/smart-search.test.ts | 50 ++ 21 files changed, 2946 insertions(+), 266 deletions(-) create mode 100644 src/functions/lesson-locks.ts diff --git a/README.md b/README.md index 1af386e19e..7972b69fcc 100644 --- a/README.md +++ b/README.md @@ -1544,17 +1544,32 @@ prose-only lessons and also accept causal schema-v1 fields: of lifecycle (`draft`, `active`, `superseded`, `retracted`); - applicability, non-applicability, falsification conditions, and general string-valued facets; -- at most eight durable evidence references anchored by a full commit SHA - and/or artifact digest; +- at most eight durable evidence references using discriminated Git, + object-store/query snapshot, OCI, DOI/URN, dataset, or attestation + provenance plus an explicit verification state; - worktree/repo/initiative/domain/global scope rings and sensitivity classification. Structured causal lessons require an explicit durable scope; global scope also -requires human approval metadata. Legacy lessons normalize on read to +requires human approval metadata and forbids `scopeId`. Facet dimensions +normalize to ASCII snake case and must match `^[a-z][a-z0-9_]*$`. Schema-v1 +approval, evidence, verification, and review timestamps require a +calendar-valid RFC3339 value with an explicit `Z` or numeric offset. + +New supported/refuted/mixed saves require every evidence reference to carry an +explicit verified review. Import/read normalization preserves older Git-shaped +verdict rows through a visible `legacy-git-anchor` verification basis; this is +a compatibility classification and explicitly does not claim that evidence +relevance was re-audited. + +Legacy lessons normalize on read to `unverified` + `active` with an implicit worktree scope and `sensitivity: restricted`; reads do not rewrite stored rows. Reinforcement records reuse without increasing evidence confidence. Supersession/retraction continue through the audited correction APIs. +Compact smart-search results retain claim/verdict/contradiction labels. +Reflection treats refuted claims as negative evidence and will not persist a +supported synthesis from a cluster containing refuted or contradicted lessons. Scope and sensitivity enforcement, automatic contradiction discovery, and hybrid/vector lesson retrieval are intentionally deferred to PR2. Until then, diff --git a/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md b/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md index e254bb8d38..7c9d624f2f 100644 --- a/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md +++ b/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md @@ -22,6 +22,7 @@ Stored legacy lessons are not rewritten by reads. Recall, list, context, JSON export, and Obsidian export normalize them in memory to: - `schemaVersion: 1` +- `identityKind: "legacy-prose"` and a canonical `lsn_*` alias - `evidenceVerdict: "unverified"` - `lifecycle: "active"` unless correction metadata proves supersession or retraction - `scope: { ring: "worktree" }` @@ -31,6 +32,9 @@ export, and Obsidian export normalize them in memory to: The legacy `project` field remains a label and compatibility filter. It is not used as a durable cross-repository join key for structured corrections. +Malformed rows carrying schema-v1 or structured markers never fall back to +legacy defaults. Export rejects them with the field diagnostic and leaves the +raw row untouched; `mem::diagnose` reports them as invalid structured lessons. ## Causal identity and claim @@ -45,6 +49,14 @@ A structured causal lesson uses: If any causal structure is supplied, both `mechanismId` and `claim` are required. Legacy prose-only saves remain valid. +Structured saves, structured imports, and replay-derived lessons all use the +same canonical `lsn_*` identity helper. Import deterministically remaps a +caller-provided structured ID and records it in `idAliases`. Two rows claiming +the same canonical ID or alias are rejected. Prose IDs are preserved only when +the normalized row explicitly carries `identityKind: "legacy-prose"`; +canonical aliases prevent replay/save duplicates during the compatibility +window. + ## Evidence verdict and lifecycle Evidence and lifecycle are independent: @@ -56,8 +68,12 @@ Evidence and lifecycle are independent: A refuted active lesson remains recallable negative evidence. Recall payloads retain the verdict, and injected context labels it explicitly so refutation is -not presented as a supported instruction. Retraction means the evidence itself -is invalid. Supersession means another active lesson replaces this record. +not presented as a supported instruction. Compact smart-search results also +retain `claim`, `evidenceVerdict`, an explicit evidence label, and contradiction +state. Reflection places refuted/contradicted lessons in a separate +counterevidence section and refuses to persist a supported synthesis from a +cluster containing that evidence. Retraction means the evidence itself is +invalid. Supersession means another active lesson replaces this record. Normal save calls may create only draft or active records. Terminal lifecycle changes reuse the audited correction functions: @@ -79,8 +95,11 @@ The schema is domain-neutral: - `falsificationConditions` - `structuredFacets: Record` -Facet dimensions are normalized to lowercase snake case. Values remain general -strings. Trading examples such as `asset`, `venue`, `horizon`, `regime`, and +Facet dimensions normalize spaces/hyphens to underscores and must then be +ASCII snake case matching `^[a-z][a-z0-9_]*$`. Slashes, punctuation, Unicode +letters, leading digits, and unsafe reserved names such as `constructor`, +`prototype`, and `__proto__` are rejected. Values remain general strings. +Trading examples such as `asset`, `venue`, `horizon`, `regime`, and `signal_family` are conventions, not hard-coded schema dimensions. Each condition list is bounded to 16 entries. Facets are bounded to 32 @@ -92,14 +111,51 @@ dimensions and 16 values per dimension. - `kind` - `projectId` as a label -- `repoRemoteUrl` -- at least one full immutable anchor: `commitSha` or `artifactDigest` +- discriminated `provenance` +- explicit `verification` - `recordedAt` -Optional fields are `path`, `validatedAt`, `evidenceKind`, and `sampleCount`. -A branch, ref, or path without a full commit SHA or artifact digest is rejected. -Supported, refuted, and mixed verdicts require at least one valid evidence -reference. +Provenance supports: + +| Type | Required immutable identity | +| --- | --- | +| `git` | normalized remote plus full commit SHA and/or digest | +| `object-store` | immutable object/version ID and/or digest | +| `database-query` | immutable snapshot/query-result ID and/or digest | +| `oci` | digest | +| `doi` | valid DOI | +| `urn` | valid URN | +| `dataset` | immutable release ID and/or digest | +| `attestation` | digest | + +Optional evidence fields remain `path`, `validatedAt`, `evidenceKind`, and +`sampleCount`. The old top-level Git shape (`repoRemoteUrl`, `commitSha`, +`artifactDigest`, `path`) remains import/read compatible and normalizes to +`provenance.type: "git"`. + +Verification state is `unverified`, `verified`, or `rejected`. Verified and +rejected decisions require actor/time metadata. New supported, refuted, and +mixed saves require every reference to be explicitly verified; a syntactically +immutable locator alone is not evidence-relevance approval. + +Older Git-shaped supported/refuted/mixed rows that predate verification +metadata are not rejected or downgraded. Import/read normalization assigns: + +```json +{ + "state": "verified", + "basis": "legacy-git-anchor", + "verifiedBy": "agentmemory:legacy-git-anchor-migration", + "verifiedAt": "" +} +``` + +This explicit compatibility basis preserves the prior verdict. It does not +assert that relevance was newly audited. New REST/MCP saves cannot select the +reserved migration basis. + +A branch, ref, or path without the immutable identity required by its +provenance type is rejected. ## Scope and sensitivity @@ -112,9 +168,10 @@ reference. - `global` A structured causal lesson requires an explicit scope. A non-global scope -requires a separate durable `scope.scopeId`. `project`/`projectId` labels do -not substitute for it. Legacy prose lessons retain the fail-closed implicit -worktree scope for compatibility. +requires a separate durable `scope.scopeId`; global scope rejects `scopeId`. +`project`/`projectId` labels do not substitute for durable scope identity. +Legacy prose lessons retain the fail-closed implicit worktree scope for +compatibility. Global scope requires: @@ -129,6 +186,12 @@ Global scope requires: } ``` +All schema-v1 approval, evidence-recording, evidence-validation, verification, +and review timestamps require a calendar-valid RFC3339 timestamp with an +explicit `Z` or numeric offset. They canonicalize to UTC before storage or +fingerprinting. Timezone-less inputs and impossible dates such as February 30 +are rejected. + Sensitivity is `public`, `internal`, `confidential`, or `restricted`, with a fail-closed default of `restricted`. @@ -147,6 +210,11 @@ Schema-v1 lessons are not confidence-decayed or soft-deleted by the legacy decay sweep. `reviewAfter` computes `computedFlags.stale` at read time. The optional `contradictedByLessonIds` relation metadata computes `computedFlags.contradicted`. Neither flag changes lifecycle or confidence. +Contradiction targets must exist, remain active, differ from the source, and +share both durable scope and the current project label. The project-label +equality check is a PR1 fail-closed authority bound, not a cross-repository join +mechanism. Supersession targets must exist, remain active, differ from the +source, and share durable scope. Pre-schema stored lessons retain the old decay behavior until an explicit replay/import normalizes them. This preserves backward compatibility without a @@ -166,10 +234,11 @@ prose, evidence verdict, evidence anchors, lifecycle, popularity, and confidence do not alter the content fingerprint. Structured lesson IDs additionally include verdict, immutable evidence -references, lifecycle, scope, sensitivity, review deadline, and contradiction -links. This allows two records to share a causal content fingerprint while -preserving distinct evidence packages or verdicts for later near-duplicate -analysis. +references, scope, sensitivity, and review deadline. Lifecycle and relation +links do not alter identity, so an audited correction retains a stable lesson +ID and relation batches do not become recursively order-dependent. This allows +two records to share a causal content fingerprint while preserving distinct +evidence packages or verdicts for later near-duplicate analysis. Object keys and unordered arrays are canonicalized before hashing. Fingerprint comparison never relies on insertion order or raw `JSON.stringify` ordering. @@ -180,8 +249,19 @@ REST and MCP lesson-save handlers validate and whitelist structured fields before calling `mem::lesson-save`. REST lesson search now whitelists its query fields instead of forwarding the raw request body. -JSON import validates all lessons, bounds the collection, rejects duplicate -lesson IDs, recomputes deterministic fingerprints, and completes validation -before a replace strategy deletes existing state. +JSON import accepts only `merge`, `replace`, or `skip`. It canonicalizes +structured IDs, resolves aliases independent of batch order, validates the +complete post-import supersession/contradiction graph, bounds the collection, +strips computed read-model fields, and completes lesson preflight under the +shared lesson mutation lock. + +Default merge never replaces a retracted/superseded row with a non-terminal +row. Whole-collection `replace` is the explicit restore path. Both successful +changes and restore transitions audit affected IDs and before/after lifecycle +metadata. Lesson delete/set application records the exact preimage; if a KV +operation fails mid-batch, import restores and verifies every affected row, +reports rollback failures explicitly, and writes a rollback audit when +possible. Save, correction, replay, decay, and import share the mutation lock, +so a concurrent correction cannot be resurrected between preflight and write. No retrieval or ranking engine is introduced in this PR. diff --git a/src/functions/diagnostics.ts b/src/functions/diagnostics.ts index 935a5b9b2c..6b15c515ce 100644 --- a/src/functions/diagnostics.ts +++ b/src/functions/diagnostics.ts @@ -409,8 +409,24 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { // Catches bad confidence values that would silently break recall // scoring (memory_lesson_recall multiplies by confidence). const lessons = await kv.list(KV.lessons); - const live = lessons.filter(isLessonListable); + const live: Lesson[] = []; let lessonIssues = 0; + for (const lesson of lessons) { + try { + if (isLessonListable(lesson)) live.push(lesson); + } catch (error) { + checks.push({ + name: `lesson-invalid-structured:${lesson.id}`, + category: "lessons", + status: "fail", + message: `Lesson ${lesson.id} has invalid structured data: ${ + error instanceof Error ? error.message : String(error) + }`, + fixable: false, + }); + lessonIssues++; + } + } for (const l of live) { // Number.isFinite rejects NaN / Infinity / non-numbers; a // corrupted row passing those would silently survive the < / > diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index ca982aadb6..e890e65574 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -1,4 +1,5 @@ import type { ISdk } from "iii-sdk"; +import { isDeepStrictEqual } from "node:util"; import type { Session, CompressedObservation, @@ -41,9 +42,25 @@ import { withActionStoreLock, } from "./action-store.js"; import { + isLessonRecallable, normalizeLesson, parseImportedLesson, + sameLessonContradictionScope, + sameLessonScope, } from "./lesson-model.js"; +import { withLessonMutationLock } from "./lesson-locks.js"; + +interface ImportedLessonCandidate { + lesson: Lesson; + sourceId: string; + canonicalized: boolean; +} + +interface LessonLifecycleTransition { + lessonId: string; + before?: string; + after?: string; +} export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::export", @@ -199,7 +216,19 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { ) { return { success: false, error: "exportData with string version is required" }; } - const strategy = data.strategy || "merge"; + const requestedStrategy = (data as { strategy?: unknown }).strategy; + if ( + requestedStrategy !== undefined && + requestedStrategy !== "merge" && + requestedStrategy !== "replace" && + requestedStrategy !== "skip" + ) { + return { + success: false, + error: "strategy must be merge, replace, or skip", + }; + } + const strategy = requestedStrategy ?? "merge"; const importData = data.exportData; const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27"]); @@ -295,8 +324,9 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { error: `Too many lessons (max ${MAX_LESSONS})`, }; } - const normalizedImportedLessons: Lesson[] = []; + const normalizedImportedLessons: ImportedLessonCandidate[] = []; const importedLessonIds = new Set(); + const importedLessonAliases = new Map(); for (const lesson of importedLessons) { const parsed = parseImportedLesson(lesson); if (!parsed.success) { @@ -312,7 +342,21 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { }; } importedLessonIds.add(parsed.lesson.id); - normalizedImportedLessons.push(parsed.lesson); + for (const alias of [ + parsed.sourceId, + ...(parsed.lesson.idAliases ?? []), + parsed.lesson.id, + ]) { + const claimedBy = importedLessonAliases.get(alias); + if (claimedBy && claimedBy !== parsed.lesson.id) { + return { + success: false, + error: `Duplicate lesson identity alias ${alias}: ${claimedBy}, ${parsed.lesson.id}`, + }; + } + importedLessonAliases.set(alias, parsed.lesson.id); + } + normalizedImportedLessons.push(parsed); } const importedActions = Array.isArray(importData.actions) @@ -460,6 +504,21 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { } } } + if ( + importData.accessLogs !== undefined && + !Array.isArray(importData.accessLogs) + ) { + return { success: false, error: "accessLogs must be an array" }; + } + if ( + Array.isArray(importData.accessLogs) && + importData.accessLogs.length > MAX_ACCESS_LOGS + ) { + return { + success: false, + error: `Too many access logs (max ${MAX_ACCESS_LOGS})`, + }; + } const stats = { sessions: 0, @@ -473,6 +532,19 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { skipped: 0, }; + const lessonImport = await withLessonMutationLock(() => + applyImportedLessonBatch( + kv, + normalizedImportedLessons, + strategy, + ), + ); + if (!lessonImport.success) { + return { success: false, error: lessonImport.error }; + } + stats.lessons = lessonImport.written; + stats.skipped += lessonImport.skipped; + if (strategy === "replace") { const existing = await kv.list(KV.sessions); for (const session of existing) { @@ -513,9 +585,6 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { for (const f of await kv.list(KV.facets).catch(() => [])) { await kv.delete(KV.facets, f.id); } - for (const l of await kv.list(KV.lessons).catch(() => [])) { - await kv.delete(KV.lessons, l.id); - } for (const i of await kv.list(KV.insights).catch(() => [])) { await kv.delete(KV.insights, i.id); } @@ -819,19 +888,6 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { await kv.set(KV.facets, facet.id, facet); } } - for (const lesson of normalizedImportedLessons) { - if (strategy === "skip") { - const existing = await kv - .get(KV.lessons, lesson.id) - .catch(() => null); - if (existing) { - stats.skipped++; - continue; - } - } - await kv.set(KV.lessons, lesson.id, lesson); - stats.lessons++; - } if (importData.insights) { for (const insight of importData.insights) { if (strategy === "skip") { @@ -842,15 +898,6 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { } } if (importData.accessLogs) { - if (!Array.isArray(importData.accessLogs)) { - return { success: false, error: "accessLogs must be an array" }; - } - if (importData.accessLogs.length > MAX_ACCESS_LOGS) { - return { - success: false, - error: `Too many access logs (max ${MAX_ACCESS_LOGS})`, - }; - } const memoryIds = new Set( importData.memories.map((m) => m.id), ); @@ -880,6 +927,291 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { ); } +async function applyImportedLessonBatch( + kv: StateKV, + imported: ImportedLessonCandidate[], + strategy: "merge" | "replace" | "skip", +): Promise< + | { success: true; written: number; skipped: number } + | { success: false; error: string } +> { + const existingRows = await kv.list(KV.lessons).catch(() => []); + const preimage = new Map( + existingRows.map((lesson) => [lesson.id, lesson] as const), + ); + const existing = new Map(); + const existingAliases = new Map(); + for (const row of existingRows) { + let normalized: Lesson; + try { + normalized = normalizeLesson(row); + } catch (error) { + return { + success: false, + error: `Invalid existing structured lesson ${row.id}: ${ + error instanceof Error ? error.message : String(error) + }`, + }; + } + existing.set(normalized.id, normalized); + for (const alias of [ + normalized.id, + ...(normalized.idAliases ?? []), + ]) { + const claimedBy = existingAliases.get(alias); + if (claimedBy && claimedBy !== normalized.id) { + return { + success: false, + error: `Existing lesson identity alias conflict ${alias}: ${claimedBy}, ${normalized.id}`, + }; + } + existingAliases.set(alias, normalized.id); + } + } + + const incomingAliases = new Map(); + for (const candidate of imported) { + for (const alias of [ + candidate.sourceId, + candidate.lesson.id, + ...(candidate.lesson.idAliases ?? []), + ]) { + const claimedBy = incomingAliases.get(alias); + if (claimedBy && claimedBy !== candidate.lesson.id) { + return { + success: false, + error: `Imported lesson identity alias conflict ${alias}: ${claimedBy}, ${candidate.lesson.id}`, + }; + } + const existingOwner = existingAliases.get(alias); + if ( + strategy !== "replace" && + existingOwner && + existingOwner !== candidate.lesson.id + ) { + return { + success: false, + error: `Imported lesson identity ${alias} conflicts with existing lesson ${existingOwner}`, + }; + } + incomingAliases.set(alias, candidate.lesson.id); + } + } + + const resolveRelationId = (id: string): string => + incomingAliases.get(id) ?? existingAliases.get(id) ?? id; + const incoming = new Map(); + for (const candidate of imported) { + const rewritten = normalizeLesson({ + ...candidate.lesson, + supersededByLessonId: candidate.lesson.supersededByLessonId + ? resolveRelationId(candidate.lesson.supersededByLessonId) + : undefined, + contradictedByLessonIds: ( + candidate.lesson.contradictedByLessonIds ?? [] + ) + .map(resolveRelationId) + .filter((id, index, ids) => ids.indexOf(id) === index) + .sort(), + }); + incoming.set(rewritten.id, rewritten); + } + + const finalLessons = + strategy === "replace" + ? new Map(incoming) + : new Map(existing); + let skipped = 0; + for (const [id, lesson] of incoming) { + const current = existing.get(id); + if (strategy === "skip" && current) { + skipped++; + continue; + } + if ( + strategy === "merge" && + current && + (current.lifecycle === "retracted" || + current.lifecycle === "superseded") && + lesson.lifecycle !== current.lifecycle + ) { + return { + success: false, + error: `Merge import cannot replace terminal ${current.lifecycle} lesson ${id} with ${lesson.lifecycle}; use replace import for an explicit audited restore`, + }; + } + finalLessons.set(id, lesson); + } + + const graphError = validateLessonGraph(finalLessons); + if (graphError) return { success: false, error: graphError }; + + const writes = [...incoming.values()].filter( + (lesson) => strategy !== "skip" || !existing.has(lesson.id), + ); + const deletes = + strategy === "replace" + ? [...existing.keys()].filter((id) => !incoming.has(id)) + : []; + const transitions: LessonLifecycleTransition[] = []; + for (const lesson of writes) { + transitions.push({ + lessonId: lesson.id, + before: existing.get(lesson.id)?.lifecycle, + after: normalizeLesson(lesson).lifecycle, + }); + } + for (const id of deletes) { + transitions.push({ + lessonId: id, + before: existing.get(id)?.lifecycle, + after: undefined, + }); + } + + const affectedIds = transitions.map((transition) => transition.lessonId); + const auditDetails = { + strategy, + canonicalizedIds: imported + .filter((candidate) => candidate.canonicalized) + .map((candidate) => ({ + sourceId: candidate.sourceId, + lessonId: candidate.lesson.id, + })), + lifecycleTransitions: transitions, + }; + try { + for (const id of deletes) { + await kv.delete(KV.lessons, id); + } + for (const lesson of writes) { + await kv.set(KV.lessons, lesson.id, lesson); + } + if (affectedIds.length > 0) { + await recordAudit( + kv, + "import", + "mem::import:lessons", + affectedIds, + auditDetails, + ); + } + } catch (error) { + const rollback = await restoreLessonPreimage( + kv, + affectedIds, + preimage, + ); + let auditError: string | undefined; + try { + await recordAudit( + kv, + "import", + "mem::import:lessons-rollback", + affectedIds, + { + ...auditDetails, + applyError: error instanceof Error ? error.message : String(error), + rollback, + }, + ); + } catch (rollbackAuditError) { + auditError = + rollbackAuditError instanceof Error + ? rollbackAuditError.message + : String(rollbackAuditError); + } + const applyError = error instanceof Error ? error.message : String(error); + if (!rollback.success) { + return { + success: false, + error: `Lesson import failed (${applyError}); rollback failed: ${rollback.errors.join("; ")}${auditError ? `; rollback audit failed: ${auditError}` : ""}`, + }; + } + return { + success: false, + error: `Lesson import failed (${applyError}); exact preimage restored${auditError ? `; rollback audit failed: ${auditError}` : ""}`, + }; + } + return { success: true, written: writes.length, skipped }; +} + +async function restoreLessonPreimage( + kv: StateKV, + affectedIds: string[], + preimage: Map, +): Promise<{ success: boolean; errors: string[] }> { + const errors: string[] = []; + for (const id of [...new Set(affectedIds)].reverse()) { + try { + const before = preimage.get(id); + if (before) { + await kv.set(KV.lessons, id, before); + } else { + await kv.delete(KV.lessons, id); + } + } catch (error) { + errors.push( + `${id}: ${error instanceof Error ? error.message : String(error)}`, + ); + } + } + for (const id of new Set(affectedIds)) { + try { + const actual = await kv.get(KV.lessons, id); + const expected = preimage.get(id) ?? null; + if (!isDeepStrictEqual(actual, expected)) { + errors.push(`${id}: preimage verification mismatch`); + } + } catch (error) { + errors.push( + `${id}: verification failed: ${ + error instanceof Error ? error.message : String(error) + }`, + ); + } + } + return { success: errors.length === 0, errors }; +} + +function validateLessonGraph(lessons: Map): string | null { + for (const lesson of lessons.values()) { + const normalized = normalizeLesson(lesson); + const supersededBy = normalized.supersededByLessonId; + if (supersededBy) { + if (supersededBy === normalized.id) { + return `Lesson ${normalized.id} cannot supersede itself`; + } + const target = lessons.get(supersededBy); + if (!target) { + return `Lesson ${normalized.id} has dangling supersession target ${supersededBy}`; + } + if (!isLessonRecallable(target)) { + return `Lesson ${normalized.id} supersession target ${supersededBy} must be active`; + } + if (!sameLessonScope(normalized, target)) { + return `Lesson ${normalized.id} supersession target ${supersededBy} crosses durable scope`; + } + } + for (const contradictionId of normalized.contradictedByLessonIds) { + if (contradictionId === normalized.id) { + return `Lesson ${normalized.id} cannot contradict itself`; + } + const target = lessons.get(contradictionId); + if (!target) { + return `Lesson ${normalized.id} has dangling contradiction target ${contradictionId}`; + } + if (!isLessonRecallable(target)) { + return `Lesson ${normalized.id} contradiction target ${contradictionId} must be active`; + } + if (!sameLessonContradictionScope(normalized, target)) { + return `Lesson ${normalized.id} contradiction target ${contradictionId} crosses durable scope or project`; + } + } + } + return null; +} + function collectImportedActionsWithDerivedBlockers( actions: Action[], edges: ActionEdge[], diff --git a/src/functions/lesson-locks.ts b/src/functions/lesson-locks.ts new file mode 100644 index 0000000000..71217a44d0 --- /dev/null +++ b/src/functions/lesson-locks.ts @@ -0,0 +1,29 @@ +import { withKeyedLock } from "../state/keyed-mutex.js"; + +const LESSON_MUTATION_LOCK = "mem:lessons:mutation"; + +function lessonLockKey(lessonId: string): string { + return `mem:lesson:${lessonId}`; +} + +export function withLessonMutationLock( + fn: () => Promise, +): Promise { + return withKeyedLock(LESSON_MUTATION_LOCK, fn); +} + +export function withLessonLocks( + lessonIds: string[], + fn: () => Promise, +): Promise { + return withLessonMutationLock(() => { + const orderedIds = [...new Set(lessonIds)].sort(); + const lockNext = (index: number): Promise => { + if (index >= orderedIds.length) return fn(); + return withKeyedLock(lessonLockKey(orderedIds[index]), () => + lockNext(index + 1), + ); + }; + return lockNext(0); + }); +} diff --git a/src/functions/lesson-model.ts b/src/functions/lesson-model.ts index 161e6a196a..b55960104d 100644 --- a/src/functions/lesson-model.ts +++ b/src/functions/lesson-model.ts @@ -2,7 +2,11 @@ import { fingerprintId } from "../state/schema.js"; import type { Lesson, LessonClaimType, + LessonEvidenceProvenance, + LessonEvidenceProvenanceType, LessonEvidenceReference, + LessonEvidenceVerification, + LessonEvidenceVerificationState, LessonEvidenceVerdict, LessonHumanApproval, LessonLifecycle, @@ -31,6 +35,21 @@ const MAX_EVIDENCE_KIND_LENGTH = 64; const MAX_EVIDENCE_PROJECT_ID_LENGTH = 128; const MAX_EVIDENCE_REMOTE_LENGTH = 2048; const MAX_EVIDENCE_PATH_LENGTH = 1024; +const MAX_EVIDENCE_LOCATOR_LENGTH = 2048; +const MAX_EVIDENCE_IMMUTABLE_ID_LENGTH = 512; +const MAX_EVIDENCE_VERIFIER_LENGTH = 256; +const MAX_EVIDENCE_VERIFICATION_NOTE_LENGTH = 1000; +const MAX_LESSON_ID_ALIASES = 16; +const MAX_LESSON_ID_LENGTH = 256; + +const FACET_DIMENSION_PATTERN = /^[a-z][a-z0-9_]*$/; +const RESERVED_FACET_DIMENSIONS = new Set([ + "__proto__", + "constructor", + "prototype", +]); +const EXPLICIT_RFC3339_PATTERN = + /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|([+-])(\d{2}):(\d{2}))$/; const EVIDENCE_VERDICTS = new Set([ "supported", @@ -64,6 +83,21 @@ const SENSITIVITIES = new Set([ "confidential", "restricted", ]); +const PROVENANCE_TYPES = new Set([ + "git", + "object-store", + "database-query", + "oci", + "doi", + "urn", + "dataset", + "attestation", +]); +const VERIFICATION_STATES = new Set([ + "unverified", + "verified", + "rejected", +]); export interface LessonSaveInput { content: string; @@ -100,6 +134,7 @@ type LessonParseOptions = { allowImplicitWorktreeScope?: boolean; source?: "crystal" | "manual" | "consolidation"; allowSourceMetadata?: boolean; + allowLegacyGitVerificationMigration?: boolean; }; class LessonInputError extends Error {} @@ -207,7 +242,10 @@ export function parseLessonSaveInput( const structuredFacets = normalizeStructuredFacets( record.structuredFacets, ); - const evidenceRefs = normalizeEvidenceRefs(record.evidenceRefs); + const evidenceRefs = normalizeEvidenceRefs( + record.evidenceRefs, + options.allowLegacyGitVerificationMigration === true, + ); const scope = normalizeScope( record.scope, options.allowImplicitWorktreeScope === true, @@ -218,7 +256,7 @@ export function parseLessonSaveInput( "sensitivity", SENSITIVITIES, ) ?? "restricted"; - const reviewAfter = optionalDate(record.reviewAfter, "reviewAfter"); + const reviewAfter = optionalStrictDate(record.reviewAfter, "reviewAfter"); const contradictedByLessonIds = normalizeStringArray( record.contradictedByLessonIds, "contradictedByLessonIds", @@ -264,6 +302,16 @@ export function parseLessonSaveInput( `${evidenceVerdict} lessons require at least one durable evidence reference`, ); } + if ( + evidenceVerdict !== "unverified" && + evidenceRefs.some( + (reference) => reference.verification?.state !== "verified", + ) + ) { + throw new LessonInputError( + `${evidenceVerdict} lessons require every evidence reference to be explicitly verified`, + ); + } return { success: true, @@ -336,17 +384,16 @@ export function lessonIdForInput(input: LessonSaveInput): string { contentFingerprint: lessonContentFingerprint(input), evidenceVerdict: input.evidenceVerdict, evidenceRefs: input.evidenceRefs, - lifecycle: input.lifecycle, scope: input.scope, sensitivity: input.sensitivity, reviewAfter: input.reviewAfter, - contradictedByLessonIds: input.contradictedByLessonIds, }), ); } export function normalizeLesson(lesson: Lesson): NormalizedLesson { const lifecycle = deriveLifecycle(lesson); + const structuredMarkers = hasStructuredLessonMarkers(lesson); const parsed = parseLessonSaveInput( { ...lesson, @@ -355,33 +402,73 @@ export function normalizeLesson(lesson: Lesson): NormalizedLesson { { allowTerminalLifecycle: true, allowImplicitWorktreeScope: true, + allowLegacyGitVerificationMigration: true, }, ); - const fallback = parseLessonSaveInput( - { - content: - typeof lesson.content === "string" && lesson.content.trim() - ? lesson.content - : lesson.id || "legacy-lesson", - context: typeof lesson.context === "string" ? lesson.context : "", - confidence: lesson.confidence, - project: lesson.project, - tags: Array.isArray(lesson.tags) ? lesson.tags : [], - source: lesson.source, - sourceIds: Array.isArray(lesson.sourceIds) ? lesson.sourceIds : [], - lifecycle, - }, + if (!parsed.success && structuredMarkers) { + throw new Error(`Invalid structured lesson ${lesson.id}: ${parsed.error}`); + } + const legacyFallback = parsed.success + ? undefined + : parseLessonSaveInput( + { + content: + typeof lesson.content === "string" && lesson.content.trim() + ? lesson.content + : lesson.id || "legacy-lesson", + context: typeof lesson.context === "string" ? lesson.context : "", + confidence: lesson.confidence, + project: lesson.project, + tags: Array.isArray(lesson.tags) ? lesson.tags : [], + source: lesson.source, + sourceIds: Array.isArray(lesson.sourceIds) ? lesson.sourceIds : [], + lifecycle, + }, + { + allowTerminalLifecycle: true, + allowImplicitWorktreeScope: true, + }, + ); + if (legacyFallback && !legacyFallback.success) { + throw new Error( + `Invalid legacy lesson ${lesson.id}: ${legacyFallback.error}`, + ); + } + const value = parsed.success ? parsed.value : legacyFallback!.value; + const identityKind = + lesson.identityKind ?? + (structuredMarkers ? "canonical" : "legacy-prose"); + if ( + identityKind === "legacy-prose" && + (value.mechanismId || value.claim || hasCausalStructure(value)) + ) { + throw new Error( + `Invalid structured lesson ${lesson.id}: legacy-prose identity cannot carry causal structure`, + ); + } + const canonicalId = lessonIdForInput(value); + const idAliases = normalizeStringArray( + lesson.idAliases, + "idAliases", { - allowTerminalLifecycle: true, - allowImplicitWorktreeScope: true, + maxItems: MAX_LESSON_ID_ALIASES, + maxLength: MAX_LESSON_ID_LENGTH, + sort: true, }, - ); - if (!fallback.success) { - throw new Error(`Invalid legacy lesson ${lesson.id}: ${fallback.error}`); + ).filter((alias) => alias !== lesson.id); + if (identityKind === "legacy-prose" && canonicalId !== lesson.id) { + idAliases.push(canonicalId); + idAliases.sort(compareText); + } + if (new Set(idAliases).size > MAX_LESSON_ID_ALIASES) { + throw new Error( + `Invalid lesson ${lesson.id}: idAliases exceed ${MAX_LESSON_ID_ALIASES} entries after canonicalization`, + ); } - const value = parsed.success ? parsed.value : fallback.value; const normalized: NormalizedLesson = { ...lesson, + identityKind, + idAliases: [...new Set(idAliases)], content: value.content, context: value.context, confidence: @@ -467,10 +554,21 @@ export function isLessonRecallable(lesson: Lesson): boolean { export function parseImportedLesson( raw: unknown, -): { success: true; lesson: NormalizedLesson } | { success: false; error: string } { +): + | { + success: true; + lesson: NormalizedLesson; + sourceId: string; + canonicalized: boolean; + } + | { success: false; error: string } { try { const record = requireRecord(raw, "lesson"); - const id = requiredString(record.id, "lesson.id"); + const sourceId = requiredString( + record.id, + "lesson.id", + MAX_LESSON_ID_LENGTH, + ); const createdAt = requiredDate(record.createdAt, "lesson.createdAt"); const updatedAt = requiredDate(record.updatedAt, "lesson.updatedAt"); if ( @@ -484,11 +582,48 @@ export function parseImportedLesson( if (record.deleted !== undefined && typeof record.deleted !== "boolean") { throw new LessonInputError("lesson.deleted must be a boolean"); } + if ( + record.identityKind !== undefined && + record.identityKind !== "canonical" && + record.identityKind !== "legacy-prose" + ) { + throw new LessonInputError( + "lesson.identityKind must be canonical or legacy-prose", + ); + } + const explicitLegacy = record.identityKind === "legacy-prose"; + const legacyProse = + explicitLegacy || !hasStructuredLessonMarkers(record); const parsed = parseLessonSaveInput(record, { allowTerminalLifecycle: true, allowImplicitWorktreeScope: true, + allowLegacyGitVerificationMigration: true, }); if (!parsed.success) throw new LessonInputError(parsed.error); + if (legacyProse && hasCausalStructure(parsed.value)) { + throw new LessonInputError( + "legacy-prose identity cannot carry structured causal fields", + ); + } + const canonicalId = lessonIdForInput(parsed.value); + const id = legacyProse ? sourceId : canonicalId; + const idAliases = normalizeStringArray( + record.idAliases, + "lesson.idAliases", + { + maxItems: MAX_LESSON_ID_ALIASES, + maxLength: MAX_LESSON_ID_LENGTH, + sort: true, + }, + ).filter((alias) => alias !== id); + if (sourceId !== id) idAliases.push(sourceId); + if (legacyProse && canonicalId !== id) idAliases.push(canonicalId); + const uniqueAliases = [...new Set(idAliases)].sort(compareText); + if (uniqueAliases.length > MAX_LESSON_ID_ALIASES) { + throw new LessonInputError( + `lesson.idAliases must contain at most ${MAX_LESSON_ID_ALIASES} aliases after canonicalization`, + ); + } const deletedAt = optionalDate(record.deletedAt, "lesson.deletedAt"); const lastReinforcedAt = optionalDate( @@ -529,7 +664,7 @@ export function parseImportedLesson( "superseded lessons require supersededByLessonId", ); } - if (supersededByLessonId === id) { + if (supersededByLessonId === sourceId) { throw new LessonInputError( "supersededByLessonId must differ from lesson.id", ); @@ -537,6 +672,8 @@ export function parseImportedLesson( const candidate: Lesson = { id, + identityKind: legacyProse ? "legacy-prose" : "canonical", + idAliases: uniqueAliases, content: parsed.value.content, context: parsed.value.context, confidence: parsed.value.confidence ?? 0.5, @@ -583,7 +720,12 @@ export function parseImportedLesson( contradictedByLessonIds: parsed.value.contradictedByLessonIds, contentFingerprint: lessonContentFingerprint(parsed.value), }; - return { success: true, lesson: normalizeLesson(candidate) }; + return { + success: true, + lesson: normalizeLesson(candidate), + sourceId, + canonicalized: id !== sourceId, + }; } catch (error) { return { success: false, @@ -617,6 +759,31 @@ export function sameLessonScope(left: Lesson, right: Lesson): boolean { return left.project === right.project; } +export function sameLessonContradictionScope( + left: Lesson, + right: Lesson, +): boolean { + return ( + sameLessonScope(left, right) && + normalizeProjectLabel(left.project) === normalizeProjectLabel(right.project) + ); +} + +export function lessonCanonicalId(lesson: Lesson): string { + const parsed = parseLessonSaveInput( + { ...lesson, lifecycle: deriveLifecycle(lesson) }, + { + allowTerminalLifecycle: true, + allowImplicitWorktreeScope: true, + allowLegacyGitVerificationMigration: true, + }, + ); + if (!parsed.success) { + throw new Error(`Invalid lesson ${lesson.id}: ${parsed.error}`); + } + return lessonIdForInput(parsed.value); +} + function normalizeConfidence(value: unknown): number | undefined { if (value === undefined || value === null) return undefined; if (typeof value !== "number") { @@ -655,6 +822,11 @@ function normalizeScope( "scope.scopeId", MAX_SCOPE_ID_LENGTH, ); + if (ring === "global" && scopeId) { + throw new LessonInputError( + "scope.scopeId must be omitted for global scope", + ); + } if ( ring !== "global" && !scopeId && @@ -676,7 +848,7 @@ function normalizeScope( approval.approvedBy, "scope.humanApproval.approvedBy", ), - approvedAt: requiredDate( + approvedAt: requiredStrictDate( approval.approvedAt, "scope.humanApproval.approvedAt", ), @@ -710,15 +882,19 @@ function normalizeStructuredFacets( `structuredFacets must have at most ${MAX_FACET_DIMENSIONS} dimensions`, ); } - const normalized: Record = {}; + const normalized = new Map(); for (const [rawDimension, rawValues] of entries) { const dimension = rawDimension .trim() .toLowerCase() .replace(/[\s-]+/g, "_"); - if (!dimension || dimension.length > 64) { + if ( + dimension.length > 64 || + !FACET_DIMENSION_PATTERN.test(dimension) || + RESERVED_FACET_DIMENSIONS.has(dimension) + ) { throw new LessonInputError( - "structuredFacets dimensions must be 1-64 characters", + "structuredFacets dimensions must normalize to 1-64 character ASCII snake_case names matching ^[a-z][a-z0-9_]*$ and must not be reserved", ); } const values = normalizeStringArray( @@ -732,23 +908,26 @@ function normalizeStructuredFacets( }, ); const mergedValues = [ - ...new Set([...(normalized[dimension] ?? []), ...values]), + ...new Set([...(normalized.get(dimension) ?? []), ...values]), ].sort(compareText); if (mergedValues.length > MAX_FACET_VALUES) { throw new LessonInputError( `structuredFacets.${dimension} must contain at most ${MAX_FACET_VALUES} values after normalization`, ); } - normalized[dimension] = mergedValues; + normalized.set(dimension, mergedValues); } return Object.fromEntries( - Object.entries(normalized).sort(([left], [right]) => + [...normalized.entries()].sort(([left], [right]) => compareText(left, right), ), ); } -function normalizeEvidenceRefs(value: unknown): LessonEvidenceReference[] { +function normalizeEvidenceRefs( + value: unknown, + allowLegacyGitVerificationMigration: boolean, +): LessonEvidenceReference[] { if (value === undefined || value === null) return []; if (!Array.isArray(value)) { throw new LessonInputError("evidenceRefs must be an array"); @@ -759,7 +938,11 @@ function normalizeEvidenceRefs(value: unknown): LessonEvidenceReference[] { ); } const refs = value.map((rawRef, index) => - normalizeEvidenceRef(rawRef, index), + normalizeEvidenceRef( + rawRef, + index, + allowLegacyGitVerificationMigration, + ), ); const unique = new Map( refs.map((ref) => [stableStringify(ref), ref] as const), @@ -772,6 +955,7 @@ function normalizeEvidenceRefs(value: unknown): LessonEvidenceReference[] { function normalizeEvidenceRef( value: unknown, index: number, + allowLegacyGitVerificationMigration: boolean, ): LessonEvidenceReference { const record = requireRecord(value, `evidenceRefs[${index}]`); const prefix = `evidenceRefs[${index}]`; @@ -784,36 +968,116 @@ function normalizeEvidenceRef( `${prefix}.projectId`, MAX_EVIDENCE_PROJECT_ID_LENGTH, ); - const repoRemoteUrl = normalizeRepoRemote( - requiredString( - record.repoRemoteUrl, - `${prefix}.repoRemoteUrl`, - MAX_EVIDENCE_REMOTE_LENGTH, - ), + const legacyRepoRemote = optionalString( + record.repoRemoteUrl, `${prefix}.repoRemoteUrl`, + MAX_EVIDENCE_REMOTE_LENGTH, ); - const commitSha = normalizeCommitSha( + const legacyCommitSha = normalizeCommitSha( optionalString(record.commitSha, `${prefix}.commitSha`, 64), `${prefix}.commitSha`, ); - const artifactDigest = normalizeArtifactDigest( + const legacyArtifactDigest = normalizeArtifactDigest( optionalString(record.artifactDigest, `${prefix}.artifactDigest`, 256), `${prefix}.artifactDigest`, ); - if (!commitSha && !artifactDigest) { + const legacyPath = normalizeEvidencePath( + optionalString(record.path, `${prefix}.path`, MAX_EVIDENCE_PATH_LENGTH), + `${prefix}.path`, + ); + const provenance = + record.provenance === undefined || record.provenance === null + ? normalizeLegacyGitProvenance( + legacyRepoRemote, + legacyCommitSha, + legacyArtifactDigest, + legacyPath, + prefix, + ) + : normalizeEvidenceProvenance(record.provenance, prefix); + if ( + provenance.type !== "git" && + (legacyRepoRemote || legacyCommitSha || legacyArtifactDigest) + ) { throw new LessonInputError( - `${prefix} requires commitSha and/or artifactDigest; branch, ref, and path are not immutable proof`, + `${prefix} Git-specific fields require provenance.type=git`, ); } - const path = normalizeEvidencePath( - optionalString(record.path, `${prefix}.path`, MAX_EVIDENCE_PATH_LENGTH), - `${prefix}.path`, + const repoRemoteUrl = + provenance.type === "git" + ? normalizeRepoRemote(provenance.locator, `${prefix}.provenance.locator`) + : undefined; + const commitSha = + provenance.type === "git" + ? normalizeCommitSha( + provenance.immutableId, + `${prefix}.provenance.immutableId`, + ) + : undefined; + const artifactDigest = + provenance.type === "git" ? provenance.digest : undefined; + if ( + provenance.type === "git" && + legacyRepoRemote && + normalizeRepoRemote(legacyRepoRemote, `${prefix}.repoRemoteUrl`) !== + repoRemoteUrl + ) { + throw new LessonInputError( + `${prefix}.repoRemoteUrl must match provenance.locator`, + ); + } + if ( + provenance.type === "git" && + legacyCommitSha && + legacyCommitSha !== commitSha + ) { + throw new LessonInputError( + `${prefix}.commitSha must match provenance.immutableId`, + ); + } + if ( + provenance.type === "git" && + legacyArtifactDigest && + legacyArtifactDigest !== artifactDigest + ) { + throw new LessonInputError( + `${prefix}.artifactDigest must match provenance.digest`, + ); + } + const path = provenance.path ?? legacyPath; + if (legacyPath && provenance.path && legacyPath !== provenance.path) { + throw new LessonInputError( + `${prefix}.path must match provenance.path`, + ); + } + const recordedAt = requiredStrictDate( + record.recordedAt, + `${prefix}.recordedAt`, ); - const recordedAt = requiredDate(record.recordedAt, `${prefix}.recordedAt`); - const validatedAt = optionalDate( + const validatedAt = optionalStrictDate( record.validatedAt, `${prefix}.validatedAt`, ); + const legacyGitShape = + (record.provenance === undefined || record.provenance === null) && + Boolean(legacyRepoRemote); + const verification = + allowLegacyGitVerificationMigration && + legacyGitShape && + (record.verification === undefined || record.verification === null) + ? { + state: "verified" as const, + basis: "legacy-git-anchor" as const, + verifiedBy: "agentmemory:legacy-git-anchor-migration", + verifiedAt: validatedAt ?? recordedAt, + note: + "Compatibility migration preserves the pre-verification schema verdict; evidence relevance was not re-audited.", + } + : normalizeEvidenceVerification( + record.verification, + prefix, + allowLegacyGitVerificationMigration, + ); const evidenceKindRaw = optionalString( record.evidenceKind, `${prefix}.evidenceKind`, @@ -838,6 +1102,8 @@ function normalizeEvidenceRef( return { kind, projectId: projectId.trim(), + provenance, + verification, repoRemoteUrl, commitSha, artifactDigest, @@ -849,6 +1115,219 @@ function normalizeEvidenceRef( }; } +function normalizeLegacyGitProvenance( + repoRemoteUrl: string | undefined, + commitSha: string | undefined, + artifactDigest: string | undefined, + path: string | undefined, + prefix: string, +): LessonEvidenceProvenance { + if (!repoRemoteUrl) { + throw new LessonInputError( + `${prefix} requires provenance or a backward-compatible repoRemoteUrl`, + ); + } + const locator = normalizeRepoRemote( + repoRemoteUrl, + `${prefix}.repoRemoteUrl`, + ); + if (!commitSha && !artifactDigest) { + throw new LessonInputError( + `${prefix} requires an immutable commit SHA or digest; branch, ref, and path are not immutable proof`, + ); + } + return { + type: "git", + locator, + immutableId: commitSha, + digest: artifactDigest, + path, + }; +} + +function normalizeEvidenceProvenance( + value: unknown, + prefix: string, +): LessonEvidenceProvenance { + const record = requireRecord(value, `${prefix}.provenance`); + const type = normalizeEnum( + record.type, + `${prefix}.provenance.type`, + PROVENANCE_TYPES, + ); + if (!type) { + throw new LessonInputError(`${prefix}.provenance.type is required`); + } + const locator = normalizeEvidenceLocator( + requiredString( + record.locator, + `${prefix}.provenance.locator`, + MAX_EVIDENCE_LOCATOR_LENGTH, + ), + type, + `${prefix}.provenance.locator`, + ); + const rawImmutableId = optionalString( + record.immutableId, + `${prefix}.provenance.immutableId`, + MAX_EVIDENCE_IMMUTABLE_ID_LENGTH, + ); + const immutableId = + type === "git" + ? normalizeCommitSha( + rawImmutableId, + `${prefix}.provenance.immutableId`, + ) + : normalizeImmutableId( + rawImmutableId, + `${prefix}.provenance.immutableId`, + ); + const digest = normalizeArtifactDigest( + optionalString( + record.digest, + `${prefix}.provenance.digest`, + 256, + ), + `${prefix}.provenance.digest`, + ); + const path = normalizeEvidencePath( + optionalString( + record.path, + `${prefix}.provenance.path`, + MAX_EVIDENCE_PATH_LENGTH, + ), + `${prefix}.provenance.path`, + ); + + if ( + (type === "git" || + type === "object-store" || + type === "database-query" || + type === "dataset") && + !immutableId && + !digest + ) { + throw new LessonInputError( + `${prefix}.provenance requires immutableId and/or digest for type ${type}`, + ); + } + if ((type === "oci" || type === "attestation") && !digest) { + throw new LessonInputError( + `${prefix}.provenance.digest is required for type ${type}`, + ); + } + + return { type, locator, immutableId, digest, path }; +} + +function normalizeEvidenceLocator( + value: string, + type: LessonEvidenceProvenanceType, + field: string, +): string { + const trimmed = value.trim(); + if (/[\s\0-\x1f]/.test(trimmed)) { + throw new LessonInputError( + `${field} must be a non-whitespace immutable locator`, + ); + } + if (type === "git") return normalizeRepoRemote(trimmed, field); + if (type === "doi") { + const normalized = trimmed.replace(/^https?:\/\/doi\.org\//i, ""); + if (!/^10\.\d{4,9}\/\S+$/i.test(normalized)) { + throw new LessonInputError(`${field} must contain a valid DOI`); + } + return normalized.toLowerCase(); + } + if (type === "urn" && !/^urn:[a-z0-9][a-z0-9-]{0,31}:.+$/i.test(trimmed)) { + throw new LessonInputError(`${field} must contain a valid URN`); + } + return trimmed; +} + +function normalizeImmutableId( + value: string | undefined, + field: string, +): string | undefined { + if (!value) return undefined; + const trimmed = value.trim(); + if (/[\s\0-\x1f]/.test(trimmed)) { + throw new LessonInputError( + `${field} must be a non-whitespace immutable identifier`, + ); + } + return trimmed; +} + +function normalizeEvidenceVerification( + value: unknown, + prefix: string, + allowLegacyGitVerificationMigration: boolean, +): LessonEvidenceVerification { + if (value === undefined || value === null) { + return { state: "unverified" }; + } + const record = requireRecord(value, `${prefix}.verification`); + const state = + normalizeEnum( + record.state, + `${prefix}.verification.state`, + VERIFICATION_STATES, + ) ?? "unverified"; + const basisRaw = optionalString( + record.basis, + `${prefix}.verification.basis`, + 64, + ); + if ( + basisRaw !== undefined && + basisRaw !== "explicit-review" && + basisRaw !== "legacy-git-anchor" + ) { + throw new LessonInputError( + `${prefix}.verification.basis must be explicit-review or legacy-git-anchor`, + ); + } + if ( + basisRaw === "legacy-git-anchor" && + !allowLegacyGitVerificationMigration + ) { + throw new LessonInputError( + `${prefix}.verification.basis legacy-git-anchor is reserved for compatibility import`, + ); + } + const basis = + state === "unverified" + ? undefined + : (basisRaw as LessonEvidenceVerification["basis"] | undefined) ?? + "explicit-review"; + const verifiedBy = optionalString( + record.verifiedBy, + `${prefix}.verification.verifiedBy`, + MAX_EVIDENCE_VERIFIER_LENGTH, + ); + const verifiedAt = optionalStrictDate( + record.verifiedAt, + `${prefix}.verification.verifiedAt`, + ); + const note = optionalString( + record.note, + `${prefix}.verification.note`, + MAX_EVIDENCE_VERIFICATION_NOTE_LENGTH, + ); + if (state !== "unverified" && (!verifiedBy || !verifiedAt)) { + throw new LessonInputError( + `${prefix}.verification ${state} state requires verifiedBy and verifiedAt`, + ); + } + if (state === "unverified" && (verifiedBy || verifiedAt)) { + throw new LessonInputError( + `${prefix}.verification unverified state must not include verifiedBy or verifiedAt`, + ); + } + return { state, basis, verifiedBy, verifiedAt, note }; +} + function normalizeRepoRemote(value: string, field: string): string { const trimmed = value.trim(); const urlStyle = /^(https?|ssh|git):\/\/[^\s]+$/i.test(trimmed); @@ -1054,6 +1533,12 @@ function requiredDate(value: unknown, field: string): string { return normalized; } +function requiredStrictDate(value: unknown, field: string): string { + const normalized = optionalStrictDate(value, field); + if (!normalized) throw new LessonInputError(`${field} is required`); + return normalized; +} + function optionalDate(value: unknown, field: string): string | undefined { if (value === undefined || value === null || value === "") return undefined; if (typeof value !== "string") { @@ -1066,6 +1551,112 @@ function optionalDate(value: unknown, field: string): string | undefined { return new Date(parsed).toISOString(); } +function optionalStrictDate( + value: unknown, + field: string, +): string | undefined { + if (value === undefined || value === null || value === "") return undefined; + const match = + typeof value === "string" + ? EXPLICIT_RFC3339_PATTERN.exec(value) + : null; + if (!match) { + throw new LessonInputError( + `${field} must be an RFC3339 timestamp with explicit Z or numeric offset`, + ); + } + const year = Number(match[1]); + const month = Number(match[2]); + const day = Number(match[3]); + const hour = Number(match[4]); + const minute = Number(match[5]); + const second = Number(match[6]); + const offsetHour = match[8] === undefined ? 0 : Number(match[8]); + const offsetMinute = match[9] === undefined ? 0 : Number(match[9]); + const daysInMonth = + month === 2 + ? isLeapYear(year) + ? 29 + : 28 + : month === 4 || month === 6 || month === 9 || month === 11 + ? 30 + : 31; + if ( + month < 1 || + month > 12 || + day < 1 || + day > daysInMonth || + hour > 23 || + minute > 59 || + second > 59 || + offsetHour > 23 || + offsetMinute > 59 + ) { + throw new LessonInputError( + `${field} must contain a calendar-valid RFC3339 timestamp`, + ); + } + const parsed = Date.parse(value); + if (!Number.isFinite(parsed)) { + throw new LessonInputError(`${field} must be a valid RFC3339 timestamp`); + } + return new Date(parsed).toISOString(); +} + +function isLeapYear(year: number): boolean { + return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0); +} + +function hasStructuredLessonMarkers( + value: Lesson | Record, +): boolean { + const record = value as Record; + if (record.identityKind === "legacy-prose") return true; + return [ + "schemaVersion", + "identityKind", + "idAliases", + "mechanismId", + "mechanismVersion", + "mechanismAliases", + "claim", + "claimType", + "evidenceVerdict", + "lifecycle", + "applicabilityConditions", + "nonApplicabilityConditions", + "falsificationConditions", + "structuredFacets", + "evidenceRefs", + "scope", + "sensitivity", + "reviewAfter", + "contradictedByLessonIds", + "contentFingerprint", + ].some((field) => record[field] !== undefined); +} + +function hasCausalStructure(input: LessonSaveInput): boolean { + return ( + Boolean( + input.mechanismId || + input.mechanismVersion || + input.claim || + input.claimType, + ) || + input.mechanismAliases.length > 0 || + input.applicabilityConditions.length > 0 || + input.nonApplicabilityConditions.length > 0 || + input.falsificationConditions.length > 0 || + Object.keys(input.structuredFacets).length > 0 || + input.evidenceRefs.length > 0 + ); +} + +function normalizeProjectLabel(value: string | undefined): string { + return value?.trim() ?? ""; +} + function normalizeDisplayText(value: string): string { return value.trim().replace(/\s+/g, " "); } diff --git a/src/functions/lessons.ts b/src/functions/lessons.ts index 7f13413765..861ce0cc38 100644 --- a/src/functions/lessons.ts +++ b/src/functions/lessons.ts @@ -1,17 +1,19 @@ import type { ISdk } from "iii-sdk"; import type { StateKV } from "../state/kv.js"; import { KV } from "../state/schema.js"; -import { withKeyedLock } from "../state/keyed-mutex.js"; import type { Lesson } from "../types.js"; import { recordAudit } from "./audit.js"; +import { withLessonLocks } from "./lesson-locks.js"; import { LESSON_SCHEMA_VERSION, isLessonListable, isLessonRecallable, + lessonCanonicalId, lessonContentFingerprint, lessonIdForInput, normalizeLesson, parseLessonSaveInput, + sameLessonContradictionScope, sameLessonScope, toLessonReadModel, } from "./lesson-model.js"; @@ -38,26 +40,64 @@ function reinforceLesson(lesson: Lesson): void { lesson.updatedAt = now; } -function lessonLockKey(lessonId: string): string { - return `mem:lesson:${lessonId}`; +function correctionFailure(code: string, error: string) { + return { success: false, code, error }; } -function withLessonLocks( - lessonIds: string[], - fn: () => Promise, -): Promise { - const orderedIds = [...new Set(lessonIds)].sort(); - const lockNext = (index: number): Promise => { - if (index >= orderedIds.length) return fn(); - return withKeyedLock(lessonLockKey(orderedIds[index]), () => - lockNext(index + 1), +async function findLessonByCanonicalIdentity( + kv: StateKV, + canonicalId: string, +): Promise { + const exact = await kv.get(KV.lessons, canonicalId); + if (exact) return exact; + const matches: Lesson[] = []; + for (const lesson of await kv.list(KV.lessons)) { + try { + const normalized = normalizeLesson(lesson); + if ( + normalized.idAliases.includes(canonicalId) || + lessonCanonicalId(normalized) === canonicalId + ) { + matches.push(lesson); + } + } catch {} + } + if (matches.length > 1) { + throw new Error( + `multiple lessons claim canonical identity ${canonicalId}`, ); - }; - return lockNext(0); + } + return matches[0] ?? null; } -function correctionFailure(code: string, error: string) { - return { success: false, code, error }; +async function validateContradictionRelations( + kv: StateKV, + source: Lesson, + targetIds: string[], +): Promise { + for (const targetId of targetIds) { + if ( + targetId === source.id || + normalizeLesson(source).idAliases.includes(targetId) + ) { + return "contradictedByLessonIds must not contain the lesson itself"; + } + const target = await kv.get(KV.lessons, targetId); + if (!target) { + return `contradiction target does not exist: ${targetId}`; + } + try { + if (!isLessonRecallable(target)) { + return `contradiction target must be active: ${targetId}`; + } + if (!sameLessonContradictionScope(source, target)) { + return `contradiction target must share durable scope and project label: ${targetId}`; + } + } catch { + return `contradiction target is invalid: ${targetId}`; + } + } + return null; } async function correctLesson( @@ -220,90 +260,135 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { const input = parsed.value; const fp = lessonIdForInput(input); - return withKeyedLock(lessonLockKey(fp), async () => { - const existing = await kv.get(KV.lessons, fp); + return withLessonLocks( + [fp, ...input.contradictedByLessonIds], + async () => { + let existing: Lesson | null; + try { + existing = await findLessonByCanonicalIdentity(kv, fp); + } catch (error) { + return correctionFailure( + "canonical_identity_conflict", + error instanceof Error ? error.message : String(error), + ); + } - if (existing && !isLessonListable(existing)) { - return correctionFailure( - "lesson_deleted", - "lesson is superseded or retracted; save corrected evidence as a new lesson", - ); - } + if (existing && !isLessonListable(existing)) { + return correctionFailure( + "lesson_deleted", + "lesson is superseded or retracted; save corrected evidence as a new lesson", + ); + } - if (existing) { - reinforceLesson(existing); - if (input.context && !existing.context) { - existing.context = input.context; + if (existing) { + const contradictionError = await validateContradictionRelations( + kv, + existing, + input.contradictedByLessonIds, + ); + if (contradictionError) { + return correctionFailure("invalid_relation", contradictionError); + } + reinforceLesson(existing); + if (input.context && !existing.context) { + existing.context = input.context; + } + existing.sourceIds = [ + ...new Set([...existing.sourceIds, ...input.sourceIds]), + ].sort(); + existing.tags = [...new Set([...existing.tags, ...input.tags])]; + existing.contradictedByLessonIds = [ + ...new Set([ + ...(existing.contradictedByLessonIds ?? []), + ...input.contradictedByLessonIds, + ]), + ].sort(); + await kv.set(KV.lessons, existing.id, existing); + + try { + await recordAudit( + kv, + "lesson_strengthen", + "mem::lesson-save", + [existing.id], + { confidenceChanged: false }, + ); + } catch {} + + return { + success: true, + action: "strengthened", + lesson: toLessonReadModel(existing), + }; + } + + const now = new Date().toISOString(); + const lesson: Lesson = { + id: fp, + identityKind: "canonical", + idAliases: [], + content: input.content, + context: input.context, + confidence: input.confidence ?? 0.5, + reinforcements: 0, + source: input.source, + sourceIds: input.sourceIds, + project: input.project, + tags: input.tags, + createdAt: now, + updatedAt: now, + decayRate: 0.05, + schemaVersion: LESSON_SCHEMA_VERSION, + mechanismId: input.mechanismId, + mechanismVersion: input.mechanismVersion, + mechanismAliases: input.mechanismAliases, + claim: input.claim, + claimType: input.claimType, + evidenceVerdict: input.evidenceVerdict, + lifecycle: input.lifecycle, + applicabilityConditions: input.applicabilityConditions, + nonApplicabilityConditions: input.nonApplicabilityConditions, + falsificationConditions: input.falsificationConditions, + structuredFacets: input.structuredFacets, + evidenceRefs: input.evidenceRefs, + scope: input.scope, + sensitivity: input.sensitivity, + reviewAfter: input.reviewAfter, + contradictedByLessonIds: input.contradictedByLessonIds, + contentFingerprint: lessonContentFingerprint(input), + }; + + const contradictionError = await validateContradictionRelations( + kv, + lesson, + input.contradictedByLessonIds, + ); + if (contradictionError) { + return correctionFailure("invalid_relation", contradictionError); } - await kv.set(KV.lessons, existing.id, existing); + await kv.set(KV.lessons, lesson.id, lesson); try { await recordAudit( kv, - "lesson_strengthen", + "lesson_save", "mem::lesson-save", - [existing.id], - { confidenceChanged: false }, + [lesson.id], + { + contentFingerprint: lesson.contentFingerprint, + evidenceVerdict: lesson.evidenceVerdict, + lifecycle: lesson.lifecycle, + }, ); } catch {} return { success: true, - action: "strengthened", - lesson: toLessonReadModel(existing), + action: "created", + lesson: toLessonReadModel(lesson), }; - } - - const now = new Date().toISOString(); - const lesson: Lesson = { - id: fp, - content: input.content, - context: input.context, - confidence: input.confidence ?? 0.5, - reinforcements: 0, - source: input.source, - sourceIds: input.sourceIds, - project: input.project, - tags: input.tags, - createdAt: now, - updatedAt: now, - decayRate: 0.05, - schemaVersion: LESSON_SCHEMA_VERSION, - mechanismId: input.mechanismId, - mechanismVersion: input.mechanismVersion, - mechanismAliases: input.mechanismAliases, - claim: input.claim, - claimType: input.claimType, - evidenceVerdict: input.evidenceVerdict, - lifecycle: input.lifecycle, - applicabilityConditions: input.applicabilityConditions, - nonApplicabilityConditions: input.nonApplicabilityConditions, - falsificationConditions: input.falsificationConditions, - structuredFacets: input.structuredFacets, - evidenceRefs: input.evidenceRefs, - scope: input.scope, - sensitivity: input.sensitivity, - reviewAfter: input.reviewAfter, - contradictedByLessonIds: input.contradictedByLessonIds, - contentFingerprint: lessonContentFingerprint(input), - }; - - await kv.set(KV.lessons, lesson.id, lesson); - - try { - await recordAudit(kv, "lesson_save", "mem::lesson-save", [lesson.id], { - contentFingerprint: lesson.contentFingerprint, - evidenceVerdict: lesson.evidenceVerdict, - lifecycle: lesson.lifecycle, - }); - } catch {} - - return { - success: true, - action: "created", - lesson: toLessonReadModel(lesson), - }; - }); + }, + ); }, ); @@ -464,7 +549,7 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { return { success: false, error: "lessonId is required" }; } - return withKeyedLock(lessonLockKey(data.lessonId), async () => { + return withLessonLocks([data.lessonId], async () => { const lesson = await kv.get(KV.lessons, data.lessonId); if (!lesson || !isLessonListable(lesson)) { return { success: false, error: "lesson not found" }; @@ -506,7 +591,7 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { const timestamp = new Date().toISOString(); const outcomes = await Promise.all( lessons.map((listedLesson) => - withKeyedLock(lessonLockKey(listedLesson.id), async () => { + withLessonLocks([listedLesson.id], async () => { const lesson = await kv.get(KV.lessons, listedLesson.id); if (!lesson || lesson.deleted) return null; diff --git a/src/functions/reflect.ts b/src/functions/reflect.ts index 849fcbbd8c..ba7bbec50e 100644 --- a/src/functions/reflect.ts +++ b/src/functions/reflect.ts @@ -9,15 +9,26 @@ import type { Lesson, Crystal, MemoryProvider, + LessonEvidenceVerdict, + LessonReadModel, } from "../types.js"; import { recordAudit } from "./audit.js"; import { REFLECT_SYSTEM, buildReflectPrompt } from "../prompts/reflect.js"; -import { isLessonRecallable } from "./lesson-model.js"; +import { + isLessonRecallable, + toLessonReadModel, +} from "./lesson-model.js"; interface ConceptCluster { concepts: string[]; facts: Array<{ fact: string; confidence: number }>; - lessons: Array<{ content: string; confidence: number }>; + lessons: Array<{ + content: string; + claim?: string; + confidence: number; + evidenceVerdict: LessonEvidenceVerdict; + contradicted: boolean; + }>; crystalNarratives: string[]; factIds: string[]; lessonIds: string[]; @@ -27,10 +38,6 @@ interface ConceptCluster { function reinforceInsight(insight: Insight): void { const now = new Date().toISOString(); insight.reinforcements++; - insight.confidence = Math.min( - 1.0, - insight.confidence + 0.1 * (1 - insight.confidence), - ); insight.lastReinforcedAt = now; insight.updatedAt = now; } @@ -161,6 +168,29 @@ function buildJaccardClusters( return clusters; } +function parseInsightAttributes( + value: string, +): Record { + const attributes: Record = {}; + const attributePattern = /([A-Za-z][A-Za-z0-9]*)="([^"]*)"/g; + let match: RegExpExecArray | null; + while ((match = attributePattern.exec(value)) !== null) { + attributes[match[1]] = match[2]; + } + return attributes; +} + +function normalizeInsightEvidenceVerdict( + value: string | undefined, +): LessonEvidenceVerdict | undefined { + return value === "supported" || + value === "refuted" || + value === "mixed" || + value === "unverified" + ? value + : undefined; +} + export function registerReflectFunctions( sdk: ISdk, kv: StateKV, @@ -181,7 +211,14 @@ export function registerReflectFunctions( kv.list(KV.crystals).catch(() => []), ]); - let activeLessons = lessons.filter(isLessonRecallable); + let activeLessons: LessonReadModel[] = []; + for (const lesson of lessons) { + try { + if (isLessonRecallable(lesson)) { + activeLessons.push(toLessonReadModel(lesson)); + } + } catch {} + } if (data?.project) { activeLessons = activeLessons.filter((l) => l.project === data.project); } @@ -219,7 +256,9 @@ export function registerReflectFunctions( const clusterLessons = activeLessons.filter((l) => l.tags.some((t) => conceptSet.has(t.toLowerCase())) || conceptNames.some((c) => - l.content.toLowerCase().includes(c.toLowerCase()), + `${l.claim ?? ""} ${l.content}` + .toLowerCase() + .includes(c.toLowerCase()), ), ); @@ -246,7 +285,10 @@ export function registerReflectFunctions( })), lessons: clusterLessons.map((l) => ({ content: l.content, + claim: l.claim, confidence: l.confidence, + evidenceVerdict: l.evidenceVerdict, + contradicted: l.computedFlags.contradicted, })), crystalNarratives: clusterCrystals.map((c) => c.narrative), factIds: clusterFacts.map((f) => f.id), @@ -259,21 +301,39 @@ export function registerReflectFunctions( const response = await provider.summarize(REFLECT_SYSTEM, prompt); const insightRegex = - /([\s\S]*?)<\/insight>/g; + /]+)>([\s\S]*?)<\/insight>/g; let match; let clusterCount = 0; + const hasNegativeLessonEvidence = cluster.lessons.some( + (lesson) => + lesson.evidenceVerdict === "refuted" || + lesson.contradicted, + ); while ( (match = insightRegex.exec(response)) !== null && clusterCount < maxInsightsPerCluster && totalInsights < maxTotal ) { - const parsedConf = parseFloat(match[1]); + const attributes = parseInsightAttributes(match[1]); + if (!attributes.title || !attributes.confidence) continue; + const outputVerdict = normalizeInsightEvidenceVerdict( + attributes.evidenceVerdict, + ); + if ( + hasNegativeLessonEvidence && + outputVerdict !== "refuted" && + outputVerdict !== "mixed" + ) { + continue; + } + const evidenceVerdict = outputVerdict ?? "supported"; + const parsedConf = parseFloat(attributes.confidence); const confidence = Number.isNaN(parsedConf) ? 0.5 : Math.max(0, Math.min(1, parsedConf)); - const title = match[2].trim(); - const content = match[3].trim(); + const title = attributes.title.trim(); + const content = match[2].trim(); if (!content) continue; @@ -282,6 +342,10 @@ export function registerReflectFunctions( if (existing && !existing.deleted) { reinforceInsight(existing); + existing.evidenceVerdict = + (existing.evidenceVerdict ?? "supported") === evidenceVerdict + ? evidenceVerdict + : "mixed"; await kv.set(KV.insights, existing.id, existing); reinforced++; } else { @@ -296,6 +360,7 @@ export function registerReflectFunctions( sourceMemoryIds: cluster.factIds, sourceLessonIds: cluster.lessonIds, sourceCrystalIds: cluster.crystalIds, + evidenceVerdict, project: data?.project, tags: conceptNames, createdAt: now, diff --git a/src/functions/replay.ts b/src/functions/replay.ts index 7e1ebd915c..5ba66ab11a 100644 --- a/src/functions/replay.ts +++ b/src/functions/replay.ts @@ -17,7 +17,13 @@ import { safeAudit } from "./audit.js"; import { buildSyntheticCompression } from "./compress-synthetic.js"; import { getSearchIndex } from "./search.js"; import { logger } from "../logger.js"; -import { normalizeLesson } from "./lesson-model.js"; +import { + lessonCanonicalId, + lessonIdForInput, + normalizeLesson, + parseLessonSaveInput, +} from "./lesson-model.js"; +import { withLessonLocks } from "./lesson-locks.js"; export const MAX_FILES_DEFAULT = 200; export const MAX_FILES_UPPER_BOUND = 1000; @@ -114,34 +120,59 @@ async function deriveCrystalAndLessons( const lessonEntries = Array.from(lessonMatches.values()).slice(0, 20); const lessonIds: string[] = []; for (const content of lessonEntries) { - // Content-addressed ID so re-importing the same JSONL does not - // duplicate lessons. fingerprintId hashes the normalized content, - // giving a stable lesson_xxx for identical text. - const lessonId = fingerprintId("lesson", content.trim().toLowerCase()); try { - const existing = await kv.get(KV.lessons, lessonId); - if (existing) { - const normalizedExisting = normalizeLesson(existing); - const existingSources = normalizedExisting.sourceIds; - const mergedSources = existingSources.includes(sessionId) - ? existingSources - : [...existingSources, sessionId]; - const existingTags = normalizedExisting.tags; - const mergedTags = existingTags.includes("auto-import") - ? existingTags - : [...existingTags, "auto-import"]; - const merged: Lesson = { - ...normalizedExisting, - sourceIds: mergedSources, - tags: mergedTags, - reinforcements: normalizedExisting.reinforcements + 1, - updatedAt: createdAt, - lastReinforcedAt: createdAt, - }; - await kv.set(KV.lessons, lessonId, merged); - } else { + const parsed = parseLessonSaveInput({ + content, + context: firstPrompt || project, + confidence: 0.4, + source: "consolidation", + sourceIds: [sessionId], + project, + tags: ["auto-import"], + }); + if (!parsed.success) continue; + const lessonId = lessonIdForInput(parsed.value); + await withLessonLocks([lessonId], async () => { + const exact = await kv.get(KV.lessons, lessonId); + const existing = + exact ?? + (await kv.list(KV.lessons)).find((lesson) => { + try { + const normalized = normalizeLesson(lesson); + return ( + normalized.idAliases.includes(lessonId) || + lessonCanonicalId(normalized) === lessonId + ); + } catch { + return false; + } + }); + if (existing) { + const normalizedExisting = normalizeLesson(existing); + const existingSources = normalizedExisting.sourceIds; + const mergedSources = existingSources.includes(sessionId) + ? existingSources + : [...existingSources, sessionId]; + const existingTags = normalizedExisting.tags; + const mergedTags = existingTags.includes("auto-import") + ? existingTags + : [...existingTags, "auto-import"]; + const merged: Lesson = { + ...normalizedExisting, + sourceIds: mergedSources, + tags: mergedTags, + reinforcements: normalizedExisting.reinforcements + 1, + updatedAt: createdAt, + lastReinforcedAt: createdAt, + }; + await kv.set(KV.lessons, existing.id, merged); + lessonIds.push(existing.id); + return; + } const lesson = normalizeLesson({ id: lessonId, + identityKind: "canonical", + idAliases: [], content, context: firstPrompt || project, confidence: 0.4, @@ -155,8 +186,8 @@ async function deriveCrystalAndLessons( decayRate: 0.05, }); await kv.set(KV.lessons, lessonId, lesson); - } - lessonIds.push(lessonId); + lessonIds.push(lessonId); + }); } catch {} } diff --git a/src/functions/smart-search.ts b/src/functions/smart-search.ts index 5d0147d9e0..8be5e22a6c 100644 --- a/src/functions/smart-search.ts +++ b/src/functions/smart-search.ts @@ -299,18 +299,41 @@ async function recallLessons( payload: { query, limit, project }, })) as { success?: boolean; lessons?: Array }; if (!result?.success || !Array.isArray(result.lessons)) return []; - return result.lessons.map((l) => ({ - lessonId: l.id, - content: - l.content.length > LESSON_CONTENT_PREVIEW_CHARS - ? l.content.slice(0, LESSON_CONTENT_PREVIEW_CHARS) + "…" - : l.content, - confidence: l.confidence, - score: l.score ?? l.confidence, - createdAt: l.createdAt, - project: l.project, - tags: l.tags ?? [], - })); + return result.lessons.map((lesson) => { + const evidenceVerdict = lesson.evidenceVerdict ?? "unverified"; + const contradicted = + Boolean( + (lesson as Lesson & { + computedFlags?: { contradicted?: boolean }; + }).computedFlags?.contradicted, + ) || + (lesson.contradictedByLessonIds?.length ?? 0) > 0; + const evidenceLabel: CompactLessonResult["evidenceLabel"] = contradicted + ? "contradicted evidence" + : evidenceVerdict === "refuted" + ? "refuted evidence (negative)" + : evidenceVerdict === "supported" + ? "supported evidence" + : evidenceVerdict === "mixed" + ? "mixed evidence" + : "unverified evidence"; + return { + lessonId: lesson.id, + content: + lesson.content.length > LESSON_CONTENT_PREVIEW_CHARS + ? lesson.content.slice(0, LESSON_CONTENT_PREVIEW_CHARS) + "…" + : lesson.content, + claim: lesson.claim, + evidenceVerdict, + evidenceLabel, + contradicted, + confidence: lesson.confidence, + score: lesson.score ?? lesson.confidence, + createdAt: lesson.createdAt, + project: lesson.project, + tags: lesson.tags ?? [], + }; + }); } catch (err) { logger.warn("Smart search: mem::lesson-recall failed; returning empty lesson list", { error: err instanceof Error ? err.message : String(err), diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts index 0ec4b58f8c..72733b46d2 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -978,7 +978,7 @@ export const V070_TOOLS: McpToolDef[] = [ structuredFacets: { type: "object", description: - "General facet dimensions mapped to string values, such as asset, venue, horizon, regime, or signal_family", + "General facet dimensions mapped to string values. Dimensions normalize to ASCII snake_case matching ^[a-z][a-z0-9_]*$", additionalProperties: { type: "array", items: { type: "string" }, @@ -988,13 +988,49 @@ export const V070_TOOLS: McpToolDef[] = [ evidenceRefs: { type: "array", description: - "At most eight immutable evidence anchors; branch, ref, or path alone is insufficient", + "At most eight immutable provenance anchors with explicit verification state; branch, ref, path, or syntactic provenance alone is insufficient", maxItems: 8, items: { type: "object", properties: { kind: { type: "string" }, projectId: { type: "string" }, + provenance: { + type: "object", + properties: { + type: { + type: "string", + enum: [ + "git", + "object-store", + "database-query", + "oci", + "doi", + "urn", + "dataset", + "attestation", + ], + }, + locator: { type: "string" }, + immutableId: { type: "string" }, + digest: { type: "string" }, + path: { type: "string" }, + }, + required: ["type", "locator"], + }, + verification: { + type: "object", + properties: { + state: { + type: "string", + enum: ["unverified", "verified", "rejected"], + }, + verifiedBy: { type: "string" }, + verifiedAt: { type: "string" }, + note: { type: "string" }, + }, + required: ["state"], + }, repoRemoteUrl: { type: "string" }, commitSha: { type: "string" }, artifactDigest: { type: "string" }, @@ -1004,12 +1040,7 @@ export const V070_TOOLS: McpToolDef[] = [ evidenceKind: { type: "string" }, sampleCount: { type: "number", minimum: 0 }, }, - required: [ - "kind", - "projectId", - "repoRemoteUrl", - "recordedAt", - ], + required: ["kind", "projectId", "recordedAt"], }, }, scope: { diff --git a/src/prompts/reflect.ts b/src/prompts/reflect.ts index 6de84351cf..6ed4cde7f8 100644 --- a/src/prompts/reflect.ts +++ b/src/prompts/reflect.ts @@ -2,7 +2,7 @@ export const REFLECT_SYSTEM = `You are a higher-order reasoning engine. Given a Output format (XML): - + The higher-order observation or principle. Should be actionable and non-obvious — something that only becomes visible when viewing multiple memories together. @@ -14,12 +14,21 @@ Rules: - Content should be the actual observation (1-3 sentences) - Prefer actionable insights over abstract summaries - Skip insights that merely restate a single source item -- Always emit confidence attribute before title attribute`; +- Treat refuted lessons as negative evidence, never as positive guidance +- Treat contradicted lessons as contested evidence, never as settled guidance +- When negative or contradicted evidence contributes, emit only refuted or mixed evidenceVerdict +- Always emit evidenceVerdict before confidence and title attributes`; export function buildReflectPrompt(cluster: { concepts: string[]; facts: Array<{ fact: string; confidence: number }>; - lessons: Array<{ content: string; confidence: number }>; + lessons: Array<{ + content: string; + claim?: string; + confidence: number; + evidenceVerdict: "supported" | "refuted" | "mixed" | "unverified"; + contradicted: boolean; + }>; crystalNarratives: string[]; }): string { const sections: string[] = []; @@ -36,12 +45,32 @@ export function buildReflectPrompt(cluster: { } if (cluster.lessons.length > 0) { - sections.push( - "\n## Lessons Learned", - ...cluster.lessons.map( - (l) => `- [confidence=${l.confidence}] ${l.content}`, - ), + const positiveLessons = cluster.lessons.filter( + (lesson) => + lesson.evidenceVerdict !== "refuted" && !lesson.contradicted, + ); + const negativeLessons = cluster.lessons.filter( + (lesson) => + lesson.evidenceVerdict === "refuted" || lesson.contradicted, ); + if (positiveLessons.length > 0) { + sections.push( + "\n## Lessons Learned", + ...positiveLessons.map( + (lesson) => + `- [verdict=${lesson.evidenceVerdict}; confidence=${lesson.confidence}] claim=${lesson.claim ?? "(prose-only)"} | ${lesson.content}`, + ), + ); + } + if (negativeLessons.length > 0) { + sections.push( + "\n## Negative or Contradicted Evidence", + ...negativeLessons.map( + (lesson) => + `- [verdict=${lesson.evidenceVerdict}; contradicted=${lesson.contradicted}; confidence=${lesson.confidence}] claim=${lesson.claim ?? "(prose-only)"} | ${lesson.content}`, + ), + ); + } } if (cluster.crystalNarratives.length > 0) { diff --git a/src/types.ts b/src/types.ts index 01989edcba..3da04cd285 100644 --- a/src/types.ts +++ b/src/types.ts @@ -292,6 +292,15 @@ export interface CompactSearchResult { export interface CompactLessonResult { lessonId: string; content: string; + claim?: string; + evidenceVerdict: LessonEvidenceVerdict; + evidenceLabel: + | "supported evidence" + | "refuted evidence (negative)" + | "mixed evidence" + | "unverified evidence" + | "contradicted evidence"; + contradicted: boolean; confidence: number; score: number; createdAt: string; @@ -972,10 +981,43 @@ export interface LessonScope { humanApproval?: LessonHumanApproval; } +export type LessonEvidenceProvenanceType = + | "git" + | "object-store" + | "database-query" + | "oci" + | "doi" + | "urn" + | "dataset" + | "attestation"; + +export interface LessonEvidenceProvenance { + type: LessonEvidenceProvenanceType; + locator: string; + immutableId?: string; + digest?: string; + path?: string; +} + +export type LessonEvidenceVerificationState = + | "unverified" + | "verified" + | "rejected"; + +export interface LessonEvidenceVerification { + state: LessonEvidenceVerificationState; + basis?: "explicit-review" | "legacy-git-anchor"; + verifiedBy?: string; + verifiedAt?: string; + note?: string; +} + export interface LessonEvidenceReference { kind: string; projectId: string; - repoRemoteUrl: string; + provenance?: LessonEvidenceProvenance; + verification?: LessonEvidenceVerification; + repoRemoteUrl?: string; commitSha?: string; artifactDigest?: string; path?: string; @@ -992,6 +1034,8 @@ export interface LessonComputedFlags { export interface Lesson { id: string; + identityKind?: "canonical" | "legacy-prose"; + idAliases?: string[]; content: string; context: string; confidence: number; @@ -1032,6 +1076,8 @@ export interface Lesson { export interface NormalizedLesson extends Lesson { schemaVersion: 1; + identityKind: "canonical" | "legacy-prose"; + idAliases: string[]; mechanismAliases: string[]; evidenceVerdict: LessonEvidenceVerdict; lifecycle: LessonLifecycle; @@ -1060,6 +1106,7 @@ export interface Insight { sourceMemoryIds: string[]; sourceLessonIds: string[]; sourceCrystalIds: string[]; + evidenceVerdict?: LessonEvidenceVerdict; project?: string; tags: string[]; createdAt: string; diff --git a/test/causal-lessons-api.test.ts b/test/causal-lessons-api.test.ts index 199181b562..f90079ce83 100644 --- a/test/causal-lessons-api.test.ts +++ b/test/causal-lessons-api.test.ts @@ -21,6 +21,11 @@ function evidence(commit = "a".repeat(40)) { recordedAt: "2026-08-02T20:00:00.000Z", evidenceKind: "unit-test", sampleCount: 12, + verification: { + state: "verified", + verifiedBy: "reviewer@example.test", + verifiedAt: "2026-08-02T20:30:00.000Z", + }, }; } @@ -205,4 +210,88 @@ describe("causal lesson REST and MCP boundaries", () => { expect(response.body.lessons).toHaveLength(1); expect(response.body.lessons[0].lifecycle).toBe("active"); }); + + it("rejects dangling, self, cross-scope, and cross-project contradiction relations", async () => { + const target = (await sdk.trigger("mem::lesson-save", { + content: "Contradiction target", + project: "project-one", + mechanismId: "relations/target", + claim: "The target claim is active.", + scope: { ring: "repo", scopeId: "repo:one" }, + })) as { lesson: Lesson }; + const sourceInput = { + content: "Contradiction source", + project: "project-one", + mechanismId: "relations/source", + claim: "The source claim is active.", + scope: { ring: "repo", scopeId: "repo:one" }, + }; + const source = (await sdk.trigger( + "mem::lesson-save", + sourceInput, + )) as { lesson: Lesson }; + + const dangling = await sdk.trigger("mem::lesson-save", { + ...sourceInput, + contradictedByLessonIds: ["lsn_missing"], + }); + const self = await sdk.trigger("mem::lesson-save", { + ...sourceInput, + contradictedByLessonIds: [source.lesson.id], + }); + const otherScope = (await sdk.trigger("mem::lesson-save", { + content: "Other scope target", + project: "project-one", + mechanismId: "relations/other-scope", + claim: "The other-scope target is active.", + scope: { ring: "repo", scopeId: "repo:two" }, + })) as { lesson: Lesson }; + const crossScope = await sdk.trigger("mem::lesson-save", { + ...sourceInput, + contradictedByLessonIds: [otherScope.lesson.id], + }); + const otherProject = (await sdk.trigger("mem::lesson-save", { + content: "Other project target", + project: "project-two", + mechanismId: "relations/other-project", + claim: "The other-project target is active.", + scope: { ring: "repo", scopeId: "repo:one" }, + })) as { lesson: Lesson }; + const crossProject = await sdk.trigger("mem::lesson-save", { + ...sourceInput, + contradictedByLessonIds: [otherProject.lesson.id], + }); + const valid = await sdk.trigger("mem::lesson-save", { + ...sourceInput, + contradictedByLessonIds: [target.lesson.id], + }); + + expect(dangling).toMatchObject({ + success: false, + code: "invalid_relation", + error: expect.stringContaining("does not exist"), + }); + expect(self).toMatchObject({ + success: false, + code: "invalid_relation", + error: expect.stringContaining("must not contain the lesson itself"), + }); + expect(crossScope).toMatchObject({ + success: false, + code: "invalid_relation", + error: expect.stringContaining("durable scope and project"), + }); + expect(crossProject).toMatchObject({ + success: false, + code: "invalid_relation", + error: expect.stringContaining("durable scope and project"), + }); + expect(valid).toMatchObject({ + success: true, + action: "strengthened", + lesson: { + contradictedByLessonIds: [target.lesson.id], + }, + }); + }); }); diff --git a/test/diagnostics.test.ts b/test/diagnostics.test.ts index 1e168767ac..48b28e52b1 100644 --- a/test/diagnostics.test.ts +++ b/test/diagnostics.test.ts @@ -678,6 +678,41 @@ describe("Diagnostics Functions", () => { expect(warn?.status).toBe("warn"); }); + it("lessons category: diagnoses malformed structured rows without legacy fallback", async () => { + await kv.set(KV.lessons, "lsn_malformed_structured", { + id: "lsn_malformed_structured", + schemaVersion: 1, + content: "malformed structured row", + context: "", + confidence: 0.7, + reinforcements: 0, + source: "manual", + sourceIds: [], + tags: [], + createdAt: "2026-08-02T00:00:00Z", + updatedAt: "2026-08-02T00:00:00Z", + decayRate: 0.05, + evidenceRefs: "invalid", + }); + + const result = (await sdk.trigger("mem::diagnose", { + categories: ["lessons"], + })) as { checks: DiagnosticCheck[] }; + + expect(result.checks).toContainEqual( + expect.objectContaining({ + name: "lesson-invalid-structured:lsn_malformed_structured", + status: "fail", + message: expect.stringContaining( + "evidenceRefs must be an array", + ), + }), + ); + expect(result.checks).not.toContainEqual( + expect.objectContaining({ name: "lessons-ok" }), + ); + }); + it("summaries category: warns on missing title", async () => { await kv.set(KV.summaries, "ses_1", { sessionId: "ses_1", project: "p", createdAt: "", title: "", diff --git a/test/export-import.test.ts b/test/export-import.test.ts index 0cb965d61f..f5f6be0851 100644 --- a/test/export-import.test.ts +++ b/test/export-import.test.ts @@ -5,6 +5,7 @@ vi.mock("../src/logger.js", () => ({ })); import { registerExportImportFunction } from "../src/functions/export-import.js"; +import { registerLessonsFunctions } from "../src/functions/lessons.js"; import type { Session, CompressedObservation, @@ -15,27 +16,90 @@ import type { ActionEdge, ActionCollectionState, ActionEvent, + AuditEntry, Lesson, } from "../src/types.js"; +import { parseImportedLesson } from "../src/functions/lesson-model.js"; function mockKV() { const store = new Map>(); + const injectedFailures: Array<{ + operation: "set" | "delete"; + scope: string; + key: string; + }> = []; + let setBarrier: + | { + scope: string; + key: string; + reached: () => void; + waitForRelease: Promise; + } + | undefined; return { get: async (scope: string, key: string): Promise => { return (store.get(scope)?.get(key) as T) ?? null; }, set: async (scope: string, key: string, data: T): Promise => { + if (setBarrier?.scope === scope && setBarrier.key === key) { + const barrier = setBarrier; + setBarrier = undefined; + barrier.reached(); + await barrier.waitForRelease; + } + const setFailureIndex = injectedFailures.findIndex( + (failure) => + failure.operation === "set" && + failure.scope === scope && + failure.key === key, + ); + if (setFailureIndex >= 0) { + injectedFailures.splice(setFailureIndex, 1); + throw new Error(`injected set failure for ${scope}/${key}`); + } if (!store.has(scope)) store.set(scope, new Map()); store.get(scope)!.set(key, data); return data; }, delete: async (scope: string, key: string): Promise => { + const deleteFailureIndex = injectedFailures.findIndex( + (failure) => + failure.operation === "delete" && + failure.scope === scope && + failure.key === key, + ); + if (deleteFailureIndex >= 0) { + injectedFailures.splice(deleteFailureIndex, 1); + throw new Error(`injected delete failure for ${scope}/${key}`); + } store.get(scope)?.delete(key); }, list: async (scope: string): Promise => { const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; }, + failNext( + operation: "set" | "delete", + scope: string, + key: string, + ): void { + injectedFailures.push({ operation, scope, key }); + }, + pauseNextSet(scope: string, key: string): { + reached: Promise; + release: () => void; + } { + let reached!: () => void; + let release!: () => void; + const reachedPromise = new Promise((resolve) => { + reached = resolve; + }); + const waitForRelease = new Promise((resolve) => { + release = resolve; + }); + setBarrier = { scope, key, reached, waitForRelease }; + return { reached: reachedPromise, release }; + }, }; } @@ -106,6 +170,70 @@ const testSummary: SessionSummary = { observationCount: 1, }; +function emptyExport(lessons: Lesson[] = []): ExportData { + return { + version: "0.9.27", + exportedAt: "2026-08-02T20:00:00.000Z", + sessions: [], + observations: {}, + memories: [], + summaries: [], + lessons, + }; +} + +function structuredLesson( + id: string, + overrides: Partial = {}, +): Lesson { + return { + id, + content: `Structured lesson ${id}`, + context: "", + confidence: 0.7, + reinforcements: 0, + source: "manual", + sourceIds: [], + project: "agentmemory", + tags: ["causal"], + createdAt: "2026-08-02T20:00:00.000Z", + updatedAt: "2026-08-02T20:00:00.000Z", + decayRate: 0.05, + schemaVersion: 1, + mechanismId: `import/${id.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}`, + claim: `The claim for ${id} is falsifiable.`, + claimType: "causal", + evidenceVerdict: "supported", + lifecycle: "active", + evidenceRefs: [ + { + kind: "experiment", + projectId: "agentmemory", + provenance: { + type: "oci", + locator: `ghcr.io/example/${id.toLowerCase()}`, + digest: `sha256:${"a".repeat(64)}`, + }, + recordedAt: "2026-08-02T20:00:00.000Z", + verification: { + state: "verified", + verifiedBy: "reviewer@example.test", + verifiedAt: "2026-08-02T20:30:00.000Z", + }, + }, + ], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + sensitivity: "restricted", + ...overrides, + }; +} + +function importedLesson(raw: Lesson): Lesson { + const parsed = parseImportedLesson(raw); + if (!parsed.success) throw new Error(parsed.error); + return parsed.lesson; +} + describe("Export/Import Functions", () => { let sdk: ReturnType; let kv: ReturnType; @@ -317,6 +445,7 @@ describe("Export/Import Functions", () => { summaries: [], lessons: [legacy, structured], }; + const structuredCanonical = importedLesson(structured); const result = (await sdk.trigger("mem::import", { exportData, @@ -328,7 +457,7 @@ describe("Export/Import Functions", () => { ); const storedStructured = await kv.get( "mem:lessons", - structured.id, + structuredCanonical.id, ); expect(result).toMatchObject({ success: true, lessons: 2 }); @@ -344,7 +473,16 @@ describe("Export/Import Functions", () => { evidenceVerdict: "supported", lifecycle: "active", sensitivity: "confidential", - evidenceRefs: [expect.objectContaining({ commitSha: "d".repeat(40) })], + idAliases: [structured.id], + evidenceRefs: [ + expect.objectContaining({ + commitSha: "d".repeat(40), + verification: expect.objectContaining({ + state: "verified", + basis: "legacy-git-anchor", + }), + }), + ], }); }); @@ -394,6 +532,440 @@ describe("Export/Import Functions", () => { expect(await kv.get("mem:sessions", "ses_1")).toEqual(testSession); }); + it("rejects unknown runtime import strategies before any mutation", async () => { + const before = await kv.list("mem:sessions"); + const result = (await sdk.trigger("mem::import", { + exportData: emptyExport([structuredLesson("unknown-strategy")]), + strategy: "overwrite", + } as never)) as { success: boolean; error: string }; + + expect(result).toMatchObject({ + success: false, + error: "strategy must be merge, replace, or skip", + }); + expect(await kv.list("mem:sessions")).toEqual(before); + expect(await kv.list("mem:lessons")).toEqual([]); + }); + + it.each(["retracted", "superseded"] as const)( + "blocks merge resurrection of a %s lesson without partially writing the batch", + async (lifecycle) => { + const replacement = importedLesson( + structuredLesson(`replacement-${lifecycle}`), + ); + const activeOriginal = structuredLesson(`terminal-${lifecycle}`); + const terminal = importedLesson({ + ...activeOriginal, + lifecycle, + deleted: true, + deletedAt: "2026-08-02T21:00:00.000Z", + deletedBy: "reviewer", + deleteReason: "terminal evidence state", + supersededByLessonId: + lifecycle === "superseded" ? replacement.id : undefined, + }); + await kv.set("mem:lessons", replacement.id, replacement); + await kv.set("mem:lessons", terminal.id, terminal); + const unrelated = structuredLesson(`unrelated-${lifecycle}`); + const unrelatedCanonical = importedLesson(unrelated); + + const result = (await sdk.trigger("mem::import", { + exportData: emptyExport([activeOriginal, unrelated]), + strategy: "merge", + })) as { success: boolean; error: string }; + + expect(result).toMatchObject({ + success: false, + error: expect.stringContaining( + `cannot replace terminal ${lifecycle}`, + ), + }); + expect(await kv.get("mem:lessons", terminal.id)).toEqual( + terminal, + ); + expect( + await kv.get("mem:lessons", unrelatedCanonical.id), + ).toBeNull(); + expect(await kv.list("mem:lessons")).toHaveLength(2); + }, + ); + + it("serializes correction against merge preflight so a concurrent tombstone cannot be resurrected", async () => { + registerLessonsFunctions(sdk as never, kv as never); + const raw = structuredLesson("concurrent-correction", { + evidenceVerdict: "unverified", + evidenceRefs: [], + }); + const active = importedLesson(raw); + await kv.set("mem:lessons", active.id, active); + const barrier = kv.pauseNextSet("mem:lessons", active.id); + + const correctionPromise = sdk.trigger("mem::lesson-delete", { + lessonId: active.id, + reason: "Concurrent evidence invalidation", + actor: "reviewer", + }); + await barrier.reached; + const importPromise = sdk.trigger("mem::import", { + exportData: emptyExport([raw]), + strategy: "merge", + }); + barrier.release(); + + const correction = await correctionPromise; + const imported = await importPromise; + const finalLesson = await kv.get("mem:lessons", active.id); + + expect(correction).toMatchObject({ + success: true, + action: "deleted", + }); + expect(imported).toMatchObject({ + success: false, + error: expect.stringContaining("cannot replace terminal retracted"), + }); + expect(finalLesson).toMatchObject({ + lifecycle: "retracted", + deleted: true, + deleteReason: "Concurrent evidence invalidation", + }); + }); + + it("allows explicit replace restoration and audits canonical IDs with lifecycle preimages", async () => { + const active = structuredLesson("explicit-restore"); + const terminal = importedLesson({ + ...active, + lifecycle: "retracted", + deleted: true, + deletedAt: "2026-08-02T21:00:00.000Z", + deletedBy: "reviewer", + deleteReason: "bad artifact", + }); + await kv.set("mem:lessons", terminal.id, terminal); + + const result = (await sdk.trigger("mem::import", { + exportData: emptyExport([active]), + strategy: "replace", + })) as { success: boolean; lessons: number }; + const restored = await kv.list("mem:lessons"); + const audits = await kv.list("mem:audit"); + + expect(result).toMatchObject({ success: true, lessons: 1 }); + expect(restored).toEqual([ + expect.objectContaining({ + id: terminal.id, + lifecycle: "active", + deleted: undefined, + }), + ]); + expect(audits).toContainEqual( + expect.objectContaining({ + functionId: "mem::import:lessons", + targetIds: [terminal.id], + details: expect.objectContaining({ + strategy: "replace", + lifecycleTransitions: [ + { + lessonId: terminal.id, + before: "retracted", + after: "active", + }, + ], + }), + }), + ); + }); + + it("restores the exact lesson preimage when a merge set fails mid-batch", async () => { + const preserved = importedLesson(structuredLesson("preserved-set")); + const first = importedLesson(structuredLesson("first-set")); + const second = importedLesson(structuredLesson("second-set")); + await kv.set("mem:lessons", preserved.id, preserved); + kv.failNext("set", "mem:lessons", second.id); + + const result = (await sdk.trigger("mem::import", { + exportData: emptyExport([ + structuredLesson("first-set"), + structuredLesson("second-set"), + ]), + strategy: "merge", + })) as { success: boolean; error: string }; + + expect(result).toMatchObject({ + success: false, + error: expect.stringContaining("exact preimage restored"), + }); + expect(await kv.list("mem:lessons")).toEqual([preserved]); + expect(await kv.get("mem:lessons", first.id)).toBeNull(); + expect(await kv.get("mem:lessons", second.id)).toBeNull(); + }); + + it("reports and audits rollback failure with the affected lesson IDs", async () => { + const first = importedLesson(structuredLesson("rollback-failure-first")); + const second = importedLesson( + structuredLesson("rollback-failure-second"), + ); + kv.failNext("set", "mem:lessons", second.id); + kv.failNext("delete", "mem:lessons", first.id); + + const result = (await sdk.trigger("mem::import", { + exportData: emptyExport([ + structuredLesson("rollback-failure-first"), + structuredLesson("rollback-failure-second"), + ]), + strategy: "merge", + })) as { success: boolean; error: string }; + const audits = await kv.list("mem:audit"); + + expect(result).toMatchObject({ + success: false, + error: expect.stringContaining("rollback failed"), + }); + expect(result.error).toContain(first.id); + expect(audits).toContainEqual( + expect.objectContaining({ + functionId: "mem::import:lessons-rollback", + targetIds: [first.id, second.id], + details: expect.objectContaining({ + rollback: expect.objectContaining({ success: false }), + }), + }), + ); + }); + + it("restores the exact lesson preimage when a replace delete fails mid-batch", async () => { + const first = importedLesson(structuredLesson("first-delete")); + const second = importedLesson(structuredLesson("second-delete")); + await kv.set("mem:lessons", first.id, first); + await kv.set("mem:lessons", second.id, second); + kv.failNext("delete", "mem:lessons", second.id); + + const result = (await sdk.trigger("mem::import", { + exportData: emptyExport(), + strategy: "replace", + })) as { success: boolean; error: string }; + + expect(result).toMatchObject({ + success: false, + error: expect.stringContaining("exact preimage restored"), + }); + const restored = await kv.list("mem:lessons"); + expect(restored).toHaveLength(2); + expect(restored).toEqual(expect.arrayContaining([first, second])); + }); + + it("canonicalizes arbitrary structured IDs and rejects canonical duplicates", async () => { + const first = { + ...structuredLesson("arbitrary-one"), + computedFlags: { stale: true, contradicted: true }, + } as Lesson; + const duplicate = { ...first, id: "arbitrary-two" }; + const canonical = importedLesson(first); + + const duplicateResult = (await sdk.trigger("mem::import", { + exportData: emptyExport([first, duplicate]), + strategy: "merge", + })) as { success: boolean; error: string }; + expect(duplicateResult).toMatchObject({ + success: false, + error: expect.stringContaining("Duplicate lesson"), + }); + expect(await kv.list("mem:lessons")).toEqual([]); + + const success = await sdk.trigger("mem::import", { + exportData: emptyExport([first]), + strategy: "merge", + }); + expect(success).toMatchObject({ success: true, lessons: 1 }); + expect(await kv.list("mem:lessons")).toEqual([ + expect.objectContaining({ + id: canonical.id, + identityKind: "canonical", + idAliases: ["arbitrary-one"], + }), + ]); + expect((await kv.list("mem:lessons"))[0]).not.toHaveProperty( + "computedFlags", + ); + }); + + it("resolves order-independent imported lineage through canonical aliases", async () => { + const target = structuredLesson("lineage-target"); + const targetCanonical = importedLesson(target); + const source = { + ...structuredLesson("lineage-source", { + evidenceVerdict: "unverified", + evidenceRefs: [], + }), + lifecycle: "superseded" as const, + deleted: true, + deletedAt: "2026-08-02T21:00:00.000Z", + deletedBy: "reviewer", + deleteReason: "new evidence", + supersededByLessonId: target.id, + }; + const sourceCanonical = importedLesson(source); + + const result = await sdk.trigger("mem::import", { + exportData: emptyExport([source, target]), + strategy: "merge", + }); + + expect(result).toMatchObject({ success: true, lessons: 2 }); + expect( + await kv.get("mem:lessons", sourceCanonical.id), + ).toMatchObject({ + supersededByLessonId: targetCanonical.id, + }); + + const reverseKv = mockKV(); + const reverseSdk = mockSdk(); + registerExportImportFunction(reverseSdk as never, reverseKv as never); + const reverse = await reverseSdk.trigger("mem::import", { + exportData: emptyExport([target, source]), + strategy: "merge", + }); + expect(reverse).toMatchObject({ success: true, lessons: 2 }); + expect( + await reverseKv.get("mem:lessons", sourceCanonical.id), + ).toMatchObject({ + supersededByLessonId: targetCanonical.id, + }); + }); + + it.each([ + { + name: "dangling contradiction", + lessons: () => [ + structuredLesson("dangling-contradiction", { + contradictedByLessonIds: ["missing-target"], + }), + ], + message: "dangling contradiction", + }, + { + name: "self contradiction", + lessons: () => { + const lesson = structuredLesson("self-contradiction"); + return [{ ...lesson, contradictedByLessonIds: [lesson.id] }]; + }, + message: "cannot contradict itself", + }, + { + name: "cross-scope contradiction", + lessons: () => { + const target = structuredLesson("cross-scope-target", { + scope: { ring: "repo", scopeId: "repo:two" }, + }); + return [ + structuredLesson("cross-scope-source", { + scope: { ring: "repo", scopeId: "repo:one" }, + contradictedByLessonIds: [target.id], + }), + target, + ]; + }, + message: "crosses durable scope or project", + }, + { + name: "cross-project contradiction", + lessons: () => { + const target = structuredLesson("cross-project-target", { + project: "project-two", + }); + return [ + structuredLesson("cross-project-source", { + project: "project-one", + contradictedByLessonIds: [target.id], + }), + target, + ]; + }, + message: "crosses durable scope or project", + }, + { + name: "cross-scope supersession", + lessons: () => { + const target = structuredLesson("cross-supersession-target", { + scope: { ring: "repo", scopeId: "repo:two" }, + }); + return [ + { + ...structuredLesson("cross-supersession-source", { + evidenceVerdict: "unverified", + evidenceRefs: [], + scope: { ring: "repo", scopeId: "repo:one" }, + }), + lifecycle: "superseded" as const, + deleted: true, + deletedAt: "2026-08-02T21:00:00.000Z", + deletedBy: "reviewer", + deleteReason: "replaced", + supersededByLessonId: target.id, + }, + target, + ]; + }, + message: "crosses durable scope", + }, + { + name: "terminal contradiction target", + lessons: () => { + const target = structuredLesson("terminal-relation-target", { + lifecycle: "retracted", + deleted: true, + deletedAt: "2026-08-02T21:00:00.000Z", + deletedBy: "reviewer", + deleteReason: "invalid", + }); + return [ + structuredLesson("terminal-relation-source", { + contradictedByLessonIds: [target.id], + }), + target, + ]; + }, + message: "must be active", + }, + ])("rejects $name in the complete post-import graph", async ({ lessons, message }) => { + const result = (await sdk.trigger("mem::import", { + exportData: emptyExport(lessons()), + strategy: "merge", + })) as { success: boolean; error: string }; + + expect(result).toMatchObject({ + success: false, + error: expect.stringContaining(message), + }); + expect(await kv.list("mem:lessons")).toEqual([]); + }); + + it("rejects malformed structured export/import without rewriting it as legacy", async () => { + const malformed = { + ...structuredLesson("malformed-roundtrip"), + evidenceRefs: "not-an-array", + } as unknown as Lesson; + await kv.set("mem:lessons", malformed.id, malformed); + + await expect(sdk.trigger("mem::export", {})).rejects.toThrow( + /Invalid structured lesson.*evidenceRefs must be an array/, + ); + expect(await kv.get("mem:lessons", malformed.id)).toEqual(malformed); + + const fresh = mockKV(); + const freshSdk = mockSdk(); + registerExportImportFunction(freshSdk as never, fresh as never); + const imported = await freshSdk.trigger("mem::import", { + exportData: emptyExport([malformed]), + strategy: "merge", + }); + expect(imported).toMatchObject({ + success: false, + error: expect.stringContaining("evidenceRefs must be an array"), + }); + expect(await fresh.list("mem:lessons")).toEqual([]); + }); + it("import rejects unsupported version", async () => { const exportData = { version: "1.0.0", diff --git a/test/lesson-corrections.test.ts b/test/lesson-corrections.test.ts index 788190c6d1..9831cb2615 100644 --- a/test/lesson-corrections.test.ts +++ b/test/lesson-corrections.test.ts @@ -260,6 +260,11 @@ describe("lesson corrections", () => { repoRemoteUrl: "https://github.com/rohitg00/agentmemory", commitSha: "c".repeat(40), recordedAt: "2026-08-02T20:00:00.000Z", + verification: { + state: "verified", + verifiedBy: "reviewer@example.test", + verifiedAt: "2026-08-02T20:30:00.000Z", + }, }, ], scope: { ring: "repo", scopeId: "repo:agentmemory" }, diff --git a/test/lesson-model.test.ts b/test/lesson-model.test.ts index 237caef246..9f517ef965 100644 --- a/test/lesson-model.test.ts +++ b/test/lesson-model.test.ts @@ -1,4 +1,5 @@ import { describe, expect, it } from "vitest"; +import { execFileSync } from "node:child_process"; import { lessonContentFingerprint, lessonIdForInput, @@ -25,6 +26,11 @@ function evidence( validatedAt: "2026-08-02T21:00:00.000Z", evidenceKind: "unit-test", sampleCount: 42, + verification: { + state: "verified", + verifiedBy: "reviewer@example.test", + verifiedAt: "2026-08-02T21:00:00.000Z", + }, ...overrides, }; } @@ -209,6 +215,140 @@ describe("causal lesson model", () => { }); }); + it("supports discriminated non-Git provenance without treating syntax as verification", () => { + const provenances = [ + { + type: "object-store", + locator: "s3://research-bucket/evidence.json", + digest: `sha256:${"1".repeat(64)}`, + }, + { + type: "database-query", + locator: "clickhouse://analytics/query-17", + immutableId: "snapshot-20260802-001", + digest: `sha256:${"2".repeat(64)}`, + }, + { + type: "oci", + locator: "ghcr.io/example/evidence", + digest: `sha256:${"3".repeat(64)}`, + }, + { type: "doi", locator: "https://doi.org/10.1000/Test.Dataset" }, + { type: "urn", locator: "urn:example:evidence:2026:08:02" }, + { + type: "dataset", + locator: "dataset://market-replay/v2", + immutableId: "release-42", + }, + { + type: "attestation", + locator: "rekor://entry/1234", + digest: `sha256:${"4".repeat(64)}`, + }, + ]; + for (const [index, provenance] of provenances.entries()) { + const parsed = parseLessonSaveInput({ + content: `Evidence provenance ${index}`, + mechanismId: `provenance/${index}`, + claim: `Provenance type ${provenance.type} is durably anchored.`, + evidenceVerdict: "supported", + evidenceRefs: [ + { + kind: "experiment", + projectId: "agentmemory", + provenance, + recordedAt: "2026-08-02T20:00:00Z", + verification: { + state: "verified", + verifiedBy: "reviewer@example.test", + verifiedAt: "2026-08-02T20:30:00Z", + }, + }, + ], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + }); + expect(parsed, provenance.type).toMatchObject({ + success: true, + value: { + evidenceRefs: [ + { + provenance: { + type: provenance.type, + }, + verification: { + state: "verified", + basis: "explicit-review", + }, + }, + ], + }, + }); + } + + const unreviewed = parseLessonSaveInput({ + content: "A digest is not an audited relevance judgment", + mechanismId: "provenance/unreviewed", + claim: "Syntactic provenance alone supports the claim.", + evidenceVerdict: "supported", + evidenceRefs: [ + { + kind: "experiment", + projectId: "agentmemory", + provenance: { + type: "oci", + locator: "ghcr.io/example/evidence", + digest: `sha256:${"5".repeat(64)}`, + }, + recordedAt: "2026-08-02T20:00:00Z", + }, + ], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + }); + expect(unreviewed).toMatchObject({ + success: false, + error: expect.stringContaining("explicitly verified"), + }); + }); + + it("migrates legacy Git-shaped verdict evidence with an explicit compatibility basis", () => { + const imported = parseImportedLesson({ + ...legacyLesson(), + id: "caller-chosen-id", + schemaVersion: 1, + mechanismId: "legacy/git-evidence", + claim: "The pre-verification schema accepted this durable Git anchor.", + evidenceVerdict: "refuted", + evidenceRefs: [ + { + kind: "falsification", + projectId: "agentmemory", + repoRemoteUrl: "https://github.com/rohitg00/agentmemory", + commitSha: "f".repeat(40), + recordedAt: "2026-08-02T20:00:00Z", + }, + ], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + }); + + expect(imported).toMatchObject({ + success: true, + canonicalized: true, + lesson: { + id: expect.stringMatching(/^lsn_[a-f0-9]{16}$/), + idAliases: ["caller-chosen-id"], + evidenceRefs: [ + { + verification: { + state: "verified", + basis: "legacy-git-anchor", + verifiedBy: "agentmemory:legacy-git-anchor-migration", + }, + }, + ], + }, + }); + }); + it("requires durable scope identity and human approval for global promotion", () => { const missingCausalScope = parseLessonSaveInput({ content: "Unscoped causal claim", @@ -234,6 +374,18 @@ describe("causal lesson model", () => { }, }, }); + const globalScopeId = parseLessonSaveInput({ + content: "Invalid global scope ID", + scope: { + ring: "global", + scopeId: "global:any", + humanApproval: { + approvedBy: "patrick", + approvedAt: "2026-08-02T22:00:00Z", + reason: "This should still fail structurally", + }, + }, + }); expect(missingCausalScope).toMatchObject({ success: false, @@ -259,6 +411,166 @@ describe("causal lesson model", () => { }, }, }); + expect(globalScopeId).toMatchObject({ + success: false, + error: expect.stringContaining("must be omitted"), + }); + }); + + it("requires explicit RFC3339 offsets and hashes offset-equivalent times identically across timezones", () => { + const timezoneLess = parseLessonSaveInput({ + content: "Timezone-less evidence", + mechanismId: "time/strict", + claim: "Timezone-less inputs are deterministic.", + evidenceRefs: [ + evidence({ + recordedAt: "2026-08-02T20:00:00", + }), + ], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + }); + expect(timezoneLess).toMatchObject({ + success: false, + error: expect.stringContaining("explicit Z or numeric offset"), + }); + for (const impossible of [ + "2026-02-30T00:00:00Z", + "2026-13-01T00:00:00Z", + "2025-02-29T00:00:00Z", + "2026-04-31T20:00:00-04:00", + ]) { + const parsed = parseLessonSaveInput({ + content: `Impossible timestamp ${impossible}`, + reviewAfter: impossible, + }); + expect(parsed, impossible).toMatchObject({ + success: false, + error: expect.stringContaining("calendar-valid"), + }); + } + expect( + parseLessonSaveInput({ + content: "Valid leap day", + reviewAfter: "2024-02-29T00:00:00Z", + }), + ).toMatchObject({ + success: true, + value: { reviewAfter: "2024-02-29T00:00:00.000Z" }, + }); + + const utc = parsedLesson({ + evidenceRefs: [ + evidence({ + recordedAt: "2026-08-02T20:00:00Z", + validatedAt: "2026-08-02T21:00:00Z", + verification: { + state: "verified", + verifiedBy: "reviewer@example.test", + verifiedAt: "2026-08-02T21:00:00Z", + }, + }), + ], + reviewAfter: "2026-09-01T00:00:00Z", + }); + const offset = parsedLesson({ + evidenceRefs: [ + evidence({ + recordedAt: "2026-08-02T16:00:00-04:00", + validatedAt: "2026-08-02T17:00:00-04:00", + verification: { + state: "verified", + verifiedBy: "reviewer@example.test", + verifiedAt: "2026-08-02T17:00:00-04:00", + }, + }), + ], + reviewAfter: "2026-08-31T20:00:00-04:00", + }); + expect(lessonIdForInput(utc)).toBe(lessonIdForInput(offset)); + + const script = ` + import { parseLessonSaveInput, lessonIdForInput } from "./src/functions/lesson-model.ts"; + const parsed = parseLessonSaveInput({ + content: "Timezone child process", + mechanismId: "time/child", + claim: "Explicit offsets make identity timezone-independent.", + evidenceVerdict: "supported", + evidenceRefs: [{ + kind: "experiment", + projectId: "agentmemory", + provenance: { type: "oci", locator: "ghcr.io/example/evidence", digest: "sha256:${"6".repeat(64)}" }, + recordedAt: "2026-08-02T16:00:00-04:00", + verification: { state: "verified", verifiedBy: "reviewer", verifiedAt: "2026-08-02T17:00:00-04:00" } + }], + scope: { ring: "repo", scopeId: "repo:agentmemory" } + }); + if (!parsed.success) throw new Error(parsed.error); + process.stdout.write(lessonIdForInput(parsed.value)); + `; + const run = (timezone: string) => + execFileSync( + process.execPath, + ["--import", "tsx", "--input-type=module", "-e", script], + { + cwd: process.cwd(), + env: { ...process.env, TZ: timezone }, + encoding: "utf8", + }, + ); + expect(run("UTC")).toBe(run("America/New_York")); + }); + + it("enforces normalized ASCII snake_case facet dimensions", () => { + for (const dimension of [ + "a/b", + "a.b", + "éxchange", + "__proto__", + "constructor", + "9asset", + ]) { + const parsed = parseLessonSaveInput({ + content: `Invalid facet ${dimension}`, + structuredFacets: { [dimension]: ["value"] }, + }); + expect(parsed, dimension).toMatchObject({ + success: false, + error: expect.stringContaining("ASCII snake_case"), + }); + } + expect( + parseLessonSaveInput({ + content: "Valid normalized facet", + mechanismId: "facet/valid", + claim: "Normalized facet dimensions remain domain-neutral.", + structuredFacets: { "Signal Family": ["order-flow"] }, + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + }), + ).toMatchObject({ + success: true, + value: { structuredFacets: { signal_family: ["order-flow"] } }, + }); + }); + + it("fails closed for malformed structured rows while retaining raw legacy fallback", () => { + expect(() => + normalizeLesson( + legacyLesson({ + schemaVersion: 1, + evidenceRefs: "not-an-array" as never, + }), + ), + ).toThrow(/Invalid structured lesson.*evidenceRefs must be an array/); + expect( + normalizeLesson( + legacyLesson({ + confidence: Number.NaN, + }), + ), + ).toMatchObject({ + identityKind: "legacy-prose", + evidenceVerdict: "unverified", + }); }); it("requires claim and mechanism together and evidence for verified verdicts", () => { diff --git a/test/reflect.test.ts b/test/reflect.test.ts index 7ea163d593..965c49eab9 100644 --- a/test/reflect.test.ts +++ b/test/reflect.test.ts @@ -84,7 +84,11 @@ function makeSemantic(fact: string, id?: string): SemanticMemory { }; } -function makeLesson(content: string, tags: string[]): Lesson { +function makeLesson( + content: string, + tags: string[], + overrides: Partial = {}, +): Lesson { return { id: `lsn_${content.slice(0, 8)}`, content, @@ -97,6 +101,7 @@ function makeLesson(content: string, tags: string[]): Lesson { createdAt: "2026-04-01T00:00:00Z", updatedAt: "2026-04-01T00:00:00Z", decayRate: 0.05, + ...overrides, }; } @@ -251,6 +256,156 @@ describe("Reflect", () => { expect(result.success).toBe(true); expect(result.newInsights).toBe(0); }); + + it("labels refuted claims in the prompt and refuses positive synthesis persistence", async () => { + provider.summarize.mockResolvedValue( + ` + +Force-pushing main is safe and should be standard practice. + +`, + ); + await kv.set( + "mem:graph:nodes", + "node_security", + makeConceptNode("security"), + ); + await kv.set( + "mem:graph:nodes", + "node_validation", + makeConceptNode("validation"), + ); + await kv.set( + "mem:graph:edges", + "edge_1", + makeEdge("security", "validation"), + ); + await kv.set( + "mem:semantic", + "sem_1", + makeSemantic("security facts require validation", "sem_1"), + ); + await kv.set( + "mem:semantic", + "sem_2", + makeSemantic("validation protects security boundaries", "sem_2"), + ); + await kv.set( + "mem:lessons", + "lsn_refuted", + makeLesson("Force-pushing main caused data loss.", ["security"], { + id: "lsn_refuted", + schemaVersion: 1, + mechanismId: "git/force-push", + claim: "Force-pushing main is safe.", + evidenceVerdict: "refuted", + lifecycle: "active", + evidenceRefs: [ + { + kind: "incident", + projectId: "agentmemory", + provenance: { + type: "attestation", + locator: "rekor://entry/refuted-force-push", + digest: `sha256:${"a".repeat(64)}`, + }, + recordedAt: "2026-04-01T00:00:00Z", + verification: { + state: "verified", + verifiedBy: "reviewer@example.test", + verifiedAt: "2026-04-01T01:00:00Z", + }, + }, + ], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + }), + ); + + const result = (await sdk.trigger("mem::reflect", {})) as { + newInsights: number; + }; + const prompt = provider.summarize.mock.calls[0][1] as string; + + expect(prompt).toContain("Negative or Contradicted Evidence"); + expect(prompt).toContain("verdict=refuted"); + expect(prompt).toContain("claim=Force-pushing main is safe."); + expect(result.newInsights).toBe(0); + expect(await kv.list("mem:insights")).toEqual([]); + }); + + it("persists an explicitly mixed synthesis when refuted evidence contributes", async () => { + provider.summarize.mockResolvedValue( + ` + +The practice has mixed evidence and the refuted claim must remain visible as counterevidence. + +`, + ); + await kv.set("mem:graph:nodes", "node_retry", makeConceptNode("retry")); + await kv.set( + "mem:graph:nodes", + "node_idempotency", + makeConceptNode("idempotency"), + ); + await kv.set( + "mem:graph:edges", + "edge_1", + makeEdge("retry", "idempotency"), + ); + await kv.set( + "mem:semantic", + "sem_1", + makeSemantic("retry requires idempotency", "sem_1"), + ); + await kv.set( + "mem:semantic", + "sem_2", + makeSemantic("idempotency bounds retry risk", "sem_2"), + ); + await kv.set( + "mem:lessons", + "lsn_retry_refuted", + makeLesson("Unbounded retries failed.", ["retry"], { + id: "lsn_retry_refuted", + schemaVersion: 1, + mechanismId: "retry/unbounded", + claim: "Unbounded retries are safe.", + evidenceVerdict: "refuted", + lifecycle: "active", + evidenceRefs: [ + { + kind: "incident", + projectId: "agentmemory", + provenance: { + type: "attestation", + locator: "rekor://entry/unbounded-retry", + digest: `sha256:${"b".repeat(64)}`, + }, + recordedAt: "2026-04-01T00:00:00Z", + verification: { + state: "verified", + verifiedBy: "reviewer@example.test", + verifiedAt: "2026-04-01T01:00:00Z", + }, + }, + ], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + }), + ); + + const result = (await sdk.trigger("mem::reflect", {})) as { + newInsights: number; + }; + const insights = await kv.list("mem:insights"); + + expect(result.newInsights).toBe(1); + expect(insights).toEqual([ + expect.objectContaining({ + evidenceVerdict: "mixed", + sourceLessonIds: ["lsn_retry_refuted"], + }), + ]); + }); }); describe("mem::insight-list", () => { diff --git a/test/replay-import-key.test.ts b/test/replay-import-key.test.ts index 9a4c64675c..1391f0ffea 100644 --- a/test/replay-import-key.test.ts +++ b/test/replay-import-key.test.ts @@ -8,7 +8,9 @@ vi.mock("../src/logger.js", () => ({ })); import { registerReplayFunctions } from "../src/functions/replay.js"; +import { registerLessonsFunctions } from "../src/functions/lessons.js"; import { KV } from "../src/state/schema.js"; +import type { Lesson } from "../src/types.js"; function mockKV() { const store = new Map>(); @@ -64,7 +66,11 @@ describe("import-jsonl re-key on parsed.sessionId (#775)", () => { tmpRoot = mkdtempSync(join(tmpdir(), "replay-import-key-")); }); - function writeFixture(sessionId: string, ts = "2026-04-17T10:00:00.000Z") { + function writeFixture( + sessionId: string, + ts = "2026-04-17T10:00:00.000Z", + assistantText = "world", + ) { const dir = join(tmpRoot, "proj"); rmSync(dir, { recursive: true, force: true }); require("node:fs").mkdirSync(dir, { recursive: true }); @@ -87,7 +93,7 @@ describe("import-jsonl re-key on parsed.sessionId (#775)", () => { timestamp: ts, message: { role: "assistant", - content: [{ type: "text", text: "world" }], + content: [{ type: "text", text: assistantText }], }, }), ]; @@ -151,4 +157,86 @@ describe("import-jsonl re-key on parsed.sessionId (#775)", () => { .filter((c) => c.scope === KV.sessions && c.key === "sess-fresh"); expect(sessionWrites.length).toBe(1); }); + + it("uses the same canonical lesson identity as save and deduplicates replay lessons", async () => { + const content = "Always validate imported sessions before replay."; + writeFixture( + "sess-canonical-lesson", + "2026-04-17T10:00:00.000Z", + content, + ); + const kv = mockKV(); + const sdk = mockSdk(kv); + registerLessonsFunctions(sdk, kv as never); + registerReplayFunctions(sdk, kv as never); + const saved = (await sdk.trigger("mem::lesson-save", { + content, + project: "proj", + })) as { lesson: Lesson }; + + const result = await sdk.trigger("mem::replay::import-jsonl", { + path: tmpRoot, + }); + const lessons = await kv.list(KV.lessons); + + expect(result).toMatchObject({ success: true, imported: 1 }); + expect(lessons).toHaveLength(1); + expect(lessons[0]).toMatchObject({ + id: saved.lesson.id, + sourceIds: ["sess-canonical-lesson"], + tags: ["auto-import"], + reinforcements: 1, + }); + }); + + it("finds a legacy replay lesson by canonical identity without creating a duplicate", async () => { + const content = "Never trust a replay path without validation."; + writeFixture( + "sess-legacy-lesson", + "2026-04-17T10:00:00.000Z", + content, + ); + const kv = mockKV(); + const sdk = mockSdk(kv); + registerLessonsFunctions(sdk, kv as never); + registerReplayFunctions(sdk, kv as never); + const legacy: Lesson = { + id: "lesson_legacy_replay_id", + content, + context: "legacy replay", + confidence: 0.4, + reinforcements: 0, + source: "consolidation", + sourceIds: ["old-session"], + project: "proj", + tags: ["auto-import"], + createdAt: "2026-03-01T00:00:00.000Z", + updatedAt: "2026-03-01T00:00:00.000Z", + decayRate: 0.05, + }; + await kv.set(KV.lessons, legacy.id, legacy); + + await sdk.trigger("mem::replay::import-jsonl", { path: tmpRoot }); + const save = (await sdk.trigger("mem::lesson-save", { + content, + project: "proj", + })) as { success: boolean; action: string; lesson: Lesson }; + const lessons = await kv.list(KV.lessons); + + expect(save).toMatchObject({ + success: true, + action: "strengthened", + lesson: { id: legacy.id }, + }); + expect(lessons).toHaveLength(1); + expect(lessons[0]).toMatchObject({ + id: legacy.id, + identityKind: "legacy-prose", + sourceIds: ["old-session", "sess-legacy-lesson"], + reinforcements: 2, + }); + expect(lessons[0].idAliases).toEqual([ + expect.stringMatching(/^lsn_[a-f0-9]{16}$/), + ]); + }); }); diff --git a/test/smart-search.test.ts b/test/smart-search.test.ts index 9d0c94e0c0..1f344736d1 100644 --- a/test/smart-search.test.ts +++ b/test/smart-search.test.ts @@ -235,6 +235,56 @@ describe("Smart Search Function", () => { expect(result.lessons[0].content).toMatch(/…$/); }); + it("carries claim and explicitly labels refuted or contradicted evidence", async () => { + sdk.registerFunction("mem::lesson-recall", async () => ({ + success: true, + lessons: [ + { + id: "lsn_refuted", + content: "Long prose must not become positive guidance.", + claim: "Force-pushing main is safe.", + evidenceVerdict: "refuted", + confidence: 0.9, + createdAt: "2026-04-01T00:00:00Z", + tags: ["git"], + score: 0.8, + }, + { + id: "lsn_contradicted", + content: "This claim has an active counterexample.", + claim: "All retries are idempotent.", + evidenceVerdict: "supported", + contradictedByLessonIds: ["lsn_counterexample"], + confidence: 0.7, + createdAt: "2026-04-01T00:00:00Z", + tags: ["retries"], + score: 0.7, + }, + ], + })); + + const result = (await sdk.trigger("mem::smart-search", { + query: "safe retries", + })) as { lessons: any[] }; + + expect(result.lessons).toEqual([ + expect.objectContaining({ + lessonId: "lsn_refuted", + claim: "Force-pushing main is safe.", + evidenceVerdict: "refuted", + evidenceLabel: "refuted evidence (negative)", + contradicted: false, + }), + expect.objectContaining({ + lessonId: "lsn_contradicted", + claim: "All retries are idempotent.", + evidenceVerdict: "supported", + evidenceLabel: "contradicted evidence", + contradicted: true, + }), + ]); + }); + it("includeLessons:false omits the lessons array entirely", async () => { // No lesson-recall handler registered — would throw if invoked. const result = (await sdk.trigger("mem::smart-search", { From 6af92b3c2397726b72f5bda19a748ea070b2a628 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Sun, 2 Aug 2026 22:54:42 -0400 Subject: [PATCH 34/43] fix: fail closed on unavailable lesson evidence --- README.md | 13 +- .../2026-08-02-causal-lesson-schema-v1.md | 22 ++- .../skills/agentmemory-mcp-tools/REFERENCE.md | 2 +- src/functions/export-import.ts | 27 +++- src/functions/lesson-model.ts | 30 +++- src/functions/obsidian-export.ts | 47 +++++- src/functions/reflect.ts | 42 ++++- src/mcp/tools-registry.ts | 15 +- src/viewer/index.html | 46 +++++- test/export-import.test.ts | 88 ++++++++++- test/lesson-model.test.ts | 147 ++++++++++++++++++ test/obsidian-export.test.ts | 55 +++++++ test/reflect.test.ts | 84 +++++++++- test/replay-import-key.test.ts | 37 +++++ test/viewer-lessons-schema.test.ts | 26 ++++ 15 files changed, 646 insertions(+), 35 deletions(-) create mode 100644 test/viewer-lessons-schema.test.ts diff --git a/README.md b/README.md index 7972b69fcc..946a655314 100644 --- a/README.md +++ b/README.md @@ -1560,7 +1560,9 @@ New supported/refuted/mixed saves require every evidence reference to carry an explicit verified review. Import/read normalization preserves older Git-shaped verdict rows through a visible `legacy-git-anchor` verification basis; this is a compatibility classification and explicitly does not claim that evidence -relevance was re-audited. +relevance was re-audited. That reserved basis is accepted only for immutable +Git provenance with the canonical AgentMemory migration actor; OCI and every +other non-Git provenance type are rejected if they claim it. Legacy lessons normalize on read to `unverified` + `active` with an implicit worktree scope and @@ -1570,6 +1572,15 @@ Supersession/retraction continue through the audited correction APIs. Compact smart-search results retain claim/verdict/contradiction labels. Reflection treats refuted claims as negative evidence and will not persist a supported synthesis from a cluster containing refuted or contradicted lessons. +Authoritative lesson enumeration and normalization fail closed for import, +portable export, and reflection; a read failure cannot become an empty lesson +set that permits tombstone restoration or positive synthesis. + +`scopeId`, global `humanApproval.approvedBy`, and correction `actor` values are +caller-supplied classification, lineage, and audit-attribution metadata. They +are not authenticated identities or an authorization boundary in PR1. +Server-resolved caller identity, approval authority, and durable-scope access +enforcement remain PR2 work. Scope and sensitivity enforcement, automatic contradiction discovery, and hybrid/vector lesson retrieval are intentionally deferred to PR2. Until then, diff --git a/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md b/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md index 7c9d624f2f..30ccd53c54 100644 --- a/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md +++ b/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md @@ -152,7 +152,10 @@ metadata are not rejected or downgraded. Import/read normalization assigns: This explicit compatibility basis preserves the prior verdict. It does not assert that relevance was newly audited. New REST/MCP saves cannot select the -reserved migration basis. +reserved migration basis. Import/read normalization accepts it only for +immutable Git provenance with +`verifiedBy: "agentmemory:legacy-git-anchor-migration"`; arbitrary migration +actors and all non-Git provenance types are rejected. A branch, ref, or path without the immutable identity required by its provenance type is rejected. @@ -173,6 +176,12 @@ requires a separate durable `scope.scopeId`; global scope rejects `scopeId`. Legacy prose lessons retain the fail-closed implicit worktree scope for compatibility. +`scopeId`, `humanApproval.approvedBy`, and correction `actor` are +caller-supplied metadata in PR1. They express classification, lineage, and +audit attribution, but they are not authenticated identities and do not grant +authorization. Server-resolved caller identity, approval authority, and +durable-scope access enforcement are deferred to PR2. + Global scope requires: ```json @@ -255,6 +264,17 @@ complete post-import supersession/contradiction graph, bounds the collection, strips computed read-model fields, and completes lesson preflight under the shared lesson mutation lock. +Authoritative lesson enumeration and structured normalization fail closed. +Import performs no writes when its lesson preflight read fails and returns a +bounded diagnostic; portable export refuses to omit an unreadable lesson +store. Reflection aborts before provider invocation or insight persistence +when lesson enumeration or normalization fails. + +Obsidian export renders discriminated provenance plus verification state +instead of assuming every anchor is Git. The viewer searches and displays +claim, verdict, lifecycle, durable scope, sensitivity, and computed +stale/contradicted flags. + Default merge never replaces a retracted/superseded row with a non-terminal row. Whole-collection `replace` is the explicit restore path. Both successful changes and restore transitions audit affected IDs and before/after lifecycle diff --git a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md index 58acd2e2da..8329a2de09 100644 --- a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md +++ b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md @@ -35,7 +35,7 @@ agentmemory exposes 60 MCP tools. 7 are in the lean core set (`--tools core` or | `memory_lesson_delete` | | `lessonId`*: string, `reason`*: string, `project`: string, `expectedUpdatedAt`: string, `actor`: string | Retract one lesson by exact ID when its evidence is invalid, preserving the legacy tombstone fields, correction metadata, and audit trail. Requires a human-readable reason. | | `memory_lesson_recall` | yes | `query`*: string, `project`: string, `minConfidence`: number, `limit`: number | Search lessons by query. Returns lessons sorted by confidence and recency. Use to check what the agent has learned before making decisions. | | `memory_lesson_save` | yes | `content`*: string, `context`: string, `confidence`: number, `project`: string, `tags`: string, `mechanismId`: string, `mechanismVersion`: string, `mechanismAliases`: array, `claim`: string, `claimType`: string, `evidenceVerdict`: string, `lifecycle`: string, `applicabilityConditions`: array, `nonApplicabilityConditions`: array, `falsificationConditions`: array, `structuredFacets`: object, `evidenceRefs`: array, `scope`: object, `sensitivity`: string, `reviewAfter`: string, `contradictedByLessonIds`: array | Save a legacy prose lesson or a structured causal lesson. Reinforcement tracks reuse without changing evidence confidence; structured inputs support verdict, lifecycle, durable evidence, scope, sensitivity, and deterministic fingerprints. | -| `memory_lesson_supersede` | | `lessonId`*: string, `replacementLessonId`*: string, `reason`*: string, `project`: string, `expectedUpdatedAt`: string, `actor`: string | Mark one lesson superseded in favor of an active replacement in the same durable scope, preserving legacy tombstone fields, lineage, and an audit trail. | +| `memory_lesson_supersede` | | `lessonId`*: string, `replacementLessonId`*: string, `reason`*: string, `project`: string, `expectedUpdatedAt`: string, `actor`: string | Mark one lesson superseded in favor of an active replacement in the same durable scope, preserving legacy tombstone fields, lineage, and an audit trail. An optional project guard applies only to the original lesson; replacement compatibility follows durable scope rules. | | `memory_llm_smoke` | | none | Run a fixed, non-sensitive LLM connectivity probe. Returns provider/model evidence and performs no persistent AgentMemory or filesystem writes. | | `memory_mesh_sync` | | `peerId`: string, `direction`: string | Sync memories and actions with peer agentmemory instances for multi-agent collaboration. | | `memory_next` | | `project`: string, `agentId`: string | Get the single most important next action to work on. Combines dependency resolution, priority, and recency into a score. | diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index e890e65574..bac5a9a1a8 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -62,6 +62,8 @@ interface LessonLifecycleTransition { after?: string; } +const MAX_LESSON_STATE_DIAGNOSTIC_DETAIL_LENGTH = 256; + export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::export", async (data?: { maxSessions?: number; offset?: number }) => { @@ -129,7 +131,11 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { kv.list(KV.sketches).catch(() => []), kv.list(KV.crystals).catch(() => []), kv.list(KV.facets).catch(() => []), - kv.list(KV.lessons).catch(() => []), + kv.list(KV.lessons).catch((error) => { + throw new Error( + `Lesson export failed closed: authoritative lesson state read failed (${boundedLessonStateDiagnosticDetail(error)})`, + ); + }), kv.list(KV.insights).catch(() => []), kv.list(KV.routines).catch(() => []), kv.list(KV.signals).catch(() => []), @@ -935,7 +941,15 @@ async function applyImportedLessonBatch( | { success: true; written: number; skipped: number } | { success: false; error: string } > { - const existingRows = await kv.list(KV.lessons).catch(() => []); + let existingRows: Lesson[]; + try { + existingRows = await kv.list(KV.lessons); + } catch (error) { + return { + success: false, + error: `Lesson import failed closed: authoritative lesson state read failed (${boundedLessonStateDiagnosticDetail(error)})`, + }; + } const preimage = new Map( existingRows.map((lesson) => [lesson.id, lesson] as const), ); @@ -1136,6 +1150,15 @@ async function applyImportedLessonBatch( return { success: true, written: writes.length, skipped }; } +function boundedLessonStateDiagnosticDetail(error: unknown): string { + const raw = error instanceof Error ? error.message : String(error); + const normalized = raw.replace(/\s+/g, " ").trim() || "unknown error"; + if (normalized.length <= MAX_LESSON_STATE_DIAGNOSTIC_DETAIL_LENGTH) { + return normalized; + } + return `${normalized.slice(0, MAX_LESSON_STATE_DIAGNOSTIC_DETAIL_LENGTH - 3)}...`; +} + async function restoreLessonPreimage( kv: StateKV, affectedIds: string[], diff --git a/src/functions/lesson-model.ts b/src/functions/lesson-model.ts index b55960104d..3c064ddba3 100644 --- a/src/functions/lesson-model.ts +++ b/src/functions/lesson-model.ts @@ -41,6 +41,10 @@ const MAX_EVIDENCE_VERIFIER_LENGTH = 256; const MAX_EVIDENCE_VERIFICATION_NOTE_LENGTH = 1000; const MAX_LESSON_ID_ALIASES = 16; const MAX_LESSON_ID_LENGTH = 256; +const LEGACY_GIT_ANCHOR_MIGRATION_ACTOR = + "agentmemory:legacy-git-anchor-migration"; +const LEGACY_GIT_ANCHOR_MIGRATION_NOTE = + "Compatibility migration preserves the pre-verification schema verdict; evidence relevance was not re-audited."; const FACET_DIMENSION_PATTERN = /^[a-z][a-z0-9_]*$/; const RESERVED_FACET_DIMENSIONS = new Set([ @@ -1061,6 +1065,10 @@ function normalizeEvidenceRef( const legacyGitShape = (record.provenance === undefined || record.provenance === null) && Boolean(legacyRepoRemote); + const allowsLegacyGitAnchorBasis = + allowLegacyGitVerificationMigration && + provenance.type === "git" && + Boolean(commitSha || artifactDigest); const verification = allowLegacyGitVerificationMigration && legacyGitShape && @@ -1068,15 +1076,14 @@ function normalizeEvidenceRef( ? { state: "verified" as const, basis: "legacy-git-anchor" as const, - verifiedBy: "agentmemory:legacy-git-anchor-migration", + verifiedBy: LEGACY_GIT_ANCHOR_MIGRATION_ACTOR, verifiedAt: validatedAt ?? recordedAt, - note: - "Compatibility migration preserves the pre-verification schema verdict; evidence relevance was not re-audited.", + note: LEGACY_GIT_ANCHOR_MIGRATION_NOTE, } : normalizeEvidenceVerification( record.verification, prefix, - allowLegacyGitVerificationMigration, + allowsLegacyGitAnchorBasis, ); const evidenceKindRaw = optionalString( record.evidenceKind, @@ -1262,7 +1269,7 @@ function normalizeImmutableId( function normalizeEvidenceVerification( value: unknown, prefix: string, - allowLegacyGitVerificationMigration: boolean, + allowLegacyGitAnchorBasis: boolean, ): LessonEvidenceVerification { if (value === undefined || value === null) { return { state: "unverified" }; @@ -1290,10 +1297,10 @@ function normalizeEvidenceVerification( } if ( basisRaw === "legacy-git-anchor" && - !allowLegacyGitVerificationMigration + !allowLegacyGitAnchorBasis ) { throw new LessonInputError( - `${prefix}.verification.basis legacy-git-anchor is reserved for compatibility import`, + `${prefix}.verification.basis legacy-git-anchor is reserved for compatibility import of immutable Git provenance`, ); } const basis = @@ -1315,6 +1322,15 @@ function normalizeEvidenceVerification( `${prefix}.verification.note`, MAX_EVIDENCE_VERIFICATION_NOTE_LENGTH, ); + if ( + basisRaw === "legacy-git-anchor" && + (state !== "verified" || + verifiedBy !== LEGACY_GIT_ANCHOR_MIGRATION_ACTOR) + ) { + throw new LessonInputError( + `${prefix}.verification.basis legacy-git-anchor requires verified state and canonical migration actor ${LEGACY_GIT_ANCHOR_MIGRATION_ACTOR}`, + ); + } if (state !== "unverified" && (!verifiedBy || !verifiedAt)) { throw new LessonInputError( `${prefix}.verification ${state} state requires verifiedBy and verifiedAt`, diff --git a/src/functions/obsidian-export.ts b/src/functions/obsidian-export.ts index 4058a1c1ef..2058d28d44 100644 --- a/src/functions/obsidian-export.ts +++ b/src/functions/obsidian-export.ts @@ -7,6 +7,7 @@ import { KV } from "../state/schema.js"; import type { Memory, Lesson, + LessonEvidenceReference, Crystal, Session, } from "../types.js"; @@ -57,6 +58,40 @@ function safeTimestamp(value: unknown): number { return Number.isFinite(time) ? time : 0; } +function evidenceReferenceToMd( + reference: LessonEvidenceReference, +): string { + const provenance = reference.provenance; + const type = provenance?.type ?? "git"; + const locator = + provenance?.locator ?? reference.repoRemoteUrl ?? "missing-locator"; + const immutableId = + provenance?.immutableId ?? reference.commitSha; + const digest = + provenance?.digest ?? reference.artifactDigest; + const path = provenance?.path ?? reference.path; + const verification = reference.verification ?? { state: "unverified" }; + const fields = [ + `type=${type}`, + `locator=${JSON.stringify(locator)}`, + immutableId ? `immutableId=${JSON.stringify(immutableId)}` : undefined, + digest ? `digest=${JSON.stringify(digest)}` : undefined, + path ? `path=${JSON.stringify(path)}` : undefined, + `verification=${verification.state}`, + verification.basis ? `basis=${verification.basis}` : undefined, + verification.verifiedBy + ? `verifiedBy=${JSON.stringify(verification.verifiedBy)}` + : undefined, + verification.verifiedAt + ? `verifiedAt=${JSON.stringify(verification.verifiedAt)}` + : undefined, + verification.note + ? `verificationNote=${JSON.stringify(verification.note)}` + : undefined, + ].filter((field): field is string => Boolean(field)); + return `- ${reference.kind}: ${fields.join(" ")}`; +} + function toFrontmatter(obj: Record): string { const lines = ["---"]; for (const [key, value] of Object.entries(obj)) { @@ -140,22 +175,24 @@ function lessonToMd(l: Lesson): string { decayRate: lesson.decayRate, mechanismId: lesson.mechanismId, mechanismVersion: lesson.mechanismVersion, + mechanismAliases: lesson.mechanismAliases, claimType: lesson.claimType, evidenceVerdict: lesson.evidenceVerdict, lifecycle: lesson.lifecycle, scopeRing: lesson.scope.ring, scopeId: lesson.scope.scopeId, sensitivity: lesson.sensitivity, + reviewAfter: lesson.reviewAfter, + contradictedByLessonIds: lesson.contradictedByLessonIds, + structuredFacets: lesson.structuredFacets, + computedStale: lesson.computedFlags.stale, + computedContradicted: lesson.computedFlags.contradicted, contentFingerprint: lesson.contentFingerprint, }); const sourceLinks = sourceIds.map((id) => `- [[${id}]]`).join("\n"); const evidenceLines = lesson.evidenceRefs - .map((reference) => { - const anchor = reference.commitSha ?? reference.artifactDigest; - const path = reference.path ? `:${reference.path}` : ""; - return `- ${reference.kind}: ${reference.repoRemoteUrl}@${anchor}${path}`; - }) + .map(evidenceReferenceToMd) .join("\n"); const sections = [ diff --git a/src/functions/reflect.ts b/src/functions/reflect.ts index ba7bbec50e..e06d82f51b 100644 --- a/src/functions/reflect.ts +++ b/src/functions/reflect.ts @@ -35,6 +35,8 @@ interface ConceptCluster { crystalIds: string[]; } +const MAX_REFLECT_DIAGNOSTIC_DETAIL_LENGTH = 256; + function reinforceInsight(insight: Insight): void { const now = new Date().toISOString(); insight.reinforcements++; @@ -191,6 +193,29 @@ function normalizeInsightEvidenceVerdict( : undefined; } +function reflectLessonReadFailure( + stage: "state read" | "normalization", + error: unknown, +): { + success: false; + error: string; + newInsights: 0; + reinforced: 0; +} { + const raw = error instanceof Error ? error.message : String(error); + const normalized = raw.replace(/\s+/g, " ").trim() || "unknown error"; + const detail = + normalized.length <= MAX_REFLECT_DIAGNOSTIC_DETAIL_LENGTH + ? normalized + : `${normalized.slice(0, MAX_REFLECT_DIAGNOSTIC_DETAIL_LENGTH - 3)}...`; + return { + success: false, + error: `Reflection failed closed: authoritative lesson ${stage} failed (${detail})`, + newInsights: 0, + reinforced: 0, + }; +} + export function registerReflectFunctions( sdk: ISdk, kv: StateKV, @@ -202,22 +227,29 @@ export function registerReflectFunctions( const maxInsightsPerCluster = 5; const maxTotal = 50; - const [graphNodes, graphEdges, semanticMemories, lessons, crystals] = + let lessons: Lesson[]; + try { + lessons = await kv.list(KV.lessons); + } catch (error) { + return reflectLessonReadFailure("state read", error); + } + const [graphNodes, graphEdges, semanticMemories, crystals] = await Promise.all([ kv.list(KV.graphNodes).catch(() => []), kv.list(KV.graphEdges).catch(() => []), kv.list(KV.semantic).catch(() => []), - kv.list(KV.lessons).catch(() => []), kv.list(KV.crystals).catch(() => []), ]); let activeLessons: LessonReadModel[] = []; - for (const lesson of lessons) { - try { + try { + for (const lesson of lessons) { if (isLessonRecallable(lesson)) { activeLessons.push(toLessonReadModel(lesson)); } - } catch {} + } + } catch (error) { + return reflectLessonReadFailure("normalization", error); } if (data?.project) { activeLessons = activeLessons.filter((l) => l.project === data.project); diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts index 72733b46d2..349bd35bb8 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -1046,7 +1046,7 @@ export const V070_TOOLS: McpToolDef[] = [ scope: { type: "object", description: - "Scope ring and durable scope identity; project remains only a label", + "Caller-supplied scope classification and lineage metadata, not authorization; project remains only a label", properties: { ring: { type: "string", @@ -1055,6 +1055,8 @@ export const V070_TOOLS: McpToolDef[] = [ scopeId: { type: "string" }, humanApproval: { type: "object", + description: + "Caller-supplied approval metadata for global promotion; PR1 does not authenticate this identity", properties: { approvedBy: { type: "string" }, approvedAt: { type: "string" }, @@ -1128,7 +1130,8 @@ export const V070_TOOLS: McpToolDef[] = [ }, actor: { type: "string", - description: "Optional actor attribution; defaults to AGENT_ID", + description: + "Optional caller-supplied audit attribution, not authenticated identity; defaults to AGENT_ID", }, }, required: ["lessonId", "reason"], @@ -1137,7 +1140,7 @@ export const V070_TOOLS: McpToolDef[] = [ { name: "memory_lesson_supersede", description: - "Mark one lesson superseded in favor of an active replacement in the same durable scope, preserving legacy tombstone fields, lineage, and an audit trail.", + "Mark one lesson superseded in favor of an active replacement in the same durable scope, preserving legacy tombstone fields, lineage, and an audit trail. An optional project guard applies only to the original lesson; replacement compatibility follows durable scope rules.", inputSchema: { type: "object", properties: { @@ -1155,7 +1158,8 @@ export const V070_TOOLS: McpToolDef[] = [ }, project: { type: "string", - description: "Optional project guard; must match both lessons", + description: + "Optional project guard for the original lesson; replacement compatibility is enforced by durable scope rules", }, expectedUpdatedAt: { type: "string", @@ -1164,7 +1168,8 @@ export const V070_TOOLS: McpToolDef[] = [ }, actor: { type: "string", - description: "Optional actor attribution; defaults to AGENT_ID", + description: + "Optional caller-supplied audit attribution, not authenticated identity; defaults to AGENT_ID", }, }, required: ["lessonId", "replacementLessonId", "reason"], diff --git a/src/viewer/index.html b/src/viewer/index.html index afbc3f0d6c..12fbe6d2bc 100644 --- a/src/viewer/index.html +++ b/src/viewer/index.html @@ -3081,7 +3081,27 @@

agentmemory

if (search) { items = items.filter(function(l) { - return (l.content + ' ' + l.context + ' ' + (l.tags || []).join(' ')).toLowerCase().indexOf(search) >= 0; + var scope = l.scope || {}; + var flags = l.computedFlags || {}; + var facets = l.structuredFacets || {}; + var facetText = Object.keys(facets).map(function(dimension) { + return dimension + ' ' + (facets[dimension] || []).join(' '); + }).join(' '); + return [ + l.content, + l.context, + l.claim, + l.mechanismId, + l.evidenceVerdict, + l.lifecycle, + scope.ring, + scope.scopeId, + l.sensitivity, + flags.stale ? 'stale' : '', + flags.contradicted ? 'contradicted' : '', + (l.tags || []).join(' '), + facetText + ].filter(Boolean).join(' ').toLowerCase().indexOf(search) >= 0; }); } @@ -3100,16 +3120,34 @@

agentmemory

'
💡
' + '
No lessons yet
' + '
Lessons are confidence-scored pattern observations — things you corrected once that the agent should never do again. They persist across projects.
' + - '
# Save a lesson explicitly\nmemory_lesson_save { rule, reason, confidence }\n\n# Or: Replay tab → Import JSONL auto-extracts lessons\n# from your past Claude Code sessions
' + + '
# Save a lesson explicitly\nmemory_lesson_save { content, confidence }\n\n# Or: Replay tab → Import JSONL auto-extracts lessons\n# from your past Claude Code sessions
' + '' + ''; } else { - html += '
LessonConfidenceReinforcementsSourceProjectUpdated
'; + html += '
LessonConfidenceReinforcementsSourceProjectUpdated
'; items.forEach(function(l) { var confPct = Math.round(l.confidence * 100); var confColor = confPct >= 70 ? 'var(--green)' : confPct >= 40 ? 'var(--yellow)' : 'var(--red)'; + var verdict = l.evidenceVerdict || 'unverified'; + var verdictBadge = verdict === 'supported' ? 'badge-green' : verdict === 'refuted' ? 'badge-red' : verdict === 'mixed' ? 'badge-yellow' : 'badge-muted'; + var lifecycle = l.lifecycle || 'active'; + var lifecycleBadge = lifecycle === 'active' ? 'badge-green' : lifecycle === 'draft' ? 'badge-muted' : lifecycle === 'superseded' ? 'badge-yellow' : 'badge-red'; + var scope = l.scope || { ring: 'worktree' }; + var flags = l.computedFlags || {}; html += ''; - html += ''; + html += ''; + html += ''; + html += ''; html += ''; html += ''; html += ''; diff --git a/test/export-import.test.ts b/test/export-import.test.ts index f5f6be0851..5f225480a4 100644 --- a/test/export-import.test.ts +++ b/test/export-import.test.ts @@ -24,9 +24,10 @@ import { parseImportedLesson } from "../src/functions/lesson-model.js"; function mockKV() { const store = new Map>(); const injectedFailures: Array<{ - operation: "set" | "delete"; + operation: "set" | "delete" | "list"; scope: string; - key: string; + key?: string; + message?: string; }> = []; let setBarrier: | { @@ -75,6 +76,16 @@ function mockKV() { store.get(scope)?.delete(key); }, list: async (scope: string): Promise => { + const listFailureIndex = injectedFailures.findIndex( + (failure) => + failure.operation === "list" && failure.scope === scope, + ); + if (listFailureIndex >= 0) { + const [failure] = injectedFailures.splice(listFailureIndex, 1); + throw new Error( + failure.message ?? `injected list failure for ${scope}`, + ); + } const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; }, @@ -85,6 +96,9 @@ function mockKV() { ): void { injectedFailures.push({ operation, scope, key }); }, + failNextList(scope: string, message?: string): void { + injectedFailures.push({ operation: "list", scope, message }); + }, pauseNextSet(scope: string, key: string): { reached: Promise; release: () => void; @@ -261,6 +275,36 @@ describe("Export/Import Functions", () => { expect(result.summaries.length).toBe(1); }); + it("fails closed instead of silently omitting lessons when authoritative export enumeration fails", async () => { + const tombstone = importedLesson({ + ...structuredLesson("export-read-failure"), + lifecycle: "retracted", + deleted: true, + deletedAt: "2026-08-02T21:00:00.000Z", + deletedBy: "reviewer", + deleteReason: "invalid evidence", + }); + await kv.set("mem:lessons", tombstone.id, tombstone); + kv.failNextList( + "mem:lessons", + `injected state::list failure ${"x".repeat(4096)}`, + ); + + const error = await sdk + .trigger("mem::export", {}) + .then(() => null) + .catch((caught) => caught as Error); + + expect(error).toBeInstanceOf(Error); + expect(error?.message).toContain( + "authoritative lesson state read failed", + ); + expect(error?.message.length).toBeLessThanOrEqual(400); + expect(await kv.get("mem:lessons", tombstone.id)).toEqual( + tombstone, + ); + }); + it("import with merge strategy adds data", async () => { const exportData: ExportData = { version: "0.3.0", @@ -547,6 +591,46 @@ describe("Export/Import Functions", () => { expect(await kv.list("mem:lessons")).toEqual([]); }); + it("fails closed on an authoritative lesson-state read error without resurrecting a tombstone", async () => { + const active = structuredLesson("read-failure-tombstone"); + const tombstone = importedLesson({ + ...active, + lifecycle: "retracted", + deleted: true, + deletedAt: "2026-08-02T21:00:00.000Z", + deletedBy: "reviewer", + deleteReason: "invalid evidence", + }); + const unrelated = importedLesson(structuredLesson("read-failure-unrelated")); + await kv.set("mem:lessons", tombstone.id, tombstone); + kv.failNextList( + "mem:lessons", + `injected state::list failure ${"x".repeat(4096)}`, + ); + + const result = (await sdk.trigger("mem::import", { + exportData: emptyExport([ + active, + structuredLesson("read-failure-unrelated"), + ]), + strategy: "merge", + })) as { success: boolean; error: string }; + + expect(result).toMatchObject({ + success: false, + error: expect.stringContaining( + "authoritative lesson state read failed", + ), + }); + expect(result.error.length).toBeLessThanOrEqual(400); + expect(result).not.toHaveProperty("lessons"); + expect(await kv.get("mem:lessons", tombstone.id)).toEqual( + tombstone, + ); + expect(await kv.get("mem:lessons", unrelated.id)).toBeNull(); + expect(await kv.list("mem:lessons")).toEqual([tombstone]); + }); + it.each(["retracted", "superseded"] as const)( "blocks merge resurrection of a %s lesson without partially writing the batch", async (lifecycle) => { diff --git a/test/lesson-model.test.ts b/test/lesson-model.test.ts index 9f517ef965..a4fd2f546a 100644 --- a/test/lesson-model.test.ts +++ b/test/lesson-model.test.ts @@ -347,6 +347,153 @@ describe("causal lesson model", () => { ], }, }); + if (!imported.success) throw new Error(imported.error); + expect(parseImportedLesson(imported.lesson)).toMatchObject({ + success: true, + lesson: { + evidenceRefs: [ + { + verification: { + state: "verified", + basis: "legacy-git-anchor", + verifiedBy: "agentmemory:legacy-git-anchor-migration", + }, + }, + ], + }, + }); + }); + + it("accepts a serialized legacy-git-anchor basis only with immutable Git provenance", () => { + const imported = parseImportedLesson({ + ...legacyLesson(), + id: "serialized-git-migration", + schemaVersion: 1, + mechanismId: "legacy/serialized-git-evidence", + claim: "A serialized compatibility record retains its immutable Git anchor.", + evidenceVerdict: "refuted", + evidenceRefs: [ + { + kind: "falsification", + projectId: "agentmemory", + provenance: { + type: "git", + locator: "https://github.com/rohitg00/agentmemory", + immutableId: "e".repeat(40), + }, + recordedAt: "2026-08-02T20:00:00Z", + verification: { + state: "verified", + basis: "legacy-git-anchor", + verifiedBy: "agentmemory:legacy-git-anchor-migration", + verifiedAt: "2026-08-02T20:00:00Z", + }, + }, + ], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + }); + + expect(imported).toMatchObject({ + success: true, + lesson: { + evidenceRefs: [ + { + provenance: { type: "git", immutableId: "e".repeat(40) }, + verification: { + state: "verified", + basis: "legacy-git-anchor", + }, + }, + ], + }, + }); + }); + + it.each([ + { + type: "oci", + provenance: { + type: "oci", + locator: "ghcr.io/example/evidence", + digest: `sha256:${"6".repeat(64)}`, + }, + }, + { + type: "doi", + provenance: { + type: "doi", + locator: "10.1000/non-git-evidence", + }, + }, + ])( + "rejects a non-Git $type reference claiming the reserved legacy migration basis", + ({ type, provenance }) => { + const imported = parseImportedLesson({ + ...legacyLesson(), + id: `spoofed-${type}-migration`, + schemaVersion: 1, + mechanismId: `legacy/spoofed-${type}`, + claim: "Non-Git provenance cannot claim the Git compatibility migration.", + evidenceVerdict: "refuted", + evidenceRefs: [ + { + kind: "falsification", + projectId: "agentmemory", + provenance, + recordedAt: "2026-08-02T20:00:00Z", + verification: { + state: "verified", + basis: "legacy-git-anchor", + verifiedBy: "agentmemory:legacy-git-anchor-migration", + verifiedAt: "2026-08-02T20:00:00Z", + }, + }, + ], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + }); + + expect(imported).toMatchObject({ + success: false, + error: expect.stringContaining( + "reserved for compatibility import of immutable Git provenance", + ), + }); + }, + ); + + it("rejects arbitrary migration actors even for immutable Git provenance", () => { + const imported = parseImportedLesson({ + ...legacyLesson(), + id: "spoofed-git-migration-actor", + schemaVersion: 1, + mechanismId: "legacy/spoofed-git-actor", + claim: "The reserved migration actor cannot be caller-selected.", + evidenceVerdict: "refuted", + evidenceRefs: [ + { + kind: "falsification", + projectId: "agentmemory", + provenance: { + type: "git", + locator: "https://github.com/rohitg00/agentmemory", + immutableId: "d".repeat(40), + }, + recordedAt: "2026-08-02T20:00:00Z", + verification: { + state: "verified", + basis: "legacy-git-anchor", + verifiedBy: "caller-selected-reviewer", + verifiedAt: "2026-08-02T20:00:00Z", + }, + }, + ], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + }); + + expect(imported).toMatchObject({ + success: false, + error: expect.stringContaining("canonical migration actor"), + }); }); it("requires durable scope identity and human approval for global promotion", () => { diff --git a/test/obsidian-export.test.ts b/test/obsidian-export.test.ts index 31394bca97..1044a47fc3 100644 --- a/test/obsidian-export.test.ts +++ b/test/obsidian-export.test.ts @@ -195,6 +195,61 @@ describe("Obsidian Export", () => { expect(content).toContain('source: "manual"'); }); + it("renders structured lesson provenance, verification, and computed fields without Git-only placeholders", async () => { + const lesson: Lesson = { + ...makeLesson("lsn_structured"), + schemaVersion: 1, + mechanismId: "projection/non-git", + claim: "Non-Git evidence remains visible in portable lesson exports.", + claimType: "causal", + evidenceVerdict: "supported", + lifecycle: "active", + evidenceRefs: [ + { + kind: "attestation", + projectId: "agentmemory", + provenance: { + type: "oci", + locator: "ghcr.io/example/evidence", + digest: `sha256:${"a".repeat(64)}`, + }, + recordedAt: "2026-04-01T00:00:00Z", + verification: { + state: "verified", + verifiedBy: "reviewer@example.test", + verifiedAt: "2026-04-01T01:00:00Z", + }, + }, + ], + structuredFacets: { signal_family: ["projection-test"] }, + contradictedByLessonIds: ["lsn_counterexample"], + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + sensitivity: "restricted", + }; + await kv.set("mem:lessons", lesson.id, lesson); + + const result = (await sdk.trigger("mem::obsidian-export", {})) as { + exported: Record; + }; + const lessonFile = [...writtenFiles.entries()].find(([path]) => + path.includes("lessons/lsn_structured.md"), + ); + + expect(result.exported.lessons).toBe(1); + expect(lessonFile).toBeDefined(); + expect(lessonFile?.[1]).toContain("type=oci"); + expect(lessonFile?.[1]).toContain( + 'locator="ghcr.io/example/evidence"', + ); + expect(lessonFile?.[1]).toContain( + `digest="sha256:${"a".repeat(64)}"`, + ); + expect(lessonFile?.[1]).toContain("verification=verified"); + expect(lessonFile?.[1]).toContain("basis=explicit-review"); + expect(lessonFile?.[1]).toContain("computedContradicted: true"); + expect(lessonFile?.[1]).not.toContain("undefined@undefined"); + }); + it("exports crystals with wikilinks to source actions", async () => { const crystal = makeCrystal("crys_001"); await kv.set("mem:crystals", crystal.id, crystal); diff --git a/test/reflect.test.ts b/test/reflect.test.ts index 965c49eab9..5a48de74cf 100644 --- a/test/reflect.test.ts +++ b/test/reflect.test.ts @@ -9,22 +9,31 @@ import type { Insight, GraphNode, GraphEdge, SemanticMemory, Lesson, Crystal } f function mockKV() { const store = new Map>(); + const listFailures = new Map(); return { get: async (scope: string, key: string): Promise => { return (store.get(scope)?.get(key) as T) ?? null; }, - set: async (scope: string, key: string, data: T): Promise => { + set: vi.fn(async (scope: string, key: string, data: T): Promise => { if (!store.has(scope)) store.set(scope, new Map()); store.get(scope)!.set(key, data); return data; - }, + }), delete: async (scope: string, key: string): Promise => { store.get(scope)?.delete(key); }, list: async (scope: string): Promise => { + const failure = listFailures.get(scope); + if (failure !== undefined) { + listFailures.delete(scope); + throw new Error(failure); + } const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; }, + failNextList(scope: string, message: string): void { + listFailures.set(scope, message); + }, }; } @@ -257,6 +266,77 @@ describe("Reflect", () => { expect(result.newInsights).toBe(0); }); + it("fails closed with zero writes when authoritative lesson enumeration fails", async () => { + await kv.set("mem:graph:nodes", "node_security", makeConceptNode("security")); + await kv.set("mem:graph:nodes", "node_validation", makeConceptNode("validation")); + await kv.set("mem:graph:edges", "edge_1", makeEdge("security", "validation")); + await kv.set("mem:semantic", "sem_1", makeSemantic("security requires validation", "sem_1")); + await kv.set("mem:semantic", "sem_2", makeSemantic("validation protects security", "sem_2")); + await kv.set("mem:semantic", "sem_3", makeSemantic("security validation blocks defects", "sem_3")); + kv.set.mockClear(); + kv.failNextList( + "mem:lessons", + `injected state::list failure ${"x".repeat(4096)}`, + ); + + const result = (await sdk.trigger("mem::reflect", {})) as { + success: boolean; + error: string; + newInsights: number; + }; + + expect(result).toMatchObject({ + success: false, + newInsights: 0, + error: expect.stringContaining( + "authoritative lesson state read failed", + ), + }); + expect(result.error.length).toBeLessThanOrEqual(400); + expect(provider.summarize).not.toHaveBeenCalled(); + expect(kv.set).not.toHaveBeenCalled(); + expect(await kv.list("mem:insights")).toEqual([]); + }); + + it("fails closed with zero writes when a structured lesson cannot be normalized", async () => { + await kv.set("mem:graph:nodes", "node_security", makeConceptNode("security")); + await kv.set("mem:graph:nodes", "node_validation", makeConceptNode("validation")); + await kv.set("mem:graph:edges", "edge_1", makeEdge("security", "validation")); + await kv.set("mem:semantic", "sem_1", makeSemantic("security requires validation", "sem_1")); + await kv.set("mem:semantic", "sem_2", makeSemantic("validation protects security", "sem_2")); + await kv.set("mem:semantic", "sem_3", makeSemantic("security validation blocks defects", "sem_3")); + await kv.set( + "mem:lessons", + "lsn_invalid", + { + ...makeLesson("Invalid structured lesson", ["security"]), + schemaVersion: 1, + mechanismId: "invalid/structured", + claim: "Malformed evidence must not disappear.", + evidenceRefs: "not-an-array", + scope: { ring: "repo", scopeId: "repo:agentmemory" }, + } as unknown as Lesson, + ); + kv.set.mockClear(); + + const result = (await sdk.trigger("mem::reflect", {})) as { + success: boolean; + error: string; + newInsights: number; + }; + + expect(result).toMatchObject({ + success: false, + newInsights: 0, + error: expect.stringContaining( + "authoritative lesson normalization failed", + ), + }); + expect(provider.summarize).not.toHaveBeenCalled(); + expect(kv.set).not.toHaveBeenCalled(); + expect(await kv.list("mem:insights")).toEqual([]); + }); + it("labels refuted claims in the prompt and refuses positive synthesis persistence", async () => { provider.summarize.mockResolvedValue( ` diff --git a/test/replay-import-key.test.ts b/test/replay-import-key.test.ts index 1391f0ffea..04a5e24a5c 100644 --- a/test/replay-import-key.test.ts +++ b/test/replay-import-key.test.ts @@ -189,6 +189,43 @@ describe("import-jsonl re-key on parsed.sessionId (#775)", () => { }); }); + it("preserves a retracted tombstone when replay rediscovers the same canonical lesson", async () => { + const content = "Always preserve terminal lesson tombstones during replay."; + writeFixture( + "sess-terminal-lesson", + "2026-04-17T10:00:00.000Z", + content, + ); + const kv = mockKV(); + const sdk = mockSdk(kv); + registerLessonsFunctions(sdk, kv as never); + registerReplayFunctions(sdk, kv as never); + const saved = (await sdk.trigger("mem::lesson-save", { + content, + project: "proj", + })) as { lesson: Lesson }; + await sdk.trigger("mem::lesson-delete", { + lessonId: saved.lesson.id, + reason: "The replayed evidence was invalid", + actor: "reviewer", + }); + + const result = await sdk.trigger("mem::replay::import-jsonl", { + path: tmpRoot, + }); + const lessons = await kv.list(KV.lessons); + + expect(result).toMatchObject({ success: true, imported: 1 }); + expect(lessons).toHaveLength(1); + expect(lessons[0]).toMatchObject({ + id: saved.lesson.id, + lifecycle: "retracted", + deleted: true, + deletedBy: "reviewer", + deleteReason: "The replayed evidence was invalid", + }); + }); + it("finds a legacy replay lesson by canonical identity without creating a duplicate", async () => { const content = "Never trust a replay path without validation."; writeFixture( diff --git a/test/viewer-lessons-schema.test.ts b/test/viewer-lessons-schema.test.ts new file mode 100644 index 0000000000..f191bd3bb0 --- /dev/null +++ b/test/viewer-lessons-schema.test.ts @@ -0,0 +1,26 @@ +import { readFileSync } from "node:fs"; +import { describe, expect, it } from "vitest"; + +describe("viewer structured lesson projection", () => { + const viewer = readFileSync("src/viewer/index.html", "utf-8"); + + it("searches canonical claim, verdict, lifecycle, scope, sensitivity, flags, and facets", () => { + expect(viewer).toContain("l.claim"); + expect(viewer).toContain("l.evidenceVerdict"); + expect(viewer).toContain("l.lifecycle"); + expect(viewer).toContain("scope.scopeId"); + expect(viewer).toContain("l.sensitivity"); + expect(viewer).toContain("flags.stale ? 'stale' : ''"); + expect(viewer).toContain("flags.contradicted ? 'contradicted' : ''"); + expect(viewer).toContain("l.structuredFacets || {}"); + }); + + it("renders structured evidence state, lifecycle, scope, sensitivity, and computed flags", () => { + expect(viewer).toContain("Claim:"); + expect(viewer).toContain("var verdict = l.evidenceVerdict || 'unverified'"); + expect(viewer).toContain("var lifecycle = l.lifecycle || 'active'"); + expect(viewer).toContain("sensitivity: "); + expect(viewer).toContain(">contradicted"); + expect(viewer).toContain(">stale"); + }); +}); From 3602a45c135867e34839ef6c5b1df92f7d461cfe Mon Sep 17 00:00:00 2001 From: wrightpt Date: Sun, 2 Aug 2026 23:17:38 -0400 Subject: [PATCH 35/43] fix(viewer): render structured lesson facets --- src/viewer/index.html | 30 +++++++++++++-- test/viewer-lessons-schema.test.ts | 61 +++++++++++++++++++++++++++++- 2 files changed, 87 insertions(+), 4 deletions(-) diff --git a/src/viewer/index.html b/src/viewer/index.html index 12fbe6d2bc..ee0679fb5c 100644 --- a/src/viewer/index.html +++ b/src/viewer/index.html @@ -1133,6 +1133,30 @@

agentmemory

d.textContent = String(s); return d.innerHTML; } + function lessonFacetEntries(facets) { + var entries = []; + Object.keys(facets || {}).sort().forEach(function(dimension) { + var values = Array.isArray(facets[dimension]) + ? facets[dimension].filter(function(value) { + return value !== undefined && value !== null && String(value).length > 0; + }).map(function(value) { return String(value); }).sort() + : []; + values.forEach(function(value) { + entries.push({ dimension: dimension, value: value }); + }); + }); + return entries; + } + function renderLessonFacets(facets) { + var entries = lessonFacetEntries(facets); + if (entries.length === 0) return ''; + var html = '
'; + html += 'Facets:'; + entries.forEach(function(entry) { + html += '' + esc(entry.dimension) + ': ' + esc(entry.value) + ''; + }); + return html + '
'; + } function formatTime(ts) { if (!ts) return ''; try { return new Date(ts).toLocaleString(); } catch { return ts; } @@ -3083,9 +3107,8 @@

agentmemory

items = items.filter(function(l) { var scope = l.scope || {}; var flags = l.computedFlags || {}; - var facets = l.structuredFacets || {}; - var facetText = Object.keys(facets).map(function(dimension) { - return dimension + ' ' + (facets[dimension] || []).join(' '); + var facetText = lessonFacetEntries(l.structuredFacets).map(function(entry) { + return entry.dimension + ' ' + entry.value; }).join(' '); return [ l.content, @@ -3139,6 +3162,7 @@

agentmemory

if (l.claim) html += '
Claim: ' + esc(truncate(l.claim, 180)) + '
'; if (l.mechanismId) html += '
' + esc(l.mechanismId) + '
'; if (l.context) html += '
' + esc(truncate(l.context, 80)) + '
'; + html += renderLessonFacets(l.structuredFacets); html += ''; html += '
Lesson / ClaimEvidenceLifecycle / ScopeConfidenceReinforcementsSourceProjectUpdated
' + esc(truncate(l.content, 120)) + (l.context ? '
' + esc(truncate(l.context, 80)) + '
' : '') + '
' + esc(truncate(l.content, 120)); + if (l.claim) html += '
Claim: ' + esc(truncate(l.claim, 180)) + '
'; + if (l.mechanismId) html += '
' + esc(l.mechanismId) + '
'; + if (l.context) html += '
' + esc(truncate(l.context, 80)) + '
'; + html += '
' + esc(verdict) + ''; + if (flags.contradicted) html += '
contradicted
'; + if (flags.stale) html += '
stale
'; + html += '
' + esc(lifecycle) + ''; + html += '
' + esc(scope.ring || 'worktree'); + if (scope.scopeId) html += ' · ' + esc(truncate(scope.scopeId, 60)); + html += '
sensitivity: ' + esc(l.sensitivity || 'restricted') + '
' + confPct + '%
' + (l.reinforcements || 0) + '' + esc(l.source) + '' + esc(verdict) + ''; if (flags.contradicted) html += '
contradicted
'; diff --git a/test/viewer-lessons-schema.test.ts b/test/viewer-lessons-schema.test.ts index f191bd3bb0..aa83c97fac 100644 --- a/test/viewer-lessons-schema.test.ts +++ b/test/viewer-lessons-schema.test.ts @@ -3,6 +3,20 @@ import { describe, expect, it } from "vitest"; describe("viewer structured lesson projection", () => { const viewer = readFileSync("src/viewer/index.html", "utf-8"); + const helpersStart = viewer.indexOf(" function lessonFacetEntries("); + const helpersEnd = viewer.indexOf("\n function formatTime(", helpersStart); + const helperSource = viewer.slice(helpersStart, helpersEnd); + const escapeHtml = (value: unknown): string => + value + ? String(value) + .replaceAll("&", "&") + .replaceAll("<", "<") + .replaceAll(">", ">") + : ""; + const renderLessonFacets = new Function( + "esc", + `${helperSource}\nreturn renderLessonFacets;`, + )(escapeHtml) as (facets?: Record) => string; it("searches canonical claim, verdict, lifecycle, scope, sensitivity, flags, and facets", () => { expect(viewer).toContain("l.claim"); @@ -12,7 +26,7 @@ describe("viewer structured lesson projection", () => { expect(viewer).toContain("l.sensitivity"); expect(viewer).toContain("flags.stale ? 'stale' : ''"); expect(viewer).toContain("flags.contradicted ? 'contradicted' : ''"); - expect(viewer).toContain("l.structuredFacets || {}"); + expect(viewer).toContain("lessonFacetEntries(l.structuredFacets)"); }); it("renders structured evidence state, lifecycle, scope, sensitivity, and computed flags", () => { @@ -23,4 +37,49 @@ describe("viewer structured lesson projection", () => { expect(viewer).toContain(">contradicted"); expect(viewer).toContain(">stale"); }); + + it("renders multiple structured facet entries visibly, deterministically, and escaped", () => { + const markup = renderLessonFacets({ + signal_family: ["mean_reversion", ""], + asset: ["ETH", "BTC"], + }); + + expect(viewer).toMatch( + /html \+= renderLessonFacets\(l\.structuredFacets\);\s*html \+= '<\/td>';/, + ); + expect(markup).toContain('class="lesson-facets"'); + expect(markup).toContain(">Facets:"); + expect(markup).not.toContain(""); + expect(markup).toContain( + "signal_family: <breakout&retest>", + ); + expect(markup.indexOf("asset: BTC")).toBeLessThan( + markup.indexOf("asset: ETH"), + ); + expect(markup.indexOf("asset: ETH")).toBeLessThan( + markup.indexOf("signal_family: <breakout&retest>"), + ); + expect( + markup.indexOf("signal_family: <breakout&retest>"), + ).toBeLessThan(markup.indexOf("signal_family: mean_reversion")); + }); + + it("omits the visible facet field for absent or empty facets", () => { + expect(renderLessonFacets()).toBe(""); + expect(renderLessonFacets({})).toBe(""); + expect( + renderLessonFacets({ + signal_family: [], + venue: undefined, + regime: [undefined, null, ""], + }), + ).toBe(""); + expect( + [ + renderLessonFacets(), + renderLessonFacets({}), + renderLessonFacets({ venue: undefined }), + ].join(""), + ).not.toContain("undefined"); + }); }); From dfe1aa195c7c5d192cb8a3d5ed4a157ed3dc92e5 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Mon, 3 Aug 2026 00:30:34 -0400 Subject: [PATCH 36/43] feat: enforce causal lesson access policy --- .env.example | 9 + README.md | 49 +- .../2026-08-02-causal-lesson-schema-v1.md | 18 +- .../2026-08-03-causal-lesson-access-v2.md | 122 ++++ integrations/openclaw/plugin.mjs | 6 + integrations/pi/index.ts | 4 + plugin/.mcp.copilot.json | 2 + plugin/.mcp.json | 2 + plugin/opencode/agentmemory-capture.ts | 6 + plugin/scripts/pre-compact.mjs | 4 + plugin/scripts/session-start.mjs | 4 + plugin/skills/agentmemory-config/REFERENCE.md | 5 +- src/cli.ts | 21 +- src/cli/connect/util.ts | 6 +- src/functions/consolidation-pipeline.ts | 7 +- src/functions/context.ts | 14 +- src/functions/crystallize.ts | 2 + src/functions/export-import.ts | 113 +++- src/functions/lesson-access.ts | 639 ++++++++++++++++++ src/functions/lessons.ts | 105 ++- src/functions/obsidian-export.ts | 34 +- src/functions/reflect.ts | 19 +- src/functions/smart-search.ts | 13 +- src/hooks/pre-compact.ts | 4 + src/hooks/session-start.ts | 4 + src/mcp/http.ts | 8 +- src/mcp/rest-proxy.ts | 12 + src/mcp/server.ts | 67 +- src/triggers/api.ts | 160 ++++- src/triggers/events.ts | 14 +- test/cli-connect.test.ts | 2 + test/lesson-access.test.ts | 374 ++++++++++ test/lesson-authorization.test.ts | 384 +++++++++++ test/mcp-standalone-proxy.test.ts | 22 + 34 files changed, 2186 insertions(+), 69 deletions(-) create mode 100644 docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md create mode 100644 src/functions/lesson-access.ts create mode 100644 test/lesson-access.test.ts create mode 100644 test/lesson-authorization.test.ts diff --git a/.env.example b/.env.example index 1ccb8dfaec..beb6a4ba01 100644 --- a/.env.example +++ b/.env.example @@ -89,6 +89,15 @@ # AGENTMEMORY_SECRET=your-secret-here +# Structured-lesson authorization is classify-only by default for compatibility. +# To enforce durable-scope and sensitivity access, configure a server-side +# caller policy and give each client a unique high-entropy raw token. The policy +# stores only SHA-256 token digests; never commit raw client tokens. +# AGENTMEMORY_LESSON_ACCESS_MODE=enforce +# AGENTMEMORY_LESSON_CALLER_POLICY_FILE=/etc/agentmemory/lesson-callers.json +# AGENT_ID=codex +# AGENTMEMORY_CALLER_TOKEN=unique-client-token + # ----------------------------------------------------------------------------- # 4. Search tuning # ----------------------------------------------------------------------------- diff --git a/README.md b/README.md index 946a655314..011702c8c2 100644 --- a/README.md +++ b/README.md @@ -650,12 +650,14 @@ The agentmemory entry is the **same MCP server block** across every host that us "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL}", - "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}" + "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}", + "AGENT_ID": "${AGENT_ID}", + "AGENTMEMORY_CALLER_TOKEN": "${AGENTMEMORY_CALLER_TOKEN}" } } ``` -**Merge this entry into the existing `mcpServers` object** in the host's config file — don't replace the file. If the file already has other servers, add `agentmemory` next to them as another key inside `mcpServers`. If `mcpServers` is missing entirely, paste the block inside `{ "mcpServers": { ... } }`. The `${VAR}` placeholders inherit `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` from the shell at MCP-server launch — unset vars pass empty strings and the shim falls back to `http://localhost:3111`. One wired entry covers both local and remote (k8s / reverse-proxied) deployments. +**Merge this entry into the existing `mcpServers` object** in the host's config file — don't replace the file. If the file already has other servers, add `agentmemory` next to them as another key inside `mcpServers`. If `mcpServers` is missing entirely, paste the block inside `{ "mcpServers": { ... } }`. The `${VAR}` placeholders inherit the endpoint, API secret, caller ID, and caller token from the shell at MCP-server launch — unset vars pass empty strings and the shim falls back to `http://localhost:3111`. One wired entry covers both local and remote (k8s / reverse-proxied) deployments. | Agent | Config file | Notes | |---|---|---| @@ -1473,6 +1475,10 @@ Create `~/.agentmemory/.env`: # Auth # AGENTMEMORY_SECRET=your-secret +# AGENTMEMORY_LESSON_ACCESS_MODE=classify # classify (default) | enforce +# AGENTMEMORY_LESSON_CALLER_POLICY_FILE=/etc/agentmemory/lesson-callers.json +# AGENT_ID=codex +# AGENTMEMORY_CALLER_TOKEN=unique-client-token # Ports (defaults: 3111 API, 3113 viewer) # III_REST_PORT=3111 @@ -1576,17 +1582,36 @@ Authoritative lesson enumeration and normalization fail closed for import, portable export, and reflection; a read failure cannot become an empty lesson set that permits tombstone restoration or positive synthesis. -`scopeId`, global `humanApproval.approvedBy`, and correction `actor` values are -caller-supplied classification, lineage, and audit-attribution metadata. They -are not authenticated identities or an authorization boundary in PR1. -Server-resolved caller identity, approval authority, and durable-scope access -enforcement remain PR2 work. - -Scope and sensitivity enforcement, automatic contradiction discovery, and -hybrid/vector lesson retrieval are intentionally deferred to PR2. Until then, -sensitivity metadata is classification, not an access-control boundary. See +Lesson authorization has two explicit modes. `classify` is the default and +preserves the PR1 behavior. `enforce` resolves a caller from a per-client token +and server-side SHA-256 token-digest policy, then applies exact durable-scope +grants and the sensitivity order +`public < internal < confidential < restricted`. Write grants imply read; +global is not a wildcard; legacy implicit-worktree rows require the +`lesson:legacy-worktree` capability. + +In enforce mode, REST and MCP arguments cannot self-assert identity. The server +stamps correction actors plus global `humanApproval.approvedBy` and +`humanApproval.approvedAt`; only an authenticated human with +`lesson:approve-global` may approve global scope. +Portable/Obsidian exports require `lesson:export`, imports require +`lesson:import`, and unauthorized lessons are removed before list, recall, +context, smart-search, reflection, and export counts are computed. + +Set `AGENTMEMORY_LESSON_ACCESS_MODE=enforce` and +`AGENTMEMORY_LESSON_CALLER_POLICY_FILE=/absolute/path/lesson-callers.json` on +the server. Set a unique high-entropy `AGENTMEMORY_CALLER_TOKEN` and matching +`AGENT_ID` on each client. Keep raw tokens out of the policy and source control; +the policy contains only `tokenSha256`. Missing/invalid policy or credentials +fail closed after enforcement is enabled. Internal scheduled functions use an +explicit service context; that service cannot approve global lessons. + +Automatic contradiction discovery and hybrid/vector lesson retrieval remain +separate follow-up work. See [Causal Lesson Schema v1](docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md) -for the complete compatibility and fingerprint contract. +for the compatibility/fingerprint contract and +[Causal Lesson Access v2](docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md) +for the authorization and rollout contract. --- diff --git a/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md b/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md index 30ccd53c54..17771fe5cc 100644 --- a/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md +++ b/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md @@ -176,11 +176,11 @@ requires a separate durable `scope.scopeId`; global scope rejects `scopeId`. Legacy prose lessons retain the fail-closed implicit worktree scope for compatibility. -`scopeId`, `humanApproval.approvedBy`, and correction `actor` are -caller-supplied metadata in PR1. They express classification, lineage, and -audit attribution, but they are not authenticated identities and do not grant -authorization. Server-resolved caller identity, approval authority, and -durable-scope access enforcement are deferred to PR2. +In PR1, `scopeId`, `humanApproval.approvedBy`, and correction `actor` were +caller-supplied metadata only. The companion +[Causal Lesson Access v2](2026-08-03-causal-lesson-access-v2.md) defines the +opt-in server-resolved identity, approval authority, and durable-scope access +enforcement added in PR2. Global scope requires: @@ -204,10 +204,10 @@ are rejected. Sensitivity is `public`, `internal`, `confidential`, or `restricted`, with a fail-closed default of `restricted`. -PR1 records and returns scope/sensitivity metadata but deliberately preserves -the existing project-based visibility behavior. Retrieval enforcement belongs -to PR2. Until that lands, callers must not treat `sensitivity` as an enforced -access-control boundary. +PR1 records and returns scope/sensitivity metadata while preserving the +existing visibility behavior. Access v2 keeps that behavior as explicit +`classify` mode and adds opt-in `enforce` mode; callers must not treat +`sensitivity` as an access-control boundary unless enforcement is active. ## Confidence, reinforcement, staleness, and contradiction diff --git a/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md b/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md new file mode 100644 index 0000000000..8b63835ba4 --- /dev/null +++ b/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md @@ -0,0 +1,122 @@ +# Causal Lesson Access v2 + +Date: 2026-08-03 +Status: implemented behind an opt-in enforcement mode; deployment and activation are out of scope +Depends on: [Causal Lesson Schema v1](2026-08-02-causal-lesson-schema-v1.md) +Out of scope: hybrid/vector retrieval, automatic contradiction discovery, deployment, token provisioning, and policy activation + +## Objective + +Make lesson scope and sensitivity an enforceable server boundary without +breaking existing installations. HTTP and MCP clients authenticate with a +unique raw token; the server resolves the principal from a policy containing +only token digests. Tool arguments and request bodies cannot grant access or +self-assert an actor. + +## Modes + +- `classify` is the default. It preserves PR1 read/write behavior while keeping + scope and sensitivity metadata visible. +- `enforce` requires a readable, valid caller policy and matching client token + for every boundary operation that reads or writes lessons. Missing policy + returns 503; missing or invalid credentials return 401. + +The mode is selected with `AGENTMEMORY_LESSON_ACCESS_MODE`. The policy path is +selected with `AGENTMEMORY_LESSON_CALLER_POLICY_FILE`. + +## Caller policy + +```json +{ + "version": 1, + "principals": [ + { + "principalId": "codex", + "principalKind": "agent", + "tokenSha256": "64-lowercase-hex-characters", + "clearance": "confidential", + "scopes": [ + { + "ring": "repo", + "scopeId": "repo:https://github.com/example/project", + "access": "write" + } + ], + "capabilities": ["lesson:export"] + } + ] +} +``` + +Principal IDs and token digests must be unique. Non-global grants require an +exact `scopeId`; global grants omit it. A write grant implies read. Global is +not a wildcard for other rings. + +Supported capabilities are: + +- `lesson:all-scopes` +- `lesson:approve-global` +- `lesson:export` +- `lesson:import` +- `lesson:legacy-worktree` + +The sensitivity order is +`public < internal < confidential < restricted`. Access requires both adequate +clearance and a matching scope grant unless `lesson:all-scopes` is present. +Legacy rows normalized to an implicit worktree scope additionally require +`lesson:legacy-worktree`. + +## Boundary contract + +Clients send: + +- `X-AgentMemory-Caller-Token`: the raw per-client token +- `X-AgentMemory-Agent-Id`: the claimed principal ID, when known + +The token is matched to `tokenSha256` with a timing-safe digest comparison. If +the optional claimed ID is present it must match the policy principal. The MCP +shim, streamable HTTP MCP bridge, bundled hooks, Pi, OpenCode, and OpenClaw +integrations forward these headers from `AGENTMEMORY_CALLER_TOKEN` and +`AGENT_ID`. + +Request bodies and MCP arguments are explicitly whitelisted. A supplied +`accessContext` is never forwarded by a public boundary. Direct iii function +calls must pass either a resolved context or the explicit service context. +Enforced contexts carry a process-local HMAC proof; unsigned or forged +classification/enforcement contexts normalize to an unresolved, no-scope +principal. + +## Decision rules + +- Save, strengthen, retract, and supersede require read/write authority for the + affected durable scope and adequate sensitivity clearance. +- Recall, list, injected context, smart search, reflection, and exports filter + unauthorized lessons before totals, ranking, or provider prompts. +- Global saves require an authenticated `human` principal with + `lesson:approve-global`; the server stamps `humanApproval.approvedBy` and + `humanApproval.approvedAt`. +- In enforce mode correction actors are server-stamped. +- Portable and Obsidian lesson exports require `lesson:export`. +- Imports require `lesson:import`, validate every incoming lesson before any + write, and require authority for overwritten or replace-deleted lessons. +- The internal service context can run scheduled maintenance across scopes but + cannot approve global publication. + +## Rollout + +1. Keep `classify` active while inventorying every client. +2. Generate one high-entropy raw token per client and store it only in that + client's secret environment. +3. Store only each token's SHA-256 digest in a root/operator-controlled policy + file. Restrict policy-file permissions and do not commit it. +4. Configure `AGENT_ID` and `AGENTMEMORY_CALLER_TOKEN` for every REST/MCP + client. +5. Validate read, write, correction, export, import, context, and scheduled + maintenance behavior in a non-live instance. +6. Switch the server to `enforce`, restart it in a separately authorized + deployment step, and verify 401/403/503 diagnostics plus authorized flows. + +Rollback is configuration-only: return the server to `classify` and restart. +No lesson migration is required. Raw token rotation is performed by updating +the client secret and its policy digest together, then restarting/reloading the +affected processes. diff --git a/integrations/openclaw/plugin.mjs b/integrations/openclaw/plugin.mjs index 332189d7e3..48b020c062 100644 --- a/integrations/openclaw/plugin.mjs +++ b/integrations/openclaw/plugin.mjs @@ -110,6 +110,8 @@ function createClient(cfg, api) { const timeoutMs = Number(cfg.timeout_ms || DEFAULT_TIMEOUT_MS); const fallbackOnError = cfg.fallback_on_error !== false; const secret = process.env.AGENTMEMORY_SECRET; + const agentId = process.env.AGENT_ID; + const callerToken = process.env.AGENTMEMORY_CALLER_TOKEN; const guardPlaintextBearerAuth = createPlaintextBearerAuthGuard( (message) => api.logger.warn?.(message), ); @@ -121,6 +123,10 @@ function createClient(cfg, api) { guardPlaintextBearerAuth(baseUrl, secret); const headers = { "Content-Type": "application/json" }; if (secret) headers.Authorization = `Bearer ${secret}`; + if (agentId) headers["X-AgentMemory-Agent-Id"] = agentId; + if (callerToken) { + headers["X-AgentMemory-Caller-Token"] = callerToken; + } try { const res = await fetch(`${baseUrl}${path}`, { method: "POST", diff --git a/integrations/pi/index.ts b/integrations/pi/index.ts index 9c6cfc7024..24069b921e 100644 --- a/integrations/pi/index.ts +++ b/integrations/pi/index.ts @@ -95,9 +95,13 @@ async function callAgentMemory( const url = `${baseUrl}/agentmemory/${pathname.replace(/^\/+/, "")}`; const headers: Record = {}; const secret = process.env.AGENTMEMORY_SECRET; + const agentId = process.env.AGENT_ID; + const callerToken = process.env.AGENTMEMORY_CALLER_TOKEN; guardPlaintextBearerAuth(baseUrl, secret); if (options?.body !== undefined) headers["Content-Type"] = "application/json"; if (secret) headers.Authorization = `Bearer ${secret}`; + if (agentId) headers["X-AgentMemory-Agent-Id"] = agentId; + if (callerToken) headers["X-AgentMemory-Caller-Token"] = callerToken; try { const response = await fetch(url, { diff --git a/plugin/.mcp.copilot.json b/plugin/.mcp.copilot.json index 827330add9..d0c1b0c713 100644 --- a/plugin/.mcp.copilot.json +++ b/plugin/.mcp.copilot.json @@ -7,6 +7,8 @@ "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}", "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET:-}", + "AGENT_ID": "${AGENT_ID:-}", + "AGENTMEMORY_CALLER_TOKEN": "${AGENTMEMORY_CALLER_TOKEN:-}", "AGENTMEMORY_TOOLS": "${AGENTMEMORY_TOOLS:-all}" }, "tools": ["*"] diff --git a/plugin/.mcp.json b/plugin/.mcp.json index 37f7754fff..669a1762b9 100644 --- a/plugin/.mcp.json +++ b/plugin/.mcp.json @@ -6,6 +6,8 @@ "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}", "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET:-}", + "AGENT_ID": "${AGENT_ID:-}", + "AGENTMEMORY_CALLER_TOKEN": "${AGENTMEMORY_CALLER_TOKEN:-}", "AGENTMEMORY_TOOLS": "${AGENTMEMORY_TOOLS:-all}" } } diff --git a/plugin/opencode/agentmemory-capture.ts b/plugin/opencode/agentmemory-capture.ts index 056d53d38d..df28537763 100644 --- a/plugin/opencode/agentmemory-capture.ts +++ b/plugin/opencode/agentmemory-capture.ts @@ -7,10 +7,16 @@ const MAX_STASHED_FILES = 20; const DEBUG = process.env.OPENCODE_AGENTMEMORY_DEBUG === "1"; const SECRET = process.env.AGENTMEMORY_SECRET || ""; +const AGENT_ID = process.env.AGENT_ID || ""; +const CALLER_TOKEN = process.env.AGENTMEMORY_CALLER_TOKEN || ""; function authHeaders(): Record { const headers: Record = { "Content-Type": "application/json" }; if (SECRET) headers["Authorization"] = `Bearer ${SECRET}`; + if (AGENT_ID) headers["X-AgentMemory-Agent-Id"] = AGENT_ID; + if (CALLER_TOKEN) { + headers["X-AgentMemory-Caller-Token"] = CALLER_TOKEN; + } return headers; } diff --git a/plugin/scripts/pre-compact.mjs b/plugin/scripts/pre-compact.mjs index c3be22d835..bde2fbe9fe 100755 --- a/plugin/scripts/pre-compact.mjs +++ b/plugin/scripts/pre-compact.mjs @@ -110,9 +110,13 @@ function isSdkChildContext(payload) { } const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; +const AGENT_ID = process.env["AGENT_ID"] || ""; +const CALLER_TOKEN = process.env["AGENTMEMORY_CALLER_TOKEN"] || ""; function authHeaders() { const h = { "Content-Type": "application/json" }; if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; + if (AGENT_ID) h["X-AgentMemory-Agent-Id"] = AGENT_ID; + if (CALLER_TOKEN) h["X-AgentMemory-Caller-Token"] = CALLER_TOKEN; return h; } async function main() { diff --git a/plugin/scripts/session-start.mjs b/plugin/scripts/session-start.mjs index 5875c3c576..b6dd890682 100755 --- a/plugin/scripts/session-start.mjs +++ b/plugin/scripts/session-start.mjs @@ -108,11 +108,15 @@ function isSdkChildContext(payload) { const INJECT_CONTEXT = process.env["AGENTMEMORY_INJECT_CONTEXT"] === "true"; const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; +const AGENT_ID = process.env["AGENT_ID"] || ""; +const CALLER_TOKEN = process.env["AGENTMEMORY_CALLER_TOKEN"] || ""; const INJECT_TIMEOUT_MS = 1500; const REGISTER_TIMEOUT_MS = 800; function authHeaders() { const h = { "Content-Type": "application/json" }; if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; + if (AGENT_ID) h["X-AgentMemory-Agent-Id"] = AGENT_ID; + if (CALLER_TOKEN) h["X-AgentMemory-Caller-Token"] = CALLER_TOKEN; return h; } async function main() { diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md index df803b0d85..af028664f6 100644 --- a/plugin/skills/agentmemory-config/REFERENCE.md +++ b/plugin/skills/agentmemory-config/REFERENCE.md @@ -3,12 +3,13 @@ Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded. -Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 52 recognized variables: +Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 55 recognized variables: - `AGENTMEMORY_AGENT_SCOPE` - `AGENTMEMORY_ALLOW_AGENT_SDK` - `AGENTMEMORY_AUTO_COMPRESS` - `AGENTMEMORY_BUILD_ID` +- `AGENTMEMORY_CALLER_TOKEN` - `AGENTMEMORY_CAPTURE_PROMPTS` - `AGENTMEMORY_COMMIT_SHA` - `AGENTMEMORY_COPILOT_MCP_BLOCK` @@ -27,6 +28,8 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e - `AGENTMEMORY_IMAGE_EMBEDDINGS` - `AGENTMEMORY_IMAGE_STORE_MAX_BYTES` - `AGENTMEMORY_INJECT_CONTEXT` +- `AGENTMEMORY_LESSON_ACCESS_MODE` +- `AGENTMEMORY_LESSON_CALLER_POLICY_FILE` - `AGENTMEMORY_LLM_OK` - `AGENTMEMORY_LLM_TIMEOUT_MS` - `AGENTMEMORY_MAX_PROMPT_CAPTURE_CHARS` diff --git a/src/cli.ts b/src/cli.ts index 6cea269a33..fdf8a2cd39 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -2037,6 +2037,21 @@ function buildDemoSessions(): DemoSession[] { ]; } +function cliJsonHeaders(): Record { + const headers: Record = { + "Content-Type": "application/json", + }; + const secret = process.env["AGENTMEMORY_SECRET"]; + const agentId = process.env["AGENT_ID"]; + const callerToken = process.env["AGENTMEMORY_CALLER_TOKEN"]; + if (secret) headers["Authorization"] = `Bearer ${secret}`; + if (agentId) headers["X-AgentMemory-Agent-Id"] = agentId; + if (callerToken) { + headers["X-AgentMemory-Caller-Token"] = callerToken; + } + return headers; +} + async function postJson( url: string, body: unknown, @@ -2045,7 +2060,7 @@ async function postJson( try { const res = await fetch(url, { method: "POST", - headers: { "Content-Type": "application/json" }, + headers: cliJsonHeaders(), body: JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs), }); @@ -2063,7 +2078,7 @@ async function postJsonStrict( ): Promise { const res = await fetch(url, { method: "POST", - headers: { "Content-Type": "application/json" }, + headers: cliJsonHeaders(), body: JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs), }); @@ -2105,7 +2120,7 @@ async function seedDemoSession( try { const res = await fetch(url, { method: "POST", - headers: { "Content-Type": "application/json" }, + headers: cliJsonHeaders(), body: JSON.stringify(payload), signal: AbortSignal.timeout(5000), }); diff --git a/src/cli/connect/util.ts b/src/cli/connect/util.ts index 580cd4ee72..96d9f053cb 100644 --- a/src/cli/connect/util.ts +++ b/src/cli/connect/util.ts @@ -11,7 +11,7 @@ import { homedir } from "node:os"; import * as p from "@clack/prompts"; // Env values use ${VAR:-default} expansion so the wired MCP entry -// inherits AGENTMEMORY_URL / AGENTMEMORY_SECRET / AGENTMEMORY_TOOLS +// inherits endpoint, caller identity, auth, and tool-selection settings // from the user's shell, but never fails parse when the var is unset // (#510). Earlier `${VAR}` form caused Claude Code to silently drop the // server when no shell-level export existed — per the Claude Code MCP @@ -28,6 +28,8 @@ export const AGENTMEMORY_MCP_BLOCK = { env: { AGENTMEMORY_URL: "${AGENTMEMORY_URL:-http://localhost:3111}", AGENTMEMORY_SECRET: "${AGENTMEMORY_SECRET:-}", + AGENT_ID: "${AGENT_ID:-}", + AGENTMEMORY_CALLER_TOKEN: "${AGENTMEMORY_CALLER_TOKEN:-}", AGENTMEMORY_TOOLS: "${AGENTMEMORY_TOOLS:-all}", }, }; @@ -49,6 +51,8 @@ export const AGENTMEMORY_COPILOT_MCP_BLOCK = { env: { AGENTMEMORY_URL: "${AGENTMEMORY_URL:-http://localhost:3111}", AGENTMEMORY_SECRET: "${AGENTMEMORY_SECRET:-}", + AGENT_ID: "${AGENT_ID:-}", + AGENTMEMORY_CALLER_TOKEN: "${AGENTMEMORY_CALLER_TOKEN:-}", AGENTMEMORY_TOOLS: "${AGENTMEMORY_TOOLS:-all}", }, tools: ["*"], diff --git a/src/functions/consolidation-pipeline.ts b/src/functions/consolidation-pipeline.ts index e51ab97c86..91af2dd415 100644 --- a/src/functions/consolidation-pipeline.ts +++ b/src/functions/consolidation-pipeline.ts @@ -17,6 +17,7 @@ import { import { recordAudit } from "./audit.js"; import { getConsolidationDecayDays, isConsolidationEnabled } from "../config.js"; import { logger } from "../logger.js"; +import { systemLessonAccessContext } from "./lesson-access.js"; function applyDecay( items: Array<{ @@ -138,6 +139,7 @@ export function registerConsolidationPipelineFunction( const reflectResult = await sdk.trigger({ function_id: "mem::reflect", payload: { maxClusters: 10, project: data?.project, + accessContext: systemLessonAccessContext(), } }); results.reflect = reflectResult; } catch (err) { @@ -249,7 +251,10 @@ export function registerConsolidationPipelineFunction( if (process.env["OBSIDIAN_AUTO_EXPORT"] === "true") { try { - await sdk.trigger({ function_id: "mem::obsidian-export", payload: {} }); + await sdk.trigger({ + function_id: "mem::obsidian-export", + payload: { accessContext: systemLessonAccessContext() }, + }); results.obsidianExport = { success: true }; } catch (err) { const msg = err instanceof Error ? err.message : String(err); diff --git a/src/functions/context.ts b/src/functions/context.ts index 1c1ab5825f..aee2c7fd55 100644 --- a/src/functions/context.ts +++ b/src/functions/context.ts @@ -21,6 +21,11 @@ import { isLessonRecallable, toLessonReadModel, } from "./lesson-model.js"; +import { + canReadLesson, + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; function estimateTokens(text: string): number { return Math.ceil(text.length / 3); @@ -40,9 +45,15 @@ export function registerContextFunction( tokenBudget: number, ): void { sdk.registerFunction("mem::context", - async (data: { sessionId: string; project: string; budget?: number }) => { + async (data: { + sessionId: string; + project: string; + budget?: number; + accessContext?: LessonAccessContext; + }) => { const budget = data.budget || tokenBudget; const blocks: ContextBlock[] = []; + const accessContext = lessonAccessContextFromPayload(data.accessContext); const [pinnedSlots, profile, lessons] = await Promise.all([ isSlotsEnabled() @@ -110,6 +121,7 @@ export function registerContextFunction( .filter( (lesson) => isLessonRecallable(lesson) && + canReadLesson(lesson, accessContext) && (!lesson.project || lesson.project === data.project), ) .map((lesson) => toLessonReadModel(lesson)) diff --git a/src/functions/crystallize.ts b/src/functions/crystallize.ts index 98598c13fc..6beba5ee1d 100644 --- a/src/functions/crystallize.ts +++ b/src/functions/crystallize.ts @@ -3,6 +3,7 @@ import type { StateKV } from "../state/kv.js"; import { KV, generateId } from "../state/schema.js"; import type { Action, ActionEdge, Crystal, MemoryProvider } from "../types.js"; import { persistAction } from "./action-store.js"; +import { systemLessonAccessContext } from "./lesson-access.js"; interface CrystalDigest { narrative: string; @@ -85,6 +86,7 @@ export function registerCrystallizeFunction( tags: [], source: "crystal", sourceIds: [crystal.id], + accessContext: systemLessonAccessContext(), }, }) .catch(() => {}), diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index bac5a9a1a8..469ad6859c 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -49,6 +49,13 @@ import { sameLessonScope, } from "./lesson-model.js"; import { withLessonMutationLock } from "./lesson-locks.js"; +import { + canReadLesson, + canUseLessonCapability, + canWriteLessonScope, + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; interface ImportedLessonCandidate { lesson: Lesson; @@ -66,7 +73,21 @@ const MAX_LESSON_STATE_DIAGNOSTIC_DETAIL_LENGTH = 256; export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::export", - async (data?: { maxSessions?: number; offset?: number }) => { + async (data?: { + maxSessions?: number; + offset?: number; + accessContext?: LessonAccessContext; + }) => { + const accessContext = lessonAccessContextFromPayload( + data?.accessContext, + ); + if (!canUseLessonCapability(accessContext, "lesson:export")) { + return { + success: false, + code: "access_denied", + error: "lesson access denied for export", + }; + } const rawMax = Number(data?.maxSessions); const maxSessions = Number.isFinite(rawMax) && rawMax > 0 ? Math.min(Math.floor(rawMax), 1000) : undefined; const rawOffset = Number(data?.offset); @@ -142,6 +163,9 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { kv.list(KV.checkpoints).catch(() => []), kv.list(KV.accessLog).catch(() => []), ]); + const authorizedLessons = lessons + .filter((lesson) => canReadLesson(lesson, accessContext)) + .map((lesson) => normalizeLesson(lesson)); const exportData: ExportData = { version: VERSION, @@ -175,8 +199,8 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { crystals: crystals.length > 0 ? crystals : undefined, facets: facets.length > 0 ? facets : undefined, lessons: - lessons.length > 0 - ? lessons.map((lesson) => normalizeLesson(lesson)) + authorizedLessons.length > 0 + ? authorizedLessons : undefined, insights: insights.length > 0 ? insights : undefined, routines: routines.length > 0 ? routines : undefined, @@ -199,6 +223,7 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { 0, ); logger.info("Export complete", { + actor: accessContext.principalId, sessions: paginatedSessions.length, totalSessions: allSessions.length, observations: totalObs, @@ -214,7 +239,18 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { async (data: { exportData: ExportData; strategy?: "merge" | "replace" | "skip"; + accessContext?: LessonAccessContext; }) => { + const accessContext = lessonAccessContextFromPayload( + data?.accessContext, + ); + if (!canUseLessonCapability(accessContext, "lesson:import")) { + return { + success: false, + code: "access_denied", + error: "lesson access denied for import", + }; + } if ( !data?.exportData || typeof data.exportData !== "object" || @@ -541,12 +577,17 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { const lessonImport = await withLessonMutationLock(() => applyImportedLessonBatch( kv, - normalizedImportedLessons, - strategy, - ), + normalizedImportedLessons, + strategy, + accessContext, + ), ); if (!lessonImport.success) { - return { success: false, error: lessonImport.error }; + return { + success: false, + error: lessonImport.error, + ...(lessonImport.code ? { code: lessonImport.code } : {}), + }; } stats.lessons = lessonImport.written; stats.skipped += lessonImport.skipped; @@ -925,6 +966,7 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { logger.info("Import complete", { strategy, ...stats }); await recordAudit(kv, "import", "mem::import", [], { + actor: accessContext.principalId, strategy, stats, }); @@ -937,9 +979,10 @@ async function applyImportedLessonBatch( kv: StateKV, imported: ImportedLessonCandidate[], strategy: "merge" | "replace" | "skip", + accessContext: LessonAccessContext, ): Promise< | { success: true; written: number; skipped: number } - | { success: false; error: string } + | { success: false; error: string; code?: "access_denied" } > { let existingRows: Lesson[]; try { @@ -983,6 +1026,57 @@ async function applyImportedLessonBatch( } } + for (const candidate of imported) { + const normalized = normalizeLesson(candidate.lesson); + if ( + !canWriteLessonScope( + normalized.scope, + normalized.sensitivity, + accessContext, + ) + ) { + return { + success: false, + code: "access_denied", + error: "Lesson import access denied for incoming durable scope", + }; + } + const current = existing.get(normalized.id); + if ( + current && + (!canReadLesson(current, accessContext) || + !canWriteLessonScope( + current.scope!, + current.sensitivity!, + accessContext, + )) + ) { + return { + success: false, + code: "access_denied", + error: "Lesson import access denied for existing durable scope", + }; + } + } + if (strategy === "replace") { + for (const current of existing.values()) { + if ( + !canReadLesson(current, accessContext) || + !canWriteLessonScope( + current.scope!, + current.sensitivity!, + accessContext, + ) + ) { + return { + success: false, + code: "access_denied", + error: "Lesson import access denied for replace deletion", + }; + } + } + } + const incomingAliases = new Map(); for (const candidate of imported) { for (const alias of [ @@ -1107,7 +1201,7 @@ async function applyImportedLessonBatch( "import", "mem::import:lessons", affectedIds, - auditDetails, + { ...auditDetails, actor: accessContext.principalId }, ); } } catch (error) { @@ -1125,6 +1219,7 @@ async function applyImportedLessonBatch( affectedIds, { ...auditDetails, + actor: accessContext.principalId, applyError: error instanceof Error ? error.message : String(error), rollback, }, diff --git a/src/functions/lesson-access.ts b/src/functions/lesson-access.ts new file mode 100644 index 0000000000..a445ec7a3d --- /dev/null +++ b/src/functions/lesson-access.ts @@ -0,0 +1,639 @@ +import { + createHash, + createHmac, + randomBytes, + timingSafeEqual, +} from "node:crypto"; +import { readFileSync } from "node:fs"; +import { getAgentId, getEnvVar } from "../config.js"; +import type { + Lesson, + LessonScope, + LessonScopeRing, + LessonSensitivity, +} from "../types.js"; +import { normalizeLesson } from "./lesson-model.js"; + +const MAX_CALLER_TOKEN_LENGTH = 4096; +const MAX_POLICY_FILE_BYTES = 256 * 1024; +const TOKEN_SHA256_PATTERN = /^[a-f0-9]{64}$/; +const ACCESS_CONTEXT_PROOF_PATTERN = /^[a-f0-9]{64}$/; +const ACCESS_CONTEXT_SECRET = randomBytes(32); +const SENSITIVITY_RANK: Record = { + public: 0, + internal: 1, + confidential: 2, + restricted: 3, +}; + +export type LessonAccessMode = "classify" | "enforce"; +export type LessonPrincipalKind = "agent" | "human" | "service"; +export type LessonScopeAccess = "read" | "write"; +export type LessonAccessCapability = + | "lesson:all-scopes" + | "lesson:approve-global" + | "lesson:export" + | "lesson:import" + | "lesson:legacy-worktree"; + +export interface LessonScopeGrant { + ring: LessonScopeRing; + scopeId?: string; + access: LessonScopeAccess; +} + +export interface LessonAccessContext { + schemaVersion: 1; + mode: LessonAccessMode; + principalId: string; + principalKind: LessonPrincipalKind; + clearance: LessonSensitivity; + scopes: LessonScopeGrant[]; + capabilities: LessonAccessCapability[]; + resolvedBy: "server-policy" | "legacy-classification" | "system"; + authorizationProof?: string; +} + +export interface LessonCallerPolicyPrincipal { + principalId: string; + principalKind: LessonPrincipalKind; + tokenSha256: string; + clearance: LessonSensitivity; + scopes: LessonScopeGrant[]; + capabilities?: LessonAccessCapability[]; +} + +export interface LessonCallerPolicy { + version: 1; + principals: LessonCallerPolicyPrincipal[]; +} + +export type LessonBoundaryAccessResult = + | { success: true; context: LessonAccessContext } + | { + success: false; + statusCode: 401 | 503; + error: string; + code: "caller_authentication_failed" | "caller_policy_unavailable"; + }; + +export interface ResolveLessonBoundaryAccessOptions { + mode?: LessonAccessMode; + policy?: LessonCallerPolicy; + policyPath?: string; + fallbackAgentId?: string; +} + +function nonEmptyString( + value: unknown, + field: string, + maxLength = 4096, +): string { + if (typeof value !== "string" || !value.trim()) { + throw new Error(`${field} must be a non-empty string`); + } + const normalized = value.trim(); + if (normalized.length > maxLength) { + throw new Error(`${field} exceeds ${maxLength} characters`); + } + return normalized; +} + +function normalizeMode(value: unknown): LessonAccessMode { + return value === "enforce" ? "enforce" : "classify"; +} + +export function getLessonAccessMode(): LessonAccessMode { + return normalizeMode(getEnvVar("AGENTMEMORY_LESSON_ACCESS_MODE")); +} + +function normalizePrincipalKind(value: unknown): LessonPrincipalKind { + if (value === "agent" || value === "human" || value === "service") { + return value; + } + throw new Error("principalKind must be agent, human, or service"); +} + +function normalizeSensitivity(value: unknown): LessonSensitivity { + if ( + value === "public" || + value === "internal" || + value === "confidential" || + value === "restricted" + ) { + return value; + } + throw new Error( + "clearance must be public, internal, confidential, or restricted", + ); +} + +function normalizeCapability(value: unknown): LessonAccessCapability { + if ( + value === "lesson:all-scopes" || + value === "lesson:approve-global" || + value === "lesson:export" || + value === "lesson:import" || + value === "lesson:legacy-worktree" + ) { + return value; + } + throw new Error(`unsupported lesson capability: ${String(value)}`); +} + +function normalizeScopeGrant(value: unknown): LessonScopeGrant { + if (!value || typeof value !== "object" || Array.isArray(value)) { + throw new Error("scope grant must be an object"); + } + const record = value as Record; + const ring = record.ring; + if ( + ring !== "worktree" && + ring !== "repo" && + ring !== "initiative" && + ring !== "domain" && + ring !== "global" + ) { + throw new Error("scope grant ring is invalid"); + } + const access = record.access; + if (access !== "read" && access !== "write") { + throw new Error("scope grant access must be read or write"); + } + const scopeId = + record.scopeId === undefined + ? undefined + : nonEmptyString(record.scopeId, "scope grant scopeId"); + if (ring === "global" && scopeId !== undefined) { + throw new Error("global scope grants must omit scopeId"); + } + if (ring !== "global" && scopeId === undefined) { + throw new Error("non-global scope grants require scopeId"); + } + return { + ring, + ...(scopeId !== undefined ? { scopeId } : {}), + access, + }; +} + +export function parseLessonCallerPolicy(value: unknown): LessonCallerPolicy { + if (!value || typeof value !== "object" || Array.isArray(value)) { + throw new Error("lesson caller policy must be an object"); + } + const record = value as Record; + if (record.version !== 1) { + throw new Error("lesson caller policy version must be 1"); + } + if (!Array.isArray(record.principals) || record.principals.length === 0) { + throw new Error("lesson caller policy principals must be a non-empty array"); + } + const seenPrincipals = new Set(); + const seenTokens = new Set(); + const principals = record.principals.map((raw, index) => { + if (!raw || typeof raw !== "object" || Array.isArray(raw)) { + throw new Error(`principals[${index}] must be an object`); + } + const principal = raw as Record; + const principalId = nonEmptyString( + principal.principalId, + `principals[${index}].principalId`, + 128, + ); + if (seenPrincipals.has(principalId)) { + throw new Error(`duplicate lesson principalId: ${principalId}`); + } + seenPrincipals.add(principalId); + const tokenSha256 = nonEmptyString( + principal.tokenSha256, + `principals[${index}].tokenSha256`, + 64, + ).toLowerCase(); + if (!TOKEN_SHA256_PATTERN.test(tokenSha256)) { + throw new Error( + `principals[${index}].tokenSha256 must be 64 lowercase hex characters`, + ); + } + if (seenTokens.has(tokenSha256)) { + throw new Error("duplicate lesson caller token digest"); + } + seenTokens.add(tokenSha256); + if (!Array.isArray(principal.scopes)) { + throw new Error(`principals[${index}].scopes must be an array`); + } + const scopes = principal.scopes.map(normalizeScopeGrant); + const capabilities = Array.isArray(principal.capabilities) + ? [...new Set(principal.capabilities.map(normalizeCapability))] + : []; + return { + principalId, + principalKind: normalizePrincipalKind(principal.principalKind), + tokenSha256, + clearance: normalizeSensitivity(principal.clearance), + scopes, + capabilities, + }; + }); + return { version: 1, principals }; +} + +function loadPolicyFile(path: string): LessonCallerPolicy { + const raw = readFileSync(path); + if (raw.byteLength > MAX_POLICY_FILE_BYTES) { + throw new Error( + `lesson caller policy exceeds ${MAX_POLICY_FILE_BYTES} bytes`, + ); + } + return parseLessonCallerPolicy(JSON.parse(raw.toString("utf8"))); +} + +function headerValue( + headers: Record | undefined, + name: string, +): string | undefined { + if (!headers) return undefined; + const match = Object.entries(headers).find( + ([key]) => key.toLowerCase() === name, + )?.[1]; + const value = Array.isArray(match) ? match[0] : match; + return typeof value === "string" && value.trim() + ? value.trim() + : undefined; +} + +function classificationContext(agentId?: string): LessonAccessContext { + return { + schemaVersion: 1, + mode: "classify", + principalId: agentId?.trim() || "legacy-unresolved", + principalKind: "agent", + clearance: "restricted", + scopes: [], + capabilities: [], + resolvedBy: "legacy-classification", + }; +} + +function accessContextProof( + context: Omit, +): string { + return createHmac("sha256", ACCESS_CONTEXT_SECRET) + .update( + JSON.stringify({ + schemaVersion: context.schemaVersion, + mode: context.mode, + principalId: context.principalId, + principalKind: context.principalKind, + clearance: context.clearance, + scopes: context.scopes, + capabilities: context.capabilities, + resolvedBy: context.resolvedBy, + }), + "utf8", + ) + .digest("hex"); +} + +function sealAccessContext( + context: Omit, +): LessonAccessContext { + return { + ...context, + authorizationProof: accessContextProof(context), + }; +} + +function hasValidAccessContextProof(context: LessonAccessContext): boolean { + const proof = context.authorizationProof; + if ( + typeof proof !== "string" || + !ACCESS_CONTEXT_PROOF_PATTERN.test(proof) + ) { + return false; + } + const { authorizationProof: _ignored, ...unsigned } = context; + const expected = accessContextProof(unsigned); + return timingSafeEqual(Buffer.from(proof, "hex"), Buffer.from(expected, "hex")); +} + +function unresolvedEnforcedContext(): LessonAccessContext { + return { + schemaVersion: 1, + mode: "enforce", + principalId: "unresolved", + principalKind: "agent", + clearance: "public", + scopes: [], + capabilities: [], + resolvedBy: "server-policy", + }; +} + +export function systemLessonAccessContext(): LessonAccessContext { + return sealAccessContext({ + schemaVersion: 1, + mode: "enforce", + principalId: "agentmemory:system", + principalKind: "service", + clearance: "restricted", + scopes: [], + capabilities: [ + "lesson:all-scopes", + "lesson:export", + "lesson:import", + "lesson:legacy-worktree", + ], + resolvedBy: "system", + }); +} + +function tokenMatches(token: string, digest: string): boolean { + const actual = createHash("sha256").update(token, "utf8").digest(); + const expected = Buffer.from(digest, "hex"); + return actual.length === expected.length && timingSafeEqual(actual, expected); +} + +export function resolveLessonBoundaryAccess( + headers?: Record, + options: ResolveLessonBoundaryAccessOptions = {}, +): LessonBoundaryAccessResult { + const mode = options.mode ?? getLessonAccessMode(); + const claimedAgentId = headerValue(headers, "x-agentmemory-agent-id"); + if (mode === "classify") { + return { + success: true, + context: classificationContext( + claimedAgentId ?? options.fallbackAgentId ?? getAgentId(), + ), + }; + } + + let policy: LessonCallerPolicy; + try { + const policyPath = + options.policyPath ?? + getEnvVar("AGENTMEMORY_LESSON_CALLER_POLICY_FILE"); + policy = options.policy + ? parseLessonCallerPolicy(options.policy) + : policyPath + ? loadPolicyFile(policyPath) + : (() => { + throw new Error("lesson caller policy file is not configured"); + })(); + } catch { + return { + success: false, + statusCode: 503, + error: "lesson caller policy is unavailable", + code: "caller_policy_unavailable", + }; + } + + const token = headerValue(headers, "x-agentmemory-caller-token"); + if (!token || token.length > MAX_CALLER_TOKEN_LENGTH) { + return { + success: false, + statusCode: 401, + error: "lesson caller authentication failed", + code: "caller_authentication_failed", + }; + } + const principal = policy.principals.find((candidate) => + tokenMatches(token, candidate.tokenSha256), + ); + if (!principal || (claimedAgentId && claimedAgentId !== principal.principalId)) { + return { + success: false, + statusCode: 401, + error: "lesson caller authentication failed", + code: "caller_authentication_failed", + }; + } + return { + success: true, + context: sealAccessContext({ + schemaVersion: 1, + mode: "enforce", + principalId: principal.principalId, + principalKind: principal.principalKind, + clearance: principal.clearance, + scopes: principal.scopes, + capabilities: principal.capabilities ?? [], + resolvedBy: "server-policy", + }), + }; +} + +export function lessonAccessContextFromPayload( + value: unknown, +): LessonAccessContext { + if (!value || typeof value !== "object" || Array.isArray(value)) { + return getLessonAccessMode() === "enforce" + ? unresolvedEnforcedContext() + : classificationContext(getAgentId()); + } + const context = value as Partial; + if ( + context.schemaVersion !== 1 || + (context.mode !== "classify" && context.mode !== "enforce") || + typeof context.principalId !== "string" || + !context.principalId.trim() || + (context.principalKind !== "agent" && + context.principalKind !== "human" && + context.principalKind !== "service") || + !Array.isArray(context.scopes) || + !Array.isArray(context.capabilities) + ) { + return getLessonAccessMode() === "enforce" + ? unresolvedEnforcedContext() + : classificationContext(getAgentId()); + } + try { + const normalized: LessonAccessContext = { + schemaVersion: 1, + mode: context.mode, + principalId: context.principalId.trim(), + principalKind: context.principalKind, + clearance: normalizeSensitivity(context.clearance), + scopes: context.scopes.map(normalizeScopeGrant), + capabilities: context.capabilities.map(normalizeCapability), + resolvedBy: + context.resolvedBy === "server-policy" || + context.resolvedBy === "system" + ? context.resolvedBy + : "legacy-classification", + ...(typeof context.authorizationProof === "string" + ? { authorizationProof: context.authorizationProof } + : {}), + }; + if ( + normalized.mode === "enforce" && + !hasValidAccessContextProof(normalized) + ) { + return unresolvedEnforcedContext(); + } + if ( + getLessonAccessMode() === "enforce" && + normalized.mode !== "enforce" + ) { + return unresolvedEnforcedContext(); + } + return normalized; + } catch { + return getLessonAccessMode() === "enforce" + ? unresolvedEnforcedContext() + : classificationContext(getAgentId()); + } +} + +function hasCapability( + context: LessonAccessContext, + capability: LessonAccessCapability, +): boolean { + return context.capabilities.includes(capability); +} + +function scopeMatches( + grant: LessonScopeGrant, + scope: LessonScope, +): boolean { + if (grant.ring !== scope.ring) return false; + return scope.ring === "global" + ? grant.scopeId === undefined + : grant.scopeId === scope.scopeId; +} + +function scopeAllowed( + context: LessonAccessContext, + scope: LessonScope, + access: LessonScopeAccess, +): boolean { + if (hasCapability(context, "lesson:all-scopes")) return true; + if ( + scope.ring === "worktree" && + !scope.scopeId && + hasCapability(context, "lesson:legacy-worktree") + ) { + return true; + } + return context.scopes.some( + (grant) => + scopeMatches(grant, scope) && + (grant.access === "write" || access === "read"), + ); +} + +export function canReadLesson( + lesson: Lesson, + context: LessonAccessContext, +): boolean { + if (context.mode === "classify") return true; + const normalized = normalizeLesson(lesson); + return ( + SENSITIVITY_RANK[context.clearance] >= + SENSITIVITY_RANK[normalized.sensitivity] && + scopeAllowed(context, normalized.scope, "read") + ); +} + +export function canWriteLessonScope( + scope: LessonScope, + sensitivity: LessonSensitivity, + context: LessonAccessContext, +): boolean { + if (context.mode === "classify") return true; + return ( + SENSITIVITY_RANK[context.clearance] >= SENSITIVITY_RANK[sensitivity] && + scopeAllowed(context, scope, "write") + ); +} + +export function canUseLessonCapability( + context: LessonAccessContext, + capability: LessonAccessCapability, +): boolean { + return context.mode === "classify" || hasCapability(context, capability); +} + +export function canApproveGlobalLesson( + context: LessonAccessContext, +): boolean { + return ( + context.mode === "classify" || + (context.principalKind === "human" && + hasCapability(context, "lesson:approve-global")) + ); +} + +export type LessonWriteIdentityResult = + | { success: true; value: unknown } + | { success: false; code: "access_denied" | "invalid_request"; error: string }; + +export function bindResolvedLessonWriteIdentity( + value: unknown, + context: LessonAccessContext, +): LessonWriteIdentityResult { + if ( + context.mode !== "enforce" || + !value || + typeof value !== "object" || + Array.isArray(value) + ) { + return { success: true, value }; + } + + const prepared = { ...(value as Record) }; + delete prepared.accessContext; + if ( + !prepared.scope || + typeof prepared.scope !== "object" || + Array.isArray(prepared.scope) + ) { + return { success: true, value: prepared }; + } + + const scope = { ...(prepared.scope as Record) }; + if (scope.ring !== "global") { + prepared.scope = scope; + return { success: true, value: prepared }; + } + if (!canApproveGlobalLesson(context)) { + return { + success: false, + code: "access_denied", + error: "lesson access denied for global approval", + }; + } + if ( + !scope.humanApproval || + typeof scope.humanApproval !== "object" || + Array.isArray(scope.humanApproval) + ) { + return { + success: false, + code: "invalid_request", + error: + "global scope requires humanApproval.approvedAt and humanApproval.reason", + }; + } + + const approval = { + ...(scope.humanApproval as Record), + }; + if ( + approval.approvedBy !== undefined && + approval.approvedBy !== context.principalId + ) { + return { + success: false, + code: "invalid_request", + error: + "scope.humanApproval.approvedBy is server-resolved and must match the authenticated principal", + }; + } + approval.approvedBy = context.principalId; + approval.approvedAt = new Date().toISOString(); + scope.humanApproval = approval; + prepared.scope = scope; + return { success: true, value: prepared }; +} diff --git a/src/functions/lessons.ts b/src/functions/lessons.ts index 861ce0cc38..547ebe1962 100644 --- a/src/functions/lessons.ts +++ b/src/functions/lessons.ts @@ -3,6 +3,13 @@ import type { StateKV } from "../state/kv.js"; import { KV } from "../state/schema.js"; import type { Lesson } from "../types.js"; import { recordAudit } from "./audit.js"; +import { + bindResolvedLessonWriteIdentity, + canReadLesson, + canWriteLessonScope, + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; import { withLessonLocks } from "./lesson-locks.js"; import { LESSON_SCHEMA_VERSION, @@ -26,6 +33,7 @@ type LessonCorrectionData = { lessonId: string; reason: string; actor?: string; + accessContext?: LessonAccessContext; project?: string; expectedUpdatedAt?: string; replacementLessonId?: string; @@ -44,6 +52,13 @@ function correctionFailure(code: string, error: string) { return { success: false, code, error }; } +function accessFailure(operation: string) { + return correctionFailure( + "access_denied", + `lesson access denied for ${operation}`, + ); +} + async function findLessonByCanonicalIdentity( kv: StateKV, canonicalId: string, @@ -105,9 +120,13 @@ async function correctLesson( data: LessonCorrectionData, mode: LessonCorrectionMode, ) { + const accessContext = lessonAccessContextFromPayload(data.accessContext); const lessonId = data.lessonId?.trim(); const reason = data.reason?.trim(); - const actor = data.actor?.trim() || "unknown"; + const actor = + accessContext.mode === "enforce" + ? accessContext.principalId + : data.actor?.trim() || "unknown"; const project = data.project?.trim() || undefined; const expectedUpdatedAt = data.expectedUpdatedAt?.trim() || undefined; const replacementLessonId = data.replacementLessonId?.trim() || undefined; @@ -153,6 +172,16 @@ async function correctLesson( } const normalizedLesson = normalizeLesson(lesson); + if ( + !canReadLesson(lesson, accessContext) || + !canWriteLessonScope( + normalizedLesson.scope, + normalizedLesson.sensitivity, + accessContext, + ) + ) { + return accessFailure(mode); + } if (!isLessonListable(lesson)) { const sameCorrection = lesson.deleteReason === reason && @@ -202,6 +231,9 @@ async function correctLesson( "replacement lesson not found", ); } + if (!canReadLesson(replacement, accessContext)) { + return accessFailure("replacement read"); + } if (!isLessonRecallable(replacement)) { return correctionFailure( "replacement_not_active", @@ -253,11 +285,29 @@ async function correctLesson( export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::lesson-save", async (data: unknown) => { - const parsed = parseLessonSaveInput(data); + const accessContext = lessonAccessContextFromPayload( + data && + typeof data === "object" && + !Array.isArray(data) + ? (data as Record).accessContext + : undefined, + ); + const prepared = bindResolvedLessonWriteIdentity(data, accessContext); + if (!prepared.success) return prepared; + const parsed = parseLessonSaveInput(prepared.value); if (!parsed.success) { return correctionFailure("invalid_request", parsed.error); } const input = parsed.value; + if ( + !canWriteLessonScope( + input.scope, + input.sensitivity, + accessContext, + ) + ) { + return accessFailure("save"); + } const fp = lessonIdForInput(input); return withLessonLocks( @@ -281,6 +331,16 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { } if (existing) { + if ( + !canReadLesson(existing, accessContext) || + !canWriteLessonScope( + normalizeLesson(existing).scope, + normalizeLesson(existing).sensitivity, + accessContext, + ) + ) { + return accessFailure("strengthen"); + } const contradictionError = await validateContradictionRelations( kv, existing, @@ -311,7 +371,10 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { "lesson_strengthen", "mem::lesson-save", [existing.id], - { confidenceChanged: false }, + { + actor: accessContext.principalId, + confidenceChanged: false, + }, ); } catch {} @@ -375,6 +438,7 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { "mem::lesson-save", [lesson.id], { + actor: accessContext.principalId, contentFingerprint: lesson.contentFingerprint, evidenceVerdict: lesson.evidenceVerdict, lifecycle: lesson.lifecycle, @@ -398,6 +462,7 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { project?: string; minConfidence?: number; limit?: number; + accessContext?: LessonAccessContext; }) => { if (!data.query?.trim()) { return { success: false, error: "query is required" }; @@ -406,10 +471,14 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { const query = data.query.toLowerCase(); const minConfidence = data.minConfidence ?? 0.1; const limit = data.limit ?? 10; + const accessContext = lessonAccessContextFromPayload( + data.accessContext, + ); const storedLessons = await kv.list(KV.lessons); let lessons = storedLessons .filter(isLessonRecallable) + .filter((lesson) => canReadLesson(lesson, accessContext)) .map((lesson) => toLessonReadModel(lesson)); lessons = lessons.filter((l) => l.confidence >= minConfidence); @@ -460,6 +529,7 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { try { await recordAudit(kv, "lesson_recall", "mem::lesson-recall", [], { query: data.query, + actor: accessContext.principalId, resultCount: scored.length, }); } catch {} @@ -482,6 +552,7 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { limit?: number; offset?: number; sortBy?: "confidence" | "recent"; + accessContext?: LessonAccessContext; }) => { const requestedLimit = data.limit ?? 50; const offset = data.offset ?? 0; @@ -506,9 +577,13 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { } const limit = Math.min(requestedLimit, MAX_LESSON_LIST_LIMIT); const minConfidence = data.minConfidence ?? 0; + const accessContext = lessonAccessContextFromPayload( + data.accessContext, + ); const storedLessons = await kv.list(KV.lessons); let lessons = storedLessons .filter(isLessonListable) + .filter((lesson) => canReadLesson(lesson, accessContext)) .map((lesson) => toLessonReadModel(lesson)) .filter((lesson) => lesson.confidence >= minConfidence); @@ -544,7 +619,10 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { ); sdk.registerFunction("mem::lesson-strengthen", - async (data: { lessonId: string }) => { + async (data: { + lessonId: string; + accessContext?: LessonAccessContext; + }) => { if (!data.lessonId) { return { success: false, error: "lessonId is required" }; } @@ -554,6 +632,20 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { if (!lesson || !isLessonListable(lesson)) { return { success: false, error: "lesson not found" }; } + const accessContext = lessonAccessContextFromPayload( + data.accessContext, + ); + const normalized = normalizeLesson(lesson); + if ( + !canReadLesson(lesson, accessContext) || + !canWriteLessonScope( + normalized.scope, + normalized.sensitivity, + accessContext, + ) + ) { + return accessFailure("strengthen"); + } reinforceLesson(lesson); @@ -565,7 +657,10 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { "lesson_strengthen", "mem::lesson-strengthen", [lesson.id], - { confidenceChanged: false }, + { + actor: accessContext.principalId, + confidenceChanged: false, + }, ); } catch {} diff --git a/src/functions/obsidian-export.ts b/src/functions/obsidian-export.ts index 2058d28d44..4fac89c126 100644 --- a/src/functions/obsidian-export.ts +++ b/src/functions/obsidian-export.ts @@ -16,6 +16,12 @@ import { isLessonListable, toLessonReadModel, } from "./lesson-model.js"; +import { + canReadLesson, + canUseLessonCapability, + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; const DEFAULT_EXPORT_ROOT = join(homedir(), ".agentmemory"); function getExportRoot(): string { @@ -336,7 +342,15 @@ export function registerObsidianExportFunction( kv: StateKV, ): void { sdk.registerFunction("mem::obsidian-export", - async (data: { vaultDir?: string; types?: string[] } | undefined) => { + async ( + data: + | { + vaultDir?: string; + types?: string[]; + accessContext?: LessonAccessContext; + } + | undefined, + ) => { if (!data || typeof data !== "object") { return { success: false, error: "payload is required" }; } @@ -362,6 +376,19 @@ export function registerObsidianExportFunction( const exportTypes = new Set( data.types ?? ["memories", "lessons", "crystals", "sessions"], ); + const accessContext = lessonAccessContextFromPayload( + data.accessContext, + ); + if ( + exportTypes.has("lessons") && + !canUseLessonCapability(accessContext, "lesson:export") + ) { + return { + success: false, + code: "access_denied", + error: "lesson access denied for Obsidian export", + }; + } const dirs = { memories: join(vaultDir, "memories"), @@ -415,7 +442,9 @@ export function registerObsidianExportFunction( for (const l of lessons.filter( (l): l is Lesson & { id: string } => - hasExportId(l) && isLessonListable(l), + hasExportId(l) && + isLessonListable(l) && + canReadLesson(l, accessContext), )) { const filename = `${sanitize(l.id)}.md`; const filepath = join(dirs.lessons, filename); @@ -501,6 +530,7 @@ export function registerObsidianExportFunction( await writeFile(join(vaultDir, "MOC.md"), moc); await recordAudit(kv, "obsidian_export", "mem::obsidian-export", [], { + actor: accessContext.principalId, vaultDir, stats, }); diff --git a/src/functions/reflect.ts b/src/functions/reflect.ts index e06d82f51b..3c9c4c660a 100644 --- a/src/functions/reflect.ts +++ b/src/functions/reflect.ts @@ -18,6 +18,11 @@ import { isLessonRecallable, toLessonReadModel, } from "./lesson-model.js"; +import { + canReadLesson, + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; interface ConceptCluster { concepts: string[]; @@ -222,10 +227,17 @@ export function registerReflectFunctions( provider: MemoryProvider, ): void { sdk.registerFunction("mem::reflect", - async (data: { maxClusters?: number; project?: string }) => { + async (data: { + maxClusters?: number; + project?: string; + accessContext?: LessonAccessContext; + }) => { const maxClusters = Math.min(data?.maxClusters ?? 10, 20); const maxInsightsPerCluster = 5; const maxTotal = 50; + const accessContext = lessonAccessContextFromPayload( + data?.accessContext, + ); let lessons: Lesson[]; try { @@ -244,7 +256,10 @@ export function registerReflectFunctions( let activeLessons: LessonReadModel[] = []; try { for (const lesson of lessons) { - if (isLessonRecallable(lesson)) { + if ( + isLessonRecallable(lesson) && + canReadLesson(lesson, accessContext) + ) { activeLessons.push(toLessonReadModel(lesson)); } } diff --git a/src/functions/smart-search.ts b/src/functions/smart-search.ts index 8be5e22a6c..493cdded4f 100644 --- a/src/functions/smart-search.ts +++ b/src/functions/smart-search.ts @@ -17,6 +17,7 @@ import { } from "../config.js"; import { logger } from "../logger.js"; import { getCounters } from "../telemetry/setup.js"; +import type { LessonAccessContext } from "./lesson-access.js"; // #771: smart-search followup-rate diagnostic. Stored per session as // the most recent search payload, used to detect whether the next @@ -95,6 +96,7 @@ export function registerSmartSearchFunction( // #771: marks viewer-originated searches so the diagnostic // ignores them — only agent-initiated re-queries should count. source?: string; + accessContext?: LessonAccessContext; }) => { // Compute the agent filter once, up front. Both the expandIds @@ -199,7 +201,13 @@ export function registerSmartSearchFunction( const [hybridResults, lessons] = await Promise.all([ searchFn(data.query, overFetchLimit), includeLessons - ? recallLessons(sdk, data.query, lessonLimit, data.project) + ? recallLessons( + sdk, + data.query, + lessonLimit, + data.project, + data.accessContext, + ) : Promise.resolve([]), ]); @@ -292,11 +300,12 @@ async function recallLessons( query: string, limit: number, project?: string, + accessContext?: LessonAccessContext, ): Promise { try { const result = (await sdk.trigger({ function_id: "mem::lesson-recall", - payload: { query, limit, project }, + payload: { query, limit, project, accessContext }, })) as { success?: boolean; lessons?: Array }; if (!result?.success || !Array.isArray(result.lessons)) return []; return result.lessons.map((lesson) => { diff --git a/src/hooks/pre-compact.ts b/src/hooks/pre-compact.ts index 8bb2660c48..e8d2c9b579 100644 --- a/src/hooks/pre-compact.ts +++ b/src/hooks/pre-compact.ts @@ -9,10 +9,14 @@ function isSdkChildContext(payload: unknown): boolean { const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; +const AGENT_ID = process.env["AGENT_ID"] || ""; +const CALLER_TOKEN = process.env["AGENTMEMORY_CALLER_TOKEN"] || ""; function authHeaders(): Record { const h: Record = { "Content-Type": "application/json" }; if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; + if (AGENT_ID) h["X-AgentMemory-Agent-Id"] = AGENT_ID; + if (CALLER_TOKEN) h["X-AgentMemory-Caller-Token"] = CALLER_TOKEN; return h; } diff --git a/src/hooks/session-start.ts b/src/hooks/session-start.ts index 80505a6ef8..9121b2588e 100644 --- a/src/hooks/session-start.ts +++ b/src/hooks/session-start.ts @@ -20,6 +20,8 @@ const INJECT_CONTEXT = process.env["AGENTMEMORY_INJECT_CONTEXT"] === "true"; const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111"; const SECRET = process.env["AGENTMEMORY_SECRET"] || ""; +const AGENT_ID = process.env["AGENT_ID"] || ""; +const CALLER_TOKEN = process.env["AGENTMEMORY_CALLER_TOKEN"] || ""; // When the server is unreachable a 5s timeout multiplies hard under // concurrent fan-out (Slack bots, multi-agent harnesses) and becomes a @@ -31,6 +33,8 @@ const REGISTER_TIMEOUT_MS = 800; function authHeaders(): Record { const h: Record = { "Content-Type": "application/json" }; if (SECRET) h["Authorization"] = `Bearer ${SECRET}`; + if (AGENT_ID) h["X-AgentMemory-Agent-Id"] = AGENT_ID; + if (CALLER_TOKEN) h["X-AgentMemory-Caller-Token"] = CALLER_TOKEN; return h; } diff --git a/src/mcp/http.ts b/src/mcp/http.ts index a0ee592530..562bfdecf4 100644 --- a/src/mcp/http.ts +++ b/src/mcp/http.ts @@ -18,7 +18,10 @@ import { } from "@modelcontextprotocol/sdk/types.js"; import { timingSafeCompare } from "../auth.js"; import { VERSION } from "../version.js"; -import { resolveEnvOrEmpty } from "./rest-proxy.js"; +import { + callerIdentityHeaders, + resolveEnvOrEmpty, +} from "./rest-proxy.js"; const DEFAULT_ENGINE_URL = "http://127.0.0.1:3111"; const DEFAULT_HOST = "127.0.0.1"; @@ -112,6 +115,7 @@ function engineHeaders(): Record { return { "content-type": "application/json", ...(secret ? { authorization: `Bearer ${secret}` } : {}), + ...callerIdentityHeaders(), }; } @@ -129,7 +133,7 @@ export function createProxyBackend(options: { async function request(path: string, init: RequestInit): Promise { const response = await fetchImpl(`${baseUrl}${path}`, { ...init, - headers: { ...engineHeaders(), ...(init.headers ?? {}) }, + headers: { ...(init.headers ?? {}), ...engineHeaders() }, signal: AbortSignal.timeout(BACKEND_TIMEOUT_MS), }); if (!response.ok) { diff --git a/src/mcp/rest-proxy.ts b/src/mcp/rest-proxy.ts index 1adbb46e83..0548911676 100644 --- a/src/mcp/rest-proxy.ts +++ b/src/mcp/rest-proxy.ts @@ -54,6 +54,17 @@ function authHeader(): Record { return secret ? { authorization: `Bearer ${secret}` } : {}; } +export function callerIdentityHeaders(): Record { + const agentId = resolveEnvOrEmpty("AGENT_ID"); + const callerToken = resolveEnvOrEmpty("AGENTMEMORY_CALLER_TOKEN"); + return { + ...(agentId ? { "x-agentmemory-agent-id": agentId } : {}), + ...(callerToken + ? { "x-agentmemory-caller-token": callerToken } + : {}), + }; +} + /** * Probes the agentmemory server's livez endpoint. Returns a Response-shaped * object whose `ok` flag drives the proxy/local-fallback decision. @@ -143,6 +154,7 @@ export async function resolveHandle(): Promise { "content-type": "application/json", ...authHeader(), ...(init?.headers as Record | undefined), + ...callerIdentityHeaders(), }, signal: AbortSignal.timeout(CALL_TIMEOUT_MS), }); diff --git a/src/mcp/server.ts b/src/mcp/server.ts index f535ab2682..2341de9a55 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -13,6 +13,11 @@ import { timingSafeCompare } from "../auth.js"; import { getAgentId, isAgentScopeIsolated } from "../config.js"; import { selectSessionPage } from "../functions/session-list.js"; import { parseLessonSaveInput } from "../functions/lesson-model.js"; +import { + bindResolvedLessonWriteIdentity, + resolveLessonBoundaryAccess, + type LessonAccessContext, +} from "../functions/lesson-access.js"; type McpResponse = { status_code: number; @@ -20,6 +25,26 @@ type McpResponse = { body: unknown; }; +type LessonRequestAccess = + | { success: true; context: LessonAccessContext } + | { success: false; response: McpResponse }; + +function resolveLessonRequestAccess(req: ApiRequest): LessonRequestAccess { + const resolved = resolveLessonBoundaryAccess( + req.headers as Record | undefined, + ); + if (!resolved.success) { + return { + success: false, + response: { + status_code: resolved.statusCode, + body: { error: resolved.error, code: resolved.code }, + }, + }; + } + return { success: true, context: resolved.context }; +} + function asNonEmptyString(value: unknown): string | undefined { return typeof value === "string" && value.trim() ? value.trim() : undefined; } @@ -335,6 +360,8 @@ export function registerMcpEndpoints( } case "memory_smart_search": { + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; if (typeof args.query !== "string" || !args.query.trim()) { return { status_code: 400, @@ -349,6 +376,7 @@ export function registerMcpEndpoints( query: args.query, expandIds, limit, + accessContext: access.context, }, }); return { @@ -432,7 +460,12 @@ export function registerMcpEndpoints( } case "memory_export": { - const result = await sdk.trigger({ function_id: "mem::export", payload: {} }); + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; + const result = await sdk.trigger({ + function_id: "mem::export", + payload: { accessContext: access.context }, + }); return { status_code: 200, body: { @@ -1308,7 +1341,20 @@ export function registerMcpEndpoints( } case "memory_lesson_save": { - const parsed = parseLessonSaveInput(args, { + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; + const prepared = bindResolvedLessonWriteIdentity( + args, + access.context, + ); + if (!prepared.success) { + return { + status_code: + prepared.code === "access_denied" ? 403 : 400, + body: { error: prepared.error, code: prepared.code }, + }; + } + const parsed = parseLessonSaveInput(prepared.value, { source: "manual", allowSourceMetadata: false, }); @@ -1320,12 +1366,14 @@ export function registerMcpEndpoints( } const lessonSaveResult = await sdk.trigger({ function_id: "mem::lesson-save", - payload: parsed.value, + payload: { ...parsed.value, accessContext: access.context }, }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(lessonSaveResult, null, 2) }] } }; } case "memory_lesson_recall": { + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; if (typeof args.query !== "string" || !args.query.trim()) { return { status_code: 400, body: { error: "query is required" } }; } @@ -1334,11 +1382,14 @@ export function registerMcpEndpoints( project: args.project, minConfidence: args.minConfidence, limit: args.limit, + accessContext: access.context, } }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(lessonRecallResult, null, 2) }] } }; } case "memory_lesson_delete": { + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const lessonId = asNonEmptyString(args.lessonId); const reason = asNonEmptyString(args.reason); if (!lessonId || !reason) { @@ -1355,12 +1406,15 @@ export function registerMcpEndpoints( project: asNonEmptyString(args.project), expectedUpdatedAt: asNonEmptyString(args.expectedUpdatedAt), actor: asNonEmptyString(args.actor) ?? getAgentId() ?? "unknown", + accessContext: access.context, }, }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(lessonDeleteResult, null, 2) }] } }; } case "memory_lesson_supersede": { + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const lessonId = asNonEmptyString(args.lessonId); const replacementLessonId = asNonEmptyString( args.replacementLessonId, @@ -1384,15 +1438,19 @@ export function registerMcpEndpoints( project: asNonEmptyString(args.project), expectedUpdatedAt: asNonEmptyString(args.expectedUpdatedAt), actor: asNonEmptyString(args.actor) ?? getAgentId() ?? "unknown", + accessContext: access.context, }, }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(lessonSupersedeResult, null, 2) }] } }; } case "memory_reflect": { + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const reflectResult = await sdk.trigger({ function_id: "mem::reflect", payload: { project: args.project, maxClusters: args.maxClusters, + accessContext: access.context, } }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(reflectResult, null, 2) }] } }; } @@ -1407,12 +1465,15 @@ export function registerMcpEndpoints( } case "memory_obsidian_export": { + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const exportTypes = typeof args.types === "string" && args.types.trim() ? args.types.split(",").map((t: string) => t.trim()).filter(Boolean) : undefined; const obsidianResult = await sdk.trigger({ function_id: "mem::obsidian-export", payload: { vaultDir: args.vaultDir, types: exportTypes, + accessContext: access.context, } }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(obsidianResult, null, 2) }] } }; } diff --git a/src/triggers/api.ts b/src/triggers/api.ts index f6c970d48f..306fe94a68 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -23,6 +23,11 @@ import { logger } from "../logger.js"; import { selectSessionPage } from "../functions/session-list.js"; import { triggerDetached } from "../utils/trigger-detached.js"; import { parseLessonSaveInput } from "../functions/lesson-model.js"; +import { + bindResolvedLessonWriteIdentity, + resolveLessonBoundaryAccess, + type LessonAccessContext, +} from "../functions/lesson-access.js"; import { isGraphExtractionEnabled, isConsolidationEnabled, @@ -42,6 +47,26 @@ type Response = { body: unknown; }; +type LessonRequestAccess = + | { success: true; context: LessonAccessContext } + | { success: false; response: Response }; + +function resolveLessonRequestAccess(req: ApiRequest): LessonRequestAccess { + const resolved = resolveLessonBoundaryAccess( + req.headers as Record | undefined, + ); + if (!resolved.success) { + return { + success: false, + response: { + status_code: resolved.statusCode, + body: { error: resolved.error, code: resolved.code }, + }, + }; + } + return { success: true, context: resolved.context }; +} + export const OBSERVATION_QUEUE = "agentmemory-observations"; function parseOptionalInt(raw: unknown): number | undefined { @@ -454,6 +479,8 @@ export function registerApiTriggers( async ( req: ApiRequest<{ sessionId: string; project: string; budget?: number }>, ): Promise => { + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const body = (req.body ?? {}) as Record; const sessionId = asNonEmptyString(body.sessionId); const project = asNonEmptyString(body.project); @@ -470,9 +497,15 @@ export function registerApiTriggers( body: { error: "budget must be a positive integer" }, }; } - const payload: { sessionId: string; project: string; budget?: number } = { + const payload: { + sessionId: string; + project: string; + budget?: number; + accessContext: LessonAccessContext; + } = { sessionId, project, + accessContext: access.context, }; if (budget !== undefined) payload.budget = budget; const result = await sdk.trigger({ function_id: "mem::context", payload }); @@ -727,6 +760,8 @@ export function registerApiTriggers( }, }; } + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const title = typeof body.title === "string" ? body.title.trim() : undefined; // allow session/start to override AGENT_ID from request body // (multi-agent runtimes that route many roles through one server @@ -752,9 +787,16 @@ export function registerApiTriggers( }; await kv.set(KV.sessions, sessionId, session); const contextResult = await sdk.trigger< - { sessionId: string; project: string }, + { + sessionId: string; + project: string; + accessContext: LessonAccessContext; + }, { context: string } - >({ function_id: "mem::context", payload: { sessionId, project } }); + >({ + function_id: "mem::context", + payload: { sessionId, project, accessContext: access.context }, + }); return { status_code: 200, body: { session, context: contextResult.context }, @@ -1461,6 +1503,13 @@ export function registerApiTriggers( body: { error: "query or expandIds is required" }, }; } + const includesLessons = + (!req.body?.expandIds || req.body.expandIds.length === 0) && + req.body?.includeLessons !== false; + const access = includesLessons + ? resolveLessonRequestAccess(req) + : undefined; + if (access && !access.success) return access.response; // #771: route the X-Agentmemory-Source header into the payload so // the followup-rate diagnostic can skip viewer-originated calls. // Body wins if both are set (advanced callers explicitly override). @@ -1480,6 +1529,7 @@ export function registerApiTriggers( agentId: req.body?.agentId, sessionId: req.body?.sessionId, source: req.body?.source ?? sourceFromHeader, + ...(access?.success ? { accessContext: access.context } : {}), }; const result = await sdk.trigger({ function_id: "mem::smart-search", payload }); return { status_code: 200, body: result }; @@ -1572,6 +1622,8 @@ export function registerApiTriggers( async (req: ApiRequest): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; // mem::export already supports maxSessions/offset internally, // but the HTTP endpoint hardcoded an empty payload — so /export on a // real corpus (40 sessions × 34K observations × 8K memories) hit the @@ -1579,7 +1631,11 @@ export function registerApiTriggers( // Pass through the query-string pagination so callers can chunk. const rawMax = req.query_params?.["maxSessions"]; const rawOffset = req.query_params?.["offset"]; - const payload: { maxSessions?: number; offset?: number } = {}; + const payload: { + maxSessions?: number; + offset?: number; + accessContext: LessonAccessContext; + } = { accessContext: access.context }; if (typeof rawMax === "string") { const n = Number(rawMax); if (Number.isInteger(n) && n > 0) payload.maxSessions = n; @@ -1592,7 +1648,11 @@ export function registerApiTriggers( function_id: "mem::export", payload, }); - return { status_code: 200, body: result }; + const response = result as { code?: string }; + return { + status_code: response.code === "access_denied" ? 403 : 200, + body: result, + }; }, ); sdk.registerTrigger({ @@ -1610,11 +1670,24 @@ export function registerApiTriggers( ): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; if (!req.body?.exportData) { return { status_code: 400, body: { error: "exportData is required" } }; } - const result = await sdk.trigger({ function_id: "mem::import", payload: req.body }); - return { status_code: 200, body: result }; + const result = await sdk.trigger({ + function_id: "mem::import", + payload: { + exportData: req.body.exportData, + strategy: req.body.strategy, + accessContext: access.context, + }, + }); + const response = result as { code?: string }; + return { + status_code: response.code === "access_denied" ? 403 : 200, + body: result, + }; }, ); sdk.registerTrigger({ @@ -3546,7 +3619,19 @@ export function registerApiTriggers( sdk.registerFunction("api::lesson-save", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; - const parsed = parseLessonSaveInput(req.body, { + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; + const prepared = bindResolvedLessonWriteIdentity( + req.body, + access.context, + ); + if (!prepared.success) { + return { + status_code: prepared.code === "access_denied" ? 403 : 400, + body: { error: prepared.error, code: prepared.code }, + }; + } + const parsed = parseLessonSaveInput(prepared.value, { source: "manual", allowSourceMetadata: false, }); @@ -3555,8 +3640,11 @@ export function registerApiTriggers( } const result = (await sdk.trigger({ function_id: "mem::lesson-save", - payload: parsed.value, - })) as { action?: string }; + payload: { ...parsed.value, accessContext: access.context }, + })) as { action?: string; code?: string }; + if (result?.code === "access_denied") { + return { status_code: 403, body: result }; + } const statusCode = result?.action === "created" ? 201 : 200; return { status_code: statusCode, body: result }; }); @@ -3565,6 +3653,8 @@ export function registerApiTriggers( sdk.registerFunction("api::lesson-list", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const params = req.query_params || {}; const minConfidence = parseOptionalFiniteNumber(params.minConfidence); if (minConfidence === null) { @@ -3605,6 +3695,7 @@ export function registerApiTriggers( limit, offset, sortBy, + accessContext: access.context, } }); return { status_code: 200, body: result }; }); @@ -3613,6 +3704,8 @@ export function registerApiTriggers( sdk.registerFunction("api::lesson-search", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const body = (req.body ?? {}) as Record; const query = asNonEmptyString(body.query); if (!query) { @@ -3649,6 +3742,7 @@ export function registerApiTriggers( project: asNonEmptyString(body.project), minConfidence: body.minConfidence, limit: body.limit, + accessContext: access.context, }, }); return { status_code: 200, body: result }; @@ -3658,16 +3752,27 @@ export function registerApiTriggers( sdk.registerFunction("api::lesson-strengthen", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const body = req.body as Record; if (!body?.lessonId || typeof body.lessonId !== "string") return { status_code: 400, body: { error: "lessonId is required" } }; - const result = await sdk.trigger({ function_id: "mem::lesson-strengthen", payload: { lessonId: body.lessonId } }); - return { status_code: 200, body: result }; + const result = await sdk.trigger({ + function_id: "mem::lesson-strengthen", + payload: { lessonId: body.lessonId, accessContext: access.context }, + }); + const response = result as { code?: string }; + return { + status_code: response.code === "access_denied" ? 403 : 200, + body: result, + }; }); sdk.registerTrigger({ type: "http", function_id: "api::lesson-strengthen", config: { api_path: "/agentmemory/lessons/strengthen", http_method: "POST" } }); sdk.registerFunction("api::lesson-delete", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const body = (req.body ?? {}) as Record; const lessonId = asNonEmptyString(body.lessonId); const reason = asNonEmptyString(body.reason); @@ -3694,6 +3799,7 @@ export function registerApiTriggers( expectedUpdatedAt: asNonEmptyString(body.expectedUpdatedAt) ?? undefined, actor: asNonEmptyString(body.actor) ?? getAgentId() ?? "unknown", + accessContext: access.context, }, }); const response = result as { success?: boolean; code?: string }; @@ -3707,6 +3813,8 @@ export function registerApiTriggers( response.code === "project_mismatch" || response.code === "scope_mismatch" ? 409 + : response.code === "access_denied" + ? 403 : 400; return { status_code: statusCode, body: result }; }); @@ -3719,6 +3827,8 @@ export function registerApiTriggers( sdk.registerFunction("api::lesson-supersede", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const body = (req.body ?? {}) as Record; const lessonId = asNonEmptyString(body.lessonId); const replacementLessonId = asNonEmptyString(body.replacementLessonId); @@ -3749,6 +3859,7 @@ export function registerApiTriggers( expectedUpdatedAt: asNonEmptyString(body.expectedUpdatedAt) ?? undefined, actor: asNonEmptyString(body.actor) ?? getAgentId() ?? "unknown", + accessContext: access.context, }, }); const response = result as { success?: boolean; code?: string }; @@ -3764,6 +3875,8 @@ export function registerApiTriggers( response.code === "scope_mismatch" || response.code === "replacement_not_active" ? 409 + : response.code === "access_denied" + ? 403 : 400; return { status_code: statusCode, body: result }; }); @@ -3788,18 +3901,37 @@ export function registerApiTriggers( }; } const types = typeof body.types === "string" ? body.types.split(",").map((t: string) => t.trim()).filter(Boolean) : undefined; - const result = await sdk.trigger({ function_id: "mem::obsidian-export", payload: { vaultDir, types } }); - return { status_code: 200, body: result }; + const includesLessons = types === undefined || types.includes("lessons"); + const access = includesLessons + ? resolveLessonRequestAccess(req) + : undefined; + if (access && !access.success) return access.response; + const result = await sdk.trigger({ + function_id: "mem::obsidian-export", + payload: { + vaultDir, + types, + ...(access?.success ? { accessContext: access.context } : {}), + }, + }); + const response = result as { code?: string }; + return { + status_code: response.code === "access_denied" ? 403 : 200, + body: result, + }; }); sdk.registerTrigger({ type: "http", function_id: "api::obsidian-export", config: { api_path: "/agentmemory/obsidian/export", http_method: "POST" } }); sdk.registerFunction("api::reflect", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const body = (req.body as Record) || {}; const result = await sdk.trigger({ function_id: "mem::reflect", payload: { project: typeof body.project === "string" ? body.project : undefined, maxClusters: typeof body.maxClusters === "number" ? body.maxClusters : undefined, + accessContext: access.context, } }); return { status_code: 200, body: result }; }); diff --git a/src/triggers/events.ts b/src/triggers/events.ts index 09e3d3a9b2..48224a5b7c 100644 --- a/src/triggers/events.ts +++ b/src/triggers/events.ts @@ -6,6 +6,8 @@ import { isReflectEnabled } from "../functions/slots.js"; import { isGraphExtractionEnabled } from "../config.js"; import { logger } from "../logger.js"; import { triggerDetached } from "../utils/trigger-detached.js"; +import { systemLessonAccessContext } from "../functions/lesson-access.js"; +import type { LessonAccessContext } from "../functions/lesson-access.js"; export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { sdk.registerFunction( @@ -37,11 +39,19 @@ export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { }; await kv.set(KV.sessions, data.sessionId, session); const contextResult = await sdk.trigger< - { sessionId: string; project: string }, + { + sessionId: string; + project: string; + accessContext: LessonAccessContext; + }, { context: string } >({ function_id: "mem::context", - payload: { sessionId: data.sessionId, project: data.project }, + payload: { + sessionId: data.sessionId, + project: data.project, + accessContext: systemLessonAccessContext(), + }, }); return { session, context: contextResult.context }; }, diff --git a/test/cli-connect.test.ts b/test/cli-connect.test.ts index 46a1f240b6..c5864311bc 100644 --- a/test/cli-connect.test.ts +++ b/test/cli-connect.test.ts @@ -352,6 +352,8 @@ describe("agentmemory connect — copilot-cli adapter (mock filesystem)", () => env: { AGENTMEMORY_URL: "${AGENTMEMORY_URL:-http://localhost:3111}", AGENTMEMORY_SECRET: "${AGENTMEMORY_SECRET:-}", + AGENT_ID: "${AGENT_ID:-}", + AGENTMEMORY_CALLER_TOKEN: "${AGENTMEMORY_CALLER_TOKEN:-}", AGENTMEMORY_TOOLS: "${AGENTMEMORY_TOOLS:-all}", }, tools: ["*"], diff --git a/test/lesson-access.test.ts b/test/lesson-access.test.ts new file mode 100644 index 0000000000..05c1055c65 --- /dev/null +++ b/test/lesson-access.test.ts @@ -0,0 +1,374 @@ +import { createHash } from "node:crypto"; +import { describe, expect, it } from "vitest"; +import { + canApproveGlobalLesson, + canReadLesson, + canUseLessonCapability, + canWriteLessonScope, + lessonAccessContextFromPayload, + parseLessonCallerPolicy, + resolveLessonBoundaryAccess, + systemLessonAccessContext, + type LessonAccessContext, + type LessonCallerPolicy, +} from "../src/functions/lesson-access.js"; +import type { Lesson } from "../src/types.js"; + +const REPO_SCOPE = { + ring: "repo" as const, + scopeId: "repo:https://github.com/wrightpt/agentmemory", +}; + +function digest(token: string): string { + return createHash("sha256").update(token, "utf8").digest("hex"); +} + +function policy(): LessonCallerPolicy { + return { + version: 1, + principals: [ + { + principalId: "codex", + principalKind: "agent", + tokenSha256: digest("codex-token"), + clearance: "confidential", + scopes: [{ ...REPO_SCOPE, access: "write" }], + capabilities: ["lesson:export"], + }, + { + principalId: "patrick", + principalKind: "human", + tokenSha256: digest("human-token"), + clearance: "restricted", + scopes: [{ ring: "global", access: "write" }], + capabilities: ["lesson:approve-global", "lesson:all-scopes"], + }, + ], + }; +} + +function lesson( + sensitivity: Lesson["sensitivity"], + scope: Lesson["scope"] = REPO_SCOPE, +): Lesson { + return { + id: "lsn_test", + content: "Authorized lesson", + context: "", + confidence: 0.8, + reinforcements: 0, + source: "manual", + sourceIds: [], + project: "agentmemory", + tags: [], + createdAt: "2026-08-03T00:00:00.000Z", + updatedAt: "2026-08-03T00:00:00.000Z", + decayRate: 0.05, + schemaVersion: 1, + identityKind: "canonical", + mechanismId: "authorization/test", + claim: "Authorization filters lessons.", + evidenceVerdict: "unverified", + lifecycle: "active", + applicabilityConditions: [], + nonApplicabilityConditions: [], + falsificationConditions: [], + structuredFacets: {}, + evidenceRefs: [], + scope, + sensitivity, + contradictedByLessonIds: [], + contentFingerprint: "a".repeat(64), + }; +} + +function legacyLesson(): Lesson { + return { + id: "lsn_legacy", + content: "Legacy authorized lesson", + context: "", + confidence: 0.8, + reinforcements: 0, + source: "manual", + sourceIds: [], + project: "agentmemory", + tags: [], + createdAt: "2026-08-03T00:00:00.000Z", + updatedAt: "2026-08-03T00:00:00.000Z", + decayRate: 0.05, + }; +} + +function context( + overrides: Partial = {}, +): LessonAccessContext { + return { + schemaVersion: 1, + mode: "enforce", + principalId: "codex", + principalKind: "agent", + clearance: "confidential", + scopes: [{ ...REPO_SCOPE, access: "write" }], + capabilities: [], + resolvedBy: "server-policy", + ...overrides, + }; +} + +describe("lesson caller policy", () => { + it("resolves a principal from a server-side token digest", () => { + const result = resolveLessonBoundaryAccess( + { + "X-AgentMemory-Agent-Id": "codex", + "x-agentmemory-caller-token": "codex-token", + }, + { mode: "enforce", policy: policy() }, + ); + + expect(result).toMatchObject({ + success: true, + context: { + schemaVersion: 1, + mode: "enforce", + principalId: "codex", + principalKind: "agent", + clearance: "confidential", + scopes: [{ ...REPO_SCOPE, access: "write" }], + capabilities: ["lesson:export"], + resolvedBy: "server-policy", + }, + }); + expect( + result.success ? result.context.authorizationProof : undefined, + ).toMatch(/^[a-f0-9]{64}$/); + }); + + it("fails closed without a policy, token, or matching claimed identity", () => { + expect( + resolveLessonBoundaryAccess({}, { mode: "enforce" }), + ).toMatchObject({ + success: false, + statusCode: 503, + code: "caller_policy_unavailable", + }); + expect( + resolveLessonBoundaryAccess( + {}, + { mode: "enforce", policy: policy() }, + ), + ).toMatchObject({ + success: false, + statusCode: 401, + code: "caller_authentication_failed", + }); + expect( + resolveLessonBoundaryAccess( + { + "x-agentmemory-agent-id": "kimi", + "x-agentmemory-caller-token": "codex-token", + }, + { mode: "enforce", policy: policy() }, + ), + ).toMatchObject({ + success: false, + statusCode: 401, + code: "caller_authentication_failed", + }); + }); + + it("keeps legacy behavior explicit in classify mode", () => { + expect( + resolveLessonBoundaryAccess( + { "x-agentmemory-agent-id": "codex" }, + { mode: "classify" }, + ), + ).toEqual({ + success: true, + context: { + schemaVersion: 1, + mode: "classify", + principalId: "codex", + principalKind: "agent", + clearance: "restricted", + scopes: [], + capabilities: [], + resolvedBy: "legacy-classification", + }, + }); + }); + + it("rejects duplicate principals, duplicate token digests, and malformed grants", () => { + const base = policy(); + expect(() => + parseLessonCallerPolicy({ + version: 1, + principals: [base.principals[0], base.principals[0]], + }), + ).toThrow("duplicate lesson principalId"); + expect(() => + parseLessonCallerPolicy({ + version: 1, + principals: [ + base.principals[0], + { + ...base.principals[1], + tokenSha256: base.principals[0].tokenSha256, + }, + ], + }), + ).toThrow("duplicate lesson caller token digest"); + expect(() => + parseLessonCallerPolicy({ + version: 1, + principals: [ + { + ...base.principals[0], + scopes: [{ ring: "repo", access: "read" }], + }, + ], + }), + ).toThrow("non-global scope grants require scopeId"); + }); +}); + +describe("lesson access decisions", () => { + it("requires both sensitivity clearance and an exact durable-scope grant", () => { + expect(canReadLesson(lesson("confidential"), context())).toBe(true); + expect(canReadLesson(lesson("restricted"), context())).toBe(false); + expect( + canReadLesson( + lesson("internal", { + ring: "repo", + scopeId: "repo:https://github.com/wrightpt/other", + }), + context(), + ), + ).toBe(false); + expect( + canWriteLessonScope(REPO_SCOPE, "confidential", context()), + ).toBe(true); + expect( + canWriteLessonScope(REPO_SCOPE, "restricted", context()), + ).toBe(false); + }); + + it("does not treat global scope as an implicit wildcard", () => { + const globalOnly = context({ + scopes: [{ ring: "global", access: "write" }], + }); + expect( + canReadLesson( + lesson("public", { + ring: "global", + humanApproval: { + approvedBy: "patrick", + approvedAt: "2026-08-03T00:00:00.000Z", + reason: "Approved for global publication.", + }, + }), + globalOnly, + ), + ).toBe( + true, + ); + expect(canReadLesson(lesson("public"), globalOnly)).toBe(false); + }); + + it("requires explicit legacy-worktree and administrative capabilities", () => { + const legacy = legacyLesson(); + expect(canReadLesson(legacy, context({ clearance: "restricted" }))).toBe( + false, + ); + expect( + canReadLesson( + legacy, + context({ + clearance: "restricted", + capabilities: ["lesson:legacy-worktree"], + }), + ), + ).toBe(true); + expect(canUseLessonCapability(context(), "lesson:export")).toBe(false); + expect( + canUseLessonCapability( + context({ capabilities: ["lesson:export"] }), + "lesson:export", + ), + ).toBe(true); + }); + + it("allows global approval only for a resolved human principal", () => { + expect( + canApproveGlobalLesson( + context({ capabilities: ["lesson:approve-global"] }), + ), + ).toBe(false); + expect( + canApproveGlobalLesson( + context({ + principalId: "patrick", + principalKind: "human", + capabilities: ["lesson:approve-global"], + }), + ), + ).toBe(true); + }); + + it("fails closed for a missing payload context in enforce mode", () => { + const previous = process.env["AGENTMEMORY_LESSON_ACCESS_MODE"]; + process.env["AGENTMEMORY_LESSON_ACCESS_MODE"] = "enforce"; + try { + const unresolved = lessonAccessContextFromPayload(undefined); + expect(unresolved).toMatchObject({ + mode: "enforce", + principalId: "unresolved", + clearance: "public", + scopes: [], + }); + expect(canReadLesson(lesson("internal"), unresolved)).toBe(false); + } finally { + if (previous === undefined) { + delete process.env["AGENTMEMORY_LESSON_ACCESS_MODE"]; + } else { + process.env["AGENTMEMORY_LESSON_ACCESS_MODE"] = previous; + } + } + }); + + it("rejects forged classify and unsigned enforce contexts after enforcement", () => { + const previous = process.env["AGENTMEMORY_LESSON_ACCESS_MODE"]; + process.env["AGENTMEMORY_LESSON_ACCESS_MODE"] = "enforce"; + try { + for (const forged of [ + { ...context(), mode: "classify", resolvedBy: "legacy-classification" }, + context(), + ]) { + expect(lessonAccessContextFromPayload(forged)).toMatchObject({ + mode: "enforce", + principalId: "unresolved", + clearance: "public", + scopes: [], + }); + } + expect( + lessonAccessContextFromPayload(systemLessonAccessContext()), + ).toMatchObject({ + principalId: "agentmemory:system", + resolvedBy: "system", + }); + } finally { + if (previous === undefined) { + delete process.env["AGENTMEMORY_LESSON_ACCESS_MODE"]; + } else { + process.env["AGENTMEMORY_LESSON_ACCESS_MODE"] = previous; + } + } + }); + + it("gives only the explicit system context full internal access", () => { + const system = systemLessonAccessContext(); + expect(canReadLesson(lesson("restricted"), system)).toBe(true); + expect(canUseLessonCapability(system, "lesson:import")).toBe(true); + expect(canApproveGlobalLesson(system)).toBe(false); + }); +}); diff --git a/test/lesson-authorization.test.ts b/test/lesson-authorization.test.ts new file mode 100644 index 0000000000..4b095031ef --- /dev/null +++ b/test/lesson-authorization.test.ts @@ -0,0 +1,384 @@ +import { createHash } from "node:crypto"; +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { registerExportImportFunction } from "../src/functions/export-import.js"; +import { registerContextFunction } from "../src/functions/context.js"; +import { systemLessonAccessContext } from "../src/functions/lesson-access.js"; +import { registerLessonsFunctions } from "../src/functions/lessons.js"; +import { registerReflectFunctions } from "../src/functions/reflect.js"; +import { registerSmartSearchFunction } from "../src/functions/smart-search.js"; +import { registerMcpEndpoints } from "../src/mcp/server.js"; +import { registerApiTriggers } from "../src/triggers/api.js"; +import type { ExportData, Lesson } from "../src/types.js"; +import { mockKV, mockSdk } from "./helpers/mocks.js"; + +const REPO_ONE = { + ring: "repo" as const, + scopeId: "repo:https://github.com/wrightpt/agentmemory", +}; +const REPO_TWO = { + ring: "repo" as const, + scopeId: "repo:https://github.com/wrightpt/trading-system", +}; + +function tokenDigest(token: string): string { + return createHash("sha256").update(token, "utf8").digest("hex"); +} + +function lessonInput( + suffix: string, + scope: typeof REPO_ONE | typeof REPO_TWO = REPO_ONE, +) { + return { + content: `Causal lesson ${suffix}`, + project: "agentmemory", + mechanismId: `authorization/${suffix}`, + claim: `Caller ${suffix} can retrieve only authorized evidence.`, + scope, + sensitivity: "confidential" as const, + }; +} + +function headers(token: string, agentId: string) { + return { + "x-agentmemory-caller-token": token, + "x-agentmemory-agent-id": agentId, + }; +} + +describe("lesson authorization boundaries", () => { + let sdk: ReturnType; + let kv: ReturnType; + let policyDir: string; + let reflectionPrompts: string[]; + + beforeEach(() => { + policyDir = mkdtempSync(join(tmpdir(), "agentmemory-lesson-policy-")); + const policyPath = join(policyDir, "callers.json"); + writeFileSync( + policyPath, + JSON.stringify({ + version: 1, + principals: [ + { + principalId: "codex", + principalKind: "agent", + tokenSha256: tokenDigest("codex-token"), + clearance: "confidential", + scopes: [{ ...REPO_ONE, access: "write" }], + capabilities: ["lesson:export", "lesson:import"], + }, + { + principalId: "readonly", + principalKind: "agent", + tokenSha256: tokenDigest("readonly-token"), + clearance: "confidential", + scopes: [{ ...REPO_ONE, access: "read" }], + capabilities: [], + }, + { + principalId: "patrick", + principalKind: "human", + tokenSha256: tokenDigest("human-token"), + clearance: "restricted", + scopes: [{ ring: "global", access: "write" }], + capabilities: ["lesson:approve-global"], + }, + ], + }), + ); + process.env["AGENTMEMORY_LESSON_ACCESS_MODE"] = "enforce"; + process.env["AGENTMEMORY_LESSON_CALLER_POLICY_FILE"] = policyPath; + + sdk = mockSdk(); + kv = mockKV(); + reflectionPrompts = []; + registerLessonsFunctions(sdk as never, kv as never); + registerContextFunction(sdk as never, kv as never, 2000); + registerSmartSearchFunction( + sdk as never, + kv as never, + async () => [], + ); + registerExportImportFunction(sdk as never, kv as never); + registerReflectFunctions( + sdk as never, + kv as never, + { + summarize: async (_system: string, prompt: string) => { + reflectionPrompts.push(prompt); + return ""; + }, + } as never, + ); + registerApiTriggers(sdk as never, kv as never); + registerMcpEndpoints(sdk as never, kv as never); + }); + + afterEach(() => { + delete process.env["AGENTMEMORY_LESSON_ACCESS_MODE"]; + delete process.env["AGENTMEMORY_LESSON_CALLER_POLICY_FILE"]; + rmSync(policyDir, { recursive: true, force: true }); + }); + + it("requires server-resolved identity and ignores a caller-supplied context", async () => { + const response = (await sdk.trigger("api::lesson-save", { + headers: {}, + body: { + ...lessonInput("spoof"), + accessContext: systemLessonAccessContext(), + }, + })) as { status_code: number; body: { code: string } }; + + expect(response).toMatchObject({ + status_code: 401, + body: { code: "caller_authentication_failed" }, + }); + expect(await kv.list("mem:lessons")).toEqual([]); + }); + + it("allows only the authenticated principal's scope and clearance", async () => { + const allowed = (await sdk.trigger("api::lesson-save", { + headers: headers("codex-token", "codex"), + body: lessonInput("allowed"), + })) as { status_code: number; body: { lesson: Lesson } }; + const denied = (await sdk.trigger("api::lesson-save", { + headers: headers("codex-token", "codex"), + body: lessonInput("denied", REPO_TWO), + })) as { status_code: number; body: { code: string } }; + + expect(allowed.status_code).toBe(201); + expect(allowed.body.lesson.scope).toEqual(REPO_ONE); + expect(denied).toMatchObject({ + status_code: 403, + body: { code: "access_denied" }, + }); + expect(await kv.list("mem:lessons")).toHaveLength(1); + }); + + it("filters list, recall, and export totals without revealing other scopes", async () => { + const system = systemLessonAccessContext(); + await sdk.trigger("mem::lesson-save", { + ...lessonInput("visible"), + accessContext: system, + }); + await sdk.trigger("mem::lesson-save", { + ...lessonInput("hidden", REPO_TWO), + accessContext: system, + }); + + const list = (await sdk.trigger("api::lesson-list", { + headers: headers("codex-token", "codex"), + query_params: {}, + })) as { + status_code: number; + body: { total: number; lessons: Lesson[] }; + }; + const recall = (await sdk.trigger("api::lesson-search", { + headers: headers("codex-token", "codex"), + body: { query: "causal lesson" }, + })) as { + status_code: number; + body: { lessons: Lesson[] }; + }; + const exported = (await sdk.trigger("api::export", { + headers: headers("codex-token", "codex"), + query_params: {}, + })) as { status_code: number; body: ExportData }; + + expect(list.body.total).toBe(1); + expect(list.body.lessons.map((lesson) => lesson.mechanismId)).toEqual([ + "authorization/visible", + ]); + expect(recall.body.lessons).toHaveLength(1); + expect(exported.status_code).toBe(200); + expect(exported.body.lessons).toHaveLength(1); + expect(exported.body.lessons?.[0].mechanismId).toBe( + "authorization/visible", + ); + }); + + it("filters injected context and smart-search lesson results", async () => { + const system = systemLessonAccessContext(); + await sdk.trigger("mem::lesson-save", { + ...lessonInput("context-visible"), + accessContext: system, + }); + await sdk.trigger("mem::lesson-save", { + ...lessonInput("context-hidden", REPO_TWO), + accessContext: system, + }); + + const context = (await sdk.trigger("api::context", { + headers: headers("codex-token", "codex"), + body: { + sessionId: "ses_current", + project: "agentmemory", + budget: 2000, + }, + })) as { status_code: number; body: { context: string } }; + const smart = (await sdk.trigger("api::smart-search", { + headers: headers("codex-token", "codex"), + body: { + query: "causal lesson context", + includeLessons: true, + project: "agentmemory", + }, + })) as { + status_code: number; + body: { lessons: Array<{ lessonId: string; content: string }> }; + }; + + expect(context.body.context).toContain("Causal lesson context-visible"); + expect(context.body.context).not.toContain("context-hidden"); + expect(smart.body.lessons).toHaveLength(1); + expect(smart.body.lessons[0].content).toContain("context-visible"); + }); + + it("filters unauthorized lessons before constructing reflection prompts", async () => { + const system = systemLessonAccessContext(); + for (const suffix of ["reflect-visible-a", "reflect-visible-b", "reflect-visible-c"]) { + await sdk.trigger("mem::lesson-save", { + ...lessonInput(suffix), + tags: ["shared", "authorization"], + accessContext: system, + }); + } + await sdk.trigger("mem::lesson-save", { + ...lessonInput("reflect-hidden", REPO_TWO), + tags: ["shared", "authorization"], + accessContext: system, + }); + + const response = (await sdk.trigger("api::reflect", { + headers: headers("codex-token", "codex"), + body: { project: "agentmemory" }, + })) as { status_code: number }; + + expect(response.status_code).toBe(200); + expect(reflectionPrompts.length).toBeGreaterThan(0); + expect(reflectionPrompts.join("\n")).toContain("reflect-visible-a"); + expect(reflectionPrompts.join("\n")).not.toContain("reflect-hidden"); + }); + + it("requires explicit export capability before reading lesson state", async () => { + const response = (await sdk.trigger("api::export", { + headers: headers("readonly-token", "readonly"), + query_params: {}, + })) as { status_code: number; body: { code: string } }; + + expect(response).toMatchObject({ + status_code: 403, + body: { code: "access_denied" }, + }); + }); + + it("rejects an out-of-scope import before writing any lesson", async () => { + const candidate = (await sdk.trigger("mem::lesson-save", { + ...lessonInput("import-hidden", REPO_TWO), + accessContext: systemLessonAccessContext(), + })) as { lesson: Lesson }; + await kv.delete("mem:lessons", candidate.lesson.id); + const exportData: ExportData = { + version: "0.9.27", + exportedAt: "2026-08-03T01:00:00.000Z", + sessions: [], + observations: {}, + memories: [], + summaries: [], + lessons: [candidate.lesson], + }; + + const response = (await sdk.trigger("api::import", { + headers: headers("codex-token", "codex"), + body: { exportData, strategy: "merge" }, + })) as { status_code: number; body: { code: string } }; + + expect(response).toMatchObject({ + status_code: 403, + body: { code: "access_denied" }, + }); + expect(await kv.list("mem:lessons")).toEqual([]); + }); + + it("server-stamps global human approval and rejects agent approval", async () => { + const body = { + content: "Human-approved global causal lesson", + mechanismId: "authorization/global", + claim: "Global lessons require authenticated human approval.", + scope: { + ring: "global", + humanApproval: { + approvedAt: "2026-08-03T01:00:00.000Z", + reason: "Reviewed for global publication.", + }, + }, + sensitivity: "internal", + }; + const human = (await sdk.trigger("api::lesson-save", { + headers: headers("human-token", "patrick"), + body, + })) as { status_code: number; body: { lesson: Lesson } }; + const agent = (await sdk.trigger("api::lesson-save", { + headers: headers("codex-token", "codex"), + body, + })) as { status_code: number; body: { code: string } }; + + expect(human.status_code).toBe(201); + expect(human.body.lesson.scope?.humanApproval?.approvedBy).toBe("patrick"); + expect(human.body.lesson.scope?.humanApproval?.approvedAt).not.toBe( + body.scope.humanApproval.approvedAt, + ); + expect( + Date.parse(human.body.lesson.scope?.humanApproval?.approvedAt ?? ""), + ).not.toBeNaN(); + expect(agent).toMatchObject({ + status_code: 403, + body: { code: "access_denied" }, + }); + }); + + it("server-stamps correction actors across REST and MCP", async () => { + const saved = (await sdk.trigger("api::lesson-save", { + headers: headers("codex-token", "codex"), + body: lessonInput("correction"), + })) as { body: { lesson: Lesson } }; + + const deleted = (await sdk.trigger("api::lesson-delete", { + headers: headers("codex-token", "codex"), + body: { + lessonId: saved.body.lesson.id, + reason: "Evidence was invalidated.", + actor: "spoofed-human", + }, + })) as { status_code: number }; + const stored = await kv.get("mem:lessons", saved.body.lesson.id); + + expect(deleted.status_code).toBe(200); + expect(stored?.deletedBy).toBe("codex"); + + const mcp = (await sdk.trigger("mcp::tools::call", { + headers: headers("readonly-token", "readonly"), + body: { + name: "memory_lesson_delete", + arguments: { + lessonId: saved.body.lesson.id, + reason: "Read-only caller cannot mutate.", + actor: "codex", + }, + }, + })) as { status_code: number; body: { content: Array<{ text: string }> } }; + expect(mcp.status_code).toBe(200); + expect(JSON.parse(mcp.body.content[0].text)).toMatchObject({ + success: false, + code: "access_denied", + }); + }); +}); diff --git a/test/mcp-standalone-proxy.test.ts b/test/mcp-standalone-proxy.test.ts index c74732d994..cf5bbd5da3 100644 --- a/test/mcp-standalone-proxy.test.ts +++ b/test/mcp-standalone-proxy.test.ts @@ -28,6 +28,28 @@ describe("@agentmemory/mcp standalone — server proxy (issue #159)", () => { resetHandleForTests(); globalThis.fetch = originalFetch; delete process.env["AGENTMEMORY_URL"]; + delete process.env["AGENT_ID"]; + delete process.env["AGENTMEMORY_CALLER_TOKEN"]; + }); + + it("forwards server-resolved caller identity headers without exposing them in payloads", async () => { + process.env["AGENT_ID"] = "codex"; + process.env["AGENTMEMORY_CALLER_TOKEN"] = "caller-secret"; + let requestHeaders: Headers | undefined; + installFetch((url, init) => { + if (url.endsWith("/agentmemory/livez")) { + return new Response("ok", { status: 200 }); + } + requestHeaders = new Headers(init?.headers); + return new Response(JSON.stringify({ sessions: [] }), { status: 200 }); + }); + + await handleToolCall("memory_sessions", { limit: 1 }); + + expect(requestHeaders?.get("x-agentmemory-agent-id")).toBe("codex"); + expect(requestHeaders?.get("x-agentmemory-caller-token")).toBe( + "caller-secret", + ); }); it("proxies memory_sessions to GET /agentmemory/sessions when server is up", async () => { From 223b2bffd440619365fd795e048d5d7be7a0dcd6 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Mon, 3 Aug 2026 00:38:24 -0400 Subject: [PATCH 37/43] fix: fail closed on lesson access edge cases --- README.md | 5 +- .../2026-08-03-causal-lesson-access-v2.md | 3 +- src/functions/lesson-access.ts | 36 ++++++++++-- src/functions/lessons.ts | 57 +++++++++++++++---- test/lesson-access.test.ts | 20 +++++++ test/lesson-authorization.test.ts | 22 +++++++ 6 files changed, 124 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 011702c8c2..48c3ca08a1 100644 --- a/README.md +++ b/README.md @@ -1603,8 +1603,9 @@ Set `AGENTMEMORY_LESSON_ACCESS_MODE=enforce` and the server. Set a unique high-entropy `AGENTMEMORY_CALLER_TOKEN` and matching `AGENT_ID` on each client. Keep raw tokens out of the policy and source control; the policy contains only `tokenSha256`. Missing/invalid policy or credentials -fail closed after enforcement is enabled. Internal scheduled functions use an -explicit service context; that service cannot approve global lessons. +fail closed after enforcement is enabled. An invalid access-mode value or +non-absolute policy path also fails closed. Internal scheduled functions use +an explicit service context; that service cannot approve global lessons. Automatic contradiction discovery and hybrid/vector lesson retrieval remain separate follow-up work. See diff --git a/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md b/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md index 8b63835ba4..b95515e334 100644 --- a/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md +++ b/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md @@ -22,7 +22,8 @@ self-assert an actor. returns 503; missing or invalid credentials return 401. The mode is selected with `AGENTMEMORY_LESSON_ACCESS_MODE`. The policy path is -selected with `AGENTMEMORY_LESSON_CALLER_POLICY_FILE`. +selected with `AGENTMEMORY_LESSON_CALLER_POLICY_FILE` and must be absolute. +Unknown mode values and relative policy paths fail closed. ## Caller policy diff --git a/src/functions/lesson-access.ts b/src/functions/lesson-access.ts index a445ec7a3d..ef7483d27c 100644 --- a/src/functions/lesson-access.ts +++ b/src/functions/lesson-access.ts @@ -5,6 +5,7 @@ import { timingSafeEqual, } from "node:crypto"; import { readFileSync } from "node:fs"; +import { isAbsolute } from "node:path"; import { getAgentId, getEnvVar } from "../config.js"; import type { Lesson, @@ -100,7 +101,19 @@ function nonEmptyString( } function normalizeMode(value: unknown): LessonAccessMode { - return value === "enforce" ? "enforce" : "classify"; + const normalized = typeof value === "string" ? value.trim() : value; + if ( + normalized === undefined || + normalized === null || + normalized === "" || + normalized === "classify" + ) { + return "classify"; + } + if (normalized === "enforce") return "enforce"; + throw new Error( + "AGENTMEMORY_LESSON_ACCESS_MODE must be classify or enforce", + ); } export function getLessonAccessMode(): LessonAccessMode { @@ -357,7 +370,20 @@ export function resolveLessonBoundaryAccess( headers?: Record, options: ResolveLessonBoundaryAccessOptions = {}, ): LessonBoundaryAccessResult { - const mode = options.mode ?? getLessonAccessMode(); + let mode: LessonAccessMode; + try { + mode = + options.mode === undefined + ? getLessonAccessMode() + : normalizeMode(options.mode); + } catch { + return { + success: false, + statusCode: 503, + error: "lesson caller policy is unavailable", + code: "caller_policy_unavailable", + }; + } const claimedAgentId = headerValue(headers, "x-agentmemory-agent-id"); if (mode === "classify") { return { @@ -375,10 +401,12 @@ export function resolveLessonBoundaryAccess( getEnvVar("AGENTMEMORY_LESSON_CALLER_POLICY_FILE"); policy = options.policy ? parseLessonCallerPolicy(options.policy) - : policyPath + : policyPath && isAbsolute(policyPath) ? loadPolicyFile(policyPath) : (() => { - throw new Error("lesson caller policy file is not configured"); + throw new Error( + "lesson caller policy file must be configured with an absolute path", + ); })(); } catch { return { diff --git a/src/functions/lessons.ts b/src/functions/lessons.ts index 547ebe1962..c9b97e1459 100644 --- a/src/functions/lessons.ts +++ b/src/functions/lessons.ts @@ -89,27 +89,52 @@ async function validateContradictionRelations( kv: StateKV, source: Lesson, targetIds: string[], -): Promise { + accessContext: LessonAccessContext, +): Promise< + | { code: "access_denied" | "invalid_relation"; error: string } + | null +> { for (const targetId of targetIds) { if ( targetId === source.id || normalizeLesson(source).idAliases.includes(targetId) ) { - return "contradictedByLessonIds must not contain the lesson itself"; + return { + code: "invalid_relation", + error: "contradictedByLessonIds must not contain the lesson itself", + }; } const target = await kv.get(KV.lessons, targetId); if (!target) { - return `contradiction target does not exist: ${targetId}`; + return { + code: "invalid_relation", + error: `contradiction target does not exist: ${targetId}`, + }; + } + if (!canReadLesson(target, accessContext)) { + return { + code: "access_denied", + error: "lesson access denied for contradiction target", + }; } try { if (!isLessonRecallable(target)) { - return `contradiction target must be active: ${targetId}`; + return { + code: "invalid_relation", + error: `contradiction target must be active: ${targetId}`, + }; } if (!sameLessonContradictionScope(source, target)) { - return `contradiction target must share durable scope and project label: ${targetId}`; + return { + code: "invalid_relation", + error: `contradiction target must share durable scope and project label: ${targetId}`, + }; } } catch { - return `contradiction target is invalid: ${targetId}`; + return { + code: "invalid_relation", + error: `contradiction target is invalid: ${targetId}`, + }; } } return null; @@ -341,13 +366,17 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { ) { return accessFailure("strengthen"); } - const contradictionError = await validateContradictionRelations( + const contradictionFailure = await validateContradictionRelations( kv, existing, input.contradictedByLessonIds, + accessContext, ); - if (contradictionError) { - return correctionFailure("invalid_relation", contradictionError); + if (contradictionFailure) { + return correctionFailure( + contradictionFailure.code, + contradictionFailure.error, + ); } reinforceLesson(existing); if (input.context && !existing.context) { @@ -421,13 +450,17 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { contentFingerprint: lessonContentFingerprint(input), }; - const contradictionError = await validateContradictionRelations( + const contradictionFailure = await validateContradictionRelations( kv, lesson, input.contradictedByLessonIds, + accessContext, ); - if (contradictionError) { - return correctionFailure("invalid_relation", contradictionError); + if (contradictionFailure) { + return correctionFailure( + contradictionFailure.code, + contradictionFailure.error, + ); } await kv.set(KV.lessons, lesson.id, lesson); diff --git a/test/lesson-access.test.ts b/test/lesson-access.test.ts index 05c1055c65..8c29e07d6b 100644 --- a/test/lesson-access.test.ts +++ b/test/lesson-access.test.ts @@ -174,6 +174,26 @@ describe("lesson caller policy", () => { statusCode: 401, code: "caller_authentication_failed", }); + expect( + resolveLessonBoundaryAccess( + { + "x-agentmemory-agent-id": "codex", + "x-agentmemory-caller-token": "codex-token", + }, + { mode: "enforce", policyPath: "relative/callers.json" }, + ), + ).toMatchObject({ + success: false, + statusCode: 503, + code: "caller_policy_unavailable", + }); + expect( + resolveLessonBoundaryAccess({}, { mode: "invalid" as never }), + ).toMatchObject({ + success: false, + statusCode: 503, + code: "caller_policy_unavailable", + }); }); it("keeps legacy behavior explicit in classify mode", () => { diff --git a/test/lesson-authorization.test.ts b/test/lesson-authorization.test.ts index 4b095031ef..8c617d3088 100644 --- a/test/lesson-authorization.test.ts +++ b/test/lesson-authorization.test.ts @@ -163,6 +163,28 @@ describe("lesson authorization boundaries", () => { expect(await kv.list("mem:lessons")).toHaveLength(1); }); + it("cannot create a contradiction relation to a lesson above its clearance", async () => { + const hidden = (await sdk.trigger("mem::lesson-save", { + ...lessonInput("restricted-target"), + sensitivity: "restricted", + accessContext: systemLessonAccessContext(), + })) as { lesson: Lesson }; + + const response = (await sdk.trigger("api::lesson-save", { + headers: headers("codex-token", "codex"), + body: { + ...lessonInput("relation-source"), + contradictedByLessonIds: [hidden.lesson.id], + }, + })) as { status_code: number; body: { code: string } }; + + expect(response).toMatchObject({ + status_code: 403, + body: { code: "access_denied" }, + }); + expect(await kv.list("mem:lessons")).toHaveLength(1); + }); + it("filters list, recall, and export totals without revealing other scopes", async () => { const system = systemLessonAccessContext(); await sdk.trigger("mem::lesson-save", { From 7f7437dfbaa41b081f1b80b05260aa4c57ad7767 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Mon, 3 Aug 2026 01:19:54 -0400 Subject: [PATCH 38/43] fix: close causal lesson access boundaries --- .env.example | 4 + README.md | 36 ++- .../2026-08-03-causal-lesson-access-v2.md | 44 +++- integrations/hermes/README.md | 4 +- integrations/hermes/__init__.py | 16 +- integrations/openclaw/README.md | 10 + integrations/openclaw/plugin.mjs | 6 +- integrations/pi/README.md | 4 +- integrations/pi/index.ts | 5 +- integrations/pi/security.ts | 2 +- plugin/skills/agentmemory-config/REFERENCE.md | 4 +- .../skills/agentmemory-mcp-tools/REFERENCE.md | 4 +- src/cli.ts | 4 +- src/functions/audit.ts | 94 ++++++- src/functions/consolidation-pipeline.ts | 19 +- src/functions/crystallize.ts | 122 +++++++-- src/functions/diagnostics.ts | 61 ++++- src/functions/evict.ts | 18 +- src/functions/export-import.ts | 167 +++++++++++- src/functions/governance.ts | 1 + src/functions/lesson-access.ts | 126 ++++++++- src/functions/lessons.ts | 40 +-- src/functions/obsidian-export.ts | 48 +++- src/functions/reflect.ts | 121 ++++++++- src/functions/replay.ts | 109 +++----- src/index.ts | 6 +- src/mcp/http-error.ts | 48 ++++ src/mcp/http.ts | 7 +- src/mcp/rest-proxy.ts | 8 +- src/mcp/server.ts | 53 +++- src/mcp/tools-registry.ts | 9 +- src/triggers/api.ts | 130 ++++++++- src/types.ts | 1 + src/viewer/server.ts | 11 + test/cli-replay-headers.test.ts | 102 ++++++++ test/consolidation-pipeline.test.ts | 2 + test/diagnostics.test.ts | 124 +++++++++ test/governance.test.ts | 181 ++++++++++++- test/hermes-plugin.test.ts | 51 ++++ test/integration-plaintext-http.test.ts | 21 ++ test/lesson-access.test.ts | 17 ++ test/lesson-authorization.test.ts | 246 +++++++++++++++++- test/mcp-http.test.ts | 20 ++ test/mcp-llm-tools.test.ts | 9 +- test/mcp-standalone-proxy.test.ts | 29 ++- test/replay-import-key.test.ts | 46 +++- test/viewer-host.test.ts | 77 ++++++ 47 files changed, 2049 insertions(+), 218 deletions(-) create mode 100644 src/mcp/http-error.ts create mode 100644 test/cli-replay-headers.test.ts diff --git a/.env.example b/.env.example index beb6a4ba01..d2e16dd212 100644 --- a/.env.example +++ b/.env.example @@ -97,6 +97,10 @@ # AGENTMEMORY_LESSON_CALLER_POLICY_FILE=/etc/agentmemory/lesson-callers.json # AGENT_ID=codex # AGENTMEMORY_CALLER_TOKEN=unique-client-token +# Give the viewer its own server-side read principal. These values are added +# only by the viewer proxy and are never delivered to browser JavaScript. +# AGENTMEMORY_VIEWER_AGENT_ID=viewer-service +# AGENTMEMORY_VIEWER_CALLER_TOKEN=unique-viewer-token # ----------------------------------------------------------------------------- # 4. Search tuning diff --git a/README.md b/README.md index 48c3ca08a1..0ab1d0d094 100644 --- a/README.md +++ b/README.md @@ -1587,8 +1587,9 @@ preserves the PR1 behavior. `enforce` resolves a caller from a per-client token and server-side SHA-256 token-digest policy, then applies exact durable-scope grants and the sensitivity order `public < internal < confidential < restricted`. Write grants imply read; -global is not a wildcard; legacy implicit-worktree rows require the -`lesson:legacy-worktree` capability. +global is not a wildcard. `lesson:legacy-worktree` is a read-only compatibility +exception for existing implicit-worktree rows; new enforced caller writes +require an explicit durable scope. In enforce mode, REST and MCP arguments cannot self-assert identity. The server stamps correction actors plus global `humanApproval.approvedBy` and @@ -1596,7 +1597,22 @@ stamps correction actors plus global `humanApproval.approvedBy` and `lesson:approve-global` may approve global scope. Portable/Obsidian exports require `lesson:export`, imports require `lesson:import`, and unauthorized lessons are removed before list, recall, -context, smart-search, reflection, and export counts are computed. +context, smart-search, reflection, audit/diagnostic projections, crystal and +insight reads, and export counts are computed. In enforcement mode, a portable +full-database import/export or an Obsidian export containing lessons or +crystals is an operator operation: the caller must have `restricted` clearance, +`lesson:all-scopes`, and the matching export/import capability. A capability +alone is intentionally insufficient. + +Replay, crystallization, consolidation, eviction, reflection, audit, and +diagnostic paths preserve the resolved caller context instead of manufacturing +service authority. New crystals record `sourceLessonIds`; synthesized insights +retain lesson/crystal provenance, and every public projection requires all +referenced lessons to be readable. Crystal lesson values must also correspond +positionally to the referenced lesson ID or authoritative lesson content, so a +readable ID cannot launder unrelated prose. Legacy crystals that contain +lesson prose but no lesson IDs are visible only to an all-scopes principal in +enforcement mode. Set `AGENTMEMORY_LESSON_ACCESS_MODE=enforce` and `AGENTMEMORY_LESSON_CALLER_POLICY_FILE=/absolute/path/lesson-callers.json` on @@ -1607,6 +1623,20 @@ fail closed after enforcement is enabled. An invalid access-mode value or non-absolute policy path also fails closed. Internal scheduled functions use an explicit service context; that service cannot approve global lessons. +The viewer must use a separate server-side read principal configured with +`AGENTMEMORY_VIEWER_AGENT_ID` and `AGENTMEMORY_VIEWER_CALLER_TOKEN`. Browser +headers are ignored and the raw viewer token is never embedded in HTML. Pi, +Hermes, OpenClaw, the MCP shims, and the replay CLI forward the caller headers; +their plaintext-HTTP guard treats either the bearer secret or caller token as +a credential. + +Import preflights collection shapes and all lesson authorization before its +first write. The lesson batch restores exact preimages if a lesson write fails. +The underlying KV API has no transaction spanning every non-lesson collection, +so a later storage failure during a full multi-collection import can still +require operator repair; this is existing portable-import behavior, not an +all-or-nothing database transaction. + Automatic contradiction discovery and hybrid/vector lesson retrieval remain separate follow-up work. See [Causal Lesson Schema v1](docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md) diff --git a/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md b/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md index b95515e334..10c74a25b8 100644 --- a/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md +++ b/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md @@ -43,7 +43,7 @@ Unknown mode values and relative policy paths fail closed. "access": "write" } ], - "capabilities": ["lesson:export"] + "capabilities": [] } ] } @@ -64,8 +64,9 @@ Supported capabilities are: The sensitivity order is `public < internal < confidential < restricted`. Access requires both adequate clearance and a matching scope grant unless `lesson:all-scopes` is present. -Legacy rows normalized to an implicit worktree scope additionally require -`lesson:legacy-worktree`. +`lesson:legacy-worktree` is a read-only exception for existing rows normalized +to an implicit worktree scope. New enforced writes require an explicit durable +scope unless they originate from the sealed internal service context. ## Boundary contract @@ -76,9 +77,15 @@ Clients send: The token is matched to `tokenSha256` with a timing-safe digest comparison. If the optional claimed ID is present it must match the policy principal. The MCP -shim, streamable HTTP MCP bridge, bundled hooks, Pi, OpenCode, and OpenClaw -integrations forward these headers from `AGENTMEMORY_CALLER_TOKEN` and -`AGENT_ID`. +shim, streamable HTTP MCP bridge, bundled hooks, Pi, OpenCode, Hermes, and +OpenClaw integrations forward these headers from `AGENTMEMORY_CALLER_TOKEN` +and `AGENT_ID`. + +The viewer uses a separate server-side identity from +`AGENTMEMORY_VIEWER_AGENT_ID` and `AGENTMEMORY_VIEWER_CALLER_TOKEN`. It ignores +browser-supplied caller identity headers and never embeds the caller token in +the rendered document. Integration plaintext-HTTP guards treat either +`AGENTMEMORY_SECRET` or `AGENTMEMORY_CALLER_TOKEN` as a credential. Request bodies and MCP arguments are explicitly whitelisted. A supplied `accessContext` is never forwarded by a public boundary. Direct iii function @@ -91,15 +98,30 @@ principal. - Save, strengthen, retract, and supersede require read/write authority for the affected durable scope and adequate sensitivity clearance. -- Recall, list, injected context, smart search, reflection, and exports filter - unauthorized lessons before totals, ranking, or provider prompts. +- Recall, list, injected context, smart search, reflection, audit/diagnostic + projections, crystal/insight reads, and exports filter unauthorized lessons + before totals, ranking, provider prompts, or derived content are returned. +- Replay, crystallization, consolidation, eviction, reflection, audit, and + diagnostics propagate a resolved caller. Scheduled maintenance alone may + receive the sealed internal service context. +- Crystals persist `sourceLessonIds`; insights retain their lesson/crystal + provenance. Every referenced lesson must be readable, and each crystal + lesson value must correspond to its positional source lesson ID or + authoritative content. A legacy crystal with lesson prose but no source IDs + requires all-scopes authority in enforcement mode. - Global saves require an authenticated `human` principal with `lesson:approve-global`; the server stamps `humanApproval.approvedBy` and `humanApproval.approvedAt`. - In enforce mode correction actors are server-stamped. -- Portable and Obsidian lesson exports require `lesson:export`. -- Imports require `lesson:import`, validate every incoming lesson before any - write, and require authority for overwritten or replace-deleted lessons. +- Portable full-database export/import and Obsidian exports containing lessons + or crystals are operator-only in enforcement mode: `restricted` clearance, + `lesson:all-scopes`, and the matching `lesson:export` or `lesson:import` + capability are all required. +- Imports preflight collection shapes and every incoming lesson before any + write, require authority for overwritten or replace-deleted lessons, and + restore exact lesson preimages if a lesson-batch write fails. The KV + abstraction has no transaction spanning all non-lesson collections, so a + later full-import storage failure can still require operator repair. - The internal service context can run scheduled maintenance across scopes but cannot approve global publication. diff --git a/integrations/hermes/README.md b/integrations/hermes/README.md index ba06c105cf..682f2d036b 100644 --- a/integrations/hermes/README.md +++ b/integrations/hermes/README.md @@ -105,7 +105,9 @@ The plugin auto-detects the running server and hooks into the Hermes agent loop. |---|---|---| | `AGENTMEMORY_URL` | `http://localhost:3111` | agentmemory server URL | | `AGENTMEMORY_SECRET` | (none) | Auth token for protected instances | -| `AGENTMEMORY_REQUIRE_HTTPS` | (off) | When set to `1`, refuse to send the bearer token over plaintext HTTP to a non-loopback host. Sends only when `AGENTMEMORY_URL` is `https://...` or points at `localhost`/`127.0.0.1`/`::1`. With this off, the plugin warns once on stderr but still sends. | +| `AGENT_ID` | (none) | Optional claimed principal ID; must match the caller-token policy entry when lesson enforcement is enabled | +| `AGENTMEMORY_CALLER_TOKEN` | (none) | Per-client raw lesson-access token; keep it out of source control | +| `AGENTMEMORY_REQUIRE_HTTPS` | (off) | When set to `1`, refuse to send either credential over plaintext HTTP to a non-loopback host. Sends only when `AGENTMEMORY_URL` is `https://...` or points at `localhost`/`127.0.0.1`/`::1`. With this off, the plugin warns once on stderr but still sends. | The plugin reads `~/.agentmemory/.env` (or `$XDG_CONFIG_HOME/agentmemory/.env`) at import time and populates any missing values into the process environment via `os.environ.setdefault`. Anything you set in the shell takes precedence; the file is only used to fill gaps. This means `hermes memory status` reports the plugin as available even when the agentmemory service is launched by systemd or another process manager that loads `~/.agentmemory/.env` directly without exporting it to the Hermes CLI shell (#250). diff --git a/integrations/hermes/__init__.py b/integrations/hermes/__init__.py index 2933632d0a..7209078a3f 100644 --- a/integrations/hermes/__init__.py +++ b/integrations/hermes/__init__.py @@ -122,7 +122,7 @@ def _uses_plaintext_bearer_auth(base: str, secret: str = "") -> bool: def _plaintext_bearer_auth_message(base: str) -> str: - return f"agentmemory: AGENTMEMORY_SECRET is configured for plaintext HTTP to {base}. Bearer tokens and memory payloads can be observed on the network; use HTTPS or an SSH tunnel." + return f"agentmemory: an AGENTMEMORY_SECRET or AGENTMEMORY_CALLER_TOKEN credential is configured for plaintext HTTP to {base}. Bearer tokens and memory payloads can be observed on the network; use HTTPS or an SSH tunnel." def _warn_plaintext_bearer_auth(message: str) -> None: @@ -156,9 +156,15 @@ def _api(base: str, path: str, body: dict | None = None, method: str = "POST", s url = f"{base}/agentmemory/{path}" headers = {"Content-Type": "application/json"} auth = secret or os.environ.get("AGENTMEMORY_SECRET", "") - _check_plaintext_bearer_guard(base, auth) + caller_token = os.environ.get("AGENTMEMORY_CALLER_TOKEN", "") + _check_plaintext_bearer_guard(base, auth or caller_token) if auth: headers["Authorization"] = f"Bearer {auth}" + agent_id = os.environ.get("AGENT_ID", "") + if agent_id: + headers["X-AgentMemory-Agent-Id"] = agent_id + if caller_token: + headers["X-AgentMemory-Caller-Token"] = caller_token data = json.dumps(body).encode() if body else None req = Request(url, data=data, headers=headers, method=method) @@ -190,7 +196,11 @@ def initialize(self, session_id: str, **kwargs: Any) -> None: self._session_id = session_id self._project = kwargs.get("cwd", os.getcwd()) if os.environ.get("AGENTMEMORY_REQUIRE_HTTPS") == "1": - _check_plaintext_bearer_guard(self._base, os.environ.get("AGENTMEMORY_SECRET", "")) + _check_plaintext_bearer_guard( + self._base, + os.environ.get("AGENTMEMORY_SECRET", "") + or os.environ.get("AGENTMEMORY_CALLER_TOKEN", ""), + ) _api(self._base, "session/start", { "sessionId": session_id, diff --git a/integrations/openclaw/README.md b/integrations/openclaw/README.md index 1fe774ae85..9dd06b83b3 100644 --- a/integrations/openclaw/README.md +++ b/integrations/openclaw/README.md @@ -130,6 +130,16 @@ What the plugin does: - captures completed conversation turns after the agent finishes (via the `agent_end` hook) - shares the same backend with Claude Code, Codex CLI, Gemini CLI, Hermes, pi, and other agents +### Environment variables + +| Variable | Default | Description | +|---|---|---| +| `AGENTMEMORY_URL` | `http://localhost:3111` | agentmemory server URL | +| `AGENTMEMORY_SECRET` | (none) | Bearer token for protected instances | +| `AGENT_ID` | (none) | Optional claimed principal ID; must match the caller-token policy entry when lesson enforcement is enabled | +| `AGENTMEMORY_CALLER_TOKEN` | (none) | Per-client raw lesson-access token; keep it out of source control | +| `AGENTMEMORY_REQUIRE_HTTPS` | (off) | When set to `1`, refuse to send either credential over plaintext HTTP to a non-loopback host. With this off, the plugin warns once but still sends. | + ### Memory runtime (current scope) The plugin currently registers a `promptBuilder` only — not a full `MemoryPluginRuntime` adapter. OpenClaw's `MemoryRuntimeBackendConfig` type today is `{ backend: "builtin" }` or `{ backend: "qmd" }`; both are openclaw-internal backends that don't fit agentmemory's external REST shape. The hook-driven recall + capture flow above is the working integration path. If you need OpenClaw's in-process memory-runtime APIs (e.g. `getMemorySearchManager`) backed by agentmemory, file an upstream request against `openclaw` for an `"external"` backend type and we'll wire `runtime` here once the contract supports it. diff --git a/integrations/openclaw/plugin.mjs b/integrations/openclaw/plugin.mjs index 48b020c062..d4a6bb6efb 100644 --- a/integrations/openclaw/plugin.mjs +++ b/integrations/openclaw/plugin.mjs @@ -89,7 +89,7 @@ function usesPlaintextBearerAuth(baseUrl, secret) { } function plaintextBearerAuthMessage(baseUrl) { - return `agentmemory: AGENTMEMORY_SECRET is configured for plaintext HTTP to ${baseUrl}. Bearer tokens and memory payloads can be observed on the network; use HTTPS or an SSH tunnel.`; + return `agentmemory: an AGENTMEMORY_SECRET or AGENTMEMORY_CALLER_TOKEN credential is configured for plaintext HTTP to ${baseUrl}. Bearer tokens and memory payloads can be observed on the network; use HTTPS or an SSH tunnel.`; } export function createPlaintextBearerAuthGuard(warn, env) { @@ -116,11 +116,11 @@ function createClient(cfg, api) { (message) => api.logger.warn?.(message), ); if (process.env.AGENTMEMORY_REQUIRE_HTTPS === "1") { - guardPlaintextBearerAuth(baseUrl, secret); + guardPlaintextBearerAuth(baseUrl, secret || callerToken); } async function postJson(path, payload) { - guardPlaintextBearerAuth(baseUrl, secret); + guardPlaintextBearerAuth(baseUrl, secret || callerToken); const headers = { "Content-Type": "application/json" }; if (secret) headers.Authorization = `Bearer ${secret}`; if (agentId) headers["X-AgentMemory-Agent-Id"] = agentId; diff --git a/integrations/pi/README.md b/integrations/pi/README.md index 85a2758e9f..83d5afcc04 100644 --- a/integrations/pi/README.md +++ b/integrations/pi/README.md @@ -53,7 +53,9 @@ If you place it under `~/.pi/agent/extensions/agentmemory/`, pi will also auto-d |---|---|---| | `AGENTMEMORY_URL` | `http://localhost:3111` | agentmemory server URL | | `AGENTMEMORY_SECRET` | (none) | Bearer token for protected instances | -| `AGENTMEMORY_REQUIRE_HTTPS` | (off) | When set to `1`, refuse to send a bearer token over plaintext HTTP to a non-loopback host. Sends the token only when `AGENTMEMORY_URL` is `https://...` or points at `localhost`/`127.0.0.1`/`::1`. With this off, the plugin warns once but still sends. | +| `AGENT_ID` | (none) | Optional claimed principal ID; must match the caller-token policy entry when lesson enforcement is enabled | +| `AGENTMEMORY_CALLER_TOKEN` | (none) | Per-client raw lesson-access token; keep it out of source control | +| `AGENTMEMORY_REQUIRE_HTTPS` | (off) | When set to `1`, refuse to send either credential over plaintext HTTP to a non-loopback host. Sends only when `AGENTMEMORY_URL` is `https://...` or points at `localhost`/`127.0.0.1`/`::1`. With this off, the plugin warns once but still sends. | ## Smoke test diff --git a/integrations/pi/index.ts b/integrations/pi/index.ts index 24069b921e..0c4f6f7db5 100644 --- a/integrations/pi/index.ts +++ b/integrations/pi/index.ts @@ -97,7 +97,7 @@ async function callAgentMemory( const secret = process.env.AGENTMEMORY_SECRET; const agentId = process.env.AGENT_ID; const callerToken = process.env.AGENTMEMORY_CALLER_TOKEN; - guardPlaintextBearerAuth(baseUrl, secret); + guardPlaintextBearerAuth(baseUrl, secret || callerToken); if (options?.body !== undefined) headers["Content-Type"] = "application/json"; if (secret) headers.Authorization = `Bearer ${secret}`; if (agentId) headers["X-AgentMemory-Agent-Id"] = agentId; @@ -120,7 +120,8 @@ export default function agentmemoryExtension(pi: ExtensionAPI) { if (process.env.AGENTMEMORY_REQUIRE_HTTPS === "1") { guardPlaintextBearerAuth( normalizeBaseUrl(process.env.AGENTMEMORY_URL || DEFAULT_URL), - process.env.AGENTMEMORY_SECRET, + process.env.AGENTMEMORY_SECRET || + process.env.AGENTMEMORY_CALLER_TOKEN, ); } let sessionId = `ephemeral-${crypto.randomUUID().slice(0, 8)}`; diff --git a/integrations/pi/security.ts b/integrations/pi/security.ts index 4db0e5295c..c34d95161f 100644 --- a/integrations/pi/security.ts +++ b/integrations/pi/security.ts @@ -15,7 +15,7 @@ export function usesPlaintextBearerAuth(baseUrl: string, secret?: string): boole } export function plaintextBearerAuthMessage(baseUrl: string): string { - return `agentmemory: AGENTMEMORY_SECRET is configured for plaintext HTTP to ${baseUrl}. Bearer tokens and memory payloads can be observed on the network; use HTTPS or an SSH tunnel.`; + return `agentmemory: an AGENTMEMORY_SECRET or AGENTMEMORY_CALLER_TOKEN credential is configured for plaintext HTTP to ${baseUrl}. Bearer tokens and memory payloads can be observed on the network; use HTTPS or an SSH tunnel.`; } export function createPlaintextBearerAuthGuard( diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md index af028664f6..277156716c 100644 --- a/plugin/skills/agentmemory-config/REFERENCE.md +++ b/plugin/skills/agentmemory-config/REFERENCE.md @@ -3,7 +3,7 @@ Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded. -Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 55 recognized variables: +Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 57 recognized variables: - `AGENTMEMORY_AGENT_SCOPE` - `AGENTMEMORY_ALLOW_AGENT_SDK` @@ -58,6 +58,8 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e - `AGENTMEMORY_URL` - `AGENTMEMORY_USE_DOCKER` - `AGENTMEMORY_VERBOSE` +- `AGENTMEMORY_VIEWER_AGENT_ID` +- `AGENTMEMORY_VIEWER_CALLER_TOKEN` - `AGENTMEMORY_VIEWER_HOST` - `AGENTMEMORY_VIEWER_URL` diff --git a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md index 8329a2de09..95085e99ee 100644 --- a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md +++ b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md @@ -21,7 +21,7 @@ agentmemory exposes 60 MCP tools. 7 are in the lean core set (`--tools core` or | `memory_diagnose` | yes | `categories`: string | Run health checks across all subsystems (actions, leases, sentinels, sketches, signals, sessions, memories, mesh). Identifies stuck, orphaned, and inconsistent state. | | `memory_diagnostic_followup` | | none | Read the smart-search follow-up-rate diagnostic counters. This is a read-only directional signal and may overcount legitimate query refinement. | | `memory_enrich_session` | | `sessionId`*: string, `lookback`: number, `lookahead`: number, `minImportance`: number | LLM-enrich qualifying observations in a session and persist enriched chunks. This is a state-changing, paid-provider operation. | -| `memory_export` | | none | Export all memory data as JSON. | +| `memory_export` | | none | Export all memory data as JSON. In lesson enforcement mode this is an operator-only operation requiring restricted clearance, lesson:all-scopes, and lesson:export. | | `memory_facet_query` | | `matchAll`: string, `matchAny`: string, `targetType`: string | Query targets by facet tags with AND/OR logic. Find all actions tagged priority:urgent AND team:backend. | | `memory_facet_tag` | | `targetId`*: string, `targetType`*: string, `dimension`*: string, `value`*: string | Attach a structured tag (dimension:value) to an action, memory, or observation for multi-dimensional categorization. | | `memory_file_history` | | `files`*: string, `sessionId`: string | Get past observations about specific files. | @@ -39,7 +39,7 @@ agentmemory exposes 60 MCP tools. 7 are in the lean core set (`--tools core` or | `memory_llm_smoke` | | none | Run a fixed, non-sensitive LLM connectivity probe. Returns provider/model evidence and performs no persistent AgentMemory or filesystem writes. | | `memory_mesh_sync` | | `peerId`: string, `direction`: string | Sync memories and actions with peer agentmemory instances for multi-agent collaboration. | | `memory_next` | | `project`: string, `agentId`: string | Get the single most important next action to work on. Combines dependency resolution, priority, and recency into a score. | -| `memory_obsidian_export` | | `vaultDir`: string, `types`: string | Export memories, lessons, and crystals as Obsidian-compatible Markdown files with YAML frontmatter and wikilinks for graph view. | +| `memory_obsidian_export` | | `vaultDir`: string, `types`: string | Export memories, lessons, and crystals as Obsidian-compatible Markdown files with YAML frontmatter and wikilinks for graph view. In lesson enforcement mode, lesson/crystal exports require restricted clearance, lesson:all-scopes, and lesson:export. | | `memory_patterns` | | `project`: string | Detect recurring patterns across sessions. | | `memory_profile` | | `project`*: string, `refresh`: string | User/project profile with top concepts and file patterns. | | `memory_recall` | yes | `query`*: string, `limit`: number, `format`: string, `token_budget`: number | Search past session observations for relevant context. Use when you need to recall what happened in previous sessions, find past decisions, or look up how a file was modified before. | diff --git a/src/cli.ts b/src/cli.ts index fdf8a2cd39..2d13eab11d 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -2778,9 +2778,7 @@ async function runImportJsonl(): Promise { if (pathArg) body["path"] = pathArg; if (maxFiles !== undefined) body["maxFiles"] = maxFiles; - const headers: Record = { "content-type": "application/json" }; - const secret = process.env["AGENTMEMORY_SECRET"]; - if (secret) headers["authorization"] = `Bearer ${secret}`; + const headers = cliJsonHeaders(); p.log.info(`Importing JSONL from ${pathArg || "~/.claude/projects"}…`); const spinner = p.spinner(); diff --git a/src/functions/audit.ts b/src/functions/audit.ts index 1e75b4b7d2..b8b2019489 100644 --- a/src/functions/audit.ts +++ b/src/functions/audit.ts @@ -1,7 +1,12 @@ -import type { AuditEntry } from "../types.js"; +import type { AuditEntry, Lesson } from "../types.js"; import { KV, generateId } from "../state/schema.js"; import type { StateKV } from "../state/kv.js"; import { logger } from "../logger.js"; +import { + buildLessonAccessIndex, + canReadLesson, + lessonAccessContextFromPayload, +} from "./lesson-access.js"; // Audit coverage policy (issue #125). // @@ -84,6 +89,7 @@ export async function queryAudit( dateFrom?: string; dateTo?: string; limit?: number; + accessContext?: unknown; }, ): Promise { const all = await kv.list(KV.audit); @@ -109,5 +115,91 @@ export async function queryAudit( entries = entries.filter((e) => new Date(e.timestamp).getTime() <= to); } + const accessContext = lessonAccessContextFromPayload( + filter?.accessContext, + ); + if (accessContext.mode === "enforce") { + const ordinaryEntries = entries.filter( + (entry) => !isLessonRelatedAuditEntry(entry), + ); + const lessonEntries = entries.filter(isLessonRelatedAuditEntry); + if (lessonEntries.length > 0) { + try { + const lessons = await kv.list(KV.lessons); + const lessonIndex = buildLessonAccessIndex(lessons); + const readableLessonEntries = lessonEntries.filter((entry) => { + if ( + !Array.isArray(entry.targetIds) || + entry.targetIds.length === 0 + ) { + return false; + } + try { + return entry.targetIds.every((id) => { + if (typeof id !== "string" || id.length === 0) return false; + const lesson = lessonIndex.get(id); + return lesson !== undefined && + canReadLesson(lesson, accessContext); + }); + } catch { + return false; + } + }); + const readableEntries = new Set(readableLessonEntries); + entries = entries.filter( + (entry) => + !isLessonRelatedAuditEntry(entry) || + readableEntries.has(entry), + ); + } catch { + // An unavailable or malformed authoritative lesson index cannot prove + // any lesson audit row is readable. Preserve unrelated audit rows. + entries = ordinaryEntries; + } + } + } + return entries.slice(0, filter?.limit || 100); } + +const LESSON_AUDIT_OPERATIONS = new Set([ + "lesson_save", + "lesson_recall", + "lesson_strengthen", + "lesson_delete", + "lesson_supersede", +]); + +function isLessonRelatedAuditEntry(entry: AuditEntry): boolean { + if (LESSON_AUDIT_OPERATIONS.has(entry.operation)) return true; + if ( + typeof entry.functionId === "string" && + (entry.functionId.startsWith("mem::lesson-") || + entry.functionId.startsWith("mem::import:lessons")) + ) { + return true; + } + + const details = + entry.details && typeof entry.details === "object" + ? entry.details + : undefined; + if (!details) return false; + if ( + "lessonId" in details || + "lessonIds" in details || + "sourceLessonIds" in details || + "canonicalizedIds" in details || + "lifecycleTransitions" in details + ) { + return true; + } + const stats = details.stats; + return Boolean( + stats && + typeof stats === "object" && + "lessons" in stats && + typeof (stats as Record).lessons === "number" && + (stats as Record).lessons > 0, + ); +} diff --git a/src/functions/consolidation-pipeline.ts b/src/functions/consolidation-pipeline.ts index 91af2dd415..d246af3523 100644 --- a/src/functions/consolidation-pipeline.ts +++ b/src/functions/consolidation-pipeline.ts @@ -17,7 +17,10 @@ import { import { recordAudit } from "./audit.js"; import { getConsolidationDecayDays, isConsolidationEnabled } from "../config.js"; import { logger } from "../logger.js"; -import { systemLessonAccessContext } from "./lesson-access.js"; +import { + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; function applyDecay( items: Array<{ @@ -49,11 +52,19 @@ export function registerConsolidationPipelineFunction( provider: MemoryProvider, ): void { sdk.registerFunction("mem::consolidate-pipeline", - async (data?: { tier?: string; force?: boolean; project?: string }) => { + async (data?: { + tier?: string; + force?: boolean; + project?: string; + accessContext?: LessonAccessContext; + }) => { if (!data?.force && !isConsolidationEnabled()) { return { success: false, skipped: true, reason: "Consolidation disabled: set CONSOLIDATION_ENABLED=true or configure an LLM provider (ANTHROPIC_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY / MINIMAX_API_KEY / OPENAI_BASE_URL / AGENTMEMORY_PROVIDER=agent-sdk)" }; } const tier = data?.tier || "all"; + const accessContext = lessonAccessContextFromPayload( + data?.accessContext, + ); const decayDays = getConsolidationDecayDays(); const results: Record = {}; @@ -139,7 +150,7 @@ export function registerConsolidationPipelineFunction( const reflectResult = await sdk.trigger({ function_id: "mem::reflect", payload: { maxClusters: 10, project: data?.project, - accessContext: systemLessonAccessContext(), + accessContext, } }); results.reflect = reflectResult; } catch (err) { @@ -253,7 +264,7 @@ export function registerConsolidationPipelineFunction( try { await sdk.trigger({ function_id: "mem::obsidian-export", - payload: { accessContext: systemLessonAccessContext() }, + payload: { accessContext }, }); results.obsidianExport = { success: true }; } catch (err) { diff --git a/src/functions/crystallize.ts b/src/functions/crystallize.ts index 6beba5ee1d..bcde792870 100644 --- a/src/functions/crystallize.ts +++ b/src/functions/crystallize.ts @@ -1,9 +1,20 @@ import type { ISdk } from "iii-sdk"; import type { StateKV } from "../state/kv.js"; import { KV, generateId } from "../state/schema.js"; -import type { Action, ActionEdge, Crystal, MemoryProvider } from "../types.js"; +import type { + Action, + ActionEdge, + Crystal, + Lesson, + MemoryProvider, +} from "../types.js"; import { persistAction } from "./action-store.js"; -import { systemLessonAccessContext } from "./lesson-access.js"; +import { + buildLessonAccessIndex, + canReadCrystal, + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; interface CrystalDigest { narrative: string; @@ -27,6 +38,7 @@ export function registerCrystallizeFunction( actionIds: string[]; sessionId?: string; project?: string; + accessContext?: LessonAccessContext; }) => { if (!data.actionIds || data.actionIds.length === 0) { return { success: false, error: "actionIds is required" }; @@ -54,17 +66,52 @@ export function registerCrystallizeFunction( ); const prompt = buildChainText(actions, relevantEdges); + const accessContext = lessonAccessContextFromPayload( + data.accessContext, + ); try { const response = await provider.summarize(CRYSTALLIZE_SYSTEM, prompt); const digest = parseDigest(response); + const crystalId = generateId("crys"); + const persistedLessons: string[] = []; + const sourceLessonIds: string[] = []; + + for (const lesson of digest.lessons) { + try { + const result = (await sdk.trigger({ + function_id: "mem::lesson-save", + payload: { + content: lesson, + context: digest.narrative, + confidence: 0.6, + project: data.project, + tags: [], + source: "crystal", + sourceIds: [crystalId], + accessContext, + }, + })) as { + success?: boolean; + lesson?: { id?: string }; + }; + if (result.success && typeof result.lesson?.id === "string") { + persistedLessons.push(lesson); + sourceLessonIds.push(result.lesson.id); + } + } catch {} + } const crystal: Crystal = { - id: generateId("crys"), + id: crystalId, narrative: digest.narrative, keyOutcomes: digest.keyOutcomes, filesAffected: digest.filesAffected, - lessons: digest.lessons, + lessons: + accessContext.mode === "classify" + ? digest.lessons + : persistedLessons, + sourceLessonIds, sourceActionIds: data.actionIds, sessionId: data.sessionId, project: data.project, @@ -73,26 +120,6 @@ export function registerCrystallizeFunction( await kv.set(KV.crystals, crystal.id, crystal); - await Promise.all( - digest.lessons.map((lesson) => - sdk - .trigger({ - function_id: "mem::lesson-save", - payload: { - content: lesson, - context: crystal.narrative, - confidence: 0.6, - project: data.project, - tags: [], - source: "crystal", - sourceIds: [crystal.id], - accessContext: systemLessonAccessContext(), - }, - }) - .catch(() => {}), - ), - ); - for (const action of actions) { const updated = { ...action, crystallizedInto: crystal.id }; await persistAction(kv, updated, { @@ -117,9 +144,30 @@ export function registerCrystallizeFunction( project?: string; sessionId?: string; limit?: number; + accessContext?: LessonAccessContext; }) => { const limit = data.limit ?? 20; + const accessContext = lessonAccessContextFromPayload( + data.accessContext, + ); let crystals = await kv.list(KV.crystals); + if (accessContext.mode === "enforce") { + try { + const lessonIndex = buildLessonAccessIndex( + await kv.list(KV.lessons), + ); + crystals = crystals.filter((crystal) => + canReadCrystal(crystal, lessonIndex, accessContext), + ); + } catch { + return { + success: false, + code: "lesson_state_unavailable", + error: "crystal access is unavailable", + crystals: [], + }; + } + } if (data.project) { crystals = crystals.filter((c) => c.project === data.project); @@ -138,7 +186,10 @@ export function registerCrystallizeFunction( ); sdk.registerFunction("mem::crystal-get", - async (data: { crystalId: string }) => { + async (data: { + crystalId: string; + accessContext?: LessonAccessContext; + }) => { if (!data.crystalId) { return { success: false, error: "crystalId is required" }; } @@ -147,6 +198,25 @@ export function registerCrystallizeFunction( if (!crystal) { return { success: false, error: "crystal not found" }; } + const accessContext = lessonAccessContextFromPayload( + data.accessContext, + ); + if (accessContext.mode === "enforce") { + try { + const lessonIndex = buildLessonAccessIndex( + await kv.list(KV.lessons), + ); + if (!canReadCrystal(crystal, lessonIndex, accessContext)) { + return { success: false, error: "crystal not found" }; + } + } catch { + return { + success: false, + code: "lesson_state_unavailable", + error: "crystal access is unavailable", + }; + } + } return { success: true, crystal }; }, @@ -157,6 +227,7 @@ export function registerCrystallizeFunction( olderThanDays?: number; project?: string; dryRun?: boolean; + accessContext?: LessonAccessContext; }) => { const olderThanDays = data.olderThanDays ?? 7; const dryRun = data.dryRun ?? false; @@ -216,6 +287,7 @@ export function registerCrystallizeFunction( const result = (await sdk.trigger({ function_id: "mem::crystallize", payload: { actionIds, project, + accessContext: data.accessContext, } })) as { success: boolean; crystal?: Crystal }; if (result.success && result.crystal) { diff --git a/src/functions/diagnostics.ts b/src/functions/diagnostics.ts index 6b15c515ce..c19a643560 100644 --- a/src/functions/diagnostics.ts +++ b/src/functions/diagnostics.ts @@ -9,6 +9,10 @@ import { persistAction, } from "./action-store.js"; import { isLessonListable } from "./lesson-model.js"; +import { + canReadLesson, + lessonAccessContextFromPayload, +} from "./lesson-access.js"; import type { Action, ActionEdge, @@ -51,7 +55,7 @@ const ONE_HOUR_MS = 60 * 60 * 1000; export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::diagnose", - async (data: { categories?: string[] }) => { + async (data: { categories?: string[]; accessContext?: unknown }) => { const categories = data.categories && data.categories.length > 0 ? data.categories.filter((c) => ALL_CATEGORIES.includes(c)) : ALL_CATEGORIES; @@ -405,16 +409,52 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { } if (categories.includes("lessons")) { + const lessonAccessContext = lessonAccessContextFromPayload( + data.accessContext, + ); // Counts only live lessons (deleted=true rows are tombstoned). // Catches bad confidence values that would silently break recall // scoring (memory_lesson_recall multiplies by confidence). - const lessons = await kv.list(KV.lessons); + let lessons: Lesson[]; + let lessonStateUnavailable = false; + if (lessonAccessContext.mode === "classify") { + lessons = await kv.list(KV.lessons); + } else { + try { + lessons = await kv.list(KV.lessons); + } catch { + lessonStateUnavailable = true; + checks.push({ + name: "lesson-projection-unavailable", + category: "lessons", + status: "fail", + message: + "Lesson diagnostics are unavailable because authoritative lesson state could not be read", + fixable: false, + }); + lessons = []; + } + } const live: Lesson[] = []; - let lessonIssues = 0; + let readableLessonCount = 0; + let lessonIssues = lessonStateUnavailable ? 1 : 0; + let projectionIncomplete = false; for (const lesson of lessons) { try { - if (isLessonListable(lesson)) live.push(lesson); + if ( + lessonAccessContext.mode === "enforce" && + !canReadLesson(lesson, lessonAccessContext) + ) { + continue; + } + const listable = isLessonListable(lesson); + readableLessonCount++; + if (listable) live.push(lesson); } catch (error) { + if (lessonAccessContext.mode === "enforce") { + projectionIncomplete = true; + continue; + } checks.push({ name: `lesson-invalid-structured:${lesson.id}`, category: "lessons", @@ -427,6 +467,17 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { lessonIssues++; } } + if (projectionIncomplete) { + checks.push({ + name: "lesson-projection-incomplete", + category: "lessons", + status: "fail", + message: + "Lesson diagnostics are incomplete because one or more authoritative rows were unreadable or invalid", + fixable: false, + }); + lessonIssues++; + } for (const l of live) { // Number.isFinite rejects NaN / Infinity / non-numbers; a // corrupted row passing those would silently survive the < / > @@ -453,7 +504,7 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { name: "lessons-ok", category: "lessons", status: "pass", - message: `All ${live.length} lessons are healthy (${lessons.length - live.length} tombstoned)`, + message: `All ${live.length} lessons are healthy (${readableLessonCount - live.length} tombstoned)`, fixable: false, }); } diff --git a/src/functions/evict.ts b/src/functions/evict.ts index 626f4ff1df..ba5c57ad0d 100644 --- a/src/functions/evict.ts +++ b/src/functions/evict.ts @@ -11,6 +11,7 @@ import { StateKV } from "../state/kv.js"; import { recordAudit } from "./audit.js"; import { deleteAccessLog } from "./access-tracker.js"; import { logger } from "../logger.js"; +import type { LessonAccessContext } from "./lesson-access.js"; interface EvictionConfig { staleSessionDays: number; @@ -79,11 +80,14 @@ async function recoverStaleSession( } } -async function runRecoveredSessionConsolidation(sdk: ISdk): Promise { +async function runRecoveredSessionConsolidation( + sdk: ISdk, + accessContext?: LessonAccessContext, +): Promise { try { await sdk.trigger({ function_id: "mem::consolidate-pipeline", - payload: { tier: "all" }, + payload: { tier: "all", accessContext }, }); } catch (err) { logger.warn("Recovered session consolidation failed", { @@ -94,7 +98,10 @@ async function runRecoveredSessionConsolidation(sdk: ISdk): Promise { export function registerEvictFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::evict", - async (data: { dryRun?: boolean }): Promise => { + async (data: { + dryRun?: boolean; + accessContext?: LessonAccessContext; + }): Promise => { const dryRun = data?.dryRun ?? false; const { decrementImageRef } = await import("./image-refs.js"); @@ -179,7 +186,10 @@ export function registerEvictFunction(sdk: ISdk, kv: StateKV): void { } if (!dryRun && recoveredStaleSessions > 0) { - await runRecoveredSessionConsolidation(sdk); + await runRecoveredSessionConsolidation( + sdk, + data.accessContext, + ); } const projectObs = new Map(); diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 469ad6859c..7ee0031f87 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -50,8 +50,13 @@ import { } from "./lesson-model.js"; import { withLessonMutationLock } from "./lesson-locks.js"; import { + bindResolvedLessonWriteIdentity, + buildCrystalAccessIndex, + buildLessonAccessIndex, + canReadCrystal, + canReadInsight, canReadLesson, - canUseLessonCapability, + canUseLessonOperatorCapability, canWriteLessonScope, lessonAccessContextFromPayload, type LessonAccessContext, @@ -71,6 +76,19 @@ interface LessonLifecycleTransition { const MAX_LESSON_STATE_DIAGNOSTIC_DETAIL_LENGTH = 256; +function isRecordWithNonEmptyString( + value: unknown, + field: string, +): boolean { + return ( + value !== null && + typeof value === "object" && + !Array.isArray(value) && + typeof (value as Record)[field] === "string" && + ((value as Record)[field] as string).length > 0 + ); +} + export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::export", async (data?: { @@ -81,7 +99,12 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { const accessContext = lessonAccessContextFromPayload( data?.accessContext, ); - if (!canUseLessonCapability(accessContext, "lesson:export")) { + if ( + !canUseLessonOperatorCapability( + accessContext, + "lesson:export", + ) + ) { return { success: false, code: "access_denied", @@ -163,9 +186,22 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { kv.list(KV.checkpoints).catch(() => []), kv.list(KV.accessLog).catch(() => []), ]); + const lessonIndex = buildLessonAccessIndex(lessons); + const crystalIndex = buildCrystalAccessIndex(crystals); const authorizedLessons = lessons .filter((lesson) => canReadLesson(lesson, accessContext)) .map((lesson) => normalizeLesson(lesson)); + const authorizedCrystals = crystals.filter((crystal) => + canReadCrystal(crystal, lessonIndex, accessContext), + ); + const authorizedInsights = insights.filter((insight) => + canReadInsight( + insight, + lessonIndex, + crystalIndex, + accessContext, + ), + ); const exportData: ExportData = { version: VERSION, @@ -196,13 +232,19 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { }, sentinels: sentinels.length > 0 ? sentinels : undefined, sketches: sketches.length > 0 ? sketches : undefined, - crystals: crystals.length > 0 ? crystals : undefined, + crystals: + authorizedCrystals.length > 0 + ? authorizedCrystals + : undefined, facets: facets.length > 0 ? facets : undefined, lessons: authorizedLessons.length > 0 ? authorizedLessons : undefined, - insights: insights.length > 0 ? insights : undefined, + insights: + authorizedInsights.length > 0 + ? authorizedInsights + : undefined, routines: routines.length > 0 ? routines : undefined, signals: signals.length > 0 ? signals : undefined, checkpoints: checkpoints.length > 0 ? checkpoints : undefined, @@ -244,7 +286,12 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { const accessContext = lessonAccessContextFromPayload( data?.accessContext, ); - if (!canUseLessonCapability(accessContext, "lesson:import")) { + if ( + !canUseLessonOperatorCapability( + accessContext, + "lesson:import", + ) + ) { return { success: false, code: "access_denied", @@ -308,6 +355,60 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { ) { return { success: false, error: "observations must be an object" }; } + const importRecord = importData as unknown as Record< + string, + unknown + >; + const keyedCollections: Array<{ + field: string; + key: string; + required?: boolean; + }> = [ + { field: "sessions", key: "id", required: true }, + { field: "memories", key: "id", required: true }, + { + field: "summaries", + key: "sessionId", + required: true, + }, + { field: "profiles", key: "project" }, + { field: "graphNodes", key: "id" }, + { field: "graphEdges", key: "id" }, + { field: "semanticMemories", key: "id" }, + { field: "proceduralMemories", key: "id" }, + { field: "actions", key: "id" }, + { field: "actionEdges", key: "id" }, + { field: "actionEvents", key: "id" }, + { field: "routines", key: "id" }, + { field: "signals", key: "id" }, + { field: "checkpoints", key: "id" }, + { field: "sentinels", key: "id" }, + { field: "sketches", key: "id" }, + { field: "crystals", key: "id" }, + { field: "facets", key: "id" }, + { field: "insights", key: "id" }, + { field: "accessLogs", key: "memoryId" }, + ]; + for (const collection of keyedCollections) { + const value = importRecord[collection.field]; + if (value === undefined && !collection.required) continue; + if (!Array.isArray(value)) { + return { + success: false, + error: `${collection.field} must be an array`, + }; + } + if ( + !value.every((item) => + isRecordWithNonEmptyString(item, collection.key), + ) + ) { + return { + success: false, + error: `${collection.field} contains an invalid record`, + }; + } + } if (importData.sessions.length > MAX_SESSIONS) { return { @@ -341,6 +442,16 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { if (!Array.isArray(obs)) { return { success: false, error: "observation values must be arrays" }; } + if ( + !obs.every((item) => + isRecordWithNonEmptyString(item, "id"), + ) + ) { + return { + success: false, + error: "observations contain an invalid record", + }; + } if (obs.length > MAX_OBS_PER_SESSION) { return { success: false, @@ -996,6 +1107,34 @@ async function applyImportedLessonBatch( const preimage = new Map( existingRows.map((lesson) => [lesson.id, lesson] as const), ); + const authorizedImported: ImportedLessonCandidate[] = []; + for (const candidate of imported) { + const prepared = bindResolvedLessonWriteIdentity( + candidate.lesson, + accessContext, + ); + if (!prepared.success) { + return { + success: false, + ...(prepared.code === "access_denied" + ? { code: "access_denied" as const } + : {}), + error: prepared.error, + }; + } + try { + authorizedImported.push({ + ...candidate, + lesson: normalizeLesson(prepared.value as Lesson), + }); + } catch { + return { + success: false, + error: "Invalid imported lesson after server identity binding", + }; + } + } + imported = authorizedImported; const existing = new Map(); const existingAliases = new Map(); for (const row of existingRows) { @@ -1124,6 +1263,24 @@ async function applyImportedLessonBatch( }); incoming.set(rewritten.id, rewritten); } + for (const lesson of incoming.values()) { + const relationIds = [ + ...(lesson.supersededByLessonId + ? [lesson.supersededByLessonId] + : []), + ...lesson.contradictedByLessonIds!, + ]; + for (const relationId of relationIds) { + const target = incoming.get(relationId) ?? existing.get(relationId); + if (target && !canReadLesson(target, accessContext)) { + return { + success: false, + code: "access_denied", + error: "Lesson import access denied for relation target", + }; + } + } + } const finalLessons = strategy === "replace" diff --git a/src/functions/governance.ts b/src/functions/governance.ts index 16d0d1c427..b28fef21e8 100644 --- a/src/functions/governance.ts +++ b/src/functions/governance.ts @@ -170,6 +170,7 @@ export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { dateFrom?: string; dateTo?: string; limit?: number; + accessContext?: unknown; }) => { return queryAudit(kv, data); }, diff --git a/src/functions/lesson-access.ts b/src/functions/lesson-access.ts index ef7483d27c..b054c332be 100644 --- a/src/functions/lesson-access.ts +++ b/src/functions/lesson-access.ts @@ -8,6 +8,8 @@ import { readFileSync } from "node:fs"; import { isAbsolute } from "node:path"; import { getAgentId, getEnvVar } from "../config.js"; import type { + Crystal, + Insight, Lesson, LessonScope, LessonScopeRing, @@ -537,12 +539,12 @@ function scopeAllowed( access: LessonScopeAccess, ): boolean { if (hasCapability(context, "lesson:all-scopes")) return true; - if ( - scope.ring === "worktree" && - !scope.scopeId && - hasCapability(context, "lesson:legacy-worktree") - ) { - return true; + if (scope.ring === "worktree" && !scope.scopeId) { + return ( + context.resolvedBy === "system" || + (access === "read" && + hasCapability(context, "lesson:legacy-worktree")) + ); } return context.scopes.some( (grant) => @@ -583,6 +585,18 @@ export function canUseLessonCapability( return context.mode === "classify" || hasCapability(context, capability); } +export function canUseLessonOperatorCapability( + context: LessonAccessContext, + capability: "lesson:export" | "lesson:import", +): boolean { + return ( + context.mode === "classify" || + (context.clearance === "restricted" && + hasCapability(context, "lesson:all-scopes") && + hasCapability(context, capability)) + ); +} + export function canApproveGlobalLesson( context: LessonAccessContext, ): boolean { @@ -593,6 +607,106 @@ export function canApproveGlobalLesson( ); } +export type LessonAccessIndex = Map; + +export function buildLessonAccessIndex( + lessons: Lesson[], +): LessonAccessIndex { + const index: LessonAccessIndex = new Map(); + for (const lesson of lessons) { + const normalized = normalizeLesson(lesson); + for (const id of [normalized.id, ...normalized.idAliases]) { + const existing = index.get(id); + if (existing && existing.id !== normalized.id) { + throw new Error(`multiple lessons claim access identity ${id}`); + } + index.set(id, normalized); + } + } + return index; +} + +export function canReadLessonSourceIds( + sourceLessonIds: string[] | undefined, + index: LessonAccessIndex, + context: LessonAccessContext, +): boolean { + if (context.mode === "classify") return true; + if (!sourceLessonIds || sourceLessonIds.length === 0) return true; + return sourceLessonIds.every((id) => { + const lesson = index.get(id); + return lesson !== undefined && canReadLesson(lesson, context); + }); +} + +export function canReadCrystal( + crystal: Crystal, + index: LessonAccessIndex, + context: LessonAccessContext, +): boolean { + if (context.mode === "classify") return true; + if (crystal.sourceLessonIds && crystal.sourceLessonIds.length > 0) { + const lessonValues = crystal.lessons ?? []; + if (lessonValues.length !== crystal.sourceLessonIds.length) { + return false; + } + return crystal.sourceLessonIds.every((id, position) => { + const lesson = index.get(id); + if (!lesson || !canReadLesson(lesson, context)) return false; + const value = lessonValues[position]; + return ( + value === id || + value === lesson.id || + value === lesson.content + ); + }); + } + if ((crystal.lessons ?? []).length > 0) { + return hasCapability(context, "lesson:all-scopes"); + } + return true; +} + +export type CrystalAccessIndex = Map; + +export function buildCrystalAccessIndex( + crystals: Crystal[], +): CrystalAccessIndex { + const index: CrystalAccessIndex = new Map(); + for (const crystal of crystals) { + if (index.has(crystal.id)) { + throw new Error(`duplicate crystal access identity ${crystal.id}`); + } + index.set(crystal.id, crystal); + } + return index; +} + +export function canReadInsight( + insight: Insight, + lessonIndex: LessonAccessIndex, + crystalIndex: CrystalAccessIndex, + context: LessonAccessContext, +): boolean { + if (context.mode === "classify") return true; + if ( + !canReadLessonSourceIds( + insight.sourceLessonIds, + lessonIndex, + context, + ) + ) { + return false; + } + return (insight.sourceCrystalIds ?? []).every((id) => { + const crystal = crystalIndex.get(id); + return ( + crystal !== undefined && + canReadCrystal(crystal, lessonIndex, context) + ); + }); +} + export type LessonWriteIdentityResult = | { success: true; value: unknown } | { success: false; code: "access_denied" | "invalid_request"; error: string }; diff --git a/src/functions/lessons.ts b/src/functions/lessons.ts index c9b97e1459..6fdaa45e4e 100644 --- a/src/functions/lessons.ts +++ b/src/functions/lessons.ts @@ -356,11 +356,12 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { } if (existing) { + const normalizedExisting = normalizeLesson(existing); if ( - !canReadLesson(existing, accessContext) || + !canReadLesson(normalizedExisting, accessContext) || !canWriteLessonScope( - normalizeLesson(existing).scope, - normalizeLesson(existing).sensitivity, + normalizedExisting.scope, + normalizedExisting.sensitivity, accessContext, ) ) { @@ -368,7 +369,7 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { } const contradictionFailure = await validateContradictionRelations( kv, - existing, + normalizedExisting, input.contradictedByLessonIds, accessContext, ); @@ -378,28 +379,37 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { contradictionFailure.error, ); } - reinforceLesson(existing); - if (input.context && !existing.context) { - existing.context = input.context; + reinforceLesson(normalizedExisting); + if (input.context && !normalizedExisting.context) { + normalizedExisting.context = input.context; } - existing.sourceIds = [ - ...new Set([...existing.sourceIds, ...input.sourceIds]), + normalizedExisting.sourceIds = [ + ...new Set([ + ...normalizedExisting.sourceIds, + ...input.sourceIds, + ]), ].sort(); - existing.tags = [...new Set([...existing.tags, ...input.tags])]; - existing.contradictedByLessonIds = [ + normalizedExisting.tags = [ + ...new Set([...normalizedExisting.tags, ...input.tags]), + ]; + normalizedExisting.contradictedByLessonIds = [ ...new Set([ - ...(existing.contradictedByLessonIds ?? []), + ...normalizedExisting.contradictedByLessonIds, ...input.contradictedByLessonIds, ]), ].sort(); - await kv.set(KV.lessons, existing.id, existing); + await kv.set( + KV.lessons, + normalizedExisting.id, + normalizedExisting, + ); try { await recordAudit( kv, "lesson_strengthen", "mem::lesson-save", - [existing.id], + [normalizedExisting.id], { actor: accessContext.principalId, confidenceChanged: false, @@ -410,7 +420,7 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { return { success: true, action: "strengthened", - lesson: toLessonReadModel(existing), + lesson: toLessonReadModel(normalizedExisting), }; } diff --git a/src/functions/obsidian-export.ts b/src/functions/obsidian-export.ts index 4fac89c126..a596d7937f 100644 --- a/src/functions/obsidian-export.ts +++ b/src/functions/obsidian-export.ts @@ -17,8 +17,10 @@ import { toLessonReadModel, } from "./lesson-model.js"; import { + buildLessonAccessIndex, + canReadCrystal, canReadLesson, - canUseLessonCapability, + canUseLessonOperatorCapability, lessonAccessContextFromPayload, type LessonAccessContext, } from "./lesson-access.js"; @@ -379,9 +381,14 @@ export function registerObsidianExportFunction( const accessContext = lessonAccessContextFromPayload( data.accessContext, ); + const exportsProtectedRecords = + exportTypes.has("lessons") || exportTypes.has("crystals"); if ( - exportTypes.has("lessons") && - !canUseLessonCapability(accessContext, "lesson:export") + exportsProtectedRecords && + !canUseLessonOperatorCapability( + accessContext, + "lesson:export", + ) ) { return { success: false, @@ -402,6 +409,37 @@ export function registerObsidianExportFunction( // TypeError as `{"error":"[object Object]"}`. With this guard the // worst case is `{success: false, error: }`. try { + let lessons: Lesson[] = []; + let crystals: Crystal[] = []; + if (exportsProtectedRecords) { + try { + const authoritativeLessons = await kv.list(KV.lessons); + lessons = exportTypes.has("lessons") + ? authoritativeLessons + : []; + if (exportTypes.has("crystals")) { + const storedCrystals = await kv.list(KV.crystals); + if (accessContext.mode === "enforce") { + const lessonIndex = buildLessonAccessIndex( + authoritativeLessons, + ); + crystals = storedCrystals.filter((crystal) => + canReadCrystal(crystal, lessonIndex, accessContext), + ); + } else { + crystals = storedCrystals; + } + } + } catch { + return { + success: false, + code: "lesson_state_unavailable", + error: "Obsidian protected export is unavailable", + vaultDir, + }; + } + } + await Promise.all( Object.values(dirs).map((dir) => mkdir(dir, { recursive: true })), ); @@ -413,10 +451,8 @@ export function registerObsidianExportFunction( const crystalMoc: string[] = []; const sessionMoc: string[] = []; - const [memories, lessons, crystals, sessions] = await Promise.all([ + const [memories, sessions] = await Promise.all([ exportTypes.has("memories") ? kv.list(KV.memories) : Promise.resolve([] as Memory[]), - exportTypes.has("lessons") ? kv.list(KV.lessons) : Promise.resolve([] as Lesson[]), - exportTypes.has("crystals") ? kv.list(KV.crystals) : Promise.resolve([] as Crystal[]), exportTypes.has("sessions") ? kv.list(KV.sessions) : Promise.resolve([] as Session[]), ]); diff --git a/src/functions/reflect.ts b/src/functions/reflect.ts index 3c9c4c660a..a7a46f3c6b 100644 --- a/src/functions/reflect.ts +++ b/src/functions/reflect.ts @@ -19,9 +19,15 @@ import { toLessonReadModel, } from "./lesson-model.js"; import { + buildCrystalAccessIndex, + buildLessonAccessIndex, + canReadCrystal, + canReadInsight, canReadLesson, lessonAccessContextFromPayload, + type CrystalAccessIndex, type LessonAccessContext, + type LessonAccessIndex, } from "./lesson-access.js"; interface ConceptCluster { @@ -221,6 +227,50 @@ function reflectLessonReadFailure( }; } +async function filterReadableInsights( + kv: StateKV, + insights: Insight[], + accessContext: LessonAccessContext, +): Promise< + | { success: true; insights: Insight[] } + | { + success: false; + code: "lesson_state_unavailable"; + error: string; + insights: []; + } +> { + if (accessContext.mode === "classify") { + return { success: true, insights }; + } + try { + const [lessons, crystals] = await Promise.all([ + kv.list(KV.lessons), + kv.list(KV.crystals), + ]); + const lessonIndex = buildLessonAccessIndex(lessons); + const crystalIndex = buildCrystalAccessIndex(crystals); + return { + success: true, + insights: insights.filter((insight) => + canReadInsight( + insight, + lessonIndex, + crystalIndex, + accessContext, + ), + ), + }; + } catch { + return { + success: false, + code: "lesson_state_unavailable", + error: "insight access is unavailable", + insights: [], + }; + } +} + export function registerReflectFunctions( sdk: ISdk, kv: StateKV, @@ -254,7 +304,11 @@ export function registerReflectFunctions( ]); let activeLessons: LessonReadModel[] = []; + let lessonIndex: LessonAccessIndex; + let crystalIndex: CrystalAccessIndex; try { + lessonIndex = buildLessonAccessIndex(lessons); + crystalIndex = buildCrystalAccessIndex(crystals); for (const lesson of lessons) { if ( isLessonRecallable(lesson) && @@ -310,12 +364,21 @@ export function registerReflectFunctions( ); const clusterCrystals = crystals.filter((c) => + canReadCrystal(c, lessonIndex, accessContext) && (c.lessons || []).some((l) => conceptNames.some((cn) => l.toLowerCase().includes(cn.toLowerCase()), ), ), ); + const clusterLessonIds = [ + ...new Set([ + ...clusterLessons.map((lesson) => lesson.id), + ...clusterCrystals.flatMap( + (crystal) => crystal.sourceLessonIds ?? [], + ), + ]), + ].sort(); const totalItems = clusterFacts.length + clusterLessons.length + clusterCrystals.length; @@ -339,7 +402,7 @@ export function registerReflectFunctions( })), crystalNarratives: clusterCrystals.map((c) => c.narrative), factIds: clusterFacts.map((f) => f.id), - lessonIds: clusterLessons.map((l) => l.id), + lessonIds: clusterLessonIds, crystalIds: clusterCrystals.map((c) => c.id), }; @@ -388,11 +451,45 @@ export function registerReflectFunctions( const existing = await kv.get(KV.insights, fp); if (existing && !existing.deleted) { + if ( + !canReadInsight( + existing, + lessonIndex, + crystalIndex, + accessContext, + ) + ) { + continue; + } reinforceInsight(existing); existing.evidenceVerdict = (existing.evidenceVerdict ?? "supported") === evidenceVerdict ? evidenceVerdict : "mixed"; + existing.sourceConceptCluster = [ + ...new Set([ + ...existing.sourceConceptCluster, + ...conceptNames, + ]), + ].sort(); + existing.sourceMemoryIds = [ + ...new Set([ + ...existing.sourceMemoryIds, + ...cluster.factIds, + ]), + ].sort(); + existing.sourceLessonIds = [ + ...new Set([ + ...existing.sourceLessonIds, + ...cluster.lessonIds, + ]), + ].sort(); + existing.sourceCrystalIds = [ + ...new Set([ + ...existing.sourceCrystalIds, + ...cluster.crystalIds, + ]), + ].sort(); await kv.set(KV.insights, existing.id, existing); reinforced++; } else { @@ -452,10 +549,21 @@ export function registerReflectFunctions( project?: string; minConfidence?: number; limit?: number; + accessContext?: LessonAccessContext; }) => { const limit = data?.limit ?? 50; const minConfidence = data?.minConfidence ?? 0; let items = await kv.list(KV.insights); + const accessContext = lessonAccessContextFromPayload( + data?.accessContext, + ); + const readable = await filterReadableInsights( + kv, + items, + accessContext, + ); + if (!readable.success) return readable; + items = readable.insights; items = items.filter( (i) => !i.deleted && i.confidence >= minConfidence, @@ -477,6 +585,7 @@ export function registerReflectFunctions( project?: string; minConfidence?: number; limit?: number; + accessContext?: LessonAccessContext; }) => { if (!data?.query?.trim()) { return { success: false, error: "query is required" }; @@ -487,6 +596,16 @@ export function registerReflectFunctions( const limit = data.limit ?? 10; let items = await kv.list(KV.insights); + const accessContext = lessonAccessContextFromPayload( + data.accessContext, + ); + const readable = await filterReadableInsights( + kv, + items, + accessContext, + ); + if (!readable.success) return readable; + items = readable.insights; items = items.filter( (i) => !i.deleted && i.confidence >= minConfidence, ); diff --git a/src/functions/replay.ts b/src/functions/replay.ts index 5ba66ab11a..58c7fb7e71 100644 --- a/src/functions/replay.ts +++ b/src/functions/replay.ts @@ -18,12 +18,11 @@ import { buildSyntheticCompression } from "./compress-synthetic.js"; import { getSearchIndex } from "./search.js"; import { logger } from "../logger.js"; import { - lessonCanonicalId, - lessonIdForInput, - normalizeLesson, - parseLessonSaveInput, -} from "./lesson-model.js"; -import { withLessonLocks } from "./lesson-locks.js"; + buildLessonAccessIndex, + canReadCrystal, + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; export const MAX_FILES_DEFAULT = 200; export const MAX_FILES_UPPER_BOUND = 1000; @@ -74,12 +73,14 @@ const LESSON_PATTERNS: RegExp[] = [ ]; async function deriveCrystalAndLessons( + sdk: ISdk, kv: StateKV, sessionId: string, project: string, rawObs: RawObservation[], compressed: CompressedObservation[], firstPrompt: string | undefined, + accessContext: LessonAccessContext, ): Promise { if (rawObs.length === 0) return; const createdAt = new Date().toISOString(); @@ -121,73 +122,25 @@ async function deriveCrystalAndLessons( const lessonIds: string[] = []; for (const content of lessonEntries) { try { - const parsed = parseLessonSaveInput({ - content, - context: firstPrompt || project, - confidence: 0.4, - source: "consolidation", - sourceIds: [sessionId], - project, - tags: ["auto-import"], - }); - if (!parsed.success) continue; - const lessonId = lessonIdForInput(parsed.value); - await withLessonLocks([lessonId], async () => { - const exact = await kv.get(KV.lessons, lessonId); - const existing = - exact ?? - (await kv.list(KV.lessons)).find((lesson) => { - try { - const normalized = normalizeLesson(lesson); - return ( - normalized.idAliases.includes(lessonId) || - lessonCanonicalId(normalized) === lessonId - ); - } catch { - return false; - } - }); - if (existing) { - const normalizedExisting = normalizeLesson(existing); - const existingSources = normalizedExisting.sourceIds; - const mergedSources = existingSources.includes(sessionId) - ? existingSources - : [...existingSources, sessionId]; - const existingTags = normalizedExisting.tags; - const mergedTags = existingTags.includes("auto-import") - ? existingTags - : [...existingTags, "auto-import"]; - const merged: Lesson = { - ...normalizedExisting, - sourceIds: mergedSources, - tags: mergedTags, - reinforcements: normalizedExisting.reinforcements + 1, - updatedAt: createdAt, - lastReinforcedAt: createdAt, - }; - await kv.set(KV.lessons, existing.id, merged); - lessonIds.push(existing.id); - return; - } - const lesson = normalizeLesson({ - id: lessonId, - identityKind: "canonical", - idAliases: [], + const result = (await sdk.trigger({ + function_id: "mem::lesson-save", + payload: { content, context: firstPrompt || project, confidence: 0.4, - reinforcements: 0, source: "consolidation", sourceIds: [sessionId], project, tags: ["auto-import"], - createdAt, - updatedAt: createdAt, - decayRate: 0.05, - }); - await kv.set(KV.lessons, lessonId, lesson); - lessonIds.push(lessonId); - }); + accessContext, + }, + })) as { + success?: boolean; + lesson?: { id?: string }; + }; + if (result.success && typeof result.lesson?.id === "string") { + lessonIds.push(result.lesson.id); + } } catch {} } @@ -205,12 +158,25 @@ async function deriveCrystalAndLessons( try { const existingCrystal = await kv.get(KV.crystals, crystalId); + if (existingCrystal && accessContext.mode === "enforce") { + try { + const lessonIndex = buildLessonAccessIndex( + await kv.list(KV.lessons), + ); + if (!canReadCrystal(existingCrystal, lessonIndex, accessContext)) { + return; + } + } catch { + return; + } + } const crystal: Crystal = { id: crystalId, narrative: narrativePreview || `Session ${sessionId.slice(0, 12)} (${rawObs.length} observations)`, keyOutcomes: Array.from(tools).slice(0, 8), filesAffected: Array.from(files).slice(0, 20), lessons: lessonIds, + sourceLessonIds: lessonIds, sourceActionIds: existingCrystal?.sourceActionIds ?? [], sessionId, project, @@ -320,7 +286,11 @@ export function registerReplayFunctions(sdk: ISdk, kv: StateKV): void { sdk.registerFunction( "mem::replay::import-jsonl", async ( - data: { path?: string; maxFiles?: number } = {}, + data: { + path?: string; + maxFiles?: number; + accessContext?: LessonAccessContext; + } = {}, ): Promise< | { success: true; @@ -399,6 +369,9 @@ export function registerReplayFunctions(sdk: ISdk, kv: StateKV): void { const sessionIds: string[] = []; let observationCount = 0; + const accessContext = lessonAccessContextFromPayload( + data.accessContext, + ); for (const file of files) { if (isSensitive(file)) continue; @@ -479,12 +452,14 @@ export function registerReplayFunctions(sdk: ISdk, kv: StateKV): void { sessionIds.push(parsed.sessionId); await deriveCrystalAndLessons( + sdk, kv, parsed.sessionId, parsed.project, parsed.observations, compressed, firstPrompt, + accessContext, ); } diff --git a/src/index.ts b/src/index.ts index 910ffae73f..9708e2773f 100644 --- a/src/index.ts +++ b/src/index.ts @@ -90,6 +90,7 @@ import { registerCompressFileFunction } from "./functions/compress-file.js"; import { registerLlmSmokeFunction } from "./functions/llm-smoke.js"; import { registerReplayFunctions } from "./functions/replay.js"; import { registerSessionContextFunction } from "./functions/session-context.js"; +import { systemLessonAccessContext } from "./functions/lesson-access.js"; import { registerApiTriggers } from "./triggers/api.js"; import { registerEventTriggers } from "./triggers/events.js"; import { registerMcpEndpoints } from "./mcp/server.js"; @@ -587,7 +588,10 @@ async function main() { if (isConsolidationEnabled()) { const consolidationTimer = setInterval(async () => { try { - await sdk.trigger({ function_id: "mem::consolidate-pipeline", payload: {} }); + await sdk.trigger({ + function_id: "mem::consolidate-pipeline", + payload: { accessContext: systemLessonAccessContext() }, + }); } catch {} }, consolidationIntervalMs); consolidationTimer.unref(); diff --git a/src/mcp/http-error.ts b/src/mcp/http-error.ts new file mode 100644 index 0000000000..d659eed278 --- /dev/null +++ b/src/mcp/http-error.ts @@ -0,0 +1,48 @@ +const MAX_UPSTREAM_ERROR_DETAIL = 512; + +function compact(value: string): string { + return value.replace(/\s+/g, " ").trim(); +} + +function structuredDetail(body: string): string { + try { + const parsed = JSON.parse(body) as unknown; + if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) { + return compact(body); + } + const record = parsed as Record; + const fields = ["code", "error", "message", "reason"].flatMap((key) => { + const value = record[key]; + return typeof value === "string" || typeof value === "number" + ? [`${key}=${String(value)}`] + : []; + }); + return fields.length > 0 ? fields.join(" ") : compact(body); + } catch { + return compact(body); + } +} + +/** + * Preserve bounded, operator-useful upstream diagnostics without reflecting + * headers, tokens, or an unbounded response body into MCP errors. + */ +export async function upstreamHttpError( + method: string, + path: string, + response: Response, +): Promise { + let detail = ""; + try { + detail = structuredDetail(await response.text()).slice( + 0, + MAX_UPSTREAM_ERROR_DETAIL, + ); + } catch { + // A missing/unreadable response body must not hide the HTTP status. + } + const suffix = detail ? `; ${detail}` : ""; + return new Error( + `${method} ${path} -> ${response.status} ${response.statusText}${suffix}`, + ); +} diff --git a/src/mcp/http.ts b/src/mcp/http.ts index 562bfdecf4..faee41109a 100644 --- a/src/mcp/http.ts +++ b/src/mcp/http.ts @@ -22,6 +22,7 @@ import { callerIdentityHeaders, resolveEnvOrEmpty, } from "./rest-proxy.js"; +import { upstreamHttpError } from "./http-error.js"; const DEFAULT_ENGINE_URL = "http://127.0.0.1:3111"; const DEFAULT_HOST = "127.0.0.1"; @@ -137,8 +138,10 @@ export function createProxyBackend(options: { signal: AbortSignal.timeout(BACKEND_TIMEOUT_MS), }); if (!response.ok) { - throw new Error( - `${init.method ?? "GET"} ${path} -> ${response.status} ${response.statusText}`, + throw await upstreamHttpError( + init.method ?? "GET", + path, + response, ); } const text = await response.text(); diff --git a/src/mcp/rest-proxy.ts b/src/mcp/rest-proxy.ts index 0548911676..5fe038c001 100644 --- a/src/mcp/rest-proxy.ts +++ b/src/mcp/rest-proxy.ts @@ -1,3 +1,5 @@ +import { upstreamHttpError } from "./http-error.js"; + const DEFAULT_URL = "http://localhost:3111"; const DEFAULT_HEALTH_PROBE_TIMEOUT_MS = 2_000; const CALL_TIMEOUT_MS = 15_000; @@ -159,8 +161,10 @@ export async function resolveHandle(): Promise { signal: AbortSignal.timeout(CALL_TIMEOUT_MS), }); if (!res.ok) { - throw new Error( - `${init?.method || "GET"} ${path} -> ${res.status} ${res.statusText}`, + throw await upstreamHttpError( + init?.method || "GET", + path, + res, ); } const text = await res.text(); diff --git a/src/mcp/server.ts b/src/mcp/server.ts index 2341de9a55..874545fc5c 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -360,8 +360,6 @@ export function registerMcpEndpoints( } case "memory_smart_search": { - const access = resolveLessonRequestAccess(req); - if (!access.success) return access.response; if (typeof args.query !== "string" || !args.query.trim()) { return { status_code: 400, @@ -369,6 +367,11 @@ export function registerMcpEndpoints( }; } const expandIds = parseCsvList(args.expandIds).slice(0, 20); + const access = + expandIds.length === 0 + ? resolveLessonRequestAccess(req) + : undefined; + if (access && !access.success) return access.response; const limit = Math.max(1, Math.min(100, asNumber(args.limit, 10) ?? 10)); const result = await sdk.trigger({ function_id: "mem::smart-search", @@ -376,7 +379,9 @@ export function registerMcpEndpoints( query: args.query, expandIds, limit, - accessContext: access.context, + ...(access?.success + ? { accessContext: access.context } + : {}), }, }); return { @@ -580,10 +585,13 @@ export function registerMcpEndpoints( } case "memory_consolidate": { + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; try { const result = await sdk.trigger({ function_id: "mem::consolidate-pipeline", payload: { tier: args.tier as string, force: true, + accessContext: access.context, } }); return { status_code: 200, @@ -675,10 +683,13 @@ export function registerMcpEndpoints( } case "memory_audit": { + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; try { const result = await sdk.trigger({ function_id: "mem::audit-query", payload: { operation: args.operation as string, limit: typeof args.limit === "number" ? args.limit : 50, + accessContext: access.context, } }); return { status_code: 200, @@ -1217,6 +1228,8 @@ export function registerMcpEndpoints( } case "memory_crystallize": { + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; if (typeof args.actionIds !== "string" || !args.actionIds.trim()) { return { status_code: 400, body: { error: "actionIds is required" } }; } @@ -1225,6 +1238,7 @@ export function registerMcpEndpoints( actionIds: crysIds, project: args.project, sessionId: args.sessionId, + accessContext: access.context, } }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(crysResult, null, 2) }] } }; } @@ -1273,7 +1287,21 @@ export function registerMcpEndpoints( const diagCats = typeof args.categories === "string" && args.categories.trim() ? args.categories.split(",").map((s: string) => s.trim()).filter(Boolean) : undefined; - const diagResult = await sdk.trigger({ function_id: "mem::diagnose", payload: { categories: diagCats } }); + const includesLessons = + diagCats === undefined || diagCats.includes("lessons"); + const access = includesLessons + ? resolveLessonRequestAccess(req) + : undefined; + if (access && !access.success) return access.response; + const diagResult = await sdk.trigger({ + function_id: "mem::diagnose", + payload: { + categories: diagCats, + ...(access?.success + ? { accessContext: access.context } + : {}), + }, + }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(diagResult, null, 2) }] } }; } @@ -1456,24 +1484,35 @@ export function registerMcpEndpoints( } case "memory_insight_list": { + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const insightListResult = await sdk.trigger({ function_id: "mem::insight-list", payload: { project: args.project, minConfidence: args.minConfidence, limit: args.limit, + accessContext: access.context, } }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(insightListResult, null, 2) }] } }; } case "memory_obsidian_export": { - const access = resolveLessonRequestAccess(req); - if (!access.success) return access.response; const exportTypes = typeof args.types === "string" && args.types.trim() ? args.types.split(",").map((t: string) => t.trim()).filter(Boolean) : undefined; + const includesProtectedRecords = + exportTypes === undefined || + exportTypes.includes("lessons") || + exportTypes.includes("crystals"); + const access = includesProtectedRecords + ? resolveLessonRequestAccess(req) + : undefined; + if (access && !access.success) return access.response; const obsidianResult = await sdk.trigger({ function_id: "mem::obsidian-export", payload: { vaultDir: args.vaultDir, types: exportTypes, - accessContext: access.context, + ...(access?.success + ? { accessContext: access.context } + : {}), } }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(obsidianResult, null, 2) }] } }; } diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts index 349bd35bb8..9f666ac87d 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -213,7 +213,8 @@ export const CORE_TOOLS: McpToolDef[] = [ }, { name: "memory_export", - description: "Export all memory data as JSON.", + description: + "Export all memory data as JSON. In lesson enforcement mode this is an operator-only operation requiring restricted clearance, lesson:all-scopes, and lesson:export.", inputSchema: { type: "object", properties: {} }, }, { @@ -1131,7 +1132,7 @@ export const V070_TOOLS: McpToolDef[] = [ actor: { type: "string", description: - "Optional caller-supplied audit attribution, not authenticated identity; defaults to AGENT_ID", + "Optional attribution hint in classify mode; ignored and server-stamped from the authenticated principal in enforce mode", }, }, required: ["lessonId", "reason"], @@ -1169,7 +1170,7 @@ export const V070_TOOLS: McpToolDef[] = [ actor: { type: "string", description: - "Optional caller-supplied audit attribution, not authenticated identity; defaults to AGENT_ID", + "Optional attribution hint in classify mode; ignored and server-stamped from the authenticated principal in enforce mode", }, }, required: ["lessonId", "replacementLessonId", "reason"], @@ -1178,7 +1179,7 @@ export const V070_TOOLS: McpToolDef[] = [ { name: "memory_obsidian_export", description: - "Export memories, lessons, and crystals as Obsidian-compatible Markdown files with YAML frontmatter and wikilinks for graph view.", + "Export memories, lessons, and crystals as Obsidian-compatible Markdown files with YAML frontmatter and wikilinks for graph view. In lesson enforcement mode, lesson/crystal exports require restricted clearance, lesson:all-scopes, and lesson:export.", inputSchema: { type: "object", properties: { diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 306fe94a68..e63cd2c6f0 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -695,8 +695,14 @@ export function registerApiTriggers( ): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const body = (req.body ?? {}) as Record; - const payload: { path?: string; maxFiles?: number } = {}; + const payload: { + path?: string; + maxFiles?: number; + accessContext: LessonAccessContext; + } = { accessContext: access.context }; if (body.path !== undefined) { if (typeof body.path !== "string" || body.path.trim().length === 0) { return { @@ -1467,9 +1473,14 @@ export function registerApiTriggers( async (req: ApiRequest<{ dryRun?: boolean }>): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const dryRun = req.query_params?.["dryRun"] === "true" || req.body?.dryRun === true; - const result = await sdk.trigger({ function_id: "mem::evict", payload: { dryRun } }); + const result = await sdk.trigger({ + function_id: "mem::evict", + payload: { dryRun, accessContext: access.context }, + }); return { status_code: 200, body: result }; }, ); @@ -2007,9 +2018,22 @@ export function registerApiTriggers( async (req: ApiRequest<{ tier?: string }>): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; + const body = (req.body ?? {}) as Record; try { - const result = await sdk.trigger({ function_id: "mem::consolidate-pipeline", payload: req.body || {}, - }); + const result = await sdk.trigger({ + function_id: "mem::consolidate-pipeline", + payload: { + tier: typeof body.tier === "string" ? body.tier : undefined, + force: typeof body.force === "boolean" ? body.force : undefined, + project: + typeof body.project === "string" + ? body.project + : undefined, + accessContext: access.context, + }, + }); return { status_code: 200, body: result }; } catch { return consolidationDisabledResponse(); @@ -2093,10 +2117,13 @@ export function registerApiTriggers( async (req: ApiRequest): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const parsedLimit = parseOptionalInt(req.query_params?.["limit"]); const entries = await sdk.trigger({ function_id: "mem::audit-query", payload: { operation: req.query_params?.["operation"], limit: parsedLimit ?? 50, + accessContext: access.context, } }); return { status_code: 200, body: { entries, success: true } }; }, @@ -3496,9 +3523,30 @@ export function registerApiTriggers( sdk.registerFunction("api::crystallize", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; - const body = req.body as Record; - if (!body?.actionIds) return { status_code: 400, body: { error: "actionIds is required" } }; - const result = await sdk.trigger({ function_id: "mem::crystallize", payload: body }); + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; + const body = (req.body as Record) || {}; + if ( + !Array.isArray(body.actionIds) || + !body.actionIds.every( + (id): id is string => typeof id === "string" && id.length > 0, + ) + ) { + return { status_code: 400, body: { error: "actionIds is required" } }; + } + const result = await sdk.trigger({ + function_id: "mem::crystallize", + payload: { + actionIds: body.actionIds, + project: + typeof body.project === "string" ? body.project : undefined, + sessionId: + typeof body.sessionId === "string" + ? body.sessionId + : undefined, + accessContext: access.context, + }, + }); return { status_code: 200, body: result }; }); sdk.registerTrigger({ type: "http", function_id: "api::crystallize", config: { api_path: "/agentmemory/crystals/create", http_method: "POST" } }); @@ -3506,6 +3554,8 @@ export function registerApiTriggers( sdk.registerFunction("api::crystal-list", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const params = req.query_params || {}; const limit = parseOptionalPositiveInt(params.limit); if (limit === null) { @@ -3514,7 +3564,15 @@ export function registerApiTriggers( body: { error: "invalid numeric parameter: limit" }, }; } - const result = await sdk.trigger({ function_id: "mem::crystal-list", payload: { project: params.project, sessionId: params.sessionId, limit } }); + const result = await sdk.trigger({ + function_id: "mem::crystal-list", + payload: { + project: params.project, + sessionId: params.sessionId, + limit, + accessContext: access.context, + }, + }); return { status_code: 200, body: result }; }); sdk.registerTrigger({ type: "http", function_id: "api::crystal-list", config: { api_path: "/agentmemory/crystals", http_method: "GET" } }); @@ -3522,8 +3580,23 @@ export function registerApiTriggers( sdk.registerFunction("api::auto-crystallize", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; - const body = req.body as Record; - const result = await sdk.trigger({ function_id: "mem::auto-crystallize", payload: body || {} }); + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; + const body = (req.body as Record) || {}; + const result = await sdk.trigger({ + function_id: "mem::auto-crystallize", + payload: { + olderThanDays: + typeof body.olderThanDays === "number" + ? body.olderThanDays + : undefined, + project: + typeof body.project === "string" ? body.project : undefined, + dryRun: + typeof body.dryRun === "boolean" ? body.dryRun : undefined, + accessContext: access.context, + }, + }); return { status_code: 200, body: result }; }); sdk.registerTrigger({ type: "http", function_id: "api::auto-crystallize", config: { api_path: "/agentmemory/crystals/auto", http_method: "POST" } }); @@ -3531,8 +3604,28 @@ export function registerApiTriggers( sdk.registerFunction("api::diagnose", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; - const body = req.body as Record; - const result = await sdk.trigger({ function_id: "mem::diagnose", payload: body || {} }); + const body = (req.body as Record) || {}; + const categories = Array.isArray(body.categories) + ? body.categories.filter( + (category): category is string => + typeof category === "string", + ) + : undefined; + const includesLessons = + categories === undefined || categories.includes("lessons"); + const access = includesLessons + ? resolveLessonRequestAccess(req) + : undefined; + if (access && !access.success) return access.response; + const result = await sdk.trigger({ + function_id: "mem::diagnose", + payload: { + categories, + ...(access?.success + ? { accessContext: access.context } + : {}), + }, + }); return { status_code: 200, body: result }; }); sdk.registerTrigger({ type: "http", function_id: "api::diagnose", config: { api_path: "/agentmemory/diagnostics", http_method: "POST" } }); @@ -3901,8 +3994,11 @@ export function registerApiTriggers( }; } const types = typeof body.types === "string" ? body.types.split(",").map((t: string) => t.trim()).filter(Boolean) : undefined; - const includesLessons = types === undefined || types.includes("lessons"); - const access = includesLessons + const includesProtectedRecords = + types === undefined || + types.includes("lessons") || + types.includes("crystals"); + const access = includesProtectedRecords ? resolveLessonRequestAccess(req) : undefined; if (access && !access.success) return access.response; @@ -3940,6 +4036,8 @@ export function registerApiTriggers( sdk.registerFunction("api::insight-list", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const params = req.query_params || {}; const minConfidence = parseOptionalFiniteNumber(params.minConfidence); if (minConfidence === null) { @@ -3959,6 +4057,7 @@ export function registerApiTriggers( project: params.project, minConfidence, limit, + accessContext: access.context, } }); return { status_code: 200, body: result }; }); @@ -3967,6 +4066,8 @@ export function registerApiTriggers( sdk.registerFunction("api::insight-search", async (req: ApiRequest) => { const denied = checkAuth(req, secret); if (denied) return denied; + const access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; const body = req.body as Record; if (!body?.query || typeof body.query !== "string") return { status_code: 400, body: { error: "query is required" } }; const result = await sdk.trigger({ function_id: "mem::insight-search", payload: { @@ -3974,6 +4075,7 @@ export function registerApiTriggers( project: typeof body.project === "string" ? body.project : undefined, minConfidence: typeof body.minConfidence === "number" ? body.minConfidence : undefined, limit: typeof body.limit === "number" ? body.limit : undefined, + accessContext: access.context, } }); return { status_code: 200, body: result }; }); diff --git a/src/types.ts b/src/types.ts index 3da04cd285..a5450a88a8 100644 --- a/src/types.ts +++ b/src/types.ts @@ -931,6 +931,7 @@ export interface Crystal { keyOutcomes: string[]; filesAffected: string[]; lessons: string[]; + sourceLessonIds?: string[]; sourceActionIds: string[]; sessionId?: string; project?: string; diff --git a/src/viewer/server.ts b/src/viewer/server.ts index c80e67f0af..c5f3f97221 100644 --- a/src/viewer/server.ts +++ b/src/viewer/server.ts @@ -406,6 +406,17 @@ async function proxyToRestApi( if (secret) { headers["Authorization"] = `Bearer ${secret}`; } + // The browser never receives these credentials, and inbound copies are + // deliberately ignored: the viewer has its own server-side read principal. + const viewerAgentId = process.env["AGENTMEMORY_VIEWER_AGENT_ID"]; + const viewerCallerToken = + process.env["AGENTMEMORY_VIEWER_CALLER_TOKEN"]; + if (viewerAgentId) { + headers["X-AgentMemory-Agent-Id"] = viewerAgentId; + } + if (viewerCallerToken) { + headers["X-AgentMemory-Caller-Token"] = viewerCallerToken; + } const ct = req.headers["content-type"]; if (ct) { headers["Content-Type"] = ct; diff --git a/test/cli-replay-headers.test.ts b/test/cli-replay-headers.test.ts new file mode 100644 index 0000000000..93e16508d7 --- /dev/null +++ b/test/cli-replay-headers.test.ts @@ -0,0 +1,102 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { spawn, type ChildProcess } from "node:child_process"; +import { createServer, type IncomingHttpHeaders, type Server } from "node:http"; +import type { AddressInfo } from "node:net"; + +describe("CLI replay import caller headers", () => { + let upstream: Server | undefined; + let child: ChildProcess | undefined; + + afterEach(async () => { + if (child && child.exitCode === null) { + child.kill("SIGTERM"); + } + child = undefined; + if (upstream) { + await new Promise((resolve) => upstream!.close(() => resolve())); + upstream = undefined; + } + }); + + it( + "uses the shared JSON headers including caller identity", + async () => { + let replayHeaders: IncomingHttpHeaders | undefined; + upstream = createServer((req, res) => { + if (req.url === "/agentmemory/livez") { + res.writeHead(200, { "Content-Type": "application/json" }); + res.end(JSON.stringify({ success: true })); + return; + } + if ( + req.url === "/agentmemory/replay/import-jsonl" && + req.method === "POST" + ) { + replayHeaders = req.headers; + res.writeHead(200, { "Content-Type": "application/json" }); + res.end( + JSON.stringify({ + success: true, + imported: 0, + observations: 0, + sessionIds: [], + }), + ); + return; + } + res.writeHead(404).end(); + }); + upstream.listen(0); + await new Promise((resolve) => + upstream!.once("listening", () => resolve()), + ); + const port = (upstream.address() as AddressInfo).port; + + child = spawn( + process.execPath, + [ + "--import", + "tsx", + "src/cli.ts", + "import-jsonl", + "--port", + String(port), + ], + { + cwd: process.cwd(), + env: { + ...process.env, + AGENTMEMORY_URL: "", + AGENTMEMORY_SECRET: "api-secret", + AGENT_ID: "cli-agent", + AGENTMEMORY_CALLER_TOKEN: "cli-caller-secret", + FORCE_COLOR: "0", + }, + stdio: ["ignore", "pipe", "pipe"], + }, + ); + + let stdout = ""; + let stderr = ""; + child.stdout?.on("data", (chunk) => { + stdout += String(chunk); + }); + child.stderr?.on("data", (chunk) => { + stderr += String(chunk); + }); + const exitCode = await new Promise((resolve, reject) => { + child!.once("error", reject); + child!.once("exit", resolve); + }); + + expect(exitCode, `${stdout}\n${stderr}`).toBe(0); + expect(replayHeaders?.authorization).toBe("Bearer api-secret"); + expect(replayHeaders?.["x-agentmemory-agent-id"]).toBe("cli-agent"); + expect(replayHeaders?.["x-agentmemory-caller-token"]).toBe( + "cli-caller-secret", + ); + expect(replayHeaders?.["content-type"]).toBe("application/json"); + }, + 15_000, + ); +}); diff --git a/test/consolidation-pipeline.test.ts b/test/consolidation-pipeline.test.ts index 5f72090ced..d379ebc073 100644 --- a/test/consolidation-pipeline.test.ts +++ b/test/consolidation-pipeline.test.ts @@ -6,6 +6,8 @@ vi.mock("../src/logger.js", () => ({ vi.mock("../src/config.js", () => ({ getConsolidationDecayDays: () => 30, + getAgentId: () => "test-agent", + getEnvVar: () => undefined, isConsolidationEnabled: vi.fn(() => true), })); diff --git a/test/diagnostics.test.ts b/test/diagnostics.test.ts index 48b28e52b1..266f1ab613 100644 --- a/test/diagnostics.test.ts +++ b/test/diagnostics.test.ts @@ -1,3 +1,4 @@ +import { createHash } from "node:crypto"; import { describe, it, expect, beforeEach, vi } from "vitest"; vi.mock("../src/logger.js", () => ({ @@ -5,6 +6,11 @@ vi.mock("../src/logger.js", () => ({ })); import { registerDiagnosticsFunction } from "../src/functions/diagnostics.js"; +import { + resolveLessonBoundaryAccess, + type LessonAccessContext, + type LessonCallerPolicy, +} from "../src/functions/lesson-access.js"; import type { Action, ActionEdge, @@ -16,6 +22,7 @@ import type { Session, Memory, MeshPeer, + Lesson, } from "../src/types.js"; import { KV } from "../src/state/schema.js"; @@ -176,6 +183,67 @@ function makePeer(overrides: Partial = {}): MeshPeer { }; } +function makeScopedLesson( + id: string, + scopeId: string, + overrides: Partial = {}, +): Lesson { + return { + id, + content: `Lesson ${id}`, + context: "", + confidence: 0.8, + reinforcements: 0, + source: "manual", + sourceIds: [], + project: "agentmemory", + tags: [], + createdAt: "2026-08-03T00:00:00.000Z", + updatedAt: "2026-08-03T00:00:00.000Z", + decayRate: 0.05, + schemaVersion: 1, + identityKind: "canonical", + mechanismId: `diagnostics/${id}`, + claim: `Diagnostics projection covers ${id}.`, + evidenceVerdict: "unverified", + lifecycle: "active", + applicabilityConditions: [], + nonApplicabilityConditions: [], + falsificationConditions: [], + structuredFacets: {}, + evidenceRefs: [], + scope: { ring: "repo", scopeId }, + sensitivity: "internal", + contradictedByLessonIds: [], + ...overrides, + }; +} + +function scopedLessonReaderContext(): LessonAccessContext { + const token = "diagnostics-reader-token"; + const policy: LessonCallerPolicy = { + version: 1, + principals: [{ + principalId: "diagnostics-reader", + principalKind: "agent", + tokenSha256: createHash("sha256").update(token).digest("hex"), + clearance: "confidential", + scopes: [{ + ring: "repo", + scopeId: "repo:visible", + access: "read", + }], + capabilities: [], + }], + }; + const resolved = resolveLessonBoundaryAccess( + { "x-agentmemory-caller-token": token }, + { mode: "enforce", policy }, + ); + if (!resolved.success) throw new Error("test access context did not resolve"); + return resolved.context; +} + describe("Diagnostics Functions", () => { let sdk: ReturnType; let kv: ReturnType; @@ -713,6 +781,62 @@ describe("Diagnostics Functions", () => { ); }); + it("lessons category: enforce mode exposes only readable checks and bounded projection failure", async () => { + await kv.set( + KV.lessons, + "lsn_visible_bad_confidence", + makeScopedLesson( + "lsn_visible_bad_confidence", + "repo:visible", + { confidence: 1.5 }, + ), + ); + await kv.set( + KV.lessons, + "lsn_hidden_private", + makeScopedLesson("lsn_hidden_private", "repo:hidden", { + content: "hidden diagnostic content", + }), + ); + await kv.set(KV.lessons, "lsn_hidden_malformed", { + ...makeScopedLesson("lsn_hidden_malformed", "repo:visible"), + evidenceRefs: "private malformed evidence detail", + }); + + const result = (await sdk.trigger("mem::diagnose", { + categories: ["lessons"], + accessContext: scopedLessonReaderContext(), + })) as { checks: DiagnosticCheck[] }; + + expect(result.checks).toContainEqual( + expect.objectContaining({ + name: "lesson-bad-confidence:lsn_visible_bad_confidence", + status: "warn", + }), + ); + expect(result.checks).toContainEqual({ + name: "lesson-projection-incomplete", + category: "lessons", + status: "fail", + message: + "Lesson diagnostics are incomplete because one or more authoritative rows were unreadable or invalid", + fixable: false, + }); + expect( + result.checks.filter( + (check) => check.name === "lesson-projection-incomplete", + ), + ).toHaveLength(1); + const serialized = JSON.stringify(result.checks); + expect(serialized).not.toContain("lsn_hidden_private"); + expect(serialized).not.toContain("hidden diagnostic content"); + expect(serialized).not.toContain("lsn_hidden_malformed"); + expect(serialized).not.toContain("private malformed evidence detail"); + expect(result.checks).not.toContainEqual( + expect.objectContaining({ name: "lessons-ok" }), + ); + }); + it("summaries category: warns on missing title", async () => { await kv.set(KV.summaries, "ses_1", { sessionId: "ses_1", project: "p", createdAt: "", title: "", diff --git a/test/governance.test.ts b/test/governance.test.ts index 6390bbeea6..dea1b3c055 100644 --- a/test/governance.test.ts +++ b/test/governance.test.ts @@ -1,3 +1,4 @@ +import { createHash } from "node:crypto"; import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"; vi.mock("../src/logger.js", () => ({ @@ -10,7 +11,12 @@ import { setIndexPersistence, } from "../src/functions/search.js"; import { memoryToObservation } from "../src/state/memory-utils.js"; -import type { Memory, AuditEntry } from "../src/types.js"; +import { + resolveLessonBoundaryAccess, + type LessonAccessContext, + type LessonCallerPolicy, +} from "../src/functions/lesson-access.js"; +import type { Memory, AuditEntry, Lesson } from "../src/types.js"; function mockKV() { const store = new Map>(); @@ -68,6 +74,83 @@ function makeMemory(id: string, type: Memory["type"] = "pattern"): Memory { }; } +function makeScopedLesson( + id: string, + scopeId: string, + sensitivity: Lesson["sensitivity"] = "internal", +): Lesson { + return { + id, + content: `Lesson ${id}`, + context: "", + confidence: 0.8, + reinforcements: 0, + source: "manual", + sourceIds: [], + project: "agentmemory", + tags: [], + createdAt: "2026-08-03T00:00:00.000Z", + updatedAt: "2026-08-03T00:00:00.000Z", + decayRate: 0.05, + schemaVersion: 1, + identityKind: "canonical", + mechanismId: `audit/${id}`, + claim: `Audit projection covers ${id}.`, + evidenceVerdict: "unverified", + lifecycle: "active", + applicabilityConditions: [], + nonApplicabilityConditions: [], + falsificationConditions: [], + structuredFacets: {}, + evidenceRefs: [], + scope: { ring: "repo", scopeId }, + sensitivity, + contradictedByLessonIds: [], + }; +} + +function scopedReaderContext(): LessonAccessContext { + const token = "governance-reader-token"; + const policy: LessonCallerPolicy = { + version: 1, + principals: [{ + principalId: "audit-reader", + principalKind: "agent", + tokenSha256: createHash("sha256").update(token).digest("hex"), + clearance: "confidential", + scopes: [{ + ring: "repo", + scopeId: "repo:visible", + access: "read", + }], + capabilities: [], + }], + }; + const resolved = resolveLessonBoundaryAccess( + { "x-agentmemory-caller-token": token }, + { mode: "enforce", policy }, + ); + if (!resolved.success) throw new Error("test access context did not resolve"); + return resolved.context; +} + +function makeAuditEntry( + id: string, + operation: AuditEntry["operation"], + functionId: string, + targetIds: string[], + details: Record = {}, +): AuditEntry { + return { + id, + timestamp: "2026-08-03T00:00:00.000Z", + operation, + functionId, + targetIds, + details, + }; +} + describe("Governance Functions", () => { let sdk: ReturnType; let kv: ReturnType; @@ -253,4 +336,100 @@ describe("Governance Functions", () => { expect(entries[0].operation).toBe("delete"); expect(entries[0].functionId).toBe("mem::governance-delete"); }); + + it("audit-query fail-closes lesson rows against the sealed caller projection", async () => { + const visible = makeScopedLesson("lsn_visible", "repo:visible"); + visible.idAliases = ["lsn_visible_alias"]; + const hidden = makeScopedLesson("lsn_hidden", "repo:hidden"); + await kv.set("mem:lessons", visible.id, visible); + await kv.set("mem:lessons", hidden.id, hidden); + + const auditEntries = [ + makeAuditEntry( + "aud_visible", + "lesson_save", + "mem::lesson-save", + [visible.id], + ), + makeAuditEntry( + "aud_hidden", + "lesson_save", + "mem::lesson-save", + [hidden.id], + ), + makeAuditEntry( + "aud_mixed", + "lesson_strengthen", + "mem::lesson-strengthen", + [visible.id, hidden.id], + ), + makeAuditEntry( + "aud_missing", + "lesson_delete", + "mem::lesson-delete", + ["lsn_missing"], + ), + makeAuditEntry( + "aud_no_targets", + "lesson_recall", + "mem::lesson-recall", + [], + { query: "private terms" }, + ), + makeAuditEntry( + "aud_import_visible", + "import", + "mem::import:lessons", + [visible.id], + ), + makeAuditEntry( + "aud_visible_alias", + "lesson_strengthen", + "mem::lesson-strengthen", + ["lsn_visible_alias"], + ), + makeAuditEntry( + "aud_ordinary", + "delete", + "mem::governance-delete", + ["mem_1"], + ), + ]; + for (const entry of auditEntries) { + await kv.set("mem:audit", entry.id, entry); + } + + const classifyEntries = (await sdk.trigger( + "mem::audit-query", + {}, + )) as AuditEntry[]; + expect(classifyEntries).toHaveLength(auditEntries.length); + + const enforceEntries = (await sdk.trigger("mem::audit-query", { + accessContext: scopedReaderContext(), + })) as AuditEntry[]; + expect(enforceEntries.map((entry) => entry.id).sort()).toEqual([ + "aud_import_visible", + "aud_ordinary", + "aud_visible", + "aud_visible_alias", + ]); + expect(JSON.stringify(enforceEntries)).not.toContain("lsn_hidden"); + expect(JSON.stringify(enforceEntries)).not.toContain("private terms"); + + const sealed = scopedReaderContext(); + const forgedEntries = (await sdk.trigger("mem::audit-query", { + accessContext: { + ...sealed, + scopes: [{ + ring: "repo", + scopeId: "repo:hidden", + access: "read", + }], + }, + })) as AuditEntry[]; + expect(forgedEntries.map((entry) => entry.id)).toEqual([ + "aud_ordinary", + ]); + }); }); diff --git a/test/hermes-plugin.test.ts b/test/hermes-plugin.test.ts index 87e7ed6441..e6e4ac37e2 100644 --- a/test/hermes-plugin.test.ts +++ b/test/hermes-plugin.test.ts @@ -1,5 +1,8 @@ import { describe, expect, it } from "vitest"; +import { spawnSync } from "node:child_process"; import { readFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; const expectedHermesHooks = [ "prefetch", @@ -68,4 +71,52 @@ describe("Hermes plugin manifest", () => { /os\.environ\.setdefault\(\s*["']AGENTMEMORY_URL["']\s*,\s*DEFAULT_BASE_URL\s*\)/, ); }); + + it("forwards the configured agent identity and caller token", () => { + const script = String.raw` +import importlib.util + +spec = importlib.util.spec_from_file_location("agentmemory_hermes", "integrations/hermes/__init__.py") +mod = importlib.util.module_from_spec(spec) +assert spec.loader is not None +spec.loader.exec_module(mod) + +seen = [] +class FakeResponse: + def __enter__(self): + return self + def __exit__(self, exc_type, exc, tb): + return False + def read(self): + return b'{"success": true}' + +def fake_urlopen(req, timeout=0): + seen.append({key.lower(): value for key, value in req.header_items()}) + return FakeResponse() + +mod.urlopen = fake_urlopen +result = mod._api("http://localhost:3111", "smart-search", {"query": "auth"}) +assert result == {"success": True}, result +assert seen[0]["authorization"] == "Bearer api-secret", seen[0] +assert seen[0]["x-agentmemory-agent-id"] == "hermes-agent", seen[0] +assert seen[0]["x-agentmemory-caller-token"] == "hermes-caller-secret", seen[0] +`; + const emptyConfigDir = join( + tmpdir(), + `agentmemory-hermes-caller-test-${process.pid}`, + ); + const result = spawnSync("python3", ["-c", script], { + cwd: process.cwd(), + env: { + ...process.env, + HOME: emptyConfigDir, + XDG_CONFIG_HOME: emptyConfigDir, + AGENTMEMORY_SECRET: "api-secret", + AGENT_ID: "hermes-agent", + AGENTMEMORY_CALLER_TOKEN: "hermes-caller-secret", + }, + encoding: "utf8", + }); + expect(result.status, result.stderr || result.stdout).toBe(0); + }); }); diff --git a/test/integration-plaintext-http.test.ts b/test/integration-plaintext-http.test.ts index 70ef689f51..fdb87fac4b 100644 --- a/test/integration-plaintext-http.test.ts +++ b/test/integration-plaintext-http.test.ts @@ -75,6 +75,17 @@ describe("OpenClaw plaintext bearer guard", () => { ); expect(fetchMock).not.toHaveBeenCalled(); }); + + it("also refuses caller-token-only authentication over remote plaintext", () => { + delete process.env["AGENTMEMORY_SECRET"]; + process.env["AGENTMEMORY_CALLER_TOKEN"] = "caller-secret"; + process.env["AGENTMEMORY_REQUIRE_HTTPS"] = "1"; + const fetchMock = mockFetch(); + expect(() => registerOpenClaw("http://remote.example:3111")).toThrow( + /plaintext HTTP to http:\/\/remote\.example:3111/, + ); + expect(fetchMock).not.toHaveBeenCalled(); + }); }); describe("pi plaintext bearer guard", () => { @@ -199,6 +210,16 @@ except RuntimeError as exc: else: raise AssertionError("expected RuntimeError") assert calls == [], calls + +os.environ.pop("AGENTMEMORY_SECRET", None) +os.environ["AGENTMEMORY_CALLER_TOKEN"] = "caller-secret" +try: + mod._api("http://remote.example:3111", "health", method="GET") +except RuntimeError as exc: + assert "plaintext HTTP to http://remote.example:3111" in str(exc), exc +else: + raise AssertionError("expected caller-token RuntimeError") +assert calls == [], calls `; const result = spawnSync("python3", ["-c", script], { cwd: process.cwd(), diff --git a/test/lesson-access.test.ts b/test/lesson-access.test.ts index 8c29e07d6b..4fed77a9b8 100644 --- a/test/lesson-access.test.ts +++ b/test/lesson-access.test.ts @@ -308,6 +308,16 @@ describe("lesson access decisions", () => { }), ), ).toBe(true); + expect( + canWriteLessonScope( + { ring: "worktree" }, + "restricted", + context({ + clearance: "restricted", + capabilities: ["lesson:legacy-worktree"], + }), + ), + ).toBe(false); expect(canUseLessonCapability(context(), "lesson:export")).toBe(false); expect( canUseLessonCapability( @@ -388,6 +398,13 @@ describe("lesson access decisions", () => { it("gives only the explicit system context full internal access", () => { const system = systemLessonAccessContext(); expect(canReadLesson(lesson("restricted"), system)).toBe(true); + expect( + canWriteLessonScope( + { ring: "worktree" }, + "restricted", + system, + ), + ).toBe(true); expect(canUseLessonCapability(system, "lesson:import")).toBe(true); expect(canApproveGlobalLesson(system)).toBe(false); }); diff --git a/test/lesson-authorization.test.ts b/test/lesson-authorization.test.ts index 8c617d3088..79b615d375 100644 --- a/test/lesson-authorization.test.ts +++ b/test/lesson-authorization.test.ts @@ -10,13 +10,19 @@ vi.mock("../src/logger.js", () => ({ import { registerExportImportFunction } from "../src/functions/export-import.js"; import { registerContextFunction } from "../src/functions/context.js"; +import { registerCrystallizeFunction } from "../src/functions/crystallize.js"; import { systemLessonAccessContext } from "../src/functions/lesson-access.js"; import { registerLessonsFunctions } from "../src/functions/lessons.js"; import { registerReflectFunctions } from "../src/functions/reflect.js"; import { registerSmartSearchFunction } from "../src/functions/smart-search.js"; import { registerMcpEndpoints } from "../src/mcp/server.js"; import { registerApiTriggers } from "../src/triggers/api.js"; -import type { ExportData, Lesson } from "../src/types.js"; +import type { + Crystal, + ExportData, + Insight, + Lesson, +} from "../src/types.js"; import { mockKV, mockSdk } from "./helpers/mocks.js"; const REPO_ONE = { @@ -89,7 +95,24 @@ describe("lesson authorization boundaries", () => { tokenSha256: tokenDigest("human-token"), clearance: "restricted", scopes: [{ ring: "global", access: "write" }], - capabilities: ["lesson:approve-global"], + capabilities: [ + "lesson:approve-global", + "lesson:all-scopes", + "lesson:export", + "lesson:import", + ], + }, + { + principalId: "backup-service", + principalKind: "service", + tokenSha256: tokenDigest("backup-token"), + clearance: "restricted", + scopes: [], + capabilities: [ + "lesson:all-scopes", + "lesson:export", + "lesson:import", + ], }, ], }), @@ -101,6 +124,19 @@ describe("lesson authorization boundaries", () => { kv = mockKV(); reflectionPrompts = []; registerLessonsFunctions(sdk as never, kv as never); + registerCrystallizeFunction( + sdk as never, + kv as never, + { + summarize: async () => + JSON.stringify({ + narrative: "Authorized crystal", + keyOutcomes: ["done"], + filesAffected: [], + lessons: ["Derived crystallization lesson"], + }), + } as never, + ); registerContextFunction(sdk as never, kv as never, 2000); registerSmartSearchFunction( sdk as never, @@ -185,7 +221,7 @@ describe("lesson authorization boundaries", () => { expect(await kv.list("mem:lessons")).toHaveLength(1); }); - it("filters list, recall, and export totals without revealing other scopes", async () => { + it("filters list and recall totals without revealing other scopes", async () => { const system = systemLessonAccessContext(); await sdk.trigger("mem::lesson-save", { ...lessonInput("visible"), @@ -210,21 +246,39 @@ describe("lesson authorization boundaries", () => { status_code: number; body: { lessons: Lesson[] }; }; - const exported = (await sdk.trigger("api::export", { - headers: headers("codex-token", "codex"), - query_params: {}, - })) as { status_code: number; body: ExportData }; - expect(list.body.total).toBe(1); expect(list.body.lessons.map((lesson) => lesson.mechanismId)).toEqual([ "authorization/visible", ]); expect(recall.body.lessons).toHaveLength(1); - expect(exported.status_code).toBe(200); - expect(exported.body.lessons).toHaveLength(1); - expect(exported.body.lessons?.[0].mechanismId).toBe( - "authorization/visible", - ); + }); + + it("reserves whole-database export for a restricted all-scopes operator", async () => { + const system = systemLessonAccessContext(); + await sdk.trigger("mem::lesson-save", { + ...lessonInput("operator-visible"), + accessContext: system, + }); + await sdk.trigger("mem::lesson-save", { + ...lessonInput("operator-other", REPO_TWO), + accessContext: system, + }); + + const repoCaller = (await sdk.trigger("api::export", { + headers: headers("codex-token", "codex"), + query_params: {}, + })) as { status_code: number; body: { code: string } }; + const operator = (await sdk.trigger("api::export", { + headers: headers("human-token", "patrick"), + query_params: {}, + })) as { status_code: number; body: ExportData }; + + expect(repoCaller).toMatchObject({ + status_code: 403, + body: { code: "access_denied" }, + }); + expect(operator.status_code).toBe(200); + expect(operator.body.lessons).toHaveLength(2); }); it("filters injected context and smart-search lesson results", async () => { @@ -302,7 +356,7 @@ describe("lesson authorization boundaries", () => { }); }); - it("rejects an out-of-scope import before writing any lesson", async () => { + it("rejects a non-operator import before writing any lesson", async () => { const candidate = (await sdk.trigger("mem::lesson-save", { ...lessonInput("import-hidden", REPO_TWO), accessContext: systemLessonAccessContext(), @@ -367,6 +421,170 @@ describe("lesson authorization boundaries", () => { }); }); + it("requires a human operator to restore a global lesson", async () => { + const saved = (await sdk.trigger("api::lesson-save", { + headers: headers("human-token", "patrick"), + body: { + content: "Restorable global causal lesson", + mechanismId: "authorization/global-restore", + claim: "Global restoration requires a fresh human approval.", + scope: { + ring: "global", + humanApproval: { + approvedAt: "2026-08-03T01:00:00.000Z", + reason: "Approved for backup restoration.", + }, + }, + sensitivity: "internal", + }, + })) as { body: { lesson: Lesson } }; + await kv.delete("mem:lessons", saved.body.lesson.id); + const exportData: ExportData = { + version: "0.9.27", + exportedAt: "2026-08-03T01:00:00.000Z", + sessions: [], + observations: {}, + memories: [], + summaries: [], + lessons: [saved.body.lesson], + }; + + const service = (await sdk.trigger("api::import", { + headers: headers("backup-token", "backup-service"), + body: { exportData, strategy: "merge" }, + })) as { status_code: number; body: { code: string } }; + expect(service).toMatchObject({ + status_code: 403, + body: { code: "access_denied" }, + }); + expect(await kv.list("mem:lessons")).toEqual([]); + + const human = (await sdk.trigger("api::import", { + headers: headers("human-token", "patrick"), + body: { exportData, strategy: "merge" }, + })) as { status_code: number; body: { success: boolean } }; + const restored = await kv.get( + "mem:lessons", + saved.body.lesson.id, + ); + expect(human).toMatchObject({ + status_code: 200, + body: { success: true }, + }); + expect(restored?.scope?.humanApproval?.approvedBy).toBe("patrick"); + expect(restored?.scope?.humanApproval?.approvedAt).not.toBe( + saved.body.lesson.scope?.humanApproval?.approvedAt, + ); + }); + + it("filters crystals and insights by their lesson provenance", async () => { + const system = systemLessonAccessContext(); + const visible = (await sdk.trigger("mem::lesson-save", { + ...lessonInput("projection-visible"), + accessContext: system, + })) as { lesson: Lesson }; + const hidden = (await sdk.trigger("mem::lesson-save", { + ...lessonInput("projection-hidden", REPO_TWO), + accessContext: system, + })) as { lesson: Lesson }; + + const visibleCrystal: Crystal = { + id: "crys_visible", + narrative: "Visible crystal", + keyOutcomes: [], + filesAffected: [], + lessons: [visible.lesson.content], + sourceLessonIds: [visible.lesson.id], + sourceActionIds: [], + createdAt: "2026-08-03T01:00:00.000Z", + }; + const hiddenCrystal: Crystal = { + ...visibleCrystal, + id: "crys_hidden", + narrative: "Hidden crystal", + lessons: [hidden.lesson.content], + sourceLessonIds: [hidden.lesson.id], + }; + await kv.set("mem:crystals", visibleCrystal.id, visibleCrystal); + await kv.set("mem:crystals", hiddenCrystal.id, hiddenCrystal); + + const insightBase: Insight = { + id: "ins_visible", + title: "Visible insight", + content: "Visible derived content", + confidence: 0.8, + reinforcements: 0, + sourceConceptCluster: [], + sourceMemoryIds: [], + sourceLessonIds: [visible.lesson.id], + sourceCrystalIds: [visibleCrystal.id], + tags: [], + createdAt: "2026-08-03T01:00:00.000Z", + updatedAt: "2026-08-03T01:00:00.000Z", + decayRate: 0.05, + }; + await kv.set("mem:insights", insightBase.id, insightBase); + await kv.set("mem:insights", "ins_hidden", { + ...insightBase, + id: "ins_hidden", + title: "Hidden insight", + content: "Hidden derived content", + sourceLessonIds: [hidden.lesson.id], + sourceCrystalIds: [hiddenCrystal.id], + }); + await kv.set("mem:crystals", "crys_spoofed", { + ...visibleCrystal, + id: "crys_spoofed", + narrative: "Spoofed crystal", + lessons: ["Hidden derived content with visible provenance"], + }); + + const crystals = (await sdk.trigger("api::crystal-list", { + headers: headers("codex-token", "codex"), + query_params: {}, + })) as { body: { crystals: Crystal[] } }; + const insights = (await sdk.trigger("api::insight-list", { + headers: headers("codex-token", "codex"), + query_params: {}, + })) as { body: { insights: Insight[] } }; + + expect(crystals.body.crystals.map((crystal) => crystal.id)).toEqual([ + visibleCrystal.id, + ]); + expect(insights.body.insights.map((insight) => insight.id)).toEqual([ + insightBase.id, + ]); + expect(JSON.stringify({ crystals, insights })).not.toContain( + "Hidden derived", + ); + expect(crystals.body.crystals.map((crystal) => crystal.id)).not.toContain( + "crys_spoofed", + ); + }); + + it("does not mint system authority for public crystallization", async () => { + await kv.set("mem:actions", "act_crystallize", { + id: "act_crystallize", + title: "Crystallize safely", + status: "done", + lifecycle: "done", + priority: 5, + tags: [], + createdAt: "2026-08-03T01:00:00.000Z", + updatedAt: "2026-08-03T01:00:00.000Z", + }); + + const response = (await sdk.trigger("api::crystallize", { + headers: headers("codex-token", "codex"), + body: { actionIds: ["act_crystallize"], project: "agentmemory" }, + })) as { status_code: number; body: { crystal: Crystal } }; + + expect(response.status_code).toBe(200); + expect(response.body.crystal.lessons).toEqual([]); + expect(response.body.crystal.sourceLessonIds).toEqual([]); + expect(await kv.list("mem:lessons")).toEqual([]); + }); + it("server-stamps correction actors across REST and MCP", async () => { const saved = (await sdk.trigger("api::lesson-save", { headers: headers("codex-token", "codex"), diff --git a/test/mcp-http.test.ts b/test/mcp-http.test.ts index cc9b9b9047..d3c233baae 100644 --- a/test/mcp-http.test.ts +++ b/test/mcp-http.test.ts @@ -257,4 +257,24 @@ describe("AgentMemory Streamable HTTP transport", () => { await backend.callTool("memory_next", { project: "workstation" }), ).toEqual({ content: [{ type: "text", text: "ok" }] }); }); + + it("preserves structured authorization errors from the engine", async () => { + const fetchImpl = vi.fn(async () => + new Response( + JSON.stringify({ + code: "lesson_access_denied", + error: "lesson access denied", + }), + { status: 403, statusText: "Forbidden" }, + ), + ); + const backend = createProxyBackend({ + baseUrl: "http://127.0.0.1:3111", + fetchImpl: fetchImpl as typeof fetch, + }); + + await expect(backend.listTools()).rejects.toThrow( + "403 Forbidden; code=lesson_access_denied error=lesson access denied", + ); + }); }); diff --git a/test/mcp-llm-tools.test.ts b/test/mcp-llm-tools.test.ts index 0ec5aef45e..56ca957831 100644 --- a/test/mcp-llm-tools.test.ts +++ b/test/mcp-llm-tools.test.ts @@ -33,7 +33,14 @@ describe("MCP LLM tools", () => { expect(result.status_code).toBe(200); expect(sdk.trigger).toHaveBeenCalledWith({ function_id: "mem::consolidate-pipeline", - payload: { tier: "semantic", force: true }, + payload: { + tier: "semantic", + force: true, + accessContext: expect.objectContaining({ + mode: "classify", + principalId: "legacy-unresolved", + }), + }, }); }); diff --git a/test/mcp-standalone-proxy.test.ts b/test/mcp-standalone-proxy.test.ts index cf5bbd5da3..8d056eded1 100644 --- a/test/mcp-standalone-proxy.test.ts +++ b/test/mcp-standalone-proxy.test.ts @@ -1,6 +1,9 @@ import { describe, expect, it, beforeEach, afterEach, vi } from "vitest"; import { handleToolCall } from "../src/mcp/standalone.js"; -import { resetHandleForTests } from "../src/mcp/rest-proxy.js"; +import { + resetHandleForTests, + resolveHandle, +} from "../src/mcp/rest-proxy.js"; import { InMemoryKV } from "../src/mcp/in-memory-kv.js"; type FetchMock = ReturnType; @@ -28,6 +31,7 @@ describe("@agentmemory/mcp standalone — server proxy (issue #159)", () => { resetHandleForTests(); globalThis.fetch = originalFetch; delete process.env["AGENTMEMORY_URL"]; + delete process.env["AGENTMEMORY_FORCE_PROXY"]; delete process.env["AGENT_ID"]; delete process.env["AGENTMEMORY_CALLER_TOKEN"]; }); @@ -52,6 +56,29 @@ describe("@agentmemory/mcp standalone — server proxy (issue #159)", () => { ); }); + it("preserves bounded structured error diagnostics from the engine", async () => { + process.env["AGENTMEMORY_FORCE_PROXY"] = "1"; + installFetch(() => + new Response( + JSON.stringify({ + code: "lesson_policy_unavailable", + error: "lesson access policy unavailable", + ignored: "x".repeat(2_000), + }), + { status: 503, statusText: "Service Unavailable" }, + ), + ); + + const handle = await resolveHandle(); + expect(handle.mode).toBe("proxy"); + if (handle.mode !== "proxy") throw new Error("expected proxy handle"); + await expect( + handle.call("/agentmemory/lessons", { method: "GET" }), + ).rejects.toThrow( + "503 Service Unavailable; code=lesson_policy_unavailable error=lesson access policy unavailable", + ); + }); + it("proxies memory_sessions to GET /agentmemory/sessions when server is up", async () => { const calls: Array<{ url: string; method: string }> = []; installFetch((url, init) => { diff --git a/test/replay-import-key.test.ts b/test/replay-import-key.test.ts index 04a5e24a5c..5b14b7f840 100644 --- a/test/replay-import-key.test.ts +++ b/test/replay-import-key.test.ts @@ -1,4 +1,11 @@ -import { describe, it, expect, beforeEach, vi } from "vitest"; +import { + afterEach, + beforeEach, + describe, + expect, + it, + vi, +} from "vitest"; import { mkdtempSync, writeFileSync, rmSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; @@ -63,9 +70,15 @@ describe("import-jsonl re-key on parsed.sessionId (#775)", () => { let tmpRoot: string; beforeEach(() => { + delete process.env["AGENTMEMORY_LESSON_ACCESS_MODE"]; tmpRoot = mkdtempSync(join(tmpdir(), "replay-import-key-")); }); + afterEach(() => { + delete process.env["AGENTMEMORY_LESSON_ACCESS_MODE"]; + rmSync(tmpRoot, { recursive: true, force: true }); + }); + function writeFixture( sessionId: string, ts = "2026-04-17T10:00:00.000Z", @@ -276,4 +289,35 @@ describe("import-jsonl re-key on parsed.sessionId (#775)", () => { expect.stringMatching(/^lsn_[a-f0-9]{16}$/), ]); }); + + it("does not mutate lessons directly when enforce mode has no caller authority", async () => { + const content = + "Always reject replay-derived lessons without caller authority."; + writeFixture( + "sess-enforce-no-authority", + "2026-04-17T10:00:00.000Z", + content, + ); + const kv = mockKV(); + const sdk = mockSdk(kv); + registerLessonsFunctions(sdk, kv as never); + registerReplayFunctions(sdk, kv as never); + const saved = (await sdk.trigger("mem::lesson-save", { + content, + project: "proj", + })) as { lesson: Lesson }; + + process.env["AGENTMEMORY_LESSON_ACCESS_MODE"] = "enforce"; + const result = await sdk.trigger("mem::replay::import-jsonl", { + path: tmpRoot, + }); + const stored = await kv.get(KV.lessons, saved.lesson.id); + + expect(result).toMatchObject({ success: true, imported: 1 }); + expect(stored).toMatchObject({ + id: saved.lesson.id, + reinforcements: 0, + sourceIds: [], + }); + }); }); diff --git a/test/viewer-host.test.ts b/test/viewer-host.test.ts index b68ecec4a8..9816758e3c 100644 --- a/test/viewer-host.test.ts +++ b/test/viewer-host.test.ts @@ -140,6 +140,83 @@ describe("requireInboundBearer", () => { }); }); +describe("viewer proxy caller headers", () => { + const originalAgentId = process.env.AGENTMEMORY_VIEWER_AGENT_ID; + const originalCallerToken = + process.env.AGENTMEMORY_VIEWER_CALLER_TOKEN; + let viewer: Server | undefined; + let upstream: Server | undefined; + + afterEach(async () => { + if (viewer) { + await new Promise((resolve) => viewer!.close(() => resolve())); + viewer = undefined; + } + if (upstream) { + await new Promise((resolve) => upstream!.close(() => resolve())); + upstream = undefined; + } + if (originalAgentId === undefined) { + delete process.env.AGENTMEMORY_VIEWER_AGENT_ID; + } else { + process.env.AGENTMEMORY_VIEWER_AGENT_ID = originalAgentId; + } + if (originalCallerToken === undefined) { + delete process.env.AGENTMEMORY_VIEWER_CALLER_TOKEN; + } else { + process.env.AGENTMEMORY_VIEWER_CALLER_TOKEN = originalCallerToken; + } + }); + + async function waitForListening(server: Server): Promise { + if (server.listening) return; + await new Promise((resolve) => + server.once("listening", () => resolve()), + ); + } + + it("adds its server-side lesson principal without exposing or trusting browser credentials", async () => { + process.env.AGENTMEMORY_VIEWER_AGENT_ID = "viewer-service"; + process.env.AGENTMEMORY_VIEWER_CALLER_TOKEN = "viewer-caller-secret"; + + let forwardedHeaders: Record = {}; + upstream = createServer((req, res) => { + forwardedHeaders = req.headers; + res.writeHead(200, { "Content-Type": "application/json" }); + res.end(JSON.stringify({ success: true })); + }); + upstream.listen(0, "127.0.0.1"); + await waitForListening(upstream); + const upstreamPort = (upstream.address() as AddressInfo).port; + + viewer = startViewerServer(0, null, null, undefined, upstreamPort); + await waitForListening(viewer); + const viewerPort = (viewer.address() as AddressInfo).port; + + const response = await fetch( + `http://127.0.0.1:${viewerPort}/agentmemory/lessons`, + { + headers: { + "X-AgentMemory-Agent-Id": "browser-supplied-agent", + "X-AgentMemory-Caller-Token": "browser-supplied-token", + }, + }, + ); + expect(response.status).toBe(200); + expect(forwardedHeaders["x-agentmemory-agent-id"]).toBe( + "viewer-service", + ); + expect(forwardedHeaders["x-agentmemory-caller-token"]).toBe( + "viewer-caller-secret", + ); + + const html = await fetch(`http://127.0.0.1:${viewerPort}/`).then((res) => + res.text(), + ); + expect(html).not.toContain("viewer-caller-secret"); + }); +}); + describe("startViewerServer host binding", () => { const originalEnv = process.env.AGENTMEMORY_VIEWER_HOST; const originalOverride = process.env.VIEWER_ALLOWED_HOSTS; From ce10a9e629c1f1bfba472b763cbe80d04ffcb369 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Mon, 3 Aug 2026 01:38:50 -0400 Subject: [PATCH 39/43] fix: harden remaining lesson access boundaries --- .env.example | 1 + README.md | 7 +- .../2026-08-03-causal-lesson-access-v2.md | 6 +- plugin/skills/agentmemory-config/REFERENCE.md | 3 +- src/functions/audit.ts | 46 +++++-- src/functions/lessons.ts | 25 ++-- src/mcp/http.ts | 18 +++ src/mcp/plaintext-credential.ts | 43 ++++++ src/mcp/rest-proxy.ts | 12 ++ src/triggers/events.ts | 6 +- test/governance.test.ts | 15 ++ test/lesson-corrections.test.ts | 2 +- test/mcp-plaintext-credential.test.ts | 129 ++++++++++++++++++ .../session-start-event-authorization.test.ts | 92 +++++++++++++ 14 files changed, 380 insertions(+), 25 deletions(-) create mode 100644 src/mcp/plaintext-credential.ts create mode 100644 test/mcp-plaintext-credential.test.ts create mode 100644 test/session-start-event-authorization.test.ts diff --git a/.env.example b/.env.example index d2e16dd212..5884795860 100644 --- a/.env.example +++ b/.env.example @@ -97,6 +97,7 @@ # AGENTMEMORY_LESSON_CALLER_POLICY_FILE=/etc/agentmemory/lesson-callers.json # AGENT_ID=codex # AGENTMEMORY_CALLER_TOKEN=unique-client-token +# AGENTMEMORY_REQUIRE_HTTPS=1 # Refuse credentials over non-loopback plaintext HTTP # Give the viewer its own server-side read principal. These values are added # only by the viewer proxy and are never delivered to browser JavaScript. # AGENTMEMORY_VIEWER_AGENT_ID=viewer-service diff --git a/README.md b/README.md index 0ab1d0d094..16cf04536f 100644 --- a/README.md +++ b/README.md @@ -1626,9 +1626,10 @@ an explicit service context; that service cannot approve global lessons. The viewer must use a separate server-side read principal configured with `AGENTMEMORY_VIEWER_AGENT_ID` and `AGENTMEMORY_VIEWER_CALLER_TOKEN`. Browser headers are ignored and the raw viewer token is never embedded in HTML. Pi, -Hermes, OpenClaw, the MCP shims, and the replay CLI forward the caller headers; -their plaintext-HTTP guard treats either the bearer secret or caller token as -a credential. +Hermes, OpenClaw, the standalone MCP shim, streamable HTTP MCP bridge, and the +replay CLI forward the caller headers. Their plaintext-HTTP guards treat either +the bearer secret or caller token as a credential, warn once for a non-loopback +HTTP endpoint, and refuse the request when `AGENTMEMORY_REQUIRE_HTTPS=1`. Import preflights collection shapes and all lesson authorization before its first write. The lesson batch restores exact preimages if a lesson write fails. diff --git a/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md b/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md index 10c74a25b8..fa9855a03e 100644 --- a/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md +++ b/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md @@ -84,8 +84,10 @@ and `AGENT_ID`. The viewer uses a separate server-side identity from `AGENTMEMORY_VIEWER_AGENT_ID` and `AGENTMEMORY_VIEWER_CALLER_TOKEN`. It ignores browser-supplied caller identity headers and never embeds the caller token in -the rendered document. Integration plaintext-HTTP guards treat either -`AGENTMEMORY_SECRET` or `AGENTMEMORY_CALLER_TOKEN` as a credential. +the rendered document. Integration and MCP proxy plaintext-HTTP guards treat +either `AGENTMEMORY_SECRET` or `AGENTMEMORY_CALLER_TOKEN` as a credential, +warn once for non-loopback HTTP, and refuse before the request when +`AGENTMEMORY_REQUIRE_HTTPS=1`. Request bodies and MCP arguments are explicitly whitelisted. A supplied `accessContext` is never forwarded by a public boundary. Direct iii function diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md index 277156716c..40269c354e 100644 --- a/plugin/skills/agentmemory-config/REFERENCE.md +++ b/plugin/skills/agentmemory-config/REFERENCE.md @@ -3,7 +3,7 @@ Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded. -Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 57 recognized variables: +Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 58 recognized variables: - `AGENTMEMORY_AGENT_SCOPE` - `AGENTMEMORY_ALLOW_AGENT_SDK` @@ -45,6 +45,7 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e - `AGENTMEMORY_PROVIDER` - `AGENTMEMORY_REFLECT` - `AGENTMEMORY_REPO_ROOT` +- `AGENTMEMORY_REQUIRE_HTTPS` - `AGENTMEMORY_SCOPE_TYPE` - `AGENTMEMORY_SDK_CHILD` - `AGENTMEMORY_SECRET` diff --git a/src/functions/audit.ts b/src/functions/audit.ts index b8b2019489..7a88f46096 100644 --- a/src/functions/audit.ts +++ b/src/functions/audit.ts @@ -128,15 +128,10 @@ export async function queryAudit( const lessons = await kv.list(KV.lessons); const lessonIndex = buildLessonAccessIndex(lessons); const readableLessonEntries = lessonEntries.filter((entry) => { - if ( - !Array.isArray(entry.targetIds) || - entry.targetIds.length === 0 - ) { - return false; - } + const referencedIds = lessonAuditReferenceIds(entry); + if (referencedIds.length === 0) return false; try { - return entry.targetIds.every((id) => { - if (typeof id !== "string" || id.length === 0) return false; + return referencedIds.every((id) => { const lesson = lessonIndex.get(id); return lesson !== undefined && canReadLesson(lesson, accessContext); @@ -162,6 +157,41 @@ export async function queryAudit( return entries.slice(0, filter?.limit || 100); } +function lessonAuditReferenceIds(entry: AuditEntry): string[] { + const ids = new Set(); + const add = (value: unknown): void => { + if (typeof value === "string" && value.length > 0) ids.add(value); + }; + if (Array.isArray(entry.targetIds)) { + for (const id of entry.targetIds) add(id); + } + + const details = + entry.details && typeof entry.details === "object" + ? entry.details + : undefined; + if (!details) return [...ids]; + + add(details.lessonId); + add(details.replacementLessonId); + for (const field of ["lessonIds", "sourceLessonIds"] as const) { + const values = details[field]; + if (Array.isArray(values)) { + for (const value of values) add(value); + } + } + for (const field of ["canonicalizedIds", "lifecycleTransitions"] as const) { + const values = details[field]; + if (!Array.isArray(values)) continue; + for (const value of values) { + if (value && typeof value === "object" && !Array.isArray(value)) { + add((value as Record).lessonId); + } + } + } + return [...ids]; +} + const LESSON_AUDIT_OPERATIONS = new Set([ "lesson_save", "lesson_recall", diff --git a/src/functions/lessons.ts b/src/functions/lessons.ts index 6fdaa45e4e..60bdef80de 100644 --- a/src/functions/lessons.ts +++ b/src/functions/lessons.ts @@ -289,14 +289,23 @@ async function correctLesson( const operation = mode === "supersede" ? "lesson_supersede" : "lesson_delete"; try { - await recordAudit(kv, operation, `mem::lesson-${mode}`, [lesson.id], { - actor, - reason, - project: lesson.project, - expectedUpdatedAt, - replacementLessonId, - deletedAt: timestamp, - }); + await recordAudit( + kv, + operation, + `mem::lesson-${mode}`, + [ + lesson.id, + ...(replacementLessonId ? [replacementLessonId] : []), + ], + { + actor, + reason, + project: lesson.project, + expectedUpdatedAt, + replacementLessonId, + deletedAt: timestamp, + }, + ); } catch {} return { diff --git a/src/mcp/http.ts b/src/mcp/http.ts index faee41109a..6f0cf8a512 100644 --- a/src/mcp/http.ts +++ b/src/mcp/http.ts @@ -23,6 +23,7 @@ import { resolveEnvOrEmpty, } from "./rest-proxy.js"; import { upstreamHttpError } from "./http-error.js"; +import { createPlaintextCredentialGuard } from "./plaintext-credential.js"; const DEFAULT_ENGINE_URL = "http://127.0.0.1:3111"; const DEFAULT_HOST = "127.0.0.1"; @@ -120,6 +121,13 @@ function engineHeaders(): Record { }; } +function outboundCredential(): string { + return ( + resolveEnvOrEmpty("AGENTMEMORY_SECRET") || + resolveEnvOrEmpty("AGENTMEMORY_CALLER_TOKEN") + ); +} + export function createProxyBackend(options: { baseUrl?: string; fetchImpl?: typeof fetch; @@ -130,8 +138,17 @@ export function createProxyBackend(options: { ) ).replace(/\/+$/, ""); const fetchImpl = options.fetchImpl ?? fetch; + const guardPlaintextCredential = createPlaintextCredentialGuard(); + const guardBackendRequest = () => { + guardPlaintextCredential(baseUrl, outboundCredential()); + }; + + if (resolveEnvOrEmpty("AGENTMEMORY_REQUIRE_HTTPS") === "1") { + guardBackendRequest(); + } async function request(path: string, init: RequestInit): Promise { + guardBackendRequest(); const response = await fetchImpl(`${baseUrl}${path}`, { ...init, headers: { ...(init.headers ?? {}), ...engineHeaders() }, @@ -150,6 +167,7 @@ export function createProxyBackend(options: { return { async health() { + guardBackendRequest(); try { const response = await fetchImpl(`${baseUrl}/agentmemory/livez`, { method: "GET", diff --git a/src/mcp/plaintext-credential.ts b/src/mcp/plaintext-credential.ts new file mode 100644 index 0000000000..3f359c135f --- /dev/null +++ b/src/mcp/plaintext-credential.ts @@ -0,0 +1,43 @@ +const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]); + +function normalizedHostname(hostname: string): string { + return hostname.replace(/^\[|\]$/g, "").toLowerCase(); +} + +function usesPlaintextCredential( + baseUrl: string, + credential?: string, +): boolean { + if (!credential) return false; + try { + const parsed = new URL(baseUrl); + return ( + parsed.protocol === "http:" && + !LOOPBACK_HOSTS.has(normalizedHostname(parsed.hostname)) + ); + } catch { + return false; + } +} + +function plaintextCredentialMessage(baseUrl: string): string { + return `agentmemory: an AGENTMEMORY_SECRET or AGENTMEMORY_CALLER_TOKEN credential is configured for plaintext HTTP to ${baseUrl}. Bearer tokens and memory payloads can be observed on the network; use HTTPS or an SSH tunnel.`; +} + +export function createPlaintextCredentialGuard( + warn: (message: string) => void = (message) => console.warn(message), + env?: { AGENTMEMORY_REQUIRE_HTTPS?: string }, +): (baseUrl: string, credential?: string) => void { + let warned = false; + return (baseUrl, credential) => { + if (!usesPlaintextCredential(baseUrl, credential)) return; + const message = plaintextCredentialMessage(baseUrl); + if ((env ?? process.env).AGENTMEMORY_REQUIRE_HTTPS === "1") { + throw new Error(message); + } + if (!warned) { + warned = true; + warn(message); + } + }; +} diff --git a/src/mcp/rest-proxy.ts b/src/mcp/rest-proxy.ts index 5fe038c001..4042d64612 100644 --- a/src/mcp/rest-proxy.ts +++ b/src/mcp/rest-proxy.ts @@ -1,4 +1,5 @@ import { upstreamHttpError } from "./http-error.js"; +import { createPlaintextCredentialGuard } from "./plaintext-credential.js"; const DEFAULT_URL = "http://localhost:3111"; const DEFAULT_HEALTH_PROBE_TIMEOUT_MS = 2_000; @@ -32,6 +33,7 @@ export type Handle = ProxyHandle | LocalHandle; let cached: Handle | null = null; let cachedAt = 0; let probeInFlight: Promise | null = null; +let guardPlaintextCredential = createPlaintextCredentialGuard(); // `${VAR}`-style placeholders ship in plugin/.mcp.json so MCP hosts that // expand them (Claude Code, Cursor) substitute the user's shell value. @@ -51,6 +53,13 @@ function baseUrl(): string { return (resolveEnvOrEmpty("AGENTMEMORY_URL") || DEFAULT_URL).replace(/\/+$/, ""); } +function outboundCredential(): string { + return ( + resolveEnvOrEmpty("AGENTMEMORY_SECRET") || + resolveEnvOrEmpty("AGENTMEMORY_CALLER_TOKEN") + ); +} + function authHeader(): Record { const secret = resolveEnvOrEmpty("AGENTMEMORY_SECRET"); return secret ? { authorization: `Bearer ${secret}` } : {}; @@ -137,6 +146,7 @@ export async function resolveHandle(): Promise { } if (probeInFlight) return probeInFlight; const url = baseUrl(); + guardPlaintextCredential(url, outboundCredential()); const skipProbe = forceProxy(); probeInFlight = (async () => { const up = skipProbe ? true : await probe(url); @@ -150,6 +160,7 @@ export async function resolveHandle(): Promise { mode: "proxy", baseUrl: url, call: async (path, init) => { + guardPlaintextCredential(url, outboundCredential()); const res = await fetch(`${url}${path}`, { ...init, headers: { @@ -192,4 +203,5 @@ export function resetHandleForTests(): void { cachedAt = 0; probeInFlight = null; livezProbe = defaultLivezProbe; + guardPlaintextCredential = createPlaintextCredentialGuard(); } diff --git a/src/triggers/events.ts b/src/triggers/events.ts index 48224a5b7c..3cc4fec8a8 100644 --- a/src/triggers/events.ts +++ b/src/triggers/events.ts @@ -6,7 +6,7 @@ import { isReflectEnabled } from "../functions/slots.js"; import { isGraphExtractionEnabled } from "../config.js"; import { logger } from "../logger.js"; import { triggerDetached } from "../utils/trigger-detached.js"; -import { systemLessonAccessContext } from "../functions/lesson-access.js"; +import { lessonAccessContextFromPayload } from "../functions/lesson-access.js"; import type { LessonAccessContext } from "../functions/lesson-access.js"; export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { @@ -21,7 +21,9 @@ export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { worktree?: string; branch?: string; taskSlug?: string; + accessContext?: unknown; }) => { + const accessContext = lessonAccessContextFromPayload(data.accessContext); const startedAt = new Date().toISOString(); const session: Session = { id: data.sessionId, @@ -50,7 +52,7 @@ export function registerEventTriggers(sdk: ISdk, kv: StateKV): void { payload: { sessionId: data.sessionId, project: data.project, - accessContext: systemLessonAccessContext(), + accessContext, }, }); return { session, context: contextResult.context }; diff --git a/test/governance.test.ts b/test/governance.test.ts index dea1b3c055..53b5c702ca 100644 --- a/test/governance.test.ts +++ b/test/governance.test.ts @@ -388,6 +388,20 @@ describe("Governance Functions", () => { "mem::lesson-strengthen", ["lsn_visible_alias"], ), + makeAuditEntry( + "aud_hidden_replacement", + "lesson_supersede", + "mem::lesson-supersede", + [visible.id], + { replacementLessonId: hidden.id }, + ), + makeAuditEntry( + "aud_visible_replacement", + "lesson_supersede", + "mem::lesson-supersede", + [visible.id], + { replacementLessonId: visible.id }, + ), makeAuditEntry( "aud_ordinary", "delete", @@ -413,6 +427,7 @@ describe("Governance Functions", () => { "aud_ordinary", "aud_visible", "aud_visible_alias", + "aud_visible_replacement", ]); expect(JSON.stringify(enforceEntries)).not.toContain("lsn_hidden"); expect(JSON.stringify(enforceEntries)).not.toContain("private terms"); diff --git a/test/lesson-corrections.test.ts b/test/lesson-corrections.test.ts index 9831cb2615..8912c7b521 100644 --- a/test/lesson-corrections.test.ts +++ b/test/lesson-corrections.test.ts @@ -145,7 +145,7 @@ describe("lesson corrections", () => { audit.filter((entry) => entry.operation === "lesson_supersede"), ).toEqual([ expect.objectContaining({ - targetIds: [original.id], + targetIds: [original.id, replacement.id], details: expect.objectContaining({ replacementLessonId: replacement.id, }), diff --git a/test/mcp-plaintext-credential.test.ts b/test/mcp-plaintext-credential.test.ts new file mode 100644 index 0000000000..7ddeb5048f --- /dev/null +++ b/test/mcp-plaintext-credential.test.ts @@ -0,0 +1,129 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { + invalidateHandle, + resetHandleForTests, + resolveHandle, + setLivezProbe, +} from "../src/mcp/rest-proxy.js"; +import { createProxyBackend } from "../src/mcp/http.js"; + +afterEach(() => { + resetHandleForTests(); + vi.restoreAllMocks(); + vi.unstubAllEnvs(); +}); + +function configureCredential( + name: "AGENTMEMORY_SECRET" | "AGENTMEMORY_CALLER_TOKEN", + value = "test-credential", +): void { + vi.stubEnv("AGENTMEMORY_SECRET", ""); + vi.stubEnv("AGENTMEMORY_CALLER_TOKEN", ""); + vi.stubEnv(name, value); +} + +describe("standalone MCP proxy plaintext credential guard", () => { + it("warns once before proxying credentials over non-loopback HTTP", async () => { + vi.stubEnv("AGENTMEMORY_URL", "http://remote.example:3111"); + vi.stubEnv("AGENTMEMORY_REQUIRE_HTTPS", ""); + configureCredential("AGENTMEMORY_SECRET"); + const warn = vi.spyOn(console, "warn").mockImplementation(() => {}); + const livezProbe = vi.fn(async () => ({ ok: true })); + setLivezProbe(livezProbe); + + expect((await resolveHandle()).mode).toBe("proxy"); + invalidateHandle(); + expect((await resolveHandle()).mode).toBe("proxy"); + + expect(warn).toHaveBeenCalledTimes(1); + expect(warn.mock.calls[0]?.[0]).toContain( + "plaintext HTTP to http://remote.example:3111", + ); + expect(livezProbe).toHaveBeenCalledTimes(2); + }); + + it("refuses caller-token-only remote HTTP before the livez probe", async () => { + vi.stubEnv("AGENTMEMORY_URL", "http://remote.example:3111"); + vi.stubEnv("AGENTMEMORY_REQUIRE_HTTPS", "1"); + configureCredential("AGENTMEMORY_CALLER_TOKEN"); + const livezProbe = vi.fn(async () => ({ ok: true })); + setLivezProbe(livezProbe); + + await expect(resolveHandle()).rejects.toThrow( + /plaintext HTTP to http:\/\/remote\.example:3111/, + ); + expect(livezProbe).not.toHaveBeenCalled(); + }); + + it.each([ + "http://localhost:3111", + "http://127.0.0.1:3111", + "http://[::1]:3111", + "https://remote.example", + ])("allows credentials with AGENTMEMORY_REQUIRE_HTTPS=1 for %s", async (url) => { + vi.stubEnv("AGENTMEMORY_URL", url); + vi.stubEnv("AGENTMEMORY_REQUIRE_HTTPS", "1"); + configureCredential("AGENTMEMORY_SECRET"); + const warn = vi.spyOn(console, "warn").mockImplementation(() => {}); + setLivezProbe(async () => ({ ok: true })); + + expect((await resolveHandle()).mode).toBe("proxy"); + expect(warn).not.toHaveBeenCalled(); + }); +}); + +describe("Streamable HTTP MCP backend plaintext credential guard", () => { + it("warns once before proxying credentials over non-loopback HTTP", async () => { + vi.stubEnv("AGENTMEMORY_REQUIRE_HTTPS", ""); + configureCredential("AGENTMEMORY_SECRET"); + const warn = vi.spyOn(console, "warn").mockImplementation(() => {}); + const fetchImpl = vi.fn(async () => new Response("ok", { status: 200 })); + const backend = createProxyBackend({ + baseUrl: "http://remote.example:3111", + fetchImpl: fetchImpl as typeof fetch, + }); + + expect(await backend.health()).toBe(true); + expect(await backend.health()).toBe(true); + + expect(warn).toHaveBeenCalledTimes(1); + expect(warn.mock.calls[0]?.[0]).toContain( + "plaintext HTTP to http://remote.example:3111", + ); + expect(fetchImpl).toHaveBeenCalledTimes(2); + }); + + it("refuses caller-token-only remote HTTP before creating the backend", () => { + vi.stubEnv("AGENTMEMORY_REQUIRE_HTTPS", "1"); + configureCredential("AGENTMEMORY_CALLER_TOKEN"); + const fetchImpl = vi.fn(); + + expect(() => + createProxyBackend({ + baseUrl: "http://remote.example:3111", + fetchImpl: fetchImpl as typeof fetch, + }), + ).toThrow(/plaintext HTTP to http:\/\/remote\.example:3111/); + expect(fetchImpl).not.toHaveBeenCalled(); + }); + + it.each([ + "http://localhost:3111", + "http://127.0.0.1:3111", + "http://[::1]:3111", + "https://remote.example", + ])("allows credentials with AGENTMEMORY_REQUIRE_HTTPS=1 for %s", async (baseUrl) => { + vi.stubEnv("AGENTMEMORY_REQUIRE_HTTPS", "1"); + configureCredential("AGENTMEMORY_SECRET"); + const warn = vi.spyOn(console, "warn").mockImplementation(() => {}); + const fetchImpl = vi.fn(async () => new Response("ok", { status: 200 })); + const backend = createProxyBackend({ + baseUrl, + fetchImpl: fetchImpl as typeof fetch, + }); + + expect(await backend.health()).toBe(true); + expect(warn).not.toHaveBeenCalled(); + expect(fetchImpl).toHaveBeenCalledTimes(1); + }); +}); diff --git a/test/session-start-event-authorization.test.ts b/test/session-start-event-authorization.test.ts new file mode 100644 index 0000000000..0628983812 --- /dev/null +++ b/test/session-start-event-authorization.test.ts @@ -0,0 +1,92 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { registerContextFunction } from "../src/functions/context.js"; +import { + systemLessonAccessContext, +} from "../src/functions/lesson-access.js"; +import { registerLessonsFunctions } from "../src/functions/lessons.js"; +import { registerEventTriggers } from "../src/triggers/events.js"; +import type { Lesson } from "../src/types.js"; +import { mockKV, mockSdk } from "./helpers/mocks.js"; + +const PRIVATE_LESSON_CONTENT = "Restricted session-start event lesson"; + +describe("session-start event lesson authorization", () => { + let sdk: ReturnType; + let kv: ReturnType; + + beforeEach(async () => { + process.env["AGENTMEMORY_LESSON_ACCESS_MODE"] = "enforce"; + sdk = mockSdk(); + kv = mockKV(); + registerLessonsFunctions(sdk as never, kv as never); + registerContextFunction(sdk as never, kv as never, 2_000); + registerEventTriggers(sdk as never, kv as never); + + const saved = (await sdk.trigger("mem::lesson-save", { + content: PRIVATE_LESSON_CONTENT, + project: "private-project", + mechanismId: "authorization/session-start-event", + claim: "Session-start events must preserve caller lesson authority.", + scope: { + ring: "repo", + scopeId: "repo:https://github.com/wrightpt/private-project", + }, + sensitivity: "restricted", + accessContext: systemLessonAccessContext(), + })) as { lesson: Lesson }; + expect(saved.lesson.content).toBe(PRIVATE_LESSON_CONTENT); + }); + + afterEach(() => { + delete process.env["AGENTMEMORY_LESSON_ACCESS_MODE"]; + }); + + it("does not retrieve restricted lessons from absent or forged caller authority", async () => { + const forgedSystemContext = { + ...systemLessonAccessContext(), + authorizationProof: "00".repeat(32), + }; + + for (const [sessionId, accessContext] of [ + ["caller-controlled-absent", undefined], + ["caller-controlled-forged", forgedSystemContext], + ] as const) { + const result = (await sdk.trigger("event::session::started", { + sessionId, + project: "private-project", + cwd: "/tmp/private-project", + ...(accessContext ? { accessContext } : {}), + })) as { context: string }; + + expect(result.context).not.toContain(PRIVATE_LESSON_CONTENT); + } + }); + + it("propagates an explicitly sealed internal service context", async () => { + const result = (await sdk.trigger("event::session::started", { + sessionId: "sealed-service", + project: "private-project", + cwd: "/tmp/private-project", + accessContext: systemLessonAccessContext(), + })) as { context: string }; + + expect(result.context).toContain(PRIVATE_LESSON_CONTENT); + }); + + it("preserves classification-mode compatibility without a context payload", async () => { + process.env["AGENTMEMORY_LESSON_ACCESS_MODE"] = "classify"; + + const result = (await sdk.trigger("event::session::started", { + sessionId: "classification-compatible", + project: "private-project", + cwd: "/tmp/private-project", + })) as { context: string }; + + expect(result.context).toContain(PRIVATE_LESSON_CONTENT); + }); +}); From af9c58f9849d5376800cb59e30a85cf156fb5957 Mon Sep 17 00:00:00 2001 From: wrightpt Date: Mon, 3 Aug 2026 11:35:11 -0400 Subject: [PATCH 40/43] feat: add authorized causal lesson hybrid retrieval --- .env.example | 4 + README.md | 54 +- ...08-03-causal-lesson-hybrid-retrieval-v3.md | 181 +++ plugin/skills/agentmemory-config/REFERENCE.md | 4 +- .../skills/agentmemory-mcp-tools/REFERENCE.md | 2 +- src/functions/lesson-model.ts | 4 +- src/functions/lesson-retrieval.ts | 1021 +++++++++++++++++ src/functions/lessons.ts | 137 +-- src/functions/smart-search.ts | 39 +- src/mcp/server.ts | 27 +- src/mcp/tools-registry.ts | 105 +- src/triggers/api.ts | 51 +- test/causal-lessons-api.test.ts | 175 ++- test/lesson-authorization.test.ts | 74 ++ test/lesson-retrieval.test.ts | 622 ++++++++++ test/smart-search.test.ts | 22 +- 16 files changed, 2359 insertions(+), 163 deletions(-) create mode 100644 docs/superpowers/specs/2026-08-03-causal-lesson-hybrid-retrieval-v3.md create mode 100644 src/functions/lesson-retrieval.ts create mode 100644 test/lesson-retrieval.test.ts diff --git a/.env.example b/.env.example index 5884795860..5ef8294fdb 100644 --- a/.env.example +++ b/.env.example @@ -97,6 +97,10 @@ # AGENTMEMORY_LESSON_CALLER_POLICY_FILE=/etc/agentmemory/lesson-callers.json # AGENT_ID=codex # AGENTMEMORY_CALLER_TOKEN=unique-client-token +# Remote lesson embeddings are off by default because query and eligible lesson +# text leave the process. Local embedding providers do not require this opt-in. +# AGENTMEMORY_LESSON_REMOTE_EMBEDDINGS=true +# AGENTMEMORY_LESSON_EMBED_MAX_SENSITIVITY=public # public|internal|confidential|restricted # AGENTMEMORY_REQUIRE_HTTPS=1 # Refuse credentials over non-loopback plaintext HTTP # Give the viewer its own server-side read principal. These values are added # only by the viewer proxy and are never delivered to browser JavaScript. diff --git a/README.md b/README.md index 16cf04536f..25dae4437e 100644 --- a/README.md +++ b/README.md @@ -1638,12 +1638,60 @@ so a later storage failure during a full multi-collection import can still require operator repair; this is existing portable-import behavior, not an all-or-nothing database transaction. -Automatic contradiction discovery and hybrid/vector lesson retrieval remain -separate follow-up work. See +`memory_lesson_recall` and `POST /agentmemory/lessons/search` accept exact +categorical filters for mechanism, claim type, verdict, facets, tags, scope +ring, and sensitivity. Facet dimensions are ANDed, values within one dimension +are ORed, and requested tags are ANDed. Filtering and authorization happen +before ranking or embedding. + +Direct lesson recall defaults to the prior confidence/relevance/recency lexical +scorer. Set `retrievalMode: "hybrid"` to add causal-document embedding +similarity with two-channel reciprocal-rank fusion. Normal smart-search requests +hybrid lesson recall automatically. Hybrid recall never uses the observation +BM25/vector indexes or knowledge graph. Provider absence, invalid vectors, +timeout, weak semantic signal, policy denial, or more than 256 authorized +candidates returns the same bounded lexical result with a fixed diagnostic +code. Semantic cosine scores below `0.2` do not qualify. + +Set `compact: true` for a deterministic, size-bounded projection without raw +evidence references or source rows. This is the normal smart-search form and is +intended for generation context: + +```json +{ + "query": "have we tried a costed queue-pressure reversal before?", + "project": "trading-system", + "retrievalMode": "hybrid", + "compact": true, + "structuredFacets": { + "asset": ["HYPE", "XMR"], + "horizon": ["5m"] + }, + "evidenceVerdicts": ["supported", "refuted", "mixed"] +} +``` + +Local embedding providers may process every authorized lesson. Remote lesson +embedding is disabled unless +`AGENTMEMORY_LESSON_REMOTE_EMBEDDINGS=true`; its default sensitivity ceiling is +`public`, configurable with +`AGENTMEMORY_LESSON_EMBED_MAX_SENSITIVITY`. Authorized rows above that ceiling +remain eligible for lexical retrieval but their text is not sent to the remote +provider. Only public lesson embeddings enter the shared cache. Protected +internal/confidential/restricted embeddings are request-local so a privileged +retrieval cannot change another authorization domain's cache hits, provider +calls, or lock timing. The public cache is deliberately process-local, lazy, +bounded to 4,096 exact-document fingerprints per provider object, and excluded +from export. Persistent lesson vectors remain a follow-up after providers +expose a stable model identity suitable for an on-disk cache key. + +Automatic contradiction discovery remains separate follow-up work. See [Causal Lesson Schema v1](docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md) for the compatibility/fingerprint contract and [Causal Lesson Access v2](docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md) -for the authorization and rollout contract. +for the authorization and rollout contract, and +[Causal Lesson Hybrid Retrieval v3](docs/superpowers/specs/2026-08-03-causal-lesson-hybrid-retrieval-v3.md) +for retrieval ordering, egress, fallback, and cache invariants. --- diff --git a/docs/superpowers/specs/2026-08-03-causal-lesson-hybrid-retrieval-v3.md b/docs/superpowers/specs/2026-08-03-causal-lesson-hybrid-retrieval-v3.md new file mode 100644 index 0000000000..0b851f71e1 --- /dev/null +++ b/docs/superpowers/specs/2026-08-03-causal-lesson-hybrid-retrieval-v3.md @@ -0,0 +1,181 @@ +# Causal Lesson Hybrid Retrieval v3 + +Date: 2026-08-03 + +Status: implementation contract + +## Goal + +Generation-time memory asks one narrow question: have we effectively tried +something like this before? The answer should come from distilled causal +lessons, not raw backtests, observation-table dumps, or a graph walk. + +PR3 upgrades the existing lesson-recall surfaces: + +- internal function `mem::lesson-recall`; +- REST `POST /agentmemory/lessons/search`; +- MCP `memory_lesson_recall`. + +It does not add a competing search tool or endpoint. `KV.lessons` remains the +authoritative source. Observation BM25/vector indexes and graph retrieval are +not used. + +## Request contract + +Required: + +- `query`, a non-empty string of at most 2,048 characters. + +Optional: + +- `project`; +- `minConfidence` in `[0, 1]`; +- `limit` from 1 through 50; +- `retrievalMode`, `lexical` or `hybrid`; +- `compact`; +- `mechanismId`; +- `claimType`; +- `evidenceVerdicts`; +- `structuredFacets`; +- `tags`; +- `scopeRing`; +- `sensitivity`. + +Unknown boundary fields are ignored. In particular, caller-supplied access +contexts, candidate IDs, lifecycle overrides, and hidden-row flags cannot +change server-resolved authorization or the candidate corpus. + +Facet dimensions are ANDed. Values within one dimension are ORed. Tags are +ANDed. Matches are exact after case and whitespace normalization; substring +matches do not satisfy structured filters. + +Schema v1 facets are string-valued, so PR3 supports exact categorical outcome +buckets but not numeric range predicates. Typed outcome metrics and range +filters require a separate schema revision rather than string parsing inside +the retriever. + +## Ordered retrieval pipeline + +The order is a security invariant: + +1. enumerate and normalize authoritative lesson rows; +2. keep active, non-deleted lessons only; +3. apply the server-resolved read policy; +4. apply confidence, project, mechanism, verdict, scope, sensitivity, tag, and + facet filters; +5. rank only the surviving candidates; +6. project only the returned rows; +7. audit returned lesson IDs and a one-way query fingerprint. + +Unauthorized lesson text, IDs, corpus counts, and provider diagnostics never +enter embedding calls or public retrieval diagnostics. Adding an otherwise +valid unauthorized row must leave the response, provider inputs, and +diagnostics unchanged. Malformed authoritative lesson state fails closed with +a bounded `lesson_state_unavailable` error and no provider call. + +## Lexical compatibility + +Direct recall defaults to `lexical`. It preserves the preceding +confidence-times-relevance-times-recency scorer and output rounding. Stable +lesson-ID ordering resolves exact score ties. Lexical mode performs no +embedding work. + +Smart-search explicitly requests `hybrid` and `compact` for its lesson branch. +Observation results remain independent; a lesson-recall failure produces an +empty lesson list without changing observation results. + +## Hybrid ranking + +The embedding document contains the distilled claim and content, mechanism and +aliases, claim type and verdict, applicability/non-applicability/falsification +conditions, structured facets, and tags. Raw lesson context, evidence +references, and source rows are excluded. + +Hybrid mode: + +1. computes lexical ranks for every authorized, filtered candidate; +2. computes semantic ranks for embedding-eligible candidates; +3. excludes non-finite vectors, dimension mismatches, and cosine similarity + below `0.2`; +4. combines lexical weight `0.4` and semantic weight `0.6` with reciprocal-rank + fusion using `k = 60`; +5. applies a bounded confidence weight and stable lesson-ID tie break. + +A semantic match may be returned with zero lexical overlap. The graph is not a +third ranking channel. + +## Egress policy + +Local providers may embed every authorized candidate. + +Remote providers require the server-owned opt-in +`AGENTMEMORY_LESSON_REMOTE_EMBEDDINGS=true`. The query is part of that explicit +egress decision. Candidate text is additionally bounded by +`AGENTMEMORY_LESSON_EMBED_MAX_SENSITIVITY`, which defaults to `public`. + +Rows above the configured ceiling remain lexical candidates but are not sent +to the remote provider. Mixed requests return the fixed notice +`embedding_sensitivity_filtered`; they do not expose excluded counts or IDs. +If no candidate is embedding-eligible, retrieval falls back entirely with +`embedding_sensitivity_blocked`. An invalid ceiling fails closed. + +## Bounded degradation + +Hybrid work is limited to 256 authorized, filtered candidates, batches of 32, +and a five-second wall-clock semantic budget. The deadline stops new batches +and prevents late results from mutating the cache. The provider interface does +not currently accept an abort signal, so an already-running provider call may +finish after the response; no subsequent batch is scheduled. + +Fixed lexical fallback codes are: + +- `embedding_provider_unavailable`; +- `remote_embedding_disabled`; +- `embedding_policy_invalid`; +- `embedding_sensitivity_blocked`; +- `semantic_candidate_limit_exceeded`; +- `embedding_failed`; +- `semantic_no_signal`. + +Provider error text is never returned. + +## Cache + +PR3 uses a lazy, process-local public cache scoped to the provider object. Keys +include the lesson ID and an exact fingerprint of the complete embedding +document. Changed retrieval text therefore invalidates the entry. Cold +concurrent public misses are serialized and rechecked under one keyed lock. +Public candidate embeddings are bounded to 4,096 entries with oldest-entry +eviction. + +Internal, confidential, and restricted embeddings remain request-local and +never enter the shared cache or its lock. A privileged protected retrieval +therefore cannot change a lower-privileged caller's cache hits, provider calls, +or lock timing. + +The cache is not persisted or exported. A durable vector index is deferred +because the current provider interface exposes name and dimensions but not a +stable model/version identity adequate for a safe persistent cache key. + +## Compact projection + +`compact: true` omits evidence references, source IDs, raw context, and other +large provenance rows. It caps: + +- content at 400 characters; +- claim at 300; +- each condition family at two 160-character entries; +- facets at six sorted dimensions and three 64-character values each; +- tags at eight 64-character entries. + +The projection retains lesson ID, mechanism, claim type, verdict, +contradiction state, confidence, score, scope, sensitivity, project, and +timestamps. One maximally populated projection must remain at or below 6,000 +UTF-8 bytes. + +## Rollout boundary + +Merging PR3 does not rebuild the globally installed package, change the +revision lock, restart `agentmemory.service`, enable remote egress, or activate +hybrid retrieval in the live daemon. Publication, deployment, and activation +remain separate operator decisions. diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md index 40269c354e..53eaf06a9e 100644 --- a/plugin/skills/agentmemory-config/REFERENCE.md +++ b/plugin/skills/agentmemory-config/REFERENCE.md @@ -3,7 +3,7 @@ Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded. -Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 58 recognized variables: +Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 60 recognized variables: - `AGENTMEMORY_AGENT_SCOPE` - `AGENTMEMORY_ALLOW_AGENT_SDK` @@ -30,6 +30,8 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e - `AGENTMEMORY_INJECT_CONTEXT` - `AGENTMEMORY_LESSON_ACCESS_MODE` - `AGENTMEMORY_LESSON_CALLER_POLICY_FILE` +- `AGENTMEMORY_LESSON_EMBED_MAX_SENSITIVITY` +- `AGENTMEMORY_LESSON_REMOTE_EMBEDDINGS` - `AGENTMEMORY_LLM_OK` - `AGENTMEMORY_LLM_TIMEOUT_MS` - `AGENTMEMORY_MAX_PROMPT_CAPTURE_CHARS` diff --git a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md index 95085e99ee..9ed4026d25 100644 --- a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md +++ b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md @@ -33,7 +33,7 @@ agentmemory exposes 60 MCP tools. 7 are in the lean core set (`--tools core` or | `memory_insight_list` | | `project`: string, `minConfidence`: number, `limit`: number | List synthesized insights, higher-order observations derived from patterns across memories, lessons, and crystals. | | `memory_lease` | | `actionId`*: string, `agentId`*: string, `operation`*: string, `result`: string, `ttlMs`: number | Acquire, release, or renew an exclusive lease on an action. Prevents multiple agents from working on the same thing. | | `memory_lesson_delete` | | `lessonId`*: string, `reason`*: string, `project`: string, `expectedUpdatedAt`: string, `actor`: string | Retract one lesson by exact ID when its evidence is invalid, preserving the legacy tombstone fields, correction metadata, and audit trail. Requires a human-readable reason. | -| `memory_lesson_recall` | yes | `query`*: string, `project`: string, `minConfidence`: number, `limit`: number | Search lessons by query. Returns lessons sorted by confidence and recency. Use to check what the agent has learned before making decisions. | +| `memory_lesson_recall` | yes | `query`*: string, `project`: string, `minConfidence`: number, `limit`: integer, `retrievalMode`: string, `compact`: boolean, `mechanismId`: string, `claimType`: string, `evidenceVerdicts`: array, `structuredFacets`: object, `tags`: array, `scopeRing`: string, `sensitivity`: string | Search causal lessons. Legacy-compatible lexical ranking is the default; retrievalMode=hybrid adds semantic similarity after authorization and exact structured prefilters, with deterministic lexical fallback. Use compact=true to inject bounded causal lessons instead of full evidence rows. | | `memory_lesson_save` | yes | `content`*: string, `context`: string, `confidence`: number, `project`: string, `tags`: string, `mechanismId`: string, `mechanismVersion`: string, `mechanismAliases`: array, `claim`: string, `claimType`: string, `evidenceVerdict`: string, `lifecycle`: string, `applicabilityConditions`: array, `nonApplicabilityConditions`: array, `falsificationConditions`: array, `structuredFacets`: object, `evidenceRefs`: array, `scope`: object, `sensitivity`: string, `reviewAfter`: string, `contradictedByLessonIds`: array | Save a legacy prose lesson or a structured causal lesson. Reinforcement tracks reuse without changing evidence confidence; structured inputs support verdict, lifecycle, durable evidence, scope, sensitivity, and deterministic fingerprints. | | `memory_lesson_supersede` | | `lessonId`*: string, `replacementLessonId`*: string, `reason`*: string, `project`: string, `expectedUpdatedAt`: string, `actor`: string | Mark one lesson superseded in favor of an active replacement in the same durable scope, preserving legacy tombstone fields, lineage, and an audit trail. An optional project guard applies only to the original lesson; replacement compatibility follows durable scope rules. | | `memory_llm_smoke` | | none | Run a fixed, non-sensitive LLM connectivity probe. Returns provider/model evidence and performs no persistent AgentMemory or filesystem writes. | diff --git a/src/functions/lesson-model.ts b/src/functions/lesson-model.ts index 3c064ddba3..f9f1396fda 100644 --- a/src/functions/lesson-model.ts +++ b/src/functions/lesson-model.ts @@ -243,7 +243,7 @@ export function parseLessonSaveInput( sort: true, }, ); - const structuredFacets = normalizeStructuredFacets( + const structuredFacets = normalizeLessonStructuredFacets( record.structuredFacets, ); const evidenceRefs = normalizeEvidenceRefs( @@ -875,7 +875,7 @@ function normalizeScope( }; } -function normalizeStructuredFacets( +export function normalizeLessonStructuredFacets( value: unknown, ): Record { if (value === undefined || value === null) return {}; diff --git a/src/functions/lesson-retrieval.ts b/src/functions/lesson-retrieval.ts new file mode 100644 index 0000000000..f5a035b464 --- /dev/null +++ b/src/functions/lesson-retrieval.ts @@ -0,0 +1,1021 @@ +import type { + EmbeddingProvider, + Lesson, + LessonClaimType, + LessonEvidenceVerdict, + LessonReadModel, + LessonScopeRing, + LessonSensitivity, +} from "../types.js"; +import { getEnvVar } from "../config.js"; +import { fingerprintId } from "../state/schema.js"; +import { withKeyedLock } from "../state/keyed-mutex.js"; +import { clipEmbedInput, getEmbeddingProvider } from "./search.js"; +import { + canReadLesson, + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; +import { + normalizeLessonStructuredFacets, + toLessonReadModel, +} from "./lesson-model.js"; + +const MAX_QUERY_LENGTH = 2_048; +const MAX_PROJECT_LENGTH = 512; +const MAX_RECALL_LIMIT = 50; +const MAX_FILTER_TAGS = 32; +const MAX_FILTER_TAG_LENGTH = 256; +const MAX_SEMANTIC_CANDIDATES = 256; +const EMBEDDING_BATCH_SIZE = 32; +const MAX_CACHED_LESSON_EMBEDDINGS = 4_096; +const COMPACT_CONTENT_CHARS = 400; +const COMPACT_CLAIM_CHARS = 300; +const COMPACT_CONDITIONS = 2; +const COMPACT_CONDITION_CHARS = 160; +const COMPACT_FACET_DIMENSIONS = 6; +const COMPACT_FACET_VALUES = 3; +const COMPACT_FACET_VALUE_CHARS = 64; +const COMPACT_TAGS = 8; +const COMPACT_TAG_CHARS = 64; +const COMPACT_MAX_UTF8_BYTES = 6_000; +const RRF_K = 60; +const MIN_SEMANTIC_SCORE = 0.2; +const SEMANTIC_TIMEOUT_MS = 5_000; + +const CLAIM_TYPES = new Set([ + "causal", + "predictive", + "procedural", + "constraint", + "descriptive", +]); +const EVIDENCE_VERDICTS = new Set([ + "supported", + "refuted", + "mixed", + "unverified", +]); +const SCOPE_RINGS = new Set([ + "worktree", + "repo", + "initiative", + "domain", + "global", +]); +const SENSITIVITIES = new Set([ + "public", + "internal", + "confidential", + "restricted", +]); + +export type LessonRetrievalMode = "lexical" | "hybrid"; + +export interface LessonRecallInput { + query: string; + project?: string; + minConfidence: number; + limit: number; + retrievalMode: LessonRetrievalMode; + compact: boolean; + mechanismId?: string; + claimType?: LessonClaimType; + evidenceVerdicts: LessonEvidenceVerdict[]; + structuredFacets: Record; + tags: string[]; + scopeRing?: LessonScopeRing; + sensitivity?: LessonSensitivity; + accessContext?: LessonAccessContext; +} + +export type LessonRecallInputResult = + | { success: true; value: LessonRecallInput } + | { success: false; error: string }; + +export interface LessonRetrievalDiagnostics { + requestedMode: LessonRetrievalMode; + usedMode: LessonRetrievalMode; + returnedCount: number; + fallbackCode?: string; + noticeCode?: string; +} + +export interface RankedLesson { + lesson: LessonReadModel; + score: number; + lexicalScore: number; + semanticScore: number; + rankingScore: number; +} + +export interface CompactRetrievedLesson { + lessonId: string; + content: string; + claim?: string; + mechanismId?: string; + claimType?: LessonClaimType; + evidenceVerdict: LessonEvidenceVerdict; + lifecycle: "active"; + contradicted: boolean; + confidence: number; + score: number; + applicabilityConditions: string[]; + nonApplicabilityConditions: string[]; + falsificationConditions: string[]; + structuredFacets: Record; + scope: { + ring: LessonScopeRing; + scopeId?: string; + }; + sensitivity: LessonSensitivity; + project?: string; + tags: string[]; + createdAt: string; + updatedAt: string; +} + +let providerEmbeddingCaches = new WeakMap< + EmbeddingProvider, + Map +>(); + +export function resetLessonRetrievalCacheForTests(): void { + providerEmbeddingCaches = new WeakMap(); +} + +export function parseLessonRecallInput(raw: unknown): LessonRecallInputResult { + try { + const record = requireRecord(raw); + const query = requiredString(record.query, "query", MAX_QUERY_LENGTH); + const project = optionalString( + record.project, + "project", + MAX_PROJECT_LENGTH, + ); + const minConfidence = + record.minConfidence === undefined + ? 0.1 + : finiteNumber(record.minConfidence, "minConfidence"); + if (minConfidence < 0 || minConfidence > 1) { + throw new Error("minConfidence must be between 0 and 1"); + } + const limit = + record.limit === undefined + ? 10 + : positiveInteger(record.limit, "limit"); + if (limit > MAX_RECALL_LIMIT) { + throw new Error(`limit must be at most ${MAX_RECALL_LIMIT}`); + } + const retrievalMode = + record.retrievalMode === undefined + ? "lexical" + : enumValue( + record.retrievalMode, + "retrievalMode", + new Set(["lexical", "hybrid"]), + ); + const compact = + record.compact === undefined + ? false + : booleanValue(record.compact, "compact"); + const mechanismId = optionalString( + record.mechanismId, + "mechanismId", + 128, + )?.toLowerCase(); + if ( + mechanismId && + !/^[a-z0-9][a-z0-9._:/-]*$/.test(mechanismId) + ) { + throw new Error( + "mechanismId must use lowercase letters, numbers, dot, underscore, colon, slash, or hyphen", + ); + } + const claimType = + record.claimType === undefined + ? undefined + : enumValue(record.claimType, "claimType", CLAIM_TYPES); + const evidenceVerdicts = stringArray( + record.evidenceVerdicts, + "evidenceVerdicts", + 4, + 32, + ).map((value) => + enumValue(value, "evidenceVerdicts", EVIDENCE_VERDICTS), + ); + const structuredFacets = normalizeLessonStructuredFacets( + record.structuredFacets, + ); + if ( + Object.values(structuredFacets).some((values) => values.length === 0) + ) { + throw new Error( + "structuredFacets filters must contain at least one value per dimension", + ); + } + const tags = stringArray( + record.tags, + "tags", + MAX_FILTER_TAGS, + MAX_FILTER_TAG_LENGTH, + ); + const scopeRing = + record.scopeRing === undefined + ? undefined + : enumValue(record.scopeRing, "scopeRing", SCOPE_RINGS); + const sensitivity = + record.sensitivity === undefined + ? undefined + : enumValue(record.sensitivity, "sensitivity", SENSITIVITIES); + + return { + success: true, + value: { + query, + project, + minConfidence, + limit, + retrievalMode, + compact, + mechanismId, + claimType, + evidenceVerdicts, + structuredFacets, + tags, + scopeRing, + sensitivity, + accessContext: record.accessContext as LessonAccessContext | undefined, + }, + }; + } catch (error) { + return { + success: false, + error: error instanceof Error ? error.message : String(error), + }; + } +} + +export function selectLessonRecallCandidates( + storedLessons: Lesson[], + input: LessonRecallInput, +): LessonReadModel[] { + const accessContext = lessonAccessContextFromPayload(input.accessContext); + const normalized = storedLessons.map((lesson) => toLessonReadModel(lesson)); + if (new Set(normalized.map((lesson) => lesson.id)).size !== normalized.length) { + throw new Error("lesson_state_unavailable"); + } + return normalized + .filter( + (lesson) => + !lesson.deleted && + lesson.lifecycle === "active", + ) + .filter((lesson) => canReadLesson(lesson, accessContext)) + .filter((lesson) => lesson.confidence >= input.minConfidence) + .filter((lesson) => !input.project || lesson.project === input.project) + .filter( + (lesson) => + !input.mechanismId || + lesson.mechanismId === input.mechanismId || + lesson.mechanismAliases.includes(input.mechanismId), + ) + .filter( + (lesson) => !input.claimType || lesson.claimType === input.claimType, + ) + .filter( + (lesson) => + input.evidenceVerdicts.length === 0 || + input.evidenceVerdicts.includes(lesson.evidenceVerdict), + ) + .filter( + (lesson) => + !input.scopeRing || lesson.scope.ring === input.scopeRing, + ) + .filter( + (lesson) => + !input.sensitivity || lesson.sensitivity === input.sensitivity, + ) + .filter((lesson) => matchesTags(lesson.tags, input.tags)) + .filter((lesson) => + matchesStructuredFacets( + lesson.structuredFacets, + input.structuredFacets, + ), + ); +} + +export async function rankLessonRecallCandidates( + candidates: LessonReadModel[], + input: LessonRecallInput, +): Promise<{ + ranked: RankedLesson[]; + diagnostics: LessonRetrievalDiagnostics; +}> { + const lexical = lexicalRanks(candidates, input.query); + const lexicalOnly = ( + fallbackCode?: string, + ): { + ranked: RankedLesson[]; + diagnostics: LessonRetrievalDiagnostics; + } => { + const ranked = lexical + .filter((item) => item.lexicalScore > 0) + .sort(compareRankedLessons) + .slice(0, input.limit); + return { + ranked, + diagnostics: { + requestedMode: input.retrievalMode, + usedMode: "lexical", + returnedCount: ranked.length, + ...(fallbackCode ? { fallbackCode } : {}), + }, + }; + }; + + if (input.retrievalMode === "lexical") return lexicalOnly(); + if (candidates.length === 0) { + return { + ranked: [], + diagnostics: { + requestedMode: "hybrid", + usedMode: "hybrid", + returnedCount: 0, + }, + }; + } + if (candidates.length > MAX_SEMANTIC_CANDIDATES) { + return lexicalOnly("semantic_candidate_limit_exceeded"); + } + + const provider = getEmbeddingProvider(); + if (!provider) { + return lexicalOnly("embedding_provider_unavailable"); + } + const policy = embeddingPolicy(provider, candidates); + if ("failureCode" in policy) { + return lexicalOnly(policy.failureCode); + } + + let semantic: Map; + const budget: SemanticBudget = { + deadlineMs: Date.now() + SEMANTIC_TIMEOUT_MS, + cancelled: false, + }; + try { + semantic = await withTimeout( + semanticScores( + provider, + policy.semanticEligible, + input.query, + budget, + ), + SEMANTIC_TIMEOUT_MS, + () => { + budget.cancelled = true; + }, + ); + } catch { + return lexicalOnly("embedding_failed"); + } + + const lexicalRank = new Map( + lexical + .filter((item) => item.lexicalScore > 0) + .sort( + (left, right) => + right.rankingScore - left.rankingScore || + left.lesson.id.localeCompare(right.lesson.id), + ) + .map((item, index) => [item.lesson.id, index + 1]), + ); + const semanticRank = new Map( + [...semantic.entries()] + .filter(([, score]) => score >= MIN_SEMANTIC_SCORE) + .sort( + ([leftId, leftScore], [rightId, rightScore]) => + rightScore - leftScore || leftId.localeCompare(rightId), + ) + .map(([lessonId], index) => [lessonId, index + 1]), + ); + if (semanticRank.size === 0) { + return lexicalOnly("semantic_no_signal"); + } + const ranked = lexical + .filter( + (item) => + lexicalRank.has(item.lesson.id) || + semanticRank.has(item.lesson.id), + ) + .map((item) => { + const lesson = item.lesson; + const lexicalPosition = lexicalRank.get(lesson.id); + const semanticPosition = semanticRank.get(lesson.id); + const lexicalRrf = lexicalPosition + ? 0.4 / (RRF_K + lexicalPosition) + : 0; + const semanticRrf = semanticPosition + ? 0.6 / (RRF_K + semanticPosition) + : 0; + const normalizedRrf = + (lexicalRrf + semanticRrf) / (1 / (RRF_K + 1)); + const confidenceWeight = 0.65 + 0.35 * lesson.confidence; + return { + lesson, + lexicalScore: item.lexicalScore, + semanticScore: semantic.get(lesson.id) ?? 0, + score: roundScore(normalizedRrf * confidenceWeight), + rankingScore: normalizedRrf * confidenceWeight, + }; + }) + .sort(compareRankedLessons) + .slice(0, input.limit); + + return { + ranked, + diagnostics: { + requestedMode: "hybrid", + usedMode: "hybrid", + returnedCount: ranked.length, + ...(policy.noticeCode ? { noticeCode: policy.noticeCode } : {}), + }, + }; +} + +export function compactRetrievedLesson( + ranked: RankedLesson, +): CompactRetrievedLesson { + const lesson = ranked.lesson; + return enforceCompactSize({ + lessonId: lesson.id, + content: truncateText(lesson.content, COMPACT_CONTENT_CHARS), + claim: lesson.claim + ? truncateText(lesson.claim, COMPACT_CLAIM_CHARS) + : undefined, + mechanismId: lesson.mechanismId, + claimType: lesson.claimType, + evidenceVerdict: lesson.evidenceVerdict, + lifecycle: "active", + contradicted: lesson.computedFlags.contradicted, + confidence: lesson.confidence, + score: ranked.score, + applicabilityConditions: compactStrings( + lesson.applicabilityConditions, + COMPACT_CONDITIONS, + COMPACT_CONDITION_CHARS, + ), + nonApplicabilityConditions: compactStrings( + lesson.nonApplicabilityConditions, + COMPACT_CONDITIONS, + COMPACT_CONDITION_CHARS, + ), + falsificationConditions: compactStrings( + lesson.falsificationConditions, + COMPACT_CONDITIONS, + COMPACT_CONDITION_CHARS, + ), + structuredFacets: compactFacets(lesson.structuredFacets), + scope: { + ring: lesson.scope.ring, + scopeId: lesson.scope.scopeId, + }, + sensitivity: lesson.sensitivity, + project: lesson.project, + tags: compactStrings(lesson.tags, COMPACT_TAGS, COMPACT_TAG_CHARS), + createdAt: lesson.createdAt, + updatedAt: lesson.updatedAt, + }); +} + +function lexicalRanks( + candidates: LessonReadModel[], + query: string, +): RankedLesson[] { + const queryTerms = query + .toLowerCase() + .split(/\s+/) + .filter((term) => term.length > 1); + const nowMs = Date.now(); + return candidates.map((lesson) => { + const text = legacyLexicalText(lesson).toLowerCase(); + const matched = queryTerms.filter((term) => text.includes(term)).length; + const relevance = + queryTerms.length === 0 ? 0 : matched / queryTerms.length; + const baseline = lesson.lastReinforcedAt ?? lesson.createdAt; + const baselineMs = Date.parse(baseline); + const daysSinceReinforced = Number.isFinite(baselineMs) + ? (nowMs - baselineMs) / (1_000 * 60 * 60 * 24) + : 0; + const recencyBoost = 1 / (1 + daysSinceReinforced * 0.01); + const rankingScore = lesson.confidence * relevance * recencyBoost; + return { + lesson, + lexicalScore: relevance, + semanticScore: 0, + score: roundLegacyScore(rankingScore), + rankingScore, + }; + }); +} + +async function semanticScores( + provider: EmbeddingProvider, + candidates: LessonReadModel[], + query: string, + budget: SemanticBudget, +): Promise> { + assertSemanticBudget(budget); + const queryEmbedding = await provider.embed(clipEmbedInput(query)); + assertSemanticBudget(budget); + ensureEmbeddingDimensions(queryEmbedding, provider); + + const cache = embeddingCache(provider); + const publicCandidates = candidates.filter( + (lesson) => lesson.sensitivity === "public", + ); + if (publicCandidates.length > 0) { + await withKeyedLock( + `lesson-retrieval-public-cache:${provider.name}:${provider.dimensions}`, + async () => { + assertSemanticBudget(budget); + const missing = publicCandidates.filter( + (lesson) => !cache.has(embeddingCacheKey(lesson)), + ); + for ( + let offset = 0; + offset < missing.length; + offset += EMBEDDING_BATCH_SIZE + ) { + assertSemanticBudget(budget); + const batch = missing.slice(offset, offset + EMBEDDING_BATCH_SIZE); + const embeddings = await embedLessonBatch( + provider, + batch, + budget, + ); + for (let index = 0; index < batch.length; index++) { + setCachedEmbedding( + cache, + embeddingCacheKey(batch[index]), + embeddings[index], + ); + } + } + }, + ); + } + + const protectedEmbeddings = new Map(); + const protectedCandidates = candidates.filter( + (lesson) => lesson.sensitivity !== "public", + ); + for ( + let offset = 0; + offset < protectedCandidates.length; + offset += EMBEDDING_BATCH_SIZE + ) { + assertSemanticBudget(budget); + const batch = protectedCandidates.slice( + offset, + offset + EMBEDDING_BATCH_SIZE, + ); + const embeddings = await embedLessonBatch(provider, batch, budget); + for (let index = 0; index < batch.length; index++) { + protectedEmbeddings.set( + batch[index].id, + new Float32Array(embeddings[index]), + ); + } + } + + assertSemanticBudget(budget); + return new Map( + candidates.map((lesson) => { + const embedding = + lesson.sensitivity === "public" + ? cache.get(embeddingCacheKey(lesson)) + : protectedEmbeddings.get(lesson.id); + if (!embedding) throw new Error("lesson embedding cache miss"); + return [lesson.id, cosineSimilarity(queryEmbedding, embedding)]; + }), + ); +} + +async function embedLessonBatch( + provider: EmbeddingProvider, + batch: LessonReadModel[], + budget: SemanticBudget, +): Promise { + const embeddings = await provider.embedBatch( + batch.map((lesson) => clipEmbedInput(lessonRetrievalText(lesson))), + ); + assertSemanticBudget(budget); + if (embeddings.length !== batch.length) { + throw new Error("embedding provider returned an invalid batch length"); + } + for (const embedding of embeddings) { + ensureEmbeddingDimensions(embedding, provider); + } + return embeddings; +} + +function legacyLexicalText(lesson: LessonReadModel): string { + const facets = Object.entries(lesson.structuredFacets) + .flatMap(([dimension, values]) => [dimension, ...values]) + .join(" "); + return [ + lesson.content, + lesson.context, + lesson.claim, + lesson.mechanismId, + ...lesson.mechanismAliases, + ...lesson.applicabilityConditions, + ...lesson.nonApplicabilityConditions, + ...lesson.falsificationConditions, + facets, + ...lesson.tags, + ] + .filter(Boolean) + .join(" "); +} + +function lessonRetrievalText(lesson: LessonReadModel): string { + const facets = Object.entries(lesson.structuredFacets) + .flatMap(([dimension, values]) => [dimension, ...values]) + .join(" "); + return [ + lesson.claim, + lesson.content, + lesson.mechanismId, + lesson.mechanismVersion, + ...lesson.mechanismAliases, + lesson.claimType, + lesson.evidenceVerdict, + ...lesson.applicabilityConditions, + ...lesson.nonApplicabilityConditions, + ...lesson.falsificationConditions, + facets, + ...lesson.tags, + ] + .filter(Boolean) + .join(" "); +} + +function embeddingCache( + provider: EmbeddingProvider, +): Map { + let cache = providerEmbeddingCaches.get(provider); + if (!cache) { + cache = new Map(); + providerEmbeddingCaches.set(provider, cache); + } + return cache; +} + +function setCachedEmbedding( + cache: Map, + key: string, + embedding: Float32Array, +): void { + cache.delete(key); + cache.set(key, new Float32Array(embedding)); + while (cache.size > MAX_CACHED_LESSON_EMBEDDINGS) { + const oldest = cache.keys().next().value; + if (typeof oldest !== "string") break; + cache.delete(oldest); + } +} + +function embeddingCacheKey(lesson: LessonReadModel): string { + return `${lesson.id}\u0000${fingerprintId( + "lrt", + lessonRetrievalText(lesson), + )}`; +} + +function ensureEmbeddingDimensions( + embedding: Float32Array, + provider: EmbeddingProvider, +): void { + if ( + embedding.length !== provider.dimensions || + [...embedding].some((value) => !Number.isFinite(value)) + ) { + throw new Error("embedding provider returned invalid dimensions"); + } +} + +function cosineSimilarity( + left: Float32Array, + right: Float32Array, +): number { + if (left.length !== right.length) return 0; + let dot = 0; + let leftNorm = 0; + let rightNorm = 0; + for (let index = 0; index < left.length; index++) { + dot += left[index] * right[index]; + leftNorm += left[index] * left[index]; + rightNorm += right[index] * right[index]; + } + const denominator = Math.sqrt(leftNorm) * Math.sqrt(rightNorm); + return denominator === 0 ? 0 : dot / denominator; +} + +function matchesTags(lessonTags: string[], requestedTags: string[]): boolean { + if (requestedTags.length === 0) return true; + const available = new Set(lessonTags.map(normalizeText)); + return requestedTags.every((tag) => available.has(normalizeText(tag))); +} + +function matchesStructuredFacets( + lessonFacets: Record, + requestedFacets: Record, +): boolean { + return Object.entries(requestedFacets).every(([dimension, values]) => { + const available = new Set( + (lessonFacets[dimension] ?? []).map(normalizeText), + ); + return ( + values.length > 0 && + values.some((value) => available.has(normalizeText(value))) + ); + }); +} + +function compareRankedLessons( + left: RankedLesson, + right: RankedLesson, +): number { + return ( + right.rankingScore - left.rankingScore || + right.semanticScore - left.semanticScore || + right.lexicalScore - left.lexicalScore || + left.lesson.id.localeCompare(right.lesson.id) + ); +} + +function normalizeText(value: string): string { + return value.trim().replace(/\s+/g, " ").toLowerCase(); +} + +function roundLegacyScore(value: number): number { + return Math.round(value * 1_000) / 1_000; +} + +function roundScore(value: number): number { + return Math.round(value * 1_000_000) / 1_000_000; +} + +function compactStrings( + values: string[], + maxItems: number, + maxChars: number, +): string[] { + return values + .slice(0, maxItems) + .map((value) => truncateText(value, maxChars)); +} + +function compactFacets( + facets: Record, +): Record { + return Object.fromEntries( + Object.entries(facets) + .sort(([left], [right]) => left.localeCompare(right)) + .slice(0, COMPACT_FACET_DIMENSIONS) + .map(([dimension, values]) => [ + dimension, + compactStrings( + values, + COMPACT_FACET_VALUES, + COMPACT_FACET_VALUE_CHARS, + ), + ]), + ); +} + +function truncateText(value: string, maxChars: number): string { + return value.length > maxChars + ? `${value.slice(0, Math.max(0, maxChars - 1))}…` + : value; +} + +function enforceCompactSize( + compact: CompactRetrievedLesson, +): CompactRetrievedLesson { + const fits = () => + Buffer.byteLength(JSON.stringify(compact), "utf8") <= + COMPACT_MAX_UTF8_BYTES; + if (fits()) return compact; + + while (compact.tags.length > 0 && !fits()) compact.tags.pop(); + + const facetDimensions = Object.keys(compact.structuredFacets).sort().reverse(); + for (const dimension of facetDimensions) { + const values = compact.structuredFacets[dimension]; + while (values.length > 0 && !fits()) values.pop(); + if (values.length === 0) delete compact.structuredFacets[dimension]; + if (fits()) return compact; + } + + for (const conditions of [ + compact.nonApplicabilityConditions, + compact.falsificationConditions, + compact.applicabilityConditions, + ]) { + while (conditions.length > 0 && !fits()) conditions.pop(); + if (fits()) return compact; + } + + while (compact.content.length > 80 && !fits()) { + compact.content = truncateText( + compact.content, + Math.max(80, compact.content.length - 32), + ); + } + while ((compact.claim?.length ?? 0) > 80 && !fits()) { + compact.claim = truncateText( + compact.claim!, + Math.max(80, compact.claim!.length - 32), + ); + } + if (!fits()) delete compact.project; + if (!fits()) delete compact.scope.scopeId; + if (!fits()) delete compact.mechanismId; + if (!fits()) compact.content = ""; + if (!fits()) delete compact.claim; + return compact; +} + +type SemanticBudget = { + deadlineMs: number; + cancelled: boolean; +}; + +function assertSemanticBudget(budget: SemanticBudget): void { + if (budget.cancelled || Date.now() >= budget.deadlineMs) { + throw new Error("lesson semantic retrieval timed out"); + } +} + +function embeddingPolicy( + provider: EmbeddingProvider, + candidates: LessonReadModel[], +): + | { + semanticEligible: LessonReadModel[]; + noticeCode?: string; + } + | { failureCode: string } { + if (provider.name === "local") { + return { semanticEligible: candidates }; + } + if (getEnvVar("AGENTMEMORY_LESSON_REMOTE_EMBEDDINGS") !== "true") { + return { failureCode: "remote_embedding_disabled" }; + } + const configuredCeiling = + getEnvVar("AGENTMEMORY_LESSON_EMBED_MAX_SENSITIVITY") ?? "public"; + if (!SENSITIVITIES.has(configuredCeiling as LessonSensitivity)) { + return { failureCode: "embedding_policy_invalid" }; + } + const rank: Record = { + public: 0, + internal: 1, + confidential: 2, + restricted: 3, + }; + const ceiling = rank[configuredCeiling as LessonSensitivity]; + const semanticEligible = candidates.filter( + (lesson) => rank[lesson.sensitivity] <= ceiling, + ); + if (semanticEligible.length === 0) { + return { failureCode: "embedding_sensitivity_blocked" }; + } + return { + semanticEligible, + ...(semanticEligible.length < candidates.length + ? { noticeCode: "embedding_sensitivity_filtered" } + : {}), + }; +} + +async function withTimeout( + promise: Promise, + timeoutMs: number, + onTimeout: () => void, +): Promise { + let timeout: ReturnType | undefined; + try { + return await Promise.race([ + promise, + new Promise((_, reject) => { + timeout = setTimeout( + () => { + onTimeout(); + reject(new Error("lesson semantic retrieval timed out")); + }, + timeoutMs, + ); + }), + ]); + } finally { + if (timeout) clearTimeout(timeout); + } +} + +function requireRecord(value: unknown): Record { + if (!value || typeof value !== "object" || Array.isArray(value)) { + throw new Error("lesson recall input must be an object"); + } + return value as Record; +} + +function requiredString( + value: unknown, + field: string, + maxLength: number, +): string { + const parsed = optionalString(value, field, maxLength); + if (!parsed) throw new Error(`${field} is required`); + return parsed; +} + +function optionalString( + value: unknown, + field: string, + maxLength: number, +): string | undefined { + if (value === undefined || value === null) return undefined; + if (typeof value !== "string") { + throw new Error(`${field} must be a string`); + } + const parsed = value.trim(); + if (!parsed) return undefined; + if (parsed.length > maxLength) { + throw new Error(`${field} must be at most ${maxLength} characters`); + } + return parsed; +} + +function finiteNumber(value: unknown, field: string): number { + if (typeof value !== "number" || !Number.isFinite(value)) { + throw new Error(`${field} must be a finite number`); + } + return value; +} + +function positiveInteger(value: unknown, field: string): number { + if (!Number.isInteger(value) || (value as number) < 1) { + throw new Error(`${field} must be a positive integer`); + } + return value as number; +} + +function booleanValue(value: unknown, field: string): boolean { + if (typeof value !== "boolean") { + throw new Error(`${field} must be a boolean`); + } + return value; +} + +function stringArray( + value: unknown, + field: string, + maxItems: number, + maxLength: number, +): string[] { + if (value === undefined || value === null) return []; + if (!Array.isArray(value)) { + throw new Error(`${field} must be an array of strings`); + } + if (value.length > maxItems) { + throw new Error(`${field} must contain at most ${maxItems} items`); + } + const parsed = value.map((item) => { + if (typeof item !== "string") { + throw new Error(`${field} must contain only strings`); + } + const text = item.trim(); + if (!text) throw new Error(`${field} must not contain empty strings`); + if (text.length > maxLength) { + throw new Error(`${field} items must be at most ${maxLength} characters`); + } + return text; + }); + return [...new Set(parsed)]; +} + +function enumValue( + value: unknown, + field: string, + allowed: Set, +): T { + if (typeof value !== "string" || !allowed.has(value as T)) { + throw new Error( + `${field} must be one of ${[...allowed].join(", ")}`, + ); + } + return value as T; +} diff --git a/src/functions/lessons.ts b/src/functions/lessons.ts index 60bdef80de..944ba420fe 100644 --- a/src/functions/lessons.ts +++ b/src/functions/lessons.ts @@ -1,6 +1,6 @@ import type { ISdk } from "iii-sdk"; import type { StateKV } from "../state/kv.js"; -import { KV } from "../state/schema.js"; +import { fingerprintId, KV } from "../state/schema.js"; import type { Lesson } from "../types.js"; import { recordAudit } from "./audit.js"; import { @@ -24,6 +24,12 @@ import { sameLessonScope, toLessonReadModel, } from "./lesson-model.js"; +import { + compactRetrievedLesson, + parseLessonRecallInput, + rankLessonRecallCandidates, + selectLessonRecallCandidates, +} from "./lesson-retrieval.js"; const MAX_LESSON_LIST_LIMIT = 500; const MAX_CORRECTION_REASON_LENGTH = 1000; @@ -508,93 +514,56 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { }, ); - sdk.registerFunction("mem::lesson-recall", - async (data: { - query: string; - project?: string; - minConfidence?: number; - limit?: number; - accessContext?: LessonAccessContext; - }) => { - if (!data.query?.trim()) { - return { success: false, error: "query is required" }; - } - - const query = data.query.toLowerCase(); - const minConfidence = data.minConfidence ?? 0.1; - const limit = data.limit ?? 10; - const accessContext = lessonAccessContextFromPayload( - data.accessContext, + sdk.registerFunction("mem::lesson-recall", async (data: unknown) => { + const parsed = parseLessonRecallInput(data); + if (!parsed.success) { + return correctionFailure("invalid_request", parsed.error); + } + const input = parsed.value; + const accessContext = lessonAccessContextFromPayload( + input.accessContext, + ); + const storedLessons = await kv.list(KV.lessons); + let candidates; + try { + candidates = selectLessonRecallCandidates(storedLessons, input); + } catch { + return correctionFailure( + "lesson_state_unavailable", + "lesson retrieval state is unavailable", ); + } + const { ranked, diagnostics } = await rankLessonRecallCandidates( + candidates, + input, + ); - const storedLessons = await kv.list(KV.lessons); - let lessons = storedLessons - .filter(isLessonRecallable) - .filter((lesson) => canReadLesson(lesson, accessContext)) - .map((lesson) => toLessonReadModel(lesson)); - - lessons = lessons.filter((l) => l.confidence >= minConfidence); - - if (data.project) { - lessons = lessons.filter((l) => l.project === data.project); - } - - const scored = lessons - .map((l) => { - const facetText = Object.entries(l.structuredFacets) - .flatMap(([dimension, values]) => [dimension, ...values]) - .join(" "); - const text = [ - l.content, - l.context, - l.claim, - l.mechanismId, - ...l.mechanismAliases, - ...l.applicabilityConditions, - ...l.nonApplicabilityConditions, - ...l.falsificationConditions, - facetText, - ...l.tags, - ] - .filter(Boolean) - .join(" ") - .toLowerCase(); - const terms = query.split(/\s+/).filter((t) => t.length > 1); - const matchCount = terms.filter((t) => text.includes(t)).length; - if (matchCount === 0) return null; - - const relevance = matchCount / terms.length; - const daysSinceReinforced = l.lastReinforcedAt - ? (Date.now() - new Date(l.lastReinforcedAt).getTime()) / - (1000 * 60 * 60 * 24) - : (Date.now() - new Date(l.createdAt).getTime()) / - (1000 * 60 * 60 * 24); - const recencyBoost = 1 / (1 + daysSinceReinforced * 0.01); - const score = l.confidence * relevance * recencyBoost; - - return { lesson: l, score }; - }) - .filter(Boolean) as Array<{ lesson: Lesson; score: number }>; - - scored.sort((a, b) => b.score - a.score); - - try { - await recordAudit(kv, "lesson_recall", "mem::lesson-recall", [], { - query: data.query, + try { + await recordAudit( + kv, + "lesson_recall", + "mem::lesson-recall", + ranked.map(({ lesson }) => lesson.id), + { + queryFingerprint: fingerprintId("qry", input.query), actor: accessContext.principalId, - resultCount: scored.length, - }); - } catch {} + requestedLimit: input.limit, + resultCount: ranked.length, + retrievalMode: diagnostics.usedMode, + fallbackCode: diagnostics.fallbackCode, + noticeCode: diagnostics.noticeCode, + }, + ); + } catch {} - return { - success: true, - lessons: scored.slice(0, limit).map((s) => ({ - ...s.lesson, - score: Math.round(s.score * 1000) / 1000, - })), - }; - }, - ); + return { + success: true, + retrieval: diagnostics, + lessons: input.compact + ? ranked.map(compactRetrievedLesson) + : ranked.map(({ lesson, score }) => ({ ...lesson, score })), + }; + }); sdk.registerFunction("mem::lesson-list", async (data: { diff --git a/src/functions/smart-search.ts b/src/functions/smart-search.ts index 493cdded4f..009212a2fa 100644 --- a/src/functions/smart-search.ts +++ b/src/functions/smart-search.ts @@ -4,7 +4,6 @@ import type { CompactSearchResult, CompressedObservation, HybridSearchResult, - Lesson, } from "../types.js"; import { KV } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; @@ -18,6 +17,7 @@ import { import { logger } from "../logger.js"; import { getCounters } from "../telemetry/setup.js"; import type { LessonAccessContext } from "./lesson-access.js"; +import type { CompactRetrievedLesson } from "./lesson-retrieval.js"; // #771: smart-search followup-rate diagnostic. Stored per session as // the most recent search payload, used to detect whether the next @@ -69,10 +69,6 @@ export function resetFollowupStatsForTests(): void { followupStats.agentInitiatedSearches = 0; } -// Compact mode trims each lesson's content for at-a-glance display. The -// full content is fetched via memory_lesson_recall when the caller needs it. -const LESSON_CONTENT_PREVIEW_CHARS = 240; - export function registerSmartSearchFunction( sdk: ISdk, kv: StateKV, @@ -305,18 +301,22 @@ async function recallLessons( try { const result = (await sdk.trigger({ function_id: "mem::lesson-recall", - payload: { query, limit, project, accessContext }, - })) as { success?: boolean; lessons?: Array }; + payload: { + query, + limit, + project, + retrievalMode: "hybrid", + compact: true, + accessContext, + }, + })) as { + success?: boolean; + lessons?: CompactRetrievedLesson[]; + }; if (!result?.success || !Array.isArray(result.lessons)) return []; return result.lessons.map((lesson) => { - const evidenceVerdict = lesson.evidenceVerdict ?? "unverified"; - const contradicted = - Boolean( - (lesson as Lesson & { - computedFlags?: { contradicted?: boolean }; - }).computedFlags?.contradicted, - ) || - (lesson.contradictedByLessonIds?.length ?? 0) > 0; + const evidenceVerdict = lesson.evidenceVerdict; + const contradicted = lesson.contradicted; const evidenceLabel: CompactLessonResult["evidenceLabel"] = contradicted ? "contradicted evidence" : evidenceVerdict === "refuted" @@ -327,17 +327,14 @@ async function recallLessons( ? "mixed evidence" : "unverified evidence"; return { - lessonId: lesson.id, - content: - lesson.content.length > LESSON_CONTENT_PREVIEW_CHARS - ? lesson.content.slice(0, LESSON_CONTENT_PREVIEW_CHARS) + "…" - : lesson.content, + lessonId: lesson.lessonId, + content: lesson.content, claim: lesson.claim, evidenceVerdict, evidenceLabel, contradicted, confidence: lesson.confidence, - score: lesson.score ?? lesson.confidence, + score: lesson.score, createdAt: lesson.createdAt, project: lesson.project, tags: lesson.tags ?? [], diff --git a/src/mcp/server.ts b/src/mcp/server.ts index 874545fc5c..4551d69666 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -13,6 +13,7 @@ import { timingSafeCompare } from "../auth.js"; import { getAgentId, isAgentScopeIsolated } from "../config.js"; import { selectSessionPage } from "../functions/session-list.js"; import { parseLessonSaveInput } from "../functions/lesson-model.js"; +import { parseLessonRecallInput } from "../functions/lesson-retrieval.js"; import { bindResolvedLessonWriteIdentity, resolveLessonBoundaryAccess, @@ -1402,16 +1403,32 @@ export function registerMcpEndpoints( case "memory_lesson_recall": { const access = resolveLessonRequestAccess(req); if (!access.success) return access.response; - if (typeof args.query !== "string" || !args.query.trim()) { - return { status_code: 400, body: { error: "query is required" } }; - } - const lessonRecallResult = await sdk.trigger({ function_id: "mem::lesson-recall", payload: { + const parsed = parseLessonRecallInput({ query: args.query, project: args.project, minConfidence: args.minConfidence, limit: args.limit, + retrievalMode: args.retrievalMode, + compact: args.compact, + mechanismId: args.mechanismId, + claimType: args.claimType, + evidenceVerdicts: args.evidenceVerdicts, + structuredFacets: args.structuredFacets, + tags: args.tags, + scopeRing: args.scopeRing, + sensitivity: args.sensitivity, accessContext: access.context, - } }); + }); + if (!parsed.success) { + return { + status_code: 400, + body: { error: parsed.error, code: "invalid_request" }, + }; + } + const lessonRecallResult = await sdk.trigger({ + function_id: "mem::lesson-recall", + payload: parsed.value, + }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(lessonRecallResult, null, 2) }] } }; } diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts index 9f666ac87d..e6b91850b7 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -6,8 +6,14 @@ export type McpSchemaProperty = { properties?: Record; required?: string[]; additionalProperties?: boolean | McpSchemaProperty; + minItems?: number; maxItems?: number; + minLength?: number; + maxLength?: number; + maxProperties?: number; + maximum?: number; minimum?: number; + pattern?: string; }; export type McpToolDef = { @@ -1093,17 +1099,108 @@ export const V070_TOOLS: McpToolDef[] = [ { name: "memory_lesson_recall", description: - "Search lessons by query. Returns lessons sorted by confidence and recency. Use to check what the agent has learned before making decisions.", + "Search causal lessons. Legacy-compatible lexical ranking is the default; retrievalMode=hybrid adds semantic similarity after authorization and exact structured prefilters, with deterministic lexical fallback. Use compact=true to inject bounded causal lessons instead of full evidence rows.", inputSchema: { type: "object", properties: { - query: { type: "string", description: "Search query" }, - project: { type: "string", description: "Filter by project" }, + query: { + type: "string", + minLength: 1, + maxLength: 2048, + pattern: "\\S", + description: "Search query", + }, + project: { + type: "string", + maxLength: 512, + description: "Filter by project", + }, minConfidence: { type: "number", + minimum: 0, + maximum: 1, description: "Minimum confidence threshold (default 0.1)", }, - limit: { type: "number", description: "Max results (default 10)" }, + limit: { + type: "integer", + minimum: 1, + maximum: 50, + description: "Max results (default 10, maximum 50)", + }, + retrievalMode: { + type: "string", + enum: ["lexical", "hybrid"], + description: + "lexical preserves the prior confidence/relevance/recency scorer; hybrid combines lexical and embedding similarity and falls back to lexical when embeddings are unavailable", + }, + compact: { + type: "boolean", + description: + "Return bounded causal lesson projections without raw evidence references or source rows", + }, + mechanismId: { + type: "string", + maxLength: 128, + pattern: "^[A-Za-z0-9][A-Za-z0-9._:/-]*$", + description: + "Exact mechanism ID or alias filter applied before ranking", + }, + claimType: { + type: "string", + enum: [ + "causal", + "predictive", + "procedural", + "constraint", + "descriptive", + ], + }, + evidenceVerdicts: { + type: "array", + description: + "Allowed evidence verdicts; values are ORed and the filter is applied before ranking", + items: { + type: "string", + enum: ["supported", "refuted", "mixed", "unverified"], + }, + maxItems: 4, + }, + structuredFacets: { + type: "object", + description: + "Exact causal facet filters. Dimensions are ANDed; values within one dimension are ORed.", + maxProperties: 32, + additionalProperties: { + type: "array", + items: { + type: "string", + minLength: 1, + maxLength: 256, + pattern: "\\S", + }, + minItems: 1, + maxItems: 16, + }, + }, + tags: { + type: "array", + description: "Require every listed tag before ranking", + items: { + type: "string", + minLength: 1, + maxLength: 256, + pattern: "\\S", + }, + maxItems: 32, + }, + scopeRing: { + type: "string", + enum: ["worktree", "repo", "initiative", "domain", "global"], + }, + sensitivity: { + type: "string", + enum: ["public", "internal", "confidential", "restricted"], + }, }, required: ["query"], }, diff --git a/src/triggers/api.ts b/src/triggers/api.ts index e63cd2c6f0..9a62207bf9 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -23,6 +23,7 @@ import { logger } from "../logger.js"; import { selectSessionPage } from "../functions/session-list.js"; import { triggerDetached } from "../utils/trigger-detached.js"; import { parseLessonSaveInput } from "../functions/lesson-model.js"; +import { parseLessonRecallInput } from "../functions/lesson-retrieval.js"; import { bindResolvedLessonWriteIdentity, resolveLessonBoundaryAccess, @@ -3800,43 +3801,31 @@ export function registerApiTriggers( const access = resolveLessonRequestAccess(req); if (!access.success) return access.response; const body = (req.body ?? {}) as Record; - const query = asNonEmptyString(body.query); - if (!query) { - return { status_code: 400, body: { error: "query is required" } }; - } - if (body.project !== undefined && typeof body.project !== "string") { - return { status_code: 400, body: { error: "project must be a string" } }; - } - if ( - body.minConfidence !== undefined && - (typeof body.minConfidence !== "number" || - !Number.isFinite(body.minConfidence)) - ) { - return { - status_code: 400, - body: { error: "minConfidence must be a finite number" }, - }; - } - if ( - body.limit !== undefined && - (typeof body.limit !== "number" || - !Number.isInteger(body.limit) || - body.limit < 1) - ) { + const parsed = parseLessonRecallInput({ + query: body.query, + project: body.project, + minConfidence: body.minConfidence, + limit: body.limit, + retrievalMode: body.retrievalMode, + compact: body.compact, + mechanismId: body.mechanismId, + claimType: body.claimType, + evidenceVerdicts: body.evidenceVerdicts, + structuredFacets: body.structuredFacets, + tags: body.tags, + scopeRing: body.scopeRing, + sensitivity: body.sensitivity, + accessContext: access.context, + }); + if (!parsed.success) { return { status_code: 400, - body: { error: "limit must be a positive integer" }, + body: { error: parsed.error, code: "invalid_request" }, }; } const result = await sdk.trigger({ function_id: "mem::lesson-recall", - payload: { - query, - project: asNonEmptyString(body.project), - minConfidence: body.minConfidence, - limit: body.limit, - accessContext: access.context, - }, + payload: parsed.value, }); return { status_code: 200, body: result }; }); diff --git a/test/causal-lessons-api.test.ts b/test/causal-lessons-api.test.ts index f90079ce83..0c0db0e00f 100644 --- a/test/causal-lessons-api.test.ts +++ b/test/causal-lessons-api.test.ts @@ -5,10 +5,18 @@ vi.mock("../src/logger.js", () => ({ })); import { registerLessonsFunctions } from "../src/functions/lessons.js"; +import { + resetLessonRetrievalCacheForTests, +} from "../src/functions/lesson-retrieval.js"; +import { setEmbeddingProvider } from "../src/functions/search.js"; import { registerMcpEndpoints } from "../src/mcp/server.js"; import { getAllTools } from "../src/mcp/tools-registry.js"; import { registerApiTriggers } from "../src/triggers/api.js"; -import type { Lesson } from "../src/types.js"; +import type { + AuditEntry, + EmbeddingProvider, + Lesson, +} from "../src/types.js"; import { mockKV, mockSdk } from "./helpers/mocks.js"; function evidence(commit = "a".repeat(40)) { @@ -34,6 +42,8 @@ describe("causal lesson REST and MCP boundaries", () => { let kv: ReturnType; beforeEach(() => { + setEmbeddingProvider(null); + resetLessonRetrievalCacheForTests(); sdk = mockSdk(); kv = mockKV(); registerLessonsFunctions(sdk as never, kv as never); @@ -200,6 +210,12 @@ describe("causal lesson REST and MCP boundaries", () => { limit: 5, lifecycle: "retracted", deleted: true, + includeHidden: true, + candidateIds: ["lsn_untrusted"], + accessContext: { + mode: "enforce", + principalId: "untrusted", + }, }, })) as { status_code: number; @@ -211,6 +227,163 @@ describe("causal lesson REST and MCP boundaries", () => { expect(response.body.lessons[0].lifecycle).toBe("active"); }); + it("accepts bounded hybrid filters at REST and MCP boundaries and hashes the audit query", async () => { + const embedder: EmbeddingProvider = { + name: "local", + dimensions: 2, + embed: vi.fn(async () => new Float32Array([1, 0])), + embedBatch: vi.fn(async (texts: string[]) => + texts.map(() => new Float32Array([1, 0])), + ), + }; + setEmbeddingProvider(embedder); + await sdk.trigger("mem::lesson-save", { + content: "Queue pressure reversal survives cost controls.", + project: "agentmemory", + tags: ["microstructure", "costed"], + mechanismId: "queue-pressure/reversal", + claim: "Queue pressure predicts a short-horizon reversal.", + claimType: "predictive", + evidenceVerdict: "unverified", + structuredFacets: { + asset: ["HYPE"], + venue: ["Bybit"], + }, + scope: { + ring: "repo", + scopeId: "repo:https://github.com/wrightpt/agentmemory", + }, + sensitivity: "public", + }); + const rawQuery = "private candidate analogy"; + const filters = { + query: rawQuery, + project: "agentmemory", + retrievalMode: "hybrid", + compact: true, + mechanismId: "queue-pressure/reversal", + claimType: "predictive", + evidenceVerdicts: ["unverified"], + structuredFacets: { + asset: ["hype"], + venue: ["BYBIT"], + }, + tags: ["microstructure", "costed"], + scopeRing: "repo", + sensitivity: "public", + includeHidden: true, + candidateIds: ["lsn_untrusted"], + }; + + const rest = (await sdk.trigger("api::lesson-search", { + headers: {}, + body: filters, + })) as { + status_code: number; + body: { + lessons: Array<{ lessonId: string; evidenceRefs?: unknown }>; + retrieval: { usedMode: string }; + }; + }; + const mcp = (await sdk.trigger("mcp::tools::call", { + headers: {}, + body: { + name: "memory_lesson_recall", + arguments: filters, + }, + })) as { + status_code: number; + body: { content: Array<{ text: string }> }; + }; + const mcpResult = JSON.parse(mcp.body.content[0].text) as { + lessons: Array<{ lessonId: string }>; + retrieval: { usedMode: string }; + }; + const audits = await kv.list("mem:audit"); + const recallAudits = audits.filter( + (entry) => entry.operation === "lesson_recall", + ); + + expect(rest).toMatchObject({ + status_code: 200, + body: { + retrieval: { usedMode: "hybrid" }, + lessons: [expect.objectContaining({ lessonId: expect.any(String) })], + }, + }); + expect(rest.body.lessons[0]).toHaveProperty("lessonId"); + expect(rest.body.lessons[0]).not.toHaveProperty("evidenceRefs"); + expect(mcp.status_code).toBe(200); + expect(mcpResult.retrieval.usedMode).toBe("hybrid"); + expect(mcpResult.lessons).toHaveLength(1); + expect(recallAudits).toHaveLength(2); + for (const audit of recallAudits) { + expect(audit.targetIds).toHaveLength(1); + expect(audit.details).toHaveProperty("queryFingerprint"); + expect(JSON.stringify(audit.details)).not.toContain(rawQuery); + expect(audit.details).not.toHaveProperty("query"); + } + const tool = getAllTools().find( + (candidate) => candidate.name === "memory_lesson_recall", + ); + expect(tool?.inputSchema.properties).toHaveProperty("retrievalMode"); + expect(tool?.inputSchema.properties).toHaveProperty("structuredFacets"); + expect(tool?.inputSchema.properties).toHaveProperty("compact"); + }); + + it("returns bounded validation errors for invalid recall input at both boundaries", async () => { + const rest = (await sdk.trigger("api::lesson-search", { + headers: {}, + body: { query: "valid", limit: 51 }, + })) as { status_code: number; body: { code: string } }; + const mcp = (await sdk.trigger("mcp::tools::call", { + headers: {}, + body: { + name: "memory_lesson_recall", + arguments: { query: "x".repeat(2_049) }, + }, + })) as { status_code: number; body: { code: string } }; + + expect(rest).toMatchObject({ + status_code: 400, + body: { code: "invalid_request" }, + }); + expect(mcp).toMatchObject({ + status_code: 400, + body: { code: "invalid_request" }, + }); + }); + + it("fails closed before embedding when authoritative lesson state is malformed", async () => { + const embedder: EmbeddingProvider = { + name: "local", + dimensions: 2, + embed: vi.fn(async () => new Float32Array([1, 0])), + embedBatch: vi.fn(async (texts: string[]) => + texts.map(() => new Float32Array([1, 0])), + ), + }; + setEmbeddingProvider(embedder); + await kv.set("mem:lessons", "lsn_invalid", { + id: "lsn_invalid", + schemaVersion: 1, + content: 42, + } as unknown as Lesson); + + const result = (await sdk.trigger("mem::lesson-recall", { + query: "invalid lesson", + retrievalMode: "hybrid", + })) as { success: boolean; code: string; error: string }; + + expect(result).toEqual({ + success: false, + code: "lesson_state_unavailable", + error: "lesson retrieval state is unavailable", + }); + expect(embedder.embed).not.toHaveBeenCalled(); + expect(embedder.embedBatch).not.toHaveBeenCalled(); + }); + it("rejects dangling, self, cross-scope, and cross-project contradiction relations", async () => { const target = (await sdk.trigger("mem::lesson-save", { content: "Contradiction target", diff --git a/test/lesson-authorization.test.ts b/test/lesson-authorization.test.ts index 79b615d375..c093a5dede 100644 --- a/test/lesson-authorization.test.ts +++ b/test/lesson-authorization.test.ts @@ -12,13 +12,18 @@ import { registerExportImportFunction } from "../src/functions/export-import.js" import { registerContextFunction } from "../src/functions/context.js"; import { registerCrystallizeFunction } from "../src/functions/crystallize.js"; import { systemLessonAccessContext } from "../src/functions/lesson-access.js"; +import { + resetLessonRetrievalCacheForTests, +} from "../src/functions/lesson-retrieval.js"; import { registerLessonsFunctions } from "../src/functions/lessons.js"; +import { setEmbeddingProvider } from "../src/functions/search.js"; import { registerReflectFunctions } from "../src/functions/reflect.js"; import { registerSmartSearchFunction } from "../src/functions/smart-search.js"; import { registerMcpEndpoints } from "../src/mcp/server.js"; import { registerApiTriggers } from "../src/triggers/api.js"; import type { Crystal, + EmbeddingProvider, ExportData, Insight, Lesson, @@ -66,6 +71,8 @@ describe("lesson authorization boundaries", () => { let reflectionPrompts: string[]; beforeEach(() => { + setEmbeddingProvider(null); + resetLessonRetrievalCacheForTests(); policyDir = mkdtempSync(join(tmpdir(), "agentmemory-lesson-policy-")); const policyPath = join(policyDir, "callers.json"); writeFileSync( @@ -159,6 +166,8 @@ describe("lesson authorization boundaries", () => { }); afterEach(() => { + setEmbeddingProvider(null); + resetLessonRetrievalCacheForTests(); delete process.env["AGENTMEMORY_LESSON_ACCESS_MODE"]; delete process.env["AGENTMEMORY_LESSON_CALLER_POLICY_FILE"]; rmSync(policyDir, { recursive: true, force: true }); @@ -253,6 +262,71 @@ describe("lesson authorization boundaries", () => { expect(recall.body.lessons).toHaveLength(1); }); + it("keeps hidden lessons out of provider inputs, results, and diagnostics", async () => { + const embedder: EmbeddingProvider = { + name: "local", + dimensions: 2, + embed: vi.fn(async () => new Float32Array([1, 0])), + embedBatch: vi.fn(async (texts: string[]) => + texts.map(() => new Float32Array([1, 0])), + ), + }; + setEmbeddingProvider(embedder); + const system = systemLessonAccessContext(); + await sdk.trigger("mem::lesson-save", { + ...lessonInput("invariance-visible"), + content: "Shared candidate visible evidence", + accessContext: system, + }); + const request = { + headers: headers("codex-token", "codex"), + body: { + query: "shared candidate unauthorized payload", + retrievalMode: "hybrid", + compact: true, + }, + }; + + const before = (await sdk.trigger( + "api::lesson-search", + request, + )) as { status_code: number; body: unknown }; + const beforeProviderInputs = JSON.stringify({ + query: vi.mocked(embedder.embed).mock.calls, + candidates: vi.mocked(embedder.embedBatch).mock.calls, + }); + + await sdk.trigger("mem::lesson-save", { + ...lessonInput("invariance-hidden", REPO_TWO), + content: "Shared candidate UNAUTHORIZED_PAYLOAD exact evidence", + accessContext: system, + }); + await sdk.trigger("mem::lesson-recall", { + query: "shared candidate unauthorized payload", + retrievalMode: "hybrid", + compact: true, + accessContext: system, + }); + vi.mocked(embedder.embed).mockClear(); + vi.mocked(embedder.embedBatch).mockClear(); + + const after = (await sdk.trigger( + "api::lesson-search", + request, + )) as { status_code: number; body: unknown }; + const afterProviderInputs = JSON.stringify({ + query: vi.mocked(embedder.embed).mock.calls, + candidates: vi.mocked(embedder.embedBatch).mock.calls, + }); + + expect(after).toEqual(before); + expect(afterProviderInputs).toBe(beforeProviderInputs); + expect(afterProviderInputs).not.toContain("UNAUTHORIZED_PAYLOAD"); + expect(JSON.stringify(after.body)).not.toContain( + "invariance-hidden", + ); + }); + it("reserves whole-database export for a restricted all-scopes operator", async () => { const system = systemLessonAccessContext(); await sdk.trigger("mem::lesson-save", { diff --git a/test/lesson-retrieval.test.ts b/test/lesson-retrieval.test.ts new file mode 100644 index 0000000000..df9b0e3459 --- /dev/null +++ b/test/lesson-retrieval.test.ts @@ -0,0 +1,622 @@ +import { + afterEach, + beforeEach, + describe, + expect, + it, + vi, +} from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { + compactRetrievedLesson, + parseLessonRecallInput, + rankLessonRecallCandidates, + resetLessonRetrievalCacheForTests, + selectLessonRecallCandidates, + type LessonRecallInput, + type RankedLesson, +} from "../src/functions/lesson-retrieval.js"; +import { setEmbeddingProvider } from "../src/functions/search.js"; +import type { + EmbeddingProvider, + LessonReadModel, +} from "../src/types.js"; + +const NOW = "2026-08-03T12:00:00.000Z"; + +function lesson( + suffix: string, + overrides: Partial = {}, +): LessonReadModel { + return { + id: `lsn_${suffix}`, + identityKind: "canonical", + idAliases: [], + content: `Distilled causal lesson ${suffix}`, + context: "Causal retrieval test", + confidence: 0.8, + reinforcements: 0, + source: "manual", + sourceIds: [], + project: "agentmemory", + tags: ["retrieval"], + createdAt: NOW, + updatedAt: NOW, + decayRate: 0.02, + schemaVersion: 1, + mechanismId: `retrieval/${suffix}`, + mechanismAliases: [], + claim: `Mechanism ${suffix} changes the outcome.`, + claimType: "causal", + evidenceVerdict: "unverified", + lifecycle: "active", + applicabilityConditions: [], + nonApplicabilityConditions: [], + falsificationConditions: [], + structuredFacets: {}, + evidenceRefs: [], + scope: { + ring: "repo", + scopeId: "repo:https://github.com/wrightpt/agentmemory", + }, + sensitivity: "public", + contradictedByLessonIds: [], + contentFingerprint: `fp_${suffix}`, + computedFlags: { stale: false, contradicted: false }, + ...overrides, + }; +} + +function recallInput( + overrides: Partial = {}, +): LessonRecallInput { + return { + query: "causal retrieval", + minConfidence: 0.1, + limit: 10, + retrievalMode: "lexical", + compact: false, + evidenceVerdicts: [], + structuredFacets: {}, + tags: [], + ...overrides, + }; +} + +function provider( + overrides: Partial = {}, +): EmbeddingProvider { + return { + name: "local", + dimensions: 2, + embed: vi.fn(async () => new Float32Array([1, 0])), + embedBatch: vi.fn(async (texts: string[]) => + texts.map(() => new Float32Array([1, 0])), + ), + ...overrides, + }; +} + +function ids(ranked: RankedLesson[]): string[] { + return ranked.map(({ lesson: item }) => item.id); +} + +describe("causal lesson retrieval", () => { + beforeEach(() => { + setEmbeddingProvider(null); + resetLessonRetrievalCacheForTests(); + delete process.env["AGENTMEMORY_LESSON_REMOTE_EMBEDDINGS"]; + delete process.env["AGENTMEMORY_LESSON_EMBED_MAX_SENSITIVITY"]; + }); + + afterEach(() => { + setEmbeddingProvider(null); + resetLessonRetrievalCacheForTests(); + delete process.env["AGENTMEMORY_LESSON_REMOTE_EMBEDDINGS"]; + delete process.env["AGENTMEMORY_LESSON_EMBED_MAX_SENSITIVITY"]; + vi.useRealTimers(); + }); + + it("applies exact categorical filters before ranking", () => { + const selected = selectLessonRecallCandidates( + [ + lesson("match", { + confidence: 0.9, + mechanismAliases: ["queue/reversal"], + evidenceVerdict: "unverified", + tags: ["Alpha", "Safe"], + structuredFacets: { + asset: ["HYPE"], + venue: ["Bybit"], + horizon: ["5m"], + }, + }), + lesson("wrong-venue", { + confidence: 0.9, + tags: ["alpha", "safe"], + structuredFacets: { + asset: ["HYPE"], + venue: ["Kraken"], + }, + }), + lesson("substring", { + confidence: 0.9, + tags: ["alpha", "safe"], + structuredFacets: { + asset: ["HYPE-PERP"], + venue: ["Bybit"], + }, + }), + ], + recallInput({ + project: "agentmemory", + minConfidence: 0.85, + mechanismId: "queue/reversal", + claimType: "causal", + evidenceVerdicts: ["unverified", "mixed"], + tags: ["alpha", "SAFE"], + structuredFacets: { + asset: ["hype", "eth"], + venue: ["BYBIT"], + }, + scopeRing: "repo", + sensitivity: "public", + }), + ); + + expect(selected.map((item) => item.id)).toEqual(["lsn_match"]); + + const substring = selectLessonRecallCandidates( + [lesson("substring", { + structuredFacets: { asset: ["HYPE-PERP"] }, + })], + recallInput({ structuredFacets: { asset: ["hype"] } }), + ); + expect(substring).toEqual([]); + }); + + it("rejects malformed and oversized recall inputs", () => { + expect( + parseLessonRecallInput({ + query: "valid", + structuredFacets: { asset: [] }, + }), + ).toMatchObject({ + success: false, + error: expect.stringContaining("at least one value"), + }); + expect( + parseLessonRecallInput({ query: "x".repeat(2_049) }), + ).toMatchObject({ + success: false, + error: expect.stringContaining("at most 2048"), + }); + expect(parseLessonRecallInput({ query: "valid", limit: 51 })).toMatchObject({ + success: false, + error: expect.stringContaining("at most 50"), + }); + }); + + it("preserves the prior lexical confidence and recency scorer without embedding", async () => { + const embedder = provider(); + setEmbeddingProvider(embedder); + const recent = lesson("recent", { + content: "Database query performance", + confidence: 0.8, + createdAt: NOW, + }); + const old = lesson("old", { + content: "Database query performance", + confidence: 0.8, + createdAt: "2025-08-03T12:00:00.000Z", + }); + + vi.useFakeTimers(); + vi.setSystemTime(new Date(NOW)); + const result = await rankLessonRecallCandidates( + [old, recent], + recallInput({ query: "database performance" }), + ); + + expect(ids(result.ranked)).toEqual(["lsn_recent", "lsn_old"]); + expect(result.ranked[0].score).toBe(0.8); + expect(embedder.embed).not.toHaveBeenCalled(); + expect(embedder.embedBatch).not.toHaveBeenCalled(); + + const versionOnly = await rankLessonRecallCandidates( + [lesson("versioned", { mechanismVersion: "v123only" })], + recallInput({ query: "v123only" }), + ); + expect(versionOnly.ranked).toEqual([]); + }); + + it("recalls a semantic match with zero lexical overlap", async () => { + const embedder = provider({ + embedBatch: vi.fn(async (texts: string[]) => + texts.map((text) => + text.includes("Mean reversion") + ? new Float32Array([1, 0]) + : new Float32Array([0, 1]), + ), + ), + }); + setEmbeddingProvider(embedder); + + const result = await rankLessonRecallCandidates( + [ + lesson("semantic", { + content: "Mean reversion fails after transaction costs.", + }), + lesson("other", { + content: "Deployment locks prevent concurrent publication.", + }), + ], + recallInput({ + query: "candidate analogy", + retrievalMode: "hybrid", + }), + ); + + expect(ids(result.ranked)).toEqual(["lsn_semantic"]); + expect(result.ranked[0]).toMatchObject({ + lexicalScore: 0, + semanticScore: 1, + }); + expect(result.diagnostics).toMatchObject({ + requestedMode: "hybrid", + usedMode: "hybrid", + returnedCount: 1, + }); + }); + + it("uses exact deterministic lexical fallback for provider failures and weak semantic signal", async () => { + const candidates = [ + lesson("first", { content: "Exact lexical candidate" }), + lesson("second", { + content: "Exact lexical candidate", + confidence: 0.5, + }), + ]; + const lexical = await rankLessonRecallCandidates( + candidates, + recallInput({ query: "exact lexical" }), + ); + + const badDimensions = provider({ + embedBatch: vi.fn(async (texts: string[]) => + texts.map(() => new Float32Array([1])), + ), + }); + setEmbeddingProvider(badDimensions); + const failed = await rankLessonRecallCandidates( + candidates, + recallInput({ + query: "exact lexical", + retrievalMode: "hybrid", + }), + ); + expect( + failed.ranked.map(({ lesson: item, score }) => [item.id, score]), + ).toEqual( + lexical.ranked.map(({ lesson: item, score }) => [item.id, score]), + ); + expect(failed.diagnostics.fallbackCode).toBe("embedding_failed"); + + resetLessonRetrievalCacheForTests(); + const nonFinite = provider({ + embed: vi.fn(async () => new Float32Array([Number.NaN, 0])), + }); + setEmbeddingProvider(nonFinite); + const invalidQueryVector = await rankLessonRecallCandidates( + candidates, + recallInput({ + query: "exact lexical", + retrievalMode: "hybrid", + }), + ); + expect( + invalidQueryVector.ranked.map(({ lesson: item, score }) => [ + item.id, + score, + ]), + ).toEqual( + lexical.ranked.map(({ lesson: item, score }) => [item.id, score]), + ); + expect(invalidQueryVector.diagnostics.fallbackCode).toBe( + "embedding_failed", + ); + + resetLessonRetrievalCacheForTests(); + const weak = provider({ + embedBatch: vi.fn(async (texts: string[]) => + texts.map(() => new Float32Array([0.1, 0.995])), + ), + }); + setEmbeddingProvider(weak); + const noSignal = await rankLessonRecallCandidates( + candidates, + recallInput({ + query: "exact lexical", + retrievalMode: "hybrid", + }), + ); + expect( + noSignal.ranked.map(({ lesson: item, score }) => [item.id, score]), + ).toEqual( + lexical.ranked.map(({ lesson: item, score }) => [item.id, score]), + ); + expect(noSignal.diagnostics.fallbackCode).toBe("semantic_no_signal"); + }); + + it("does no provider or cache work for zero candidates or candidate overflow", async () => { + const embedder = provider(); + setEmbeddingProvider(embedder); + + const empty = await rankLessonRecallCandidates( + [], + recallInput({ query: "candidate", retrievalMode: "hybrid" }), + ); + expect(empty).toEqual({ + ranked: [], + diagnostics: { + requestedMode: "hybrid", + usedMode: "hybrid", + returnedCount: 0, + }, + }); + + const overflow = await rankLessonRecallCandidates( + Array.from({ length: 257 }, (_, index) => + lesson(`candidate-${index}`, { content: "Candidate match" }), + ), + recallInput({ query: "candidate", retrievalMode: "hybrid" }), + ); + expect(overflow.diagnostics.fallbackCode).toBe( + "semantic_candidate_limit_exceeded", + ); + expect(embedder.embed).not.toHaveBeenCalled(); + expect(embedder.embedBatch).not.toHaveBeenCalled(); + }); + + it("caches exact candidate documents and deduplicates concurrent cold misses", async () => { + let releaseBatch: (() => void) | undefined; + const gate = new Promise((resolve) => { + releaseBatch = resolve; + }); + const embedder = provider({ + embedBatch: vi.fn(async (texts: string[]) => { + await gate; + return texts.map(() => new Float32Array([1, 0])); + }), + }); + setEmbeddingProvider(embedder); + const candidate = lesson("cached", { + content: "Cache candidate", + }); + const input = recallInput({ + query: "cache candidate", + retrievalMode: "hybrid", + }); + + const first = rankLessonRecallCandidates([candidate], input); + const second = rankLessonRecallCandidates([candidate], input); + await Promise.resolve(); + releaseBatch?.(); + await Promise.all([first, second]); + + expect(embedder.embedBatch).toHaveBeenCalledTimes(1); + await rankLessonRecallCandidates([candidate], input); + expect(embedder.embedBatch).toHaveBeenCalledTimes(1); + + await rankLessonRecallCandidates( + [{ ...candidate, content: "Cache candidate changed" }], + input, + ); + expect(embedder.embedBatch).toHaveBeenCalledTimes(2); + }); + + it("keeps protected embeddings request-local while reusing public embeddings", async () => { + const embedder = provider(); + setEmbeddingProvider(embedder); + const input = recallInput({ + query: "cache isolation", + retrievalMode: "hybrid", + }); + const publicCandidate = lesson("public-cache", { + content: "Cache isolation", + sensitivity: "public", + }); + const protectedCandidate = lesson("protected-cache", { + content: "Cache isolation", + sensitivity: "confidential", + }); + + await rankLessonRecallCandidates([publicCandidate], input); + await rankLessonRecallCandidates([publicCandidate], input); + expect(embedder.embedBatch).toHaveBeenCalledTimes(1); + + vi.mocked(embedder.embedBatch).mockClear(); + await rankLessonRecallCandidates([protectedCandidate], input); + await rankLessonRecallCandidates([protectedCandidate], input); + expect(embedder.embedBatch).toHaveBeenCalledTimes(2); + }); + + it("requires explicit remote egress and keeps rows above the ceiling lexical-only", async () => { + const remote = provider({ + name: "openai", + embedBatch: vi.fn(async (texts: string[]) => + texts.map(() => new Float32Array([1, 0])), + ), + }); + setEmbeddingProvider(remote); + const publicLesson = lesson("public", { + content: "Public semantic candidate", + context: "RAW_CONTEXT_MUST_NOT_EGRESS", + sensitivity: "public", + }); + const restrictedLesson = lesson("restricted", { + content: "Restricted lexical secret", + sensitivity: "restricted", + }); + const input = recallInput({ + query: "restricted lexical secret", + retrievalMode: "hybrid", + }); + + const disabled = await rankLessonRecallCandidates( + [publicLesson, restrictedLesson], + input, + ); + expect(disabled.diagnostics.fallbackCode).toBe( + "remote_embedding_disabled", + ); + expect(remote.embed).not.toHaveBeenCalled(); + expect(remote.embedBatch).not.toHaveBeenCalled(); + + process.env["AGENTMEMORY_LESSON_REMOTE_EMBEDDINGS"] = "true"; + process.env["AGENTMEMORY_LESSON_EMBED_MAX_SENSITIVITY"] = "public"; + const enabled = await rankLessonRecallCandidates( + [publicLesson, restrictedLesson], + input, + ); + const embeddedTexts = vi + .mocked(remote.embedBatch) + .mock.calls.flatMap(([texts]) => texts); + + expect(enabled.diagnostics).toMatchObject({ + usedMode: "hybrid", + noticeCode: "embedding_sensitivity_filtered", + }); + expect(ids(enabled.ranked)).toContain("lsn_restricted"); + expect(embeddedTexts.join("\n")).toContain("Public semantic candidate"); + expect(embeddedTexts.join("\n")).not.toContain( + "Restricted lexical secret", + ); + expect(embeddedTexts.join("\n")).not.toContain( + "RAW_CONTEXT_MUST_NOT_EGRESS", + ); + + resetLessonRetrievalCacheForTests(); + vi.mocked(remote.embed).mockClear(); + vi.mocked(remote.embedBatch).mockClear(); + const blocked = await rankLessonRecallCandidates( + [restrictedLesson], + input, + ); + expect(blocked.diagnostics.fallbackCode).toBe( + "embedding_sensitivity_blocked", + ); + expect(remote.embed).not.toHaveBeenCalled(); + expect(remote.embedBatch).not.toHaveBeenCalled(); + + process.env["AGENTMEMORY_LESSON_EMBED_MAX_SENSITIVITY"] = + "not-a-sensitivity"; + const invalidPolicy = await rankLessonRecallCandidates( + [publicLesson], + input, + ); + expect(invalidPolicy.diagnostics.fallbackCode).toBe( + "embedding_policy_invalid", + ); + expect(remote.embed).not.toHaveBeenCalled(); + expect(remote.embedBatch).not.toHaveBeenCalled(); + }); + + it("stops scheduling embedding batches after the semantic deadline", async () => { + vi.useFakeTimers(); + const slow = provider({ + dimensions: 3, + embed: vi.fn(async () => new Float32Array([1, 0, 0])), + embedBatch: vi.fn(async (texts: string[]) => { + await new Promise((resolve) => setTimeout(resolve, 10_000)); + return texts.map(() => new Float32Array([1, 0, 0])); + }), + }); + setEmbeddingProvider(slow); + const candidates = Array.from({ length: 33 }, (_, index) => + lesson(`slow-${index}`, { content: "Slow lexical candidate" }), + ); + + const pending = rankLessonRecallCandidates( + candidates, + recallInput({ + query: "slow lexical", + retrievalMode: "hybrid", + }), + ); + await vi.advanceTimersByTimeAsync(5_001); + const result = await pending; + + expect(result.diagnostics.fallbackCode).toBe("embedding_failed"); + expect(slow.embedBatch).toHaveBeenCalledTimes(1); + await vi.advanceTimersByTimeAsync(5_000); + expect(slow.embedBatch).toHaveBeenCalledTimes(1); + }); + + it("returns a deterministic compact projection under a serialized size ceiling", () => { + const hostile = `\u0000"\\😀${"z".repeat(100)}`; + const facets = Object.fromEntries( + Array.from({ length: 32 }, (_, dimension) => [ + `dimension_${dimension.toString().padStart(2, "0")}`, + Array.from( + { length: 16 }, + (_, value) => `value-${value}-${hostile}`, + ), + ]), + ); + const large = lesson("large", { + content: hostile.repeat(20), + claim: hostile.repeat(10), + project: hostile.repeat(6), + scope: { + ring: "repo", + scopeId: hostile.repeat(4), + }, + applicabilityConditions: Array(16).fill(hostile.repeat(4)), + nonApplicabilityConditions: Array(16).fill(hostile.repeat(4)), + falsificationConditions: Array(16).fill(hostile.repeat(4)), + structuredFacets: facets, + tags: Array.from({ length: 32 }, (_, index) => + `tag-${index}-${hostile}`, + ), + evidenceRefs: [ + { + kind: "experiment", + projectId: "agentmemory", + recordedAt: NOW, + provenance: { + type: "dataset", + locator: "secret://raw-evidence", + immutableId: "sha256:secret", + }, + }, + ], + sourceIds: ["source-secret"], + }); + const compact = compactRetrievedLesson({ + lesson: large, + score: 0.75, + rankingScore: 0.75, + lexicalScore: 0.8, + semanticScore: 0.9, + }); + const serialized = JSON.stringify(compact); + + expect(Buffer.byteLength(serialized, "utf8")).toBeLessThanOrEqual(6_000); + expect(compact.content.length).toBeLessThanOrEqual(400); + expect(compact.claim?.length).toBeLessThanOrEqual(300); + expect(Object.keys(compact.structuredFacets)).toEqual( + Object.keys(compact.structuredFacets).slice().sort(), + ); + expect(Object.keys(compact.structuredFacets).length).toBeLessThanOrEqual(6); + expect(compact.tags.length).toBeLessThanOrEqual(8); + expect(serialized).not.toContain("secret://raw-evidence"); + expect(serialized).not.toContain("source-secret"); + expect(compact).not.toHaveProperty("evidenceRefs"); + expect(compact).not.toHaveProperty("sourceIds"); + }); +}); diff --git a/test/smart-search.test.ts b/test/smart-search.test.ts index 1f344736d1..d4698aedba 100644 --- a/test/smart-search.test.ts +++ b/test/smart-search.test.ts @@ -199,8 +199,8 @@ describe("Smart Search Function", () => { sdk.registerFunction("mem::lesson-recall", async (payload: any) => ({ success: true, lessons: [ - { id: "lsn_a", content: "always rebase before push", confidence: 0.9, createdAt: "2026-04-01T00:00:00Z", project: "p", tags: ["git"], score: 0.81 }, - { id: "lsn_b", content: "never force-push to main", confidence: 0.95, createdAt: "2026-04-02T00:00:00Z", project: "p", tags: ["git"], score: 0.76 }, + { lessonId: "lsn_a", content: "always rebase before push", evidenceVerdict: "supported", contradicted: false, confidence: 0.9, createdAt: "2026-04-01T00:00:00Z", project: "p", tags: ["git"], score: 0.81 }, + { lessonId: "lsn_b", content: "never force-push to main", evidenceVerdict: "supported", contradicted: false, confidence: 0.95, createdAt: "2026-04-02T00:00:00Z", project: "p", tags: ["git"], score: 0.76 }, ], })); @@ -220,19 +220,18 @@ describe("Smart Search Function", () => { expect(result.lessons![0].tags).toEqual(["git"]); }); - it("compact mode truncates long lesson content for preview", async () => { - const long = "x".repeat(500); + it("preserves the retriever's already-bounded lesson projection", async () => { + const bounded = `${"x".repeat(399)}…`; sdk.registerFunction("mem::lesson-recall", async () => ({ success: true, - lessons: [{ id: "lsn_long", content: long, confidence: 0.5, createdAt: "", tags: [], score: 0.4 }], + lessons: [{ lessonId: "lsn_long", content: bounded, evidenceVerdict: "unverified", contradicted: false, confidence: 0.5, createdAt: "", tags: [], score: 0.4 }], })); const result = (await sdk.trigger("mem::smart-search", { query: "x", })) as { lessons: any[] }; - expect(result.lessons[0].content.length).toBeLessThan(long.length); - expect(result.lessons[0].content).toMatch(/…$/); + expect(result.lessons[0].content).toBe(bounded); }); it("carries claim and explicitly labels refuted or contradicted evidence", async () => { @@ -240,21 +239,22 @@ describe("Smart Search Function", () => { success: true, lessons: [ { - id: "lsn_refuted", + lessonId: "lsn_refuted", content: "Long prose must not become positive guidance.", claim: "Force-pushing main is safe.", evidenceVerdict: "refuted", + contradicted: false, confidence: 0.9, createdAt: "2026-04-01T00:00:00Z", tags: ["git"], score: 0.8, }, { - id: "lsn_contradicted", + lessonId: "lsn_contradicted", content: "This claim has an active counterexample.", claim: "All retries are idempotent.", evidenceVerdict: "supported", - contradictedByLessonIds: ["lsn_counterexample"], + contradicted: true, confidence: 0.7, createdAt: "2026-04-01T00:00:00Z", tags: ["retries"], @@ -311,6 +311,8 @@ describe("Smart Search Function", () => { expect(receivedPayload).toMatchObject({ query: "rebase", project: "gitops-assistant", + retrievalMode: "hybrid", + compact: true, }); }); From 6c27da22ecff4832fa550c1d168a5b03c37d2ec2 Mon Sep 17 00:00:00 2001 From: pi-agent Date: Tue, 4 Aug 2026 21:39:16 -0400 Subject: [PATCH 41/43] fix(memories): clear dangling supersedes/parentId/relatedIds on delete + heal MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Root cause (D2): mem::governance-delete and mem::governance-bulk deleted a memory without clearing supersedes/parentId/relatedIds back-references in *other* memories, so every delete minted new memory-missing-supersedes warnings. The heal path could not repair them either (the warn was fixable=false and no prune branch existed). Changes (code-only; no live data touched, no restart/deploy): - src/state/memory-utils.ts: add pure stripMemoryReferences() that drops references to a given id set from supersedes/parentId/relatedIds and reports what was removed. Shared by governance and diagnostics. - src/functions/governance.ts: governance-delete and governance-bulk now call clearDanglingMemoryReferences() on surviving memories after a delete, returning repairedReferrers + removedReferences in the result and audit details. Indexes untouched (ref fields are not searchable). - src/functions/diagnostics.ts: * memory-missing-supersedes warn is now fixable=true. * add memory-missing-parent and memory-missing-related warn detection. * add a memories heal branch that prunes dangling supersedes/parentId/ relatedIds (dry-run supported), audited as reason "dangling-memory-reference-prune". - Honest project-coverage messaging (D3): the diagnostic no longer blindly prescribes infer-memory-projects. It splits the unscoped count into session-linked (inferable) vs session-less (ambiguous; the migration returns them unchanged), and says so explicitly — verified live that infer-memory-projects is updated=0/ambiguous=128 here. Tests: +8 in test/diagnostics.test.ts and test/governance.test.ts covering delete cleanup (single + bulk), heal prune (apply + dry-run), the new parentId/relatedIds warns, and the honest coverage messages. Full suite: 1699 passed (160 files). Build: tsdown OK. Not pushed, not merged, not deployed, not activated. The diverged local main (ahead 2 / behind 13) is untouched. The running engine build is unchanged; these changes take effect only after a supervisor-authorized build + systemctl restart agentmemory.service, at which point the existing dangling references can be pruned via mem::heal {categories:["memories"]} (dry-run first). Refs: AgentMemory action act_msfdnoby_4609034b3c0f (workstation) --- src/functions/diagnostics.ts | 121 +++++++++++++++++++++++++-- src/functions/governance.ts | 64 +++++++++++++- src/state/memory-utils.ts | 59 +++++++++++++ test/diagnostics.test.ts | 156 ++++++++++++++++++++++++++++++++++- test/governance.test.ts | 85 +++++++++++++++++++ 5 files changed, 476 insertions(+), 9 deletions(-) diff --git a/src/functions/diagnostics.ts b/src/functions/diagnostics.ts index c19a643560..02c352cd83 100644 --- a/src/functions/diagnostics.ts +++ b/src/functions/diagnostics.ts @@ -8,6 +8,7 @@ import { deleteActionEdge, persistAction, } from "./action-store.js"; +import { stripMemoryReferences } from "../state/memory-utils.js"; import { isLessonListable } from "./lesson-model.js"; import { canReadLesson, @@ -343,13 +344,44 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { category: "memories", status: "warn", message: `Memory "${memory.title}" supersedes non-existent memory ${sid}`, - fixable: false, + // Fixable via mem::heal {categories:["memories"]}, which now + // prunes dangling supersedes/parentId/relatedIds references. + fixable: true, }); memoryIssues++; } supersededBy.set(sid, memory.id); } } + + // parentId / relatedIds dangling-reference detection. Same root + // cause as missing-supersedes (a delete that did not clear + // back-references), so they are heal-fixable too. + if (memory.parentId && !memoryIds.has(memory.parentId)) { + checks.push({ + name: `memory-missing-parent:${memory.id}:${memory.parentId}`, + category: "memories", + status: "warn", + message: `Memory "${memory.title}" has parentId ${memory.parentId} which does not exist`, + fixable: true, + }); + memoryIssues++; + } + + if (memory.relatedIds && memory.relatedIds.length > 0) { + for (const rid of memory.relatedIds) { + if (!memoryIds.has(rid)) { + checks.push({ + name: `memory-missing-related:${memory.id}:${rid}`, + category: "memories", + status: "warn", + message: `Memory "${memory.title}" references non-existent related memory ${rid}`, + fixable: true, + }); + memoryIssues++; + } + } + } } for (const memory of memories) { @@ -366,11 +398,29 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { } // Project-coverage check: unscoped memories (no project field) will - // appear in every project's context and search results until the - // infer-memory-projects migration runs. Surface a count so operators - // know the backfill is still pending and can trigger it explicitly. + // appear in every project's context and search results until they are + // assigned a project. The message must be honest about what the + // infer-memory-projects migration can actually do: it only attributes + // memories that have sessionIds resolving to a strict-majority project. + // Unscoped memories with empty sessionIds (common for pre-session-link + // legacy rows) are returned as `ambiguous` and left unchanged, so + // prescribing that migration for them is a no-op. Split the count so + // an operator knows how many are inferable vs need manual assignment. const latestMemories = memories.filter((m) => m.isLatest); - const unscopedCount = latestMemories.filter((m) => !m.project).length; + const unscoped = latestMemories.filter((m) => !m.project); + const unscopedCount = unscoped.length; + const inferableCount = unscoped.filter( + (m) => (m.sessionIds?.length ?? 0) > 0, + ).length; + const ambiguousCount = unscopedCount - inferableCount; + const inferHint = + inferableCount > 0 + ? `run POST /agentmemory/migrate {"step":"infer-memory-projects"} to attempt backfill of the ${inferableCount} session-linked` + : `no session-linked unscoped memories remain; infer-memory-projects is a no-op here`; + const ambiguousHint = + ambiguousCount > 0 + ? `; the remaining ${ambiguousCount} have no sessionIds and need manual project assignment (or a session linkage pass) — the migration cannot attribute them` + : ""; if (unscopedCount === 0) { checks.push({ name: "memory-project-coverage", @@ -384,7 +434,7 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { name: "memory-project-coverage", category: "memories", status: "warn", - message: `${unscopedCount} of ${latestMemories.length} latest memories have no project scope — run POST /agentmemory/migrate {"step":"infer-memory-projects"} to backfill`, + message: `${unscopedCount} of ${latestMemories.length} latest memories have no project scope — ${inferHint}${ambiguousHint}`, fixable: true, }); } else { @@ -392,7 +442,7 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { name: "memory-project-coverage", category: "memories", status: "fail", - message: `${unscopedCount} of ${latestMemories.length} latest memories have no project scope — run POST /agentmemory/migrate {"step":"infer-memory-projects"} to backfill`, + message: `${unscopedCount} of ${latestMemories.length} latest memories have no project scope — ${inferHint}${ambiguousHint}`, fixable: true, }); } @@ -1166,6 +1216,63 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { } } } + + // Prune dangling inter-memory references (supersedes/parentId/ + // relatedIds pointing at non-existent memories). These accumulate when + // memories are removed outside governance-delete (legacy deletes, + // manual KV edits) and are exactly what the memory-missing-* warns + // above flag. Code-only: no live data is touched until an operator + // invokes mem::heal after deploy. + const currentMemories = await kv.list(KV.memories); + const existingIds = new Set(currentMemories.map((m) => m.id)); + for (const memory of currentMemories) { + const dangling = new Set(); + for (const id of memory.supersedes ?? []) { + if (!existingIds.has(id)) dangling.add(id); + } + if (memory.parentId && !existingIds.has(memory.parentId)) { + dangling.add(memory.parentId); + } + for (const id of memory.relatedIds ?? []) { + if (!existingIds.has(id)) dangling.add(id); + } + if (dangling.size === 0) continue; + + if (dryRun) { + details.push( + `[dry-run] Would prune ${dangling.size} dangling reference(s) from memory "${memory.title}" (${memory.id})`, + ); + fixed++; + continue; + } + const didFix = await withKeyedLock( + `mem:memory:${memory.id}`, + async () => { + const fresh = await kv.get(KV.memories, memory.id); + if (!fresh) return false; + const { memory: next, changed } = + stripMemoryReferences(fresh, dangling); + if (!changed) return false; + next.updatedAt = new Date().toISOString(); + await kv.set(KV.memories, next.id, next); + await recordAudit(kv, "heal", "mem::heal", [next.id], { + entityType: "memory", + reason: "dangling-memory-reference-prune", + action: "update", + removed: [...dangling], + }); + return true; + }, + ); + if (didFix) { + details.push( + `Pruned ${dangling.size} dangling reference(s) from memory "${memory.title}" (${memory.id})`, + ); + fixed++; + } else { + skipped++; + } + } } return { success: true, fixed, skipped, details }; diff --git a/src/functions/governance.ts b/src/functions/governance.ts index b28fef21e8..e227f0ae41 100644 --- a/src/functions/governance.ts +++ b/src/functions/governance.ts @@ -5,8 +5,41 @@ import type { StateKV } from "../state/kv.js"; import { recordAudit, safeAudit, queryAudit } from "./audit.js"; import { deleteAccessLog } from "./access-tracker.js"; import { getSearchIndex, vectorIndexRemove, flushIndexSave } from "./search.js"; +import { stripMemoryReferences } from "../state/memory-utils.js"; import { logger } from "../logger.js"; +/** + * After memories are deleted, clear now-dangling `supersedes`/`parentId`/ + * `relatedIds` back-references in the *surviving* memories. Returns the IDs of + * memories that were repaired and how many references were dropped, for audit + * and result reporting. Indexes are not touched: reference fields are not part + * of the search/vector observation shape. + */ +async function clearDanglingMemoryReferences( + kv: StateKV, + deletedIds: string[], +): Promise<{ repairedReferrers: string[]; removedCount: number }> { + if (deletedIds.length === 0) { + return { repairedReferrers: [], removedCount: 0 }; + } + const removed = new Set(deletedIds); + const memories = await kv.list(KV.memories); + const repairedReferrers: string[] = []; + let removedCount = 0; + for (const memory of memories) { + if (removed.has(memory.id)) continue; + const { memory: next, changed, removed: dropped } = + stripMemoryReferences(memory, removed); + if (changed) { + next.updatedAt = new Date().toISOString(); + await kv.set(KV.memories, next.id, next); + repairedReferrers.push(next.id); + removedCount += dropped.length; + } + } + return { repairedReferrers, removedCount }; +} + export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::governance-delete", async (data: { memoryIds: string[]; reason?: string }) => { @@ -19,6 +52,7 @@ export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { } let deleted = 0; + const deletedIds: string[] = []; for (const id of data.memoryIds) { const mem = await kv.get(KV.memories, id); if (mem) { @@ -27,11 +61,18 @@ export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { getSearchIndex().remove(id); vectorIndexRemove(id); deleted++; + deletedIds.push(id); } } if (deleted > 0) await flushIndexSave(); + // Prevent the delete from leaving dangling supersedes/parentId/ + // relatedIds back-references in surviving memories. Without this, every + // governance-delete would mint new memory-missing-supersedes warnings. + const { repairedReferrers, removedCount } = + await clearDanglingMemoryReferences(kv, deletedIds); + await recordAudit( kv, "delete", @@ -40,14 +81,24 @@ export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { { reason: data.reason || "manual deletion", deleted, + repairedReferrers: repairedReferrers.length > 0 ? repairedReferrers : undefined, + removedReferences: removedCount > 0 ? removedCount : undefined, }, ); logger.info("Governance delete", { requested: data.memoryIds.length, deleted, + repairedReferrers: repairedReferrers.length, + removedReferences: removedCount, }); - return { success: true, deleted, total: data.memoryIds.length }; + return { + success: true, + deleted, + total: data.memoryIds.length, + repairedReferrers, + removedReferences: removedCount, + }; }, ); @@ -138,6 +189,11 @@ export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { if (successfulIds.length > 0) await flushIndexSave(); + // Same dangling-reference cleanup as the single governance-delete path, + // applied to the batch of successfully deleted memories. + const { repairedReferrers, removedCount } = + await clearDanglingMemoryReferences(kv, successfulIds); + await safeAudit( kv, "delete", @@ -148,18 +204,24 @@ export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { deleted: successfulIds.length, failed: failures.length, failures: failures.length > 0 ? failures : undefined, + repairedReferrers: repairedReferrers.length > 0 ? repairedReferrers : undefined, + removedReferences: removedCount > 0 ? removedCount : undefined, }, ); logger.info("Governance bulk delete", { deleted: successfulIds.length, failed: failures.length, + repairedReferrers: repairedReferrers.length, + removedReferences: removedCount, }); return { success: failures.length === 0, deleted: successfulIds.length, failed: failures.length, failures: failures.length > 0 ? failures : undefined, + repairedReferrers, + removedReferences: removedCount, }; }, ); diff --git a/src/state/memory-utils.ts b/src/state/memory-utils.ts index aa0bcc5b8a..917e16e796 100644 --- a/src/state/memory-utils.ts +++ b/src/state/memory-utils.ts @@ -1,5 +1,64 @@ import type { CompressedObservation, Memory } from "../types.js"; +export type MemoryReferenceField = "supersedes" | "parentId" | "relatedIds"; + +/** + * Remove references to `idsToRemove` from a memory's inter-memory reference + * fields (`supersedes`, `parentId`, `relatedIds`). Returns a shallow copy with + * the dangling references dropped, plus what was removed. + * + * Pure (no KV): used by governance-delete to keep a delete from leaving + * dangling back-references in *other* memories, and by diagnostics heal to + * prune references that already point at non-existent memories. Covering all + * three fields here keeps the two call sites consistent — a partial fix that + * cleared only `supersedes`/`parentId` would leave `relatedIds` dangling for + * the same root cause. + */ +export function stripMemoryReferences( + memory: Memory, + idsToRemove: Set, +): { + memory: Memory; + changed: boolean; + removed: Array<{ field: MemoryReferenceField; value: string }>; +} { + const removed: Array<{ field: MemoryReferenceField; value: string }> = []; + const next: Memory = { ...memory }; + + if (next.supersedes && next.supersedes.length > 0) { + const kept = next.supersedes.filter((id) => { + if (idsToRemove.has(id)) { + removed.push({ field: "supersedes", value: id }); + return false; + } + return true; + }); + if (kept.length !== next.supersedes.length) { + next.supersedes = kept; + } + } + + if (next.parentId && idsToRemove.has(next.parentId)) { + removed.push({ field: "parentId", value: next.parentId }); + next.parentId = undefined; + } + + if (next.relatedIds && next.relatedIds.length > 0) { + const kept = next.relatedIds.filter((id) => { + if (idsToRemove.has(id)) { + removed.push({ field: "relatedIds", value: id }); + return false; + } + return true; + }); + if (kept.length !== next.relatedIds.length) { + next.relatedIds = kept; + } + } + + return { memory: next, changed: removed.length > 0, removed }; +} + // Wraps a Memory record in the CompressedObservation shape that // SearchIndex / VectorIndex / enrichment paths consume. Memories share // the same searchable fields as observations (title + content + diff --git a/test/diagnostics.test.ts b/test/diagnostics.test.ts index 266f1ab613..a5ce8b0684 100644 --- a/test/diagnostics.test.ts +++ b/test/diagnostics.test.ts @@ -504,7 +504,95 @@ describe("Diagnostics Functions", () => { ); expect(check).toBeDefined(); expect(check!.status).toBe("warn"); - expect(check!.fixable).toBe(false); + // Fixable via mem::heal {categories:["memories"]}, which prunes + // dangling supersedes/parentId/relatedIds references. + expect(check!.fixable).toBe(true); + }); + + it("dangling parentId and relatedIds produce fixable warns", async () => { + const alive = makeMemory({ id: "mem_alive" }); + const withParent = makeMemory({ + id: "mem_orphan", + parentId: "mem_gone", + }); + const withRelated = makeMemory({ + id: "mem_related", + relatedIds: ["mem_gone", "mem_alive"], + }); + for (const m of [alive, withParent, withRelated]) { + await kv.set(KV.memories, m.id, m); + } + + const result = (await sdk.trigger("mem::diagnose", { + categories: ["memories"], + })) as { checks: DiagnosticCheck[] }; + + const parentCheck = result.checks.find((c) => + c.name.startsWith("memory-missing-parent:"), + ); + expect(parentCheck).toBeDefined(); + expect(parentCheck!.status).toBe("warn"); + expect(parentCheck!.fixable).toBe(true); + + const relatedCheck = result.checks.find((c) => + c.name.startsWith("memory-missing-related:"), + ); + expect(relatedCheck).toBeDefined(); + expect(relatedCheck!.status).toBe("warn"); + expect(relatedCheck!.fixable).toBe(true); + }); + + it("project-coverage message is honest when unscoped memories lack sessionIds", async () => { + // Unscoped memories with no sessionIds cannot be attributed by + // infer-memory-projects (returned as `ambiguous`). The message must say + // so instead of prescribing a no-op migration. + await kv.set( + KV.memories, + "m1", + makeMemory({ id: "m1", project: undefined, sessionIds: [] }), + ); + + const result = (await sdk.trigger("mem::diagnose", { + categories: ["memories"], + })) as { checks: DiagnosticCheck[] }; + + const check = result.checks.find( + (c) => c.name === "memory-project-coverage", + ); + expect(check).toBeDefined(); + expect(check!.message).toContain("no session-linked unscoped memories remain"); + expect(check!.message).toContain("infer-memory-projects is a no-op here"); + expect(check!.message).toContain("need manual project assignment"); + }); + + it("project-coverage message distinguishes inferable from ambiguous unscoped memories", async () => { + await kv.set( + KV.memories, + "inferable", + makeMemory({ + id: "inferable", + project: undefined, + sessionIds: ["ses_1"], + }), + ); + await kv.set( + KV.memories, + "ambiguous", + makeMemory({ id: "ambiguous", project: undefined, sessionIds: [] }), + ); + + const result = (await sdk.trigger("mem::diagnose", { + categories: ["memories"], + })) as { checks: DiagnosticCheck[] }; + + const check = result.checks.find( + (c) => c.name === "memory-project-coverage", + ); + expect(check).toBeDefined(); + // The session-linked count (1) is surfaced for the migration hint... + expect(check!.message).toContain("attempt backfill of the 1 session-linked"); + // ...and the session-less count (1) is flagged as needing manual work. + expect(check!.message).toContain("remaining 1 have no sessionIds"); }); it("stale mesh peer produces warn", async () => { @@ -707,6 +795,72 @@ describe("Diagnostics Functions", () => { const unchanged = await kv.get(KV.actions, blocked.id); expect(unchanged!.status).toBe("blocked"); }); + + it("prunes dangling supersedes/parentId/relatedIds references", async () => { + // mem_alive is legitimately superseded by mem_child, so isLatest=false — + // this also keeps the stale-latest heal pass quiet so the count isolates + // the dangling-reference prune. + const alive = makeMemory({ id: "mem_alive", title: "Alive", isLatest: false }); + const supersedesDangling = makeMemory({ + id: "mem_child", + title: "Child", + supersedes: ["mem_gone", "mem_alive"], + }); + const parentDangling = makeMemory({ + id: "mem_orphan", + title: "Orphan", + parentId: "mem_gone", + }); + const relatedDangling = makeMemory({ + id: "mem_related", + title: "Related", + relatedIds: ["mem_gone", "mem_alive"], + }); + for (const m of [alive, supersedesDangling, parentDangling, relatedDangling]) { + await kv.set(KV.memories, m.id, m); + } + + const result = (await sdk.trigger("mem::heal", { + categories: ["memories"], + })) as { success: boolean; fixed: number; details: string[] }; + + expect(result.success).toBe(true); + // Three memories had dangling refs pruned. + expect(result.fixed).toBe(3); + + const child = await kv.get(KV.memories, "mem_child"); + expect(child!.supersedes).toEqual(["mem_alive"]); + + const orphan = await kv.get(KV.memories, "mem_orphan"); + expect(orphan!.parentId).toBeUndefined(); + + const related = await kv.get(KV.memories, "mem_related"); + expect(related!.relatedIds).toEqual(["mem_alive"]); + }); + + it("dry run reports dangling references without pruning", async () => { + const alive = makeMemory({ id: "mem_alive", title: "Alive" }); + const dangling = makeMemory({ + id: "mem_child", + title: "Child", + supersedes: ["mem_gone"], + }); + await kv.set(KV.memories, alive.id, alive); + await kv.set(KV.memories, dangling.id, dangling); + + const result = (await sdk.trigger("mem::heal", { + categories: ["memories"], + dryRun: true, + })) as { success: boolean; fixed: number; details: string[] }; + + expect(result.success).toBe(true); + expect(result.fixed).toBe(1); + expect(result.details.some((d) => d.includes("[dry-run]"))).toBe(true); + + // Nothing actually changed. + const unchanged = await kv.get(KV.memories, "mem_child"); + expect(unchanged!.supersedes).toEqual(["mem_gone"]); + }); }); describe("per-store tally categories (#lesson-visibility)", () => { diff --git a/test/governance.test.ts b/test/governance.test.ts index 53b5c702ca..ad4157c92b 100644 --- a/test/governance.test.ts +++ b/test/governance.test.ts @@ -224,6 +224,91 @@ describe("Governance Functions", () => { // Delete paths must tear down the BM25 index entry and trigger an // IndexPersistence save so a hard process exit can't restore a stale // snapshot at next boot. + describe("dangling reference cleanup on delete (#supersedes-parent-cleanup)", () => { + it("governance-delete clears supersedes/parentId/relatedIds in survivors", async () => { + // mem_target is referenced by all three fields of mem_holder. Deleting it + // must drop those references rather than leaving them dangling. + const target = makeMemory("mem_target", "pattern"); + const holder = makeMemory("mem_holder", "bug"); + holder.supersedes = ["mem_target", "mem_other_alive"]; + holder.parentId = "mem_target"; + holder.relatedIds = ["mem_target", "mem_other_alive"]; + const otherAlive = makeMemory("mem_other_alive", "pattern"); + for (const m of [target, holder, otherAlive]) { + await kv.set("mem:memories", m.id, m); + } + + const result = (await sdk.trigger("mem::governance-delete", { + memoryIds: ["mem_target"], + reason: "superseded cleanup", + })) as { + success: boolean; + deleted: number; + repairedReferrers: string[]; + removedReferences: number; + }; + + expect(result.success).toBe(true); + expect(result.deleted).toBe(1); + expect(result.repairedReferrers).toEqual(["mem_holder"]); + // 1 supersedes + 1 parentId + 1 relatedIds = 3 references dropped. + expect(result.removedReferences).toBe(3); + + const holderAfter = (await kv.get("mem:memories", "mem_holder")) as Memory; + expect(holderAfter.supersedes).toEqual(["mem_other_alive"]); + expect(holderAfter.parentId).toBeUndefined(); + expect(holderAfter.relatedIds).toEqual(["mem_other_alive"]); + }); + + it("governance-delete with no surviving refs reports empty repair lists", async () => { + // mem_1/mem_2/mem_3 are the beforeEach seed; none reference each other. + const result = (await sdk.trigger("mem::governance-delete", { + memoryIds: ["mem_1"], + })) as { + success: boolean; + repairedReferrers: string[]; + removedReferences: number; + }; + + expect(result.success).toBe(true); + expect(result.repairedReferrers).toEqual([]); + expect(result.removedReferences).toBe(0); + }); + + it("governance-bulk clears supersedes/parentId/relatedIds in survivors", async () => { + // holder is type "fact" so it survives a pattern-only bulk delete; it + // references mem_target (pattern) via all three fields. + const target = makeMemory("mem_target", "pattern"); + const holder = makeMemory("mem_holder", "fact"); + holder.supersedes = ["mem_target"]; + holder.parentId = "mem_target"; + holder.relatedIds = ["mem_target"]; + for (const m of [target, holder]) { + await kv.set("mem:memories", m.id, m); + } + + const result = (await sdk.trigger("mem::governance-bulk", { + type: ["pattern"], + })) as { + success: boolean; + deleted: number; + repairedReferrers: string[]; + removedReferences: number; + }; + + expect(result.success).toBe(true); + // mem_target + the two seeded pattern memories (mem_1, mem_3) deleted. + expect(result.deleted).toBe(3); + expect(result.repairedReferrers).toEqual(["mem_holder"]); + expect(result.removedReferences).toBe(3); + + const holderAfter = (await kv.get("mem:memories", "mem_holder")) as Memory; + expect(holderAfter.supersedes ?? []).toEqual([]); + expect(holderAfter.parentId).toBeUndefined(); + expect(holderAfter.relatedIds ?? []).toEqual([]); + }); + }); + describe("search index cleanup on delete", () => { function indexedObs(id: string, title: string) { return memoryToObservation({ From 54f95826aacf29ba465d82400868bef78f2f3d56 Mon Sep 17 00:00:00 2001 From: pi-agent Date: Tue, 4 Aug 2026 21:55:32 -0400 Subject: [PATCH 42/43] =?UTF-8?q?fix(diagnostics):=20review=20corrections?= =?UTF-8?q?=20=E2=80=94=20gate=20honesty=20+=20concurrency=20safety?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Code-only supervisor review corrections for 6c27da22. No live mutation, no restart/deploy. (1) blocked-deps-done false-positive guard (the rebound root cause): - src/functions/actions.ts: export hasExplicitNonDependencyGate() — true when an action is held by blockedReason / awaitingHuman / pending-or- rejected approval / an unsatisfied gated_by checkpoint (i.e. NOT by its requires-deps alone). - diagnostics.ts diagnosis: only flag blocked-deps-done (fixable) when the block is dependency-only; explicitly-gated actions are intentionally blocked and are no longer flagged. - diagnostics.ts heal: the blocked-deps-done branch now skips explicitly- gated actions (returns false -> skipped), so heal no longer churns revisions or writes a misleading newStatus=pending audit for actions legacyStatusFor would immediately re-block. (2) Honest project-coverage fixability: fixable = inferableCount > 0. When every unscoped memory lacks sessionIds the infer-memory-projects migration is a no-op, so the finding is not auto-fixable. (3) clearDanglingMemoryReferences concurrency: each survivor is now repaired under its per-memory keyed lock (mem:memory:) with a fresh read immediately before strip/write, so a concurrent survivor update is preserved instead of clobbered by a stale snapshot. (4) Removed the untracked node_modules symlink from the worktree. Tests (+4): diagnose "explicit human/approval/blockedReason gates not flagged"; heal "does not unblock an explicit-gate action"; governance concurrency "preserves a concurrent survivor update" and "does not clobber a concurrently-corrected survivor" (both fail on the pre-fix code). Project-coverage tests gained fixable assertions (zero-candidate=false, mixed=true). Full suite 1703 passed (160 files); tsdown build OK. git status clean (node_modules symlink removed). Not pushed, not merged, not deployed, not activated. REBOUND-INVESTIGATION conclusions unchanged (the three live actions remain correctly blocked by their approval gates; this commit just stops flagging/healing them). Refs: AgentMemory action act_msfdnoby_4609034b3c0f (workstation) --- src/functions/actions.ts | 36 +++++++++++ src/functions/diagnostics.ts | 46 +++++++++++--- src/functions/governance.ts | 33 +++++++--- test/diagnostics.test.ts | 84 +++++++++++++++++++++++++ test/governance.test.ts | 117 +++++++++++++++++++++++++++++++++++ 5 files changed, 299 insertions(+), 17 deletions(-) diff --git a/src/functions/actions.ts b/src/functions/actions.ts index 6514ab8ab3..72980051fb 100644 --- a/src/functions/actions.ts +++ b/src/functions/actions.ts @@ -649,6 +649,42 @@ async function actionGateExists( return Boolean(checkpoint || sentinel); } +/** + * True when an action is held blocked by something OTHER than its `requires` + * dependency edges: a manual `blockedReason`, `awaitingHuman`, a pending or + * rejected `approval`, or an unsatisfied `gated_by` checkpoint/sentinel. + * + * Used by diagnosis and heal so a "blocked but all dependencies done" finding + * is only treated as fixable when the dependencies are the SOLE blocker. An + * explicit gate means the block is intentional, and heal must not clear it: + * `normalizeActionV2` -> `legacyStatusFor` would immediately re-derive + * `status: "blocked"` from the surviving gate, so unblocking would only + * produce revision churn and a misleading "newStatus: pending" audit. + */ +export async function hasExplicitNonDependencyGate( + kv: StateKV, + action: Action, + edges: ActionEdge[], +): Promise { + if (action.blockedReason) return true; + if (action.awaitingHuman) return true; + const approvalState = action.approval?.state; + if (approvalState === "pending" || approvalState === "rejected") return true; + const gates = edges.filter( + (edge) => edge.sourceActionId === action.id && edge.type === "gated_by", + ); + for (const edge of gates) { + const checkpoint = await kv.get( + KV.checkpoints, + edge.targetActionId, + ); + if (checkpoint?.status === "passed") continue; + const sentinel = await kv.get(KV.sentinels, edge.targetActionId); + if (sentinel?.status !== "triggered") return true; + } + return false; +} + function applyActionUpdate( action: Action, data: ActionUpdateInput, diff --git a/src/functions/diagnostics.ts b/src/functions/diagnostics.ts index 02c352cd83..a707c76504 100644 --- a/src/functions/diagnostics.ts +++ b/src/functions/diagnostics.ts @@ -8,6 +8,7 @@ import { deleteActionEdge, persistAction, } from "./action-store.js"; +import { hasExplicitNonDependencyGate } from "./actions.js"; import { stripMemoryReferences } from "../state/memory-utils.js"; import { isLessonListable } from "./lesson-model.js"; import { @@ -99,13 +100,26 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { return target && target.status === "done"; }); if (allDone) { - checks.push({ - name: `blocked-deps-done:${action.id}`, - category: "actions", - status: "fail", - message: `Action "${action.title}" is blocked but all dependencies are done`, - fixable: true, - }); + // Only a dependency-only block is a fixable defect. An explicit + // non-dependency gate (blockedReason / awaitingHuman / + // pending-or-rejected approval / unsatisfied gated_by) means the + // block is intentional — flagging it as "deps done, should + // unblock" is a false positive (heal cannot clear the gate; + // legacyStatusFor would revert the unblock). + const hasExplicitGate = await hasExplicitNonDependencyGate( + kv, + action, + allEdges, + ); + if (!hasExplicitGate) { + checks.push({ + name: `blocked-deps-done:${action.id}`, + category: "actions", + status: "fail", + message: `Action "${action.title}" is blocked but all dependencies are done`, + fixable: true, + }); + } } } } @@ -421,6 +435,12 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { ambiguousCount > 0 ? `; the remaining ${ambiguousCount} have no sessionIds and need manual project assignment (or a session linkage pass) — the migration cannot attribute them` : ""; + // Fixability is honest: the engine can only auto-backfill the + // session-linked (inferable) subset via infer-memory-projects. When + // every unscoped memory lacks sessionIds the migration is a no-op, so + // the finding is not fixable by an automated heal/migrate step (it + // needs manual project assignment or a session-linkage pass). + const coverageFixable = inferableCount > 0; if (unscopedCount === 0) { checks.push({ name: "memory-project-coverage", @@ -435,7 +455,7 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { category: "memories", status: "warn", message: `${unscopedCount} of ${latestMemories.length} latest memories have no project scope — ${inferHint}${ambiguousHint}`, - fixable: true, + fixable: coverageFixable, }); } else { checks.push({ @@ -443,7 +463,7 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { category: "memories", status: "fail", message: `${unscopedCount} of ${latestMemories.length} latest memories have no project scope — ${inferHint}${ambiguousHint}`, - fixable: true, + fixable: coverageFixable, }); } @@ -808,6 +828,14 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void { return target && target.status === "done"; }); if (!stillAllDone) return false; + // Skip actions held by an explicit non-dependency gate: + // unblocking them is a no-op (legacyStatusFor reverts it) + // that only churns revisions and writes a misleading audit. + if ( + await hasExplicitNonDependencyGate(kv, fresh, freshEdges) + ) { + return false; + } const before = structuredClone(fresh); fresh.status = "pending"; fresh.lifecycle = "pending"; diff --git a/src/functions/governance.ts b/src/functions/governance.ts index e227f0ae41..97b899e4d8 100644 --- a/src/functions/governance.ts +++ b/src/functions/governance.ts @@ -2,6 +2,7 @@ import type { ISdk } from "iii-sdk"; import type { Memory, GovernanceFilter, AuditEntry } from "../types.js"; import { KV } from "../state/schema.js"; import type { StateKV } from "../state/kv.js"; +import { withKeyedLock } from "../state/keyed-mutex.js"; import { recordAudit, safeAudit, queryAudit } from "./audit.js"; import { deleteAccessLog } from "./access-tracker.js"; import { getSearchIndex, vectorIndexRemove, flushIndexSave } from "./search.js"; @@ -14,6 +15,12 @@ import { logger } from "../logger.js"; * memories that were repaired and how many references were dropped, for audit * and result reporting. Indexes are not touched: reference fields are not part * of the search/vector observation shape. + * + * Each survivor is repaired under its per-memory keyed lock + * (`mem:memory:`, the same key diagnostics heal uses) with a fresh read + * immediately before stripping/writing, so a concurrent update to a survivor + * (e.g. a new `supersedes` added between the list and the write) is preserved + * rather than clobbered by a stale snapshot. */ async function clearDanglingMemoryReferences( kv: StateKV, @@ -23,18 +30,28 @@ async function clearDanglingMemoryReferences( return { repairedReferrers: [], removedCount: 0 }; } const removed = new Set(deletedIds); - const memories = await kv.list(KV.memories); + // List once to pick candidate survivors; the authoritative read happens per + // memory inside the lock below. + const snapshot = await kv.list(KV.memories); + const candidateIds = snapshot + .filter((m) => !removed.has(m.id)) + .map((m) => m.id); const repairedReferrers: string[] = []; let removedCount = 0; - for (const memory of memories) { - if (removed.has(memory.id)) continue; - const { memory: next, changed, removed: dropped } = - stripMemoryReferences(memory, removed); - if (changed) { + for (const id of candidateIds) { + const droppedHere = await withKeyedLock(`mem:memory:${id}`, async () => { + const fresh = await kv.get(KV.memories, id); + if (!fresh) return 0; + const { memory: next, changed, removed: dropped } = + stripMemoryReferences(fresh, removed); + if (!changed) return 0; next.updatedAt = new Date().toISOString(); await kv.set(KV.memories, next.id, next); - repairedReferrers.push(next.id); - removedCount += dropped.length; + return dropped.length; + }); + if (droppedHere > 0) { + repairedReferrers.push(id); + removedCount += droppedHere; } } return { repairedReferrers, removedCount }; diff --git a/test/diagnostics.test.ts b/test/diagnostics.test.ts index a5ce8b0684..99eaeb804c 100644 --- a/test/diagnostics.test.ts +++ b/test/diagnostics.test.ts @@ -314,6 +314,50 @@ describe("Diagnostics Functions", () => { expect(check!.fixable).toBe(true); }); + it("explicit human/approval/blockedReason gates are not flagged as blocked-deps-done", async () => { + // Each blocked action has all requires-deps done BUT also carries an + // explicit non-dependency gate. None should be reported as a fixable + // blocked-deps-done defect (they are intentionally blocked). + const dep = makeAction({ status: "done" }); + const humanGated = makeAction({ + status: "blocked", + title: "Human-gated", + awaitingHuman: true, + }); + const approvalGated = makeAction({ + status: "blocked", + title: "Approval-gated", + approval: { state: "pending" }, + }); + const reasonGated = makeAction({ + status: "blocked", + title: "Reason-gated", + blockedReason: "Waiting on a manual merge gate", + }); + for (const a of [humanGated, approvalGated, reasonGated]) { + await kv.set(KV.actions, a.id, a); + await kv.set( + KV.actionEdges, + `edge_${a.id}`, + makeEdge({ + sourceActionId: a.id, + targetActionId: dep.id, + type: "requires", + }), + ); + } + await kv.set(KV.actions, dep.id, dep); + + const result = (await sdk.trigger("mem::diagnose", { + categories: ["actions"], + })) as { checks: DiagnosticCheck[] }; + + const flagged = result.checks.filter((c) => + c.name.startsWith("blocked-deps-done:"), + ); + expect(flagged).toEqual([]); + }); + it("pending action with unsatisfied deps produces fail (fixable)", async () => { const dep = makeAction({ status: "active" }); const pending = makeAction({ status: "pending" }); @@ -563,6 +607,9 @@ describe("Diagnostics Functions", () => { expect(check!.message).toContain("no session-linked unscoped memories remain"); expect(check!.message).toContain("infer-memory-projects is a no-op here"); expect(check!.message).toContain("need manual project assignment"); + // Zero inferable candidates => the migration is a no-op, so the finding + // must NOT claim to be fixable by an automated heal/migrate step. + expect(check!.fixable).toBe(false); }); it("project-coverage message distinguishes inferable from ambiguous unscoped memories", async () => { @@ -593,6 +640,9 @@ describe("Diagnostics Functions", () => { expect(check!.message).toContain("attempt backfill of the 1 session-linked"); // ...and the session-less count (1) is flagged as needing manual work. expect(check!.message).toContain("remaining 1 have no sessionIds"); + // At least one inferable candidate => the migration can do something, so + // the finding is honestly fixable. + expect(check!.fixable).toBe(true); }); it("stale mesh peer produces warn", async () => { @@ -674,6 +724,40 @@ describe("Diagnostics Functions", () => { expect(updated!.status).toBe("pending"); }); + it("does not unblock an action held by an explicit non-dependency gate", async () => { + // Same shape as "unblocks stuck blocked action" but the blocked action + // also carries awaitingHuman + a pending approval. Heal must leave it + // blocked (skipped), not mint a misleading unblock. + const dep = makeAction({ status: "done" }); + const gated = makeAction({ + status: "blocked", + title: "Approval-gated task", + awaitingHuman: true, + approval: { state: "pending" }, + }); + const edge = makeEdge({ + sourceActionId: gated.id, + targetActionId: dep.id, + type: "requires", + }); + await kv.set(KV.actions, dep.id, dep); + await kv.set(KV.actions, gated.id, gated); + await kv.set(KV.actionEdges, edge.id, edge); + + const result = (await sdk.trigger("mem::heal", { + categories: ["actions"], + })) as { success: boolean; fixed: number; skipped: number; details: string[] }; + + expect(result.success).toBe(true); + expect(result.fixed).toBe(0); + expect(result.skipped).toBe(1); + expect(result.details.some((d) => d.includes("Unblocked"))).toBe(false); + + const unchanged = await kv.get(KV.actions, gated.id); + expect(unchanged!.status).toBe("blocked"); + expect(unchanged!.awaitingHuman).toBe(true); + }); + it("blocks pending action with unsatisfied deps", async () => { const dep = makeAction({ status: "active" }); const pending = makeAction({ diff --git a/test/governance.test.ts b/test/governance.test.ts index ad4157c92b..e173eb6d13 100644 --- a/test/governance.test.ts +++ b/test/governance.test.ts @@ -533,3 +533,120 @@ describe("Governance Functions", () => { ]); }); }); + +describe("clearDanglingMemoryReferences concurrency safety (#fresh-read-under-lock)", () => { + // The fresh-read-under-keyed-lock fix prevents a stale snapshot from + // clobbering a concurrent survivor update. This test injects a concurrent + // write between the initial list snapshot and the per-memory fresh read, and + // asserts the concurrent addition survives (it would be lost if the function + // wrote back the stale snapshot). It fails on the pre-fix scan-then-write + // implementation and passes once each survivor is re-read inside its lock. + it("preserves a concurrent survivor update made after the snapshot", async () => { + const base = mockKV(); + const target = makeMemory("mem_target", "pattern"); + const alive = makeMemory("mem_alive", "bug"); + const holder = makeMemory("mem_holder", "fact"); + holder.supersedes = ["mem_target", "mem_alive"]; + const concurrent = makeMemory("mem_concurrent", "fact"); + for (const m of [target, alive, holder, concurrent]) { + await base.set("mem:memories", m.id, m); + } + + // Simulate a concurrent writer that appends mem_concurrent to holder's + // supersedes after the list snapshot is taken but before the per-memory + // fresh read. We inject on holder's first get (which, post-fix, happens + // inside the per-memory keyed lock). The pre-fix code never re-read the + // holder, so it would write the stale snapshot back and lose this addition. + let injected = false; + const wrapped = { + get: async (scope: string, key: string) => { + const v = await base.get(scope, key); + if ( + !injected && + scope === "mem:memories" && + key === "mem_holder" && + v + ) { + injected = true; + const mem = { ...(v as Memory) }; + mem.supersedes = [...(mem.supersedes ?? []), "mem_concurrent"]; + await base.set("mem:memories", "mem_holder", mem); + return mem; + } + return v; + }, + set: (scope: string, key: string, data: unknown) => + base.set(scope, key, data), + delete: (scope: string, key: string) => base.delete(scope, key), + list: (scope: string) => base.list(scope), + }; + + const sdk = mockSdk(); + registerGovernanceFunction(sdk as never, wrapped as never); + + const result = (await sdk.trigger("mem::governance-delete", { + memoryIds: ["mem_target"], + })) as { success: boolean; repairedReferrers: string[] }; + + expect(result.success).toBe(true); + expect(result.repairedReferrers).toEqual(["mem_holder"]); + + const holderAfter = (await base.get("mem:memories", "mem_holder")) as Memory; + // The deleted reference is pruned, AND the concurrent writer's addition is + // preserved — proving the write was based on a fresh read, not the snapshot. + expect(holderAfter.supersedes).toEqual(["mem_alive", "mem_concurrent"]); + expect(holderAfter.supersedes).not.toContain("mem_target"); + }); + + it("does not clobber a survivor that lost its dangling ref before the write", async () => { + // If a survivor is concurrently corrected between the list snapshot and + // the fresh read, the fresh read sees the corrected state and the function + // writes nothing (changed=false), avoiding a redundant/regressive write. + const base = mockKV(); + const target = makeMemory("mem_target", "pattern"); + const holder = makeMemory("mem_holder", "fact"); + holder.supersedes = ["mem_target"]; + await base.set("mem:memories", target.id, target); + await base.set("mem:memories", holder.id, holder); + + let injected = false; + const wrapped = { + get: async (scope: string, key: string) => { + const v = await base.get(scope, key); + if ( + !injected && + scope === "mem:memories" && + key === "mem_holder" && + v + ) { + injected = true; + // Concurrent writer already removed the dangling ref. + const mem = { ...(v as Memory), supersedes: [] }; + await base.set("mem:memories", "mem_holder", mem); + return mem; + } + return v; + }, + set: (scope: string, key: string, data: unknown) => + base.set(scope, key, data), + delete: (scope: string, key: string) => base.delete(scope, key), + list: (scope: string) => base.list(scope), + }; + + const sdk = mockSdk(); + registerGovernanceFunction(sdk as never, wrapped as never); + + const result = (await sdk.trigger("mem::governance-delete", { + memoryIds: ["mem_target"], + })) as { success: boolean; repairedReferrers: string[]; removedReferences: number }; + + expect(result.success).toBe(true); + // Nothing to repair: the concurrent correction already cleared the ref, and + // the fresh read saw it — so no write, no reported repair. + expect(result.repairedReferrers).toEqual([]); + expect(result.removedReferences).toBe(0); + + const holderAfter = (await base.get("mem:memories", "mem_holder")) as Memory; + expect(holderAfter.supersedes ?? []).toEqual([]); + }); +}); From abfc83ea64255140f50f489522f822ef24b82956 Mon Sep 17 00:00:00 2001 From: pi Date: Wed, 5 Aug 2026 19:54:10 -0400 Subject: [PATCH 43/43] fix(lessons): allow implicit worktree scope for legacy prose saves The causal schema foundation (495b051) tightened scope validation but the three write entry points (mem::lesson-save, api::lesson-save REST, and the memory_lesson_save MCP handler) parse input without allowImplicitWorktreeScope, so every scope-less legacy prose save fails with 'scope.scopeId is required for non-global explicit scopes'. The causal-lesson-schema-v1 spec mandates: 'Legacy prose lessons retain the fail-closed implicit worktree scope for compatibility' and 'Legacy prose-only saves remain valid'. Restore the spec behavior at all three entry points. Structured causal lessons still require an explicit durable scope (that guard is independent in parseLessonSaveInput and is now regression-tested). No change to global scope humanApproval, access enforcement, or FORCE_PROXY semantics. --- src/functions/lessons.ts | 8 ++++- src/mcp/server.ts | 4 +++ src/triggers/api.ts | 4 +++ test/causal-lessons-api.test.ts | 64 +++++++++++++++++++++++++++++++++ 4 files changed, 79 insertions(+), 1 deletion(-) diff --git a/src/functions/lessons.ts b/src/functions/lessons.ts index 944ba420fe..6ee5509b43 100644 --- a/src/functions/lessons.ts +++ b/src/functions/lessons.ts @@ -334,7 +334,13 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { ); const prepared = bindResolvedLessonWriteIdentity(data, accessContext); if (!prepared.success) return prepared; - const parsed = parseLessonSaveInput(prepared.value); + // Legacy prose saves keep the fail-closed implicit worktree scope + // (causal-lesson-schema-v1 spec: "Legacy prose lessons retain the + // fail-closed implicit worktree scope for compatibility"). Structured + // causal lessons still require an explicit durable scope below. + const parsed = parseLessonSaveInput(prepared.value, { + allowImplicitWorktreeScope: true, + }); if (!parsed.success) { return correctionFailure("invalid_request", parsed.error); } diff --git a/src/mcp/server.ts b/src/mcp/server.ts index 4551d69666..dc712bba8e 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -1386,6 +1386,10 @@ export function registerMcpEndpoints( const parsed = parseLessonSaveInput(prepared.value, { source: "manual", allowSourceMetadata: false, + // Legacy prose saves keep the fail-closed implicit worktree + // scope per causal-lesson-schema-v1; structured causal saves + // still require an explicit durable scope. + allowImplicitWorktreeScope: true, }); if (!parsed.success) { return { diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 9a62207bf9..bdc0640efc 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -3728,6 +3728,10 @@ export function registerApiTriggers( const parsed = parseLessonSaveInput(prepared.value, { source: "manual", allowSourceMetadata: false, + // Legacy prose saves keep the fail-closed implicit worktree scope per + // causal-lesson-schema-v1; structured causal saves still require an + // explicit durable scope. + allowImplicitWorktreeScope: true, }); if (!parsed.success) { return { status_code: 400, body: { error: parsed.error } }; diff --git a/test/causal-lessons-api.test.ts b/test/causal-lessons-api.test.ts index 0c0db0e00f..3665c30426 100644 --- a/test/causal-lessons-api.test.ts +++ b/test/causal-lessons-api.test.ts @@ -160,6 +160,70 @@ describe("causal lesson REST and MCP boundaries", () => { expect(tool?.inputSchema.properties).toHaveProperty("sensitivity"); }); + it("keeps legacy prose saves valid without a scope at both boundaries (implicit worktree scope)", async () => { + const mcp = (await sdk.trigger("mcp::tools::call", { + headers: {}, + body: { + name: "memory_lesson_save", + arguments: { + content: "Legacy prose lesson without explicit scope", + project: "agentmemory", + tags: "legacy,compat", + confidence: 0.4, + }, + }, + })) as { + status_code: number; + body: { error?: string; content?: Array<{ text: string }> }; + }; + expect(mcp.status_code).toBe(200); + const mcpResult = JSON.parse(mcp.body.content![0].text) as { + lesson: Lesson; + }; + expect(mcpResult.lesson.scope).toMatchObject({ ring: "worktree" }); + expect(mcpResult.lesson.scope.scopeId).toBeUndefined(); + + const rest = (await sdk.trigger("api::lesson-save", { + headers: {}, + body: { + content: "Legacy prose REST lesson without explicit scope", + project: "agentmemory", + tags: ["legacy", "compat"], + }, + })) as { status_code: number; body: { lesson?: Lesson; error?: string } }; + expect(rest.status_code).toBe(201); + expect(rest.body.lesson?.scope).toMatchObject({ ring: "worktree" }); + }); + + it("still rejects structured causal saves that omit an explicit scope", async () => { + const mcp = (await sdk.trigger("mcp::tools::call", { + headers: {}, + body: { + name: "memory_lesson_save", + arguments: { + content: "Structured lesson missing scope", + mechanismId: "scope/guard", + claim: "Structured lessons require explicit durable scope.", + claimType: "causal", + }, + }, + })) as { status_code: number; body: { error?: string } }; + expect(mcp.status_code).toBe(400); + expect(mcp.body.error).toContain("explicit durable scope"); + + const rest = (await sdk.trigger("api::lesson-save", { + headers: {}, + body: { + content: "Structured lesson missing scope", + mechanismId: "scope/guard-rest", + claim: "Structured lessons require explicit durable scope.", + claimType: "causal", + }, + })) as { status_code: number; body: { error?: string } }; + expect(rest.status_code).toBe(400); + expect(rest.body.error).toContain("explicit durable scope"); + }); + it("rejects invalid immutable evidence and unapproved global scope at both boundaries", async () => { const rest = (await sdk.trigger("api::lesson-save", { headers: {},