@sema-agent/client-core 0.97.1 → 0.99.0

package/dist/retryStatus.js

@@ -1,4 +1,5 @@
 import { displayUntrusted } from './displayUntrusted.js';
+import { guardedRead, readOwnDataFiniteNumber, readOwnDataNonEmptyString, readOwnDataValue } from './ownKey.js';
 export const BRAIN_STATUS_PHASES = [
     'rate_limited',
     'retrying',
@@ -25,9 +26,12 @@ export const BRAIN_STATUS_PAYLOAD_KEYS = [
 ];
 const _brainStatusKeyPin = [true, true];
 void _brainStatusKeyPin;
+const RETRY_AT_SKEW_BUDGET_MS = 5_000;
 export function mapBrainStatusToRetry(p, nowMs) {
     const remainingMs = typeof p.retryInMs === 'number' ? p.retryInMs : (p.retryInSec ?? 0) * 1000;
-    const deadline = nowMs + Math.max(0, remainingMs);
+    const localDeadline = nowMs + Math.max(0, remainingMs);
+    const producerAt = typeof p.retryAtMs === 'number' && Number.isFinite(p.retryAtMs) ? p.retryAtMs : undefined;
+    const deadline = producerAt !== undefined && Math.abs(producerAt - localDeadline) <= RETRY_AT_SKEW_BUDGET_MS ? producerAt : localDeadline;
     const counts = {
         ...(typeof p.attempt === 'number' ? { attempt: p.attempt } : {}),
         ...(typeof p.maxRetries === 'number' ? { maxRetries: p.maxRetries } : {}),
@@ -74,3 +78,183 @@ export function mapBrainStatusToRetry(p, nowMs) {
             return { kind: 'error', deadline, ...extra, error: { formatted: '' } };
     }
 }
+export function retryStatusFromArm(arm, nowMs) {
+    const object = guardedRead(() => typeof arm === 'object' && arm !== null && !Array.isArray(arm));
+    if (object !== true || arm === null || arm === undefined)
+        return undefined;
+    const bit = (key) => guardedRead(() => readOwnDataValue(arm, key));
+    if (typeof bit('parentToolCallId') === 'string')
+        return undefined;
+    const num = (key) => {
+        const v = bit(key);
+        return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+    };
+    const str = (key) => {
+        const v = bit(key);
+        return typeof v === 'string' ? v : undefined;
+    };
+    const word = (key) => {
+        const v = str(key);
+        return v !== undefined && v.length > 0 ? v : undefined;
+    };
+    const [detail, retryInSec, retryInMs, attempt, maxRetries, errClass, retryAtMs, errorStatus, elapsedMs, timeoutMs, providerCondition, providerConditionSource] = [
+        str('detail'), num('retryInSec'), num('retryInMs'), num('attempt'), num('maxRetries'), str('errClass'), num('retryAtMs'), num('errorStatus'), num('elapsedMs'), num('timeoutMs'), word('providerCondition'), word('providerConditionSource'),
+    ];
+    const phase = str('phase');
+    if (phase === undefined)
+        return undefined;
+    return mapBrainStatusToRetry({
+        phase,
+        ...(detail !== undefined ? { detail } : {}),
+        ...(retryInSec !== undefined ? { retryInSec } : {}),
+        ...(retryInMs !== undefined ? { retryInMs } : {}),
+        ...(attempt !== undefined ? { attempt } : {}),
+        ...(maxRetries !== undefined ? { maxRetries } : {}),
+        ...(errClass !== undefined ? { errClass } : {}),
+        ...(retryAtMs !== undefined ? { retryAtMs } : {}),
+        ...(errorStatus !== undefined ? { errorStatus } : {}),
+        ...(elapsedMs !== undefined ? { elapsedMs } : {}),
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        ...(providerCondition !== undefined ? { providerCondition } : {}),
+        ...(providerConditionSource !== undefined ? { providerConditionSource } : {}),
+    }, nowMs);
+}
+const WAIT_SWITCH_FRACTION = 0.5;
+const CONDITION_READINGS = Object.freeze({
+    quota_exhausted: { clause: 'this account cannot be served by the model service until someone acts or its usage window resets', recourse: 'switch_model' },
+    throttled: { clause: 'the model service is rate limiting requests, which clears on its own', recourse: 'switch_model' },
+    overloaded: { clause: 'the model service is overloaded', recourse: 'switch_model' },
+    stop_other: { clause: 'the model service refused this request', resendNote: 'resending will not change it', recourse: 'fix_request' },
+    unknown: null,
+});
+function conditionReadingOf(word) {
+    if (word === undefined || !Object.hasOwn(CONDITION_READINGS, word))
+        return undefined;
+    return CONDITION_READINGS[word] ?? undefined;
+}
+function noticeNumber(carrier, key) {
+    return guardedRead(() => readOwnDataFiniteNumber(carrier, key));
+}
+function noticeText(carrier, key) {
+    return guardedRead(() => readOwnDataNonEmptyString(carrier, key));
+}
+function noticeValue(carrier, key) {
+    return guardedRead(() => readOwnDataValue(carrier, key));
+}
+function washedText(raw) {
+    if (raw === undefined)
+        return undefined;
+    const shown = displayUntrusted(raw);
+    return shown.trim() === '' ? undefined : shown;
+}
+function noticeCount(n) {
+    return n !== undefined && Number.isInteger(n) && n >= 1 ? n : undefined;
+}
+function noticeHttp(n) {
+    return n !== undefined && Number.isInteger(n) && n >= 100 && n <= 999 ? n : undefined;
+}
+function spanText(ms) {
+    const total = Math.floor(ms / 1000);
+    const h = Math.floor(total / 3600);
+    const mi = Math.floor((total % 3600) / 60);
+    const se = total % 60;
+    return h > 0 ? `${h}h ${mi}m ${se}s` : mi > 0 ? `${mi}m ${se}s` : `${se}s`;
+}
+function noticeAttemptTail(attempt, maxRetries) {
+    if (attempt !== undefined && maxRetries !== undefined)
+        return `, attempt ${attempt} of ${maxRetries}`;
+    if (attempt !== undefined)
+        return `, attempt ${attempt}`;
+    if (maxRetries !== undefined)
+        return `, up to ${maxRetries} ${maxRetries === 1 ? 'retry' : 'retries'}`;
+    return '';
+}
+function sealNotice(line, phase, recourse) {
+    return Object.freeze(recourse === undefined ? { line, phase } : { line, recourse, phase });
+}
+export function retryStatusNotice(status, ctx) {
+    const modelName = washedText(noticeText(ctx, 'modelName'))?.trim();
+    const prefix = modelName === undefined || modelName === '' ? '' : `${modelName}: `;
+    if (status === null)
+        return sealNotice('', 'cleared', undefined);
+    const armWord = noticeText(status, 'kind');
+    const kind = armWord === 'stalled' || armWord === 'waiting' ? armWord : 'error';
+    if (kind === 'waiting') {
+        const elapsedRaw = noticeNumber(status, 'elapsedMs');
+        const timeoutRaw = noticeNumber(status, 'timeoutMs');
+        const elapsed = elapsedRaw !== undefined && elapsedRaw >= 0 && elapsedRaw <= Number.MAX_SAFE_INTEGER ? elapsedRaw : undefined;
+        const ceiling = timeoutRaw !== undefined && timeoutRaw > 0 && timeoutRaw <= Number.MAX_SAFE_INTEGER ? timeoutRaw : undefined;
+        const progress = [...(elapsed === undefined ? [] : [`${spanText(elapsed)} so far`]), ...(ceiling === undefined ? [] : [`limit ${spanText(ceiling)}`])];
+        const offerSwitch = prefix !== '' && elapsed !== undefined && ceiling !== undefined && elapsed >= ceiling * WAIT_SWITCH_FRACTION;
+        const text = `${prefix}Waiting for the model's first token${progress.length === 0 ? '' : ` — ${progress.join(', ')}`}${offerSwitch ? '; keep waiting or switch model' : ''}`;
+        return sealNotice(text, 'waiting_first_token', offerSwitch ? 'switch_model' : 'wait');
+    }
+    const terminal = kind === 'error' && noticeValue(status, 'terminal') === true;
+    const reading = conditionReadingOf(noticeText(status, 'providerCondition'));
+    const http = noticeHttp(noticeNumber(status, 'errorStatus'));
+    const attempt = noticeCount(noticeNumber(status, 'attempt'));
+    const maxRetries = noticeCount(noticeNumber(status, 'maxRetries'));
+    const engineWords = kind === 'stalled' ? noticeText(status, 'detail') : noticeText(noticeValue(status, 'error'), 'formatted');
+    const httpPart = http === undefined ? '' : ` (HTTP ${http})`;
+    let first;
+    if (terminal) {
+        const after = attempt === undefined ? '' : ` after ${attempt} attempt${attempt === 1 ? '' : 's'}`;
+        const why = reading === undefined ? '' : `: ${reading.clause}${reading.resendNote === undefined ? '' : `, and ${reading.resendNote}`}`;
+        first = `Stopped${after}${why}${httpPart}`;
+    }
+    else {
+        const head = reading !== undefined ? `${reading.clause.charAt(0).toUpperCase()}${reading.clause.slice(1)}` : http !== undefined || kind === 'error' ? 'Request failed' : 'Waiting for the API response';
+        first = `${head}${httpPart} — ${kind === 'stalled' ? 'will retry' : 'retrying'}${noticeAttemptTail(attempt, maxRetries)}`;
+    }
+    const note = washedText(engineWords);
+    const serviceSide = http !== undefined && (http === 429 || (http >= 500 && http <= 599));
+    const knownArm = armWord === 'stalled' || armWord === 'error';
+    const recourse = !knownArm
+        ? undefined
+        : reading !== undefined
+            ? reading.recourse
+            : serviceSide
+                ? 'switch_model'
+                : !terminal
+                    ? 'wait'
+                    : undefined;
+    return sealNotice(`${prefix}${first}${note === undefined ? '' : ` · ${note}`}`, kind === 'stalled' ? 'reconnecting' : terminal ? 'gave_up' : 'retrying', recourse);
+}
+const API_ERROR_PROVIDER_TEXT_MAX = 200;
+function isRecordObject(v) {
+    return guardedRead(() => typeof v === 'object' && v !== null && !Array.isArray(v)) === true;
+}
+export function apiErrorFactsOfRow(row) {
+    if (!isRecordObject(row))
+        return Object.freeze({});
+    const status = noticeHttp(noticeNumber(row, '_sema_api_error_status'));
+    const providerCondition = noticeText(row, '_sema_provider_condition');
+    const errorCode = noticeText(row, '_sema_api_error_code');
+    return Object.freeze({
+        ...(status !== undefined ? { status } : {}),
+        ...(providerCondition !== undefined ? { providerCondition } : {}),
+        ...(errorCode !== undefined ? { errorCode } : {}),
+    });
+}
+export function apiErrorNotice(facts, ctx) {
+    if (!isRecordObject(facts))
+        return undefined;
+    const status = noticeHttp(noticeNumber(facts, 'status'));
+    const providerCondition = noticeText(facts, 'providerCondition');
+    if (status === undefined && conditionReadingOf(providerCondition) === undefined)
+        return undefined;
+    const rawText = noticeText(ctx, 'providerText');
+    const shownText = rawText === undefined ? undefined : washedText(displayUntrusted(rawText, { max: API_ERROR_PROVIDER_TEXT_MAX }));
+    const terminal = {
+        kind: 'error',
+        deadline: 0,
+        terminal: true,
+        ...(status !== undefined ? { errorStatus: status } : {}),
+        ...(providerCondition !== undefined ? { providerCondition } : {}),
+        error: { formatted: shownText ?? '' },
+    };
+    const modelName = noticeText(ctx, 'modelName');
+    const notice = retryStatusNotice(terminal, modelName !== undefined ? { modelName } : undefined);
+    const recourse = status === 401 || status === 403 ? 'check_credentials' : notice.recourse;
+    return Object.freeze(recourse === undefined ? { line: notice.line } : { line: notice.line, recourse });
+}

package/dist/rewindArchiveCapability.d.ts

@@ -3,13 +3,9 @@ import type { RewindMode } from './rewindWireCaps.js';
 export { projectRewindArchiveCapability, rewindConversationAvailability } from './rewindArchiveReading.js';
 export type { RewindArchiveBit, RewindArchiveReading, RewindCodeArchive } from './rewindArchiveReading.js';
 export type RewindArchiveMode = 'both' | 'code';
-export declare function noteEngineCapsForRewindArchive(baseUrl: string, caps: unknown, opts?: {
-    generation?: number;
-}): void;
 export declare function observedRewindArchive(baseUrl?: string | undefined): RewindArchiveReading;
 export declare function rewindCodeArchiveAvailability(reading: RewindArchiveReading, mode: RewindArchiveMode): RewindCodeArchive;
 export declare function rewindArchiveDoctorDetail(reading: RewindArchiveReading, mode: RewindArchiveMode): string;
 export declare function engineRewindRefusedNow(option: RewindMode, reading?: RewindArchiveReading): boolean;
 export declare function rewindConversationDoctorDetail(reading: RewindArchiveReading): string;
 export declare function rewindRestoreFilesEpochDetail(reading: RewindArchiveReading): string;
-export declare function __resetRewindArchiveReadingsForTests(): void;

package/dist/rewindArchiveCapability.js

@@ -1,12 +1,7 @@
 import { engineWireTarget } from './engineWireTarget.js';
-import { resetRewindArchiveReader, rewindArchiveReadingAt, rewindConversationAvailability, } from './rewindArchiveReading.js';
+import { rewindArchiveReadingAt, rewindConversationAvailability, } from './rewindArchiveReading.js';
 import { unreadableReadingDetail } from './engineCapReader.js';
 export { projectRewindArchiveCapability, rewindConversationAvailability } from './rewindArchiveReading.js';
-export function noteEngineCapsForRewindArchive(baseUrl, caps, opts) {
-    void baseUrl;
-    void caps;
-    void opts;
-}
 export function observedRewindArchive(baseUrl = engineWireTarget()?.baseUrl) {
     return rewindArchiveReadingAt(baseUrl);
 }
@@ -87,11 +82,8 @@ export function rewindRestoreFilesEpochDetail(reading) {
         case 'off':
             return 'this engine does not announce the restore-files request key, so a rewind with code restore built from this reading leaves the key out and moves the conversation only';
         case 'not_reported':
-            return 'this engine does not report the restore-files epoch bit (older engine), so a rewind with code restore built from this reading leaves the key out and moves the conversation only';
+            return 'this engine does not report the restore-files epoch bit, so a rewind with code restore built from this reading leaves the key out and moves the conversation only';
         case 'malformed':
             return 'the restore-files epoch bit is reported in an unreadable shape, so a rewind with code restore built from this reading leaves the key out and moves the conversation only';
     }
 }
-export function __resetRewindArchiveReadingsForTests() {
-    resetRewindArchiveReader();
-}

package/dist/rewindArchiveReading.d.ts

@@ -13,5 +13,4 @@ export type RewindArchiveReading = {
 export type RewindCodeArchive = 'available' | 'unavailable' | 'unknown';
 export declare function projectRewindArchiveCapability(caps: unknown): RewindArchiveReading | undefined;
 export declare function rewindArchiveReadingAt(baseUrl: string | undefined): RewindArchiveReading;
-export declare function resetRewindArchiveReader(): void;
 export declare function rewindConversationAvailability(reading: RewindArchiveReading): RewindCodeArchive;

package/dist/rewindArchiveReading.js

@@ -41,9 +41,6 @@ const reader = createEngineCapReader({
 export function rewindArchiveReadingAt(baseUrl) {
     return reader.observed(baseUrl);
 }
-export function resetRewindArchiveReader() {
-    reader.__resetForTests();
-}
 export function rewindConversationAvailability(reading) {
     if (reading.kind !== 'present')
         return 'unknown';

package/dist/runCancelContext.d.ts

@@ -12,6 +12,7 @@ export type RunCancelContextReading = {
 };
 export declare function readRunCancelContext(record: unknown): RunCancelContextReading | undefined;
 import { type RunTerminalRead } from './runTerminal.js';
+import type { AbortCause } from '@sema-agent/sdk';
 export type RunAbortCause = {
     kind: 'cancelled';
     context?: RunCancelContextView;
@@ -30,7 +31,7 @@ export type RunAbortCause = {
 export declare const RUN_CANCELLED_CODE: "cancelled";
 export declare function classifyRunAbortCause(record: unknown): RunAbortCause;
 export declare const ABORT_CAUSES: readonly ["client_disconnected", "ask_park_grace_exhausted", "cancel_verb"];
-export type AbortCause = (typeof ABORT_CAUSES)[number];
+export type { AbortCause };
 export type AbortCauseReading = {
     readonly kind: 'known';
     readonly cause: AbortCause;

package/dist/runCancelContext.js

@@ -34,9 +34,9 @@ export function readRunCancelContext(record) {
     };
 }
 import { readRunTerminal } from './runTerminal.js';
+import { isSdkRunLive } from './terminalStatuses.js';
 import { SDK_ABORT_CAUSES } from './generated/sdkFactTables.js';
 export const RUN_CANCELLED_CODE = 'cancelled';
-const LIVE_STATUSES = new Set(['running', 'queued', 'suspended', 'needs_review']);
 export function classifyRunAbortCause(record) {
     if (record === null || typeof record !== 'object')
         return { kind: 'unknown' };
@@ -53,11 +53,13 @@ export function classifyRunAbortCause(record) {
     }
     if (read !== null && read.kind === 'paused')
         return { kind: 'run_still_live', ...(status !== undefined ? { status } : {}) };
-    if ((read === null || read.kind === 'unknown') && status !== undefined && LIVE_STATUSES.has(status))
+    if ((read === null || read.kind === 'unknown') && status !== undefined && isSdkRunLive(status))
         return { kind: 'run_still_live', status };
     return { kind: 'unknown', ...(read !== null ? { terminal: read.kind } : {}) };
 }
 export const ABORT_CAUSES = SDK_ABORT_CAUSES;
+const _abortCauseTablePin = true;
+void _abortCauseTablePin;
 function ownDataOf(o, key) {
     const d = Object.getOwnPropertyDescriptor(o, key);
     return d !== undefined && Object.hasOwn(d, 'value') ? d.value : undefined;

package/dist/runReattachPolicy.d.ts

@@ -0,0 +1,31 @@
+export declare const REATTACH_MAX_TRIES = 5;
+export interface ReattachBudget {
+    readonly tries: number;
+    readonly drainingStreak: number;
+    readonly drainingTotal: number;
+}
+export declare const REATTACH_BUDGET_FRESH: ReattachBudget;
+export type ReattachEvent = {
+    readonly cause: 'connection_lost';
+    readonly hasRunId: boolean;
+    readonly error?: object;
+} | {
+    readonly cause: 'stream_cap';
+    readonly hasRunId: boolean;
+} | {
+    readonly cause: 'stream_draining';
+    readonly hasRunId: boolean;
+    readonly frame: object;
+    readonly madeProgress?: boolean;
+};
+export type ReattachGiveUp = 'no_run_id' | 'budget_exhausted' | 'bad_input';
+export type ReattachDecision = {
+    readonly action: 'reattach';
+    readonly afterMs: number;
+    readonly budget: ReattachBudget;
+} | {
+    readonly action: 'give_up';
+    readonly reason: ReattachGiveUp;
+    readonly budget: ReattachBudget;
+};
+export declare function runReattachPolicy(budget: ReattachBudget, event: ReattachEvent): ReattachDecision;

package/dist/runReattachPolicy.js

@@ -0,0 +1,46 @@
+import { STREAM_DRAINING_RECONNECT_MAX, drainingRetryDelayMs, isPreStreamDrainingReject } from './wireErrorTriage.js';
+import { drainingLegStep } from './streamDrainingLegs.js';
+export const REATTACH_MAX_TRIES = 5;
+const DRAINING_TOTAL_MAX = REATTACH_MAX_TRIES * STREAM_DRAINING_RECONNECT_MAX;
+export const REATTACH_BUDGET_FRESH = Object.freeze({ tries: 0, drainingStreak: 0, drainingTotal: 0 });
+const isCount = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+const giveUp = (reason, budget) => Object.freeze({ action: 'give_up', reason, budget });
+const reattach = (afterMs, tries, drainingStreak, drainingTotal) => Object.freeze({ action: 'reattach', afterMs, budget: Object.freeze({ tries, drainingStreak, drainingTotal }) });
+export function runReattachPolicy(budget, event) {
+    try {
+        if (typeof budget !== 'object' || budget === null || !isCount(budget.tries) || !isCount(budget.drainingStreak) || !isCount(budget.drainingTotal))
+            return giveUp('bad_input', REATTACH_BUDGET_FRESH);
+        if (typeof event !== 'object' || event === null || typeof event.hasRunId !== 'boolean')
+            return giveUp('bad_input', budget);
+        if (!event.hasRunId)
+            return giveUp('no_run_id', budget);
+        const { tries, drainingStreak, drainingTotal } = budget;
+        if (event.cause === 'connection_lost') {
+            if (tries >= REATTACH_MAX_TRIES)
+                return giveUp('budget_exhausted', budget);
+            const next = tries + 1;
+            const afterMs = isPreStreamDrainingReject(event.error) ? drainingRetryDelayMs(event.error, next - 1) : 1000 * next;
+            return reattach(afterMs, next, 0, drainingTotal);
+        }
+        if (event.cause === 'stream_cap') {
+            if (tries >= REATTACH_MAX_TRIES)
+                return giveUp('budget_exhausted', budget);
+            return reattach(0, tries + 1, 0, drainingTotal);
+        }
+        if (event.cause === 'stream_draining') {
+            const streak = event.madeProgress === true ? 0 : drainingStreak;
+            const { decision, streak: nextStreak } = drainingLegStep(streak, event.frame);
+            if ('reconnectAfterMs' in decision && drainingTotal < DRAINING_TOTAL_MAX)
+                return reattach(decision.reconnectAfterMs, tries, nextStreak, drainingTotal + 1);
+            if ('giveUp' in decision && decision.giveUp === 'not_draining_end')
+                return giveUp('bad_input', budget);
+            if (tries >= REATTACH_MAX_TRIES)
+                return giveUp('budget_exhausted', budget);
+            return reattach(0, tries + 1, nextStreak, drainingTotal);
+        }
+        return giveUp('bad_input', budget);
+    }
+    catch {
+        return giveUp('bad_input', REATTACH_BUDGET_FRESH);
+    }
+}

package/dist/runTerminal.d.ts

@@ -1,4 +1,4 @@
-import type { CheckpointGate, TerminalModelOutputInvalidDetail } from '@sema-agent/sdk';
+import type { CheckpointGate, PromptBlockCause, TerminalModelOutputInvalidDetail } from '@sema-agent/sdk';
 export type RunTerminalPlane = 'cause' | 'flat';
 export interface RunTerminalPause {
     gate?: CheckpointGate;
@@ -55,7 +55,7 @@ export type RunTerminalCompletedDetail = {
     word: string;
 };
 export declare const PROMPT_BLOCK_CAUSES: readonly ["block", "crashed", "timeout", "cancelled"];
-export type PromptBlockCause = (typeof PROMPT_BLOCK_CAUSES)[number];
+export type { PromptBlockCause };
 export type RunTerminalBlockedDetail = {
     kind: 'prompt_blocked_by_hook';
     cause: PromptBlockCause;
@@ -69,9 +69,7 @@ export type RunTerminalBlockedDetail = {
     kind: 'unrecognized';
     word: string;
 };
-export type RunTerminalRead = RunTerminalReadArm & {
-    readonly replay?: true;
-};
+export type RunTerminalRead = RunTerminalReadArm;
 type RunTerminalReadArm = {
     kind: 'completed';
     plane: RunTerminalPlane;
@@ -102,4 +100,3 @@ export declare function runTerminalGateKind(read: RunTerminalRead | null): strin
 export declare function runTerminalGateToolName(read: RunTerminalRead | null): string | undefined;
 export declare function runTerminalCode(read: RunTerminalRead | null): string | undefined;
 export declare function isReviewPark(read: RunTerminalRead | null): boolean;
-export {};

package/dist/runTerminal.js

@@ -3,6 +3,8 @@ import { isSdkRunParked } from './terminalStatuses.js';
 import { readOwnDataNonEmptyString, readOwnDataValue } from './ownKey.js';
 import { doneResultView } from './replayBody.js';
 export const PROMPT_BLOCK_CAUSES = CORE_PROMPT_BLOCK_CAUSES;
+const _promptBlockTablePin = true;
+void _promptBlockTablePin;
 const PROMPT_BLOCKED_BY_HOOK_DETAIL_KIND = 'prompt_blocked_by_hook';
 function str(v) {
     return typeof v === 'string' && v.length > 0 ? v : undefined;
@@ -267,8 +269,7 @@ export function readRunTerminal(result) {
         return null;
     const view = doneResultView(result);
     if (view.replay) {
-        const inner = readRunTerminalArm(view.engine) ?? readRunTerminalArm({ status: view.row?.status, errorCode: view.row?.errorCode, errorMessage: view.row?.error });
-        return inner === null ? null : { ...inner, replay: true };
+        return readRunTerminalArm(view.engine) ?? readRunTerminalArm({ status: view.row?.status, errorCode: view.row?.errorCode, errorMessage: view.row?.error });
     }
     return readRunTerminalArm(result);
 }
@@ -278,16 +279,14 @@ function readRunTerminalArm(result) {
     const r = result;
     if ('terminal' in r) {
         const t = r.terminal;
-        if (typeof t !== 'object' || t === null || Array.isArray(t))
-            return { kind: 'unknown', plane: 'cause' };
-        const c = t;
-        const kind = str(c.kind);
-        if (kind === undefined)
-            return { kind: 'unknown', plane: 'cause' };
+        const c = typeof t === 'object' && t !== null && !Array.isArray(t) ? t : undefined;
+        const kind = c === undefined ? undefined : str(c.kind);
         const parkWord = str(r.status);
         if (isSdkRunParked(parkWord)) {
-            return { kind: 'paused', plane: 'cause', flatStatus: parkWord, ...(kind === 'paused' ? (pauseOf(c) ?? {}) : {}) };
+            return { kind: 'paused', plane: 'cause', flatStatus: parkWord, ...(c !== undefined && kind === 'paused' ? (pauseOf(c) ?? {}) : {}) };
         }
+        if (c === undefined || kind === undefined)
+            return { kind: 'unknown', plane: 'cause' };
         switch (kind) {
             case 'completed': {
                 const detail = completedDetailOf(c);

package/dist/sandboxWire.d.ts

@@ -23,4 +23,6 @@ export declare const SANDBOX_K8S_ONLY_400_ANCHOR = "only supported on the k8s sa
 export declare const SANDBOX_NO_IMAGE_INDEX_400_ANCHOR = "requires the image index";
 export declare const SANDBOX_NO_PUBLISHED_IMAGE_404_ANCHOR = "no published sandbox image for profile";
 export declare const SANDBOX_CASCADE_CONFLICT_400_ANCHOR = "not supported together with cascade/verify";
-export declare function sandboxDegradeHint(err: unknown): string | undefined;
+export type SandboxHintHost = 'terminal' | 'web' | 'desktop';
+export declare const SANDBOX_HINT_HOSTS: readonly SandboxHintHost[];
+export declare function sandboxDegradeHint(err: unknown, host?: SandboxHintHost): string | undefined;

package/dist/sandboxWire.js

@@ -1,5 +1,6 @@
 import { lastFlagValue } from './argvFlagValue.js';
 import { CAPABILITY_IMAGE_INDEX_REQUIRED } from './engineErrorCodes.js';
+import { THROWN_SLOT_UNREADABLE, readThrownSlot } from './wireFailureShape.js';
 const MAX_PROFILE_LEN = 128;
 const USAGE_HINT = "sema: --sandbox expects a profile name or 'auto'.\n" +
     '  --sandbox <profile>  run on that sandbox image profile (k8s-lane workers; list: sema cloud images list)\n' +
@@ -46,36 +47,84 @@ export const SANDBOX_K8S_ONLY_400_ANCHOR = 'only supported on the k8s sandbox ba
 export const SANDBOX_NO_IMAGE_INDEX_400_ANCHOR = 'requires the image index';
 export const SANDBOX_NO_PUBLISHED_IMAGE_404_ANCHOR = 'no published sandbox image for profile';
 export const SANDBOX_CASCADE_CONFLICT_400_ANCHOR = 'not supported together with cascade/verify';
-const SANDBOX_IMAGE_INDEX_501_HINT = 'Cloud sandbox images are not available on this engine: its storage backend keeps no image index, so profiles cannot be listed or selected here.\n' +
-    'Use a worker backed by a SQL store (it has the image index), or re-run without --sandbox.';
-function imageIndexRequiredCode(err) {
+export const SANDBOX_HINT_HOSTS = Object.freeze(['terminal', 'web', 'desktop']);
+const SANDBOX_HINT_ARMS = Object.freeze({
+    imageIndexRequired501: {
+        fact: 'Cloud sandbox images are not available on this engine: its storage backend keeps no image index, so profiles cannot be listed or selected here.',
+        sep: '\n',
+        outlet: {
+            terminal: 'Use a worker backed by a SQL store (it has the image index), or re-run without --sandbox.',
+            graphical: 'Use a worker backed by a SQL store (it has the image index), or keep the default environment.',
+        },
+    },
+    k8sLaneOnly400: {
+        subject: { terminal: '--sandbox <profile>', graphical: 'The selected sandbox image profile' },
+        fact: ' only applies on k8s-lane workers; this engine runs a host/e2b sandbox lane, so the request was honestly rejected.',
+        sep: '\n',
+        outlet: {
+            terminal: 'Re-run without --sandbox (worker default image), or point the shell at a k8s-lane worker (sema cloud engine connect <url>).',
+            graphical: 'Keep the default environment, or connect to a k8s-lane worker.',
+        },
+    },
+    noImageIndex400: {
+        fact: 'This worker has no sandbox image index configured (the sema-web-admin config center is not attached), so per-task profiles cannot resolve.',
+        sep: '\n',
+        outlet: {
+            terminal: 'Re-run without --sandbox, or use a worker with the image index enabled.',
+            graphical: 'Keep the default environment, or use a worker with the image index enabled.',
+        },
+    },
+    noPublishedImage404: {
+        fact: 'No published image matches that profile for your principal.',
+        sep: ' ',
+        outlet: {
+            terminal: 'List what you can use: sema cloud images list',
+            graphical: 'Choose one of the environments that are offered instead.',
+        },
+    },
+    cascadeConflict400: {
+        subject: { terminal: '--sandbox', graphical: 'The sandbox image profile' },
+        fact: ' cannot combine with cascade/verify submits in v1 (the per-task image would not bind to the sub-runs).',
+        sep: ' ',
+        outlet: { terminal: 'Drop one of the two.', graphical: 'Drop one of the two.' },
+    },
+});
+function sandboxHintOf(arm, host) {
+    const terminal = host === undefined || host === 'terminal';
+    const graphical = host === 'web' || host === 'desktop';
+    const subject = arm.subject === undefined ? '' : terminal ? arm.subject.terminal : arm.subject.graphical;
+    const factSegment = `${subject}${arm.fact}`;
+    if (terminal)
+        return `${factSegment}${arm.sep}${arm.outlet.terminal}`;
+    if (graphical)
+        return `${factSegment}${arm.sep}${arm.outlet.graphical}`;
+    return factSegment;
+}
+function sandboxSlot(err, key) {
+    const v = readThrownSlot(err, key, 'data');
+    return v === THROWN_SLOT_UNREADABLE ? undefined : v;
+}
+export function sandboxDegradeHint(err, host) {
+    const status = sandboxSlot(err, 'status');
+    if (status === 501 && sandboxSlot(err, 'errorCode') === CAPABILITY_IMAGE_INDEX_REQUIRED)
+        return sandboxHintOf(SANDBOX_HINT_ARMS.imageIndexRequired501, host);
+    if (typeof err !== 'object' || err === null || typeof status !== 'number')
+        return undefined;
     try {
-        return typeof err === 'object' && err !== null && err.errorCode === CAPABILITY_IMAGE_INDEX_REQUIRED;
+        const msg = err.message;
+        if (typeof msg !== 'string')
+            return undefined;
+        if (status === 400 && msg.includes(SANDBOX_K8S_ONLY_400_ANCHOR))
+            return sandboxHintOf(SANDBOX_HINT_ARMS.k8sLaneOnly400, host);
+        if (status === 400 && msg.includes(SANDBOX_NO_IMAGE_INDEX_400_ANCHOR))
+            return sandboxHintOf(SANDBOX_HINT_ARMS.noImageIndex400, host);
+        if (status === 404 && msg.includes(SANDBOX_NO_PUBLISHED_IMAGE_404_ANCHOR))
+            return sandboxHintOf(SANDBOX_HINT_ARMS.noPublishedImage404, host);
+        if (status === 400 && msg.includes(SANDBOX_CASCADE_CONFLICT_400_ANCHOR))
+            return sandboxHintOf(SANDBOX_HINT_ARMS.cascadeConflict400, host);
+        return undefined;
     }
     catch {
-        return false;
-    }
-}
-export function sandboxDegradeHint(err) {
-    const e = err;
-    if (e?.status === 501 && imageIndexRequiredCode(err))
-        return SANDBOX_IMAGE_INDEX_501_HINT;
-    if (typeof e?.status !== 'number' || typeof e?.message !== 'string')
         return undefined;
-    const msg = e.message;
-    if (e.status === 400 && msg.includes(SANDBOX_K8S_ONLY_400_ANCHOR)) {
-        return ('--sandbox <profile> only applies on k8s-lane workers; this engine runs a host/e2b sandbox lane, so the request was honestly rejected.\n' +
-            'Re-run without --sandbox (worker default image), or point the shell at a k8s-lane worker (sema cloud engine connect <url>).');
-    }
-    if (e.status === 400 && msg.includes(SANDBOX_NO_IMAGE_INDEX_400_ANCHOR)) {
-        return ('This worker has no sandbox image index configured (the sema-web-admin config center is not attached), so per-task profiles cannot resolve.\n' +
-            'Re-run without --sandbox, or use a worker with the image index enabled.');
-    }
-    if (e.status === 404 && msg.includes(SANDBOX_NO_PUBLISHED_IMAGE_404_ANCHOR)) {
-        return 'No published image matches that profile for your principal. List what you can use: sema cloud images list';
-    }
-    if (e.status === 400 && msg.includes(SANDBOX_CASCADE_CONFLICT_400_ANCHOR)) {
-        return '--sandbox cannot combine with cascade/verify submits in v1 (the per-task image would not bind to the sub-runs). Drop one of the two.';
     }
-    return undefined;
 }

package/dist/scenarioRefusal.d.ts

@@ -0,0 +1,9 @@
+export interface ScenarioRefusalReading {
+    readonly errorCode?: string;
+    readonly error?: string;
+    readonly scenario?: string;
+    readonly source?: 'ruling' | 'deployment';
+}
+export declare function scenarioRefusalOf(body: object): ScenarioRefusalReading | undefined | null;
+export declare function scenarioRefusalFromError(err: {} | null | undefined): ScenarioRefusalReading | null;
+export declare function scenarioRefusalContent(reading: ScenarioRefusalReading): string;