@sema-agent/client-core 0.98.0 → 0.99.0

package/dist/resumeRefusalCopy.js

@@ -1,4 +1,5 @@
-import { readBlockedBy, readErrorNumber, readErrorString } from './wireFailureShape.js';
+import { msg, renderMessage } from './i18n/translate.js';
+import { readBlockedBy, readErrorNumber, readErrorString, readThrownSlot } from './wireFailureShape.js';
 import { guardedRead, ownDataField, readOwnDataNonEmptyString, readOwnDataValue } from './ownKey.js';
 import { CORE_RESUME_STARTUP_CAUSES } from './generated/engineFactTables.js';
 import { RESUME_CONTEXT_UNAVAILABLE, RESUME_PLACEMENT_MISMATCH, RESUME_PREFLIGHT_REJECTED, RESUME_POLICY_FOLD_CODE, PARKED_RESUME_STARTUP_FAILED, isStatusDerivedCoarseCode, RESUME_SESSION_NOT_FOUND, REQUEST_FIELD_CONFLICT, CHECKPOINT_UNSUPPORTED_VERSION, CHECKPOINT_WALLTIME_AXIS_RETIRED, CHECKPOINT_CONFIG_REFUSED, isRefusedParkCode, refusalSaysStillPending, refusalRetriableReading, } from './engineErrorCodes.js';
@@ -27,51 +28,30 @@ export function resumeRefusalFromError(err) {
         ...(timed.retryAfterSec !== undefined ? { retryAfterSec: timed.retryAfterSec } : {}),
     };
 }
-export function resumeRefusalContent(detail) {
-    const parts = [];
-    if (detail.code === RESUME_PLACEMENT_MISMATCH) {
-        parts.push('This resume named a different placement root than the one recorded when the work was parked');
-        parts.push('The engine refused it before consuming anything — the parked work is untouched');
-        parts.push('Retry with the recorded root, or omit the placement root to inherit it');
-        return parts.join(' · ');
-    }
-    parts.push("The deployment's resume preflight refused this attempt");
-    parts.push('The refusal happened before the commit — your decision was not consumed');
-    parts.push(detail.waitable
-        ? 'The engine supplied a wait, so this token stays redeemable once the obstacle clears'
-        :
-            'The engine supplied no wait, so this refusal does not say whether the token stays redeemable');
-    return parts.join(' · ');
+export function resumeRefusalContent(detail, lang) {
+    if (detail.code === RESUME_PLACEMENT_MISMATCH)
+        return renderMessage(msg('resume.refusal.placementMismatch'), lang);
+    return renderMessage(msg(detail.waitable ? 'resume.refusal.preflightWaitable' : 'resume.refusal.preflightNoWait'), lang);
 }
 export function resumePolicyBlockFromError(err) {
     if (typeof err !== 'object' || err === null)
         return null;
     const o = err;
-    let outer;
-    try {
-        outer = o['errorCode'];
-    }
-    catch {
-        return null;
-    }
+    const outer = guardedRead(() => ownDataField(err, 'errorCode'));
     if (outer !== RESUME_POLICY_FOLD_CODE)
         return null;
     return { blockedBy: readBlockedBy(o) };
 }
-export function resumePolicyBlockContent(detail) {
+export function resumePolicyBlockContent(detail, lang) {
     const b = detail.blockedBy;
     const reason = b.kind === 'named'
         ? isStatusDerivedCoarseCode(b.code)
-            ? `The refusal did not name a more specific check (it carried only the generic code for its HTTP status: ${b.code})`
-            : `The check that refused it: ${capForDisplay(b.code, 80)}`
+            ? msg('resume.refusal.policyBlockReason.coarse', { code: b.code })
+            : msg('resume.refusal.policyBlockReason.named', { code: capForDisplay(b.code, 80) })
         : b.kind === 'absent'
-            ? 'The refusal did not name a more specific check'
-            : 'The refusal carried a more specific reason that could not be read';
-    return [
-        'The engine refused to resume this parked work at its admission check (the engine reports that its admission policy changed since the work was first accepted)',
-        reason,
-        "This refusal does not say whether anything was consumed before it or whether a retry would pass — check the task's current state before deciding again, and ask whoever operates this deployment if it keeps happening",
-    ].join(' · ');
+            ? msg('resume.refusal.policyBlockReason.absent')
+            : msg('resume.refusal.policyBlockReason.unreadable');
+    return renderMessage(msg('resume.refusal.policyBlock', { reason }), lang);
 }
 export { resumeReopenFromError, resumeReopenContent } from './hitl/suspendedReopen.js';
 const REQUIRE_EXISTING_BY_STATUS = new Map([
@@ -82,27 +62,29 @@ export function requireExistingSessionRefusalFromError(err) {
     if (typeof err !== 'object' || err === null)
         return null;
     try {
-        const o = err;
-        const status = o['status'];
+        const status = readThrownSlot(err, 'status', 'data');
         const byStatus = typeof status === 'number' ? REQUIRE_EXISTING_BY_STATUS.get(status) : undefined;
         if (byStatus === undefined)
             return null;
-        return o['errorCode'] === byStatus.code ? Object.freeze({ code: RESUME_SESSION_NOT_FOUND, form: byStatus.form }) : null;
+        return readThrownSlot(err, 'errorCode', 'data') === byStatus.code ? Object.freeze({ code: RESUME_SESSION_NOT_FOUND, form: byStatus.form }) : null;
     }
     catch {
         return null;
     }
 }
-const REQUIRE_EXISTING_SESSION_SENTENCES = Object.freeze({
-    session_not_found: 'The engine did not continue this conversation: the conversation it was asked to continue does not exist there (it may have expired, been removed, or never been created on that engine; this client cannot tell which), and this request asked to continue only an existing one, so no new conversation was started · Start a new conversation, or pick another one to continue',
-    session_id_missing: 'The engine did not continue this conversation: this request asked to continue only an existing conversation but named none, so there was nothing to continue and no new conversation was started · Name the conversation to continue, or start a new one',
+const REQUIRE_EXISTING_SESSION_KEYS = Object.freeze({
+    session_not_found: 'resume.refusal.requireExisting.sessionNotFound',
+    session_id_missing: 'resume.refusal.requireExisting.sessionIdMissing',
 });
-const REQUIRE_EXISTING_SESSION_GENERIC = 'The engine did not continue this conversation: this request asked to continue only an existing conversation and there was none it could continue, so no new conversation was started · Start a new conversation, or pick another one to continue';
-export function requireExistingSessionRefusalContent(detail) {
+const REQUIRE_EXISTING_SESSION_GENERIC = 'resume.refusal.requireExisting.generic';
+export function requireExistingSessionRefusalContent(detail, lang) {
+    return renderMessage(msg(requireExistingSessionKey(detail)), lang);
+}
+function requireExistingSessionKey(detail) {
     try {
         const form = detail?.form;
-        return typeof form === 'string' && Object.hasOwn(REQUIRE_EXISTING_SESSION_SENTENCES, form)
-            ? REQUIRE_EXISTING_SESSION_SENTENCES[form]
+        return typeof form === 'string' && Object.hasOwn(REQUIRE_EXISTING_SESSION_KEYS, form)
+            ? REQUIRE_EXISTING_SESSION_KEYS[form]
             : REQUIRE_EXISTING_SESSION_GENERIC;
     }
     catch {
@@ -112,8 +94,7 @@ export function requireExistingSessionRefusalContent(detail) {
 export function resumeContextUnavailableFromError(err) {
     if (typeof err !== 'object' || err === null)
         return null;
-    const e = err;
-    if (e.errorCode !== RESUME_CONTEXT_UNAVAILABLE)
+    if (readThrownSlot(err, 'errorCode', 'data') !== RESUME_CONTEXT_UNAVAILABLE)
         return null;
     const sec = readErrorNumber(err, 'staleAfterSec');
     const staleSec = sec !== undefined && Number.isInteger(sec) && sec >= 1 ? sec : undefined;
@@ -125,17 +106,11 @@ export function resumeContextUnavailableFromError(err) {
         ...(runId !== undefined ? { runId } : {}),
     };
 }
-export function resumeContextUnavailableContent(d) {
+export function resumeContextUnavailableContent(d, lang) {
     const sec = d.staleAfterSec;
-    const retention = typeof sec === 'number' && Number.isSafeInteger(sec) && sec >= 1 ? ` (this deployment keeps conversations for ${sec} seconds)` : '';
-    const third = (d.runId !== undefined
-        ? "The error carries this run's id: use it to recover the run yourself, then decide again; raising the conversation retention time only prevents this from happening again and cannot rescue this one"
-        : 'The error carries no run id: go back to the run list, find this run and recover it yourself, then decide again; raising the conversation retention time only prevents this from happening again and cannot rescue this one') + retention;
-    return [
-        'This approval has nowhere to be delivered: the conversation that started this run has no usable context to continue it right now',
-        'Nothing was decided and your decision was not consumed; this card is still waiting',
-        third,
-    ].join(' · ');
+    const retention = typeof sec === 'number' && Number.isSafeInteger(sec) && sec >= 1 ? msg('resume.refusal.contextRetention', { sec }) : '';
+    const third = msg(d.runId !== undefined ? 'resume.refusal.contextThird.withRun' : 'resume.refusal.contextThird.noRun', { retention });
+    return renderMessage(msg('resume.refusal.contextUnavailable', { third }), lang);
 }
 function parkedResumeStartupCauseWord(err) {
     let named;
@@ -150,6 +125,7 @@ function parkedResumeStartupCauseWord(err) {
 function isResumeStartupCause(v) {
     return typeof v === 'string' && CORE_RESUME_STARTUP_CAUSES.includes(v);
 }
+const RESUME_CAUSE_CORE_AHEAD = Object.freeze(['transcript_corrupt']);
 const _startupCausePin = true;
 void _startupCausePin;
 export function parkedResumeStartupFromError(err, decision) {
@@ -176,62 +152,28 @@ export function parkedResumeStartupFromError(err, decision) {
         denyStaysOpen: true,
     };
 }
-const PARKED_RESUME_STARTUP_STATE = 'This refusal does not say whether the card is still waiting — re-fetch the pending approvals';
-const PARKED_RESUME_STARTUP_SENTENCES = Object.freeze({
-    resume_rejected: [
-        'The engine could not start the parked work to apply this decision (its session may be gone, or the engine rejected the decision itself; this client cannot tell which)',
-        PARKED_RESUME_STARTUP_STATE,
-        'If the card is still there, decide it again from the fresh list',
-    ].join(' · '),
-    undetermined: [
-        'The engine could not start the parked work to apply this decision',
-        PARKED_RESUME_STARTUP_STATE,
-        'If the card is still there: when the engine rejected the decision itself (for example an answer given to the wrong question), correct it and decide again; when the approved tool is one the agent inherits from the task that started it, approving it again will not work on this server — deny the card, or wait for a server upgrade',
-    ].join(' · '),
+const PARKED_RESUME_STARTUP_KEYS = Object.freeze({
+    resume_rejected: 'resume.refusal.startup.resumeRejected',
+    undetermined: 'resume.refusal.startup.undetermined',
 });
-const PARKED_RESUME_STARTUP_CAUSE_SENTENCES = Object.freeze({
-    environment: [
-        'The engine could not start the parked work to apply this decision: the environment it runs in failed to come up (for example the workspace could not be restored); the decision itself was not rejected',
-        PARKED_RESUME_STARTUP_STATE,
-        'If the card is still there, deciding it again replays the same decision',
-    ].join(' · '),
-    session_gone: [
-        'The engine could not start the parked work to apply this decision: the session of the agent it would resume is gone',
-        PARKED_RESUME_STARTUP_STATE,
-        'If the card is still there, deny it to close it; the work it was waiting on cannot be resumed',
-    ].join(' · '),
-    tool_unavailable: [
-        'The engine could not start the parked work to apply this decision: the approved tool is not available to the resumed work (it is gone, or a different tool now has its name)',
-        PARKED_RESUME_STARTUP_STATE,
-        'This approval cannot run as decided — if the card is still there, decide it afresh (denying it settles it)',
-    ].join(' · '),
-    configuration: [
-        "The engine could not start the parked work to apply this decision: this deployment's configuration refuses the resumed work",
-        PARKED_RESUME_STARTUP_STATE,
-        'Deciding again under the same configuration fails the same way — the configuration has to change first; denying the card settles it',
-    ].join(' · '),
-    decision_rejected: [
-        'The engine could not start the parked work to apply this decision: the engine rejected the decision itself (for example an answer given to the wrong question, or an edited input the constraints refuse)',
-        PARKED_RESUME_STARTUP_STATE,
-        'If the card is still there, correct the decision and decide it again from the fresh list',
-    ].join(' · '),
+const PARKED_RESUME_STARTUP_CAUSE_KEYS = Object.freeze({
+    environment: 'resume.refusal.startup.cause.environment',
+    session_gone: 'resume.refusal.startup.cause.sessionGone',
+    tool_unavailable: 'resume.refusal.startup.cause.toolUnavailable',
+    configuration: 'resume.refusal.startup.cause.configuration',
+    decision_rejected: 'resume.refusal.startup.cause.decisionRejected',
+    transcript_corrupt: 'resume.refusal.startup.cause.transcriptCorrupt',
 });
-export function parkedResumeStartupContent(detail) {
+export function parkedResumeStartupContent(detail, lang) {
     const word = guardedRead(() => readOwnDataValue(detail, 'startupCause'));
     if (isResumeStartupCause(word))
-        return PARKED_RESUME_STARTUP_CAUSE_SENTENCES[word];
-    return detail.cause === 'resume_rejected' ? PARKED_RESUME_STARTUP_SENTENCES.resume_rejected : PARKED_RESUME_STARTUP_SENTENCES.undetermined;
+        return renderMessage(msg(PARKED_RESUME_STARTUP_CAUSE_KEYS[word]), lang);
+    return renderMessage(msg(detail.cause === 'resume_rejected' ? PARKED_RESUME_STARTUP_KEYS.resume_rejected : PARKED_RESUME_STARTUP_KEYS.undetermined), lang);
 }
 export function checkpointUnsupportedVersionFromError(err) {
     if (typeof err !== 'object' || err === null)
         return null;
-    let code;
-    try {
-        code = err.errorCode;
-    }
-    catch {
-        return null;
-    }
+    const code = guardedRead(() => ownDataField(err, 'errorCode'));
     if (code !== CHECKPOINT_UNSUPPORTED_VERSION || !refusalSaysStillPending(err))
         return null;
     const writerVersion = readErrorString(err, 'writerVersion');
@@ -257,10 +199,7 @@ function checkpointUnsupportedHasRun(kind) {
             return undefined;
     }
 }
-const CHECKPOINT_UNSUPPORTED_WHAT = 'This server cannot continue this parked work in the form it was stored in';
-const CHECKPOINT_UNSUPPORTED_STILL_WAITING = 'Nothing was decided or resumed and the parked work is still waiting, but sending the same request again will not by itself continue it';
-const CHECKPOINT_UNSUPPORTED_DRAIN = " — whoever operates this deployment can find such parked work before an upgrade with the server's pre-upgrade drain check";
-export function checkpointUnsupportedVersionContent(detail, ctx) {
+export function checkpointUnsupportedVersionContent(detail, ctx, lang) {
     let writer;
     let reader;
     try {
@@ -272,11 +211,7 @@ export function checkpointUnsupportedVersionContent(detail, ctx) {
         reader = undefined;
     }
     if (writerEngineIsNewer(writer, reader)) {
-        return [
-            `This parked work was stored by a newer engine version (${String(writer)}) than this engine (${String(reader)})`,
-            CHECKPOINT_UNSUPPORTED_STILL_WAITING,
-            `Continue it on an engine at version ${String(writer)} or newer`,
-        ].join(' · ');
+        return renderMessage(msg('resume.refusal.checkpoint.newerEngine', { writer: String(writer), reader: String(reader) }), lang);
     }
     let kind;
     let runId;
@@ -291,17 +226,16 @@ export function checkpointUnsupportedVersionContent(detail, ctx) {
     const hasRun = checkpointUnsupportedHasRun(kind);
     let outlet;
     if (hasRun === true) {
-        const named = typeof runId === 'string' && runId.length > 0 ? ` (${capForDisplay(runId, 80)})` : '';
-        outlet = `If it was parked before this server was upgraded, cancel its run${named} first, then submit the work again as a new task`;
+        const named = typeof runId === 'string' && runId.length > 0 ? msg('resume.refusal.checkpoint.runNamed', { runId: capForDisplay(runId, 80) }) : '';
+        outlet = msg('resume.refusal.checkpoint.outletWithRun', { named });
     }
     else if (hasRun === false) {
-        outlet = 'If it was parked before this server was upgraded, there is no run to cancel: start a new task in that conversation';
+        outlet = msg('resume.refusal.checkpoint.outletNoRun');
     }
     else {
-        outlet =
-            'If it was parked before this server was upgraded, submit the work again as a new task (this client cannot tell which kind of parked work this is, so both ways out are given): when it still has a run waiting on it (a tool approval, a plan review or a paused resource), cancel that run first; when it was waiting to be woken up, or was a workflow step continuing its host conversation, there is no run to cancel, so start a new task in that conversation';
+        outlet = msg('resume.refusal.checkpoint.outletUnknownKind');
     }
-    return [CHECKPOINT_UNSUPPORTED_WHAT, CHECKPOINT_UNSUPPORTED_STILL_WAITING, outlet + CHECKPOINT_UNSUPPORTED_DRAIN].join(' · ');
+    return renderMessage(msg('resume.refusal.checkpoint.content', { outlet }), lang);
 }
 const REFUSED_PARK_FIELD_TOKEN = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
 export function refusedParkFromError(failure) {
@@ -336,16 +270,14 @@ function refusedParkShownRunId(runId) {
 function refusedParkWhy(code, field) {
     switch (code) {
         case CHECKPOINT_WALLTIME_AXIS_RETIRED:
-            return 'its run carries a wall-clock time allowance, which this engine version no longer enforces';
+            return msg('resume.refusal.park.whyWalltime');
         case CHECKPOINT_CONFIG_REFUSED:
-            return field === 'inheritedGate'
-                ? 'the permission-mode setting it was parked with can no longer be read'
-                : 'the engine refuses the task configuration it was parked with';
+            return msg(field === 'inheritedGate' ? 'resume.refusal.park.whyInheritedGate' : 'resume.refusal.park.whyConfigRefused');
         default:
-            return 'it was parked under conditions this engine version does not support (for example, by an earlier engine version)';
+            return msg('resume.refusal.park.whyUnsupported');
     }
 }
-export function refusedParkContent(input) {
+export function refusedParkContent(input, lang) {
     let what;
     let lane;
     let runId;
@@ -370,30 +302,25 @@ export function refusedParkContent(input) {
         rawCode = field = stillPending = undefined;
     }
     const code = rawCode === CHECKPOINT_WALLTIME_AXIS_RETIRED || rawCode === CHECKPOINT_CONFIG_REFUSED ? rawCode : CHECKPOINT_UNSUPPORTED_VERSION;
-    const shownWhat = typeof what === 'string' && what !== '' ? capForDisplay(what, 40) : 'parked step';
+    const shownWhat = typeof what === 'string' && what !== '' ? capForDisplay(what, 40) : msg('resume.refusal.park.whatDefault');
     const why = refusedParkWhy(code, typeof field === 'string' ? field : undefined);
     const shownRun = refusedParkShownRunId(runId);
-    const head = `This ${shownWhat} cannot be resumed by this engine version: ${why}. The same refusal comes back every time, so ` +
-        `answering it again will not help (nothing was decided and nothing was resumed).`;
-    const configMayReturn = code === CHECKPOINT_CONFIG_REFUSED && field !== 'inheritedGate' ? ' If that configuration is restored, the same answer can go through again.' : '';
+    const head = msg('resume.refusal.park.head', { what: shownWhat, why });
+    const configMayReturn = code === CHECKPOINT_CONFIG_REFUSED && field !== 'inheritedGate' ? msg('resume.refusal.park.configMayReturn') : '';
     if (lane === 'print') {
-        if (stillPending === false) {
-            return `${head} The engine ended that run (${code}); submit the work again as a new task.`;
-        }
+        if (stillPending === false)
+            return renderMessage(msg('resume.refusal.park.printEnded', { head, code }), lang);
         const cancel = `POST /v1/runs/${shownRun ?? '<run id>'}/cancel`;
-        return `${head}${configMayReturn} The parked run still holds this session (${code}): cancel it (${cancel}), then submit the work again as a new task.`;
-    }
-    if (stillPending === false) {
-        return `${head} The engine ended that parked run, so this conversation is free: send the work again as a new message.`;
+        return renderMessage(msg('resume.refusal.park.printHolds', { head, configMayReturn, code, cancel }), lang);
     }
-    return `${head}${configMayReturn} The parked run keeps this conversation busy until it is cancelled.`;
+    if (stillPending === false)
+        return renderMessage(msg('resume.refusal.park.interactiveEnded', { head }), lang);
+    return renderMessage(msg('resume.refusal.park.interactiveBusy', { head, configMayReturn }), lang);
 }
-export function refusedParkBlockedContent(taskId, lane = 'interactive') {
+export function refusedParkBlockedContent(taskId, lane = 'interactive', lang) {
     const runId = refusedParkShownRunId(taskId);
-    const head = `sema will not put the card for run ${runId ?? '<unknown>'} back on screen by itself: this engine version refuses to resume it.`;
-    if (lane === 'print') {
-        return `${head} Cancel the run (POST /v1/runs/${runId ?? '<run id>'}/cancel) and submit the work again as a new task.`;
-    }
-    return (`${head} To free this conversation, send a message to bring the card back and answer it — sema then offers to cancel ` +
-        `that run, after which you can send the work again as a new message.`);
+    const run = runId ?? '<unknown>';
+    if (lane === 'print')
+        return renderMessage(msg('resume.refusal.park.blockedPrint', { run, cancel: `POST /v1/runs/${runId ?? '<run id>'}/cancel` }), lang);
+    return renderMessage(msg('resume.refusal.park.blockedInteractive', { run }), lang);
 }

package/dist/retryStatus.d.ts

@@ -71,6 +71,23 @@ export interface BrainStatusPayload {
 }
 export declare const BRAIN_STATUS_PAYLOAD_KEYS: readonly ["phase", "detail", "retryInSec", "retryInMs", "attempt", "maxRetries", "errClass", "retryAtMs", "errorStatus", "elapsedMs", "timeoutMs", "providerCondition", "providerConditionSource"];
 export declare function mapBrainStatusToRetry(p: BrainStatusPayload, nowMs: number): RetryStatus | null;
+export interface RetryStatusArmLike {
+    readonly phase?: string;
+    readonly detail?: string;
+    readonly retryInSec?: number;
+    readonly retryInMs?: number;
+    readonly attempt?: number;
+    readonly maxRetries?: number;
+    readonly errClass?: string;
+    readonly retryAtMs?: number;
+    readonly errorStatus?: number;
+    readonly elapsedMs?: number;
+    readonly timeoutMs?: number;
+    readonly providerCondition?: string;
+    readonly providerConditionSource?: string;
+    readonly parentToolCallId?: string;
+}
+export declare function retryStatusFromArm(arm: RetryStatusArmLike | null | undefined, nowMs: number): RetryStatus | null | undefined;
 export interface RetryStatusNotice {
     readonly line: string;
     readonly recourse?: 'switch_model' | 'wait' | 'fix_request';
@@ -79,4 +96,24 @@ export interface RetryStatusNotice {
 export declare function retryStatusNotice(status: RetryStatus | null, ctx?: {
     readonly modelName?: string;
 }): RetryStatusNotice;
+export interface ApiErrorRowLike {
+    readonly _sema_api_error_status?: number;
+    readonly _sema_provider_condition?: string;
+    readonly _sema_api_error_code?: string;
+}
+export interface ApiErrorRowFacts {
+    readonly status?: number;
+    readonly providerCondition?: string;
+    readonly errorCode?: string;
+}
+export interface ApiErrorNotice {
+    readonly line: string;
+    readonly recourse?: NonNullable<RetryStatusNotice['recourse']> | 'check_credentials';
+}
+export interface ApiErrorNoticeCtx {
+    readonly modelName?: string;
+    readonly providerText?: string;
+}
+export declare function apiErrorFactsOfRow(row: ApiErrorRowLike | null | undefined): ApiErrorRowFacts;
+export declare function apiErrorNotice(facts: ApiErrorRowFacts | null | undefined, ctx?: ApiErrorNoticeCtx): ApiErrorNotice | undefined;
 export {};

package/dist/retryStatus.js

@@ -78,6 +78,47 @@ 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' },
@@ -179,3 +220,41 @@ export function retryStatusNotice(status, ctx) {
                     : 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/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;

package/dist/scenarioRefusal.js

@@ -0,0 +1,111 @@
+import { capForDisplay } from './fleetTaskDesc.js';
+import { readOwnDataValue } from './ownKey.js';
+import { SCENARIO_ASSIGNMENT_UNKNOWN_ERROR_CODE } from './engineErrorCodes.js';
+import { readErrorRecord, readErrorString } from './wireFailureShape.js';
+import { effectiveWireErrorCode } from './wireErrorTriage.js';
+const SCENARIO_REFUSAL_ERROR_MAX = 200;
+function detailBits(detail) {
+    if (detail === undefined)
+        return {};
+    let scenario;
+    let source;
+    try {
+        scenario = readOwnDataValue(detail, 'scenario');
+    }
+    catch {
+        scenario = undefined;
+    }
+    try {
+        source = readOwnDataValue(detail, 'source');
+    }
+    catch {
+        source = undefined;
+    }
+    return {
+        ...(typeof scenario === 'string' && scenario.length > 0 ? { scenario } : {}),
+        ...(source === 'ruling' || source === 'deployment' ? { source } : {}),
+    };
+}
+const isPlainRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+export function scenarioRefusalOf(body) {
+    let raw;
+    try {
+        const d = Object.getOwnPropertyDescriptor(body, 'scenarioRefusal');
+        if (d === undefined)
+            return undefined;
+        raw = 'value' in d ? d.value : undefined;
+    }
+    catch {
+        return null;
+    }
+    try {
+        if (!isPlainRecord(raw))
+            return Object.freeze({});
+        const own = (key) => {
+            try {
+                return readOwnDataValue(raw, key);
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const errorCode = own('errorCode');
+        const error = own('error');
+        const detail = own('detail');
+        let bits = {};
+        try {
+            bits = detailBits(isPlainRecord(detail) ? detail : undefined);
+        }
+        catch {
+            bits = {};
+        }
+        return Object.freeze({
+            ...(typeof errorCode === 'string' && errorCode.length > 0 ? { errorCode } : {}),
+            ...(typeof error === 'string' && error.length > 0 ? { error: capForDisplay(error, SCENARIO_REFUSAL_ERROR_MAX) } : {}),
+            ...bits,
+        });
+    }
+    catch {
+        return Object.freeze({});
+    }
+}
+export function scenarioRefusalFromError(err) {
+    try {
+        if (err === null || typeof err !== 'object')
+            return null;
+        if (effectiveWireErrorCode(err) !== SCENARIO_ASSIGNMENT_UNKNOWN_ERROR_CODE)
+            return null;
+        const error = readErrorString(err, 'message');
+        return Object.freeze({
+            errorCode: SCENARIO_ASSIGNMENT_UNKNOWN_ERROR_CODE,
+            ...(error !== undefined && error.length > 0 ? { error: capForDisplay(error, SCENARIO_REFUSAL_ERROR_MAX) } : {}),
+            ...detailBits(readErrorRecord(err, 'detail')),
+        });
+    }
+    catch {
+        return null;
+    }
+}
+export function scenarioRefusalContent(reading) {
+    let code;
+    let scenario;
+    let source;
+    try {
+        code = isPlainRecord(reading) ? readOwnDataValue(reading, 'errorCode') : undefined;
+        scenario = isPlainRecord(reading) ? readOwnDataValue(reading, 'scenario') : undefined;
+        source = isPlainRecord(reading) ? readOwnDataValue(reading, 'source') : undefined;
+    }
+    catch {
+        code = undefined;
+        scenario = undefined;
+        source = undefined;
+    }
+    if (code === SCENARIO_ASSIGNMENT_UNKNOWN_ERROR_CODE) {
+        const name = typeof scenario === 'string' && scenario.length > 0 ? ` ("${capForDisplay(scenario, 80)}")` : '';
+        const from = source === 'ruling' ? ', assigned to you by the configuration center,' : source === 'deployment' ? ", this deployment's default scenario," : '';
+        return (`This deployment cannot resolve your scenario: the scenario${name}${from} does not exist here, so it refuses whatever depends on your scenario — ` +
+            "new runs that do not name a scenario, and this session's list of MCP servers · Ask whoever operates the engine to fix the scenario assignment");
+    }
+    const tail = typeof code === 'string' && code.length > 0 ? ` (${capForDisplay(code, 80)})` : '';
+    return `This deployment's scenario check refused to resolve your scenario${tail}, so whatever depends on your scenario is not available — this session's list of MCP servers is unknown`;
+}