@sema-agent/client-core 0.99.0 → 0.101.0

package/dist/ruleCompileVerdict.js

@@ -1,4 +1,6 @@
-import { validatePermissionRules } from './coreValuePorts.js';
+import { readRuleEntry, validatePermissionRules } from './coreValuePorts.js';
+import { guardedRead, readOwnDataValue } from './ownKey.js';
+import { engineVersionTier } from './supportFloor.js';
 const RULE_COMPILE_ROOT = '/';
 function issueText(issue, key) {
     try {
@@ -20,9 +22,21 @@ function firstIssue(issues) {
     }
 }
 export function ruleCompileVerdict(rule, behavior) {
+    return compileUnder(rule, behavior, { root: RULE_COMPILE_ROOT });
+}
+export function ruleCompileVerdictUnder(rule, behavior, pathBases) {
+    const given = {};
+    for (const base of ['cwd', 'root', 'home']) {
+        const v = guardedRead(() => readOwnDataValue(pathBases, base));
+        if (typeof v === 'string')
+            given[base] = v;
+    }
+    return compileUnder(rule, behavior, given);
+}
+function compileUnder(rule, behavior, pathBases) {
     let issues;
     try {
-        issues = validatePermissionRules([{ rule, behavior }], { pathBases: { root: RULE_COMPILE_ROOT } });
+        issues = validatePermissionRules([{ rule, behavior }], { pathBases });
         if (!Array.isArray(issues))
             return { kind: 'unknown' };
         if (issues.length === 0)
@@ -36,3 +50,54 @@ export function ruleCompileVerdict(rule, behavior) {
     const message = issueText(issue, 'message');
     return { kind: 'refused', ...(code !== undefined ? { code } : {}), ...(message !== undefined ? { message } : {}) };
 }
+export function denyEntryReading(rule) {
+    try {
+        const reading = readRuleEntry(rule, 'deny');
+        if (typeof reading !== 'object' || reading === null)
+            return { kind: 'unknown' };
+        const kind = readOwnDataValue(reading, 'kind');
+        if (kind === 'row') {
+            const compiled = readOwnDataValue(reading, 'compiled');
+            return typeof compiled === 'object' && compiled !== null ? { kind: 'row' } : { kind: 'unknown' };
+        }
+        if (kind !== 'inert')
+            return { kind: 'unknown' };
+        const reason = readOwnDataValue(reading, 'reason');
+        if (reason === 'grammar' || reason === 'content_unsupported' || reason === 'wildcard_all' || reason === 'namespace_wildcard')
+            return { kind: 'inert', reason };
+        return { kind: 'unknown' };
+    }
+    catch {
+        return { kind: 'unknown' };
+    }
+}
+function readsAsDomainSpelling(rule) {
+    try {
+        const reading = readRuleEntry(rule, 'allow');
+        if (typeof reading !== 'object' || reading === null)
+            return false;
+        if (readOwnDataValue(reading, 'kind') !== 'row')
+            return false;
+        const compiled = readOwnDataValue(reading, 'compiled');
+        if (typeof compiled !== 'object' || compiled === null)
+            return false;
+        return readOwnDataValue(compiled, 'kind') === 'domain';
+    }
+    catch {
+        return false;
+    }
+}
+export const DOMAIN_TIGHTEN_HONORED_FROM = '7.135.0';
+function targetLeavesDomainTightenInert(serverVersion) {
+    return engineVersionTier(serverVersion) === 'engine' && engineVersionTier(serverVersion, DOMAIN_TIGHTEN_HONORED_FROM) === 'legacy';
+}
+export function tightenEntryNeverMatches(rule, serverVersion) {
+    if (!targetLeavesDomainTightenInert(serverVersion))
+        return false;
+    const r = denyEntryReading(rule);
+    if (r.kind !== 'inert' || r.reason !== 'content_unsupported')
+        return false;
+    if (!readsAsDomainSpelling(rule))
+        return false;
+    return ruleCompileVerdict(rule, 'deny').kind === 'compiles';
+}

package/dist/ruleReadings.d.ts

@@ -0,0 +1,58 @@
+import type { UiLanguage } from './env/uiLanguage.js';
+import { type PermissionsDeclarationInput, type PermissionsKeptReason, type WireRuleOrigin } from './permissionsDeclaration.js';
+import type { PermissionsAllowGrantReading } from './permissionsAllowGrantCapability.js';
+import { type RuleCompileVerdict } from './ruleCompileVerdict.js';
+import type { ToolRosterView } from './toolRoster.js';
+export interface RuleReadingBases {
+    readonly cwd?: string;
+    readonly root?: string;
+    readonly home?: string;
+}
+export interface RuleReadingFacts {
+    readonly bases?: RuleReadingBases;
+    readonly roster?: ToolRosterView | null;
+}
+export interface RuleReadingEntryRow {
+    readonly kind: 'row';
+    readonly grammar: string;
+}
+export interface RuleReadingEntryInert {
+    readonly kind: 'inert';
+    readonly reason: string;
+    readonly verdict?: string;
+    readonly currentName?: string;
+    readonly currentNameShown?: string;
+}
+export interface RuleReadingEntryUnread {
+    readonly kind: 'unread';
+}
+export type RuleReadingEntry = RuleReadingEntryRow | RuleReadingEntryInert | RuleReadingEntryUnread;
+export type PermissionsRuleCompileReading = RuleCompileVerdict;
+export interface PermissionsRuleWireSent {
+    readonly sent: true;
+    readonly as: string;
+}
+export interface PermissionsRuleWireKept {
+    readonly sent: false;
+    readonly reason: PermissionsKeptReason;
+    readonly code?: string;
+    readonly message?: string;
+}
+export type PermissionsRuleWire = PermissionsRuleWireSent | PermissionsRuleWireKept;
+export interface PermissionsRuleReading {
+    readonly rule: string;
+    readonly list: 'deny' | 'cliDeny' | 'ask' | 'allow';
+    readonly bucket: 'deny' | 'ask' | 'allow';
+    readonly origin?: WireRuleOrigin;
+    readonly wire: PermissionsRuleWire;
+    readonly entry: RuleReadingEntry;
+    readonly compile?: PermissionsRuleCompileReading;
+}
+export type RuleReadingEntryMode = 'with_roster' | 'grammar_only' | 'unavailable';
+export interface PermissionsRuleReadings {
+    readonly rules: readonly PermissionsRuleReading[];
+    readonly entryMode: RuleReadingEntryMode;
+}
+export declare function ruleReadingsOf(input: PermissionsDeclarationInput, caps: PermissionsAllowGrantReading, facts?: RuleReadingFacts | null): PermissionsRuleReadings;
+export type RuleNearMissRow = Pick<PermissionsRuleReading, 'rule' | 'wire' | 'entry'>;
+export declare function ruleNearMissSentence(rows: readonly RuleNearMissRow[], lang?: UiLanguage): string | undefined;

package/dist/ruleReadings.js

@@ -0,0 +1,132 @@
+import { displayUntrusted } from './displayUntrusted.js';
+import { capForDisplay } from './fleetTaskDesc.js';
+import { hasCoreValuePort, readRuleEntry } from './coreValuePorts.js';
+import { msg, renderMessage } from './i18n/translate.js';
+import { guardedRead, readOwnDataValue } from './ownKey.js';
+import { assembledRuleRows } from './permissionsDeclaration.js';
+import { ruleCompileVerdictUnder } from './ruleCompileVerdict.js';
+import { rosterMountedNames } from './rosterMountedNames.js';
+const unread = () => Object.freeze({ kind: 'unread' });
+function text(v) {
+    return typeof v === 'string' && v !== '' ? v : undefined;
+}
+function entryOf(rule, direction, roster) {
+    try {
+        const reading = readRuleEntry(rule, direction, roster);
+        if (typeof reading !== 'object' || reading === null)
+            return unread();
+        const kind = readOwnDataValue(reading, 'kind');
+        if (kind === 'row') {
+            const compiled = readOwnDataValue(reading, 'compiled');
+            if (typeof compiled !== 'object' || compiled === null)
+                return unread();
+            const grammar = text(readOwnDataValue(compiled, 'kind'));
+            return grammar === undefined ? unread() : Object.freeze({ kind: 'row', grammar });
+        }
+        if (kind !== 'inert')
+            return unread();
+        const reason = text(readOwnDataValue(reading, 'reason'));
+        if (reason === undefined)
+            return unread();
+        const verdict = text(readOwnDataValue(reading, 'verdict'));
+        const currentName = text(readOwnDataValue(reading, 'currentName'));
+        return Object.freeze({
+            kind: 'inert',
+            reason,
+            ...(verdict !== undefined ? { verdict } : {}),
+            ...(currentName !== undefined ? { currentName, currentNameShown: displayUntrusted(currentName) } : {}),
+        });
+    }
+    catch {
+        return unread();
+    }
+}
+function factsOf(facts) {
+    if (typeof facts !== 'object' || facts === null)
+        return { bases: undefined, roster: undefined };
+    const bases = guardedRead(() => readOwnDataValue(facts, 'bases'));
+    const roster = guardedRead(() => readOwnDataValue(facts, 'roster'));
+    return {
+        bases: typeof bases === 'object' && bases !== null ? bases : undefined,
+        roster: (roster ?? undefined),
+    };
+}
+export function ruleReadingsOf(input, caps, facts) {
+    const rows = assembledRuleRows(input, caps);
+    const { bases, roster: rosterView } = factsOf(facts);
+    const readerInstalled = hasCoreValuePort('readRuleEntry');
+    const mounted = readerInstalled ? rosterMountedNames(rosterView) : 'absent';
+    const roster = typeof mounted === 'object' ? mounted : undefined;
+    const rules = rows.map((r) => {
+        const wire = r.fate.sent
+            ? Object.freeze({ sent: true, as: r.fate.wire })
+            : Object.freeze({
+                sent: false,
+                reason: r.fate.reason,
+                ...(r.fate.code !== undefined ? { code: r.fate.code } : {}),
+                ...(r.fate.message !== undefined ? { message: r.fate.message } : {}),
+            });
+        const entry = readerInstalled ? entryOf(r.rule, r.bucket === 'allow' ? 'allow' : 'deny', roster) : unread();
+        const compile = bases !== undefined && r.bucket !== 'allow' ? ruleCompileVerdictUnder(r.rule, r.bucket, bases) : undefined;
+        return Object.freeze({
+            rule: r.rule,
+            list: r.list,
+            bucket: r.bucket,
+            ...(r.origin !== undefined ? { origin: r.origin } : {}),
+            wire,
+            entry,
+            ...(compile !== undefined ? { compile } : {}),
+        });
+    });
+    const anyRead = rules.some((r) => r.entry.kind !== 'unread');
+    const entryMode = !readerInstalled || (rules.length > 0 && !anyRead) ? 'unavailable' : roster !== undefined ? 'with_roster' : 'grammar_only';
+    return Object.freeze({ rules: Object.freeze(rules), entryMode });
+}
+const NEAR_MISS_NAMED_MAX = 5;
+const NEAR_MISS_RULE_MAX = 120;
+const NEAR_MISS_NAME_MAX = 80;
+export function ruleNearMissSentence(rows, lang) {
+    const seen = new Set();
+    const items = [];
+    try {
+        if (!Array.isArray(rows))
+            return undefined;
+        for (const row of rows) {
+            if (typeof row !== 'object' || row === null)
+                continue;
+            const rule = guardedRead(() => readOwnDataValue(row, 'rule'));
+            if (typeof rule !== 'string' || rule === '' || seen.has(rule))
+                continue;
+            const wire = guardedRead(() => readOwnDataValue(row, 'wire'));
+            if (typeof wire !== 'object' || wire === null || guardedRead(() => readOwnDataValue(wire, 'sent')) !== true)
+                continue;
+            const entry = guardedRead(() => readOwnDataValue(row, 'entry'));
+            if (typeof entry !== 'object' || entry === null)
+                continue;
+            if (guardedRead(() => readOwnDataValue(entry, 'kind')) !== 'inert' || guardedRead(() => readOwnDataValue(entry, 'reason')) !== 'near_miss')
+                continue;
+            const mounted = text(guardedRead(() => readOwnDataValue(entry, 'currentName')));
+            if (mounted === undefined)
+                continue;
+            seen.add(rule);
+            items.push({ rule, mounted });
+        }
+    }
+    catch {
+        return undefined;
+    }
+    if (items.length === 0)
+        return undefined;
+    const shown = items.slice(0, NEAR_MISS_NAMED_MAX);
+    const separator = renderMessage(msg('rules.refusal.itemSeparator'), lang);
+    const named = shown
+        .map((it) => renderMessage(msg('rules.refusal.item', {
+        rule: `"${capForDisplay(it.rule, NEAR_MISS_RULE_MAX)}"`,
+        reason: renderMessage(msg('rules.nearMiss.reason', { mounted: capForDisplay(displayUntrusted(it.mounted), NEAR_MISS_NAME_MAX) }), lang),
+    }), lang))
+        .join(separator);
+    const rest = items.length - shown.length;
+    const list = rest > 0 ? msg('rules.refusal.list.more', { shown: named, count: rest }) : named;
+    const listText = typeof list === 'string' ? list : renderMessage(list, lang);
+    return renderMessage(items.length === 1 ? msg('rules.nearMiss.sentence.one', { list: listText }) : msg('rules.nearMiss.sentence.other', { count: items.length, list: listText }), lang);
+}

package/dist/ruleRefusalSentence.d.ts

@@ -0,0 +1,8 @@
+import type { UiLanguage } from './env/uiLanguage.js';
+import type { PermissionsKeptRule } from './permissionsDeclaration.js';
+export type RuleRefusalRow = Pick<PermissionsKeptRule, 'rule' | 'reason' | 'code' | 'message'>;
+export declare function ruleRefusalSentence(rows: readonly RuleRefusalRow[], lang?: UiLanguage): string | undefined;
+export declare function ruleRefusalListText(items: readonly {
+    readonly rule?: string;
+    readonly reason: string;
+}[], lang?: UiLanguage): string;

package/dist/ruleRefusalSentence.js

@@ -0,0 +1,64 @@
+import { capForDisplay } from './fleetTaskDesc.js';
+import { msg, renderMessage } from './i18n/translate.js';
+import { permissionRuleIssueDetail } from './permissionRuleIssue.js';
+const RULE_REFUSAL_NAMED_MAX = 5;
+const RULE_NAME_MAX = 120;
+const CLASS_OF_REASON = Object.freeze({
+    retired_tool_name: 'toolName',
+    unprefixed_namespaced_name: 'toolName',
+    incomplete_protocol_name: 'toolName',
+    home_relative_path: 'homePath',
+    compile_refused: 'compile',
+    paren_in_tool_name: 'compile',
+    content_form_never_matches: 'neverMatches',
+});
+function reasonOf(row, lang) {
+    const cls = typeof row.reason === 'string' && Object.hasOwn(CLASS_OF_REASON, row.reason) ? CLASS_OF_REASON[row.reason] : undefined;
+    if (cls === 'toolName')
+        return renderMessage(msg('rules.refusal.reason.toolName'), lang);
+    if (cls === 'homePath')
+        return renderMessage(msg('rules.refusal.reason.homePath'), lang);
+    if (cls === 'neverMatches')
+        return renderMessage(msg('rules.refusal.reason.neverMatches'), lang);
+    if (cls === 'compile')
+        return permissionRuleIssueDetail(row.code, row.message, row.rule, lang);
+    return undefined;
+}
+function nameOf(rule) {
+    return `"${capForDisplay(rule, RULE_NAME_MAX)}"`;
+}
+export function ruleRefusalSentence(rows, lang) {
+    const seen = new Set();
+    const items = [];
+    try {
+        if (!Array.isArray(rows))
+            return undefined;
+        for (const row of rows) {
+            if (typeof row !== 'object' || row === null)
+                continue;
+            const rule = row.rule;
+            if (typeof rule !== 'string' || rule === '' || seen.has(rule))
+                continue;
+            const reason = reasonOf(row, lang);
+            if (reason === undefined)
+                continue;
+            seen.add(rule);
+            items.push({ rule, reason });
+        }
+    }
+    catch {
+        return undefined;
+    }
+    if (items.length === 0)
+        return undefined;
+    const listText = ruleRefusalListText(items, lang);
+    return renderMessage(items.length === 1 ? msg('rules.refusal.sentence.one', { list: listText }) : msg('rules.refusal.sentence.other', { count: items.length, list: listText }), lang);
+}
+export function ruleRefusalListText(items, lang) {
+    const shown = items.slice(0, RULE_REFUSAL_NAMED_MAX);
+    const separator = renderMessage(msg('rules.refusal.itemSeparator'), lang);
+    const named = shown.map((it) => (it.rule === undefined ? it.reason : renderMessage(msg('rules.refusal.item', { rule: nameOf(it.rule), reason: it.reason }), lang))).join(separator);
+    const rest = items.length - shown.length;
+    const list = rest > 0 ? msg('rules.refusal.list.more', { shown: named, count: rest }) : named;
+    return typeof list === 'string' ? list : renderMessage(list, lang);
+}

package/dist/runCancelContext.d.ts

@@ -30,7 +30,6 @@ 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 };
 export type AbortCauseReading = {
     readonly kind: 'known';

package/dist/runCancelContext.js

@@ -57,7 +57,6 @@ export function classifyRunAbortCause(record) {
         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) {
@@ -85,7 +84,7 @@ function abortCauseIn(holder) {
     const raw = ownDataOf(holder, 'abortCause');
     if (typeof raw !== 'string' || raw.length === 0)
         return undefined;
-    return ABORT_CAUSES.includes(raw) ? { kind: 'known', cause: raw } : { kind: 'unrecognized', word: raw };
+    return SDK_ABORT_CAUSES.includes(raw) ? { kind: 'known', cause: raw } : { kind: 'unrecognized', word: raw };
 }
 export function readAbortCause(frame) {
     try {

package/dist/runTerminal.d.ts

@@ -27,6 +27,9 @@ export type RunTerminalFailureDetail = RunTerminalProviderRejectedDetail | {
 export type RunTerminalJsonValue = string | number | boolean | null | readonly RunTerminalJsonValue[] | {
     readonly [key: string]: RunTerminalJsonValue;
 };
+export type RunTerminalCodedDetail = {
+    readonly [key: string]: RunTerminalJsonValue;
+};
 export interface RunTerminalOutputLimit {
     capStop: boolean;
     outputTokens?: number;
@@ -94,6 +97,8 @@ type RunTerminalReadArm = {
     code?: string;
     message?: string;
 };
+export declare function runTerminalCodedDetail(read: RunTerminalRead | null | undefined): RunTerminalCodedDetail | undefined;
+export declare function terminalCodedDetailOf(carrier: {} | null | undefined): RunTerminalCodedDetail | undefined;
 export declare function readRunTerminal(result: unknown): RunTerminalRead | null;
 export declare const REVIEW_PARK_GATE_KINDS: readonly string[];
 export declare function runTerminalGateKind(read: RunTerminalRead | null): string | undefined;

package/dist/runTerminal.js

@@ -2,6 +2,7 @@ import { CORE_PROMPT_BLOCK_CAUSES } from './generated/engineFactTables.js';
 import { isSdkRunParked } from './terminalStatuses.js';
 import { readOwnDataNonEmptyString, readOwnDataValue } from './ownKey.js';
 import { doneResultView } from './replayBody.js';
+import { washCredentials } from './displayUntrusted.js';
 export const PROMPT_BLOCK_CAUSES = CORE_PROMPT_BLOCK_CAUSES;
 const _promptBlockTablePin = true;
 void _promptBlockTablePin;
@@ -39,7 +40,7 @@ void _modelOutputInvalidCausePin;
 const CODED_DETAIL_MAX_DEPTH = 40;
 function ownData(o, k) {
     const d = Object.getOwnPropertyDescriptor(o, k);
-    return d !== undefined && 'value' in d ? d.value : undefined;
+    return d !== undefined && Object.hasOwn(d, 'value') ? d.value : undefined;
 }
 function isPlainRecord(v) {
     if (typeof v !== 'object' || v === null || Array.isArray(v))
@@ -53,8 +54,10 @@ function jsonSnapshot(v, depth, ctx) {
     ctx.budget -= 1;
     if (ctx.budget < 0)
         throw CODED_DETAIL_OVER_BUDGET;
-    if (v === null || typeof v === 'string' || typeof v === 'boolean')
+    if (v === null || typeof v === 'boolean')
         return v;
+    if (typeof v === 'string')
+        return ctx.leaf === undefined ? v : ctx.leaf(v);
     if (typeof v === 'number')
         return Number.isFinite(v) ? v : undefined;
     if (depth >= CODED_DETAIL_MAX_DEPTH)
@@ -148,6 +151,51 @@ function requestRouteOf(d) {
         return undefined;
     }
 }
+function codedBodySnapshot(inner, washLeaves = false) {
+    if (!isPlainRecord(inner))
+        return undefined;
+    let snap;
+    try {
+        snap = jsonSnapshot(inner, 0, { budget: CODED_DETAIL_BUDGET, path: new Set(), ...(washLeaves ? { leaf: washCredentials } : {}) });
+    }
+    catch (e) {
+        if (e === CODED_DETAIL_OVER_BUDGET)
+            return undefined;
+        throw e;
+    }
+    if (snap === undefined || snap === null || typeof snap !== 'object' || Array.isArray(snap))
+        return undefined;
+    return snap;
+}
+export function runTerminalCodedDetail(read) {
+    try {
+        if (typeof read !== 'object' || read === null)
+            return undefined;
+        if (ownData(read, 'kind') !== 'failed')
+            return undefined;
+        const detail = ownData(read, 'detail');
+        if (typeof detail !== 'object' || detail === null)
+            return undefined;
+        if (ownData(detail, 'kind') !== CODED_DETAIL_KIND)
+            return undefined;
+        const body = codedBodySnapshot(ownData(detail, 'detail'), true);
+        return body !== undefined && Object.keys(body).length > 0 ? body : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function terminalCodedDetailOf(carrier) {
+    try {
+        if (typeof carrier !== 'object' || carrier === null || Array.isArray(carrier))
+            return undefined;
+        const body = codedBodySnapshot(ownData(carrier, '_sema_coded_detail'), true);
+        return body !== undefined && Object.keys(body).length > 0 ? body : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function failureDetailOf(cause) {
     try {
         const own = ownValueOf;
@@ -185,21 +233,8 @@ function failureDetailOf(cause) {
             };
         }
         if (kind === CODED_DETAIL_KIND) {
-            const inner = ownData(v, 'detail');
-            if (!isPlainRecord(inner))
-                return undefined;
-            let snap;
-            try {
-                snap = jsonSnapshot(inner, 0, { budget: CODED_DETAIL_BUDGET, path: new Set() });
-            }
-            catch (e) {
-                if (e === CODED_DETAIL_OVER_BUDGET)
-                    return undefined;
-                throw e;
-            }
-            if (snap === undefined || snap === null || typeof snap !== 'object' || Array.isArray(snap))
-                return undefined;
-            return { kind: CODED_DETAIL_KIND, detail: snap };
+            const snap = codedBodySnapshot(ownData(v, 'detail'));
+            return snap === undefined ? undefined : { kind: CODED_DETAIL_KIND, detail: snap };
         }
         if (kind === MODEL_OUTPUT_INVALID_DETAIL_KIND) {
             const c = ownData(v, 'cause');

package/dist/sandboxWire.d.ts

@@ -1,3 +1,4 @@
+import type { TaskRequestLike } from './request/taskRequest.js';
 export type SandboxSelection = {
     mode: 'default';
 } | {
@@ -13,7 +14,7 @@ export type SandboxParseResult = {
     ok: false;
     error: string;
 };
-export declare function parseSandboxArgv(argv: readonly string[]): SandboxParseResult;
+export declare function sandboxFromFlag(value?: string): SandboxParseResult;
 export declare function sandboxRequestFields(sel: SandboxSelection | undefined): {
     sandboxImageProfile?: string;
 };
@@ -25,4 +26,4 @@ export declare const SANDBOX_NO_PUBLISHED_IMAGE_404_ANCHOR = "no published sandb
 export declare const SANDBOX_CASCADE_CONFLICT_400_ANCHOR = "not supported together with cascade/verify";
 export type SandboxHintHost = 'terminal' | 'web' | 'desktop';
 export declare const SANDBOX_HINT_HOSTS: readonly SandboxHintHost[];
-export declare function sandboxDegradeHint(err: unknown, host?: SandboxHintHost): string | undefined;
+export declare function sandboxDegradeHint(err: unknown, host?: SandboxHintHost, sentRequest?: TaskRequestLike): string | undefined;

package/dist/sandboxWire.js

@@ -1,18 +1,16 @@
-import { lastFlagValue } from './argvFlagValue.js';
-import { CAPABILITY_IMAGE_INDEX_REQUIRED } from './engineErrorCodes.js';
+import { CAPABILITY_IMAGE_INDEX_REQUIRED, CAPABILITY_K8S_LANE_REQUIRED, isStatusDerivedCoarseCode, NOT_FOUND_IMAGE, REQUEST_FIELD_CONFLICT, REQUEST_PRECONDITION_UNMET } 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' +
     '  --sandbox auto       let the model pick via its SelectEnvironment tool (advisory — choice + reason shown in the reply)\n' +
     '  (no flag)            the worker default image';
-export function parseSandboxArgv(argv) {
-    const flag = lastFlagValue(argv, '--sandbox');
-    if (!flag.present)
+export function sandboxFromFlag(value) {
+    if (value === undefined)
         return { ok: true, sel: { mode: 'default' } };
-    if (flag.raw === undefined)
+    if (typeof value !== 'string')
         return { ok: false, error: USAGE_HINT };
-    const v = flag.raw.trim();
+    const v = value.trim();
     if (v.length === 0)
         return { ok: false, error: USAGE_HINT };
     if (/\s/.test(v)) {
@@ -49,15 +47,15 @@ export const SANDBOX_NO_PUBLISHED_IMAGE_404_ANCHOR = 'no published sandbox image
 export const SANDBOX_CASCADE_CONFLICT_400_ANCHOR = 'not supported together with cascade/verify';
 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.',
+    imageIndexRequired: {
+        fact: 'Cloud sandbox images are not available on this engine: it has no sandbox image index (its store keeps none, or no image catalog is attached from the sema-web-admin config center), 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.',
+            terminal: 'Use a worker that has the image index (a SQL-backed store with the image catalog attached), or re-run without --sandbox.',
+            graphical: 'Use a worker that has the image index (a SQL-backed store with the image catalog attached), or keep the default environment.',
         },
     },
-    k8sLaneOnly400: {
+    k8sLaneOnly: {
         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',
@@ -66,12 +64,13 @@ const SANDBOX_HINT_ARMS = Object.freeze({
             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.',
+    sessionRequired: {
+        subject: { terminal: '--sandbox <profile>', graphical: 'The selected sandbox image profile' },
+        fact: ' is bound to a session, and this request resolved none, so the per-task image could not be registered.',
         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.',
+            terminal: 'Run it inside a session, or re-run without --sandbox.',
+            graphical: 'Start the work inside a session, or keep the default environment.',
         },
     },
     noPublishedImage404: {
@@ -104,21 +103,54 @@ 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;
+function sentSandboxFacts(sentRequest) {
+    if (sentRequest === undefined || sentRequest === null || typeof sentRequest !== 'object')
+        return { profile: false, cascadeOrVerify: false, sessionOrDevice: false };
+    const profile = sandboxSlot(sentRequest, 'sandboxImageProfile');
+    const sent = (key) => {
+        const v = sandboxSlot(sentRequest, key);
+        return typeof v === 'string' && v.length > 0;
+    };
+    return {
+        profile: typeof profile === 'string' && profile.length > 0,
+        cascadeOrVerify: sandboxSlot(sentRequest, 'cascade') === true || sandboxSlot(sentRequest, 'verify') === true,
+        sessionOrDevice: sent('sessionId') || sent('deviceId'),
+    };
+}
+export function sandboxDegradeHint(err, host, sentRequest) {
     try {
+        if (typeof err !== 'object' || err === null)
+            return undefined;
+        const status = sandboxSlot(err, 'status');
+        const codeRaw = sandboxSlot(err, 'errorCode');
+        const code = typeof codeRaw === 'string' && codeRaw.length > 0 ? codeRaw : undefined;
+        if (status === 501 && code === CAPABILITY_K8S_LANE_REQUIRED)
+            return sandboxHintOf(SANDBOX_HINT_ARMS.k8sLaneOnly, host);
+        if (status === 501 && code === CAPABILITY_IMAGE_INDEX_REQUIRED)
+            return sandboxHintOf(SANDBOX_HINT_ARMS.imageIndexRequired, host);
+        if (status === 404 && code === NOT_FOUND_IMAGE)
+            return sandboxHintOf(SANDBOX_HINT_ARMS.noPublishedImage404, host);
+        if (status === 400 && code === REQUEST_PRECONDITION_UNMET) {
+            const sent = sentSandboxFacts(sentRequest);
+            return sent.profile && !sent.cascadeOrVerify && !sent.sessionOrDevice ? sandboxHintOf(SANDBOX_HINT_ARMS.sessionRequired, host) : undefined;
+        }
+        if (typeof status !== 'number')
+            return undefined;
+        const noCode = code === undefined || isStatusDerivedCoarseCode(code);
+        const cascadeCoded = code === REQUEST_FIELD_CONFLICT && (sentRequest === undefined || (() => {
+            const sent = sentSandboxFacts(sentRequest);
+            return sent.profile && sent.cascadeOrVerify;
+        })());
+        if (!noCode && !cascadeCoded)
+            return undefined;
         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))
+        if (noCode && status === 400 && msg.includes(SANDBOX_K8S_ONLY_400_ANCHOR))
+            return sandboxHintOf(SANDBOX_HINT_ARMS.k8sLaneOnly, host);
+        if (noCode && status === 400 && msg.includes(SANDBOX_NO_IMAGE_INDEX_400_ANCHOR))
+            return sandboxHintOf(SANDBOX_HINT_ARMS.imageIndexRequired, host);
+        if (noCode && 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);