crosscheck-mcp 0.2.27 → 0.2.29

package/dist/embed.d.cts

@@ -1,3 +1,62 @@
+import { C as ChatMessage } from './types-BcprisDl.cjs';
+
+/**
+ * A record of which engine processes are alive, and what they are RUNNING.
+ *
+ * WHY
+ * An engine process started weeks earlier was found still serving a pre-fix
+ * build while reporting the version on disk — so `crosscheck doctor` said
+ * "up to date" and the user kept hitting a bug that had already been fixed.
+ * Thirty-six such processes were once killed across twelve trees. Nothing
+ * reaps them and nothing notices them.
+ *
+ * The version a process REPORTS must be the one it LOADED, not the one
+ * currently installed. That is the whole point of writing it down at boot: a
+ * long-lived process cannot tell you what it is running if it re-reads the
+ * answer from disk every time you ask.
+ *
+ * WHY IT ONLY REPORTS
+ * It would be easy to kill anything older than N hours on startup. That is
+ * exactly what not to do here:
+ *   - the CLI and the desktop app share this directory, so "ours" is not a
+ *     safe inference from a name or a path;
+ *   - a long-running process may be mid-panel, and panels cost real money;
+ *   - a pid is reused after a process dies, so killing by a recorded pid can
+ *     kill something unrelated that happens to have inherited the number.
+ * So this module writes, reads, and prunes records of processes that are
+ * already gone. Deciding to kill a live one is the operator's, with the
+ * command printed for them.
+ */
+interface ProcRecord {
+    pid: number;
+    /** The engine version this process LOADED — not what is on disk now. */
+    version: string;
+    /** Epoch ms at boot. */
+    startedAt: number;
+    /** Parent pid at boot: the host that spawned us (Claude Code, a shell). */
+    ppid: number;
+    /** This process's session id, so a stale process can be tied to its rows. */
+    sessionId: string;
+}
+interface ProcStatus extends ProcRecord {
+    alive: boolean;
+    /** True when alive and running a version other than the one installed. */
+    outdated: boolean;
+    ageMs: number;
+}
+/** Is a pid still running? `kill(pid, 0)` signals nothing and throws ESRCH
+ *  when the process is gone — EPERM means alive but owned by someone else,
+ *  which still counts as alive. */
+declare function isAlive(pid: number): boolean;
+/**
+ * Every recorded process, with liveness. Records for dead pids are PRUNED as
+ * a side effect — they are the safe half of cleanup: the process is already
+ * gone, so deleting its note cannot hurt anything.
+ */
+declare function listProcesses(installedVersion: string, env?: NodeJS.ProcessEnv, now?: number): ProcStatus[];
+/** Directory path, for messages that tell an operator where to look. */
+declare function processRegistryPath(env?: NodeJS.ProcessEnv): string;
+
 /** Default model per provider — matches Python's `build_providers()`. */
 declare const DEFAULT_MODELS: Readonly<Record<string, string>>;
 /**
@@ -71,6 +130,7 @@ declare const DEFAULT_EXCLUDED_PROVIDERS: readonly string[];
  * 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.
  *
@@ -151,7 +211,54 @@ type EngineEvent =
     runId: string;
     at: number;
     message: string;
+}
+/** ACTIVITY — one provider request went out. Emitted for EVERY model call
+ *  a run makes, whatever the tool: panelists, the planner, workers,
+ *  reviewers, judges, synthesis, the co-reasoner. `purpose` is the
+ *  engine's role tag; `asked` is the start of the last user message. */
+ | {
+    type: "call.start";
+    runId: string;
+    at: number;
+    callId: number;
+    provider: string;
+    model: string;
+    purpose: string;
+    asked: string;
+}
+/** ACTIVITY — that request resolved. `text` is what the model said (capped
+ *  at ACTIVITY_TEXT_CAP; `truncated` says so). Finished text, not a token
+ *  stream: no adapter streams, and pretending otherwise would be a lie. */
+ | {
+    type: "call.done";
+    runId: string;
+    at: number;
+    callId: number;
+    provider: string;
+    model: string;
+    purpose: string;
+    ok: boolean;
+    ms: number;
+    text: string;
+    truncated: boolean;
+    error: string | null;
+    usage: EventUsage | null;
+    /** Set when the host stopped waiting (embed only): "user" from
+     *  skip(), "timeout" from the run's per-call time limit. The request
+     *  was aborted; the provider may still bill for work already done. */
+    stopped?: "user" | "timeout";
+}
+/** ACTIVITY — a step message from a multi-stage tool (orchestrate's
+ *  levels, recombine). */
+ | {
+    type: "progress";
+    runId: string;
+    at: number;
+    message: string;
 };
+/** How much of each model reply an activity event carries. Enough to read
+ *  the back-and-forth; the full text is in the envelope. */
+declare const ACTIVITY_TEXT_CAP = 8000;
 type EngineEventSink = (event: EngineEvent) => void;
 interface EmbeddedEngineOptions {
     /** Vault provider id → raw API key. Only providers present here are built.
@@ -167,6 +274,33 @@ interface EmbeddedEngineOptions {
     /** Directory to archive run transcripts into. Omit to write none. */
     transcriptsDir?: string;
 }
+interface RunOptions {
+    /** Stop waiting on any single model call after this long (ms). The run
+     *  continues with the answers already in. Off when 0/undefined. */
+    callTimeoutMs?: number;
+}
+interface AskOptions {
+    /** Vault id ("grok", not "xai"). Must be a provider this engine built. */
+    provider: string;
+    /** Model override; defaults to the provider's effective model. */
+    model?: string;
+    messages: ChatMessage[];
+    schema?: Record<string, unknown>;
+    /** Role tag for usage + the activity feed, e.g. "unify" or "code". */
+    purpose: string;
+    maxTokens?: number;
+    runId?: string;
+    onEvent?: EngineEventSink;
+}
+interface AskResult {
+    ok: boolean;
+    /** The model's raw reply. */
+    text: string;
+    /** Schema-validated value when a schema was given and the reply passed. */
+    json: unknown | null;
+    error: string | null;
+    model: string;
+}
 interface EmbeddedEngine {
     readonly version: string;
     /** Providers actually built, by vault id — i.e. the ones with a usable key
@@ -176,12 +310,27 @@ interface EmbeddedEngine {
     readonly models: Readonly<Record<string, string>>;
     /** Every registered tool name. */
     listTools(): string[];
+    /** A tool's required input fields, from its own schema — or null if there
+     *  is no such tool. Lets a host test its argument mapping against the
+     *  engine instead of guessing field names (the desktop guessed five of ten
+     *  wrong, and every one of those tools failed on missing input). */
+    requiredArgs(name: string): string[] | null;
     /** 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>;
+    run(name: string, args: Record<string, unknown>, onEvent: EngineEventSink, opts?: RunOptions): Promise<unknown>;
+    /** Stop waiting on one provider for the rest of a run: its in-flight
+     *  requests are aborted and later ones (e.g. debate rounds) aren't sent.
+     *  The run carries on with everyone else. The run's moderator is never
+     *  stopped mid-synthesis. Returns how many in-flight calls were stopped;
+     *  0 (and a no-op) once the run has finished. */
+    skip(runId: string, provider: string): number;
+    /** One call to one chosen provider/model — the host's own moderator or
+     *  coding step. With `runId` + `onEvent` it reports into that run's
+     *  activity feed. With `schema`, returns validated JSON when it can. */
+    ask(opts: AskOptions): Promise<AskResult>;
     /** Flush queued telemetry. Call before the host process exits. */
     close(): Promise<void>;
 }
@@ -202,4 +351,4 @@ declare const __test_internals: {
     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 };
+export { ACTIVITY_TEXT_CAP, type AskOptions, type AskResult, DEFAULT_EXCLUDED_PROVIDERS, DEFAULT_FALLBACKS, DEFAULT_MODELS, type EmbeddedEngine, type EmbeddedEngineOptions, type EngineEvent, type EngineEventSink, type EventUsage, type ProcRecord, type ProcStatus, type RunOptions, KEY_ENV as __KEY_ENV, MODEL_ENV as __MODEL_ENV, __test_internals, createEmbeddedEngine, isAlive, listProcesses, processRegistryPath };

package/dist/embed.d.ts

@@ -1,3 +1,62 @@
+import { C as ChatMessage } from './types-BcprisDl.js';
+
+/**
+ * A record of which engine processes are alive, and what they are RUNNING.
+ *
+ * WHY
+ * An engine process started weeks earlier was found still serving a pre-fix
+ * build while reporting the version on disk — so `crosscheck doctor` said
+ * "up to date" and the user kept hitting a bug that had already been fixed.
+ * Thirty-six such processes were once killed across twelve trees. Nothing
+ * reaps them and nothing notices them.
+ *
+ * The version a process REPORTS must be the one it LOADED, not the one
+ * currently installed. That is the whole point of writing it down at boot: a
+ * long-lived process cannot tell you what it is running if it re-reads the
+ * answer from disk every time you ask.
+ *
+ * WHY IT ONLY REPORTS
+ * It would be easy to kill anything older than N hours on startup. That is
+ * exactly what not to do here:
+ *   - the CLI and the desktop app share this directory, so "ours" is not a
+ *     safe inference from a name or a path;
+ *   - a long-running process may be mid-panel, and panels cost real money;
+ *   - a pid is reused after a process dies, so killing by a recorded pid can
+ *     kill something unrelated that happens to have inherited the number.
+ * So this module writes, reads, and prunes records of processes that are
+ * already gone. Deciding to kill a live one is the operator's, with the
+ * command printed for them.
+ */
+interface ProcRecord {
+    pid: number;
+    /** The engine version this process LOADED — not what is on disk now. */
+    version: string;
+    /** Epoch ms at boot. */
+    startedAt: number;
+    /** Parent pid at boot: the host that spawned us (Claude Code, a shell). */
+    ppid: number;
+    /** This process's session id, so a stale process can be tied to its rows. */
+    sessionId: string;
+}
+interface ProcStatus extends ProcRecord {
+    alive: boolean;
+    /** True when alive and running a version other than the one installed. */
+    outdated: boolean;
+    ageMs: number;
+}
+/** Is a pid still running? `kill(pid, 0)` signals nothing and throws ESRCH
+ *  when the process is gone — EPERM means alive but owned by someone else,
+ *  which still counts as alive. */
+declare function isAlive(pid: number): boolean;
+/**
+ * Every recorded process, with liveness. Records for dead pids are PRUNED as
+ * a side effect — they are the safe half of cleanup: the process is already
+ * gone, so deleting its note cannot hurt anything.
+ */
+declare function listProcesses(installedVersion: string, env?: NodeJS.ProcessEnv, now?: number): ProcStatus[];
+/** Directory path, for messages that tell an operator where to look. */
+declare function processRegistryPath(env?: NodeJS.ProcessEnv): string;
+
 /** Default model per provider — matches Python's `build_providers()`. */
 declare const DEFAULT_MODELS: Readonly<Record<string, string>>;
 /**
@@ -71,6 +130,7 @@ declare const DEFAULT_EXCLUDED_PROVIDERS: readonly string[];
  * 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.
  *
@@ -151,7 +211,54 @@ type EngineEvent =
     runId: string;
     at: number;
     message: string;
+}
+/** ACTIVITY — one provider request went out. Emitted for EVERY model call
+ *  a run makes, whatever the tool: panelists, the planner, workers,
+ *  reviewers, judges, synthesis, the co-reasoner. `purpose` is the
+ *  engine's role tag; `asked` is the start of the last user message. */
+ | {
+    type: "call.start";
+    runId: string;
+    at: number;
+    callId: number;
+    provider: string;
+    model: string;
+    purpose: string;
+    asked: string;
+}
+/** ACTIVITY — that request resolved. `text` is what the model said (capped
+ *  at ACTIVITY_TEXT_CAP; `truncated` says so). Finished text, not a token
+ *  stream: no adapter streams, and pretending otherwise would be a lie. */
+ | {
+    type: "call.done";
+    runId: string;
+    at: number;
+    callId: number;
+    provider: string;
+    model: string;
+    purpose: string;
+    ok: boolean;
+    ms: number;
+    text: string;
+    truncated: boolean;
+    error: string | null;
+    usage: EventUsage | null;
+    /** Set when the host stopped waiting (embed only): "user" from
+     *  skip(), "timeout" from the run's per-call time limit. The request
+     *  was aborted; the provider may still bill for work already done. */
+    stopped?: "user" | "timeout";
+}
+/** ACTIVITY — a step message from a multi-stage tool (orchestrate's
+ *  levels, recombine). */
+ | {
+    type: "progress";
+    runId: string;
+    at: number;
+    message: string;
 };
+/** How much of each model reply an activity event carries. Enough to read
+ *  the back-and-forth; the full text is in the envelope. */
+declare const ACTIVITY_TEXT_CAP = 8000;
 type EngineEventSink = (event: EngineEvent) => void;
 interface EmbeddedEngineOptions {
     /** Vault provider id → raw API key. Only providers present here are built.
@@ -167,6 +274,33 @@ interface EmbeddedEngineOptions {
     /** Directory to archive run transcripts into. Omit to write none. */
     transcriptsDir?: string;
 }
+interface RunOptions {
+    /** Stop waiting on any single model call after this long (ms). The run
+     *  continues with the answers already in. Off when 0/undefined. */
+    callTimeoutMs?: number;
+}
+interface AskOptions {
+    /** Vault id ("grok", not "xai"). Must be a provider this engine built. */
+    provider: string;
+    /** Model override; defaults to the provider's effective model. */
+    model?: string;
+    messages: ChatMessage[];
+    schema?: Record<string, unknown>;
+    /** Role tag for usage + the activity feed, e.g. "unify" or "code". */
+    purpose: string;
+    maxTokens?: number;
+    runId?: string;
+    onEvent?: EngineEventSink;
+}
+interface AskResult {
+    ok: boolean;
+    /** The model's raw reply. */
+    text: string;
+    /** Schema-validated value when a schema was given and the reply passed. */
+    json: unknown | null;
+    error: string | null;
+    model: string;
+}
 interface EmbeddedEngine {
     readonly version: string;
     /** Providers actually built, by vault id — i.e. the ones with a usable key
@@ -176,12 +310,27 @@ interface EmbeddedEngine {
     readonly models: Readonly<Record<string, string>>;
     /** Every registered tool name. */
     listTools(): string[];
+    /** A tool's required input fields, from its own schema — or null if there
+     *  is no such tool. Lets a host test its argument mapping against the
+     *  engine instead of guessing field names (the desktop guessed five of ten
+     *  wrong, and every one of those tools failed on missing input). */
+    requiredArgs(name: string): string[] | null;
     /** 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>;
+    run(name: string, args: Record<string, unknown>, onEvent: EngineEventSink, opts?: RunOptions): Promise<unknown>;
+    /** Stop waiting on one provider for the rest of a run: its in-flight
+     *  requests are aborted and later ones (e.g. debate rounds) aren't sent.
+     *  The run carries on with everyone else. The run's moderator is never
+     *  stopped mid-synthesis. Returns how many in-flight calls were stopped;
+     *  0 (and a no-op) once the run has finished. */
+    skip(runId: string, provider: string): number;
+    /** One call to one chosen provider/model — the host's own moderator or
+     *  coding step. With `runId` + `onEvent` it reports into that run's
+     *  activity feed. With `schema`, returns validated JSON when it can. */
+    ask(opts: AskOptions): Promise<AskResult>;
     /** Flush queued telemetry. Call before the host process exits. */
     close(): Promise<void>;
 }
@@ -202,4 +351,4 @@ declare const __test_internals: {
     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 };
+export { ACTIVITY_TEXT_CAP, type AskOptions, type AskResult, DEFAULT_EXCLUDED_PROVIDERS, DEFAULT_FALLBACKS, DEFAULT_MODELS, type EmbeddedEngine, type EmbeddedEngineOptions, type EngineEvent, type EngineEventSink, type EventUsage, type ProcRecord, type ProcStatus, type RunOptions, KEY_ENV as __KEY_ENV, MODEL_ENV as __MODEL_ENV, __test_internals, createEmbeddedEngine, isAlive, listProcesses, processRegistryPath };