@wrongstack/core 0.284.1 → 0.286.0

package/dist/execution/auto-compaction-middleware.d.ts

@@ -0,0 +1,123 @@
+import type { Context } from '../core/context.js';
+import type { EventBus } from '../kernel/events.js';
+import type { MiddlewareHandler } from '../kernel/pipeline.js';
+import type { SessionEventBridge } from '../storage/session-event-bridge.js';
+import type { Compactor } from '../types/compactor.js';
+import type { ContextWindowAggressiveOn, ContextWindowPolicy } from '../types/context-window.js';
+export interface ContextWindowBudgetSnapshot {
+    maxContext: number;
+    inputTokens: number;
+    availableInputTokens: number;
+    remainingInputTokens: number;
+    reservedOutputTokens: number;
+    reservedSafetyTokens: number;
+    load: number;
+    overflowTokens: number;
+}
+export type CompactionFailureMode = 'throw' | 'throw_on_hard' | 'continue';
+export interface AutoCompactionOptions {
+    aggressiveOn?: ContextWindowAggressiveOn | undefined;
+    events?: EventBus | undefined;
+    failureMode?: CompactionFailureMode | undefined;
+    policyProvider?: (ctx: Context) => Pick<ContextWindowPolicy, 'thresholds' | 'aggressiveOn'> | null | undefined;
+    /** Optional bridge for writing compaction events into the persistent session log. */
+    sessionBridge?: SessionEventBridge | undefined;
+}
+/**
+ * Pipeline middleware that monitors context token load and automatically
+ * triggers compaction when the warn/soft/hard thresholds are crossed.
+ * Runs before the next agent iteration.
+ *
+ * Uses `estimateRequestTokens` for accurate full-request token counting:
+ * messages + systemPrompt + toolDefs. This replaces the previous pattern
+ * of applying an OVERHEAD_FACTOR to a messages-only estimate.
+ */
+export declare class AutoCompactionMiddleware {
+    readonly name = "AutoCompaction";
+    private readonly compactor;
+    /** Deprecated. Kept for backward compat with tests that pass simpleEstimator. */
+    private readonly _estimator?;
+    private readonly warnThreshold;
+    private readonly softThreshold;
+    private readonly hardThreshold;
+    /** Writable so model-switch can update the denominator without re-registering the middleware. */
+    private _maxContext;
+    /**
+     * Runtime on/off gate. The middleware is always installed in the pipeline so
+     * auto-compaction can be toggled live from the TUI `/settings` picker; when
+     * disabled the handler is a pass-through. Defaults to enabled.
+     */
+    private _enabled;
+    private readonly aggressiveOn;
+    private readonly events?;
+    private readonly failureMode;
+    private readonly policyProvider?;
+    private readonly sessionBridge?;
+    /**
+     * Once a compaction attempt reduces nothing (preserveK protects everything,
+     * no oversized tool_results remain to elide), retrying on every iteration
+     * just spams `compaction.fired` events without making progress. We remember
+     * the no-op and skip until either the pressure level escalates or context
+     * has grown by at least this many tokens since the failed attempt.
+     */
+    private static readonly NOOP_RETRY_DELTA_TOKENS;
+    /** Tracks the most recent no-op attempt so we can avoid re-firing per turn. */
+    private lastNoopAttempt;
+    /**
+     * Cached token estimate from the last handler() invocation. When the
+     * message count and tool count haven't changed since the last estimate
+     * (autonomous idle loops), we skip the expensive O(n) token estimation
+     * and reuse this value. Reset to -1 when the context changes.
+     */
+    private _cachedTokens;
+    private _cachedMsgCount;
+    private _cachedToolCount;
+    /**
+     * @param compactor        Compactor to use for compaction.
+     * @param maxContext Provider's max context window in tokens.
+     * @param _estimator       Deprecated parameter kept for backward compatibility.
+     *                         The middleware now uses `estimateRequestTokens` internally
+     *                         for accurate full-request token counting (messages +
+     *                         systemPrompt + toolDefs).
+     * @param thresholds       Threshold fractions (0-1) of maxContext.
+     * @param opts             Optional behavior. By default, failures at the
+     *                         hard threshold throw AGENT_CONTEXT_OVERFLOW so
+     *                         the agent does not continue into a likely
+     *                         provider context overflow. Warn/soft failures
+     *                         still emit compaction.failed and continue.
+     */
+    constructor(compactor: Compactor, maxContext: number, _estimator: (ctx: Context) => number, thresholds: {
+        warn: number;
+        soft: number;
+        hard: number;
+    }, optsOrAggressiveOn?: AutoCompactionOptions | ContextWindowAggressiveOn, events?: EventBus | undefined);
+    /** Allow callers (e.g. model-switch in WebUI) to update the context window
+     *  denominator when the active model changes. */
+    setMaxContext(maxContext: number): void;
+    /** Whether auto-compaction is currently active. */
+    get enabled(): boolean;
+    /** Toggle auto-compaction on a live session (TUI `/settings`). When disabled
+     *  the middleware passes every iteration straight through without estimating
+     *  tokens or compacting. */
+    setEnabled(enabled: boolean): void;
+    handler(): MiddlewareHandler<Context>;
+    /**
+     * H1: try to read a pre-computed token total from `ctx.lastRequestTokens`
+     * (set by the agent loop's pre-flight or its restash in emitContextPct).
+     * Returns the uncalibrated total when the stash is valid for the current
+     * context shape (positive number, and the message count it was computed
+     * at matches the current one — otherwise tool results have been appended
+     * since and the value is stale). Returns null when missing or stale so
+     * the caller falls back to a fresh walk.
+     */
+    private tryStashedTokens;
+    /**
+     * Returns true when the previous compaction at the same or higher pressure
+     * level reduced nothing and context has not grown materially since. Prevents
+     * a stuck preserveK window from spamming compaction events every iteration.
+     */
+    private shouldSkipNoopRetry;
+    private recordAttempt;
+    private compact;
+}
+//# sourceMappingURL=auto-compaction-middleware.d.ts.map

package/dist/execution/auto-compaction-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-compaction-middleware.d.ts","sourceRoot":"","sources":["../../src/execution/auto-compaction-middleware.ts"],"names":[],"mappings":"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"}

package/dist/execution/autonomous-runner.d.ts

@@ -0,0 +1,61 @@
+import type { Agent, RunResult } from '../core/agent.js';
+import type { Context } from '../core/context.js';
+import type { Logger } from '../types/logger.js';
+import type { DoneCondition } from '../types/multi-agent.js';
+type AutonomousResult = RunResult & {
+    toolCalls: number;
+    reason?: string | undefined;
+};
+export interface DoneCheckResult {
+    done: boolean;
+    reason?: string | undefined;
+    iterations: number;
+    toolCalls: number;
+}
+export declare class DoneConditionChecker {
+    private readonly condition;
+    private readonly compiledRegex;
+    private readonly logger;
+    constructor(condition: DoneCondition, opts?: {
+        logger?: Logger | undefined;
+    });
+    check(state: {
+        iterations: number;
+        toolCalls: number;
+        lastOutput?: string | undefined;
+    }): DoneCheckResult;
+}
+export interface AutonomousRunnerOptions {
+    agent: Agent;
+    context: Context;
+    doneCondition: DoneCondition;
+    iterationTimeoutMs?: number | undefined;
+    onIteration?: (state: {
+        iteration: number | undefined;
+        toolCalls: number;
+    }) => void;
+    onDone?: (((result: AutonomousResult) => void)) | undefined;
+    /**
+     * When true and `doneCondition.type === 'directive'`, the runner
+     * runs the agent with `autonomousContinue: true` so the agent loop
+     * handles its own [continue]/[done] markers internally (no outer
+     * re-invocation needed). The runner still provides iteration/timeouts.
+     */
+    enableAutonomousContinue?: boolean | undefined;
+    /** Logger for structured warnings. Falls back to console.warn when omitted. */
+    logger?: Logger | undefined;
+}
+export declare class AutonomousRunner {
+    private readonly opts;
+    private iterations;
+    private toolCalls;
+    private lastOutput?;
+    private stopped;
+    private readonly doneChecker;
+    constructor(opts: AutonomousRunnerOptions);
+    run(): Promise<AutonomousResult>;
+    private runLoop;
+    stop(): void;
+}
+export {};
+//# sourceMappingURL=autonomous-runner.d.ts.map

package/dist/execution/autonomous-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autonomous-runner.d.ts","sourceRoot":"","sources":["../../src/execution/autonomous-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAI7D,KAAK,gBAAgB,GAAG,SAAS,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEvF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,oBAAoB;IAK7B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAE5C,YACmB,SAAS,EAAE,aAAa,EACzC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,EA0BvC;IAED,KAAK,CAAC,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG,eAAe,CA0DxG;CACF;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,aAAa,CAAC;IAC7B,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACpF,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;IAC5D;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/C,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,qBAAa,gBAAgB;IAOf,OAAO,CAAC,QAAQ,CAAC,IAAI;IANjC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,UAAU,CAAC,CAAqB;IACxC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuB;IAEnD,YAA6B,IAAI,EAAE,uBAAuB,EAEzD;IAEK,GAAG,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAgCrC;YAEa,OAAO;IA6GrB,IAAI,IAAI,IAAI,CAEX;CACF"}

package/dist/execution/autonomy-brain.d.ts

@@ -0,0 +1,151 @@
+/**
+ * AutonomyBrain — a self-driving decision layer for autonomous workflows.
+ *
+ * Unlike the standard BrainArbiter which asks the human when uncertain,
+ * AutonomyBrain makes decisions autonomously within configured risk
+ * boundaries, keeping the system running unattended. It uses the session
+ * LLM to evaluate situations and produce decisions.
+ *
+ * ## Identity
+ * The AutonomyBrain is NOT the main agent. It is a dedicated decision
+ * engine with a single purpose: evaluate blocked/stuck situations in
+ * autonomous workflows and decide whether to continue, pivot, or stop.
+ *
+ * ## Decision Flow
+ * 1. RISK GATE — if request risk > maxAutoRisk, auto-deny
+ * 2. HEURISTIC — fast pattern-match for common situations (deadlock, retry-exhausted)
+ * 3. LLM EVALUATION — complex decisions (goal completion, conflict resolution)
+ *
+ * ## Decision Logging
+ * Every decision is emitted via `onDecision` callback with a human-readable
+ * summary suitable for chat history and journal entries.
+ *
+ * Usage:
+ *   const brain = createAutonomyBrain({
+ *     provider, model, maxAutoRisk: 'high',
+ *     onDecision: (summary) => journal.push(summary),
+ *   });
+ */
+import type { Provider } from '../types/provider.js';
+import type { BrainArbiter, BrainDecision, BrainDecisionRequest } from '../coordination/brain.js';
+/** One (provider, model) pair the Brain may call for a decision. */
+export interface BrainLlmTarget {
+    provider: Provider;
+    model: string;
+    /** Display label for logs/status (e.g. "anthropic/claude-haiku"). */
+    label?: string | undefined;
+}
+export interface AutonomyBrainOptions {
+    /** LLM provider for decision-making. Ignored when `targets` is non-empty. */
+    provider?: Provider | undefined;
+    /** Model to use for decisions (should be fast + cheap). Ignored when `targets` is non-empty. */
+    model?: string | undefined;
+    /**
+     * Ordered LLM pool. With `strategy: 'fallback'` (default) the first target
+     * is primary and later ones are tried in order when a call fails/times
+     * out; with 'round-robin' successive decisions rotate the starting target.
+     * At least one of `targets` / (`provider` + `model`) must be provided.
+     */
+    targets?: BrainLlmTarget[] | undefined;
+    /** Pool selection strategy. Default 'fallback'. */
+    strategy?: 'fallback' | 'round-robin' | undefined;
+    /** Maximum risk level the brain will auto-decide. Default: 'high'.
+     *  'low'    — only auto-decide low-risk questions
+     *  'medium' — auto-decide low/medium
+     *  'high'   — auto-decide low/medium/high
+     *  'all'    — auto-decide everything (including critical)
+     */
+    maxAutoRisk?: 'low' | 'medium' | 'high' | 'all' | undefined;
+    /** Timeout for each decision call (ms). Default: 15_000. */
+    decisionTimeoutMs?: number | undefined;
+    /**
+     * Decision-history digest for the LLM prompt (typically
+     * `BrainDecisionLedger.digestFor`): how similar past decisions went and
+     * how they turned out. Appended to the user message when non-empty.
+     */
+    getDecisionDigest?: ((request: BrainDecisionRequest) => string | undefined) | undefined;
+    /**
+     * Called after every decision with a human-readable summary.
+     * Use this to log decisions into chat history, journal, or status line.
+     * Example: "🧠 Brain: skipped deadlocked tasks → continuing with phase 3/5"
+     */
+    onDecision?: ((summary: string, decision: BrainDecision, request: BrainDecisionRequest) => void) | undefined;
+}
+/** Runtime-adjustable autonomy ceiling for the tiered brain. */
+export type BrainAutoRisk = 'off' | 'low' | 'medium' | 'high' | 'all';
+export interface TieredBrainArbiterOptions {
+    /** Fast deterministic policy layer (DefaultBrainArbiter). Consulted first. */
+    policy: BrainArbiter;
+    /** LLM-backed autonomous layer (createAutonomyBrain). Consulted when the
+     *  policy layer would escalate to the human and the request's risk is
+     *  within the live ceiling. */
+    autonomous?: BrainArbiter | undefined;
+    /**
+     * Live autonomy ceiling — read on EVERY decision so `/brain risk <level>`
+     * changes take effect immediately. 'off' disables the autonomous layer
+     * entirely (everything the policy can't answer goes to the human).
+     */
+    getMaxAutoRisk?: (() => BrainAutoRisk) | undefined;
+    /**
+     * Multi-LLM council (createCouncilBrainArbiter). When present, requests at
+     * or above the council risk floor are decided by the council INSTEAD of
+     * the single-LLM layer. Council answers AND denies are terminal — a panel
+     * that considered the question and refused is a real decision, not a
+     * failure. Only `ask_human` (quorum not met / judge unavailable) falls
+     * through to the escalation tier.
+     */
+    council?: BrainArbiter | undefined;
+    /** Live council risk floor. Default 'high'. Read on every decision. */
+    getCouncilMinRisk?: (() => 'medium' | 'high' | 'critical') | undefined;
+}
+/**
+ * The standard Brain positioning: policy first, LLM/council second,
+ * escalation last.
+ *
+ *   1. POLICY  — deterministic DefaultBrainArbiter (low-risk fast path,
+ *      fallback semantics). Denies and option-backed answers pass through
+ *      untouched. A fallback-produced `continue` answer (no optionId, the
+ *      request declared `fallback: 'continue'`) is only PROVISIONAL: it
+ *      means "nobody could decide", not "this is the right call", so the
+ *      LLM tier still gets consulted within the ceiling. Historically it
+ *      short-circuited here, which meant e.g. goal-completion checks never
+ *      reached the LLM at all.
+ *   2. COUNCIL — requests at/above the council floor (default 'high') are
+ *      decided by the multi-LLM council when one is wired.
+ *   3. LLM     — everything else within the live ceiling goes to the
+ *      single-LLM autonomous brain. Only a real `answer` short-circuits;
+ *      denials/failures fall through.
+ *   4. ESCALATION — anything left escalates. Callers wrap this in
+ *      `EscalationRoutingBrainArbiter` (interactive prompt or headless
+ *      terminal policy) or the legacy `HumanEscalatingBrainArbiter`.
+ */
+export declare function createTieredBrainArbiter(opts: TieredBrainArbiterOptions): BrainArbiter;
+/**
+ * Create a self-driving brain that makes autonomous decisions.
+ * Never asks the human — within its risk boundary it answers, above it denies.
+ */
+export declare function createAutonomyBrain(opts: AutonomyBrainOptions): BrainArbiter;
+/**
+ * Format a decision as a human-readable one-liner for chat history.
+ */
+export declare function formatDecisionSummary(decision: BrainDecision, request: BrainDecisionRequest): string;
+/**
+ * Render a decision request as the user message for a Brain LLM call.
+ * Shared by the single-LLM tier and every council voter so all of them see
+ * the same question/context/options shape.
+ */
+export declare function buildBrainUserMessage(request: BrainDecisionRequest): string;
+/** Append a decision-history digest to a Brain user message (shared shape). */
+export declare function withDecisionDigest(user: string, digest: string | undefined): string;
+/**
+ * One Brain LLM call against a single target. Throws on transport failure,
+ * timeout, or abort — callers own the pool/fallback semantics.
+ */
+export declare function completeBrainLlm(target: BrainLlmTarget, input: {
+    system: string;
+    user: string;
+    timeoutMs: number;
+    maxTokens?: number | undefined;
+}): Promise<string>;
+export declare function parseOptionDecision(rawText: string, options: NonNullable<BrainDecisionRequest['options']>): BrainDecision | null;
+//# sourceMappingURL=autonomy-brain.d.ts.map

package/dist/execution/autonomy-brain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autonomy-brain.d.ts","sourceRoot":"","sources":["../../src/execution/autonomy-brain.ts"],"names":[],"mappings":"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"}

package/dist/execution/autonomy-prompt-contributor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * System-prompt contributor that surfaces eternal-autonomy state to the
+ * model on every turn.
+ *
+ * Why this exists: when the engine drives a long-running loop, the
+ * per-iteration directive carries the rules. But the directive is a USER
+ * message — it scrolls out of working memory after a few compactions and
+ * the model forgets it's in autonomy mode (forgets `[GOAL_COMPLETE]`,
+ * forgets the todo-state protocol, forgets the no-confirmation rule).
+ * Injecting the same anchor as a CACHED system-prompt block solves that
+ * — the rules sit next to the identity layer and survive compactions.
+ *
+ * Block is tagged `ephemeral` so its content (journal tail, iteration
+ * counter) changes each turn without invalidating the upstream prefix
+ * cache.
+ */
+import type { SystemPromptContributor } from '../types/system-prompt-contributor.js';
+export interface AutonomyPromptContributorOptions {
+    /** Absolute path to the project's `goal.json`. */
+    goalPath: string;
+    /**
+     * Gating function. The contributor consults this on every build and
+     * returns an empty array when `false` — without this, the block would
+     * leak into interactive runs that happen to have a goal on disk and
+     * teach the model loop-control markers it shouldn't emit.
+     *
+     * Typical wiring: enable while `eternal` or `eternal-parallel` autonomy is active.
+     */
+    enabled: () => boolean;
+    /** Number of journal entries to include in the recent-tail block. Default 5. */
+    journalTailSize?: number | undefined;
+}
+/**
+ * Build a contributor that renders the autonomy-state system block.
+ * Returns `[]` when disabled, no goal exists, or the goal has been
+ * completed/abandoned — all silent fast-paths.
+ */
+export declare function makeAutonomyPromptContributor(opts: AutonomyPromptContributorOptions): SystemPromptContributor;
+//# sourceMappingURL=autonomy-prompt-contributor.d.ts.map

package/dist/execution/autonomy-prompt-contributor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autonomy-prompt-contributor.d.ts","sourceRoot":"","sources":["../../src/execution/autonomy-prompt-contributor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AAOrF,MAAM,WAAW,gCAAgC;IAC/C,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,gFAAgF;IAChF,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,gCAAgC,GACrC,uBAAuB,CA+CzB"}

package/dist/execution/brain-chain.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Brain tier assembly — turns `Config.brain` into the concrete LLM tiers
+ * (single-LLM pool + optional multi-LLM council) that
+ * `createTieredBrainArbiter` composes. Shared by every host that wires a
+ * Brain (CLI/TUI in `wiring/brain-and-orchestration.ts`, the standalone
+ * WebUI server in `backend-services.ts`) so the config surface behaves
+ * identically everywhere.
+ *
+ * Hosts differ only in HOW a provider id becomes a `Provider` instance, so
+ * that is the one injected dependency (`resolveProvider`). Unresolvable
+ * pool/council entries are skipped — one bad ref never takes the Brain down.
+ *
+ * @module brain-chain
+ */
+import type { BrainArbiter, BrainDecisionRequest } from '../coordination/brain.js';
+import type { BrainConfig } from '../types/config.js';
+import type { Provider } from '../types/provider.js';
+export interface BrainTierAssemblyOptions {
+    /** `config.brain` — undefined assembles the legacy session-model single tier. */
+    brainConfig: BrainConfig | undefined;
+    /** The session's provider id (`config.provider`). */
+    defaultProviderId: string;
+    /** Live session provider — read per decision so `/setmodel` switches apply. */
+    sessionProvider: () => Provider;
+    /** Live session model id — read per decision. */
+    sessionModel: () => string;
+    /**
+     * Resolve a NON-default provider id to a Provider instance. May throw or
+     * return null; the entry is then skipped.
+     */
+    resolveProvider: (providerId: string, model: string) => Provider | null;
+    /**
+     * Decision-history digest (typically `BrainDecisionLedger.digestFor`) —
+     * injected into both the single-LLM and council prompts so the Brain
+     * learns from the outcomes of its past similar decisions.
+     */
+    getDecisionDigest?: ((request: BrainDecisionRequest) => string | undefined) | undefined;
+}
+export interface BrainTierAssembly {
+    /** Single-LLM tier for `TieredBrainArbiterOptions.autonomous`. */
+    autonomous: BrainArbiter;
+    /** Council tier for `TieredBrainArbiterOptions.council` (undefined = disabled). */
+    council: BrainArbiter | undefined;
+    /** Live council risk floor for `TieredBrainArbiterOptions.getCouncilMinRisk`. */
+    getCouncilMinRisk: () => 'medium' | 'high' | 'critical';
+    /** Human-readable pool labels for status surfaces; empty = session model. */
+    poolLabels: string[];
+    /** Human-readable council seat labels; empty = council disabled. */
+    councilLabels: string[];
+}
+/** Assemble the LLM tiers of the Brain chain from `Config.brain`. */
+export declare function assembleBrainTiers(opts: BrainTierAssemblyOptions): BrainTierAssembly;
+//# sourceMappingURL=brain-chain.d.ts.map

package/dist/execution/brain-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-chain.d.ts","sourceRoot":"","sources":["../../src/execution/brain-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEnF,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AACvE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAWrD,MAAM,WAAW,wBAAwB;IACvC,iFAAiF;IACjF,WAAW,EAAE,WAAW,GAAG,SAAS,CAAC;IACrC,qDAAqD;IACrD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,eAAe,EAAE,MAAM,QAAQ,CAAC;IAChC,iDAAiD;IACjD,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B;;;OAGG;IACH,eAAe,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,QAAQ,GAAG,IAAI,CAAC;IACxE;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,oBAAoB,KAAK,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;CACzF;AAED,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,UAAU,EAAE,YAAY,CAAC;IACzB,mFAAmF;IACnF,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;IAClC,iFAAiF;IACjF,iBAAiB,EAAE,MAAM,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IACxD,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,oEAAoE;IACpE,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,wBAAwB,GAAG,iBAAiB,CAqGpF"}

package/dist/execution/brain-evaluation.d.ts

@@ -0,0 +1,66 @@
+import type { BrainArbiter, BrainDecision, BrainDecisionRequest } from '../coordination/brain.js';
+export declare const BRAIN_EVALUATION_CASE_VERSION: 1;
+export interface BrainEvaluationExpectations {
+    /** Restrict the accepted decision variants for this case. */
+    allowedDecisionTypes?: BrainDecision['type'][] | undefined;
+    /** Exact option ids that may be selected. Every id must exist in the request. */
+    allowedOptionIds?: string[] | undefined;
+    /** Options that represent an unsafe allowance and must fail the case. */
+    unsafeOptionIds?: string[] | undefined;
+    /** Require an answer to carry an exact option id. */
+    requireOptionId?: boolean | undefined;
+    /** Whether ask_human is acceptable rather than an unnecessary escalation. */
+    allowEscalation?: boolean | undefined;
+}
+/** Versioned, JSON-serializable fixture for side-effect-free Brain evaluation. */
+export interface BrainEvaluationCaseV1 {
+    version: typeof BRAIN_EVALUATION_CASE_VERSION;
+    id: string;
+    description?: string | undefined;
+    request: BrainDecisionRequest;
+    expectations?: BrainEvaluationExpectations | undefined;
+}
+export type BrainEvaluationFailureCode = 'invalid_fixture' | 'arbiter_error' | 'unexpected_decision_type' | 'invalid_option_id' | 'missing_option_id' | 'disallowed_option_id' | 'unsafe_option_id' | 'unexpected_escalation';
+export interface BrainEvaluationFailure {
+    code: BrainEvaluationFailureCode;
+    message: string;
+}
+export interface BrainEvaluationCaseResult {
+    caseId: string;
+    passed: boolean;
+    decision?: BrainDecision | undefined;
+    failures: BrainEvaluationFailure[];
+    latencyMs: number;
+}
+export interface BrainEvaluationMetrics {
+    totalCases: number;
+    passedCases: number;
+    failedCases: number;
+    optionDecisionCount: number;
+    invalidOptionCount: number;
+    validOptionRate: number;
+    unsafeAllowanceCount: number;
+    unnecessaryEscalationCount: number;
+    averageLatencyMs: number;
+}
+export interface BrainEvaluationReport {
+    version: typeof BRAIN_EVALUATION_CASE_VERSION;
+    results: BrainEvaluationCaseResult[];
+    metrics: BrainEvaluationMetrics;
+}
+export type BrainEvaluationCaseValidation = {
+    ok: true;
+    value: BrainEvaluationCaseV1;
+} | {
+    ok: false;
+    diagnostics: string[];
+};
+/** Validate a fixture loaded from JSON before any arbiter is invoked. */
+export declare function validateBrainEvaluationCase(value: unknown): BrainEvaluationCaseValidation;
+/**
+ * Replay evaluation fixtures through a Brain arbiter without applying the
+ * returned decisions. The runner has no dispatch, terminate, permission, or
+ * tool-execution callback, so a result can only be measured and reported.
+ */
+export declare function runBrainEvaluation(arbiter: BrainArbiter, cases: readonly unknown[]): Promise<BrainEvaluationReport>;
+//# sourceMappingURL=brain-evaluation.d.ts.map

package/dist/execution/brain-evaluation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-evaluation.d.ts","sourceRoot":"","sources":["../../src/execution/brain-evaluation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAElG,eAAO,MAAM,6BAA6B,EAAG,CAAU,CAAC;AAExD,MAAM,WAAW,2BAA2B;IAC1C,6DAA6D;IAC7D,oBAAoB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,GAAG,SAAS,CAAC;IAC3D,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACxC,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACvC,qDAAqD;IACrD,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,6EAA6E;IAC7E,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACvC;AAED,kFAAkF;AAClF,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,6BAA6B,CAAC;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,YAAY,CAAC,EAAE,2BAA2B,GAAG,SAAS,CAAC;CACxD;AAED,MAAM,MAAM,0BAA0B,GAClC,iBAAiB,GACjB,eAAe,GACf,0BAA0B,GAC1B,mBAAmB,GACnB,mBAAmB,GACnB,sBAAsB,GACtB,kBAAkB,GAClB,uBAAuB,CAAC;AAE5B,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,0BAA0B,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACrC,QAAQ,EAAE,sBAAsB,EAAE,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,0BAA0B,EAAE,MAAM,CAAC;IACnC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,6BAA6B,CAAC;IAC9C,OAAO,EAAE,yBAAyB,EAAE,CAAC;IACrC,OAAO,EAAE,sBAAsB,CAAC;CACjC;AAED,MAAM,MAAM,6BAA6B,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,GAC1C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAUzC,yEAAyE;AACzE,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,6BAA6B,CAsGzF;AA4DD;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,SAAS,OAAO,EAAE,GACxB,OAAO,CAAC,qBAAqB,CAAC,CA0FhC"}