@odingard/guardian-mcp 0.3.2 → 0.3.4

package/dist/index.js

@@ -2,8 +2,6 @@
 
 // src/index.ts
 import { createRequire } from "node:module";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -18,10 +16,21 @@ var USAGE = `guardian-mcp \u2014 route an agent's tool calls through Guardian (A
 Usage:
   guardian-mcp                               Guardian tools (guardian_invoke_tool, guardian_claim, guardian_receipt)
   guardian-mcp proxy -- <command> [args...]  Govern every tool of an existing stdio MCP server
+  guardian-mcp proxy --url <https-url> [--transport streamable-http|sse] [--header "Name: value"]...
+                                             Govern every tool of a remote MCP server (Streamable
+                                             HTTP by default, or SSE). The agent still talks stdio.
   guardian-mcp tools [--json] -- <command> [args...]
+  guardian-mcp tools [--json] --url <https-url> [--transport ...] [--header ...]
                                              List a server's tools with a suggested Guardian mode
                                              for each (no Guardian credential needed)
 
+Remote upstreams:
+  Write secrets as \${ENV_VAR} references, e.g. --header 'x-api-key: \${COMPOSIO_API_KEY}'
+  (single quotes in a shell, so the key never appears in the process list; JSON configs need
+  no quoting). guardian-mcp expands them itself, refuses a missing variable and any
+  GUARDIAN_* variable, and never prints the URL or header values. The URL must be https://
+  (plain http:// only for localhost).
+
 Environment:
   GUARDIAN_BASE_URL          required, e.g. https://guardian-api.odingard.com
   GUARDIAN_AGENT_CREDENTIAL  required, the agent credential (gac1.\u2026) from the Guardian console
@@ -31,8 +40,9 @@ Environment:
                              use (mcp.install). Default off: register the tools once in the
                              console as "My own code (record-only)" and allow them for the agent
 
-Example (proxy):
+Examples (proxy):
   guardian-mcp proxy -- npx -y @modelcontextprotocol/server-filesystem ./data
+  guardian-mcp proxy --url https://mcp.example.com/mcp --header 'Authorization: Bearer \${REMOTE_MCP_API_KEY}'
 `;
 function parseCli(argv, env) {
   let mode = { kind: "dispatch" };
@@ -41,39 +51,22 @@ function parseCli(argv, env) {
   }
   if (argv[0] === "tools") {
     const json = argv[1] === "--json";
-    const after = argv.slice(json ? 2 : 1);
-    const rest = after[0] === "--" ? after.slice(1) : after;
-    const [command, ...args] = rest;
-    if (!command) {
-      return {
-        ok: false,
-        message: `guardian-mcp tools: missing the MCP server command.
-
-${USAGE}`
-      };
-    }
+    const target = parseTarget("tools", argv.slice(json ? 2 : 1), env);
+    if (!target.ok) return target;
     return {
       ok: true,
       config: {
         baseUrl: "",
         credential: "",
         autoRegister: false,
-        mode: { kind: "tools", command, args, json }
+        mode: { kind: "tools", json, ...target.target }
       }
     };
   }
   if (argv[0] === "proxy") {
-    const rest = argv[1] === "--" ? argv.slice(2) : argv.slice(1);
-    const [command, ...args] = rest;
-    if (!command) {
-      return {
-        ok: false,
-        message: `guardian-mcp proxy: missing the upstream MCP server command.
-
-${USAGE}`
-      };
-    }
-    mode = { kind: "proxy", command, args };
+    const target = parseTarget("proxy", argv.slice(1), env);
+    if (!target.ok) return target;
+    mode = { kind: "proxy", ...target.target };
   } else if (argv.length > 0) {
     return {
       ok: false,
@@ -103,7 +96,7 @@ ${USAGE}`
       credential: env.GUARDIAN_AGENT_CREDENTIAL,
       ...env.GUARDIAN_CONNECTION_ID ? { connectionId: env.GUARDIAN_CONNECTION_ID } : {},
       ...env.GUARDIAN_ADAPTER_ID ? { adapterId: env.GUARDIAN_ADAPTER_ID } : {},
-      // WO-050: off by default — production denies first-use registration
+      // Off by default — production denies first-use registration
       // unless the grant pins mcp.install. Opt in with GUARDIAN_AUTO_REGISTER=true.
       autoRegister: /^(true|1|yes|on)$/i.test(env.GUARDIAN_AUTO_REGISTER ?? ""),
       mode
@@ -118,6 +111,168 @@ function upstreamEnv(env) {
   }
   return out;
 }
+var ENV_REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+var HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+function expandEnv(cmd, value, env, where) {
+  for (const match of value.matchAll(ENV_REF)) {
+    const name = match[1];
+    if (name.startsWith("GUARDIAN_")) {
+      return {
+        ok: false,
+        message: `guardian-mcp ${cmd}: ${where} refers to \${${name}}; Guardian settings are never sent to the upstream server.`
+      };
+    }
+    if (!env[name]) {
+      return {
+        ok: false,
+        message: `guardian-mcp ${cmd}: ${where} refers to \${${name}}, which is not set.`
+      };
+    }
+  }
+  return {
+    ok: true,
+    value: value.replace(ENV_REF, (_, name) => env[name])
+  };
+}
+function parseTarget(cmd, argv, env) {
+  const fail = (message) => ({
+    ok: false,
+    message: `guardian-mcp ${cmd}: ${message}
+
+${USAGE}`
+  });
+  if (argv[0] === "--") argv = argv.slice(1);
+  else if (argv[0]?.startsWith("--")) return parseRemote(cmd, argv, env, fail);
+  const [command, ...args] = argv;
+  if (!command) {
+    return fail(
+      cmd === "proxy" ? "missing the upstream MCP server command (or --url for a remote server)." : "missing the MCP server command (or --url for a remote server)."
+    );
+  }
+  return { ok: true, target: { command, args } };
+}
+function parseRemote(cmd, argv, env, fail) {
+  let rawUrl;
+  let transport = "streamable-http";
+  const rawHeaders = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const eq = arg.indexOf("=");
+    const flag = arg.startsWith("--") && eq > 0 ? arg.slice(0, eq) : arg;
+    let value;
+    if (flag !== arg) value = arg.slice(eq + 1);
+    else if (flag === "--url" || flag === "--transport" || flag === "--header") {
+      value = argv[++i];
+    }
+    if (flag === "--url") {
+      if (rawUrl !== void 0) return fail("--url given more than once.");
+      if (!value) return fail("--url needs a value.");
+      rawUrl = value;
+    } else if (flag === "--transport") {
+      if (value !== "streamable-http" && value !== "sse" && value !== "http") {
+        return fail('--transport must be "streamable-http" or "sse".');
+      }
+      transport = value === "sse" ? "sse" : "streamable-http";
+    } else if (flag === "--header") {
+      if (!value) return fail("--header needs a value.");
+      rawHeaders.push(value);
+    } else if (flag === "--") {
+      return fail("give either --url or a command after --, not both.");
+    } else {
+      return fail(
+        `unknown option at position ${i + 1} (expected --url, --transport or --header).`
+      );
+    }
+  }
+  if (!rawUrl) return fail("--url is required with --transport or --header.");
+  const expandedUrl = expandEnv(cmd, rawUrl, env, "--url");
+  if (!expandedUrl.ok) return expandedUrl;
+  let url;
+  try {
+    url = new URL(expandedUrl.value);
+  } catch {
+    return fail("--url is not a valid URL.");
+  }
+  if (url.username || url.password) {
+    return fail(
+      "--url must not carry a user name or password; send credentials with --header."
+    );
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && LOOPBACK.has(url.hostname))) {
+    return fail(
+      "--url must be https:// (plain http:// is accepted only for localhost)."
+    );
+  }
+  const headers = {};
+  for (const [n, raw] of rawHeaders.entries()) {
+    const colon = raw.indexOf(":");
+    const name = colon > 0 ? raw.slice(0, colon).trim() : "";
+    if (!name || !HEADER_NAME.test(name)) {
+      return fail(`--header #${n + 1} must look like "Name: value".`);
+    }
+    const expanded = expandEnv(
+      cmd,
+      raw.slice(colon + 1).trim(),
+      env,
+      `--header ${name}`
+    );
+    if (!expanded.ok) return expanded;
+    if (!expanded.value) return fail(`--header ${name} has an empty value.`);
+    if (/[\r\n]/.test(expanded.value))
+      return fail(`--header ${name} contains a line break.`);
+    headers[name] = expanded.value;
+  }
+  return {
+    ok: true,
+    target: { remote: { url: url.href, transport, headers } }
+  };
+}
+function secretsOf(target) {
+  if (!("remote" in target)) return [];
+  const { url, headers } = target.remote;
+  const out = /* @__PURE__ */ new Set([url]);
+  const parsed2 = new URL(url);
+  if (parsed2.search) out.add(parsed2.search.slice(1));
+  for (const v of parsed2.searchParams.values()) if (v.length >= 4) out.add(v);
+  for (const pair of parsed2.search.slice(1).split("&")) {
+    const raw = pair.slice(pair.indexOf("=") + 1);
+    if (pair.indexOf("=") < 0 || raw.length < 4) continue;
+    const forms = [raw, raw.replace(/\+/g, " ")];
+    for (const form of [...forms]) {
+      try {
+        forms.push(decodeURIComponent(form));
+      } catch {
+      }
+    }
+    for (const form of forms) if (form.length >= 4) out.add(form);
+  }
+  for (const segment of parsed2.pathname.split("/")) {
+    if (segment.length >= 16 || segment.length >= 8 && /\d/.test(segment)) {
+      out.add(segment);
+      out.add(decodeURIComponent(segment));
+    }
+  }
+  for (const value of Object.values(headers)) {
+    out.add(value);
+    const parts = value.split(/\s+/);
+    for (const part of parts) if (part.length >= 8) out.add(part);
+  }
+  return [...out].sort((a, b) => b.length - a.length);
+}
+function redact(text, secrets) {
+  let out = text;
+  for (const secret of secrets) {
+    if (secret) out = out.split(secret).join("[redacted]");
+  }
+  return out;
+}
+function describeTarget(target) {
+  if ("remote" in target) {
+    return `${new URL(target.remote.url).origin} (${target.remote.transport})`;
+  }
+  return [target.command, ...target.args].join(" ");
+}
 
 // src/dispatch.ts
 var TOOLS = [
@@ -165,11 +320,26 @@ var TOOLS = [
   }
 ];
 function jsonResult(payload) {
-  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+  };
 }
 function errorResult(message) {
   return { isError: true, content: [{ type: "text", text: message }] };
 }
+function jsonError(payload) {
+  return { ...jsonResult(payload), isError: true };
+}
+var CHECK_FIRST = "Call guardian_receipt with this requestId, or check the target system, before retrying.";
+function denied(reasonCode, requestId) {
+  const code = reasonCode ?? "DENIED";
+  return jsonError({
+    decision: "DENY",
+    reasonCode: code,
+    ...requestId ? { requestId } : {},
+    message: code === "SERVICE_UNAVAILABLE" ? "Guardian could not be reached, so nothing was done. Try again later." : "Guardian denied this call. Nothing was done. Do not retry the same call."
+  });
+}
 async function requestAndExecute(client2, result) {
   if (!result.ok) {
     const heldRequestId = result.requestId;
@@ -181,33 +351,62 @@ async function requestAndExecute(client2, result) {
         next: "Held for human approval. Call guardian_claim with this requestId after approval."
       });
     }
-    return jsonResult({ decision: "DENY", reasonCode: result.reasonCode });
+    return denied(
+      result.reasonCode,
+      typeof heldRequestId === "string" && heldRequestId.length > 0 ? heldRequestId : void 0
+    );
   }
   if (result.decision === "ALLOW" && result.capabilityToken) {
     const executed = await client2.execute({
       requestId: result.requestId,
       capabilityToken: result.capabilityToken
     });
-    return jsonResult(
-      executed.ok ? {
+    if (!executed.ok) {
+      return jsonError({
+        decision: "ALLOW",
+        requestId: result.requestId,
+        outcome: "unknown",
+        executionFailed: executed.reasonCode,
+        message: `Guardian could not confirm the outcome (${executed.reasonCode}). The call may have been done. ${CHECK_FIRST}`
+      });
+    }
+    const status = executed.receipt?.status;
+    if (status === "sent-verified") {
+      return jsonResult({
         decision: "ALLOW",
         requestId: result.requestId,
         receipt: executed.receipt
-      } : {
+      });
+    }
+    if (status === "not-sent") {
+      return jsonError({
         decision: "ALLOW",
         requestId: result.requestId,
-        executionFailed: executed.reasonCode
-      }
-    );
+        outcome: "not-done",
+        receipt: executed.receipt,
+        message: "Guardian did not send the call (receipt status not-sent). It was not done."
+      });
+    }
+    return jsonError({
+      decision: "ALLOW",
+      requestId: result.requestId,
+      outcome: "unknown",
+      receipt: executed.receipt,
+      message: `The outcome is unknown (receipt status ${typeof status === "string" ? status : "missing"}). The call may have been done. ${CHECK_FIRST}`
+    });
   }
-  return jsonResult({
-    decision: result.decision,
-    requestId: result.requestId,
-    ...result.reasonCode ? { reasonCode: result.reasonCode } : {},
-    ...result.decision === "ASK" ? {
+  if (result.decision === "ASK") {
+    return jsonResult({
+      decision: "ASK",
+      requestId: result.requestId,
+      ...result.reasonCode ? { reasonCode: result.reasonCode } : {},
       message: "Held for human approval. Call guardian_claim with this requestId after approval."
-    } : {}
-  });
+    });
+  }
+  return denied(
+    result.reasonCode ?? (result.decision === "DENY" ? void 0 : "MISSING_CAPABILITY"),
+    result.requestId
+  );
 }
 async function handleToolCall(options, name, arguments_) {
   const { client: client2, defaultConnectionId, adapterId } = options;
@@ -267,12 +466,85 @@ var READ_VERBS = /* @__PURE__ */ new Set([
   "find",
   "lookup",
   "count",
-  "inspect",
-  "status",
-  "fetch"
+  "inspect"
+]);
+var WRITE_VERBS = /* @__PURE__ */ new Set([
+  "add",
+  "append",
+  "apply",
+  "approve",
+  "archive",
+  "assign",
+  "buy",
+  "cancel",
+  "charge",
+  "clear",
+  "close",
+  "commit",
+  "copy",
+  "create",
+  "delete",
+  "deploy",
+  "destroy",
+  "disable",
+  "drop",
+  "edit",
+  "enable",
+  "exec",
+  "execute",
+  "fork",
+  "grant",
+  "import",
+  "insert",
+  "install",
+  "invite",
+  "kill",
+  "lock",
+  "merge",
+  "modify",
+  "move",
+  "notify",
+  "patch",
+  "pay",
+  "post",
+  "publish",
+  "purge",
+  "push",
+  "put",
+  "refund",
+  "remove",
+  "rename",
+  "replace",
+  "reply",
+  "reset",
+  "restart",
+  "restore",
+  "revoke",
+  "rm",
+  "run",
+  "save",
+  "schedule",
+  "sell",
+  "send",
+  "set",
+  "share",
+  "sign",
+  "start",
+  "stop",
+  "submit",
+  "sync",
+  "transfer",
+  "trigger",
+  "truncate",
+  "uninstall",
+  "unlock",
+  "update",
+  "upload",
+  "upsert",
+  "write"
 ]);
-function firstWord(name) {
-  return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().split(/[^a-z0-9]+/).find(Boolean) ?? "";
+function words(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
 }
 function suggestTool(tool) {
   const governable = GUARDIAN_TOOL_NAME.test(tool.name) && tool.name.length <= 64;
@@ -285,6 +557,16 @@ function suggestTool(tool) {
       governable
     };
   }
+  const tokens = words(tool.name);
+  const writeVerb = tokens.find((token) => WRITE_VERBS.has(token));
+  if (writeVerb) {
+    return {
+      name: tool.name,
+      suggestedMode: "ask",
+      why: `"${writeVerb}" may change something`,
+      governable
+    };
+  }
   if (annotations.readOnlyHint === true) {
     return {
       name: tool.name,
@@ -293,7 +575,7 @@ function suggestTool(tool) {
       governable
     };
   }
-  const verb = firstWord(tool.name);
+  const verb = tokens[0] ?? "";
   if (READ_VERBS.has(verb)) {
     return {
       name: tool.name,
@@ -309,7 +591,7 @@ function suggestTool(tool) {
     governable
   };
 }
-function renderSuggestions(serverCommand, tools) {
+function renderSuggestions(serverCommand, tools, remote = false) {
   const rows = tools.map(suggestTool);
   const width = Math.max(4, ...rows.map((r) => r.name.length));
   const lines = [
@@ -322,7 +604,7 @@ function renderSuggestions(serverCommand, tools) {
     "",
     "Register these in the Guardian console (Connections \u2192 Register a tool server \u2192",
     "record-only), then set each mode for your agent. Run the server through",
-    "`guardian-mcp proxy -- <same command>` so every call is decided first."
+    remote ? "`guardian-mcp proxy --url <same url> --header \u2026` so every call is decided first." : "`guardian-mcp proxy -- <same command>` so every call is decided first."
   ];
   const ungovernable = rows.filter((r) => !r.governable);
   if (ungovernable.length > 0) {
@@ -349,6 +631,20 @@ import {
 } from "@odingard/guardian-sdk";
 var CLAIM_TOOL = "guardian_claim";
 var RECEIPT_TOOL = "guardian_receipt";
+var GUARDIAN_RESULT_META = "com.odingard/guardian";
+var UNAVAILABLE = "SERVICE_UNAVAILABLE";
+function unreachableResult(toolName, requestId) {
+  return jsonResult2(
+    {
+      decision: "DENY",
+      toolName,
+      reasonCode: UNAVAILABLE,
+      ...requestId ? { requestId } : {},
+      message: `Guardian could not be reached, so ${toolName} was not checked and nothing was forwarded. Try again later.`
+    },
+    true
+  );
+}
 var PROXY_GOVERNANCE_TOOLS = [
   {
     name: CLAIM_TOOL,
@@ -375,10 +671,93 @@ function jsonResult2(payload, isError = false) {
     content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
   };
 }
+function withRequestId(result, requestId) {
+  if (!requestId) return result;
+  const meta = typeof result._meta === "object" && result._meta !== null ? result._meta : {};
+  return {
+    ...result,
+    _meta: { ...meta, [GUARDIAN_RESULT_META]: { requestId } }
+  };
+}
 function isDecisionResult(value) {
   return typeof value === "object" && value !== null && "guardian" in value && typeof value.guardian === "object";
 }
-function failure(err, toolName) {
+var UpstreamCallFailed = class extends Error {
+  constructor(toolName) {
+    super("upstream call failed");
+    this.toolName = toolName;
+    this.name = "UpstreamCallFailed";
+  }
+  toolName;
+};
+var UPSTREAM_RESULT = /* @__PURE__ */ Symbol("guardian-mcp.upstreamResult");
+function upstreamRan(value) {
+  return typeof value === "object" && value !== null && Object.prototype.hasOwnProperty.call(value, UPSTREAM_RESULT);
+}
+var UpstreamCallCancelled = class extends Error {
+  constructor(toolName) {
+    super("the call was cancelled before it was forwarded");
+    this.toolName = toolName;
+    this.name = "UpstreamCallCancelled";
+  }
+  toolName;
+};
+var UpstreamListFailed = class extends Error {
+  constructor() {
+    super(
+      "guardian-mcp: the upstream MCP server's tool list is unavailable; no tools are served."
+    );
+    this.name = "UpstreamListFailed";
+  }
+};
+function callUpstream(upstream, name, args, signal, forwarding) {
+  return async () => {
+    if (signal?.aborted) {
+      throw new UpstreamCallCancelled(name);
+    }
+    forwarding.sent = true;
+    try {
+      return {
+        [UPSTREAM_RESULT]: await upstream.callTool(
+          name,
+          args,
+          signal ? { signal } : void 0
+        )
+      };
+    } catch (err) {
+      if (err instanceof UpstreamCallCancelled) {
+        forwarding.sent = false;
+        throw err;
+      }
+      throw new UpstreamCallFailed(name);
+    }
+  };
+}
+function cancelledResult(toolName, requestId) {
+  return jsonResult2(
+    {
+      toolName,
+      ...requestId ? { requestId } : {},
+      cancelled: true,
+      message: requestId ? `The request was cancelled before ${toolName} was forwarded. Nothing was forwarded; the approved call is still held, so call ${CLAIM_TOOL} with this requestId to forward it.` : `The request was cancelled before ${toolName} was forwarded. Nothing was forwarded.`
+    },
+    true
+  );
+}
+function failure(err, toolName, forwarding) {
+  if (err instanceof UpstreamCallCancelled) {
+    return cancelledResult(toolName);
+  }
+  if (err instanceof UpstreamCallFailed) {
+    return jsonResult2(
+      {
+        decision: "ALLOW",
+        toolName,
+        error: "Guardian allowed the call but the upstream MCP server did not return a result. It may or may not have run; check before retrying. The capability was not redeemed."
+      },
+      true
+    );
+  }
   if (err instanceof GuardianExecutionFailed) {
     return jsonResult2(
       {
@@ -387,12 +766,16 @@ function failure(err, toolName) {
         requestId: err.requestId,
         executionFailed: err.reasonCode,
         localEffectRan: err.localEffectRan,
-        message: err.localEffectRan ? "The upstream call ran but Guardian refused to redeem the capability. Treat this as an incident, not a success." : "Guardian could not redeem the capability; the call was not completed."
+        ...err.outcomeUnknown ? { outcomeUnknown: true } : {},
+        message: err.outcomeUnknown ? err.localEffectRan ? `The upstream call ran, but Guardian could not confirm that it was recorded. Do not call it again; check this requestId with ${RECEIPT_TOOL}.` : `Guardian could not confirm whether the call completed. It may have run. Do not call it again; check this requestId with ${RECEIPT_TOOL}.` : err.localEffectRan ? "The upstream call ran but Guardian refused to redeem the capability. Do not call it again. Treat this as an incident, not a success." : "Guardian could not redeem the capability; the call was not completed."
       },
       true
     );
   }
   if (err instanceof GuardianDenied) {
+    if (err.reasonCode === UNAVAILABLE) {
+      return unreachableResult(toolName, err.requestId);
+    }
     return jsonResult2(
       {
         decision: "DENY",
@@ -417,17 +800,28 @@ function failure(err, toolName) {
   return jsonResult2(
     {
       toolName,
-      error: "Guardian proxy error; the call was not forwarded."
+      error: forwarding.sent ? "Guardian proxy error after the call was forwarded. It may have run; check before retrying." : "Guardian proxy error; the call was not forwarded."
     },
     true
   );
 }
+var CLAIMED_REQUESTS_LIMIT = 1e3;
 function createGovernedProxy(options) {
   const { upstream, log = () => {
   } } = options;
   const toolInvokeRequestIds = /* @__PURE__ */ new Set();
   const pendingCalls = /* @__PURE__ */ new Map();
   const pendingInstalls = /* @__PURE__ */ new Map();
+  const claimedCapabilities = /* @__PURE__ */ new Map();
+  const claimedRequests = /* @__PURE__ */ new Map();
+  const rememberClaim = (requestId, entry) => {
+    claimedRequests.delete(requestId);
+    claimedRequests.set(requestId, entry);
+    while (claimedRequests.size > CLAIMED_REQUESTS_LIMIT) {
+      const oldest = claimedRequests.keys().next().value;
+      claimedRequests.delete(oldest);
+    }
+  };
   const recordingClient = {
     ...options.client,
     async request(invocation) {
@@ -449,6 +843,26 @@ function createGovernedProxy(options) {
     ...options.adapterId ? { adapterId: options.adapterId } : {},
     ...options.agentName ? { agentName: options.agentName } : {}
   });
+  ctx.installed ??= /* @__PURE__ */ new Set();
+  function heldSetupStep(toolName, requestId) {
+    const held = ctx.heldSetup?.get(`${options.connectionId}:${toolName}`);
+    return held?.requestId === requestId ? held.step : void 0;
+  }
+  function tracked() {
+    let allowed;
+    return {
+      ctx: {
+        ...ctx,
+        options: {
+          ...ctx.options,
+          onReceipt: (event) => {
+            allowed = event.requestId;
+          }
+        }
+      },
+      allowedRequestId: () => allowed
+    };
+  }
   let upstreamTools = null;
   async function loadTools() {
     if (upstreamTools) return upstreamTools;
@@ -465,8 +879,19 @@ function createGovernedProxy(options) {
     upstreamTools = tools;
     return tools;
   }
-  function toCallResult(toolName, args, output) {
-    if (!isDecisionResult(output)) return output;
+  function toCallResult(toolName, args, output, allowedRequestId) {
+    if (upstreamRan(output)) {
+      return withRequestId(output[UPSTREAM_RESULT], allowedRequestId);
+    }
+    if (!isDecisionResult(output)) {
+      return jsonResult2(
+        {
+          toolName,
+          error: "Guardian proxy error; the call was not forwarded."
+        },
+        true
+      );
+    }
     const g = output.guardian;
     if (g.decision === "ASK") {
       if (toolInvokeRequestIds.has(g.requestId)) {
@@ -479,37 +904,92 @@ function createGovernedProxy(options) {
         });
       }
       pendingInstalls.set(g.requestId, toolName);
+      const step = heldSetupStep(toolName, g.requestId);
       return jsonResult2({
         decision: "ASK",
         toolName,
         requestId: g.requestId,
-        message: `First use of ${toolName} needs a human to approve registering it with Guardian. After approval call ${CLAIM_TOOL} with this requestId, then retry the original call.`
+        message: step === "enable" ? `Switching on ${toolName} for this agent needs a human to approve it in Guardian. After approval call ${CLAIM_TOOL} with this requestId (or retry the original call).` : `First use of ${toolName} needs a human to approve registering it with Guardian. After approval call ${CLAIM_TOOL} with this requestId, then retry the original call.`
       });
     }
     if (g.decision === "DENY") {
-      return jsonResult2({
-        decision: "DENY",
-        toolName,
-        reasonCode: g.reasonCode,
-        ...g.requestId ? { requestId: g.requestId } : {},
-        message: g.message
-      });
+      if (g.reasonCode === UNAVAILABLE) {
+        return unreachableResult(toolName, g.requestId);
+      }
+      return jsonResult2(
+        {
+          decision: "DENY",
+          toolName,
+          reasonCode: g.reasonCode,
+          ...g.requestId ? { requestId: g.requestId } : {},
+          message: g.message
+        },
+        true
+      );
     }
     return jsonResult2({ decision: "ALLOW", toolName, requestId: g.requestId });
   }
-  async function claim(requestId) {
+  function alreadyClaimed(requestId) {
+    const seen = claimedRequests.get(requestId);
+    if (!seen) return void 0;
+    if (seen.state === "forwarding" || !seen.result) {
+      return jsonResult2(
+        {
+          toolName: seen.toolName,
+          requestId,
+          alreadyClaimed: true,
+          message: `This approved call is already being forwarded by an earlier ${CLAIM_TOOL}. Do not propose ${seen.toolName} again; wait, then call ${RECEIPT_TOOL} with this requestId to see what happened.`
+        },
+        true
+      );
+    }
+    const notice = {
+      type: "text",
+      text: `This requestId was already claimed and ${seen.toolName} was already forwarded. Do not propose it again. The earlier result follows.`
+    };
+    const earlier = seen.result;
+    return {
+      ...earlier,
+      isError: true,
+      content: [
+        notice,
+        ...Array.isArray(earlier.content) ? earlier.content : []
+      ]
+    };
+  }
+  async function claim(requestId, signal) {
+    const repeat = alreadyClaimed(requestId);
+    if (repeat) return repeat;
     const held = pendingCalls.get(requestId);
     if (held) {
+      if (signal?.aborted) {
+        return cancelledResult(held.name, requestId);
+      }
+      pendingCalls.delete(requestId);
+      const putBack = () => {
+        claimedRequests.delete(requestId);
+        pendingCalls.set(requestId, held);
+      };
+      rememberClaim(requestId, { toolName: held.name, state: "forwarding" });
       let claimed;
-      try {
-        claimed = await options.client.claim(requestId);
-      } catch {
-        return jsonResult2(
-          { requestId, error: "Guardian unreachable; nothing was forwarded." },
-          true
-        );
+      const reused = claimedCapabilities.get(requestId);
+      if (reused) {
+        claimedCapabilities.delete(requestId);
+        claimed = reused;
+      } else {
+        try {
+          claimed = await options.client.claim(requestId);
+        } catch {
+          putBack();
+          return unreachableResult(held.name, requestId);
+        }
+      }
+      if (!claimed.ok && claimed.reasonCode === UNAVAILABLE) {
+        putBack();
+        return unreachableResult(held.name, requestId);
       }
       if (claimed.ok && claimed.decision === "ASK" || !claimed.ok && (claimed.reasonCode === "APPROVAL_PENDING" || claimed.reasonCode === "APPROVAL_REQUIRED")) {
+        putBack();
         return jsonResult2({
           decision: "ASK",
           toolName: held.name,
@@ -517,40 +997,95 @@ function createGovernedProxy(options) {
           message: "Still awaiting human approval. Nothing was sent."
         });
       }
-      pendingCalls.delete(requestId);
+      let result;
+      const forwarding = { sent: false };
       try {
+        const call = tracked();
         const output = await settle(
-          ctx,
+          call.ctx,
           held.name,
           held.args,
           claimed,
-          () => upstream.callTool(held.name, held.args)
+          callUpstream(upstream, held.name, held.args, signal, forwarding)
+        );
+        result = toCallResult(
+          held.name,
+          held.args,
+          output,
+          call.allowedRequestId()
         );
-        return toCallResult(held.name, held.args, output);
       } catch (err) {
-        return failure(err, held.name);
+        if (err instanceof UpstreamCallCancelled) {
+          putBack();
+          if (claimed.ok && claimed.decision === "ALLOW") {
+            claimedCapabilities.set(requestId, claimed);
+          }
+          return cancelledResult(held.name, requestId);
+        }
+        result = failure(err, held.name, forwarding);
+      }
+      if (!claimed.ok || claimed.decision !== "ALLOW" || !claimed.capabilityToken) {
+        claimedRequests.delete(requestId);
+      } else {
+        rememberClaim(requestId, {
+          toolName: held.name,
+          state: "done",
+          result
+        });
       }
+      return result;
     }
     const installFor = pendingInstalls.get(requestId);
     if (installFor) {
-      const claimed = await options.client.claim(requestId);
+      if (signal?.aborted) {
+        return jsonResult2(
+          {
+            toolName: installFor,
+            requestId,
+            cancelled: true,
+            message: `The request was cancelled. Nothing was claimed; call ${CLAIM_TOOL} with this requestId again.`
+          },
+          true
+        );
+      }
+      const key = `${options.connectionId}:${installFor}`;
+      const step = heldSetupStep(installFor, requestId) ?? "install";
+      const forgetHeld = () => {
+        if (ctx.heldSetup?.get(key)?.requestId === requestId) {
+          ctx.heldSetup.delete(key);
+        }
+      };
+      let claimed;
+      try {
+        claimed = await options.client.claim(requestId);
+      } catch {
+        return unreachableResult(installFor, requestId);
+      }
+      if (!claimed.ok && claimed.reasonCode === UNAVAILABLE) {
+        return unreachableResult(installFor, requestId);
+      }
       if (claimed.ok && claimed.decision === "ALLOW" && claimed.capabilityToken) {
+        forgetHeld();
+        pendingInstalls.delete(requestId);
         const executed = await options.client.execute({
           requestId: claimed.requestId,
           capabilityToken: claimed.capabilityToken
         });
-        pendingInstalls.delete(requestId);
-        ctx.ensured.add(`${options.connectionId}:${installFor}`);
+        if (executed.ok && step === "enable") {
+          ctx.ensured.add(key);
+        } else if (executed.ok) {
+          ctx.installed?.add(key);
+        }
         return jsonResult2(
           executed.ok ? {
             decision: "ALLOW",
             toolName: installFor,
-            message: `${installFor} is registered with Guardian. Retry the original call.`
+            message: step === "enable" ? `${installFor} is switched on for this agent. Retry the original call.` : `${installFor} is registered with Guardian. Retry the original call; switching it on for this agent may need one more approval.`
           } : { toolName: installFor, executionFailed: executed.reasonCode },
           !executed.ok
         );
       }
-      if (claimed.ok && claimed.decision === "ASK") {
+      if (claimed.ok && claimed.decision === "ASK" || !claimed.ok && (claimed.reasonCode === "APPROVAL_PENDING" || claimed.reasonCode === "APPROVAL_REQUIRED")) {
         return jsonResult2({
           decision: "ASK",
           toolName: installFor,
@@ -558,24 +1093,36 @@ function createGovernedProxy(options) {
           message: "Still awaiting human approval."
         });
       }
+      forgetHeld();
       pendingInstalls.delete(requestId);
-      return jsonResult2({
-        decision: "DENY",
-        toolName: installFor,
-        reasonCode: claimed.ok ? claimed.reasonCode ?? "MISSING_CAPABILITY" : claimed.reasonCode
-      });
+      return jsonResult2(
+        {
+          decision: "DENY",
+          toolName: installFor,
+          reasonCode: claimed.ok ? claimed.reasonCode ?? "MISSING_CAPABILITY" : claimed.reasonCode
+        },
+        true
+      );
     }
     return jsonResult2(
       {
         requestId,
-        error: "No held call with this requestId in this proxy session. Nothing was forwarded."
+        error: `This proxy holds no call with this requestId, so this claim forwarded nothing. If it was claimed before (in this or an earlier proxy session), the call may already have been forwarded: call ${RECEIPT_TOOL} with this requestId before proposing it again.`
       },
       true
     );
   }
   return {
     async listTools() {
-      const tools = await loadTools();
+      let tools;
+      try {
+        tools = await loadTools();
+      } catch {
+        log(
+          "guardian-mcp proxy: the upstream MCP server's tool list is unavailable"
+        );
+        throw new UpstreamListFailed();
+      }
       return [
         ...[...tools.values()].map((tool) => ({
           ...tool,
@@ -584,13 +1131,14 @@ function createGovernedProxy(options) {
         ...PROXY_GOVERNANCE_TOOLS
       ];
     },
-    async callTool(name, args) {
+    async callTool(name, args, callOptions) {
+      const signal = callOptions?.signal;
       if (name === CLAIM_TOOL) {
         const requestId = args.requestId;
         if (typeof requestId !== "string" || requestId.length === 0) {
           return jsonResult2({ error: "requestId is required" }, true);
         }
-        return claim(requestId);
+        return claim(requestId, signal);
       }
       if (name === RECEIPT_TOOL) {
         const requestId = args.requestId;
@@ -603,26 +1151,123 @@ function createGovernedProxy(options) {
           !result.ok
         );
       }
-      const tools = await loadTools();
+      let tools;
+      try {
+        tools = await loadTools();
+      } catch {
+        return jsonResult2(
+          {
+            toolName: name,
+            error: "The upstream MCP server's tool list is unavailable; nothing was forwarded."
+          },
+          true
+        );
+      }
       if (!tools.has(name)) {
         return jsonResult2({ error: `unknown tool: ${name}` }, true);
       }
+      if (signal?.aborted) {
+        return cancelledResult(name);
+      }
+      const forwarding = { sent: false };
       try {
+        const call = tracked();
         const output = await runThroughGuardian(
-          ctx,
+          call.ctx,
           name,
           args,
-          () => upstream.callTool(name, args)
+          callUpstream(upstream, name, args, signal, forwarding)
         );
-        return toCallResult(name, args, output);
+        return toCallResult(name, args, output, call.allowedRequestId());
       } catch (err) {
-        return failure(err, name);
+        return failure(err, name, forwarding);
       }
     }
   };
 }
 
+// src/upstream.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+var UpstreamConnectError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UpstreamConnectError";
+  }
+};
+function upstreamTransport(target, env) {
+  if (!("remote" in target)) {
+    return new StdioClientTransport({
+      command: target.command,
+      args: target.args,
+      env: upstreamEnv(env),
+      stderr: "inherit"
+    });
+  }
+  const { url, transport, headers } = target.remote;
+  const options = {
+    requestInit: { headers },
+    redirectPolicy: "same-origin"
+  };
+  return transport === "sse" ? new SSEClientTransport(new URL(url), options) : new StreamableHTTPClientTransport(new URL(url), options);
+}
+async function connectUpstream(target, env, clientInfo, transport = upstreamTransport(target, env)) {
+  const client2 = new Client(clientInfo, { capabilities: {} });
+  try {
+    await client2.connect(transport);
+  } catch (err) {
+    await client2.close().catch(() => {
+    });
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new UpstreamConnectError(
+      `guardian-mcp: could not connect to the upstream MCP server at ${describeTarget(target)}: ${redact(detail, secretsOf(target)).slice(0, 300)}. No tools are served.`
+    );
+  }
+  return client2;
+}
+async function listAllTools(client2) {
+  const tools = [];
+  let cursor;
+  do {
+    const page = await client2.listTools(cursor ? { cursor } : void 0);
+    tools.push(...page.tools);
+    cursor = page.nextCursor;
+  } while (cursor);
+  return tools;
+}
+function toolListFailure(target, err) {
+  const detail = err instanceof Error ? err.message : String(err);
+  return `guardian-mcp: the upstream MCP server at ${describeTarget(target)} did not return its tool list: ${redact(detail, secretsOf(target)).slice(0, 300)}.`;
+}
+function clientUpstream(client2) {
+  return {
+    listTools: () => listAllTools(client2),
+    async callTool(name, args, options) {
+      if (options?.signal?.aborted) {
+        throw new UpstreamCallCancelled(name);
+      }
+      return await client2.callTool({
+        name,
+        arguments: args
+      });
+    }
+  };
+}
+
 // src/index.ts
+async function connectOrExit(...args) {
+  try {
+    return await connectUpstream(...args);
+  } catch (err) {
+    process.stderr.write(
+      `${err instanceof UpstreamConnectError ? err.message : "guardian-mcp: could not connect to the upstream MCP server. No tools are served."}
+`
+    );
+    process.exit(1);
+  }
+}
 var VERSION = createRequire(import.meta.url)("../package.json").version;
 var parsed = parseCli(process.argv.slice(2), process.env);
 if (!parsed.ok) {
@@ -633,30 +1278,25 @@ if (!parsed.ok) {
 var config = parsed.config;
 if (config.mode.kind === "tools") {
   const mode = config.mode;
-  const lister = new Client(
-    { name: "guardian-mcp-tools", version: VERSION },
-    { capabilities: {} }
-  );
-  await lister.connect(
-    new StdioClientTransport({
-      command: mode.command,
-      args: mode.args,
-      env: upstreamEnv(process.env),
-      stderr: "inherit"
-    })
-  );
-  const tools = [];
-  let cursor;
-  do {
-    const page = await lister.listTools(cursor ? { cursor } : void 0);
-    tools.push(...page.tools);
-    cursor = page.nextCursor;
-  } while (cursor);
+  const lister = await connectOrExit(mode, process.env, {
+    name: "guardian-mcp-tools",
+    version: VERSION
+  });
+  let tools;
+  try {
+    tools = await listAllTools(lister);
+  } catch (err) {
+    process.stderr.write(`${toolListFailure(mode, err)}
+`);
+    await lister.close().catch(() => {
+    });
+    process.exit(1);
+  }
   await lister.close();
-  const serverCommand = [mode.command, ...mode.args].join(" ");
+  const serverCommand = describeTarget(mode);
   process.stdout.write(
     mode.json ? `${JSON.stringify({ server: serverCommand, tools: tools.map(suggestTool) }, null, 2)}
-` : `${renderSuggestions(serverCommand, tools)}
+` : `${renderSuggestions(serverCommand, tools, "remote" in mode)}
 `
   );
   process.exit(0);
@@ -671,18 +1311,10 @@ var server = new Server(
   { capabilities: { tools: {} } }
 );
 if (config.mode.kind === "proxy") {
-  const upstreamClient = new Client(
-    { name: "guardian-mcp-proxy", version: VERSION },
-    { capabilities: {} }
-  );
-  await upstreamClient.connect(
-    new StdioClientTransport({
-      command: config.mode.command,
-      args: config.mode.args,
-      env: upstreamEnv(process.env),
-      stderr: "inherit"
-    })
-  );
+  const upstreamClient = await connectOrExit(config.mode, process.env, {
+    name: "guardian-mcp-proxy",
+    version: VERSION
+  });
   const proxy = createGovernedProxy({
     client,
     connectionId: config.connectionId,
@@ -690,35 +1322,19 @@ if (config.mode.kind === "proxy") {
     ...config.adapterId ? { adapterId: config.adapterId } : {},
     log: (message) => process.stderr.write(`${message}
 `),
-    upstream: {
-      async listTools() {
-        const tools = [];
-        let cursor;
-        do {
-          const page = await upstreamClient.listTools(
-            cursor ? { cursor } : void 0
-          );
-          tools.push(...page.tools);
-          cursor = page.nextCursor;
-        } while (cursor);
-        return tools;
-      },
-      async callTool(name, args) {
-        return await upstreamClient.callTool({
-          name,
-          arguments: args
-        });
-      }
-    }
+    upstream: clientUpstream(upstreamClient)
   });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: await proxy.listTools()
   }));
   server.setRequestHandler(
     CallToolRequestSchema,
-    async (request) => await proxy.callTool(
+    async (request, extra) => await proxy.callTool(
       request.params.name,
-      request.params.arguments ?? {}
+      request.params.arguments ?? {},
+      // Cancelled (notifications/cancelled) or timed-out requests are
+      // not forwarded if the signal fires before the call is sent.
+      { signal: extra.signal }
     )
   );
 } else {