loopctl-mcp-server 2.52.0 → 2.54.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 (96)
+## Tools (109)
 
 > Plus **per-tenant generated Context Retriever tools** (`cr_*`) appended
 > dynamically at runtime — see [Dynamic per-tenant Context Retriever
@@ -297,7 +297,7 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | Tool | Description |
 |---|---|
 | `llm_config` | **Check your onboarding status.** Get the tenant's BYO LLM config: per-operation models and whether each key is set — `has_api_key` (Anthropic) / `has_embedding_key` (OpenAI embedding) — plus masked last-4 hints. Never returns a key. Requires **user** key. |
-| `set_llm_config` | **First-time setup (do once).** Set/rotate the tenant's OWN **Anthropic `api_key`** (powers ingest) AND **OpenAI `embedding_api_key`** (powers semantic search) — both stored encrypted, never returned — plus the per-operation models (`extraction_model`/`classification_model`/`merge_model`/`embedding_model`). Any subset; partial-merge (omitting a key leaves it untouched). See [First-time setup](#first-time-setup--provision-your-byo-llm-keys). Requires **user** key. |
+| `set_llm_config` | **First-time setup (do once).** Set/rotate the tenant's OWN **Anthropic `api_key`** (powers ingest) AND **OpenAI `embedding_api_key`** (powers semantic search) — both stored encrypted, never returned — plus the per-operation models (`extraction_model`/`classification_model`/`merge_model`/`embedding_model`). Any subset; partial-merge (omitting a key leaves it untouched). **Private tier (US-41.3):** also sets `chat_provider` (`anthropic` | `openai_compatible`), `chat_base_url`, `extraction_model` (required on that provider) and `chat_api_key` (optional — omit it for a keyless local server) so ingest extraction / classification / merge / memory promotion run against YOUR OWN OpenAI-compatible endpoint and document text never leaves your boundary. Every model the config resolves to is PROBED with a trivial completion before it is saved (a 422 persists nothing); the probe re-runs on any chat-surface change (provider, base_url, key rotation, model), a private-range host is refused by the SSRF guard, and moving to a NEW host needs a matching `chat_api_key` or `acknowledge_key_transmission: true`. See [First-time setup](#first-time-setup--provision-your-byo-llm-keys). Requires **user** key. |
 | `knowledge_llm_usage` | Per-tenant LLM token-usage summary, grouped by operation + model + source_type + day over an optional `from`/`to` range (defaults to a 90-day lookback; effective window echoed in `meta.from`/`meta.to`), with `limit`/`offset` pagination. Record-only (no budget enforcement). Requires orchestrator key. |
 
 ### Knowledge Analytics Tools (orchestrator key)
@@ -311,6 +311,20 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | `knowledge_curation_log` | Concise human-readable log of KB CURATION adjustments — novelty-gate decisions (`gate_duplicate`/`gate_draft`) and conflict resolutions (`supersede`/`merge`/`dismiss`) — for analyzing the agents'-KB rollout, distinct from the verbose audit log. Each entry: `{at, kind, summary, refs, actor, confidence}`. **RECORDED ONLY when `settings.kb_curation_log` is on** (PATCH `/api/v1/admin/tenants/:id` with `settings:{kb_curation_log:true}`); off by default = no rows. Most recent first. Requires orchestrator role. Optional: `kind`, `since` (ISO8601), `limit` (default 50, max 500), `offset`. |
 | `knowledge_retrieval_metrics` | Daily retrieval-PRECISION time series: for each day, the share of search results the agent then opened (search → get/context within a window). A proxy for whether retrieval is improving as the corpus is de-duplicated, better navigated (MOCs), and conflict-resolved. Most recent day first. Requires orchestrator role. Optional: `limit` (default 30, max 365), `offset`. |
 
+### Egress / Privacy Tools (US-41.4)
+
+The fail-closed no-egress guard. `local_only` is **OFF by default everywhere** —
+nothing changes until a scope opts in.
+
+| Tool | Description |
+|---|---|
+| `egress_posture` | **VERIFY BEFORE YOU HARVEST.** This instance's egress posture for your tenant: the resolved embedding + chat endpoints with a locality VERDICT for each (`network-local` / `tenant-declared (unverified attestation), not network-local` / `non-local`), your declared trusted endpoints and their purposes, per-scope `local_only` / `encrypt_body`, and any named posture defects. Endpoints are shown; **keys never are**. Deployment-allowlist CONTENTS appear only at **user**+ — at agent role each endpoint carries only a boolean saying whether its verdict came from the allowlist. Agent key. |
+| `set_local_only` | **TIGHTEN**: mark a scope `local_only`, so loopctl HARD-REFUSES any model-provider call whose resolved endpoint is not classified local. Scope resolution is MOST-RESTRICTIVE-WINS (project OR tenant); a project can never relax a tenant marking. MANDATORY PRE-FLIGHT: refused with **409** `would_block_endpoints` naming every endpoint that would become `egress_blocked`, unless you pass `acknowledge: true`. Requires **orchestrator** key — tightening is safe to automate. |
+| `clear_local_only` | **WIDEN**: remove a scope's `local_only` marking. Requires your **user** key (`LOOPCTL_USER_KEY`) — deliberately not available to an agent or orchestrator, because clearing is the self-widening move an automated key must never make one call before a harvest. Audited with actor + scope. |
+| `declare_trusted_endpoint` | Declare a host you attest is YOUR OWN so a `local_only` scope can reach it. **This is an unverified tenant attestation, not network locality** — labelled as such everywhere. Three enforced constraints: PUBLIC addresses only (write time AND pin time), PURPOSE-SCOPED (`inference` / `webhook` / `ingest`), vendor hosts excluded. Carves nothing out of the SSRF denylist. Requires **user** key. |
+| `revoke_trusted_endpoint` | Revoke a declaration. Invalidation is IMMEDIATE and cluster-wide — a revoked declaration does not keep working for the remainder of the pin TTL. Requires **user** key. |
+| `egress_repin` | Recover from a `:pin_stale` error (your box got a new DHCP lease and the pinned address set changed — DISTINCT from `egress_blocked`). Re-resolves and re-pins the host. **Agent** key by design: requiring a human user-role write to recover would contradict loopctl's agent-native, no-UI design. |
+
 ### Discovery Tools
 
 | Tool | Description |

package/index.js

@@ -1852,6 +1852,10 @@ async function setLlmConfig({
   merge_model,
   embedding_api_key,
   embedding_model,
+  chat_provider,
+  chat_base_url,
+  chat_api_key,
+  acknowledge_key_transmission,
 }) {
   const body = {};
   if (api_key != null) body.api_key = api_key;
@@ -1860,6 +1864,15 @@ async function setLlmConfig({
   if (merge_model !== undefined) body.merge_model = merge_model;
   if (embedding_api_key != null) body.embedding_api_key = embedding_api_key;
   if (embedding_model !== undefined) body.embedding_model = embedding_model;
+  // US-41.3: pluggable OpenAI-compatible chat endpoint. The server PROBES the
+  // endpoint with a trivial completion before persisting, and refuses an endpoint
+  // change that carries neither a matching chat_api_key nor an explicit
+  // acknowledge_key_transmission.
+  if (chat_provider !== undefined) body.chat_provider = chat_provider;
+  if (chat_base_url !== undefined) body.chat_base_url = chat_base_url;
+  if (chat_api_key != null) body.chat_api_key = chat_api_key;
+  if (acknowledge_key_transmission === true)
+    body.acknowledge_key_transmission = true;
   // PATCH (partial-merge) + EXACT user key (review #12, #13).
   const result = await apiCall(
     "PATCH",
@@ -1871,6 +1884,88 @@ async function setLlmConfig({
   return toContent(result);
 }
 
+// --- US-41.4: fail-closed no-egress guard -----------------------------------
+//
+// egress_posture is a READ available at AGENT role: an agent must be able to
+// verify locality with the key it already has, or the whole verify-before-harvest
+// workflow fails. WRITING local_only is asymmetric: ENABLE (tightening) is
+// orchestrator+, CLEAR (widening) is user-only, and declaring a trusted endpoint
+// is user-only. Re-pinning is agent-role on purpose — a home Ollama box or a DHCP
+// VPS changes IP routinely and recovery must not need a human.
+async function egressPosture() {
+  const result = await apiCall(
+    "GET",
+    "/api/v1/egress/posture",
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function setLocalOnly({ project_id, acknowledge } = {}) {
+  const body = {};
+  if (project_id != null) body.project_id = project_id;
+  if (acknowledge === true) body.acknowledge = true;
+  // ENABLE = tightening = orchestrator+.
+  const result = await apiCall(
+    "POST",
+    "/api/v1/egress/local-only",
+    body,
+    process.env.LOOPCTL_ORCH_KEY,
+  );
+  return toContent(result);
+}
+
+async function clearLocalOnly({ project_id } = {}) {
+  // CLEAR = self-widening = EXACT user key. An agent must never be able to
+  // re-open egress one tool call before a harvest.
+  const qs = project_id ? `?project_id=${encodeURIComponent(project_id)}` : "";
+  const result = await apiCall(
+    "DELETE",
+    `/api/v1/egress/local-only${qs}`,
+    null,
+    process.env.LOOPCTL_USER_KEY,
+    { exactKey: true },
+  );
+  return toContent(result);
+}
+
+async function declareTrustedEndpoint({ host, purposes, note } = {}) {
+  const body = { host, purposes };
+  if (note != null) body.note = note;
+  const result = await apiCall(
+    "POST",
+    "/api/v1/egress/trusted-endpoints",
+    body,
+    process.env.LOOPCTL_USER_KEY,
+    { exactKey: true },
+  );
+  return toContent(result);
+}
+
+async function revokeTrustedEndpoint({ host } = {}) {
+  const result = await apiCall(
+    "DELETE",
+    `/api/v1/egress/trusted-endpoints/${encodeURIComponent(host)}`,
+    null,
+    process.env.LOOPCTL_USER_KEY,
+    { exactKey: true },
+  );
+  return toContent(result);
+}
+
+async function egressRepin({ host, project_id } = {}) {
+  const body = { host };
+  if (project_id != null) body.project_id = project_id;
+  const result = await apiCall(
+    "POST",
+    "/api/v1/egress/repin",
+    body,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
 async function knowledgeLlmUsage(args = {}) {
   // Query-string building lives in lib/http-helpers.js so the test suite exercises
   // the same from/to/limit/offset logic the server ships.
@@ -4863,6 +4958,145 @@ const TOOLS = [
   },
 
   // Per-tenant BYO LLM config + usage (Epic 28 residual, #179)
+  {
+    name: "egress_posture",
+    description:
+      "VERIFY BEFORE YOU HARVEST. Reports this instance's egress posture for YOUR tenant: " +
+      "the resolved embedding and chat endpoints, a locality VERDICT for each " +
+      "(network-local / 'tenant-declared (unverified attestation), not network-local' / " +
+      "non-local), your declared trusted endpoints with their purposes, per-scope " +
+      "local_only status, and any named posture defects. Endpoints are shown; KEYS NEVER " +
+      "ARE. Call this BEFORE sending private documents anywhere, instead of trusting that " +
+      "the operator configured things correctly. READ tool, available at AGENT role — the " +
+      "key you already have. NOTE the deployment allowlist CONTENTS are operator " +
+      "infrastructure and are NOT disclosed at agent role: you get only a boolean per " +
+      "endpoint saying whether its verdict came from the allowlist (contents at user+). " +
+      "SCOPE OF THE GUARANTEE: fail-closed enforcement covers every outbound HTTP call " +
+      "made by loopctl application code on the MODEL-PROVIDER path. Webhook delivery is " +
+      "not covered yet (US-41.5), and HTTP performed inside a dependency, plus this " +
+      "separate mcp-server codebase, are outside the static chokepoint check.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "set_local_only",
+    description:
+      "TIGHTEN the posture: mark a scope local_only so loopctl HARD-REFUSES any " +
+      "model-provider call whose resolved endpoint is not classified local. Default is OFF " +
+      "everywhere; nothing changes until a scope opts in. Scope resolution is " +
+      "MOST-RESTRICTIVE-WINS (project OR tenant) and a project can NEVER relax a tenant " +
+      "marking. MANDATORY PRE-FLIGHT: the call is REFUSED with 409 would_block_endpoints, " +
+      "naming every endpoint that would become egress_blocked, unless you pass " +
+      "acknowledge: true — because on a tenant still using vendor default endpoints this " +
+      "instantly stops embedding, extraction, classification and merge, and only a " +
+      "human user-role key can undo it. Requires an ORCHESTRATOR key: tightening is safe " +
+      "to automate. CLEARING is a different tool (clear_local_only) and is user-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: {
+          type: "string",
+          description:
+            "Mark this PROJECT only (omit to mark the whole tenant). A project-less row — " +
+            "a tenant-wide article, any memory — always follows the TENANT marking.",
+        },
+        acknowledge: {
+          type: "boolean",
+          description:
+            "Accept the reported blocked posture and proceed. Required when the pre-flight " +
+            "finds endpoints that would become egress_blocked.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "clear_local_only",
+    description:
+      "WIDEN the posture: remove a scope's local_only marking, re-permitting non-local " +
+      "model-provider egress for it. Requires your EXACT user-role key " +
+      "(LOOPCTL_USER_KEY) — deliberately NOT available to an agent or an orchestrator, " +
+      "because clearing is the self-widening move that would otherwise let an automated " +
+      "key re-open egress immediately before a harvest. Audited with actor and scope.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: {
+          type: "string",
+          description: "Clear this PROJECT's marking (omit to clear the tenant marking).",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "declare_trusted_endpoint",
+    description:
+      "Declare a host you attest is YOUR OWN (your VPS, tailscale funnel, or domain) so a " +
+      "local_only scope can reach it. THIS IS AN UNVERIFIED TENANT ATTESTATION, NOT " +
+      "NETWORK LOCALITY: loopctl does not prove you own the host, and the posture report " +
+      "and custody claim label it 'tenant-declared (unverified attestation), not " +
+      "network-local' — never as network-local. THREE ENFORCED CONSTRAINTS: (1) PUBLIC " +
+      "ADDRESSES ONLY — a host that resolves to loopback, 0/8, 10/8, 127/8, 169.254/16, " +
+      "172.16-31, 192.168/16, 100.64/10 or fdaa::/16 is REJECTED at write time and again " +
+      "at pin time, whether given literally or via a public hostname that resolves there; " +
+      "private-range carve-outs are available ONLY through the operator-controlled " +
+      "deployment allowlist, which no role can write. (2) PURPOSE-SCOPED — a host declared " +
+      "for inference does NOT authorize webhook POSTs of your content to it, nor loopctl " +
+      "FETCHING tenant-supplied URLs from it (purpose 'ingest'). (3) VENDOR " +
+      "HOSTS EXCLUDED (api.openai.com, api.anthropic.com). Requires your EXACT user-role " +
+      "key.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        host: {
+          type: "string",
+          description:
+            "The PUBLIC hostname (or a full URL — only the authority is kept), e.g. " +
+            "'ollama.example.com'.",
+        },
+        purposes: {
+          type: "array",
+          items: { type: "string", enum: ["inference", "webhook", "ingest"] },
+          description:
+            "What this declaration authorizes. At least one. Declarations are honoured " +
+            "ONLY for their declared purposes.",
+        },
+        note: { type: "string", description: "Free-form operator note." },
+      },
+      required: ["host", "purposes"],
+    },
+  },
+  {
+    name: "revoke_trusted_endpoint",
+    description:
+      "Revoke a tenant-declared trusted endpoint. Invalidation is IMMEDIATE — the " +
+      "declaration does not keep working for the remainder of the pin TTL. Requires your " +
+      "EXACT user-role key.",
+    inputSchema: {
+      type: "object",
+      properties: { host: { type: "string", description: "The declared host to revoke." } },
+      required: ["host"],
+    },
+  },
+  {
+    name: "egress_repin",
+    description:
+      "Recover from a :pin_stale error. loopctl pins the IP set it classified so the " +
+      "address it connects to is the address it vetted (closing DNS rebinding). When your " +
+      "box gets a new lease and the address set changes, calls return the DISTINCT " +
+      ":pin_stale error — NOT egress_blocked — and this tool re-resolves and re-pins the " +
+      "host. Available at AGENT role BY DESIGN: home Ollama boxes, tailscale funnels and " +
+      "DHCP VPSes change IP routinely, and requiring a human user-role write to recover " +
+      "would contradict loopctl's agent-native, no-UI design.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        host: { type: "string", description: "The host to re-pin." },
+        project_id: { type: "string", description: "Scope the re-pin to a project." },
+      },
+      required: ["host"],
+    },
+  },
   {
     name: "llm_config",
     description:
@@ -4893,7 +5127,11 @@ const TOOLS = [
       "(extraction_model / classification_model / merge_model / embedding_model) are " +
       "free-form (any model the key permits) and default server-side when omitted. Typical " +
       'onboarding call: set_llm_config({api_key: "sk-ant-...", embedding_api_key: "sk-..."}). ' +
-      "Verify anytime with llm_config (has_api_key / has_embedding_key). REQUIRES your " +
+      "PRIVATE TIER: set chat_provider 'openai_compatible' + chat_base_url + " +
+      "extraction_model (+ chat_api_key unless your server is keyless) to run " +
+      "extraction/classification/merge against YOUR OWN endpoint so document text " +
+      "never leaves your boundary; every model it resolves to is probed before it is saved. " +
+      "Verify anytime with llm_config (has_api_key / has_embedding_key / chat_provider). REQUIRES your " +
       "user-role key LOOPCTL_USER_KEY (minted by the human-anchored signup ceremony); if it " +
       "is unset the tool fails fast telling you to set it.",
     inputSchema: {
@@ -4907,7 +5145,14 @@ const TOOLS = [
         },
         extraction_model: {
           type: "string",
-          description: "Model id for knowledge extraction (null → server default).",
+          description:
+            "Model id for knowledge extraction (null → server default). REQUIRED with " +
+            "chat_provider 'openai_compatible': the server default is an Anthropic model " +
+            "id your endpoint cannot serve, so there is no safe fallback. It is also the " +
+            "fallback for classification_model / merge_model on that provider. " +
+            "HuggingFace repo ids are valid (e.g. 'meta-llama/Meta-Llama-3-8B-Instruct') " +
+            "— it is sent verbatim as the OpenAI `model` field, so it must match the name " +
+            "your server actually serves.",
         },
         classification_model: {
           type: "string",
@@ -4929,6 +5174,48 @@ const TOOLS = [
           description:
             "Embedding model id (null → server default text-embedding-3-small).",
         },
+        chat_provider: {
+          type: "string",
+          enum: ["anthropic", "openai_compatible"],
+          description:
+            "Which provider serves the CHAT surface (ingest extraction, classification, " +
+            "merge synthesis, memory promotion). Omit or 'anthropic' keeps the hardcoded " +
+            "Anthropic endpoint and identical behaviour. 'openai_compatible' routes that " +
+            "surface — the largest and most sensitive payload in the pipeline, your " +
+            "documents' full text — to YOUR OWN endpoint instead.",
+        },
+        chat_base_url: {
+          type: "string",
+          description:
+            "API base of your OpenAI-compatible server, e.g. " +
+            "'https://llm.example.internal/v1' (the client appends /chat/completions). " +
+            "Required with chat_provider 'openai_compatible'. PROBED with a trivial " +
+            "completion per resolved model BEFORE it is saved: an unreachable host, a " +
+            "rejected credential or a non-OpenAI-compatible response is a 422 and NOTHING " +
+            "is persisted. A host resolving into a private/loopback/link-local range is " +
+            "refused outright unless the OPERATOR allowlisted it (SSRF guard). Must be a " +
+            "BARE base: no query string, no fragment, no user:pass@ credentials (this " +
+            "column is NOT encrypted — anything in the URL is stored and echoed back). " +
+            "Plaintext http is accepted ONLY for a host the egress policy classifies " +
+            "network-local; a public http:// endpoint is refused because the request " +
+            "carries your key and your documents' full text in cleartext.",
+        },
+        chat_api_key: {
+          type: "string",
+          description:
+            "Credential for chat_base_url. Write-only; stored encrypted, never returned. " +
+            "SEPARATE from api_key — your Anthropic key is never sent to your endpoint. " +
+            "OPTIONAL: a local server that serves /chat/completions with no auth is " +
+            "configured by omitting this, and no authorization header is then sent.",
+        },
+        acknowledge_key_transmission: {
+          type: "boolean",
+          description:
+            "Required when CHANGING chat_base_url without supplying a matching " +
+            "chat_api_key: explicitly acknowledges that the already-stored key will be " +
+            "transmitted to the new host. The probe never ships an existing credential to " +
+            "a new host silently. Not persisted.",
+        },
       },
       required: [],
     },
@@ -4936,7 +5223,7 @@ const TOOLS = [
   {
     name: "knowledge_llm_usage",
     description:
-      "Per-tenant LLM token-usage summary, grouped by operation + model + source_type + " +
+      "Per-tenant LLM token-usage summary, grouped by operation + model + provider + source_type + " +
       "day over an optional date range, newest day first, with offset/limit pagination " +
       "over meta.total_count. When `from` is omitted it defaults to a 90-day lookback; the " +
       "EFFECTIVE window is echoed in meta.from/meta.to so you can detect that older usage " +
@@ -5684,6 +5971,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_ingestion_jobs":
       return await knowledgeIngestionJobs(args);
 
+    // US-41.4 — fail-closed no-egress guard
+    case "egress_posture":
+      return await egressPosture();
+
+    case "set_local_only":
+      return await setLocalOnly(args);
+
+    case "clear_local_only":
+      return await clearLocalOnly(args);
+
+    case "declare_trusted_endpoint":
+      return await declareTrustedEndpoint(args);
+
+    case "revoke_trusted_endpoint":
+      return await revokeTrustedEndpoint(args);
+
+    case "egress_repin":
+      return await egressRepin(args);
+
     // Per-tenant BYO LLM config + usage (Epic 28, #179)
     case "llm_config":
       return await llmConfig();

package/package.json

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