@sema-agent/client-core 0.94.0 → 0.96.0

package/dist/generated/engineNoticeTables.js

@@ -14,7 +14,7 @@ export const CORE_ENGINE_NOTICE_CODES = Object.freeze([
     "config.artifact_host_invalid",
     "config.task_root_not_canonical",
     "config.write_protection_target_view_absent",
-    "config.write_protection_unresolved",
+    "config.path_view_unresolved",
     "config.execution_env_capability_invalid",
     "config.tool_card_undeclared",
     "config.tool_face_undeclared",
@@ -66,6 +66,9 @@ export const CORE_ENGINE_NOTICE_CODES = Object.freeze([
     "route.base_url_changed_key_unchanged",
     "route.response_model_mismatch",
     "route.tool_call_id_folded",
+    "route.finish_reason_unknown",
+    "route.stream_end_ignored",
+    "route.extra_body_reserved_dropped",
     "context.tool_turn_repaired",
     "task.user_steer_undrained",
     "task.user_followup_undrained",
@@ -103,7 +106,7 @@ export const CORE_NOTICE_AUDIENCE = Object.freeze({
     "config.artifact_host_invalid": "operator",
     "config.task_root_not_canonical": "operator",
     "config.write_protection_target_view_absent": "operator",
-    "config.write_protection_unresolved": "operator",
+    "config.path_view_unresolved": "operator",
     "config.execution_env_capability_invalid": "operator",
     "config.tool_card_undeclared": "operator",
     "config.tool_face_undeclared": "operator",
@@ -155,6 +158,9 @@ export const CORE_NOTICE_AUDIENCE = Object.freeze({
     "route.base_url_changed_key_unchanged": "operator",
     "route.response_model_mismatch": "operator",
     "route.tool_call_id_folded": "operator",
+    "route.finish_reason_unknown": "user",
+    "route.stream_end_ignored": "user",
+    "route.extra_body_reserved_dropped": "operator",
     "context.tool_turn_repaired": "operator",
     "task.user_steer_undrained": "user",
     "task.user_followup_undrained": "user",
@@ -198,7 +204,7 @@ export const CORE_NOTICE_MINTER = Object.freeze({
     "config.artifact_host_invalid": "engine",
     "config.task_root_not_canonical": "engine",
     "config.write_protection_target_view_absent": "engine",
-    "config.write_protection_unresolved": "engine",
+    "config.path_view_unresolved": "engine",
     "config.execution_env_capability_invalid": "engine",
     "config.tool_card_undeclared": "engine",
     "config.tool_face_undeclared": "engine",
@@ -250,6 +256,9 @@ export const CORE_NOTICE_MINTER = Object.freeze({
     "route.base_url_changed_key_unchanged": "engine",
     "route.response_model_mismatch": "engine",
     "route.tool_call_id_folded": "engine",
+    "route.finish_reason_unknown": "engine",
+    "route.stream_end_ignored": "engine",
+    "route.extra_body_reserved_dropped": "engine",
     "context.tool_turn_repaired": "engine",
     "task.user_steer_undrained": "engine",
     "task.user_followup_undrained": "engine",

package/dist/generated/sdkFactTables.d.ts

@@ -1,3 +1,5 @@
 export declare const SDK_ABORT_CAUSES: readonly ["client_disconnected", "ask_park_grace_exhausted", "cancel_verb"];
 export declare const SDK_STATUS_DERIVED_COARSE_CODES: readonly ["request.rejected", "auth.unauthorized", "auth.forbidden", "not_found.resource", "request.payload_too_large", "request.unprocessable", "limit.rate_exceeded", "capability.unavailable", "internal.error"];
 export declare const SDK_DENY_REASON_ROUTING_FAILURE: "routing_failure_fail_closed";
+export declare const SDK_ASK_ROW_ENDING_CAUSES: readonly ["routing_failure_fail_closed", "run_cancelled", "run_exited", "batch_aborted", "batch_sibling_withdrawn", "batch_bound_elsewhere", "adhoc_leg_no_durable_domain", "orphan_ttl_exceeded", "crashed_before_park", "shutdown_before_park"];
+export declare const SDK_RUN_DEATH_VERDICT_CODES: readonly ["run.stalled", "run.orphaned", "approval.expired"];

package/dist/generated/sdkFactTables.js

@@ -15,3 +15,20 @@ export const SDK_STATUS_DERIVED_COARSE_CODES = Object.freeze([
     "internal.error",
 ]);
 export const SDK_DENY_REASON_ROUTING_FAILURE = "routing_failure_fail_closed";
+export const SDK_ASK_ROW_ENDING_CAUSES = Object.freeze([
+    "routing_failure_fail_closed",
+    "run_cancelled",
+    "run_exited",
+    "batch_aborted",
+    "batch_sibling_withdrawn",
+    "batch_bound_elsewhere",
+    "adhoc_leg_no_durable_domain",
+    "orphan_ttl_exceeded",
+    "crashed_before_park",
+    "shutdown_before_park",
+]);
+export const SDK_RUN_DEATH_VERDICT_CODES = Object.freeze([
+    "run.stalled",
+    "run.orphaned",
+    "approval.expired",
+]);

package/dist/generated/settingsSchemaFns.d.ts

@@ -0,0 +1,13 @@
+export declare const SETTINGS_AT_MENTION_MODES: readonly ["all", "none", "only"];
+export type SettingsAtMention = {
+    readonly mode: Exclude<(typeof SETTINGS_AT_MENTION_MODES)[number], 'only'>;
+} | {
+    readonly mode: 'only';
+    readonly models: readonly string[];
+};
+export type SettingsHookMatcherForm = "literal" | "regex" | "invalid";
+export declare const SETTINGS_IS_LOOPBACK_AUTH_HOST: (host: string) => boolean;
+export declare const SETTINGS_IS_HIERARCHICAL_URL: (raw: string) => boolean;
+export declare const SETTINGS_NARROW_AT_MENTION: (atMention: SettingsAtMention, available: ReadonlySet<string>) => SettingsAtMention;
+export declare const SETTINGS_HOOK_MATCHER_SELECTS: (matcher: string | undefined, name: string) => boolean | 'invalid';
+export declare const SETTINGS_HOOK_MATCHER_FORM: (matcher: string | undefined) => SettingsHookMatcherForm;

package/dist/generated/settingsSchemaFns.js

@@ -0,0 +1,75 @@
+export const SETTINGS_AT_MENTION_MODES = Object.freeze([
+    "all",
+    "none",
+    "only",
+]);
+export const SETTINGS_IS_LOOPBACK_AUTH_HOST = function isLoopbackAuthHost(host) {
+    return host === "127.0.0.1" || host === "localhost" || host === "::1" || host === "[::1]" || host === "::ffff:127.0.0.1";
+};
+export const SETTINGS_IS_HIERARCHICAL_URL = function isHierarchicalUrl(raw) {
+    if (!URL.canParse(raw))
+        return false;
+    const u = new URL(raw);
+    return u.href.startsWith(`${u.protocol}//`);
+};
+export const SETTINGS_NARROW_AT_MENTION = function narrowAtMention(atMention, available) {
+    if (atMention.mode !== "only")
+        return atMention;
+    const kept = atMention.models.filter((n) => available.has(n));
+    if (kept.length === atMention.models.length)
+        return atMention;
+    return kept.length > 0 ? { mode: "only", models: kept } : { mode: "none" };
+};
+const HOOK_MATCHER_NAME_LIST = /^[a-zA-Z0-9_|, -]+$/;
+const readHookMatcher = function readHookMatcher(matcher) {
+    if (matcher === undefined || matcher === "" || matcher === "*")
+        return { form: "all" };
+    if (HOOK_MATCHER_NAME_LIST.test(matcher)) {
+        return {
+            form: "names",
+            names: matcher
+                .split(/[|,]/)
+                .map((part) => part.trim())
+                .filter((part) => part !== ""),
+        };
+    }
+    try {
+        return { form: "regex", pattern: new RegExp(matcher) };
+    }
+    catch {
+        return { form: "invalid" };
+    }
+};
+export const SETTINGS_HOOK_MATCHER_SELECTS = function hookMatcherSelects(matcher, name) {
+    const r = readHookMatcher(matcher);
+    switch (r.form) {
+        case "all":
+            return true;
+        case "names":
+            return r.names.includes(name);
+        case "regex":
+            return r.pattern.test(name);
+        case "invalid":
+            return "invalid";
+        default: {
+            const unhandled = r;
+            throw new Error(`hookMatcherSelects: unhandled matcher reading ${JSON.stringify(unhandled)}`);
+        }
+    }
+};
+export const SETTINGS_HOOK_MATCHER_FORM = function hookMatcherForm(matcher) {
+    const r = readHookMatcher(matcher);
+    switch (r.form) {
+        case "all":
+        case "names":
+            return "literal";
+        case "regex":
+            return "regex";
+        case "invalid":
+            return "invalid";
+        default: {
+            const unhandled = r;
+            throw new Error(`hookMatcherForm: unhandled matcher reading ${JSON.stringify(unhandled)}`);
+        }
+    }
+};

package/dist/generated/toolNameTables.d.ts

@@ -1,2 +1,3 @@
 export declare const CORE_PROTOCOL_PREFIXES: readonly ["mcp__", "a2a__"];
 export declare const CORE_RETIRED_TOOL_CURRENT_NAMES: ReadonlyMap<string, string | null>;
+export declare const CORE_SKILL_TOOL_NAME: "Skill";

package/dist/generated/toolNameTables.js

@@ -41,3 +41,4 @@ export const CORE_RETIRED_TOOL_CURRENT_NAMES = new Map([
     ["Recall", null],
     ["recall", null],
 ]);
+export const CORE_SKILL_TOOL_NAME = "Skill";

package/dist/headlessPermissionModeWire.d.ts

@@ -3,7 +3,7 @@ import { type PermissionModesReading } from './permissionModesCapability.js';
 import { type EnvLike } from './hostEnv.js';
 export declare const HEADLESS_PERMISSION_MODE_ENV = "SEMA_HEADLESS_PERMISSION_MODE";
 export declare const HEADLESS_PERMISSION_WIRE_MODES: readonly PermissionMode[];
-export declare function normalizeShellPermissionModeForWire(mode: string | undefined, _permissionModes?: PermissionModesReading): string | undefined;
+export declare function normalizeShellPermissionModeForWire(mode: string | undefined): string | undefined;
 export type HeadlessPermissionResolution = {
     fields: PermissionModeField;
     source: 'flag' | 'env' | 'default';

package/dist/headlessPermissionModeWire.js

@@ -7,7 +7,7 @@ import { readOwnDataValue } from './ownKey.js';
 export const HEADLESS_PERMISSION_MODE_ENV = 'SEMA_HEADLESS_PERMISSION_MODE';
 export const HEADLESS_PERMISSION_WIRE_MODES = [...PERMISSION_MODE_WORDS];
 const SHELL_INTERNAL_MODE_TO_WIRE = new Map([['manual', 'default']]);
-export function normalizeShellPermissionModeForWire(mode, _permissionModes) {
+export function normalizeShellPermissionModeForWire(mode) {
     if (mode === undefined)
         return undefined;
     return SHELL_INTERNAL_MODE_TO_WIRE.get(mode) ?? mode;

package/dist/headlessReconnectWire.js

@@ -1,23 +1,18 @@
 import { isSseIdleError, probeEngineAlive } from './sseIdleTriage.js';
 import { hostEnv } from './hostEnv.js';
+import { isSdkRunFrameSynthesizable } from './terminalStatuses.js';
+import { createStreamDrainingLegs } from './streamDrainingLegs.js';
+import { abortableSleep } from './abortableSleep.js';
 export const HEADLESS_RECONNECT_MAX = 2;
 function debugLog(msg) {
     if (hostEnv().SEMA_DEBUG) {
         console.error(`[sema] headless reconnect: ${msg}`);
     }
 }
-const RUN_ROW_TERMINAL_STATUSES = new Set([
-    'completed',
-    'failed',
-    'timeout',
-    'blocked',
-    'suspended',
-    'needs_review',
-]);
 export function terminalEventFromRunRow(row) {
     if (!row || typeof row.status !== 'string')
         return null;
-    if (RUN_ROW_TERMINAL_STATUSES.has(row.status)) {
+    if (isSdkRunFrameSynthesizable(row.status)) {
         if (row.result && typeof row.result === 'object') {
             return { type: 'done', result: row.result };
         }
@@ -49,6 +44,15 @@ export async function* withHeadlessR1Reconnect(live, deps) {
     let lastSeenSeq;
     const probe = deps.probeAlive ?? probeEngineAlive;
     let isRecoverableTear;
+    const drains = createStreamDrainingLegs();
+    let drainReopenAfterMs;
+    const terminalFromRunRow = async (taskId) => {
+        const row = await deps.getRun(taskId).catch(() => null);
+        const terminal = terminalEventFromRunRow(row);
+        if (terminal)
+            debugLog(`run row terminal (${String(row?.status)}) — synthesizing the terminal frame (R1b)`);
+        return terminal;
+    };
     for (;;) {
         if (deps.signal?.aborted)
             throw originalTearErr;
@@ -59,25 +63,37 @@ export async function* withHeadlessR1Reconnect(live, deps) {
         const taskId = deps.getTaskId();
         if (!taskId)
             throw originalTearErr;
-        if (attempts >= HEADLESS_RECONNECT_MAX) {
-            debugLog(`budget exhausted (${attempts}/${HEADLESS_RECONNECT_MAX}) — falling to the honest death path`);
-            throw originalTearErr;
+        if (drainReopenAfterMs !== undefined) {
+            const waitMs = drainReopenAfterMs;
+            drainReopenAfterMs = undefined;
+            await abortableSleep(waitMs, deps.signal ?? new AbortController().signal);
+            if (deps.signal?.aborted)
+                throw originalTearErr;
+            debugLog(`engine draining — reopening runs.events(${taskId}${lastSeenSeq !== undefined ? `, Last-Event-ID ${lastSeenSeq}` : ''}) after ${waitMs}ms (not counted against the reconnect budget)`);
+        }
+        else {
+            if (attempts >= HEADLESS_RECONNECT_MAX) {
+                debugLog(`budget exhausted (${attempts}/${HEADLESS_RECONNECT_MAX}) — falling to the honest death path`);
+                throw originalTearErr;
+            }
+            attempts++;
+            if (!(await probe(deps.baseUrl)))
+                throw originalTearErr;
+            debugLog(`attempt ${attempts}/${HEADLESS_RECONNECT_MAX} — switching to runs.events(${taskId}${lastSeenSeq !== undefined ? `, Last-Event-ID ${lastSeenSeq}` : ''})`);
         }
-        attempts++;
-        if (!(await probe(deps.baseUrl)))
-            throw originalTearErr;
-        debugLog(`attempt ${attempts}/${HEADLESS_RECONNECT_MAX} — switching to runs.events(${taskId}${lastSeenSeq !== undefined ? `, Last-Event-ID ${lastSeenSeq}` : ''})`);
         try {
             const cont = deps.openEvents(taskId, lastSeenSeq !== undefined ? String(lastSeenSeq) : undefined);
             for await (const ev of cont) {
                 if (deps.signal?.aborted)
                     return;
+                if (drains.see(ev))
+                    continue;
                 const rec = ev;
                 const t = rec?.type;
                 if (t === undefined)
                     continue;
                 if (t === 'error') {
-                    debugLog(`runs.events lane frame type=error code=${String(rec?.errorCode ?? rec?.code ?? '')} — SDK resumes with Last-Event-ID internally`);
+                    debugLog(`runs.events lane frame type=error code=${String(rec?.errorCode ?? rec?.code ?? '')} — not forwarded (the cap frame is resumed inside the SDK)`);
                     continue;
                 }
                 const seq = typeof rec?.id === 'string' && /^\d+$/.test(rec.id) ? Number(rec.id) : undefined;
@@ -94,16 +110,29 @@ export async function* withHeadlessR1Reconnect(live, deps) {
             }
             if (deps.signal?.aborted)
                 return;
+            const drained = drains.legEnded('returned');
+            if (drained !== undefined) {
+                if ('reconnectAfterMs' in drained) {
+                    drainReopenAfterMs = drained.reconnectAfterMs;
+                    continue;
+                }
+                debugLog(`runs.events kept ending on drain end frames (${drained.giveUp}) — checking the run row`);
+                const terminal = await terminalFromRunRow(taskId);
+                if (terminal) {
+                    yield terminal;
+                    return;
+                }
+                continue;
+            }
             debugLog('runs.events continuation ended without a terminal frame');
         }
         catch (contErr) {
+            drains.legEnded('threw');
             debugLog(`runs.events continuation failed: ${contErr instanceof Error ? contErr.message : String(contErr)}`);
             if (deps.signal?.aborted)
                 throw originalTearErr;
-            const row = await deps.getRun(taskId).catch(() => null);
-            const terminal = terminalEventFromRunRow(row);
+            const terminal = await terminalFromRunRow(taskId);
             if (terminal) {
-                debugLog(`run row terminal (${String(row?.status)}) — synthesizing the terminal frame (R1b)`);
                 yield terminal;
                 return;
             }

package/dist/hitl/allowRuleShadow.d.ts

@@ -18,4 +18,4 @@ export interface ApprovalAllowRuleShadow {
 export declare function readAllowRuleShadowFromWire(carrier: object | null | undefined, leg: 'frame' | 'row'): ApprovalAllowRuleShadow | undefined;
 export declare function readApprovalAllowRuleShadow(card: object | null | undefined): ApprovalAllowRuleShadow | undefined;
 export declare function approvalAllowRuleShadowed(card: object | null | undefined): boolean;
-export declare function legacyShadowedRuleTextOf(r: ApprovalAllowRuleShadow | undefined): string | undefined;
+export declare function allowRuleShadowSentence(card: object | null | undefined): string | undefined;

package/dist/hitl/allowRuleShadow.js

@@ -1,4 +1,5 @@
 import { CORE_ALLOW_RULE_MEMBERS } from '../generated/engineFactTables.js';
+import { quoteUntrustedForSentence } from '../displayUntrusted.js';
 const KNOWN_MEMBERS = new Set(CORE_ALLOW_RULE_MEMBERS);
 function freezeMember(m) {
     return Object.freeze({ ...m });
@@ -154,14 +155,54 @@ export function readApprovalAllowRuleShadow(card) {
 export function approvalAllowRuleShadowed(card) {
     return readApprovalAllowRuleShadow(card) !== undefined;
 }
-export function legacyShadowedRuleTextOf(r) {
-    if (r === undefined)
+const ENTRY_MAX = 4096;
+const MEMBER_MAX = 64;
+const ENTRIES_SHOWN = 5;
+const UNREADABLE_LINE = 'An allow rule matched this call but cannot clear it; which rule could not be read, so this one is confirmed individually.';
+function legacySingleEntry(shadow) {
+    if (shadow.unreadable === true || shadow.members.length !== 1)
         return undefined;
-    for (const m of r.members) {
-        if (m.member !== 'persisted' || m.entries === undefined)
-            continue;
-        const first = m.entries[0];
-        return typeof first === 'string' && first.trim() !== '' ? first : undefined;
+    const m = shadow.members[0];
+    if (m.member !== 'persisted' || m.malformed === true || m.omitted !== undefined)
+        return undefined;
+    if (m.entries === undefined || m.entries.length !== 1)
+        return undefined;
+    return quoteUntrustedForSentence(m.entries[0], ENTRY_MAX);
+}
+function memberPhrase(m) {
+    const memberWord = m.member === undefined ? undefined : KNOWN_MEMBERS.has(m.member) ? m.member : quoteUntrustedForSentence(m.member, MEMBER_MAX);
+    const word = memberWord ?? 'an unrecognised source';
+    const entries = m.entries ?? [];
+    if (m.malformed === true && entries.length === 0)
+        return `${word} (could not be read)`;
+    const listed = entries
+        .map((e) => quoteUntrustedForSentence(e, ENTRY_MAX))
+        .filter((e) => e !== undefined)
+        .slice(0, ENTRIES_SHOWN);
+    const notListed = entries.length - listed.length + (m.omitted ?? 0);
+    const parts = [];
+    if (listed.length > 0)
+        parts.push(listed.join(', '));
+    if (notListed > 0)
+        parts.push(listed.length > 0 ? `and ${String(notListed)} more not listed` : `${String(notListed)} not listed`);
+    if (m.malformed === true)
+        parts.push('part of it could not be read');
+    return parts.length > 0 ? `${word}: ${parts.join('; ')}` : word;
+}
+export function allowRuleShadowSentence(card) {
+    const shadow = readApprovalAllowRuleShadow(card);
+    if (shadow === undefined)
+        return undefined;
+    try {
+        if (shadow.unreadable === true || shadow.members.length === 0)
+            return UNREADABLE_LINE;
+        const legacy = legacySingleEntry(shadow);
+        if (legacy !== undefined) {
+            return `Your saved permission rule ${legacy} still exists — it just cannot clear this particular call, so this one is confirmed individually.`;
+        }
+        return `Allow rules matched this call but cannot clear it, so this one is confirmed individually — ${shadow.members.map(memberPhrase).join(' · ')}.`;
+    }
+    catch {
+        return UNREADABLE_LINE;
     }
-    return undefined;
 }

package/dist/hitl/approvalCompleteParked.d.ts

@@ -0,0 +1 @@
+export declare function approvalCompleteParked(frame: unknown): boolean;

package/dist/hitl/approvalCompleteParked.js

@@ -0,0 +1,14 @@
+function ownData(o, key) {
+    const d = Object.getOwnPropertyDescriptor(o, key);
+    return d !== undefined && 'value' in d ? d.value : undefined;
+}
+export function approvalCompleteParked(frame) {
+    try {
+        if (frame === null || typeof frame !== 'object')
+            return false;
+        return ownData(frame, 'outcome') === 'expired' && ownData(frame, 'parked') === true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/hitl/approvalEndingCause.d.ts

@@ -0,0 +1,7 @@
+import type { ApprovalSettleCause, AskRowEndingCause } from '@sema-agent/sdk';
+export declare const ASK_ROW_ENDING_CAUSE_WORDS: readonly ["routing_failure_fail_closed", "run_cancelled", "run_exited", "batch_aborted", "batch_sibling_withdrawn", "batch_bound_elsewhere", "adhoc_leg_no_durable_domain", "orphan_ttl_exceeded", "crashed_before_park", "shutdown_before_park"];
+export declare function askRowEndingCauseFor(state: 'VOID' | 'DENIED' | undefined, word: unknown): AskRowEndingCause | undefined;
+export declare function approvalCompleteCauseOf(frame: unknown): ApprovalSettleCause | undefined;
+export declare function notPendingCauseReading(err: object): 'ended' | 'other_replica' | 'none';
+export declare function refusalCauseWordOf(err: object): string | undefined;
+export declare function notPendingCauseSaysEnded(err: object): boolean;

package/dist/hitl/approvalEndingCause.js

@@ -0,0 +1,71 @@
+import { ASK_GONE_DENIED_WORD } from '../engineErrorCodes.js';
+import { SDK_ASK_ROW_ENDING_CAUSES } from '../generated/sdkFactTables.js';
+import { readThrownExtra } from '../wireFailureShape.js';
+export const ASK_ROW_ENDING_CAUSE_WORDS = SDK_ASK_ROW_ENDING_CAUSES;
+const _askRowCausePin = true;
+void _askRowCausePin;
+const DENIED_GROUP_WORD = ASK_GONE_DENIED_WORD;
+const WAIT_CLASS_SETTLE_CAUSE_WORDS = Object.freeze({
+    ttl_expired: true,
+    broadcast_lost: true,
+    stream_disconnected: true,
+    undeliverable: true,
+});
+function isAskRowEndingCause(v) {
+    return typeof v === 'string' && ASK_ROW_ENDING_CAUSE_WORDS.includes(v);
+}
+function isApprovalSettleCause(v) {
+    return isAskRowEndingCause(v) || (typeof v === 'string' && Object.hasOwn(WAIT_CLASS_SETTLE_CAUSE_WORDS, v));
+}
+export function askRowEndingCauseFor(state, word) {
+    if (!isAskRowEndingCause(word))
+        return undefined;
+    if (state === 'DENIED')
+        return word === DENIED_GROUP_WORD ? word : undefined;
+    if (state === 'VOID')
+        return word !== DENIED_GROUP_WORD ? word : undefined;
+    return undefined;
+}
+function ownDataSlot(o, key) {
+    try {
+        const slot = Object.getOwnPropertyDescriptor(o, key);
+        return slot !== undefined && Object.hasOwn(slot, 'value') ? slot.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function approvalCompleteCauseOf(frame) {
+    try {
+        if (typeof frame !== 'object' || frame === null)
+            return undefined;
+        if (ownDataSlot(frame, 'type') !== 'tool_approval_complete')
+            return undefined;
+        const word = ownDataSlot(frame, 'cause');
+        return isApprovalSettleCause(word) ? word : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const NOT_PENDING_OTHER_REPLICA_WORDS = Object.freeze({
+    unknown_or_other_replica: true,
+});
+export function notPendingCauseReading(err) {
+    const word = refusalCauseWordOf(err);
+    if (word === undefined)
+        return 'none';
+    if (isAskRowEndingCause(word))
+        return 'ended';
+    return Object.hasOwn(NOT_PENDING_OTHER_REPLICA_WORDS, word) ? 'other_replica' : 'none';
+}
+export function refusalCauseWordOf(err) {
+    const reading = readThrownExtra(err);
+    if (reading.state !== 'object')
+        return undefined;
+    const word = ownDataSlot(reading.value, 'cause');
+    return typeof word === 'string' && word !== '' ? word : undefined;
+}
+export function notPendingCauseSaysEnded(err) {
+    return notPendingCauseReading(err) === 'ended';
+}

package/dist/hitl/approvalHolds.d.ts

@@ -1,4 +1,4 @@
-import type { FsApprovalOutcome, ToolApprovalFrameOutcome } from './toolApprovalWire.js';
+import type { ApprovalHolderIdentity, FsApprovalOutcome, ToolApprovalFrameOutcome } from './toolApprovalWire.js';
 export interface DurableDecisionHold {
     readonly lane: 'durable';
     readonly outcome: Promise<FsApprovalOutcome>;
@@ -9,6 +9,7 @@ export interface DurableDecisionHold {
 }
 export interface LiveCardHold {
     readonly lane: 'live';
+    readonly identity: LiveCardIdentity;
     readonly outcome: Promise<ToolApprovalFrameOutcome>;
     phase: 'card' | 'respond';
     superseded?: {
@@ -19,6 +20,15 @@ export interface LiveCardHold {
     trailing?: Promise<void>;
 }
 export type ApprovalHold = DurableDecisionHold | LiveCardHold;
+export interface LiveCardIdentity {
+    readonly approvalId: string;
+    readonly toolCallId?: string;
+    readonly taskId?: string;
+    readonly sessionId?: string;
+}
+export declare function liveCardHoldFor(who: ApprovalHolderIdentity): LiveCardHold | undefined;
+export declare function liveCardAnsweredHow(o: ToolApprovalFrameOutcome): 'answered' | 'interrupted' | undefined;
+export declare function awaitLiveCardHolder(hold: LiveCardHold, signal: AbortSignal | undefined): Promise<ToolApprovalFrameOutcome | undefined>;
 export interface ApprovalDecisionHoldTable {
     readonly inFlight: Map<string, ApprovalHold>;
     readonly settled: Map<string, DurableSettledHold>;
@@ -31,6 +41,6 @@ export interface DurableSettledHold {
 }
 export declare const approvalDecisionHolds: ApprovalDecisionHoldTable;
 export declare function liveCardHoldOf(key: string): LiveCardHold | undefined;
-export declare function holdLiveCard(key: string, callerSignal: AbortSignal | undefined, present: (hold: LiveCardHold) => Promise<ToolApprovalFrameOutcome>): Promise<ToolApprovalFrameOutcome>;
+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 supersedeLiveCard(key: string, parked: boolean): boolean;

package/dist/hitl/approvalHolds.js

@@ -1,10 +1,61 @@
 import { hostLog } from '../host.js';
+import { liveFrameCallKey } from './gateIdentity.js';
+import { approvalResolutionOf } from './approvalResolution.js';
+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;
+    for (const h of approvalDecisionHolds.inFlight.values()) {
+        if (h.lane !== 'live' || h.phase !== 'card')
+            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;
+    }
+    return undefined;
+}
+function liveCardSettledQuestion(hold, o) {
+    const r = approvalResolutionOf(o);
+    if (answeredHowOf(r) !== undefined)
+        return true;
+    if (r.kind === 'unsettled')
+        return false;
+    return hold.superseded !== undefined && !hold.superseded.parked;
+}
+export function liveCardAnsweredHow(o) {
+    return answeredHowOf(approvalResolutionOf(o));
+}
+function answeredHowOf(r) {
+    if (r.kind === 'decided')
+        return 'answered';
+    return r.kind === 'unsettled' && r.cause === 'interrupted' ? 'interrupted' : undefined;
+}
+export async function awaitLiveCardHolder(hold, signal) {
+    const unsubscribe = followCallerSignal(signal, hold.interrupt);
+    let o;
+    try {
+        o = await hold.outcome;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        unsubscribe();
+    }
+    return liveCardSettledQuestion(hold, o) ? { ...o, joinedInFlight: true } : undefined;
+}
 export const approvalDecisionHolds = { inFlight: new Map(), settled: new Map(), openReads: new Set(), clock: 0 };
 export function liveCardHoldOf(key) {
     const h = approvalDecisionHolds.inFlight.get(key);
     return h !== undefined && h.lane === 'live' ? h : undefined;
 }
-export function holdLiveCard(key, callerSignal, present) {
+export function holdLiveCard(identity, callerSignal, present) {
+    const key = liveFrameCallKey(identity.approvalId);
     const h = approvalDecisionHolds;
     const cut = new AbortController();
     let settled = false;
@@ -19,7 +70,7 @@ export function holdLiveCard(key, callerSignal, present) {
         resolveOutcome = resolve;
         rejectOutcome = reject;
     });
-    const hold = { lane: 'live', outcome, phase: 'card', cardSignal: cut.signal, interrupt };
+    const hold = { lane: 'live', identity: Object.freeze({ ...identity }), outcome, phase: 'card', cardSignal: cut.signal, interrupt };
     h.inFlight.set(key, hold);
     const release = () => {
         if (h.inFlight.get(key) === hold)