@sema-agent/client-core 0.109.0 → 0.111.0

package/dist/hitl/planReviewWire.js

@@ -150,6 +150,22 @@ export function planReviewCardViewOf(frame, lang) {
         return Object.freeze({ options: OPTIONS_BY_SHAPE.withheld, note: renderMessage(planReviewUnreadableNoteRef(), lang) });
     }
 }
+export function planReviewEvidenceMovedOf(shown, latest) {
+    try {
+        const a = planReviewCardFactsFrom(shown);
+        const b = planReviewCardFactsFrom(latest);
+        if (a === undefined || b === undefined || a.taskId !== b.taskId)
+            return 'unknown';
+        if (a.checkpointId !== undefined && b.checkpointId !== undefined && a.checkpointId !== b.checkpointId)
+            return 'moved';
+        if (a.evidenceRevision === undefined || b.evidenceRevision === undefined)
+            return 'unknown';
+        return a.evidenceRevision === b.evidenceRevision ? 'same' : 'moved';
+    }
+    catch {
+        return 'unknown';
+    }
+}
 export function notePlanReviewAnsweredIfDecisive(questionId, answer) {
     notePlanReviewAnsweredIfDecisiveFor(DEFAULT_SESSION_KEY, questionId, answer);
 }
@@ -498,11 +514,15 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
         armedPlanReviews.set(taskId, instance);
         armedTaskId = taskId;
         let unregister = () => { };
+        const onWithdraw = () => {
+            hostLog('debug', `planReviewWire: card-withdrawn-by-host task=${taskId} card=${questionId}`);
+            retireArmedPlanReview(taskId, instance);
+        };
         const responder = async (_id, answer) => {
             const choice = planReviewAnswerChoiceOf(questionId, answer);
             if (choice === 'inadmissible') {
                 if (armedPlanReviews.get(taskId) === instance && !hasLocalQuestionResponder(questionId))
-                    unregister = registerLocalQuestionResponder(questionId, responder);
+                    unregister = registerLocalQuestionResponder(questionId, responder, onWithdraw);
                 hostLog('debug', `planReviewWire: answer-inadmissible card=${questionId}`);
                 return { ok: false, inadmissible: true };
             }
@@ -520,10 +540,10 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
             const cardDelivery = cardReason !== undefined ? { ...delivery, reason: cardReason } : delivery;
             notePlanReviewAnswered(questionId);
             hostLog('debug', `planReviewWire: arm responder delivering ${decided} for task ${taskId} (path=arm)`);
-            void decidePlanReviewFor(taskId, decided, modeAfter, cardDelivery, facts);
+            void decidePlanReviewFor(taskId, decided, modeAfter, cardDelivery, facts, questionId);
             return { ok: true };
         };
-        unregister = registerLocalQuestionResponder(questionId, responder);
+        unregister = registerLocalQuestionResponder(questionId, responder, onWithdraw);
         publishArmedPlanReviewCard(instance);
         hostLog('debug', `planReviewWire: approval card armed for parked plan (task ${taskId})`);
     }
@@ -721,7 +741,7 @@ function askAgainReasonOf(card, opts) {
         return renderMessage(msg('approval.planReview.askAgain.unknown'), DATA_FACE_LANGUAGE);
     }
 }
-async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts, card) {
+async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts, card, cardId) {
     if (typeof taskId === 'string' && planReviewOpsOf(taskId).some((op) => op.phase === 'posting')) {
         hostLog('error', `planReviewWire: decidePlanReview(${decision}) for task ${taskId} REFUSED — a decision for this task is already in flight (duplicate delivery latched)`);
         return;
@@ -754,7 +774,7 @@ async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts,
     try {
         const wireDecision = decision === 'ask_again' ? 'reject' : decision;
         const wireOpts = decision === 'ask_again' ? { ...opts, reason: askAgainReasonOf(card, opts) } : opts;
-        await decidePlanReviewInner(taskId, wireDecision, permissionModeAfter, dispatchNo, releaseLatch, settle, wireOpts, card, decision);
+        await decidePlanReviewInner(taskId, wireDecision, permissionModeAfter, dispatchNo, releaseLatch, settle, wireOpts, card, decision, cardId);
     }
     finally {
         releaseLatch();
@@ -775,7 +795,7 @@ function planReviewClientsFor(resolved) {
         repull: () => resolved.make({ timeoutMs: 15_000 }),
     };
 }
-async function decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch, settle, opts, card, semanticDecision) {
+async function decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch, settle, opts, card, semanticDecision, cardId) {
     let outcome;
     let decisionReason;
     const gateBefore = card?.checkpointId;
@@ -1015,7 +1035,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
     const onOutcome = opts?.onOutcome;
     settle(effect === 'not_sent' || effect === 'still_parked');
     try {
-        const delivered = enqueuePlanReviewOutcome(prompt, { taskId, dispatchNo, decision: semanticDecision, effect, ...(effect === 'still_parked' && stillParkedCause !== undefined ? { cause: stillParkedCause } : {}) });
+        const delivered = enqueuePlanReviewOutcome(prompt, { taskId, dispatchNo, decision: semanticDecision, effect, ...(effect === 'still_parked' && stillParkedCause !== undefined ? { cause: stillParkedCause } : {}), ...(cardId !== undefined ? { questionId: cardId } : {}) });
         if (!delivered) {
             if (onOutcome !== undefined) {
                 hostLog('debug', `planReviewWire: outcome queue port not installed for task ${taskId} — outcome handed to the host's onOutcome callback only`);
@@ -1035,6 +1055,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
             decision: semanticDecision,
             effect,
             ...(effect === 'still_parked' && stillParkedCause !== undefined ? { cause: stillParkedCause } : {}),
+            ...(cardId !== undefined ? { questionId: cardId } : {}),
             detail: outcome,
             tail,
             prompt,
@@ -1156,15 +1177,21 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs, taken) {
         ((tid, decision, reason, card) => {
             hostLog('debug', `planReviewWire: reopen responder delivering ${decision} for task ${tid} (path=reopen-default)`);
             const withReason = reason === undefined ? delivery : { ...delivery, reason };
-            void decidePlanReviewFor(tid, decision, undefined, withReason, card);
+            void decidePlanReviewFor(tid, decision, undefined, withReason, card, questionId);
         });
     const activeKey = `${sessionKey}\u0000${canonicalId}`;
     let unregister = () => { };
+    const onWithdraw = () => {
+        hostLog('debug', `planReviewWire: card-withdrawn-by-host task=${taskId} card=${questionId}`);
+        if (activeReopenResponders.get(activeKey)?.questionId === questionId)
+            activeReopenResponders.delete(activeKey);
+        publishQuestionFrameFor(sessionKey, { type: 'question_complete', questionId });
+    };
     const responder = async (_id, answer) => {
         const choice = planReviewAnswerChoiceOf(questionId, answer);
         if (choice === 'inadmissible') {
             if (activeReopenResponders.get(activeKey)?.questionId === questionId && !hasLocalQuestionResponder(questionId)) {
-                unregister = registerLocalQuestionResponder(questionId, responder);
+                unregister = registerLocalQuestionResponder(questionId, responder, onWithdraw);
             }
             hostLog('debug', `planReviewWire: answer-inadmissible card=${questionId}`);
             return { ok: false, inadmissible: true };
@@ -1190,7 +1217,7 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs, taken) {
         return { ok: true };
     };
     const shape = cardShapeOf(facts, false);
-    unregister = registerLocalQuestionResponder(questionId, responder);
+    unregister = registerLocalQuestionResponder(questionId, responder, onWithdraw);
     activeReopenResponders.set(activeKey, { questionId, unregister: () => unregister(), shape });
     const receipt = waitForGateArmedFor(sessionKey, [questionId], receiptMs);
     publishQuestionFrameFor(sessionKey, planReviewQuestionFrame(questionId, REOPEN_QUESTION, shape, facts));

package/dist/hitl/policyDenyCause.d.ts

@@ -1,3 +1,3 @@
-export declare const POLICY_DENY_CAUSES: readonly ["no_approval_ui", "dont_ask", "deny_rule", "engine_floor"];
+export declare const POLICY_DENY_CAUSES: readonly ["no_approval_ui", "dont_ask", "deny_rule", "engine_floor", "hook"];
 export type PolicyDenyCause = (typeof POLICY_DENY_CAUSES)[number];
 export declare function readPolicyDenyCause(decision: object | null | undefined): PolicyDenyCause | undefined;

package/dist/hitl/policyDenyCause.js

@@ -1,4 +1,4 @@
-export const POLICY_DENY_CAUSES = Object.freeze(['no_approval_ui', 'dont_ask', 'deny_rule', 'engine_floor']);
+export const POLICY_DENY_CAUSES = Object.freeze(['no_approval_ui', 'dont_ask', 'deny_rule', 'engine_floor', 'hook']);
 export function readPolicyDenyCause(decision) {
     if (decision === null || typeof decision !== 'object')
         return undefined;

package/dist/hitl/resumeRunningCard.d.ts

@@ -21,6 +21,7 @@ export declare function runningAttachOffered(canAttach: boolean | undefined): bo
 export declare function resumeRunningOptions(i: ResumeRunningCardInput): ResumeRunningCardOption[];
 export declare function resumeChoiceFromLabels(selected: readonly string[] | null | undefined): ResumeRunningChoice;
 export declare const RESUME_RUNNING_NO_UI_EXIT_CODE = 75;
+export declare const ENGINE_UNAVAILABLE_EXIT_CODE = 69;
 export declare const RESUME_RUNNING_GUIDANCE_TAG = "sema: resume-running:";
 export declare function resumeRunningNoUiGuidance(i: {
     taskId: string;

package/dist/hitl/resumeRunningCard.js

@@ -50,6 +50,7 @@ export function resumeChoiceFromLabels(selected) {
     return 'background';
 }
 export const RESUME_RUNNING_NO_UI_EXIT_CODE = 75;
+export const ENGINE_UNAVAILABLE_EXIT_CODE = 69;
 export const RESUME_RUNNING_GUIDANCE_TAG = 'sema: resume-running:';
 export function resumeRunningNoUiGuidance(i) {
     const sid = typeof i.sessionId === 'string' && i.sessionId.length > 0 ? i.sessionId : null;

package/dist/hitl/screenCardCarriers.d.ts

@@ -0,0 +1,15 @@
+export declare const PARK_GATE_KEY = "_sema_parkGate";
+export declare function sourceGenerationNow(deps: {
+    readonly engineGeneration?: () => number;
+} | null | undefined): number | undefined;
+export declare function parkQuestionFrameBits(taskId: string, gatedCallId: string | undefined, sourceGeneration: number | undefined): {
+    readonly _sema_parkGate?: {
+        readonly taskId: string;
+        readonly gatedCallId: string;
+    };
+    readonly _sema_sourceGeneration?: number;
+};
+export declare function sourceGenerationBit(sourceGeneration: number | undefined): {
+    readonly sourceGeneration?: number;
+};
+export declare function questionFrameSourceGenerationOf(frame: object | null | undefined): number | undefined;

package/dist/hitl/screenCardCarriers.js

@@ -0,0 +1,41 @@
+import { slotReadOf } from '../wireFailureShape.js';
+import { engineGenerationReadingOf } from '../engineGenerationPort.js';
+export const PARK_GATE_KEY = '_sema_parkGate';
+const SOURCE_GENERATION_KEY = '_sema_sourceGeneration';
+const nonEmpty = (v) => typeof v === 'string' && v.length > 0;
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+export function sourceGenerationNow(deps) {
+    try {
+        if (typeof deps !== 'object' || deps === null)
+            return undefined;
+        const read = deps.engineGeneration;
+        if (typeof read !== 'function')
+            return undefined;
+        const r = engineGenerationReadingOf(() => read.call(deps));
+        return r.known ? r.generation : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parkQuestionFrameBits(taskId, gatedCallId, sourceGeneration) {
+    return {
+        ...(nonEmpty(taskId) && nonEmpty(gatedCallId) ? { _sema_parkGate: Object.freeze({ taskId, gatedCallId }) } : {}),
+        ...(finite(sourceGeneration) ? { _sema_sourceGeneration: sourceGeneration } : {}),
+    };
+}
+export function sourceGenerationBit(sourceGeneration) {
+    return finite(sourceGeneration) ? { sourceGeneration } : {};
+}
+export function questionFrameSourceGenerationOf(frame) {
+    try {
+        if (typeof frame !== 'object' || frame === null)
+            return undefined;
+        const r = slotReadOf(frame, SOURCE_GENERATION_KEY);
+        const v = r.presence === 'present' ? r.value : undefined;
+        return finite(v) ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/hitl/screenDecisionCards.d.ts

@@ -0,0 +1,98 @@
+import { type ScreenCardOrigin } from './gateIdentity.js';
+import { type EndedGenerationOpenedCall, type EndedGenerationPhaseChange, type EndedGenerationPhaseHold } from '../engineGenerationConvergence.js';
+import type { HostWithdrawal } from './hostWithdrawal.js';
+export type ScreenCardGate = {
+    readonly kind: 'tool';
+    readonly taskId: string;
+    readonly gatedCallId: string;
+} | {
+    readonly kind: 'plan';
+    readonly taskId: string;
+    readonly checkpointId?: string;
+};
+export interface ScreenCardWindow {
+    readonly leftMs?: number;
+    readonly closedByEngine?: boolean;
+}
+export interface ScreenDecisionCard {
+    readonly instance: string;
+    readonly origin?: ScreenCardOrigin;
+    readonly gate?: ScreenCardGate;
+    readonly sourceGeneration?: number;
+    readonly toolCallId?: string;
+    readonly window?: ScreenCardWindow;
+}
+export declare const SCREEN_CARD_KEEP_REASONS: readonly ["not-ready", "generation-moved", "not-withdrawable", "no-gate", "not-early", "no-row", "not-owned", "verdict-ok", "verdict-absent"];
+export type ScreenCardKeepReason = (typeof SCREEN_CARD_KEEP_REASONS)[number];
+export interface EngineGenerationEndedCardFacts {
+    readonly phase: 'ended';
+    readonly endedGeneration: number;
+    readonly cards: readonly ScreenDecisionCard[];
+    readonly opened: readonly EndedGenerationOpenedCall[];
+    readonly phases?: readonly EndedGenerationPhaseHold[];
+}
+export interface EngineGenerationReadyCardFacts<R extends object> {
+    readonly phase: 'ready';
+    readonly generation: number;
+    readonly ready: boolean;
+    readonly readGeneration: number;
+    readonly cards: readonly ScreenDecisionCard[];
+    readonly rows: readonly R[];
+    readonly isOwned: (row: R) => boolean;
+    readonly withdrawable: readonly ScreenCardOrigin[];
+}
+export interface EngineGenerationEndedCardPlan {
+    readonly phase: 'ended';
+    readonly retract: readonly string[];
+    readonly phases: readonly EndedGenerationPhaseChange[];
+}
+export interface ScreenCardWithdrawal<R extends object> {
+    readonly instance: string;
+    readonly origin: ScreenCardOrigin;
+    readonly row: R;
+    readonly withdrawal: HostWithdrawal;
+}
+export interface ScreenCardKeep {
+    readonly instance: string;
+    readonly why: ScreenCardKeepReason;
+}
+export interface EngineGenerationReadyCardPlan<R extends object> {
+    readonly phase: 'ready';
+    readonly withdraw: readonly ScreenCardWithdrawal<R>[];
+    readonly keep: readonly ScreenCardKeep[];
+}
+export interface EngineGenerationCardRecheckDueFacts {
+    readonly generation: number;
+    readonly ready: boolean;
+    readonly cards: readonly ScreenDecisionCard[];
+    readonly withdrawable: readonly ScreenCardOrigin[];
+}
+export declare function questionFrameGateOf(frame: object | null | undefined): ScreenCardGate | undefined;
+export declare function approvalCardGateOf(card: object | null | undefined): ScreenCardGate | undefined;
+export declare function approvalCardOriginOf(card: object | null | undefined): 'live-approval' | 'park-approval';
+export declare function screenCardsHoldEngineDecision(cards: readonly {
+    readonly origin?: ScreenCardOrigin;
+}[] | null | undefined): boolean;
+export declare function engineGenerationCardPlan(facts: EngineGenerationEndedCardFacts): EngineGenerationEndedCardPlan;
+export declare function engineGenerationCardPlan<R extends object>(facts: EngineGenerationReadyCardFacts<R>): EngineGenerationReadyCardPlan<R>;
+export declare function engineGenerationCardRecheckDue(facts: EngineGenerationCardRecheckDueFacts): boolean;
+export interface ScreenCardGoldenRow {
+    readonly taskId?: string;
+    readonly toolCallId?: string;
+    readonly boundCallId?: string;
+    readonly checkpointId?: string;
+    readonly rowVerdict?: ScreenCardGoldenRowVerdict;
+    readonly owned: boolean;
+}
+export interface ScreenCardGoldenRowVerdict {
+    readonly kind: string;
+    readonly code?: string;
+    readonly reason?: string;
+    readonly sentence?: string;
+}
+export interface EngineGenerationCardPlanGoldenCase {
+    readonly name: string;
+    readonly facts: EngineGenerationEndedCardFacts | Omit<EngineGenerationReadyCardFacts<ScreenCardGoldenRow>, 'isOwned'>;
+    readonly plan: EngineGenerationEndedCardPlan | EngineGenerationReadyCardPlan<ScreenCardGoldenRow>;
+}
+export declare const ENGINE_GENERATION_CARD_PLAN_GOLDEN: readonly EngineGenerationCardPlanGoldenCase[];