@sema-agent/client-core 0.98.0 → 0.100.0

package/dist/hitl/attributionLadder.d.ts

@@ -0,0 +1,23 @@
+export declare function shouldResendWithoutAttribution(e: {} | null | undefined, sentAttributionKey: boolean, signal?: AbortSignal): boolean;
+export declare function shouldResendUnderSuccessorKey(e: {} | null | undefined, lastSendCarriedRetiredKey: boolean, signal?: AbortSignal): boolean;
+export declare function carriesAttributionKey(body: object): boolean;
+export declare function withoutAttributionKey<T extends {
+    settledBy?: unknown;
+    decidedBy?: unknown;
+}>(body: T): Omit<T, 'settledBy' | 'decidedBy'>;
+export declare function withAttributionKeyRenamed<T extends {
+    settledBy?: unknown;
+    decidedBy?: unknown;
+}>(body: T): Omit<T, 'settledBy' | 'decidedBy'> & {
+    decidedBy?: Exclude<T['settledBy'], undefined>;
+};
+export interface AttributionLadderState {
+    lastCarried: boolean;
+    dropped: boolean;
+    renamed: boolean;
+}
+export type AttributionLadderStep = 'dropped' | 'renamed' | 'renamed_then_dropped';
+export declare function deliverWithAttributionLadder<B extends {
+    settledBy?: unknown;
+    decidedBy?: unknown;
+}, R>(body: B, send: (b: B) => Promise<R>, signal: AbortSignal | undefined, state: AttributionLadderState, onStep?: (step: AttributionLadderStep) => void): Promise<R>;

package/dist/hitl/attributionLadder.js

@@ -0,0 +1,67 @@
+import { denyAttributionRefusalFromError } from '../wireRefusalCopy.js';
+export function shouldResendWithoutAttribution(e, sentAttributionKey, signal) {
+    if (!sentAttributionKey)
+        return false;
+    if (signal?.aborted === true)
+        return false;
+    return denyAttributionRefusalFromError(e, true)?.kind === 'not_in_proof';
+}
+export function shouldResendUnderSuccessorKey(e, lastSendCarriedRetiredKey, signal) {
+    if (!lastSendCarriedRetiredKey)
+        return false;
+    if (signal?.aborted === true)
+        return false;
+    return denyAttributionRefusalFromError(e, true)?.kind === 'retired_key';
+}
+export function carriesAttributionKey(body) {
+    return Object.hasOwn(body, 'settledBy') || Object.hasOwn(body, 'decidedBy');
+}
+export function withoutAttributionKey(body) {
+    const { settledBy: _droppedSettledBy, decidedBy: _droppedDecidedBy, ...rest } = body;
+    void _droppedSettledBy;
+    void _droppedDecidedBy;
+    return rest;
+}
+export function withAttributionKeyRenamed(body) {
+    const { settledBy, decidedBy: _replaced, ...rest } = body;
+    void _replaced;
+    return settledBy === undefined ? rest : { ...rest, decidedBy: settledBy };
+}
+export async function deliverWithAttributionLadder(body, send, signal, state, onStep) {
+    state.lastCarried = carriesAttributionKey(body);
+    state.dropped = false;
+    state.renamed = false;
+    try {
+        return await send(body);
+    }
+    catch (first) {
+        if (shouldResendWithoutAttribution(first, state.lastCarried, signal)) {
+            const withoutAttribution = withoutAttributionKey(body);
+            state.lastCarried = false;
+            onStep?.('dropped');
+            const r = await send(withoutAttribution);
+            state.dropped = true;
+            return r;
+        }
+        if (shouldResendUnderSuccessorKey(first, Object.hasOwn(body, 'settledBy'), signal)) {
+            const renamed = withAttributionKeyRenamed(body);
+            onStep?.('renamed');
+            try {
+                const r = await send(renamed);
+                state.renamed = true;
+                return r;
+            }
+            catch (second) {
+                if (!shouldResendWithoutAttribution(second, true, signal))
+                    throw second;
+                const renamedWithoutAttribution = withoutAttributionKey(renamed);
+                state.lastCarried = false;
+                onStep?.('renamed_then_dropped');
+                const r = await send(renamedWithoutAttribution);
+                state.dropped = true;
+                return r;
+            }
+        }
+        throw first;
+    }
+}

package/dist/hitl/automaticAnswerVerdict.d.ts

@@ -1,5 +1,6 @@
 import { type CoreModeArbitrationRow } from '../generated/engineFactTables.js';
 import { CORE_ASK_FACES } from '../generated/engineAskFaceTables.js';
+import type { UiLanguage } from '../env/uiLanguage.js';
 export type AutomaticAnswerLane = 'mode_posture' | 'standing_rule' | 'permission_request_hook';
 export type AutomaticAnswerAskFace = (typeof CORE_ASK_FACES)[number];
 export interface AutomaticAnswerFacts {
@@ -22,6 +23,6 @@ export type AutomaticAnswerVerdict = {
 export declare const MODE_ARBITRATION: Readonly<Record<"hook" | "write_protection" | "mode" | "target_unresolved" | "content_question" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "org_rule" | "rule_unreadable" | "ask_rule" | "denial_limit_fallback" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary", CoreModeArbitrationRow>>;
 export declare function foldModeArbitrationRow(classes: Iterable<string>, askFace?: AutomaticAnswerAskFace): CoreModeArbitrationRow;
 export declare function automaticAnswerVerdict(card: object | null | undefined, lane: AutomaticAnswerLane, facts?: AutomaticAnswerFacts | null): AutomaticAnswerVerdict;
-export declare function mandatedApprovalDetailOf(card: object | null | undefined): string;
+export declare function mandatedApprovalDetailOf(card: object | null | undefined, lang?: UiLanguage): string;
 export type PermissionRequestHookScope = 'allow_or_deny' | 'deny_only' | 'skip';
 export declare function permissionRequestHookScope(verdict: AutomaticAnswerVerdict | null | undefined): PermissionRequestHookScope;

package/dist/hitl/automaticAnswerVerdict.js

@@ -1,6 +1,7 @@
 import { CORE_MODE_ARBITRATION, CORE_MODE_RELEASE_REASONS } from '../generated/engineFactTables.js';
 import { CORE_RELEASABLE_ASK_CLASSES_BY_FACE, CORE_SHELL_FACE_TOOL_NAMES } from '../generated/engineAskFaceTables.js';
 import { mandatedApprovalDetail } from '../gateVocabulary.js';
+import { msg, renderMessage } from '../i18n/translate.js';
 import { readAskOrigin, readOwnNonEmptyString } from '../ownKey.js';
 import { readAskClassPairState } from './askClassPair.js';
 import { readRequiresRealApproval } from './approvalCardReading.js';
@@ -179,26 +180,25 @@ export function automaticAnswerVerdict(card, lane, facts) {
         return UNKNOWN.card_unreadable;
     }
 }
-export function mandatedApprovalDetailOf(card) {
+export function mandatedApprovalDetailOf(card, lang) {
     try {
         if (typeof card !== 'object' || card === null)
-            return mandatedApprovalDetail();
+            return mandatedApprovalDetail(lang);
         const pair = readAskClassPairState(card);
         if (pair.state !== 'pair')
-            return mandatedApprovalDetail();
+            return mandatedApprovalDetail(lang);
         const classes = pair.classes;
         if (classes.some((c) => !Object.hasOwn(TABLE, c)))
-            return mandatedApprovalDetail();
+            return mandatedApprovalDetail(lang);
         const row = foldModeArbitrationRow(classes);
         if (row.classifierEligible || row.sandboxAdmission)
-            return mandatedApprovalDetail();
-        return MANDATED_NO_AUTOMATIC_CHECK_DETAIL;
+            return mandatedApprovalDetail(lang);
+        return renderMessage(msg('approval.mandate.noAutomaticCheck'), lang);
     }
     catch {
-        return mandatedApprovalDetail();
+        return mandatedApprovalDetail(lang);
     }
 }
-const MANDATED_NO_AUTOMATIC_CHECK_DETAIL = 'no saved allow rule and no remembered answer can retire this question, and no automatic check answers it; each call is settled on its own, by you here, and an answer covers only that call';
 export function permissionRequestHookScope(verdict) {
     try {
         const kind = typeof verdict === 'object' && verdict !== null ? verdict.kind : undefined;

package/dist/hitl/crashConvergedNotice.d.ts

@@ -1,6 +1,7 @@
+import type { UiLanguage } from '../env/uiLanguage.js';
 import type { CrashConvergedProjection, CrashConvergedRowReading } from './crashConverged.js';
 export declare const NEEDS_HUMAN_REASON_ORDER: readonly ["approved_then_interrupted", "pending_unsafe", "contradictory", "unstable_row"];
-export declare function crashConvergedNeedsHumanSentence(reason: string | undefined, n: number, total: number): string | undefined;
-export declare function crashConvergedNotice(projection: CrashConvergedProjection | undefined): string | undefined;
-export declare function crashConvergedRowSentence(projection: CrashConvergedProjection | undefined, row: Pick<CrashConvergedRowReading, 'approvalId'>): string | undefined;
-export declare function crashConvergedCauseSentence(cause: string | undefined): string | undefined;
+export declare function crashConvergedNeedsHumanSentence(reason: string | undefined, n: number, total: number, lang?: UiLanguage): string | undefined;
+export declare function crashConvergedNotice(projection: CrashConvergedProjection | undefined, lang?: UiLanguage): string | undefined;
+export declare function crashConvergedRowSentence(projection: CrashConvergedProjection | undefined, row: Pick<CrashConvergedRowReading, 'approvalId'>, lang?: UiLanguage): string | undefined;
+export declare function crashConvergedCauseSentence(cause: string | undefined, lang?: UiLanguage): string | undefined;

package/dist/hitl/crashConvergedNotice.js

@@ -1,3 +1,4 @@
+import { msg, renderMessage } from '../i18n/translate.js';
 import { askEndingCauseClause } from './askSettlementLine.js';
 import { crashConvergedRowInProjection, isCrashConvergedCause, readCrashConvergedNoticeFacts } from './crashConverged.js';
 export const NEEDS_HUMAN_REASON_ORDER = Object.freeze(['approved_then_interrupted', 'pending_unsafe', 'contradictory', 'unstable_row']);
@@ -7,53 +8,40 @@ const _orderHasNoDuplicate = true;
 void _orderCoversReasons;
 void _orderInsideReasons;
 void _orderHasNoDuplicate;
-const RECORDED = 'based on what was recorded';
-const NO_AUTO_RERUN = 'sema has not re-run anything';
 const plural = (n, one, many) => (n === 1 ? one : many);
 const NEEDS_HUMAN_CLAUSES = Object.freeze({
-    approved_then_interrupted: {
-        one: 'had already been approved and may have been running when the previous engine run ended, so a side effect may have partly landed',
-        many: 'had already been approved and may have been running when the previous engine run ended, so a side effect may have partly landed',
-    },
-    pending_unsafe: {
-        one: `had not started, ${RECORDED}, but the engine did not mark it as safe to re-run`,
-        many: `had not started, ${RECORDED}, but the engine did not mark them as safe to re-run`,
-    },
-    contradictory: { one: 'has a contradictory record', many: 'have contradictory records' },
-    unstable_row: {
-        one: 'has a record that read differently each time it was read',
-        many: 'have records that read differently each time they were read',
-    },
+    approved_then_interrupted: { one: 'session.crashConverged.reason.approvedThenInterrupted.one', many: 'session.crashConverged.reason.approvedThenInterrupted.many' },
+    pending_unsafe: { one: 'session.crashConverged.reason.pendingUnsafe.one', many: 'session.crashConverged.reason.pendingUnsafe.many' },
+    contradictory: { one: 'session.crashConverged.reason.contradictory.one', many: 'session.crashConverged.reason.contradictory.many' },
+    unstable_row: { one: 'session.crashConverged.reason.unstableRow.one', many: 'session.crashConverged.reason.unstableRow.many' },
 });
-const FALLBACK_CLAUSE = Object.freeze({
-    one: 'had already been approved, or cannot be accounted for, so a side effect may have partly landed',
-    many: 'had already been approved, or cannot be accounted for, so a side effect may have partly landed',
-});
-const RESUME_SAFE_CLAUSE = `had not started, ${RECORDED}, and can be re-run`;
-const countedClause = (clause, n, total) => `${n} of ${total} ${n === 1 ? clause.one : clause.many}`;
+const FALLBACK_CLAUSE = Object.freeze({ one: 'session.crashConverged.fallback.one', many: 'session.crashConverged.fallback.many' });
+const RESUME_SAFE_CLAUSE = 'session.crashConverged.resumeSafe';
+const countedClause = (clause, n, total, lang) => renderMessage(msg('session.crashConverged.counted', { n, total, clause: msg(n === 1 ? clause.one : clause.many) }), lang);
 const isNeedsHumanReason = (v) => typeof v === 'string' && Object.hasOwn(NEEDS_HUMAN_CLAUSES, v);
-export function crashConvergedNeedsHumanSentence(reason, n, total) {
+export function crashConvergedNeedsHumanSentence(reason, n, total, lang) {
     if (!isNeedsHumanReason(reason))
         return undefined;
     if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < 1)
         return undefined;
     if (typeof total !== 'number' || !Number.isSafeInteger(total) || total < n)
         return undefined;
-    return countedClause(NEEDS_HUMAN_CLAUSES[reason], n, total);
+    return countedClause(NEEDS_HUMAN_CLAUSES[reason], n, total, lang);
 }
-function needsHumanClauses(reasons, total) {
+function needsHumanClauses(reasons, total, lang) {
     const clauses = [];
     for (const reason of NEEDS_HUMAN_REASON_ORDER) {
         const n = reasons.filter((r) => r === reason).length;
         if (n > 0)
-            clauses.push(countedClause(NEEDS_HUMAN_CLAUSES[reason], n, total));
+            clauses.push(countedClause(NEEDS_HUMAN_CLAUSES[reason], n, total, lang));
     }
     const fallback = reasons.filter((r) => !isNeedsHumanReason(r)).length;
     if (fallback > 0)
-        clauses.push(countedClause(FALLBACK_CLAUSE, fallback, total));
-    return `${clauses.join('; ')} — check ${plural(reasons.length, 'it', 'them')} by hand before re-running`;
+        clauses.push(countedClause(FALLBACK_CLAUSE, fallback, total, lang));
+    const joined = clauses.join(renderMessage(msg('session.crashConverged.clauseJoin'), lang));
+    return renderMessage(msg(plural(reasons.length, 'session.crashConverged.needsHumanBody.one', 'session.crashConverged.needsHumanBody.many'), { clauses: joined }), lang);
 }
-export function crashConvergedNotice(projection) {
+export function crashConvergedNotice(projection, lang) {
     const facts = readCrashConvergedNoticeFacts(projection);
     if (facts === undefined)
         return undefined;
@@ -61,16 +49,15 @@ export function crashConvergedNotice(projection) {
     if (total === 0 && dropped === 0)
         return undefined;
     if (total === 0) {
-        return `the previous session left ${dropped} crash-converged approval ${plural(dropped, 'record', 'records')} that this version could not read. ${NO_AUTO_RERUN}.`;
+        return renderMessage(msg(plural(dropped, 'session.crashConverged.droppedOnly.one', 'session.crashConverged.droppedOnly.many'), { count: dropped }), lang);
     }
-    const recordedAs = causes !== undefined && causes.length > 0 ? ` (recorded as ${causes.join(', ')})` : '';
-    const head = `the previous engine run ended with ${total} ${plural(total, 'approval', 'approvals')} still waiting${recordedAs}, ` +
-        `and the engine converged ${plural(total, 'it', 'them')} to denied`;
-    const body = needsHumanReasons.length > 0 ? needsHumanClauses(needsHumanReasons, total) : `${RECORDED}, ${plural(total, 'it', 'they')} can be re-run`;
-    const droppedClause = dropped > 0 ? ` (${dropped} further ${plural(dropped, 'record', 'records')} could not be read.)` : '';
-    return `${head}; ${body}. ${NO_AUTO_RERUN}.${droppedClause}`;
+    const recordedAs = causes !== undefined && causes.length > 0 ? msg('session.crashConverged.recordedAs', { causes: causes.join(', ') }) : '';
+    const head = renderMessage(msg(plural(total, 'session.crashConverged.head.one', 'session.crashConverged.head.many'), { total, recorded: recordedAs }), lang);
+    const body = needsHumanReasons.length > 0 ? needsHumanClauses(needsHumanReasons, total, lang) : renderMessage(msg(plural(total, 'session.crashConverged.rerunnable.one', 'session.crashConverged.rerunnable.many')), lang);
+    const droppedClause = dropped > 0 ? msg(plural(dropped, 'session.crashConverged.droppedTail.one', 'session.crashConverged.droppedTail.many'), { count: dropped }) : '';
+    return renderMessage(msg('session.crashConverged.line', { head, body, dropped: droppedClause }), lang);
 }
-export function crashConvergedRowSentence(projection, row) {
+export function crashConvergedRowSentence(projection, row, lang) {
     const hit = crashConvergedRowInProjection(projection, row);
     if (hit === undefined)
         return undefined;
@@ -82,13 +69,13 @@ export function crashConvergedRowSentence(projection, row) {
         return undefined;
     }
     if (hit.bucket === 'resumeSafe')
-        return descriptor === undefined ? RESUME_SAFE_CLAUSE : undefined;
+        return descriptor === undefined ? renderMessage(msg(RESUME_SAFE_CLAUSE), lang) : undefined;
     const reason = descriptor !== undefined && Object.hasOwn(descriptor, 'value') ? descriptor.value : undefined;
-    return (isNeedsHumanReason(reason) ? NEEDS_HUMAN_CLAUSES[reason] : FALLBACK_CLAUSE).one;
+    return renderMessage(msg((isNeedsHumanReason(reason) ? NEEDS_HUMAN_CLAUSES[reason] : FALLBACK_CLAUSE).one), lang);
 }
-export function crashConvergedCauseSentence(cause) {
+export function crashConvergedCauseSentence(cause, lang) {
     if (typeof cause !== 'string' || cause === '')
         return undefined;
-    const clause = isCrashConvergedCause(cause) ? askEndingCauseClause(cause) : undefined;
-    return clause === undefined ? 'the decision converged automatically' : `${clause}, and the decision converged automatically`;
+    const clause = isCrashConvergedCause(cause) ? askEndingCauseClause(cause, lang) : undefined;
+    return renderMessage(clause === undefined ? msg('session.crashConverged.cause.neutral') : msg('session.crashConverged.cause.withClause', { clause }), lang);
 }

package/dist/hitl/decisionLedger.d.ts

@@ -0,0 +1,55 @@
+export declare const DECISION_LEDGER_FAMILIES: readonly ["plan_review", "tool_approval", "elicitation"];
+export type DecisionLedgerFamily = (typeof DECISION_LEDGER_FAMILIES)[number];
+export type DecisionLedgerPhase = 'handed' | 'posting' | 'landed';
+export type DecisionLedgerSettler = 'host' | 'package' | 'gate_left';
+export interface DecisionLedgerOp {
+    readonly family: DecisionLedgerFamily;
+    keys: readonly string[];
+    readonly handedAt: number;
+    settledAt: number | null;
+    settler: DecisionLedgerSettler | null;
+    phase: DecisionLedgerPhase;
+    notApplied: boolean;
+    ownCallOpen: boolean;
+}
+export interface DecisionLedgerIdentityParts {
+    readonly taskId?: string | undefined;
+    readonly planTaskId?: string | undefined;
+    readonly approvalId?: string | undefined;
+    readonly callId?: string | undefined;
+    readonly askId?: string | undefined;
+    readonly elicitationId?: string | undefined;
+}
+export declare function decisionLedgerKeysOf(parts: DecisionLedgerIdentityParts): string[];
+export declare function planDecisionKey(taskId: string): string;
+export declare function nextDecisionLedgerTick(): number;
+export declare function decisionOpsWithKey(family: DecisionLedgerFamily, key: string): DecisionLedgerOp[];
+export declare function decisionOpsOfFamily(family: DecisionLedgerFamily): readonly DecisionLedgerOp[];
+export declare function openDecisionOp(family: DecisionLedgerFamily, keys: readonly string[], phase: DecisionLedgerPhase, ownCallOpen: boolean): DecisionLedgerOp;
+export declare function settleDecisionOp(op: DecisionLedgerOp, by: DecisionLedgerSettler): void;
+export declare function closeDecisionOp(op: DecisionLedgerOp, by: DecisionLedgerSettler): void;
+export declare function addDecisionOpKeys(op: DecisionLedgerOp, keys: readonly string[]): void;
+export declare function dropDecisionOp(op: DecisionLedgerOp): void;
+export declare function markLatestDecisionNotApplied(family: DecisionLedgerFamily, key: string): void;
+export declare function settleDecisionOpsOnGateLeft(family: DecisionLedgerFamily, key: string): void;
+export declare function latestDecisionHandedMark(family: DecisionLedgerFamily, key: string): number | null;
+export declare function readMarkOf(v: number | undefined): number | undefined;
+export declare function decisionKeyInFlight(key: string, mark: number | undefined): boolean;
+export type DecisionIdentity = {
+    readonly gate: 'plan_review';
+    readonly taskId: string;
+} | {
+    readonly gate: 'tool_approval';
+    readonly approvalId?: string;
+    readonly callId?: string;
+    readonly askId?: string;
+} | {
+    readonly gate: 'elicitation';
+    readonly elicitationId: string;
+} | {
+    readonly gate: 'run';
+    readonly taskId: string;
+};
+export declare function decisionInFlightOf(identity: DecisionIdentity, readMark?: number): boolean;
+export declare function decisionReadMark(): number;
+export declare function __resetDecisionLedgerForTests(family?: DecisionLedgerFamily): void;

package/dist/hitl/decisionLedger.js

@@ -0,0 +1,156 @@
+import { guardedRead, readOwnDataNonEmptyString } from '../ownKey.js';
+export const DECISION_LEDGER_FAMILIES = Object.freeze(['plan_review', 'tool_approval', 'elicitation']);
+const FAMILY_CAPACITY = Object.freeze({ plan_review: 32, tool_approval: 64, elicitation: 64 });
+const KEY_PREFIX = Object.freeze({ run: 'run\u0000', plan: 'plan\u0000', approval: 'approval\u0000', call: 'call\u0000', ask: 'ask\u0000', elicitation: 'elicitation\u0000' });
+const nonEmpty = (v) => typeof v === 'string' && v !== '';
+export function decisionLedgerKeysOf(parts) {
+    const out = [];
+    const add = (prefix, v) => {
+        if (nonEmpty(v) && !out.includes(prefix + v))
+            out.push(prefix + v);
+    };
+    add(KEY_PREFIX.run, parts.taskId);
+    add(KEY_PREFIX.plan, parts.planTaskId);
+    add(KEY_PREFIX.approval, parts.approvalId);
+    add(KEY_PREFIX.call, parts.callId);
+    add(KEY_PREFIX.ask, parts.askId);
+    add(KEY_PREFIX.elicitation, parts.elicitationId);
+    return out;
+}
+export function planDecisionKey(taskId) {
+    return KEY_PREFIX.plan + taskId;
+}
+const ledger = Object.freeze({ plan_review: [], tool_approval: [], elicitation: [] });
+let ledgerClock = 0;
+export function nextDecisionLedgerTick() {
+    return ++ledgerClock;
+}
+export function decisionOpsWithKey(family, key) {
+    return ledger[family].filter((op) => op.keys.includes(key));
+}
+export function decisionOpsOfFamily(family) {
+    return ledger[family];
+}
+export function openDecisionOp(family, keys, phase, ownCallOpen) {
+    const op = {
+        family,
+        keys: Object.freeze([...keys]),
+        handedAt: ++ledgerClock,
+        settledAt: null,
+        settler: null,
+        phase,
+        notApplied: false,
+        ownCallOpen,
+    };
+    const rows = ledger[family];
+    rows.push(op);
+    while (rows.length > FAMILY_CAPACITY[family]) {
+        let victim = rows.findIndex((o) => o.settledAt !== null && !o.ownCallOpen);
+        if (victim < 0)
+            victim = rows.findIndex((o) => o !== op && o.phase === 'handed' && !o.ownCallOpen);
+        if (victim < 0)
+            break;
+        rows.splice(victim, 1);
+    }
+    return op;
+}
+export function settleDecisionOp(op, by) {
+    if (op.settledAt !== null)
+        return;
+    op.settledAt = ++ledgerClock;
+    op.settler = by;
+}
+export function closeDecisionOp(op, by) {
+    if (op.phase === 'posting')
+        op.phase = 'landed';
+    settleDecisionOp(op, by);
+    op.ownCallOpen = false;
+}
+export function addDecisionOpKeys(op, keys) {
+    const extra = keys.filter((k) => !op.keys.includes(k));
+    if (extra.length > 0)
+        op.keys = Object.freeze([...op.keys, ...extra]);
+}
+export function dropDecisionOp(op) {
+    const rows = ledger[op.family];
+    const i = rows.indexOf(op);
+    if (i >= 0)
+        rows.splice(i, 1);
+}
+export function markLatestDecisionNotApplied(family, key) {
+    const ops = decisionOpsWithKey(family, key);
+    if (ops.some((op) => op.settledAt === null))
+        return;
+    let latest;
+    for (const op of ops)
+        if (latest === undefined || op.handedAt > latest.handedAt)
+            latest = op;
+    if (latest !== undefined)
+        latest.notApplied = true;
+}
+export function settleDecisionOpsOnGateLeft(family, key) {
+    for (const op of decisionOpsWithKey(family, key))
+        settleDecisionOp(op, 'gate_left');
+}
+export function latestDecisionHandedMark(family, key) {
+    let mark = null;
+    for (const op of decisionOpsWithKey(family, key))
+        if (mark === null || op.handedAt > mark)
+            mark = op.handedAt;
+    return mark;
+}
+function anyInFlight(keys, mark) {
+    if (keys.length === 0)
+        return false;
+    for (const family of DECISION_LEDGER_FAMILIES) {
+        for (const op of ledger[family]) {
+            if (!op.keys.some((k) => keys.includes(k)))
+                continue;
+            if (op.settledAt === null)
+                return true;
+            if (mark !== undefined && op.settledAt > mark && !op.notApplied)
+                return true;
+        }
+    }
+    return false;
+}
+export function readMarkOf(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+export function decisionKeyInFlight(key, mark) {
+    return anyInFlight([key], mark);
+}
+function queryKeysOf(identity) {
+    if (typeof identity !== 'object' || identity === null)
+        return [];
+    const gate = guardedRead(() => readOwnDataNonEmptyString(identity, 'gate'));
+    const s = (key) => guardedRead(() => readOwnDataNonEmptyString(identity, key));
+    switch (gate) {
+        case 'plan_review':
+            return decisionLedgerKeysOf({ planTaskId: s('taskId') });
+        case 'run':
+            return decisionLedgerKeysOf({ taskId: s('taskId') });
+        case 'tool_approval':
+            return decisionLedgerKeysOf({ approvalId: s('approvalId'), callId: s('callId'), askId: s('askId') });
+        case 'elicitation':
+            return decisionLedgerKeysOf({ elicitationId: s('elicitationId') });
+        default:
+            return [];
+    }
+}
+export function decisionInFlightOf(identity, readMark) {
+    try {
+        return anyInFlight(queryKeysOf(identity), readMarkOf(readMark));
+    }
+    catch {
+        return false;
+    }
+}
+export function decisionReadMark() {
+    return ++ledgerClock;
+}
+export function __resetDecisionLedgerForTests(family) {
+    for (const f of DECISION_LEDGER_FAMILIES)
+        if (family === undefined || f === family)
+            ledger[f].length = 0;
+}

package/dist/hitl/decisionRefusal.d.ts

@@ -2,6 +2,7 @@ import { type GateCurrentPending, type HitlSafetyCode } from './hitlBridge.js';
 import { type DecisionRefusalConflict } from './decisionConflict.js';
 import { type ProtocolErrorName } from '../wireFailureShape.js';
 import { type DenyAttributionRefusalDetail } from '../wireRefusalCopy.js';
+export declare const ASK_DECIDED_CODE = "conflict.ask_decided";
 export type DecisionRefusalStanding = 'settled-elsewhere' | 'ambiguous' | 'refused-pending';
 export type { DecisionRefusalConflict } from './decisionConflict.js';
 export interface RefusalCarrier {

package/dist/hitl/decisionRefusal.js

@@ -7,7 +7,7 @@ import { readLivePendingRows } from './livePendingAsk.js';
 import { guardedRead, ownDataField, readOwnDataValue } from '../ownKey.js';
 import { PROTOCOL_ERROR_NAME, isDisplayableWireCode, protocolErrorNameReading, readErrorRecord, readRefusalField } from '../wireFailureShape.js';
 import { denyAttributionRefusalFromError } from '../wireRefusalCopy.js';
-const ASK_DECIDED_CODE = 'conflict.ask_decided';
+export const ASK_DECIDED_CODE = 'conflict.ask_decided';
 const TRANSIENT_STATUSES = new Set([408, 425, 429, 502, 503, 504]);
 export function refusalCarrierOf(err) {
     if (typeof err !== 'object' || err === null)

package/dist/hitl/decisionSend.d.ts

@@ -0,0 +1,113 @@
+import type { AgentClient, ElicitResponse } from '@sema-agent/sdk';
+import { type AskGoneDetail } from '../decideReceipt.js';
+import type { ApprovalDecidedByReading } from '../approvalDecidedByCapability.js';
+import { type DecisionNoteAudit } from './approvalDecisionNoteAudit.js';
+import { type DecisionRefusalClassified, type LiveAskPendingReading } from './decisionRefusal.js';
+import { type HostApprovalCardHold } from './approvalHolds.js';
+import { type ApprovalCardDecision, type ToolApprovalRespondAckView, type ToolApprovalRespondParkingView } from './toolApprovalWire.js';
+export declare const HITL_DECISION_FAMILIES: readonly ["approval", "ask", "elicitation"];
+export type HitlDecisionFamily = (typeof HITL_DECISION_FAMILIES)[number];
+export declare const HITL_DECISION_NOT_APPLIED_CAUSES: readonly ["gone", "parked", "parking", "lane_disabled", "refused", "idempotency_crossed"];
+export type HitlDecisionNotAppliedCause = (typeof HITL_DECISION_NOT_APPLIED_CAUSES)[number];
+export declare const HITL_DECISION_UNCONFIRMED_CAUSES: readonly ["transport", "server_error", "local_error", "aborted", "gone_after_retry"];
+export type HitlDecisionUnconfirmedCause = (typeof HITL_DECISION_UNCONFIRMED_CAUSES)[number];
+export declare const HITL_DECISION_NOT_SENT_CAUSES: readonly ["aborted", "duplicate_in_flight", "invalid_request", "no_verb", "not_an_answer"];
+export type HitlDecisionNotSentCause = (typeof HITL_DECISION_NOT_SENT_CAUSES)[number];
+export interface HitlApprovalDecisionRequest {
+    readonly family: 'approval';
+    readonly approvalId: string;
+    readonly taskId?: string;
+    readonly toolCallId?: string;
+    readonly answer: ApprovalCardDecision;
+}
+export interface HitlAskDecisionRequest {
+    readonly family: 'ask';
+    readonly taskId: string;
+    readonly askId: string;
+    readonly approvalId?: string;
+    readonly toolCallId?: string;
+    readonly answer: ApprovalCardDecision;
+}
+export interface HitlElicitationDecisionRequest {
+    readonly family: 'elicitation';
+    readonly elicitationId: string;
+    readonly taskId?: string;
+    readonly response: ElicitResponse;
+}
+export type HitlDecisionSendRequest = HitlApprovalDecisionRequest | HitlAskDecisionRequest | HitlElicitationDecisionRequest;
+export interface HitlDecisionSendClient {
+    readonly toolApprovals?: Partial<Pick<AgentClient['toolApprovals'], 'respond' | 'decideAsk'>>;
+    readonly elicitations?: Partial<Pick<AgentClient['elicitations'], 'respond'>>;
+}
+export interface HitlDecisionGate {
+    readonly family: HitlDecisionFamily;
+    readonly approvalId?: string;
+    readonly askId?: string;
+    readonly taskId?: string;
+    readonly elicitationId?: string;
+}
+export interface HitlDecisionSendDeps {
+    readonly client: HitlDecisionSendClient;
+    readonly signal?: AbortSignal;
+    readonly approvalDecisionNoteCapable?: boolean;
+    readonly approvalDecidedBy?: ApprovalDecidedByReading;
+    readonly readPending?: (gate: HitlDecisionGate, opts: {
+        readonly signal: AbortSignal;
+    }) => Promise<LiveAskPendingReading>;
+    readonly hold?: HostApprovalCardHold;
+}
+interface HitlDecisionOutcomeBase {
+    readonly family: HitlDecisionFamily;
+    readonly attempts: number;
+    readonly fallback?: 'approval';
+    readonly noteDropped?: true;
+    readonly rememberDropped?: true;
+    readonly attributionDropped?: true;
+    readonly attributionRenamed?: true;
+    readonly pending?: LiveAskPendingReading;
+}
+export interface HitlDecisionApplied extends HitlDecisionOutcomeBase {
+    readonly kind: 'applied';
+    readonly ack?: ToolApprovalRespondAckView;
+    readonly noteAudit?: DecisionNoteAudit;
+}
+export interface HitlDecisionSettledElsewhere extends HitlDecisionOutcomeBase {
+    readonly kind: 'settled_elsewhere';
+    readonly firstDecision?: 'approve' | 'deny';
+    readonly contrary?: true;
+    readonly decidedAtMs?: number;
+    readonly actorLabel?: string;
+    readonly noteAudit?: DecisionNoteAudit;
+}
+export interface HitlDecisionNotApplied extends HitlDecisionOutcomeBase {
+    readonly kind: 'not_applied';
+    readonly cause: HitlDecisionNotAppliedCause;
+    readonly errorCode?: string;
+    readonly status?: number;
+    readonly sessionId?: string;
+    readonly gone?: AskGoneDetail;
+    readonly retryAfterMs?: number;
+    readonly parking?: ToolApprovalRespondParkingView;
+    readonly refusal?: DecisionRefusalClassified;
+    readonly closesOut?: true;
+}
+export interface HitlDecisionUnconfirmed extends HitlDecisionOutcomeBase {
+    readonly kind: 'unconfirmed';
+    readonly cause: HitlDecisionUnconfirmedCause;
+    readonly status?: number;
+}
+export interface HitlDecisionNotSent extends HitlDecisionOutcomeBase {
+    readonly kind: 'not_sent';
+    readonly cause: HitlDecisionNotSentCause;
+}
+export type HitlDecisionSendOutcome = HitlDecisionApplied | HitlDecisionSettledElsewhere | HitlDecisionNotApplied | HitlDecisionUnconfirmed | HitlDecisionNotSent;
+export declare const HITL_DECISION_READBACK_BUDGET_MS = 4000;
+export interface HitlDecisionSendTiming {
+    readonly delays?: readonly number[];
+    readonly budgetMs?: number;
+    readonly parkingDelayMs?: number;
+}
+export declare function __setHitlDecisionSendTimingForTests(t?: HitlDecisionSendTiming): void;
+export declare function hitlAskIdempotencyKey(askId: string, verdict: 'approve' | 'deny'): string;
+export declare function sendHitlDecision(request: HitlDecisionSendRequest, deps: HitlDecisionSendDeps): Promise<HitlDecisionSendOutcome>;
+export {};