crosscheck-mcp 0.2.24 → 0.2.26

package/dist/embed.d.cts

@@ -0,0 +1,205 @@
+/** Default model per provider — matches Python's `build_providers()`. */
+declare const DEFAULT_MODELS: Readonly<Record<string, string>>;
+/**
+ * Built-in fallbacks for the DEFAULT models, used when a seat hasn't set its
+ * own `<PROVIDER>_MODEL_FALLBACKS`.
+ *
+ * This exists because of a concrete hazard the previous default was written
+ * to dodge: a newer model is not enabled on every account or project, so
+ * pinning one as the default breaks calls for anyone who lacks access. The
+ * old code solved that by defaulting to an older model everyone could reach,
+ * which cost everyone else the better one.
+ *
+ * A chain solves it properly — ask for the current model, and degrade to the
+ * broadly-available one ONLY on a model-access failure (never on a bad key, a
+ * rate limit, or a 500; see core/model-fallback.ts). Same mechanism the super
+ * lineup uses.
+ */
+declare const DEFAULT_FALLBACKS: Readonly<Record<string, readonly string[]>>;
+/** Build the active provider registry. Returns a `Record<name, Provider>`
+ *  with only the providers whose API key is present in `opts.env`.
+ *
+ *  Provider iteration order in the returned dict matches Python: anthropic,
+ *  openai, xai, mistral, groq, deepseek, gemini. */
+/**
+ * Providers kept OUT of the panel even when a key is present.
+ *
+ * A panel's cost and latency scale with its width, and every seat has to earn
+ * its place by contributing a view the others don't. mistral and groq were
+ * standing in the panel on the strength of having a key configured, not on
+ * the strength of what they added — so they are excluded at the registry,
+ * which is the one place every tool, the router and list_providers all read.
+ * Excluding here rather than in each tool's own resolveProviders (there are
+ * four separate copies) means they cannot reappear through a path someone
+ * forgot to update.
+ *
+ * Reversible without a rebuild:
+ *   CROSSCHECK_ENABLE_PROVIDERS=mistral,groq   puts them back
+ *   CROSSCHECK_EXCLUDE_PROVIDERS=kimi,qwen     excludes others
+ */
+declare const DEFAULT_EXCLUDED_PROVIDERS: readonly string[];
+
+/**
+ * Embedded host entrypoint — the API Crosscheck Desktop runs panels through.
+ *
+ * WHY NOT JUST SPEAK MCP OVER STDIO?
+ * ----------------------------------
+ * Because MCP's `tools/call` is request/response: one JSON envelope at the
+ * end. A `confer super` panel runs for minutes. A desktop app that shows a
+ * spinner for three minutes and then dumps five answers at once is not a
+ * working screen, it's a progress bar with extra steps.
+ *
+ * `runConfer` and `runDebate` already accept per-panelist hooks (added for
+ * the browser extension). This entrypoint turns those hooks into ONE typed,
+ * JSON-serializable event stream that survives an Electron IPC boundary, so
+ * the host can render the panel as it happens.
+ *
+ * WHAT THIS IS NOT
+ * ----------------
+ * Not token-level streaming. `Provider.send()` returns finished text — no
+ * adapter in this engine speaks SSE today. These events are panel LIFECYCLE:
+ * dispatched → resolved, with usage and cost attached. That is the honest
+ * granularity, and a host that renders it as "per-provider status + elapsed"
+ * is telling the truth. A host that renders a fake typewriter off these
+ * events is lying to its user.
+ *
+ * THE ENV RULE
+ * ------------
+ * Provider keys go into a PRIVATE env object that is handed to
+ * `buildProviders` and then dropped. They are never written to `process.env`.
+ * That is not tidiness — the desktop app spawns a terminal, and a child shell
+ * inherits `process.env`. Keeping keys out of it is what stops a user's own
+ * `env | grep KEY` from printing their Anthropic key inside our app.
+ */
+/**
+ * Vault provider id → engine env var.
+ *
+ * The two sides disagree on one name and always have: the vault (and the
+ * user) call it `grok`, the engine registry calls it `xai`. That split is
+ * load-bearing in both repos, so this table is the single place it is
+ * reconciled — mirroring `KEY_BINDINGS` in crosscheck-cli's mcp.ts. If you
+ * add a provider, it goes in both.
+ */
+declare const KEY_ENV: Readonly<Record<string, string>>;
+/** Vault provider id → engine model-pin env var. Same split, same reason. */
+declare const MODEL_ENV: Readonly<Record<string, string>>;
+declare function vaultId(engineName: string): string;
+/** Usage as a host should render it. Cost is what the engine computed from
+ *  pricing.json; `null` means we could not price the call, which a UI must
+ *  show as "unavailable" rather than as $0.00. */
+interface EventUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    costUsd: number | null;
+}
+type EngineEvent = 
+/** The panel has been selected and dispatch is about to begin. Carries the
+ *  full roster so a host can paint every provider's column up front. */
+{
+    type: "run.start";
+    runId: string;
+    tool: string;
+    at: number;
+    panel: Array<{
+        provider: string;
+        model: string;
+    }>;
+}
+/** One panelist's request just went out. `round` is present for debate. */
+ | {
+    type: "panelist.start";
+    runId: string;
+    at: number;
+    provider: string;
+    model: string;
+    round?: number;
+}
+/** One panelist resolved. `ok: false` means that provider failed and the
+ *  others carried on — never a reason to fail the run. */
+ | {
+    type: "panelist.done";
+    runId: string;
+    at: number;
+    provider: string;
+    model: string;
+    round?: number;
+    ok: boolean;
+    text: string;
+    error: string | null;
+    usage: EventUsage | null;
+}
+/** The moderator's synthesis landed (debate only). */
+ | {
+    type: "synthesis.done";
+    runId: string;
+    at: number;
+    text: string;
+    usage: EventUsage | null;
+}
+/** The run finished. `envelope` is byte-identical to what `call()` returns. */
+ | {
+    type: "run.done";
+    runId: string;
+    at: number;
+    durationMs: number;
+    envelope: unknown;
+}
+/** The run itself failed — not a panelist. Rare: a config or budget gate. */
+ | {
+    type: "run.error";
+    runId: string;
+    at: number;
+    message: string;
+};
+type EngineEventSink = (event: EngineEvent) => void;
+interface EmbeddedEngineOptions {
+    /** Vault provider id → raw API key. Only providers present here are built.
+     *  Held in a private env object; never written to `process.env`. */
+    keys: Readonly<Record<string, string>>;
+    /** Vault provider id → pinned model. Omit a provider to take the engine
+     *  default. Mirrors what `/account/models` and `crosscheck models set` do. */
+    models?: Readonly<Record<string, string>>;
+    /** Default moderator/synthesis provider. */
+    moderator?: string;
+    /** Explicit pricing.json path. Defaults to the copy bundled in `dist/`. */
+    pricingPath?: string;
+    /** Directory to archive run transcripts into. Omit to write none. */
+    transcriptsDir?: string;
+}
+interface EmbeddedEngine {
+    readonly version: string;
+    /** Providers actually built, by vault id — i.e. the ones with a usable key
+     *  that are not excluded from the panel. Sorted. */
+    readonly providers: readonly string[];
+    /** Effective model per built provider, by vault id. */
+    readonly models: Readonly<Record<string, string>>;
+    /** Every registered tool name. */
+    listTools(): string[];
+    /** Invoke any tool and wait for the final envelope. No events. */
+    call(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /** Invoke a tool, emitting lifecycle events as the panel progresses.
+     *  `confer` and `debate` stream; every other tool emits `run.start` and
+     *  `run.done` around a plain `call`, so a host can use one code path. */
+    run(name: string, args: Record<string, unknown>, onEvent: EngineEventSink): Promise<unknown>;
+    /** Flush queued telemetry. Call before the host process exits. */
+    close(): Promise<void>;
+}
+/** Pull the host-facing usage numbers out of an askOne envelope. Returns null
+ *  when the provider reported nothing — which a UI must render as unknown,
+ *  not as zero. */
+declare function usageOf(answer: Record<string, unknown>): EventUsage | null;
+declare function textOf(answer: Record<string, unknown>): string;
+declare function errorOf(answer: Record<string, unknown>): string | null;
+declare function createEmbeddedEngine(opts: EmbeddedEngineOptions): EmbeddedEngine;
+
+/** Test seam. `usageOf` encodes the "unknown is not zero" rule that the cost
+ *  column depends on, and it is not otherwise reachable without live keys. */
+declare const __test_internals: {
+    usageOf: typeof usageOf;
+    textOf: typeof textOf;
+    errorOf: typeof errorOf;
+    vaultId: typeof vaultId;
+};
+
+export { DEFAULT_EXCLUDED_PROVIDERS, DEFAULT_FALLBACKS, DEFAULT_MODELS, type EmbeddedEngine, type EmbeddedEngineOptions, type EngineEvent, type EngineEventSink, type EventUsage, KEY_ENV as __KEY_ENV, MODEL_ENV as __MODEL_ENV, __test_internals, createEmbeddedEngine };

package/dist/embed.d.ts

@@ -0,0 +1,205 @@
+/** Default model per provider — matches Python's `build_providers()`. */
+declare const DEFAULT_MODELS: Readonly<Record<string, string>>;
+/**
+ * Built-in fallbacks for the DEFAULT models, used when a seat hasn't set its
+ * own `<PROVIDER>_MODEL_FALLBACKS`.
+ *
+ * This exists because of a concrete hazard the previous default was written
+ * to dodge: a newer model is not enabled on every account or project, so
+ * pinning one as the default breaks calls for anyone who lacks access. The
+ * old code solved that by defaulting to an older model everyone could reach,
+ * which cost everyone else the better one.
+ *
+ * A chain solves it properly — ask for the current model, and degrade to the
+ * broadly-available one ONLY on a model-access failure (never on a bad key, a
+ * rate limit, or a 500; see core/model-fallback.ts). Same mechanism the super
+ * lineup uses.
+ */
+declare const DEFAULT_FALLBACKS: Readonly<Record<string, readonly string[]>>;
+/** Build the active provider registry. Returns a `Record<name, Provider>`
+ *  with only the providers whose API key is present in `opts.env`.
+ *
+ *  Provider iteration order in the returned dict matches Python: anthropic,
+ *  openai, xai, mistral, groq, deepseek, gemini. */
+/**
+ * Providers kept OUT of the panel even when a key is present.
+ *
+ * A panel's cost and latency scale with its width, and every seat has to earn
+ * its place by contributing a view the others don't. mistral and groq were
+ * standing in the panel on the strength of having a key configured, not on
+ * the strength of what they added — so they are excluded at the registry,
+ * which is the one place every tool, the router and list_providers all read.
+ * Excluding here rather than in each tool's own resolveProviders (there are
+ * four separate copies) means they cannot reappear through a path someone
+ * forgot to update.
+ *
+ * Reversible without a rebuild:
+ *   CROSSCHECK_ENABLE_PROVIDERS=mistral,groq   puts them back
+ *   CROSSCHECK_EXCLUDE_PROVIDERS=kimi,qwen     excludes others
+ */
+declare const DEFAULT_EXCLUDED_PROVIDERS: readonly string[];
+
+/**
+ * Embedded host entrypoint — the API Crosscheck Desktop runs panels through.
+ *
+ * WHY NOT JUST SPEAK MCP OVER STDIO?
+ * ----------------------------------
+ * Because MCP's `tools/call` is request/response: one JSON envelope at the
+ * end. A `confer super` panel runs for minutes. A desktop app that shows a
+ * spinner for three minutes and then dumps five answers at once is not a
+ * working screen, it's a progress bar with extra steps.
+ *
+ * `runConfer` and `runDebate` already accept per-panelist hooks (added for
+ * the browser extension). This entrypoint turns those hooks into ONE typed,
+ * JSON-serializable event stream that survives an Electron IPC boundary, so
+ * the host can render the panel as it happens.
+ *
+ * WHAT THIS IS NOT
+ * ----------------
+ * Not token-level streaming. `Provider.send()` returns finished text — no
+ * adapter in this engine speaks SSE today. These events are panel LIFECYCLE:
+ * dispatched → resolved, with usage and cost attached. That is the honest
+ * granularity, and a host that renders it as "per-provider status + elapsed"
+ * is telling the truth. A host that renders a fake typewriter off these
+ * events is lying to its user.
+ *
+ * THE ENV RULE
+ * ------------
+ * Provider keys go into a PRIVATE env object that is handed to
+ * `buildProviders` and then dropped. They are never written to `process.env`.
+ * That is not tidiness — the desktop app spawns a terminal, and a child shell
+ * inherits `process.env`. Keeping keys out of it is what stops a user's own
+ * `env | grep KEY` from printing their Anthropic key inside our app.
+ */
+/**
+ * Vault provider id → engine env var.
+ *
+ * The two sides disagree on one name and always have: the vault (and the
+ * user) call it `grok`, the engine registry calls it `xai`. That split is
+ * load-bearing in both repos, so this table is the single place it is
+ * reconciled — mirroring `KEY_BINDINGS` in crosscheck-cli's mcp.ts. If you
+ * add a provider, it goes in both.
+ */
+declare const KEY_ENV: Readonly<Record<string, string>>;
+/** Vault provider id → engine model-pin env var. Same split, same reason. */
+declare const MODEL_ENV: Readonly<Record<string, string>>;
+declare function vaultId(engineName: string): string;
+/** Usage as a host should render it. Cost is what the engine computed from
+ *  pricing.json; `null` means we could not price the call, which a UI must
+ *  show as "unavailable" rather than as $0.00. */
+interface EventUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    costUsd: number | null;
+}
+type EngineEvent = 
+/** The panel has been selected and dispatch is about to begin. Carries the
+ *  full roster so a host can paint every provider's column up front. */
+{
+    type: "run.start";
+    runId: string;
+    tool: string;
+    at: number;
+    panel: Array<{
+        provider: string;
+        model: string;
+    }>;
+}
+/** One panelist's request just went out. `round` is present for debate. */
+ | {
+    type: "panelist.start";
+    runId: string;
+    at: number;
+    provider: string;
+    model: string;
+    round?: number;
+}
+/** One panelist resolved. `ok: false` means that provider failed and the
+ *  others carried on — never a reason to fail the run. */
+ | {
+    type: "panelist.done";
+    runId: string;
+    at: number;
+    provider: string;
+    model: string;
+    round?: number;
+    ok: boolean;
+    text: string;
+    error: string | null;
+    usage: EventUsage | null;
+}
+/** The moderator's synthesis landed (debate only). */
+ | {
+    type: "synthesis.done";
+    runId: string;
+    at: number;
+    text: string;
+    usage: EventUsage | null;
+}
+/** The run finished. `envelope` is byte-identical to what `call()` returns. */
+ | {
+    type: "run.done";
+    runId: string;
+    at: number;
+    durationMs: number;
+    envelope: unknown;
+}
+/** The run itself failed — not a panelist. Rare: a config or budget gate. */
+ | {
+    type: "run.error";
+    runId: string;
+    at: number;
+    message: string;
+};
+type EngineEventSink = (event: EngineEvent) => void;
+interface EmbeddedEngineOptions {
+    /** Vault provider id → raw API key. Only providers present here are built.
+     *  Held in a private env object; never written to `process.env`. */
+    keys: Readonly<Record<string, string>>;
+    /** Vault provider id → pinned model. Omit a provider to take the engine
+     *  default. Mirrors what `/account/models` and `crosscheck models set` do. */
+    models?: Readonly<Record<string, string>>;
+    /** Default moderator/synthesis provider. */
+    moderator?: string;
+    /** Explicit pricing.json path. Defaults to the copy bundled in `dist/`. */
+    pricingPath?: string;
+    /** Directory to archive run transcripts into. Omit to write none. */
+    transcriptsDir?: string;
+}
+interface EmbeddedEngine {
+    readonly version: string;
+    /** Providers actually built, by vault id — i.e. the ones with a usable key
+     *  that are not excluded from the panel. Sorted. */
+    readonly providers: readonly string[];
+    /** Effective model per built provider, by vault id. */
+    readonly models: Readonly<Record<string, string>>;
+    /** Every registered tool name. */
+    listTools(): string[];
+    /** Invoke any tool and wait for the final envelope. No events. */
+    call(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /** Invoke a tool, emitting lifecycle events as the panel progresses.
+     *  `confer` and `debate` stream; every other tool emits `run.start` and
+     *  `run.done` around a plain `call`, so a host can use one code path. */
+    run(name: string, args: Record<string, unknown>, onEvent: EngineEventSink): Promise<unknown>;
+    /** Flush queued telemetry. Call before the host process exits. */
+    close(): Promise<void>;
+}
+/** Pull the host-facing usage numbers out of an askOne envelope. Returns null
+ *  when the provider reported nothing — which a UI must render as unknown,
+ *  not as zero. */
+declare function usageOf(answer: Record<string, unknown>): EventUsage | null;
+declare function textOf(answer: Record<string, unknown>): string;
+declare function errorOf(answer: Record<string, unknown>): string | null;
+declare function createEmbeddedEngine(opts: EmbeddedEngineOptions): EmbeddedEngine;
+
+/** Test seam. `usageOf` encodes the "unknown is not zero" rule that the cost
+ *  column depends on, and it is not otherwise reachable without live keys. */
+declare const __test_internals: {
+    usageOf: typeof usageOf;
+    textOf: typeof textOf;
+    errorOf: typeof errorOf;
+    vaultId: typeof vaultId;
+};
+
+export { DEFAULT_EXCLUDED_PROVIDERS, DEFAULT_FALLBACKS, DEFAULT_MODELS, type EmbeddedEngine, type EmbeddedEngineOptions, type EngineEvent, type EngineEventSink, type EventUsage, KEY_ENV as __KEY_ENV, MODEL_ENV as __MODEL_ENV, __test_internals, createEmbeddedEngine };