@sigrun/ext-mcp 0.0.0-stage → 0.1.0

package/dist/oauth.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The OAuth authorization-code flow (T3c): paste-the-URL mode for stdio MCP
+ * servers living where the user's browser cannot reach them (inside a pod).
+ *
+ * `startOauth` builds the authorize URL (with PKCE S256 — RFC 7636; the
+ * verifier is generated with node:crypto, no new deps), starts a loopback
+ * listener on 127.0.0.1 with a RANDOM port (RFC 8252) as redirect_uri, and
+ * returns the URL for the user to open however they get there. The CLI also
+ * prints the redirect_uri and reads pasted redirected URLs from stdin —
+ * first arrival wins: the loopback hit OR the paste. The code is exchanged
+ * at `tokenUrl` (POST, client_id, grant_type=authorization_code, code,
+ * redirect_uri, code_verifier) and the token lands in the store.
+ */
+import type { McpOAuthConfig } from "./config.js";
+import { type McpStoredToken } from "./tokens.js";
+/** The paste-the-URL flow's interactive handles (what `runOauth` returns). */
+export interface OauthFlow {
+    /** The authorize URL to open in a browser (also printed by the CLI). */
+    readonly authorizeUrl: string;
+    /** The loopback redirect_uri (`http://127.0.0.1:<port>/callback`). */
+    readonly redirectUri: string;
+    /** Feed a pasted redirected URL (the paste fallback). Extracts the code;
+     * a URL with no code is IGNORED (the user may paste again); a URL
+     * carrying an AS `error` parameter FAILS the flow fast. */
+    pasteUrl(url: string): void;
+    /** Settles with the STORED token, or rejects on AS error / exchange
+     * failure / timeout. */
+    readonly done: Promise<McpStoredToken>;
+    /** Tear down the listener (idempotent; no-op after the flow settles). */
+    stop(): void;
+}
+/** Extract `code` (and `error`) from a redirected URL's query string. */
+export declare function extractCode(url: string): {
+    code: string;
+} | {
+    error: string;
+};
+/** Exchange the code at `tokenUrl` and return the normalized token. */
+export declare function exchangeCode(oauth: McpOAuthConfig, code: string, redirectUri: string, verifier: string): Promise<McpStoredToken>;
+/** An injected seam for tests: how the CLI/flow mints the verifier. */
+export declare function makePkcePair(): {
+    readonly verifier: string;
+    readonly challenge: string;
+};
+/** Build the authorize URL (PKCE S256 + optional scopes + redirect_uri). */
+export declare function buildAuthorizeUrl(oauth: McpOAuthConfig, redirectUri: string, codeChallenge: string): string;
+/** Oauth start options (defaults match the CLI: 5-minute timeout). */
+export interface StartOauthOptions {
+    /** How long to wait for a code (listener or paste) before failing. */
+    readonly timeoutMs?: number;
+    /** Where to store the token (default: beside the resolved config). */
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * Run the flow for one server (the CLI-equivalent `runOauth`): start the
+ * loopback listener, build + return the authorize URL, and expose
+ * `pasteUrl` for the paste-the-URL fallback. First arrival wins; the flow
+ * resolves with the STORED token (written to the token store).
+ */
+export declare function startOauth(serverName: string, oauth: McpOAuthConfig, options?: StartOauthOptions): Promise<OauthFlow>;

package/dist/oauth.js

@@ -0,0 +1,238 @@
+/**
+ * The OAuth authorization-code flow (T3c): paste-the-URL mode for stdio MCP
+ * servers living where the user's browser cannot reach them (inside a pod).
+ *
+ * `startOauth` builds the authorize URL (with PKCE S256 — RFC 7636; the
+ * verifier is generated with node:crypto, no new deps), starts a loopback
+ * listener on 127.0.0.1 with a RANDOM port (RFC 8252) as redirect_uri, and
+ * returns the URL for the user to open however they get there. The CLI also
+ * prints the redirect_uri and reads pasted redirected URLs from stdin —
+ * first arrival wins: the loopback hit OR the paste. The code is exchanged
+ * at `tokenUrl` (POST, client_id, grant_type=authorization_code, code,
+ * redirect_uri, code_verifier) and the token lands in the store.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { storeMcpToken } from "./tokens.js";
+/** Extract `code` (and `error`) from a redirected URL's query string. */
+export function extractCode(url) {
+    const query = url.slice(url.indexOf("?") + 1);
+    for (const pair of query.split("&")) {
+        const eq = pair.indexOf("=");
+        if (eq < 0)
+            continue;
+        const key = decodeURIComponent(pair.slice(0, eq));
+        const value = decodeURIComponent(pair.slice(eq + 1));
+        if (key === "code")
+            return { code: value };
+        if (key === "error")
+            return { error: value };
+    }
+    throw new Error(`redirected URL has no code in its query: ${url}`);
+}
+/** Base64url (RFC 7636 §2) — used for the PKCE pair. */
+function b64url(bytes) {
+    return bytes
+        .toString("base64")
+        .replace(/=+$/, "")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_");
+}
+/** POST form-encoded params to `url`, resolve the parsed JSON body. */
+async function postJson(url, params) {
+    const body = Object.entries(params)
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+        .join("&");
+    const target = new URL(url);
+    const send = target.protocol === "https:" ? httpsRequest : httpRequest;
+    return new Promise((resolve, reject) => {
+        const req = send({
+            hostname: target.hostname,
+            port: target.port,
+            path: `${target.pathname}${target.search}`,
+            method: "POST",
+            headers: {
+                "content-type": "application/x-www-form-urlencoded",
+                "content-length": String(Buffer.byteLength(body)),
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => {
+                const text = Buffer.concat(chunks).toString("utf8");
+                if ((res.statusCode ?? 0) < 200 || (res.statusCode ?? 0) >= 300) {
+                    reject(new Error(`token endpoint ${url} returned ${res.statusCode}: ${text}`));
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(text);
+                    if (typeof parsed !== "object" ||
+                        parsed === null ||
+                        Array.isArray(parsed)) {
+                        throw new Error("not an object");
+                    }
+                    resolve(parsed);
+                }
+                catch (cause) {
+                    reject(new Error(`token endpoint ${url} returned non-JSON: ${cause instanceof Error ? cause.message : String(cause)}`));
+                }
+            });
+        });
+        req.on("error", reject);
+        req.end(body);
+    });
+}
+/** Exchange the code at `tokenUrl` and return the normalized token. */
+export async function exchangeCode(oauth, code, redirectUri, verifier) {
+    const response = await postJson(oauth.tokenUrl, {
+        client_id: oauth.clientId,
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: verifier,
+    });
+    if (typeof response.access_token !== "string" ||
+        typeof response.token_type !== "string") {
+        throw new Error(`token endpoint response lacks access_token/token_type: ${JSON.stringify(response)}`);
+    }
+    const now = Math.floor(Date.now() / 1000);
+    return {
+        access_token: response.access_token,
+        token_type: response.token_type,
+        ...(typeof response.refresh_token === "string"
+            ? { refresh_token: response.refresh_token }
+            : {}),
+        ...(typeof response.expires_in === "number"
+            ? { expires_at: now + response.expires_in }
+            : {}),
+        obtained_at: now,
+    };
+}
+/** An injected seam for tests: how the CLI/flow mints the verifier. */
+export function makePkcePair() {
+    const verifier = b64url(randomBytes(32));
+    const challenge = b64url(createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+/** Build the authorize URL (PKCE S256 + optional scopes + redirect_uri). */
+export function buildAuthorizeUrl(oauth, redirectUri, codeChallenge) {
+    const url = new URL(oauth.authorizeUrl);
+    url.searchParams.set("client_id", oauth.clientId);
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("code_challenge", codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    if (oauth.scopes !== undefined) {
+        url.searchParams.set("scope", oauth.scopes.join(" "));
+    }
+    return url.toString();
+}
+/**
+ * Run the flow for one server (the CLI-equivalent `runOauth`): start the
+ * loopback listener, build + return the authorize URL, and expose
+ * `pasteUrl` for the paste-the-URL fallback. First arrival wins; the flow
+ * resolves with the STORED token (written to the token store).
+ */
+export async function startOauth(serverName, oauth, options = {}) {
+    const { createServer } = await import("node:http");
+    const { verifier, challenge } = makePkcePair();
+    // The code settlement: the listener hit and the paste handler both feed
+    // this seam; the first caller wins (later calls are ignored).
+    let settleCode;
+    let failFlow;
+    const codeReceived = new Promise((resolve, reject) => {
+        settleCode = resolve;
+        failFlow = reject;
+    });
+    // Loopback listener (RFC 8252): random port on 127.0.0.1, one route.
+    const server = createServer((req, res) => {
+        const url = req.url ?? "/";
+        let code;
+        let oauthError;
+        for (const pair of url.slice(url.indexOf("?") + 1).split("&")) {
+            const eq = pair.indexOf("=");
+            if (eq < 0)
+                continue;
+            const [key, value] = [
+                pair.slice(0, eq),
+                decodeURIComponent(pair.slice(eq + 1)),
+            ];
+            if (key === "code")
+                code = value;
+            if (key === "error")
+                oauthError = value;
+        }
+        res.writeHead(200, { "content-type": "text/plain" });
+        if (oauthError !== undefined) {
+            res.end(`Authorization failed: ${oauthError}`);
+            failFlow?.(new Error(`authorization server returned error: ${oauthError}`));
+            return;
+        }
+        if (code !== undefined) {
+            res.end("Authorization complete. You can close this tab.");
+            settleCode?.(code);
+        }
+        else {
+            res.end("Missing code in the redirect.");
+        }
+    });
+    const listening = new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (address !== null && typeof address === "object") {
+                resolve(address.port);
+            }
+            else {
+                reject(new Error("loopback listener did not report a port"));
+            }
+        });
+    });
+    const port = await listening;
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const authorizeUrl = buildAuthorizeUrl(oauth, redirectUri, challenge);
+    const timeoutMs = options.timeoutMs ?? 5 * 60_000;
+    // The flow: code (listener-or-paste, or timeout) → exchange → store.
+    const done = (async () => {
+        const code = await Promise.race([
+            codeReceived,
+            new Promise((_, reject) => {
+                setTimeout(() => reject(new Error(`oauth for "${serverName}" timed out after ${timeoutMs / 1000}s waiting for the redirect (listener or paste)`)), timeoutMs).unref?.();
+            }),
+        ]);
+        const token = await exchangeCode(oauth, code, redirectUri, verifier);
+        storeMcpToken(serverName, token, options.env);
+        return token;
+    })();
+    // Settle closes the listener no matter which path won. NOTE: the rejection
+    // is HANDLED here (both callbacks), so the derived promise never becomes an
+    // unhandled rejection when the flow fails.
+    const stop = () => server.close();
+    void done.then(stop, stop);
+    return {
+        authorizeUrl,
+        redirectUri,
+        pasteUrl(url) {
+            let extracted;
+            try {
+                extracted = extractCode(url);
+            }
+            catch {
+                // A pasted line with no code (a stray paste, a log line): ignore —
+                // the user may paste the right URL next. Never throw: this runs in
+                // the CLI's readline handler, where a throw would crash the bin.
+                return;
+            }
+            if ("error" in extracted) {
+                // The AS redirected with an error parameter: fail fast instead
+                // of hanging until the timeout.
+                failFlow?.(new Error(`authorization server returned error: ${extracted.error}`));
+                return;
+            }
+            settleCode?.(extracted.code);
+        },
+        done,
+        stop,
+    };
+}

package/dist/section.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The `mcp_servers` prompt section (spec slice 3): lists every enabled server
+ * with codemode/deferred tools — name, description, and HOW its tools are
+ * reached (`tool_search` loads deferred tools; codemode scripts call
+ * codemode-exposed ones).
+ *
+ * Gating (rev 3's corrected channel — extensions have no boot hook, no
+ * registry visibility, no args; the section render is the only per-request
+ * seam): it reads `PromptInput.agent` at RENDER time. A server appears ONLY
+ * when its discovery tool is model-offered in THIS request (`codemode` for
+ * servers whose tools are script-reachable, `tool_search` for servers with
+ * deferred tools — a server with both needs at least one of them). When
+ * servers exist whose tools are unreachable through the offered set, one
+ * notice line says so. Per-request, de-duplicated by construction, visible
+ * to the model where it matters.
+ *
+ * Budget: the skills-section precedent — 4KB total including the truncation
+ * notice, whole lines drop from the end until the text fits, the notice
+ * names how many servers were cut.
+ */
+/** The section key the server list renders under (Task 7 asserts this). */
+export declare const MCP_SERVERS_SECTION_KEY = "mcp_servers";
+/** Total rendered-section budget (skills-section precedent), notice included. */
+export declare const MCP_SERVERS_SECTION_LIMIT_BYTES = 4096;
+/** One server's section entry (built at render time from live agent state). */
+export interface McpServerSectionEntry {
+    /** The configured server name (its tools register as `<name>/<tool>`). */
+    readonly name: string;
+    /** One line describing the server (from config or the connection). */
+    readonly description: string;
+    /** How the tools are reached: "codemode scripts" / "the tool_search tool". */
+    readonly how: string;
+}
+/** Which discovery tool a server's exposure needs to be listed. */
+export type Reach = "codemode" | "tool_search" | "either";
+/**
+ * Assemble the section text: the header plus one
+ * `- name: description (reachable via ...)` line per server, capped at
+ * {@link MCP_SERVERS_SECTION_LIMIT_BYTES} bytes including the truncation
+ * notice. Whole lines drop from the end until the text fits; the notice
+ * names how many servers were cut. Zero servers and zero unreachable
+ * render no section at all.
+ */
+export declare function renderMcpServersSection(entries: readonly McpServerSectionEntry[], unreachableCount: number): string | undefined;
+/**
+ * Partition live agent state for the section render: which configured
+ * codemode/deferred servers are LISTED (their discovery tool is offered in
+ * this request) and how many are unreachable (for the notice line).
+ *
+ * `offers` names the model-offered tool names in this request (from
+ * `PromptInput.agent.tools`); `reaches` maps each configured server name to
+ * the exposure mix its REGISTERED tools use (the extension computes this
+ * snapshot from its live registrations).
+ */
+export declare function partitionForSection(serverReaches: ReadonlyMap<string, Reach>, offers: ReadonlySet<string>): {
+    listed: string[];
+    unreachable: string[];
+};

package/dist/section.js

@@ -0,0 +1,92 @@
+/**
+ * The `mcp_servers` prompt section (spec slice 3): lists every enabled server
+ * with codemode/deferred tools — name, description, and HOW its tools are
+ * reached (`tool_search` loads deferred tools; codemode scripts call
+ * codemode-exposed ones).
+ *
+ * Gating (rev 3's corrected channel — extensions have no boot hook, no
+ * registry visibility, no args; the section render is the only per-request
+ * seam): it reads `PromptInput.agent` at RENDER time. A server appears ONLY
+ * when its discovery tool is model-offered in THIS request (`codemode` for
+ * servers whose tools are script-reachable, `tool_search` for servers with
+ * deferred tools — a server with both needs at least one of them). When
+ * servers exist whose tools are unreachable through the offered set, one
+ * notice line says so. Per-request, de-duplicated by construction, visible
+ * to the model where it matters.
+ *
+ * Budget: the skills-section precedent — 4KB total including the truncation
+ * notice, whole lines drop from the end until the text fits, the notice
+ * names how many servers were cut.
+ */
+/** The section key the server list renders under (Task 7 asserts this). */
+export const MCP_SERVERS_SECTION_KEY = "mcp_servers";
+/** Total rendered-section budget (skills-section precedent), notice included. */
+export const MCP_SERVERS_SECTION_LIMIT_BYTES = 4096;
+const SECTION_HEADER = "MCP servers with script-only or deferred tools. Tools on these servers are NOT offered to you directly:";
+const ENABLE_NOTICE = (count) => `(${count} server${count === 1 ? " has" : "s have"} script-only or deferred tools; enable codemode/tool_search in Settings → default tools to reach them)`;
+function byteLength(text) {
+    return new TextEncoder().encode(text).length;
+}
+/**
+ * Assemble the section text: the header plus one
+ * `- name: description (reachable via ...)` line per server, capped at
+ * {@link MCP_SERVERS_SECTION_LIMIT_BYTES} bytes including the truncation
+ * notice. Whole lines drop from the end until the text fits; the notice
+ * names how many servers were cut. Zero servers and zero unreachable
+ * render no section at all.
+ */
+export function renderMcpServersSection(entries, unreachableCount) {
+    if (entries.length === 0 && unreachableCount === 0)
+        return undefined;
+    // The unreachable-server notice always appends (count only).
+    const notice = unreachableCount === 0
+        ? ""
+        : `\n${ENABLE_NOTICE(unreachableCount)}`;
+    if (entries.length === 0) {
+        return notice.replace(/^\n/, "");
+    }
+    const header = `${SECTION_HEADER}\n\n`;
+    const lines = entries.map((entry) => `- ${entry.name}: ${entry.description} (reachable via ${entry.how})`);
+    const body = header + lines.join("\n");
+    if (byteLength(body + notice) <= MCP_SERVERS_SECTION_LIMIT_BYTES) {
+        return body + notice;
+    }
+    // Over budget: drop whole lines from the end until it fits (the skills
+    // section's idiom); the truncation notice names how many were cut.
+    let kept = lines.length - 1;
+    while (kept >= 0) {
+        const dropped = lines.length - kept;
+        const truncation = `\n(server list truncated: ${dropped} more not shown)`;
+        const text = header + lines.slice(0, kept).join("\n") + truncation;
+        if (byteLength(text + notice) <= MCP_SERVERS_SECTION_LIMIT_BYTES) {
+            return text + notice;
+        }
+        kept -= 1;
+    }
+    // The header alone always fits (reached only if a header change ever
+    // grows past the budget).
+    return header.replace(/\s+$/, "");
+}
+/**
+ * Partition live agent state for the section render: which configured
+ * codemode/deferred servers are LISTED (their discovery tool is offered in
+ * this request) and how many are unreachable (for the notice line).
+ *
+ * `offers` names the model-offered tool names in this request (from
+ * `PromptInput.agent.tools`); `reaches` maps each configured server name to
+ * the exposure mix its REGISTERED tools use (the extension computes this
+ * snapshot from its live registrations).
+ */
+export function partitionForSection(serverReaches, offers) {
+    const listed = [];
+    const unreachable = [];
+    for (const [name, reach] of serverReaches) {
+        const ok = reach === "codemode"
+            ? offers.has("codemode")
+            : reach === "tool_search"
+                ? offers.has("tool_search")
+                : offers.has("codemode") || offers.has("tool_search");
+        (ok ? listed : unreachable).push(name);
+    }
+    return { listed, unreachable };
+}

package/dist/tokens.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The OAuth token store (ruling 2): a JSON file BESIDE the resolved mcp.json
+ * — `<resolved-config-dir>/mcp-tokens.json` — so the `SIGRUN_MCP_CONFIG`
+ * override relocates tokens with config (a test / pod override moves both).
+ *
+ * Shape (one entry per configured server name):
+ *   { "<server-name>": {
+ *       "access_token": string, "token_type": string,
+ *       "refresh_token"?: string, "expires_at"?: number, "obtained_at": number
+ *   } }
+ *
+ * Files are written 0600 (secrets). A missing file is an empty store; an
+ * existing-but-malformed file is a fail-loud config error (consistent with
+ * the config store).
+ */
+/** One stored token (the AS's token-endpoint response, normalized). */
+export interface McpStoredToken {
+    readonly access_token: string;
+    readonly token_type: string;
+    readonly refresh_token?: string;
+    readonly expires_at?: number;
+    readonly obtained_at: number;
+}
+/** The whole token store: server name → token. */
+export type McpTokenStore = Record<string, McpStoredToken>;
+/** Resolve the token-store path for a given environment (beside config). */
+export declare function resolveMcpTokenPath(env?: NodeJS.ProcessEnv): string;
+/** Parse and validate a token-store body. */
+export declare function parseMcpTokenStore(text: string, source: string): McpTokenStore;
+/** Load the token store from beside the resolved config (missing = empty). */
+export declare function loadMcpTokens(env?: NodeJS.ProcessEnv): McpTokenStore;
+/** Persist the store: 0600, beside the resolved config (create-on-write —
+ * the config dir is expected to exist since the config file lives there). */
+export declare function saveMcpTokens(store: McpTokenStore, env?: NodeJS.ProcessEnv): void;
+/** Store one server's token (merge over the existing store). */
+export declare function storeMcpToken(name: string, token: McpStoredToken, env?: NodeJS.ProcessEnv): McpTokenStore;
+/**
+ * The env var a stored token is injected as (ruling 3): stdio MCP servers
+ * take credentials through env, not HTTP headers. A server with both an
+ * oauth block and a stored token spawns with this set (merged OVER the
+ * server's own `env`, so config wins over inheritance).
+ */
+export declare const MCP_ACCESS_TOKEN_ENV = "MCP_ACCESS_TOKEN";
+/**
+ * The spawn env for one server: the server's config env plus the stored
+ * token (as {@link MCP_ACCESS_TOKEN_ENV}) when the server has an oauth
+ * block AND a stored token. No oauth block, or no token yet (the user has
+ * not run `sigrun-ext-mcp oauth <name>`) → the server's env unchanged.
+ */
+export declare function spawnEnvWithToken(name: string, server: {
+    readonly env?: Readonly<Record<string, string>>;
+    readonly oauth?: {
+        readonly clientId: string;
+    };
+}, env?: NodeJS.ProcessEnv): Record<string, string>;

package/dist/tokens.js

@@ -0,0 +1,118 @@
+/**
+ * The OAuth token store (ruling 2): a JSON file BESIDE the resolved mcp.json
+ * — `<resolved-config-dir>/mcp-tokens.json` — so the `SIGRUN_MCP_CONFIG`
+ * override relocates tokens with config (a test / pod override moves both).
+ *
+ * Shape (one entry per configured server name):
+ *   { "<server-name>": {
+ *       "access_token": string, "token_type": string,
+ *       "refresh_token"?: string, "expires_at"?: number, "obtained_at": number
+ *   } }
+ *
+ * Files are written 0600 (secrets). A missing file is an empty store; an
+ * existing-but-malformed file is a fail-loud config error (consistent with
+ * the config store).
+ */
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { resolveMcpConfigPath } from "./config.js";
+/** Resolve the token-store path for a given environment (beside config). */
+export function resolveMcpTokenPath(env = process.env) {
+    const configPath = resolveMcpConfigPath(env);
+    return join(dirname(configPath), "mcp-tokens.json");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseTokenEntry(name, value, source) {
+    if (!isRecord(value)) {
+        throw new Error(`token store ${source}: entry "${name}" must be an object`);
+    }
+    if (typeof value.access_token !== "string" ||
+        typeof value.token_type !== "string" ||
+        typeof value.obtained_at !== "number") {
+        throw new Error(`token store ${source}: entry "${name}" needs string "access_token", string "token_type" and number "obtained_at"`);
+    }
+    if (value.refresh_token !== undefined &&
+        typeof value.refresh_token !== "string") {
+        throw new Error(`token store ${source}: entry "${name}" refresh_token must be a string`);
+    }
+    if (value.expires_at !== undefined && typeof value.expires_at !== "number") {
+        throw new Error(`token store ${source}: entry "${name}" expires_at must be a number`);
+    }
+    return {
+        access_token: value.access_token,
+        token_type: value.token_type,
+        ...(typeof value.refresh_token === "string"
+            ? { refresh_token: value.refresh_token }
+            : {}),
+        ...(typeof value.expires_at === "number"
+            ? { expires_at: value.expires_at }
+            : {}),
+        obtained_at: value.obtained_at,
+    };
+}
+/** Parse and validate a token-store body. */
+export function parseMcpTokenStore(text, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new Error(`token store ${source} is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    if (!isRecord(parsed)) {
+        throw new Error(`token store ${source} must be a JSON object`);
+    }
+    const store = {};
+    for (const [name, value] of Object.entries(parsed)) {
+        store[name] = parseTokenEntry(name, value, source);
+    }
+    return store;
+}
+/** Load the token store from beside the resolved config (missing = empty). */
+export function loadMcpTokens(env = process.env) {
+    const path = resolveMcpTokenPath(env);
+    if (!existsSync(path))
+        return {};
+    return parseMcpTokenStore(readFileSync(path, "utf8"), path);
+}
+/** Persist the store: 0600, beside the resolved config (create-on-write —
+ * the config dir is expected to exist since the config file lives there). */
+export function saveMcpTokens(store, env = process.env) {
+    const path = resolveMcpTokenPath(env);
+    writeFileSync(path, JSON.stringify(store, null, "\t") + "\n", {
+        mode: 0o600,
+    });
+    // POSIX honors `mode` only on create; chmod so an existing file also ends
+    // 0600 (e.g. a rewritten store on a stricter umask).
+    chmodSync(path, 0o600);
+}
+/** Store one server's token (merge over the existing store). */
+export function storeMcpToken(name, token, env = process.env) {
+    const store = loadMcpTokens(env);
+    store[name] = token;
+    saveMcpTokens(store, env);
+    return store;
+}
+/**
+ * The env var a stored token is injected as (ruling 3): stdio MCP servers
+ * take credentials through env, not HTTP headers. A server with both an
+ * oauth block and a stored token spawns with this set (merged OVER the
+ * server's own `env`, so config wins over inheritance).
+ */
+export const MCP_ACCESS_TOKEN_ENV = "MCP_ACCESS_TOKEN";
+/**
+ * The spawn env for one server: the server's config env plus the stored
+ * token (as {@link MCP_ACCESS_TOKEN_ENV}) when the server has an oauth
+ * block AND a stored token. No oauth block, or no token yet (the user has
+ * not run `sigrun-ext-mcp oauth <name>`) → the server's env unchanged.
+ */
+export function spawnEnvWithToken(name, server, env = process.env) {
+    if (server.oauth === undefined)
+        return { ...server.env };
+    const token = loadMcpTokens(env)[name];
+    if (token === undefined)
+        return { ...server.env };
+    return { ...server.env, [MCP_ACCESS_TOKEN_ENV]: token.access_token };
+}

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+/** Wire types for the MCP stdio protocol surface this extension uses. */
+import type { McpServerConfig } from "./config.js";
+/** One tool as `tools/list` reports it. */
+export interface McpToolDefinition {
+    readonly name: string;
+    readonly description?: string;
+    /** JSON Schema for the tool's arguments object. */
+    readonly inputSchema?: {
+        readonly type?: unknown;
+        readonly properties?: unknown;
+        readonly required?: unknown;
+        [key: string]: unknown;
+    };
+}
+/** One content block in a `tools/call` result. */
+export interface McpContentBlock {
+    readonly type: string;
+    readonly text?: string;
+    [key: string]: unknown;
+}
+/** A `tools/call` result: content blocks plus the error flag. */
+export interface McpToolResult {
+    readonly content?: readonly McpContentBlock[];
+    /** True when the tool ran and reported failure (a valid outcome). */
+    readonly isError?: boolean;
+    [key: string]: unknown;
+}
+export type { McpServerConfig };

package/dist/types.js

@@ -0,0 +1,2 @@
+/** Wire types for the MCP stdio protocol surface this extension uses. */
+export {};