@sema-agent/client-core 0.104.1 → 0.105.0

package/dist/reattachWindow.js

@@ -1,5 +1,6 @@
 import { usableClockMs } from './clockReading.js';
 import { readThrownSlot, THROWN_SLOT_UNREADABLE } from './wireFailureShape.js';
+import { isReattachBreak, mintRunNotFollowed } from './runFollow.js';
 export const REATTACH_WINDOW_MS = 300_000;
 export const REATTACH_BACKOFF_START_MS = 1_000;
 export const REATTACH_BACKOFF_CAP_MS = 30_000;
@@ -25,15 +26,37 @@ export function reattachBackoffMs(attempt, tuning) {
     const raw = startMs * 2 ** (attempt - 1);
     return Number.isFinite(raw) ? Math.min(raw, capMs) : capMs;
 }
-export function reattachWindowOpen(nowMs, tuning) {
+const isRunHandle = (v) => typeof v === 'string' && v !== '';
+export function reattachWindowOpen(nowMs, tuning, runId) {
     const t = tuned(tuning);
     const start = usableClockMs(nowMs) ?? Number.NaN;
-    return Object.freeze({ enteredAtMs: start, deadlineMs: start + t.windowMs, attempt: 0, consecutiveNotFound: 0, notFoundConfirmed: false, tuning: Object.freeze(t) });
+    return Object.freeze({
+        enteredAtMs: start,
+        deadlineMs: start + t.windowMs,
+        attempt: 0,
+        consecutiveNotFound: 0,
+        notFoundConfirmed: false,
+        tuning: Object.freeze(t),
+        ...(isRunHandle(runId) ? { runId } : {}),
+    });
 }
 const step = (state, decision) => Object.freeze({ state, decision });
-const exhausted = (state) => step(state, Object.freeze({ action: 'window-exhausted' }));
+const runOf = (state) => {
+    const v = readThrownSlot(state, 'runId', 'data');
+    return isRunHandle(v) ? v : undefined;
+};
+const exhausted = (state) => {
+    const brk = readThrownSlot(state, 'lastBreak', 'data');
+    return step(state, Object.freeze({ action: 'window-exhausted', notFollowed: mintRunNotFollowed('reattach_exhausted', runOf(state), isReattachBreak(brk) ? brk : undefined) }));
+};
+const badInput = (state, runId) => step(state, Object.freeze({ action: 'window-exhausted', notFollowed: mintRunNotFollowed('bad_input', runId) }));
 const cont = (state, notFoundConfirmed = false) => step(state, Object.freeze({ action: 'continue', notFoundConfirmed }));
-const next = (state, patch) => Object.freeze({ ...state, ...patch });
+const next = (state, patch, lastBreak) => {
+    if (lastBreak === undefined)
+        return Object.freeze({ ...state, ...patch });
+    const { lastBreak: _previous, ...rest } = state;
+    return Object.freeze(lastBreak.to === undefined ? { ...rest, ...patch } : { ...rest, ...patch, lastBreak: lastBreak.to });
+};
 const isCount = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
 function validState(s) {
     if (typeof s !== 'object' || s === null)
@@ -42,18 +65,20 @@ function validState(s) {
     return typeof o.enteredAtMs === 'number' && typeof o.deadlineMs === 'number' && isCount(o.attempt) && isCount(o.consecutiveNotFound) && typeof o.notFoundConfirmed === 'boolean' && typeof o.tuning === 'object' && o.tuning !== null;
 }
 export function reattachWindowStep(state, event, nowMs) {
+    let windowRun;
     try {
+        windowRun = runOf(state);
         if (!validState(state))
-            return exhausted(reattachWindowOpen(Number.NaN));
+            return badInput(reattachWindowOpen(Number.NaN, undefined, windowRun), windowRun);
         if (typeof event !== 'object' || event === null)
             return cont(state);
         const type = event.type;
         const result = event.result;
         const serverRetryAfterMs = event.serverRetryAfterMs;
         if (type === 'new-segment')
-            return cont(reattachWindowOpen(nowMs, state.tuning));
-        if (usableClockMs(nowMs) === null || !Number.isFinite(state.deadlineMs))
-            return exhausted(state);
+            return cont(reattachWindowOpen(nowMs, state.tuning, windowRun));
+        if (usableClockMs(nowMs) === null || usableClockMs(state.enteredAtMs) === null || !Number.isFinite(state.deadlineMs))
+            return badInput(state, windowRun);
         switch (type) {
             case 'attempt':
                 return nowMs < state.deadlineMs ? cont(next(state, { attempt: state.attempt + 1 })) : exhausted(state);
@@ -70,18 +95,25 @@ export function reattachWindowStep(state, event, nowMs) {
             case 'tail-frame':
                 return cont(next(state, { consecutiveNotFound: 0, notFoundConfirmed: false }));
             case 'tail-refused-404':
-                return state.notFoundConfirmed ? step(state, Object.freeze({ action: 'run-unknown', confirmations: state.consecutiveNotFound })) : cont(state);
+                return state.notFoundConfirmed
+                    ? step(state, Object.freeze({ action: 'run-unknown', confirmations: state.consecutiveNotFound, notFollowed: mintRunNotFollowed('run_unknown', windowRun) }))
+                    : cont(state);
             case 'backoff': {
-                const own = reattachBackoffMs(state.attempt, state.tuning);
+                const brkRead = readThrownSlot(event, 'break');
+                const brk = isReattachBreak(brkRead) ? brkRead : undefined;
+                const handoffRead = readThrownSlot(event, 'runId');
+                const handoff = isRunHandle(handoffRead) && handoffRead !== windowRun ? handoffRead : undefined;
+                const moved = next(state, handoff !== undefined ? { runId: handoff, consecutiveNotFound: 0, notFoundConfirmed: false } : {}, { to: brk });
+                const own = reattachBackoffMs(moved.attempt, moved.tuning);
                 const delay = typeof serverRetryAfterMs === 'number' && Number.isFinite(serverRetryAfterMs) && serverRetryAfterMs > 0 ? Math.max(own, serverRetryAfterMs) : own;
-                return nowMs + delay >= state.deadlineMs ? exhausted(state) : step(state, Object.freeze({ action: 'wait', afterMs: delay }));
+                return nowMs + delay >= moved.deadlineMs ? exhausted(moved) : step(moved, Object.freeze({ action: 'wait', afterMs: delay }));
             }
             default:
                 return cont(state);
         }
     }
     catch {
-        return exhausted(reattachWindowOpen(Number.NaN));
+        return badInput(reattachWindowOpen(Number.NaN, undefined, windowRun), windowRun);
     }
 }
 export function poisonFrameInitial() {

package/dist/runFollow.d.ts

@@ -0,0 +1,30 @@
+import type { UiLanguage } from './env/uiLanguage.js';
+import { type MessageRef } from './i18n/translate.js';
+import type { ReattachEvent } from './runReattachPolicy.js';
+export type RunNotFollowedCause = 'reattach_exhausted' | 'no_run_id' | 'bad_input' | 'run_unknown' | 'target_unconfirmed' | 'cursor_unknown';
+export type ReattachBreak = ReattachEvent['cause'];
+export type RunNotFollowed<C extends RunNotFollowedCause = RunNotFollowedCause> = C extends 'reattach_exhausted' ? RunNotFollowedExhausted : RunNotFollowedFact<C>;
+interface RunNotFollowedFact<C extends RunNotFollowedCause> {
+    readonly kind: 'not_followable';
+    readonly cause: C;
+    readonly taskId?: string;
+}
+interface RunNotFollowedExhausted extends RunNotFollowedFact<'reattach_exhausted'> {
+    readonly lastBreak?: ReattachBreak;
+}
+export declare const isReattachBreak: (v: {} | null | undefined) => v is ReattachBreak;
+export declare function mintRunNotFollowed<C extends RunNotFollowedCause>(cause: C, taskId?: string, lastBreak?: ReattachBreak): RunNotFollowed<C>;
+export declare function registerRunNotFollowed(thrown: object, fact: RunNotFollowed): void;
+export declare function runNotFollowedOf(err: {} | null | undefined): RunNotFollowed | undefined;
+interface NoticeParts {
+    readonly reason: MessageRef;
+    readonly ending: MessageRef | '';
+    readonly exit: MessageRef | '';
+}
+export declare function runNotFollowedHeadRef(taskId: string | undefined, parts: NoticeParts): MessageRef;
+export declare function runNotFollowedReasonRef(cause: RunNotFollowedCause, lastBreak?: ReattachBreak): MessageRef;
+export declare function runNotFollowedEndingUnknownRef(): MessageRef;
+export declare function runNotFollowedExitRef(cause: RunNotFollowedCause): MessageRef | '';
+export declare function runNotFollowedNoticeRef(fact: RunNotFollowed): MessageRef;
+export declare function runNotFollowedNotice(fact: RunNotFollowed, lang?: UiLanguage): string;
+export {};

package/dist/runFollow.js

@@ -0,0 +1,117 @@
+import { msg, renderMessage } from './i18n/translate.js';
+import { displayUntrusted } from './displayUntrusted.js';
+import { guardedRead, readOwnDataValue } from './ownKey.js';
+const RUN_NOT_FOLLOWED_CAUSES = Object.freeze(['reattach_exhausted', 'no_run_id', 'bad_input', 'run_unknown', 'target_unconfirmed', 'cursor_unknown']);
+const _causesPin = true;
+void _causesPin;
+const REATTACH_BREAKS = Object.freeze(['connection_lost', 'stream_cap', 'stream_draining']);
+const _breaksPin = true;
+void _breaksPin;
+const isCause = (v) => RUN_NOT_FOLLOWED_CAUSES.includes(v);
+export const isReattachBreak = (v) => REATTACH_BREAKS.includes(v);
+export function mintRunNotFollowed(cause, taskId, lastBreak) {
+    const c = isCause(cause) ? cause : 'bad_input';
+    const run = typeof taskId === 'string' && taskId !== '' ? { taskId } : {};
+    const fact = c === 'reattach_exhausted' ? { kind: 'not_followable', cause: c, ...run, ...(isReattachBreak(lastBreak) ? { lastBreak } : {}) } : { kind: 'not_followable', cause: c, ...run };
+    return Object.freeze(fact);
+}
+const notFollowedByThrown = new WeakMap();
+export function registerRunNotFollowed(thrown, fact) {
+    try {
+        if ((typeof thrown === 'object' && thrown !== null) || typeof thrown === 'function')
+            notFollowedByThrown.set(thrown, fact);
+    }
+    catch {
+    }
+}
+export function runNotFollowedOf(err) {
+    try {
+        if (typeof err === 'object' && err !== null)
+            return notFollowedByThrown.get(err);
+        if (typeof err === 'function')
+            return notFollowedByThrown.get(err);
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const TASK_ID_MAX = 64;
+function readFact(fact) {
+    if (typeof fact !== 'object' || fact === null)
+        return undefined;
+    if (guardedRead(() => readOwnDataValue(fact, 'kind')) !== 'not_followable')
+        return undefined;
+    const cause = guardedRead(() => readOwnDataValue(fact, 'cause'));
+    if (!isCause(cause))
+        return undefined;
+    const rawTask = guardedRead(() => readOwnDataValue(fact, 'taskId'));
+    const shown = typeof rawTask === 'string' && rawTask !== '' ? guardedRead(() => displayUntrusted(rawTask, { max: TASK_ID_MAX, blanks: true })) : undefined;
+    const brk = cause === 'reattach_exhausted' ? guardedRead(() => readOwnDataValue(fact, 'lastBreak')) : undefined;
+    return { cause, ...(shown !== undefined && shown !== '' ? { taskId: shown } : {}), ...(isReattachBreak(brk) ? { lastBreak: brk } : {}) };
+}
+export function runNotFollowedHeadRef(taskId, parts) {
+    const tail = { reason: parts.reason, ending: parts.ending, exit: parts.exit };
+    return taskId !== undefined && taskId !== '' ? msg('follow.notFollowed.headRun', { taskId, ...tail }) : msg('follow.notFollowed.headTurn', tail);
+}
+const LAST_BREAK_REASON_KEYS = Object.freeze({
+    stream_draining: 'follow.notFollowed.reason.exhaustedDraining',
+    connection_lost: 'follow.notFollowed.reason.exhaustedConnectionLost',
+    stream_cap: 'follow.notFollowed.reason.exhaustedStreamCap',
+});
+export function runNotFollowedReasonRef(cause, lastBreak) {
+    switch (cause) {
+        case 'reattach_exhausted':
+            return msg(lastBreak !== undefined && isReattachBreak(lastBreak) ? LAST_BREAK_REASON_KEYS[lastBreak] : 'follow.notFollowed.reason.exhausted');
+        case 'bad_input':
+            return msg('follow.notFollowed.reason.badInput');
+        case 'no_run_id':
+            return msg('follow.notFollowed.reason.noRunId');
+        case 'run_unknown':
+            return msg('follow.notFollowed.reason.runUnknown');
+        default:
+            return msg('follow.notFollowed.reason.unspecified');
+    }
+}
+export function runNotFollowedEndingUnknownRef() {
+    return msg('follow.notFollowed.endingUnknown');
+}
+export function runNotFollowedExitRef(cause) {
+    switch (cause) {
+        case 'reattach_exhausted':
+        case 'bad_input':
+            return msg('follow.notFollowed.exit.reattach');
+        case 'no_run_id':
+            return msg('follow.notFollowed.exit.checkRuns');
+        case 'run_unknown':
+            return msg('follow.notFollowed.exit.runUnknown');
+        default:
+            return '';
+    }
+}
+function neutralNoticeRef() {
+    return runNotFollowedHeadRef(undefined, { reason: msg('follow.notFollowed.reason.unspecified'), ending: runNotFollowedEndingUnknownRef(), exit: '' });
+}
+export function runNotFollowedNoticeRef(fact) {
+    try {
+        const r = readFact(fact);
+        if (r === undefined)
+            return neutralNoticeRef();
+        return runNotFollowedHeadRef(r.taskId, {
+            reason: runNotFollowedReasonRef(r.cause, r.lastBreak),
+            ending: r.cause === 'run_unknown' ? '' : runNotFollowedEndingUnknownRef(),
+            exit: runNotFollowedExitRef(r.cause),
+        });
+    }
+    catch {
+        return neutralNoticeRef();
+    }
+}
+export function runNotFollowedNotice(fact, lang) {
+    try {
+        return renderMessage(runNotFollowedNoticeRef(fact), lang);
+    }
+    catch {
+        return renderMessage(neutralNoticeRef(), lang);
+    }
+}

package/dist/runLedgerSnapshot.d.ts

@@ -0,0 +1,20 @@
+export interface RunLedgerSnapshot<F = never> {
+    readonly highWater: string;
+    readonly openToolStart?: object;
+    readonly folded?: F;
+}
+export interface RunLedgerFold<F> {
+    readonly init: () => F;
+    readonly step: (acc: F, ev: object) => F;
+    readonly strictOrder?: boolean;
+    readonly agree?: (a: F, b: F) => boolean;
+    readonly substantive?: (ev: object) => boolean;
+}
+export interface RunLedgerSnapshotDeps<F = never> {
+    readonly isParked: (taskId: string, signal: AbortSignal) => Promise<boolean>;
+    readonly frames: (taskId: string, signal: AbortSignal) => AsyncIterable<object>;
+    readonly budgetMs?: number;
+    readonly log?: (msg: string) => void;
+    readonly fold?: RunLedgerFold<F>;
+}
+export declare function readRunLedgerSnapshot<F = never>(taskId: string, callId: string | undefined, deps: RunLedgerSnapshotDeps<F>, signal?: AbortSignal): Promise<RunLedgerSnapshot<F> | null>;

package/dist/runLedgerSnapshot.js

@@ -0,0 +1,272 @@
+import { createStreamDrainingLegs } from './streamDrainingLegs.js';
+import { abortableSleep, settleWithinDeadline } from './abortableSleep.js';
+import { readOwnDataValue } from './ownKey.js';
+const RUN_LEDGER_SNAPSHOT_BUDGET_MS = 8_000;
+const UNNUMBERED_FRAME_CAP = 64;
+const PARK_TRAILER_MAX = 4;
+function frameSeq(ev) {
+    try {
+        const id = ev?.id;
+        if (typeof id !== 'string' || id.length === 0)
+            return undefined;
+        const n = Number(id);
+        return Number.isSafeInteger(n) && n >= 0 ? n : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isParkMarker(ev) {
+    try {
+        const t = ev?.type;
+        return t === 'suspended' || t === 'needs_review';
+    }
+    catch {
+        return false;
+    }
+}
+function isOwnToolStart(ev, callId) {
+    if (callId === undefined || callId.length === 0)
+        return false;
+    try {
+        const e = ev;
+        return e !== null && typeof e === 'object' && e.type === 'tool_start' && e.toolCallId === callId;
+    }
+    catch {
+        return false;
+    }
+}
+function errorNameOf(e) {
+    try {
+        const name = e?.name;
+        return typeof name === 'string' ? name : 'Error';
+    }
+    catch {
+        return 'Error';
+    }
+}
+function budgetMsOf(deps) {
+    try {
+        const raw = readOwnDataValue(deps, 'budgetMs');
+        return typeof raw === 'number' && Number.isFinite(raw) ? Math.max(0, raw) : RUN_LEDGER_SNAPSHOT_BUDGET_MS;
+    }
+    catch {
+        return RUN_LEDGER_SNAPSHOT_BUDGET_MS;
+    }
+}
+export async function readRunLedgerSnapshot(taskId, callId, deps, signal) {
+    const log = (msg) => {
+        try {
+            deps.log?.(msg);
+        }
+        catch {
+        }
+    };
+    if (typeof taskId !== 'string' || taskId.length === 0)
+        return null;
+    const ac = new AbortController();
+    const onOuterAbort = () => ac.abort();
+    let outerWatched = false;
+    try {
+        if (signal?.aborted === true)
+            return null;
+        signal?.addEventListener('abort', onOuterAbort, { once: true });
+        outerWatched = signal !== undefined;
+    }
+    catch (e) {
+        log(`[ledgerSnapshot] signal-unreadable task=${taskId} name=${errorNameOf(e)}`);
+        return null;
+    }
+    const budget = budgetMsOf(deps);
+    let onExpire;
+    const expired = new Promise((resolve) => {
+        onExpire = () => resolve(null);
+        if (ac.signal.aborted)
+            resolve(null);
+        else
+            ac.signal.addEventListener('abort', onExpire, { once: true });
+    });
+    const parkedNow = async () => {
+        try {
+            return (await deps.isParked(taskId, ac.signal)) === true;
+        }
+        catch (e) {
+            log(`[ledgerSnapshot] parked-read-threw task=${taskId} name=${errorNameOf(e)}`);
+            return false;
+        }
+    };
+    const waitAbortable = (ms) => abortableSleep(Math.max(0, ms), ac.signal).then(() => !ac.signal.aborted);
+    const readOnce = async (drainLegs) => {
+        let max;
+        let folded;
+        let numbered = 0;
+        let lastParkAt = -1;
+        let openToolStart;
+        let unnumbered = 0;
+        let preambleLen = 0;
+        let unnumberedRun = 0;
+        let complete = false;
+        let cappedOut = false;
+        let disordered = false;
+        const passAc = new AbortController();
+        const onOuter = () => passAc.abort();
+        if (ac.signal.aborted)
+            passAc.abort();
+        else
+            ac.signal.addEventListener('abort', onOuter, { once: true });
+        try {
+            if (deps.fold !== undefined)
+                folded = deps.fold.init();
+            for await (const ev of deps.frames(taskId, passAc.signal)) {
+                if (ac.signal.aborted)
+                    break;
+                if (drainLegs.see(ev))
+                    continue;
+                const seq = frameSeq(ev);
+                if (seq === undefined && deps.fold?.substantive?.(ev) === true) {
+                    disordered = true;
+                    break;
+                }
+                if (seq === undefined) {
+                    unnumbered += 1;
+                    if (unnumbered > UNNUMBERED_FRAME_CAP + 3 * preambleLen) {
+                        cappedOut = true;
+                        break;
+                    }
+                    if (max === undefined) {
+                        preambleLen += 1;
+                        continue;
+                    }
+                    unnumberedRun += 1;
+                    if (preambleLen > 0 && unnumberedRun >= 2 * preambleLen) {
+                        complete = true;
+                        break;
+                    }
+                    continue;
+                }
+                unnumberedRun = 0;
+                if (deps.fold?.strictOrder === true && max !== undefined && seq <= max) {
+                    disordered = true;
+                    break;
+                }
+                numbered += 1;
+                if (max === undefined || seq > max)
+                    max = seq;
+                if (isParkMarker(ev))
+                    lastParkAt = numbered;
+                if (isOwnToolStart(ev, callId))
+                    openToolStart = ev;
+                if (deps.fold !== undefined)
+                    folded = deps.fold.step(folded, ev);
+            }
+            if (!complete && !cappedOut && !disordered && !ac.signal.aborted) {
+                const drained = drainLegs.legEnded('returned');
+                if (drained !== undefined)
+                    return { kind: 'drained', decision: drained };
+                complete = true;
+            }
+        }
+        catch (e) {
+            drainLegs.legEnded('threw');
+            const name = errorNameOf(e);
+            if (!ac.signal.aborted && name === 'StreamEndedWithoutTerminalError')
+                complete = true;
+            else
+                log(`[ledgerSnapshot] read-ended-unproven task=${taskId} name=${name}`);
+        }
+        finally {
+            passAc.abort();
+            ac.signal.removeEventListener('abort', onOuter);
+        }
+        if (!complete || disordered || max === undefined || ac.signal.aborted) {
+            if (disordered)
+                log(`[ledgerSnapshot] read-unordered task=${taskId}`);
+            return { kind: 'read', result: null };
+        }
+        const nearParkTail = lastParkAt > 0 && numbered - lastParkAt <= PARK_TRAILER_MAX;
+        return {
+            kind: 'read',
+            result: { max, nearParkTail, ...(openToolStart !== undefined ? { openToolStart } : {}), ...(deps.fold !== undefined ? { folded: folded } : {}) },
+        };
+    };
+    const readPass = async () => {
+        const drainLegs = createStreamDrainingLegs();
+        for (;;) {
+            const once = await readOnce(drainLegs);
+            if (once.kind === 'read')
+                return once.result;
+            if (!('reconnectAfterMs' in once.decision)) {
+                log(`[ledgerSnapshot] drained-give-up task=${taskId}`);
+                return null;
+            }
+            log(`[ledgerSnapshot] drained-reread task=${taskId} ms=${String(once.decision.reconnectAfterMs)}`);
+            if (!(await waitAbortable(once.decision.reconnectAfterMs)))
+                return null;
+        }
+    };
+    const body = async () => {
+        try {
+            if (!(await parkedNow())) {
+                log(`[ledgerSnapshot] not-parked-before task=${taskId}`);
+                return null;
+            }
+            const [first, second] = await Promise.all([readPass(), readPass()]);
+            if (first === null) {
+                log(`[ledgerSnapshot] no-proof task=${taskId}`);
+                return null;
+            }
+            if (!first.nearParkTail) {
+                log(`[ledgerSnapshot] tail-not-at-park task=${taskId}`);
+                return null;
+            }
+            if (second === null || second.max !== first.max || !second.nearParkTail) {
+                log(`[ledgerSnapshot] passes-disagree-on-end task=${taskId}`);
+                return null;
+            }
+            const agree = deps.fold?.agree;
+            if (agree !== undefined && !(first.folded !== undefined && second.folded !== undefined && agree(first.folded, second.folded) === true)) {
+                log(`[ledgerSnapshot] passes-disagree-on-fold task=${taskId}`);
+                return null;
+            }
+            const chosen = second.openToolStart !== undefined ? second : first;
+            if (!(await parkedNow())) {
+                log(`[ledgerSnapshot] not-parked-after task=${taskId}`);
+                return null;
+            }
+            if (ac.signal.aborted)
+                return null;
+            return {
+                highWater: String(chosen.max),
+                ...(chosen.openToolStart !== undefined ? { openToolStart: chosen.openToolStart } : {}),
+                ...(deps.fold !== undefined && chosen.folded !== undefined ? { folded: chosen.folded } : {}),
+            };
+        }
+        catch (e) {
+            log(`[ledgerSnapshot] internal-error task=${taskId} name=${errorNameOf(e)}`);
+            return null;
+        }
+    };
+    try {
+        const bounded = settleWithinDeadline(budget, (deadline) => {
+            if (deadline.aborted)
+                ac.abort();
+            else
+                deadline.addEventListener('abort', () => ac.abort(), { once: true });
+            return body();
+        }).then((settled) => (settled.kind === 'value' ? settled.value : null));
+        return await Promise.race([bounded, expired]);
+    }
+    finally {
+        if (outerWatched) {
+            try {
+                signal?.removeEventListener('abort', onOuterAbort);
+            }
+            catch (e) {
+                log(`[ledgerSnapshot] signal-unlisten-threw task=${taskId} name=${errorNameOf(e)}`);
+            }
+        }
+        if (onExpire !== undefined)
+            ac.signal.removeEventListener('abort', onExpire);
+        ac.abort();
+    }
+}

package/dist/runPermissionModeSwitch.d.ts

@@ -0,0 +1,57 @@
+import type { UiLanguage } from './env/uiLanguage.js';
+import { type PermissionModeReceiptView } from './adapter/downstream/wiringManifestView.js';
+import { SDK_PERMISSION_MODE_ADMISSION_FOLDS, SDK_PERMISSION_MODE_PERSIST_MISSES } from './generated/sdkFactTables.js';
+import { type PermissionModeWriteReading } from './permissionModeWriteCapability.js';
+import type { PermissionMode } from './permissionWireCaps.js';
+export type { PermissionModeReceiptView };
+type AdmissionFold = (typeof SDK_PERMISSION_MODE_ADMISSION_FOLDS)[number];
+type PersistMiss = (typeof SDK_PERMISSION_MODE_PERSIST_MISSES)[number];
+export interface PermissionModeAdmissionView {
+    readonly requested: string;
+    readonly admitted: string;
+    readonly foldedBy: AdmissionFold;
+}
+export type RunPermissionModeSwitchOutcome = {
+    readonly kind: 'switched';
+    readonly taskId: string;
+    readonly sessionId: string;
+    readonly permissionMode: PermissionModeReceiptView;
+    readonly admission?: PermissionModeAdmissionView;
+    readonly persisted: true;
+} | {
+    readonly kind: 'switched';
+    readonly taskId: string;
+    readonly sessionId: string;
+    readonly permissionMode: PermissionModeReceiptView;
+    readonly admission?: PermissionModeAdmissionView;
+    readonly persisted: false;
+    readonly persistMiss: PersistMiss;
+} | {
+    readonly kind: 'not-running';
+} | {
+    readonly kind: 'not-found';
+} | {
+    readonly kind: 'refused';
+    readonly status: number;
+    readonly errorCode?: string;
+} | {
+    readonly kind: 'unconfirmed';
+    readonly why: 'transport' | 'server-error' | 'unreadable-answer';
+    readonly status?: number;
+} | {
+    readonly kind: 'unavailable';
+};
+export interface RunPermissionModeSwitchRuns {
+    setPermissionMode(taskId: string, mode: PermissionMode, opts?: {
+        session?: string;
+        signal?: AbortSignal;
+    }): Promise<object>;
+}
+export interface RunPermissionModeSwitchOptions {
+    readonly permissionModeWrite?: PermissionModeWriteReading | undefined;
+    readonly sessionId?: string | undefined;
+    readonly signal?: AbortSignal | undefined;
+}
+export declare const PERMISSION_MODE_SWITCH_RESULT_KEYS: readonly ["taskId", "sessionId", "status", "permissionMode", "admission", "persisted", "persistMiss"];
+export declare function setRunPermissionMode(runs: RunPermissionModeSwitchRuns | null | undefined, taskId: string, mode: PermissionMode, opts?: RunPermissionModeSwitchOptions): Promise<RunPermissionModeSwitchOutcome>;
+export declare function runPermissionModeSwitchLine(outcome: RunPermissionModeSwitchOutcome, lang?: UiLanguage): string;