@sema-agent/client-core 0.99.0 → 0.100.0

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 {};