agent-authority 0.1.0

package/dist/mcp.d.ts

@@ -0,0 +1,63 @@
+import { Behalf } from "./behalf.js";
+import { Mandate } from "./mandate.js";
+/**
+ * MCP middleware — the adoption killer. Wrap any MCP-style tool server once and
+ * every tool call is automatically checked against the caller's mandate: scope,
+ * limits, expiry, revocation, and audit, with no per-tool code.
+ */
+/** Minimal structural view of an MCP-ish tool server. */
+export interface ToolServerLike {
+    callTool(name: string, args: Record<string, unknown>, ctx?: CallContext): Promise<unknown>;
+}
+/** Per-call context; the caller's mandate rides here. */
+export interface CallContext {
+    mandate?: Mandate;
+    [k: string]: unknown;
+}
+/** A capability requirement: a fixed string or one derived from call args. */
+export type CapabilityRule = string | ((args: Record<string, unknown>) => string);
+export interface WithBehalfOptions {
+    /** Map each tool name to the capability it requires. */
+    policy: Record<string, CapabilityRule>;
+    /** What to do on a denied call. */
+    onDenied?: "throw" | "prompt";
+    /**
+     * Just-in-time consent callback (used when onDenied === "prompt"). Return true
+     * to allow the call through despite the missing authority.
+     */
+    onPrompt?: (info: {
+        tool: string;
+        capability: string;
+        mandate?: Mandate;
+    }) => Promise<boolean>;
+    /** Engine to use (defaults to the shared Behalf default). */
+    engine?: Behalf;
+}
+/**
+ * Wrap a tool server so every call is authorized first.
+ *
+ *   const server = withBehalf(myMcpServer, {
+ *     policy: {
+ *       send_email: "write:email",
+ *       read_calendar: "read:calendar",
+ *       transfer_funds: (args) => `spend:usd<=${args.amount}`,
+ *     },
+ *     onDenied: "throw",
+ *   });
+ */
+export declare function withBehalf(server: ToolServerLike, opts: WithBehalfOptions): ToolServerLike;
+/** Symmetric binding for agent-to-agent (A2A) calls — same enforcement shape. */
+export declare function withBehalfA2A(server: ToolServerLike, opts: WithBehalfOptions): ToolServerLike;
+/** A tool definition for the agent-legibility layer. */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: Record<string, unknown>, ctx?: CallContext) => Promise<unknown>;
+}
+/**
+ * The three discovery tools that let any agent obtain and use authority
+ * natively: `request_mandate`, `present_mandate`, and `check_authority`.
+ */
+export declare function behalfMcpTools(engine?: Behalf): ToolDefinition[];
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC;;;;GAIG;AAEH,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5F;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,CAAC;AAElF,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACvC,mCAAmC;IACnC,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/F,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAiC1F;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAE7F;AAED,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACjF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,GAAE,MAAuB,GAAG,cAAc,EAAE,CAkEhF"}

package/dist/mcp.js

@@ -0,0 +1,123 @@
+import { Behalf } from "./behalf.js";
+import { AuthorizationError } from "./errors.js";
+/**
+ * Wrap a tool server so every call is authorized first.
+ *
+ *   const server = withBehalf(myMcpServer, {
+ *     policy: {
+ *       send_email: "write:email",
+ *       read_calendar: "read:calendar",
+ *       transfer_funds: (args) => `spend:usd<=${args.amount}`,
+ *     },
+ *     onDenied: "throw",
+ *   });
+ */
+export function withBehalf(server, opts) {
+    return {
+        async callTool(name, args, ctx) {
+            const rule = opts.policy[name];
+            // Tools without a policy entry pass through unguarded (explicit opt-in).
+            if (rule === undefined)
+                return server.callTool(name, args, ctx);
+            const capability = typeof rule === "function" ? rule(args) : rule;
+            const mandate = ctx?.mandate;
+            let denied;
+            if (!mandate) {
+                denied = "no mandate presented";
+            }
+            else {
+                try {
+                    await mandate.authorize(capability);
+                }
+                catch (e) {
+                    denied = e instanceof AuthorizationError ? e.reason : String(e);
+                }
+            }
+            if (denied) {
+                if (opts.onDenied === "prompt" && opts.onPrompt) {
+                    const allow = await opts.onPrompt({ tool: name, capability, mandate });
+                    if (!allow)
+                        throw new AuthorizationError(capability, `${denied} (consent declined)`);
+                }
+                else {
+                    throw new AuthorizationError(capability, denied);
+                }
+            }
+            return server.callTool(name, args, ctx);
+        },
+    };
+}
+/** Symmetric binding for agent-to-agent (A2A) calls — same enforcement shape. */
+export function withBehalfA2A(server, opts) {
+    return withBehalf(server, opts);
+}
+/**
+ * The three discovery tools that let any agent obtain and use authority
+ * natively: `request_mandate`, `present_mandate`, and `check_authority`.
+ */
+export function behalfMcpTools(engine = Behalf.default) {
+    return [
+        {
+            name: "request_mandate",
+            description: "Request a scoped, time-bound mandate authorizing an agent to act on a principal's behalf. " +
+                "Returns `mandate` (a HOLDER credential containing the delegation key — treat it as a secret) " +
+                "and `publicToken` (safe to share for inspection/presentation).",
+            inputSchema: {
+                type: "object",
+                required: ["principal", "agent", "can", "expiresIn"],
+                properties: {
+                    principal: { type: "string" },
+                    agent: { type: "string" },
+                    can: { type: "array", items: { type: "string" } },
+                    expiresIn: { type: "string", description: 'e.g. "1h", "10m"' },
+                },
+            },
+            handler: async (args) => {
+                const m = engine.grant({
+                    principal: String(args.principal),
+                    agent: String(args.agent),
+                    can: args.can,
+                    expiresIn: String(args.expiresIn),
+                });
+                // The holder credential includes the delegation key — without it the
+                // requester could never authorize (proof of possession would fail).
+                return { mandate: m.serializeWithKey(), publicToken: m.serialize(), id: m.id };
+            },
+        },
+        {
+            name: "present_mandate",
+            description: "Validate a serialized mandate and return its decoded scope, principal, and expiry.",
+            inputSchema: {
+                type: "object",
+                required: ["mandate"],
+                properties: { mandate: { type: "string" } },
+            },
+            handler: async (args) => {
+                const m = engine.import(String(args.mandate));
+                engine.verifySignature(m.token);
+                return {
+                    valid: true,
+                    id: m.id,
+                    principal: m.principal,
+                    agent: m.agent,
+                    expiresAt: m.expiresAt,
+                    chain: m.chain,
+                };
+            },
+        },
+        {
+            name: "check_authority",
+            description: "Advisory check of whether a mandate's scope would allow an action (does not perform it and does not prove possession).",
+            inputSchema: {
+                type: "object",
+                required: ["mandate", "action"],
+                properties: { mandate: { type: "string" }, action: { type: "string" } },
+            },
+            handler: async (args) => {
+                const m = engine.import(String(args.mandate));
+                return engine.inspect(m.token, String(args.action));
+            },
+        },
+    ];
+}
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/persist.d.ts

@@ -0,0 +1,51 @@
+import type { AuditEntry, AuditFields, ConsentRecord } from "./types.js";
+import type { AuditStore, ConsentStore, PolicyStore, RateStore, RevocationStore } from "./store.js";
+/** Revocation list persisted as a JSON array of ids. */
+export declare class FileRevocationStore implements RevocationStore {
+    private readonly path;
+    private readonly revoked;
+    constructor(path: string);
+    revoke(id: string): void;
+    isRevoked(id: string): boolean;
+}
+/** Append-only audit log persisted as JSON Lines (one entry per line). */
+export declare class FileAuditStore implements AuditStore {
+    private readonly path;
+    /** Last sealed entry, tracked in memory so writes stay O(1) (no full re-read). */
+    private last;
+    constructor(path: string);
+    record(fields: AuditFields): AuditEntry;
+    append(entry: AuditEntry): void;
+    all(): AuditEntry[];
+    forMandate(mandateId: string): AuditEntry[];
+    forIssuer(issuer: string): AuditEntry[];
+}
+/** Consent records persisted as a JSON object keyed by id. */
+export declare class FileConsentStore implements ConsentStore {
+    private readonly path;
+    private readonly records;
+    constructor(path: string);
+    private flush;
+    put(record: ConsentRecord): void;
+    get(id: string): ConsentRecord | undefined;
+    list(): ConsentRecord[];
+}
+/** Named policies persisted as a JSON object keyed by name. */
+export declare class FilePolicyStore implements PolicyStore {
+    private readonly path;
+    private readonly policies;
+    constructor(path: string);
+    private flush;
+    set(name: string, policy: unknown): void;
+    get(name: string): unknown;
+    has(name: string): boolean;
+}
+/** Rate-limit windows persisted as a JSON object of key → hit timestamps. */
+export declare class FileRateStore implements RateStore {
+    private readonly path;
+    private readonly hits;
+    constructor(path: string);
+    private flush;
+    hit(key: string, windowMs: number, limit: number, now: number): boolean;
+}
+//# sourceMappingURL=persist.d.ts.map

package/dist/persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist.d.ts","sourceRoot":"","sources":["../src/persist.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAcpG,wDAAwD;AACxD,qBAAa,mBAAoB,YAAW,eAAe;IAG7C,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;gBAET,IAAI,EAAE,MAAM;IAOzC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKxB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAG/B;AAED,0EAA0E;AAC1E,qBAAa,cAAe,YAAW,UAAU;IAInC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,kFAAkF;IAClF,OAAO,CAAC,IAAI,CAA2B;gBAEV,IAAI,EAAE,MAAM;IAUzC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU;IAMvC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAK/B,GAAG,IAAI,UAAU,EAAE;IAQnB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,EAAE;IAI3C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE;CAGxC;AAED,8DAA8D;AAC9D,qBAAa,gBAAiB,YAAW,YAAY;IAGvC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;gBAExB,IAAI,EAAE,MAAM;IAOzC,OAAO,CAAC,KAAK;IAIb,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAIhC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAG1C,IAAI,IAAI,aAAa,EAAE;CAGxB;AAED,+DAA+D;AAC/D,qBAAa,eAAgB,YAAW,WAAW;IAGrC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;gBAEnB,IAAI,EAAE,MAAM;IAOzC,OAAO,CAAC,KAAK;IAIb,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAIxC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAG1B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAG3B;AAED,6EAA6E;AAC7E,qBAAa,aAAc,YAAW,SAAS;IAGjC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwB;gBAEhB,IAAI,EAAE,MAAM;IAOzC,OAAO,CAAC,KAAK;IAIb,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;CAYxE"}

package/dist/persist.js

@@ -0,0 +1,150 @@
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { seal } from "./audit.js";
+/**
+ * Local-first, file-backed stores. These keep revocation and audit state across
+ * process restarts with zero infrastructure — the "offline-verifiable, only
+ * revocation needs a check" model, persisted to disk. Swap in a networked store
+ * for distributed revocation propagation (the Phase-2 control plane).
+ */
+function ensureDir(file) {
+    const dir = dirname(file);
+    if (dir && !existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+/** Revocation list persisted as a JSON array of ids. */
+export class FileRevocationStore {
+    path;
+    revoked;
+    constructor(path) {
+        this.path = path;
+        ensureDir(path);
+        this.revoked = existsSync(path)
+            ? new Set(JSON.parse(readFileSync(path, "utf8")))
+            : new Set();
+    }
+    revoke(id) {
+        this.revoked.add(id);
+        writeFileSync(this.path, JSON.stringify([...this.revoked]), "utf8");
+    }
+    isRevoked(id) {
+        return this.revoked.has(id);
+    }
+}
+/** Append-only audit log persisted as JSON Lines (one entry per line). */
+export class FileAuditStore {
+    path;
+    /** Last sealed entry, tracked in memory so writes stay O(1) (no full re-read). */
+    last = null;
+    constructor(path) {
+        this.path = path;
+        ensureDir(path);
+        if (existsSync(path)) {
+            const entries = this.all();
+            this.last = entries[entries.length - 1] ?? null;
+        }
+        else {
+            writeFileSync(path, "", "utf8");
+        }
+    }
+    record(fields) {
+        const entry = seal(this.last, fields);
+        this.append(entry);
+        return entry;
+    }
+    append(entry) {
+        appendFileSync(this.path, JSON.stringify(entry) + "\n", "utf8");
+        this.last = entry;
+    }
+    all() {
+        const raw = readFileSync(this.path, "utf8");
+        return raw
+            .split("\n")
+            .filter((l) => l.length > 0)
+            .map((l) => JSON.parse(l));
+    }
+    forMandate(mandateId) {
+        return this.all().filter((e) => e.chain.includes(mandateId));
+    }
+    forIssuer(issuer) {
+        return this.all().filter((e) => e.issuer === issuer);
+    }
+}
+/** Consent records persisted as a JSON object keyed by id. */
+export class FileConsentStore {
+    path;
+    records;
+    constructor(path) {
+        this.path = path;
+        ensureDir(path);
+        this.records = existsSync(path)
+            ? new Map(Object.entries(JSON.parse(readFileSync(path, "utf8"))))
+            : new Map();
+    }
+    flush() {
+        writeFileSync(this.path, JSON.stringify(Object.fromEntries(this.records)), "utf8");
+    }
+    put(record) {
+        this.records.set(record.id, record);
+        this.flush();
+    }
+    get(id) {
+        return this.records.get(id);
+    }
+    list() {
+        return [...this.records.values()];
+    }
+}
+/** Named policies persisted as a JSON object keyed by name. */
+export class FilePolicyStore {
+    path;
+    policies;
+    constructor(path) {
+        this.path = path;
+        ensureDir(path);
+        this.policies = existsSync(path)
+            ? new Map(Object.entries(JSON.parse(readFileSync(path, "utf8"))))
+            : new Map();
+    }
+    flush() {
+        writeFileSync(this.path, JSON.stringify(Object.fromEntries(this.policies)), "utf8");
+    }
+    set(name, policy) {
+        this.policies.set(name, policy);
+        this.flush();
+    }
+    get(name) {
+        return this.policies.get(name);
+    }
+    has(name) {
+        return this.policies.has(name);
+    }
+}
+/** Rate-limit windows persisted as a JSON object of key → hit timestamps. */
+export class FileRateStore {
+    path;
+    hits;
+    constructor(path) {
+        this.path = path;
+        ensureDir(path);
+        this.hits = existsSync(path)
+            ? new Map(Object.entries(JSON.parse(readFileSync(path, "utf8"))))
+            : new Map();
+    }
+    flush() {
+        writeFileSync(this.path, JSON.stringify(Object.fromEntries(this.hits)), "utf8");
+    }
+    hit(key, windowMs, limit, now) {
+        const recent = (this.hits.get(key) ?? []).filter((t) => now - t < windowMs);
+        if (recent.length + 1 > limit) {
+            this.hits.set(key, recent);
+            this.flush();
+            return false;
+        }
+        recent.push(now);
+        this.hits.set(key, recent);
+        this.flush();
+        return true;
+    }
+}
+//# sourceMappingURL=persist.js.map

package/dist/persist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist.js","sourceRoot":"","sources":["../src/persist.ts"],"names":[],"mappings":"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"}

package/dist/quickstart.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Dynamic, per-surface quickstart generator.
+ *
+ * Wiring Behalf into an AI surface is one of two shapes: an MCP server entry
+ * (Claude Code/Desktop, Cursor, Copilot/VS Code, Windsurf, Gemini CLI, OpenAI
+ * Agents, ...) or a function-calling tool schema (OpenAI / Gemini APIs). Rather
+ * than hand-write a doc per tool, surfaces are described as DATA and rendered on
+ * demand — so the three mains (Claude Code, Cursor, Copilot), Gemini and GPT are
+ * built in, and ANY other AI is configurable via a custom surface or the generic
+ * MCP template.
+ */
+export interface Surface {
+    id: string;
+    name: string;
+    kind: "mcp" | "tool-api";
+    /** mcp: where the config lives. */
+    configFile?: string;
+    /** mcp: top-level key — usually "mcpServers", VS Code uses "servers". */
+    configKey?: string;
+    /** mcp: include `"type": "stdio"` in the entry (VS Code, some clients). */
+    stdioType?: boolean;
+    /** mcp: optional one-liner CLI to register, with {name}/{command}/{args}. */
+    cli?: string;
+    /** tool-api: which function-calling dialect to emit. */
+    api?: "openai" | "gemini";
+    /** Freeform guidance shown with the snippet. */
+    notes?: string;
+}
+export interface QuickstartOptions {
+    /** Server name shown in the client config. Default "agent-authority". */
+    name?: string;
+    /** Command to launch the MCP server. Default "npx". */
+    command?: string;
+    /** Args for the command. Default ["-y", "agent-authority-mcp"]. */
+    args?: string[];
+    /** Extra environment variables for the server entry. */
+    env?: Record<string, string>;
+}
+export interface Quickstart {
+    surface: string;
+    name: string;
+    kind: Surface["kind"];
+    instructions: string;
+    /** The config/snippet to paste (JSON or code). */
+    snippet: string;
+    /** Optional one-line CLI alternative (MCP surfaces). */
+    cli?: string;
+    notes?: string;
+    /** A ready-to-print text rendering of everything above. */
+    text: string;
+}
+/** Built-in surfaces. Extend at runtime by passing your own {@link Surface}. */
+export declare const DEFAULT_SURFACES: Surface[];
+/** Look up a built-in (or supplied) surface by id. */
+export declare function findSurface(id: string, extra?: Surface[]): Surface | undefined;
+/** List all surface ids/names (built-in plus any supplied). */
+export declare function listSurfaces(extra?: Surface[]): {
+    id: string;
+    name: string;
+}[];
+/** Render a ready-to-paste quickstart for a surface. */
+export declare function generateQuickstart(surface: Surface, opts?: QuickstartOptions): Quickstart;
+//# sourceMappingURL=quickstart.d.ts.map

package/dist/quickstart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickstart.d.ts","sourceRoot":"","sources":["../src/quickstart.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,KAAK,GAAG,UAAU,CAAC;IACzB,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,GAAG,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,EAAE,OAAO,EA8ErC,CAAC;AAQF,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,GAAE,OAAO,EAAO,GAAG,OAAO,GAAG,SAAS,CAElF;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,KAAK,GAAE,OAAO,EAAO,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAElF;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,iBAAsB,GAAG,UAAU,CAY7F"}

package/dist/quickstart.js

@@ -0,0 +1,171 @@
+import { behalfMcpTools } from "./mcp.js";
+/** Built-in surfaces. Extend at runtime by passing your own {@link Surface}. */
+export const DEFAULT_SURFACES = [
+    {
+        id: "claude-code",
+        name: "Claude Code",
+        kind: "mcp",
+        configFile: ".mcp.json (project) or ~/.claude.json",
+        configKey: "mcpServers",
+        cli: "claude mcp add {name} -- {command} {args}",
+    },
+    {
+        id: "claude-desktop",
+        name: "Claude Desktop",
+        kind: "mcp",
+        configFile: "~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\\Claude\\claude_desktop_config.json (Windows)",
+        configKey: "mcpServers",
+    },
+    {
+        id: "cursor",
+        name: "Cursor",
+        kind: "mcp",
+        configFile: ".cursor/mcp.json (project) or ~/.cursor/mcp.json (global)",
+        configKey: "mcpServers",
+    },
+    {
+        id: "copilot",
+        name: "GitHub Copilot (VS Code)",
+        kind: "mcp",
+        configFile: ".vscode/mcp.json",
+        configKey: "servers",
+        stdioType: true,
+        notes: "Enable agent mode; VS Code uses the `servers` key and a `type` field.",
+    },
+    {
+        id: "windsurf",
+        name: "Windsurf",
+        kind: "mcp",
+        configFile: "~/.codeium/windsurf/mcp_config.json",
+        configKey: "mcpServers",
+    },
+    {
+        id: "gemini-cli",
+        name: "Gemini CLI",
+        kind: "mcp",
+        configFile: "~/.gemini/settings.json",
+        configKey: "mcpServers",
+    },
+    {
+        id: "openai-agents",
+        name: "OpenAI Agents SDK",
+        kind: "mcp",
+        configFile: "your agent setup (MCP stdio server)",
+        configKey: "mcpServers",
+        notes: "The Agents SDK launches MCP servers over stdio; use this command/args.",
+    },
+    {
+        id: "gpt",
+        name: "GPT / OpenAI API (function calling)",
+        kind: "tool-api",
+        api: "openai",
+        notes: "Pass these as `tools`. Have the model call `check_authority` before any sensitive action.",
+    },
+    {
+        id: "gemini",
+        name: "Gemini API (function calling)",
+        kind: "tool-api",
+        api: "gemini",
+        notes: "Pass these as `functionDeclarations` in a `tools` entry.",
+    },
+    {
+        id: "generic-mcp",
+        name: "Any MCP client (generic)",
+        kind: "mcp",
+        configFile: "your MCP client's config",
+        configKey: "mcpServers",
+        notes: "Most MCP clients accept a `mcpServers` map of stdio servers.",
+    },
+];
+const DEFAULTS = {
+    name: "agent-authority",
+    command: "npx",
+    args: ["-y", "agent-authority-mcp"],
+};
+/** Look up a built-in (or supplied) surface by id. */
+export function findSurface(id, extra = []) {
+    return [...DEFAULT_SURFACES, ...extra].find((s) => s.id === id);
+}
+/** List all surface ids/names (built-in plus any supplied). */
+export function listSurfaces(extra = []) {
+    return [...DEFAULT_SURFACES, ...extra].map((s) => ({ id: s.id, name: s.name }));
+}
+/** Render a ready-to-paste quickstart for a surface. */
+export function generateQuickstart(surface, opts = {}) {
+    const o = {
+        name: opts.name ?? DEFAULTS.name,
+        command: opts.command ?? DEFAULTS.command,
+        args: opts.args ?? DEFAULTS.args,
+        env: opts.env,
+    };
+    if (surface.kind === "tool-api") {
+        return renderToolApi(surface, o);
+    }
+    return renderMcp(surface, o);
+}
+function renderMcp(surface, o) {
+    const entry = { command: o.command, args: o.args };
+    if (surface.stdioType)
+        entry.type = "stdio";
+    if (o.env)
+        entry.env = o.env;
+    const config = { [surface.configKey ?? "mcpServers"]: { [o.name]: entry } };
+    const snippet = JSON.stringify(config, null, 2);
+    const cli = surface.cli
+        ? surface.cli
+            .replace("{name}", o.name)
+            .replace("{command}", o.command)
+            .replace("{args}", o.args.join(" "))
+        : undefined;
+    const instructions = `Add to ${surface.configFile ?? "your MCP client config"}:`;
+    const text = [
+        `# ${surface.name} — Behalf quickstart`,
+        "",
+        instructions,
+        "",
+        "```json",
+        snippet,
+        "```",
+        cli ? `\nOr from the CLI:\n\n\`\`\`bash\n${cli}\n\`\`\`` : "",
+        surface.notes ? `\nNote: ${surface.notes}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return { surface: surface.id, name: surface.name, kind: "mcp", instructions, snippet, cli, notes: surface.notes, text };
+}
+function renderToolApi(surface, o) {
+    const tools = behalfMcpTools();
+    let snippet;
+    let instructions;
+    if (surface.api === "gemini") {
+        const decls = tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            parameters: t.inputSchema,
+        }));
+        snippet = JSON.stringify({ tools: [{ functionDeclarations: decls }] }, null, 2);
+        instructions = "Register these function declarations with the Gemini API:";
+    }
+    else {
+        const fns = tools.map((t) => ({
+            type: "function",
+            function: { name: t.name, description: t.description, parameters: t.inputSchema },
+        }));
+        snippet = JSON.stringify({ tools: fns }, null, 2);
+        instructions = "Pass these tools to the OpenAI API (Chat Completions / Responses):";
+    }
+    const text = [
+        `# ${surface.name} — Behalf quickstart`,
+        "",
+        instructions,
+        "",
+        "```json",
+        snippet,
+        "```",
+        surface.notes ? `\nNote: ${surface.notes}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return { surface: surface.id, name: surface.name, kind: "tool-api", instructions, snippet, notes: surface.notes, text };
+}
+//# sourceMappingURL=quickstart.js.map

package/dist/quickstart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickstart.js","sourceRoot":"","sources":["../src/quickstart.ts"],"names":[],"mappings":"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"}