@sema-agent/client-core 0.100.0 → 0.101.0

package/dist/displayUntrusted.d.ts

@@ -1,6 +1,7 @@
 export declare const REDACTION_MARKER_PREFIX = "\u00ABredacted";
 export declare function looksLikeKnownSecret(s: string): boolean;
 export declare function isDiagnosticValueWord(value: string): boolean;
+export declare function percentBoundaryReadingOf(text: string): string;
 export declare function washCredentials(text: string): string;
 export type DisplayMark = 'escape' | 'dot' | 'space';
 export interface DisplayFace {

package/dist/displayUntrusted.js

@@ -1407,6 +1407,10 @@ function percentBoundaryDecode(text) {
     }
     return { decoded: chars.join(''), from, to };
 }
+export function percentBoundaryReadingOf(text) {
+    const wide = percentBoundaryDecode(text);
+    return wide === null ? text : wide.decoded;
+}
 const MAX_PERCENT_VIEW_LAYERS = 3;
 function percentLayers(text) {
     const out = [];
@@ -3911,11 +3915,12 @@ function screenSurfaces(text, o) {
 function percentSurfaces(raw, text, base, o) {
     const surfaces = [];
     const contents = [];
+    const locals = [];
     for (const layer of percentLayers(text))
-        layerSurfaces(raw, layer, base, o, surfaces, contents);
-    return { surfaces, contents };
+        layerSurfaces(raw, layer, base, o, surfaces, contents, true, base === null ? locals : undefined);
+    return { surfaces, contents, locals };
 }
-function layerSurfaces(raw, layer, base, o, surfaces, contents, decoded = true) {
+function layerSurfaces(raw, layer, base, o, surfaces, contents, decoded = true, locals) {
     const n = layer.text.length;
     const ps = new Int32Array(n);
     const pe = new Int32Array(n);
@@ -3937,6 +3942,52 @@ function layerSurfaces(raw, layer, base, o, surfaces, contents, decoded = true)
         surfaces.push(base === null ? { ...joined, rawDot: null, decoded } : { ...joined, decoded });
     for (const [a, b] of VD.contents)
         contents.push({ sub: layer.text.slice(a, b), rawAt: (k) => ps[a + k] ?? 0, rawEndAt: (k) => pe[a + k] ?? 0 });
+    if (locals !== undefined && decoded && base === null && hasLineBreakAny(layer.text)) {
+        locals.push({ text: layer.text, view: VD, ps, pe });
+        if (layer.text.includes('+')) {
+            const spaced = layer.text.split('+').join(' ');
+            locals.push({ text: spaced, view: buildScanView(spaced, o), ps, pe });
+        }
+    }
+}
+function hasLineBreakAny(text) {
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        if ((c === 0x0a || c === 0x0d || c === 0x5c) && lineBreakLengthAt(text, i) > 0)
+            return true;
+    }
+    return false;
+}
+function decodedLayerLocalCandidates(L, o, out) {
+    const layerSep = { ...separatedSurface(L.text, L.view), rawDot: null, decoded: true };
+    const layerJoined = joinedSurface(L.text, L.view);
+    const surfaces = layerJoined === null ? [layerSep] : [layerSep, { ...layerJoined, rawDot: null, decoded: true }];
+    const blocks = { raw: L.text, view: L.view, out: [], lines: [null, null], marks: null };
+    const found = [];
+    for (const S of surfaces) {
+        const cands = [];
+        const regions = [];
+        if (o.urls) {
+            const unitPos = (k) => S.dropped(k) || L.view.rawUnit[S.rawStart(k)] === 1;
+            urlCandidates(S.text, [], regions, unitPos, (k) => unitPos(k) || S.painted(k), o.queryByShape ?? false, o.wholeAddress === true, false);
+        }
+        runLabelPasses(S, regions, cands, blocks);
+        for (const c of cands) {
+            const r = toRaw(S, c);
+            if (r !== null)
+                found.push(r);
+        }
+    }
+    for (const r of blocks.out)
+        found.push(r);
+    for (const r of found) {
+        const start = L.ps[r.start];
+        const end = L.pe[r.end - 1];
+        if (start === undefined || end === undefined || end <= start)
+            continue;
+        const tokenEnd = r.tokenEnd > r.start ? (L.pe[Math.min(r.tokenEnd, L.text.length) - 1] ?? end) : end;
+        out.push({ ...r, start, end, tokenEnd });
+    }
 }
 function parserViewLayer(text) {
     if (!/[\t\n\r]/.test(text))
@@ -4209,6 +4260,13 @@ function toRaw(S, c) {
     const te = c.te > b ? S.rawEnd(c.te - 1) : S.rawEnd(b - 1);
     return { start: S.rawStart(a), end: S.rawEnd(b - 1), kind: c.kind, cls: c.cls, tokenEnd: te };
 }
+function runLabelPasses(S, regions, cands, blocks) {
+    labelCandidates(S, 'scheme', regions, cands, blocks);
+    labelCandidates(S, 'token', regions, cands, blocks);
+    labelCandidates(S, 'label', regions, cands, blocks);
+    labelCandidates(S, 'scheme', regions, cands, blocks, true);
+    labelCandidates(S, 'label', regions, cands, blocks, true);
+}
 function collectCandidates(text, o, nested) {
     const V = buildScanView(text, o);
     const separated = separatedSurface(text, V);
@@ -4252,11 +4310,7 @@ function collectCandidates(text, o, nested) {
         if (o.words) {
             editsToCandidates(pemEdits(S, (blk) => { if (S === regionSurface)
                 pemBlocksSeen.push(pemBlockToRaw(S, blk)); }), 'pem', cands);
-            labelCandidates(S, 'scheme', regions, cands, blocks);
-            labelCandidates(S, 'token', regions, cands, blocks);
-            labelCandidates(S, 'label', regions, cands, blocks);
-            labelCandidates(S, 'scheme', regions, cands, blocks, true);
-            labelCandidates(S, 'label', regions, cands, blocks, true);
+            runLabelPasses(S, regions, cands, blocks);
             editsToCandidates(authParamEdits(S.text), 'param', cands);
             editsToCandidates(proseLiteralEdits(S.text), 'prose', cands);
         }
@@ -4266,6 +4320,9 @@ function collectCandidates(text, o, nested) {
                 raw.push(S.rawDot !== null ? { ...r, dotted: true } : r);
         }
     }
+    if (o.words)
+        for (const L of decoded.locals)
+            decodedLayerLocalCandidates(L, o, raw);
     if (!nested) {
         for (const [a, b] of V.contents) {
             const sub = text.slice(a, b);

package/dist/engineCapReader.js

@@ -11,7 +11,7 @@ function freezeReading(reading, seen = new Set()) {
     seen.add(reading);
     Object.freeze(reading);
     for (const d of Object.values(Object.getOwnPropertyDescriptors(reading))) {
-        if ('value' in d)
+        if (Object.hasOwn(d, 'value'))
             freezeReading(d.value, seen);
     }
     return reading;

package/dist/engineConfigDrift.js

@@ -3,7 +3,7 @@ function countOf(v) {
 }
 function ownValue(o, key) {
     const d = Object.getOwnPropertyDescriptor(o, key);
-    return d !== undefined && 'value' in d ? d.value : undefined;
+    return d !== undefined && Object.hasOwn(d, 'value') ? d.value : undefined;
 }
 export function readEngineConfigApplyState(health) {
     try {

package/dist/engineErrorCodes.d.ts

@@ -1,4 +1,6 @@
+import { SDK_STATUS_DERIVED_COARSE_CODES } from './generated/sdkFactTables.js';
 import type { RunDeathVerdictCode } from '@sema-agent/sdk';
+import type { SDKResultError } from '@sema-agent/agent-types';
 export declare const LIMITS_MAX_TOKENS_EXCEEDED = "limits.max_tokens_exceeded";
 export declare const LIMITS_MAX_COST_EXCEEDED = "limits.max_cost_exceeded";
 export declare const LIMITS_MAX_TURNS_EXCEEDED = "limits.max_turns_exceeded";
@@ -8,8 +10,6 @@ export declare const USAGE_WINDOW_EXHAUSTED = "usage.window_exhausted";
 export declare const ENV_LIFETIME_EXPIRED = "env.lifetime_expired";
 export declare const FLEET_LEASE_UNAVAILABLE = "fleet.lease_unavailable";
 export declare const CONFIG_LIMIT_INVALID = "config.limit_invalid";
-export declare const CONFIG_STRATEGY_FIND_LIMIT_INVALID = "config.strategy_find_limit_invalid";
-export declare const CONFIG_STRATEGY_MAX_SIZE_INVALID = "config.strategy_max_size_invalid";
 export declare const CONFIG_LIMIT_UNKNOWN_KEY = "config.limit_unknown_key";
 export declare const CONFIG_DELEGATION_ENTRY_CAPS = "config.delegation_entry_caps";
 export declare const CONFIG_MEMORY_PROJECT_KEY_SPELLING = "config.memory_project_key_spelling";
@@ -18,6 +18,7 @@ export declare const CONFIG_LEGACY_TOOL_NAME = "config.legacy_tool_name";
 export declare const CONFIG_IMAGE_INVALID = "config.image_invalid";
 export declare const CONFIG_AGENT_UNKNOWN_TOOL = "config.agent.unknown_tool";
 export declare const CONFIG_TOOL_FACE_CONTROL = "config.tool_face_control";
+export declare const CONFIG_MCP_SERVER_NAME_COLLISION = "config.mcp_server_name_collision";
 export declare const PROMPT_ASSEMBLED_ROLE_REFUSED = "prompt.assembled_role_refused";
 export declare const CONFIG_OUTPUT_STYLE_INVALID = "config.output_style_invalid";
 export declare const RULES_INERT_ENTRY = "rules.inert_entry";
@@ -30,6 +31,8 @@ export declare function isDelegationCapCode(code: string | undefined): boolean;
 export type DelegationCapDisposition = 'wait-for-slot' | 'reuse-existing-or-await-reap';
 export declare function delegationCapDispositionOf(code: string | undefined): DelegationCapDisposition | undefined;
 export declare const MCP_SERVER_REVOKED = "mcp.server_revoked";
+export declare const MCP_TOOL_DECLARATION_CHANGED = "mcp.tool_declaration_changed";
+export declare const MCP_TOOL_LISTING_UNREACHED = "mcp.tool_listing_unreached";
 export declare function isConfigRefusalCode(code: string | undefined): boolean;
 export declare const TOOL_END_INTERRUPTED_NEVER_STARTED = "interrupted_never_started";
 export declare const TOOL_END_INTERRUPTED_OUTCOME_UNKNOWN = "interrupted_outcome_unknown";
@@ -63,8 +66,13 @@ export declare const STOP_NOT_LANDED = "stop.not_landed";
 export declare const STOP_NOT_LOCAL = "stop.not_local";
 export declare const STOP_PARKED = "stop.parked";
 export declare const OUTPUT_INVALID = "output.invalid";
+export type ResultLimitWord = 'wall_clock' | 'tokens' | 'turns' | 'budget_usd' | 'structured_output_retries';
+export declare const RESULT_LIMIT_WORDS: readonly ResultLimitWord[];
+export declare function resultLimitRowOfCode(code: string | undefined): {
+    readonly word: ResultLimitWord;
+    readonly subtype: SDKResultError['subtype'];
+} | undefined;
 export declare const RESUME_POLICY_FOLD_CODE = "resume_blocked_by_policy";
-export declare const 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 function isStatusDerivedCoarseCode(code: string | null | undefined): boolean;
 export declare const RESUME_AT_ERROR_CODE_PREFIX = "resume_at.";
 export declare const REWIND_ERROR_CODE_PREFIXES: readonly ["resume_at.", "rewind_snapshot."];
@@ -81,7 +89,7 @@ export declare const CHECKPOINT_REFUSED_PARK_CODES: readonly string[];
 export declare function isRefusedParkCode(code: string | null | undefined): code is typeof CHECKPOINT_UNSUPPORTED_VERSION | typeof CHECKPOINT_WALLTIME_AXIS_RETIRED | typeof CHECKPOINT_CONFIG_REFUSED;
 export declare function refusalSaysStillPending(err: object): boolean;
 export declare function refusalRetriableReading(err: object): boolean | undefined;
-export type StatusDerivedCoarseCode = (typeof STATUS_DERIVED_COARSE_CODES)[number];
+export type StatusDerivedCoarseCode = (typeof SDK_STATUS_DERIVED_COARSE_CODES)[number];
 export declare const RESUME_PLACEMENT_MISMATCH = "resume.placement_mismatch";
 export declare const RESUME_CONTEXT_UNAVAILABLE = "conflict.resume_context_unavailable";
 export declare const RESUME_RETRY_LATER_CODES: readonly string[];
@@ -102,6 +110,8 @@ export declare const CONFLICT_NOT_RESUMABLE = "conflict.not_resumable";
 export declare const GATE_NOT_TOOL_APPROVAL = "gate_not_tool_approval";
 export declare const DECIDE_PARK_MOVED_CODES: readonly string[];
 export declare function isDecideParkMovedCode(code: string | null | undefined): boolean;
+export declare const DECIDE_ROW_UNREVIVABLE = "decide.row_unrevivable";
+export declare function isDecideRowUnrevivableCode(code: string | null | undefined): boolean;
 export declare const APPROVAL_STALE = "approval_stale";
 export declare const APPROVAL_BINDING_MISMATCH = "approval_binding_mismatch";
 export declare const CHECKPOINT_INVALID_OUTCOME = "checkpoint.invalid_outcome";
@@ -119,7 +129,6 @@ export declare const ASK_IDEMPOTENCY_CONFLICT = "conflict.ask_idempotency";
 export declare const ASK_PARKING_RETRY = "parking.ask_retry";
 export declare const ASK_DECISION_LANE_DISABLED = "feature.approval_ask_disabled";
 export declare const ASK_GONE_DENIED_WORD: "routing_failure_fail_closed";
-export declare const RUN_DEATH_VERDICT_CODES: readonly ["run.stalled", "run.orphaned", "approval.expired"];
 export type { RunDeathVerdictCode };
 export declare const RUN_STALLED: "run.stalled";
 export declare const RUN_ORPHANED: "run.orphaned";

package/dist/engineErrorCodes.js

@@ -1,6 +1,6 @@
 import { frozenSet } from './frozenSet.js';
 import { ownDataField } from './ownKey.js';
-import { SDK_DENY_REASON_ROUTING_FAILURE, SDK_RUN_DEATH_VERDICT_CODES, SDK_STATUS_DERIVED_COARSE_CODES } from './generated/sdkFactTables.js';
+import { SDK_DENY_REASON_ROUTING_FAILURE, SDK_STATUS_DERIVED_COARSE_CODES } from './generated/sdkFactTables.js';
 export const LIMITS_MAX_TOKENS_EXCEEDED = 'limits.max_tokens_exceeded';
 export const LIMITS_MAX_COST_EXCEEDED = 'limits.max_cost_exceeded';
 export const LIMITS_MAX_TURNS_EXCEEDED = 'limits.max_turns_exceeded';
@@ -13,8 +13,6 @@ export const USAGE_WINDOW_EXHAUSTED = 'usage.window_exhausted';
 export const ENV_LIFETIME_EXPIRED = 'env.lifetime_expired';
 export const FLEET_LEASE_UNAVAILABLE = 'fleet.lease_unavailable';
 export const CONFIG_LIMIT_INVALID = 'config.limit_invalid';
-export const CONFIG_STRATEGY_FIND_LIMIT_INVALID = 'config.strategy_find_limit_invalid';
-export const CONFIG_STRATEGY_MAX_SIZE_INVALID = 'config.strategy_max_size_invalid';
 export const CONFIG_LIMIT_UNKNOWN_KEY = 'config.limit_unknown_key';
 export const CONFIG_DELEGATION_ENTRY_CAPS = 'config.delegation_entry_caps';
 export const CONFIG_MEMORY_PROJECT_KEY_SPELLING = 'config.memory_project_key_spelling';
@@ -23,6 +21,7 @@ export const CONFIG_LEGACY_TOOL_NAME = 'config.legacy_tool_name';
 export const CONFIG_IMAGE_INVALID = 'config.image_invalid';
 export const CONFIG_AGENT_UNKNOWN_TOOL = 'config.agent.unknown_tool';
 export const CONFIG_TOOL_FACE_CONTROL = 'config.tool_face_control';
+export const CONFIG_MCP_SERVER_NAME_COLLISION = 'config.mcp_server_name_collision';
 export const PROMPT_ASSEMBLED_ROLE_REFUSED = 'prompt.assembled_role_refused';
 export const CONFIG_OUTPUT_STYLE_INVALID = 'config.output_style_invalid';
 export const RULES_INERT_ENTRY = 'rules.inert_entry';
@@ -48,6 +47,8 @@ export function delegationCapDispositionOf(code) {
     return undefined;
 }
 export const MCP_SERVER_REVOKED = 'mcp.server_revoked';
+export const MCP_TOOL_DECLARATION_CHANGED = 'mcp.tool_declaration_changed';
+export const MCP_TOOL_LISTING_UNREACHED = 'mcp.tool_listing_unreached';
 export function isConfigRefusalCode(code) {
     return typeof code === 'string' && code.startsWith('config.');
 }
@@ -112,10 +113,27 @@ export const STOP_NOT_LANDED = 'stop.not_landed';
 export const STOP_NOT_LOCAL = 'stop.not_local';
 export const STOP_PARKED = 'stop.parked';
 export const OUTPUT_INVALID = 'output.invalid';
+const RESULT_LIMIT_TABLE = Object.freeze([
+    Object.freeze({ code: LIMITS_MAX_TURNS_EXCEEDED, word: 'turns', subtype: 'error_max_turns' }),
+    Object.freeze({ code: LIMITS_MAX_COST_EXCEEDED, word: 'budget_usd', subtype: 'error_max_budget_usd' }),
+    Object.freeze({ code: OUTPUT_INVALID, word: 'structured_output_retries', subtype: 'error_max_structured_output_retries' }),
+    Object.freeze({ code: LIMITS_MAX_WALLTIME_EXCEEDED, word: 'wall_clock', subtype: 'error_during_execution' }),
+    Object.freeze({ code: LIMITS_MAX_TOKENS_EXCEEDED, word: 'tokens', subtype: 'error_during_execution' }),
+]);
+export const RESULT_LIMIT_WORDS = Object.freeze(RESULT_LIMIT_TABLE.map((r) => r.word));
+const _limitWordPins = [true, true];
+void _limitWordPins;
+export function resultLimitRowOfCode(code) {
+    if (typeof code !== 'string' || code.length === 0)
+        return undefined;
+    for (const row of RESULT_LIMIT_TABLE)
+        if (row.code === code)
+            return row;
+    return undefined;
+}
 export const RESUME_POLICY_FOLD_CODE = 'resume_blocked_by_policy';
-export const STATUS_DERIVED_COARSE_CODES = SDK_STATUS_DERIVED_COARSE_CODES;
 export function isStatusDerivedCoarseCode(code) {
-    return typeof code === 'string' && STATUS_DERIVED_COARSE_CODES.includes(code);
+    return typeof code === 'string' && SDK_STATUS_DERIVED_COARSE_CODES.includes(code);
 }
 export const RESUME_AT_ERROR_CODE_PREFIX = 'resume_at.';
 export const REWIND_ERROR_CODE_PREFIXES = Object.freeze([RESUME_AT_ERROR_CODE_PREFIX, 'rewind_snapshot.']);
@@ -189,6 +207,10 @@ export const DECIDE_PARK_MOVED_CODES = Object.freeze([
 export function isDecideParkMovedCode(code) {
     return typeof code === 'string' && DECIDE_PARK_MOVED_CODES.includes(code);
 }
+export const DECIDE_ROW_UNREVIVABLE = 'decide.row_unrevivable';
+export function isDecideRowUnrevivableCode(code) {
+    return typeof code === 'string' && code === DECIDE_ROW_UNREVIVABLE;
+}
 export const APPROVAL_STALE = 'approval_stale';
 export const APPROVAL_BINDING_MISMATCH = 'approval_binding_mismatch';
 export const CHECKPOINT_INVALID_OUTCOME = 'checkpoint.invalid_outcome';
@@ -213,7 +235,6 @@ export const ASK_IDEMPOTENCY_CONFLICT = 'conflict.ask_idempotency';
 export const ASK_PARKING_RETRY = 'parking.ask_retry';
 export const ASK_DECISION_LANE_DISABLED = 'feature.approval_ask_disabled';
 export const ASK_GONE_DENIED_WORD = SDK_DENY_REASON_ROUTING_FAILURE;
-export const RUN_DEATH_VERDICT_CODES = SDK_RUN_DEATH_VERDICT_CODES;
 const _runDeathVerdictCodePin = true;
 void _runDeathVerdictCodePin;
 export const RUN_STALLED = 'run.stalled';

package/dist/engineGenerationConvergence.d.ts

@@ -0,0 +1,39 @@
+export interface ApprovalWindowAnchor {
+    readonly receivedAtMs?: number;
+    readonly expiresInMs?: number;
+}
+export declare const ENGINE_GENERATION_WINDOW_MARGIN_MS = 5000;
+export declare const ENGINE_STOPPED_CALL_PHASES: readonly ["engine-stopped-awaiting-approval", "engine-stopped-before-result"];
+export type EngineStoppedCallPhase = (typeof ENGINE_STOPPED_CALL_PHASES)[number];
+export interface EndedGenerationCard {
+    readonly callKey: string;
+    readonly toolCallId?: string;
+    readonly parkRow: boolean;
+    readonly windowLeftMs?: number;
+    readonly closedByEngine?: boolean;
+}
+export interface EndedGenerationOpenedCall {
+    readonly toolCallId: string;
+    readonly generation: number;
+}
+export interface EndedGenerationPhaseHold {
+    readonly toolCallId: string;
+    readonly generation: number;
+}
+export interface EndedGenerationFacts {
+    readonly cards: readonly EndedGenerationCard[];
+    readonly opened: readonly EndedGenerationOpenedCall[];
+    readonly phases?: readonly EndedGenerationPhaseHold[];
+    readonly endedGeneration: number;
+}
+export interface EndedGenerationPhaseChange {
+    readonly toolCallId: string;
+    readonly phase: EngineStoppedCallPhase;
+    readonly viaCallKey?: string;
+}
+export interface EngineGenerationConvergence {
+    readonly retract: readonly string[];
+    readonly phases: readonly EndedGenerationPhaseChange[];
+}
+export declare function approvalWindowLeftMs(keys: Readonly<ApprovalWindowAnchor> | null | undefined, nowMs: number): number | undefined;
+export declare function convergeEndedEngineGeneration(facts: EndedGenerationFacts): EngineGenerationConvergence;

package/dist/engineGenerationConvergence.js

@@ -0,0 +1,95 @@
+import { usableClockMs } from './clockReading.js';
+export const ENGINE_GENERATION_WINDOW_MARGIN_MS = 5_000;
+export const ENGINE_STOPPED_CALL_PHASES = Object.freeze(['engine-stopped-awaiting-approval', 'engine-stopped-before-result']);
+const EMPTY = Object.freeze({ retract: Object.freeze([]), phases: Object.freeze([]) });
+const nonEmpty = (v) => typeof v === 'string' && v.length > 0;
+export function approvalWindowLeftMs(keys, nowMs) {
+    try {
+        const now = usableClockMs(nowMs);
+        if (typeof keys !== 'object' || keys === null || now === null)
+            return undefined;
+        const { receivedAtMs, expiresInMs } = keys;
+        if (usableClockMs(receivedAtMs) === null || typeof expiresInMs !== 'number' || !Number.isFinite(expiresInMs))
+            return undefined;
+        if (now < receivedAtMs)
+            return undefined;
+        return receivedAtMs + expiresInMs - now;
+    }
+    catch {
+        return undefined;
+    }
+}
+function forEachGuarded(items, visit) {
+    let skipped = 0;
+    for (const item of items) {
+        try {
+            visit(item);
+        }
+        catch {
+            skipped += 1;
+        }
+    }
+    return skipped;
+}
+function windowDefinitelyOpen(card) {
+    if (card.closedByEngine === true)
+        return false;
+    const left = card.windowLeftMs;
+    return typeof left === 'number' && Number.isFinite(left) && left > ENGINE_GENERATION_WINDOW_MARGIN_MS;
+}
+export function convergeEndedEngineGeneration(facts) {
+    try {
+        if (typeof facts !== 'object' || facts === null)
+            return EMPTY;
+        const ended = facts.endedGeneration;
+        if (typeof ended !== 'number' || !Number.isFinite(ended))
+            return EMPTY;
+        const retract = [];
+        const phases = [];
+        const held = new Map();
+        const holds = facts.phases;
+        if (Array.isArray(holds)) {
+            forEachGuarded(holds, (p) => {
+                if (typeof p === 'object' && p !== null && nonEmpty(p.toolCallId) && typeof p.generation === 'number')
+                    held.set(p.toolCallId, p.generation);
+            });
+        }
+        const cards = facts.cards;
+        if (Array.isArray(cards)) {
+            forEachGuarded(cards, (card) => {
+                if (typeof card !== 'object' || card === null || !nonEmpty(card.callKey))
+                    return;
+                if (card.parkRow !== false || !windowDefinitelyOpen(card))
+                    return;
+                if (retract.includes(card.callKey))
+                    return;
+                const id = card.toolCallId;
+                retract.push(card.callKey);
+                if (!nonEmpty(id))
+                    return;
+                const heldGen = held.get(id);
+                if (heldGen !== undefined && heldGen !== ended)
+                    return;
+                if (phases.some((p) => p.toolCallId === id))
+                    return;
+                phases.push({ toolCallId: id, phase: 'engine-stopped-awaiting-approval', viaCallKey: card.callKey });
+                held.set(id, ended);
+            });
+        }
+        const opened = facts.opened;
+        if (Array.isArray(opened)) {
+            forEachGuarded(opened, (call) => {
+                if (typeof call !== 'object' || call === null || !nonEmpty(call.toolCallId) || call.generation !== ended)
+                    return;
+                if (held.has(call.toolCallId))
+                    return;
+                phases.push({ toolCallId: call.toolCallId, phase: 'engine-stopped-before-result' });
+                held.set(call.toolCallId, ended);
+            });
+        }
+        return Object.freeze({ retract: Object.freeze(retract), phases: Object.freeze(phases.map((p) => Object.freeze(p))) });
+    }
+    catch {
+        return EMPTY;
+    }
+}

package/dist/engineGenerationPort.d.ts

@@ -0,0 +1,61 @@
+export declare const REATTACH_RUN_STATES: readonly ["done", "died", "parked", "running", "unreachable", "unauthorized", "engine-known-dead"];
+export type ReattachRunState = (typeof REATTACH_RUN_STATES)[number];
+export interface ReattachLivenessReading {
+    readonly state: ReattachRunState;
+    readonly notFound?: boolean;
+}
+export interface ReattachOutageStopLineParts {
+    readonly taskId: string;
+    readonly action: string;
+    readonly nextMessage: string;
+}
+export type ReattachOutageStopLine = (parts: ReattachOutageStopLineParts) => string;
+export interface EndedGenerationMaterials {
+    readonly restartPending: boolean;
+    readonly outageStopLine?: ReattachOutageStopLine;
+}
+export interface EngineGenerationPort {
+    current: () => number;
+    endedMaterials: () => Promise<EndedGenerationMaterials>;
+    replacementInFlight?: () => boolean;
+    awaitEngineInstalled?: (signal: AbortSignal, maxMs: number) => Promise<boolean>;
+}
+export type EngineGenerationReading = {
+    readonly known: true;
+    readonly generation: number;
+} | {
+    readonly known: false;
+};
+export declare function engineGenerationReadingOf(read: (() => number | undefined) | undefined): EngineGenerationReading;
+export declare function engineGenerationOfPort(port: EngineGenerationPort | undefined): EngineGenerationReading;
+export interface EngineGenerationEndedFacts {
+    readonly run: EngineGenerationReading;
+    readonly current: EngineGenerationReading;
+    readonly freshCredentialAdopted?: boolean;
+}
+export declare function engineGenerationEnded(facts: EngineGenerationEndedFacts): boolean;
+export interface ApprovalFrameGenerationFacts {
+    readonly streamOpenedIn: EngineGenerationReading;
+    readonly current: EngineGenerationReading;
+    readonly freshCredentialAdopted?: boolean;
+}
+export declare function approvalFrameGenerationVerdict(facts: ApprovalFrameGenerationFacts): 'admit' | 'drop';
+export declare const REATTACH_AWAIT_NEXT_ENGINE_MS = 245000;
+export declare function unreachableForSettle(liveness: ReattachLivenessReading): boolean;
+export type EndedGenerationSettleStep = 'await-next-engine' | 'refresh-credentials' | 'credentials-rejected' | 'hand-over-terminal' | 'parked' | 'engine-stopped';
+export interface EndedGenerationSettleFacts {
+    readonly liveness: ReattachLivenessReading;
+    readonly canAwaitNextEngine: boolean;
+    readonly awaitedNextEngine: boolean;
+    readonly refreshedCredentials: boolean | null;
+    readonly terminalReadable?: boolean;
+}
+export declare function endedGenerationSettleStep(facts: EndedGenerationSettleFacts): EndedGenerationSettleStep;
+export declare const AWAIT_ENGINE_INSTALL_POLL_MS = 200;
+export interface AwaitNextEngineDeps {
+    readonly installed: () => boolean;
+    readonly replacing: () => boolean;
+    readonly now?: () => number;
+    readonly pollMs?: number;
+}
+export declare function awaitNextEngineInstalled(signal: AbortSignal, maxMs: number, deps: AwaitNextEngineDeps): Promise<boolean>;

package/dist/engineGenerationPort.js

@@ -0,0 +1,144 @@
+import { usableClockMs } from './clockReading.js';
+import { readSignalAborted, tryListenAbortOnce, tryUnlistenAbort } from './engineWireFor.js';
+export const REATTACH_RUN_STATES = Object.freeze(['done', 'died', 'parked', 'running', 'unreachable', 'unauthorized', 'engine-known-dead']);
+const UNKNOWN = Object.freeze({ known: false });
+export function engineGenerationReadingOf(read) {
+    if (typeof read !== 'function')
+        return UNKNOWN;
+    try {
+        const g = read();
+        return typeof g === 'number' && Number.isFinite(g) ? Object.freeze({ known: true, generation: g }) : UNKNOWN;
+    }
+    catch {
+        return UNKNOWN;
+    }
+}
+export function engineGenerationOfPort(port) {
+    if (typeof port !== 'object' || port === null)
+        return UNKNOWN;
+    return engineGenerationReadingOf(() => port.current());
+}
+export function engineGenerationEnded(facts) {
+    try {
+        const { run, current, freshCredentialAdopted } = facts;
+        const runGeneration = knownGenerationOf(run);
+        if (runGeneration === null)
+            return false;
+        if (freshCredentialAdopted === true)
+            return true;
+        const currentGeneration = knownGenerationOf(current);
+        if (currentGeneration === null)
+            return false;
+        return currentGeneration !== runGeneration;
+    }
+    catch {
+        return false;
+    }
+}
+function knownGenerationOf(reading) {
+    if (typeof reading !== 'object' || reading === null)
+        return null;
+    const raw = reading;
+    const known = raw.known;
+    const generation = raw.generation;
+    return known === true && typeof generation === 'number' && Number.isFinite(generation) ? generation : null;
+}
+export function approvalFrameGenerationVerdict(facts) {
+    try {
+        return engineGenerationEnded({ run: facts.streamOpenedIn, current: facts.current, ...(facts.freshCredentialAdopted === true ? { freshCredentialAdopted: true } : {}) }) ? 'drop' : 'admit';
+    }
+    catch {
+        return 'admit';
+    }
+}
+export const REATTACH_AWAIT_NEXT_ENGINE_MS = 245_000;
+export function unreachableForSettle(liveness) {
+    try {
+        return liveness.state === 'engine-known-dead' || (liveness.state === 'unreachable' && liveness.notFound !== true);
+    }
+    catch {
+        return false;
+    }
+}
+export function endedGenerationSettleStep(facts) {
+    try {
+        const liveness = facts.liveness;
+        if (typeof liveness !== 'object' || liveness === null || !REATTACH_RUN_STATES.includes(liveness.state))
+            return 'engine-stopped';
+        if (facts.canAwaitNextEngine === true && facts.awaitedNextEngine !== true && unreachableForSettle(liveness))
+            return 'await-next-engine';
+        if (liveness.state === 'unauthorized')
+            return facts.refreshedCredentials === null ? 'refresh-credentials' : 'credentials-rejected';
+        if (liveness.state === 'done')
+            return facts.terminalReadable === false ? 'engine-stopped' : 'hand-over-terminal';
+        if (liveness.state === 'parked')
+            return 'parked';
+        return 'engine-stopped';
+    }
+    catch {
+        return 'engine-stopped';
+    }
+}
+export const AWAIT_ENGINE_INSTALL_POLL_MS = 200;
+export function awaitNextEngineInstalled(signal, maxMs, deps) {
+    const clock = typeof deps.now === 'function' ? deps.now : () => performance.now();
+    const pollMs = typeof deps.pollMs === 'number' && Number.isFinite(deps.pollMs) && deps.pollMs > 0 ? deps.pollMs : AWAIT_ENGINE_INSTALL_POLL_MS;
+    const budgetMs = typeof maxMs === 'number' && Number.isFinite(maxMs) ? Math.max(0, maxMs) : 0;
+    const maxTicks = Math.ceil(budgetMs / pollMs) + 1;
+    const read = (f) => {
+        try {
+            return f() === true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const now = () => {
+        try {
+            return usableClockMs(clock());
+        }
+        catch {
+            return null;
+        }
+    };
+    return new Promise((resolve) => {
+        if (readSignalAborted(signal) === true) {
+            resolve(false);
+            return;
+        }
+        const start = now();
+        const deadline = start === null ? null : start + budgetMs;
+        let timer;
+        let done = false;
+        let ticks = 0;
+        const finish = (v) => {
+            if (done)
+                return;
+            done = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            tryUnlistenAbort(signal, onAbort);
+            resolve(v);
+        };
+        const onAbort = () => finish(false);
+        tryListenAbortOnce(signal, onAbort);
+        const tick = () => {
+            if (done)
+                return;
+            ticks += 1;
+            if (read(deps.installed))
+                return finish(true);
+            if (done)
+                return;
+            if (!read(deps.replacing))
+                return finish(read(deps.installed));
+            if (done)
+                return;
+            const t = now();
+            if (deadline === null || t === null || t >= deadline || ticks >= maxTicks)
+                return finish(false);
+            timer = setTimeout(tick, pollMs);
+        };
+        tick();
+    });
+}

package/dist/engineHealthFacts.d.ts

@@ -0,0 +1,23 @@
+import type { HealthAuthKind } from '@sema-agent/sdk';
+export interface EngineHealthCenterFacts {
+    readonly issuer?: string;
+    readonly webBaseUrl?: string;
+    readonly sessionsVisible: boolean | 'unknown';
+}
+export interface EngineHealthAuthFacts {
+    readonly required: boolean;
+    readonly kinds: readonly (HealthAuthKind | (string & {}))[];
+    readonly identityAttach: 'available' | 'unavailable';
+}
+export interface EngineHealthDrainingFacts {
+    readonly actionId: string;
+    readonly since: number;
+    readonly deadlineAt: number;
+}
+export interface EngineHealthFacts {
+    readonly center?: EngineHealthCenterFacts;
+    readonly auth?: EngineHealthAuthFacts;
+    readonly operator?: 'present' | 'absent';
+    readonly draining?: EngineHealthDrainingFacts;
+}
+export declare function readEngineHealthFacts(health: object | null | undefined): EngineHealthFacts;