loopctl-mcp-server 2.37.0 → 2.39.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 (82)
+## Tools (84)
 
 ### Project Tools
 
@@ -214,6 +214,7 @@ autonomous agent) can self-remediate without a human. Full agent-tenant lifecycl
 | `knowledge_conflicts` | List potential-conflict article pairs — published articles flagged "too similar to comfortably coexist" by the auto-linker / nightly lint sweep, highest-overlap first. The KB only FLAGS the pair; it does NOT decide redundancy-vs-contradiction — that's your call with live context. Each entry has both articles (id/title/status/category) + similarity. Then merge (supersede one, `knowledge_create` the merged article, or PATCH) or reconcile if they genuinely disagree. Paginated with `total_count` in meta. Agent role. Optional: `limit` (default 50, max 1000, clamped), `offset`. |
 | `knowledge_resolve_conflict` | Record YOUR verdict on a potential-conflict pair (from `knowledge_conflicts`). Dispositions: `dismiss` (false positive, drops from queue), `supersede` (one wins — pass `authoritative_article_id`; nightly executor links + retires loser, only at `confidence:"high"`, reversible/audited), `merge` (at high confidence an LLM synthesizes both into ONE new DRAFT, sources preserved, never auto-published). Non-destructive at agent role — you record intent, the privileged nightly job executes. Last-write-wins per pair. Required: `source_article_id`, `target_article_id`, `disposition`. Optional: `authoritative_article_id`, `classification`, `evidence`, `confidence`. |
 | `knowledge_create` | Create a new knowledge article. File findings, document patterns, or record decisions. **Published immediately by default** (visible per `metadata.visibility` — default `owner` for agent authors, only visible to that agent; `shared` for visibility to all agents) — the response `note` says which outcome occurred. Pass `draft: true` to stage it for later review instead (publish afterwards with `knowledge_publish`). Pass `metadata: {visibility: "shared"}` to make the article visible to other agents; higher roles can set visibility and agent_id explicitly. Pass `idempotency_key` for idempotent capture (re-creating with the same key is a no-op returning the existing article — no partial duplicates). Optional: `category`, `tags`, `project_id`, `draft`, `idempotency_key`, `source_type`, `source_id`, `metadata`. |
+| `knowledge_update` | Edit an EXISTING article IN PLACE, **preserving its ID** (IDs are load-bearing — cited in project CLAUDE.mds and cross-links). Fold in a new fact, tidy a hub, retag, or reclassify without churning a new row. Send only the fields to change; `tags` REPLACES the whole array. A changed body/tags re-triggers embedding + auto-linking. Agent role — KB-content curation (reversible + audited); visibility-scoped, so another agent's private/owner memory 404s. Required: `article_id`. Optional: `title`, `body`, `category`, `tags`, `metadata`. |
 | `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. |
 
@@ -233,6 +234,7 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | `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`. |
+| `memory_promote` | Call at session end to compile this session's short-term (`session`-tier) memory into durable `long_term` memory — unlike `memory_remember` (a single explicit write), this compiles the whole session in one shot; fire it once at session end, not per turn. Returns 202 with `{job_id, session_id, status: "enqueued"}` — promotion runs asynchronously, so the resulting memory is recallable via `memory_recall` only after the worker drains. You can only promote your own sessions (scope resolved server-side from your key). Required: `session_id`. |
 
 ### Knowledge Management Tools (orchestrator key)
 
@@ -242,8 +244,8 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | `knowledge_bulk_publish` | **Requires `LOOPCTL_USER_KEY`.** Publish drafts, partial-success style: every valid draft publishes; others are reported per-id as `skipped` (already published — idempotent — or archived/superseded), `not_found`, or `errored`. No 100-id cap (auto-chunked); duplicates ignored; safe to retry. `meta.count` = published; `meta.counts`/`meta.results` give the breakdown. Required: `article_ids` (array). |
 | `knowledge_unpublish` | **Requires `LOOPCTL_USER_KEY`.** Revert a published article back to draft (hidden from search/context, not deleted). Required: `article_id`. |
 | `knowledge_bulk_unpublish` | **Requires `LOOPCTL_USER_KEY`.** Revert published articles to draft in bulk, partial-success style (mirror of `knowledge_bulk_publish`): per-id `unpublished`/`skipped` (already draft, or archived/superseded)/`not_found`/`errored`. No 100-id cap (auto-chunked, ≤5000); duplicates ignored; safe to retry. Not deleted (re-publish to restore; `knowledge_bulk_delete` to archive). `meta.count`/`meta.counts`/`meta.results` give the breakdown. Required: `article_ids` (array). |
-| `knowledge_archive` | **Requires `LOOPCTL_USER_KEY`.** Soft-delete an article (draft or published). Row retained for audit; hidden from all reads. Required: `article_id`. |
-| `knowledge_delete` | **Requires `LOOPCTL_USER_KEY`.** Alias for `knowledge_archive` — DELETE verb on the REST API archives under the hood. Required: `article_id`. |
+| `knowledge_archive` | Soft-delete an article (draft or published). Row retained for audit; hidden from all reads (reversible — re-publish/edit it back). Agent role — KB-content curation, visibility-scoped (another agent's private/owner memory 404s). Required: `article_id`. |
+| `knowledge_delete` | Alias for `knowledge_archive` — DELETE verb on the REST API archives under the hood (soft delete, reversible, audited). Agent role. (Irreversible HARD delete is `knowledge_bulk_delete hard:true`, which stays `LOOPCTL_USER_KEY`.) Required: `article_id`. |
 | `knowledge_bulk_delete` | **Requires `LOOPCTL_USER_KEY`.** Bulk archive (default, reversible) or IRREVERSIBLE hard-delete by selector. Provide exactly one selector: `article_ids` (list), `source_type`+`source_id` (every active article from a source), or `tag`+`confirm:true` (every active article with the tag — high blast radius). Default = set-based soft archive (idempotent; `meta.count`=archived, `meta.counts`/`meta.results` give the breakdown; ≤5000). **Dry-run** (`dry_run:true`) mutates nothing, returns `meta.would_affect` (with `hard:true` also a single-use `meta.token`, or `meta.confirm_hash` for oversized selectors). **Hard delete** (irreversible): dry-run with `hard:true` for a token, then call again with `hard:true`+`token` to FK-correctly delete the frozen id-set (links first, access events cascade). |
 | `knowledge_drafts` | List draft (unpublished) knowledge articles with pagination. Optional: `limit` (default 20, max 1000 — over-max → 400, no silent clamp), `offset` (default 0), `project_id`. Returns `meta.total_count`. |
 | `knowledge_lint` | Run a lint check on the knowledge wiki to identify stale or low-coverage articles. Optional: `project_id`, `stale_days`, `min_coverage`, `max_per_category` (default 50, max 500). True totals returned in `summary.total_per_category`. |

package/index.js

@@ -1065,6 +1065,26 @@ async function knowledgeCreate({
   return toContent(result);
 }
 
+// In-place edit of an existing article (#331). PATCH preserves the ID; only the
+// provided fields change. Agent role — KB-content curation, visibility-scoped
+// server-side (another agent's private/owner memory 404s).
+async function knowledgeUpdate({ article_id, title, body, category, tags, metadata }) {
+  const payload = {};
+  if (title != null) payload.title = title;
+  if (body != null) payload.body = body;
+  if (category != null) payload.category = category;
+  if (tags != null) payload.tags = tags;
+  if (metadata != null) payload.metadata = metadata;
+
+  const result = await apiCall(
+    "PATCH",
+    `/api/v1/articles/${article_id}`,
+    payload,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
 // --- Agent Memory Tools (US-28.4) ---
 //
 // memory_* is YOUR own scoped, private, accumulated working state — recall
@@ -1159,6 +1179,17 @@ async function memoryForget({ id }) {
   return toContent(result);
 }
 
+async function memoryPromote({ session_id }) {
+  const payload = { session_id };
+  const result = await apiCall(
+    "POST",
+    "/api/v1/memory/promote",
+    payload,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
 // --- Knowledge Management Tools (orch key) ---
 
 async function knowledgePublish({ article_id }) {
@@ -1226,22 +1257,25 @@ async function knowledgeUnpublish({ article_id }) {
   return toContent(result);
 }
 
+// #331: single-article archive is agent-role KB curation (reversible soft delete,
+// audited, visibility-scoped server-side).
 async function knowledgeArchive({ article_id }) {
   const result = await apiCall(
     "POST",
     `/api/v1/articles/${article_id}/archive`,
     null,
-    process.env.LOOPCTL_USER_KEY
+    process.env.LOOPCTL_AGENT_KEY
   );
   return toContent(result);
 }
 
+// #331: soft-delete (archive) is agent-role KB curation, same as knowledge_archive.
 async function knowledgeDelete({ article_id }) {
   const result = await apiCall(
     "DELETE",
     `/api/v1/articles/${article_id}`,
     null,
-    process.env.LOOPCTL_USER_KEY
+    process.env.LOOPCTL_AGENT_KEY
   );
   return toContent(result);
 }
@@ -3146,6 +3180,54 @@ const TOOLS = [
       required: ["title", "body"],
     },
   },
+  {
+    name: "knowledge_update",
+    description:
+      "Edit an EXISTING knowledge article IN PLACE, preserving its ID. Use this to fold a " +
+      "new fact into a canonical article, tidy a hub, retag, or reclassify — WITHOUT " +
+      "creating a new row and churning the article ID (IDs are load-bearing: cited in " +
+      "project CLAUDE.mds and cross-links). Send only the fields you want to change; every " +
+      "field is optional except article_id. `tags` REPLACES the whole array (send the full " +
+      "desired set, not a delta). A changed body/tags re-triggers embedding + auto-linking. " +
+      "Agent role — this is KB-content curation (reversible + audited). Visibility-scoped: " +
+      "you can only edit an article you can see, so another agent's private/owner memory " +
+      "returns 404. `tenant_id` is never accepted. Returns the full updated article. To " +
+      "instead retire/replace an article, use knowledge_archive or knowledge_resolve_conflict.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        article_id: {
+          type: "string",
+          description: "The UUID of the article to edit (preserved across the update).",
+        },
+        title: {
+          type: "string",
+          description: "Optional: new title.",
+        },
+        body: {
+          type: "string",
+          description: "Optional: new body (Markdown). Re-triggers embedding + linking.",
+        },
+        category: {
+          type: "string",
+          description: "Optional: new category.",
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional: REPLACES the whole tags array (send the full desired set).",
+        },
+        metadata: {
+          type: "object",
+          description:
+            "Optional: extensible JSONB (merged/replaced wholesale). For an agent key, an " +
+            "agent-memory `agent_id` is stamped from your verified key identity — you cannot " +
+            "re-attribute a memory to another agent.",
+        },
+      },
+      required: ["article_id"],
+    },
+  },
 
   // Agent Memory Tools (US-28.4)
   {
@@ -3298,6 +3380,29 @@ const TOOLS = [
       required: ["id"],
     },
   },
+  {
+    name: "memory_promote",
+    description:
+      "Call at session end to compile this session's short-term memory into durable long-term memory" +
+      " — private, scoped working state, NOT the shared knowledge wiki. Unlike " +
+      "memory_remember, which writes a single explicit fact, this compiles the WHOLE session's " +
+      "session-tier memory in one shot — fire it once at session end, not per turn. Scope " +
+      "(tenant_id/subject_id) is resolved server-side from your API key: you can only promote " +
+      "your OWN sessions. Returns 202 Accepted with `{job_id, session_id, status: \"enqueued\"}` " +
+      "— promotion runs asynchronously via a background worker, so the resulting long-term " +
+      "memory becomes recallable via memory_recall only after that worker drains, not " +
+      "immediately.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        session_id: {
+          type: "string",
+          description: "The session whose short-term memory to compile into long-term memory.",
+        },
+      },
+      required: ["session_id"],
+    },
+  },
 
   // Knowledge Management Tools (orchestrator key)
   {
@@ -3387,9 +3492,10 @@ const TOOLS = [
     name: "knowledge_archive",
     description:
       "Archive an article (soft delete). The article is hidden from search, context, " +
-      "and the index but the row is retained for audit/history. Works for drafts and " +
-      "published articles. REQUIRES LOOPCTL_USER_KEY (user role — orchestrator role is " +
-      "NOT sufficient for this destructive operation).",
+      "and the index but the row is retained for audit/history (reversible — re-publish " +
+      "or edit it back). Works for drafts and published articles. Agent role — KB-content " +
+      "curation. Visibility-scoped: you can only archive an article you can see, so " +
+      "another agent's private/owner memory returns 404.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3406,8 +3512,9 @@ const TOOLS = [
     description:
       "Delete an article. Under the hood this performs the same soft-delete (archive) " +
       "as knowledge_archive — use whichever name is clearer at the call site. The row " +
-      "is retained for audit; there is no hard delete. REQUIRES LOOPCTL_USER_KEY (user " +
-      "role — orchestrator role is NOT sufficient for this destructive operation).",
+      "is retained for audit; there is no hard delete (that is knowledge_bulk_delete " +
+      "hard:true, which stays user-gated). Agent role — KB-content curation, reversible + " +
+      "audited, visibility-scoped (another agent's private/owner memory 404s).",
     inputSchema: {
       type: "object",
       properties: {
@@ -4510,6 +4617,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_create":
       return await knowledgeCreate(args);
 
+    case "knowledge_update":
+      return await knowledgeUpdate(args);
+
     // Agent Memory Tools
     case "memory_remember":
       return await memoryRemember(args);
@@ -4523,6 +4633,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "memory_forget":
       return await memoryForget(args);
 
+    case "memory_promote":
+      return await memoryPromote(args);
+
     // Knowledge Management Tools
     case "knowledge_publish":
       return await knowledgePublish(args);

package/package.json

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