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/.env.example b/.env.example index 77ca0f3a38..5ef8294fdb 100644 --- a/.env.example +++ b/.env.example @@ -89,6 +89,24 @@ # 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 +# 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. +# AGENTMEMORY_VIEWER_AGENT_ID=viewer-service +# AGENTMEMORY_VIEWER_CALLER_TOKEN=unique-viewer-token + # ----------------------------------------------------------------------------- # 4. Search tuning # ----------------------------------------------------------------------------- @@ -106,6 +124,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 @@ -119,7 +138,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 + 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) @@ -127,6 +146,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/.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 diff --git a/AGENTS.md b/AGENTS.md index 873ef10fc1..6d0a5225b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,12 +5,22 @@ 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) -## 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 @@ -57,6 +67,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) => { @@ -94,7 +112,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` 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 @@ -114,10 +133,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 +- 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/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/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..25dae4437e 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@

95.2% retrieval R@5 92% fewer tokens - 53 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 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 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 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 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 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 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 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 60 memory tools: mcp_servers: agentmemory: @@ -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 | |---|---|---| @@ -959,11 +961,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. +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 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|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`. -### 53 Tools +### 60 Tools
Core tools (always available) @@ -985,7 +987,7 @@ npm install @xenova/transformers
-Extended tools (53 total — set AGENTMEMORY_TOOLS=all) +Extended tools (60 total — set AGENTMEMORY_TOOLS=all) | Tool | Description | |------|-------------| @@ -1002,6 +1004,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) | @@ -1016,6 +1019,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 | @@ -1067,6 +1074,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 { @@ -1172,6 +1201,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 +1228,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 | @@ -1439,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 @@ -1482,7 +1522,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 @@ -1493,31 +1533,192 @@ 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), +# "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 +``` + +### 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 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 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. 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 +`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. +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. + +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. `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 +`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, 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 +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. 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 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. +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. + +`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, 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. + ---

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. +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 | 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 | +| `POST` | `/agentmemory/observe` | Capture observation synchronously | +| `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 | | `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 | +| `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/assets/tags/light/stat-tools.svg b/assets/tags/light/stat-tools.svg index e6d598532f..0beaf179fa 100644 --- a/assets/tags/light/stat-tools.svg +++ b/assets/tags/light/stat-tools.svg @@ -1,5 +1,5 @@ - + - 53 + 60 MCP TOOLS diff --git a/assets/tags/stat-tools.svg b/assets/tags/stat-tools.svg index 2f38d7a109..136a4ecc53 100644 --- a/assets/tags/stat-tools.svg +++ b/assets/tags/stat-tools.svg @@ -1,5 +1,5 @@ - + - 53 + 60 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..459a5b08ba --- /dev/null +++ b/docs/superpowers/specs/2026-07-17-actions-v2-design.md @@ -0,0 +1,409 @@ +# 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. 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 + 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. + +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. + +## 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. + +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. + +## 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/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..17771fe5cc --- /dev/null +++ b/docs/superpowers/specs/2026-08-02-causal-lesson-schema-v1.md @@ -0,0 +1,287 @@ +# 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` +- `identityKind: "legacy-prose"` and a canonical `lsn_*` alias +- `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. +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 + +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. + +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: + +| 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. 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: + +- `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 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 +dimensions and 16 values per dimension. + +## Durable evidence references + +`evidenceRefs` contains at most eight records. Each reference requires: + +- `kind` +- `projectId` as a label +- discriminated `provenance` +- explicit `verification` +- `recordedAt` + +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. 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. + +## 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`; 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. + +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: + +```json +{ + "ring": "global", + "humanApproval": { + "approvedBy": "human identity", + "approvedAt": "ISO-8601 timestamp", + "reason": "approval rationale" + } +} +``` + +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`. + +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 + +`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. +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 +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, 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. + +## 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 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. + +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 +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/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..fa9855a03e --- /dev/null +++ b/docs/superpowers/specs/2026-08-03-causal-lesson-access-v2.md @@ -0,0 +1,147 @@ +# 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` and must be absolute. +Unknown mode values and relative policy paths fail closed. + +## 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": [] + } + ] +} +``` + +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. +`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 + +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, 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 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 +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, 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 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. + +## 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/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/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/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 332189d7e3..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) { @@ -110,17 +110,23 @@ 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), ); 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; + if (callerToken) { + headers["X-AgentMemory-Caller-Token"] = callerToken; + } try { const res = await fetch(`${baseUrl}${path}`, { method: "POST", 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 9c6cfc7024..0c4f6f7db5 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; - guardPlaintextBearerAuth(baseUrl, secret); + const agentId = process.env.AGENT_ID; + const callerToken = process.env.AGENTMEMORY_CALLER_TOKEN; + 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; + if (callerToken) headers["X-AgentMemory-Caller-Token"] = callerToken; try { const response = await fetch(url, { @@ -116,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/package.json b/package.json index 4e2bc8c4c3..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": { @@ -18,6 +19,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", @@ -60,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/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index cb4e6df7b8..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, 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, 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 7c42f13094..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, 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, 60 MCP tools, 8 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" 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/README.md b/plugin/opencode/README.md index 60f5e5bb94..8c3fe582f8 100644 --- a/plugin/opencode/README.md +++ b/plugin/opencode/README.md @@ -9,7 +9,7 @@

- 53 MCP tools + 60 MCP tools 22 hooks 2 slash commands 95.2% R@5 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/plugin.json b/plugin/plugin.json index 9d0751a7ab..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, 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, 60 MCP tools, 15 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" diff --git a/plugin/scripts/notification.mjs b/plugin/scripts/notification.mjs index 3967158c92..0084ea1db9 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, realpathSync } 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,116 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); + } catch { + return ""; + } +} +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} +function nearestProjectFile(cwd, boundary) { + 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 || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; + } +} +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/_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 {} - return basename(dir); } - //#endregion //#region src/hooks/notification.ts function isSdkChildContext(payload) { @@ -29,13 +131,6 @@ function isSdkChildContext(payload) { 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; @@ -49,28 +144,20 @@ 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"; - fetch(`${REST_URL}/agentmemory/observe`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "notification", - sessionId, - project: resolveProject(data.cwd), - cwd: data.cwd || process.cwd(), - 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 -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..640c782c38 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, realpathSync } 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,116 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); + } catch { + return ""; + } +} +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} +function nearestProjectFile(cwd, boundary) { + 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 || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; + } +} +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/_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 {} - return basename(dir); } - //#endregion //#region src/hooks/post-tool-failure.ts function isSdkChildContext(payload) { @@ -29,13 +131,6 @@ function isSdkChildContext(payload) { 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; @@ -49,29 +144,23 @@ 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; - 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(), - 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 -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..b602c97a5a 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, realpathSync } 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,116 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); + } catch { + return ""; + } +} +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} +function nearestProjectFile(cwd, boundary) { + 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 || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; + } +} +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/_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 {} - return basename(dir); } - //#endregion //#region src/hooks/post-tool-use.ts function isSdkChildContext(payload) { @@ -29,13 +131,6 @@ function isSdkChildContext(payload) { 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; @@ -49,26 +144,33 @@ 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", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "post_tool_use", - sessionId, - project: resolveProject(data.cwd), - cwd: data.cwd || process.cwd(), - timestamp: (/* @__PURE__ */ new Date()).toISOString(), - data: { - tool_name: toolName, - tool_input: toolInput, - tool_output: truncate(cleanOutput, 8e3), - ...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() : ""; + 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; @@ -116,7 +218,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..bde2fbe9fe 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, realpathSync } 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,93 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); - } catch {} - return basename(dir); + } catch { + return ""; + } +} +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} +function nearestProjectFile(cwd, boundary) { + 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 || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; + } +} +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) { @@ -31,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() { @@ -74,7 +157,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..1a831dd6c2 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, realpathSync } 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,116 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); + } catch { + return ""; + } +} +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} +function nearestProjectFile(cwd, boundary) { + 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 || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; + } +} +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/_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 {} - return basename(dir); } - //#endregion //#region src/hooks/prompt-submit.ts function isSdkChildContext(payload) { @@ -29,13 +131,6 @@ function isSdkChildContext(payload) { 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; @@ -47,23 +142,29 @@ async function main() { } if (isSdkChildContext(data)) return; const sessionId = data.session_id || data.sessionId || "unknown"; - 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(), - timestamp: (/* @__PURE__ */ new Date()).toISOString(), - data: { prompt: data.prompt ?? data.userPrompt } - }), - signal: AbortSignal.timeout(3e3) - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + const context = resolveProjectContext(data.cwd); + const promptData = promptCapture(data.prompt ?? data.userPrompt); + await submitObservation({ + hookType: "prompt_submit", + sessionId, + ...context, + timestamp: (/* @__PURE__ */ new Date()).toISOString(), + data: promptData + }); +} +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..b6dd890682 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, realpathSync } 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,90 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); - } catch {} - return basename(dir); + } catch { + return ""; + } +} +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} +function nearestProjectFile(cwd, boundary) { + 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 || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; + } +} +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) { @@ -32,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() { @@ -50,16 +130,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 +159,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..9dab7f9d29 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, realpathSync } 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,116 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); + } catch { + return ""; + } +} +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} +function nearestProjectFile(cwd, boundary) { + 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 || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; + } +} +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/_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 {} - return basename(dir); } - //#endregion //#region src/hooks/subagent-start.ts function isSdkChildContext(payload) { @@ -29,14 +131,6 @@ function isSdkChildContext(payload) { 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; @@ -50,26 +144,19 @@ 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; - 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(), - 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 -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..d002786abf 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, realpathSync } 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,116 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); + } catch { + return ""; + } +} +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} +function nearestProjectFile(cwd, boundary) { + 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 || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; + } +} +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/_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 {} - return basename(dir); } - //#endregion //#region src/hooks/subagent-stop.ts function isSdkChildContext(payload) { @@ -29,13 +131,6 @@ function isSdkChildContext(payload) { 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; @@ -50,27 +145,20 @@ 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) : ""; - 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(), - 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 -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..d1f1e6048a 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, realpathSync } 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,116 @@ function resolveProject(cwd) { ], timeout: 500 }).toString().trim(); - if (top) return basename(top); + } catch { + return ""; + } +} +function canonicalExistingPath(path) { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} +function nearestProjectFile(cwd, boundary) { + 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 || current === filesystemRoot) return void 0; + const parent = dirname(current); + if (parent === current) return void 0; + current = parent; + } +} +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/_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 {} - return basename(dir); } - //#endregion //#region src/hooks/task-completed.ts function isSdkChildContext(payload) { @@ -29,13 +131,6 @@ function isSdkChildContext(payload) { 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; @@ -46,30 +141,22 @@ async function main() { return; } if (isSdkChildContext(data)) return; - const sessionId = data.session_id || "unknown"; - 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(), - 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 -export { }; +export {}; + //# sourceMappingURL=task-completed.mjs.map \ No newline at end of file diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md index 08c873a444..53eaf06a9e 100644 --- a/plugin/skills/agentmemory-config/REFERENCE.md +++ b/plugin/skills/agentmemory-config/REFERENCE.md @@ -3,40 +3,66 @@ 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). 60 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` - `AGENTMEMORY_CWD` - `AGENTMEMORY_DEBUG` +- `AGENTMEMORY_DISABLED_TOOLS` +- `AGENTMEMORY_DISABLE_LLM_TOOLS` - `AGENTMEMORY_DROP_STALE_INDEX` - `AGENTMEMORY_EXPORT_ROOT` - `AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS` - `AGENTMEMORY_FORCE_PROXY` - `AGENTMEMORY_GRAPH_WEIGHT` +- `AGENTMEMORY_HOOK_ACK_TIMEOUT_MS` - `AGENTMEMORY_III_CONFIG` - `AGENTMEMORY_III_VERSION` - `AGENTMEMORY_IMAGE_EMBEDDINGS` - `AGENTMEMORY_IMAGE_STORE_MAX_BYTES` - `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` +- `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` - `AGENTMEMORY_REFLECT` +- `AGENTMEMORY_REPO_ROOT` +- `AGENTMEMORY_REQUIRE_HTTPS` +- `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` - `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 0c556fc77f..9ed4026d25 100644 --- a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md +++ b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md @@ -3,46 +3,53 @@ 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 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 | | --- | --- | --- | --- | -| `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. | | `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. | +| `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. 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. | +| `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. | | `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_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_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`: 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. | | `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. | -| `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..64ef269ec8 100644 --- a/plugin/skills/agentmemory-rest-api/REFERENCE.md +++ b/plugin/skills/agentmemory-rest-api/REFERENCE.md @@ -5,13 +5,15 @@ 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: +124 registered endpoints: | Method | Path | | --- | --- | | POST | `/agentmemory/actions` | | 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` | @@ -36,6 +38,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` | @@ -66,7 +69,9 @@ 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` | | GET | `/agentmemory/memories/:id` | | GET | `/agentmemory/mesh/export` | @@ -77,6 +82,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 +104,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/cli.ts b/src/cli.ts index 93b907491d..2d13eab11d 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) @@ -190,7 +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 Tool visibility (default: all = ${ALL_TOOLS_COUNT} tools; core = ${CORE_TOOLS_COUNT} essentials) + --tools all|core|workstation|workstation-llm + Tool visibility (default: all = ${ALL_TOOLS_COUNT}; core = ${CORE_TOOLS_COUNT}; + 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 @@ -202,6 +205,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}). @@ -216,6 +222,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); @@ -224,12 +231,17 @@ 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", "workstation-llm"].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, workstation-llm, 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"); @@ -1197,6 +1209,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 @@ -1397,7 +1430,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 +1444,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"; @@ -2004,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, @@ -2012,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), }); @@ -2030,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), }); @@ -2072,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), }); @@ -2649,6 +2697,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)); @@ -2725,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(); @@ -2982,6 +3033,7 @@ const commands: Record Promise> = { stop: runStop, remove: runRemove, mcp: runMcp, + "mcp-http": runMcpHttp, "import-jsonl": runImportJsonl, }; 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/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/action-model.ts b/src/functions/action-model.ts new file mode 100644 index 0000000000..8f410a7d6b --- /dev/null +++ b/src/functions/action-model.ts @@ -0,0 +1,790 @@ +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; + index?: ActionViewIndex; +} + +export interface ActionViewIndex { + actionMap: Map; + edgesByActionId: Map; + checkpointMap: Map; + sentinelMap: Map; + activeLeaseMap: Map; +} + +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"); + const validTagProjectIds = tagProjectIds.filter(isCanonicalProjectId); + const invalidTagProjectIds = tagProjectIds.filter( + (value) => !isCanonicalProjectId(value), + ); + + 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 (!projectId && legacyProject && !isProjectPath(legacyProject)) { + if (isCanonicalProjectId(legacyProject)) { + projectId = legacyProject; + } else { + 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) + ? 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; + } + } + + 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, + ), + ); + 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: 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, +): ActionViewItem { + const now = context.now ?? Date.now(); + 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; + 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 = index.activeLeaseMap.get(action.id); + 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 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[], + 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..3750e5dda0 --- /dev/null +++ b/src/functions/action-query.ts @@ -0,0 +1,191 @@ +import type { + Action, + ActionReadinessView, + ActionViewItem, + Checkpoint, + Lease, + Sentinel, +} from "../types.js"; +import { + actionFilterFingerprint, + buildActionViewIndex, + 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 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, { + ...viewContext, + index, + }), + ) + .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..2d477c4161 --- /dev/null +++ b/src/functions/action-store.ts @@ -0,0 +1,448 @@ +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"; +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 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); +} + +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 current = await kv.get(KV.actions, input.id); + const candidate = + options.before === undefined + ? 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(candidate, { + 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); +} + +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 new file mode 100644 index 0000000000..a685c967b1 --- /dev/null +++ b/src/functions/actions-v2-migration.ts @@ -0,0 +1,281 @@ +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 unresolvedDerivedActionIds = collectUnresolvedDerivedActionIds( + actions, + edges, + checkpoints, + sentinels, + ); + const candidates: MigrationCandidate[] = page.map((action) => { + const hasDerivedBlockers = unresolvedDerivedActionIds.has(action.id); + 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 collectUnresolvedDerivedActionIds( + 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 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 12d12df39b..72980051fb 100644 --- a/src/functions/actions.ts +++ b/src/functions/actions.ts @@ -1,46 +1,120 @@ 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, + ActionRevisionConflictError, + deleteAction, + 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", +]); +const MAX_ACTION_GRAPH_ACTIONS = 5_000; - 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 +122,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" }; - } + sdk.registerFunction("mem::action-update", async (data: ActionUpdateInput) => { + const validationError = validateUpdateInput(data); + if (validationError) return { success: false, error: validationError }; - 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 }; - - 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,141 +293,699 @@ 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, + sdk.registerFunction("mem::action-list", async (data: ActionListOptions) => { + if (data.view !== undefined && !isActionReadinessView(data.view)) { + return { + success: false, + error: "view must be actionable, scheduled, waiting, blocked, completed, or cancelled", }; + } + 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); + } + }); - 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-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-list", + 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, + }; + }); + + sdk.registerFunction( + "mem::action-gc", async (data: { - status?: string; - project?: string; - parentId?: string; - tags?: string[]; + maxAgeDays?: number; + dryRun?: boolean; limit?: number; + actor?: string; }) => { - let actions = await kv.list(KV.actions); - - if (data.status) { - actions = actions.filter((a) => a.status === data.status); + 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 (data.project) { - actions = actions.filter((a) => a.project === data.project); + if (typeof dryRun !== "boolean") { + return { success: false, error: "dryRun must be a boolean" }; } - if (data.parentId) { - actions = actions.filter((a) => a.parentId === data.parentId); + if (!Number.isInteger(limit) || limit < 1 || limit > 5000) { + return { success: false, error: "limit must be an integer between 1 and 5000" }; } - if (data.tags && data.tags.length > 0) { - actions = actions.filter((a) => - data.tags!.some((t) => a.tags.includes(t)), + 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( + 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`, + }); + } +} + +export async function propagateActionCompletion( + kv: StateKV, + completedActionId: string, + actor: string, +): Promise { + await withActionStoreLock(async () => { + await recoverActionStoreUnlocked(kv); + await propagateCompletionUnlocked(kv, completedActionId, actor); + }); +} - actions.sort( - (a, b) => - new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(), +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 limit = data.limit || 50; - return { success: true, actions: actions.slice(0, limit) }; - }, +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); +} + +/** + * 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; +} - sdk.registerFunction("mem::action-get", - async (data: { actionId: string }) => { - if (!data.actionId) { - return { success: false, error: "actionId is required" }; +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`; } - const action = await kv.get(KV.actions, data.actionId); - if (!action) { - return { success: false, error: "action not found" }; + } + 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; +} - const allEdges = await kv.list(KV.actionEdges); - const edges = allEdges.filter( - (e) => - e.sourceActionId === data.actionId || - e.targetActionId === data.actionId, - ); +function normalizePriority(value?: number): number { + return Math.max(1, Math.min(10, value || 5)); +} - const children = (await kv.list(KV.actions)).filter( - (a) => a.parentId === data.actionId, - ); +function isValidEdgeType(value: string): value is ActionEdge["type"] { + return VALID_EDGE_TYPES.includes(value as ActionEdge["type"]); +} - return { success: true, action, edges, children }; - }, +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) ); } -async function propagateCompletion( - kv: StateKV, - completedActionId: string, -): Promise { - const allEdges = await kv.list(KV.actionEdges); - const unlockEdges = allEdges.filter( - (e) => - e.targetActionId === completedActionId && - (e.type === "requires" || e.type === "unlocks"), +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) ); +} - const allActions = await kv.list(KV.actions); - const actionMap = new Map(allActions.map((a) => [a.id, a])); +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, + }; +} - 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 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 { + success: false, + error: "action_revision_conflict", + actionId: error.actionId, + fields: error.fields, + message: error.message, + }; } + 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/audit.ts b/src/functions/audit.ts index 1e75b4b7d2..7a88f46096 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,121 @@ 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) => { + const referencedIds = lessonAuditReferenceIds(entry); + if (referencedIds.length === 0) return false; + try { + return referencedIds.every((id) => { + 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); } + +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", + "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/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/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/src/functions/compress.ts b/src/functions/compress.ts index 0569555e06..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 { @@ -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"; @@ -215,7 +242,6 @@ export function registerCompressFunction( sessionId: data.sessionId, }, }, - action: TriggerAction.Void(), }), ]); for (const result of streamResults) { diff --git a/src/functions/consolidation-pipeline.ts b/src/functions/consolidation-pipeline.ts index e51ab97c86..d246af3523 100644 --- a/src/functions/consolidation-pipeline.ts +++ b/src/functions/consolidation-pipeline.ts @@ -17,6 +17,10 @@ import { import { recordAudit } from "./audit.js"; import { getConsolidationDecayDays, isConsolidationEnabled } from "../config.js"; import { logger } from "../logger.js"; +import { + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; function applyDecay( items: Array<{ @@ -48,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 = {}; @@ -138,6 +150,7 @@ export function registerConsolidationPipelineFunction( const reflectResult = await sdk.trigger({ function_id: "mem::reflect", payload: { maxClusters: 10, project: data?.project, + accessContext, } }); results.reflect = reflectResult; } catch (err) { @@ -249,7 +262,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 }, + }); 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 1e6102cf37..aee2c7fd55 100644 --- a/src/functions/context.ts +++ b/src/functions/context.ts @@ -17,6 +17,15 @@ import { listPinnedSlots, renderPinnedContext, } from "./slots.js"; +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); @@ -36,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() @@ -103,7 +118,13 @@ 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) && + canReadLesson(lesson, accessContext) && + (!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 +134,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/crystallize.ts b/src/functions/crystallize.ts index 1f0b84316d..bcde792870 100644 --- a/src/functions/crystallize.ts +++ b/src/functions/crystallize.ts @@ -1,7 +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 { + buildLessonAccessIndex, + canReadCrystal, + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; interface CrystalDigest { narrative: string; @@ -25,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" }; @@ -52,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, @@ -71,28 +120,13 @@ 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], - }, - }) - .catch(() => {}), - ), - ); - 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 }; @@ -110,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); @@ -131,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" }; } @@ -140,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 }; }, @@ -150,6 +227,7 @@ export function registerCrystallizeFunction( olderThanDays?: number; project?: string; dryRun?: boolean; + accessContext?: LessonAccessContext; }) => { const olderThanDays = data.olderThanDays ?? 7; const dryRun = data.dryRun ?? false; @@ -209,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 cc982883f6..a707c76504 100644 --- a/src/functions/diagnostics.ts +++ b/src/functions/diagnostics.ts @@ -3,6 +3,18 @@ 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 { hasExplicitNonDependencyGate } from "./actions.js"; +import { stripMemoryReferences } from "../state/memory-utils.js"; +import { isLessonListable } from "./lesson-model.js"; +import { + canReadLesson, + lessonAccessContextFromPayload, +} from "./lesson-access.js"; import type { Action, ActionEdge, @@ -45,7 +57,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; @@ -88,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, + }); + } } } } @@ -333,13 +358,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) { @@ -356,11 +412,35 @@ 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` + : ""; + // 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", @@ -374,16 +454,16 @@ 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`, - fixable: true, + message: `${unscopedCount} of ${latestMemories.length} latest memories have no project scope — ${inferHint}${ambiguousHint}`, + fixable: coverageFixable, }); } else { checks.push({ 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`, - fixable: true, + message: `${unscopedCount} of ${latestMemories.length} latest memories have no project scope — ${inferHint}${ambiguousHint}`, + fixable: coverageFixable, }); } @@ -399,12 +479,75 @@ 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); - const live = lessons.filter((l) => !l.deleted); - let lessonIssues = 0; + 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 readableLessonCount = 0; + let lessonIssues = lessonStateUnavailable ? 1 : 0; + let projectionIncomplete = false; + for (const lesson of lessons) { + try { + 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", + status: "fail", + message: `Lesson ${lesson.id} has invalid structured data: ${ + error instanceof Error ? error.message : String(error) + }`, + fixable: false, + }); + 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 < / > @@ -431,7 +574,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, }); } @@ -685,9 +828,24 @@ 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"; 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 +902,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,15 +976,33 @@ 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", 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; }, @@ -941,7 +1124,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 +1136,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", @@ -1055,6 +1244,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/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/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 327117b265..7ee0031f87 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, @@ -12,6 +13,8 @@ import type { ProceduralMemory, Action, ActionEdge, + ActionCollectionState, + ActionEvent, Routine, Signal, Checkpoint, @@ -30,10 +33,84 @@ 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"; +import { + isLessonRecallable, + normalizeLesson, + parseImportedLesson, + sameLessonContradictionScope, + sameLessonScope, +} from "./lesson-model.js"; +import { withLessonMutationLock } from "./lesson-locks.js"; +import { + bindResolvedLessonWriteIdentity, + buildCrystalAccessIndex, + buildLessonAccessIndex, + canReadCrystal, + canReadInsight, + canReadLesson, + canUseLessonOperatorCapability, + canWriteLessonScope, + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; + +interface ImportedLessonCandidate { + lesson: Lesson; + sourceId: string; + canonicalized: boolean; +} + +interface LessonLifecycleTransition { + lessonId: string; + before?: string; + after?: string; +} + +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?: { maxSessions?: number; offset?: number }) => { + async (data?: { + maxSessions?: number; + offset?: number; + accessContext?: LessonAccessContext; + }) => { + const accessContext = lessonAccessContextFromPayload( + data?.accessContext, + ); + if ( + !canUseLessonOperatorCapability( + 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); @@ -77,8 +154,7 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { graphEdges, semanticMemories, proceduralMemories, - actions, - actionEdges, + actionStore, sentinels, sketches, crystals, @@ -94,19 +170,38 @@ 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(() => []), 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(() => []), 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, @@ -122,14 +217,34 @@ 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, + crystals: + authorizedCrystals.length > 0 + ? authorizedCrystals + : undefined, facets: facets.length > 0 ? facets : undefined, - lessons: lessons.length > 0 ? lessons : undefined, - insights: insights.length > 0 ? insights : undefined, + lessons: + authorizedLessons.length > 0 + ? authorizedLessons + : 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, @@ -150,6 +265,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, @@ -165,7 +281,23 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { async (data: { exportData: ExportData; strategy?: "merge" | "replace" | "skip"; + accessContext?: LessonAccessContext; }) => { + const accessContext = lessonAccessContextFromPayload( + data?.accessContext, + ); + if ( + !canUseLessonOperatorCapability( + accessContext, + "lesson:import", + ) + ) { + return { + success: false, + code: "access_denied", + error: "lesson access denied for import", + }; + } if ( !data?.exportData || typeof data.exportData !== "object" || @@ -173,7 +305,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"]); @@ -190,6 +334,10 @@ 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; + const MAX_LESSONS = 100_000; if (!Array.isArray(importData.sessions)) { return { success: false, error: "sessions must be an array" }; @@ -207,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 { @@ -240,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, @@ -255,14 +467,242 @@ 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: ImportedLessonCandidate[] = []; + const importedLessonIds = new Set(); + const importedLessonAliases = new Map(); + 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); + 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) + ? 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 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 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" }; + } + 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}`, + }; + } + } + } + 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, observations: 0, memories: 0, summaries: 0, + actions: 0, + actionEdges: 0, + actionEvents: 0, + lessons: 0, skipped: 0, }; + const lessonImport = await withLessonMutationLock(() => + applyImportedLessonBatch( + kv, + normalizedImportedLessons, + strategy, + accessContext, + ), + ); + if (!lessonImport.success) { + return { + success: false, + error: lessonImport.error, + ...(lessonImport.code ? { code: lessonImport.code } : {}), + }; + } + stats.lessons = lessonImport.written; + stats.skipped += lessonImport.skipped; + if (strategy === "replace") { const existing = await kv.list(KV.sessions); for (const session of existing) { @@ -282,12 +722,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); } @@ -309,9 +743,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); } @@ -448,24 +879,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") { @@ -529,15 +1046,6 @@ 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; } - } - await kv.set(KV.lessons, lesson.id, lesson); - } - } if (importData.insights) { for (const insight of importData.insights) { if (strategy === "skip") { @@ -548,15 +1056,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), ); @@ -578,6 +1077,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, }); @@ -585,3 +1085,518 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { }, ); } + +async function applyImportedLessonBatch( + kv: StateKV, + imported: ImportedLessonCandidate[], + strategy: "merge" | "replace" | "skip", + accessContext: LessonAccessContext, +): Promise< + | { success: true; written: number; skipped: number } + | { success: false; error: string; code?: "access_denied" } +> { + 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), + ); + 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) { + 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); + } + } + + 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 [ + 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); + } + 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" + ? 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, actor: accessContext.principalId }, + ); + } + } catch (error) { + const rollback = await restoreLessonPreimage( + kv, + affectedIds, + preimage, + ); + let auditError: string | undefined; + try { + await recordAudit( + kv, + "import", + "mem::import:lessons-rollback", + affectedIds, + { + ...auditDetails, + actor: accessContext.principalId, + 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 }; +} + +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[], + 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[], + 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; + 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 30f43fec60..1b39bf7e82 100644 --- a/src/functions/frontier.ts +++ b/src/functions/frontier.ts @@ -1,122 +1,96 @@ 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 { + buildActionViewIndex, + 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 === "done" || action.status === "cancelled") 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 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) => + !data.project || matchesActionProject(action, data.project), + ) + .map((action) => + classifyAction(action, { + ...viewContext, + index, + }), + ) + .filter((item) => item.view === "actionable") + .map((item) => ({ + ...item, + score: computeActionScore( + item.action, + index.edgesByActionId.get(item.action.id) ?? [], + 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 +99,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 +120,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 +135,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/governance.ts b/src/functions/governance.ts index 16d0d1c427..97b899e4d8 100644 --- a/src/functions/governance.ts +++ b/src/functions/governance.ts @@ -2,11 +2,61 @@ 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"; +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. + * + * 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, + deletedIds: string[], +): Promise<{ repairedReferrers: string[]; removedCount: number }> { + if (deletedIds.length === 0) { + return { repairedReferrers: [], removedCount: 0 }; + } + const removed = new Set(deletedIds); + // 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 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); + return dropped.length; + }); + if (droppedHere > 0) { + repairedReferrers.push(id); + removedCount += droppedHere; + } + } + return { repairedReferrers, removedCount }; +} + export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::governance-delete", async (data: { memoryIds: string[]; reason?: string }) => { @@ -19,6 +69,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 +78,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 +98,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 +206,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 +221,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, }; }, ); @@ -170,6 +249,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/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/leases.ts b/src/functions/leases.ts index 1a2de33bfc..de1ca03049 100644 --- a/src/functions/leases.ts +++ b/src/functions/leases.ts @@ -2,8 +2,15 @@ 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 { + ActionRevisionConflictError, + 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 +35,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 +64,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 = { @@ -68,20 +91,37 @@ export function registerLeasesFunction(sdk: ISdk, kv: StateKV): void { }; await kv.set(KV.leases, lease.id, lease); + const before = { ...action }; + action.status = "active"; + action.lifecycle = "active"; + action.assignedTo = data.agentId; + action.updatedAt = now.toISOString(); + 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, }); - - const before = { ...action }; - action.status = "active"; - action.assignedTo = data.agentId; - action.updatedAt = now.toISOString(); - await kv.set(KV.actions, action.id, action); await recordAudit(kv, "action_update", "mem::lease-acquire", [action.id], { before, - after: action, + after: persisted.action, }); return { success: true, lease, renewed: false }; @@ -122,18 +162,39 @@ 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); + } + } 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 }; @@ -228,15 +289,34 @@ 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, 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/src/functions/lesson-access.ts b/src/functions/lesson-access.ts new file mode 100644 index 0000000000..b054c332be --- /dev/null +++ b/src/functions/lesson-access.ts @@ -0,0 +1,781 @@ +import { + createHash, + createHmac, + randomBytes, + timingSafeEqual, +} from "node:crypto"; +import { readFileSync } from "node:fs"; +import { isAbsolute } from "node:path"; +import { getAgentId, getEnvVar } from "../config.js"; +import type { + Crystal, + Insight, + 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 { + 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 { + 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 { + 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 { + 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 && isAbsolute(policyPath) + ? loadPolicyFile(policyPath) + : (() => { + throw new Error( + "lesson caller policy file must be configured with an absolute path", + ); + })(); + } 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) { + return ( + context.resolvedBy === "system" || + (access === "read" && + hasCapability(context, "lesson:legacy-worktree")) + ); + } + 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 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 { + return ( + context.mode === "classify" || + (context.principalKind === "human" && + hasCapability(context, "lesson:approve-global")) + ); +} + +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 }; + +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/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 new file mode 100644 index 0000000000..f9f1396fda --- /dev/null +++ b/src/functions/lesson-model.ts @@ -0,0 +1,1718 @@ +import { fingerprintId } from "../state/schema.js"; +import type { + Lesson, + LessonClaimType, + LessonEvidenceProvenance, + LessonEvidenceProvenanceType, + LessonEvidenceReference, + LessonEvidenceVerification, + LessonEvidenceVerificationState, + 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 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 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([ + "__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", + "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", +]); +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; + 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; + allowLegacyGitVerificationMigration?: 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 = normalizeLessonStructuredFacets( + record.structuredFacets, + ); + const evidenceRefs = normalizeEvidenceRefs( + record.evidenceRefs, + options.allowLegacyGitVerificationMigration === true, + ); + const scope = normalizeScope( + record.scope, + options.allowImplicitWorktreeScope === true, + ); + const sensitivity = + normalizeEnum( + record.sensitivity, + "sensitivity", + SENSITIVITIES, + ) ?? "restricted"; + const reviewAfter = optionalStrictDate(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`, + ); + } + 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, + 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, + scope: input.scope, + sensitivity: input.sensitivity, + reviewAfter: input.reviewAfter, + }), + ); +} + +export function normalizeLesson(lesson: Lesson): NormalizedLesson { + const lifecycle = deriveLifecycle(lesson); + const structuredMarkers = hasStructuredLessonMarkers(lesson); + const parsed = parseLessonSaveInput( + { + ...lesson, + lifecycle, + }, + { + allowTerminalLifecycle: true, + allowImplicitWorktreeScope: true, + allowLegacyGitVerificationMigration: true, + }, + ); + 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", + { + maxItems: MAX_LESSON_ID_ALIASES, + maxLength: MAX_LESSON_ID_LENGTH, + sort: true, + }, + ).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 normalized: NormalizedLesson = { + ...lesson, + identityKind, + idAliases: [...new Set(idAliases)], + 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; + sourceId: string; + canonicalized: boolean; + } + | { success: false; error: string } { + try { + const record = requireRecord(raw, "lesson"); + 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 ( + 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"); + } + 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( + 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 === sourceId) { + throw new LessonInputError( + "supersededByLessonId must differ from lesson.id", + ); + } + + 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, + 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), + sourceId, + canonicalized: id !== sourceId, + }; + } 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; +} + +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") { + 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) { + throw new LessonInputError( + "scope.scopeId must be omitted for global scope", + ); + } + 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: requiredStrictDate( + 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, + }; +} + +export function normalizeLessonStructuredFacets( + 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 = new Map(); + for (const [rawDimension, rawValues] of entries) { + const dimension = rawDimension + .trim() + .toLowerCase() + .replace(/[\s-]+/g, "_"); + if ( + dimension.length > 64 || + !FACET_DIMENSION_PATTERN.test(dimension) || + RESERVED_FACET_DIMENSIONS.has(dimension) + ) { + throw new LessonInputError( + "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( + rawValues, + `structuredFacets.${rawDimension}`, + { + maxItems: MAX_FACET_VALUES, + maxLength: MAX_FACET_VALUE_LENGTH, + normalize: normalizeDisplayText, + sort: true, + }, + ); + const mergedValues = [ + ...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.set(dimension, mergedValues); + } + return Object.fromEntries( + [...normalized.entries()].sort(([left], [right]) => + compareText(left, right), + ), + ); +} + +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"); + } + 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, + allowLegacyGitVerificationMigration, + ), + ); + 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, + allowLegacyGitVerificationMigration: boolean, +): 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 legacyRepoRemote = optionalString( + record.repoRemoteUrl, + `${prefix}.repoRemoteUrl`, + MAX_EVIDENCE_REMOTE_LENGTH, + ); + const legacyCommitSha = normalizeCommitSha( + optionalString(record.commitSha, `${prefix}.commitSha`, 64), + `${prefix}.commitSha`, + ); + const legacyArtifactDigest = normalizeArtifactDigest( + optionalString(record.artifactDigest, `${prefix}.artifactDigest`, 256), + `${prefix}.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} Git-specific fields require provenance.type=git`, + ); + } + 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 validatedAt = optionalStrictDate( + record.validatedAt, + `${prefix}.validatedAt`, + ); + const legacyGitShape = + (record.provenance === undefined || record.provenance === null) && + Boolean(legacyRepoRemote); + const allowsLegacyGitAnchorBasis = + allowLegacyGitVerificationMigration && + provenance.type === "git" && + Boolean(commitSha || artifactDigest); + const verification = + allowLegacyGitVerificationMigration && + legacyGitShape && + (record.verification === undefined || record.verification === null) + ? { + state: "verified" as const, + basis: "legacy-git-anchor" as const, + verifiedBy: LEGACY_GIT_ANCHOR_MIGRATION_ACTOR, + verifiedAt: validatedAt ?? recordedAt, + note: LEGACY_GIT_ANCHOR_MIGRATION_NOTE, + } + : normalizeEvidenceVerification( + record.verification, + prefix, + allowsLegacyGitAnchorBasis, + ); + 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(), + provenance, + verification, + repoRemoteUrl, + commitSha, + artifactDigest, + path, + recordedAt, + validatedAt, + evidenceKind, + sampleCount, + }; +} + +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, + allowLegacyGitAnchorBasis: 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" && + !allowLegacyGitAnchorBasis + ) { + throw new LessonInputError( + `${prefix}.verification.basis legacy-git-anchor is reserved for compatibility import of immutable Git provenance`, + ); + } + 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 ( + 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`, + ); + } + 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); + 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 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") { + 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 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, " "); +} + +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/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 9e69f464fd..6ee5509b43 100644 --- a/src/functions/lessons.ts +++ b/src/functions/lessons.ts @@ -1,169 +1,618 @@ import type { ISdk } from "iii-sdk"; import type { StateKV } from "../state/kv.js"; -import { KV, fingerprintId } from "../state/schema.js"; +import { fingerprintId, 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, + isLessonListable, + isLessonRecallable, + lessonCanonicalId, + lessonContentFingerprint, + lessonIdForInput, + normalizeLesson, + parseLessonSaveInput, + sameLessonContradictionScope, + 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; +const MAX_CORRECTION_ACTOR_LENGTH = 128; + +type LessonCorrectionData = { + lessonId: string; + reason: string; + actor?: string; + accessContext?: LessonAccessContext; + project?: string; + expectedUpdatedAt?: string; + replacementLessonId?: string; +}; + +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; } -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" }; - } - - const fp = fingerprintId("lsn", data.content.trim().toLowerCase()); - const existing = await kv.get(KV.lessons, fp); +function correctionFailure(code: string, error: string) { + return { success: false, code, error }; +} - if (existing && !existing.deleted) { - reinforceLesson(existing); - if (data.context && !existing.context) { - existing.context = data.context; - } - await kv.set(KV.lessons, existing.id, existing); +function accessFailure(operation: string) { + return correctionFailure( + "access_denied", + `lesson access denied for ${operation}`, + ); +} - try { - await recordAudit(kv, "lesson_strengthen", "mem::lesson-save", [ - existing.id, - ]); - } catch {} +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 matches[0] ?? null; +} +async function validateContradictionRelations( + kv: StateKV, + source: Lesson, + targetIds: string[], + 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 { + code: "invalid_relation", + error: "contradictedByLessonIds must not contain the lesson itself", + }; + } + const target = await kv.get(KV.lessons, targetId); + if (!target) { + 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 { - success: true, - action: "strengthened", - lesson: existing, + code: "invalid_relation", + error: `contradiction target must be active: ${targetId}`, }; } - - 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, + if (!sameLessonContradictionScope(source, target)) { + return { + code: "invalid_relation", + error: `contradiction target must share durable scope and project label: ${targetId}`, + }; + } + } catch { + return { + code: "invalid_relation", + error: `contradiction target is invalid: ${targetId}`, }; + } + } + return null; +} - await kv.set(KV.lessons, lesson.id, lesson); - - try { - await recordAudit(kv, "lesson_save", "mem::lesson-save", [lesson.id]); - } catch {} - - return { success: true, action: "created", lesson }; - }, - ); - - sdk.registerFunction("mem::lesson-recall", - async (data: { - query: string; - project?: string; - minConfidence?: number; - limit?: number; - }) => { - if (!data.query?.trim()) { - return { success: false, error: "query is required" }; +async function correctLesson( + kv: StateKV, + data: LessonCorrectionData, + mode: LessonCorrectionMode, +) { + const accessContext = lessonAccessContextFromPayload(data.accessContext); + const lessonId = data.lessonId?.trim(); + const reason = data.reason?.trim(); + 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; + + 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"); + } + + 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 && + lesson.supersededByLessonId === replacementLessonId && + normalizedLesson.lifecycle === + (mode === "supersede" ? "superseded" : "retracted"); + if (sameCorrection) { + return { + success: true, + action: + mode === "supersede" + ? "already_superseded" + : "already_deleted", + lesson: toLessonReadModel(lesson), + }; } + return correctionFailure( + "lesson_already_deleted", + "lesson is already deleted with different correction metadata", + ); + } - const query = data.query.toLowerCase(); - const minConfidence = data.minConfidence ?? 0.1; - const limit = data.limit ?? 10; - - let lessons = await kv.list(KV.lessons); + 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", + ); + } - lessons = lessons.filter( - (l) => !l.deleted && l.confidence >= minConfidence, + if (replacementLessonId) { + const replacement = await kv.get( + KV.lessons, + replacementLessonId, + ); + if (!replacement) { + return correctionFailure( + "replacement_not_found", + "replacement lesson not found", + ); + } + if (!canReadLesson(replacement, accessContext)) { + return accessFailure("replacement read"); + } + if (!isLessonRecallable(replacement)) { + return correctionFailure( + "replacement_not_active", + "replacement lesson must be active", + ); + } + if (!sameLessonScope(replacement, lesson)) { + return correctionFailure( + replacement.scope?.scopeId || lesson.scope?.scopeId + ? "scope_mismatch" + : "project_mismatch", + "replacement lesson must belong to the same durable scope", + ); + } + } + + const timestamp = new Date().toISOString(); + lesson.deleted = true; + lesson.deletedAt = timestamp; + 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); + + const operation = + mode === "supersede" ? "lesson_supersede" : "lesson_delete"; + try { + await recordAudit( + kv, + operation, + `mem::lesson-${mode}`, + [ + lesson.id, + ...(replacementLessonId ? [replacementLessonId] : []), + ], + { + actor, + reason, + project: lesson.project, + expectedUpdatedAt, + replacementLessonId, + deletedAt: timestamp, + }, ); + } catch {} + + return { + success: true, + action: mode === "supersede" ? "superseded" : "deleted", + lesson: toLessonReadModel(lesson), + }; + }); +} - if (data.project) { - lessons = lessons.filter((l) => l.project === data.project); +export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { + sdk.registerFunction("mem::lesson-save", + async (data: unknown) => { + 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; + // 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); + } + const input = parsed.value; + if ( + !canWriteLessonScope( + input.scope, + input.sensitivity, + accessContext, + ) + ) { + return accessFailure("save"); } - const scored = lessons - .map((l) => { - const text = `${l.content} ${l.context} ${l.tags.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, - resultCount: scored.length, - }); - } catch {} + const fp = lessonIdForInput(input); + 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), + ); + } - return { - success: true, - lessons: scored.slice(0, limit).map((s) => ({ - ...s.lesson, - score: Math.round(s.score * 1000) / 1000, - })), - }; + if (existing && !isLessonListable(existing)) { + return correctionFailure( + "lesson_deleted", + "lesson is superseded or retracted; save corrected evidence as a new lesson", + ); + } + + if (existing) { + const normalizedExisting = normalizeLesson(existing); + if ( + !canReadLesson(normalizedExisting, accessContext) || + !canWriteLessonScope( + normalizedExisting.scope, + normalizedExisting.sensitivity, + accessContext, + ) + ) { + return accessFailure("strengthen"); + } + const contradictionFailure = await validateContradictionRelations( + kv, + normalizedExisting, + input.contradictedByLessonIds, + accessContext, + ); + if (contradictionFailure) { + return correctionFailure( + contradictionFailure.code, + contradictionFailure.error, + ); + } + reinforceLesson(normalizedExisting); + if (input.context && !normalizedExisting.context) { + normalizedExisting.context = input.context; + } + normalizedExisting.sourceIds = [ + ...new Set([ + ...normalizedExisting.sourceIds, + ...input.sourceIds, + ]), + ].sort(); + normalizedExisting.tags = [ + ...new Set([...normalizedExisting.tags, ...input.tags]), + ]; + normalizedExisting.contradictedByLessonIds = [ + ...new Set([ + ...normalizedExisting.contradictedByLessonIds, + ...input.contradictedByLessonIds, + ]), + ].sort(); + await kv.set( + KV.lessons, + normalizedExisting.id, + normalizedExisting, + ); + + try { + await recordAudit( + kv, + "lesson_strengthen", + "mem::lesson-save", + [normalizedExisting.id], + { + actor: accessContext.principalId, + confidenceChanged: false, + }, + ); + } catch {} + + return { + success: true, + action: "strengthened", + lesson: toLessonReadModel(normalizedExisting), + }; + } + + 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 contradictionFailure = await validateContradictionRelations( + kv, + lesson, + input.contradictedByLessonIds, + accessContext, + ); + if (contradictionFailure) { + return correctionFailure( + contradictionFailure.code, + contradictionFailure.error, + ); + } + await kv.set(KV.lessons, lesson.id, lesson); + + try { + await recordAudit( + kv, + "lesson_save", + "mem::lesson-save", + [lesson.id], + { + actor: accessContext.principalId, + contentFingerprint: lesson.contentFingerprint, + evidenceVerdict: lesson.evidenceVerdict, + lifecycle: lesson.lifecycle, + }, + ); + } catch {} + + return { + success: true, + action: "created", + lesson: toLessonReadModel(lesson), + }; + }, + ); }, ); + 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, + ); + + try { + await recordAudit( + kv, + "lesson_recall", + "mem::lesson-recall", + ranked.map(({ lesson }) => lesson.id), + { + queryFingerprint: fingerprintId("qry", input.query), + actor: accessContext.principalId, + requestedLimit: input.limit, + resultCount: ranked.length, + retrievalMode: diagnostics.usedMode, + fallbackCode: diagnostics.fallbackCode, + noticeCode: diagnostics.noticeCode, + }, + ); + } catch {} + + return { + success: true, + retrieval: diagnostics, + lessons: input.compact + ? ranked.map(compactRetrievedLesson) + : ranked.map(({ lesson, score }) => ({ ...lesson, score })), + }; + }); + sdk.registerFunction("mem::lesson-list", async (data: { project?: string; source?: string; minConfidence?: number; limit?: number; + offset?: number; + sortBy?: "confidence" | "recent"; + accessContext?: LessonAccessContext; }) => { - 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); - - lessons = lessons.filter( - (l) => !l.deleted && l.confidence >= minConfidence, + 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); if (data.project) { lessons = lessons.filter((l) => l.project === data.project); @@ -172,112 +621,182 @@ 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, + }; }, ); 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" }; } - const lesson = await kv.get(KV.lessons, data.lessonId); - if (!lesson || lesson.deleted) { - return { success: false, error: "lesson not found" }; - } + 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" }; + } + const accessContext = lessonAccessContextFromPayload( + data.accessContext, + ); + const normalized = normalizeLesson(lesson); + if ( + !canReadLesson(lesson, accessContext) || + !canWriteLessonScope( + normalized.scope, + normalized.sensitivity, + accessContext, + ) + ) { + return accessFailure("strengthen"); + } - 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], + { + actor: accessContext.principalId, + confidenceChanged: false, + }, + ); + } catch {} - return { success: true, lesson }; + return { success: true, lesson: toLessonReadModel(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) => + withLessonLocks([listedLesson.id], async () => { + 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 || + 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"; }), ), ); - return { success: true, decayed, softDeleted, total: lessons.length }; + const decayed = outcomes.filter((outcome) => outcome === "decay").length; + const softDeleted = outcomes.filter( + (outcome) => outcome === "soft-delete", + ).length; + const stale = outcomes.filter((outcome) => outcome === "stale").length; + + return { + success: true, + decayed, + softDeleted, + stale, + total: lessons.length, + }; }, ); } + +function lessonTimestampMs(lesson: Lesson): number { + const parsed = Date.parse(lesson.updatedAt || lesson.createdAt); + return Number.isFinite(parsed) ? parsed : 0; +} 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/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/observe.ts b/src/functions/observe.ts index 8ad4ba0ff5..2ec4bde99f 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 { 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"; import { stripPrivateData } from "./privacy.js"; @@ -11,6 +11,18 @@ 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"; +import { triggerDetached } from "../utils/trigger-detached.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; @@ -59,7 +71,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) { @@ -73,9 +90,6 @@ export function registerObserveFunction( toolName, d["tool_input"], ); - if (dedupMap.isDuplicate(dedupHash)) { - return { deduplicated: true, sessionId: payload.sessionId }; - } } let sanitizedRaw: unknown = payload.data; @@ -125,9 +139,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})`, @@ -139,11 +182,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<{ - 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(); @@ -151,33 +193,37 @@ 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"); 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(), }); } } 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 @@ -199,42 +245,65 @@ 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(), - }); + triggerDetached(sdk, { + 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 }, + }, + }); + } 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, + value: requestedObservationId + ? (await kv.list(observationScope)).length + : (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 +315,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 +347,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", @@ -285,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( @@ -317,12 +403,13 @@ export function registerObserveFunction( data: { type: "compressed", observation: synthetic }, }, }); - await sdk.trigger({ - function_id: "stream::set", + triggerDetached(sdk, { + 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, diff --git a/src/functions/obsidian-export.ts b/src/functions/obsidian-export.ts index 0e8194813a..a596d7937f 100644 --- a/src/functions/obsidian-export.ts +++ b/src/functions/obsidian-export.ts @@ -7,10 +7,23 @@ import { KV } from "../state/schema.js"; import type { Memory, Lesson, + LessonEvidenceReference, Crystal, Session, } from "../types.js"; import { recordAudit } from "./audit.js"; +import { + isLessonListable, + toLessonReadModel, +} from "./lesson-model.js"; +import { + buildLessonAccessIndex, + canReadCrystal, + canReadLesson, + canUseLessonOperatorCapability, + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; const DEFAULT_EXPORT_ROOT = join(homedir(), ".agentmemory"); function getExportRoot(): string { @@ -53,6 +66,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)) { @@ -116,25 +163,45 @@ 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, + 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(evidenceReferenceToMd) + .join("\n"); const sections = [ fm, @@ -144,8 +211,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 +252,9 @@ function lessonToMd(l: Lesson): string { if (sourceLinks) { sections.push("", "## Sources", sourceLinks); } + if (evidenceLines) { + sections.push("", "## Evidence Anchors", evidenceLines); + } return sections.join("\n"); } @@ -246,7 +344,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" }; } @@ -272,6 +378,24 @@ export function registerObsidianExportFunction( const exportTypes = new Set( data.types ?? ["memories", "lessons", "crystals", "sessions"], ); + const accessContext = lessonAccessContextFromPayload( + data.accessContext, + ); + const exportsProtectedRecords = + exportTypes.has("lessons") || exportTypes.has("crystals"); + if ( + exportsProtectedRecords && + !canUseLessonOperatorCapability( + accessContext, + "lesson:export", + ) + ) { + return { + success: false, + code: "access_denied", + error: "lesson access denied for Obsidian export", + }; + } const dirs = { memories: join(vaultDir, "memories"), @@ -285,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 })), ); @@ -296,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[]), ]); @@ -324,7 +477,10 @@ 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) && + canReadLesson(l, accessContext), )) { const filename = `${sanitize(l.id)}.md`; const filepath = join(dirs.lessons, filename); @@ -410,6 +566,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 3a2af82934..a7a46f3c6b 100644 --- a/src/functions/reflect.ts +++ b/src/functions/reflect.ts @@ -9,27 +9,48 @@ 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, + toLessonReadModel, +} from "./lesson-model.js"; +import { + buildCrystalAccessIndex, + buildLessonAccessIndex, + canReadCrystal, + canReadInsight, + canReadLesson, + lessonAccessContextFromPayload, + type CrystalAccessIndex, + type LessonAccessContext, + type LessonAccessIndex, +} from "./lesson-access.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[]; crystalIds: string[]; } +const MAX_REFLECT_DIAGNOSTIC_DETAIL_LENGTH = 256; + 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; } @@ -160,27 +181,145 @@ 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; +} + +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, + }; +} + +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, 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, + ); - 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 = lessons.filter((l) => !l.deleted); + let activeLessons: LessonReadModel[] = []; + let lessonIndex: LessonAccessIndex; + let crystalIndex: CrystalAccessIndex; + try { + lessonIndex = buildLessonAccessIndex(lessons); + crystalIndex = buildCrystalAccessIndex(crystals); + for (const lesson of lessons) { + if ( + isLessonRecallable(lesson) && + canReadLesson(lesson, accessContext) + ) { + activeLessons.push(toLessonReadModel(lesson)); + } + } + } catch (error) { + return reflectLessonReadFailure("normalization", error); + } if (data?.project) { activeLessons = activeLessons.filter((l) => l.project === data.project); } @@ -218,17 +357,28 @@ 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()), ), ); 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; @@ -245,11 +395,14 @@ 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), - lessonIds: clusterLessons.map((l) => l.id), + lessonIds: clusterLessonIds, crystalIds: clusterCrystals.map((c) => c.id), }; @@ -258,21 +411,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; @@ -280,7 +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 { @@ -295,6 +504,7 @@ export function registerReflectFunctions( sourceMemoryIds: cluster.factIds, sourceLessonIds: cluster.lessonIds, sourceCrystalIds: cluster.crystalIds, + evidenceVerdict, project: data?.project, tags: conceptNames, createdAt: now, @@ -339,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, @@ -364,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" }; @@ -374,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/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/functions/replay.ts b/src/functions/replay.ts index e44ca8cc9d..58c7fb7e71 100644 --- a/src/functions/replay.ts +++ b/src/functions/replay.ts @@ -17,6 +17,12 @@ import { safeAudit } from "./audit.js"; import { buildSyntheticCompression } from "./compress-synthetic.js"; import { getSearchIndex } from "./search.js"; import { logger } from "../logger.js"; +import { + buildLessonAccessIndex, + canReadCrystal, + lessonAccessContextFromPayload, + type LessonAccessContext, +} from "./lesson-access.js"; export const MAX_FILES_DEFAULT = 200; export const MAX_FILES_UPPER_BOUND = 1000; @@ -67,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(); @@ -113,48 +121,26 @@ 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 existingSources = existing.sourceIds || []; - const mergedSources = existingSources.includes(sessionId) - ? existingSources - : [...existingSources, sessionId]; - const existingTags = existing.tags || []; - const mergedTags = existingTags.includes("auto-import") - ? existingTags - : [...existingTags, "auto-import"]; - const merged: Lesson = { - ...existing, - sourceIds: mergedSources, - tags: mergedTags, - reinforcements: (existing.reinforcements || 0) + 1, - updatedAt: createdAt, - lastReinforcedAt: createdAt, - }; - await kv.set(KV.lessons, lessonId, merged); - } else { - const lesson: Lesson = { - id: lessonId, + 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); + accessContext, + }, + })) as { + success?: boolean; + lesson?: { id?: string }; + }; + if (result.success && typeof result.lesson?.id === "string") { + lessonIds.push(result.lesson.id); } - lessonIds.push(lessonId); } catch {} } @@ -172,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, @@ -287,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; @@ -366,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; @@ -446,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/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/session-context.ts b/src/functions/session-context.ts new file mode 100644 index 0000000000..cf7ff979a0 --- /dev/null +++ b/src/functions/session-context.ts @@ -0,0 +1,98 @@ +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, + contextUpdatedAt: session.contextUpdatedAt, + }; +} + +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) }; + } + + updates.push({ + type: "set", + path: "contextUpdatedAt", + value: new Date().toISOString(), + }); + 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..c45ba594f3 --- /dev/null +++ b/src/functions/session-list.ts @@ -0,0 +1,149 @@ +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, + contextUpdatedAt: session.contextUpdatedAt, + 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/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/functions/smart-search.ts b/src/functions/smart-search.ts index 5d0147d9e0..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"; @@ -17,6 +16,8 @@ import { } from "../config.js"; 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 @@ -68,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, @@ -95,6 +92,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 +197,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,25 +296,50 @@ 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 }, - })) 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((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; + const contradicted = lesson.contradicted; + 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.lessonId, + content: lesson.content, + claim: lesson.claim, + evidenceVerdict, + evidenceLabel, + contradicted, + confidence: lesson.confidence, + score: lesson.score, + 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/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/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/_project.ts b/src/hooks/_project.ts index 35364ea3bb..d161177168 100644 --- a/src/hooks/_project.ts +++ b/src/hooks/_project.ts @@ -1,20 +1,138 @@ -import { execSync } from "node:child_process"; -import { basename } from "node:path"; +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync, realpathSync } 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 canonicalExistingPath(path: string): string { + try { + return realpathSync.native(path); + } catch { + return resolve(path); + } +} + +function nearestProjectFile(cwd: string, boundary?: string): string | undefined { + 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 || current === filesystemRoot) return undefined; + const parent = dirname(current); + if (parent === current) return undefined; + current = parent; + } +} + +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..23d0153e97 100644 --- a/src/hooks/notification.ts +++ b/src/hooks/notification.ts @@ -1,5 +1,6 @@ #!/usr/bin/env node -import { resolveProject } from "./_project.js"; +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) { @@ -38,25 +30,19 @@ async function main() { typeof rawSessionId === "string" && rawSessionId.length > 0 ? rawSessionId : "unknown"; - - fetch(`${REST_URL}/agentmemory/observe`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "notification", - sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), - 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(); + const context = resolveProjectContext(data.cwd as string | undefined); + + 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 f0295b3e62..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 { resolveProject } from "./_project.js"; +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,33 +26,31 @@ 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; - - fetch(`${REST_URL}/agentmemory/observe`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "post_tool_failure", - sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), - 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(); + const context = resolveProjectContext(data.cwd as string | undefined); + + 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 c68a7731d3..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 { resolveProject } from "./_project.js"; +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,28 +26,45 @@ 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)); - fetch(`${REST_URL}/agentmemory/observe`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "post_tool_use", - sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), - timestamp: new Date().toISOString(), - data: { - tool_name: toolName, - tool_input: toolInput, - tool_output: truncate(cleanOutput, 8000), - ...(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 { + 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 { 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/prompt-submit.ts b/src/hooks/prompt-submit.ts index 2da8ea6a41..5e3946cba0 100644 --- a/src/hooks/prompt-submit.ts +++ b/src/hooks/prompt-submit.ts @@ -1,5 +1,6 @@ #!/usr/bin/env node -import { resolveProject } from "./_project.js"; +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) { @@ -32,21 +24,28 @@ 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); + + await submitObservation({ + hookType: "prompt_submit", + sessionId, + ...context, + timestamp: new Date().toISOString(), + data: promptData, + }); +} - fetch(`${REST_URL}/agentmemory/observe`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "prompt_submit", - sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), - timestamp: new Date().toISOString(), - data: { prompt: data.prompt ?? data.userPrompt }, - }), - 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..9121b2588e 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). @@ -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; } @@ -52,14 +56,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..bf7c66f29c 100644 --- a/src/hooks/subagent-start.ts +++ b/src/hooks/subagent-start.ts @@ -1,5 +1,6 @@ #!/usr/bin/env node -import { resolveProject } from "./_project.js"; +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) { @@ -42,24 +28,18 @@ 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; - - fetch(`${REST_URL}/agentmemory/observe`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "subagent_start", - sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), - timestamp: new Date().toISOString(), - data: { - agent_id: agentId, - agent_type: agentType, - }, - }), - signal: AbortSignal.timeout(TIMEOUT_MS), - }).catch(() => {}); - setTimeout(() => process.exit(0), 500).unref(); + const context = resolveProjectContext(data.cwd as string | undefined); + + 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 5a437c9fd4..73562da847 100644 --- a/src/hooks/subagent-stop.ts +++ b/src/hooks/subagent-stop.ts @@ -1,5 +1,6 @@ #!/usr/bin/env node -import { resolveProject } from "./_project.js"; +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) { @@ -38,25 +30,19 @@ async function main() { typeof data.last_assistant_message === "string" ? data.last_assistant_message.slice(0, 4000) : ""; - - fetch(`${REST_URL}/agentmemory/observe`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "subagent_stop", - sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), - 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(); + const context = resolveProjectContext(data.cwd as string | undefined); + + 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 dbdf815ac8..c937f757e8 100644 --- a/src/hooks/task-completed.ts +++ b/src/hooks/task-completed.ts @@ -1,5 +1,6 @@ #!/usr/bin/env node -import { resolveProject } from "./_project.js"; +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) { @@ -32,29 +24,23 @@ async function main() { if (isSdkChildContext(data)) return; const sessionId = (data.session_id as string) || "unknown"; - - fetch(`${REST_URL}/agentmemory/observe`, { - method: "POST", - headers: authHeaders(), - body: JSON.stringify({ - hookType: "task_completed", - sessionId, - project: resolveProject(data.cwd as string | undefined), - cwd: (data.cwd as string | undefined) || process.cwd(), - 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(); + const context = resolveProjectContext(data.cwd as string | undefined); + + 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/src/index.ts b/src/index.ts index 1e623eae81..9708e2773f 100644 --- a/src/index.ts +++ b/src/index.ts @@ -87,7 +87,10 @@ 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 { systemLessonAccessContext } from "./functions/lesson-access.js"; import { registerApiTriggers } from "./triggers/api.js"; import { registerEventTriggers } from "./triggers/events.js"; import { registerMcpEndpoints } from "./mcp/server.js"; @@ -99,32 +102,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( @@ -158,6 +163,7 @@ process.on("unhandledRejection", (reason) => { }); async function main() { + acquireWorkerPidfileLease(); const config = loadConfig(); const embeddingConfig = loadEmbeddingConfig(); const fallbackConfig = loadFallbackConfig(); @@ -214,8 +220,6 @@ async function main() { }, }); - writeWorkerPidfile(); - const kv = new StateKV(sdk); const secret = getEnvVar("AGENTMEMORY_SECRET"); const metricsStore = new MetricsStore(kv); @@ -331,7 +335,9 @@ 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( `v0.6 advanced retrieval: sliding-window, query-expansion, temporal-graph, retention-scoring`, ); @@ -369,7 +375,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); @@ -518,7 +524,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: 136 endpoints at http://localhost:${config.restPort}/agentmemory/*`, ); bootLog( `MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`, @@ -582,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(); @@ -607,6 +616,7 @@ async function main() { } main().catch((err) => { + clearWorkerPidfile(); console.error(`[agentmemory] Fatal:`, err); process.exit(1); }); 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 new file mode 100644 index 0000000000..6f0cf8a512 --- /dev/null +++ b/src/mcp/http.ts @@ -0,0 +1,435 @@ +#!/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 { + callerIdentityHeaders, + 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"; +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}` } : {}), + ...callerIdentityHeaders(), + }; +} + +function outboundCredential(): string { + return ( + resolveEnvOrEmpty("AGENTMEMORY_SECRET") || + resolveEnvOrEmpty("AGENTMEMORY_CALLER_TOKEN") + ); +} + +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; + 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() }, + signal: AbortSignal.timeout(BACKEND_TIMEOUT_MS), + }); + if (!response.ok) { + throw await upstreamHttpError( + init.method ?? "GET", + path, + response, + ); + } + const text = await response.text(); + return text ? JSON.parse(text) : null; + } + + return { + async health() { + guardBackendRequest(); + 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/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 1adbb46e83..4042d64612 100644 --- a/src/mcp/rest-proxy.ts +++ b/src/mcp/rest-proxy.ts @@ -1,3 +1,6 @@ +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; const CALL_TIMEOUT_MS = 15_000; @@ -30,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. @@ -49,11 +53,29 @@ 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}` } : {}; } +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. @@ -124,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); @@ -137,18 +160,22 @@ export async function resolveHandle(): Promise { mode: "proxy", baseUrl: url, call: async (path, init) => { + guardPlaintextCredential(url, outboundCredential()); const res = await fetch(`${url}${path}`, { ...init, headers: { "content-type": "application/json", ...authHeader(), ...(init?.headers as Record | undefined), + ...callerIdentityHeaders(), }, 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(); @@ -176,4 +203,5 @@ export function resetHandleForTests(): void { cachedAt = 0; probeInFlight = null; livezProbe = defaultLivezProbe; + guardPlaintextCredential = createPlaintextCredentialGuard(); } diff --git a/src/mcp/server.ts b/src/mcp/server.ts index dbca07d9b8..dc712bba8e 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -11,6 +11,14 @@ 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"; +import { parseLessonSaveInput } from "../functions/lesson-model.js"; +import { parseLessonRecallInput } from "../functions/lesson-retrieval.js"; +import { + bindResolvedLessonWriteIdentity, + resolveLessonBoundaryAccess, + type LessonAccessContext, +} from "../functions/lesson-access.js"; type McpResponse = { status_code: number; @@ -18,6 +26,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; } @@ -165,6 +193,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 { @@ -238,6 +279,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, @@ -253,12 +339,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) }, ], }, }; @@ -272,6 +368,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", @@ -279,6 +380,9 @@ export function registerMcpEndpoints( query: args.query, expandIds, limit, + ...(access?.success + ? { accessContext: access.context } + : {}), }, }); return { @@ -362,7 +466,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: { @@ -477,9 +586,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, @@ -571,10 +684,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, @@ -674,14 +790,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, @@ -700,11 +841,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, @@ -716,6 +895,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, @@ -1021,6 +1229,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" } }; } @@ -1029,18 +1239,86 @@ 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) }] } }; } + 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) : 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) }] } }; } + 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) @@ -1092,49 +1370,148 @@ 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 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 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(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 }, + }; + } + const lessonSaveResult = await sdk.trigger({ + function_id: "mem::lesson-save", + payload: { ...parsed.value, accessContext: access.context }, + }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(lessonSaveResult, null, 2) }] } }; } case "memory_lesson_recall": { - 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 access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; + 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) }] } }; } + 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) { + 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", + 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, + ); + 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", + 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) }] } }; } 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) }] } }; } @@ -1143,9 +1520,20 @@ export function registerMcpEndpoints( 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, + ...(access?.success + ? { accessContext: access.context } + : {}), } }); return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(obsidianResult, null, 2) }] } }; } diff --git a/src/mcp/standalone.ts b/src/mcp/standalone.ts index dd66ecb1dd..b64e147630 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": { @@ -339,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 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 c4df3499c7..e6b91850b7 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -1,9 +1,27 @@ +export type McpSchemaProperty = { + type: string; + description?: string; + enum?: string[]; + items?: 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 = { name: string; description: string; inputSchema: { type: "object"; - properties: Record; + properties: Record; required?: string[]; }; }; @@ -115,8 +133,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", @@ -189,7 +219,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: {} }, }, { @@ -374,7 +405,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", @@ -388,6 +430,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"], }, @@ -404,15 +473,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: @@ -759,7 +904,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: { @@ -777,6 +922,176 @@ 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. Dimensions normalize to ASCII snake_case matching ^[a-z][a-z0-9_]*$", + additionalProperties: { + type: "array", + items: { type: "string" }, + maxItems: 16, + }, + }, + evidenceRefs: { + type: "array", + description: + "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" }, + path: { type: "string" }, + recordedAt: { type: "string" }, + validatedAt: { type: "string" }, + evidenceKind: { type: "string" }, + sampleCount: { type: "number", minimum: 0 }, + }, + required: ["kind", "projectId", "recordedAt"], + }, + }, + scope: { + type: "object", + description: + "Caller-supplied scope classification and lineage metadata, not authorization; project remains only a label", + properties: { + ring: { + type: "string", + enum: ["worktree", "repo", "initiative", "domain", "global"], + }, + 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" }, + 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"], }, @@ -784,25 +1099,184 @@ 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"], }, }, + { + name: "memory_lesson_delete", + description: + "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: { + 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 attribution hint in classify mode; ignored and server-stamped from the authenticated principal in enforce mode", + }, + }, + required: ["lessonId", "reason"], + }, + }, + { + 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. An optional project guard applies only to the original lesson; replacement compatibility follows durable scope rules.", + 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 for the original lesson; replacement compatibility is enforced by durable scope rules", + }, + expectedUpdatedAt: { + type: "string", + description: + "Optional optimistic concurrency guard from the original lesson's updatedAt", + }, + actor: { + type: "string", + description: + "Optional attribution hint in classify mode; ignored and server-stamped from the authenticated principal in enforce mode", + }, + }, + required: ["lessonId", "replacementLessonId", "reason"], + }, + }, { 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: { @@ -853,6 +1327,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", @@ -928,12 +1463,40 @@ 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_action_list", + "memory_frontier", + "memory_next", + "memory_lease", + "memory_signal_send", + "memory_signal_read", + "memory_diagnostic_followup", +]); + +export const LLM_BACKED_TOOLS = new Set([ + "memory_compress_file", + "memory_consolidate", + "memory_crystallize", "memory_reflect", + "memory_enrich_session", + "memory_flow_compress", + "memory_llm_smoke", +]); + +export const WORKSTATION_LLM_TOOLS = new Set([ + ...WORKSTATION_TOOLS, + ...LLM_BACKED_TOOLS, ]); export function getAllTools(): McpToolDef[] { @@ -945,17 +1508,43 @@ export function getAllTools(): McpToolDef[] { ...V061_TOOLS, ...V070_TOOLS, ...V073_TOOLS, + ...V0927_WORKSTATION_TOOLS, ...V010_SLOTS_TOOLS, ]; } -// 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 if (mode === "workstation-llm") { + selected = all.filter((tool) => WORKSTATION_LLM_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/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/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/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/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/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 7b6c2bf2b8..bdc0640efc 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -1,7 +1,14 @@ -import { TriggerAction, type ISdk, type ApiRequest } from "iii-sdk"; -import type { Session, CompressedObservation, HookPayload, CommitLink, SessionSummary } from "../types.js"; +import { TriggerAction, type ISdk, type ApiRequest, type EnqueueResult } from "iii-sdk"; +import type { + Session, + CompressedObservation, + HookPayload, + CommitLink, + SessionSummary, + ProviderConfig, +} 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"; @@ -13,6 +20,15 @@ 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 { triggerDetached } from "../utils/trigger-detached.js"; +import { parseLessonSaveInput } from "../functions/lesson-model.js"; +import { parseLessonRecallInput } from "../functions/lesson-retrieval.js"; +import { + bindResolvedLessonWriteIdentity, + resolveLessonBoundaryAccess, + type LessonAccessContext, +} from "../functions/lesson-access.js"; import { isGraphExtractionEnabled, isConsolidationEnabled, @@ -20,6 +36,8 @@ import { isContextInjectionEnabled, detectEmbeddingProvider, detectLlmProviderKind, + getLlmExecutionState, + LLM_METRIC_FUNCTION_IDS, getAgentId, isAgentScopeIsolated, } from "../config.js"; @@ -30,6 +48,28 @@ 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 { if (raw === undefined || raw === null || raw === "") return undefined; const n = typeof raw === "number" ? raw : parseInt(String(raw), 10); @@ -116,6 +156,65 @@ 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 [ + "repoRoot", + "scopeType", + "worktree", + "branch", + "taskSlug", + ] as const) { + const value = asNonEmptyString(body[field]); + if (value) result[field] = value.slice(0, 4096); + } + return result; +} + +function parseObserveRequest( + req: ApiRequest, +): { 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; @@ -135,12 +234,20 @@ 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, secret?: string, metricsStore?: MetricsStore, - provider?: ResilientProvider | { circuitState?: unknown }, + provider?: ResilientProvider, + providerConfig?: Pick, ): void { sdk.registerFunction( "middleware::api-auth", @@ -180,6 +287,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 = [ { @@ -232,6 +340,7 @@ export function registerApiTriggers( body: { version: VERSION, provider: providerKind, + llmExecutionState, embeddingProvider, flags, }, @@ -251,7 +360,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; @@ -264,6 +380,14 @@ export function registerApiTriggers( status, 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", + llmExecutionState, + llmProvider: provider?.name ?? null, + llmConfiguredProvider: providerConfig?.provider ?? null, + llmModel: providerConfig?.model ?? null, health: health || null, functionMetrics, circuitBreaker, @@ -285,38 +409,68 @@ 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) { + 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 }; + }, + ); + sdk.registerTrigger({ + type: "http", + function_id: "api::observe", + config: { + api_path: "/agentmemory/observe", + http_method: "POST", + middleware_function_ids: ["middleware::api-auth"], + }, + }); + + sdk.registerFunction("api::observe::async", + async (req: ApiRequest): Promise => { + const parsed = parseObserveRequest(req); + if ("error" in parsed) return parsed.error; + + 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: 400, + status_code: 202, body: { - error: - "hookType, sessionId, project, cwd, and timestamp are required strings", + 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", }, }; } - const payload: HookPayload = { - hookType: hookType as HookPayload["hookType"], - sessionId, - project, - cwd, - timestamp, - data: body.data, - }; - const result = await sdk.trigger({ function_id: "mem::observe", payload }); - return { status_code: 201, body: result }; }, ); sdk.registerTrigger({ type: "http", - function_id: "api::observe", + function_id: "api::observe::async", config: { - api_path: "/agentmemory/observe", + api_path: "/agentmemory/observe/async", http_method: "POST", middleware_function_ids: ["middleware::api-auth"], }, @@ -326,6 +480,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); @@ -342,9 +498,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 }); @@ -473,6 +635,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); @@ -517,8 +696,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 { @@ -559,7 +744,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); @@ -573,6 +767,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 @@ -582,11 +778,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) } : {}), @@ -595,9 +794,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 }, @@ -614,6 +820,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); @@ -628,18 +873,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 } }; }, ); @@ -820,18 +1061,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({ @@ -953,6 +1217,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<{ @@ -1073,7 +1391,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; @@ -1087,13 +1414,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 }; }, @@ -1108,9 +1474,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 }; }, ); @@ -1144,6 +1515,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). @@ -1163,6 +1541,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 }; @@ -1255,6 +1634,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 @@ -1262,7 +1643,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; @@ -1275,7 +1660,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({ @@ -1293,11 +1682,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({ @@ -1617,9 +2019,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(); @@ -1703,10 +2118,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 } }; }, @@ -2210,25 +2628,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({ @@ -2238,23 +2675,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({ @@ -2267,12 +2726,54 @@ 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 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({ @@ -2281,6 +2782,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); @@ -2299,21 +2829,50 @@ 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<{ - 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({ @@ -2733,8 +3292,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 { @@ -2932,9 +3524,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" } }); @@ -2942,6 +3555,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) { @@ -2950,7 +3565,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" } }); @@ -2958,8 +3581,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" } }); @@ -2967,8 +3605,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" } }); @@ -3055,20 +3713,36 @@ 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 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, + // 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 } }; + } 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", - }, - })) 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 }; }); @@ -3077,6 +3751,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) { @@ -3092,11 +3768,32 @@ 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) ?? undefined; + 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, + accessContext: access.context, } }); return { status_code: 200, body: result }; }); @@ -3105,9 +3802,35 @@ 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 access = resolveLessonRequestAccess(req); + if (!access.success) return access.response; + const body = (req.body ?? {}) as Record; + 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: parsed.error, code: "invalid_request" }, + }; + } + const result = await sdk.trigger({ + function_id: "mem::lesson-recall", + payload: parsed.value, + }); return { status_code: 200, body: result }; }); sdk.registerTrigger({ type: "http", function_id: "api::lesson-search", config: { api_path: "/agentmemory/lessons/search", http_method: "POST" } }); @@ -3115,13 +3838,143 @@ 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); + 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", + accessContext: access.context, + }, + }); + 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" || + response.code === "scope_mismatch" + ? 409 + : response.code === "access_denied" + ? 403 + : 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 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); + 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", + accessContext: access.context, + }, + }); + 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" || + response.code === "scope_mismatch" || + response.code === "replacement_not_active" + ? 409 + : response.code === "access_denied" + ? 403 + : 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; @@ -3134,18 +3987,40 @@ 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 includesProtectedRecords = + types === undefined || + types.includes("lessons") || + types.includes("crystals"); + const access = includesProtectedRecords + ? 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 }; }); @@ -3154,6 +4029,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) { @@ -3173,6 +4050,7 @@ export function registerApiTriggers( project: params.project, minConfidence, limit, + accessContext: access.context, } }); return { status_code: 200, body: result }; }); @@ -3181,6 +4059,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: { @@ -3188,6 +4068,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/triggers/events.ts b/src/triggers/events.ts index e38b58db4d..3cc4fec8a8 100644 --- a/src/triggers/events.ts +++ b/src/triggers/events.ts @@ -1,30 +1,59 @@ -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"; +import { lessonAccessContextFromPayload } from "../functions/lesson-access.js"; +import type { LessonAccessContext } from "../functions/lesson-access.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; + accessContext?: unknown; + }) => { + const accessContext = lessonAccessContextFromPayload(data.accessContext); + 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, }; 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, + }, }); return { session, context: contextResult.context }; }, @@ -45,20 +74,19 @@ 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 = await sdk.trigger({ + function_id: "mem::summarize", + 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 { @@ -67,11 +95,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", { @@ -118,7 +149,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, @@ -132,7 +163,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/types.ts b/src/types.ts index 6797dfaf99..a5450a88a8 100644 --- a/src/types.ts +++ b/src/types.ts @@ -2,7 +2,15 @@ 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; + contextUpdatedAt?: string; endedAt?: string; status: "active" | "completed" | "abandoned"; observationCount: number; @@ -133,8 +141,14 @@ export type HookType = export interface HookPayload { hookType: HookType; sessionId: string; + observationId?: string; project: string; cwd: string; + repoRoot?: string; + scopeType?: string; + worktree?: string; + branch?: string; + taskSlug?: string; timestamp: string; data: unknown; } @@ -151,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; @@ -194,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 { @@ -273,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; @@ -320,6 +348,8 @@ export interface ExportData { proceduralMemories?: ProceduralMemory[]; actions?: Action[]; actionEdges?: ActionEdge[]; + actionEvents?: ActionEvent[]; + actionSnapshot?: ActionSnapshot; routines?: Routine[]; signals?: Signal[]; checkpoints?: Checkpoint[]; @@ -563,6 +593,7 @@ export interface AuditEntry { timestamp: string; operation: | "observe" + | "session_context_update" | "compress" | "remember" | "forget" @@ -574,6 +605,7 @@ export interface AuditEntry { | "export" | "action_create" | "action_update" + | "action_delete" | "lease_acquire" | "lease_release" | "routine_run" @@ -596,6 +628,8 @@ export interface AuditEntry { | "lesson_save" | "lesson_recall" | "lesson_strengthen" + | "lesson_delete" + | "lesson_supersede" | "obsidian_export" | "reflect" | "insight_search" @@ -663,6 +697,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 = @@ -792,14 +931,112 @@ export interface Crystal { keyOutcomes: string[]; filesAffected: string[]; lessons: string[]; + sourceLessonIds?: string[]; sourceActionIds: string[]; sessionId?: string; project?: string; 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 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; + provenance?: LessonEvidenceProvenance; + verification?: LessonEvidenceVerification; + 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; + identityKind?: "canonical" | "legacy-prose"; + idAliases?: string[]; content: string; context: string; confidence: number; @@ -814,6 +1051,50 @@ export interface Lesson { lastDecayedAt?: string; decayRate: number; deleted?: boolean; + deletedAt?: string; + 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; + identityKind: "canonical" | "legacy-prose"; + idAliases: string[]; + 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 { @@ -826,6 +1107,7 @@ export interface Insight { sourceMemoryIds: string[]; sourceLessonIds: string[]; sourceCrystalIds: string[]; + evidenceVerdict?: LessonEvidenceVerdict; project?: string; tags: string[]; createdAt: string; 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/src/viewer/index.html b/src/viewer/index.html index 305397e935..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; } @@ -1345,7 +1369,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'), @@ -1536,16 +1560,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 += ''; @@ -2534,7 +2562,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 +2789,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 +2925,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(); @@ -3077,13 +3105,32 @@

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 facetText = lessonFacetEntries(l.structuredFacets).map(function(entry) { + return entry.dimension + ' ' + entry.value; + }).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; }); } 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 += '
'; @@ -3096,16 +3143,35 @@

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 += '
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) : '-') + '
'; + 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 += ''; @@ -3376,7 +3442,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/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/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/actions-api-pagination.test.ts b/test/actions-api-pagination.test.ts new file mode 100644 index 0000000000..186c1e8bf5 --- /dev/null +++ b/test/actions-api-pagination.test.ts @@ -0,0 +1,175 @@ +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); + }); + + 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("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) => { + 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-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 }); + }); +}); diff --git a/test/actions-v2-migration.test.ts b/test/actions-v2-migration.test.ts new file mode 100644 index 0000000000..22cceb2614 --- /dev/null +++ b/test/actions-v2-migration.test.ts @@ -0,0 +1,391 @@ +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("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( + "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("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"; + 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..7666df09b2 --- /dev/null +++ b/test/actions-v2.test.ts @@ -0,0 +1,660 @@ +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 { + ActionRevisionConflictError, + persistAction, +} from "../src/functions/action-store.js"; +import { registerLeasesFunction } from "../src/functions/leases.js"; +import type { + Action, + ActionCollectionState, + ActionEvent, + ActionViewItem, + Checkpoint, + Lease, + 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("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", + })) 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("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", + })) 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/actions.test.ts b/test/actions.test.ts index 156ba795db..e3810e2f38 100644 --- a/test/actions.test.ts +++ b/test/actions.test.ts @@ -386,10 +386,137 @@ 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); + }); + }); + + 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); }); }); diff --git a/test/api-llm-state.test.ts b/test/api-llm-state.test.ts new file mode 100644 index 0000000000..c6282cc6d6 --- /dev/null +++ b/test/api-llm-state.test.ts @@ -0,0 +1,72 @@ +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, + { provider: "openai", model: "deepseek-v4-pro" }, + ); + + 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)", + llmConfiguredProvider: "openai", + llmModel: "deepseek-v4-pro", + }); + 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 new file mode 100644 index 0000000000..08ae53d8e7 --- /dev/null +++ b/test/api-observe-async.test.ts @@ -0,0 +1,122 @@ +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; + }>; + let rejectQueue: boolean; + + beforeEach(() => { + sdk = mockSdk(); + dispatched = []; + rejectQueue = false; + 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); + 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); + }) as typeof sdk.trigger; + + registerApiTriggers(sdk as never, mockKV() as never); + }); + + it("acknowledges only after the durable observation queue returns a receipt", 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; + observationId: string; + messageReceiptId: string; + }; + }; + + expect(response).toMatchObject({ + status_code: 202, + 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: "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", + }, + }); + }); + + 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/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/auto-compress.test.ts b/test/auto-compress.test.ts index fdcced8fe3..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 () => { @@ -131,8 +140,119 @@ 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("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/causal-lessons-api.test.ts b/test/causal-lessons-api.test.ts new file mode 100644 index 0000000000..3665c30426 --- /dev/null +++ b/test/causal-lessons-api.test.ts @@ -0,0 +1,534 @@ +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 { + 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 { + AuditEntry, + EmbeddingProvider, + 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, + verification: { + state: "verified", + verifiedBy: "reviewer@example.test", + verifiedAt: "2026-08-02T20:30:00.000Z", + }, + }; +} + +describe("causal lesson REST and MCP boundaries", () => { + let sdk: ReturnType; + let kv: ReturnType; + + beforeEach(() => { + setEmbeddingProvider(null); + resetLessonRetrievalCacheForTests(); + 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("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: {}, + 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, + includeHidden: true, + candidateIds: ["lsn_untrusted"], + accessContext: { + mode: "enforce", + principalId: "untrusted", + }, + }, + })) 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"); + }); + + 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", + 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/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/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/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/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."); 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")); 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/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/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", 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/diagnostics.test.ts b/test/diagnostics.test.ts index 1e168767ac..99eaeb804c 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; @@ -246,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" }); @@ -436,9 +548,103 @@ describe("Diagnostics Functions", () => { ); expect(check).toBeDefined(); expect(check!.status).toBe("warn"); + // 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"); + // 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 () => { + 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"); + // 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 () => { const peer = makePeer({ lastSyncAt: new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString(), @@ -518,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({ @@ -639,6 +879,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)", () => { @@ -678,6 +984,97 @@ 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("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/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/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/export-import.test.ts b/test/export-import.test.ts index 3949862699..5f225480a4 100644 --- a/test/export-import.test.ts +++ b/test/export-import.test.ts @@ -5,32 +5,115 @@ vi.mock("../src/logger.js", () => ({ })); import { registerExportImportFunction } from "../src/functions/export-import.js"; +import { registerLessonsFunctions } from "../src/functions/lessons.js"; import type { Session, CompressedObservation, Memory, SessionSummary, ExportData, + Action, + 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" | "list"; + scope: string; + key?: string; + message?: 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 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[]) : []; }, + failNext( + operation: "set" | "delete", + scope: string, + key: string, + ): 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; + } { + 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 }; + }, }; } @@ -101,6 +184,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; @@ -128,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", @@ -231,6 +408,648 @@ 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 structuredCanonical = importedLesson(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", + structuredCanonical.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", + idAliases: [structured.id], + evidenceRefs: [ + expect.objectContaining({ + commitSha: "d".repeat(40), + verification: expect.objectContaining({ + state: "verified", + basis: "legacy-git-anchor", + }), + }), + ], + }); + }); + + 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("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("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) => { + 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", @@ -249,4 +1068,280 @@ 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("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", + 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/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(); diff --git a/test/governance.test.ts b/test/governance.test.ts index 6390bbeea6..e173eb6d13 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; @@ -141,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({ @@ -253,4 +421,232 @@ 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_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", + "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", + "aud_visible_replacement", + ]); + 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", + ]); + }); +}); + +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([]); + }); }); 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/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`"); + }); +}); diff --git a/test/hook-project.test.ts b/test/hook-project.test.ts index 66e25f181f..8bcc8ab3f8 100644 --- a/test/hook-project.test.ts +++ b/test/hook-project.test.ts @@ -1,8 +1,16 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest"; -import { mkdtempSync, rmSync } from "node:fs"; +import { + mkdirSync, + mkdtempSync, + realpathSync, + rmSync, + symlinkSync, + 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 +71,60 @@ 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(realpathSync.native(dir)); + } finally { + 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: realpathSync.native(repo), + worktree: realpathSync.native(repo), + }); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); }); 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/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/lesson-access.test.ts b/test/lesson-access.test.ts new file mode 100644 index 0000000000..4fed77a9b8 --- /dev/null +++ b/test/lesson-access.test.ts @@ -0,0 +1,411 @@ +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", + }); + 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", () => { + 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( + canWriteLessonScope( + { ring: "worktree" }, + "restricted", + context({ + clearance: "restricted", + capabilities: ["lesson:legacy-worktree"], + }), + ), + ).toBe(false); + 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( + 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 new file mode 100644 index 0000000000..c093a5dede --- /dev/null +++ b/test/lesson-authorization.test.ts @@ -0,0 +1,698 @@ +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 { 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, +} 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(() => { + setEmbeddingProvider(null); + resetLessonRetrievalCacheForTests(); + 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", + "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", + ], + }, + ], + }), + ); + 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); + 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, + 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(() => { + setEmbeddingProvider(null); + resetLessonRetrievalCacheForTests(); + 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("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 and recall 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[] }; + }; + expect(list.body.total).toBe(1); + expect(list.body.lessons.map((lesson) => lesson.mechanismId)).toEqual([ + "authorization/visible", + ]); + 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", { + ...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 () => { + 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 a non-operator 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("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"), + 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/lesson-corrections.test.ts b/test/lesson-corrections.test.ts new file mode 100644 index 0000000000..8912c7b521 --- /dev/null +++ b/test/lesson-corrections.test.ts @@ -0,0 +1,358 @@ +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, + lifecycle: "retracted", + 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, + lifecycle: "superseded", + 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, replacement.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("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", + verification: { + state: "verified", + verifiedBy: "reviewer@example.test", + verifiedAt: "2026-08-02T20:30: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([ + 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/lesson-model.test.ts b/test/lesson-model.test.ts new file mode 100644 index 0000000000..a4fd2f546a --- /dev/null +++ b/test/lesson-model.test.ts @@ -0,0 +1,857 @@ +import { describe, expect, it } from "vitest"; +import { execFileSync } from "node:child_process"; +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, + verification: { + state: "verified", + verifiedBy: "reviewer@example.test", + verifiedAt: "2026-08-02T21:00:00.000Z", + }, + ...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("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", + }, + }, + ], + }, + }); + 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", () => { + 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", + }, + }, + }); + 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, + 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", + }, + }, + }, + }); + 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", () => { + 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/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/lessons-api-pagination.test.ts b/test/lessons-api-pagination.test.ts new file mode 100644 index 0000000000..3890c04b3a --- /dev/null +++ b/test/lessons-api-pagination.test.ts @@ -0,0 +1,116 @@ +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("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"], + ])("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..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", () => { @@ -228,14 +250,93 @@ 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", () => { - 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, @@ -247,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, @@ -261,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 () => { @@ -274,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, @@ -282,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); @@ -297,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, @@ -310,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!); @@ -330,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; @@ -348,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); + }); }); }); 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/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-http.test.ts b/test/mcp-http.test.ts new file mode 100644 index 0000000000..d3c233baae --- /dev/null +++ b/test/mcp-http.test.ts @@ -0,0 +1,280 @@ +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" }] }); + }); + + 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 new file mode 100644 index 0000000000..56ca957831 --- /dev/null +++ b/test/mcp-llm-tools.test.ts @@ -0,0 +1,125 @@ +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, + accessContext: expect.objectContaining({ + mode: "classify", + principalId: "legacy-unresolved", + }), + }, + }); + }); + + 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-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/mcp-standalone-proxy.test.ts b/test/mcp-standalone-proxy.test.ts index dc08a024ee..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,52 @@ 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"]; + }); + + 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("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 () => { @@ -50,7 +99,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..b26498c6ad 100644 --- a/test/mcp-surface-default.test.ts +++ b/test/mcp-surface-default.test.ts @@ -3,11 +3,14 @@ import { readFileSync } from "node:fs"; import { getAllTools, getVisibleTools, + LLM_BACKED_TOOLS, + WORKSTATION_LLM_TOOLS, + 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 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)", () => { @@ -20,7 +23,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); @@ -32,24 +35,59 @@ 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_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); + expect(names.has("memory_reflect")).toBe(false); + }); + + 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); + 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_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); + }); + + 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/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/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/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/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", + }); + }); +}); 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/reflect.test.ts b/test/reflect.test.ts index 7ea163d593..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); + }, }; } @@ -84,7 +93,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 +110,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 +265,227 @@ describe("Reflect", () => { expect(result.success).toBe(true); 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( + ` + +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..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"; @@ -8,7 +15,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>(); @@ -61,10 +70,20 @@ 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-")); }); - function writeFixture(sessionId: string, ts = "2026-04-17T10:00:00.000Z") { + 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", + assistantText = "world", + ) { const dir = join(tmpRoot, "proj"); rmSync(dir, { recursive: true, force: true }); require("node:fs").mkdirSync(dir, { recursive: true }); @@ -87,7 +106,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 +170,154 @@ 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("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( + "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}$/), + ]); + }); + + 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/session-context.test.ts b/test/session-context.test.ts new file mode 100644 index 0000000000..40f1a7ca26 --- /dev/null +++ b/test/session-context.test.ts @@ -0,0 +1,115 @@ +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", + updatedAt: "2026-01-02T00: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"], + updatedAt: "2026-01-02T00:00:00Z", + }); + expect(result.context.contextUpdatedAt).toEqual(expect.any(String)); + 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-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"/, ); }); }); 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/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); + }); +}); diff --git a/test/smart-search.test.ts b/test/smart-search.test.ts index 9d0c94e0c0..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,69 @@ 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 () => { + sdk.registerFunction("mem::lesson-recall", async () => ({ + success: true, + lessons: [ + { + 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, + }, + { + lessonId: "lsn_contradicted", + content: "This claim has an active counterexample.", + claim: "All retries are idempotent.", + evidenceVerdict: "supported", + contradicted: true, + 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 () => { @@ -261,6 +311,8 @@ describe("Smart Search Function", () => { expect(receivedPayload).toMatchObject({ query: "rebase", project: "gitops-assistant", + retrievalMode: "hybrid", + compact: true, }); }); 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, + }); + }); +}); 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/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({ diff --git a/test/tool-count-consistency.test.ts b/test/tool-count-consistency.test.ts index 6e845df064..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 = 53; +const EXPECTED_TOOL_COUNT = 60; 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( - "(default: all = ${ALL_TOOLS_COUNT} tools; core = ${CORE_TOOLS_COUNT} essentials)", + "workstation-llm = curated + 7 LLM tools", ); expect(cli).not.toMatch(/all\s*=\s*51 tools/); }); 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; diff --git a/test/viewer-lessons-schema.test.ts b/test/viewer-lessons-schema.test.ts new file mode 100644 index 0000000000..aa83c97fac --- /dev/null +++ b/test/viewer-lessons-schema.test.ts @@ -0,0 +1,85 @@ +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"); + 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"); + 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("lessonFacetEntries(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"); + }); + + 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"); + }); +}); 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"); + }); +}); 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) => ({
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 += renderLessonFacets(l.structuredFacets); + 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) + '