@agentwares/agentguard 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,488 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { RequestId, Tool, ListResourcesResult, ListResourceTemplatesResult, ReadResourceResult, ListPromptsResult, GetPromptResult, CompleteRequest, CompleteResult, LoggingLevel, ServerRequest, ServerNotification, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { AgentScope, Classification, Guard, GuardResult, GuardEvent, ApprovalRecord, Policy, Upstream, Finding } from '@agentwares/agentguard-core';
+import { LoadedPolicy, FileKillSwitch, FileAuditSink, FileApprovalStore } from '@agentwares/agentguard-core/node';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { ToolDef } from '@agentwares/mcp-kit';
+
+/**
+ * Upstream side of the proxy: one MCP client per upstream (stdio or Streamable HTTP), the merged
+ * tool table, resource/prompt routing, notification fan-out to downstream sessions, and
+ * `callTool` through the policy engine.
+ */
+
+interface ExposedTool {
+    /** the name the agent sees */
+    name: string;
+    upstream: string;
+    /** the name the upstream knows */
+    original: string;
+    tool: Tool;
+    classification: Classification;
+}
+interface DownstreamSession {
+    id: string;
+    server: McpServer;
+    lastActive: number;
+    /** upstream name → downstream request ids currently waiting on it (newest last) */
+    inflight: Map<string, RequestId[]>;
+}
+interface UpstreamStatus {
+    name: string;
+    connected: boolean;
+    tools: number;
+    transport: "stdio" | "http";
+    error?: string;
+}
+interface RuntimeOptions {
+    loaded: LoadedPolicy;
+    guard: Guard;
+    /** fixed agent scope for stdio (`--agent`) */
+    agent?: AgentScope | null;
+    /** run id when neither `X-Run-Id` nor `_meta.runId` is present */
+    defaultRunId: string;
+    log?: (line: string) => void;
+    /** connect timeout per upstream (ms) */
+    connectTimeoutMs?: number;
+    /** in-process upstreams for tests: name → already-connected client */
+    clients?: Record<string, Client>;
+}
+interface CallContext {
+    runId: string;
+    agent?: AgentScope | null;
+    sessionId?: string;
+    onprogress?: (progress: {
+        progress: number;
+        total?: number;
+        message?: string;
+    }) => void;
+    /** downstream session + request id, so upstream notifications can be related to this call */
+    session?: DownstreamSession;
+    requestId?: RequestId;
+}
+declare class ProxyRuntime {
+    readonly loaded: LoadedPolicy;
+    readonly guard: Guard;
+    readonly agent: AgentScope | null | undefined;
+    readonly defaultRunId: string;
+    readonly sessions: Set<DownstreamSession>;
+    private readonly connections;
+    private exposed;
+    private readonly resourceOwner;
+    private readonly templateOwner;
+    private readonly promptOwner;
+    private readonly log;
+    private readonly connectTimeoutMs;
+    private readonly testClients;
+    /** stop relaying upstream stderr once we are tearing down — shutdown noise is not the user's problem */
+    private closing;
+    constructor(opts: RuntimeOptions);
+    get policy(): {
+        version: 1;
+        mode: "dry-run" | "enforce";
+        upstreams: {
+            name: string;
+            headers: Record<string, string>;
+            args: string[];
+            env: Record<string, string>;
+            prefix: string | boolean;
+            timeout_ms: number;
+            url?: string | undefined;
+            auth?: string | undefined;
+            command?: string | undefined;
+            cwd?: string | undefined;
+        }[];
+        classify: {
+            read: string[];
+            write: string[];
+            spend: string[];
+            unknown: "read" | "write" | "block";
+        };
+        deny: string[];
+        caps: {
+            per_run: {
+                [x: string]: number;
+                tool_calls?: number | undefined;
+                writes?: number | undefined;
+                deletes?: number | undefined;
+                emails?: number | undefined;
+                spend_usd?: number | undefined;
+            };
+            per_day: {
+                [x: string]: number;
+                tool_calls?: number | undefined;
+                writes?: number | undefined;
+                deletes?: number | undefined;
+                emails?: number | undefined;
+                spend_usd?: number | undefined;
+            };
+        };
+        counters: Record<string, string[]>;
+        loop: {
+            window: number;
+            max_repeats: number;
+            max_cycle_len: number;
+            ignore_args: string[];
+            max_read_repeats: number;
+        };
+        dry_run: {
+            tools: string[];
+            synthesize: boolean;
+        };
+        approval: {
+            tools: string[];
+            wait_s: number;
+            ttl_s: number;
+            notify: {
+                slack?: string | undefined;
+                webhook?: string | undefined;
+            };
+        };
+        kill: {
+            file: string;
+            env: string;
+        };
+        spend: {
+            tools: Record<string, {
+                divisor: number;
+                amount_arg?: string | undefined;
+                currency_arg?: string | undefined;
+                fixed_usd?: number | undefined;
+            }>;
+            result_fields: string[];
+            models: Record<string, {
+                input_per_mtok: number;
+                output_per_mtok: number;
+                cached_input_per_mtok?: number | undefined;
+            }>;
+            default_usd: number;
+        };
+        agents: {
+            name: string;
+            allow: string[];
+            deny: string[];
+            key_hash?: string | undefined;
+            caps?: {
+                per_run: {
+                    [x: string]: number;
+                    tool_calls?: number | undefined;
+                    writes?: number | undefined;
+                    deletes?: number | undefined;
+                    emails?: number | undefined;
+                    spend_usd?: number | undefined;
+                };
+                per_day: {
+                    [x: string]: number;
+                    tool_calls?: number | undefined;
+                    writes?: number | undefined;
+                    deletes?: number | undefined;
+                    emails?: number | undefined;
+                    spend_usd?: number | undefined;
+                };
+            } | undefined;
+            mode?: "dry-run" | "enforce" | undefined;
+            upstreams?: string[] | undefined;
+        }[];
+        audit: {
+            path: string;
+            redact: boolean;
+            include_results: boolean;
+            max_chars: number;
+        };
+        alerts: {
+            on: ("KILLED" | "APPROVAL_REQUIRED" | "LOOP_DETECTED" | "CAP_EXCEEDED" | "TOOL_DENIED")[];
+            slack?: string | undefined;
+            webhook?: string | undefined;
+        };
+        state: {
+            dir: string;
+        };
+        allow?: string[] | undefined;
+    };
+    start(): Promise<void>;
+    private connect;
+    private wire;
+    private pickSession;
+    private broadcast;
+    private refreshTools;
+    private rebuildExposed;
+    listTools(agent?: AgentScope | null): ExposedTool[];
+    findTool(name: string): ExposedTool | undefined;
+    upstreamStatus(): UpstreamStatus[];
+    attach(session: DownstreamSession): void;
+    detach(session: DownstreamSession): void;
+    /** Run a tool call through the policy engine and, if allowed, the upstream. */
+    callTool(name: string, args: unknown, ctx: CallContext): Promise<{
+        result: GuardResult;
+        tool?: ExposedTool;
+    }>;
+    private connectedWith;
+    listResources(): Promise<ListResourcesResult>;
+    listResourceTemplates(): Promise<ListResourceTemplatesResult>;
+    private ownerForUri;
+    readResource(uri: string): Promise<ReadResourceResult>;
+    subscribe(uri: string, on: boolean): Promise<void>;
+    listPrompts(): Promise<ListPromptsResult>;
+    getPrompt(name: string, args: Record<string, string> | undefined): Promise<GetPromptResult>;
+    complete(params: CompleteRequest["params"]): Promise<CompleteResult>;
+    setLevel(level: LoggingLevel): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * Downstream side of the proxy: the MCP server an agent connects to. One instance per session
+ * (stdio: one; Streamable HTTP: one per `Mcp-Session-Id`). Every request is served from the
+ * runtime; tool calls go through the policy engine.
+ */
+
+type Extra = RequestHandlerExtra<ServerRequest, ServerNotification>;
+interface DownstreamOptions {
+    /** run id for calls that carry neither `X-Run-Id` nor `_meta.runId` (default: runtime.defaultRunId) */
+    defaultRunId?: string;
+}
+declare function runIdFor(extra: Extra, meta: Record<string, unknown> | undefined, fallback: string): string;
+/** Shape the engine's verdict into what the MCP client receives. */
+declare function toCallToolResult(result: GuardResult, tool: ExposedTool | undefined): CallToolResult;
+/** Build the per-session MCP server. */
+declare function createDownstreamServer(runtime: ProxyRuntime, opts?: DownstreamOptions): McpServer;
+
+interface HttpProxyOptions {
+    runtime: ProxyRuntime;
+    port?: number;
+    host?: string;
+    path?: string;
+    token?: string;
+    /** write `<stateDir>/http.json` for the CLI (default true) */
+    registerFile?: boolean;
+}
+interface HttpProxy {
+    url: string;
+    port: number;
+    token: string;
+    close(): Promise<void>;
+}
+interface HttpRegistration {
+    url: string;
+    baseUrl: string;
+    token: string;
+    pid: number;
+    startedAt: string;
+}
+declare function registrationPath(stateDir: string): string;
+declare function startHttpProxy(opts: HttpProxyOptions): Promise<HttpProxy>;
+
+/** Tiny argv parser: `--flag value`, `--flag=value`, `--bool`, `--no-bool`, repeated flags → arrays. */
+interface ParsedArgs {
+    command: string | undefined;
+    positionals: string[];
+    flags: Record<string, string | boolean | string[]>;
+}
+
+interface Io {
+    out: (line: string) => void;
+    err: (line: string) => void;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** false when stdout is a pipe — an MCP client spawned us and wants a server, not the help text */
+    tty?: boolean;
+}
+declare function loadPolicyFor(args: ParsedArgs, io: Io, opts?: {
+    allowMissingEnv?: boolean;
+}): LoadedPolicy;
+interface FileGuard {
+    guard: Guard;
+    kill: FileKillSwitch;
+    audit: FileAuditSink;
+    approvals: FileApprovalStore;
+    loaded: LoadedPolicy;
+}
+/** A guard wired to the state dir, audit file, KILL file and approvals of a loaded policy. */
+declare function createFileGuard(loaded: LoadedPolicy, opts?: {
+    onEvent?: (e: GuardEvent) => void | Promise<void>;
+    approvalUrl?: (r: ApprovalRecord) => string | undefined;
+    log?: (line: string) => void;
+    alerts?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): FileGuard;
+/** A running HTTP proxy for this policy, if one registered itself. */
+declare function readRegistration(loaded: LoadedPolicy): HttpRegistration | undefined;
+
+interface AlerterOptions {
+    policy: Policy;
+    approvalUrl?: (record: ApprovalRecord) => string | undefined;
+    log?: (line: string) => void;
+    fetch?: typeof fetch;
+}
+declare function approvalSlackMessage(event: GuardEvent, url: string | undefined): {
+    text: string;
+    blocks: unknown[];
+};
+declare function haltSlackMessage(event: GuardEvent): {
+    text: string;
+    blocks: unknown[];
+};
+/** Returns a `Guard.onEvent` handler. Never throws; failures are logged. */
+declare function createAlerter(opts: AlerterOptions): (event: GuardEvent) => Promise<void>;
+
+type ClientKind = "claude-code-project" | "claude-code-user" | "claude-desktop" | "cursor-project" | "cursor-user" | "vscode" | "windsurf" | "generic";
+interface ClientConfigFile {
+    kind: ClientKind;
+    label: string;
+    path: string;
+    /** `mcpServers` (most clients) or `servers` (VS Code) */
+    serversKey: "mcpServers" | "servers";
+}
+interface ServerEntry {
+    type?: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    [k: string]: unknown;
+}
+declare function candidateConfigs(cwd?: string, home?: string, env?: NodeJS.ProcessEnv): ClientConfigFile[];
+/** Configs that exist on disk, project-level first. */
+declare function detectClientConfigs(cwd?: string, home?: string, env?: NodeJS.ProcessEnv): ClientConfigFile[];
+declare function readServers(file: ClientConfigFile): Record<string, ServerEntry>;
+/** Client servers → policy upstreams. Names are sanitized; secrets stay where they were (in the config). */
+declare function serversToUpstreams(servers: Record<string, ServerEntry>): {
+    upstreams: Upstream[];
+    skipped: {
+        name: string;
+        reason: string;
+    }[];
+};
+/** The entry that replaces every server: one proxy, all upstreams behind it. */
+declare function proxyEntry(file: ClientConfigFile, policyPath: string, opts?: {
+    agent?: string;
+}): ServerEntry;
+/** Back up the file (once) and replace its servers with the single proxy entry. */
+declare function rewriteClientConfig(file: ClientConfigFile, policyPath: string, opts?: {
+    agent?: string;
+}): {
+    backup: string;
+    replaced: string[];
+};
+/** `agentguard init --undo`: restore the backup. */
+declare function restoreClientConfig(file: ClientConfigFile): boolean;
+
+/**
+ * `agentguard tools` — connect to every upstream and print the tools the agent will see,
+ * with their class and why. Also the probe `init` uses to seed the policy.
+ */
+
+interface ProbedTool {
+    upstream: string;
+    name: string;
+    tool: Tool;
+    classification: Classification;
+}
+interface ProbeResult {
+    tools: ProbedTool[];
+    upstreams: {
+        name: string;
+        connected: boolean;
+        tools: number;
+        error?: string;
+    }[];
+}
+/** Connect to the upstreams (with a policy for classification), list tools, disconnect. */
+declare function probeUpstreams(upstreams: Upstream[], opts?: {
+    policy?: Policy;
+    timeoutMs?: number;
+    log?: (l: string) => void;
+    env?: NodeJS.ProcessEnv;
+}): Promise<ProbeResult>;
+
+interface StarterPolicyOptions {
+    upstreams: Upstream[];
+    tools?: ProbedTool[];
+    mode?: "dry-run" | "enforce";
+    generatedAt?: Date;
+    probeErrors?: string[];
+}
+/** The commented starter policy — the file people read, so every knob explains itself. */
+declare function renderStarterPolicy(opts: StarterPolicyOptions): string;
+
+declare const DEFAULT_PERMISSION_PATHS: string[];
+interface PermissionDiffResult {
+    base: string;
+    head: string;
+    files: string[];
+    findings: Finding[];
+    markdown: string;
+}
+declare function runPermissionDiff(cwd: string, opts: {
+    base?: string;
+    head?: string;
+    paths?: string[];
+    title?: string;
+}): PermissionDiffResult;
+
+/**
+ * Fake CRM MCP server used by the tests, the demo agent and the README walkthrough. In-memory
+ * contacts; every mutation is recorded so tests can assert what really happened upstream.
+ *
+ *   node dist/fixtures/crm-server.js            # stdio
+ *   node dist/fixtures/crm-server.js --http     # Streamable HTTP on 127.0.0.1:<port> (prints the URL)
+ */
+
+interface Contact {
+    id: string;
+    name: string;
+    email: string;
+    updated_at: string;
+}
+interface CrmState {
+    contacts: Map<string, Contact>;
+    mutations: {
+        tool: string;
+        args: unknown;
+    }[];
+    emails: {
+        to: string;
+        subject: string;
+    }[];
+    charges: {
+        customer_id: string;
+        amount_usd: number;
+    }[];
+}
+declare function seedState(): CrmState;
+declare function crmTools(state: CrmState): ToolDef[];
+declare function createCrmMcpServer(state?: CrmState): McpServer;
+
+/**
+ * A scripted "agent" that misbehaves on purpose: reads, then writes, then loops, then bursts
+ * writes past the cap. Run it against the proxy to see dry-run diffs, LOOP_DETECTED and
+ * CAP_EXCEEDED in `agentguard report`.
+ *
+ *   node dist/fixtures/demo-agent.js --config agentguard.yaml   # spawns `agentguard proxy` over stdio
+ */
+
+interface DemoStep {
+    step: string;
+    tool: string;
+    ok: boolean;
+    code?: string;
+    dryRun?: boolean;
+    text?: string;
+}
+interface DemoOptions {
+    /** how many writes to burst at the end (default 60 — past a `writes: 50` cap) */
+    burst?: number;
+    /** how many times to repeat the identical update (default 5 — past `max_repeats: 3`) */
+    loop?: number;
+    runId?: string;
+    log?: (line: string) => void;
+}
+/** 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/agentwares/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 };