@sema-agent/client-core 0.88.0 → 0.90.0

package/dist/adapter/activeRunSelfHeal.js

@@ -1,5 +1,6 @@
 import { abortableSleep } from '../abortableSleep.js';
 import { corruptStoredRowContent, corruptStoredRowWhere, effectiveWireErrorCode } from '../wireErrorTriage.js';
+import { steeringRefusedBeforeEngine, steeringStatusIs4xx } from '../controlRouter.js';
 export const PLAN_REVIEW_GATE_KIND = 'plan_review';
 export const PLAN_REVIEW_GATE_KINDS = Object.freeze([PLAN_REVIEW_GATE_KIND, 'dry_run_review']);
 export const ASK_PARK_GATE_KINDS = Object.freeze(['human', 'irreversible_ask', 'policy_ask', 'tool_approval']);
@@ -260,8 +261,9 @@ function reopenedOfOutcome(outcome) {
     }
 }
 export function atMostOnceFailureClass(e) {
-    const status = errorSlot(e, 'status');
-    return typeof status === 'number' && status >= 400 && status < 500 ? 'rejected' : 'unknown';
+    if (typeof e === 'object' && e !== null && steeringStatusIs4xx(e))
+        return 'rejected';
+    return typeof e === 'object' && e !== null && steeringRefusedBeforeEngine(e) !== undefined ? 'rejected' : 'unknown';
 }
 export function readSteerDelivery(receipt) {
     try {

package/dist/adapter/downstream/eventToSdkMessage.js

@@ -1,4 +1,4 @@
-import { wiringManifestViewOf } from './wiringManifestView.js';
+import { readInstructionsSegment, wiringManifestViewOf } from './wiringManifestView.js';
 import { stamp, snapshotSegmentIdentity, } from '../types.js';
 import { turnUsageToModelUsage } from './turnUsageToModelUsage.js';
 import { ccToolDenialKindForToolEnd, gateOutcomeOf } from '../../gateOutcome.js';
@@ -550,7 +550,8 @@ function wiringManifestSupersetBody(ev) {
     const readDeny = projectReadDenySection(ev.readDeny);
     const hands = projectHandsSection(ev);
     const fileHistory = projectFileHistorySection(ev);
-    if (modelGate === undefined && autoMode === undefined && mcp === undefined && tools === undefined && hooks === undefined && lsp === undefined && writeProtection === undefined && autoConsolidation === undefined && readDeny === undefined && hands === undefined && fileHistory === undefined)
+    const instructions = readInstructionsSegment(ev, 'instructions');
+    if (modelGate === undefined && autoMode === undefined && mcp === undefined && tools === undefined && hooks === undefined && lsp === undefined && writeProtection === undefined && autoConsolidation === undefined && readDeny === undefined && hands === undefined && fileHistory === undefined && instructions === undefined)
         return undefined;
     return {
         ...(modelGate !== undefined ? { _sema_modelGate: modelGate } : {}),
@@ -564,6 +565,7 @@ function wiringManifestSupersetBody(ev) {
         ...(readDeny !== undefined ? { _sema_readDeny: readDeny } : {}),
         ...(hands !== undefined ? { _sema_hands: hands } : {}),
         ...(fileHistory !== undefined ? { _sema_fileHistory: fileHistory } : {}),
+        ...(instructions !== undefined ? { _sema_instructions: instructions } : {}),
     };
 }
 function projectFileHistorySection(holder) {

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

@@ -12,6 +12,9 @@ export type WiringManifestSections = {
     _sema_readDeny?: WiringManifestReadDenyView;
     _sema_hands?: WiringManifestHandsView;
     _sema_fileHistory?: string;
+    _sema_instructions?: {
+        readonly selected: readonly string[];
+    };
     eventId?: string;
 };
 export interface WiringManifestView {
@@ -26,6 +29,12 @@ export interface WiringManifestView {
     readDeny?: WiringManifestReadDenyView;
     hands?: WiringManifestHandsView;
     fileHistory?: string;
+    instructions?: {
+        readonly selected: readonly string[];
+    };
     eventId?: string;
 }
+export declare function readInstructionsSegment(holder: object, key: 'instructions' | '_sema_instructions'): {
+    readonly selected: readonly string[];
+} | undefined;
 export declare function wiringManifestViewOf(s: WiringManifestSections): WiringManifestView | undefined;

package/dist/adapter/downstream/wiringManifestView.js

@@ -2,8 +2,34 @@ const _viewPin = true;
 void _viewPin;
 const _viewKeysPin = true;
 void _viewKeysPin;
+export function readInstructionsSegment(holder, key) {
+    try {
+        if (!Object.hasOwn(holder, key))
+            return undefined;
+        const raw = holder[key];
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw) || !Object.hasOwn(raw, 'selected'))
+            return undefined;
+        const sel = raw.selected;
+        if (!Array.isArray(sel))
+            return undefined;
+        const out = [];
+        for (let i = 0; i < sel.length; i++) {
+            if (!Object.hasOwn(sel, i))
+                return undefined;
+            const v = sel[i];
+            if (typeof v !== 'string' || v.length === 0)
+                return undefined;
+            out.push(v);
+        }
+        return Object.freeze({ selected: Object.freeze(out) });
+    }
+    catch {
+        return undefined;
+    }
+}
 const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 export function wiringManifestViewOf(s) {
+    const instructions = readInstructionsSegment(s, '_sema_instructions');
     const view = {
         ...(isObj(s._sema_modelGate) ? { modelGate: s._sema_modelGate } : {}),
         ...(isObj(s._sema_autoMode) ? { autoMode: s._sema_autoMode } : {}),
@@ -16,6 +42,7 @@ export function wiringManifestViewOf(s) {
         ...(isObj(s._sema_readDeny) ? { readDeny: s._sema_readDeny } : {}),
         ...(isObj(s._sema_hands) && typeof s._sema_hands.mounted === 'boolean' ? { hands: s._sema_hands } : {}),
         ...(typeof s._sema_fileHistory === 'string' && s._sema_fileHistory.length > 0 ? { fileHistory: s._sema_fileHistory } : {}),
+        ...(instructions !== undefined ? { instructions } : {}),
     };
     if (Object.keys(view).length === 0)
         return undefined;

package/dist/adapter/runStream.d.ts

@@ -1,6 +1,7 @@
 import type { AgentEvent } from '@sema-agent/sdk';
 import { type SDKMessage, type EmitContext, type ModelUsage } from './types.js';
 import { type EngineTurnUsage } from './downstream/turnUsageToModelUsage.js';
+import { type ToolHistoryErrorCarrier } from '../toolHistoryMismatch.js';
 export interface ActiveRunPendingGate {
     readonly kind: string | null;
     readonly decidePath: string | null;
@@ -27,6 +28,7 @@ export declare function isGovernanceTerminal(input: {
     status: string | undefined;
     errorCode: string | undefined;
 }): boolean;
+export declare function toolHistoryErrorCarrierOf(terminalOrResult: object | null | undefined): ToolHistoryErrorCarrier;
 export declare function droppedWhySentence(why: string): string;
 export declare function _resetDroppedFrameReportForTest(): void;
 export declare function _droppedFrameMemoSizeForTest(): number;

package/dist/adapter/runStream.js

@@ -140,11 +140,6 @@ function engineSessionIdOf(result) {
     const v = result?.sessionId;
     return typeof v === 'string' && v.length > 0 ? v : undefined;
 }
-function providerFailureStatusOf(result) {
-    const af = result?.apiFailure;
-    const status = typeof af === 'object' && af !== null ? af.status : undefined;
-    return typeof status === 'number' && Number.isFinite(status) ? status : undefined;
-}
 export function isOutcomeUnknownRowText(text) {
     return text.trimStart().startsWith(`${OUTCOME_UNKNOWN_ROW_PREFIX}:`);
 }
@@ -155,6 +150,157 @@ export function isGovernanceTerminal(input) {
         return true;
     return input.errorCode === OUTPUT_INVALID;
 }
+function terminalRowFacts(ev) {
+    const doneTerminal = ev.type === 'done' ? readRunTerminal(ev.result) : null;
+    const errTextRaw = ev.type === 'failed'
+        ? (ev.errorMessage ?? ev.errorCode ?? 'run failed')
+        : doneTerminal?.kind === 'failed'
+            ? (doneTerminal.message ?? doneTerminal.code ?? 'run failed')
+            : doneTerminal?.kind === 'blocked'
+                ? (doneTerminal.reason
+                    ? `Run blocked: ${doneTerminal.reason}`
+                    : 'Run blocked (the agent reported it cannot proceed)')
+                : null;
+    const errText = errTextRaw === '' ? null : errTextRaw;
+    if (errText === null)
+        return { doneTerminal, errText, activeTaskId: undefined, busy: { busy: false, handle: null }, governance: false };
+    const activeTaskId = (ev.type === 'done' ? ev.result?.activeTaskId : undefined) ??
+        (ev.type === 'failed' ? ev.activeTaskId : undefined);
+    const busy = classifyActiveRunBusy({
+        errorCode: ev.type === 'failed' ? ev.errorCode : runTerminalCode(doneTerminal),
+        activeTaskId,
+    });
+    const governance = isGovernanceTerminal({
+        status: ev.type === 'failed' ? undefined : doneTerminal?.kind === 'blocked' ? 'blocked' : undefined,
+        errorCode: ev.type === 'failed' ? ev.errorCode : runTerminalCode(doneTerminal),
+    });
+    return { doneTerminal, errText, activeTaskId, busy, governance };
+}
+const PROVIDER_REJECTED_DETAIL = 'provider_rejected';
+function ownDataBit(o, k) {
+    try {
+        const d = Object.getOwnPropertyDescriptor(o, k);
+        return d !== undefined && Object.prototype.hasOwnProperty.call(d, 'value') ? d.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function plainObjectOf(v) {
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    try {
+        return Array.isArray(v) ? undefined : v;
+    }
+    catch {
+        return undefined;
+    }
+}
+function ownDataCopy(o, keys) {
+    const out = Object.create(null);
+    for (const k of keys) {
+        const v = ownDataBit(o, k);
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+function ownTerminalSnapshot(result) {
+    let causePlane;
+    try {
+        causePlane = 'terminal' in result;
+    }
+    catch {
+        return undefined;
+    }
+    const snap = ownDataCopy(result, ['status', 'errorCode', 'errorMessage']);
+    if (!causePlane)
+        return snap;
+    let d;
+    try {
+        d = Object.getOwnPropertyDescriptor(result, 'terminal');
+    }
+    catch {
+        return undefined;
+    }
+    if (d === undefined || !Object.prototype.hasOwnProperty.call(d, 'value'))
+        return undefined;
+    const t = plainObjectOf(d.value);
+    if (t === undefined) {
+        snap.terminal = null;
+        return snap;
+    }
+    const ts = ownDataCopy(t, ['kind', 'code', 'message']);
+    const detail = plainObjectOf(ownDataBit(t, 'detail'));
+    if (detail !== undefined)
+        ts.detail = ownDataCopy(detail, ['kind', 'status', 'code']);
+    snap.terminal = ts;
+    return snap;
+}
+function nonEmptyStr(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+function mintToolHistoryCarrier(code, status, message) {
+    const out = Object.create(null);
+    if (code !== undefined)
+        out.code = code;
+    if (status !== undefined)
+        out.status = status;
+    if (message !== undefined)
+        out.message = message;
+    return Object.freeze(out);
+}
+export function toolHistoryErrorCarrierOf(terminalOrResult) {
+    const empty = () => mintToolHistoryCarrier(undefined, undefined, undefined);
+    try {
+        const x = plainObjectOf(terminalOrResult);
+        if (x === undefined)
+            return empty();
+        const type = ownDataBit(x, 'type');
+        const frame = (type === 'done' || type === 'failed' ? x : { type: 'done', result: x });
+        return toolHistoryCarrierFromFacts(x, terminalRowFacts(frame));
+    }
+    catch {
+        return empty();
+    }
+}
+function toolHistoryCarrierFromFacts(x, facts) {
+    const empty = () => mintToolHistoryCarrier(undefined, undefined, undefined);
+    try {
+        const type = ownDataBit(x, 'type');
+        if (facts.errText === null || facts.busy.busy || facts.governance || isModelOutputErrorText(facts.errText))
+            return empty();
+        if (type === 'failed')
+            return mintToolHistoryCarrier(nonEmptyStr(ownDataBit(x, 'errorCode')), undefined, nonEmptyStr(ownDataBit(x, 'errorMessage')));
+        const result = type === 'done' ? plainObjectOf(ownDataBit(x, 'result')) : x;
+        if (result === undefined)
+            return empty();
+        const snap = ownTerminalSnapshot(result);
+        if (snap === undefined)
+            return empty();
+        const read = readRunTerminal(snap);
+        if (read === null || read.kind !== 'failed')
+            return empty();
+        const detail = plainObjectOf(ownDataBit(read, 'detail'));
+        const detailStatus = detail !== undefined && ownDataBit(detail, 'kind') === PROVIDER_REJECTED_DETAIL ? ownDataBit(detail, 'status') : undefined;
+        const apiFailure = plainObjectOf(ownDataBit(result, 'apiFailure'));
+        const apiStatus = apiFailure === undefined ? undefined : ownDataBit(apiFailure, 'status');
+        const status = typeof apiStatus === 'number' && Number.isFinite(apiStatus) ? apiStatus : typeof detailStatus === 'number' ? detailStatus : undefined;
+        return mintToolHistoryCarrier(nonEmptyStr(ownDataBit(read, 'code')), status, nonEmptyStr(ownDataBit(read, 'message')));
+    }
+    catch {
+        return empty();
+    }
+}
+function toolHistoryCarrierOfRowFrame(ev, facts) {
+    try {
+        const x = plainObjectOf(ev);
+        return x === undefined ? mintToolHistoryCarrier(undefined, undefined, undefined) : toolHistoryCarrierFromFacts(x, facts);
+    }
+    catch {
+        return mintToolHistoryCarrier(undefined, undefined, undefined);
+    }
+}
 const reportedDroppedTypes = new Set();
 const DROPPED_TYPE_MEMO_CAP = 64;
 const DROPPED_TYPE_DISPLAY_CAP = 60;
@@ -477,30 +623,15 @@ async function* runStreamInner(events, ctx, handle = {}) {
             continue;
         }
         if (ev.type === 'done' || ev.type === 'failed') {
-            const doneTerminal = ev.type === 'done' ? readRunTerminal(ev.result) : null;
-            const errText = ev.type === 'failed'
-                ? (ev.errorMessage ?? ev.errorCode ?? 'run failed')
-                : doneTerminal?.kind === 'failed'
-                    ? (doneTerminal.message ?? doneTerminal.code ?? 'run failed')
-                    : doneTerminal?.kind === 'blocked'
-                        ? (doneTerminal.reason
-                            ? `Run blocked: ${doneTerminal.reason}`
-                            : 'Run blocked (the agent reported it cannot proceed)')
-                        : null;
+            const rowFacts = terminalRowFacts(ev);
+            const doneTerminal = rowFacts.doneTerminal;
+            const errText = rowFacts.errText;
             if (errText) {
-                const activeTaskId = (ev.type === 'done' ? ev.result?.activeTaskId : undefined) ??
-                    (ev.type === 'failed' ? ev.activeTaskId : undefined);
-                const busy = classifyActiveRunBusy({
-                    errorCode: ev.type === 'failed' ? ev.errorCode : runTerminalCode(doneTerminal),
-                    activeTaskId,
-                });
+                const busy = rowFacts.busy;
                 const maxTokHint = /max_tokens/i.test(errText)
                     ? '\nyour provider caps max_tokens lower — lower it in /model (press m, or M to type a value)'
                     : '';
-                const governance = isGovernanceTerminal({
-                    status: ev.type === 'failed' ? undefined : doneTerminal?.kind === 'blocked' ? 'blocked' : undefined,
-                    errorCode: ev.type === 'failed' ? ev.errorCode : runTerminalCode(doneTerminal),
-                });
+                const governance = rowFacts.governance;
                 const busyHandle = busy.handle;
                 const rowText = busy.busy
                     ? `This session is locked by an earlier run${busyHandle ? ` (run ${busyHandle})` : ''} that ` +
@@ -516,13 +647,7 @@ async function* runStreamInner(events, ctx, handle = {}) {
                 const sessionUnreadable = ev.type === 'failed'
                     ? isCorruptSessionCode(ev.errorCode)
                     : doneTerminal?.kind === 'failed' && isCorruptSessionCode(doneTerminal.code);
-                const historyMismatch = !busy.busy && !governance && !isModelOutputErrorText(errText)
-                    ? classifyToolHistoryMismatch({
-                        code: ev.type === 'failed' ? ev.errorCode : runTerminalCode(doneTerminal),
-                        status: ev.type === 'done' ? providerFailureStatusOf(ev.result) : undefined,
-                        message: errText,
-                    })
-                    : null;
+                const historyMismatch = classifyToolHistoryMismatch(toolHistoryCarrierOfRowFrame(ev, rowFacts));
                 const historyEchoedSid = ev.type === 'done' ? engineSessionIdOf(ev.result) : undefined;
                 const historyRepeat = noteToolHistoryTerminal({
                     sessionId: historyEchoedSid ?? ctx.sessionId,

package/dist/attachmentsWireCaps.d.ts

@@ -6,7 +6,6 @@ export interface AttachmentsSpec {
     changedFiles?: true | {
         maxFiles?: number;
     };
-    planModeReminder?: true;
     budgetUsd?: true;
     backgroundTasks?: boolean;
     toolsDelta?: true;
@@ -14,6 +13,18 @@ export interface AttachmentsSpec {
     agentListing?: boolean;
     skillsListing?: boolean;
 }
-export declare const ATTACHMENTS_SPEC_KEYS: readonly ["todoReminder", "todoReminderMode", "changedFiles", "planModeReminder", "budgetUsd", "backgroundTasks", "toolsDelta", "mcpInstructions", "agentListing", "skillsListing"];
+export declare const ATTACHMENTS_SPEC_KEYS: readonly ["todoReminder", "todoReminderMode", "changedFiles", "budgetUsd", "backgroundTasks", "toolsDelta", "mcpInstructions", "agentListing", "skillsListing"];
 export declare const ATTACHMENTS_DEFAULT_ON_KEYS: readonly ["agentListing", "skillsListing", "backgroundTasks"];
+export declare class AttachmentsSpecRefused extends TypeError {
+    readonly token: string;
+    readonly why: string;
+    readonly allowed: readonly string[];
+    readonly key?: string;
+    constructor(message: string, init: {
+        readonly token: string;
+        readonly why: string;
+        readonly allowed: readonly string[];
+        readonly key?: string;
+    });
+}
 export declare function attachmentsForRequest(env?: EnvLike): AttachmentsSpec | undefined;

package/dist/attachmentsWireCaps.js

@@ -1,11 +1,11 @@
 import { hostEnv } from './hostEnv.js';
 import { envFlagOff } from './envFlag.js';
+import { retiredAttachmentsKeyWhy } from './taskRequestWords.js';
 export const ATTACHMENTS_ENV = 'SEMA_ATTACHMENTS';
 export const ATTACHMENTS_SPEC_KEYS = Object.freeze([
     'todoReminder',
     'todoReminderMode',
     'changedFiles',
-    'planModeReminder',
     'budgetUsd',
     'backgroundTasks',
     'toolsDelta',
@@ -17,7 +17,6 @@ export const ATTACHMENTS_DEFAULT_ON_KEYS = ['agentListing', 'skillsListing', 'ba
 const OPT_IN_KEYS = [
     'todoReminder',
     'changedFiles',
-    'planModeReminder',
     'budgetUsd',
     'backgroundTasks',
     'toolsDelta',
@@ -28,16 +27,37 @@ const DEFAULT_PAIR = ['backgroundTasks', 'toolsDelta'];
 const _attachmentsKeyPins = [true, true, true, true, true, true];
 void _attachmentsKeyPins;
 const TODO_REMINDER_MODES = ['baseline', 'off'];
+export class AttachmentsSpecRefused extends TypeError {
+    token;
+    why;
+    allowed;
+    constructor(message, init) {
+        super(message);
+        this.name = 'AttachmentsSpecRefused';
+        this.token = init.token;
+        this.why = init.why;
+        this.allowed = Object.freeze([...init.allowed]);
+        if (init.key !== undefined)
+            this.key = init.key;
+    }
+}
+function legalAttachmentsTokens() {
+    return ['off', 'full', 'all', 'default', '<literalTrueKey>', '+<literalTrueKey>', ...DEFAULT_ON_ONLY_KEYS.map(k => `-${k}`), `todoReminderMode=${TODO_REMINDER_MODES.join('|')}`];
+}
 function refuse(token, why) {
-    throw new Error(`${ATTACHMENTS_ENV}: refusing token "${token}" — ${why}. ` +
-        `Legal tokens: off | full | all | default | <literalTrueKey> | +<literalTrueKey> | ` +
-        `-agentListing | -skillsListing | todoReminderMode=baseline|off`);
+    const allowed = legalAttachmentsTokens();
+    throw new AttachmentsSpecRefused(`${ATTACHMENTS_ENV}: refusing token "${token}" — ${why}. Legal tokens: ${allowed.join(' | ')}`, { token, why, allowed });
 }
 export function attachmentsForRequest(env = hostEnv()) {
     const raw = (env[ATTACHMENTS_ENV] ?? '').trim().toLowerCase();
     if (envFlagOff(raw))
         return allDefaultOnOff();
     const tokens = raw.split(',').map(t => t.trim()).filter(t => t.length > 0);
+    for (const token of tokens) {
+        const named = retiredAttachmentsKeyWhy(token);
+        if (named !== undefined)
+            refuse(token, named);
+    }
     if (tokens.length === 0)
         return { backgroundTasks: true, toolsDelta: true };
     if (tokens.length === 1 && (tokens[0] === 'full' || tokens[0] === 'all'))

package/dist/controlRouter.d.ts

@@ -17,7 +17,7 @@ export interface RunsResourceLike {
 export interface ControlClientLike {
     runs: RunsResourceLike;
 }
-export type ControlSafetyCode = 'not_running' | 'invalid_content' | 'queue_full' | 'duplicate_input_id' | 'ambiguous_target' | 'still_running' | 'blocked_by_hook' | 'steering_other' | 'cancel_lost_race' | 'cancel_run_not_running' | 'not_found';
+export type ControlSafetyCode = 'not_running' | 'invalid_content' | 'queue_full' | 'duplicate_input_id' | 'ambiguous_target' | 'still_running' | 'blocked_by_hook' | 'ledger_unavailable' | 'steering_other' | 'cancel_lost_race' | 'cancel_run_not_running' | 'not_found';
 export declare class ControlSafetyError extends Error {
     readonly code: ControlSafetyCode;
     readonly cause?: unknown | undefined;
@@ -71,3 +71,9 @@ export interface ErrCodes {
     status?: number | undefined;
 }
 export declare function errCodes(e: unknown): ErrCodes;
+export declare function steeringStatusIs4xx(e: object): boolean;
+export interface SteeringRefusedBeforeEngine {
+    safety: ControlSafetyCode;
+    advice: string;
+}
+export declare function steeringRefusedBeforeEngine(e: object): SteeringRefusedBeforeEngine | undefined;

package/dist/controlRouter.js

@@ -64,8 +64,9 @@ export class ControlRouter {
         catch (e) {
             const verdict = steeringVerdict(e);
             if (verdict !== undefined) {
+                const safety = steeringSafetyOf(e, verdict);
                 const wireCode = errCodes(e).code ?? errCodes(e).name ?? 'steering.<unknown>';
-                throw new ControlSafetyError(`${wireCode} — ${STEERING_ADVICE.get(verdict) ?? 'steering refused'}`, verdict, e);
+                throw new ControlSafetyError(`${wireCode} — ${steeringAdviceOf(e, safety) ?? 'steering refused'}`, safety, e);
             }
             throw e;
         }
@@ -138,12 +139,14 @@ const STEERING_CODE_TO_SAFETY = new Map([
     ['steering.ambiguous_label', 'ambiguous_target'],
     ['steering.still_running', 'still_running'],
     ['steering.blocked_by_hook', 'blocked_by_hook'],
+    ['steering.ledger_unavailable', 'ledger_unavailable'],
 ]);
 const STEERING_NAME_TO_SAFETY = new Map([
     ['SteeringNotRunningError', 'not_running'],
     ['SteeringInvalidContentError', 'invalid_content'],
     ['SteeringAmbiguousTargetError', 'ambiguous_target'],
     ['SteeringStillRunningError', 'still_running'],
+    ['SteeringLedgerUnavailableError', 'ledger_unavailable'],
     ['SteeringError', 'steering_other'],
 ]);
 const STEERING_ADVICE = new Map([
@@ -154,8 +157,47 @@ const STEERING_ADVICE = new Map([
     ['ambiguous_target', 'more than one live target matches — address it uniquely (sub-agent: parentToolCallId; workflow: a more specific label); retrying verbatim yields the same result'],
     ['still_running', 'the target is STILL RUNNING — steer it instead of resuming, or wait for it to settle (this is the exact opposite of not_running: never collapse the two)'],
     ['blocked_by_hook', "this deployment's userPromptSubmit gate refused the input (block, timeout and crash all report this one code, fail-closed) — the input was NOT accepted: no human_input frame, the inputId is not on the ledger, so editing the text and sending again is a normal retry, not a duplicate"],
+    ['ledger_unavailable', 'the server could not record this steer in its user-input ledger and refused it before anything reached the engine — the input was NOT delivered; resend the same text later (the same Idempotency-Key is fine)'],
     ['steering_other', 'an unrecognized steering.* refusal (open set) — the steer did NOT land; log the errorCode verbatim, do not guess its meaning'],
 ]);
+const STEERING_OTHER_UNKNOWN_ADVICE = 'an unrecognized steering.* refusal (open set) — treat delivery as unknown (do not resend as if it had certainly been dropped); log the errorCode verbatim, do not guess its meaning';
+export function steeringStatusIs4xx(e) {
+    let status;
+    try {
+        status = errCodes(e).status;
+    }
+    catch {
+        return false;
+    }
+    return status !== undefined && status >= 400 && status < 500;
+}
+function steeringAdviceOf(e, safety) {
+    if (safety === 'steering_other' && !(typeof e === 'object' && e !== null && steeringStatusIs4xx(e)))
+        return STEERING_OTHER_UNKNOWN_ADVICE;
+    return STEERING_ADVICE.get(safety);
+}
+const STEERING_REFUSED_BEFORE_ENGINE = new Map([['ledger_unavailable', 503]]);
+export function steeringRefusedBeforeEngine(e) {
+    try {
+        const { status } = errCodes(e);
+        if (status === undefined)
+            return undefined;
+        const safety = steeringVerdict(e);
+        if (safety === undefined || STEERING_REFUSED_BEFORE_ENGINE.get(safety) !== status)
+            return undefined;
+        const advice = STEERING_ADVICE.get(safety);
+        return advice === undefined ? undefined : { safety, advice };
+    }
+    catch {
+        return undefined;
+    }
+}
+function steeringSafetyOf(e, verdict) {
+    if (!STEERING_REFUSED_BEFORE_ENGINE.has(verdict))
+        return verdict;
+    const refused = typeof e === 'object' && e !== null ? steeringRefusedBeforeEngine(e) : undefined;
+    return refused !== undefined && refused.safety === verdict ? verdict : 'steering_other';
+}
 function steeringVerdict(e) {
     const { code, name } = errCodes(e);
     if (typeof code === 'string' && code.startsWith('steering.')) {

package/dist/coreValuePorts.d.ts

@@ -16,6 +16,7 @@ export interface AllowDenyPolicyOptionsView {
     deny?: string[];
     onInvalidName?: 'throw' | 'skip';
     onInvalidNameIssue?: (issue: AllowDenyInvalidNameIssueView) => void;
+    scope?: 'grant' | 'narrowing';
 }
 export interface AllowDenyInvalidNameIssueView {
     entry: string;

package/dist/disableSkillsWire.d.ts

@@ -0,0 +1,17 @@
+export declare function refuseBadDisableSkills(v: unknown, who: string): void;
+export declare function refuseDisableSkillsConflict(disableSkills: unknown, skills: unknown, agents: unknown, who: string): void;
+type DisableSkillsWithheldCause = 'not_reported' | 'unsupported' | 'unprobed' | 'unreadable';
+export type DisableSkillsDeclaration = {
+    readonly field: {
+        readonly disableSkills: true;
+    };
+    readonly withheld?: undefined;
+} | {
+    readonly field: Readonly<Record<string, never>>;
+    readonly withheld?: {
+        readonly cause: DisableSkillsWithheldCause;
+        readonly text: string;
+    };
+};
+export declare function disableSkillsDeclaration(want: unknown, baseUrl: string | undefined): DisableSkillsDeclaration;
+export {};

package/dist/disableSkillsWire.js

@@ -0,0 +1,52 @@
+import { engineCapState } from './engineCapsCache.js';
+const KEY = 'disableSkills';
+const shapeOf = (v) => {
+    try {
+        return v === null ? 'null' : Array.isArray(v) ? 'typeof=object / array' : typeof v === 'string' ? `typeof=string(长 ${v.length})` : `typeof=${typeof v}`;
+    }
+    catch {
+        return `typeof=${typeof v} / unreadable`;
+    }
+};
+export function refuseBadDisableSkills(v, who) {
+    if (v === undefined || v === null || v === true || v === false)
+        return;
+    throw new TypeError(`${who}: disableSkills 只接受布尔或缺席(undefined/null)—— 收到 ${shapeOf(v)}。` +
+        '这一位是「这一发一只技能都不装」的声明:本层若把坏值折成缺席,这一次运行会照常装上技能而声明人不会知道;' +
+        '上游对非布尔值同样拒收。错误文本只报形状,不回显值。');
+}
+const nonEmptyArray = (v) => Array.isArray(v) && v.length > 0;
+const anyAgentCarriesSkills = (agents) => Array.isArray(agents) && agents.some((a) => typeof a === 'object' && a !== null && nonEmptyArray(a.skills));
+export function refuseDisableSkillsConflict(disableSkills, skills, agents, who) {
+    if (disableSkills !== true)
+        return;
+    const inSkills = nonEmptyArray(skills);
+    const inAgents = anyAgentCarriesSkills(agents);
+    if (!inSkills && !inAgents)
+        return;
+    const which = inSkills && inAgents ? 'skills 与 agents[].skills' : inSkills ? 'skills' : 'agents[].skills';
+    throw new TypeError(`${who}: disableSkills: true(这一发一只技能都不装)与非空的 ${which} 同在 —— 二选一:要关技能就别交技能,要交技能就别带 disableSkills。` +
+        '上游对这一组合同样拒收(在任何东西跑起来之前);本层在装配前拒,不让它走一次往返。错误文本只报键名,不回显技能名。');
+}
+const WITHHELD_TEXT = Object.freeze({
+    not_reported: 'Skills were not turned off for this request: the connected engine does not report that it can turn them off, and an engine that does not know this setting rejects the whole request, so the setting was left out and this run keeps its usual skills.',
+    unsupported: 'Skills were not turned off for this request: the connected engine reports that it cannot turn them off, so the setting was left out and this run keeps its usual skills.',
+    unprobed: 'Skills were not turned off for this request: what the connected engine supports has not been read yet, and an engine that does not know this setting rejects the whole request, so the setting was held back and this run keeps its usual skills.',
+    unreadable: 'Skills were not turned off for this request: the connected engine reported whether it can turn them off in a form this version cannot read, so the setting was left out and this run keeps its usual skills.',
+});
+const WITHHELD_CAUSE_OF = {
+    absent: 'not_reported',
+    false: 'unsupported',
+    unprobed: 'unprobed',
+    non_boolean: 'unreadable',
+};
+export function disableSkillsDeclaration(want, baseUrl) {
+    refuseBadDisableSkills(want, 'disableSkillsDeclaration');
+    if (want !== true)
+        return Object.freeze({ field: Object.freeze({}) });
+    const state = engineCapState(baseUrl, KEY);
+    if (state === 'true')
+        return Object.freeze({ field: Object.freeze({ disableSkills: true }) });
+    const cause = WITHHELD_CAUSE_OF[state];
+    return Object.freeze({ field: Object.freeze({}), withheld: Object.freeze({ cause, text: WITHHELD_TEXT[cause] }) });
+}