@itookit/dsht 0.5.1 → 0.6.0

package/dist/controller/controller.d.ts

@@ -5,7 +5,7 @@ import { type HistoryLimits } from '../session/memory.ts';
 import { type SessionRender } from '../session/history.ts';
 import { SessionController } from '../session/controller.ts';
 import { CatalogController } from '../catalog/controller.ts';
-import type { Telemetry } from '../session/telemetry.ts';
+import type { TelemetryReader } from '../session/telemetry.ts';
 import type { Transcript } from '../session/transcript.ts';
 import type { CostLedger } from '../cost/ledger.ts';
 import { CostController } from '../cost/controller.ts';
@@ -14,8 +14,8 @@ import { MemoryLog } from './memory-log.ts';
 import { TraceLog } from './trace-log.ts';
 import { PromptStore } from './prompts.ts';
 import { type LoopLimits, type LoopProtocol } from './loop.ts';
-import { type VerifierPort } from './verifier.ts';
-import type { ClientActivity, ForegroundKind, ForegroundSnapshot, LoopProgress, LoopRecord, OutputSource, PeekSnapshot } from '../contracts.ts';
+import type { VerifierPort } from './verifier.ts';
+import type { ClientActivity, ForegroundKind, ForegroundSnapshot, LoopProgress, LoopRecord, LoopSourceInfo, OutputSource, PeekSnapshot } from '../contracts.ts';
 import { SessionPeek } from '../session/peek.ts';
 import { type ControllerStore, type State } from '../state.ts';
 import { ShellController } from '../shell/index.ts';
@@ -24,13 +24,13 @@ import type { SavedPrompt } from '../contracts.ts';
 import type { FileReference } from '../session/references.ts';
 import type { InteractionState, OptionState } from '../session/info.ts';
 import type { Reasoning } from '../session/history.ts';
-/** Mutating operations the UI drives; each runs in the client's single foreground slot. */
+/** Mutating operations: foreground work, local edits, and control cancellation with its own admission. */
 export interface Actions {
     /** Claim the single foreground slot for work the front end orchestrates itself (paging, loading).
      *
      * The controller owns the slot, the abort controller and the identity; the front end only supplies
      * the work and renders `queries.foreground`. Returns undefined when the client is busy with another
-     * operation or when this one was cancelled.
+     * operation or the client has stopped. Admitted work keeps its result/error on cancellation.
      */
     foreground<T>(kind: ForegroundKind, label: string, work: (signal: AbortSignal) => Promise<T>, wait?: boolean): Promise<T | undefined>;
     /** Cancel the operation that owns the slot; false when none is running. */
@@ -80,6 +80,7 @@ export interface Actions {
     /** Repeated keys share one cancellation; it reports exit eligibility itself. */
     interrupt(force?: boolean): Promise<boolean>;
     older(signal?: AbortSignal, transcript?: Transcript): Promise<boolean>;
+    openHistory(target: number, signal: AbortSignal): Promise<boolean>;
     historyThrough(target: number | 'first', signal: AbortSignal): Promise<boolean>;
     removeQueued(itemId: string): Promise<boolean>;
     /** Local shortcut prompts: no connection and no busy envelope, since they never reach the host. */
@@ -100,7 +101,7 @@ export interface Actions {
     pickWorkspace(workspaceId?: string): void;
     /** Leave a picker and return to the selected conversation; false when none is selected. */
     showChat(): boolean;
-    setViewWindow(window?: Transcript): void;
+    showLatest(): void;
     pinHistory(pinned: boolean): void;
     setAnswers(answers: Record<string, AnswerValue['answers']>): void;
     setOption(option?: OptionState): void;
@@ -128,7 +129,7 @@ export interface Queries {
     readonly record: Transcript;
     readonly window: Transcript | undefined;
     readonly interaction: InteractionState;
-    readonly telemetry: Telemetry;
+    readonly telemetry: TelemetryReader;
     readonly recallAtOldest: boolean;
     readonly recallLength: number;
     readonly recallHasOlder: boolean;
@@ -146,12 +147,13 @@ export interface Queries {
     readonly peek: PeekSnapshot | undefined;
     /** Every `loop.yaml` record, so the picker can offer names and their defaults without a lookup. */
     readonly loopRecords: readonly LoopRecord[];
+    /** Where those records came from, so the picker can say which file supplied or replaced them. */
+    readonly loopSource: LoopSourceInfo;
     /** Why the saved prompts could not be read, when the file was malformed. */
     readonly promptsError: string | undefined;
     pendingCounts(): ReadonlyMap<string, number>;
     recall(direction: -1 | 1, current: string): string;
     references(query: string, signal: AbortSignal): Promise<FileReference[]>;
-    historyAt(target: number, signal: AbortSignal): Promise<Transcript>;
     /** Plain rows and offsets for one laid-out record. */
     render(input: {
         transcript: Transcript;
@@ -221,50 +223,12 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     readonly trace: TraceLog | undefined;
     /** Shortcut prompts the operator saved; in memory for this run when no path was supplied. */
     readonly promptStore: PromptStore;
-    /** Running agent loop, if any; the loop lives here, not in the UI. */
-    private loop?;
-    /** Prompt the loop still has to send, when it could not be sent immediately. */
-    private loopPrompt?;
     /** Finished turns of the selected session, so a waiter never has to sample a cached flag. */
     private completedTurns;
     /** Sessions the host reported busy, so a lone idle frame cannot claim a finished turn. */
     private readonly busySessions;
-    /** When the in-flight attempt's turn ended, while its result block is still awaited. */
-    private loopEndedAt?;
-    /** Timer that settles an attempt whose reply never commits its result block. */
-    private loopSettleTimer?;
-    /** Whether an attempt is currently being judged by an independent verifier. */
-    private loopVerifying;
-    /** A verdict is being consumed right now.
-     *
-     * Consuming one reads the artifact, so it is asynchronous; without this gate a replayed idle edge
-     * could start a second verification of an attempt whose verdict is already being applied.
-     */
-    private loopSettling;
-    /** Cancels that verification when the loop is stopped or replaced. */
-    private loopVerifyAbort?;
-    /** Verdict of the previous attempt on the current step, for the retry and the next verifier. */
-    private loopPrevious?;
-    /** Identity of the run in flight, so its verdicts are isolated from every other run's. */
-    private loopRunId?;
-    /** Whether the run in flight already wrote its `loop end`; one end per begin (I9). */
-    private loopEndTraced;
-    /** Sequence of the verification task in flight, so a retry never reuses the old task's identity. */
-    private loopVerifySeq;
-    /** Identity of the verification task whose result may still decide the attempt in flight. */
-    private loopVerifyIdentity?;
-    /** Timer that stops the whole run when its budget expires. */
-    private loopDeadlineTimer?;
-    /** Whole-run budget, when the operator set one. */
-    private readonly deadlineMs?;
-    /** Consecutive verifier outages in this attempt, so a broken verifier is retried then reported. */
-    private loopVerifierMisses;
-    /** What the operator answered when a verifier abstained; consumed by the next judgment. */
-    private loopAnswer?;
-    /** Whether a reply block may stand in for a missing verdict; off unless asked for. */
-    private readonly allowSelfFallback;
-    /** Client-side directory verdict files are written under. */
-    private readonly verdictRoot;
+    /** Loop execution owns all verifier, settling and deadline state. */
+    private readonly loops;
     /** Local `!` commands, run on this machine and shown inline in the transcript. */
     readonly shell: ShellController;
     /** Mutating surface the UI drives. */
@@ -281,26 +245,17 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     readonly memoryLogPath: string | undefined;
     /** Directory this client runs in. */
     readonly localDirectory: string;
-    /** Independent verifier for scored rounds, when one was supplied. */
-    private readonly verifier;
     /** Session opened at startup, when one was named. */
     private readonly initialSession;
     private readonly observers;
     private selector;
     private connectionSettled;
+    /** Startup defaults apply once; subsequent generations restore the operator's selection. */
+    private initialized;
     /** Counter behind `commandId`, so every executed line has one identifier in begin and end. */
     private commandSeq;
-    /** The operation that owns the client right now, when one does; the single foreground slot. */
-    private foreground?;
-    /** Callers waiting for the slot, oldest first; woken one at a time so nobody barges in. */
-    private readonly foregroundWaiters;
-    /** True while a waiter has been promised the slot but has not taken it yet. */
-    private foregroundGranted;
-    /** Set when the client stops, so a waiter never starts work on a closed connection. */
-    private foregroundClosed;
-    private foregroundSeq;
-    /** Which operation the current async continuation belongs to, so a nested call never re-claims. */
-    private readonly foregroundOwner;
+    /** Scheduling and cancellation are owned independently of domain operations. */
+    private readonly foregroundSlot;
     /** Read-only follower for the full-screen view; it borrows the connection and never selects. */
     readonly peek: SessionPeek;
     /** Sources this client created, keyed by session id; the host cannot record that lineage itself. */
@@ -384,39 +339,11 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     private runAction;
     /** Same slot, for an operation that produces a value the caller needs. */
     private runActionValue;
-    /** Whether the current async continuation is already inside the foreground operation.
-     *
-     * An action invoked *by* a running operation (a paging loop calling `older`, a command's policy
-     * calling an action) belongs to that operation: refusing it for being busy would deadlock the very
-     * work that owns the slot. An async-local owner answers that exactly, where a plain flag could not
-     * tell a nested call from a second, unrelated one.
-     * @returns True when this call runs inside the operation that owns the slot.
-     */
-    private ownsForeground;
-    /** Run one operation in the foreground slot, claiming it when the caller does not already own it.
-     *
-     * The slot serializes what the operator is doing — one thing at a time — which is a different
-     * question from the session write order (§6.3): a read takes this slot too. The controller owns the
-     * slot, the abort controller and the identity, so the front end only renders `queries.foreground`
-     * and cancels it in one call.
-     * @param kind - What the operation is.
-     * @param label - Human label shown while it runs.
-     * @param work - The work, handed the signal that `cancelForeground` aborts.
-     * @returns What the work returned, or undefined when the slot was taken or the work was cancelled.
+    /** Run outside the foreground slot, with the same application failure reporting.
+     * Local prompt edits need no connection; verifier cancellation uses the session control lane and
+     * must reach the host even while the foreground is busy or closed for shutdown.
      */
-    private claimForeground;
-    /** Cancel the operation that owns the foreground slot; false when none is running.
-     * @returns Whether an operation was there to cancel.
-     */
-    private cancelForeground;
-    /** Run one local operation that needs no connection, reporting failure the way `runAction` does.
-     *
-     * Shortcut prompts are the operator's own file, so they must keep working while the host is
-     * disconnected; only the failure line is shared with the remote operations.
-     * @param operation - Operation to run against local storage.
-     * @returns Whether it ran to completion.
-     */
-    private runLocalAction;
+    private runImmediateAction;
     /** Read the counters one memory sample records; content never leaves as text.
      *
      * The retained transcript and the ledger are small in practice, so a sample also reads the two
@@ -494,14 +421,6 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     private pendingCounts;
     /** Load the optional preset roster once per connection. */
     private loadPresetNames;
-    /** @returns Host model routes and adapter-owned reasoning choices. */
-    private modelCatalog;
-    /** Select the next request's model.
-     * @param provider - Host provider route ID.
-     * @param model - Exact model ID.
-     * @param reasoningEffort - Optional adapter-owned effort ID.
-     */
-    private selectModel;
     /** Stop the selected turn, or allow exit only while idle.
      * @param force - Send an explicit cancellation even when the cached running flag is idle.
      * @returns True when the caller may exit.
@@ -517,7 +436,6 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     /** Show a detached history window, releasing the one it replaces.
      * @param window - Record to display, or undefined to return to the live transcript.
      */
-    private setViewWindow;
     /** Recall one step through the selected session's prompt index; never touches the network.
      * @param direction - Negative for older input, positive for newer input.
      * @param current - Composer content before recall began, restored at the newest position.
@@ -660,132 +578,6 @@ export declare class Controller implements ControllerStore, ConnectionListener {
      * agent and starts an idle one, exactly like submitted text.
      */
     private handoff;
-    /** Start a scored loop and send its opening step.
-     * @param protocol - Prompt text and step count the loop follows.
-     * @param limits - Resolved `--from/--to/--score/--tries`.
-     */
-    private startLoop;
-    /** End a run whose next prompt could not be sent, keeping the reason visible.
-     *
-     * A rejected send is not a verdict and not an operator cancellation, so the phase is `needs-human`
-     * and `terminalReason` says why — this is what keeps `phase=cancelled` meaning "a person stopped it".
-     * @param loop - Run that could not send.
-     * @param error - What the host or the session layer rejected with.
-     */
-    private rejectLoopSend;
-    /** Record the end of one run once, with the phase it stopped in and why.
-     *
-     * I9 needs every `begin` to be paired inside the trace window; this is the only writer of `loop end`.
-     * @param loop - Run whose terminal phase was just published.
-     */
-    private traceLoopEnd;
-    /** Whether a step begins with verification rather than with a work prompt.
-     *
-     * Needs all three: the record asks for it, the record has a verifier prompt, and this client was
-     * given a verifier. Otherwise there is nobody to verify first, and the step asks for work.
-     * @param loop - Loop about to start a step.
-     * @returns True when the step starts by verifying.
-     */
-    private startsByVerifying;
-    /** Verify the step in flight without a work turn before it.
-     *
-     * The activity is set inside `verifyRound`, so the first verification, a work-turn verdict and a
-     * retry all publish the same state without this caller having to remember it.
-     * @param loop - Loop whose step and attempt are already set.
-     */
-    private verifyStep;
-    /** Check the round's own section before spending a verifier on it, then verify or ask for work.
-     *
-     * Verify-first exists so a round that already passes costs no work turn. When the section is not in
-     * the artifact at all the round *cannot* pass, and this client can read that itself — the same check
-     * it applies to a verdict before accepting one. Sending a verifier to discover "the file is missing"
-     * costs a session and, because a failed attempt consumes one, also the round's first attempt: a run
-     * over a document with no review yet would start working at attempt 2/10. An artifact this client
-     * cannot read stays a boundary: the verification runs and its verdict decides, as before.
-     * @param loop - Loop whose step and attempt are already set.
-     */
-    private verifySection;
-    /** Whether the directory this client runs in is readable here at all.
-     *
-     * `readText` answers undefined for a missing file and for a file inside a directory this machine does
-     * not have, and the two mean opposite things: the first is a producer that wrote nothing, the second
-     * is a workspace whose verdict cannot be checked from here.
-     * @returns True when the directory can be listed.
-     */
-    private workspaceVisible;
-    /** Arm the whole-run budget, when the operator set one. */
-    private armLoopDeadline;
-    /** Answer a paused run, so the current artifact is judged again with what the operator supplied.
-     *
-     * The answer is not a work order: it only adds a condition to the judgment, so nothing is sent to the
-     * agent and no attempt is consumed. The verification that follows is a new task with a new identity,
-     * which is what keeps a late verdict from the paused one from deciding the attempt.
-     * @param text - What the operator added; never written to the trace.
-     */
-    private answerLoop;
-    /** Stop a running review; the terminal progress stays visible for the reader.
-     * @param reason - Why it stopped; the default is an operator action.
-     */
-    private stopLoop;
-    /** Drop a finished run's progress line, keeping an active one.
-     *
-     * D3 keeps a terminal result on screen because it is what the reader most needs to see — but it is a
-     * result, not a status: the next line the operator runs means they have read it. An active run is
-     * left alone, so `/loop answer` and `/loop stop` keep the target they were typed for.
-     */
-    private clearLoopResult;
-    /** Drop the loop entirely, without publishing a cancelled phase.
-     * @param reason - Why it was dropped, recorded when it never reached a terminal phase itself.
-     */
-    private forgetLoop;
-    /** Note that an attempt's turn ended; its block may still be arriving.
-     * @param sessionId - Session the host reported idle.
-     */
-    private settleLoop;
-    /** Consume the attempt once its result block is committed, or the grace period expires.
-     *
-     * The final assistant message can land a moment after the idle event, so an empty parse is not yet
-     * a failed attempt: the next publish retries, and one timer covers a transcript that never grows.
-     */
-    private trySettleLoop;
-    /** Score one finished round out of band, in a process of its own.
-     *
-     * The child writes its verdict to a file, so a slow or failed verifier delays the attempt instead
-     * of corrupting it: with no verdict the reply block decides, and with neither the attempt fails.
-     * @param loop - The run whose attempt just finished.
-     */
-    private verifyRound;
-    /** Apply a protocol's own artifact requirement, then settle the attempt.
-     *
-     * The score is the verifier's judgement; whether the round's conclusion actually reached the
-     * artifact is a fact this client checks itself. A hard condition may not be overridden by a score:
-     * a round whose section is missing fails even at 10/10, and the missing line is fed back to the
-     * next attempt like any other finding. An artifact this client cannot read cannot be checked, so
-     * the verdict stands rather than being failed on a boundary.
-     * @param loop - The run whose attempt just finished.
-     * @param result - Verdict to consume.
-     * @param note - Note to show instead, when the check accepted the verdict unchanged.
-     */
-    private settleChecked;
-    /** Apply one attempt's verdict, and continue the run when it has a next step.
-     * @param loop - The run being settled.
-     * @param result - Verdict to consume, or undefined when the attempt produced none.
-     */
-    private settleWith;
-    /** Stop an in-flight verification, if any; its result can no longer decide anything. */
-    private abortVerification;
-    /** Stop the run because the whole-run budget expired; a budget stop, not a verdict.
-     *
-     * Any verification in flight is cancelled (bounded, as everywhere else) and its late result can
-     * no longer decide anything, because the loop is no longer active.
-     */
-    private expireLoopDeadline;
-    /** Drop the run deadline, if one is armed. */
-    private clearLoopDeadline;
-    /** Drop a pending settle timer, if any. */
-    private forgetSettleTimer;
-    /** Send the prompt the loop is holding, once the client can actually send it. */
-    private flushLoop;
     /** Cancel the active turn; pending queue items remain host-owned. */
     private cancelTurn;
     /** Add a page before the retained window.
@@ -799,12 +591,6 @@ export declare class Controller implements ControllerStore, ConnectionListener {
      * @returns Newest-first bounded summaries and an explicit truncation flag.
      */
     private searchHistory;
-    /** Load a separate small window ending at a search target.
-     * @param target - Durable message sequence to display.
-     * @param signal - Cancels the target-page request.
-     * @returns A caller-owned historical window that must be disposed when closed.
-     */
-    private historyAt;
     /** Plain rows and offsets for one laid-out record; the projection stays in the session domain. */
     private render;
     /** Load the prefix required for an explicit history jump.