@agentwares/agentguard 0.1.5 → 0.1.7

package/dist/cli.js

@@ -925,7 +925,7 @@ function version() {
 }
 
 // src/context.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { resolve } from "path";
 import { Guard } from "@agentwares/agentguard-core";
 import {
@@ -935,7 +935,7 @@ import {
   FileStateStore,
   loadPolicyFile
 } from "@agentwares/agentguard-core/node";
-import { existsSync as exists, readFileSync as readFileSync2 } from "fs";
+import { existsSync as exists, readFileSync as readFileSync3 } from "fs";
 
 // ../../packages/mcp-kit/dist/chunk-7LRFDQNC.js
 import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
@@ -1161,6 +1161,10 @@ function errorResult(err, opts = {}) {
     _meta: meta
   };
 }
+function createToolContext(init = {}) {
+  const { headers, ...rest } = init;
+  return { headers: headers ?? new Headers(), ...rest };
+}
 var TOOL_NAME_PATTERN = /^[a-z][a-z0-9]*(_[a-z0-9]+)+$/;
 var MIN_NAMESPACE_LENGTH = 3;
 var MIN_DESCRIPTION_LENGTH = 20;
@@ -1914,6 +1918,48 @@ function localhostHosts(port) {
   return [...hosts, ...hosts.map((h) => `${h}:${port}`)];
 }
 
+// ../../packages/mcp-kit/dist/chunk-M567BWMA.js
+var LIST_MAX_PAGES = 20;
+var LIST_MAX_ITEMS = 2e3;
+async function readAllPages(fetchPage, opts = {}) {
+  const maxPages = opts.maxPages ?? LIST_MAX_PAGES;
+  const maxItems = opts.maxItems ?? LIST_MAX_ITEMS;
+  const method = opts.method ?? "tools/list";
+  const items = [];
+  const followed = /* @__PURE__ */ new Set();
+  let cursor;
+  for (let page = 1; ; page++) {
+    const res = await fetchPage(cursor, page);
+    if (Array.isArray(res.items)) items.push(...res.items);
+    const next = res.nextCursor;
+    const more = typeof next === "string" && next !== "";
+    if (items.length > maxItems) {
+      return {
+        items,
+        pages: page,
+        truncated: {
+          ceiling: "items",
+          reason: `${method} listed more than ${maxItems} items in ${page} page${page === 1 ? "" : "s"}${more ? " and had more" : ""}; at most ${maxItems} are read`
+        }
+      };
+    }
+    if (!more) return { items, pages: page };
+    if (followed.has(next)) return { items, pages: page, repeatedCursor: true };
+    if (page >= maxPages) {
+      return {
+        items,
+        pages: page,
+        truncated: {
+          ceiling: "pages",
+          reason: `${method} had more than ${maxPages} pages (${items.length} items read); at most ${maxPages} pages are read`
+        }
+      };
+    }
+    followed.add(next);
+    cursor = next;
+  }
+}
+
 // ../../packages/mcp-kit/dist/index.js
 import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
 async function serveStdio(serverOrOpts) {
@@ -1931,7 +1977,7 @@ async function serveStdio(serverOrOpts) {
 }
 
 // src/proxy/http.ts
-import { writeFileSync, unlinkSync, existsSync, mkdirSync } from "fs";
+import { writeFileSync, unlinkSync, existsSync as existsSync2, mkdirSync } from "fs";
 import { createServer } from "http";
 import { join } from "path";
 import { FileKillSwitch } from "@agentwares/agentguard-core/node";
@@ -1955,6 +2001,278 @@ import {
   keyFromHeaders,
   resolveAgent
 } from "@agentwares/agentguard-core";
+
+// src/proxy/own-tools.ts
+import {
+  buildReport,
+  latestRunId,
+  listRuns,
+  parseAuditJsonl,
+  renderReportMarkdown,
+  verifyChain
+} from "@agentwares/agentguard-core";
+import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { z as z5 } from "zod";
+var INIT_COMMAND = "npx -y @agentwares/agentguard init";
+var READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var runIdInput = z5.string().min(1).max(128).optional().describe(
+  "Run to read, as it appears in the audit log (for example run_20261007093015_ab12, or the X-Run-Id an HTTP client sent). Omit it for the most recent run."
+);
+var counters = z5.record(z5.string(), z5.number()).describe(
+  "counter name (tool_calls, writes, deletes, emails, spend_usd or a custom one) \u2192 value"
+);
+function readAudit(path) {
+  if (!existsSync(path)) return { exists: false, entries: [] };
+  try {
+    return { exists: true, entries: parseAuditJsonl(readFileSync2(path, "utf8")) };
+  } catch (err) {
+    return { exists: true, entries: [], error: err instanceof Error ? err.message : String(err) };
+  }
+}
+function unreadable(path, error) {
+  return toolError({
+    code: "AUDIT_UNREADABLE",
+    cause: `the audit log at ${path} could not be read: ${error}`,
+    fix: "call agentguard_verify_audit_log to see where it breaks; a hand-edited or truncated line has to be restored from a copy",
+    retryable: false
+  });
+}
+function numbers(caps) {
+  const out = {};
+  for (const [k, v] of Object.entries(caps)) if (typeof v === "number") out[k] = v;
+  return out;
+}
+function nextStep(runtime) {
+  if (!runtime.configured)
+    return `agentguard is guarding nothing: no policy file at ${runtime.loaded.path}. Run \`${INIT_COMMAND}\` in the project directory: it writes agentguard.yaml in dry-run mode and routes the project's MCP servers through agentguard (backup kept, \`--undo\` restores). Then restart the MCP client.`;
+  if (runtime.policy.upstreams.length === 0)
+    return `${runtime.loaded.path} lists no upstream servers, so agentguard is guarding nothing. Add the MCP servers your agent uses under \`upstreams:\` in that file (it has commented examples), then restart the MCP client.`;
+  return "agentguard is running; run your agent, then read agentguard_get_report.";
+}
+var StatusOutput = z5.object({
+  configured: z5.boolean().describe(
+    "true when a policy file was found and loaded; false means agentguard guards nothing"
+  ),
+  policy_path: z5.string().describe("absolute path of the policy file read, or looked for"),
+  mode: z5.enum(["dry-run", "enforce"]).describe("dry-run fakes writes and spends and records them; enforce lets allowed calls run"),
+  upstreams: z5.array(
+    z5.object({
+      name: z5.string().describe("upstream name from the policy"),
+      connected: z5.boolean().describe("whether agentguard is connected to it"),
+      tools: z5.number().int().describe("tools it exposes"),
+      transport: z5.enum(["stdio", "http"]).describe("how agentguard reaches it"),
+      error: z5.string().optional().describe("why it is not connected")
+    })
+  ).describe("the MCP servers this proxy fronts; empty means none are configured"),
+  run_id: z5.string().nullable().describe(
+    "run the usage is for: the requested run_id, else the latest run in the log, else null"
+  ),
+  caps: z5.object({ per_run: counters, per_day: counters }).describe("limits from the policy; a counter that is absent has no cap"),
+  used: z5.object({ per_run: counters, per_day: counters }).describe("what that run, and today, have used against the caps"),
+  remaining: z5.record(
+    z5.string(),
+    z5.object({ per_run: z5.number().optional(), per_day: z5.number().optional() })
+  ).describe("budget left per capped counter, per run and per day"),
+  kill_switch: z5.object({
+    on: z5.boolean().describe("true halts every tool call with KILLED"),
+    reason: z5.string().optional().describe("why it was pulled"),
+    source: z5.string().optional().describe("file, env or memory")
+  }).describe("the kill switch state"),
+  pending_approvals: z5.number().int().describe("destructive calls waiting for a human decision"),
+  audit_log: z5.object({
+    path: z5.string().describe("absolute path of the hash-chained JSONL audit log"),
+    entries: z5.number().int().describe("entries in it; 0 when it does not exist yet")
+  }).describe("where every tool call is recorded"),
+  next_step: z5.string().describe("the one thing to do next, with the command when there is one")
+});
+var ReportOutput = z5.object({
+  configured: z5.boolean().describe("false when no policy file was found (agentguard guards nothing)"),
+  audit_log_path: z5.string().describe("absolute path of the audit log the report was built from"),
+  run_id: z5.string().nullable().describe("the run reported on; null when the log has no runs"),
+  runs_in_log: z5.number().int().describe("how many runs the audit log holds"),
+  tool_calls: z5.number().int().describe("tool calls in this run"),
+  would_have: z5.object({
+    creates: z5.number().int(),
+    updates: z5.number().int(),
+    deletes: z5.number().int(),
+    sends: z5.number().int(),
+    executes: z5.number().int(),
+    spends: z5.number().int(),
+    spend_usd: z5.number()
+  }).describe("what dry-run mode faked: what the run would have done had the calls executed"),
+  did: z5.object({
+    writes: z5.number().int(),
+    deletes: z5.number().int(),
+    sends: z5.number().int(),
+    spend_usd: z5.number()
+  }).describe("what actually executed upstream"),
+  halts: z5.array(
+    z5.object({
+      seq: z5.number().int().describe("audit entry number"),
+      ts: z5.string().describe("ISO time of the call"),
+      code: z5.string().describe("CAP_EXCEEDED, LOOP_DETECTED, KILLED, APPROVAL_REQUIRED, \u2026"),
+      tool: z5.string().describe("the tool that was stopped"),
+      cause: z5.string().describe("why")
+    })
+  ).describe("every call agentguard stopped, in order"),
+  top_tools: z5.array(z5.object({ tool: z5.string(), calls: z5.number().int(), class: z5.string() })).describe("the most-called tools with their class (read, write, spend)"),
+  markdown: z5.string().describe("the same report `agentguard report` prints, as Markdown")
+});
+var VerifyOutput = z5.object({
+  configured: z5.boolean().describe("false when no policy file was found (agentguard guards nothing)"),
+  path: z5.string().describe("absolute path of the audit log checked"),
+  exists: z5.boolean().describe("false when no call has been recorded yet; an absent log verifies"),
+  ok: z5.boolean().describe("true when every entry's hash and prev_hash recompute"),
+  entries: z5.number().int().describe("entries checked"),
+  head_hash: z5.string().nullable().describe(
+    "hash of the last entry; record it with the count to detect entries cut from the end"
+  ),
+  broken_at: z5.number().int().nullable().describe("seq of the first entry that does not verify"),
+  reason: z5.string().nullable().describe("why verification failed")
+});
+function createOwnTools(runtime) {
+  const status = defineTool({
+    name: "agentguard_get_status",
+    title: "agentguard status",
+    description: "Report what agentguard is guarding right now: the policy file it loaded (or that none was found), dry-run or enforce mode, each upstream MCP server and whether it connected, a run's cap usage and remaining budget, the kill switch, and pending approvals. Call it first to learn whether agentguard is set up; next_step says what to do when it is not. For what a run did, use agentguard_get_report; to check the log was not edited, agentguard_verify_audit_log. Reads local files only and changes nothing.",
+    input: z5.strictObject({ run_id: runIdInput }),
+    output: StatusOutput,
+    annotations: { title: "agentguard status", ...READ_ONLY },
+    async handler({ run_id }) {
+      const { loaded, guard } = runtime;
+      const audit = readAudit(loaded.auditPath);
+      if (audit.error) throw unreadable(loaded.auditPath, audit.error);
+      const runId = run_id ?? latestRunId(audit.entries) ?? null;
+      const state = await guard.status(runId ?? "(none yet)");
+      const pending = await guard.approvals.list("pending");
+      return {
+        configured: runtime.configured,
+        policy_path: loaded.path,
+        mode: runtime.policy.mode,
+        upstreams: runtime.upstreamStatus(),
+        run_id: runId,
+        caps: { per_run: numbers(state.caps.per_run), per_day: numbers(state.caps.per_day) },
+        used: state.usage,
+        remaining: state.remaining,
+        kill_switch: {
+          on: state.killed.killed,
+          ...state.killed.reason ? { reason: state.killed.reason } : {},
+          ...state.killed.source ? { source: state.killed.source } : {}
+        },
+        pending_approvals: pending.length,
+        audit_log: { path: loaded.auditPath, entries: audit.entries.length },
+        next_step: nextStep(runtime)
+      };
+    }
+  });
+  const report = defineTool({
+    name: "agentguard_get_report",
+    title: "agentguard run report",
+    description: "Summarize one run from agentguard's audit log: how many tool calls, what dry-run mode faked (records it would have created, updated or deleted, messages sent, dollars spent), what really ran upstream, and every call agentguard halted with its code and cause. Defaults to the most recent run. Use it after an agent run, before switching a policy from dry-run to enforce; for live caps and the kill switch use agentguard_get_status. Read-only: reads the audit file and does not record this call.",
+    input: z5.strictObject({ run_id: runIdInput }),
+    output: ReportOutput,
+    annotations: { title: "agentguard run report", ...READ_ONLY },
+    handler({ run_id }) {
+      const { loaded } = runtime;
+      const audit = readAudit(loaded.auditPath);
+      if (audit.error) throw unreadable(loaded.auditPath, audit.error);
+      const runs = listRuns(audit.entries);
+      if (run_id && !runs.some((r) => r.runId === run_id)) {
+        throw toolError({
+          code: "NOT_FOUND",
+          cause: `no run "${run_id}" in the audit log at ${loaded.auditPath}`,
+          fix: `call again without run_id for the latest run${runs.length ? `; runs in the log: ${runs.slice(0, 5).map((r) => r.runId).join(", ")}` : "; the log has no runs yet"}`,
+          retryable: false
+        });
+      }
+      const runId = run_id ?? latestRunId(audit.entries) ?? null;
+      const built = buildReport(audit.entries, { runId: runId ?? void 0 });
+      const markdown = runId ? renderReportMarkdown(built) : `# agentguard report
+
+No runs recorded in ${loaded.auditPath} yet. ${nextStep(runtime)}`;
+      return {
+        configured: runtime.configured,
+        audit_log_path: loaded.auditPath,
+        run_id: runId,
+        runs_in_log: runs.length,
+        tool_calls: runId ? audit.entries.filter((e) => e.run_id === runId).length : 0,
+        would_have: {
+          creates: built.wouldHave.creates,
+          updates: built.wouldHave.updates,
+          deletes: built.wouldHave.deletes,
+          sends: built.wouldHave.sends,
+          executes: built.wouldHave.executes,
+          spends: built.wouldHave.spends,
+          spend_usd: built.wouldHave.spendUsd
+        },
+        did: {
+          writes: built.did.writes,
+          deletes: built.did.deletes,
+          sends: built.did.sends,
+          spend_usd: built.did.spendUsd
+        },
+        halts: built.halts,
+        top_tools: built.topTools,
+        markdown
+      };
+    }
+  });
+  const verify = defineTool({
+    name: "agentguard_verify_audit_log",
+    title: "Verify agentguard audit log",
+    description: "Recompute the hash chain of agentguard's audit log (JSONL, one entry per tool call) and say whether any entry was edited, removed from the middle or reordered, naming the first broken entry. Returns the entry count and head hash; record both elsewhere, because entries cut from the end of the file still verify. Use it before trusting agentguard_get_report. Takes no arguments: it checks the log the loaded policy names. Read-only; a log that does not exist yet verifies as empty.",
+    input: z5.strictObject({}),
+    output: VerifyOutput,
+    annotations: { title: "Verify agentguard audit log", ...READ_ONLY },
+    async handler() {
+      const { loaded } = runtime;
+      const audit = readAudit(loaded.auditPath);
+      if (audit.error) {
+        return {
+          configured: runtime.configured,
+          path: loaded.auditPath,
+          exists: true,
+          ok: false,
+          entries: 0,
+          head_hash: null,
+          broken_at: null,
+          reason: audit.error
+        };
+      }
+      const result = await verifyChain(audit.entries);
+      return {
+        configured: runtime.configured,
+        path: loaded.auditPath,
+        exists: audit.exists,
+        ok: result.ok,
+        entries: result.entries,
+        // an empty chain's head is the genesis hash, which is not an entry anyone can record
+        head_hash: result.entries > 0 ? result.head ?? null : null,
+        broken_at: result.brokenAt ?? null,
+        reason: result.reason ?? null
+      };
+    }
+  });
+  return [status, report, verify];
+}
+function ownToolsActive(runtime) {
+  return runtime.upstreamStatus().length === 0;
+}
+function ownToolList(tools) {
+  return listToolManifest(tools);
+}
+async function callOwnTool(tools, name, args, requestId) {
+  const tool = tools.find((t) => t.name === name);
+  if (!tool) return void 0;
+  return tool.invoke(args, createToolContext({ requestId }));
+}
+
+// src/proxy/server.ts
 var PROXY_VERSION = version();
 function headerValue(extra, name) {
   const raw = extra.requestInfo?.headers?.[name] ?? extra.requestInfo?.headers?.[name.toLowerCase()];
@@ -2055,6 +2373,11 @@ function killedError(state) {
     { code: -32e3 }
   );
 }
+function serverInstructions(runtime) {
+  if (ownToolsActive(runtime))
+    return `agentguard is an MCP policy proxy, and this one fronts no upstream MCP servers${runtime.configured ? "" : ` (no policy file at ${runtime.loaded.path})`}, so it serves only its own read-only tools: agentguard_get_status (what it guards, caps, kill switch), agentguard_get_report (what a run did or would have done) and agentguard_verify_audit_log. To guard the user's MCP servers, run \`${INIT_COMMAND}\` in the project directory and restart the client.`;
+  return `Tool calls pass through agentguard (${runtime.policy.mode} mode). Errors carry { code, cause, fix, retryable }; follow "fix". CAP_EXCEEDED, LOOP_DETECTED and KILLED are not retryable: stop and report to the user. APPROVAL_REQUIRED: relay the approval command to the user, then retry the identical call once.`;
+}
 function createDownstreamServer(runtime, opts = {}) {
   const server = new McpServer3(
     { name: "agentguard", version: PROXY_VERSION, title: "agentguard policy proxy" },
@@ -2066,9 +2389,10 @@ function createDownstreamServer(runtime, opts = {}) {
         logging: {},
         completions: {}
       },
-      instructions: `Tool calls pass through agentguard (${runtime.policy.mode} mode). Errors carry { code, cause, fix, retryable }; follow "fix". CAP_EXCEEDED, LOOP_DETECTED and KILLED are not retryable: stop and report to the user. APPROVAL_REQUIRED: relay the approval command to the user, then retry the identical call once.`
+      instructions: serverInstructions(runtime)
     }
   );
+  const ownTools = createOwnTools(runtime);
   const session = {
     id: crypto.randomUUID(),
     server,
@@ -2106,12 +2430,22 @@ function createDownstreamServer(runtime, opts = {}) {
     touch();
     const { agent } = await agentFor(extra);
     const scope = agent === void 0 ? runtime.agent : agent;
+    if (ownToolsActive(runtime)) return { tools: ownToolList(ownTools) };
     return {
       tools: runtime.listTools(scope).map((t) => annotateTool(t, scope?.mode ?? runtime.policy.mode))
     };
   });
   low.setRequestHandler(CallToolRequestSchema2, async (req, extra) => {
     touch();
+    if (ownToolsActive(runtime)) {
+      const own = await callOwnTool(
+        ownTools,
+        req.params.name,
+        req.params.arguments ?? {},
+        String(extra.requestId)
+      );
+      if (own) return own;
+    }
     const { agent, error } = await agentFor(extra);
     const runId = runIdFor(extra, req.params._meta, opts.defaultRunId ?? runtime.defaultRunId);
     if (error) {
@@ -2378,7 +2712,7 @@ async function startHttpProxy(opts) {
     port,
     token,
     close: () => new Promise((resolve5, reject) => {
-      if (opts.registerFile !== false && existsSync(regFile)) {
+      if (opts.registerFile !== false && existsSync2(regFile)) {
         try {
           unlinkSync(regFile);
         } catch {
@@ -2674,7 +3008,7 @@ function readRegistration(loaded) {
   const file = registrationPath(loaded.stateDir);
   if (!exists(file)) return void 0;
   try {
-    const reg = JSON.parse(readFileSync2(file, "utf8"));
+    const reg = JSON.parse(readFileSync3(file, "utf8"));
     return reg;
   } catch {
     return void 0;
@@ -2690,11 +3024,11 @@ function describeError(err) {
 }
 
 // src/commands/connect.ts
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync5 } from "fs";
 import { relative } from "path";
 
 // src/configs.ts
-import { copyFileSync, existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { copyFileSync, existsSync as existsSync4, readFileSync as readFileSync4, 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) {
@@ -2727,6 +3061,12 @@ function candidateConfigs(cwd = process.cwd(), home = homedir2(), env = process.
       serversKey: "servers"
     },
     { kind: "generic", label: "mcp.json", path: join2(cwd, "mcp.json"), serversKey: "mcpServers" },
+    {
+      kind: "gemini-project",
+      label: "Gemini CLI (project .gemini/settings.json)",
+      path: join2(cwd, ".gemini", "settings.json"),
+      serversKey: "mcpServers"
+    },
     { kind: "claude-desktop", label: "Claude Desktop", path: desktop, serversKey: "mcpServers" },
     {
       kind: "cursor-user",
@@ -2745,11 +3085,20 @@ function candidateConfigs(cwd = process.cwd(), home = homedir2(), env = process.
       label: "Claude Code (user ~/.claude.json)",
       path: join2(home, ".claude.json"),
       serversKey: "mcpServers"
+    },
+    {
+      kind: "gemini-user",
+      label: "Gemini CLI (user ~/.gemini/settings.json)",
+      path: join2(home, ".gemini", "settings.json"),
+      serversKey: "mcpServers"
     }
   ];
 }
+function isGeminiConfig(file) {
+  return file.kind === "gemini-project" || file.kind === "gemini-user" || /[/\\]\.gemini[/\\]settings\.json$/.test(file.path);
+}
 function detectClientConfigs(cwd, home, env) {
-  return candidateConfigs(cwd, home, env).filter((c) => existsSync3(c.path));
+  return candidateConfigs(cwd, home, env).filter((c) => existsSync4(c.path));
 }
 function describeConfigPath(path) {
   const abs = resolve2(path);
@@ -2757,7 +3106,7 @@ function describeConfigPath(path) {
   if (known) return known;
   let serversKey = "mcpServers";
   try {
-    const parsed = JSON.parse(readFileSync3(abs, "utf8"));
+    const parsed = JSON.parse(readFileSync4(abs, "utf8"));
     if (parsed.servers && !parsed.mcpServers) serversKey = "servers";
   } catch {
   }
@@ -2769,7 +3118,7 @@ function describeConfigPath(path) {
   };
 }
 function readServers(file) {
-  const raw = JSON.parse(readFileSync3(file.path, "utf8"));
+  const raw = JSON.parse(readFileSync4(file.path, "utf8"));
   const servers = raw[file.serversKey];
   if (!servers || typeof servers !== "object") return {};
   return servers;
@@ -2788,10 +3137,11 @@ function serversToUpstreams(servers) {
       continue;
     }
     const name = rawName.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/^[^a-zA-Z0-9]+/, "") || "upstream";
-    if (entry.url) {
+    const url = typeof entry.httpUrl === "string" ? entry.httpUrl : entry.url;
+    if (url) {
       upstreams.push({
         name,
-        url: entry.url,
+        url,
         headers: entry.headers ?? {},
         args: [],
         env: {},
@@ -2826,27 +3176,27 @@ function proxyEntry(file, policyPath, opts = {}) {
   return entry;
 }
 function rewriteClientConfig(file, policyPath, opts = {}) {
-  const raw = JSON.parse(readFileSync3(file.path, "utf8"));
+  const raw = JSON.parse(readFileSync4(file.path, "utf8"));
   const servers = raw[file.serversKey] ?? {};
   const replaced = Object.keys(servers).filter((n) => !isProxyEntry(servers[n]));
   const backup = backupPath(file);
-  if (!existsSync3(backup)) copyFileSync(file.path, backup);
+  if (!existsSync4(backup)) copyFileSync(file.path, backup);
   raw[file.serversKey] = { [PROXY_SERVER_NAME]: proxyEntry(file, policyPath, opts) };
   writeFileSync2(file.path, JSON.stringify(raw, null, 2) + "\n");
   return { backup, replaced };
 }
 function restoreClientConfig(file) {
   const backup = backupPath(file);
-  if (!existsSync3(backup)) return false;
+  if (!existsSync4(backup)) return false;
   copyFileSync(backup, file.path);
   return true;
 }
 function mergeServerIntoConfig(file, name, entry) {
-  const raw = JSON.parse(readFileSync3(file.path, "utf8"));
+  const raw = JSON.parse(readFileSync4(file.path, "utf8"));
   const servers = raw[file.serversKey] ?? {};
   const replaced = name in servers;
   const backup = backupPath(file);
-  if (!existsSync3(backup)) copyFileSync(file.path, backup);
+  if (!existsSync4(backup)) copyFileSync(file.path, backup);
   raw[file.serversKey] = { ...servers, [name]: entry };
   writeFileSync2(file.path, JSON.stringify(raw, null, 2) + "\n");
   return { backup, replaced };
@@ -2929,11 +3279,12 @@ async function connectCommand(args, io, fetchImpl = fetch) {
       return 1;
     }
     for (const c of chosen) {
-      if (!existsSync4(c.path)) {
+      if (!existsSync5(c.path)) {
         io.err(`no MCP config at ${c.path}`);
         return 1;
       }
-      const { backup, replaced } = mergeServerIntoConfig(c, PROXY_SERVER_NAME, entry);
+      const forClient = isGeminiConfig(c) ? { httpUrl: entry.url, ...entry.headers ? { headers: entry.headers } : {} } : entry;
+      const { backup, replaced } = mergeServerIntoConfig(c, PROXY_SERVER_NAME, forClient);
       io.out(
         `${replaced ? "updated" : "wrote  "} ${rel(c.path)} (${c.label}) \u2192 ${PROXY_SERVER_NAME} = ${conn.mcpUrl}`
       );
@@ -3048,7 +3399,7 @@ async function approvalsCommand(args, io) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync5, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync6, writeFileSync as writeFileSync3 } from "fs";
 import { relative as relative2, resolve as resolve3 } from "path";
 import YAML from "yaml";
 
@@ -3085,6 +3436,7 @@ var ProxyRuntime = class {
   guard;
   agent;
   defaultRunId;
+  configured;
   sessions = /* @__PURE__ */ new Set();
   connections = /* @__PURE__ */ new Map();
   exposed = [];
@@ -3101,6 +3453,7 @@ var ProxyRuntime = class {
     this.guard = opts.guard;
     this.agent = opts.agent;
     this.defaultRunId = opts.defaultRunId;
+    this.configured = opts.configured ?? true;
     this.log = opts.log ?? ((line) => process.stderr.write(`[agentguard] ${line}
 `));
     this.connectTimeoutMs = opts.connectTimeoutMs ?? 15e3;
@@ -3246,6 +3599,13 @@ var ProxyRuntime = class {
       }
     }
   }
+  /**
+   * Re-read an upstream's tools, every page (mcp-kit's `readAllPages`): at most 20 requests, each
+   * under the upstream's `timeout_ms`, ending at a cursor already followed. It used to follow
+   * `nextCursor` with no bound, so an upstream that echoed its cursor kept the proxy asking for
+   * the same page forever. A refresh that fails, or stops at the 20-page / 2,000-tool ceiling,
+   * changes nothing: the agent keeps the last good list, and the log says why.
+   */
   async refreshTools(name) {
     const conn = this.connections.get(name);
     if (!conn?.connected) return;
@@ -3253,22 +3613,23 @@ var ProxyRuntime = class {
       conn.tools = [];
       return;
     }
+    const kept = () => `keeping the last good list (${conn.tools.length} tool${conn.tools.length === 1 ? "" : "s"})`;
     try {
-      const tools = [];
-      let cursor;
-      do {
+      const read = await readAllPages(async (cursor) => {
         const page = await conn.client.listTools(cursor ? { cursor } : void 0, {
           timeout: conn.upstream.timeout_ms
         });
-        tools.push(...page.tools);
-        cursor = page.nextCursor;
-      } while (cursor);
-      conn.tools = tools;
+        return { items: page.tools, nextCursor: page.nextCursor };
+      });
+      if (read.truncated) {
+        this.log(`tools/list for "${name}" not applied: ${read.truncated.reason}; ${kept()}`);
+        return;
+      }
+      conn.tools = read.items;
     } catch (err) {
       this.log(
-        `tools/list failed for "${name}": ${err instanceof Error ? err.message : String(err)}`
+        `tools/list failed for "${name}": ${err instanceof Error ? err.message : String(err)}; ${kept()}`
       );
-      conn.tools = [];
     }
   }
   rebuildExposed() {
@@ -3645,6 +4006,10 @@ async function toolsCommand(args, io) {
     io.err(
       `${u.connected ? "ok  " : "down"} ${u.name}: ${u.connected ? `${u.tools} tools` : u.error}`
     );
+  if (result.upstreams.length === 0)
+    io.err(
+      "no upstreams in the policy: an MCP client sees agentguard's own read-only tools instead (agentguard_get_status, agentguard_get_report, agentguard_verify_audit_log)"
+    );
   for (const line of formatToolTable(result.tools)) io.out(line);
   const counts = result.tools.reduce(
     (acc, t) => ({ ...acc, [t.classification.class]: (acc[t.classification.class] ?? 0) + 1 }),
@@ -3812,7 +4177,7 @@ async function initCommand(args, io) {
         `found   ${c.path} (${c.label}, user-level) \u2014 not touched; pass --client ${JSON.stringify(c.path)} to route it through agentguard`
       );
   }
-  if (!chosen.every((c) => existsSync5(c.path))) {
+  if (!chosen.every((c) => existsSync6(c.path))) {
     io.err(`no MCP config at ${chosen.map((c) => c.path).join(", ")}`);
     return 1;
   }
@@ -3827,11 +4192,11 @@ async function initCommand(args, io) {
   }
   if (chosen.length === 0)
     io.out(
-      "found   no MCP config (Claude Code .mcp.json, Cursor, VS Code, Claude Desktop, Windsurf) \u2014 writing a policy with no upstreams"
+      "found   no MCP config (Claude Code .mcp.json, Cursor, VS Code, Claude Desktop, Windsurf, Gemini CLI) \u2014 writing a policy with no upstreams"
     );
   const { upstreams, skipped } = serversToUpstreams(servers);
   for (const s of skipped) io.err(`skipped ${s.name}: ${s.reason}`);
-  if (skipped.some((s) => s.reason.includes("already")) && upstreams.length === 0 && existsSync5(policyPath)) {
+  if (skipped.some((s) => s.reason.includes("already")) && upstreams.length === 0 && existsSync6(policyPath)) {
     io.out(
       `already initialized: ${rel(policyPath)} exists and ${chosen.map((c) => rel(c.path)).join(", ")} already points at agentguard`
     );
@@ -3858,7 +4223,7 @@ async function initCommand(args, io) {
     }
   }
   const mode = flagString(args, "mode") ?? "dry-run";
-  if (existsSync5(policyPath) && !flagBool(args, "force")) {
+  if (existsSync6(policyPath) && !flagBool(args, "force")) {
     io.out(`kept    ${rel(policyPath)} (exists; pass --force to regenerate)`);
   } else {
     writeFileSync3(policyPath, renderStarterPolicy({ upstreams, tools: probed, mode, probeErrors }));
@@ -3902,13 +4267,13 @@ async function initCommand(args, io) {
 }
 
 // src/commands/keys.ts
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
+import { readFileSync as readFileSync5, 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 path = policyPathFrom(args, io);
-  const doc = YAML2.parseDocument(readFileSync4(path, "utf8"));
+  const doc = YAML2.parseDocument(readFileSync5(path, "utf8"));
   let agents = doc.get("agents");
   if (!isSeq(agents)) {
     agents = new YAMLSeq();
@@ -4075,14 +4440,65 @@ async function permissionDiffCommand(args, io) {
 }
 
 // src/commands/proxy.ts
-import { resolveAgent as resolveAgent2 } from "@agentwares/agentguard-core";
+import { existsSync as existsSync7 } from "fs";
+import { dirname } from "path";
+import { Guard as Guard3, defaultPolicy, resolveAgent as resolveAgent2 } from "@agentwares/agentguard-core";
+import { FileKillSwitch as FileKillSwitch3, resolvePath } from "@agentwares/agentguard-core/node";
 function newRunId(now = /* @__PURE__ */ new Date()) {
   return `run_${now.toISOString().replace(/[-:.TZ]/g, "").slice(0, 14)}_${Math.random().toString(36).slice(2, 6)}`;
 }
+function unconfiguredPolicy(args, io) {
+  if (flagString(args, "config") !== void 0 || io.env.AGENTGUARD_CONFIG) return void 0;
+  const path = policyPathFrom(args, io);
+  if (existsSync7(path)) return void 0;
+  const policy = defaultPolicy();
+  const baseDir = dirname(path);
+  return {
+    policy,
+    path,
+    baseDir,
+    stateDir: resolvePath(policy.state.dir, baseDir),
+    auditPath: resolvePath(policy.audit.path, baseDir),
+    killPath: resolvePath(policy.kill.file, baseDir)
+  };
+}
+async function serveOverStdio(runtime) {
+  const server = createDownstreamServer(runtime);
+  const stop = async () => {
+    await runtime.close();
+  };
+  process.once("SIGINT", () => void stop().then(() => process.exit(0)));
+  process.once("SIGTERM", () => void stop().then(() => process.exit(0)));
+  await serveStdio(server);
+  await stop();
+  return 0;
+}
 async function proxyCommand(args, io) {
-  const loaded = loadPolicyFor(args, io);
   const log = (line) => io.err(`[agentguard] ${line}`);
   const modeOverride = flagString(args, "mode");
+  const http = flagBool(args, "http") === true;
+  const unconfigured = http ? void 0 : unconfiguredPolicy(args, io);
+  if (unconfigured) {
+    if (modeOverride === "dry-run" || modeOverride === "enforce")
+      unconfigured.policy.mode = modeOverride;
+    const runtime2 = new ProxyRuntime({
+      loaded: unconfigured,
+      guard: new Guard3({
+        policy: unconfigured.policy,
+        env: io.env,
+        kill: new FileKillSwitch3(unconfigured.killPath)
+      }),
+      configured: false,
+      defaultRunId: flagString(args, "run-id") ?? newRunId(),
+      log
+    });
+    await runtime2.start();
+    log(
+      `no policy file at ${unconfigured.path}: serving agentguard's own read-only tools only. To guard your MCP servers, run \`${INIT_COMMAND}\` in the project directory.`
+    );
+    return serveOverStdio(runtime2);
+  }
+  const loaded = loadPolicyFor(args, io);
   if (modeOverride === "dry-run" || modeOverride === "enforce") loaded.policy.mode = modeOverride;
   const agentName = flagString(args, "agent");
   let agent = void 0;
@@ -4096,7 +4512,6 @@ async function proxyCommand(args, io) {
     }
     agent = resolved.agent;
   }
-  const http = flagBool(args, "http") === true;
   let approvalBase;
   const fileGuard = createFileGuard(loaded, {
     log,
@@ -4122,59 +4537,55 @@ async function proxyCommand(args, io) {
     log(
       `kill switch is ON (${killed.reason}); every call returns KILLED until \`agentguard resume\``
     );
+  if (runtime.upstreamStatus().length === 0)
+    log(
+      `${loaded.path} lists no upstreams: serving agentguard's own read-only tools only. Add servers under \`upstreams:\` to guard them.`
+    );
   if (http) {
-    const server2 = await startHttpProxy({
+    const server = await startHttpProxy({
       runtime,
       port: flagNumber(args, "port") ?? 8788,
       host: flagString(args, "host") ?? "127.0.0.1",
       token: io.env.AGENTGUARD_HTTP_TOKEN
     });
-    approvalBase = { baseUrl: server2.url.replace(/\/mcp$/, ""), token: server2.token };
+    approvalBase = { baseUrl: server.url.replace(/\/mcp$/, ""), token: server.token };
     log(
-      `Streamable HTTP at ${server2.url} \xB7 GET ${approvalBase.baseUrl}/health \xB7 control token in ${loaded.stateDir}/http.json`
+      `Streamable HTTP at ${server.url} \xB7 GET ${approvalBase.baseUrl}/health \xB7 control token in ${loaded.stateDir}/http.json`
     );
     log(
-      `point your agent at ${server2.url} (send X-Run-Id per run; Authorization: Bearer <agent key> for scoped agents)`
+      `point your agent at ${server.url} (send X-Run-Id per run; Authorization: Bearer <agent key> for scoped agents)`
     );
-    const stop2 = async () => {
-      await server2.close();
+    const stop = async () => {
+      await server.close();
       await runtime.close();
       process.exit(0);
     };
-    process.once("SIGINT", () => void stop2());
-    process.once("SIGTERM", () => void stop2());
+    process.once("SIGINT", () => void stop());
+    process.once("SIGTERM", () => void stop());
     await new Promise(() => void 0);
   }
-  const server = createDownstreamServer(runtime);
-  const stop = async () => {
-    await runtime.close();
-  };
-  process.once("SIGINT", () => void stop().then(() => process.exit(0)));
-  process.once("SIGTERM", () => void stop().then(() => process.exit(0)));
-  await serveStdio(server);
-  await stop();
-  return 0;
+  return serveOverStdio(runtime);
 }
 
 // src/commands/report.ts
 import { resolve as resolve4 } from "path";
 import {
-  buildReport,
-  latestRunId,
-  listRuns,
+  buildReport as buildReport2,
+  latestRunId as latestRunId2,
+  listRuns as listRuns2,
   renderMutationDiff,
-  renderReportMarkdown
+  renderReportMarkdown as renderReportMarkdown2
 } from "@agentwares/agentguard-core";
 import { readAuditFile, verifyAuditFile } from "@agentwares/agentguard-core/node";
 function pickRun(args, entries) {
   if (flagBool(args, "all")) return void 0;
-  return flagString(args, "run") ?? latestRunId(entries);
+  return flagString(args, "run") ?? latestRunId2(entries);
 }
 async function reportCommand(args, io) {
   const loaded = loadPolicyFor(args, io, { allowMissingEnv: true });
   const entries = readAuditFile(loaded.auditPath);
   const runId = pickRun(args, entries);
-  const report = buildReport(entries, { runId });
+  const report = buildReport2(entries, { runId });
   if (flagBool(args, "json")) {
     io.out(
       JSON.stringify(
@@ -4193,12 +4604,12 @@ async function reportCommand(args, io) {
     );
     return 0;
   }
-  io.out(renderReportMarkdown(report));
+  io.out(renderReportMarkdown2(report));
   const chain = await verifyAuditFile(loaded.auditPath);
   io.out(
     chain.ok ? `Audit chain: ${chain.entries} entries, verified (${loaded.auditPath}).` : `Audit chain BROKEN at entry ${chain.brokenAt}: ${chain.reason}`
   );
-  if (runId && listRuns(entries).length > 1) io.out(`Other runs: agentguard report --all`);
+  if (runId && listRuns2(entries).length > 1) io.out(`Other runs: agentguard report --all`);
   return 0;
 }
 async function diffCommand(args, io) {
@@ -4225,7 +4636,7 @@ async function statusCommand(args, io) {
   const loaded = loadPolicyFor(args, io, { allowMissingEnv: true });
   const { guard, kill } = createFileGuard(loaded, { alerts: false, env: io.env });
   const entries = readAuditFile(loaded.auditPath);
-  const runId = flagString(args, "run") ?? latestRunId(entries) ?? "(none yet)";
+  const runId = flagString(args, "run") ?? latestRunId2(entries) ?? "(none yet)";
   const status = await guard.status(runId);
   const killed = kill.check();
   const reg = readRegistration(loaded);