@agentwares/agentguard 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -482,7 +482,7 @@ interface DemoOptions {
 /** Drive a connected client through the scripted scenario. Returns every step's outcome. */
 declare function runDemoAgent(client: Client, opts?: DemoOptions): Promise<DemoStep[]>;
 
-declare const HELP = "agentguard \u2014 MCP policy proxy for agents that touch production\n\n  npx @agentwares/agentguard init                 read your MCP config, write agentguard.yaml (dry-run), route every server through the proxy\n  agentguard report [--run id|--all]  what this run did / would have destroyed / spent, where it was halted\n  agentguard diff [--run id]          record-by-record mutation diff from a dry run\n  agentguard verify [audit.jsonl]     prove the hash-chained audit log was not edited\n\n  agentguard proxy [--http --port 8788] [--agent name] [--run-id id] [--mode dry-run|enforce]\n  agentguard tools [--json]           the tools your agent will see, with class and why\n  agentguard status [--run id]        counters vs caps, kill state, pending approvals\n\n  agentguard kill [reason]            halt every run now (file + running HTTP proxy);  agentguard resume\n  agentguard approvals [--all]        pending approvals;  agentguard approve <id> | deny <id> [--note text]\n  agentguard key create <agent> [--allow 'crm_get_*']... [--deny p] [--writes n] [--spend n] [--mode m]\n  agentguard key list | revoke <agent>\n  agentguard permission-diff [--base ref] [--head ref] [--paths a,b] [--format markdown|json] [--fail-on-widen]\n\nOptions: --config <agentguard.yaml> (or AGENTGUARD_CONFIG), --json, --help, --version\nDocs: https://github.com/agentwares/agentguard/tree/main/apps/agentguard-cli";
+declare const HELP = "agentguard \u2014 MCP policy proxy for agents that touch production\n\n  npx @agentwares/agentguard init                 read your MCP config, write agentguard.yaml (dry-run), route every server through the proxy\n  agentguard report [--run id|--all]  what this run did / would have destroyed / spent, where it was halted\n  agentguard diff [--run id]          record-by-record mutation diff from a dry run\n  agentguard verify [audit.jsonl]     prove the hash-chained audit log was not edited\n  agentguard connect <key> [--write]  point this machine at your hosted proxy (paid tiers)\n\n  agentguard proxy [--http --port 8788] [--agent name] [--run-id id] [--mode dry-run|enforce]\n  agentguard tools [--json]           the tools your agent will see, with class and why\n  agentguard status [--run id]        counters vs caps, kill state, pending approvals\n\n  agentguard kill [reason]            halt every run now (file + running HTTP proxy);  agentguard resume\n  agentguard approvals [--all]        pending approvals;  agentguard approve <id> | deny <id> [--note text]\n  agentguard key create <agent> [--allow 'crm_get_*']... [--deny p] [--writes n] [--spend n] [--mode m]\n  agentguard key list | revoke <agent>\n  agentguard permission-diff [--base ref] [--head ref] [--paths a,b] [--format markdown|json] [--fail-on-widen]\n\nOptions: --config <agentguard.yaml> (or AGENTGUARD_CONFIG), --json, --help, --version\nDocs: https://github.com/agentwares/agentguard/tree/main/apps/agentguard-cli";
 declare function main(argv: readonly string[], io?: Io): Promise<number>;
 
 export { type CallContext, type ClientConfigFile, type CrmState, DEFAULT_PERMISSION_PATHS, type DemoOptions, type DemoStep, type DownstreamOptions, type DownstreamSession, type ExposedTool, type FileGuard, HELP, type HttpProxy, type HttpProxyOptions, type HttpRegistration, type Io, type PermissionDiffResult, type ProbeResult, type ProbedTool, ProxyRuntime, type RuntimeOptions, type ServerEntry, type UpstreamStatus, approvalSlackMessage, candidateConfigs, createAlerter, createCrmMcpServer, createDownstreamServer, createFileGuard, crmTools, detectClientConfigs, haltSlackMessage, loadPolicyFor, main, probeUpstreams, proxyEntry, readRegistration, readServers, registrationPath, renderStarterPolicy, restoreClientConfig, rewriteClientConfig, runDemoAgent, runIdFor, runPermissionDiff, seedState, serversToUpstreams, startHttpProxy, toCallToolResult };

package/dist/index.js

@@ -806,6 +806,21 @@ var require_dist = __commonJS({
 
 // src/proxy/runtime.ts
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+
+// src/version.ts
+import { readFileSync } from "fs";
+var cached;
+function version() {
+  if (cached !== void 0) return cached;
+  try {
+    cached = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+  } catch {
+    cached = "0.0.0";
+  }
+  return cached;
+}
+
+// src/proxy/runtime.ts
 import {
   getDefaultEnvironment,
   StdioClientTransport
@@ -886,7 +901,7 @@ var ProxyRuntime = class {
   }
   async connect(upstream) {
     const client = new Client(
-      { name: "agentguard", version: "0.1.0" },
+      { name: "agentguard", version: version() },
       { capabilities: { sampling: {}, elicitation: {} } }
     );
     const conn = {
@@ -1331,7 +1346,7 @@ import {
   keyFromHeaders,
   resolveAgent
 } from "@agentwares/agentguard-core";
-var PROXY_VERSION = "0.1.0";
+var PROXY_VERSION = version();
 function headerValue(extra, name) {
   const raw = extra.requestInfo?.headers?.[name] ?? extra.requestInfo?.headers?.[name.toLowerCase()];
   if (Array.isArray(raw)) return raw[0];
@@ -1559,7 +1574,7 @@ function createDownstreamServer(runtime, opts = {}) {
   return server;
 }
 
-// ../../packages/mcp-kit/dist/chunk-AO7AV7MI.js
+// ../../packages/mcp-kit/dist/chunk-NF4BQXVM.js
 import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import {
@@ -1571,6 +1586,7 @@ import {
 import { z } from "zod";
 
 // ../../packages/x402/dist/index.js
+var DEFAULT_X402_NETWORK = "eip155:8453";
 var X402_HEADER = "X-Payment-Requirements";
 var X402_REQUIRED_HEADER = "PAYMENT-REQUIRED";
 function toAmount(priceUsd) {
@@ -1580,42 +1596,51 @@ function toAmount(priceUsd) {
 }
 function buildPaymentRequired(opts) {
   const amountUsd = toAmount(opts.priceUsd);
-  const accepts = [
-    {
+  const creditsPayTo = opts.creditsPayTo ?? opts.selfServe?.keysUrl;
+  const accepts = [];
+  if (opts.payTo) {
+    accepts.push({
       rail: "x402",
       amountUsd,
       resource: opts.resource,
       description: opts.description,
-      network: "eip155:8453",
+      network: opts.network ?? DEFAULT_X402_NETWORK,
       asset: "USDC",
       payTo: opts.payTo,
       maxTimeoutSeconds: 300
-    },
-    {
-      rail: "mpp",
+    });
+  }
+  if (creditsPayTo) {
+    accepts.push({
+      rail: "prepaid_credits",
       amountUsd,
       resource: opts.resource,
       description: opts.description,
       currency: "usd",
-      payTo: opts.payTo,
-      maxTimeoutSeconds: 300
-    }
-  ];
+      payTo: creditsPayTo,
+      maxTimeoutSeconds: 300,
+      // funding a balance ends at a hosted Stripe Checkout page, which an agent cannot fill in
+      humanRequired: true
+    });
+  }
   const live = opts.live === true;
+  const selfServe = opts.selfServe;
+  const liveFix = selfServe ? `Free first: retry with sample=true \u2014 no key, no payment. To pay: POST ${selfServe.keysUrl} (no auth, no signup) returns a key and a Stripe Checkout URL. Funding that key needs a person to complete the Checkout page in a browser; if you are running unattended, surface the URL to your operator rather than retrying. Once funded, send Authorization: Bearer <key>, plus Idempotency-Key so a repeated call is charged once.` : "Retry with a PAYMENT header satisfying one of `accepts`, or send an API key with credit balance.";
   const body = {
     code: "PAYMENT_REQUIRED",
     cause: live ? `This call costs $${amountUsd}. No valid payment or credit was presented.` : `This call costs $${amountUsd}. Pay-per-call (x402 / Stripe MPP) is coming soon; use an API key with prepaid credits.`,
-    fix: live ? "Retry with a PAYMENT header satisfying one of `accepts`, or send an API key with credit balance." : `Create an API key${opts.signupUrl ? ` at ${opts.signupUrl}` : ""} and retry with Authorization: Bearer <key>. Try the free sample mode first.`,
+    fix: live ? liveFix : `Create an API key${opts.signupUrl ? ` at ${opts.signupUrl}` : ""} and retry with Authorization: Bearer <key>. Try the free sample mode first.`,
     retryable: true,
     priceUsd: opts.priceUsd,
     accepts,
     comingSoon: !live,
-    alternatives: ["api_key_credits", "sample_mode"]
+    alternatives: ["api_key_credits", "sample_mode"],
+    ...selfServe ? { selfServe } : {}
   };
   const encoded = JSON.stringify({ x402Version: 2, accepts, resource: opts.resource });
   const headers = {
     "Content-Type": "application/json",
-    "WWW-Authenticate": `Payment realm="agentwares", methods="x402 mpp", price="${amountUsd} USD"`,
+    "WWW-Authenticate": `Payment realm="agentwares", methods="x402 prepaid_credits", price="${amountUsd} USD"`,
     [X402_HEADER]: encoded,
     [X402_REQUIRED_HEADER]: btoa(encoded),
     "Cache-Control": "no-store"
@@ -1633,7 +1658,7 @@ var StubVerifier = class {
   }
 };
 
-// ../../packages/mcp-kit/dist/chunk-AO7AV7MI.js
+// ../../packages/mcp-kit/dist/chunk-NF4BQXVM.js
 import { z as z2 } from "zod";
 import { z as z3 } from "zod";
 import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -1815,13 +1840,13 @@ function defineTool(opts) {
     annotations,
     handler,
     async invoke(rawInput, ctx) {
-      const fail = (err) => {
+      const fail2 = (err) => {
         const result = errorResult(err, { requestId: ctx.requestId });
         if (output) delete result.structuredContent;
         return result;
       };
       const parsed = input.safeParse(rawInput ?? {});
-      if (!parsed.success) return fail(invalidInputError(parsed.error.issues));
+      if (!parsed.success) return fail2(invalidInputError(parsed.error.issues));
       try {
         const value = await handler(parsed.data, ctx);
         if (output && !isCallToolResult(value)) {
@@ -1839,7 +1864,7 @@ function defineTool(opts) {
         }
         return toCallToolResult2(value);
       } catch (err) {
-        return fail(err);
+        return fail2(err);
       }
     }
   };
@@ -2080,6 +2105,7 @@ function withPayment(tool, opts) {
     );
   }
   const verifier = opts.verifier ?? new StubVerifier();
+  const liveRail = opts.verifier !== void 0;
   const input = tool.input.extend({
     [sampleField]: z2.boolean().default(false).describe(
       "Set true to return an example response at no charge (sample mode). Default false."
@@ -2110,17 +2136,35 @@ function withPayment(tool, opts) {
         live: opts.live,
         description: opts.description,
         payTo: opts.payTo,
-        signupUrl: opts.signupUrl
+        creditsPayTo: opts.creditsPayTo,
+        signupUrl: opts.signupUrl,
+        selfServe: opts.selfServe
       });
-      const requirement = required.body.accepts[0];
-      if (requirement) {
-        const verified = await verifier.verify(
-          new Request(`https://mcp.local/${tool.name}`, { headers: ctx.headers }),
-          requirement
-        );
-        if (verified.ok) return tool.handler(record, ctx);
-        reason = reason ?? verified.reason;
+      const advertised = required.body.accepts.find((a) => a.rail === "prepaid_credits") ?? required.body.accepts[0];
+      const requirement = advertised ?? {
+        rail: "prepaid_credits",
+        amountUsd: String(required.body.priceUsd),
+        resource: tool.name
+      };
+      const verified = await verifier.verify(
+        new Request(`https://mcp.local/${tool.name}`, { headers: ctx.headers }),
+        requirement
+      );
+      if (verified.ok) {
+        let result;
+        try {
+          result = await tool.handler(record, ctx);
+        } catch (error) {
+          await opts.onPaidFailure?.(ctx, verified, error);
+          throw error;
+        }
+        const settled = await verifier.settle?.(verified);
+        if (settled && !settled.ok) {
+          opts.onSettlementFailure?.(ctx, verified, settled.reason);
+        }
+        return result;
       }
+      reason = liveRail ? verified.reason ?? reason : reason ?? verified.reason;
       throw paymentRequiredError(required.body, reason);
     }
   });
@@ -2809,7 +2853,7 @@ import {
   FileStateStore,
   loadPolicyFile
 } from "@agentwares/agentguard-core/node";
-import { existsSync as exists, readFileSync } from "fs";
+import { existsSync as exists, readFileSync as readFileSync2 } from "fs";
 
 // ../../node_modules/.pnpm/postal-mime@2.7.5/node_modules/postal-mime/src/decode-strings.js
 var textEncoder = new TextEncoder();
@@ -2842,8 +2886,8 @@ var MAX_HEADERS_SIZE = 2 * 1024 * 1024;
 
 // ../../node_modules/.pnpm/resend@6.25.0/node_modules/resend/dist/index.mjs
 var import_standardwebhooks = __toESM(require_dist(), 1);
-var version = "6.25.0";
-var defaultUserAgent = `resend-node:${version}`;
+var version2 = "6.25.0";
+var defaultUserAgent = `resend-node:${version2}`;
 
 // ../../packages/notify/dist/index.js
 var palette = {
@@ -3193,7 +3237,7 @@ function readRegistration(loaded) {
   const file = registrationPath(loaded.stateDir);
   if (!exists(file)) return void 0;
   try {
-    const reg = JSON.parse(readFileSync(file, "utf8"));
+    const reg = JSON.parse(readFileSync2(file, "utf8"));
     return reg;
   } catch {
     return void 0;
@@ -3209,7 +3253,7 @@ function describeError(err) {
 }
 
 // src/configs.ts
-import { copyFileSync, existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { copyFileSync, existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
 import { homedir as homedir2, platform } from "os";
 import { join as join2, resolve as resolve2 } from "path";
 function candidateConfigs(cwd = process.cwd(), home = homedir2(), env = process.env) {
@@ -3272,7 +3316,7 @@ function describeConfigPath(path2) {
   if (known) return known;
   let serversKey = "mcpServers";
   try {
-    const parsed = JSON.parse(readFileSync2(abs, "utf8"));
+    const parsed = JSON.parse(readFileSync3(abs, "utf8"));
     if (parsed.servers && !parsed.mcpServers) serversKey = "servers";
   } catch {
   }
@@ -3284,7 +3328,7 @@ function describeConfigPath(path2) {
   };
 }
 function readServers(file) {
-  const raw = JSON.parse(readFileSync2(file.path, "utf8"));
+  const raw = JSON.parse(readFileSync3(file.path, "utf8"));
   const servers = raw[file.serversKey];
   if (!servers || typeof servers !== "object") return {};
   return servers;
@@ -3340,7 +3384,7 @@ function proxyEntry(file, policyPath, opts = {}) {
   return entry;
 }
 function rewriteClientConfig(file, policyPath, opts = {}) {
-  const raw = JSON.parse(readFileSync2(file.path, "utf8"));
+  const raw = JSON.parse(readFileSync3(file.path, "utf8"));
   const servers = raw[file.serversKey] ?? {};
   const replaced = Object.keys(servers).filter((n) => !isProxyEntry(servers[n]));
   const backup = backupPath(file);
@@ -3355,6 +3399,16 @@ function restoreClientConfig(file) {
   copyFileSync(backup, file.path);
   return true;
 }
+function mergeServerIntoConfig(file, name, entry) {
+  const raw = JSON.parse(readFileSync3(file.path, "utf8"));
+  const servers = raw[file.serversKey] ?? {};
+  const replaced = name in servers;
+  const backup = backupPath(file);
+  if (!existsSync3(backup)) copyFileSync(file.path, backup);
+  raw[file.serversKey] = { ...servers, [name]: entry };
+  writeFileSync2(file.path, JSON.stringify(raw, null, 2) + "\n");
+  return { backup, replaced };
+}
 
 // src/commands/init.ts
 import { existsSync as existsSync4, writeFileSync as writeFileSync3 } from "fs";
@@ -4083,8 +4137,111 @@ ${steps.length} calls; halts: ${halts.join(", ") || "none"}. Now run: agentguard
   }
 }
 
-// src/cli.ts
-import { readFileSync as readFileSync4 } from "fs";
+// src/commands/connect.ts
+import { existsSync as existsSync5 } from "fs";
+import { relative as relative2 } from "path";
+var DEFAULT_PROXY_URL = "https://agentwares-agentguard-proxy.vercel.app";
+function fail(e) {
+  throw e;
+}
+async function connectCommand(args, io, fetchImpl = fetch) {
+  const key = args.positionals[0] ?? io.env.AGENTGUARD_KEY;
+  if (!key) {
+    io.err("usage: agentguard connect <key> [--write] [--client <path>] [--url <proxy-url>]");
+    io.err("  the key is on your dashboard; it starts with agk_");
+    return 2;
+  }
+  const base = (flagString(args, "url") ?? io.env.AGENTGUARD_PROXY_URL ?? DEFAULT_PROXY_URL).replace(/\/+$/, "");
+  let res;
+  try {
+    res = await fetchImpl(`${base}/connect`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ key })
+    });
+  } catch (err) {
+    fail({
+      code: "PROXY_UNREACHABLE",
+      cause: `could not reach ${base}: ${err instanceof Error ? err.message : String(err)}`,
+      fix: "check the network, or pass --url if you run your own proxy",
+      retryable: true
+    });
+  }
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    fail({
+      code: "PROXY_BAD_RESPONSE",
+      cause: `${base}/connect returned ${res.status} that was not JSON: ${text.slice(0, 200)}`,
+      fix: "check --url points at an agentguard proxy, not at the dashboard",
+      retryable: false
+    });
+  }
+  if (!res.ok) {
+    const e = body;
+    fail({
+      code: e.code ?? "CONNECT_REFUSED",
+      cause: e.cause ?? `${base}/connect returned ${res.status}`,
+      fix: e.fix ?? "check the key on your dashboard; revoked keys stop working immediately",
+      retryable: e.retryable ?? false
+    });
+  }
+  const conn = body;
+  if (flagBool(args, "json")) {
+    io.out(JSON.stringify(conn, null, 2));
+    return 0;
+  }
+  const rel = (p) => p.startsWith(io.cwd + "/") ? relative2(io.cwd, p) : p;
+  const entry = conn.mcpServers[PROXY_SERVER_NAME] ?? {
+    type: "http",
+    url: conn.mcpUrl,
+    headers: conn.headers
+  };
+  if (!flagBool(args, "write")) {
+    io.out(JSON.stringify({ mcpServers: { [PROXY_SERVER_NAME]: entry } }, null, 2));
+  } else {
+    const explicit = flagString(args, "client");
+    const configs = explicit ? [describeConfigPath(explicit)] : detectClientConfigs(io.cwd, homeFrom(io), io.env);
+    const projectLevel = configs.filter((c) => c.path.startsWith(io.cwd + "/"));
+    let chosen;
+    if (explicit || flagBool(args, "all")) chosen = configs;
+    else chosen = projectLevel.slice(0, 1);
+    if (chosen.length === 0) {
+      io.err(
+        "no MCP config found here (.mcp.json, .cursor/mcp.json, .vscode/mcp.json). Create one, or paste this into your client:"
+      );
+      io.out(JSON.stringify({ mcpServers: { [PROXY_SERVER_NAME]: entry } }, null, 2));
+      return 1;
+    }
+    for (const c of chosen) {
+      if (!existsSync5(c.path)) {
+        io.err(`no MCP config at ${c.path}`);
+        return 1;
+      }
+      const { backup, replaced } = mergeServerIntoConfig(c, PROXY_SERVER_NAME, entry);
+      io.out(
+        `${replaced ? "updated" : "wrote  "} ${rel(c.path)} (${c.label}) \u2192 ${PROXY_SERVER_NAME} = ${conn.mcpUrl}`
+      );
+      io.out(`backup  ${rel(backup)}`);
+    }
+    for (const c of configs.filter((c2) => !chosen.includes(c2)))
+      io.out(
+        `found   ${c.path} (${c.label}, user-level) \u2014 not touched; pass --client ${JSON.stringify(c.path)} to write it too`
+      );
+  }
+  const band = conn.band ? ` band=${conn.band.tier} (${conn.band.quantity} calls/mo)` : "";
+  io.out(`
+proxy ${conn.slug} (${conn.proxyId}) mode=${conn.mode}${band}`);
+  if (conn.upstreams?.length) io.out(`upstreams: ${conn.upstreams.join(", ")}`);
+  if (conn.dashboardUrl) io.out(`dashboard: ${conn.dashboardUrl}`);
+  if (conn.claudeCode) io.out(`claude code: ${conn.claudeCode}`);
+  if (!flagBool(args, "write"))
+    io.out(`
+run again with --write to add this to your MCP client config`);
+  return 0;
+}
 
 // src/commands/control.ts
 async function pokeHttp(io, reg, path2, body) {
@@ -4178,13 +4335,13 @@ async function approvalsCommand(args, io) {
 }
 
 // src/commands/keys.ts
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "fs";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
 import YAML2, { isMap, isSeq, YAMLSeq } from "yaml";
 import { generateAgentKey, hashAgentKey } from "@agentwares/agentguard-core";
 async function keyCommand(args, io) {
   const [sub, name] = args.positionals;
   const path2 = policyPathFrom(args, io);
-  const doc = YAML2.parseDocument(readFileSync3(path2, "utf8"));
+  const doc = YAML2.parseDocument(readFileSync4(path2, "utf8"));
   let agents = doc.get("agents");
   if (!isSeq(agents)) {
     agents = new YAMLSeq();
@@ -4461,19 +4618,13 @@ async function statusCommand(args, io) {
 }
 
 // src/cli.ts
-function version2() {
-  try {
-    return JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8")).version;
-  } catch {
-    return "0.0.0";
-  }
-}
 var HELP = `agentguard \u2014 MCP policy proxy for agents that touch production
 
   npx @agentwares/agentguard init                 read your MCP config, write agentguard.yaml (dry-run), route every server through the proxy
   agentguard report [--run id|--all]  what this run did / would have destroyed / spent, where it was halted
   agentguard diff [--run id]          record-by-record mutation diff from a dry run
   agentguard verify [audit.jsonl]     prove the hash-chained audit log was not edited
+  agentguard connect <key> [--write]  point this machine at your hosted proxy (paid tiers)
 
   agentguard proxy [--http --port 8788] [--agent name] [--run-id id] [--mode dry-run|enforce]
   agentguard tools [--json]           the tools your agent will see, with class and why
@@ -4490,7 +4641,7 @@ Docs: https://github.com/agentwares/agentguard/tree/main/apps/agentguard-cli`;
 async function main(argv, io = defaultIo()) {
   const args = parseArgs(argv);
   if (args.flags.version) {
-    io.out(version2());
+    io.out(version());
     return 0;
   }
   if (args.command === void 0 && !args.flags.help && io.tty === false) {
@@ -4518,6 +4669,8 @@ async function main(argv, io = defaultIo()) {
         return await diffCommand(args, io);
       case "verify":
         return await verifyCommand(args, io);
+      case "connect":
+        return await connectCommand(args, io);
       case "status":
         return await statusCommand(args, io);
       case "tools":