@sema-agent/client-core 0.104.0 → 0.105.0

package/dist/headlessReconnectWire.js

@@ -3,7 +3,17 @@ import { hostEnv } from './hostEnv.js';
 import { isSdkRunFrameSynthesizable } from './terminalStatuses.js';
 import { createStreamDrainingLegs } from './streamDrainingLegs.js';
 import { abortableSleep } from './abortableSleep.js';
+import { mintRunNotFollowed, registerRunNotFollowed } from './runFollow.js';
+import { classifyTurnWireError } from './wireErrorTriage.js';
 export const HEADLESS_RECONNECT_MAX = 2;
+function guardedTransport(e) {
+    try {
+        return classifyTurnWireError(e).kind === 'transport';
+    }
+    catch {
+        return false;
+    }
+}
 function debugLog(msg) {
     if (hostEnv().SEMA_DEBUG) {
         console.error(`[sema] headless reconnect: ${msg}`);
@@ -46,6 +56,12 @@ export async function* withHeadlessR1Reconnect(live, deps) {
     let isRecoverableTear;
     const drains = createStreamDrainingLegs();
     let drainReopenAfterMs;
+    let lastBreak;
+    const giveUp = (fact) => {
+        if (typeof originalTearErr === 'object' && originalTearErr !== null)
+            registerRunNotFollowed(originalTearErr, fact);
+        throw originalTearErr;
+    };
     const terminalFromRunRow = async (taskId) => {
         const row = await deps.getRun(taskId).catch(() => null);
         const terminal = terminalEventFromRunRow(row);
@@ -60,9 +76,18 @@ export async function* withHeadlessR1Reconnect(live, deps) {
             isRecoverableTear = isSseIdleError(originalTearErr);
         if (!isRecoverableTear)
             throw originalTearErr;
-        const taskId = deps.getTaskId();
-        if (!taskId)
-            throw originalTearErr;
+        let handle;
+        try {
+            handle = deps.getTaskId();
+        }
+        catch {
+            return giveUp(mintRunNotFollowed('bad_input'));
+        }
+        if (handle === null || handle === undefined)
+            return giveUp(mintRunNotFollowed('no_run_id'));
+        if (typeof handle !== 'string' || handle === '')
+            return giveUp(mintRunNotFollowed('bad_input'));
+        const taskId = handle;
         if (drainReopenAfterMs !== undefined) {
             const waitMs = drainReopenAfterMs;
             drainReopenAfterMs = undefined;
@@ -74,7 +99,7 @@ export async function* withHeadlessR1Reconnect(live, deps) {
         else {
             if (attempts >= HEADLESS_RECONNECT_MAX) {
                 debugLog(`budget exhausted (${attempts}/${HEADLESS_RECONNECT_MAX}) — falling to the honest death path`);
-                throw originalTearErr;
+                return giveUp(mintRunNotFollowed('reattach_exhausted', taskId, lastBreak));
             }
             attempts++;
             if (!(await probe(deps.baseUrl)))
@@ -111,6 +136,7 @@ export async function* withHeadlessR1Reconnect(live, deps) {
             if (deps.signal?.aborted)
                 return;
             const drained = drains.legEnded('returned');
+            lastBreak = drained !== undefined ? 'stream_draining' : undefined;
             if (drained !== undefined) {
                 if ('reconnectAfterMs' in drained) {
                     drainReopenAfterMs = drained.reconnectAfterMs;
@@ -128,6 +154,7 @@ export async function* withHeadlessR1Reconnect(live, deps) {
         }
         catch (contErr) {
             drains.legEnded('threw');
+            lastBreak = guardedTransport(contErr) ? 'connection_lost' : undefined;
             debugLog(`runs.events continuation failed: ${contErr instanceof Error ? contErr.message : String(contErr)}`);
             if (deps.signal?.aborted)
                 throw originalTearErr;

package/dist/hitl/askGateWire.js

@@ -1,9 +1,10 @@
 import { createGateLedger } from './gateLedger.js';
-import { flushHeldWithInterruptRewrite, isHostProgressFrame, routeFrame, } from './frameRouter.js';
+import { bridgeRunHandleFallbackOf, flushHeldWithInterruptRewrite, isHostProgressFrame, routeFrame, } from './frameRouter.js';
 import { resolvePark, nextHopBudget, stalledTerminal, MAX_GATE_HOPS } from './parkResolver.js';
 import { createStreamDrainingLegs } from '../streamDrainingLegs.js';
 import { abortableSleep } from '../abortableSleep.js';
 import { hostLog } from '../host.js';
+import { invokeHostCallbackIsolated } from '../hostCallbackGuard.js';
 import { decideAcceptedNotResolved, readDecideReceipt } from '../decideReceipt.js';
 import { APPROVAL_EXPIRED } from '../engineErrorCodes.js';
 import { isNotFoundFailure } from '../wireErrorTriage.js';
@@ -37,11 +38,14 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
     let lastRoundDecided = false;
     let unverifiableParks = 0;
     const drains = createStreamDrainingLegs();
+    let lastDrainFrame;
     while (true) {
         let park = null;
         for await (const ev of stream) {
-            if (drains.see(ev))
+            if (drains.see(ev)) {
+                lastDrainFrame = ev;
                 continue;
+            }
             const answering = led.answeringLiveCards();
             if (answering.length > 0)
                 await Promise.all(answering);
@@ -77,6 +81,11 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
             const drained = drains.legEnded('returned');
             if (drained !== undefined) {
                 const reopenAfterMs = 'reconnectAfterMs' in drained ? drained.reconnectAfterMs : undefined;
+                if (taskId.current === undefined) {
+                    const bound = bridgeRunHandleFallbackOf(deps);
+                    if (bound !== undefined && reopenAfterMs !== undefined)
+                        taskId.current = bound;
+                }
                 if (reopenAfterMs !== undefined && taskId.current !== undefined && !opts?.signal?.aborted) {
                     hostLog('debug', `liveHitlAskWire: runs.events(${taskId.current}) ended on the drain end frame — the engine is going down; reopening in ${reopenAfterMs}ms`);
                     await abortableSleep(reopenAfterMs, opts?.signal ?? new AbortController().signal);
@@ -91,6 +100,13 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
                     }
                 }
                 hostLog('debug', `liveHitlAskWire: runs.events ended on the drain end frame and is not reopened (${'giveUp' in drained ? drained.giveUp : taskId.current === undefined ? 'no run handle' : 'aborted'}) — ending this leg like a dropped stream`);
+                if (!opts?.signal?.aborted) {
+                    const runId = taskId.current;
+                    const event = 'giveUp' in drained
+                        ? { cause: 'stream_draining', ladder: 'exhausted', ...(runId !== undefined ? { runId } : {}) }
+                        : { cause: 'stream_draining', frame: lastDrainFrame ?? {}, ...(runId !== undefined ? { runId } : {}) };
+                    notifyBreak(deps, Object.freeze(event), opts?.signal);
+                }
             }
             yield* flushHeldWithInterruptRewrite(led, { signal: opts?.signal });
             return;
@@ -161,6 +177,14 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
         });
     }
 }
+function notifyBreak(deps, event, signal) {
+    invokeHostCallbackIsolated('liveHitlAskWire: onBreak', () => {
+        const cb = deps.onBreak;
+        if (typeof cb !== 'function' || signal?.aborted === true)
+            return;
+        return cb.call(deps, event);
+    });
+}
 export const LATE_DECIDE_OUTCOMES = Object.freeze(['accepted-not-resolved', 'resumed', 'expired-reaped', 'settled-elsewhere', 'unknown']);
 const LATE_DECIDE_TASK_ID_MAX = 64;
 export function lateDecideOutcomeOf(reply, opts) {

package/dist/hitl/frameRouter.d.ts

@@ -5,6 +5,7 @@ import type { ApprovalResolution } from './approvalResolution.js';
 import type { GateLedger } from './gateLedger.js';
 import type { NoAllowCause } from './noAllowCause.js';
 import { type ReplayedApprovalDisposition } from './replayedApproval.js';
+import type { ReattachDrainingEvent } from '../runReattachPolicy.js';
 export declare const HITL_REJECT_MESSAGE = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
 export declare const HITL_POLICY_DENY_MESSAGE: string;
 export type PolicyDenyLane = 'no_approval_ui' | 'dont_ask';
@@ -31,11 +32,14 @@ export interface AskGateWireDeps {
     }) => AsyncGenerator<AgentEvent>;
     respondToolApproval?: RespondToolApprovalFn;
     onParkReattach?: (e: ParkReattachNotice) => void;
+    onBreak?: (event: ReattachDrainingEvent) => void;
     approvalLane?: ToolApprovalFrameLaneOpts;
     onToolApprovalOutcome?: (frame: ToolApprovalFrame, resolution: ApprovalResolution) => void | Promise<void>;
     onDecideOperation?: DecideOperationObserver;
     onReplayedApproval?: (frame: ToolApprovalFrame, disposition: ReplayedApprovalDisposition) => void | Promise<void>;
 }
+export declare function setBridgeRunHandleFallback(deps: object, read: () => string | undefined): void;
+export declare function bridgeRunHandleFallbackOf(deps: object): string | undefined;
 type GateKind = 'ask' | 'fs';
 export interface GatePark {
     gate: GateKind;

package/dist/hitl/frameRouter.js

@@ -83,6 +83,20 @@ function denyStampedEnd(ev, attribution) {
 export const HITL_INTERRUPT_MESSAGE_FOR_TOOL_USE = '[Request interrupted by user for tool use]';
 const RUN_CANCELLED_ERROR_CODE = RUN_CANCELLED_CODE;
 export const ENGINE_ABORT_TOOL_RESULT = 'Operation aborted';
+const bridgeRunHandleFallbacks = new WeakMap();
+export function setBridgeRunHandleFallback(deps, read) {
+    bridgeRunHandleFallbacks.set(deps, read);
+}
+export function bridgeRunHandleFallbackOf(deps) {
+    try {
+        const read = bridgeRunHandleFallbacks.get(deps);
+        const v = read?.();
+        return typeof v === 'string' && v !== '' ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function isAskToolLoose(name) {
     return typeof name === 'string' && name.replace(/[\s_-]+/g, '').toLowerCase() === 'askuserquestion';
 }

package/dist/hitl/gateIdentity.d.ts

@@ -3,6 +3,7 @@ export declare const REOPEN_ID_TAIL = "#reopen-";
 export declare function approvalCallKey(gatedCallId: string | undefined, taskId: string): string;
 export declare function askGateQuestionId(callKey: string): string;
 export declare function planReviewQuestionId(taskId: string): string;
+export declare function freshPlanReviewQuestionId(taskId: string, suffix: string): string;
 export declare function liveFrameCallKey(approvalId: string): string;
 export declare function taskIdFromPlanReviewQuestionId(questionId: string): string | undefined;
 export declare function armedKeyFromQuestionId(questionId: string): string;

package/dist/hitl/gateIdentity.js

@@ -11,6 +11,9 @@ export function askGateQuestionId(callKey) {
 export function planReviewQuestionId(taskId) {
     return `${PLAN_REVIEW_QUESTION_ID_PREFIX}${taskId}`;
 }
+export function freshPlanReviewQuestionId(taskId, suffix) {
+    return `${planReviewQuestionId(taskId)}${REOPEN_ID_TAIL}${suffix}`;
+}
 export function liveFrameCallKey(approvalId) {
     return `${HITL_FRAME_CALL_KEY_PREFIX}${approvalId}`;
 }

package/dist/hitl/livePendingAsk.d.ts

@@ -1,3 +1,4 @@
+import { type ApprovalRequestFrame } from '@sema-agent/sdk';
 import type { ApprovalResolution } from './approvalResolution.js';
 import type { ApprovalsFeedEmission } from './approvalsFeed.js';
 import { type RespondToolApprovalFn, type ToolApprovalFrame, type ToolApprovalFrameLaneOpts } from './toolApprovalWire.js';
@@ -11,7 +12,7 @@ export interface LivePendingAskView {
     governanceForced?: true;
     fromSubagent?: true;
     originTaskId?: string;
-    frame?: ToolApprovalFrame;
+    frame?: ToolApprovalFrame | ApprovalRequestFrame;
 }
 export type LivePendingReading = {
     kind: 'not_reported';

package/dist/hitl/livePendingAsk.js

@@ -1,3 +1,4 @@
+import { isApprovalRequestFrameV1 } from '@sema-agent/sdk';
 import { appendOwnElement } from '../ownKey.js';
 import { readRequiresRealApproval } from './approvalCardReading.js';
 import { THROWN_SLOT_UNREADABLE, readThrownSlot } from '../wireFailureShape.js';
@@ -21,6 +22,11 @@ function snapshotMembers(raw) {
     }
     return raw.length === length ? out : undefined;
 }
+function openingFrameOf(f) {
+    if (isToolApprovalFrame(f))
+        return f.type === 'tool_approval' ? f : undefined;
+    return isApprovalRequestFrameV1(f) ? f : undefined;
+}
 export function readLivePendingRows(body) {
     if (body === null || typeof body !== 'object' || Array.isArray(body))
         return { kind: 'malformed' };
@@ -65,7 +71,7 @@ export function readLivePendingRows(body) {
             ...(o.governanceForced === true ? { governanceForced: true } : {}),
             ...(o.fromSubagent === true ? { fromSubagent: true } : {}),
             ...(nonEmptyString(o.originTaskId) ? { originTaskId: o.originTaskId } : {}),
-            ...(isToolApprovalFrame(o.frame) && o.frame.type === 'tool_approval' && o.frame.approvalId === o.approvalId ? { frame: o.frame } : {}),
+            ...((f) => (f !== undefined && f.approvalId === o.approvalId ? { frame: f } : {}))(openingFrameOf(o.frame)),
         });
     }
     if (members.length > 0 && rows.length === 0)

package/dist/hitl/planReviewCard.d.ts

@@ -0,0 +1,21 @@
+import { type PlanReviewCardFacts, type PlanReviewFactsTaken } from '../planReviewCardFacts.js';
+import { type MessageRef } from '../i18n/translate.js';
+import type { MessageKey } from '../i18n/messages.en.js';
+import type { UiLanguage } from '../env/uiLanguage.js';
+export declare function planReviewCardNoteRef(facts: PlanReviewCardFacts): MessageRef | undefined;
+export declare function planReviewUnreadableNoteRef(): MessageRef;
+export declare function planReviewCardNote(facts: PlanReviewCardFacts, lang?: UiLanguage): string | undefined;
+export declare function planReviewAskAgainKey(facts: PlanReviewCardFacts | undefined): MessageKey;
+export interface PlanReviewLedgerSource {
+    readonly runRow: (taskId: string, signal: AbortSignal) => Promise<object>;
+    readonly frames: (taskId: string, signal: AbortSignal) => AsyncIterable<object>;
+}
+export type PlanReviewFactsTaking = {
+    readonly kind: 'now';
+    readonly taken: PlanReviewFactsTaken;
+} | {
+    readonly kind: 'ledger';
+    readonly pending: Promise<PlanReviewFactsTaken | undefined>;
+};
+export declare function _resetPlanReviewFactsFlightsForTest(): void;
+export declare function takePlanReviewFacts(sessionKey: string, taskId: string, checkpointId: string | undefined, source: () => PlanReviewLedgerSource | undefined, signal?: AbortSignal): PlanReviewFactsTaking;

package/dist/hitl/planReviewCard.js

@@ -0,0 +1,229 @@
+import { currentPlanReviewGateOf, isPlanReviewClaimFrame, mintPlanReviewCardFacts, openPlanReviewLedgerFold, planGateRowReadOf, planReviewBodyOf, planReviewCardFactsFrom, planReviewLedgerClaimOf, planReviewRunGeneration, beginPlanReviewFactsRead, commitPlanReviewFacts, samePlanClaim, stepPlanReviewLedgerFold, unknownBody, } from '../planReviewCardFacts.js';
+import { msg, renderMessage } from '../i18n/translate.js';
+import { readRunLedgerSnapshot } from '../runLedgerSnapshot.js';
+import { snapshotIsSubFlow, snapshotSegmentIdentity } from '../adapter/types.js';
+import { settleWithinDeadline } from '../abortableSleep.js';
+import { hostLog } from '../host.js';
+export function planReviewCardNoteRef(facts) {
+    const body = facts.body;
+    switch (body.kind) {
+        case 'shown':
+            return body.markdown.trim() === '' ? msg('approval.planReview.note.empty') : undefined;
+        case 'marked':
+            return msg('approval.planReview.note.marked');
+        case 'too_large':
+            return msg('approval.planReview.note.tooLarge', { length: body.length });
+        case 'unknown':
+            return msg(body.cause === 'not_carried' ? 'approval.planReview.note.notCarried' : 'approval.planReview.note.unknown');
+    }
+}
+export function planReviewUnreadableNoteRef() {
+    return msg('approval.planReview.note.unknown');
+}
+export function planReviewCardNote(facts, lang) {
+    let ref;
+    try {
+        const read = planReviewCardFactsFrom(facts);
+        ref = read === undefined ? planReviewUnreadableNoteRef() : planReviewCardNoteRef(read);
+    }
+    catch {
+        ref = planReviewUnreadableNoteRef();
+    }
+    return ref === undefined ? undefined : renderMessage(ref, lang);
+}
+export function planReviewAskAgainKey(facts) {
+    const body = facts?.body;
+    if (body === undefined)
+        return 'approval.planReview.askAgain.unknown';
+    switch (body.kind) {
+        case 'shown':
+            return 'approval.planReview.askAgain.shown';
+        case 'marked':
+            return 'approval.planReview.askAgain.marked';
+        case 'too_large':
+            return 'approval.planReview.askAgain.tooLarge';
+        case 'unknown':
+            return body.cause === 'not_carried' ? 'approval.planReview.askAgain.notCarried' : 'approval.planReview.askAgain.unknown';
+    }
+}
+const PLAN_REVIEW_LEDGER_BUDGET_MS = 3_000;
+const planReviewFactsFlights = new Map();
+export function _resetPlanReviewFactsFlightsForTest() {
+    planReviewFactsFlights.clear();
+}
+export function takePlanReviewFacts(sessionKey, taskId, checkpointId, source, signal) {
+    const now = (facts, generation) => ({ kind: 'now', taken: { sessionKey, taskId, facts, generation } });
+    try {
+        const g0 = planReviewRunGeneration(sessionKey, taskId);
+        const gate = currentPlanReviewGateOf(sessionKey, taskId);
+        if (checkpointId !== undefined && gate !== undefined && gate.checkpointId === checkpointId)
+            return now(gate.facts, gate.generation);
+        const flightKey = `${sessionKey}\u0000${taskId}\u0000${checkpointId ?? ''}`;
+        const inFlight = planReviewFactsFlights.get(flightKey);
+        if (inFlight !== undefined)
+            return { kind: 'ledger', pending: inFlight };
+        let src;
+        try {
+            src = source();
+        }
+        catch {
+            src = undefined;
+        }
+        if (src === undefined)
+            return now(mintPlanReviewCardFacts(taskId, checkpointId, unknownBody('not_observed')), g0);
+        const reader = src;
+        const started = Date.now();
+        const ledger = (budgetMs) => readPlanReviewFactsFromLedger(beginPlanReviewFactsRead(sessionKey, taskId), checkpointId, reader, signal, budgetMs);
+        const viaRow = checkpointId === undefined && gate !== undefined
+            ? readPlanGateRowWithin(reader, taskId, signal, PLAN_REVIEW_LEDGER_BUDGET_MS).then((row) => {
+                const cur = currentPlanReviewGateOf(sessionKey, taskId);
+                if (row.ok && row.atPlanGate && row.checkpointId !== undefined && cur !== undefined && cur.checkpointId === row.checkpointId) {
+                    return { sessionKey, taskId, facts: cur.facts, generation: cur.generation };
+                }
+                if (!row.ok)
+                    return { sessionKey, taskId, facts: mintPlanReviewCardFacts(taskId, undefined, unknownBody('unreadable')), generation: g0 };
+                return ledger(Math.max(0, PLAN_REVIEW_LEDGER_BUDGET_MS - (Date.now() - started)));
+            })
+            : undefined;
+        const pending = (viaRow ?? ledger(PLAN_REVIEW_LEDGER_BUDGET_MS)).then((taken) => {
+            if (planReviewFactsFlights.get(flightKey) === pending)
+                planReviewFactsFlights.delete(flightKey);
+            return taken;
+        }, () => {
+            if (planReviewFactsFlights.get(flightKey) === pending)
+                planReviewFactsFlights.delete(flightKey);
+            return undefined;
+        });
+        planReviewFactsFlights.set(flightKey, pending);
+        return { kind: 'ledger', pending };
+    }
+    catch {
+        return now(mintPlanReviewCardFacts(taskId, checkpointId, unknownBody('unreadable')), Number.NaN);
+    }
+}
+const rowUnread = () => ({ ok: false, atPlanGate: false });
+async function readPlanGateRow(source, taskId, signal) {
+    try {
+        return planGateRowReadOf(await source.runRow(taskId, signal));
+    }
+    catch {
+        return rowUnread();
+    }
+}
+async function readPlanGateRowWithin(source, taskId, outer, budgetMs) {
+    if (outer?.aborted === true)
+        return rowUnread();
+    let onOuterAbort;
+    try {
+        const aborted = new Promise((resolve) => {
+            onOuterAbort = () => resolve(rowUnread());
+            outer?.addEventListener('abort', onOuterAbort, { once: true });
+        });
+        const read = settleWithinDeadline(budgetMs, (deadline) => {
+            const ac = new AbortController();
+            const stop = () => ac.abort();
+            deadline.addEventListener('abort', stop, { once: true });
+            outer?.addEventListener('abort', stop, { once: true });
+            return readPlanGateRow(source, taskId, ac.signal).finally(() => {
+                deadline.removeEventListener('abort', stop);
+                outer?.removeEventListener('abort', stop);
+            });
+        }).then((settled) => (settled.kind === 'value' ? settled.value : rowUnread()));
+        return await Promise.race([read, aborted]);
+    }
+    catch {
+        return rowUnread();
+    }
+    finally {
+        if (onOuterAbort !== undefined)
+            outer?.removeEventListener('abort', onOuterAbort);
+    }
+}
+function foldLedgerFrame(fold, ev) {
+    if (typeof ev !== 'object' || ev === null)
+        return fold;
+    const snap = snapshotSegmentIdentity(ev);
+    return stepPlanReviewLedgerFold(fold, ev, snap === null || snapshotIsSubFlow(snap));
+}
+async function readPlanReviewFactsFromLedger(ticket, given, source, signal, budgetMs) {
+    const { sessionKey, taskId } = ticket;
+    const reads = [];
+    let claim;
+    let highWater;
+    try {
+        const snap = await readRunLedgerSnapshot(taskId, undefined, {
+            isParked: async (id, s) => {
+                const r = await readPlanGateRow(source, id, s);
+                reads.push(r);
+                const first = reads[0];
+                if (!r.ok || !r.atPlanGate || r.checkpointId === undefined)
+                    return false;
+                if (given !== undefined && r.checkpointId !== given)
+                    return false;
+                return reads.length === 1 || (first !== undefined && first.ok && first.checkpointId === r.checkpointId);
+            },
+            frames: (id, s) => source.frames(id, s),
+            budgetMs,
+            log: (msg) => {
+                hostLog('debug', `planReviewCard: ${msg}`);
+            },
+            fold: {
+                init: openPlanReviewLedgerFold,
+                step: foldLedgerFrame,
+                strictOrder: true,
+                substantive: isPlanReviewClaimFrame,
+                agree: (a, b) => {
+                    const x = planReviewLedgerClaimOf(a);
+                    const y = planReviewLedgerClaimOf(b);
+                    return x === undefined || y === undefined ? x === y : samePlanClaim(x, y);
+                },
+            },
+        }, signal);
+        if (snap !== null && snap.folded !== undefined) {
+            claim = planReviewLedgerClaimOf(snap.folded);
+            if (claim !== undefined)
+                highWater = snap.highWater;
+        }
+    }
+    catch {
+        claim = undefined;
+    }
+    const first = reads[0];
+    const firstGate = first !== undefined && first.ok && first.atPlanGate ? first.checkpointId : undefined;
+    let facts;
+    if (claim !== undefined && firstGate !== undefined) {
+        facts = mintPlanReviewCardFacts(taskId, firstGate, claim.kind === 'text' ? planReviewBodyOf(claim.text) : unknownBody(claim.cause));
+    }
+    else {
+        const missed = ledgerMissOf(reads, given);
+        claim = { kind: 'cause', cause: missed.cause };
+        highWater = undefined;
+        facts = mintPlanReviewCardFacts(taskId, missed.checkpointId, unknownBody(missed.cause));
+    }
+    const out = commitPlanReviewFacts(ticket, facts, claim, highWater);
+    if (out === undefined) {
+        hostLog('debug', `planReviewCard: ledger-read-superseded task=${taskId}`);
+        return undefined;
+    }
+    return { sessionKey, taskId, facts: out, generation: ticket.generation };
+}
+function ledgerMissOf(reads, given) {
+    const first = reads[0];
+    if (first === undefined || !first.ok)
+        return { cause: 'unreadable', ...(given !== undefined ? { checkpointId: given } : {}) };
+    if (!first.atPlanGate || first.checkpointId === undefined)
+        return { cause: 'gate_unidentified' };
+    const asked = given ?? first.checkpointId;
+    if (given !== undefined && first.checkpointId !== given)
+        return { cause: 'gate_moved', checkpointId: asked };
+    const second = reads[1];
+    if (second !== undefined) {
+        if (!second.ok)
+            return { cause: 'unreadable', checkpointId: asked };
+        if (!second.atPlanGate || second.checkpointId === undefined)
+            return { cause: 'gate_unidentified' };
+        if (second.checkpointId !== first.checkpointId)
+            return { cause: 'gate_moved', checkpointId: asked };
+    }
+    return { cause: 'unreadable', checkpointId: asked };
+}

package/dist/hitl/planReviewWire.d.ts

@@ -2,34 +2,52 @@ import { type QuestionAnswer } from '../liveQuestionStore.js';
 import type { EngineWireInjection } from '../engineWireSdk.js';
 import { type PlanReviewModeAfter } from './hitlBridge.js';
 import type { AgentClient } from '@sema-agent/sdk';
+import { isPlanReviewPark, type PlanReviewCardFacts } from '../planReviewCardFacts.js';
+import type { UiLanguage } from '../env/uiLanguage.js';
 import type { ReopenCardVerdict } from '../adapter/activeRunSelfHeal.js';
 export declare const PLAN_REVIEW_APPROVE_LABEL = "Yes, approve and run the plan";
 export declare const PLAN_REVIEW_REJECT_LABEL = "No, reject it (keep planning)";
 export declare const PLAN_REVIEW_APPROVE_AUTO_LABEL = "Yes, and auto-accept edits";
 export declare const PLAN_REVIEW_APPROVE_MANUAL_LABEL = "Yes, and manually approve edits";
-export declare function planReviewDecisionFromAnswer(answer: QuestionAnswer | null | undefined, shownLabels?: readonly string[]): 'approve' | 'reject' | 'dismissed';
+export type PlanReviewOptionChoice = 'approve' | 'approve_accept_edits' | 'approve_manual' | 'reject' | 'ask_again';
+export interface PlanReviewOption {
+    readonly label: string;
+    readonly description: string;
+    readonly choice: PlanReviewOptionChoice;
+}
+type PlanReviewNonDecision = 'dismissed' | 'inadmissible';
+export declare function planReviewDecisionFromAnswer(answer: QuestionAnswer | null | undefined, shownLabels?: readonly string[]): 'approve' | 'reject' | 'ask_again' | PlanReviewNonDecision;
 export type PlanReviewChoice = {
     decision: 'approve';
     permissionModeAfter?: PlanReviewModeAfter;
 } | {
     decision: 'reject';
     reason?: string;
+} | {
+    decision: 'ask_again';
+    reason?: string;
 };
-export declare function planReviewChoiceFromAnswer(answer: QuestionAnswer | null | undefined, shownLabels?: readonly string[]): PlanReviewChoice | 'dismissed';
+export declare function planReviewChoiceFromAnswer(answer: QuestionAnswer | null | undefined, shownLabels?: readonly string[]): PlanReviewChoice | PlanReviewNonDecision;
 export declare function planReviewCardOptions(offerModeAfter: boolean): Array<{
     label: string;
     description: string;
 }>;
+export declare function planReviewOptionsOf(facts: PlanReviewCardFacts, opts?: {
+    readonly submittedInPlanMode?: boolean;
+}): readonly PlanReviewOption[];
+export interface PlanReviewCardView {
+    readonly facts?: PlanReviewCardFacts;
+    readonly options: readonly PlanReviewOption[];
+    readonly note?: string;
+}
+export declare function planReviewCardViewOf(frame: object | null | undefined, lang?: UiLanguage): PlanReviewCardView | undefined;
 export declare function notePlanReviewAnsweredIfDecisive(questionId: unknown, answer: QuestionAnswer | null | undefined): void;
-export declare function isPlanReviewPark(result: unknown): result is {
-    taskId: string;
-    sessionId?: string;
-};
+export { isPlanReviewPark };
 export declare function _resetArmedPlanReviewsForTest(): void;
 export type PlanReviewReopenTrigger = 'user' | 'automatic';
 export type PlanReviewGateInstanceReader = (taskId: string) => Promise<ReadonlySet<string> | null>;
 export declare function clearPlanReviewUserDismissals(sessionKey?: string): void;
-export type PlanReviewOfferedMode = 'three_choice' | 'two_choice' | 'unknown';
+export type PlanReviewOfferedMode = 'three_choice' | 'two_choice' | 'withheld' | 'unknown';
 export interface PlanReviewCardLike {
     readonly questionId?: string;
     readonly questions?: ReadonlyArray<{
@@ -45,8 +63,8 @@ export interface PlanReviewQuestionIdReading {
 export declare function planReviewTaskIdFromQuestionId(questionId: {} | null | undefined): PlanReviewQuestionIdReading | undefined;
 export declare function planReviewOfferedModeOf(card: string | PlanReviewCardLike): PlanReviewOfferedMode;
 export declare function planReviewShownLabelsOf(questionId: {} | null | undefined): readonly string[] | undefined;
-export declare function planReviewAnswerChoiceOf(questionId: {} | null | undefined, answer: QuestionAnswer | null | undefined): PlanReviewChoice | 'dismissed';
-export declare function planReviewAnswerDecisionOf(questionId: {} | null | undefined, answer: QuestionAnswer | null | undefined): 'approve' | 'reject' | 'dismissed';
+export declare function planReviewAnswerChoiceOf(questionId: {} | null | undefined, answer: QuestionAnswer | null | undefined): PlanReviewChoice | PlanReviewNonDecision;
+export declare function planReviewAnswerDecisionOf(questionId: {} | null | undefined, answer: QuestionAnswer | null | undefined): 'approve' | 'reject' | 'ask_again' | PlanReviewNonDecision;
 export interface ArmPlanReviewOptions {
     submittedInPlanMode?: boolean;
     readGateInstanceKeys?: PlanReviewGateInstanceReader;
@@ -58,14 +76,14 @@ export type PlanReviewDecisionEffect = 'took_effect' | 'advanced' | 'still_parke
 export interface PlanReviewOutcomeMeta {
     taskId: string;
     dispatchNo: number;
-    decision: 'approve' | 'reject';
+    decision: 'approve' | 'reject' | 'ask_again';
     effect: PlanReviewDecisionEffect;
     cause?: 'stored_form_unsupported';
 }
 export declare function planReviewOutcomeTail(taskId: string, decision: 'approve' | 'reject', effect: PlanReviewDecisionEffect, cause?: 'stored_form_unsupported'): string;
 export type PlanReviewWireClient = {
     assistant: Pick<AgentClient['assistant'], 'planReview'>;
-    runs: Pick<AgentClient['runs'], 'get'>;
+    runs: Pick<AgentClient['runs'], 'get'> & Partial<Pick<AgentClient['runs'], 'events'>>;
 };
 export interface PlanReviewWire extends EngineWireInjection<PlanReviewWireClient> {
     client: PlanReviewWireClient;
@@ -95,17 +113,18 @@ export declare function notePlanReviewDecisionNotApplied(taskId: string): void;
 export declare function notePlanReviewGateLeft(taskId: string): void;
 export declare function latestPlanReviewDecisionMark(taskId: string): number | null;
 export declare function __resetPlanReviewDecisionLatchForTests(): void;
-export declare function decidePlanReview(taskId: string, decision: 'approve' | 'reject', permissionModeAfter?: string, opts?: DecidePlanReviewOptions): Promise<void>;
+export declare function decidePlanReview(taskId: string, decision: 'approve' | 'reject' | 'ask_again', permissionModeAfter?: string, opts?: DecidePlanReviewOptions): Promise<void>;
 export interface ReopenPlanReviewSharedOpts {
     sessionKey?: string;
     presentationReceiptMs: number;
     trigger?: PlanReviewReopenTrigger;
     readGateInstanceKeys?: PlanReviewGateInstanceReader;
     pendingReadStartedAt?: number;
+    checkpointId?: string;
 }
 export interface ReopenPlanReviewFreshOpts extends ReopenPlanReviewSharedOpts {
     mintFreshQuestionId?: true;
-    deliverDecision?: (taskId: string, decision: 'approve' | 'reject', reason?: string) => void | Promise<void>;
+    deliverDecision?: (taskId: string, decision: Parameters<typeof decidePlanReview>[1], reason?: string) => void | Promise<void>;
     wire?: PlanReviewWire;
     onOutcome?: PlanReviewDeliveryOptions['onOutcome'];
 }
@@ -118,3 +137,9 @@ export interface ReopenPlanReviewReuseOpts extends ReopenPlanReviewSharedOpts {
 export type ReopenPlanReviewOpts = ReopenPlanReviewFreshOpts | ReopenPlanReviewReuseOpts;
 export declare function _resetActiveReopenRespondersForTest(): void;
 export declare function reopenPlanReviewCard(taskId: string, opts: ReopenPlanReviewOpts): Promise<ReopenCardVerdict>;
+export interface ReadPlanReviewCardFactsOptions {
+    readonly checkpointId?: string;
+    readonly wire?: PlanReviewWire;
+    readonly signal?: AbortSignal;
+}
+export declare function readPlanReviewCardFacts(taskId: string, opts?: ReadPlanReviewCardFactsOptions): Promise<PlanReviewCardFacts>;