reasonix 0.0.4 → 0.0.6

package/dist/index.d.ts

@@ -172,6 +172,58 @@ declare function emptyPlanState(): TypedPlanState;
 declare function isPlanStateEmpty(s: TypedPlanState | null | undefined): boolean;
 declare function harvest(reasoningContent: string | null | undefined, client?: DeepSeekClient, options?: HarvestOptions): Promise<TypedPlanState>;
 
+/**
+ * Self-consistency branching.
+ *
+ * When enabled, the loop fans out into N parallel samples per turn (varied
+ * temperatures), runs Pillar 2 harvest on each, and selects the sample with
+ * the fewest flagged uncertainties (ties broken by answer length — a crude
+ * Occam prior).
+ *
+ * The unique opportunity here: because DeepSeek is ~20× cheaper than Claude,
+ * running N=3–5 samples per turn is still cheaper than a single Claude call,
+ * while the majority-confidence selection tends to dominate single-sample
+ * answers on fuzzy multi-step reasoning tasks.
+ */
+
+interface BranchSample {
+    index: number;
+    temperature: number;
+    response: ChatResponse;
+    planState: TypedPlanState;
+}
+type BranchSelector = (samples: BranchSample[]) => BranchSample;
+interface BranchOptions {
+    /** Number of parallel samples. 1 disables branching. Default 1. */
+    budget?: number;
+    /** Temperatures for each branch. Default spreads across [0, 1]. */
+    temperatures?: readonly number[];
+    /** Harvest options; the selector needs harvest to score samples. */
+    harvestOptions?: HarvestOptions;
+    /** Custom selector. Default: min uncertainties, tie-break shortest answer. */
+    selector?: BranchSelector;
+    /**
+     * Fires as each sample finishes (main call + harvest both complete).
+     * Useful for progress UI. Not awaited; exceptions are swallowed.
+     */
+    onSampleDone?: (sample: BranchSample) => void;
+}
+interface BranchResult {
+    chosen: BranchSample;
+    samples: BranchSample[];
+}
+/** Default: fewest uncertainties wins, ties broken by shorter answer content. */
+declare const defaultSelector: BranchSelector;
+declare function runBranches(client: DeepSeekClient, request: ChatRequestOptions, opts?: BranchOptions): Promise<BranchResult>;
+/** Sum usage across branch samples for telemetry purposes. */
+declare function aggregateBranchUsage(samples: readonly BranchSample[]): {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    promptCacheHitTokens: number;
+    promptCacheMissTokens: number;
+};
+
 interface ImmutablePrefixOptions {
     system: string;
     toolSpecs?: readonly ToolSpec[];
@@ -364,7 +416,20 @@ declare class ToolRegistry {
     dispatch(name: string, argumentsRaw: string | Record<string, unknown>): Promise<string>;
 }
 
-type EventRole = "assistant_delta" | "assistant_final" | "tool" | "done" | "error";
+type EventRole = "assistant_delta" | "assistant_final" | "tool" | "done" | "error" | "branch_start" | "branch_progress" | "branch_done";
+interface BranchSummary {
+    budget: number;
+    chosenIndex: number;
+    uncertainties: number[];
+    temperatures: number[];
+}
+interface BranchProgress {
+    completed: number;
+    total: number;
+    latestIndex: number;
+    latestTemperature: number;
+    latestUncertainties: number;
+}
 interface LoopEvent {
     turn: number;
     role: EventRole;
@@ -374,6 +439,8 @@ interface LoopEvent {
     stats?: TurnStats;
     planState?: TypedPlanState;
     repair?: RepairReport;
+    branch?: BranchSummary;
+    branchProgress?: BranchProgress;
     error?: string;
 }
 interface CacheFirstLoopOptions {
@@ -389,6 +456,19 @@ interface CacheFirstLoopOptions {
      * cheap but non-zero V3 call per turn).
      */
     harvest?: boolean | HarvestOptions;
+    /**
+     * Self-consistency branching. Pass a number for just a budget (e.g. 3) or
+     * a full `BranchOptions` object. Disables streaming for the branched turn
+     * because all samples must complete before selection. Auto-enables harvest
+     * since the default selector scores samples by plan-state uncertainty.
+     */
+    branch?: number | BranchOptions;
+    /**
+     * Session name. When set, the loop pre-loads the session's prior messages
+     * into its log on construction, and appends every new log entry to
+     * `~/.reasonix/sessions/<name>.jsonl` so the next run can resume.
+     */
+    session?: string;
 }
 /**
  * Pillar 1 — Cache-First Loop.
@@ -399,27 +479,79 @@ interface CacheFirstLoopOptions {
  *
  * Yields a stream of events so a TUI can render progressively.
  */
+interface ReconfigurableOptions {
+    model?: string;
+    harvest?: boolean | HarvestOptions;
+    branch?: number | BranchOptions;
+    stream?: boolean;
+}
 declare class CacheFirstLoop {
     readonly client: DeepSeekClient;
     readonly prefix: ImmutablePrefix;
     readonly tools: ToolRegistry;
-    readonly model: string;
     readonly maxToolIters: number;
-    readonly stream: boolean;
-    readonly harvestEnabled: boolean;
-    readonly harvestOptions: HarvestOptions;
     readonly log: AppendOnlyLog;
     readonly scratch: VolatileScratch;
     readonly stats: SessionStats;
     readonly repair: ToolCallRepair;
+    model: string;
+    stream: boolean;
+    harvestEnabled: boolean;
+    harvestOptions: HarvestOptions;
+    branchEnabled: boolean;
+    branchOptions: BranchOptions;
+    sessionName: string | null;
+    /** Number of messages that were pre-loaded from the session file. */
+    readonly resumedMessageCount: number;
     private _turn;
+    private _streamPreference;
     constructor(opts: CacheFirstLoopOptions);
+    private appendAndPersist;
+    /**
+     * Reconfigure model/harvest/branch/stream mid-session. The loop's log,
+     * scratch, and stats are preserved — only the per-turn behavior changes.
+     * Used by the TUI's slash commands and by library callers who want to
+     * flip a knob between turns.
+     */
+    configure(opts: ReconfigurableOptions): void;
     private buildMessages;
     step(userInput: string): AsyncGenerator<LoopEvent>;
     run(userInput: string, onEvent?: (ev: LoopEvent) => void): Promise<string>;
     private assistantMessage;
 }
 
+/**
+ * Session persistence.
+ *
+ * Every turn's log entries (user / assistant / tool messages) are appended to
+ * a JSONL file under `~/.reasonix/sessions/<name>.jsonl`. Next time the user
+ * starts the CLI with the same session name, the loop pre-loads the file
+ * into its AppendOnlyLog so the new turn has full prior context.
+ *
+ * Design notes:
+ *   - JSONL rather than JSON so concurrent writes don't corrupt.
+ *   - 0600 permissions on Unix (chmod no-ops on Windows).
+ *   - Name sanitization keeps paths safe: only [\w-] and CJK letters pass;
+ *     anything else is replaced with underscore, max 64 chars.
+ *   - The loop's stats/session aren't persisted — only the message log.
+ *     Cost accounting resets each run (by design — old costs are sunk).
+ */
+
+interface SessionInfo {
+    name: string;
+    path: string;
+    size: number;
+    messageCount: number;
+    mtime: Date;
+}
+declare function sessionsDir(): string;
+declare function sessionPath(name: string): string;
+declare function sanitizeName(name: string): string;
+declare function loadSessionMessages(name: string): ChatMessage[];
+declare function appendSessionMessage(name: string, message: ChatMessage): void;
+declare function listSessions(): SessionInfo[];
+declare function deleteSession(name: string): boolean;
+
 /**
  * Minimal `.env` loader; no dependency on dotenv.
  *
@@ -458,4 +590,4 @@ declare function redactKey(key: string): string;
 
 declare const VERSION = "0.0.1";
 
-export { AppendOnlyLog, CacheFirstLoop, type CacheFirstLoopOptions, type ChatMessage, type ChatResponse, DeepSeekClient, type DeepSeekClientOptions, type EventRole, type FlattenDecision, type HarvestOptions, ImmutablePrefix, type ImmutablePrefixOptions, type JSONSchema, type LoopEvent, type ReasonixConfig, type RepairReport, type RetryInfo, type RetryOptions, type Role, type ScavengeOptions, type ScavengeResult, SessionStats, type SessionSummary, StormBreaker, type StreamChunk, type ToolCall, ToolCallRepair, type ToolCallRepairOptions, type ToolDefinition, type ToolFunctionSpec, ToolRegistry, type ToolSpec, type TruncationRepairResult, type TurnStats, type TypedPlanState, Usage, VERSION, VolatileScratch, analyzeSchema, claudeEquivalentCost, costUsd, defaultConfigPath, emptyPlanState, fetchWithRetry, flattenSchema, harvest, isPlanStateEmpty, isPlausibleKey, loadApiKey, loadDotenv, nestArguments, readConfig, redactKey, repairTruncatedJson, saveApiKey, scavengeToolCalls, writeConfig };
+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 EventRole, type FlattenDecision, type HarvestOptions, ImmutablePrefix, type ImmutablePrefixOptions, type JSONSchema, type LoopEvent, type ReasonixConfig, type ReconfigurableOptions, type RepairReport, 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 TruncationRepairResult, type TurnStats, type TypedPlanState, Usage, VERSION, VolatileScratch, aggregateBranchUsage, analyzeSchema, appendSessionMessage, claudeEquivalentCost, costUsd, defaultConfigPath, defaultSelector, deleteSession, emptyPlanState, fetchWithRetry, flattenSchema, harvest, isPlanStateEmpty, isPlausibleKey, listSessions, loadApiKey, loadDotenv, loadSessionMessages, nestArguments, readConfig, redactKey, repairTruncatedJson, runBranches, sanitizeName as sanitizeSessionName, saveApiKey, scavengeToolCalls, sessionPath, sessionsDir, writeConfig };