loopctl-mcp-server 2.35.0 → 2.37.0

package/README.md

@@ -121,7 +121,7 @@ REST endpoint (`PATCH /api/v1/tenants/me/llm-config`), and the docs — so you (
 autonomous agent) can self-remediate without a human. Full agent-tenant lifecycle:
 [`docs/onboarding-agent-tenant.md`](../docs/onboarding-agent-tenant.md).
 
-## Tools (73)
+## Tools (82)
 
 ### Project Tools
 
@@ -217,6 +217,23 @@ autonomous agent) can self-remediate without a human. Full agent-tenant lifecycl
 | `knowledge_okf_export` | **Requires `LOOPCTL_USER_KEY`.** Export the wiki as a portable OKF (Open Knowledge Format) v0.1 bundle of markdown files. Writes to `out_dir`, or returns `{files, meta}` inline. |
 | `knowledge_okf_import` | **Requires `LOOPCTL_USER_KEY`.** Import an OKF v0.1 bundle from a local directory. Creates or (with `merge`) updates articles; tolerates and preserves unknown frontmatter. |
 
+### Agent Memory Tools (agent key)
+
+`memory_*` is YOUR OWN scoped, private, accumulated working state — running notes, in-flight
+task context, recall across sessions — NOT the shared knowledge wiki. Use `memory_*` for that
+private per-scope state; use `knowledge_*` for curated knowledge other agents should see. Scope
+(`tenant_id`/`subject_id`) is resolved server-side from your API key — none of these tools accept
+a `tenant_id`/`subject_id`, so there is no NON-SUPERADMIN way to read or write into another
+scope. (The one carve-out: `memory_list`'s `all_subjects` boolean IS a cross-subject read, but
+it is enforced server-side and a no-op for a non-superadmin key — see below.)
+
+| Tool | Description |
+|---|---|
+| `memory_remember` | Write to your own working memory. `tier` selects the substrate: `long_term` (default; requires `text`, embedded asynchronously and later recalled by semantic similarity via `memory_recall`) or `session` (short-term; requires `session_id`, `content`, `expires_at` — pruned after expiry, not semantically recalled). Returns 201 with the stored memory. Optional: `confidence`, `tags`, `source_session_id`, `metadata` (long-term); `role` (session). |
+| `memory_recall` | Semantically recall your own long-term memories most similar to `query`. When embedding generation is unavailable the response degrades to a recent-first text match with `meta.fallback: true` and a stable `meta.reason` (score is `null` on that path) — check `meta.fallback` before treating a short/empty result as a genuinely empty scope. `meta.total_count`/`meta.underfilled` are also returned. Optional: `limit`, `include_superseded`. |
+| `memory_list` | List your own long-term memories, newest first, paginated with `meta.total_count/limit/offset` (the true scoped count, never silently capped by `limit`). Optional: `limit`, `offset`, `include_superseded`, `all_subjects` (superadmin only; ignored for non-superadmin keys). |
+| `memory_forget` | Delete one of your own long-term memories by id. A foreign-subject, foreign-tenant, or unknown id returns 404 (no existence leak). Required: `id`. |
+
 ### Knowledge Management Tools (orchestrator key)
 
 | Tool | Description |

package/index.js

@@ -18,6 +18,7 @@ import {
   projectsPath,
   ingestionJobsPath,
   llmUsagePath,
+  memoryPath,
   parseJsonResponseBody,
 } from "./lib/http-helpers.js";
 import {
@@ -1064,6 +1065,100 @@ async function knowledgeCreate({
   return toContent(result);
 }
 
+// --- Agent Memory Tools (US-28.4) ---
+//
+// memory_* is YOUR own scoped, private, accumulated working state — recall
+// across sessions, running notes, in-flight task context. knowledge_* is the
+// curated, shared wiki. Scope (tenant_id/subject_id) is resolved SERVER-SIDE
+// from the API key (US-28.3) — these tools never accept or forward a
+// tenant_id/subject_id, so there is no NON-SUPERADMIN way to express a
+// cross-scope read/write here even by mistake. (The one carve-out:
+// memory_list's `all_subjects` boolean IS a cross-subject read, but it is
+// enforced server-side and a no-op for a non-superadmin key — see its
+// description below.) Routes through the shared apiCall/witness client
+// (same as every other write tool), so witness/STH persistence + the
+// transparent 412 self-heal on a fresh MCP process apply automatically
+// (AC-28.4.3) — no bespoke witness code needed.
+
+async function memoryRemember({
+  tier,
+  text,
+  confidence,
+  tags,
+  source_session_id,
+  session_id,
+  role,
+  content,
+  expires_at,
+  metadata,
+}) {
+  const payload = {};
+  if (tier) payload.tier = tier;
+  if (text != null) payload.text = text;
+  if (confidence != null) payload.confidence = confidence;
+  if (tags) payload.tags = tags;
+  if (source_session_id) payload.source_session_id = source_session_id;
+  if (session_id) payload.session_id = session_id;
+  if (role) payload.role = role;
+  if (content != null) payload.content = content;
+  if (expires_at) payload.expires_at = expires_at;
+  if (metadata != null) payload.metadata = metadata;
+
+  const result = await apiCall(
+    "POST",
+    "/api/v1/memory",
+    payload,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function memoryRecall({ query, limit, include_superseded }) {
+  const payload = { query };
+  if (limit != null) payload.limit = limit;
+  if (include_superseded != null) payload.include_superseded = include_superseded;
+
+  const result = await apiCall(
+    "POST",
+    "/api/v1/memory/recall",
+    payload,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  // Surface meta (fallback/reason/total_count/underfilled) so the caller can tell
+  // a degraded recall from a genuinely empty scope (AC-28.4.4) — toContent already
+  // preserves the full result (data + meta), we just keep this call explicit.
+  return toContent(result);
+}
+
+async function memoryList({ limit, offset, include_superseded, all_subjects }) {
+  // all_subjects is superadmin-only server-side; a non-superadmin key sending
+  // this is ignored (falls back to its own subject) rather than erroring — the
+  // one deliberate cross-subject read this MCP surface can express (module
+  // comment above), and only for a superadmin caller.
+  const path = memoryPath({ limit, offset, include_superseded, all_subjects });
+  const result = await apiCall("GET", path, null, process.env.LOOPCTL_AGENT_KEY);
+  // Surface meta.total_count/limit/offset (AC-28.4.4).
+  return toContent(result);
+}
+
+async function memoryForget({ id }) {
+  // Path-injection guard (mirrors knowledgeAgentUsage's UUID_RE check below).
+  if (typeof id !== "string" || !UUID_RE.test(id)) {
+    return {
+      content: [{ type: "text", text: "Error: id must be a canonical UUID (8-4-4-4-12 hex)." }],
+      isError: true,
+    };
+  }
+
+  const result = await apiCall(
+    "DELETE",
+    `/api/v1/memory/${id}`,
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
 // --- Knowledge Management Tools (orch key) ---
 
 async function knowledgePublish({ article_id }) {
@@ -1690,6 +1785,71 @@ async function signup({ name, slug, email }) {
   return toContent(result);
 }
 
+// US-26.7.2: opt-in WebAuthn trust-tier upgrade ceremony (agent_rooted ->
+// human_anchored) + authenticator revocation. All four require the EXACT
+// user-role key (LOOPCTL_USER_KEY) + ownership of `tenant_id` — mirroring
+// set_llm_config's exactKey:true pattern, since these mutate the tenant's
+// root of trust. NOT headless: completing enrollment/revocation requires an
+// INTERACTIVE WebAuthn client (a browser or a native FIDO2 library) with a
+// human present to touch the hardware authenticator — an agent alone cannot
+// produce a valid attestation or assertion, by design (see
+// docs/chain-of-custody-v2.md §9).
+async function requestAuthenticatorChallenge({ tenant_id }) {
+  const result = await apiCall(
+    "POST",
+    `/api/v1/tenants/${tenant_id}/authenticators/challenge`,
+    {},
+    process.env.LOOPCTL_USER_KEY,
+    { exactKey: true },
+  );
+  return toContent(result);
+}
+
+async function enrollAuthenticator({
+  tenant_id,
+  challenge_id,
+  attestation_object,
+  client_data_json,
+  credential_id,
+  friendly_name,
+  reauth_assertion,
+}) {
+  const body = { challenge_id, attestation_object, client_data_json, credential_id };
+  if (friendly_name != null) body.friendly_name = friendly_name;
+  if (reauth_assertion != null) body.reauth_assertion = reauth_assertion;
+
+  const result = await apiCall(
+    "POST",
+    `/api/v1/tenants/${tenant_id}/authenticators`,
+    body,
+    process.env.LOOPCTL_USER_KEY,
+    { exactKey: true },
+  );
+  return toContent(result);
+}
+
+async function requestAuthenticatorRevokeChallenge({ tenant_id }) {
+  const result = await apiCall(
+    "POST",
+    `/api/v1/tenants/${tenant_id}/authenticators/revoke-challenge`,
+    {},
+    process.env.LOOPCTL_USER_KEY,
+    { exactKey: true },
+  );
+  return toContent(result);
+}
+
+async function revokeAuthenticator({ tenant_id, authenticator_id, webauthn_assertion }) {
+  const result = await apiCall(
+    "DELETE",
+    `/api/v1/tenants/${tenant_id}/authenticators/${authenticator_id}`,
+    { webauthn_assertion },
+    process.env.LOOPCTL_USER_KEY,
+    { exactKey: true },
+  );
+  return toContent(result);
+}
+
 // US-26: Signed Tree Head retrieval
 async function getSth({ tenant_id }) {
   const result = await apiCall("GET", `/api/v1/audit/sth/${tenant_id}`);
@@ -2987,6 +3147,158 @@ const TOOLS = [
     },
   },
 
+  // Agent Memory Tools (US-28.4)
+  {
+    name: "memory_remember",
+    description:
+      "Write to YOUR OWN scoped, private, accumulated working memory — running notes, " +
+      "in-flight task state, decisions you made this session — NOT the shared knowledge " +
+      "wiki. Use memory_* for private per-scope working state across sessions; use " +
+      "knowledge_* for curated, shared knowledge articles other agents should see. Scope " +
+      "(tenant_id/subject_id) is resolved server-side from your API key — never pass or " +
+      "expect a tenant_id/subject_id here; there is no way to write into another scope. " +
+      "`tier` selects the substrate: `long_term` (default; requires `text`, embedded " +
+      "asynchronously and later recalled by semantic similarity via memory_recall) or " +
+      "`session` (short-term; requires `session_id`, `content`, `expires_at` — pruned " +
+      "after expiry, not semantically recalled). Returns 201 with the stored memory.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tier: {
+          type: "string",
+          enum: ["long_term", "session"],
+          description: "Memory substrate. Defaults to long_term.",
+        },
+        text: {
+          type: "string",
+          description: "Long-term memory content (required when tier=long_term).",
+        },
+        confidence: {
+          type: "number",
+          description: "Optional: confidence score (0.0-1.0) for a long-term memory.",
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional: tags for a long-term memory.",
+        },
+        source_session_id: {
+          type: "string",
+          description: "Optional: the session this long-term memory was distilled from.",
+        },
+        session_id: {
+          type: "string",
+          description: "Session identifier (required when tier=session).",
+        },
+        role: {
+          type: "string",
+          enum: ["user", "assistant", "system", "fact"],
+          description: "Optional: speaker role for a session-tier turn.",
+        },
+        content: {
+          type: "string",
+          description: "Session turn content (required when tier=session).",
+        },
+        expires_at: {
+          type: "string",
+          format: "date-time",
+          description: "Prune deadline (required when tier=session).",
+        },
+        metadata: {
+          type: "object",
+          description: "Optional: arbitrary structured metadata to attach to the memory.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "memory_recall",
+    description:
+      "Semantically recall YOUR OWN long-term memories most similar to `query` — private, " +
+      "scoped working state, NOT the shared knowledge wiki. Use memory_* for your scoped, " +
+      "private, accumulated working state across sessions; use knowledge_* for curated, " +
+      "shared knowledge articles. Scope is resolved server-side from your API key. When " +
+      "embedding generation is unavailable the response degrades to a recent-first text " +
+      "match with `meta.fallback: true` and a stable `meta.reason` (score is null on that " +
+      "path) — check meta.fallback before treating a short/empty result as a genuinely " +
+      "empty scope. `meta.total_count` and `meta.underfilled` are also returned so you can " +
+      "distinguish a short page from a hard cap.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Text to embed / match against.",
+        },
+        limit: {
+          type: "integer",
+          description: "Optional: max results, clamped to the vector-search max (no silent hard cap).",
+        },
+        include_superseded: {
+          type: "boolean",
+          description: "Optional: include superseded memories (default false).",
+        },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "memory_list",
+    description:
+      "List YOUR OWN long-term memories, newest first — private, scoped working state, " +
+      "NOT the shared knowledge wiki. Use memory_* for your scoped, private, accumulated " +
+      "working state across sessions; use knowledge_* for curated, shared knowledge " +
+      "articles. Scope is resolved server-side from your API key. Paginated with " +
+      "`meta.total_count/limit/offset` (the true scoped count, never silently capped by " +
+      "limit) so you can distinguish an empty scope from a short page.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "integer",
+          description: "Optional: page size (default 50, max 200).",
+        },
+        offset: {
+          type: "integer",
+          description: "Optional: records to skip (default 0).",
+        },
+        include_superseded: {
+          type: "boolean",
+          description: "Optional: include superseded memories (default false).",
+        },
+        all_subjects: {
+          type: "boolean",
+          description:
+            "Optional, superadmin only: list all subjects' memories in the tenant. Ignored " +
+            "(falls back to your own subject) for non-superadmin keys.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "memory_forget",
+    description:
+      "Delete one of YOUR OWN long-term memories by id — private, scoped working state, " +
+      "NOT the shared knowledge wiki. Use memory_* for your scoped, private, accumulated " +
+      "working state; use knowledge_* for curated, shared knowledge articles (delete those " +
+      "with knowledge_delete). Scope is resolved server-side from your API key: a foreign-" +
+      "subject, foreign-tenant, or unknown id returns 404 (no existence leak) rather than " +
+      "revealing whether it exists in another scope.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          format: "uuid",
+          description: "The UUID of the memory to forget.",
+        },
+      },
+      required: ["id"],
+    },
+  },
+
   // Knowledge Management Tools (orchestrator key)
   {
     name: "knowledge_publish",
@@ -3892,6 +4204,114 @@ const TOOLS = [
       required: ["name", "slug", "email"],
     },
   },
+  {
+    name: "request_authenticator_challenge",
+    description:
+      "Step 1 of the opt-in WebAuthn trust-tier upgrade ceremony (US-26.7.2): issues a " +
+      "registration challenge for enrolling a hardware authenticator against an EXISTING " +
+      "agent_rooted (KB-tier) tenant, promoting it to human_anchored on success. " +
+      "IMPORTANT: completing this ceremony requires an INTERACTIVE WebAuthn client " +
+      "(a browser calling navigator.credentials.create(), or a native FIDO2 library) " +
+      "with a HUMAN present to physically touch the authenticator — an agent alone " +
+      "cannot produce a valid attestation, by design. Use this tool to fetch the " +
+      "challenge/rp/user/pubKeyCredParams payload, drive the WebAuthn ceremony in your " +
+      "interactive client, then call enroll_authenticator with the result. If the " +
+      "tenant is already human_anchored, the response includes reauth_required: true " +
+      "plus a reauth_challenge — enroll_authenticator will need a fresh assertion from " +
+      "an EXISTING authenticator too (see enroll_authenticator's description). Requires " +
+      "LOOPCTL_USER_KEY (user role) bound to tenant_id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tenant_id: { type: "string", description: "Tenant UUID to enroll an authenticator for." },
+      },
+      required: ["tenant_id"],
+    },
+  },
+  {
+    name: "enroll_authenticator",
+    description:
+      "Step 2 of the opt-in WebAuthn trust-tier upgrade ceremony: completes enrollment " +
+      "with the attestation produced by navigator.credentials.create() against the " +
+      "challenge from request_authenticator_challenge. On a tenant's FIRST enrollment " +
+      "(zero prior authenticators) this call FLIPS the tenant from agent_rooted to " +
+      "human_anchored, unlocking the work-breakdown / chain-of-custody surface " +
+      "(projects, stories, dispatch, ...). On a SUBSEQUENT (backup) enrollment for an " +
+      "already human_anchored tenant, `reauth_assertion` (a fresh WebAuthn assertion " +
+      "from an EXISTING enrolled authenticator, from the challenge's reauth_challenge) " +
+      "is REQUIRED — omitting it when required returns 401 reauth_required. All " +
+      "binary fields are base64url encoded. Requires LOOPCTL_USER_KEY (user role) " +
+      "bound to tenant_id. Cannot be completed by an agent alone — see " +
+      "request_authenticator_challenge.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tenant_id: { type: "string", description: "Tenant UUID." },
+        challenge_id: {
+          type: "string",
+          description: "challenge_id from request_authenticator_challenge.",
+        },
+        attestation_object: { type: "string", description: "Base64url attestation object." },
+        client_data_json: { type: "string", description: "Base64url raw client data JSON." },
+        credential_id: { type: "string", description: "Base64url credential id." },
+        friendly_name: {
+          type: "string",
+          description: "Operator-supplied label (1..120 chars, default \"Authenticator\").",
+        },
+        reauth_assertion: {
+          type: "object",
+          description:
+            "Required ONLY when enrolling a backup authenticator on an already " +
+            "human_anchored tenant: a fresh assertion (challenge_id, credential_id, " +
+            "authenticator_data, signature, client_data_json — all base64url) from an " +
+            "EXISTING enrolled authenticator, bound to the reauth_challenge returned by " +
+            "request_authenticator_challenge.",
+        },
+      },
+      required: ["tenant_id", "challenge_id", "attestation_object", "client_data_json", "credential_id"],
+    },
+  },
+  {
+    name: "request_authenticator_revoke_challenge",
+    description:
+      "Issues a fresh-assertion challenge to authorize revoking one of a tenant's " +
+      "enrolled WebAuthn authenticators. Requires an INTERACTIVE WebAuthn client + " +
+      "human touch to produce the assertion revoke_authenticator needs — an agent " +
+      "alone cannot authorize a revocation. Requires LOOPCTL_USER_KEY (user role) " +
+      "bound to tenant_id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tenant_id: { type: "string", description: "Tenant UUID." },
+      },
+      required: ["tenant_id"],
+    },
+  },
+  {
+    name: "revoke_authenticator",
+    description:
+      "Revokes an enrolled authenticator using the assertion from " +
+      "request_authenticator_revoke_challenge (navigator.credentials.get() against an " +
+      "EXISTING authenticator — human touch required). Refuses (409 last_authenticator) " +
+      "to remove a human_anchored tenant's LAST authenticator — there is no " +
+      "auto-downgrade; losing every authenticator is a fatal, human-recovery-only event " +
+      "(docs/chain-of-custody-v2.md §9.3). Requires LOOPCTL_USER_KEY (user role) bound " +
+      "to tenant_id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tenant_id: { type: "string", description: "Tenant UUID." },
+        authenticator_id: { type: "string", description: "UUID of the authenticator to revoke." },
+        webauthn_assertion: {
+          type: "object",
+          description:
+            "The assertion (challenge_id, credential_id, authenticator_data, signature, " +
+            "client_data_json — all base64url) bound to the revoke-challenge.",
+        },
+      },
+      required: ["tenant_id", "authenticator_id", "webauthn_assertion"],
+    },
+  },
   {
     name: "get_sth",
     description: "Get the latest Signed Tree Head for a tenant's audit chain. Public — no auth required.",
@@ -4090,6 +4510,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_create":
       return await knowledgeCreate(args);
 
+    // Agent Memory Tools
+    case "memory_remember":
+      return await memoryRemember(args);
+
+    case "memory_recall":
+      return await memoryRecall(args);
+
+    case "memory_list":
+      return await memoryList(args);
+
+    case "memory_forget":
+      return await memoryForget(args);
+
     // Knowledge Management Tools
     case "knowledge_publish":
       return await knowledgePublish(args);
@@ -4182,6 +4615,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "signup":
       return await signup(args);
 
+    case "request_authenticator_challenge":
+      return await requestAuthenticatorChallenge(args);
+
+    case "enroll_authenticator":
+      return await enrollAuthenticator(args);
+
+    case "request_authenticator_revoke_challenge":
+      return await requestAuthenticatorRevokeChallenge(args);
+
+    case "revoke_authenticator":
+      return await revokeAuthenticator(args);
+
     case "get_sth":
       return await getSth(args);
 

package/lib/http-helpers.js

@@ -68,6 +68,24 @@ export function llmUsagePath({ from, to, limit, offset } = {}) {
   ])}`;
 }
 
+/**
+ * Path for `memory_list`, honoring limit/offset/include_superseded/all_subjects
+ * (US-28.4). Routes through the shared `buildQuery` helper (rather than a local
+ * `URLSearchParams` mirror) so the query-string construction is exercised by the
+ * SAME code the server ships.
+ *
+ * @param {{ limit?: number, offset?: number, include_superseded?: boolean, all_subjects?: boolean }} [args]
+ * @returns {string}
+ */
+export function memoryPath({ limit, offset, include_superseded, all_subjects } = {}) {
+  return `/api/v1/memory${buildQuery([
+    ["limit", limit],
+    ["offset", offset],
+    ["include_superseded", include_superseded],
+    ["all_subjects", all_subjects],
+  ])}`;
+}
+
 /**
  * Defensively parse the raw text body of a JSON-content-type HTTP response
  * (#249, mcp-03).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.35.0",
+  "version": "2.37.0",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",