crosscheck-mcp 0.1.0

package/dist/node-stdio.d.ts

@@ -0,0 +1,487 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+
+/** sessions row. */
+interface SessionRow {
+    session_id: string;
+    started_at: number;
+    last_at: number | null;
+    calls: number;
+    wall_ms: number;
+    cache_hits: number;
+    total_prompt_tokens: number;
+    total_completion_tokens: number;
+    total_cached_tokens: number;
+    total_tokens: number;
+    total_cost_usd: number;
+    total_cpu_ms: number;
+}
+/** usage_log row. */
+interface UsageLogRow {
+    id: number;
+    session_id: string;
+    ts: number;
+    tool: string | null;
+    purpose: string;
+    provider: string;
+    model: string;
+    prompt_tokens: number;
+    completion_tokens: number;
+    cached_tokens: number;
+    total_tokens: number;
+    cost_usd: number;
+    estimated: number;
+    wall_ms: number;
+    cpu_ms: number;
+}
+/** Insert shape for usage_log (id is auto-assigned, defaults filled by SQL). */
+interface UsageLogInsert {
+    session_id: string;
+    ts: number;
+    tool: string | null;
+    purpose: string;
+    provider: string;
+    model: string;
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    cached_tokens?: number;
+    total_tokens?: number;
+    cost_usd?: number;
+    estimated?: number;
+    wall_ms?: number;
+    cpu_ms?: number;
+}
+/** claims row. citations_json is the raw JSON string as stored. */
+interface ClaimRow {
+    id: number;
+    session_id: string;
+    text: string;
+    provider: string | null;
+    confidence: number | null;
+    citations_json: string | null;
+    kind: string | null;
+    created_at: number;
+}
+interface ClaimInsert {
+    session_id: string;
+    text: string;
+    provider?: string | null;
+    confidence?: number | null;
+    citations?: readonly string[] | null;
+    kind?: string | null;
+}
+/** claim_links row. kind is constrained: supports | attacks | derives_from | merges_with. */
+type ClaimLinkKind = "supports" | "attacks" | "derives_from" | "merges_with";
+interface ClaimLinkRow {
+    id: number;
+    src_id: number;
+    dst_id: number;
+    kind: ClaimLinkKind;
+    created_at: number;
+}
+/** provider_stats row. */
+interface ProviderStatsRow {
+    provider: string;
+    wins: number;
+    losses: number;
+    abstains: number;
+    last_at: number | null;
+}
+/** delegations row. */
+interface DelegationRow {
+    id: number;
+    session_id: string | null;
+    requester: string | null;
+    tool_call: string;
+    via: string;
+    accepted: number;
+    created_at: number;
+}
+/** session_memory row. kind is constrained: fact | open_question | decision. */
+type SessionMemoryKind = "fact" | "open_question" | "decision";
+interface SessionMemoryRow {
+    id: number;
+    session_id: string;
+    kind: SessionMemoryKind;
+    content: string;
+    source_tool: string | null;
+    source_call_id: string | null;
+    confidence: number | null;
+    created_at: number;
+    stale_at: number | null;
+    stale_reason: string | null;
+}
+interface SessionMemoryInsert {
+    session_id: string;
+    kind: SessionMemoryKind;
+    content: string;
+    source_tool?: string | null;
+    source_call_id?: string | null;
+    confidence?: number | null;
+}
+/** A single FTS5 search hit. The adapter handles snippet/highlight
+ *  internally; the caller never sees raw bm25 scores either — `score`
+ *  is normalized to [0, 1] where higher = better match. */
+interface SearchHit {
+    path: string;
+    session_id: string | null;
+    tool: string | null;
+    ts: number;
+    snippet: string;
+    /** Normalized [0,1]; higher is better. Adapters convert bm25 (lower-is-
+     *  better) to this normalized form internally. */
+    score: number;
+}
+interface RecallSearchOpts {
+    /** Match within a single session. */
+    session_id?: string;
+    /** Match within a single tool. */
+    tool?: string;
+    /** Only matches with ts >= sinceMs. */
+    since_ms?: number;
+}
+interface ListSessionMemoryOpts {
+    kinds?: readonly SessionMemoryKind[];
+    include_stale?: boolean;
+    limit?: number;
+}
+interface MarkStaleOpts {
+    ids?: readonly number[];
+    kinds?: readonly SessionMemoryKind[];
+    reason?: string;
+}
+interface StorageRead {
+    getSession(sessionId: string): Promise<SessionRow | null>;
+    listSessions(opts?: {
+        limit?: number;
+    }): Promise<readonly SessionRow[]>;
+    listUsageForSession(sessionId: string, opts?: {
+        only_purpose?: readonly string[];
+        only_provider?: readonly string[];
+        limit?: number;
+    }): Promise<readonly UsageLogRow[]>;
+    listUsageGroupedByPurpose(sessionId: string): Promise<readonly {
+        purpose: string;
+        calls: number;
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        cost_usd: number;
+        wall_ms: number;
+        cpu_ms: number;
+    }[]>;
+    listUsageGroupedByProvider(purpose?: string): Promise<readonly {
+        provider: string;
+        calls: number;
+        total_tokens: number;
+        cost_usd: number;
+        errors: number;
+    }[]>;
+    /** Per-provider per-purpose averages for the smart router. Filters
+     *  to ts >= sinceMs (epoch ms) when supplied. Returns provider,
+     *  calls + token sum + averages (tokens, cost, wall_ms). Mirrors
+     *  Python's `_router_stats` aggregation, sans the event-log error
+     *  counts (TS doesn't write an events.jsonl; callers default
+     *  error_rate to 0). */
+    listRouterStatsByPurpose(purpose: string, sinceMs?: number): Promise<readonly {
+        provider: string;
+        calls: number;
+        tokens_sum: number;
+        avg_total_tokens: number;
+        avg_cost_usd: number;
+        avg_wall_ms: number;
+    }[]>;
+    listClaimsForSession(sessionId: string): Promise<readonly ClaimRow[]>;
+    getClaim(claimId: number): Promise<ClaimRow | null>;
+    listClaimLinksForSession(sessionId: string): Promise<readonly ClaimLinkRow[]>;
+    listProviderStats(opts?: {
+        limit?: number;
+    }): Promise<readonly ProviderStatsRow[]>;
+    getProviderStats(provider: string): Promise<ProviderStatsRow | null>;
+    listDelegationsForSession(sessionId: string): Promise<readonly DelegationRow[]>;
+    countDelegationsByRequester(requester: string): Promise<number>;
+    countDelegationsBySession(sessionId: string): Promise<number>;
+    /** Count accepted-only delegations for a session. Used by the
+     *  delegate tool's quota check (Python's
+     *  `WHERE session_id=? AND accepted=1`). */
+    countAcceptedDelegationsBySession(sessionId: string): Promise<number>;
+    /** Count accepted-only delegations for a requester. Used by the
+     *  delegate tool's quota check. */
+    countAcceptedDelegationsByRequester(requester: string): Promise<number>;
+    /** Aggregate delegations grouped by (requester, accepted). Used by
+     *  scoreboard to count per-requester acceptances vs refusals. */
+    listDelegationAggregatesByRequester(): Promise<readonly {
+        requester: string;
+        accepted: 0 | 1;
+        count: number;
+    }[]>;
+    /** Return the four global row counts in one transaction. Each count
+     *  degrades to 0 if the table is missing (matches Python's
+     *  best-effort behavior). */
+    countScoreboardTotals(): Promise<{
+        sessions: number;
+        claims: number;
+        claim_links: number;
+        delegations: number;
+    }>;
+    listSessionMemory(sessionId: string, opts?: ListSessionMemoryOpts): Promise<readonly SessionMemoryRow[]>;
+    getFetchEgressTotals(sessionId: string): Promise<{
+        total_bytes: number;
+        unique_hosts: number;
+    }>;
+    /** True iff the (session_id, host) pair has been recorded before.
+     *  Used by fetch's unique-hosts cap to allow continued requests to
+     *  hosts already counted while rejecting new ones at the limit. */
+    hasFetchEgressHost(sessionId: string, host: string): Promise<boolean>;
+    recallSearch(query: string, k: number, opts?: RecallSearchOpts): Promise<readonly SearchHit[]>;
+}
+interface StorageWrite {
+    upsertSession(row: SessionRow): Promise<void>;
+    accumulateSessionTotals(sessionId: string, delta: {
+        calls?: number;
+        wall_ms?: number;
+        cache_hits?: number;
+        total_prompt_tokens?: number;
+        total_completion_tokens?: number;
+        total_cached_tokens?: number;
+        total_tokens?: number;
+        total_cost_usd?: number;
+        total_cpu_ms?: number;
+        last_at?: number;
+    }): Promise<void>;
+    insertUsage(rows: readonly UsageLogInsert[]): Promise<void>;
+    insertClaim(claim: ClaimInsert): Promise<number>;
+    insertClaimLink(srcId: number, dstId: number, kind: ClaimLinkKind): Promise<void>;
+    deleteClaimsForSession(sessionId: string): Promise<number>;
+    bumpProviderBallot(provider: string, ballot: "agree" | "disagree" | "abstain", at: number): Promise<void>;
+    insertDelegation(row: {
+        session_id: string | null;
+        requester: string | null;
+        tool_call: string;
+        via: string;
+        accepted: 0 | 1;
+        created_at: number;
+    }): Promise<void>;
+    insertSessionMemory(row: SessionMemoryInsert & {
+        created_at: number;
+    }): Promise<number>;
+    markSessionMemoryStale(sessionId: string, at: number, opts?: MarkStaleOpts): Promise<number>;
+    clearSessionMemory(sessionId: string): Promise<number>;
+    recordFetchEgress(sessionId: string, host: string, bytes: number, at: number): Promise<void>;
+    indexTranscript(row: {
+        path: string;
+        session_id: string | null;
+        tool: string;
+        ts: number;
+        content: string;
+    }): Promise<void>;
+}
+type Txn = StorageRead & StorageWrite;
+interface UnsafeStorage {
+    /** Execute arbitrary DDL/DML. Returns the rows-changed count.
+     *  DO NOT call from app code. */
+    exec(sql: string, params?: readonly unknown[]): Promise<number>;
+    /** Run a query returning rows. Returns each row as a generic record. */
+    query(sql: string, params?: readonly unknown[]): Promise<readonly Record<string, unknown>[]>;
+}
+interface Storage extends StorageRead, StorageWrite {
+    /** Open a transaction. The callback receives a Txn with the same
+     *  surface as Storage; nesting reuses the outer transaction via
+     *  SAVEPOINTs. Throws bubble out as ROLLBACK. */
+    txn<T>(fn: (txn: Txn) => Promise<T>): Promise<T>;
+    /** Migration runner — applies any pending migrations in order. Idempotent;
+     *  re-running is a no-op when nothing's pending. */
+    migrate(): Promise<{
+        applied: readonly string[];
+    }>;
+    /** PRAGMA-derived canonical schema string. Used by the parity gate to
+     *  assert a TS-init'd DB has the same schema as a Python-init'd one. */
+    canonicalSchema(): Promise<string>;
+    /** Access the unsafe surface. Migrations only. */
+    unsafe(): UnsafeStorage;
+    /** Close any underlying handles. */
+    close(): Promise<void>;
+}
+
+/** A live bridge to a Python crosscheck-agent child. */
+interface BridgeHandle {
+    /** Names of the tools exposed by the Python child (from its
+     *  `tools/list` response). */
+    readonly toolNames: ReadonlySet<string>;
+    /** PID of the spawned Python child process, or `null` if the
+     *  transport hasn't started yet / has already closed. Useful for
+     *  shutdown verification and host-side diagnostics. */
+    readonly pid: number | null;
+    /** Forward a `tools/call` to the Python child and return the result
+     *  envelope verbatim. */
+    callTool(name: string, args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: boolean;
+    }>;
+    /** Re-fetch the tool list (in case the child surfaces new tools mid-
+     *  session). Returns the new tool names. */
+    refreshTools(): Promise<ReadonlySet<string>>;
+    /** Tear down the bridge cleanly. Idempotent — repeat calls are no-ops. */
+    close(): Promise<void>;
+}
+
+interface PricingDoc {
+    /** `<provider>` -> `<model>` -> ModelRates. */
+    [provider: string]: unknown;
+}
+
+/** One provider call's token + cost record. Mirrors `Usage.to_dict()`
+ *  output exactly. */
+interface Usage {
+    provider: string;
+    model: string;
+    prompt_tokens: number;
+    completion_tokens: number;
+    cached_tokens: number;
+    total_tokens: number;
+    cost_usd: number;
+    estimated: boolean;
+    purpose: string;
+}
+
+/** Inbound message shape — chat-completions style. */
+interface ChatMessage {
+    role: "system" | "user" | "assistant" | string;
+    content: string;
+    [k: string]: unknown;
+}
+/** A successful `send()` result. */
+interface SendResult {
+    /** Concatenated text from the provider response. */
+    text: string;
+    /** Number of HTTP attempts that produced this result (>= 1). */
+    attempts: number;
+    /** Parsed + cost-augmented usage record. */
+    usage: Usage;
+}
+/** Args passed into every `Provider.send()` call. Mirrors the Python
+ *  `send(messages, max_tokens, temperature, purpose='worker')` signature
+ *  plus an optional `signal` for cancellation. */
+interface SendArgs {
+    messages: readonly ChatMessage[];
+    maxTokens: number;
+    temperature: number;
+    purpose?: string;
+    /** Optional AbortSignal so callers can cancel long-running calls. */
+    signal?: AbortSignal;
+    /** Optional one-call model override. Used by the cheap-mode tier
+     *  picker (see core/retarget.ts) to route a node to a cheaper model
+     *  without mutating the provider's default. */
+    modelOverride?: string;
+}
+/** Provider adapter. */
+interface Provider {
+    /** Lowercased identifier (e.g. "anthropic", "openai"). */
+    readonly name: string;
+    /** Default model for this provider (env-resolved at factory time). */
+    readonly model: string;
+    /** Make a request and return the parsed result. Throws `ProviderError`
+     *  on classified failures (auth, rate_limit, timeout, server, parse,
+     *  network, client). */
+    send(args: SendArgs): Promise<SendResult>;
+}
+
+declare const SERVER_NAME = "crosscheck-agent";
+declare const SERVER_VERSION = "0.1.0";
+interface CreateServerOptions {
+    /** Optional Python bridge. When supplied, the bridge's tools are
+     *  merged into the registry as proxy entries — they forward `tools/call`
+     *  to the Python child. In Phase 4 this is route-all mode (every
+     *  tool name comes from Python); in Phase 5+ native TS tools
+     *  override per-name. */
+    bridge?: BridgeHandle;
+    /** Native LLM providers, keyed by lowercased name. Threaded into
+     *  pick / audit / confer via the tool registry. When absent, those
+     *  tools return a clear "no providers" error (or defer to the bridge
+     *  if one is wired). */
+    providers?: Readonly<Record<string, Provider>>;
+    /** Optional provider allowlist. */
+    providerAllowlist?: readonly string[] | null;
+    /** SQLite-backed storage adapter. Threaded into recall / scoreboard /
+     *  session_memory / explain via the tool registry. */
+    storage?: Storage;
+    /** Directory holding transcript JSON files (used by `explain`). */
+    transcriptsDir?: string;
+    /** Repo root path (`.git/` ancestor). Used by update_crosscheck for
+     *  git ops + cache writes, and by `fetch` for evidence-dir resolution. */
+    repoRoot?: string;
+    /** Pricing doc (pricing.json content). Used by orchestrate's
+     *  cheap_mode tier picker. Without it, cheap_mode falls back to
+     *  id-hash provider rotation. */
+    pricing?: PricingDoc;
+}
+/**
+ * Create a not-yet-connected MCP server with the current tool surface
+ * registered. The caller is responsible for connecting it to a Transport.
+ *
+ * When `opts.bridge` is supplied, the Python tool surface is merged in
+ * via proxy handlers — TS-native tools win on name collisions so we can
+ * cut over per-tool in Phase 5 without restarting.
+ */
+declare function createServer(opts?: CreateServerOptions): Server;
+/**
+ * Connect a server to a transport and start serving. Pure plumbing — kept
+ * here so the entrypoint files stay short.
+ */
+declare function connectAndServe(transport: Transport, opts?: CreateServerOptions): Promise<Server>;
+
+/** The shape every event carries. v1 is single-typed (tool_invoke)
+ *  but the discriminant is kept on the payload so a future v2 can
+ *  add other events (provider_call, retry, breaker_trip, ...)
+ *  without breaking consumers. */
+interface CrosscheckEvent {
+    event: "tool_invoke";
+    /** Monotonic-time-derived id. NOT a UUID; just a short hex that's
+     *  unique within a process run so events from one call can be
+     *  correlated across emitters. */
+    id: string;
+    /** Tool name the host called (e.g. "confer", "audit"). */
+    tool: string;
+    /** ISO-8601 timestamp captured at handler start, in UTC. */
+    started_at: string;
+    /** Handler wall-clock duration in milliseconds. */
+    duration_ms: number;
+    /** "ok" when the handler returned without throwing; "error" when
+     *  it threw. A returned error-envelope (with `error_code`) still
+     *  counts as "ok" — the call completed, the tool just reported a
+     *  domain-level failure. */
+    status: "ok" | "error";
+    /** Top-level keys present in the args bag the host passed.
+     *  Sanitized in the sense that values are NOT included; key
+     *  inventory is usually enough to triage a regression. */
+    args_keys: string[];
+    /** When status="ok": top-level keys present in the result
+     *  envelope. Empty when status="error". */
+    result_keys: string[];
+    /** When the result envelope carries `error_code`, mirror it here
+     *  for easy filtering. Absent on a clean success. */
+    error_code?: string;
+    /** When status="error" (handler threw): the exception's message.
+     *  Truncated to 512 chars. */
+    error_message?: string;
+    /** Stringified-envelope byte length on success. Useful for
+     *  spotting outsized debate transcripts / orchestrate DAGs. */
+    envelope_bytes?: number;
+}
+/** Pluggable transport. Implementations should NEVER throw — a bad
+ *  emitter must not break the tool call it's observing. */
+interface EventEmitter {
+    emit(event: CrosscheckEvent): void;
+}
+declare function setEventEmitter(emitter: EventEmitter): void;
+declare function getEventEmitter(): EventEmitter;
+declare class RecordingEmitter implements EventEmitter {
+    readonly events: CrosscheckEvent[];
+    emit(event: CrosscheckEvent): void;
+    clear(): void;
+}
+
+export { type CreateServerOptions, type CrosscheckEvent, type EventEmitter, RecordingEmitter, SERVER_NAME, SERVER_VERSION, connectAndServe, createServer, getEventEmitter, setEventEmitter };