@chances-ai/engine 24.0.0

package/dist/mcp/content.d.ts

@@ -0,0 +1,86 @@
+import type { McpResourceContent } from "./types.js";
+/**
+ * (5.4) An MCP content part — the shape carried by tool results, prompt
+ * messages, and embedded resources. Moved here (from `bridge.ts`) so the
+ * renderer can be shared by the bridge, the resource tools, and the prompt
+ * commands; `bridge.ts` re-exports it for backwards compatibility.
+ */
+export type McpContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data?: string;
+    mimeType?: string;
+} | {
+    type: "audio";
+    data?: string;
+    mimeType?: string;
+} | {
+    type: "resource";
+    resource?: {
+        uri?: string;
+        text?: string;
+        blob?: string;
+        mimeType?: string;
+    };
+} | {
+    type: "resource_link";
+    uri?: string;
+    name?: string;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+export interface RenderOptions {
+    /** Per-server secret scrubber. Applied to ALL rendered content (5.4 codex
+     *  R1 S1 — successful content is redacted too, not just errors: a server can
+     *  echo a bearer token in a normal prompt message / resource body). */
+    redact?: (msg: string) => string;
+}
+/**
+ * (5.4) Render MCP content parts to model/TUI-safe text. Text-first: `text`
+ * and embedded-resource `text` inline; `resource_link` and binary
+ * (`image`/`audio`/blob) become bracketed placeholders — v1 does not forward
+ * binary media into the model message (providers vary; the bridge has always
+ * done this for tool results). Strips terminal control sequences, then applies
+ * the caller's per-server redactor.
+ */
+export declare function renderMcpContentParts(content: ReadonlyArray<McpContentPart> | undefined, opts?: RenderOptions): string;
+/**
+ * Cap a string at `maxBytes` UTF-8 bytes WITHOUT splitting a code point (CJK-
+ * safe). Iterates by code point (`for…of`), stopping before the budget is
+ * exceeded; only runs the loop when truncation is actually needed.
+ */
+export declare function capUtf8(text: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+    fullBytes: number;
+};
+/** Resolve a SAFE extension for a blob's mime type. Strips any `;params`, then
+ *  looks up the allowlist; anything unknown → `bin`. */
+export declare function safeBlobExt(mimeType: string | undefined): string;
+/**
+ * Persist a binary blob under `<root>/.chances/tool-results/<id>/resource.<ext>`
+ * (0o700 dir, 0o600 file). `root` MUST be `ctx.parentWorkspaceRoot ?? ctx.workspaceRoot`
+ * (M6 — isolated-subagent artifacts survive worktree removal). Returns the path,
+ * or null on any fs failure (best-effort, like `persistFullOutput`).
+ */
+export declare function persistResourceBlob(root: string, data: Buffer, mimeType: string | undefined): string | null;
+export interface FormatResourceOptions {
+    redact?: (msg: string) => string;
+    /** Per-content-item UTF-8 byte cap for inline text. */
+    maxBytes: number;
+    /** Called for blob content; returns the persisted path (or null). When
+     *  omitted, blobs are summarised without persistence. */
+    persistBlob?: (data: Buffer, mimeType?: string) => string | null;
+}
+/**
+ * (5.4) Format `resources/read` content items into model-safe text. Text items
+ * are stripped + redacted + byte-capped (with a truncation note pointing at no
+ * file — callers that need the full body use the larger tool cap); blob items
+ * are persisted to disk and replaced with a bracketed path reference (claude-
+ * code parity). Never inlines base64.
+ */
+export declare function formatResourceContents(contents: McpResourceContent[], opts: FormatResourceOptions): string;
+//# sourceMappingURL=content.d.ts.map

package/dist/mcp/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/mcp/content.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGrD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAClG;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAE3C,MAAM,WAAW,aAAa;IAC5B;;2EAEuE;IACvE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;CAClC;AAID;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,EAClD,IAAI,GAAE,aAAkB,GACvB,MAAM,CAuBR;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAYzD;AAoBD;wDACwD;AACxD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAIhE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,GAAG,IAAI,CAUf;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IACjC,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB;6DACyD;IACzD,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAClE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,kBAAkB,EAAE,EAC9B,IAAI,EAAE,qBAAqB,GAC1B,MAAM,CA8BR"}

package/dist/mcp/content.js

@@ -0,0 +1,147 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createId } from "@chances-ai/runtime";
+import { stripTerminalControls } from "./redact.js";
+const identity = (m) => m;
+/**
+ * (5.4) Render MCP content parts to model/TUI-safe text. Text-first: `text`
+ * and embedded-resource `text` inline; `resource_link` and binary
+ * (`image`/`audio`/blob) become bracketed placeholders — v1 does not forward
+ * binary media into the model message (providers vary; the bridge has always
+ * done this for tool results). Strips terminal control sequences, then applies
+ * the caller's per-server redactor.
+ */
+export function renderMcpContentParts(content, opts = {}) {
+    const redact = opts.redact ?? identity;
+    if (!content || content.length === 0)
+        return "";
+    const parts = [];
+    for (const part of content) {
+        if (part.type === "text" && typeof part.text === "string") {
+            parts.push(part.text);
+        }
+        else if (part.type === "resource") {
+            const r = part.resource;
+            if (r?.text)
+                parts.push(r.text);
+            else if (r?.uri)
+                parts.push(`[resource ${r.uri}]`);
+        }
+        else if (part.type === "resource_link") {
+            const p = part;
+            parts.push(p.name ? `[resource ${p.uri ?? "?"} — ${p.name}]` : `[resource ${p.uri ?? "?"}]`);
+        }
+        else if (part.type === "image") {
+            parts.push(`[image ${part.mimeType ?? "unknown"}]`);
+        }
+        else if (part.type === "audio") {
+            parts.push(`[audio ${part.mimeType ?? "unknown"}]`);
+        }
+        else {
+            parts.push(`[${part.type} content]`);
+        }
+    }
+    return redact(stripTerminalControls(parts.join("\n")));
+}
+/**
+ * Cap a string at `maxBytes` UTF-8 bytes WITHOUT splitting a code point (CJK-
+ * safe). Iterates by code point (`for…of`), stopping before the budget is
+ * exceeded; only runs the loop when truncation is actually needed.
+ */
+export function capUtf8(text, maxBytes) {
+    const fullBytes = Buffer.byteLength(text, "utf8");
+    if (fullBytes <= maxBytes)
+        return { text, truncated: false, fullBytes };
+    let bytes = 0;
+    let out = "";
+    for (const ch of text) {
+        const b = Buffer.byteLength(ch, "utf8");
+        if (bytes + b > maxBytes)
+            break;
+        bytes += b;
+        out += ch;
+    }
+    return { text: out, truncated: true, fullBytes };
+}
+/** mime → safe file extension allowlist (5.4 codex R1 M6 — never derive a path
+ *  segment from raw MIME, which can carry `/`, params, or hostile text). */
+const MIME_EXT = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+    "image/svg+xml": "svg",
+    "application/pdf": "pdf",
+    "application/json": "json",
+    "application/octet-stream": "bin",
+    "text/plain": "txt",
+    "text/csv": "csv",
+    "text/html": "html",
+    "audio/mpeg": "mp3",
+    "audio/wav": "wav",
+};
+/** Resolve a SAFE extension for a blob's mime type. Strips any `;params`, then
+ *  looks up the allowlist; anything unknown → `bin`. */
+export function safeBlobExt(mimeType) {
+    if (!mimeType)
+        return "bin";
+    const base = mimeType.split(";")[0].trim().toLowerCase();
+    return MIME_EXT[base] ?? "bin";
+}
+/**
+ * Persist a binary blob under `<root>/.chances/tool-results/<id>/resource.<ext>`
+ * (0o700 dir, 0o600 file). `root` MUST be `ctx.parentWorkspaceRoot ?? ctx.workspaceRoot`
+ * (M6 — isolated-subagent artifacts survive worktree removal). Returns the path,
+ * or null on any fs failure (best-effort, like `persistFullOutput`).
+ */
+export function persistResourceBlob(root, data, mimeType) {
+    try {
+        const dir = join(root, ".chances", "tool-results", createId("mcpres"));
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const path = join(dir, `resource.${safeBlobExt(mimeType)}`);
+        writeFileSync(path, data, { mode: 0o600 });
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * (5.4) Format `resources/read` content items into model-safe text. Text items
+ * are stripped + redacted + byte-capped (with a truncation note pointing at no
+ * file — callers that need the full body use the larger tool cap); blob items
+ * are persisted to disk and replaced with a bracketed path reference (claude-
+ * code parity). Never inlines base64.
+ */
+export function formatResourceContents(contents, opts) {
+    const redact = opts.redact ?? identity;
+    const out = [];
+    for (const c of contents) {
+        if (typeof c.text === "string") {
+            const cleaned = redact(stripTerminalControls(c.text));
+            const capped = capUtf8(cleaned, opts.maxBytes);
+            out.push(capped.truncated
+                ? `${capped.text}\n[…truncated — ${capped.fullBytes} bytes total]`
+                : capped.text);
+        }
+        else if (typeof c.blob === "string") {
+            let buf;
+            try {
+                buf = Buffer.from(c.blob, "base64");
+            }
+            catch {
+                buf = undefined;
+            }
+            const path = buf && opts.persistBlob ? opts.persistBlob(buf, c.mimeType) : null;
+            const mime = c.mimeType ?? "application/octet-stream";
+            // (5.4 R2 S1) `mimeType` is server-controlled — strip + redact BOTH the
+            // persisted and the not-persisted notes, not just the persisted one.
+            const note = path
+                ? `[binary resource (${mime}) saved to ${path}]`
+                : `[binary resource (${mime})${buf ? `, ${buf.length} bytes` : ""} — not persisted]`;
+            out.push(redact(stripTerminalControls(note)));
+        }
+    }
+    return out.join("\n\n");
+}
+//# sourceMappingURL=content.js.map

package/dist/mcp/content.js.map

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

package/dist/mcp/env.d.ts

@@ -0,0 +1,19 @@
+import type { McpServerConfig } from "./types.js";
+/**
+ * Expands `${VAR}` and `${VAR:-default}` references inside a single string.
+ * No `$VAR` (without braces) on purpose — too many MCP commands contain
+ * unbraced dollars in URLs and we don't want false positives.
+ *
+ * Unknown variables without a `:-default` fallback throw `AppError(Config)`
+ * so misconfigured env doesn't silently produce a string with an unresolved
+ * `${VAR}` literal that the MCP server can't parse.
+ */
+export declare function expandEnv(raw: string, env: Record<string, string | undefined>): string;
+/**
+ * Walks a config entry and expands every string field that could meaningfully
+ * carry an env reference: command, args[], env values, cwd, url, header
+ * values. Leaves booleans / numbers / undefined alone. Returns a new object —
+ * never mutates the input.
+ */
+export declare function expandServerEnv(config: McpServerConfig, env: Record<string, string | undefined>): McpServerConfig;
+//# sourceMappingURL=env.d.ts.map

package/dist/mcp/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/mcp/env.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,CAUtF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,eAAe,CAgBjB"}

package/dist/mcp/env.js

@@ -0,0 +1,50 @@
+import { AppError, ErrorCode } from "@chances-ai/runtime";
+/**
+ * Expands `${VAR}` and `${VAR:-default}` references inside a single string.
+ * No `$VAR` (without braces) on purpose — too many MCP commands contain
+ * unbraced dollars in URLs and we don't want false positives.
+ *
+ * Unknown variables without a `:-default` fallback throw `AppError(Config)`
+ * so misconfigured env doesn't silently produce a string with an unresolved
+ * `${VAR}` literal that the MCP server can't parse.
+ */
+export function expandEnv(raw, env) {
+    return raw.replace(/\$\{([A-Z_][A-Z0-9_]*)(?::-([^}]*))?\}/gi, (_match, name, fallback) => {
+        const value = env[name];
+        if (value !== undefined && value !== "")
+            return value;
+        if (fallback !== undefined)
+            return fallback;
+        throw new AppError(ErrorCode.Config, `mcp env: required variable \${${name}} is not set (use \${${name}:-default} to provide a fallback)`);
+    });
+}
+/**
+ * Walks a config entry and expands every string field that could meaningfully
+ * carry an env reference: command, args[], env values, cwd, url, header
+ * values. Leaves booleans / numbers / undefined alone. Returns a new object —
+ * never mutates the input.
+ */
+export function expandServerEnv(config, env) {
+    const exp = (s) => expandEnv(s, env);
+    if (config.type === "stdio") {
+        return {
+            ...config,
+            command: exp(config.command),
+            args: config.args?.map(exp),
+            env: config.env ? mapValues(config.env, exp) : undefined,
+            cwd: config.cwd ? exp(config.cwd) : undefined,
+        };
+    }
+    return {
+        ...config,
+        url: exp(config.url),
+        headers: config.headers ? mapValues(config.headers, exp) : undefined,
+    };
+}
+function mapValues(obj, f) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj))
+        out[k] = f(v);
+    return out;
+}
+//# sourceMappingURL=env.js.map

package/dist/mcp/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/mcp/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAG1D;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,GAAuC;IAC5E,OAAO,GAAG,CAAC,OAAO,CAAC,0CAA0C,EAAE,CAAC,MAAM,EAAE,IAAY,EAAE,QAAiB,EAAE,EAAE;QACzG,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;YAAE,OAAO,KAAK,CAAC;QACtD,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAC;QAC5C,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,MAAM,EAChB,iCAAiC,IAAI,wBAAwB,IAAI,mCAAmC,CACrG,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAuB,EACvB,GAAuC;IAEvC,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACrD,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC5B,OAAO;YACL,GAAG,MAAM;YACT,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC;YAC5B,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC;YAC3B,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;YACxD,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;SAC9C,CAAC;IACJ,CAAC;IACD,OAAO;QACL,GAAG,MAAM;QACT,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;KACrE,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAI,GAAsB,EAAE,CAAc;IAC1D,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/mcp/host.d.ts

@@ -0,0 +1,199 @@
+import type { EventBus, Logger } from "@chances-ai/runtime";
+import type { ToolRegistry } from "../tools/index.js";
+import { type ClientIdentity } from "./client.js";
+import { type RuntimeRedactor } from "./redact.js";
+import type { HttpMcpConfig, McpPrompt, McpPromptMessage, McpResource, McpResourceContent, McpServerConfig, McpServerStatus, McpTestResult } from "./types.js";
+import type { McpResourceProvider } from "./resources.js";
+import { ChancesOAuthClientProvider } from "./oauth/provider.js";
+import { LoopbackCallbackServer } from "./oauth/callback-server.js";
+/**
+ * (3.7) Narrow vault surface the host depends on. Mirrored from
+ * `@chances-ai/local-vault#LocalVault` so this package does NOT hard-import
+ * the optional peer (which is loaded via computed specifier in
+ * `loadMcp({withVault})` — see `index.ts`).
+ */
+export interface LocalVaultLike {
+    read<T = unknown>(key: string): Promise<T | undefined>;
+    list(): Promise<readonly string[]>;
+    remove(key: string): Promise<void>;
+    mergeMutate<T>(key: string, mutator: (current: T | undefined) => T | undefined | Promise<T | undefined>, allowDelete?: boolean): Promise<void>;
+}
+export interface McpHostOptions {
+    /** Map keyed by server id (used in `mcp__<server>__<tool>` names). */
+    servers: Record<string, McpServerConfig>;
+    bus: EventBus;
+    logger: Logger;
+    registry: ToolRegistry;
+    /** Optional env source for `${VAR}` expansion. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Connection-attempt timeout, in ms. Caps a single server's startup so a
+     * wedged spawn doesn't block the whole boot. Defaults to 10 000 ms. */
+    connectTimeoutMs?: number;
+    /**
+     * Identity the host announces to each MCP server during the initialize
+     * handshake. Callers (the CLI) thread `{ name: pkg.name, version: pkg.version }`
+     * read from their own `package.json` — keeping the version read out of
+     * `@chances-ai/mcp` itself avoids the unverified "Bun embeds a transitive
+     * workspace JSON import" path under `bun build --compile`. When omitted,
+     * the library falls back to a `0.0.0-dev` default.
+     */
+    clientIdentity?: ClientIdentity;
+    /**
+     * (3.7) Encrypted credential store. Required for OAuth-configured
+     * servers; absent means OAuth servers fail with a clear "vault
+     * unavailable" message and the rest keep working. Routed in by
+     * `loadMcp({withVault: true})` — see `index.ts`. `apps/cli` never
+     * imports `@chances-ai/local-vault` directly (boundary decision).
+     */
+    vault?: LocalVaultLike;
+    /**
+     * (3.7) Platform-agnostic browser launcher used by `/mcp login`.
+     * Default delegates to `open` / `xdg-open` / `start.exe`. Tests inject
+     * a stub.
+     */
+    openBrowser?: (url: URL) => Promise<void>;
+    /**
+     * (5.4 D6′) Absolute workspace root advertised to servers via `roots/list`
+     * when `advertiseRoots` is true. Threaded from the CLI boot.
+     */
+    workspaceRoot?: string;
+    /**
+     * (5.4 D6′ / S5) Advertise the `roots` capability (workspace path) to
+     * servers. `listChanged` is always false. Default false at the library layer;
+     * the CLI passes `config.mcp.advertiseRoots` (default true).
+     */
+    advertiseRoots?: boolean;
+}
+/**
+ * (3.7) Per-server OAuth state held by the host across restart cycles.
+ * The redactor outlives any single connect cycle so tokens written
+ * during connect-N stay scrubbed in errors from connect-N+1.
+ *
+ * **(codex Round-2 MUST-FIX #3 + #4)** The provider + callbackServer
+ * pair is recreated whenever the vault generation bumps (e.g. on
+ * `/mcp logout`), since the provider holds an immutable snapshot of
+ * that generation. The previous V1 also held a `RefreshCoalescer` but
+ * no production codepath called `coalescer.refresh(...)` — the SDK
+ * owns refresh through `auth()` and we never intercepted it — so the
+ * field has been removed. Coalescing the SDK's refresh path is a
+ * 3.7.1 follow-up (would require taking ownership of refresh in the
+ * provider's `tokens()` and re-issuing the IdP call ourselves).
+ */
+export interface OAuthServerState {
+    provider: ChancesOAuthClientProvider;
+    callbackServer: LoopbackCallbackServer;
+    redactor: RuntimeRedactor;
+    /** The OAuth-configured HTTP server config — the slash command's
+     *  `/mcp login` flow needs the URL + scopes to drive `auth()`. */
+    config: HttpMcpConfig & {
+        auth: {
+            kind: "oauth";
+            scopes?: readonly string[];
+        };
+    };
+}
+/**
+ * Lifecycle orchestrator for one or more MCP servers. Connects them in
+ * parallel on `start()`, surfaces per-server failures as `failed` status
+ * instead of crashing the whole boot, and registers each server's discovered
+ * tools into the host `ToolRegistry`.
+ *
+ * Not a Plugin — MCP integration lives at the runtime layer because the
+ * engine consumes tools, not plugin hooks. Slash commands and CLI glue talk
+ * to the host directly.
+ *
+ * **Lifecycle serialization.** Every method that mutates host state
+ * (`startServer` / `restart` / `remove` / `dispose`) is chained behind a
+ * single `opsLock` promise so concurrent calls observe a consistent state
+ * machine. Two concurrent `restart(x)` calls run sequentially; a
+ * `dispose()` interleaved with a `restart()` always wins (because each
+ * step re-checks `disposed`). This guards against the codex-flagged race
+ * where a floating `/mcp restart` could resurrect a server after global
+ * teardown.
+ */
+export declare class McpHost implements McpResourceProvider {
+    private readonly opts;
+    private readonly states;
+    private disposed;
+    private opsLock;
+    private constructor();
+    /**
+     * Constructs and starts the host. Returns once every server has either
+     * connected (and its tools are in the registry) or failed (status
+     * `failed`, error message logged). Always resolves — never throws — so a
+     * misconfigured MCP server can't take down the agent.
+     */
+    static start(opts: McpHostOptions): Promise<McpHost>;
+    status(): McpServerStatus[];
+    /**
+     * Tears down the named server (if any), wipes its registered tools, then
+     * reconnects from its current config. Surfaces the new status. Caller is
+     * the `/mcp restart` slash command.
+     */
+    restart(id: string): Promise<McpServerStatus>;
+    /**
+     * Tears down the named server and unregisters its tools, but leaves no
+     * trace in host state — callers (typically `/mcp remove`) own the config
+     * mutation. Throws if no such server is known.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * One-shot validation: connect, list tools, dispose. Doesn't register any
+     * tools or mutate host state. Caller is `/mcp test`.
+     */
+    test(id: string): Promise<McpTestResult>;
+    /**
+     * Tears down every server and unregisters their tools. Safe to call
+     * repeatedly; subsequent calls are no-ops.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Serializes a lifecycle operation behind `opsLock` so concurrent
+     * `restart`/`remove`/`dispose` calls run one at a time. The lock is a
+     * promise chain — every new op `.then`s itself onto the previous one.
+     */
+    private runOp;
+    private startServer;
+    private discoverResources;
+    private discoverPrompts;
+    private disposeServer;
+    /** Cached `resources/list` snapshot across servers (optional filter). */
+    resources(server?: string): McpResource[];
+    /** Cached `prompts/list` snapshot across servers (optional filter). */
+    prompts(server?: string): McpPrompt[];
+    readResource(server: string, uri: string, signal: AbortSignal): Promise<{
+        contents: McpResourceContent[];
+        redact: (msg: string) => string;
+    }>;
+    getPrompt(server: string, name: string, args: Record<string, string>, signal: AbortSignal): Promise<{
+        messages: McpPromptMessage[];
+        description?: string;
+        redact: (msg: string) => string;
+    }>;
+    /** (5.4 S3) Throw if the server's client was swapped/disposed during an await. */
+    private assertSameGeneration;
+    /**
+     * Test/slash seam — returns the per-server OAuth bag (provider,
+     * callback server, coalescer, redactor). Returns undefined when the
+     * server isn't OAuth-configured or hasn't been started yet.
+     */
+    getOAuthState(id: string): OAuthServerState | undefined;
+    /**
+     * (3.7) Logs out a single OAuth-configured server:
+     *  1. Bumps the vault payload's generation (via `invalidateCredentials("all")`)
+     *     so late-arriving `saveTokens` from a refresh that escaped the
+     *     teardown drops on the generation guard inside `mergeMutate`
+     *     (codex Round-1 MUST-FIX #5).
+     *  2. Restarts the server. **(codex Round-2 MUST-FIX #3)** `startServer`
+     *     constructs a FRESH `ChancesOAuthClientProvider` with the new
+     *     generation snapshot, so the next `/mcp login` can persist tokens
+     *     and the old provider's cached state can't resurface.
+     *
+     * No-op when the server isn't OAuth-configured.
+     */
+    logout(id: string): Promise<void>;
+    /** (3.7) Logs out every OAuth-configured server. Per-server failures
+     *  don't abort the loop. */
+    logoutAll(): Promise<void>;
+}
+//# sourceMappingURL=host.d.ts.map

package/dist/mcp/host.d.ts.map

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