reasonix 0.2.2 → 0.3.0-alpha.1

package/dist/index.d.ts

@@ -612,6 +612,13 @@ interface TranscriptRecord {
      * stability, not to a different system prompt.
      */
     prefixHash?: string;
+    /**
+     * Structured plan state extracted by the Pillar 2 harvester. Present on
+     * assistant_final records when harvest was enabled and produced non-empty
+     * state. Omitted entirely when harvest is off or produced nothing —
+     * absence means "no data", not "empty plan".
+     */
+    planState?: TypedPlanState;
     /** Optional error message (role === "error"). */
     error?: string;
 }
@@ -690,6 +697,12 @@ interface ReplayStats extends SessionSummary {
     userTurns: number;
     /** Count of tool-role records (tool calls executed). */
     toolCalls: number;
+    /** Count of assistant_final records that carry a non-empty planState (harvest signal). */
+    harvestedTurns: number;
+    /** Sum of uncertainties across all harvested turns — a proxy for "how much did R1 hedge?" */
+    totalUncertainties: number;
+    /** Sum of subgoals across all harvested turns. */
+    totalSubgoals: number;
 }
 /**
  * Parse a transcript file and compute replay stats. Throws only on I/O
@@ -770,6 +783,261 @@ interface RenderOptions {
 declare function renderSummaryTable(report: DiffReport, _opts?: RenderOptions): string;
 declare function renderMarkdown(report: DiffReport): string;
 
+/**
+ * MCP (Model Context Protocol) type definitions.
+ *
+ * Hand-rolled rather than importing @modelcontextprotocol/sdk because:
+ *   - Reasonix's value-add isn't reimplementing the protocol, but *caching*
+ *     it. Owning the types lets us tune them for our integration (strip
+ *     fields we don't use, add the ones we do like Reasonix's prefixHash).
+ *   - Zero dependencies — consistent with how we wrote the DeepSeek client.
+ *   - If Anthropic bumps the SDK and introduces a breaking change, we're
+ *     insulated as long as we keep up with the spec itself.
+ *
+ * Spec reference: https://spec.modelcontextprotocol.io/ (2024-11-05 draft
+ * at time of writing). Only the subset Reasonix consumes is modeled here —
+ * tools list/call + init handshake. Resources and prompts are deferred.
+ *
+ * Transport note: the wire format for stdio MCP is **newline-delimited
+ * JSON** (NDJSON), not the LSP-style Content-Length header framing that
+ * some readers might expect. One JSON-RPC message per line.
+ */
+type JsonRpcId = string | number;
+interface JsonRpcRequest<P = unknown> {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    method: string;
+    params?: P;
+}
+interface JsonRpcNotification<P = unknown> {
+    jsonrpc: "2.0";
+    method: string;
+    params?: P;
+}
+interface JsonRpcSuccess<R = unknown> {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    result: R;
+}
+interface JsonRpcError {
+    jsonrpc: "2.0";
+    id: JsonRpcId | null;
+    error: {
+        /** JSON-RPC standard codes: -32700 parse, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal. MCP also defines its own range. */
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+type JsonRpcResponse<R = unknown> = JsonRpcSuccess<R> | JsonRpcError;
+type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcSuccess | JsonRpcError;
+interface McpClientInfo {
+    name: string;
+    version: string;
+}
+interface InitializeResult {
+    protocolVersion: string;
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    capabilities: {
+        tools?: {
+            listChanged?: boolean;
+        };
+        resources?: unknown;
+        prompts?: unknown;
+    };
+    instructions?: string;
+}
+interface McpToolSchema {
+    /** JSON Schema — compatible with Reasonix's tools.ts JSONSchema shape. */
+    type?: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    [extra: string]: unknown;
+}
+interface McpTool {
+    name: string;
+    description?: string;
+    /** MCP calls this `inputSchema`. Reasonix's `parameters` field is the same concept. */
+    inputSchema: McpToolSchema;
+}
+interface ListToolsResult {
+    tools: McpTool[];
+    nextCursor?: string;
+}
+interface McpContentBlockText {
+    type: "text";
+    text: string;
+}
+interface McpContentBlockImage {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+/** MCP result content is an array of typed blocks. Reasonix consumes only text for now — image blocks get stringified with a placeholder. */
+type McpContentBlock = McpContentBlockText | McpContentBlockImage;
+interface CallToolResult {
+    content: McpContentBlock[];
+    /** True = tool raised an error; the content describes it. */
+    isError?: boolean;
+}
+/** Current MCP protocol version Reasonix is coded against. */
+declare const MCP_PROTOCOL_VERSION = "2024-11-05";
+/** Type guard — success vs error response. */
+declare function isJsonRpcError(msg: JsonRpcResponse): msg is JsonRpcError;
+
+/**
+ * Stdio transport for MCP.
+ *
+ * MCP's stdio wire format is **newline-delimited JSON** (one JSON-RPC
+ * message per line). We spawn the server as a child process, write
+ * frames to its stdin, parse its stdout line-by-line as they arrive.
+ *
+ * Transport is abstracted behind an interface so unit tests can fake it
+ * with an in-process duplex pair — spawning real servers in unit tests
+ * is flaky and slow.
+ */
+
+/**
+ * A transport sends JSON-RPC messages upstream and surfaces messages
+ * arriving downstream via an async iterator. One instance per server
+ * connection.
+ */
+interface McpTransport {
+    /** Send one JSON-RPC message. Resolves when the bytes are accepted. */
+    send(message: JsonRpcMessage): Promise<void>;
+    /** Async iterator over incoming messages. Ends when the connection closes. */
+    messages(): AsyncIterableIterator<JsonRpcMessage>;
+    /** Close the underlying resource (kill child process, close streams). */
+    close(): Promise<void>;
+}
+interface StdioTransportOptions {
+    /** Argv to spawn. First element is the command. */
+    command: string;
+    args?: string[];
+    /** Env overlay — merged over process.env unless replaceEnv=true. */
+    env?: Record<string, string>;
+    /** When true, only the env above is visible to the child. Default false. */
+    replaceEnv?: boolean;
+    /** CWD for the child. Default: process.cwd(). */
+    cwd?: string;
+}
+/**
+ * Spawn `command args...` as a child process and use its stdin/stdout as
+ * an MCP transport. Stderr is forwarded to the parent's stderr so server
+ * diagnostics are still visible.
+ */
+declare class StdioTransport implements McpTransport {
+    private readonly child;
+    private readonly queue;
+    private readonly waiters;
+    private closed;
+    private stdoutBuffer;
+    constructor(opts: StdioTransportOptions);
+    send(message: JsonRpcMessage): Promise<void>;
+    messages(): AsyncIterableIterator<JsonRpcMessage>;
+    close(): Promise<void>;
+    /** Parse incoming stdout chunks into NDJSON messages. */
+    private onStdout;
+    private onClose;
+    private push;
+}
+
+/**
+ * MCP client — request/response correlation, initialize handshake,
+ * tools/list, tools/call. Built on top of a McpTransport so the same
+ * logic works against a real stdio server or an in-process fake.
+ */
+
+interface McpClientOptions {
+    transport: McpTransport;
+    clientInfo?: McpClientInfo;
+    /** Per-request timeout. Default 60s. */
+    requestTimeoutMs?: number;
+}
+declare class McpClient {
+    private readonly transport;
+    private readonly clientInfo;
+    private readonly requestTimeoutMs;
+    private readonly pending;
+    private nextId;
+    private readerStarted;
+    private initialized;
+    private _serverCapabilities;
+    constructor(opts: McpClientOptions);
+    /** Server's advertised capabilities, available after initialize(). */
+    get serverCapabilities(): InitializeResult["capabilities"];
+    /**
+     * Complete the initialize → initialized handshake. Must be called
+     * before any other method (otherwise compliant servers reject).
+     */
+    initialize(): Promise<InitializeResult>;
+    /** List tools the server exposes. */
+    listTools(): Promise<ListToolsResult>;
+    /** Invoke a tool by name. Returns the raw MCP result (caller unwraps content). */
+    callTool(name: string, args?: Record<string, unknown>): Promise<CallToolResult>;
+    /** Close the transport and reject any outstanding requests. */
+    close(): Promise<void>;
+    private assertInitialized;
+    private request;
+    private startReaderIfNeeded;
+    private readLoop;
+    private dispatch;
+}
+
+/**
+ * Bridge: register an MCP server's tools into a Reasonix ToolRegistry.
+ *
+ * This is the integration surface. Once done, `CacheFirstLoop` sees the
+ * MCP tools as if they were native — they inherit Cache-First + repair
+ * (scavenge / truncation / storm) automatically. That's the payoff: any
+ * MCP ecosystem tool, wrapped in Reasonix's Pillar 1 + Pillar 3 benefits.
+ */
+
+interface BridgeOptions {
+    /**
+     * Prefix prepended to every MCP tool name when registered. Defaults to
+     * empty (no prefix). Useful when bridging multiple servers into one
+     * registry and names collide — e.g. `fs` + `gh` both exposing `search`.
+     */
+    namePrefix?: string;
+    /** Registry to populate. Creates a fresh one if omitted. */
+    registry?: ToolRegistry;
+    /** Auto-flatten deep schemas (Pillar 3). Defaults to the registry's own default (true). */
+    autoFlatten?: boolean;
+}
+interface BridgeResult {
+    registry: ToolRegistry;
+    /** Names actually registered (may differ from MCP names when a prefix is applied). */
+    registeredNames: string[];
+    /** Names the server listed but the bridge skipped (e.g. invalid schemas). */
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+}
+/**
+ * Walk a connected `McpClient`'s tools/list result, register each into a
+ * Reasonix `ToolRegistry`. Each registered `fn` proxies through the
+ * client's tools/call. Tool results are flattened into a string (joining
+ * text blocks with newlines, prefixing image blocks as placeholders) so
+ * they fit Reasonix's existing tool-dispatch contract.
+ */
+declare function bridgeMcpTools(client: McpClient, opts?: BridgeOptions): Promise<BridgeResult>;
+/**
+ * Turn an MCP CallToolResult into a string — the contract Reasonix's
+ * ToolRegistry.dispatch returns. We:
+ *   - join text blocks with newlines (most common case)
+ *   - stringify image blocks as placeholders (LLM can't use bytes anyway
+ *     in Reasonix's current surface; image support comes with multimodal
+ *     prompts later)
+ *   - prefix error results with "ERROR: " so the calling model sees the
+ *     failure clearly even through JSON mode
+ */
+declare function flattenMcpResult(result: CallToolResult): string;
+
 /**
  * User-level config storage for the Reasonix CLI.
  *
@@ -797,6 +1065,6 @@ declare function redactKey(key: string): string;
 
 /** Reasonix — DeepSeek-native agent framework. Library entry point. */
 
-declare const VERSION = "0.2.2";
+declare const VERSION = "0.3.0-alpha.1";
 
-export { AppendOnlyLog, type BranchOptions, type BranchProgress, type BranchResult, type BranchSample, type BranchSelector, type BranchSummary, CacheFirstLoop, type CacheFirstLoopOptions, type ChatMessage, type ChatResponse, DeepSeekClient, type DeepSeekClientOptions, type RenderOptions as DiffRenderOptions, type DiffReport, type DiffSide, type EventRole, type FlattenDecision, type HarvestOptions, ImmutablePrefix, type ImmutablePrefixOptions, type JSONSchema, type LoopEvent, type ReadTranscriptResult, type ReasonixConfig, type ReconfigurableOptions, type RepairReport, type ReplayStats, type RetryInfo, type RetryOptions, type Role, type ScavengeOptions, type ScavengeResult, type SessionInfo, SessionStats, type SessionSummary, StormBreaker, type StreamChunk, type ToolCall, ToolCallRepair, type ToolCallRepairOptions, type ToolDefinition, type ToolFunctionSpec, ToolRegistry, type ToolSpec, type TranscriptMeta, type TranscriptRecord, type TruncationRepairResult, type TurnPair, type TurnStats, type TypedPlanState, Usage, VERSION, VolatileScratch, aggregateBranchUsage, analyzeSchema, appendSessionMessage, claudeEquivalentCost, computeReplayStats, costUsd, defaultConfigPath, defaultSelector, deleteSession, diffTranscripts, emptyPlanState, fetchWithRetry, flattenSchema, harvest, isPlanStateEmpty, isPlausibleKey, listSessions, loadApiKey, loadDotenv, loadSessionMessages, nestArguments, openTranscriptFile, parseTranscript, readConfig, readTranscript, recordFromLoopEvent, redactKey, renderMarkdown as renderDiffMarkdown, renderSummaryTable as renderDiffSummary, repairTruncatedJson, replayFromFile, runBranches, sanitizeName as sanitizeSessionName, saveApiKey, scavengeToolCalls, sessionPath, sessionsDir, similarity, writeConfig, writeMeta, writeRecord };
+export { AppendOnlyLog, type BranchOptions, type BranchProgress, type BranchResult, type BranchSample, type BranchSelector, type BranchSummary, type BridgeOptions, type BridgeResult, CacheFirstLoop, type CacheFirstLoopOptions, type CallToolResult, type ChatMessage, type ChatResponse, DeepSeekClient, type DeepSeekClientOptions, type RenderOptions as DiffRenderOptions, type DiffReport, type DiffSide, type EventRole, type FlattenDecision, type HarvestOptions, ImmutablePrefix, type ImmutablePrefixOptions, type InitializeResult, type JSONSchema, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcResponse, type ListToolsResult, type LoopEvent, MCP_PROTOCOL_VERSION, McpClient, type McpClientOptions, type McpContentBlock, type McpTool, type McpToolSchema, type McpTransport, type ReadTranscriptResult, type ReasonixConfig, type ReconfigurableOptions, type RepairReport, type ReplayStats, type RetryInfo, type RetryOptions, type Role, type ScavengeOptions, type ScavengeResult, type SessionInfo, SessionStats, type SessionSummary, StdioTransport, type StdioTransportOptions, StormBreaker, type StreamChunk, type ToolCall, ToolCallRepair, type ToolCallRepairOptions, type ToolDefinition, type ToolFunctionSpec, ToolRegistry, type ToolSpec, type TranscriptMeta, type TranscriptRecord, type TruncationRepairResult, type TurnPair, type TurnStats, type TypedPlanState, Usage, VERSION, VolatileScratch, aggregateBranchUsage, analyzeSchema, appendSessionMessage, bridgeMcpTools, claudeEquivalentCost, computeReplayStats, costUsd, defaultConfigPath, defaultSelector, deleteSession, diffTranscripts, emptyPlanState, fetchWithRetry, flattenMcpResult, flattenSchema, harvest, isJsonRpcError, isPlanStateEmpty, isPlausibleKey, listSessions, loadApiKey, loadDotenv, loadSessionMessages, nestArguments, openTranscriptFile, parseTranscript, readConfig, readTranscript, recordFromLoopEvent, redactKey, renderMarkdown as renderDiffMarkdown, renderSummaryTable as renderDiffSummary, repairTruncatedJson, replayFromFile, runBranches, sanitizeName as sanitizeSessionName, saveApiKey, scavengeToolCalls, sessionPath, sessionsDir, similarity, writeConfig, writeMeta, writeRecord };