@buildaharness/aielia 0.3.0

package/dist/answer-claim.d.ts

@@ -0,0 +1,51 @@
+import { Evidence, VerificationResult } from '@buildaharness/harness';
+/**
+ * Where the evidence backing a reply actually came from — 'tool_evidence' when at least one
+ * real observation (a gather_evidence call, a real read_file/web_search result, ...) was
+ * recorded this turn, 'model_reasoning' when the harness ran but produced no such observation
+ * (a plain-reasoning reply, still gated through the full loop).
+ */
+export type AnswerClaimSourceType = 'tool_evidence' | 'model_reasoning';
+/**
+ * The four branches this plan's Validation section names explicitly — each backed by a real,
+ * mechanically-derived signal (see buildAnswerClaim), never guessed from the reply text itself:
+ * - 'verified': the verification layer found no critical failure and at least one layer
+ *   actually PASSed (not just SKIPPED) against real evidence.
+ * - 'unverified_attempted': evidence was gathered, but no layer could independently confirm it
+ *   (all SKIPPED/no tool to check with) — an honest "couldn't verify," not a fake PASS.
+ * - 'contradicted': the Contradiction layer flagged a conflict with an existing belief this turn.
+ * - 'no_evidence': no real observation was gathered at all — a plain-reasoning answer.
+ */
+export type AnswerClaimVerificationStatus = 'verified' | 'unverified_attempted' | 'contradicted' | 'no_evidence';
+/**
+ * Phase 6 of the harness/assistant remediation plan: a first-class epistemic-honesty signal
+ * attached to a reply that went through the harness loop, distinguishing "this is true" from
+ * "I found X but couldn't independently verify it." Built entirely from real, already-computed
+ * harness signal (Phase 2/3's now-real verification layers, the EvidenceStore's real
+ * observations, the Contradiction layer's own finding) — never a new LLM judgment call.
+ */
+export interface AnswerClaim {
+    evidence: Evidence[];
+    /** min(verificationHealth.strength, verificationHealth.feasibility) — the same real number chat-ui's "Why?" panel already buckets into plain language. */
+    confidence: number;
+    /** ISO timestamp of the least-fresh evidence backing this claim, or null when there's no evidence at all. */
+    freshness: string | null;
+    source_type: AnswerClaimSourceType;
+    verification_status: AnswerClaimVerificationStatus;
+}
+/**
+ * Builds an AnswerClaim from one turn's real harness output. `verification` is the last
+ * VerificationResult HarnessRuntime's onVerification hook reported this turn (null when the
+ * turn never reached verify() at all — e.g. the harness was skipped by the triviality fast
+ * path, in which case the caller should not attach an AnswerClaim at all rather than call this
+ * with a fabricated null).
+ */
+export declare function buildAnswerClaim(input: {
+    evidence: Evidence[];
+    verification: VerificationResult | null;
+    contradicted: boolean;
+    verificationHealth: {
+        strength: number;
+        feasibility: number;
+    };
+}): AnswerClaim;

package/dist/ask-clarification-service.d.ts

@@ -0,0 +1,70 @@
+import { AskQuestion, AskResponse } from '@buildaharness/harness';
+import { MemoryAdapter } from '@buildaharness/runtime';
+import { AssistantSession } from './assistant-session.js';
+import { HarnessBridge } from './harness-bridge.js';
+import { ResponseService } from './response-service.js';
+import { PlanRecord } from './plan-store.js';
+import { TurnIntentClassification } from './turn-intent-classifier.js';
+import { UserFact } from './fact-extraction.js';
+import { AssistantTurnResult } from './assistant-types.js';
+import { TraceEvent } from './trace-events.js';
+/**
+ * Everything AskClarificationService.resolvePendingClarification needs to re-drive the harness
+ * run once the user answers — persisted alongside the staged questions themselves (mirrors
+ * AgentLoop's BatchPendingState, staged the same `memory.set('ask-pending:${id}', ...)` way, see
+ * ActionApprovalService's own "resolved by ID, never re-derived from a second LLM call"
+ * discipline this mirrors, T4 of the file-tools plan).
+ */
+export interface AskClarificationPendingState {
+    sessionId: string;
+    questions: AskQuestion[];
+    classification: TurnIntentClassification;
+    activePlan: PlanRecord | null;
+    facts: UserFact[];
+    draftReply: string;
+}
+/**
+ * Owns the ask-question "staged clarification, resolved by ID" pattern — Q2 of
+ * plans/ask_question_and_plan_mode_plan.html, structurally mirroring ActionApprovalService (T4 of
+ * the file-tools plan: what gets resolved is exactly what was staged, never re-derived from a
+ * second LLM call). Unlike a write/shell action, resolving a clarification means resuming a
+ * *harness run* — the checkpoint HarnessBridge would otherwise have deleted on any thrown
+ * EscalationHalt (see HarnessBridge.run()'s askModeEnabled/preserveForClarification handling) is
+ * kept alive specifically so this service can hand it back to HarnessBridge with the user's
+ * answer folded in via a one-shot UpdateChannel, instead of losing the run's progress and
+ * starting over.
+ */
+export declare class AskClarificationService {
+    private readonly memory;
+    private readonly session;
+    private readonly harnessBridge;
+    private readonly responseService;
+    private readonly onTrace;
+    constructor(memory: MemoryAdapter, session: AssistantSession, harnessBridge: HarnessBridge, responseService: ResponseService, onTrace: ((event: TraceEvent) => void) | undefined);
+    private pendingKey;
+    /**
+     * Stages a batch of questions and returns the `needs_clarification` AssistantTurnResult — the
+     * ResponseService.buildEscalatedResult counterpart for a structured-question escalation
+     * (called instead of it, from assistant.ts's EscalationHalt catch, when
+     * `err.blocker.questions` is populated and the effective askMode is enabled).
+     */
+    stageAndRespond(params: {
+        sessionId: string;
+        transcriptKey: string;
+        userMessage: string;
+        questions: AskQuestion[];
+        classification: TurnIntentClassification;
+        activePlan: PlanRecord | null;
+        facts: UserFact[];
+        draftReply: string;
+    }): Promise<AssistantTurnResult>;
+    /**
+     * Resolves a staged clarification by ID — validates the response against exactly the
+     * questions that were staged (INV-28: a malformed/incomplete payload is rejected, never
+     * silently coerced), folds the answer into the paused harness run via a one-shot
+     * UpdateChannel, and resumes it. A follow-up escalation (INV-37's deferred batch two) routes
+     * back through `stageAndRespond` exactly like the first, via the same catch this resume goes
+     * through.
+     */
+    resolvePendingClarification(sessionId: string, transcriptKey: string, pendingClarificationId: string, response: AskResponse | undefined, askModeEnabled: boolean): Promise<AssistantTurnResult>;
+}

package/dist/ask-mode-flag.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure logic backing PersonalAssistant's ASSISTANT_ASK_MODE handling — split out so it's
+ * unit-testable in isolation, mirroring one-loop-flag.ts's exact shape (module-level default,
+ * an injectable resolver so tests never touch real process.env).
+ *
+ * Q2 of plans/ask_question_and_plan_mode_plan.html: the "global flag" control point (tier 1 of
+ * Q1's three-tier INV-29 resolution) for the batched-questions ask-question mechanism, resolved
+ * at this package's boundary and handed to `@buildaharness/harness`'s `resolveAskMode()` as
+ * `globalEnabled`. 'disabled' (the default, for the whole rollout window, per Q1's
+ * `DEFAULT_ASK_MODE`) means every escalation stays on today's plain `escalated`/`reply: null`
+ * path — AskClarificationService is never reached. 'enabled' lets a populated
+ * `EscalationHalt.blocker.questions` promote to `needs_clarification` instead.
+ */
+export type AskMode = 'enabled' | 'disabled';
+export declare const DEFAULT_ASK_MODE: AskMode;
+/**
+ * Value-level resolver, shared by every surface: `resolveAskMode` (CLI, reads
+ * `process.env.ASSISTANT_ASK_MODE`) and chat-ui's `envOverridesFromImportMetaEnv` (browser
+ * build, reads Vite's `import.meta.env.VITE_ASSISTANT_ASK_MODE`). An unset or empty value falls
+ * back to the default silently; an unrecognized non-empty value falls back with a startup
+ * warning naming `varName` — same typo-tolerance-with-a-warning convention
+ * `normalizeOneLoopMode` uses, since a silently-misread flag here is safety-relevant.
+ */
+export declare function normalizeAskMode(raw: string | undefined, varName?: string): AskMode;
+export declare function resolveAskMode(env: NodeJS.ProcessEnv): AskMode;

package/dist/ask-response-format.d.ts

@@ -0,0 +1,8 @@
+import { AskQuestion, AskResponse } from '@buildaharness/harness';
+/**
+ * Renders a full AskResponse as one transcript-ready message — shared by
+ * AskClarificationService (Q2, resuming a paused harness run) and PlanDraftingService's nested-ask
+ * resolution (P8, continuing a plan draft), both of which fold the user's answer into a plain-text
+ * follow-up message for their own "next call" rather than duplicating this formatting logic.
+ */
+export declare function formatAskResponse(questions: AskQuestion[], response: AskResponse): string;

package/dist/assistant-session.d.ts

@@ -0,0 +1,267 @@
+import { CheckpointStore, LayerActivityEvent, ExternalContradictionInput } from '@buildaharness/harness';
+import { MemoryAdapter, ChatMessage, TokenUsage, FsBackend } from '@buildaharness/runtime';
+import { FileToolsContext } from './file-tools.js';
+import { UndoLogEntry } from './action-snapshot.js';
+import { ShellToolsContext } from './shell-tools.js';
+import { ActionToolsContext } from './action-tools.js';
+import { SpendCapConfig, SpendState } from './spend-cap.js';
+/**
+ * P1 of plans/ask_question_and_plan_mode_plan.html — session/turn-routing switch, distinct from a
+ * tool-permission list. While `active`, `assistant.ts`'s turn entry point routes every incoming
+ * message for this session to `PlanDraftingService` instead of `TurnInterpreter`'s normal
+ * classify/tool-loop pipeline (see PlanDraftingService's own doc comment for the two designed
+ * exits). `draftId` is an opaque per-entry token (not a lookup key into anything today — the
+ * drafting `PlanRecord` itself still lives at plan-store.ts's single `plan:${sessionId}` slot,
+ * same as an ordinary plan) reserved for P2's approval flow to correlate "the draft that was
+ * staged" against "the draft the user is approving", the same "resolved by exactly what was
+ * staged, never re-derived" discipline ActionApprovalService/AskClarificationService already
+ * follow.
+ */
+export interface PlanModeState {
+    active: boolean;
+    draftId: string;
+}
+export declare const RESUME_ATTEMPT_CAP = 2;
+export declare const resumeAttemptsKey: (sessionId: string) => string;
+/**
+ * One searchable, individually-addressable transcript entry — key `transcript-msg:<sessionId>:<n>`
+ * (see messageIndexKey). Written alongside every `transcript:<sessionId>` append by
+ * appendTranscriptMessage so scoreEntries() (via MemoryAdapter.search()) can resolve a hit to this
+ * one exchange instead of the whole session array. Derived, not authoritative: the per-session
+ * `transcript:<sessionId>` array remains the one source of truth for conversation replay,
+ * compaction, and /export — losing an index entry (a failed write, or a pre-backfill install) only
+ * ever degrades search recall, never conversation behavior.
+ */
+export interface IndexedMessage {
+    sessionId: string;
+    role: 'user' | 'assistant';
+    content: string;
+    at: string;
+}
+/** One ranked `/search` result — an `IndexedMessage` plus the graduated relevance score `scoreEntries()` gave it. */
+export interface TranscriptSearchHit {
+    sessionId: string;
+    role: 'user' | 'assistant';
+    content: string;
+    at: string;
+    score: number;
+}
+/**
+ * Owns session/transcript/checkpoint/spend/undo bookkeeping — the "everyday persistence" half of
+ * PersonalAssistant, split out in Phase 4d of the architecture remediation plan. `fileTools`/
+ * `shellTools` are the same shared option objects AgentLoop also holds (needed here for the
+ * shell-result-cache clear in clearSession, and the workspace lookup in undo/sweep) — not a
+ * duplication, just two collaborators independently needing the same read-only context.
+ */
+export declare class AssistantSession {
+    private readonly memory;
+    private readonly checkpointStore;
+    private readonly spendCap;
+    private readonly model;
+    private readonly fileTools;
+    private readonly shellTools;
+    private readonly actionTools;
+    private readonly notifiedContradictions;
+    constructor(memory: MemoryAdapter, checkpointStore: CheckpointStore, spendCap: SpendCapConfig | undefined, model: () => string | undefined, fileTools: FileToolsContext | undefined, shellTools: ShellToolsContext | undefined, actionTools: ActionToolsContext | undefined);
+    private static notifiedContradictionsKey;
+    getNotifiedContradictions(sessionId: string): Promise<Set<string>>;
+    recordNotifiedContradiction(sessionId: string, seen: Set<string>, value: string): Promise<void>;
+    /** findContradictionNotice's own text, deduped once per session — see notifiedContradictions'
+     * doc comment and findContradictionNotice's for why this exists: without it, the always-on
+     * lexical Contradiction layer re-fires the identical notice on every subsequent non-trivial
+     * turn, since the WorldModel it runs against is rebuilt fresh (re-seeded from all known facts)
+     * each turn with no memory of its own that this exact conflict was already surfaced. */
+    dedupedContradictionNotice(sessionId: string, layerActivity: LayerActivityEvent[], extraContradictions?: ExternalContradictionInput[]): Promise<string | undefined>;
+    /** Persisted alongside transcript/facts/plan (this.memory) — 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>;
+    /**
+     * Pre-turn spend-cap check — a no-op (`{ allowed: true }`) whenever no cap is configured. Only
+     * ever checked before a turn starts, never mid-turn (see spend-cap.ts's checkSpendCap doc
+     * comment) — `turn()` skips this entirely for a pendingActionId continuation, since that's a
+     * resumption of a turn that already passed this check when it first started.
+     */
+    checkSpendCapForTurn(sessionId: string): Promise<{
+        allowed: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Called once per successfully completed ('ok') turn — counts turns, not raw internal LLM
+     * calls (see SpendCapConfig's doc comment for why). Estimates cost the same way cli.ts's
+     * withCostEstimate does for a backend that doesn't report a real costUsd, so the cap enforces
+     * against the same number /cost displays, not a second cost model.
+     *
+     * Always records, even when no cap is currently configured — the ledger must reflect true
+     * cumulative spend regardless of whether a cap happens to exist yet, or a session that chats
+     * for a while uncapped and only later runs `/config set sessionCostLimitUsd ...` would have
+     * every turn before that point silently excluded from the cumulative total checkSpendCap
+     * enforces against, understating real spend. The enforcement gate itself (checkSpendCapForTurn)
+     * already correctly no-ops whenever no cap is configured, so this never enforces a cap that
+     * isn't set.
+     */
+    recordSpend(sessionId: string, usage: TokenUsage | undefined): Promise<void>;
+    /** Read-only — null means plan mode has never been entered (or was already exited/cancelled) for this session. */
+    getPlanModeState(sessionId: string): Promise<PlanModeState | null>;
+    /**
+     * The one place `planMode.active` ever flips true — a fresh `draftId` per entry, even if a
+     * prior drafting session was cancelled without ever reaching approval, so a stale draftId can
+     * never be mistaken for the current one. Idempotent to call again while already active (returns
+     * a new state, same as a fresh entry) — callers that only ever call this once per drafting
+     * session (P3's future auto-trigger) never observe that.
+     */
+    enterPlanMode(sessionId: string): Promise<PlanModeState>;
+    /** Clears `planMode.active` — the only two designed callers are an explicit cancel phrase (PlanDraftingService) and P2's future approval resolution. */
+    exitPlanMode(sessionId: string): Promise<void>;
+    /** The session's conversation transcript, oldest first — same array `turn()` reads/appends to. Used by `/export`. */
+    getTranscript(sessionId: string): Promise<ChatMessage[]>;
+    /**
+     * Reads `sessionId`'s transcript and runs it through transcript-compaction.ts's compactTranscript,
+     * persisting the compacted array back when compaction actually collapsed anything — the first
+     * thing `runTurn()` did with the raw transcript before this split. Kept on AssistantSession
+     * (rather than the sequencer reading `memory` directly) so this remains the one place that reads
+     * `transcript:${sessionId}` for a live turn.
+     */
+    loadAndCompactTranscript(sessionId: string): Promise<ChatMessage[]>;
+    /**
+     * Appends `message` to `transcriptKey`'s array — every site that used to call
+     * `this.memory.set(transcriptKey, message, 'append')` directly now goes through here instead, so
+     * a per-message search index entry (transcript-msg:<sessionId>:<n> — see messageIndexKey) is
+     * always written alongside it, with no call site able to forget. The index write is best-effort:
+     * caught and logged, never thrown — a search-indexing problem must never be able to break an
+     * ordinary turn or lose the transcript message itself.
+     */
+    appendTranscriptMessage(sessionId: string, transcriptKey: string, message: {
+        role: 'user' | 'assistant';
+        content: string;
+    }): Promise<void>;
+    /**
+     * One-off, idempotent backfill for installs that already had transcript history before the
+     * message index existed: scans every `transcript:*` session currently in `this.memory` and
+     * indexes whichever messages don't already have a `transcript-msg:` entry, so pre-existing
+     * conversations become searchable too, not just messages sent after this shipped. Guarded by
+     * MESSAGE_INDEX_BACKFILL_VERSION_KEY so it only does real work once per install (and once more
+     * per future version bump); a second call is a cheap no-op. Only covers what's still present in
+     * the live (possibly already-compacted) transcript array — a session already compacted before
+     * backfill ran has already lost its older messages the same way /search would, a known,
+     * documented limitation rather than a bug (see README).
+     *
+     * Run fire-and-forget from PersonalAssistant's constructor, never awaited by a turn — a large
+     * pre-existing history must not delay the first prompt/render.
+     */
+    backfillMessageIndex(): Promise<void>;
+    /**
+     * Prunes stale `.pending-actions/` records on startup. A leftover record is harmless (never
+     * applied without a matching id) but unbounded, so this keeps the directory from growing
+     * forever across crashed/abandoned turns.
+     *
+     * Safety-first, not per-record: `stagePendingAction`'s records carry no `sessionId` (the id is a
+     * random UUID, unrelated to any session — see file-tools.ts), so there is no direct way to tie
+     * one staged record to one session's checkpoint. Rather than sweep blind, this skips the sweep
+     * entirely for this startup if ANY known session still has a checkpoint eligible for resume —
+     * the coarser, but always-safe, version of "never sweep a record that could still be
+     * legitimately resumed". Known sessions are discovered the same way backfillMessageIndex
+     * already does (transcript: key prefixes), so no new bookkeeping is added.
+     */
+    sweepAbandonedPendingActionsOnStartup(): Promise<void>;
+    /**
+     * Records a message-level risk-gate decline (the `needs_approval` branch with no
+     * `pendingActionId`) as a resolved, paired exchange, once the caller (cli.ts) knows the final
+     * answer was "no". Unlike the eager-append this deliberately avoids inside runTurn itself (the
+     * outcome isn't known yet at that point), this is safe: both the user message and a "declined"
+     * reply are appended together, atomically, only after the decline is already final — there is
+     * never a dangling, un-replied-to turn a later tool-enabled call could mistake for a live
+     * request.
+     *
+     * Without this, a message-level decline (unlike a tool-call-level one, which resolvePendingAction
+     * already persists) left zero trace at all: a later "did that unsubscribe actually happen?"
+     * question found nothing in the transcript and confidently denied the request was ever made,
+     * instead of correctly recalling that it was asked and declined.
+     */
+    recordDeclinedRequest(sessionId: string, userMessage: string, reason: string): Promise<void>;
+    /**
+     * Ends the current conversation: deletes the transcript, extracted facts, any active plan for
+     * this session, and the shell-result cache (see file-tools.ts's shell-result-cache doc comment
+     * — a fresh conversation shouldn't silently answer from a previous, unrelated conversation's
+     * shell results), plus a leftover in-flight-turn checkpoint if one exists (from an abandoned
+     * turn that never reached its normal cleanup). Deliberately leaves
+     * `experienceStore`/`reminderStore`/DURABLE_FACTS_KEY untouched — those are durable,
+     * cross-conversation learning, not per-conversation scratch state (see the README's "Three
+     * things live outside a single harness run" section).
+     */
+    clearSession(sessionId: string): Promise<void>;
+    /**
+     * Scoped recovery for a stuck harness checkpoint: clears just `turn:${sessionId}`'s checkpoint
+     * (and its resume-attempt count) without touching transcript/facts/plan — unlike clearSession
+     * (`/clear`/`/new`), which wipes the whole conversation. Returns `{ cleared: false }` when there
+     * was nothing to clear, so a caller can report "nothing stuck" instead of a false "cleared".
+     */
+    clearCheckpoint(sessionId: string): Promise<{
+        cleared: boolean;
+        stepsUsed?: number;
+        currentNode?: string;
+    }>;
+    /**
+     * Read-only counterpart to clearCheckpoint — reports whether `sessionId` has a checkpoint left
+     * behind by a prior turn and how many times in a row it has already failed to resume, without
+     * clearing anything. Lets a caller (cli.ts's `/checkpoint`) inspect before deciding whether to
+     * clear.
+     */
+    getCheckpointStatus(sessionId: string): Promise<{
+        present: boolean;
+        stepsUsed?: number;
+        currentNode?: string;
+        failedResumeAttempts: number;
+    }>;
+    /**
+     * Removes the most recent exchange from conversation history — a completed turn drops its
+     * user message and assistant reply (2 entries); a turn that ended in `needs_approval` before
+     * any reply was appended drops just the pending user message (1 entry). Only affects what the
+     * model remembers: a real `write_file`/`run_shell_command` effect from the undone turn is not
+     * reversed. Returns `{ undone: false }` on an empty transcript instead of throwing.
+     */
+    undoLastTurn(sessionId: string): Promise<{
+        undone: boolean;
+    }>;
+    /** The workspace backend/root a staged write/shell/revert action lives under — `undefined` when neither fileTools nor shellTools is configured (e.g. a webTools-only assistant). Public: also used by ActionApprovalService for the same lookup. */
+    undoWorkspace(): {
+        backend: FsBackend;
+        workspaceRoot: string;
+    } | undefined;
+    /** Real filesystem effects still on record as revertible, newest first — bounded by action-snapshot.ts's UNDO_LOG_MAX_ENTRIES retention cap. Backs `/undo-action` with no argument. Distinct from `/undo` (undoLastTurn above), which only forgets conversation history — see README's /undo-action section for the naming distinction. */
+    listUndoLogEntries(): Promise<UndoLogEntry[]>;
+    /**
+     * Stages a revert of undo-log entry `id` as its own approval-gated `PendingActionPayload` —
+     * reusing the exact same staging/approval machinery write_file/run_shell_command already use,
+     * rather than a new confirmation concept. Approve/decline it the same way any other staged
+     * action resolves: `turn('', { sessionId, approved, pendingActionId })`.
+     */
+    stageUndoAction(id: string): Promise<{
+        status: 'staged';
+        pendingActionId: string;
+        reason: string;
+    } | {
+        status: 'error';
+        message: string;
+    }>;
+    /**
+     * Ranked search over the per-message index (see appendTranscriptMessage/IndexedMessage), not
+     * the whole session transcript — a hit resolves to the one exchange that matched. Deliberately
+     * not scoped to a single sessionId: this is a single local install's memory namespace, and
+     * "what did I tell you about my dentist appointment" should find it regardless of which
+     * session it was said in.
+     *
+     * `MemoryAdapter.search()` scores every stored key in one pass (facts, reminders, experience
+     * data, the message index itself, its counters, ...), so this asks for every entry scoring
+     * above 0 rather than a small topK directly, then filters to `transcript-msg:` keys and
+     * truncates afterward — otherwise a real match could be pushed out of a small topK by
+     * unrelated non-transcript entries that happen to score higher. Read-only and synchronous over
+     * already-persisted data: never an LLM call, never a network request, never a mutation. Used
+     * by `/search`.
+     *
+     * `FileSystemAdapter.search()` (packages/runtime) throws if ANY file under the memory namespace
+     * fails to parse as JSON — e.g. a transcript file left truncated by a process kill mid-write.
+     * One corrupt entry unrelated to this query must not turn `/search` into an uncaught error for
+     * the user — degrade to "no results" instead, same fail-open posture as the other two
+     * `memory.search()` call sites (backfillMessageIndex, sweepAbandonedPendingActionsOnStartup).
+     */
+    searchTranscript(query: string, topK?: number): Promise<TranscriptSearchHit[]>;
+}

package/dist/assistant-source.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A real, non-mutating tool call the model made while producing a reply — grounds a reply in something other
+ * than the model's own words. write_file is deliberately excluded: until approved, nothing was actually read or
+ * changed. `path` holds the file path for read_file/list_directory, the URL for fetch_url, or the query for
+ * web_search — same shape, different meaning per tool, to keep this interface minimal.
+ *
+ * Split into its own file (rather than living on assistant.ts or agent-loop.ts) so both can import it without
+ * either owning it — AgentLoop produces AssistantSource entries while executing tool calls, and assistant.ts's
+ * public AssistantTurnResult.sources field is typed with it.
+ */
+export interface AssistantSource {
+    tool: 'read_file' | 'list_directory' | 'web_search' | 'fetch_url';
+    path: string;
+}

package/dist/assistant-types.d.ts

@@ -0,0 +1,158 @@
+import { RiskState, LayerActivityEvent, AskQuestion } from '@buildaharness/harness';
+import { TokenUsage } from '@buildaharness/runtime';
+import { AnswerClaim } from './answer-claim.js';
+import { TurnIntentClassification } from './turn-intent-classifier.js';
+import { AssistantSource } from './assistant-source.js';
+import { BatchBudgetTrace } from './agent-loop.js';
+import { PlanPosition } from './plan-store.js';
+/**
+ * The public result/progress shapes every extracted module (ActionApprovalService,
+ * TurnInterpreter, HarnessBridge, ResponseService) builds or consumes — split into its own file
+ * so those modules can depend on the shapes without depending on assistant.ts itself (which, in
+ * turn, depends on all of them to assemble the sequencer). assistant.ts re-exports these under
+ * their original names for full backward compatibility with existing imports
+ * (index.ts/cli.ts/cli-session.ts/assistant.test.ts).
+ */
+export interface AssistantTrace {
+    nodeExecutionOrder: string[];
+    verificationHealth: {
+        strength: number;
+        feasibility: number;
+    };
+    /** Every one of the 11 harness layers' fired/skipped report for this turn — see LayerActivityEvent. Powers the "Why?" panel's "What I checked" list and the 11-layer status grid. */
+    layerActivity: LayerActivityEvent[];
+    /**
+     * Present only when the batch-research path (batch-list-detector.ts / AgentLoop.runBatchToolLoop)
+     * drove this turn — absent otherwise, same "absent when unused" convention as sources/usage.
+     */
+    batchBudget?: BatchBudgetTrace;
+}
+/**
+ * Which code path actually produced this turn's reply — a test/telemetry affordance for
+ * plans/chat_ui_browser_e2e_plan.html phase B1 (the browser-e2e lane that unblocks the
+ * ASSISTANT_ONE_LOOP default-flip, R5 of the D2 one-loop rewire). The reply text itself is
+ * identical across all three by design (INV-19); this field is how a test asserts "the flag
+ * changed which path ran" without diffing internal traces.
+ *
+ * - 'posthoc'       — flag OFF (or a trivial / no-tool turn): AgentLoop.runToolLoop finished a
+ *                     draftReply before HarnessBridge constructed HarnessRuntime; the harness run
+ *                     is post-hoc bookkeeping over an already-produced reply.
+ * - 'flat-oneloop'  — flag ON, non-batch: the flat tool loop ran inside the harness's own
+ *                     driveMainLoop via AgentLoop.createOneLoopProposer.
+ * - 'batch-oneloop' — flag ON, batch-research: AgentLoop.createBatchOneLoopProposer drove the
+ *                     probe→calibrate→confirm→resolve→synthesize sequence under driveMainLoop.
+ */
+export type ProposerKind = 'posthoc' | 'flat-oneloop' | 'batch-oneloop';
+export interface AssistantTurnResult {
+    /**
+     * `needs_clarification` (Q2 of plans/ask_question_and_plan_mode_plan.html): a structured
+     * ask-question escalation (a populated `EscalationHalt.blocker.questions`, Q0) was staged for
+     * resume via AskClarificationService instead of terminating the turn — pass
+     * `pendingClarificationId` + a completed `AskResponse` back into
+     * `turn(message, { pendingClarificationId, clarificationAnswer })` to resolve it. Only reachable
+     * when the effective askMode (Q1's three-tier INV-29 resolution) is enabled; flag-off leaves
+     * every escalation on the pre-existing `escalated`/`reply: null` path, byte-identical to today.
+     */
+    /**
+     * `needs_plan_approval` (P2 of plans/ask_question_and_plan_mode_plan.html): a drafted plan
+     * (plan mode's P1/P3) was staged for the mandatory whole-plan approval gate instead of
+     * continuing to revise — pass `planApprovalId` back into
+     * `turn(message, { planApprovalId, planDecision, edits? })` to resolve it. Every drafted plan
+     * passes through this exactly once, regardless of risk (no risk-tiered skip — see
+     * PlanApprovalService's doc comment).
+     */
+    status: 'ok' | 'needs_approval' | 'escalated' | 'needs_clarification' | 'needs_plan_approval';
+    reply: string | null;
+    reason?: string;
+    /** See ProposerKind. Always set (defaults to 'posthoc'), on every status. */
+    proposerKind?: ProposerKind;
+    riskLevel?: TurnIntentClassification['riskLevel'];
+    controlState?: {
+        riskState: RiskState;
+        escalationReason: string | null;
+    };
+    stepsUsed?: number;
+    /** True when the turn was answered by the triviality fast path — no HarnessRuntime.run() this turn. */
+    harnessSkipped?: boolean;
+    /** Structured harness telemetry for a "Why?" disclosure — the step sequence and verification confidence, not free-text reasoning. */
+    trace?: AssistantTrace;
+    /** Set only when `needs_approval` was triggered by a `write_file`/`run_shell_command`/`send_email` tool call — pass back into `turn(message, { approved, pendingActionId })` to apply or discard it. */
+    pendingActionId?: string;
+    /** Which kind of action `pendingActionId` refers to — a write shows path + content preview, a shell command shows the exact command + resolved cwd, an email shows recipient + subject + body, a batch confirmation shows the projected remaining search count, a revert (staged only via /undo-action, never by the model) shows which paths will be restored/removed. */
+    pendingActionKind?: 'write' | 'shell' | 'email' | 'batch' | 'revert';
+    /** Real read_file/list_directory calls made while producing this reply, in call order. Only set when fileTools is configured and at least one such call happened this turn. */
+    sources?: AssistantSource[];
+    /**
+     * Structured, durable plan progress — present whenever a templated plan (new or
+     * resumed) drove this turn's initialTasks, absent otherwise (same "absent when
+     * unused" convention as trace/sources). Unlike trace, this can be non-null across
+     * many consecutive turns in the same session: the plan persists in `memory` until
+     * every task is COMPLETE or the user abandons it. See plan-store.ts.
+     */
+    planStatus?: {
+        templateName: string | null;
+        successCriteria: string;
+        completionPct: number;
+        tasks: {
+            id: string;
+            description: string;
+            status: string;
+        }[];
+    };
+    /**
+     * Token usage accumulated across every real LLM call this turn made (can be more than one:
+     * decomposition, plan-building, up to maxSteps tool-loop round trips).
+     * Absent when the backend/response never reported usage at all (e.g. the claude-cli backend
+     * with no usage field) — same "absent when unused" convention as trace/sources. Never set on
+     * needs_approval/escalated, matching how trace/sources already behave.
+     */
+    usage?: TokenUsage;
+    /** Set when the Contradiction layer flagged a conflict with an existing belief this turn — see assistant-session.ts's findContradictionNotice doc comment for why this is a separate field instead of folded into `reply`. */
+    contradictionNotice?: string;
+    /**
+     * An epistemic-honesty signal for replies that went through the harness loop (absent on the
+     * triviality fast path, same "absent when unused" convention as trace/sources — a
+     * harness-skipped reply has no verification/evidence trail to attach). See answer-claim.ts's
+     * doc comment for how each field is derived.
+     */
+    answerClaim?: AnswerClaim;
+    /**
+     * Set only on a plan-pacing pause — the "Ready to continue with: ...?"/"All plan steps have
+     * run..." text appended to `reply` after the model's own draftReply. A caller that streamed
+     * `reply` token-by-token via `onToken` (see TurnOptions.onToken) already showed draftReply
+     * live and must print this separately, since draftReply is all `onToken` ever saw — this text
+     * is computed after the harness run completes, well after streaming finished.
+     */
+    pausedNote?: string;
+    /** Set only on `status: 'needs_clarification'` — pass back into `turn(message, { pendingClarificationId, clarificationAnswer })` to resolve it. See AskClarificationService. */
+    pendingClarificationId?: string;
+    /** The batch of questions `pendingClarificationId` refers to — set only on `status: 'needs_clarification'`, absent otherwise (same "absent when unused" convention as trace/sources). */
+    questions?: AskQuestion[];
+    /** Set only on `status: 'needs_plan_approval'` — pass back into `turn(message, { planApprovalId, planDecision, edits? })` to resolve it. See PlanApprovalService. */
+    planApprovalId?: string;
+    /**
+     * The staged plan `planApprovalId` refers to — set only on `status: 'needs_plan_approval'`,
+     * absent otherwise (same "absent when unused" convention as trace/sources). Each task's own
+     * `riskLevel` is included so an approval screen can show it prominently even though nothing
+     * about risk ever skips this gate (Section 5b-2). `reviewNotes` stays absent until P6's
+     * self-verification pass exists.
+     */
+    planApproval?: {
+        templateName: string | null;
+        successCriteria: string;
+        rationale: string;
+        tasks: {
+            id: string;
+            description: string;
+            riskLevel?: 'LOW' | 'MEDIUM' | 'HIGH';
+        }[];
+        reviewNotes?: string[];
+    };
+}
+export interface AssistantProgress {
+    stepsUsed: number;
+    maxSteps: number;
+    currentNode?: string;
+    /** Live, mid-run position within a durable plan — set only while a plan is actually driving this turn. Absent for an ad hoc single-task/decomposed turn, same "absent when unused" convention as AssistantTurnResult.planStatus. */
+    planPosition?: PlanPosition;
+}