@sema-agent/client-core 0.97.1 → 0.99.0

package/dist/hitl/approvalHolds.d.ts

@@ -1,15 +1,18 @@
-import type { ApprovalHolderIdentity, FsApprovalOutcome, ToolApprovalFrameOutcome } from './toolApprovalWire.js';
+import type { ApprovalHolderIdentity } from './toolApprovalWire.js';
+import type { ApprovalResolution, ApprovalResolutionLane } from './approvalResolution.js';
 export declare const APPROVAL_SETTLED_HOWS: readonly ["answered", "interrupted", "closed_by_engine"];
 export type ApprovalSettledHow = (typeof APPROVAL_SETTLED_HOWS)[number];
 export declare const SETTLED_APPROVALS_MAX_ENTRIES = 4096;
 export interface SettledApprovalEntry {
     readonly how: ApprovalSettledHow;
     readonly parked: boolean;
-    readonly outcome: ToolApprovalFrameOutcome;
+    readonly outcome: ApprovalResolution;
 }
 export interface DurableDecisionHold {
     readonly lane: 'durable';
-    readonly outcome: Promise<FsApprovalOutcome>;
+    readonly identity: HoldIdentity;
+    phase: 'card' | 'respond';
+    readonly outcome: Promise<ApprovalResolution>;
     presented: boolean;
     readonly interrupt: () => void;
     readonly cardSignal: AbortSignal;
@@ -18,7 +21,7 @@ export interface DurableDecisionHold {
 export interface LiveCardHold {
     readonly lane: 'live';
     readonly identity: LiveCardIdentity;
-    readonly outcome: Promise<ToolApprovalFrameOutcome>;
+    readonly outcome: Promise<ApprovalResolution>;
     phase: 'card' | 'respond';
     superseded?: {
         readonly parked: boolean;
@@ -27,17 +30,47 @@ export interface LiveCardHold {
     readonly interrupt: () => void;
     trailing?: Promise<boolean>;
 }
-export type ApprovalHold = DurableDecisionHold | LiveCardHold;
-export interface LiveCardIdentity {
+export interface HostCardHold {
+    readonly lane: 'host';
+    readonly identity: HoldIdentity;
+    phase: 'card' | 'respond';
+    readonly released: Promise<'answered' | 'interrupted' | undefined>;
+}
+export type ApprovalHold = DurableDecisionHold | LiveCardHold | HostCardHold;
+export interface LiveCardIdentity extends HoldIdentity {
     readonly approvalId: string;
-    readonly toolCallId?: string;
-    readonly taskId?: string;
-    readonly sessionId?: string;
 }
-export declare function liveCardHoldFor(who: ApprovalHolderIdentity): LiveCardHold | undefined;
+export interface HoldIdentity extends ApprovalHolderIdentity {
+    readonly askSig?: string;
+}
+export declare function approvalHoldFor(who: HoldIdentity, except?: (h: ApprovalHold) => boolean): ApprovalHold | undefined;
 export declare function settledForDurableLane(entry: SettledApprovalEntry | undefined): boolean;
-export declare function liveCardAnsweredHow(o: ToolApprovalFrameOutcome): 'answered' | 'interrupted' | undefined;
-export declare function awaitLiveCardHolder(hold: LiveCardHold, signal: AbortSignal | undefined): Promise<ToolApprovalFrameOutcome | undefined>;
+export declare function liveCardAnsweredHow(r: ApprovalResolution): 'answered' | 'interrupted' | undefined;
+export type ApprovalHolderWait = {
+    readonly kind: 'settled';
+    readonly how: 'answered' | 'interrupted';
+    readonly outcome: ApprovalResolution;
+} | {
+    readonly kind: 'free';
+} | {
+    readonly kind: 'left';
+};
+export declare function awaitApprovalHolder(hold: ApprovalHold, signal: AbortSignal | undefined, asker: ApprovalResolutionLane): Promise<ApprovalHolderWait>;
+export interface HostApprovalCardHold {
+    readonly identity: ApprovalHolderIdentity;
+    sending(): void;
+    release(settled?: 'answered' | 'interrupted'): void;
+}
+export type ApprovalCardClaim = {
+    readonly kind: 'held';
+    readonly hold: HostApprovalCardHold;
+} | {
+    readonly kind: 'joined';
+    readonly outcome: ApprovalResolution;
+} | {
+    readonly kind: 'aborted';
+};
+export declare function claimApprovalCardFor(who: HoldIdentity, signal: AbortSignal | undefined): Promise<ApprovalCardClaim>;
 export interface ApprovalDecisionHoldTable {
     readonly inFlight: Map<string, ApprovalHold>;
     readonly settled: Map<string, DurableSettledHold>;
@@ -54,8 +87,10 @@ export declare function settledApprovalOf(approvalId: string | undefined): Settl
 export declare function clearSettledApprovals(): void;
 export declare function anyApprovalSettled(): boolean;
 export declare function noteEngineClosedApproval(approvalId: string, parked: boolean): void;
-export declare function settledLiveCardOutcome(approvalId: string): ToolApprovalFrameOutcome | undefined;
+export declare function settleEngineClosedApproval(frame: object, parked: boolean): boolean;
+export declare function noteHolderSettledApproval(approvalId: string, how: 'answered' | 'interrupted', outcome: ApprovalResolution): void;
+export declare function settledLiveCardOutcome(approvalId: string): ApprovalResolution | undefined;
 export declare function liveCardHoldOf(key: string): LiveCardHold | undefined;
-export declare function holdLiveCard(identity: LiveCardIdentity, callerSignal: AbortSignal | undefined, present: (hold: LiveCardHold) => Promise<ToolApprovalFrameOutcome>): Promise<ToolApprovalFrameOutcome>;
-export declare function joinLiveCard(hold: LiveCardHold, signal: AbortSignal | undefined): Promise<ToolApprovalFrameOutcome>;
+export declare function holdLiveCard(identity: LiveCardIdentity, callerSignal: AbortSignal | undefined, present: (hold: LiveCardHold) => Promise<ApprovalResolution>): Promise<ApprovalResolution>;
+export declare function joinLiveCard(hold: LiveCardHold, signal: AbortSignal | undefined): Promise<ApprovalResolution>;
 export declare function supersedeLiveCard(key: string, parked: boolean): boolean;

package/dist/hitl/approvalHolds.js

@@ -1,51 +1,179 @@
 import { hostLog } from '../host.js';
 import { liveFrameCallKey } from './gateIdentity.js';
-import { approvalResolutionOf } from './approvalResolution.js';
+import { decideReceiptReopen, readDecideReceipt } from '../decideReceipt.js';
 export const APPROVAL_SETTLED_HOWS = Object.freeze(['answered', 'interrupted', 'closed_by_engine']);
 export const SETTLED_APPROVALS_MAX_ENTRIES = 4096;
 const nonEmpty = (v) => typeof v === 'string' && v !== '';
-export function liveCardHoldFor(who) {
-    if (nonEmpty(who.approvalId))
-        return liveCardHoldOf(liveFrameCallKey(who.approvalId));
-    if (!nonEmpty(who.taskId) || !nonEmpty(who.toolCallId))
-        return undefined;
+function sameApproval(who, h) {
+    const id = h.identity;
+    if (nonEmpty(who.approvalId) && nonEmpty(id.approvalId))
+        return who.approvalId === id.approvalId;
+    if (h.phase !== 'card')
+        return false;
+    if (!nonEmpty(who.taskId) || !nonEmpty(who.toolCallId) || id.taskId !== who.taskId || id.toolCallId !== who.toolCallId)
+        return false;
+    if (nonEmpty(who.sessionId) && nonEmpty(id.sessionId) && id.sessionId !== who.sessionId)
+        return false;
+    return !(nonEmpty(who.askSig) && nonEmpty(id.askSig) && id.askSig !== who.askSig);
+}
+export function approvalHoldFor(who, except) {
     for (const h of approvalDecisionHolds.inFlight.values()) {
-        if (h.lane !== 'live' || h.phase !== 'card')
+        if (except?.(h) === true)
             continue;
-        const id = h.identity;
-        if (id.taskId !== who.taskId || id.toolCallId !== who.toolCallId)
-            continue;
-        if (nonEmpty(who.sessionId) && nonEmpty(id.sessionId) && id.sessionId !== who.sessionId)
-            continue;
-        return h;
+        if (sameApproval(who, h))
+            return h;
     }
     return undefined;
 }
 export function settledForDurableLane(entry) {
     return entry !== undefined && !entry.parked;
 }
-export function liveCardAnsweredHow(o) {
-    return answeredHowOf(approvalResolutionOf(o));
-}
-function answeredHowOf(r) {
+export function liveCardAnsweredHow(r) {
     if (r.kind === 'decided')
         return 'answered';
     return r.kind === 'unsettled' && r.cause === 'interrupted' ? 'interrupted' : undefined;
 }
-export async function awaitLiveCardHolder(hold, signal) {
+const HOLDER_FREE = Object.freeze({ kind: 'free' });
+function nothingSentHere(asker) {
+    return Object.freeze({ kind: 'not_sent', lane: asker, cause: 'retracted' });
+}
+function interruptedThere(asker) {
+    return Object.freeze({ kind: 'unsettled', lane: asker, cause: 'interrupted' });
+}
+export async function awaitApprovalHolder(hold, signal, asker) {
+    if (hold.lane === 'host')
+        return awaitHostHolder(hold, signal, asker);
     const unsubscribe = followCallerSignal(signal, hold.interrupt);
-    let o;
     try {
-        o = await hold.outcome;
+        if (hold.lane === 'live') {
+            let o;
+            try {
+                o = await hold.outcome;
+            }
+            catch {
+                return HOLDER_FREE;
+            }
+            const stillHeld = approvalDecisionHolds.inFlight.get(liveFrameCallKey(hold.identity.approvalId)) === hold;
+            const entry = settledApprovalOf(hold.identity.approvalId);
+            if (!stillHeld && !settledForDurableLane(entry))
+                return HOLDER_FREE;
+            return Object.freeze({ kind: 'settled', how: entry?.how === 'answered' ? 'answered' : 'interrupted', outcome: o });
+        }
+        let r;
+        try {
+            r = await hold.outcome;
+        }
+        catch {
+            return HOLDER_FREE;
+        }
+        if (r.kind === 'decided') {
+            if (decideReceiptReopen(r.receipt) !== null)
+                return HOLDER_FREE;
+            return Object.freeze({ kind: 'settled', how: 'answered', outcome: r });
+        }
+        if (r.kind !== 'unsettled' || r.cause !== 'interrupted' || hold.trailing === undefined)
+            return HOLDER_FREE;
+        const landed = await hold.trailing.then((raw) => decideReceiptReopen(readDecideReceipt(raw)) === null, () => false);
+        return landed ? Object.freeze({ kind: 'settled', how: 'interrupted', outcome: r }) : HOLDER_FREE;
+    }
+    finally {
+        unsubscribe();
+    }
+}
+async function awaitHostHolder(hold, signal, asker) {
+    let leave = () => { };
+    const left = new Promise((resolve) => {
+        leave = () => resolve('left');
+    });
+    const unsubscribe = followCallerSignal(signal, leave);
+    try {
+        const r = await Promise.race([hold.released, left]);
+        if (r === 'left')
+            return Object.freeze({ kind: 'left' });
+        if (r === undefined)
+            return HOLDER_FREE;
+        return Object.freeze({ kind: 'settled', how: r, outcome: r === 'interrupted' ? interruptedThere(asker) : nothingSentHere(asker) });
+    }
+    finally {
+        unsubscribe();
+    }
+}
+function holdHostCard(identity, signal) {
+    const h = approvalDecisionHolds;
+    const key = `hitl-host:${++h.clock}`;
+    let resolveReleased = () => { };
+    const released = new Promise((resolve) => {
+        resolveReleased = resolve;
+    });
+    const frozen = Object.freeze({ ...identity });
+    const hold = { lane: 'host', identity: frozen, phase: 'card', released };
+    h.inFlight.set(key, hold);
+    let done = false;
+    let stopFollowing = () => { };
+    const release = (settled) => {
+        if (done)
+            return;
+        done = true;
+        stopFollowing();
+        const how = settled === 'answered' || settled === 'interrupted' ? settled : undefined;
+        if (how !== undefined && nonEmpty(frozen.approvalId))
+            noteSettled(frozen.approvalId, how, false, how === 'interrupted' ? interruptedThere('decide') : nothingSentHere('decide'), true);
+        if (h.inFlight.get(key) === hold)
+            h.inFlight.delete(key);
+        resolveReleased(how);
+    };
+    const handle = Object.freeze({
+        identity: frozen,
+        sending: () => {
+            if (done)
+                return;
+            hold.phase = 'respond';
+            stopFollowing();
+        },
+        release,
+    });
+    stopFollowing = followCallerSignal(signal, () => {
+        if (!done && hold.phase === 'card')
+            release();
+    });
+    return handle;
+}
+function callerSignalAborted(signal) {
+    if (signal === undefined || signal === null)
+        return false;
+    try {
+        return signal.aborted === true;
     }
     catch {
-        return undefined;
+        return false;
+    }
+}
+export async function claimApprovalCardFor(who, signal) {
+    let leave = () => { };
+    const left = new Promise((resolve) => {
+        leave = () => resolve('aborted');
+    });
+    const unsubscribe = followCallerSignal(signal, leave);
+    try {
+        for (;;) {
+            if (callerSignalAborted(signal))
+                return Object.freeze({ kind: 'aborted' });
+            const entry = settledApprovalOf(who.approvalId);
+            if (settledForDurableLane(entry) && entry !== undefined)
+                return Object.freeze({ kind: 'joined', outcome: { ...entry.outcome, joinedInFlight: true } });
+            const holder = approvalHoldFor(who);
+            if (holder === undefined)
+                return Object.freeze({ kind: 'held', hold: holdHostCard(who, signal) });
+            const wait = await Promise.race([awaitApprovalHolder(holder, undefined, 'decide'), left]);
+            if (wait === 'aborted')
+                return Object.freeze({ kind: 'aborted' });
+            if (wait.kind === 'settled')
+                return Object.freeze({ kind: 'joined', outcome: { ...wait.outcome, joinedInFlight: true } });
+        }
     }
     finally {
         unsubscribe();
     }
-    const stillHeld = approvalDecisionHolds.inFlight.get(liveFrameCallKey(hold.identity.approvalId)) === hold;
-    return stillHeld || settledForDurableLane(settledApprovalOf(hold.identity.approvalId)) ? { ...o, joinedInFlight: true } : undefined;
 }
 export const approvalDecisionHolds = { inFlight: new Map(), settled: new Map(), openReads: new Set(), outcomes: new Map(), clock: 0 };
 export function settledApprovalOf(approvalId) {
@@ -57,14 +185,17 @@ export function clearSettledApprovals() {
 export function anyApprovalSettled() {
     return approvalDecisionHolds.outcomes.size > 0;
 }
-function noteSettled(approvalId, how, parked, outcome) {
+function noteSettled(approvalId, how, parked, outcome, upgradesParked = false) {
     if (typeof approvalId !== 'string' || approvalId === '')
         return;
     if (!APPROVAL_SETTLED_HOWS.includes(how))
         return;
     const t = approvalDecisionHolds.outcomes;
-    if (t.has(approvalId))
+    const prev = t.get(approvalId);
+    if (prev !== undefined && !(upgradesParked && prev.parked && how !== 'closed_by_engine'))
         return;
+    if (prev !== undefined)
+        t.delete(approvalId);
     t.set(approvalId, Object.freeze({ how, parked, outcome: Object.freeze({ ...outcome }) }));
     while (t.size > SETTLED_APPROVALS_MAX_ENTRIES) {
         const oldest = t.keys().next();
@@ -73,9 +204,28 @@ function noteSettled(approvalId, how, parked, outcome) {
         t.delete(oldest.value);
     }
 }
-const ENGINE_CLOSED_OUTCOME = Object.freeze({ decision: 'unresolved', retracted: true });
+function engineClosedOutcome() {
+    return Object.freeze({ kind: 'not_sent', lane: 'respond', cause: 'retracted' });
+}
 export function noteEngineClosedApproval(approvalId, parked) {
-    noteSettled(approvalId, 'closed_by_engine', parked, ENGINE_CLOSED_OUTCOME);
+    noteSettled(approvalId, 'closed_by_engine', parked, engineClosedOutcome());
+}
+export function settleEngineClosedApproval(frame, parked) {
+    let id;
+    try {
+        const d = typeof frame === 'object' && frame !== null ? Object.getOwnPropertyDescriptor(frame, 'approvalId') : undefined;
+        id = d !== undefined && Object.hasOwn(d, 'value') ? d.value : undefined;
+    }
+    catch {
+        return false;
+    }
+    if (!nonEmpty(id))
+        return false;
+    noteEngineClosedApproval(id, parked);
+    return supersedeLiveCard(liveFrameCallKey(id), parked);
+}
+export function noteHolderSettledApproval(approvalId, how, outcome) {
+    noteSettled(approvalId, how, false, outcome, true);
 }
 export function settledLiveCardOutcome(approvalId) {
     const e = settledApprovalOf(approvalId);

package/dist/hitl/approvalResolution.d.ts

@@ -1,36 +1,61 @@
 import type { DecideReceiptView } from '../decideReceipt.js';
-import type { HitlSafetyCode } from './hitlBridge.js';
-import type { FsApprovalOutcome, ToolApprovalFrameOutcome, ToolApprovalRespondAckView, ToolApprovalRespondDecision, ToolApprovalRespondParkingView } from './toolApprovalWire.js';
-export declare const APPROVAL_NOT_SENT_CAUSES: readonly ["retracted", "edit_refused", "no_pending", "fetch_failed", "no_input", "card_unavailable"];
+import { type HitlSafetyCode } from './hitlBridge.js';
+import type { AskAnsweredOutput } from './gateLedger.js';
+import type { ApprovalDenySettledBy, ToolApprovalRespondAckView, ToolApprovalRespondDecision, ToolApprovalRespondParkingView } from './toolApprovalWire.js';
+import { type DecisionRefusalReading, type RefusalRouteContext } from './decisionRefusal.js';
+export declare const APPROVAL_RESOLUTION_LANES: readonly ["respond", "decide", "ask"];
+export type ApprovalResolutionLane = (typeof APPROVAL_RESOLUTION_LANES)[number];
+export declare const APPROVAL_NOT_SENT_CAUSES: readonly ["retracted", "edit_refused", "no_pending", "wrong_gate", "fetch_failed", "no_input", "card_unavailable", "safety_stop"];
 export type ApprovalNotSentCause = (typeof APPROVAL_NOT_SENT_CAUSES)[number];
-export declare const APPROVAL_UNSETTLED_CAUSES: readonly ["engine_refused", "decide_failed", "transport_exhausted", "safety_stop", "respond_failed", "parking_in_progress", "interrupted", "orchestration", "unreadable"];
+export declare const APPROVAL_UNSETTLED_CAUSES: readonly ["engine_refused", "engine_error", "no_answer", "transport_exhausted", "parking_in_progress", "interrupted", "orchestration", "unreadable"];
 export type ApprovalUnsettledCause = (typeof APPROVAL_UNSETTLED_CAUSES)[number];
-export interface ApprovalResolutionDecided {
-    kind: 'decided';
-    decision: ToolApprovalRespondDecision;
-    gatedCallId?: string;
-    receipt?: DecideReceiptView;
-    ack?: ToolApprovalRespondAckView;
+export interface ApprovalDenyFacts {
+    readonly settledBy?: ApprovalDenySettledBy;
+    readonly reason?: string;
+    readonly attributionKey?: 'dropped' | 'renamed';
 }
-export interface ApprovalResolutionNotSent {
-    kind: 'not_sent';
-    cause: ApprovalNotSentCause;
-    gatedCallId?: string;
-    detail?: string;
+interface ApprovalResolutionBase {
+    readonly lane: ApprovalResolutionLane;
+    readonly gatedCallId?: string;
+    readonly joinedInFlight?: true;
 }
-export interface ApprovalResolutionUnsettled {
-    kind: 'unsettled';
-    cause: ApprovalUnsettledCause;
-    gatedCallId?: string;
-    safetyCode?: HitlSafetyCode;
-    errorCode?: string;
-    status?: number;
-    detail?: string;
-    parking?: ToolApprovalRespondParkingView;
+export interface ApprovalResolutionDecided extends ApprovalResolutionBase {
+    readonly kind: 'decided';
+    readonly decision: ToolApprovalRespondDecision;
+    readonly deny?: ApprovalDenyFacts;
+    readonly receipt?: DecideReceiptView;
+    readonly ack?: ToolApprovalRespondAckView;
+    readonly answered?: AskAnsweredOutput;
+}
+export interface ApprovalResolutionNotSent extends ApprovalResolutionBase {
+    readonly kind: 'not_sent';
+    readonly cause: ApprovalNotSentCause;
+    readonly safetyCode?: Exclude<HitlSafetyCode, 'binding_mismatch' | 'no_pending' | 'wrong_gate'>;
+    readonly detail?: string;
+}
+export interface ApprovalResolutionUnsettled extends ApprovalResolutionBase {
+    readonly kind: 'unsettled';
+    readonly cause: ApprovalUnsettledCause;
+    readonly safetyCode?: 'binding_mismatch';
+    readonly refusal?: DecisionRefusalReading;
+    readonly parking?: ToolApprovalRespondParkingView;
+    readonly detail?: string;
 }
 export type ApprovalResolution = ApprovalResolutionDecided | ApprovalResolutionNotSent | ApprovalResolutionUnsettled;
-export type ApprovalLegOutcome = FsApprovalOutcome | ToolApprovalFrameOutcome;
-export declare function approvalResolutionOf(outcome: ApprovalLegOutcome): ApprovalResolution;
 export declare function isApprovalDecided(r: ApprovalResolution): r is ApprovalResolutionDecided;
 export declare function approvalNotSentCause(r: ApprovalResolution): ApprovalNotSentCause | undefined;
 export declare function approvalUnsettledCause(r: ApprovalResolution): ApprovalUnsettledCause | undefined;
+export declare const APPROVAL_NOTE_RETRACTED_DETAIL = "the card was retracted (this host no longer has a decision port for it)";
+export declare const APPROVAL_NOTE_EDIT_REFUSED_DETAIL = "edits are not accepted on this card";
+export declare function approvalResolutionDetail(r: ApprovalResolution): string | undefined;
+export declare function unsettledCauseOfReading(reading: DecisionRefusalReading): 'engine_refused' | 'engine_error' | 'no_answer';
+export interface DecisionFailureMint {
+    readonly lane: ApprovalResolutionLane;
+    readonly route: NonNullable<RefusalRouteContext['route']>;
+    readonly gatedCallId?: string | undefined;
+    readonly detail?: string | undefined;
+    readonly attributionCarried?: boolean | undefined;
+}
+export declare function resolutionOfDecisionFailure(e: {} | null | undefined, m: DecisionFailureMint): ApprovalResolution;
+export declare function joinedResolution(r: ApprovalResolution, gatedCallId?: string): ApprovalResolution;
+export {};