@sema-agent/client-core 0.98.0 → 0.100.0

package/dist/hitl/decisionSend.js

@@ -0,0 +1,579 @@
+import { abortableSleep, settleWithinDeadline } from '../abortableSleep.js';
+import { hostLog } from '../host.js';
+import { askGoneFromError } from '../decideReceipt.js';
+import { guardedRead, readOwnDataNonEmptyString, readOwnDataValue } from '../ownKey.js';
+import { effectiveWireErrorCode, isWireTransportError } from '../wireErrorTriage.js';
+import { ASK_DECISION_LANE_DISABLED, ASK_GONE, ASK_GONE_PARKED, ASK_IDEMPOTENCY_CONFLICT, ASK_NOT_FOUND, ASK_PARKING_RETRY } from '../engineErrorCodes.js';
+import { readErrorNumber, readErrorString, readThrownSlot, readThrownStatusSlot, THROWN_SLOT_UNREADABLE } from '../wireFailureShape.js';
+import { readDecisionNoteAudit } from './approvalDecisionNoteAudit.js';
+import { deliverWithAttributionLadder } from './attributionLadder.js';
+import { ASK_DECIDED_CODE, classifyDecisionRefusal, decisionRefusalClosesOut } 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 RETRY_DELAYS_MS = Object.freeze([500, 1_000, 2_000]);
+const RETRY_BUDGET_MS = 8_000;
+const PARKING_POLL_MAX = 2;
+const PARKING_POLL_DELAY_MS = 400;
+const PARKING_POLL_WAIT_CAP_MS = 5_000;
+export const HITL_DECISION_READBACK_BUDGET_MS = 4_000;
+const IDEMPOTENCY_KEY_MAX = 255;
+let timingOverride;
+export function __setHitlDecisionSendTimingForTests(t) {
+    timingOverride = 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 isAbortShaped(e) {
+    const name = readThrownSlot(e, 'name');
+    return name === 'TimeoutError' || name === 'AbortError';
+}
+function transportClassOf(e, signal) {
+    if (signal?.aborted === true)
+        return 'aborted';
+    const status = typeof e === 'object' && e !== null ? readThrownStatusSlot(e) : undefined;
+    if (status === THROWN_SLOT_UNREADABLE)
+        return 'local_error';
+    if (typeof status === 'number')
+        return status === 501 ? 'verdict' : status >= 500 ? 'server_5xx' : 'verdict';
+    return isWireTransportError(e) || isAbortShaped(e) ? 'transport' : 'local_error';
+}
+function attemptSignal(attempt, caller, startedAt, budgetMs) {
+    if (attempt === 1)
+        return caller;
+    const deadline = AbortSignal.timeout(Math.max(1, budgetMs - (Date.now() - startedAt)));
+    if (caller === undefined)
+        return deadline;
+    if (typeof AbortSignal.any === 'function')
+        return AbortSignal.any([caller, deadline]);
+    const ac = new AbortController();
+    const abort = (s) => ac.abort(s.reason);
+    if (caller.aborted)
+        abort(caller);
+    else
+        caller.addEventListener('abort', () => abort(caller), { once: true });
+    deadline.addEventListener('abort', () => abort(deadline), { once: true });
+    return ac.signal;
+}
+function budgetSpent(tally, extraMs) {
+    return Date.now() - tally.startedAt + extraMs >= (timingOverride?.budgetMs ?? RETRY_BUDGET_MS);
+}
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+function sleepFor(ms, signal) {
+    return abortableSleep(ms, signal ?? new AbortController().signal);
+}
+async function withTransportRetry(send, signal, tally) {
+    const delays = timingOverride?.delays ?? RETRY_DELAYS_MS;
+    const budgetMs = timingOverride?.budgetMs ?? RETRY_BUDGET_MS;
+    const startedAt = tally.startedAt;
+    for (let attempt = 1;; attempt++) {
+        tally.attempts++;
+        try {
+            return await send(attemptSignal(attempt, signal, startedAt, budgetMs));
+        }
+        catch (e) {
+            const cls = transportClassOf(e, signal);
+            const delay = delays[attempt - 1] ?? 0;
+            const retriable = cls === 'transport' || cls === 'server_5xx';
+            const overBudget = Date.now() - startedAt + delay >= budgetMs;
+            if (!retriable || attempt > delays.length || overBudget)
+                throw e;
+            tally.retried = true;
+            await sleepFor(delay, signal);
+            if (signal?.aborted === true)
+                throw e;
+        }
+    }
+}
+function retryAfterMsOf(e) {
+    if (typeof e !== 'object' || e === null)
+        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) {
+    const base = { family, attempts: tally.attempts };
+    const cls = transportClassOf(e, signal);
+    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 obj = e;
+    const status = readThrownStatusSlot(obj);
+    if (cls === 'server_5xx')
+        return { ...base, kind: 'unconfirmed', cause: 'server_error', status };
+    const code = effectiveWireErrorCode(e);
+    const at = { ...base, status, ...(code !== undefined ? { errorCode: code } : {}) };
+    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) };
+            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 family !== 'ask' && tally.retried ? { ...base, kind: 'unconfirmed', cause: 'gone_after_retry', status } : { ...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) };
+}
+function refusalOf(e) {
+    const r = classifyDecisionRefusal(e);
+    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);
+    let raw;
+    try {
+        raw = await deliverWithAttributionLadder(body, (b) => withTransportRetry((signal) => respond(approvalId, b, signal !== undefined ? { signal } : undefined), ctx.signal, ctx.tally), ctx.signal, ladder);
+    }
+    catch (e) {
+        return { ...outcomeOfThrown(e, 'approval', ours, ctx.signal, ctx.tally, ctx.noteCapable), ...extras };
+    }
+    const facts = { ...extras, ...(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;
+        return { ...base, kind: 'not_applied', cause: 'parking', ...(view !== undefined ? { parking: view, ...(view.retryAfterMs !== undefined ? { retryAfterMs: view.retryAfterMs } : {}) } : {}) };
+    }
+    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 = timingOverride?.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);
+            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 code = effectiveWireErrorCode(e);
+            const wait = Math.max(parkingDelay * (poll + 1), retryAfterMsOf(e) ?? 0);
+            if (code === ASK_PARKING_RETRY && poll < PARKING_POLL_MAX && !isAborted(ctx.signal) && wait <= PARKING_POLL_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);
+            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;
+                    copy.push(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: { attempts: 0, retried: false, startedAt: Date.now() },
+        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);
+}

package/dist/hitl/frameRouter.js

@@ -8,11 +8,11 @@ import { readRunTerminal, runTerminalCode, runTerminalGateKind, runTerminalGateT
 import { parkHeldCallIdOf } from '../engineRowRef.js';
 import { inheritFrameBinding } from '../frameBinding.js';
 import { surfaceForCurrentSession, surfaceReplayedApprovalListUnreadable } from './hitlHostSurface.js';
-import { liveCardHoldOf, noteEngineClosedApproval, supersedeLiveCard } from './approvalHolds.js';
+import { liveCardHoldOf, noteEngineClosedApproval, settleEngineClosedApproval } from './approvalHolds.js';
 import { approvalCompleteParked } from './approvalCompleteParked.js';
 import { liveFrameCallKey } from './gateIdentity.js';
 import { SEMA_DENIAL_KIND_KEY, hasLedgerPositionKey } from './gateLedger.js';
-import { replayedApprovalDisposition, settledApprovalDisposition } from './replayedApproval.js';
+import { replayedApprovalClosesCardFrame, replayedApprovalDisposition, settledApprovalDisposition } from './replayedApproval.js';
 import { settleWithinDeadline } from '../abortableSleep.js';
 import { ccToolDenialKindForSettledBy } from '../gateVocabulary.js';
 import { REJECT_MESSAGE } from '../adapt/wireShapes.js';
@@ -285,12 +285,9 @@ const TOOL_END_ARMS = [
 async function routeToolApprovalFrame(ev, ctx) {
     const { led, deps } = ctx;
     if (ev.type === 'tool_approval_complete') {
-        const id = ev.approvalId;
-        const parked = approvalCompleteParked(ev);
-        if (typeof id === 'string' && id !== '')
-            noteEngineClosedApproval(id, parked);
-        if (typeof id === 'string' && id !== '' && supersedeLiveCard(liveFrameCallKey(id), parked)) {
-            hostLog('debug', `liveHitlAskWire: tool_approval_complete for ${id} arrived while its card was waiting — card withdrawn (nothing will be sent from it)`);
+        if (settleEngineClosedApproval(ev, approvalCompleteParked(ev))) {
+            const id = ev.approvalId;
+            hostLog('debug', `liveHitlAskWire: tool_approval_complete for ${String(id)} arrived while its card was waiting — card withdrawn (nothing will be sent from it)`);
         }
         return { kind: 'skip' };
     }
@@ -307,6 +304,8 @@ async function routeToolApprovalFrame(ev, ctx) {
                 : `liveHitlAskWire: tool_approval frame ${ev.approvalId} read back from the run event log is ${disposition.kind}` +
                     `${disposition.kind === 'unknown' ? ` (${disposition.why})` : disposition.cause !== undefined ? ` (${disposition.cause})` : ''}` +
                     ' — not raised as a question, no decision sent');
+            if (settledHere === undefined && replayedApprovalClosesCardFrame(disposition))
+                noteEngineClosedApproval(ev.approvalId, false);
             if (disposition.kind === 'unknown' && ctx.signal?.aborted !== true)
                 surfaceReplayedApprovalListUnreadable();
             if (deps.onReplayedApproval !== undefined) {

package/dist/hitl/hitlBridge.d.ts

@@ -3,6 +3,7 @@ import type { PermissionResult } from '@sema-agent/agent-types';
 import type { ApprovalsListEnvelope } from './crashConverged.js';
 import { type SuspendedReopenReading } from './suspendedReopen.js';
 export declare const DEFAULT_DENY_REASON = "The user rejected this tool use";
+export declare const MAX_DENY_REASON_CHARS = 4096;
 export declare function denyReasonForWire(reason: string | undefined, tag: string): string | undefined;
 export interface HitlPermissionDecisionLike {
     behavior: 'allow' | 'ask' | 'deny';