@buildaharness/aielia 0.3.4 → 0.3.6

package/dist/assistant.d.ts

@@ -1,4 +1,4 @@
-import { ExperienceStore, CheckpointStore, AskResponse } from '@buildaharness/harness';
+import { ExperienceStore, CheckpointStore, AskResponse, LayerPolicyMode } from '@buildaharness/harness';
 import { MemoryAdapter, ILLMClient, ChatMessage, ReminderStore } from '@buildaharness/runtime';
 import { FileToolsContext } from './file-tools.js';
 import { UndoLogEntry } from './action-snapshot.js';
@@ -8,13 +8,18 @@ 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 { MemoryService, MemorySummary, MemoryExport, AuditEntry, MemoryStatus, MemoryInjection, ConsolidationOutcome } from './memory-service.js';
+import { MemoryWriteMode } from './memory-governance.js';
+import { ConsolidationProposal } from './memory-consolidation.js';
 import { UserFact } from './fact-extraction.js';
 import { TranscriptSearchHit } from './assistant-session.js';
+import { SessionDigest } from './episodic-digest.js';
 import { PlanDecision, PlanApprovalEdits } from './plan-approval-service.js';
 import { PlanRecord } from './plan-store.js';
+import { GoalGraphRecord } from './goal-graph-store.js';
 import { OneLoopMode } from './one-loop-flag.js';
 import { AskMode } from './ask-mode-flag.js';
+import { AmbiguityGuardMode } from './ambiguity-guard-flag.js';
 import { PlanRolloutMode } from './plan-mode-flag.js';
 import { GoalGraphSuggestMode } from './goal-graph-suggest-flag.js';
 import { GoalGraphState } from './goal-graph-service.js';
@@ -43,6 +48,10 @@ export type MemoryPendingOutcome = {
 };
 export interface TurnOptions {
     sessionId?: string;
+    /** Internal: this turn is the one-time correction the reply audit asked for; it is not a user message and is never retried again. */
+    auditRetry?: boolean;
+    /** M4: a scripted / piped / batch caller. The post-turn memory reviewer is skipped for it (it only runs for an interactive session). */
+    nonInteractive?: boolean;
     approved?: boolean;
     pendingActionId?: string;
     /**
@@ -73,6 +82,12 @@ export interface TurnOptions {
      * flag is off.
      */
     askMode?: AskMode;
+    /**
+     * Stops the turn: once it fires, no further model call starts or is kept, the transcript is left as it was before
+     * the turn, and `turn()` resolves with `status: 'cancelled'` right away. Ignored when resuming a staged action
+     * (`pendingActionId`), because that applies a write/shell/email the user already approved and must not be half-done.
+     */
+    signal?: AbortSignal;
     onProgress?: (progress: AssistantProgress) => void;
     /**
      * Called with each token as the model's reply streams in. On the plain chat
@@ -97,7 +112,7 @@ export interface TurnOptions {
      */
     onToolStep?: (step: AssistantToolStep) => void;
     /**
-     * **Eval harness only** (`packages/aielia/eval/`). Wraps the one-loop
+     * **Benchmark harness only.** 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
@@ -108,6 +123,7 @@ export interface TurnOptions {
         failIterations: number;
         seedFailures: number;
         onInjected?: () => void;
+        symptom?: string;
     };
     /**
      * Phase 4 of plans/hierarchical_goal_tree_and_steering_plan.html (R1/R4) — the session-scoped
@@ -137,6 +153,14 @@ export interface PersonalAssistantOptions {
      * fresh install with no workspace concept at all.
      */
     activeProject?: string;
+    /** M1: character budget for the facts block under `AUDIT_MEMORY_BUDGETED_RENDER` — see config.ts's `memoryBudgetChars`. */
+    memoryBudgetChars?: number;
+    /** M6: where model-originated memory writes may land (`auto`/`staged`/`user_only`, default `staged`) — see memory-governance.ts. Changeable live via `setMemoryWriteMode`. */
+    memoryWriteMode?: MemoryWriteMode;
+    /**
+     * M5: run memory consolidation in the background on `/new` (`clearSession`). Off unless the host sets it: the CLI does; chat-ui must not until M6's pending-queue controls exist (D1 stages every proposal, and a browser user could not review one). Still gated by `AUDIT_MEMORY_CONSOLIDATION`.
+     */
+    consolidateOnNewSession?: boolean;
     /** 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. */
@@ -226,6 +250,8 @@ export interface PersonalAssistantOptions {
      * call resolveOneLoopMode(process.env) and pass the result here.
      */
     oneLoopMode?: OneLoopMode;
+    /** AL8a — layer policy mode ('static' default = today's behaviour). Resolved by the surface via resolveLayerPolicyMode; PersonalAssistant never reads process.env for it. */
+    layerPolicyMode?: LayerPolicyMode;
     /**
      * R7 (Tier 1.5) — next-step suggestions, one bounded LLM call each: after every full
      * (non-trivial, `ok`) turn, up to three options are attached to the result as `nextSteps` for
@@ -236,6 +262,8 @@ export interface PersonalAssistantOptions {
      * that never asks for suggestions makes no extra call and sees no new field (INV-43).
      */
     goalGraphSuggestMode?: GoalGraphSuggestMode;
+    /** Run the reply audit (reply-audit.ts) after each successful turn; defaults to the AIELIA_REPLY_AUDIT env gate (on). */
+    replyAudit?: boolean;
     /**
      * Q2 of the internal plan — global-flag control point (tier 1 of
      * INV-29) for the ask-question mechanism. Undefined (the default) falls back to
@@ -256,6 +284,13 @@ export interface PersonalAssistantOptions {
      * resolvePlanMode(process.env)/normalizePlanMode(import.meta.env...) and pass the result here.
      */
     planMode?: PlanRolloutMode;
+    /**
+     * AL3a — see ambiguity-guard-flag.ts. Absent/'disabled' (the default): routing is byte-identical to
+     * before. 'enabled': a consequential turn whose request doesn't determine the action gets a
+     * clarifying question instead of a staged guess. PersonalAssistant never reads process.env; the
+     * surface entry point resolves ASSISTANT_AMBIGUITY_GUARD / `/config set ambiguityGuardMode`.
+     */
+    ambiguityGuardMode?: AmbiguityGuardMode;
 }
 /**
  * A light, everyday-use wrapper around HarnessRuntime: one harness run per chat turn,
@@ -275,8 +310,14 @@ export interface PersonalAssistantOptions {
  */
 export declare class PersonalAssistant {
     private readonly llmClient;
+    private readonly abortGate;
+    /** A stopped turn whose in-flight model call has not come back yet. Its gate stays armed until it settles, so it cannot write the transcript late. */
+    private stoppedWork?;
     private model?;
     private activeProject?;
+    private memoryBudgetChars?;
+    private memoryWriteMode;
+    private consolidateOnNewSession;
     private readonly memory;
     private readonly webTools?;
     private readonly onTrace?;
@@ -286,6 +327,7 @@ export declare class PersonalAssistant {
     private readonly toolLoopWillRun;
     /** R3 of the internal plan — 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;
+    private readonly layerPolicyMode;
     /** 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. */
@@ -301,9 +343,24 @@ export declare class PersonalAssistant {
     /** See PersonalAssistantOptions.goalGraphSuggestMode. */
     private readonly goalGraphSuggestMode;
     private readonly memoryService;
+    /** M4 post-turn cross-turn memory reviewer; inert unless `AUDIT_MEMORY_REVIEWER` is on. */
+    private readonly memoryReviewer;
     private readonly session;
     private readonly agentLoop;
     private readonly actionApproval;
+    /** Set when the reply was already logged by the reply-ready hook this turn (see AssistantSession.replyReadyHook). */
+    private replyLoggedEarly;
+    /** Automatic correction retries still allowed for the current user message; resumed (approval) turns share it so a retry cannot chain. */
+    private auditRetryBudget;
+    /** The session of the turn in progress, for log lines written by code that has no session of its own (the side-call retry note). */
+    private lastSessionId;
+    /** The last real (not fail-safe) risk classification of a user message, per session, for the audit retry that may correct its reply. */
+    private readonly lastClassifiedBySession;
+    /** Files, directories and pages each session's turns have read (tool and target, oldest first, capped): the reply audit needs reads from EARLIER turns too, or a correct answer about a file read last turn looks like an unverified outside fact (V1). In memory only; cleared with the session. */
+    private readonly sourcesReadBySession;
+    /** Index into the action list where the current user message's actions start; an approval resume is a separate turn() call but the same user message. */
+    private userMessageActionsStart;
+    private readonly replyAuditOn;
     private readonly planService;
     private readonly planApproval;
     private readonly planDrafting;
@@ -321,12 +378,31 @@ export declare class PersonalAssistant {
      * PersonalAssistant(...)` outside a browser (e.g. the CLI).
      */
     static create(options: PersonalAssistantOptions): Promise<PersonalAssistant>;
+    /**
+     * The bigger picture both next-step proposers get (see next-step-context.ts): earlier
+     * conversation, the steps taken this turn, and every goal thread the session tracks. Best-effort —
+     * any read failure just yields no extra context, never a failed turn. At turn end the focus
+     * thread is the one the graph currently marks active; for a thread that just finished it is that
+     * thread.
+     */
+    private nextStepContext;
+    /** Logs a message that arrived while a turn was running, at receipt time (its `user_message` is only logged when it is processed). */
+    logQueuedMessage(sessionId: string, message: string): void;
     /**
      * 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>;
+    /**
+     * M4: after a delivered, ordinary interactive reply, counts the turn and (every N turns without a memory write) starts the
+     * cross-turn memory review in the background. Not awaited: the reply is already on its way. Skipped for non-interactive and
+     * batch-research turns, and when the layer policy switched the layer off. Its spend is recorded through the same
+     * `recordSpend` path as the turn's own, so `/cost` and the spend cap include it.
+     */
+    private maybeStartMemoryReview;
+    /** Resolves when any in-flight background memory review has finished (a host about to exit, or a test). */
+    awaitMemoryReview(): Promise<void>;
     /** 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`. */
@@ -338,7 +414,48 @@ export declare class PersonalAssistant {
      */
     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. */
+    /** Remembers what a turn read (tool and target) for the reply audit of later turns; oldest entries drop first. */
+    private noteSourcesRead;
     clearSession(sessionId: string): Promise<void>;
+    /** M5: propose memory consolidation (applies nothing). `manual` forces the model pass past the cost gate. Usage is recorded against the spend state like any other call. */
+    proposeMemoryConsolidation(sessionId: string, manual?: boolean): Promise<Awaited<ReturnType<MemoryService['runConsolidation']>>>;
+    /** The consolidator MemoryService.consolidate() runs for `/memory consolidate` (chat-ui's button): runs the proposal pass now and reports; applying anything is still the user's accept. */
+    private runRegisteredConsolidation;
+    /** M5: staged proposals awaiting the user. */
+    memoryProposals(): Promise<ConsolidationProposal[]>;
+    /** M5: `/memory consolidate accept <n>` (1-based). */
+    acceptMemoryProposal(selector: string, sessionId: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** M5: `/memory consolidate dismiss <n>` (1-based). */
+    dismissMemoryProposal(selector: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** How many entries at the head of `listArchivedFacts()` were set aside by staged forgetting (M5) and can be restored; the rest were replaced by a newer statement. */
+    restorableArchiveCount(): Promise<number>;
+    /** `/memory archive restore <n>` (1-based, over the same numbered listing as `/memory archive`). */
+    restoreArchivedMemory(selector: string, sessionId: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /**
+     * M3 session edge: with AUDIT_EPISODIC_DIGEST on, writes the conversation's handoff digest (one bounded call, fail-open)
+     * for the current conversation (the rolling digest is refreshed, not duplicated, if the same conversation is digested again). `clearSession` (/new) calls it, then ends the conversation's digest identity; the CLI calls it on exit; never from inside a turn.
+     * With the flag off this does nothing, so the old behaviour is untouched.
+     */
+    endSession(sessionId: string): Promise<void>;
+    /** Stored episodic digests (newest first), for the memory panel and `/memory`; read-only. */
+    listSessionDigests(): Promise<SessionDigest[]>;
+    /** Which optional memory writers are switched on for this process (their `AUDIT_*` flags): hosts use it to show or hide the matching controls. A writer that is off makes no model call and no write. */
+    memoryWriterFlags(): {
+        reviewer: boolean;
+        consolidation: boolean;
+        digest: boolean;
+    };
+    /** M3 (D4): `/memory forget digest <id>` or all digests when `id` is omitted; returns how many were removed. */
+    forgetDigests(id?: string): Promise<number>;
     /**
      * P1 of the internal plan — explicit entry point into plan mode's
      * exclusive drafting state. No production caller yet: P3 will later set this automatically from
@@ -369,6 +486,11 @@ export declare class PersonalAssistant {
      * goal graph yet, same "nothing to show" convention `getGoalGraphState` itself documents.
      */
     getGoalGraphState(sessionId: string): Promise<GoalGraphState>;
+    /**
+     * Read-only source for the plan graph view: the session's goal graph when it has threads, else its
+     * plan record, else `null`. Never throws and never creates a record.
+     */
+    getPlanGraph(sessionId: string): Promise<PlanRecord | GoalGraphRecord | null>;
     /**
      * P9 of the internal plan — the lightweight plan-sketch delegate: a
      * cheaper "just go research and draft an approach" path than plan mode's durable task-graph
@@ -427,9 +549,39 @@ export declare class PersonalAssistant {
      * 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>;
+     * REJECTED_FACTS_KEY — see MemoryService.forgetFact's doc comment. By default the removal is recorded
+     * in the audit log with the fact's text (so `/memory undo` can restore it); `erase` also scrubs that text.
+     */
+    forgetFact(selector: string, sessionId: string, erase?: boolean): Promise<MemoryPendingOutcome>;
+    /** `/memory history` — the newest audit-log entries (M2). Empty unless `AUDIT_MEMORY_AUDIT_LOG` is on. */
+    memoryHistory(limit?: number): Promise<AuditEntry[]>;
+    /** `/memory undo <seq>` — restores the pre-image of one audit entry (M2). */
+    undoMemoryChange(selector: string, sessionId: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** `/memory` governance mode (M6) — takes effect on the next write. */
+    getMemoryWriteMode(): MemoryWriteMode;
+    /** Live mode change (CLI `/config set` reloads the assistant; chat-ui calls this directly). Unknown values keep the default rather than widening write authority. */
+    setMemoryWriteMode(mode: MemoryWriteMode | string): void;
+    /** `/memory off` / `/memory on` — stop or resume all memory writes (facts, pending queue, digests, reviewer, consolidation) for this install. Existing data stays readable and removable. */
+    setMemoryEnabled(enabled: boolean): Promise<void>;
+    isMemoryEnabled(): Promise<boolean>;
+    /** Store size vs budget, pending/audit counts, last consolidation, governance state — `/doctor` and the memory panel. Read-only. */
+    getMemoryStatus(sessionId: string): Promise<MemoryStatus>;
+    /** The facts the last turn's prompt actually contained, plus how many were left out — the "Why?" panel / `/why` line. Undefined before the first turn. */
+    getLastMemoryInjection(): MemoryInjection | undefined;
+    /** `/memory archive` — entries set aside by staged forgetting (restorable, first) then entries a keyed update replaced (newest first). */
+    listArchivedFacts(): Promise<UserFact[]>;
+    /** `/memory archive forget <n>` — permanently erases one archived entry and its history pre-images. */
+    forgetArchivedFact(selector: string): Promise<MemoryPendingOutcome>;
+    /** `/memory consolidate` — runs the registered consolidator (M5). Until M5 registers one this reports `unavailable`. */
+    consolidateMemory(sessionId: string): Promise<ConsolidationOutcome | {
+        status: 'unavailable' | 'blocked';
+        message: string;
+    }>;
+    /** M5 hook: lets the consolidation phase plug in without touching the surfaces. */
+    registerMemoryConsolidator(fn: Parameters<MemoryService['registerConsolidator']>[0]): void;
     /** 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. */
@@ -447,6 +599,8 @@ export declare class PersonalAssistant {
      * plan-cancel bypass, the triviality fast path) actually lives now.
      */
     private runTurn;
+    /** What ActionApprovalService needs to continue a paused tool loop after an approval: the live callbacks, and how a further pause becomes a turn result. */
+    private loopResumeOptions;
     /**
      * 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

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

@@ -21,6 +21,12 @@ export interface InjectedFailureOptions {
      * the internal plan F2).
      */
     onInjected?: () => void;
+    /**
+     * The failure symptom text (a paraphrase of a known class, a missing resource, a rate limit…).
+     * Becomes the seeded records' description, the observation and the failed execution's error, so
+     * failure matching sees the task's own wording. Absent = the generic ETIMEDOUT text.
+     */
+    symptom?: string;
 }
 type Proposer = (toolCtx: ToolExecutorContext) => unknown | Promise<unknown>;
 export declare function wrapProposerWithInjectedFailure(realProposer: Proposer, opts: InjectedFailureOptions): (toolCtx: ToolExecutorContext) => Promise<unknown>;