@sema-agent/client-core 0.99.0 → 0.101.0

package/dist/hitl/decisionSend.js

@@ -0,0 +1,563 @@
+import { settleWithinDeadline } from '../abortableSleep.js';
+import { hostLog } from '../host.js';
+import { msg, renderMessage } from '../i18n/translate.js';
+import { askGoneFromError } from '../decideReceipt.js';
+import { appendOwnElement, guardedRead, readOwnDataNonEmptyString, readOwnDataValue } from '../ownKey.js';
+import { effectiveCodeOf, ownReadingSlot } from '../engineWireFor.js';
+import { ASK_DECISION_LANE_DISABLED, ASK_GONE, ASK_GONE_PARKED, ASK_IDEMPOTENCY_CONFLICT, ASK_NOT_FOUND, ASK_PARKING_RETRY } from '../engineErrorCodes.js';
+import { isSlotCarrier, readErrorNumber, readErrorString, readThrownSlot } from '../wireFailureShape.js';
+import { readDecisionNoteAudit } from './approvalDecisionNoteAudit.js';
+import { carrierReadOf, deliverWithAttributionLadder, isLocalSafetyStop } from './attributionLadder.js';
+import { budgetSpent, deliverApprovalDecision, deliveryTiming, isAborted, newSendTally, PARKING_WAIT_CAP_MS, setDeliveryTimingForTests, sleepFor, settledTransportReadingOf, withTransportRetry, deliveryReadingOf, } from './approvalDelivery.js';
+import { ASK_DECIDED_CODE, classifyDeliveredDecisionRefusal, decisionRefusalClosesOut, notPendingAfterRetry } from './decisionRefusal.js';
+import { addDecisionOpKeys, closeDecisionOp, decisionLedgerKeysOf, decisionOpsWithKey, openDecisionOp } from './decisionLedger.js';
+import { hostHoldIsActive, takeHostHoldLedgerOp, tryHoldApprovalNow } from './approvalHolds.js';
+import { answerPayloadFor, decisionAttributionKeyOf, isToolApprovalRespondReplayed, readApprovalDenySettledBy, readToolApprovalRespondAck, readToolApprovalRespondParking, } from './toolApprovalWire.js';
+export const HITL_DECISION_FAMILIES = Object.freeze(['approval', 'ask', 'elicitation']);
+export const HITL_DECISION_NOT_APPLIED_CAUSES = Object.freeze(['gone', 'parked', 'parking', 'lane_disabled', 'refused', 'idempotency_crossed']);
+export const HITL_DECISION_UNCONFIRMED_CAUSES = Object.freeze(['transport', 'server_error', 'local_error', 'aborted', 'gone_after_retry']);
+export const HITL_DECISION_NOT_SENT_CAUSES = Object.freeze(['aborted', 'duplicate_in_flight', 'invalid_request', 'no_verb', 'not_an_answer']);
+const PARKING_POLL_MAX = 2;
+const PARKING_POLL_DELAY_MS = 400;
+export const HITL_DECISION_READBACK_BUDGET_MS = 4_000;
+const IDEMPOTENCY_KEY_MAX = 255;
+export function __setHitlDecisionSendTimingForTests(t) {
+    setDeliveryTimingForTests(t);
+}
+export function hitlAskIdempotencyKey(askId, verdict) {
+    const key = `sema-ask:${askId}:${verdict}`;
+    return key.length <= IDEMPOTENCY_KEY_MAX ? key : key.slice(0, IDEMPOTENCY_KEY_MAX);
+}
+function retryAfterMsOf(e) {
+    if (!isSlotCarrier(e))
+        return undefined;
+    const ms = readErrorNumber(e, 'retryAfterMs');
+    if (ms !== undefined && Number.isFinite(ms) && ms >= 0)
+        return ms;
+    const sec = readErrorNumber(e, 'retryAfterSec');
+    return sec !== undefined && Number.isFinite(sec) && sec >= 0 ? sec * 1000 : undefined;
+}
+function actorLabelOf(e) {
+    const actor = readThrownSlot(e, 'actor', 'data');
+    if (typeof actor !== 'object' || actor === null)
+        return undefined;
+    const label = guardedRead(() => readOwnDataNonEmptyString(actor, 'label'));
+    if (label !== undefined)
+        return label;
+    const id = guardedRead(() => readOwnDataNonEmptyString(actor, 'id'));
+    return id !== undefined && id !== '_' ? id : undefined;
+}
+function verdictOf(word) {
+    return word === 'approve' || word === 'allow' || word === 'allow_session' ? 'approve' : word === 'deny' ? 'deny' : undefined;
+}
+function outcomeOfThrown(e, family, ours, signal, tally, noteCapable, reading = settledTransportReadingOf(e, signal, tally)) {
+    const base = { family, attempts: tally.attempts };
+    const cls = reading.cls;
+    if (cls === 'aborted')
+        return { ...base, kind: 'unconfirmed', cause: 'aborted' };
+    if (cls === 'transport')
+        return { ...base, kind: 'unconfirmed', cause: 'transport' };
+    if (cls === 'local_error')
+        return { ...base, kind: 'unconfirmed', cause: 'local_error' };
+    const answered = ownReadingSlot(reading, 'answered');
+    if (answered === undefined)
+        return { ...base, kind: 'unconfirmed', cause: 'local_error' };
+    return answeredOutcome(answered.layer, answered.status, reading, cls, family, ours, tally, noteCapable, base);
+}
+function answeredOutcome(e, status, reading, cls, family, ours, tally, noteCapable, base) {
+    const obj = e;
+    if (cls === 'server_5xx')
+        return { ...base, kind: 'unconfirmed', cause: 'server_error', status };
+    const answeredCapture = ownReadingSlot(reading, 'answered');
+    const code = answeredCapture !== undefined ? effectiveCodeOf(answeredCapture.code) : undefined;
+    const at = { ...base, status, ...(code !== undefined ? { errorCode: code } : {}) };
+    const retried = family !== 'ask' && tally.retried;
+    if (retried && notPendingAfterRetry(status, true))
+        return { ...base, kind: 'unconfirmed', cause: 'gone_after_retry', status };
+    if (isSafetyStopLayer(e, reading))
+        return { ...at, kind: 'not_applied', cause: 'refused', ...refusalOf(e, reading) };
+    if (family === 'ask') {
+        switch (code) {
+            case ASK_DECIDED_CODE: {
+                const first = verdictOf(readErrorString(obj, 'firstDecision'));
+                const decidedAtMs = readErrorNumber(obj, 'decidedAtMs');
+                const actorLabel = actorLabelOf(obj);
+                const note = readErrorString(obj, 'decisionNote');
+                return {
+                    ...base,
+                    kind: 'settled_elsewhere',
+                    ...(first !== undefined ? { firstDecision: first } : {}),
+                    ...(first !== undefined && ours !== undefined && first !== ours ? { contrary: true } : {}),
+                    ...(decidedAtMs !== undefined ? { decidedAtMs } : {}),
+                    ...(actorLabel !== undefined ? { actorLabel } : {}),
+                    ...(noteCapable && note !== undefined ? { noteAudit: readDecisionNoteAudit({ decisionNote: note }) } : {}),
+                };
+            }
+            case ASK_IDEMPOTENCY_CONFLICT:
+                return { ...at, kind: 'not_applied', cause: 'idempotency_crossed', ...refusalOf(e, reading) };
+            case ASK_GONE_PARKED: {
+                const sessionId = readErrorString(obj, 'sessionId');
+                return { ...at, kind: 'not_applied', cause: 'parked', ...(sessionId !== undefined ? { sessionId } : {}) };
+            }
+            case ASK_GONE: {
+                const gone = askGoneFromError(e);
+                return { ...at, kind: 'not_applied', cause: 'gone', ...(gone !== null ? { gone } : {}) };
+            }
+            case ASK_PARKING_RETRY: {
+                const retryAfterMs = retryAfterMsOf(e);
+                return { ...at, kind: 'not_applied', cause: 'parking', ...(retryAfterMs !== undefined ? { retryAfterMs } : {}) };
+            }
+            case ASK_DECISION_LANE_DISABLED:
+                return { ...at, kind: 'not_applied', cause: 'lane_disabled' };
+            case ASK_NOT_FOUND:
+                return { ...at, kind: 'not_applied', cause: 'gone' };
+            default:
+                break;
+        }
+    }
+    if (status === 404 || status === 410)
+        return { ...at, kind: 'not_applied', cause: 'gone' };
+    if (status === 501)
+        return { ...at, kind: 'not_applied', cause: 'lane_disabled' };
+    return { ...at, kind: 'not_applied', cause: 'refused', ...refusalOf(e, reading) };
+}
+function isSafetyStopLayer(layer, reading) {
+    return isLocalSafetyStop(carrierReadOf(layer, reading), reading);
+}
+function refusalOf(e, reading) {
+    const r = classifyDeliveredDecisionRefusal(e, reading);
+    return r !== undefined ? { refusal: r } : {};
+}
+async function sendApprovalFamily(respond, approvalId, answer, ctx) {
+    const payload = answerPayloadFor(answer, 'respond', { approvalDecisionNoteCapable: ctx.noteCapable });
+    if (payload === undefined)
+        return { family: 'approval', attempts: ctx.tally.attempts, kind: 'not_sent', cause: 'not_an_answer' };
+    const attribution = answer.kind === 'deny' ? decisionAttributionKeyOf(ctx.decidedBy, readApprovalDenySettledBy(answer)) : {};
+    const body = { ...payload, ...attribution };
+    const ladder = { lastCarried: false, dropped: false, renamed: false };
+    const ours = verdictOf(payload.decision);
+    const extras = bodyFacts(answer, payload, false);
+    const delivery = await deliverApprovalDecision({
+        approvalId,
+        body,
+        send: (b, signal) => respond(approvalId, b, signal !== undefined ? { signal } : undefined),
+        signal: ctx.signal,
+        tally: ctx.tally,
+        ladder,
+        parkingOf: (raw) => {
+            const p = readToolApprovalRespondParking(raw);
+            return p?.kind === 'parking' ? p.view : undefined;
+        },
+    });
+    const retriedFact = ownReadingSlot(delivery, 'parkingRetried') === true ? { parkingRetried: true } : {};
+    if (delivery.kind === 'thrown')
+        return { ...outcomeOfThrown(delivery.error, 'approval', ours, ctx.signal, ctx.tally, ctx.noteCapable), ...extras, ...retriedFact };
+    const raw = delivery.raw;
+    const facts = { ...extras, ...retriedFact, ...(ladder.dropped ? { attributionDropped: true } : {}), ...(ladder.renamed ? { attributionRenamed: true } : {}) };
+    const base = { family: 'approval', attempts: ctx.tally.attempts, ...facts };
+    const parking = readToolApprovalRespondParking(raw);
+    if (parking !== undefined) {
+        const view = parking.kind === 'parking' && parking.view.approvalId === approvalId ? parking.view : undefined;
+        const hint = view !== undefined ? ownReadingSlot(view, 'retryAfterMs') : undefined;
+        return { ...base, kind: 'not_applied', cause: 'parking', ...(view !== undefined ? { parking: view, ...(hint !== undefined ? { retryAfterMs: hint } : {}) } : {}) };
+    }
+    const parsed = readToolApprovalRespondAck(raw);
+    if (parsed !== undefined && isToolApprovalRespondReplayed(parsed)) {
+        const first = parsed.approvalId === approvalId ? verdictOf(parsed.decision) : undefined;
+        return {
+            ...base,
+            kind: 'settled_elsewhere',
+            ...(first !== undefined ? { firstDecision: first } : {}),
+            ...(first !== undefined && ours !== undefined && first !== ours ? { contrary: true } : {}),
+        };
+    }
+    if (ownTrue(raw, 'idempotent'))
+        return { ...base, kind: 'settled_elsewhere' };
+    const ack = parsed !== undefined && parsed.approvalId === approvalId ? parsed : undefined;
+    return { ...base, kind: 'applied', ...(ack !== undefined ? { ack } : {}), ...(ctx.noteCapable ? { noteAudit: readDecisionNoteAudit(raw) } : {}) };
+}
+function bodyFacts(answer, payload, rememberUnsupported) {
+    const reason = answer.kind === 'deny' && typeof answer.reason === 'string' ? answer.reason : undefined;
+    return {
+        ...(reason !== undefined && reason.trim() !== '' && payload.note === undefined ? { noteDropped: true } : {}),
+        ...(rememberUnsupported && answer.kind === 'allow' && answer.allowSession === true ? { rememberDropped: true } : {}),
+    };
+}
+function ownTrue(raw, key) {
+    return typeof raw === 'object' && raw !== null && guardedRead(() => readOwnDataValue(raw, key)) === true;
+}
+async function sendAskFamily(respondForFallback, decideAsk, req, ctx) {
+    const payload = answerPayloadFor(req.answer, 'respond', { approvalDecisionNoteCapable: ctx.noteCapable });
+    if (payload === undefined)
+        return { family: 'ask', attempts: ctx.tally.attempts, kind: 'not_sent', cause: 'not_an_answer' };
+    const verdict = verdictOf(payload.decision) ?? 'deny';
+    const attribution = req.answer.kind === 'deny' ? decisionAttributionKeyOf(ctx.decidedBy, readApprovalDenySettledBy(req.answer)) : {};
+    const body = {
+        decision: verdict,
+        idempotencyKey: hitlAskIdempotencyKey(req.askId, verdict),
+        ...(verdict === 'approve' && payload.updatedInput !== undefined ? { updatedInput: payload.updatedInput } : {}),
+        ...(payload.note !== undefined ? { note: payload.note } : {}),
+        ...attribution,
+    };
+    const extras = bodyFacts(req.answer, payload, true);
+    const ladder = { lastCarried: false, dropped: false, renamed: false };
+    let current = body;
+    const parkingDelay = deliveryTiming().parkingDelayMs ?? PARKING_POLL_DELAY_MS;
+    for (let poll = 0;; poll++) {
+        try {
+            const raw = await deliverWithAttributionLadder(current, (b) => {
+                current = b;
+                return withTransportRetry((signal) => decideAsk(req.taskId, req.askId, b, signal !== undefined ? { signal } : undefined), ctx.signal, ctx.tally);
+            }, ctx.signal, ladder, undefined, { kind: 'delivered', readingOf: (thrown) => deliveryReadingOf(thrown, ctx.tally) });
+            return {
+                family: 'ask',
+                attempts: ctx.tally.attempts,
+                ...extras,
+                ...(ladder.dropped ? { attributionDropped: true } : {}),
+                ...(ladder.renamed ? { attributionRenamed: true } : {}),
+                kind: 'applied',
+                ...(ctx.noteCapable ? { noteAudit: readDecisionNoteAudit(raw) } : {}),
+            };
+        }
+        catch (e) {
+            const settled = settledTransportReadingOf(e, ctx.signal, ctx.tally);
+            const settledAnswer = ownReadingSlot(settled, 'answered');
+            const code = settledAnswer !== undefined ? effectiveCodeOf(settledAnswer.code) : undefined;
+            const wait = Math.max(parkingDelay * (poll + 1), retryAfterMsOf(settledAnswer?.layer ?? e) ?? 0);
+            const safetyStop = settledAnswer !== undefined && isSafetyStopLayer(settledAnswer.layer, settled);
+            if (code === ASK_PARKING_RETRY && !safetyStop && poll < PARKING_POLL_MAX && !isAborted(ctx.signal) && wait <= PARKING_WAIT_CAP_MS && !budgetSpent(ctx.tally, wait)) {
+                await sleepFor(wait, ctx.signal);
+                if (!isAborted(ctx.signal))
+                    continue;
+            }
+            const out = outcomeOfThrown(e, 'ask', verdict, ctx.signal, ctx.tally, ctx.noteCapable, settled);
+            if (out.kind === 'not_applied' && out.cause === 'lane_disabled' && code === ASK_DECISION_LANE_DISABLED && req.approvalId !== undefined) {
+                if (respondForFallback !== undefined && ctx.signal?.aborted !== true) {
+                    const fb = await sendApprovalFamily(respondForFallback, req.approvalId, req.answer, ctx);
+                    return { ...fb, family: 'ask', fallback: 'approval' };
+                }
+            }
+            return { ...out, ...extras };
+        }
+    }
+}
+function validElicitResponse(r) {
+    if (typeof r !== 'object' || r === null)
+        return undefined;
+    const action = guardedRead(() => readOwnDataValue(r, 'action'));
+    if (action !== 'accept' && action !== 'decline' && action !== 'cancel')
+        return undefined;
+    const content = guardedRead(() => readOwnDataValue(r, 'content'));
+    if (content === undefined)
+        return Object.freeze({ action });
+    if (action !== 'accept' || typeof content !== 'object' || content === null || Array.isArray(content))
+        return undefined;
+    const out = {};
+    try {
+        for (const k of Object.keys(content)) {
+            const v = readOwnDataValue(content, k);
+            if (typeof v === 'string' || typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v)))
+                Object.defineProperty(out, k, { value: v, enumerable: true, writable: true, configurable: true });
+            else if (Array.isArray(v)) {
+                const copy = [];
+                for (let i = 0; i < v.length; i++) {
+                    const x = readOwnDataValue(v, String(i));
+                    if (typeof x !== 'string')
+                        return undefined;
+                    appendOwnElement(copy, x);
+                }
+                Object.defineProperty(out, k, { value: copy, enumerable: true, writable: true, configurable: true });
+            }
+            else
+                return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return Object.freeze({ action, content: out });
+}
+function verbOf(holder, name) {
+    if (typeof holder !== 'object' || holder === null)
+        return undefined;
+    try {
+        const fn = holder[name];
+        if (typeof fn !== 'function')
+            return undefined;
+        const bound = (...args) => {
+            try {
+                return Promise.resolve(fn.apply(holder, args));
+            }
+            catch (e) {
+                return Promise.reject(e);
+            }
+        };
+        return bound;
+    }
+    catch {
+        return undefined;
+    }
+}
+function signalOf(v) {
+    try {
+        return v instanceof AbortSignal ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function holdOf(v) {
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    try {
+        const h = v;
+        return typeof h.sending === 'function' && typeof h.release === 'function' ? h : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function holdFits(handle, req) {
+    try {
+        const id = handle.identity;
+        if (typeof id.approvalId === 'string' && id.approvalId !== '')
+            return id.approvalId === req.approvalId;
+        if (typeof id.toolCallId !== 'string' || id.toolCallId === '' || id.toolCallId !== req.toolCallId)
+            return false;
+        return typeof id.taskId !== 'string' || id.taskId === '' || id.taskId === req.taskId;
+    }
+    catch {
+        return false;
+    }
+}
+function callHold(call) {
+    try {
+        call();
+    }
+    catch (e) {
+        hostLog('debug', `decisionSend.callHold: ${String(e).slice(0, 120)}`);
+    }
+}
+function hostField(holder, key) {
+    if (typeof holder !== 'object' || holder === null)
+        return undefined;
+    try {
+        return holder[key];
+    }
+    catch {
+        return undefined;
+    }
+}
+function snapshotAnswer(raw) {
+    const kind = guardedRead(() => readOwnDataValue(raw, 'kind'));
+    if (kind === 'allow') {
+        const allowSession = guardedRead(() => readOwnDataValue(raw, 'allowSession')) === true;
+        const edited = guardedRead(() => readOwnDataValue(raw, 'updatedInput'));
+        if (edited === undefined)
+            return Object.freeze({ kind: 'allow', allowSession });
+        let copy;
+        try {
+            const text = JSON.stringify(edited);
+            if (typeof text !== 'string')
+                return undefined;
+            copy = JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        }
+        return Object.freeze({ kind: 'allow', allowSession, updatedInput: copy });
+    }
+    if (kind === 'deny') {
+        const reason = guardedRead(() => readOwnDataValue(raw, 'reason'));
+        const settledBy = readApprovalDenySettledBy(raw);
+        return Object.freeze({ kind: 'deny', ...(typeof reason === 'string' ? { reason } : {}), ...(settledBy !== undefined ? { settledBy } : {}) });
+    }
+    return typeof kind === 'string' ? Object.freeze({ kind }) : undefined;
+}
+function readRequest(req) {
+    if (typeof req !== 'object' || req === null)
+        return undefined;
+    const s = (k) => guardedRead(() => readOwnDataNonEmptyString(req, k));
+    const family = s('family');
+    if (family === 'elicitation') {
+        const elicitationId = s('elicitationId');
+        const response = validElicitResponse(guardedRead(() => readOwnDataValue(req, 'response')));
+        return elicitationId !== undefined && response !== undefined ? { family, elicitationId, taskId: s('taskId'), response } : undefined;
+    }
+    const rawAnswer = guardedRead(() => readOwnDataValue(req, 'answer'));
+    if (typeof rawAnswer !== 'object' || rawAnswer === null)
+        return undefined;
+    const answer = snapshotAnswer(rawAnswer);
+    if (answer === undefined)
+        return undefined;
+    if (family === 'approval') {
+        const approvalId = s('approvalId');
+        return approvalId !== undefined ? { family, approvalId, taskId: s('taskId'), toolCallId: s('toolCallId'), answer } : undefined;
+    }
+    if (family === 'ask') {
+        const taskId = s('taskId');
+        const askId = s('askId');
+        return taskId !== undefined && askId !== undefined ? { family, taskId, askId, approvalId: s('approvalId'), toolCallId: s('toolCallId'), answer } : undefined;
+    }
+    return undefined;
+}
+function latchKeysOf(r) {
+    if (r.family === 'elicitation')
+        return decisionLedgerKeysOf({ elicitationId: r.elicitationId });
+    if (r.family === 'ask')
+        return decisionLedgerKeysOf({ askId: r.askId, approvalId: r.approvalId });
+    return decisionLedgerKeysOf({ approvalId: r.approvalId });
+}
+function ledgerFamilyOf(family) {
+    return family === 'elicitation' ? 'elicitation' : 'tool_approval';
+}
+async function readBack(deps, gate) {
+    const port = hostField(deps, 'readPending');
+    if (typeof port !== 'function')
+        return undefined;
+    const settled = await settleWithinDeadline(HITL_DECISION_READBACK_BUDGET_MS, (signal) => Promise.resolve(port.call(deps, gate, { signal })));
+    if (settled.kind !== 'value')
+        return 'unknown';
+    return settled.value === 'pending' || settled.value === 'not_pending' ? settled.value : 'unknown';
+}
+export async function sendHitlDecision(request, deps) {
+    const familyRead = typeof request === 'object' && request !== null ? guardedRead(() => readOwnDataNonEmptyString(request, 'family')) : undefined;
+    const family = familyRead === 'ask' || familyRead === 'elicitation' ? familyRead : 'approval';
+    const notSent = (cause) => Object.freeze({ family, attempts: 0, kind: 'not_sent', cause });
+    let req;
+    try {
+        req = readRequest(request);
+    }
+    catch {
+        req = undefined;
+    }
+    if (req === undefined)
+        return notSent('invalid_request');
+    const signal = signalOf(hostField(deps, 'signal'));
+    const client = hostField(deps, 'client');
+    const toolApprovals = hostField(client, 'toolApprovals');
+    const respond = verbOf(toolApprovals, 'respond');
+    const decideAsk = verbOf(toolApprovals, 'decideAsk');
+    const elicit = verbOf(hostField(client, 'elicitations'), 'respond');
+    if ((req.family === 'approval' && respond === undefined) || (req.family === 'ask' && decideAsk === undefined) || (req.family === 'elicitation' && elicit === undefined))
+        return notSent('no_verb');
+    if (req.family !== 'elicitation' && req.answer.kind !== 'allow' && req.answer.kind !== 'deny')
+        return notSent('not_an_answer');
+    if (isAborted(signal))
+        return notSent('aborted');
+    let ownHold;
+    let hold;
+    if (req.family !== 'elicitation' && req.approvalId !== undefined) {
+        const given = holdOf(hostField(deps, 'hold'));
+        if (given !== undefined && hostHoldIsActive(given) && holdFits(given, req)) {
+            hold = given;
+        }
+        else {
+            const attempt = tryHoldApprovalNow({ approvalId: req.approvalId, ...(req.taskId !== undefined ? { taskId: req.taskId } : {}), ...(req.toolCallId !== undefined ? { toolCallId: req.toolCallId } : {}) }, signal);
+            if (attempt.kind === 'settled')
+                return Object.freeze({ family, attempts: 0, kind: 'settled_elsewhere' });
+            if (attempt.kind === 'busy')
+                return notSent('duplicate_in_flight');
+            ownHold = attempt.hold;
+            hold = ownHold;
+        }
+        callHold(() => hold?.sending());
+    }
+    const ledgerFamily = ledgerFamilyOf(req.family);
+    if (latchKeysOf(req).some((k) => decisionOpsWithKey(ledgerFamily, k).some((o) => o.phase === 'posting' && o.settledAt === null))) {
+        ownHold?.release();
+        return notSent('duplicate_in_flight');
+    }
+    const requestKeys = req.family === 'elicitation'
+        ? decisionLedgerKeysOf({ taskId: req.taskId, elicitationId: req.elicitationId })
+        : decisionLedgerKeysOf({ taskId: req.taskId, approvalId: req.approvalId, callId: req.toolCallId, askId: req.family === 'ask' ? req.askId : undefined });
+    const taken = hold !== undefined ? takeHostHoldLedgerOp(hold) : undefined;
+    let op;
+    if (taken !== undefined && taken.settledAt === null) {
+        op = taken;
+        op.phase = 'posting';
+        op.ownCallOpen = true;
+        addDecisionOpKeys(op, requestKeys);
+    }
+    else {
+        op = openDecisionOp(ledgerFamily, requestKeys, 'posting', true);
+    }
+    const decidedBy = hostField(deps, 'approvalDecidedBy');
+    const ctx = {
+        signal,
+        tally: newSendTally(),
+        noteCapable: hostField(deps, 'approvalDecisionNoteCapable') === true,
+        decidedBy: typeof decidedBy === 'object' && decidedBy !== null ? decidedBy : undefined,
+    };
+    let out;
+    try {
+        if (req.family === 'approval') {
+            out = await sendApprovalFamily(respond, req.approvalId, req.answer, ctx);
+        }
+        else if (req.family === 'ask') {
+            out = await sendAskFamily(respond, decideAsk, { taskId: req.taskId, askId: req.askId, approvalId: req.approvalId, answer: req.answer }, ctx);
+        }
+        else {
+            const { elicitationId, response } = req;
+            try {
+                await withTransportRetry((sig) => elicit(elicitationId, response, sig !== undefined ? { signal: sig } : undefined), signal, ctx.tally);
+                out = { family: 'elicitation', attempts: ctx.tally.attempts, kind: 'applied' };
+            }
+            catch (e) {
+                out = outcomeOfThrown(e, 'elicitation', undefined, signal, ctx.tally, false);
+            }
+        }
+        const ambiguous = out.kind === 'unconfirmed' || (out.kind === 'not_applied' && (out.cause === 'parking' || out.cause === 'refused' || out.cause === 'idempotency_crossed'));
+        if (ambiguous && out.cause !== 'aborted') {
+            const gate = req.family === 'elicitation'
+                ? { family: req.family, elicitationId: req.elicitationId, ...(req.taskId !== undefined ? { taskId: req.taskId } : {}) }
+                : {
+                    family: req.family,
+                    ...(req.approvalId !== undefined ? { approvalId: req.approvalId } : {}),
+                    ...(req.family === 'ask' ? { askId: req.askId } : {}),
+                    ...(req.taskId !== undefined ? { taskId: req.taskId } : {}),
+                };
+            const pending = await readBack(deps, gate);
+            if (pending !== undefined) {
+                out = { ...out, pending };
+                if ((out.cause === 'refused' || out.cause === 'idempotency_crossed') && decisionRefusalClosesOut(out.refusal, pending))
+                    out = { ...out, closesOut: true };
+            }
+        }
+    }
+    catch {
+        out = { family: req.family, attempts: ctx.tally.attempts, kind: 'unconfirmed', cause: 'local_error' };
+    }
+    const notApplied = out.kind !== 'applied' &&
+        (out.pending === 'pending' ||
+            (out.kind === 'not_applied' && (out.cause === 'lane_disabled' || out.cause === 'idempotency_crossed' || (out.cause === 'refused' && out.refusal?.standing === 'refused-pending'))));
+    if (notApplied)
+        op.notApplied = true;
+    closeDecisionOp(op, 'package');
+    if (ownHold !== undefined)
+        ownHold.release(out.kind === 'applied' || out.kind === 'settled_elsewhere' ? 'answered' : undefined);
+    return Object.freeze(out);
+}
+export function hitlDecisionOutcomeContent(outcome, lang) {
+    try {
+        if (typeof outcome !== 'object' || outcome === null)
+            return undefined;
+        const kind = readOwnDataValue(outcome, 'kind');
+        if (kind === 'settled_elsewhere') {
+            if (readOwnDataValue(outcome, 'contrary') !== true)
+                return undefined;
+            const first = readOwnDataValue(outcome, 'firstDecision');
+            if (first === 'deny')
+                return renderMessage(msg('approval.decision.settledElsewhereContrary.deniedFirst'), lang);
+            if (first === 'approve')
+                return renderMessage(msg('approval.decision.settledElsewhereContrary.approvedFirst'), lang);
+            return undefined;
+        }
+        if (kind === 'unconfirmed' && readOwnDataValue(outcome, 'cause') === 'gone_after_retry')
+            return renderMessage(msg('approval.decision.unconfirmedAfterRetry'), lang);
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/hitl/frameRouter.d.ts

@@ -70,6 +70,7 @@ export interface FrameRouterCtx {
     signal?: AbortSignal | undefined;
 }
 export declare function isAskTool(toolName: string | undefined): boolean;
+export declare function questionCardVerdict(carrier: object | null | undefined): boolean | undefined;
 export declare function parkGateArmOf(gate: unknown): GateKind | null;
 export declare function isHostProgressFrame(ev: AgentEvent): boolean;
 interface HeldFlushInterruptEvidence {

package/dist/hitl/frameRouter.js

@@ -5,6 +5,8 @@ import { classifierDenyFromToolEnd } from '../classifierVerdictWire.js';
 import { toolEndOutputText } from '../toolResultContent.js';
 import { GATE_PARKED_ERROR_CODE } from '../engineErrorCodes.js';
 import { readRunTerminal, runTerminalCode, runTerminalGateKind, runTerminalGateToolName } from '../runTerminal.js';
+import { readApprovalCardWord } from './approvalCardReading.js';
+import { guardedRead, readOwnDataValue } from '../ownKey.js';
 import { parkHeldCallIdOf } from '../engineRowRef.js';
 import { inheritFrameBinding } from '../frameBinding.js';
 import { surfaceForCurrentSession, surfaceReplayedApprovalListUnreadable } from './hitlHostSurface.js';
@@ -102,6 +104,10 @@ function parkFamilyEvidence(led, gateToolName, gatedCallId) {
         return false;
     return gatedCallId === undefined || led.isFsOrShellGatedCall(gatedCallId);
 }
+export function questionCardVerdict(carrier) {
+    const word = readApprovalCardWord(carrier);
+    return word === undefined ? undefined : word === 'question';
+}
 export function parkGateArmOf(gate) {
     if (gate === null || typeof gate !== 'object')
         return null;
@@ -117,7 +123,7 @@ export function parkGateArmOf(gate) {
     const leg = durableDecideLegOf(typeof kind === 'string' ? { gateKind: kind } : null);
     if (leg !== 'approval' && leg !== 'absent')
         return null;
-    if (isAskToolLoose(toolName))
+    if (questionCardVerdict(gate) ?? isAskToolLoose(toolName))
         return 'ask';
     if (leg === 'approval')
         return 'fs';
@@ -147,7 +153,8 @@ function parkGateOf(result) {
     if (typeof taskId !== 'string' || taskId.length === 0)
         return null;
     const toolName = runTerminalGateToolName(read);
-    const arm = parkGateArmOf({ kind: runTerminalGateKind(read), toolName });
+    const approvalCard = guardedRead(() => readOwnDataValue(read.gate, 'approvalCard'));
+    const arm = parkGateArmOf({ kind: runTerminalGateKind(read), toolName, approvalCard });
     return arm === null ? null : { taskId, gate: arm, toolName };
 }
 function parkGatedCallId(src) {

package/dist/hitl/hitlBridge.d.ts

@@ -1,5 +1,6 @@
-import type { AgentEvent, ApprovalDecidedBy, ApprovalDecision, ApprovalStaleError, PendingCheckpoint, CheckpointGate, PlanReviewRequest, AssistantTaskStatus } from '@sema-agent/sdk';
+import type { AgentEvent, ApprovalDecidedBy, ApprovalDecision, ApprovalStaleError, PendingCheckpoint, CheckpointGate, PlanReviewRequest, AssistantTaskStatus, QuestionAnswerItem } from '@sema-agent/sdk';
 import type { PermissionResult } from '@sema-agent/agent-types';
+import { type CapturedLocalCode, type CauseSlotRead } from '../engineWireFor.js';
 import type { ApprovalsListEnvelope } from './crashConverged.js';
 import { type SuspendedReopenReading } from './suspendedReopen.js';
 export declare const DEFAULT_DENY_REASON = "The user rejected this tool use";
@@ -33,11 +34,7 @@ export interface HitlClientLike {
     approvals: ApprovalsResourceLike;
     assistant: AssistantResourceLike;
 }
-export interface AskAnswer {
-    header: string;
-    selected: string[];
-    note?: string;
-}
+export type AskAnswer = QuestionAnswerItem;
 export interface PlanReviewOutcome {
     decision: 'approve' | 'edit' | 'reject';
     editedPlan?: string;
@@ -63,6 +60,21 @@ export declare class HitlSafetyError extends Error {
     readonly code: HitlSafetyCode;
     constructor(message: string, code: HitlSafetyCode, options?: ErrorOptions);
 }
+export interface RefusalCarrier {
+    readonly local?: HitlSafetyCode;
+    readonly carrier: {} | null | undefined;
+}
+export declare function refusalCarrierOf(err: {} | null | undefined, localCodeRead?: {
+    readonly value: CapturedLocalCode;
+}, answeredLayer?: boolean, causeRead?: CauseSlotRead, headRead?: SafetyStopHead): RefusalCarrier;
+export declare function safetyStopNamed(err: {} | null | undefined): boolean;
+export interface SafetyStopHead {
+    readonly named: boolean;
+    readonly local?: HitlSafetyCode;
+}
+export declare function safetyStopHeadOf(err: {} | null | undefined, localCodeRead?: {
+    readonly value: CapturedLocalCode;
+}, namedRead?: boolean): SafetyStopHead;
 export declare function hitlSafetyCodeOf(e: unknown): HitlSafetyCode | undefined;
 export type GateCurrentPending = Readonly<NonNullable<ApprovalStaleError['currentPending']>>;
 export declare function readDecideCurrentPending(e: unknown): GateCurrentPending | undefined;