@buildaharness/aielia 0.3.0

package/dist/assistant.d.ts

@@ -0,0 +1,419 @@
+import { ExperienceStore, CheckpointStore, AskResponse } from '@buildaharness/harness';
+import { MemoryAdapter, ILLMClient, ChatMessage, ReminderStore } from '@buildaharness/runtime';
+import { FileToolsContext } from './file-tools.js';
+import { UndoLogEntry } from './action-snapshot.js';
+import { WebToolsContext } from './web-tools.js';
+import { ShellToolsContext } from './shell-tools.js';
+import { ActionToolsContext } from './action-tools.js';
+import { SpendCapConfig, SpendState } from './spend-cap.js';
+import { TraceEvent } from './trace-events.js';
+import { AssistantToolStep } from './tool-step.js';
+import { MemorySummary, MemoryExport } from './memory-service.js';
+import { UserFact } from './fact-extraction.js';
+import { TranscriptSearchHit } from './assistant-session.js';
+import { PlanDecision, PlanApprovalEdits } from './plan-approval-service.js';
+import { PlanRecord } from './plan-store.js';
+import { OneLoopMode } from './one-loop-flag.js';
+import { AskMode } from './ask-mode-flag.js';
+import { PlanRolloutMode } from './plan-mode-flag.js';
+import { DebugLogEntry } from './debug-log.js';
+import { AssistantTurnResult, AssistantProgress } from './assistant-types.js';
+export type { MemorySummary, MemoryExport, PendingFact } from './memory-service.js';
+export type { FactCategory } from './turn-intent-classifier.js';
+export type { IndexedMessage, TranscriptSearchHit } from './assistant-session.js';
+export type { BatchBudgetState } from './agent-loop.js';
+export { trimmedAverage, nextItemBudget } from './agent-loop.js';
+export type { AssistantSource } from './assistant-source.js';
+export type { DebugLogEntry } from './debug-log.js';
+export type { AssistantTrace, AssistantTurnResult, AssistantProgress, ProposerKind } from './assistant-types.js';
+export type { PlanDecision, PlanApprovalEdits } from './plan-approval-service.js';
+export type { PlanMode } from './plan-store.js';
+/** Result of `/memory confirm`/`/memory reject` (single index or bulk category) — see PersonalAssistant.confirmPendingFact/rejectPendingFact. */
+export type MemoryPendingOutcome = {
+    ok: true;
+    facts: UserFact[];
+    conflictNotices: string[];
+} | {
+    ok: false;
+    error: string;
+};
+export interface TurnOptions {
+    sessionId?: string;
+    approved?: boolean;
+    pendingActionId?: string;
+    /**
+     * Q2 of plans/ask_question_and_plan_mode_plan.html — resolves a staged `needs_clarification`
+     * result (see AssistantTurnResult.pendingClarificationId) with the user's answer. Mirrors
+     * `pendingActionId`/`approved`'s own "resolved by ID, never re-derived" shape:
+     * `clarificationAnswer` must answer exactly the questions that were staged, validated
+     * server-side (INV-28) regardless of what the client already checked.
+     */
+    pendingClarificationId?: string;
+    clarificationAnswer?: AskResponse;
+    /**
+     * P2 of plans/ask_question_and_plan_mode_plan.html — resolves a staged `needs_plan_approval`
+     * result (see AssistantTurnResult.planApprovalId) with the user's decision. Mirrors
+     * `pendingActionId`/`approved`'s "resolved by ID, never re-derived" shape: what gets
+     * approved/declined is exactly the plan that was staged, never re-drafted.
+     */
+    planApprovalId?: string;
+    /** `'approve'`/`'approve_with_edits'`/`'decline'` — required to resolve `planApprovalId`; omitting it leaves the plan `awaiting_approval` (fail closed), same as an unanswered clarification. */
+    planDecision?: PlanDecision;
+    /** Only meaningful with `planDecision: 'approve_with_edits'` — cancels/edits applied before the plan is activated. */
+    planEdits?: PlanApprovalEdits;
+    /**
+     * Per-session override — tier 2 of Q1's three-tier INV-29 resolution. `'disabled'` forces
+     * plain free-text-fallback escalations for this turn even when the global `askMode` config is
+     * `'enabled'`. Absent/`'enabled'` defers to the global flag. Never widens the global flag: an
+     * override can only turn structured questions off relative to it, never on when the global
+     * flag is off.
+     */
+    askMode?: AskMode;
+    onProgress?: (progress: AssistantProgress) => void;
+    /**
+     * Called with each token as the model's reply streams in. On the plain chat
+     * path (no tool loop active) this is the turn's one real LLM call, read via
+     * callChat. On the tool-loop path (fileTools/webTools configured), every
+     * tool-bearing round trip stays non-streaming — callChatStructured isn't a
+     * streaming call for either backend — but once the model stops calling tools,
+     * one extra callChat request re-asks for that same final answer as a real
+     * streamed completion, *only when `onToken` is supplied* (so a caller who
+     * doesn't listen never pays for it). ClaudeCliLLMClient's callChat isn't real
+     * per-token streaming either way (it yields the whole reply as one chunk) —
+     * this only reads token-by-token on the proxy backend.
+     */
+    onToken?: (token: string) => void;
+    /**
+     * Called once per tool call as it happens, with a human-readable summary — the "what
+     * step is the assistant on right now" signal, distinct from onTrace's name/status-only
+     * telemetry. Fires for every backend: the proxy backend's tool loop reports each call it
+     * dispatches directly; the claude-cli backend reports calls its own agentic loop makes
+     * autonomously inside a single subprocess call, via ChatOptions.onToolStep (see
+     * ClaudeCliLLMClient).
+     */
+    onToolStep?: (step: AssistantToolStep) => void;
+    /**
+     * **Eval harness only** (`packages/aielia/eval/`). Wraps the one-loop
+     * proposer so its first `failIterations` harness iterations report a failed execution
+     * and `seedFailures` recurring same-class records are seeded into the run's
+     * `failureDiagnostics` — enough to trip `cannotMakeProgress()` on iteration 1 and
+     * exercise the Trajectory Supervisor's stall edge inside a single benchmark turn. Never
+     * set by a real caller; ignored unless the one-loop proposer path is active.
+     */
+    __benchmarkInjectedFailure?: {
+        failIterations: number;
+        seedFailures: number;
+        onInjected?: () => void;
+    };
+}
+export interface PersonalAssistantOptions {
+    llmClient: ILLMClient;
+    model?: string;
+    /**
+     * The already-resolved project label a project-scoped fact gets tagged with and filtered
+     * against — see UserFact.project's doc comment. Callers resolve `config.activeProject ??
+     * workspaceRoot` themselves (cli.ts's buildAssistant) before passing it in; PersonalAssistant
+     * doesn't know about workspaceRoot itself (it's a per-tool option, not assistant-wide — see
+     * fileTools/shellTools/actionTools). Undefined/empty leaves every fact unscoped, matching a
+     * fresh install with no workspace concept at all.
+     */
+    activeProject?: string;
+    /** Conversation transcript storage — defaults to an in-process Map, swap for IndexedDBAdapter in the browser. */
+    memory?: MemoryAdapter;
+    /** Learning-layer store — persist and pass the same instance back in across sessions to retain strategy weights. */
+    experienceStore?: ExperienceStore;
+    /** Stores an in-flight harness run's checkpoint so a crash/reload mid-turn can resume instead of losing the turn. */
+    checkpointStore?: CheckpointStore;
+    /**
+     * Caps both the harness's plan-driven main loop (auto-raised there via
+     * `Math.max(maxSteps, initialTasks.length)` so a decomposed plan is never starved) and the
+     * ReAct-style tool loop's round-trips (AgentLoop.runToolLoop) — one shared per-turn step
+     * budget rather than two independently-tuned constants. Defaults to 15: high enough that a
+     * legitimate multi-query research task (e.g. "find primary schools near me", which can
+     * easily take 5+ real search round-trips) doesn't get cut off mid-work, while still bounding
+     * a stuck/looping model.
+     */
+    maxSteps?: number;
+    /**
+     * When set, `turn()` gives the model real read_file/list_directory/write_file
+     * tools scoped to `workspaceRoot` instead of a single plain chat call. Absent
+     * by default — behavior is byte-for-byte unchanged from before this option existed.
+     * `write_file` never executes inline; it always stages a proposal and the turn
+     * returns `needs_approval` with a `pendingWriteId`.
+     */
+    fileTools?: FileToolsContext;
+    /**
+     * When set, `turn()` also gives the model web_search/fetch_url tools, grounding replies in external content.
+     * Absent by default — behavior is unchanged when unset. Results from these two tools are wrapped in
+     * `<untrusted_external_content>` before they reach the model (see trust-tagging.ts) — unlike file tools,
+     * this is content the assistant does not vouch for.
+     */
+    webTools?: WebToolsContext;
+    /**
+     * When set, `turn()` gives the model a real run_shell_command tool scoped to `workspaceRoot`.
+     * Every call is gated on approval, full stop — there is no "safe subset" the way `read_file` is
+     * safe within `write_file`'s tool group (a shell command has no structural split between "reads"
+     * and "mutates"). Once approved, the command's stdout+stderr is wrapped in
+     * `<untrusted_external_content>` (same trust boundary as web_search/fetch_url — see
+     * trust-tagging.ts) before it's saved into the transcript, since it can carry the same kind of
+     * injection-shaped content a fetched web page can. Independent of `fileTools`/`webTools` so a
+     * caller can enable file/web access without ever exposing shell.
+     */
+    shellTools?: ShellToolsContext;
+    /**
+     * When set, `turn()` gives the model real "effect" tools — today `send_email` — scoped to
+     * `workspaceRoot` for staging. Every call is approval-gated exactly like `write_file` /
+     * `run_shell_command`: the model can only propose a message, never deliver one. On approval,
+     * `applyPendingAction` calls `sendEmail` (email.ts's Resend transport / email-smtp.ts's SMTP
+     * transport — wired in by a Node caller, never imported here). Independent of
+     * `fileTools`/`webTools`/`shellTools`. Absent by default — no `send_email` tool exists unless set.
+     */
+    actionTools?: ActionToolsContext;
+    /** Stores reminders detected from "remind me"/"set a reminder"-shaped requests — defaults to an in-process store. See ReminderStore's `dueAt` doc: v1 stores raw text only, no time parsing, so `listDue()` won't return these yet. */
+    reminderStore?: ReminderStore;
+    /** Structured turn telemetry — turn/risk/triviality/harness-node/tool-call/escalation/error events. Purely additive instrumentation; no behavior change when unset. */
+    onTrace?: (event: TraceEvent) => void;
+    /**
+     * Full message/tool content for live debugging — deliberately separate from `onTrace`
+     * (which is name/status-only by design, safe to hand to an arbitrary sink; see its own doc
+     * comment) since this one carries the actual conversation. Off by default: nothing is
+     * logged anywhere unless a caller wires this in. See DebugLogEntry.
+     */
+    onDebugLog?: (entry: DebugLogEntry) => void;
+    /**
+     * Equivalent of Claude Code's own --dangerously-skip-permissions (see AssistantConfig's doc
+     * comment in config.ts). When true, both the message-level risk gate and write_file/
+     * run_shell_command's per-call staging resolve as if the user had already said yes, instead
+     * of returning `needs_approval` — turn() auto-applies a staged action the same way a second
+     * turn() call with `approved: true` would. The underlying sandboxing (path validation, SSRF
+     * guard, shell env allowlist, output truncation, timeout) is never skipped — only the ask.
+     * Off by default.
+     */
+    dangerouslySkipPermissions?: boolean;
+    /**
+     * Opt-in session spend/turn-count ceilings — see spend-cap.ts. Undefined by default, same as
+     * every other field here that changes behavior only when a caller sets it: no ceiling means
+     * exactly today's unbounded behavior. Checked once per turn, before any LLM call that turn
+     * would make (see turn()) — never mid-turn.
+     */
+    spendCap?: SpendCapConfig;
+    /**
+     * R2 of plans/harness_d2_one_loop_rewire_plan.html — see one-loop-flag.ts's doc comment for the
+     * full rollout rationale. 'disabled' (the default, for the whole R2-R4 rollout window): today's
+     * behavior, byte-for-byte — HarnessBridge.run() always uses `() => draftReply` as its toolFn,
+     * regardless of whether a caller happens to supply a proposer. 'enabled' lets a supplied
+     * proposer (see HarnessRunParams.oneLoopProposer) actually be used. PersonalAssistant itself
+     * never touches process.env — only cli.ts (or an equivalent surface entry point) is expected to
+     * call resolveOneLoopMode(process.env) and pass the result here.
+     */
+    oneLoopMode?: OneLoopMode;
+    /**
+     * Q2 of plans/ask_question_and_plan_mode_plan.html — global-flag control point (tier 1 of
+     * INV-29) for the ask-question mechanism. Undefined (the default) falls back to
+     * `DEFAULT_ASK_MODE` ('disabled') — today's behavior, byte-for-byte: every escalation stays on
+     * the plain `escalated`/`reply: null` path. Only cli.ts/chat-ui's App.tsx (or an equivalent
+     * surface entry point) is expected to resolve this from ASSISTANT_ASK_MODE/
+     * VITE_ASSISTANT_ASK_MODE and pass it down — PersonalAssistant itself never touches
+     * process.env, mirroring oneLoopMode's own convention.
+     */
+    askMode?: AskMode;
+    /**
+     * P11 of plans/ask_question_and_plan_mode_plan.html — see plan-mode-flag.ts's doc comment for
+     * the full rollout rationale. 'legacy' (the default, for the whole rollout window): P3's
+     * judgment-based auto-trigger below never fires, so `turn()` never auto-enters plan mode's
+     * exclusive drafting+approval loop — today's behavior, byte-for-byte, for every real user turn.
+     * 'gated' lets that auto-trigger run. PersonalAssistant itself never touches process.env — only
+     * cli.ts/chat-ui's App.tsx (or an equivalent surface entry point) is expected to call
+     * resolvePlanMode(process.env)/normalizePlanMode(import.meta.env...) and pass the result here.
+     */
+    planMode?: PlanRolloutMode;
+}
+/**
+ * A light, everyday-use wrapper around HarnessRuntime: one harness run per chat turn,
+ * one real LLM call per turn (skipped entirely while a HIGH-risk action awaits approval).
+ * Conversation history lives beside the harness run (in `memory`), not inside it — each
+ * turn's WorldModel/TaskGraph/etc. are scratch state for that single turn, same as the
+ * rest of the 11-layer runtime; only the transcript, the ExperienceStore, and (while a
+ * turn is actually in flight) a HarnessRunState checkpoint persist.
+ *
+ * Phase 4d of the architecture remediation plan split this class's internals into 8
+ * single-purpose collaborators (MemoryService, AssistantSession, AgentLoop,
+ * ActionApprovalService, PlanService, TurnInterpreter, HarnessBridge, ResponseService), each
+ * constructed once here and wired together. This class itself is now a thin facade + sequencer:
+ * its public constructor signature and every public method below are unchanged, so every
+ * existing caller (cli.ts, chat-ui's App.tsx, assistant.test.ts's ~89 `new PersonalAssistant(...)`
+ * call sites) keeps working with zero call-site changes.
+ */
+export declare class PersonalAssistant {
+    private readonly llmClient;
+    private model?;
+    private activeProject?;
+    private readonly memory;
+    private readonly webTools?;
+    private readonly onTrace?;
+    private readonly onDebugLog?;
+    private readonly dangerouslySkipPermissions;
+    /** Whenever any of fileTools/webTools/shellTools is configured, `turn()` routes through AgentLoop instead of a single plain chat call — computed once here since it never changes for the lifetime of an instance. */
+    private readonly toolLoopWillRun;
+    /** R3 of plans/harness_d2_one_loop_rewire_plan.html — mirrors the same flag HarnessBridge was given at construction, kept here too so runTurn can decide whether to defer the tool loop into a harness-driven proposer instead of precomputing draftReply. See PersonalAssistantOptions.oneLoopMode's doc comment. */
+    private readonly oneLoopMode;
+    /** Q2 — global-flag tier of the ask-question mechanism's three-tier INV-29 resolution. See PersonalAssistantOptions.askMode's doc comment. */
+    private readonly askMode;
+    /** P11 — gates whether P3's auto-trigger below can ever enter plan mode for real traffic. See PersonalAssistantOptions.planMode's doc comment. */
+    private readonly planMode;
+    /**
+     * Scratch slot for which proposer drove the most recent runTurn — read by `turn()` to stamp
+     * AssistantTurnResult.proposerKind, and emitted as a 'proposer_selected' trace event from
+     * runTurn itself. A single mutable field is safe because `turn()` is awaited end to end (turns
+     * never overlap within one instance). See AssistantTurnResult.proposerKind and
+     * plans/chat_ui_browser_e2e_plan.html phase B1.
+     */
+    private lastProposerKind;
+    private readonly memoryService;
+    private readonly session;
+    private readonly agentLoop;
+    private readonly actionApproval;
+    private readonly planService;
+    private readonly planApproval;
+    private readonly planDrafting;
+    private readonly planSketch;
+    private readonly turnInterpreter;
+    private readonly harnessBridge;
+    private readonly responseService;
+    private readonly askClarification;
+    constructor(options: PersonalAssistantOptions);
+    /**
+     * Preferred entry point in a browser: defaults transcript, learning, and
+     * checkpoint storage to their IndexedDB/Dexie-backed implementations so all
+     * three survive a page reload, instead of the in-process defaults the plain
+     * constructor uses. Falls back to the same in-memory defaults as `new
+     * PersonalAssistant(...)` outside a browser (e.g. the CLI).
+     */
+    static create(options: PersonalAssistantOptions): Promise<PersonalAssistant>;
+    /**
+     * Thin wrapper around runTurn(): emits turn_start/turn_end/error trace events
+     * around the actual logic, so every one of runTurn's return paths gets a
+     * matching turn_end without instrumenting each one individually.
+     */
+    turn(userMessage: string, options?: TurnOptions): Promise<AssistantTurnResult>;
+    /** Persisted alongside transcript/facts/plan — survives a process restart, same as everything else keyed by sessionId, so the ceiling is genuinely cross-session, not just cross-turn within one process lifetime. */
+    getSpendState(sessionId: string): Promise<SpendState>;
+    /** The session's conversation transcript, oldest first — same array `turn()` reads/appends to. Used by `/export`. */
+    getTranscript(sessionId: string): Promise<ChatMessage[]>;
+    /**
+     * Records a message-level risk-gate decline as a resolved, paired exchange, once the caller
+     * (cli.ts) knows the final answer was "no". See AssistantSession.recordDeclinedRequest's doc
+     * comment for the full reasoning.
+     */
+    recordDeclinedRequest(sessionId: string, userMessage: string, reason: string): Promise<void>;
+    /** Ends the current conversation — see AssistantSession.clearSession's doc comment for exactly what is and isn't cleared. */
+    clearSession(sessionId: string): Promise<void>;
+    /**
+     * P1 of plans/ask_question_and_plan_mode_plan.html — explicit entry point into plan mode's
+     * exclusive drafting state. No production caller yet: P3 will later set this automatically from
+     * a judgment-based trigger ahead of TurnInterpreter's classification. Until then this is reached
+     * only by a caller (a future `/plan` CLI command, or a test) that wants to exercise the drafting
+     * loop directly. Once active, every `turn()` call for this session routes to
+     * `PlanDraftingService` instead of the normal pipeline until the user says an explicit
+     * cancel/abort phrase.
+     */
+    enterPlanMode(sessionId: string): Promise<{
+        active: boolean;
+        draftId: string;
+    }>;
+    /**
+     * P7 of plans/ask_question_and_plan_mode_plan.html — the raw current `PlanRecord` for this
+     * session, regardless of `mode`, so a caller (chat-ui's persistent banner, the CLI's `/plan
+     * show`) can display live drafting/awaiting-approval state independent of any single turn's
+     * own result (a `needs_plan_approval` result only carries a snapshot at the moment it's
+     * staged; a plain `status: 'ok'` drafting reply doesn't carry `rationale`/`reviewNotes` at
+     * all). Returns `null` when no plan record exists for this session yet.
+     */
+    getPlanState(sessionId: string): Promise<PlanRecord | null>;
+    /**
+     * P9 of plans/ask_question_and_plan_mode_plan.html — the lightweight plan-sketch delegate: a
+     * cheaper "just go research and draft an approach" path than plan mode's durable task-graph
+     * machinery (P0-P8), explicitly invoked (a CLI `/plan sketch <request>` command, a chat-ui
+     * "Sketch a plan" action) rather than auto-triggered. Returns advice in the reply text — it
+     * never creates a `PlanRecord`, never sets `planMode.active` (`enterPlanMode` above), never
+     * stages anything for `PlanApprovalService`, and cannot execute a single task (INV-35). A real,
+     * cost-incurring LLM call, so it still goes through the same session spend-cap check/record as
+     * an ordinary `turn()` — just none of `turn()`'s classification/tool-loop/plan-mode machinery.
+     */
+    sketchPlan(sessionId: string, request: string): Promise<AssistantTurnResult>;
+    /** Scoped recovery for a stuck harness checkpoint — see AssistantSession.clearCheckpoint's doc comment. */
+    clearCheckpoint(sessionId: string): Promise<{
+        cleared: boolean;
+        stepsUsed?: number;
+        currentNode?: string;
+    }>;
+    /** Read-only counterpart to clearCheckpoint — see AssistantSession.getCheckpointStatus's doc comment. */
+    getCheckpointStatus(sessionId: string): Promise<{
+        present: boolean;
+        stepsUsed?: number;
+        currentNode?: string;
+        failedResumeAttempts: number;
+    }>;
+    /** Removes the most recent exchange from conversation history — see AssistantSession.undoLastTurn's doc comment. */
+    undoLastTurn(sessionId: string): Promise<{
+        undone: boolean;
+    }>;
+    /** Real filesystem effects still on record as revertible, newest first — see AssistantSession.listUndoLogEntries's doc comment. */
+    listUndoLogEntries(): Promise<UndoLogEntry[]>;
+    /** Stages a revert of undo-log entry `id` as its own approval-gated pending action — see AssistantSession.stageUndoAction's doc comment. */
+    stageUndoAction(id: string): Promise<{
+        status: 'staged';
+        pendingActionId: string;
+        reason: string;
+    } | {
+        status: 'error';
+        message: string;
+    }>;
+    /** Read-only snapshot of what this session/assistant has learned — see MemoryService.getMemorySummary's doc comment. Used by `/memory`. */
+    getMemorySummary(sessionId: string): Promise<MemorySummary>;
+    /** Full, unbounded snapshot of everything learned so far — see MemoryService.exportMemory's doc comment. Used by `/memory export`. */
+    exportMemory(sessionId: string): Promise<MemoryExport>;
+    /**
+     * `/memory confirm <n|category>` — `selector` is either a 1-based index into `/memory`'s
+     * flat, display-order "Pending confirmation" listing, or one of FactCategory's names for a
+     * bulk confirm. Phase 3 of plans/personal_assistant_fact_extraction_llm_confidence_plan.html.
+     * `conflictNotices` (if any) are advisory only — every confirmed fact is promoted regardless,
+     * matching how every other contradiction check in this codebase never gates belief admission.
+     */
+    confirmPendingFact(selector: string): Promise<MemoryPendingOutcome>;
+    /** `/memory reject <n|category>` — mirror of confirmPendingFact, see its doc comment for `selector`'s shape. */
+    rejectPendingFact(selector: string): Promise<MemoryPendingOutcome>;
+    /**
+     * `/memory forget <n>` — `n` is a 1-based index into `/memory`'s "Facts I know" listing (durable
+     * facts first, then session facts — the same order `getMemorySummary()` returns). Unlike
+     * confirm/reject, there's no category form: a durable/session fact carries no `category` field,
+     * only pending model-inferred guesses do. Hard-deletes rather than routing through
+     * REJECTED_FACTS_KEY — see MemoryService.forgetFact's doc comment.
+     */
+    forgetFact(selector: string, sessionId: string): Promise<MemoryPendingOutcome>;
+    /** Ranked search over the per-message index — see AssistantSession.searchTranscript's doc comment. Used by `/search`. */
+    searchTranscript(query: string, topK?: number): Promise<TranscriptSearchHit[]>;
+    /** Changes the model used by every subsequent `turn()` call, mid-session — no reconstruction needed. Used by `/model`. Every collaborator constructed above reads this field through a getter closure, never a captured string, so this takes effect for all of them immediately. */
+    setModel(model: string | undefined): void;
+    /** The project label new project-scoped facts are tagged with and existing ones are filtered against this session — see UserFact.project's doc comment. Empty string when none is set (cli.ts's buildAssistant always resolves one from workspaceRoot, but a bare `new PersonalAssistant()` with no `activeProject` option should read as "no project concept" rather than `undefined`). */
+    getActiveProject(): string;
+    /** Mid-session override for `activeProject`, mirroring setModel — takes effect on the very next turn via the same getter-closure MemoryService already reads through. Used by `/project <name>` outside the CLI's own /config-set-and-reload path (e.g. a future non-CLI embedder). */
+    setActiveProject(project: string | undefined): void;
+    /**
+     * The sequencer: constructs no state of its own beyond what a single turn needs
+     * (transcript/facts/system prompt, the turn-scoped usage accumulator), and otherwise just
+     * calls each collaborator in the same order the pre-split code ran their logic inline, wiring
+     * each one's output into the next. See turn-interpreter.ts/agent-loop.ts/harness-bridge.ts/
+     * response-service.ts for where the real control-flow subtlety (the batch-research path, the
+     * plan-cancel bypass, the triviality fast path) actually lives now.
+     */
+    private runTurn;
+    /**
+     * Shared by the flag-OFF flat/batch tool loop's own needs_approval/escalated ToolLoopResult and
+     * the flag-ON harness-driven proposer's equivalent OneLoopPause (R3 of
+     * plans/harness_d2_one_loop_rewire_plan.html, see runTurn's two call sites) — "the model wants
+     * to write/run/send something" or "the tool loop gave up" means the same thing to the caller
+     * regardless of which loop discovered it.
+     */
+    private buildToolLoopPauseResult;
+}

package/dist/batch-list-detector.d.ts

@@ -0,0 +1,15 @@
+export interface BatchListDetection {
+    /** Exact strings as they appeared in the list (marker/bullet stripped), in message order. */
+    items: string[];
+}
+/**
+ * Zero-LLM-call gate for the one task shape this plan targets: an explicit, syntactically obvious
+ * list of ≥3 lookup targets (newline-separated names, markdown bullets, or a numbered list).
+ * Deliberately narrower than decomposition-classifier.ts's enumeration detection — no
+ * comma-enumeration, no sequencing-word detection, no word-count fallback. Those stay that file's
+ * problem; this one only fires on a shape unambiguous enough that a false positive should be
+ * essentially impossible. Fails closed (returns null) for anything else, including a list where
+ * most lines don't read as name-shaped (task instructions, not lookup targets) and a run below the
+ * 3-item floor.
+ */
+export declare function detectHomogeneousBatchList(message: string): BatchListDetection | null;

package/dist/batch-research-fixtures.d.ts

@@ -0,0 +1,50 @@
+import { LLMStructuredResponse } from '@buildaharness/runtime';
+import { WebSearchResult } from './web-tools.js';
+/**
+ * The real school-dates comparison this plan is built on (see
+ * plans/personal_assistant_dynamic_tool_budget_plan.html's Reference Transcripts tab), encoded as
+ * a reusable scripted-LLM-response fixture instead of duplicated inline in assistant.test.ts —
+ * so the integration replay test stays traceable back to the actual incident that motivated this
+ * plan, and any recalibration of thresholds later has the real shape to check against.
+ *
+ * `searchYields` lists one entry per web_search call this item's own per-item sub-loop makes, in
+ * order. An item whose last 3 entries are all `'dead_end'` (Halensee-Grundschule below) trips
+ * resolveBatchItem's item-scoped dead-end window (BATCH_DEAD_END_WINDOW = 3) — that item never
+ * reaches a final LLM call at all, so `finalAnswer` is omitted for it; every other item needs one.
+ */
+export interface BatchFixtureItem {
+    /** Exact list-item text, as it will appear (one per line) in the batch request message. */
+    item: string;
+    searchYields: ReadonlyArray<'productive' | 'dead_end'>;
+    /** The model's own final per-item answer, once every scripted search yield above has been
+     * consumed. Omitted only for an item whose sub-loop resolves via the dead-end window instead
+     * (see the doc comment above). */
+    finalAnswer?: string;
+}
+/**
+ * The actual 7-school request from the comparison transcript, in the same order the user pasted
+ * them back. Grunewald-Grundschule (cheap — resolved without needing a single search) and
+ * Erich-Kästner-Grundschule (expensive — needed several searches before the Terminplan PDF turned
+ * up a confirmed date) are items[0]/items[1], so a 7-item batch's probe phase (probeCount = 2)
+ * naturally covers both the cheap and the expensive case. Halensee-Grundschule (the genuinely
+ * dead 404'd page) sits among the remaining items, proving the item-scoped dead-end window
+ * doesn't drag down the other, perfectly findable schools queued behind it.
+ */
+export declare const SCHOOL_DATES_BATCH_FIXTURE: readonly BatchFixtureItem[];
+/** The batch request message a user would actually send — each item on its own line, matching
+ * detectHomogeneousBatchList's expected shape. */
+export declare function fixtureUserMessage(items?: readonly BatchFixtureItem[]): string;
+/**
+ * The ordered callChatStructured script every item's own sub-loop consumes, in the exact order
+ * runBatchToolLoop/resolveRemainingBatchItems resolve them (probe items first, in array order,
+ * then the rest in array order) — a ScriptedToolLLMClient (see assistant.test.ts) plays this back
+ * verbatim regardless of what the mocked web_search calls actually return.
+ */
+export declare function fixtureStructuredResponses(items?: readonly BatchFixtureItem[]): LLMStructuredResponse[];
+/**
+ * A stateful web_search mock consuming `searchYields` in the same flattened order
+ * fixtureStructuredResponses schedules its tool calls in — 'dead_end' yields an empty result
+ * array (web-tools.ts's executor turns that into the literal "No results found."); 'productive'
+ * yields one real-looking result.
+ */
+export declare function fixtureWebSearch(items?: readonly BatchFixtureItem[]): () => Promise<WebSearchResult[]>;

package/dist/benchmark-injected-failure.d.ts

@@ -0,0 +1,27 @@
+import { ToolExecutorContext } from '@buildaharness/harness';
+export interface InjectedFailureOptions {
+    /** How many leading harness iterations report a failed execution. */
+    failIterations: number;
+    /** Recurring same-class `failure_history` records seeded on the first call. */
+    seedFailures: number;
+    /**
+     * How many times the *real* proposer may run after the failure phase (default 2).
+     * The first real call is the derailed attempt; a supervisor recovery (a re-queued
+     * leaf after GATHER_EVIDENCE / REDIRECT_STRATEGY, S8) gets a second, fresh call so
+     * newly gathered evidence in the WorldModel can actually change the answer. Beyond
+     * this the last real result is replayed so a thrashing run still converges without
+     * unbounded backend cost.
+     */
+    maxRealCalls?: number;
+    /**
+     * Called exactly once, the first time the wrapper actually runs (i.e. the failure was really
+     * injected into this turn). The benchmark reads it back as `ArmTurnOutput.injectedFailureFired`
+     * so `recoveryRate` only counts tasks where the failure genuinely fired for this arm — not
+     * every task that merely *declares* an `injectedFailure` (see
+     * plans/feature_audit_fair_comparison_plan.html F2).
+     */
+    onInjected?: () => void;
+}
+type Proposer = (toolCtx: ToolExecutorContext) => unknown | Promise<unknown>;
+export declare function wrapProposerWithInjectedFailure(realProposer: Proposer, opts: InjectedFailureOptions): (toolCtx: ToolExecutorContext) => Promise<unknown>;
+export {};