@sema-agent/client-core 0.84.0 → 0.85.0

package/dist/abortableSleep.d.ts

@@ -1 +1,11 @@
 export declare function abortableSleep(ms: number, signal: AbortSignal): Promise<void>;
+export type DeadlineSettled<T> = {
+    kind: 'value';
+    value: T;
+} | {
+    kind: 'error';
+    detail: string;
+} | {
+    kind: 'deadline';
+};
+export declare function settleWithinDeadline<T>(ms: number, run: (signal: AbortSignal) => Promise<T>): Promise<DeadlineSettled<T>>;

package/dist/abortableSleep.js

@@ -13,3 +13,40 @@ export function abortableSleep(ms, signal) {
         signal.addEventListener('abort', onAbort, { once: true });
     });
 }
+function errorDetail(error) {
+    try {
+        return String(error);
+    }
+    catch {
+        return '';
+    }
+}
+export function settleWithinDeadline(ms, run) {
+    const ac = new AbortController();
+    return new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            resolve({ kind: 'deadline' });
+            ac.abort();
+        }, ms);
+        const finish = (out) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(out);
+        };
+        let pending;
+        try {
+            pending = Promise.resolve(run(ac.signal));
+        }
+        catch (error) {
+            finish({ kind: 'error', detail: errorDetail(error) });
+            return;
+        }
+        pending.then((value) => finish({ kind: 'value', value }), (error) => finish({ kind: 'error', detail: errorDetail(error) }));
+    });
+}

package/dist/adapt/arms.js

@@ -141,7 +141,7 @@ const userArm = function* (m, { ctx, idOf }) {
 };
 const systemArm = function* (m, { ctx, idOf }) {
     yield transcript(m, ctx.now());
-    const attachedFiles = m._sema_attached_files ?? m.attachedFiles;
+    const attachedFiles = m._sema_attached_files;
     if (Array.isArray(attachedFiles)) {
         let i = 0;
         for (const f of attachedFiles) {

package/dist/adapt.d.ts

@@ -1,5 +1,5 @@
 import type { AdapterContext, AdapterOutput, WireToCcAdapter } from './seam.js';
-export { CANCEL_MESSAGE, estimateCjkTokens, flattenWireOutput, FLUSH_INTERVAL_MS, IDLE_FLUSH_MS, REJECT_MESSAGE, sanitizeToolUseBlock, shortTaskLabel, SUBAGENT_TOOL_NAMES, WORKFLOW_TOOL_NAMES, } from './adapt/wireShapes.js';
+export { CANCEL_MESSAGE, estimateCjkTokens, flattenWireOutput, FLUSH_INTERVAL_MS, IDLE_FLUSH_MS, REJECT_MESSAGE, sanitizeToolUseBlock, SUBAGENT_TOOL_NAMES, WORKFLOW_TOOL_NAMES, } from './adapt/wireShapes.js';
 export interface AdapterLedgerState {
     version: 1;
     renderedNotifications: string[];

package/dist/adapt.js

@@ -1,5 +1,5 @@
 import { isEngineWorkflowNotified, isWorkflowCompletionCardEnqueued, listNotifiedRuns, listWorkflowCompletionCardsEnqueued, markEngineWorkflowNotified, noteWorkflowCompletionCardEnqueued, parseTranscriptNotificationSeeds, } from './notifications.js';
-export { CANCEL_MESSAGE, estimateCjkTokens, flattenWireOutput, FLUSH_INTERVAL_MS, IDLE_FLUSH_MS, REJECT_MESSAGE, sanitizeToolUseBlock, shortTaskLabel, SUBAGENT_TOOL_NAMES, WORKFLOW_TOOL_NAMES, } from './adapt/wireShapes.js';
+export { CANCEL_MESSAGE, estimateCjkTokens, flattenWireOutput, FLUSH_INTERVAL_MS, IDLE_FLUSH_MS, REJECT_MESSAGE, sanitizeToolUseBlock, SUBAGENT_TOOL_NAMES, WORKFLOW_TOOL_NAMES, } from './adapt/wireShapes.js';
 import { IDLE_FLUSH_MS } from './adapt/wireShapes.js';
 import { chrome, mainLane, makeIdOf } from './adapt/ids.js';
 import { createTextStream } from './adapt/textStream.js';

package/dist/adapter/downstream/terminalToSdkResult.d.ts

@@ -30,6 +30,7 @@ export interface SemaPermissionDenial {
     readonly tool_use_id?: string;
     readonly tool_input?: Record<string, unknown>;
     readonly _sema_tool_input_source?: 'tool_start';
+    readonly _sema_tool_input_redacted?: true;
     readonly _sema_tool_arg?: string;
     readonly deniedBy?: DeniedBy;
     readonly _sema_denied_by_source?: 'tool_end';

package/dist/adapter/downstream/terminalToSdkResult.js

@@ -5,7 +5,11 @@ import { REDACTION_MARKER_PREFIX, washCredentials } from '../../displayUntrusted
 import { readEffectiveReasoning, readEffectiveMemoryScopes } from '../../effectiveFacts.js';
 import { isReviewPark, readRunTerminal, runTerminalCode, runTerminalGateToolName, } from '../../runTerminal.js';
 import { toCcModelUsage } from './turnUsageToModelUsage.js';
-import { LIMITS_MAX_COST_EXCEEDED, LIMITS_MAX_TOKENS_EXCEEDED, LIMITS_MAX_TURNS_EXCEEDED, LIMITS_MAX_WALLTIME_EXCEEDED, OUTPUT_INVALID, isRewindFamilyCode, } from '../../engineErrorCodes.js';
+import { LIMITS_MAX_COST_EXCEEDED, LIMITS_MAX_TOKENS_EXCEEDED, LIMITS_MAX_TURNS_EXCEEDED, LIMITS_MAX_WALLTIME_EXCEEDED, OUTPUT_INVALID, isCorruptSessionCode, isRewindFamilyCode, } from '../../engineErrorCodes.js';
+import { corruptSessionContent } from '../../corruptSessionCopy.js';
+function withSessionUnreadableNote(text, code) {
+    return isCorruptSessionCode(code) ? `${text}\n${corruptSessionContent()}` : text;
+}
 function finiteOr0(v) {
     return typeof v === 'number' && Number.isFinite(v) ? v : 0;
 }
@@ -40,14 +44,15 @@ function joinableToolInput(args) {
     if (args === null || typeof args !== 'object' || Array.isArray(args))
         return undefined;
     let nodes = 0;
+    let transportRedacted = false;
     const stack = [{ v: args, depth: 0 }];
     while (stack.length > 0) {
         const { v, depth } = stack.pop();
         if (++nodes > TOOL_INPUT_SCAN_MAX_NODES || depth > TOOL_INPUT_SCAN_MAX_DEPTH)
             return undefined;
         if (typeof v === 'string') {
-            if (v.includes(REDACTION_MARKER_PREFIX) || isTransportPlaceholderLeaf(v))
-                return undefined;
+            if (!transportRedacted && (v.includes(REDACTION_MARKER_PREFIX) || isTransportPlaceholderLeaf(v)))
+                transportRedacted = true;
             continue;
         }
         if (v === null || typeof v !== 'object')
@@ -56,7 +61,7 @@ function joinableToolInput(args) {
         for (const c of children)
             stack.push({ v: c, depth: depth + 1 });
     }
-    return args;
+    return { input: args, transportRedacted };
 }
 const GATE_DENIED_DECISIONS = new Set(['deny']);
 const GATE_NON_DENIAL_DECISIONS = new Set(['allow', 'approve', 'edit', 'reject']);
@@ -92,9 +97,10 @@ function permissionDenialParts(stats, observed) {
         const ledgerInput = rawInput !== null && typeof rawInput === 'object' && !Array.isArray(rawInput)
             ? rawInput
             : undefined;
-        const joinedInput = ledgerInput === undefined && toolUseId !== undefined && toolInputByCallId?.has(toolUseId) === true
+        const joined = ledgerInput === undefined && toolUseId !== undefined && toolInputByCallId?.has(toolUseId) === true
             ? joinableToolInput(toolInputByCallId.get(toolUseId))
             : undefined;
+        const joinedInput = joined?.input;
         const toolInput = ledgerInput ?? joinedInput;
         const ledgerDeniedByRaw = row.deniedBy;
         const ledgerDeniedBy = typeof ledgerDeniedByRaw === 'string' && isGateDeniedByWord(ledgerDeniedByRaw)
@@ -116,6 +122,7 @@ function permissionDenialParts(stats, observed) {
             ...(toolUseId !== undefined ? { tool_use_id: toolUseId } : {}),
             ...(toolInput !== undefined ? { tool_input: toolInput } : {}),
             ...(joinedInput !== undefined ? { _sema_tool_input_source: 'tool_start' } : {}),
+            ...(joined?.transportRedacted === true ? { _sema_tool_input_redacted: true } : {}),
             ...(deniedBy !== undefined ? { deniedBy } : {}),
             ...(joinedDeniedBy !== undefined && ledgerDeniedBy === undefined
                 ? { _sema_denied_by_source: 'tool_end' }
@@ -145,7 +152,8 @@ function permissionDenialParts(stats, observed) {
                 continue;
             }
             const toolName = nonEmptyStr(toolNameRaw);
-            const joinedInput = toolInputByCallId?.has(callId) === true ? joinableToolInput(toolInputByCallId.get(callId)) : undefined;
+            const joined = toolInputByCallId?.has(callId) === true ? joinableToolInput(toolInputByCallId.get(callId)) : undefined;
+            const joinedInput = joined?.input;
             const deniedByRaw = gateDeniedByByCallId?.has(callId) === true ? gateDeniedByByCallId.get(callId) : undefined;
             const deniedBy = typeof deniedByRaw === 'string' && isGateDeniedByWord(deniedByRaw) ? deniedByRaw : undefined;
             const toolDenialKind = isCcToolDenialKind(mergedKind) ? mergedKind : undefined;
@@ -153,6 +161,7 @@ function permissionDenialParts(stats, observed) {
                 ...(toolName !== undefined ? { tool_name: toolName } : {}),
                 tool_use_id: callId,
                 ...(joinedInput !== undefined ? { tool_input: joinedInput, _sema_tool_input_source: 'tool_start' } : {}),
+                ...(joined?.transportRedacted === true ? { _sema_tool_input_redacted: true } : {}),
                 ...(deniedBy !== undefined ? { deniedBy, _sema_denied_by_source: 'tool_end' } : {}),
                 ...(toolDenialKind !== undefined ? { toolDenialKind } : {}),
             });
@@ -522,9 +531,9 @@ export function doneToSdkResult(ev, ctx, observed) {
             ...errorBase,
             subtype: failedSubtype,
             errors: [
-                isRewindFamilyCode(failedCode) && failedMessage
+                withSessionUnreadableNote(isRewindFamilyCode(failedCode) && failedMessage
                     ? `${failedMessage} (${failedCode})`
-                    : (failedMessage ?? 'run failed'),
+                    : (failedMessage ?? 'run failed'), failedCode),
             ],
         });
     }
@@ -614,9 +623,9 @@ export function failedToSdkResult(ev, ctx, observed) {
         durationMs: elapsedMs(ctx),
         errorCode: ev.errorCode,
         errors: [
-            isRewindFamilyCode(ev.errorCode) && ev.errorMessage
+            withSessionUnreadableNote(isRewindFamilyCode(ev.errorCode) && ev.errorMessage
                 ? `${ev.errorMessage} (${ev.errorCode})`
-                : (ev.errorMessage ?? ev.errorCode ?? 'run failed'),
+                : (ev.errorMessage ?? ev.errorCode ?? 'run failed'), ev.errorCode),
         ],
     });
 }

package/dist/adapter/runStream.js

@@ -3,7 +3,8 @@ import { eventToSdkMessage, turnEndUsage } from './downstream/eventToSdkMessage.
 import { turnUsageToModelUsage } from './downstream/turnUsageToModelUsage.js';
 import { readRunCostFacts, terminalToSdkResult, TOOL_INPUT_JOIN_MAX_CALLS } from './downstream/terminalToSdkResult.js';
 import { coerceOutput, publishSubagentContentEvent } from '../subagentContentStore.js';
-import { ACTIVE_RUN_BUSY_ERROR_CODE, OUTPUT_INVALID, isLimitsExceededCode } from '../engineErrorCodes.js';
+import { ACTIVE_RUN_BUSY_ERROR_CODE, OUTPUT_INVALID, isCorruptSessionCode, isLimitsExceededCode } from '../engineErrorCodes.js';
+import { corruptSessionContent } from '../corruptSessionCopy.js';
 import { isReviewPark, readRunTerminal, runTerminalCode } from '../runTerminal.js';
 import { washCredentials } from '../displayUntrusted.js';
 import { ccToolDenialKindForToolEnd, gateDeniedBy, gateOutcomeOf } from '../gateOutcome.js';
@@ -474,7 +475,10 @@ async function* runStreamInner(events, ctx, handle = {}) {
                             ?
                                 `${MODEL_OUTPUT_ERROR_PREFIX}: ${errText}${maxTokHint}`
                             : `API Error: ${errText}${maxTokHint}`;
-                yield syntheticTerminalRow(ctx, rowText);
+                const sessionUnreadable = ev.type === 'failed'
+                    ? isCorruptSessionCode(ev.errorCode)
+                    : doneTerminal?.kind === 'failed' && isCorruptSessionCode(doneTerminal.code);
+                yield syntheticTerminalRow(ctx, sessionUnreadable ? `${rowText}\n${corruptSessionContent()}` : rowText);
             }
             if (ev.type === 'done' && isReviewPark(doneTerminal) && ctx.emitChrome) {
                 try {

package/dist/agentSession/engineSessionBackgroundStop.d.ts

@@ -0,0 +1,50 @@
+import type { AgentClient, SessionBackgroundStopOutcome } from '@sema-agent/sdk';
+import type { EngineWireInjection } from '../engineWireSdk.js';
+export type EngineSessionBackgroundStopClient = {
+    sessions: Pick<AgentClient['sessions'], 'backgroundStop'>;
+};
+export type EngineSessionBackgroundStopWire = EngineWireInjection<EngineSessionBackgroundStopClient>;
+export interface EngineSessionBackgroundStopOptions {
+    wire?: EngineSessionBackgroundStopWire;
+    signal?: AbortSignal;
+    sessionKey?: string;
+}
+export interface EngineSessionBackgroundReceipt {
+    readonly id: string;
+    readonly outcome: SessionBackgroundStopOutcome | (string & {});
+}
+export type EngineSessionBackgroundStopUnavailableWhy = 'bad_input' | 'no_wire' | 'capability_unknown' | 'no_exit_face';
+export type EngineSessionBackgroundStopRefusedWhy = 'credentials_required' | 'not_permitted' | 'ownership_required' | 'session_not_found' | 'route_absent' | 'bad_request' | 'rate_limited' | 'other';
+export type EngineSessionBackgroundStopResult = {
+    kind: 'stopped';
+    receipts?: readonly EngineSessionBackgroundReceipt[];
+    unreadableReceipts?: number;
+} | {
+    kind: 'unavailable';
+    why: EngineSessionBackgroundStopUnavailableWhy;
+    detail: string;
+} | {
+    kind: 'refused';
+    why: EngineSessionBackgroundStopRefusedWhy;
+    detail: string;
+    status?: number;
+    errorCode?: string;
+    retryAfterMs?: number;
+} | {
+    kind: 'error';
+    detail: string;
+    status?: number;
+    errorCode?: string;
+    unconfirmed?: true;
+};
+export declare function stopEngineSessionBackground(sessionId: string, body: {
+    readonly includeRetained: boolean;
+}, opts?: EngineSessionBackgroundStopOptions): Promise<EngineSessionBackgroundStopResult>;
+export type EngineSessionBackgroundReceiptState = 'stopped' | 'still_running' | 'may_be_running';
+export declare const ENGINE_SESSION_BACKGROUND_RECEIPT_STATES: readonly EngineSessionBackgroundReceiptState[];
+export interface EngineSessionBackgroundReceiptReading {
+    readonly state: EngineSessionBackgroundReceiptState;
+    readonly text: string;
+    readonly unrecognizedOutcome?: string;
+}
+export declare function engineSessionBackgroundReceiptReadingOf(outcome: string): EngineSessionBackgroundReceiptReading;

package/dist/agentSession/engineSessionBackgroundStop.js

@@ -0,0 +1,291 @@
+import { engineCapValue } from '../engineCapsCache.js';
+import { isStatusDerivedCoarseCode } from '../engineErrorCodes.js';
+import { clientHasVerbs, engineWireFor, INJECTED_WIRE_SETTLE_MS, noAnswerDetailFrom, sendOnce, settleInjected } from '../engineWireFor.js';
+import { engineWireDebugEnabled } from '../engineWireTarget.js';
+import { hostLog } from '../host.js';
+import { DEFAULT_SESSION_KEY } from '../sessionSlot.js';
+const NOTHING_SENT = ' — nothing sent';
+const DETAIL_BAD_SESSION = `the session id must be a non-empty string${NOTHING_SENT}`;
+const DETAIL_BAD_INCLUDE_RETAINED = `includeRetained must be true or false (the engine has no default for it)${NOTHING_SENT}`;
+const DETAIL_BAD_OPTIONS = `the options could not be read${NOTHING_SENT}`;
+const DETAIL_BAD_ARGUMENTS = `the arguments could not be read${NOTHING_SENT}`;
+const DETAIL_BAD_SESSION_KEY = `the session key must be a non-empty string${NOTHING_SENT}`;
+const DETAIL_BAD_SIGNAL = `the signal must be an AbortSignal${NOTHING_SENT}`;
+const DETAIL_INJECTED_UNUSABLE = `the connection supplied by the host cannot send this request (no usable sessions.backgroundStop)${NOTHING_SENT}`;
+const DETAIL_NO_TARGET = `no engine connection is installed for this session${NOTHING_SENT}`;
+const DETAIL_NO_CLIENT = `an engine client could not be built from the installed connection${NOTHING_SENT}`;
+const DETAIL_CAPS_KEY_REQUIRED = `capability evidence for background.exitFaces is not available under the key the host named (capsBaseUrl)${NOTHING_SENT}`;
+const DETAIL_CAPS_UNOBSERVED = `the engine capabilities have not been read for this connection yet — wait for the capability probe to settle, then call again${NOTHING_SENT}`;
+const DETAIL_NO_EXIT_FACE = `this engine does not offer the session background stop (capabilities.background.exitFaces is not true); background tasks may keep running${NOTHING_SENT}`;
+function refusedDetail(why) {
+    switch (why) {
+        case 'credentials_required':
+            return 'this engine does not accept stop requests until it is configured with a service credential';
+        case 'not_permitted':
+            return 'this caller is not permitted to stop the background tasks of this session';
+        case 'ownership_required':
+            return 'this engine has no session ownership face, so it cannot stop session background tasks';
+        case 'session_not_found':
+            return 'the engine does not know this session';
+        case 'route_absent':
+            return 'this engine has no session background stop route';
+        case 'bad_request':
+            return 'the engine rejected the request shape';
+        case 'rate_limited':
+            return 'the engine is rate-limiting stop requests — try again later';
+        case 'other':
+            return 'the engine refused the stop';
+        default: {
+            const unreachable = why;
+            return unreachable;
+        }
+    }
+}
+function note(msg) {
+    try {
+        hostLog('debug', `[session-background] stop: ${msg}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function debugOn() {
+    try {
+        return engineWireDebugEnabled();
+    }
+    catch {
+        return false;
+    }
+}
+function unavailable(why, detail) {
+    note(`unavailable (${why})`);
+    return { kind: 'unavailable', why, detail };
+}
+function usableStopClient(client) {
+    return clientHasVerbs(client, [['sessions', 'backgroundStop']]);
+}
+function exitFaceGate(capsKey) {
+    try {
+        const v = engineCapValue(capsKey, 'background');
+        if (v.kind === 'unobserved')
+            return { why: 'capability_unknown', detail: DETAIL_CAPS_UNOBSERVED };
+        if (v.kind !== 'value')
+            return { why: 'no_exit_face', detail: DETAIL_NO_EXIT_FACE };
+        const bg = v.value;
+        if (typeof bg !== 'object' || bg === null || !Object.hasOwn(bg, 'exitFaces'))
+            return { why: 'no_exit_face', detail: DETAIL_NO_EXIT_FACE };
+        return bg.exitFaces === true ? null : { why: 'no_exit_face', detail: DETAIL_NO_EXIT_FACE };
+    }
+    catch {
+        return { why: 'capability_unknown', detail: DETAIL_CAPS_UNOBSERVED };
+    }
+}
+function readReceipt(v) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return undefined;
+    const id = Object.hasOwn(v, 'id') ? v.id : undefined;
+    const outcome = Object.hasOwn(v, 'outcome') ? v.outcome : undefined;
+    if (typeof id !== 'string' || id.length === 0 || typeof outcome !== 'string' || outcome.length === 0)
+        return undefined;
+    return { id, outcome };
+}
+function readStopped(body) {
+    if (typeof body !== 'object' || body === null || !Object.hasOwn(body, 'receipts')) {
+        note('stopped (receipt list unreadable)');
+        return { kind: 'stopped' };
+    }
+    const raw = body.receipts;
+    if (!Array.isArray(raw)) {
+        note('stopped (receipt list unreadable)');
+        return { kind: 'stopped' };
+    }
+    const receipts = [];
+    let unreadable = 0;
+    for (const r of raw) {
+        const got = readReceipt(r);
+        if (got === undefined)
+            unreadable++;
+        else
+            receipts.push(got);
+    }
+    if (unreadable > 0)
+        note(`stopped (${unreadable} receipt(s) unreadable)`);
+    else if (debugOn())
+        note(`stopped (${receipts.length} receipt(s))`);
+    return { kind: 'stopped', receipts, ...(unreadable > 0 ? { unreadableReceipts: unreadable } : {}) };
+}
+function refusedWhyOf(rawCode, status) {
+    const code = rawCode !== undefined && status !== undefined && isStatusDerivedCoarseCode(rawCode) ? undefined : rawCode;
+    if (code !== undefined) {
+        if (code === 'auth.service_token_required')
+            return 'credentials_required';
+        if (code === 'capability.session_ownership_required')
+            return 'ownership_required';
+        if (code === 'not_found.session')
+            return 'session_not_found';
+        if (code === 'not_found.route')
+            return 'route_absent';
+        if (code === 'limit.rate_exceeded')
+            return 'rate_limited';
+        if (code.startsWith('auth.'))
+            return 'not_permitted';
+        if (code.startsWith('request.'))
+            return 'bad_request';
+    }
+    if (status === undefined)
+        return undefined;
+    if (status === 429)
+        return 'rate_limited';
+    if (status === 401 || status === 403)
+        return 'not_permitted';
+    if (status === 400)
+        return 'bad_request';
+    if (status >= 400 && status < 500)
+        return 'other';
+    return undefined;
+}
+function diagOf(e) {
+    const o = e;
+    const rawStatus = o.status ?? o.statusCode;
+    const status = typeof rawStatus === 'number' && Number.isInteger(rawStatus) ? rawStatus : undefined;
+    const errorCode = typeof o.errorCode === 'string' && o.errorCode.length > 0 ? o.errorCode : undefined;
+    const ra = o.retryAfterMs;
+    const retryAfterMs = typeof ra === 'number' && Number.isFinite(ra) && ra >= 0 ? ra : undefined;
+    const message = typeof o.message === 'string' && o.message.length > 0 ? o.message : undefined;
+    return {
+        ...(status !== undefined ? { status } : {}),
+        ...(errorCode !== undefined ? { errorCode } : {}),
+        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+        ...(message !== undefined ? { message } : {}),
+    };
+}
+function classifyFailure(e) {
+    try {
+        if (typeof e !== 'object' || e === null) {
+            note('error (non-object failure)');
+            return { kind: 'error', detail: `the stop request failed: ${String(e).slice(0, 200)}` };
+        }
+        const d = diagOf(e);
+        if (d.status === undefined && d.errorCode === undefined) {
+            const noAnswer = noAnswerDetailFrom(e);
+            if (noAnswer !== null) {
+                note('error (no answer — the stop may have taken effect)');
+                return { kind: 'error', detail: noAnswer, unconfirmed: true };
+            }
+        }
+        const diag = { ...(d.status !== undefined ? { status: d.status } : {}), ...(d.errorCode !== undefined ? { errorCode: d.errorCode } : {}) };
+        const bits = [d.status !== undefined ? `status=${d.status}` : '', d.errorCode !== undefined ? `errorCode=${d.errorCode}` : ''].filter((b) => b.length > 0).join(' ');
+        const why = refusedWhyOf(d.errorCode, d.status);
+        if (why !== undefined) {
+            note(`refused (${why})${bits.length > 0 ? ` ${bits}` : ''}`);
+            return {
+                kind: 'refused',
+                why,
+                detail: `${refusedDetail(why)}${bits.length > 0 ? ` (${bits})` : ''}`,
+                ...diag,
+                ...(why === 'rate_limited' && d.retryAfterMs !== undefined ? { retryAfterMs: d.retryAfterMs } : {}),
+            };
+        }
+        note(`error${bits.length > 0 ? ` ${bits}` : ''}`);
+        return { kind: 'error', detail: (d.message ?? 'the stop request failed').slice(0, 300), ...diag };
+    }
+    catch {
+        note('error (the failure could not be read)');
+        return { kind: 'error', detail: 'the stop request failed (the error could not be read)' };
+    }
+}
+export async function stopEngineSessionBackground(sessionId, body, opts) {
+    let includeRetained;
+    let wireIn;
+    let signal;
+    let sessionKey;
+    try {
+        if (typeof sessionId !== 'string' || sessionId.length === 0)
+            return unavailable('bad_input', DETAIL_BAD_SESSION);
+        const flag = typeof body === 'object' && body !== null && Object.hasOwn(body, 'includeRetained') ? body.includeRetained : undefined;
+        if (typeof flag !== 'boolean')
+            return unavailable('bad_input', DETAIL_BAD_INCLUDE_RETAINED);
+        includeRetained = flag;
+        if (opts !== undefined && opts !== null && typeof opts !== 'object')
+            return unavailable('bad_input', DETAIL_BAD_OPTIONS);
+        wireIn = opts?.wire;
+        const sig = opts?.signal;
+        if (sig !== undefined && sig !== null && (typeof sig !== 'object' || typeof sig.addEventListener !== 'function' || typeof sig.aborted !== 'boolean')) {
+            return unavailable('bad_input', DETAIL_BAD_SIGNAL);
+        }
+        signal = sig ?? undefined;
+        const key = opts?.sessionKey;
+        if (key !== undefined && (typeof key !== 'string' || key.length === 0))
+            return unavailable('bad_input', DETAIL_BAD_SESSION_KEY);
+        sessionKey = key ?? DEFAULT_SESSION_KEY;
+    }
+    catch {
+        return unavailable('bad_input', DETAIL_BAD_ARGUMENTS);
+    }
+    let resolved;
+    try {
+        resolved = engineWireFor(wireIn, sessionKey, usableStopClient);
+    }
+    catch {
+        return unavailable('no_wire', wireIn !== undefined ? DETAIL_INJECTED_UNUSABLE : DETAIL_NO_TARGET);
+    }
+    if (resolved.kind === 'injected-unusable')
+        return unavailable('no_wire', DETAIL_INJECTED_UNUSABLE);
+    if (resolved.kind === 'no-target')
+        return unavailable('no_wire', DETAIL_NO_TARGET);
+    if (resolved.kind === 'injected' && resolved.capsBaseUrl === undefined)
+        return unavailable('capability_unknown', DETAIL_CAPS_KEY_REQUIRED);
+    const gate = exitFaceGate(resolved.kind === 'injected' ? resolved.capsBaseUrl : resolved.target.baseUrl);
+    if (gate !== null)
+        return unavailable(gate.why, gate.detail);
+    let client;
+    try {
+        client = resolved.kind === 'injected' ? resolved.client : resolved.make();
+    }
+    catch {
+        client = null;
+    }
+    if (client === null)
+        return unavailable('no_wire', DETAIL_NO_CLIENT);
+    const stopBody = { includeRetained };
+    const stopOnce = (s) => client.sessions.backgroundStop(sessionId, stopBody, s !== undefined ? { signal: s } : undefined);
+    let answered;
+    try {
+        answered = resolved.kind === 'injected' ? await settleInjected(INJECTED_WIRE_SETTLE_MS, signal, stopOnce) : await sendOnce(signal, () => stopOnce(signal));
+    }
+    catch (e) {
+        return classifyFailure(e);
+    }
+    try {
+        return readStopped(answered);
+    }
+    catch {
+        note('stopped (receipt list unreadable)');
+        return { kind: 'stopped' };
+    }
+}
+const RECEIPT_STATE_TEXT = {
+    stopped: 'Stopped.',
+    still_running: 'Still running — it was set to keep running, so it was left in place.',
+    may_be_running: 'May still be running — the engine could not confirm that it ended.',
+};
+export const ENGINE_SESSION_BACKGROUND_RECEIPT_STATES = Object.freeze(Object.keys(RECEIPT_STATE_TEXT));
+function receiptReading(state) {
+    return { state, text: RECEIPT_STATE_TEXT[state] };
+}
+export function engineSessionBackgroundReceiptReadingOf(outcome) {
+    if (typeof outcome !== 'string')
+        return receiptReading('may_be_running');
+    switch (outcome) {
+        case 'killed':
+        case 'already_gone':
+            return receiptReading('stopped');
+        case 'retained_skipped':
+            return receiptReading('still_running');
+        case 'no_pgid':
+            return receiptReading('may_be_running');
+        default:
+            return { ...receiptReading('may_be_running'), unrecognizedOutcome: outcome };
+    }
+}

package/dist/agentsWireCaps.d.ts

@@ -1,4 +1,5 @@
 import { type EngineProbeOpts, type WireAuthTokenSource } from './engineWireSdk.js';
+import type { ReasoningEffort } from './effortWire.js';
 export declare const MAX_TASK_AGENTS = 32;
 export declare const MAX_AGENT_NAME_CHARS = 64;
 export declare const MAX_AGENT_TEXT_CHARS = 4096;
@@ -8,7 +9,7 @@ export declare const MAX_AGENT_TOOL_NAME_CHARS = 128;
 export declare const MAX_AGENT_SKILL_CONTENT_CHARS = 1048576;
 export declare const MAX_AGENT_MAX_TURNS = 1000;
 export declare const TASK_AGENT_WIRE_FIELDS: readonly ["name", "whenToUse", "whenToUseLean", "allowTools", "denyTools", "skills", "background", "isolation", "model", "thinking", "systemPrompt", "maxTurns", "memory", "observer", "observerMessage"];
-export type WireThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+export type WireThinkingLevel = ReasoningEffort;
 export type TaskAgentWireSkill = {
     name: string;
     description: string;

package/dist/agentsWireCaps.js

@@ -1,6 +1,7 @@
 import { hostEnv } from './hostEnv.js';
 import { makeEngineWireClient } from './engineWireSdk.js';
 import { frozenSet } from './frozenSet.js';
+import { settleWithinDeadline } from './abortableSleep.js';
 export const MAX_TASK_AGENTS = 32;
 export const MAX_AGENT_NAME_CHARS = 64;
 export const MAX_AGENT_TEXT_CHARS = 4_096;
@@ -173,6 +174,13 @@ export function projectAgentsForWire(defs, deps) {
     return { agents: out.length > 0 ? out : undefined, warnings };
 }
 export async function engineSupportsTaskAgents(baseUrl, opts) {
+    if (opts?.client !== undefined) {
+        const injected = opts.client;
+        if (typeof injected?.capabilities !== 'function')
+            return undefined;
+        const got = await settleWithinDeadline(opts.timeoutMs ?? 3000, (signal) => injected.capabilities({ signal }));
+        return got.kind === 'value' ? got.value?.taskAgents === true : undefined;
+    }
     const client = makeEngineWireClient({
         baseUrl,
         ...(opts?.authToken ? { token: opts.authToken } : {}),

package/dist/cloudConfigWireCaps.js

@@ -1,5 +1,6 @@
 import { MCP_CAPS } from './mcpWireCaps.js';
 import { toCappedSpec } from './skillsWireCaps.js';
+import { TIER_ORDER } from './model/tierVocabulary.js';
 const asRec = (v) => (typeof v === 'object' && v !== null && !Array.isArray(v) ? v : undefined);
 const asArr = (v) => (Array.isArray(v) ? v : []);
 const asStr = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
@@ -127,7 +128,7 @@ function withoutRegistryAnnotations(e) {
     }
     return out;
 }
-const TIER_WORDS = Object.freeze(['ultra', 'max', 'pro', 'flash', 'lite']);
+const TIER_WORDS = TIER_ORDER;
 const TIER_GROUP_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
 const setOwn = (o, k, v) => {
     Object.defineProperty(o, k, { value: v, enumerable: true, writable: true, configurable: true });

package/dist/corruptSession.d.ts

@@ -0,0 +1,3 @@
+export declare function isCorruptSessionError(err: unknown): boolean;
+export declare function isCorruptSessionResult(result: unknown): boolean;
+export declare function isCorruptSessionRunRow(row: unknown): boolean;

package/dist/corruptSession.js

@@ -0,0 +1,29 @@
+import { isCorruptSessionCode } from './engineErrorCodes.js';
+import { effectiveWireErrorCode } from './wireErrorTriage.js';
+import { readRunTerminal } from './runTerminal.js';
+export function isCorruptSessionError(err) {
+    return isCorruptSessionCode(effectiveWireErrorCode(err));
+}
+export function isCorruptSessionResult(result) {
+    try {
+        const read = readRunTerminal(result);
+        return read !== null && read.kind === 'failed' && isCorruptSessionCode(read.code);
+    }
+    catch {
+        return false;
+    }
+}
+export function isCorruptSessionRunRow(row) {
+    if (typeof row !== 'object' || row === null || Array.isArray(row))
+        return false;
+    try {
+        const read = readRunTerminal(row.result);
+        if (read !== null)
+            return read.kind === 'failed' && isCorruptSessionCode(read.code);
+        const column = row.errorCode;
+        return typeof column === 'string' && isCorruptSessionCode(column);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/corruptSessionCopy.d.ts

@@ -0,0 +1 @@
+export declare function corruptSessionContent(): string;

package/dist/corruptSessionCopy.js

@@ -0,0 +1,4 @@
+export function corruptSessionContent() {
+    return ("This session's saved history cannot be read — its stored log is damaged — so the engine cannot open this session. " +
+        'Retrying will not help: whoever operates this engine has to repair or remove that stored log. Until then, continue in a new session.');
+}

package/dist/decideFailureNote.d.ts

@@ -1 +1,2 @@
-export declare function decideFailureNote(err: unknown): string;
+import { type ParkedResumeStartupDecision } from './resumeRefusalCopy.js';
+export declare function decideFailureNote(err: unknown, decision?: ParkedResumeStartupDecision): string;