loopctl-mcp-server 2.41.0 → 2.43.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 (84)
+## Tools (89)
 
 > Plus **per-tenant generated Context Retriever tools** (`cr_*`) appended
 > dynamically at runtime — see [Dynamic per-tenant Context Retriever
@@ -133,6 +133,7 @@ autonomous agent) can self-remediate without a human. Full agent-tenant lifecycl
 |---|---|
 | `get_tenant` | Get current tenant info. Use to verify connectivity. |
 | `list_projects` | List all projects in the current tenant. |
+| `resolve_project` | Resolve a repo to its `project_id` in one cheap call — provide any of `slug`, `repo_url` (`git@github.com:owner/repo.git`, `https://github.com/owner/repo`, and bare `owner/repo` all match), or `name`. Precedence `slug > repo_url > name`, first match wins. Use the returned `id` to scope captures/recall (`memory_*`, `recall_context`). `404` `not_found` if nothing matches, `422` `no_identifier` if none supplied, `409` if a fuzzy identifier matches more than one active project. |
 | `create_project` | Create a new project in the current tenant. |
 | `delete_project` | **Requires `LOOPCTL_USER_KEY`.** Delete a project and all of its dependent resources (epics, stories, audit entries). Irreversible — orchestrator role is not sufficient. |
 | `get_progress` | Get progress summary for a project, including story counts by status. Pass `include_cost=true` for cost data. |
@@ -243,7 +244,9 @@ 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`. |
+| `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 `{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`. |
+| `recall_context` | ONE round-trip returning the re-ranked `global ∪ active-project` union of long-term MEMORY **and** KNOWLEDGE for `query` — what you previously assembled by calling `memory_recall` and `knowledge_search` separately. Pass `project_id` (from `resolve_project`) to merge global with that project on both sides; absent → global-only. The knowledge half is combined-search *summaries* (not full bodies — use `knowledge_context` for those). Response carries merged `results` (each tagged `source: memory\|knowledge`) plus the untouched per-source `memory`/`knowledge` envelopes; `meta.degraded?` flags a one-sided degrade (the other side is still returned — never a 500). A blank query, or one over 500 chars, is a `422` up front. Required: `query`. Optional: `project_id`, `limit`. |
+| `memory_graduate` | Graduate ONE of your long-term memories into a durable Knowledge Wiki article — the explicit, on-demand version of the hourly graduation sweep. Use when a private memory has proven valuable enough to become durable knowledge. **Visibility**: the graduated article stays **owner-visible** (`metadata.visibility: "owner"`, keyed to your subject) — discoverable by YOU, NOT peer-readable (graduation does not share a memory to teammates; `re_scope: "global"` widens only the project scope, not visibility). Scope is key-derived (you can only graduate your OWN memory; a foreign/unknown `memory_id` → 404). DEDUPED by the novelty gate: `data.verdict` is `created` (novel → published) or `gated_to_draft` (near-dup → review draft) with a new article (**201**), or `duplicate`/`deduplicated` (already represented → canonical article, nothing created) (**200**). By default the article inherits the memory's project scope; pass `re_scope: "global"` to promote a PROJECT memory to a tenant-wide article — only valid on its FIRST graduation, and only if the hourly sweep hasn't graduated it project-scoped first (`409` `already_graduated` otherwise). An already-graduated global memory re-graduates idempotently (**200**). `503` `gate_unavailable` if the embedding backend is down — retry later. Required: `memory_id`. Optional: `re_scope` (`inherit`\|`global`). |
 
 ### Knowledge Management Tools (orchestrator key)
 

package/index.js

@@ -376,6 +376,22 @@ async function listProjects(args = {}) {
   return toContent(result);
 }
 
+async function resolveProject({ slug, repo_url, name } = {}) {
+  // Cheap repo -> project_id resolution (loopctl #411 Gap 1). Server tries
+  // slug -> repo_url -> name and returns the first match; agent-role read.
+  const params = new URLSearchParams();
+  if (slug) params.set("slug", slug);
+  if (repo_url) params.set("repo_url", repo_url);
+  if (name) params.set("name", name);
+  const result = await apiCall(
+    "GET",
+    `/api/v1/projects/resolve?${params}`,
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
 async function createProject({ name, slug, repo_url, description, tech_stack, mission }) {
   const body = { name, slug };
   if (repo_url) body.repo_url = repo_url;
@@ -386,6 +402,17 @@ async function createProject({ name, slug, repo_url, description, tech_stack, mi
   return toContent(result);
 }
 
+async function createKbScope({ name, slug, repo_url, description, tech_stack }) {
+  const body = { name, slug };
+  if (repo_url) body.repo_url = repo_url;
+  if (description) body.description = description;
+  if (tech_stack) body.tech_stack = tech_stack;
+  // Uses the AGENT key (not ORCH): a KB scope is agent-createable on the KB tier — that is
+  // the whole point. The server forces kind: :kb; a body-supplied kind is ignored.
+  const result = await apiCall("POST", "/api/v1/kb-scopes", body, process.env.LOOPCTL_AGENT_KEY);
+  return toContent(result);
+}
+
 async function deleteProject({ project_id }) {
   const result = await apiCall(
     "DELETE",
@@ -1206,6 +1233,26 @@ async function memoryRecall({ query, limit, include_superseded }) {
   return toContent(result);
 }
 
+async function recallContext({ query, project_id, limit }) {
+  // Merged recall (#411 Gap 2): ONE round-trip returning the re-ranked
+  // global ∪ active-project union of long-term MEMORY and KNOWLEDGE. Scope
+  // (tenant_id/subject_id) is derived server-side from the agent key; project_id is
+  // the partition key (merges global with that project on BOTH sides).
+  const payload = { query };
+  if (project_id) payload.project_id = project_id;
+  if (limit != null) payload.limit = limit;
+
+  const result = await apiCall(
+    "POST",
+    "/api/v1/recall",
+    payload,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  // Surface both per-source metas (memory fallback/underfilled + knowledge degraded)
+  // so the caller can tell a degraded recall from a genuinely empty scope.
+  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
@@ -1246,6 +1293,24 @@ async function memoryPromote({ session_id }) {
   return toContent(result);
 }
 
+async function memoryGraduate({ memory_id, re_scope }) {
+  // Explicit memory→knowledge graduation (#411 Gap 3). Scope (tenant_id/subject_id)
+  // is derived server-side from the agent key; memory_id identifies the caller's OWN
+  // memory to graduate. The graduated article stays OWNER-visible (not peer-readable).
+  // re_scope: "global" widens only the project partition (project → tenant-wide), NOT
+  // visibility, and only on the memory's first graduation.
+  const payload = { memory_id };
+  if (re_scope) payload.re_scope = re_scope;
+
+  const result = await apiCall(
+    "POST",
+    "/api/v1/memory/graduate",
+    payload,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
 // --- Knowledge Management Tools (orch key) ---
 
 async function knowledgePublish({ article_id }) {
@@ -1998,6 +2063,34 @@ const TOOLS = [
       required: [],
     },
   },
+  {
+    name: "resolve_project",
+    description:
+      "Resolve a repo to its project in one cheap call. Provide any of slug, " +
+      "repo_url (git@github.com:owner/repo.git, https://github.com/owner/repo, " +
+      "and bare owner/repo all match), or name. Precedence: slug > repo_url > " +
+      "name; first match wins. Returns the project (use its id to scope " +
+      "captures/recall), 404 not_found if nothing matches, 422 no_identifier " +
+      "if none supplied.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: {
+          type: "string",
+          description: "Exact project slug (often the repo basename).",
+        },
+        repo_url: {
+          type: "string",
+          description: "Git remote URL or bare owner/repo.",
+        },
+        name: {
+          type: "string",
+          description: "Exact project name (case-insensitive).",
+        },
+      },
+      required: [],
+    },
+  },
   {
     name: "create_project",
     description: "Create a new project in the current tenant.",
@@ -2018,6 +2111,25 @@ const TOOLS = [
       required: ["name", "slug"],
     },
   },
+  {
+    name: "create_kb_scope",
+    description:
+      "Create a knowledge-only project scope (kind: kb) for the current tenant. Unlike create_project (work project, orchestrator+ / human-anchored), this is available to an agent-rooted (KB-tier) tenant with an agent key: a kb scope carries NO chain-of-custody / work-breakdown surface (it cannot host epics/stories/dispatch/ui-tests), it exists only to partition knowledge articles by repo so captured/created articles can be project-scoped. Then resolve_project by its repo_url/slug and pass the returned id as project_id on article/knowledge writes. Counts toward the tenant's max_projects budget.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Scope name (often the repo name)." },
+        slug: { type: "string", description: "URL-safe slug (often the repo basename)." },
+        repo_url: {
+          type: "string",
+          description: "Repo URL, so resolve_project can map a repo to this scope.",
+        },
+        description: { type: "string", description: "Scope description." },
+        tech_stack: { type: "string", description: "Tech stack summary." },
+      },
+      required: ["name", "slug"],
+    },
+  },
   {
     name: "delete_project",
     description:
@@ -3484,6 +3596,45 @@ const TOOLS = [
       required: ["query"],
     },
   },
+  {
+    name: "recall_context",
+    description:
+      "MERGED recall in ONE round-trip: the re-ranked global ∪ active-project union of " +
+      "your long-term MEMORY (private working state) AND the shared KNOWLEDGE wiki for " +
+      "`query` — instead of calling memory_recall and knowledge_context/knowledge_search " +
+      "separately and merging by hand (#411 Gap 2). Both sides merge global with the " +
+      "active project: pass project_id to include that project's rows alongside global " +
+      "ones on BOTH sides (another project's rows are excluded); omit it for global-only. " +
+      "project_id is a PARTITION key, NOT isolation — scope (tenant/subject) is resolved " +
+      "server-side from your key. Returns `data` (merged, each item tagged source: " +
+      "memory|knowledge, sorted by a heuristically-comparable score DESC) PLUS the " +
+      "untouched per-source `memory` and `knowledge` envelopes so you can re-rank. " +
+      "Cross-source scores are heuristic, not calibrated. If the knowledge search " +
+      "degrades (embedding unavailable) or errors, the memory side is still returned and " +
+      "meta.degraded is true — never a hard failure.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Text to embed / match against on BOTH the memory and knowledge sides.",
+        },
+        project_id: {
+          type: "string",
+          format: "uuid",
+          description:
+            "Optional: partition scope. Present → both sides return global ∪ that project; " +
+            "omit → global-only.",
+        },
+        limit: {
+          type: "integer",
+          description:
+            "Optional: overall merged page size, clamped to [1, 50] (default 10).",
+        },
+      },
+      required: ["query"],
+    },
+  },
   {
     name: "memory_list",
     description:
@@ -3562,6 +3713,45 @@ const TOOLS = [
       required: ["session_id"],
     },
   },
+  {
+    name: "memory_graduate",
+    description:
+      "Graduate ONE of your long-term memories into a durable Knowledge Wiki article — the " +
+      "explicit, on-demand version of the hourly graduation sweep. Use when a private memory " +
+      "has proven valuable enough to become durable, curated knowledge. IMPORTANT: the " +
+      "graduated article stays OWNER-VISIBLE (metadata.visibility=owner, keyed to your " +
+      "subject) — discoverable by YOU, NOT peer-readable; graduation does NOT share a memory " +
+      "with teammates, and re_scope only widens project scope, not visibility. Scope " +
+      "(tenant_id/subject_id) is resolved server-side from your API key: you can only " +
+      "graduate your OWN memory; a foreign/unknown memory_id returns 404 (no cross-subject " +
+      "leak). By default the article inherits the memory's project scope; pass " +
+      're_scope: "global" to promote a PROJECT memory to a tenant-wide (global) article — ' +
+      "only valid on the memory's FIRST graduation (re_scope: global on an already-graduated " +
+      "PROJECT memory returns 409 already_graduated; on an already-graduated GLOBAL memory it " +
+      "is an idempotent no-op → 200). The article is DEDUPED by the novelty gate: the " +
+      'response `data.verdict` is "created" (novel → published) or "gated_to_draft" ' +
+      '(near-duplicate → review draft) with a new article, or "duplicate"/"deduplicated" ' +
+      "(content already represented → the canonical article, nothing created). Returns 503 " +
+      "gate_unavailable if the embedding backend is down — retry later.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        memory_id: {
+          type: "string",
+          description: "UUID of your own long-term memory to graduate into a knowledge article.",
+        },
+        re_scope: {
+          type: "string",
+          enum: ["inherit", "global"],
+          description:
+            'Article scope. "inherit" (default) keeps the memory\'s project scope; ' +
+            '"global" promotes a PROJECT memory to a tenant-wide (global) article ' +
+            "(only on its first graduation).",
+        },
+      },
+      required: ["memory_id"],
+    },
+  },
 
   // Knowledge Management Tools (orchestrator key)
   {
@@ -4694,9 +4884,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "list_projects":
       return await listProjects(args);
 
+    case "resolve_project":
+      return await resolveProject(args);
+
     case "create_project":
       return await createProject(args);
 
+    case "create_kb_scope":
+      return await createKbScope(args);
+
     case "delete_project":
       return await deleteProject(args);
 
@@ -4833,6 +5029,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
     case "memory_recall":
       return await memoryRecall(args);
+    case "recall_context":
+      return await recallContext(args);
 
     case "memory_list":
       return await memoryList(args);
@@ -4843,6 +5041,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "memory_promote":
       return await memoryPromote(args);
 
+    case "memory_graduate":
+      return await memoryGraduate(args);
+
     // Knowledge Management Tools
     case "knowledge_publish":
       return await knowledgePublish(args);

package/package.json

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