@sema-agent/client-core 0.87.0 → 0.89.0

package/dist/seatContract.js

@@ -478,6 +478,8 @@ export const TOOL_PERMISSION_REQUEST_KEYS = [
     "mandate",
     "origin",
     "ruleOffersAbsence",
+    "askClass",
+    "classes",
 ];
 export const LOCAL_SESSION_RECORD_KEYS = [
     "sessionId",
@@ -563,6 +565,14 @@ export const SEAT_VALIDATOR_KEY_COVERAGE = {
                 key: "origin",
                 why: "喂姿态谓词 askSurvivesPosture 的安全位(CC-203),按开集读(非空串原文字节、词表不校);权威窄读在卡口与过境口 toolPermissionRequestAskBits,座位门不设第二判官(为一个位拒掉整条 request = 把安全 ask 丢给引擎 TTL deny)。坏形的两种失效方向:非串 / 空串读成缺席 ⇒ 宿主报了没命中时姿态谓词可答可以放(放宽方向:真出身若是必问词就丢了);表外串读成不认识的词 ⇒ 答 unknown,宿主退回自己的规则(不放宽)。不经过境口自铸座位请求的宿主要自己按同一把窄读。",
             },
+            {
+                key: "askClass",
+                why: "展示位(CC-284),权威成对窄读在卡口与过境口 toolPermissionRequestAskBits(与 classes 同在同缺、首员等于 askClass、不判成员、不重排);座位门不设第二判官,理由同 mandated(为一个展示位拒掉整条 request = 把安全 ask 丢给引擎超时拒)。坏形读成缺席 ⇒ 卡上不显示问类,不改决断;缺席不是「普通问」。不经过境口自铸座位请求的宿主要自己按同一把成对窄读。",
+            },
+            {
+                key: "classes",
+                why: "与 askClass 同一对(CC-284),同在同缺、同一只成对窄读(非空、每员非空串、无重复、首员等于 askClass;开集、原样顺序);座位门不设第二判官,理由同 askClass。",
+            },
             {
                 key: "ruleOffersAbsence",
                 why: "喂强制判据口 approvalIsMandated 的位(CC-203;寄存行那条腿的强制只以缺席词 mandated 表达),按开集读(非空串原文字节、词表不校);权威窄读在卡口与过境口,座位门不设第二判官,理由同 mandated。坏形读成缺席 ⇒ 这一路不判强制(放宽方向:寄存行上的强制就丢了;另两路 mandated / mandate 照判);表外串只是不等于 mandated。不经过境口自铸座位请求的宿主要自己按同一把窄读。",

package/dist/sessionMemoryErase.d.ts

@@ -0,0 +1,76 @@
+import type { EngineWireClientConfig } from './engineWireSdk.js';
+import type { MemoryEraseReceiptReading, MemoryEraseUnreadableCause } from './memoryEntriesWire.js';
+export type SessionMemoryEraseWire = Pick<EngineWireClientConfig, 'baseUrl' | 'token' | 'principal' | 'timeoutMs' | 'fetchImpl'>;
+export interface SessionMemoryEraseCall {
+    sessionId: string;
+    requestId: string;
+    allowUnevidenced?: boolean;
+}
+export interface SessionMemoryEraseOptions {
+    signal?: AbortSignal | null;
+}
+export interface SessionMemoryEraseSent {
+    sessionId: string;
+    requestId: string;
+    allowUnevidenced?: boolean;
+}
+export type SessionMemoryEraseNotSentWhy = 'bad_input' | 'no_connection' | 'cancelled';
+export type SessionMemoryEraseJson = null | boolean | number | string | readonly SessionMemoryEraseJson[] | {
+    readonly [key: string]: SessionMemoryEraseJson;
+};
+export type SessionMemoryEraseAnswer = {
+    kind: 'not_sent';
+    why: SessionMemoryEraseNotSentWhy;
+    detail: string;
+} | {
+    kind: 'answered';
+    sent: SessionMemoryEraseSent;
+    status: number;
+    body: SessionMemoryEraseJson | undefined;
+} | {
+    kind: 'no_answer';
+    sent: SessionMemoryEraseSent;
+    detail: string;
+};
+export declare function eraseSessionMemory(call: SessionMemoryEraseCall, wire: SessionMemoryEraseWire, opts?: SessionMemoryEraseOptions): Promise<SessionMemoryEraseAnswer>;
+export type SessionMemoryEraseRefusalReason = 'bad_input' | 'no_connection' | 'cancelled_before_send' | 'credentials_required' | 'not_permitted' | 'memory_engine_absent' | 'session_not_found' | 'route_absent' | 'request_rejected' | 'evidence_unavailable' | 'request_id_reused' | 'store_unreadable';
+export type SessionMemoryEraseUnconfirmedWhy = 'no_answer' | 'receipt_unreadable' | 'receipt_mismatch' | 'store_link_outside' | 'control_plane_corrupt' | 'engine_fault' | 'unclassified' | 'no_code' | 'unreadable';
+export type SessionMemoryEraseRetry = 'not_needed' | 'same_request_id' | 'new_request_id' | 'needs_operator' | 'needs_consent' | 'human_decision' | 'pointless';
+type SessionMemoryEraseReceipt = Extract<MemoryEraseReceiptReading, {
+    kind: 'present';
+}>;
+export type SessionMemoryEraseOutcome = {
+    kind: 'erased';
+    receipt: SessionMemoryEraseReceipt;
+    text: string;
+    retry: 'not_needed';
+    retryText: string;
+} | {
+    kind: 'partial';
+    receipt: SessionMemoryEraseReceipt;
+    text: string;
+    retry: 'same_request_id' | 'human_decision';
+    retryText: string;
+} | {
+    kind: 'refused';
+    reason: SessionMemoryEraseRefusalReason;
+    text: string;
+    retry: SessionMemoryEraseRetry;
+    retryText: string;
+    status?: number;
+    errorCode?: string;
+} | {
+    kind: 'unconfirmed';
+    why: SessionMemoryEraseUnconfirmedWhy;
+    text: string;
+    retry: SessionMemoryEraseRetry;
+    retryText: string;
+    status?: number;
+    errorCode?: string;
+    receiptWhy?: MemoryEraseUnreadableCause;
+};
+export declare const SESSION_MEMORY_ERASE_REFUSAL_REASONS: readonly SessionMemoryEraseRefusalReason[];
+export declare const SESSION_MEMORY_ERASE_UNCONFIRMED_WHYS: readonly SessionMemoryEraseUnconfirmedWhy[];
+export declare const SESSION_MEMORY_ERASE_RETRIES: readonly SessionMemoryEraseRetry[];
+export declare function sessionMemoryEraseOutcome(answer: SessionMemoryEraseAnswer): SessionMemoryEraseOutcome;
+export {};

package/dist/sessionMemoryErase.js

@@ -0,0 +1,432 @@
+import { isLoopbackWireUrl, resolveWireAuth } from './engineWireSdk.js';
+import { INJECTED_WIRE_SETTLE_MS, connectionLostDetail, noAnswerDetailFrom, noAnswerKindOf, provablyNotSent, settleInjected } from './engineWireFor.js';
+import { memoryEraseReplayPosture, readMemoryEraseReceipt } from './memoryEntriesWire.js';
+import { normalizeWirePrincipal } from './principalWire.js';
+const PRINCIPAL_HEADER = 'x-agent-principal';
+const MAX_TIMER_MS = 2_147_483_647;
+const NOT_SENT = ' — nothing was sent';
+const DETAIL_BAD_CALL = `the erase call needs a session id (a non-empty string that is not a dot segment) and a request id (a non-empty string), and allowUnevidenced must be true or false when given${NOT_SENT}`;
+const DETAIL_BAD_OPTIONS = `the options could not be read, or the signal is not an AbortSignal${NOT_SENT}`;
+const DETAIL_BAD_WIRE = `the connection could not be read (it needs a baseUrl string, a known token form, a positive time limit and a fetch function)${NOT_SENT}`;
+const DETAIL_BROWSER = `a connection that carries a token is refused in a browser; use the same-origin relay form${NOT_SENT}`;
+const DETAIL_NO_FETCH = `no fetch function is available${NOT_SENT}`;
+const DETAIL_CANCELLED = `the call was cancelled before the request was sent${NOT_SENT}`;
+const DETAIL_CONNECT_FAILED = `the connection to the engine could not be opened${NOT_SENT}`;
+const DETAIL_ANSWER_UNREADABLE = 'an answer came back but could not be read (the request may still have been received)';
+class AnswerUnreadable extends Error {
+}
+function plainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function nonEmptyString(v) {
+    return typeof v === 'string' && v !== '';
+}
+function notSent(why, detail) {
+    return { kind: 'not_sent', why, detail };
+}
+function tokenFormOf(token, baseUrl) {
+    if (token === undefined)
+        return { kind: 'value', read: () => undefined };
+    if (typeof token === 'string')
+        return { kind: 'value', read: () => token };
+    if (typeof token === 'function') {
+        const fn = token;
+        return {
+            kind: 'value',
+            read: () => {
+                try {
+                    return fn();
+                }
+                catch {
+                    return undefined;
+                }
+            },
+        };
+    }
+    if (plainObject(token)) {
+        let mode;
+        try {
+            mode = token.mode;
+        }
+        catch {
+            return null;
+        }
+        if (mode === 'same-origin-relay')
+            return { kind: 'relay' };
+        if (mode === 'loopback-unauthed' && isLoopbackWireUrl(baseUrl))
+            return { kind: 'unauthed' };
+        return null;
+    }
+    return null;
+}
+function inBrowser() {
+    try {
+        return typeof globalThis.window !== 'undefined';
+    }
+    catch {
+        return false;
+    }
+}
+function outboundHeaders(baseUrl, form, principal) {
+    const h = {};
+    if (form.kind === 'value') {
+        const resolved = resolveWireAuth(baseUrl, form.read());
+        if (typeof resolved === 'string')
+            h.authorization = `Bearer ${resolved}`;
+    }
+    if (principal !== undefined)
+        h[PRINCIPAL_HEADER] = principal;
+    h['content-type'] = 'application/json';
+    return h;
+}
+async function readAnswer(res) {
+    let status;
+    let textOf;
+    try {
+        if (res === null || typeof res !== 'object')
+            throw new AnswerUnreadable();
+        status = res.status;
+        textOf = res.text;
+    }
+    catch {
+        throw new AnswerUnreadable();
+    }
+    if (typeof status !== 'number' || !Number.isInteger(status) || status < 100 || status > 599 || typeof textOf !== 'function')
+        throw new AnswerUnreadable();
+    let text;
+    try {
+        text = await textOf.call(res);
+    }
+    catch (e) {
+        if (e !== null && typeof e === 'object' && noAnswerKindOf(e) !== null)
+            throw e;
+        throw new AnswerUnreadable();
+    }
+    if (typeof text !== 'string')
+        throw new AnswerUnreadable();
+    return { status, text };
+}
+export async function eraseSessionMemory(call, wire, opts) {
+    let sent;
+    let sessionSegment;
+    try {
+        if (!plainObject(call))
+            return notSent('bad_input', DETAIL_BAD_CALL);
+        const sessionId = call.sessionId;
+        const requestId = call.requestId;
+        const allowUnevidenced = Object.hasOwn(call, 'allowUnevidenced') ? call.allowUnevidenced : undefined;
+        if (!nonEmptyString(sessionId) || !nonEmptyString(requestId))
+            return notSent('bad_input', DETAIL_BAD_CALL);
+        if (sessionId === '.' || sessionId === '..')
+            return notSent('bad_input', DETAIL_BAD_CALL);
+        if (allowUnevidenced !== undefined && typeof allowUnevidenced !== 'boolean')
+            return notSent('bad_input', DETAIL_BAD_CALL);
+        sessionSegment = encodeURIComponent(sessionId);
+        sent = { sessionId, requestId, ...(allowUnevidenced !== undefined ? { allowUnevidenced } : {}) };
+    }
+    catch {
+        return notSent('bad_input', DETAIL_BAD_CALL);
+    }
+    let signal;
+    try {
+        if (opts !== undefined && opts !== null && typeof opts !== 'object')
+            return notSent('bad_input', DETAIL_BAD_OPTIONS);
+        const sig = opts?.signal;
+        if (sig !== undefined && sig !== null) {
+            if (typeof sig !== 'object' || typeof sig.addEventListener !== 'function' || typeof sig.aborted !== 'boolean') {
+                return notSent('bad_input', DETAIL_BAD_OPTIONS);
+            }
+            if (typeof AbortSignal.any === 'function' && !(sig instanceof AbortSignal))
+                return notSent('bad_input', DETAIL_BAD_OPTIONS);
+            signal = sig;
+        }
+    }
+    catch {
+        return notSent('bad_input', DETAIL_BAD_OPTIONS);
+    }
+    let baseUrl;
+    let form;
+    let principal;
+    let timeoutMs;
+    let fetchImpl;
+    try {
+        if (!plainObject(wire))
+            return notSent('no_connection', DETAIL_BAD_WIRE);
+        const rawBase = wire.baseUrl;
+        const rawToken = wire.token;
+        const rawPrincipal = wire.principal;
+        const rawTimeout = wire.timeoutMs;
+        const rawFetch = wire.fetchImpl;
+        if (typeof rawBase !== 'string')
+            return notSent('no_connection', DETAIL_BAD_WIRE);
+        const f = tokenFormOf(rawToken, rawBase);
+        if (f === null)
+            return notSent('no_connection', DETAIL_BAD_WIRE);
+        if (rawPrincipal !== undefined && typeof rawPrincipal !== 'string')
+            return notSent('no_connection', DETAIL_BAD_WIRE);
+        if (rawTimeout !== undefined && (typeof rawTimeout !== 'number' || !Number.isFinite(rawTimeout) || rawTimeout <= 0 || rawTimeout > MAX_TIMER_MS)) {
+            return notSent('no_connection', DETAIL_BAD_WIRE);
+        }
+        if (rawFetch !== undefined && typeof rawFetch !== 'function')
+            return notSent('no_connection', DETAIL_BAD_WIRE);
+        if (f.kind !== 'relay' && inBrowser())
+            return notSent('no_connection', DETAIL_BROWSER);
+        const globalFetch = globalThis.fetch;
+        const chosen = rawFetch ?? (typeof globalFetch === 'function' ? globalFetch.bind(globalThis) : undefined);
+        if (typeof chosen !== 'function')
+            return notSent('no_connection', DETAIL_NO_FETCH);
+        baseUrl = rawBase;
+        form = f;
+        principal = normalizeWirePrincipal(rawPrincipal);
+        timeoutMs = rawTimeout ?? INJECTED_WIRE_SETTLE_MS;
+        fetchImpl = chosen;
+    }
+    catch {
+        return notSent('no_connection', DETAIL_BAD_WIRE);
+    }
+    try {
+        if (signal !== undefined && signal.aborted === true)
+            return notSent('cancelled', DETAIL_CANCELLED);
+    }
+    catch {
+        return notSent('bad_input', DETAIL_BAD_OPTIONS);
+    }
+    const url = `${baseUrl.replace(/\/+$/, '')}/v1/sessions/${sessionSegment}/memory/erase`;
+    const payload = JSON.stringify(sent.allowUnevidenced !== undefined ? { requestId: sent.requestId, allowUnevidenced: sent.allowUnevidenced } : { requestId: sent.requestId });
+    const once = (s) => fetchImpl(url, { method: 'POST', headers: outboundHeaders(baseUrl, form, principal), body: payload, signal: s }).then(readAnswer);
+    let got;
+    try {
+        got = await settleInjected(timeoutMs, signal, once);
+    }
+    catch (e) {
+        if (e instanceof AnswerUnreadable)
+            return { kind: 'no_answer', sent, detail: DETAIL_ANSWER_UNREADABLE };
+        const obj = e !== null && typeof e === 'object' ? e : null;
+        if (obj !== null && noAnswerKindOf(obj) !== null)
+            return { kind: 'no_answer', sent, detail: noAnswerDetailFrom(obj) ?? connectionLostDetail() };
+        if (obj !== null && provablyNotSent(obj))
+            return notSent('no_connection', DETAIL_CONNECT_FAILED);
+        return { kind: 'no_answer', sent, detail: connectionLostDetail() };
+    }
+    let body;
+    try {
+        body = got.text === '' ? undefined : JSON.parse(got.text);
+    }
+    catch {
+        body = undefined;
+    }
+    return { kind: 'answered', sent, status: got.status, body };
+}
+const REFUSAL_TEXT = {
+    bad_input: 'Nothing was erased: the erase request could not be built from what was given, so it was not sent.',
+    no_connection: 'Nothing was erased: there is no usable connection to the engine, so the request was not sent.',
+    cancelled_before_send: 'Nothing was erased: the erase was cancelled before the request was sent.',
+    credentials_required: 'Nothing was erased: this deployment does not accept memory erase requests until its operator configures a service credential.',
+    not_permitted: "Nothing was erased: this caller is not permitted to erase this session's memory.",
+    memory_engine_absent: "Nothing was erased: this deployment has no memory store that supports erasing a session's memory.",
+    session_not_found: 'Nothing was erased: the engine does not recognise this session for this caller.',
+    route_absent: "Nothing was erased: this engine version cannot erase a session's memory.",
+    request_rejected: 'Nothing was erased: the engine rejected the erase request as malformed.',
+    evidence_unavailable: "Nothing was erased: this deployment's memory store cannot keep proof of an erase, so the erase was declined.",
+    request_id_reused: 'Nothing was erased: this request id was already used for a different erase.',
+    store_unreadable: 'Nothing was erased: part of the memory store could not be read, so the erase was declined before anything changed; the deployment operator needs to repair the store.',
+};
+const UNCONFIRMED_TEXT = {
+    no_answer: 'Not confirmed: no answer came back from the engine, so the erase may or may not have happened.',
+    receipt_unreadable: 'Not confirmed: the engine answered, but its erase receipt could not be read.',
+    receipt_mismatch: 'Not confirmed: the engine answered with a receipt for a different erase request.',
+    store_link_outside: 'Not confirmed: the memory store contains a link that leads outside it, so the erase stopped before finishing and may have erased part of this memory or none of it; the deployment operator needs to remove the link.',
+    control_plane_corrupt: "Not confirmed: the memory store's own records could not be read cleanly, so the erase may have changed nothing or may already be committed; the deployment operator needs to repair them.",
+    engine_fault: 'Not confirmed: the engine reported an internal failure during the erase, so it may or may not have happened.',
+    unclassified: 'Not confirmed: the engine refused in a way this client does not recognise.',
+    no_code: 'Not confirmed: an answer came back without the engine error code, so it may not have come from the engine at all.',
+    unreadable: 'Not confirmed: the result of this erase could not be read.',
+};
+const ERASED_TEXT = 'Erased: every memory entry recorded as coming from this session was erased or was already gone.';
+const PARTIAL_TEXT = 'Partly erased: some memory entries from this session were not erased yet.';
+const RETRY_TEXT = {
+    not_needed: 'Nothing more to do.',
+    same_request_id: 'It is safe to try again with the same request id.',
+    new_request_id: "To erase this session's memory, try again with a new request id.",
+    needs_operator: 'Ask the deployment operator to fix this first, then try again with the same request id.',
+    needs_consent: 'It can only go ahead if someone explicitly agrees to erase without keeping proof.',
+    human_decision: 'Trying again may erase a second time, so a person should decide whether to retry.',
+    pointless: 'Trying again as it is will not help.',
+};
+const REFUSAL_RETRY = {
+    bad_input: 'pointless',
+    no_connection: 'same_request_id',
+    cancelled_before_send: 'same_request_id',
+    credentials_required: 'needs_operator',
+    not_permitted: 'pointless',
+    memory_engine_absent: 'pointless',
+    session_not_found: 'pointless',
+    route_absent: 'pointless',
+    request_rejected: 'pointless',
+    evidence_unavailable: 'needs_consent',
+    request_id_reused: 'new_request_id',
+    store_unreadable: 'needs_operator',
+};
+export const SESSION_MEMORY_ERASE_REFUSAL_REASONS = Object.freeze(Object.keys(REFUSAL_TEXT));
+export const SESSION_MEMORY_ERASE_UNCONFIRMED_WHYS = Object.freeze(Object.keys(UNCONFIRMED_TEXT));
+export const SESSION_MEMORY_ERASE_RETRIES = Object.freeze(Object.keys(RETRY_TEXT));
+const MAX_DIAG_CODE = 200;
+function refusedBy(reason, diag) {
+    const retry = REFUSAL_RETRY[reason];
+    return { kind: 'refused', reason, text: REFUSAL_TEXT[reason], retry, retryText: RETRY_TEXT[retry], ...diag };
+}
+function unconfirmedRetry(why, allowUnevidenced) {
+    if (allowUnevidenced === true)
+        return 'human_decision';
+    switch (why) {
+        case 'store_link_outside':
+        case 'control_plane_corrupt':
+            return 'needs_operator';
+        case 'receipt_mismatch':
+        case 'unreadable':
+            return 'human_decision';
+        case 'no_answer':
+        case 'receipt_unreadable':
+        case 'engine_fault':
+        case 'unclassified':
+        case 'no_code':
+            return 'same_request_id';
+        default: {
+            const unreachable = why;
+            return unreachable;
+        }
+    }
+}
+function unconfirmedBy(why, allowUnevidenced, diag) {
+    const retry = unconfirmedRetry(why, allowUnevidenced);
+    return { kind: 'unconfirmed', why, text: UNCONFIRMED_TEXT[why], retry, retryText: RETRY_TEXT[retry], ...diag };
+}
+function bandOfCode(code) {
+    switch (code) {
+        case 'auth.service_token_required':
+            return { refused: 'credentials_required' };
+        case 'principal_unverified':
+            return { refused: 'not_permitted' };
+        case 'capability.memory_engine_required':
+            return { refused: 'memory_engine_absent' };
+        case 'not_found.session':
+            return { refused: 'session_not_found' };
+        case 'not_found.route':
+            return { refused: 'route_absent' };
+        case 'request.path_malformed':
+        case 'request.body_shape':
+        case 'request.request_id_required':
+        case 'request.field_invalid':
+        case 'config.memory_erasure_request':
+            return { refused: 'request_rejected' };
+        case 'memory.erasure_evidence_unavailable':
+            return { refused: 'evidence_unavailable' };
+        case 'memory.erasure_selector_mismatch':
+            return { refused: 'request_id_reused' };
+        case 'memory.erasure_census_incomplete':
+            return { refused: 'store_unreadable' };
+        case 'memory.target_outside_store':
+            return { unconfirmed: 'store_link_outside' };
+        case 'internal.memory_control_plane_corrupt':
+            return { unconfirmed: 'control_plane_corrupt' };
+        case 'internal.error':
+            return { unconfirmed: 'engine_fault' };
+        default:
+            return code.startsWith('auth.') ? { refused: 'not_permitted' } : undefined;
+    }
+}
+function selectEchoMatches(body, sessionId) {
+    try {
+        if (!plainObject(body) || !Object.hasOwn(body, 'select'))
+            return true;
+        const sel = body.select;
+        if (!plainObject(sel) || !Object.hasOwn(sel, 'sessionId'))
+            return false;
+        return sel.sessionId === sessionId;
+    }
+    catch {
+        return false;
+    }
+}
+export function sessionMemoryEraseOutcome(answer) {
+    let kind;
+    let why;
+    let sessionId;
+    let requestId;
+    let allowUnevidenced;
+    let status;
+    let body;
+    const a = answer;
+    try {
+        if (!plainObject(a))
+            return unconfirmedBy('unreadable', undefined, {});
+        kind = a.kind;
+        if (kind === 'not_sent') {
+            why = a.why;
+        }
+        else if (kind === 'answered' || kind === 'no_answer') {
+            const sent = a.sent;
+            if (!plainObject(sent))
+                return unconfirmedBy('unreadable', undefined, {});
+            sessionId = sent.sessionId;
+            requestId = sent.requestId;
+            allowUnevidenced = Object.hasOwn(sent, 'allowUnevidenced') ? sent.allowUnevidenced : undefined;
+            if (kind === 'answered') {
+                status = a.status;
+                body = a.body;
+            }
+        }
+    }
+    catch {
+        return unconfirmedBy('unreadable', undefined, {});
+    }
+    if (kind === 'not_sent') {
+        if (why === 'bad_input')
+            return refusedBy('bad_input', {});
+        if (why === 'no_connection')
+            return refusedBy('no_connection', {});
+        if (why === 'cancelled')
+            return refusedBy('cancelled_before_send', {});
+        return unconfirmedBy('unreadable', undefined, {});
+    }
+    if (kind !== 'answered' && kind !== 'no_answer')
+        return unconfirmedBy('unreadable', undefined, {});
+    if (!nonEmptyString(sessionId) || !nonEmptyString(requestId) || (allowUnevidenced !== undefined && typeof allowUnevidenced !== 'boolean')) {
+        return unconfirmedBy('unreadable', undefined, {});
+    }
+    const signed = allowUnevidenced;
+    if (kind === 'no_answer')
+        return unconfirmedBy('no_answer', signed, {});
+    if (typeof status !== 'number' || !Number.isInteger(status) || status < 100 || status > 599)
+        return unconfirmedBy('unreadable', undefined, {});
+    if (status >= 200 && status < 300) {
+        const reading = readMemoryEraseReceipt(body);
+        if (reading.kind !== 'present')
+            return unconfirmedBy('receipt_unreadable', signed, { status, receiptWhy: reading.why });
+        if (reading.requestId !== requestId || !selectEchoMatches(body, sessionId))
+            return unconfirmedBy('receipt_mismatch', signed, { status });
+        if (reading.status === 'complete') {
+            return { kind: 'erased', receipt: reading, text: ERASED_TEXT, retry: 'not_needed', retryText: RETRY_TEXT.not_needed };
+        }
+        const retry = memoryEraseReplayPosture(reading) === 'idempotent' ? 'same_request_id' : 'human_decision';
+        return { kind: 'partial', receipt: reading, text: PARTIAL_TEXT, retry, retryText: RETRY_TEXT[retry] };
+    }
+    if (status < 400)
+        return unconfirmedBy('unclassified', signed, { status });
+    let rawCode;
+    try {
+        rawCode = plainObject(body) && Object.hasOwn(body, 'errorCode') ? body.errorCode : undefined;
+    }
+    catch {
+        return unconfirmedBy('unreadable', undefined, {});
+    }
+    if (!nonEmptyString(rawCode))
+        return unconfirmedBy('no_code', signed, { status });
+    const diag = { status, ...(rawCode.length <= MAX_DIAG_CODE ? { errorCode: rawCode } : {}) };
+    const band = bandOfCode(rawCode);
+    if (band !== undefined && 'refused' in band)
+        return refusedBy(band.refused, diag);
+    if (band !== undefined)
+        return unconfirmedBy(band.unconfirmed, signed, diag);
+    return unconfirmedBy(status >= 500 ? 'engine_fault' : 'unclassified', signed, diag);
+}

package/dist/subagent/engineSubagentResume.js

@@ -1,5 +1,6 @@
 import { hostLog } from '../host.js';
 import { resumeRetryLaterFromError } from '../wireErrorTriage.js';
+import { RESUME_SESSION_NOT_FOUND } from '../engineErrorCodes.js';
 import { displayUntrusted } from '../displayUntrusted.js';
 import { engineCapTrue } from '../engineCapsCache.js';
 import { clientHasVerbs, engineWireFor, INJECTED_WIRE_SETTLE_MS, noAnswerDetailFrom, sendOnce, settleInjected } from '../engineWireFor.js';
@@ -21,7 +22,7 @@ export function resolveSubagentContinueTarget(rowId, displayName) {
 const RETENTION_LAPSED_CODES = new Set([
     'resume.evicted',
     'resume.cap',
-    'resume.session_not_found',
+    RESUME_SESSION_NOT_FOUND,
 ]);
 function shapeOf(e) {
     const o = (e ?? {});

package/dist/subagent/engineSubagentSteer.d.ts

@@ -4,10 +4,17 @@ export type SubagentSteerWireClient = {
     runs: Pick<AgentClient['runs'], 'steerSubagent'>;
 };
 export type SubagentSteerWire = EngineWireInjection<SubagentSteerWireClient>;
+export interface SubagentSteerNotDelivered {
+    ok: false;
+    reason: 'not-delivered';
+    safety: 'ledger_unavailable';
+    detail: string;
+}
 export type SubagentSteerOutcome = {
     ok: true;
     receipt: string;
-} | {
+    messageId?: string;
+} | SubagentSteerNotDelivered | {
     ok: false;
     reason: 'no-wire' | 'no-run' | 'not-running' | 'error';
     detail?: string;

package/dist/subagent/engineSubagentSteer.js

@@ -3,9 +3,21 @@ import { clientHasVerbs, engineWireFor, INJECTED_WIRE_SETTLE_MS, noAnswerDetailF
 import { engineSessionParamFor } from '../engineSessionParam.js';
 import { resolveOwnerContext, resolveOwnerRunId } from './engineSubagentResume.js';
 import { noteBgOwnerAbsence } from './subagentOwnerAbsence.js';
+import { errCodes, steeringRefusedBeforeEngine } from '../controlRouter.js';
 function usableSteerClient(client) {
     return clientHasVerbs(client, [['runs', 'steerSubagent']]);
 }
+function steerReceiptMessageId(body) {
+    try {
+        if (typeof body !== 'object' || body === null || !Object.hasOwn(body, 'messageId'))
+            return undefined;
+        const v = body.messageId;
+        return typeof v === 'string' && v.length > 0 ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function steerEngineSubagent(target, text, childTaskId, opts) {
     const named = typeof childTaskId === 'string' && childTaskId !== '' ? childTaskId : undefined;
     const { record: owner, key } = resolveOwnerContext(named);
@@ -36,13 +48,24 @@ export async function steerEngineSubagent(target, text, childTaskId, opts) {
         const copy = body?.note ?? body?.message;
         if (typeof copy === 'string' && copy.length > 0)
             receipt = copy;
-        return { ok: true, receipt };
+        const messageId = steerReceiptMessageId(body);
+        return messageId === undefined ? { ok: true, receipt } : { ok: true, receipt, messageId };
     }
     catch (e) {
-        const status = e?.status;
-        if (typeof status === 'number') {
+        let status;
+        try {
+            status = errCodes(e).status;
+        }
+        catch {
+            status = undefined;
+        }
+        if (status !== undefined) {
             const detail = e instanceof Error ? e.message : String(e);
             hostLog('debug', `engineSubagentSteer: ${status} ${detail.slice(0, 200)}`);
+            const refused = typeof e === 'object' && e !== null ? steeringRefusedBeforeEngine(e) : undefined;
+            if (refused !== undefined && refused.safety === 'ledger_unavailable') {
+                return { ok: false, reason: 'not-delivered', safety: refused.safety, detail: refused.advice };
+            }
             if (status === 409 || status === 404) {
                 return { ok: false, reason: 'not-running', detail };
             }