@quantiya/codevibe-core 1.0.23 → 2.0.1

package/dist/orchestration-shell/non-tty-fallback.d.ts

@@ -0,0 +1,46 @@
+import { OrchestrationStore } from './store';
+import { ConversationEntry } from './types';
+export interface RunLineLogFallbackArgs {
+    store: OrchestrationStore;
+    /** CP-1.b PlannerAdapter; CP-1.a passes a stub or `undefined`. */
+    plannerClient?: unknown;
+    /** CP-1.b cache layer; CP-1.a passes a stub or `undefined`. */
+    cacheLayer?: unknown;
+    /** CP-1.b health machine; CP-1.a passes a stub or `undefined`. */
+    healthMachine?: unknown;
+    /** CP-1.c executor; CP-1.a passes a stub or `undefined`. */
+    executor?: unknown;
+    /** Optional override for input — defaults to `process.stdin`. */
+    input?: NodeJS.ReadableStream;
+    /** Optional override for output — defaults to `process.stdout`. */
+    output?: NodeJS.WritableStream;
+    /** Optional onUserInput handler (host wires this to the slash router / planner classifier). */
+    onUserInput?: (text: string) => Promise<void> | void;
+    /**
+     * CP-1.b IMPL r4 H-3 — Optional abort signal so the surrounding
+     * shell can break the readline loop on SIGINT/SIGTERM. Aborting
+     * triggers a clean rl.close() so the awaiting promise resolves.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Renders a single `ConversationEntry` as a line-prefixed text string.
+ * Strict text only — no ANSI escapes, no colors, no `\r` rewrites.
+ */
+export declare function renderEntryAsLine(entry: ConversationEntry): string;
+/**
+ * Subscribes to the store and prints new conversation entries as
+ * line-prefixed text. Returns a promise that resolves on `EXIT` action
+ * (currently inferred by the store-state being a re-emission of the
+ * same state object after `EXIT` dispatch — the runner uses an
+ * `exitRequested` flag toggled by an external dispatch wrapper).
+ *
+ * CP-1.a ships the basic line-log + stdin readline loop; CP-1.b/c
+ * additional knobs (plannerClient, cacheLayer, executor) are accepted
+ * as optional args but ignored. The runner exits on:
+ *   - The host's onUserInput throwing (propagated).
+ *   - stdin closing (EOF).
+ *   - `/quit` slash command (the host detects via the SLASH_OUTPUT
+ *     action's sideEffect — the host wires `exitRequested` here).
+ */
+export declare function runLineLogFallback(args: RunLineLogFallbackArgs): Promise<void>;

package/dist/orchestration-shell/process-markers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The three baseline markers every subprocess inherits. `CODEVIBE_PROCESS_ROLE`
+ * defaults to `'implementor'`; per-subprocess role overrides via
+ * `withRoleMarker()`.
+ */
+export declare function processMarkers(): Record<string, string>;
+/**
+ * Returns `base` with `CODEVIBE_PROCESS_ROLE` overridden to `role`.
+ * CP-1.c will call this per-spawn (e.g., reviewer spawns set role to
+ * `'reviewer'`; planner-health probes to `'health_probe'`).
+ */
+export declare function withRoleMarker(base: Record<string, string>, role: 'implementor' | 'reviewer' | 'health_probe' | 'auth_probe' | 'model_probe'): Record<string, string>;

package/dist/orchestration-shell/reducer.d.ts

@@ -0,0 +1,8 @@
+import { OrchestrationAction, OrchestrationState } from './types';
+/** Max conversation-buffer size per §5.1 line 469 ("bounded ring buffer (last 500 entries)"). */
+export declare const CONVERSATION_BUFFER_MAX = 500;
+/**
+ * Pure reducer. Returns a NEW state object on every dispatch — never
+ * mutates `state` in place. Map fields are cloned via `new Map(state.x)`.
+ */
+export declare function reducer(state: OrchestrationState, action: OrchestrationAction): OrchestrationState;

package/dist/orchestration-shell/slash-router.d.ts

@@ -0,0 +1,45 @@
+import { OrchestrationAction } from './types';
+/**
+ * Side effects a handler can request the entrypoint to dispatch.
+ * The router itself never touches the store — keeps slash handling
+ * pure for unit testing.
+ *
+ * Widened to a 3-arm union by CP-1.d per `PHASE-CP-1-D-DESIGN.md` §4.8
+ * (lines 1060-1066). `[ADDITIVE WIDENING — CP-1.d]` — the §16 LOCK #10
+ * slash-command CATALOG (names + ownership patterns) is unchanged; the
+ * internal side-effect kind is implementation detail of the orchestration
+ * shell and never crosses the AppSync boundary.
+ */
+export type ShellAction = {
+    kind: 'EXIT';
+} | {
+    kind: 'REGENERATE_STRUCTURAL_SUMMARY';
+} | {
+    kind: 'OPT_IN_BODY_PATH';
+    path: string;
+};
+export interface SlashOutput {
+    /** Verbatim user input (including leading `/`). Echoed in the conversation entry. */
+    command: string;
+    /** Rendered text shown inline in `<ConversationPane>` (per §11). */
+    output: string;
+    /** Optional side effect; only `/quit` populates it in CP-1.a. */
+    sideEffect?: ShellAction;
+}
+/**
+ * §16 LOCK #10 + §5.1.5 + §11 row. Routes user input that starts with
+ * `/`. Per §17 Q3 RESOLVED disposition: EXACT-MATCH only. Unknown
+ * commands return a help hint.
+ */
+export declare function routeSlashCommand(input: string): SlashOutput;
+/**
+ * Convenience helper for callers that wire the side effect directly
+ * into the store. CP-1.a's `cli.ts` uses this; CP-1.b/c may dispatch
+ * the resulting `slash-output` action plus the side effect.
+ */
+export declare function applySlashOutput(output: SlashOutput): {
+    storeAction: Extract<OrchestrationAction, {
+        type: 'SLASH_OUTPUT';
+    }>;
+    exit: boolean;
+};

package/dist/orchestration-shell/sticky-preference.d.ts

@@ -0,0 +1,24 @@
+import { Mode, Tier } from './types';
+/**
+ * Filesystem location of the sticky preference file.
+ */
+export declare function stickyPreferenceFilePath(): string;
+/**
+ * §2 LOCK lines 103-116. Reads the sticky preference. Returns `null`
+ * on every failure mode the design names:
+ *   - file missing
+ *   - malformed JSON
+ *   - schema-version mismatch
+ *   - `pickedByTier === 'PRO'` but current tier is now `FREE`
+ *     (tier downgrade INVALIDATES the sticky)
+ */
+export declare function readStickyPreference(currentTier?: Tier): Promise<Mode | null>;
+/**
+ * Writes the sticky preference. Creates the parent directory if
+ * missing. Used by the orchestration-mode entrypoint after a user
+ * picks a mode via the interactive prompt.
+ */
+export declare function writeStickyPreference(args: {
+    mode: Mode;
+    pickedByTier: 'PRO' | 'MAX';
+}): Promise<void>;

package/dist/orchestration-shell/store.d.ts

@@ -0,0 +1,17 @@
+import { Session } from '../types';
+import { OrchestrationAction, OrchestrationState } from './types';
+export interface OrchestrationStore {
+    getState(): OrchestrationState;
+    dispatch(action: OrchestrationAction): void;
+    /**
+     * Subscribe to state changes. Returns an unsubscribe fn. The
+     * listener fires AFTER each dispatch with the new state.
+     */
+    subscribe(listener: (state: OrchestrationState) => void): () => void;
+}
+export interface CreateOrchestrationStoreArgs {
+    session: Session;
+    /** Optional initial state override for tests. */
+    initial?: Partial<OrchestrationState>;
+}
+export declare function createOrchestrationStore(args: CreateOrchestrationStoreArgs): OrchestrationStore;

package/dist/orchestration-shell/types.d.ts

@@ -0,0 +1,417 @@
+import { Session } from '../types/session';
+import type { StructuralSummary } from '../structural-summary/types';
+import type { GatePromptEnvelope } from './gate-prompts';
+/**
+ * Engine's reply to `applyUserDecision`. Surfaced by the SDK as
+ * `Promise<PostDecisionAction>`. Discriminated by `kind`; payload
+ * fields are snake_case to match the SDK's wire-form parse.
+ */
+export type PostDecisionAction = {
+    kind: 'terminate_gate';
+    notes: string | null;
+} | {
+    kind: 'open_new_round';
+    next_round: number;
+    user_notes: string;
+} | {
+    kind: 'restart_proposal';
+} | {
+    kind: 'abort_task';
+};
+/**
+ * CP-1.a §2 LOCK. The literal union used for sticky-preference, mode
+ * selection, and the `MODE_SELECTED` EventType `metadata.mode` field.
+ */
+export type Mode = 'companion' | 'orchestration';
+/**
+ * Structural stub matching the design §6 5-action schema. CP-1.b
+ * replaces this with the real `PlannerDecision` from
+ * `codevibe-core/src/planner/adapter.ts`. CP-1.a only needs the
+ * SHAPE — never inspects field semantics beyond what `OrchestrationAction`
+ * consumes.
+ *
+ * Per §6 line 958-965: discriminated by `action`; `clarifying_question`
+ * present only when action === 'ask_user'; `advisory_summary` only
+ * when action === 'advisory_response'; `gateRequest` opaque per §6
+ * line 967-972 (CP-2 Stage A finalises shape).
+ */
+export interface PlannerDecision {
+    action: 'start_task' | 'summarize_current_status' | 'advisory_response' | 'ask_user' | 'refuse';
+    rationale: string;
+    clarifying_question?: string;
+    advisory_summary?: string;
+    /**
+     * Opaque per §6 line 967-972; CP-1 NEVER inspects fields. CP-2 Stage A
+     * locks shape.
+     */
+    gateRequest?: Record<string, unknown>;
+}
+export type AgentKind = 'CLAUDE' | 'GEMINI' | 'CODEX';
+/**
+ * Health-state surface from §8. CP-1.a stores this in
+ * `OrchestrationState.plannerHealth`; CP-1.b's state machine drives
+ * the transitions.
+ */
+export type PlannerHealthState = 'Available' | 'Degraded' | 'Outage';
+/**
+ * §5.1 store-shape LOCK (lines 537-545). Implementor subprocess
+ * lifecycle from spawn to clean exit.
+ */
+export interface RunningTaskState {
+    taskId: string;
+    agentKind: AgentKind;
+    pid: number;
+    startedAt: string;
+    status: 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed';
+    exitCode?: number;
+    bypassReason?: 'deterministic_shortcut' | 'planner_outage' | 'planner_degraded_explicit_override';
+}
+/**
+ * §5.1 LOCK (lines 547-556). Single reviewer subprocess identity +
+ * verdict. `reviewerKind` is hand-listed per CP-1 — CP-3 Stage A
+ * widens to the full reviewer-registry per `[DEFERRED TECH DEBT — CP-3]`
+ * note at design line 774.
+ */
+export interface ReviewerSeatState {
+    seatId: string;
+    reviewerKind: 'codex' | 'gemini' | 'claude';
+    status: 'queued' | 'running' | 'PASS' | 'REVISE' | 'BLOCK';
+    startedAt?: string;
+    elapsedMs?: number;
+    findingCount?: number;
+    verdictDigest?: string;
+}
+/**
+ * §5.1 LOCK (lines 558-569). Per-gate aggregate over reviewer-quorum +
+ * auto-revise round count. `autoReviseCap: 2 | 6` literal-union prevents
+ * accidental drift in implementor code per CP-0 §6 line 155 (Pro = 2,
+ * Max = 6).
+ */
+export interface GateState {
+    gateId: string;
+    taskId: string;
+    gateKind: 'code-review' | 'merge-gate' | 'continuation-handoff';
+    quorumRequired: number;
+    quorumAchieved: number;
+    autoReviseRound: number;
+    autoReviseCap: 2 | 6;
+    status: 'pending' | 'in_review' | 'PASS' | 'REVISE' | 'BLOCK' | 'merge_gate_pending';
+    finalizedAt?: string;
+}
+/**
+ * §5.1 LOCK lines 576-583. LE-originated Class A `EXECUTION_EVENT`
+ * messageType payloads. Five sub-kinds per CP-0 §2.4 verbatim.
+ */
+export interface ExecutionEventEntry {
+    eventId: string;
+    timestamp: string;
+    kind: 'PROCESS_SPAWNED' | 'FILE_CHANGE' | 'TOOL_USE' | 'VERIFICATION_RUN' | 'PROCESS_EXITED';
+    parentTaskId: string;
+    authorRole: 'implementor' | 'reviewer' | 'shell';
+    payload: Record<string, unknown>;
+}
+/**
+ * §5.1 LOCK lines 591-613. Separate Class A `EXECUTOR_REFUSAL`
+ * messageType per CP-0 §2.3 + §2.4. NOT an EXECUTION_EVENT sub-kind.
+ */
+export interface RefusalEventEntry {
+    eventId: string;
+    timestamp: string;
+    kind: 'EXECUTOR_REFUSAL';
+    parentTaskId: string;
+    authorRole: 'shell';
+    payload: {
+        refusedMessageId: string;
+        refusalCategory: 'authority_scope_conflict' | 'local_permission_denied' | 'signature_invalid' | 'ulid_replay' | 'auth_revoked_local' | 'transport_authority_mismatch';
+        refusalDetail: string;
+        recommendedRecovery: 'reauthorize_locally' | 'abort_task' | 'ask_user' | 'retry_after_resync';
+    };
+}
+/**
+ * §5.1 LOCK lines 621-628. CP-1 placeholder; payload shape is
+ * `[DEFERRED TECH DEBT — CP-2]` per design.
+ */
+export interface BypassEventEntry {
+    eventId: string;
+    timestamp: string;
+    kind: 'TASK_BYPASS';
+    parentTaskId: string;
+    authorRole: 'shell';
+    payload: {
+        bypassReason: string;
+    };
+}
+/**
+ * §5.1 LOCK lines 635-642. Mobile-replay EventType values that flow
+ * into the store without going through the Class A wire. `parentTaskId`
+ * is nullable per Stage 2 r3 Gemini M1 — `NOTIFICATION` events may be
+ * session-scope.
+ */
+export interface MobileEventEntry {
+    eventId: string;
+    timestamp: string;
+    kind: 'USER_PROMPT' | 'ASSISTANT_RESPONSE' | 'INTERACTIVE_PROMPT' | 'NOTIFICATION';
+    parentTaskId: string | null;
+    source: 'DESKTOP' | 'MOBILE';
+    payload: Record<string, unknown>;
+}
+/**
+ * §5.1 LOCK line 646. Discriminated union used inside
+ * `ConversationEntry.subagent-event`.
+ */
+export type EventStreamEntry = ExecutionEventEntry | RefusalEventEntry | BypassEventEntry | MobileEventEntry;
+/**
+ * §5.1 LOCK lines 527-534. Discriminated union; every entry carries
+ * `final: boolean`. Non-final entries re-render in place; final entries
+ * freeze in scrollback (migrate from `<ConversationPane>` into `<Static>`
+ * per design line 441-447).
+ */
+export type ConversationEntry = {
+    kind: 'user-message';
+    id: string;
+    timestamp: string;
+    final: true;
+    text: string;
+} | {
+    kind: 'planner-decision';
+    id: string;
+    timestamp: string;
+    final: true;
+    action: PlannerDecision['action'];
+    rationale: string;
+    taskId?: string;
+} | {
+    kind: 'subagent-event';
+    id: string;
+    timestamp: string;
+    final: true;
+    parentTaskId: string;
+    role: 'implementor' | 'reviewer';
+    event: EventStreamEntry;
+} | {
+    kind: 'reviewer-status-node';
+    id: string;
+    timestamp: string;
+    final: boolean;
+    taskId: string;
+    seats: ReviewerSeatState[];
+    quorumStatus: 'queued' | 'running' | 'PASS' | 'REVISE' | 'BLOCK';
+} | {
+    kind: 'gate-status-node';
+    id: string;
+    timestamp: string;
+    final: boolean;
+    taskId: string;
+    gate: GateState;
+} | {
+    kind: 'slash-output';
+    id: string;
+    timestamp: string;
+    final: true;
+    command: string;
+    output: string;
+} | {
+    kind: 'advisory';
+    id: string;
+    timestamp: string;
+    final: true;
+    source: 'planner' | 'shell';
+    text: string;
+} | {
+    kind: 'gate-prompt';
+    id: string;
+    timestamp: string;
+    final: false | true;
+    envelope: GatePromptEnvelope;
+    queue: ReadonlyArray<GatePromptEnvelope>;
+    uiState: {
+        phase: 'awaiting-number';
+    } | {
+        phase: 'awaiting-notes';
+        decisionDraft: string;
+    } | {
+        phase: 'submitting';
+    } | {
+        phase: 'resolved';
+        postAction: PostDecisionAction;
+        resolvedBy: 'self';
+    };
+};
+/**
+ * §5.1 LOCK lines 485-490. Stage 2 r3 Gemini M4. Captures a
+ * PlannerDecision the user wants to run but cannot start yet because
+ * the prior task is still running.
+ */
+export interface QueuedTask {
+    queuedTaskId: string;
+    plannerDecision: PlannerDecision;
+    queuedAt: string;
+    blockedOnTaskId?: string;
+}
+/**
+ * §5.1 LOCK lines 496-500. Codex r2 M1. Captures the original prompt
+ * + every clarifying question the planner has asked so far + the user's
+ * answers. Next USER_INPUT under `pendingClarification !== null`
+ * resolves the most recent question and re-routes through
+ * `classifyPlannerPrompt` with the full `clarifications` array.
+ */
+export interface PendingClarification {
+    originalPrompt: string;
+    rounds: Array<{
+        question: string;
+        answer?: string;
+    }>;
+    conversationEntryId: string;
+}
+/**
+ * §5.1 LOCK lines 463-480. Owned by the orchestration-shell store.
+ * Bounded ring buffer on `conversation` (last 500 entries — design line
+ * 469).
+ */
+export interface OrchestrationState {
+    session: Session;
+    plannerHealth: PlannerHealthState;
+    conversation: ConversationEntry[];
+    runningTasks: Map<string, RunningTaskState>;
+    queuedTasks: QueuedTask[];
+    activeReviewerSeats: Map<string, ReviewerSeatState>;
+    currentGate: GateState | null;
+    pendingClarification: PendingClarification | null;
+    inputHistory: string[];
+    /**
+     * `[ADDITIVE WIDENING — CP-1.d]` per `PHASE-CP-1-D-DESIGN.md` §4.8
+     * lines 1011-1019. `null` until session-start generation completes (or
+     * the `/structural-summary --regenerate` side effect refreshes it).
+     * sha256 is stable per `assembler.ts` canonical-replacer.
+     */
+    structuralSummary: StructuralSummary | null;
+    /**
+     * `[ADDITIVE WIDENING — CP-1.d]` per `PHASE-CP-1-D-DESIGN.md` §4.8
+     * lines 1011-1019. Populated when `STRUCTURAL_SUMMARY_FAILED` fires
+     * (fail-closed per §4.7); cleared on next successful regeneration.
+     */
+    structuralSummaryError: string | null;
+}
+/**
+ * §5.1 LOCK lines 502-513. Discriminated union over every state
+ * transition the reducer covers. `attachedTaskId` / `ATTACH` / `DETACH`
+ * variants are NOT present per §5.1.5 — `/attach` is DEFERRED to CP-1.1.
+ *
+ * [ADDITIVE WIDENING — CP-1.a, per Stage 1 r1 MEDIUM-1] CP-1.a widens the
+ * locked §5.1 OrchestrationAction with 5 additive surfaces (all required
+ * by the reducer + render pipeline; none change the locked semantics):
+ *
+ *   - `PLANNER_DECISION.taskId?: string` (optional) — populates
+ *     `state.runningTasks.taskId` when the decision spawns one. CP-1.b
+ *     will widen further when the planner client wires the real taskId.
+ *   - `REVIEWER_STATE_CHANGED.nodeId: string` — disambiguates which
+ *     `kind:'reviewer-status-node'` ConversationEntry to update in place
+ *     (multiple reviewer-quorum nodes can be live concurrently).
+ *   - `GATE_STATE_CHANGED.nodeId: string` — same disambiguation for
+ *     `kind:'gate-status-node'`.
+ *   - `TASK_LIFECYCLE` (new variant) — populates `state.runningTasks`
+ *     on spawn / cancel / completion. The design's §5.1 line 470 calls
+ *     for `runningTasks: Map<string, RunningTaskState>` but did not name
+ *     the action that writes to it; this is the gap-filling variant.
+ *   - `CLEAR_PENDING_CLARIFICATION` (new variant) — invoked by `cli.ts`
+ *     when the planner returns a non-`ask_user` decision and we need to
+ *     clear stale clarifications. Design §5.1 says the next USER_INPUT
+ *     resolves the question, but a non-ask_user decision returning
+ *     out-of-band needs an explicit reset.
+ *
+ * CP-1.b/c may further widen the union. Stage A LOCK invariant: every
+ * NEW variant or required field is tagged here before the reducer
+ * consumes it.
+ */
+export type OrchestrationAction = {
+    type: 'USER_INPUT';
+    text: string;
+} | {
+    type: 'PLANNER_DECISION';
+    decision: PlannerDecision;
+    taskId?: string;
+} | {
+    type: 'EVENT_RECEIVED';
+    event: EventStreamEntry;
+    role?: 'implementor' | 'reviewer';
+} | {
+    type: 'REVIEWER_STATE_CHANGED';
+    nodeId: string;
+    seatId: string;
+    newState: ReviewerSeatState;
+} | {
+    type: 'GATE_STATE_CHANGED';
+    nodeId: string;
+    gate: GateState;
+} | {
+    type: 'PLANNER_HEALTH_CHANGED';
+    newState: PlannerHealthState;
+} | {
+    type: 'SLASH_OUTPUT';
+    command: string;
+    output: string;
+} | {
+    type: 'CLARIFICATION_ANSWERED';
+    answer: string;
+} | {
+    type: 'TASK_QUEUED';
+    queuedTask: QueuedTask;
+} | {
+    type: 'TASK_DEQUEUED';
+    queuedTaskId: string;
+} | {
+    type: 'TASK_LIFECYCLE';
+    task: RunningTaskState;
+} | {
+    type: 'CLEAR_PENDING_CLARIFICATION';
+} | {
+    type: 'STRUCTURAL_SUMMARY_GENERATED';
+    summary: StructuralSummary;
+    elapsedMs: number;
+} | {
+    type: 'STRUCTURAL_SUMMARY_FAILED';
+    error: string;
+} | {
+    type: 'GATE_PROMPT_RECEIVED';
+    envelope: GatePromptEnvelope;
+} | {
+    type: 'GATE_PROMPT_NOTES_REQUESTED';
+    promptEntryId: string;
+    decisionDraft: string;
+} | {
+    type: 'GATE_PROMPT_SUBMIT_STARTED';
+    promptEntryId: string;
+} | {
+    type: 'GATE_PROMPT_RESOLVED';
+    promptEntryId: string;
+    postAction: PostDecisionAction;
+} | {
+    type: 'GATE_PROMPT_SUBMIT_FAILED';
+    promptEntryId: string;
+    error: string;
+} | {
+    type: 'SHELL_ADVISORY';
+    text: string;
+    source: 'shell';
+} | {
+    type: 'GATE_PROMPT_NOTES_CANCELLED';
+    promptEntryId: string;
+} | {
+    type: 'EXIT';
+};
+/**
+ * §2 LOCK lines 108-113. `~/.codevibe/last-mode.json` shape.
+ */
+export interface LastModeFile {
+    schemaVersion: 1;
+    mode: Mode;
+    pickedAt: string;
+    pickedByTier: 'PRO' | 'MAX';
+}
+/**
+ * Tier surface used by §2 mode-selection. Matches the runtime tiers
+ * carried by `getSubscriptionStatus` (FREE / PRO / MAX). CP-1.a only
+ * needs the literal union — the AppSync-side enum lives in
+ * `src/types/auth.ts` already.
+ */
+export type Tier = 'FREE' | 'PRO' | 'MAX';

package/dist/planner/__tests__/cache-clarification-bypass.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/planner/__tests__/cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/planner/__tests__/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/planner/__tests__/health-machine-transitions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/planner/__tests__/types-zod.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/planner/adapter.d.ts

@@ -0,0 +1,16 @@
+export type { PlannerInput, PlannerDecision, PlannerProbeResult, SessionContext, BudgetHint, Clarification, CachedClassification, ClassificationKind, Tier, PlannerHealthState, PlannerHealthTransition, } from './types';
+import type { PlannerInput, PlannerDecision, PlannerProbeResult } from './types';
+export interface PlannerAdapter {
+    classify(input: PlannerInput): Promise<PlannerDecision>;
+    probe(): Promise<PlannerProbeResult>;
+    /**
+     * CP-1.b IMPL r2 H-3 — Bind the active session for subsequent
+     * `probe()` calls. Stage 2 r1 added this to `BackendPlannerClient`
+     * but missed declaring it on the interface, so callers — notably
+     * `runOrchestrationShell` — never invoked it and `probe()` threw
+     * "no active session" unconditionally in production.
+     *
+     * Pass `null` on session teardown to clear the binding.
+     */
+    setActiveSession(sessionId: string | null): void;
+}

package/dist/planner/cache.d.ts

@@ -0,0 +1,35 @@
+import type { CachedClassification } from './types';
+export declare class PlannerCacheLayer {
+    private workflowCache;
+    private signatureCache;
+    private hydrated;
+    private mutex;
+    private cacheRoot;
+    constructor(cacheRoot?: string);
+    getWorkflowClassification(userId: string, prompt: string): Promise<CachedClassification | null>;
+    setWorkflowClassification(userId: string, prompt: string, c: CachedClassification): Promise<void>;
+    /**
+     * CP-1.b Stage 2 r2 M-2 — Explicit lazy-persist flush for callers
+     * that need to durably commit pending in-memory inserts (e.g.
+     * orchestration-shell on session end). LOCK #18 permits this
+     * trigger.
+     */
+    flush(): Promise<void>;
+    getSignatureClassification(userId: string, sigHash: string): CachedClassification | null;
+    setSignatureClassification(userId: string, sigHash: string, c: CachedClassification): void;
+    flushForTier(userId: string): Promise<void>;
+    flushAll(): Promise<void>;
+    purgeOnUserSwitch(newUserId: string): Promise<void>;
+    private hydrateWorkflowIfNeeded;
+    private rotateCorrupt;
+    private persistWorkflow;
+    private cacheDir;
+    private userIdPrefix;
+    private workflowFilePath;
+    private canonicalize;
+    private assertNoActionJson;
+    private evictLru;
+    private ensureCacheRoot;
+    private ensureDir;
+    private rmRecursiveSafe;
+}