@sema-agent/client-core 0.97.1 → 0.99.0

package/dist/engineCapReader.d.ts

@@ -1,3 +1,4 @@
+import type { UiLanguage } from './env/uiLanguage.js';
 interface EngineCapReaderSpec<R> {
     name: string;
     project: (caps: unknown) => R | undefined;
@@ -9,14 +10,10 @@ type ReaderUnreadable = {
     kind: 'unreadable';
 };
 interface EngineCapReader<R> {
-    note(baseUrl: string, caps: unknown, opts?: {
-        generation?: number;
-    }): void;
     observed(baseUrl: string | undefined): R | ReaderUnobserved | ReaderUnreadable;
-    __resetForTests(): void;
 }
 export declare function createEngineCapReader<R>(spec: EngineCapReaderSpec<R>): EngineCapReader<R>;
-export declare function unreadableReadingDetail(subject?: string): string;
+export declare function unreadableReadingDetail(subject?: string, lang?: UiLanguage): string;
 export type StoreSeat = {
     kind: 'object';
     store: object;

package/dist/engineCapReader.js

@@ -1,7 +1,10 @@
 import { engineCapsLandingOf } from './engineCapsCache.js';
+import { msg, renderMessage } from './i18n/translate.js';
 import { ownDataField } from './ownKey.js';
-const unobserved = () => ({ kind: 'unobserved' });
-const unreadable = () => ({ kind: 'unreadable' });
+const UNOBSERVED = Object.freeze({ kind: 'unobserved' });
+const UNREADABLE = Object.freeze({ kind: 'unreadable' });
+const unobserved = () => UNOBSERVED;
+const unreadable = () => UNREADABLE;
 function freezeReading(reading, seen = new Set()) {
     if (reading === null || typeof reading !== 'object' || seen.has(reading))
         return reading;
@@ -15,9 +18,8 @@ function freezeReading(reading, seen = new Set()) {
 }
 const PROJECTING = Symbol('projecting');
 export function createEngineCapReader(spec) {
-    let memo = new WeakMap();
+    const memo = new WeakMap();
     return {
-        note(_baseUrl, _caps, _opts) { },
         observed(baseUrl) {
             if (typeof baseUrl !== 'string' || baseUrl === '')
                 return unobserved();
@@ -48,14 +50,10 @@ export function createEngineCapReader(spec) {
             mine.set(landing, done);
             return done.reading === undefined ? unreadable() : done.reading;
         },
-        __resetForTests() {
-            memo = new WeakMap();
-        },
     };
 }
-export function unreadableReadingDetail(subject) {
-    const head = typeof subject === 'string' && subject.length > 0 ? `${subject} could not be read` : 'could not be read';
-    return `${head} — the engine's /v1/capabilities report arrived, but this entry is not in a form this client reads, so it is shown as unknown, not as absent; probing the same engine again will not change it while the engine reports it this way`;
+export function unreadableReadingDetail(subject, lang) {
+    return renderMessage(typeof subject === 'string' && subject.length > 0 ? msg('notice.capability.unreadable.subject', { subject }) : msg('notice.capability.unreadable.bare'), lang);
 }
 export function storeSeatOf(caps) {
     try {

package/dist/engineCapsCache.d.ts

@@ -6,6 +6,11 @@ export type EngineCapsLanding = {
 } | {
     readonly kind: 'unreadable';
 };
+export interface EngineCapsChange {
+    readonly kind: 'landed' | 'invalidated' | 'replaced';
+    readonly baseUrl: string;
+    readonly generation: number;
+}
 export declare function engineCapsGeneration(baseUrl: string): number;
 export declare function engineCapsLandingOf(baseUrl: string | undefined): EngineCapsLanding;
 export declare function kickEngineCapsProbe(baseUrl: string, probe: () => Promise<unknown>): void;
@@ -18,6 +23,10 @@ export declare function engineCapStateVia(baseUrl: string | undefined, key: stri
     withinMs?: number;
     signal?: AbortSignal;
 }): Promise<EngineCapState>;
+export declare function engineCapValueVia(baseUrl: string | undefined, key: string, probe: (signal?: AbortSignal) => Promise<object | null | undefined>, opts?: {
+    withinMs?: number;
+    signal?: AbortSignal;
+}): Promise<EngineCapValueState>;
 export declare function engineCapTrue(baseUrl: string | undefined, key: string): boolean;
 export declare function engineCapNestedTrue(baseUrl: string | undefined, parentKey: string, key: string): boolean;
 export declare function engineCapNestedValue(baseUrl: string | undefined, parentKey: string, key: string): EngineCapValueState;
@@ -38,6 +47,9 @@ export declare function engineCapString(baseUrl: string | undefined, key: string
 export declare function invalidateEngineCaps(baseUrl: string | undefined, probe?: () => Promise<unknown>): void;
 export type EngineCapsProbeRotation = 'started' | 'registered' | 'ignored';
 export declare function rotateEngineCapsProbe(baseUrl: string | undefined, probe: () => Promise<unknown>): EngineCapsProbeRotation;
+export type EngineCapsReprobe = 'reprobed' | 'no_probe' | 'ignored';
+export declare function invalidateEngineCapsAndReprobe(baseUrl: string | undefined): EngineCapsReprobe;
+export declare function registerCapsChangeDelivery(baseUrl: string | undefined, deliver: (change: EngineCapsChange) => void): () => void;
 export declare function refreshEngineCapsOnce(baseUrl: string | undefined, opts?: {
     withinMs?: number;
 }): Promise<'settled' | 'timed_out' | 'no_probe'>;

package/dist/engineCapsCache.js

@@ -4,11 +4,11 @@ const NOT_LANDED = Object.freeze({ kind: 'not_landed' });
 const capsByBase = new Map();
 const inFlight = new Set();
 const settleByBase = new Map();
-const genByBase = new Map();
+const stateByBase = new Map();
 const probeByBase = new Map();
 const refreshByBase = new Map();
 function capsGeneration(baseUrl) {
-    return genByBase.get(baseUrl) ?? 0;
+    return stateByBase.get(baseUrl)?.gen ?? 0;
 }
 export function engineCapsGeneration(baseUrl) {
     return capsGeneration(baseUrl);
@@ -169,6 +169,7 @@ function landCapsSnapshot(baseUrl, gen, caps) {
         ? Object.freeze({ kind: 'unreadable' })
         : Object.freeze({ kind: 'landed', caps: snapshot });
     capsByBase.set(baseUrl, record);
+    publishCapsChange(baseUrl, 'landed');
     return 'landed';
 }
 function snapshotCapsBody(body) {
@@ -197,7 +198,7 @@ function snapshotCapsBody(body) {
                 length = ld.value;
             }
             const proto = isArray ? null : Object.getPrototypeOf(src);
-            out = isArray ? new Array(length) : proto === Object.prototype || proto === null ? {} : Object.create(FOREIGN_PROTOTYPE);
+            out = isArray ? new Array(length) : isPlainRecordPrototype(proto) ? {} : Object.create(FOREIGN_PROTOTYPE);
         }
         catch {
             return UNREADABLE_NODE;
@@ -257,9 +258,6 @@ function slotInLanding(landing, key) {
             return capSlotIn(landing.caps, key);
     }
 }
-function capStateIn(caps, key) {
-    return stateOfSlot(capSlotIn(caps, key));
-}
 function stateOfSlot(slot) {
     switch (slot.kind) {
         case 'unobserved':
@@ -293,24 +291,30 @@ async function untilSettledOrAborted(p, signal) {
     }
 }
 export async function engineCapStateVia(baseUrl, key, probe, opts) {
+    return stateOfSlot(await capSlotVia(baseUrl, key, probe, opts));
+}
+export async function engineCapValueVia(baseUrl, key, probe, opts) {
+    return valueStateOfSlot(await capSlotVia(baseUrl, key, probe, opts));
+}
+async function capSlotVia(baseUrl, key, probe, opts) {
     const signal = opts?.signal;
     if (!baseUrl) {
         try {
             if (signal?.aborted)
-                return 'unprobed';
+                return SLOT_UNOBSERVED;
             const body = await probe(signal);
-            return isPlainCapsBody(body) ? capStateIn(body, key) : 'unprobed';
+            return isPlainCapsBody(body) ? capSlotIn(body, key) : SLOT_UNOBSERVED;
         }
         catch {
-            return 'unprobed';
+            return SLOT_UNOBSERVED;
         }
     }
-    const now = engineCapState(baseUrl, key);
-    if (now !== 'unprobed')
+    const now = slotInLanding(engineCapsLandingOf(baseUrl), key);
+    if (now.kind !== 'unobserved')
         return now;
     kickEngineCapsProbe(baseUrl, () => probe());
     await untilSettledOrAborted(engineCapsSettled(baseUrl, opts?.withinMs !== undefined ? { withinMs: opts.withinMs } : undefined), signal);
-    return engineCapState(baseUrl, key);
+    return slotInLanding(engineCapsLandingOf(baseUrl), key);
 }
 export function engineCapTrue(baseUrl, key) {
     return engineCapState(baseUrl, key) === 'true';
@@ -352,18 +356,25 @@ export function invalidateEngineCaps(baseUrl, probe) {
         return;
     if (probe === undefined)
         probeByBase.delete(baseUrl);
-    const hadState = capsByBase.has(baseUrl) ||
+    const hadLanding = capsByBase.has(baseUrl);
+    const hadState = hadLanding ||
         inFlight.has(baseUrl) ||
         settleByBase.has(baseUrl) ||
-        genByBase.has(baseUrl);
+        stateByBase.get(baseUrl)?.gen !== undefined;
     if (hadState) {
-        genByBase.set(baseUrl, capsGeneration(baseUrl) + 1);
+        const st = stateByBase.get(baseUrl);
+        if (st === undefined)
+            stateByBase.set(baseUrl, { gen: 1, subscribers: new Set() });
+        else
+            st.gen = capsGeneration(baseUrl) + 1;
         capsByBase.delete(baseUrl);
         inFlight.delete(baseUrl);
         settleByBase.get(baseUrl)?.wake();
     }
     if (probe !== undefined)
         kickEngineCapsProbe(baseUrl, probe);
+    if (hadLanding)
+        publishCapsChange(baseUrl, probe !== undefined ? 'replaced' : 'invalidated');
 }
 export function rotateEngineCapsProbe(baseUrl, probe) {
     try {
@@ -378,6 +389,51 @@ export function rotateEngineCapsProbe(baseUrl, probe) {
         return 'ignored';
     }
 }
+export function invalidateEngineCapsAndReprobe(baseUrl) {
+    try {
+        if (typeof baseUrl !== 'string' || baseUrl === '')
+            return 'ignored';
+        const probe = probeByBase.get(baseUrl);
+        if (probe === undefined)
+            return 'no_probe';
+        invalidateEngineCaps(baseUrl, probe);
+        return 'reprobed';
+    }
+    catch {
+        return 'ignored';
+    }
+}
+export function registerCapsChangeDelivery(baseUrl, deliver) {
+    if (typeof baseUrl !== 'string' || baseUrl === '' || typeof deliver !== 'function')
+        return () => { };
+    let st = stateByBase.get(baseUrl);
+    if (st === undefined) {
+        st = { gen: undefined, subscribers: new Set() };
+        stateByBase.set(baseUrl, st);
+    }
+    const sub = { deliver, live: true };
+    const owner = st;
+    owner.subscribers.add(sub);
+    return () => {
+        if (!sub.live)
+            return;
+        sub.live = false;
+        owner.subscribers.delete(sub);
+        if (owner.subscribers.size === 0 && owner.gen === undefined && stateByBase.get(baseUrl) === owner)
+            stateByBase.delete(baseUrl);
+    };
+}
+function publishCapsChange(baseUrl, kind) {
+    const subs = stateByBase.get(baseUrl)?.subscribers;
+    if (subs === undefined || subs.size === 0)
+        return;
+    const change = Object.freeze({ kind, baseUrl, generation: capsGeneration(baseUrl) });
+    for (const sub of [...subs]) {
+        if (!sub.live)
+            continue;
+        sub.deliver(change);
+    }
+}
 export async function refreshEngineCapsOnce(baseUrl, opts) {
     try {
         if (typeof baseUrl !== 'string' || baseUrl === '')
@@ -424,8 +480,7 @@ function isPlainCapsBody(caps) {
             return false;
         if (Array.isArray(caps))
             return false;
-        const proto = Object.getPrototypeOf(caps);
-        if (proto !== null && Object.getPrototypeOf(proto) !== null)
+        if (!isPlainRecordPrototype(Object.getPrototypeOf(caps)))
             return false;
         for (const key of Reflect.ownKeys(caps))
             Object.getOwnPropertyDescriptor(caps, key);
@@ -435,6 +490,9 @@ function isPlainCapsBody(caps) {
         return false;
     }
 }
+function isPlainRecordPrototype(proto) {
+    return proto === null || (typeof proto === 'object' && Object.getPrototypeOf(proto) === null);
+}
 async function awaitRefreshWithin(entry, budget) {
     if (budget === undefined) {
         await entry.promise;
@@ -449,7 +507,7 @@ export function __resetEngineCapsCacheForTests() {
     capsByBase.clear();
     inFlight.clear();
     settleByBase.clear();
-    genByBase.clear();
+    stateByBase.clear();
     probeByBase.clear();
     refreshByBase.clear();
 }

package/dist/engineCapsChange.d.ts

@@ -0,0 +1,2 @@
+import { type EngineCapsChange } from './engineCapsCache.js';
+export declare function onEngineCapsChange(baseUrl: string | undefined, listener: (change: EngineCapsChange) => void): () => void;

package/dist/engineCapsChange.js

@@ -0,0 +1,9 @@
+import { registerCapsChangeDelivery } from './engineCapsCache.js';
+import { invokeHostCallbackIsolated } from './hostCallbackGuard.js';
+export function onEngineCapsChange(baseUrl, listener) {
+    if (typeof listener !== 'function')
+        return () => { };
+    return registerCapsChangeDelivery(baseUrl, (change) => {
+        invokeHostCallbackIsolated('engineCapsChange: listener', () => listener(change));
+    });
+}

package/dist/engineClosedSets.d.ts

@@ -1,2 +1,3 @@
 export declare const ASK_EVIDENCE_ABSENCE_VALUES: readonly ["not_wired", "not_adjudicated", "unavailable", "no_match", "not_reported"];
 export declare const SYSTEM_INJECTION_PRIORITIES: readonly ["now", "next", "later"];
+export declare const BUILTIN_SUBAGENT_TYPES: readonly ["Explore", "Plan", "fork", "general-purpose"];

package/dist/engineClosedSets.js

@@ -1,3 +1,6 @@
-import { CORE_ASK_EVIDENCE_ABSENCE_VALUES, CORE_SYSTEM_INJECTION_PRIORITIES } from './generated/engineFactTables.js';
+import { CORE_ASK_EVIDENCE_ABSENCE_VALUES, CORE_BUILTIN_SUBAGENT_TYPES, CORE_SYSTEM_INJECTION_PRIORITIES } from './generated/engineFactTables.js';
 export const ASK_EVIDENCE_ABSENCE_VALUES = CORE_ASK_EVIDENCE_ABSENCE_VALUES;
 export const SYSTEM_INJECTION_PRIORITIES = CORE_SYSTEM_INJECTION_PRIORITIES;
+export const BUILTIN_SUBAGENT_TYPES = CORE_BUILTIN_SUBAGENT_TYPES;
+const _builtinSubagentTypePins = [true];
+void _builtinSubagentTypePins;

package/dist/engineErrorCodes.d.ts

@@ -1,3 +1,4 @@
+import type { RunDeathVerdictCode } from '@sema-agent/sdk';
 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";
@@ -18,7 +19,8 @@ export declare const CONFIG_IMAGE_INVALID = "config.image_invalid";
 export declare function imageInvalidFailureNoteOf(code: string | undefined): string | undefined;
 export declare const CONFIG_AGENT_UNKNOWN_TOOL = "config.agent.unknown_tool";
 export declare const CONFIG_OUTPUT_STYLE_INVALID = "config.output_style_invalid";
-export declare const RULES_LEGACY_TOOL_NAME = "rules.legacy_tool_name";
+export declare const RULES_INERT_ENTRY = "rules.inert_entry";
+export declare const RULES_INVALID_SHAPE = "rules.invalid_shape";
 export declare function isRulesRefusalCode(code: string | undefined): boolean;
 export declare const DELEGATION_CONCURRENCY_CAP = "delegation.concurrency_cap";
 export declare const DELEGATION_SESSION_CAP = "delegation.session_cap";
@@ -48,13 +50,14 @@ export declare function classifyActiveRunBusy(input: {
 }): BusyClassification;
 export declare function activeRunBusyCarrierOf(ev: unknown): Record<string, unknown> | null;
 export declare const CORRUPT_SESSION_ERROR_CODE = "corrupt_session";
+export declare const CORRUPT_ROW_ERROR_CODE = "corrupt";
+export declare const MEMORY_CONTROL_PLANE_CORRUPT = "internal.memory_control_plane_corrupt";
 export declare function isCorruptSessionCode(code: string | null | undefined): boolean;
 export declare const STOP_PARK_ARBITER_UNREACHABLE = "stop.park_arbiter_unreachable";
 export declare const STOP_PARK_RESUME_WON = "stop.park_resume_won";
 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 STOP_CONFLICT_CODES: readonly ["stop.park_arbiter_unreachable", "stop.park_resume_won", "stop.not_landed", "stop.not_local", "stop.parked"];
 export declare const OUTPUT_INVALID = "output.invalid";
 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"];
@@ -91,10 +94,13 @@ export declare const DECIDE_WORKFLOW_LANE_CODES: readonly string[];
 export declare const DECIDE_NOT_PARKED = "decide.not_parked";
 export declare const DECIDE_GATE_MOVED = "decide.gate_moved";
 export declare const DECIDE_CLAIM_LOST = "decide.claim_lost";
+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 APPROVAL_STALE = "approval_stale";
 export declare const APPROVAL_BINDING_MISMATCH = "approval_binding_mismatch";
+export declare const CHECKPOINT_INVALID_OUTCOME = "checkpoint.invalid_outcome";
 export declare const RESUME_OUTCOME_INVALID = "resume_outcome_invalid";
 export declare const CHECKPOINT_ALREADY_RESOLVED = "checkpoint.already_resolved";
 export declare const NOT_FOUND_APPROVAL = "not_found.approval";
@@ -106,7 +112,7 @@ export declare const ASK_GONE = "gone.ask";
 export declare const ASK_GONE_PARKED = "gone.ask_parked";
 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 = (typeof RUN_DEATH_VERDICT_CODES)[number];
+export type { RunDeathVerdictCode };
 export declare const RUN_STALLED: "run.stalled";
 export declare const RUN_ORPHANED: "run.orphaned";
 export declare const APPROVAL_EXPIRED: "approval.expired";
@@ -121,6 +127,8 @@ export declare function isWorkflowParkRefusalCode(code: unknown): boolean;
 export declare const DRAINING_ERROR_CODE = "draining";
 export declare const SCENARIO_NOT_ALLOWED_ERROR_CODE = "scenario_not_allowed";
 export declare const SCENARIO_ASSIGNMENT_UNKNOWN_ERROR_CODE = "state.scenario_assignment_unknown";
+export declare const USER_ATTACHMENT_INVALID_ERROR_CODE = "config.user_attachment_invalid";
+export declare const USER_INVOKED_SKILL_UNKNOWN_ERROR_CODE = "config.user_invoked_skill_unknown";
 export declare const STREAM_MAX_DURATION = "STREAM_MAX_DURATION";
 export type ModelFallbackReason = 'inherit_no_tier_binding';
 export declare const MODEL_FALLBACK_INHERIT_NO_TIER_BINDING: ModelFallbackReason;

package/dist/engineErrorCodes.js

@@ -28,7 +28,8 @@ export function imageInvalidFailureNoteOf(code) {
 }
 export const CONFIG_AGENT_UNKNOWN_TOOL = 'config.agent.unknown_tool';
 export const CONFIG_OUTPUT_STYLE_INVALID = 'config.output_style_invalid';
-export const RULES_LEGACY_TOOL_NAME = 'rules.legacy_tool_name';
+export const RULES_INERT_ENTRY = 'rules.inert_entry';
+export const RULES_INVALID_SHAPE = 'rules.invalid_shape';
 const RULES_ERROR_CODE_PREFIX = 'rules.';
 export function isRulesRefusalCode(code) {
     return typeof code === 'string' && code.startsWith(RULES_ERROR_CODE_PREFIX);
@@ -100,6 +101,8 @@ export function activeRunBusyCarrierOf(ev) {
     return null;
 }
 export const CORRUPT_SESSION_ERROR_CODE = 'corrupt_session';
+export const CORRUPT_ROW_ERROR_CODE = 'corrupt';
+export const MEMORY_CONTROL_PLANE_CORRUPT = 'internal.memory_control_plane_corrupt';
 export function isCorruptSessionCode(code) {
     return code === CORRUPT_SESSION_ERROR_CODE;
 }
@@ -108,13 +111,6 @@ export const STOP_PARK_RESUME_WON = 'stop.park_resume_won';
 export const STOP_NOT_LANDED = 'stop.not_landed';
 export const STOP_NOT_LOCAL = 'stop.not_local';
 export const STOP_PARKED = 'stop.parked';
-export const STOP_CONFLICT_CODES = Object.freeze([
-    STOP_PARK_ARBITER_UNREACHABLE,
-    STOP_PARK_RESUME_WON,
-    STOP_NOT_LANDED,
-    STOP_NOT_LOCAL,
-    STOP_PARKED,
-]);
 export const OUTPUT_INVALID = 'output.invalid';
 export const RESUME_POLICY_FOLD_CODE = 'resume_blocked_by_policy';
 export const STATUS_DERIVED_COARSE_CODES = SDK_STATUS_DERIVED_COARSE_CODES;
@@ -181,16 +177,21 @@ export const DECIDE_WORKFLOW_LANE_CODES = Object.freeze([
 export const DECIDE_NOT_PARKED = 'decide.not_parked';
 export const DECIDE_GATE_MOVED = 'decide.gate_moved';
 export const DECIDE_CLAIM_LOST = 'decide.claim_lost';
+export const CONFLICT_NOT_RESUMABLE = 'conflict.not_resumable';
+export const GATE_NOT_TOOL_APPROVAL = 'gate_not_tool_approval';
 export const DECIDE_PARK_MOVED_CODES = Object.freeze([
     DECIDE_NOT_PARKED,
     DECIDE_GATE_MOVED,
     DECIDE_CLAIM_LOST,
+    CONFLICT_NOT_RESUMABLE,
+    GATE_NOT_TOOL_APPROVAL,
 ]);
 export function isDecideParkMovedCode(code) {
     return typeof code === 'string' && DECIDE_PARK_MOVED_CODES.includes(code);
 }
 export const APPROVAL_STALE = 'approval_stale';
 export const APPROVAL_BINDING_MISMATCH = 'approval_binding_mismatch';
+export const CHECKPOINT_INVALID_OUTCOME = 'checkpoint.invalid_outcome';
 export const RESUME_OUTCOME_INVALID = 'resume_outcome_invalid';
 export const CHECKPOINT_ALREADY_RESOLVED = 'checkpoint.already_resolved';
 export const NOT_FOUND_APPROVAL = 'not_found.approval';
@@ -258,6 +259,8 @@ export function isWorkflowParkRefusalCode(code) {
 export const DRAINING_ERROR_CODE = 'draining';
 export const SCENARIO_NOT_ALLOWED_ERROR_CODE = 'scenario_not_allowed';
 export const SCENARIO_ASSIGNMENT_UNKNOWN_ERROR_CODE = 'state.scenario_assignment_unknown';
+export const USER_ATTACHMENT_INVALID_ERROR_CODE = 'config.user_attachment_invalid';
+export const USER_INVOKED_SKILL_UNKNOWN_ERROR_CODE = 'config.user_invoked_skill_unknown';
 export const STREAM_MAX_DURATION = 'STREAM_MAX_DURATION';
 export const MODEL_FALLBACK_INHERIT_NO_TIER_BINDING = 'inherit_no_tier_binding';
 export function asModelFallbackReason(v) {

package/dist/engineIdentity.d.ts

@@ -9,3 +9,4 @@ export type EngineIdentityVerdict = 'changed' | 'same' | 'unknown';
 export declare function engineIdentityVerdict(a: unknown, b: unknown): EngineIdentityVerdict;
 export declare function engineIdentityChangedBy(a: unknown, b: unknown): keyof EngineIdentityView | undefined;
 export declare function engineIdentityChanged(a: unknown, b: unknown): boolean;
+export declare function toolKillCauseAcrossEngineIdentity(before: object | null | undefined, after: object | null | undefined): 'engine_restarted' | undefined;

package/dist/engineIdentity.js

@@ -55,3 +55,11 @@ export function engineIdentityChangedBy(a, b) {
 export function engineIdentityChanged(a, b) {
     return engineIdentityVerdict(a, b) === 'changed';
 }
+export function toolKillCauseAcrossEngineIdentity(before, after) {
+    try {
+        return engineIdentityVerdict(before, after) === 'changed' ? 'engine_restarted' : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/engineRowRef.d.ts

@@ -0,0 +1,28 @@
+import type { AgentEvent } from '@sema-agent/sdk';
+export interface EngineRowRef {
+    readonly eventId?: string;
+    readonly taskId?: string;
+    readonly sessionId?: string;
+}
+export type SameEngineRefVerdict = 'same' | 'different' | 'unknown';
+export interface EngineBoundRun {
+    readonly taskId?: string;
+    readonly sessionId?: string;
+}
+export declare function engineRefOf(row: object | null | undefined): EngineRowRef | undefined;
+export declare function sameEngineRef(a: object | null | undefined, b: object | null | undefined): SameEngineRefVerdict;
+export declare function wireEventIdOf(ev: object): string | undefined;
+export declare function envelopeUuidOf(eventId: string, envelopeType: string): string;
+export type TerminalUuidLabel = 'result' | 'terminal-row' | 'outcome-unknown';
+export declare function terminalUuidOf(runId: string, label: TerminalUuidLabel): string;
+export declare function readBoundRun(call: () => EngineBoundRun | undefined): EngineBoundRun | undefined;
+export declare function mintEngineRowRef(eventId: string, bound: EngineBoundRun | undefined): EngineRowRef;
+export declare function terminalRunIdOf(ev: Extract<AgentEvent, {
+    type: 'done';
+} | {
+    type: 'failed';
+}>): string | undefined;
+export declare const TRANSCRIPT_ROW_SIDECAR_KEYS: readonly string[];
+export declare function parkHeldCallIdOf(carrier: {} | null | undefined): string | undefined;
+export declare function parkedToolEndRoleOf(frame: {} | null | undefined): 'held' | 'collateral' | undefined;
+export declare function isUnsettledHeldToolEnd(frame: {} | null | undefined): boolean;

package/dist/engineRowRef.js

@@ -0,0 +1,114 @@
+import { guardedRead, readFrameStringKey, readOwnDataNonEmptyString, readOwnDataValue } from './ownKey.js';
+import { GATE_PARKED_ERROR_CODE } from './engineErrorCodes.js';
+import { isCcToolDenialKind } from './gateVocabulary.js';
+import { doneResultView } from './replayBody.js';
+import { TRANSCRIPT_ID_NAMESPACE, uuidV5 } from './uuidV5.js';
+const ENGINE_REF_KEY = '_sema_engine_ref';
+function refFromCarrier(carrier) {
+    const out = {};
+    for (const k of ['eventId', 'taskId', 'sessionId']) {
+        const v = guardedRead(() => readOwnDataNonEmptyString(carrier, k));
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out.eventId !== undefined || out.taskId !== undefined || out.sessionId !== undefined ? out : undefined;
+}
+export function engineRefOf(row) {
+    if (typeof row !== 'object' || row === null)
+        return undefined;
+    const carrier = guardedRead(() => readOwnDataValue(row, ENGINE_REF_KEY));
+    if (typeof carrier !== 'object' || carrier === null)
+        return undefined;
+    if (guardedRead(() => (Array.isArray(carrier) ? undefined : true)) !== true)
+        return undefined;
+    return refFromCarrier(carrier);
+}
+export function sameEngineRef(a, b) {
+    const ra = engineRefOf(a);
+    const rb = engineRefOf(b);
+    if (ra?.eventId !== undefined && rb?.eventId !== undefined)
+        return ra.eventId === rb.eventId ? 'same' : 'different';
+    if (ra?.taskId !== undefined && rb?.taskId !== undefined && ra.taskId !== rb.taskId)
+        return 'different';
+    if (ra?.sessionId !== undefined && rb?.sessionId !== undefined && ra.sessionId !== rb.sessionId)
+        return 'different';
+    return 'unknown';
+}
+export function wireEventIdOf(ev) {
+    return guardedRead(() => readOwnDataNonEmptyString(ev, 'eventId'));
+}
+export function envelopeUuidOf(eventId, envelopeType) {
+    return uuidV5(TRANSCRIPT_ID_NAMESPACE, `ev_${eventId}#${envelopeType}`);
+}
+export function terminalUuidOf(runId, label) {
+    return uuidV5(TRANSCRIPT_ID_NAMESPACE, `run_${runId}#${label}`);
+}
+export function readBoundRun(call) {
+    let raw;
+    try {
+        raw = call();
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const then = guardedRead(() => raw.then);
+    if (typeof then === 'function') {
+        void Promise.resolve(raw).then(undefined, () => undefined);
+        return undefined;
+    }
+    const taskId = guardedRead(() => readOwnDataNonEmptyString(raw, 'taskId'));
+    const sessionId = guardedRead(() => readOwnDataNonEmptyString(raw, 'sessionId'));
+    if (taskId === undefined && sessionId === undefined)
+        return undefined;
+    return { ...(taskId !== undefined ? { taskId } : {}), ...(sessionId !== undefined ? { sessionId } : {}) };
+}
+export function mintEngineRowRef(eventId, bound) {
+    return {
+        eventId,
+        ...(bound?.taskId !== undefined ? { taskId: bound.taskId } : {}),
+        ...(bound?.sessionId !== undefined ? { sessionId: bound.sessionId } : {}),
+    };
+}
+export function terminalRunIdOf(ev) {
+    if (ev.type !== 'done')
+        return undefined;
+    const v = (doneResultView(ev.result).engine ?? ev.result)?.runId;
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+export const TRANSCRIPT_ROW_SIDECAR_KEYS = Object.freeze([
+    '_sema_segment_id',
+    '_sema_engine_ref',
+    '_sema_replay',
+    '_sema_api_error_message',
+    '_sema_tool_history_mismatch',
+    '_sema_provider_rejection_resend',
+    '_sema_tool_recovered',
+    '_sema_degraded',
+    '_sema_denial_kind',
+    '_sema_gate',
+    '_sema_not_executed',
+    '_sema_collateral_abort',
+    '_sema_interrupted_never_started',
+    '_sema_approval_window_expired',
+    '_sema_denial_limit_window_expired',
+    '_sema_api_error_status',
+    '_sema_api_error_code',
+    '_sema_provider_condition',
+]);
+export function parkHeldCallIdOf(carrier) {
+    return readFrameStringKey(carrier, 'toolCallId');
+}
+export function parkedToolEndRoleOf(frame) {
+    if (readFrameStringKey(frame, 'errorCode') !== GATE_PARKED_ERROR_CODE)
+        return undefined;
+    const gated = readFrameStringKey(frame, 'gatedCallId');
+    const call = readFrameStringKey(frame, 'toolCallId');
+    if (gated === undefined || call === undefined)
+        return undefined;
+    return gated === call ? 'held' : 'collateral';
+}
+export function isUnsettledHeldToolEnd(frame) {
+    return parkedToolEndRoleOf(frame) === 'held' && !isCcToolDenialKind(readFrameStringKey(frame, '_sema_denial_kind'));
+}