@sema-agent/client-core 0.91.0 → 0.93.0

package/dist/generated/engineFactTables.js

@@ -151,6 +151,8 @@ export const CORE_MODE_ARBITRATION = Object.freeze({
     "rule_unreadable": Object.freeze({ bypassImmune: false, classifierEligible: false, sandboxAdmission: false, ruleMayClear: false, hookAskFloor: false }),
     "ask_rule": Object.freeze({ bypassImmune: true, classifierEligible: false, sandboxAdmission: false, ruleMayClear: false, hookAskFloor: true }),
     "denial_limit_fallback": Object.freeze({ bypassImmune: true, classifierEligible: false, sandboxAdmission: false, ruleMayClear: false, hookAskFloor: false }),
+    "classifier_no_ruling": Object.freeze({ bypassImmune: true, classifierEligible: false, sandboxAdmission: false, ruleMayClear: false, hookAskFloor: false }),
+    "requires_user_interaction": Object.freeze({ bypassImmune: true, classifierEligible: false, sandboxAdmission: false, ruleMayClear: false, hookAskFloor: true }),
     "operator_forced": Object.freeze({ bypassImmune: true, classifierEligible: true, sandboxAdmission: true, ruleMayClear: false, hookAskFloor: false }),
     "shell_floor": Object.freeze({ bypassImmune: true, classifierEligible: true, sandboxAdmission: true, ruleMayClear: false, hookAskFloor: false }),
     "write_protection_unresolved": Object.freeze({ bypassImmune: true, classifierEligible: false, sandboxAdmission: true, ruleMayClear: false, hookAskFloor: true }),
@@ -164,3 +166,92 @@ export const CORE_MODE_ARBITRATION = Object.freeze({
     "unstated": Object.freeze({ bypassImmune: false, classifierEligible: true, sandboxAdmission: false, ruleMayClear: true, hookAskFloor: false }),
     "ordinary": Object.freeze({ bypassImmune: false, classifierEligible: true, sandboxAdmission: true, ruleMayClear: true, hookAskFloor: false }),
 });
+export const CORE_SKILL_GRANT_ORIGINS = Object.freeze([
+    "model",
+    "user",
+    "inherited",
+]);
+export const CORE_ALLOW_ENTRY_INERT_REASONS = Object.freeze([
+    "wildcard_all",
+    "namespace_wildcard",
+    "path_pattern",
+    "domain",
+    "content_unsupported",
+    "grammar",
+    "tool_name",
+    "near_miss",
+]);
+export const CORE_ALLOW_RULE_MEMBERS = Object.freeze([
+    "hook",
+    "deployment",
+    "persisted",
+    "skill",
+    "request",
+]);
+export const CORE_RULE_TOOL_NAME_VERDICTS = Object.freeze([
+    "current",
+    "retired",
+    "unprefixed_namespace",
+    "unmintable_segment",
+]);
+export const CORE_SETTLEMENT_KINDS = Object.freeze([
+    "human_allowed",
+    "human_refused",
+    "approval_window_expired",
+    "denial_limit_window_expired",
+    "park_sla_expired",
+    "no_approver",
+    "approver_unavailable",
+    "approver_error",
+    "approver_contract",
+    "presentation_failed",
+    "blanket_allow_refused",
+    "policy_allowed",
+    "policy_refused",
+    "task_aborted",
+]);
+export const CORE_CLASSIFIER_DENY_CAUSES = Object.freeze([
+    "unavailable",
+    "parse_error",
+]);
+export const CORE_AUTO_MODE_UNAVAILABLE_CAUSES = Object.freeze([
+    "error",
+    "timeout",
+]);
+export const CORE_DEFAULT_TIER_ORDER = Object.freeze([
+    "ultra",
+    "max",
+    "pro",
+    "flash",
+    "lite",
+]);
+export const CORE_CC_MODEL_TIER_ALIASES = Object.freeze({
+    "fable": "max",
+    "mythos": "max",
+    "opus": "pro",
+    "sonnet": "flash",
+    "haiku": "lite",
+});
+export const CORE_DURABLE_AGENT_HANDLE_RE = Object.freeze(/^a[0-9a-f]{6,32}$/);
+export const CORE_PERMISSION_MODE_CLASSES = Object.freeze([
+    "bypass",
+    "prompting",
+]);
+export const CORE_MCP_LIVENESS_STATES = Object.freeze([
+    "reachable",
+    "unreachable",
+    "unknown",
+]);
+export const CORE_RULE_BEHAVIORS = Object.freeze([
+    "deny",
+    "ask",
+    "allow",
+]);
+export const CORE_MCP_IMAGE_MAX_BASE64 = 5242880;
+export const CORE_MAX_PENDING_STEER_CHARS = 16000;
+export const CORE_PROMPT_BLOCK_CAUSES = Object.freeze([
+    "block",
+    "crashed",
+    "timeout",
+    "cancelled",
+]);

package/dist/generated/engineNoticeTables.d.ts

@@ -2,5 +2,5 @@ export declare const CORE_ENGINE_NOTICE_CODES: readonly string[];
 export declare const CORE_NOTICE_AUDIENCE: Readonly<Record<string, 'user' | 'operator'>>;
 export declare const CORE_MCP_INJECTION_DROP_REASONS: readonly string[];
 export declare const CORE_NOTICE_MINTER: Readonly<Record<string, 'engine' | 'server'>>;
-export declare const CORE_USER_STEER_UNDRAINED_CAUSES: readonly ["leg_end", "crashed"];
+export declare const CORE_USER_INPUT_UNDRAINED_CAUSES: readonly ["leg_end", "crashed"];
 export declare const CORE_TOOL_TURN_INCOMPLETE_CAUSES: readonly ["truncated", "unnamed", "bad_frame", "missing_result_synthesized"];

package/dist/generated/engineNoticeTables.js

@@ -28,6 +28,7 @@ export const CORE_ENGINE_NOTICE_CODES = Object.freeze([
     "permission.ask_released_by_mode",
     "permission.read_deny_unapplied",
     "permission.rule_store_unavailable",
+    "permission.allowed_tool_not_granted",
     "peer.inbound_disposition",
     "peer.held_settled",
     "peer.idle_subscription",
@@ -115,6 +116,7 @@ export const CORE_NOTICE_AUDIENCE = Object.freeze({
     "permission.ask_released_by_mode": "user",
     "permission.read_deny_unapplied": "user",
     "permission.rule_store_unavailable": "user",
+    "permission.allowed_tool_not_granted": "user",
     "peer.inbound_disposition": "user",
     "peer.held_settled": "user",
     "peer.idle_subscription": "user",
@@ -208,6 +210,7 @@ export const CORE_NOTICE_MINTER = Object.freeze({
     "permission.ask_released_by_mode": "engine",
     "permission.read_deny_unapplied": "engine",
     "permission.rule_store_unavailable": "engine",
+    "permission.allowed_tool_not_granted": "engine",
     "peer.inbound_disposition": "engine",
     "peer.held_settled": "engine",
     "peer.idle_subscription": "engine",
@@ -265,7 +268,7 @@ export const CORE_NOTICE_MINTER = Object.freeze({
     "memory.layer_locked_legacy": "server",
     "server.model_unreachable": "server",
 });
-export const CORE_USER_STEER_UNDRAINED_CAUSES = Object.freeze([
+export const CORE_USER_INPUT_UNDRAINED_CAUSES = Object.freeze([
     "leg_end",
     "crashed",
 ]);

package/dist/generated/settingsSchemaTables.d.ts

@@ -0,0 +1,8 @@
+export declare const SETTINGS_ENGINE_OWNED_HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PreCompact", "PostCompact", "Stop", "StopFailure", "UserPromptSubmit"];
+export declare const SETTINGS_SECRET_LITERAL_RE: RegExp;
+export declare const SETTINGS_TIER_GROUP_NAME_RE: RegExp;
+export declare const SETTINGS_BUDGET_NUMBER_KEYS: readonly ["maxBudgetUsd", "tpmLimit", "rpmLimit", "maxParallelRequests", "maxRunCostUsd", "maxIterations"];
+export declare const SETTINGS_BUDGET_STRING_KEYS: readonly ["mode", "budgetDuration", "enforcement"];
+export declare const SETTINGS_BUDGET_PER_MODEL_NUMBER_KEYS: readonly ["maxBudgetUsd", "tpmLimit", "rpmLimit"];
+export declare const SETTINGS_MODEL_API_WORDS: readonly ["openai-completions", "anthropic-messages"];
+export declare const SETTINGS_TOOL_NAME_MATCHER_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure"];

package/dist/generated/settingsSchemaTables.js

@@ -0,0 +1,40 @@
+export const SETTINGS_ENGINE_OWNED_HOOK_EVENTS = Object.freeze([
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PostToolBatch",
+    "PreCompact",
+    "PostCompact",
+    "Stop",
+    "StopFailure",
+    "UserPromptSubmit",
+]);
+export const SETTINGS_SECRET_LITERAL_RE = Object.freeze(/^(sk-|gh[opus]_|github_pat_|xox[baprse]-|xapp-|bearer\s|basic\s|eyJ[A-Za-z0-9_-]{10,}\.|AKIA[0-9A-Z]{12,}|AIza[0-9A-Za-z_-]{20,}|-----BEGIN[A-Z0-9 ]*PRIVATE KEY)/i);
+export const SETTINGS_TIER_GROUP_NAME_RE = Object.freeze(/^[a-z0-9][a-z0-9._-]*$/i);
+export const SETTINGS_BUDGET_NUMBER_KEYS = Object.freeze([
+    "maxBudgetUsd",
+    "tpmLimit",
+    "rpmLimit",
+    "maxParallelRequests",
+    "maxRunCostUsd",
+    "maxIterations",
+]);
+export const SETTINGS_BUDGET_STRING_KEYS = Object.freeze([
+    "mode",
+    "budgetDuration",
+    "enforcement",
+]);
+export const SETTINGS_BUDGET_PER_MODEL_NUMBER_KEYS = Object.freeze([
+    "maxBudgetUsd",
+    "tpmLimit",
+    "rpmLimit",
+]);
+export const SETTINGS_MODEL_API_WORDS = Object.freeze([
+    "openai-completions",
+    "anthropic-messages",
+]);
+export const SETTINGS_TOOL_NAME_MATCHER_EVENTS = Object.freeze([
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+]);

package/dist/goalStopHook.d.ts

@@ -1,15 +1,8 @@
 import { type EnvLike } from './hostEnv.js';
 import type { WireHooksConfig } from './finalVerifyWire.js';
 export declare const GOAL_STOP_HOOK_WIRE_ENV = "SEMA_GOAL_STOP_HOOK_WIRE";
-export declare const CC_STOP_SEMANTICS_MIN_SERVER = "1.279.3";
-export declare function ccStopSemanticsFromVersion(version: string | undefined | null): boolean;
-export declare function engineCcStopSemantics(env?: EnvLike): boolean;
 export declare function isGoalStopHookWireArmed(env?: EnvLike): boolean;
-export declare function setWireSessionStopHook(prompt: string | null, opts?: {
-    ccSemantics?: boolean;
-}): void;
+export declare function setWireSessionStopHook(prompt: string | null): void;
 export declare function getWireSessionStopHook(): string | null;
-export declare function getWireSessionStopHookCcSemantics(): boolean;
-export declare function buildGoalStopHookPrompt(condition: string): string;
 export declare function goalStopHookMatcher(managedOnly: boolean): NonNullable<WireHooksConfig[string]>[number] | null;
 export declare function __resetGoalStopHookForTests(): void;

package/dist/goalStopHook.js

@@ -1,80 +1,24 @@
 import { hostEnv } from './hostEnv.js';
 import { envFlagOff } from './envFlag.js';
-import { engineCapString } from './engineCapsCache.js';
 let wireSessionStopHookPrompt = null;
-let wireSessionStopHookCcSemantics = false;
 export const GOAL_STOP_HOOK_WIRE_ENV = 'SEMA_GOAL_STOP_HOOK_WIRE';
-export const CC_STOP_SEMANTICS_MIN_SERVER = '1.279.3';
-function parseSemverCore(v) {
-    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
-    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
-}
-export function ccStopSemanticsFromVersion(version) {
-    if (typeof version !== 'string' || version.length === 0)
-        return false;
-    const got = parseSemverCore(version);
-    const min = parseSemverCore(CC_STOP_SEMANTICS_MIN_SERVER);
-    if (got === null || min === null)
-        return false;
-    const [gotMajor, gotMinor, gotPatch] = got;
-    const [minMajor, minMinor, minPatch] = min;
-    if (gotMajor !== minMajor)
-        return gotMajor > minMajor;
-    if (gotMinor !== minMinor)
-        return gotMinor > minMinor;
-    if (gotPatch !== minPatch)
-        return gotPatch > minPatch;
-    return true;
-}
-export function engineCcStopSemantics(env = hostEnv()) {
-    const base = env.SEMA_LIVE_BASEURL;
-    if (!base)
-        return false;
-    return ccStopSemanticsFromVersion(engineCapString(base, 'version'));
-}
 export function isGoalStopHookWireArmed(env = hostEnv()) {
     return !envFlagOff(env[GOAL_STOP_HOOK_WIRE_ENV]);
 }
-export function setWireSessionStopHook(prompt, opts) {
+export function setWireSessionStopHook(prompt) {
     wireSessionStopHookPrompt = prompt && prompt.length > 0 ? prompt : null;
-    wireSessionStopHookCcSemantics = wireSessionStopHookPrompt === null ? false : opts?.ccSemantics === true;
 }
 export function getWireSessionStopHook() {
     return wireSessionStopHookPrompt;
 }
-export function getWireSessionStopHookCcSemantics() {
-    return wireSessionStopHookCcSemantics;
-}
-export function buildGoalStopHookPrompt(condition) {
-    const reason = `[session goal] Before you stop: verify that this goal actually holds — ${condition}. ` +
-        `If it does hold, say so plainly and finish. If it does not, keep working toward it and do not ` +
-        `pause to ask the user what to do.`;
-    return ('You are the Stop gate for an autonomous coding agent session. The user set this session goal, ' +
-        'which the agent is supposed to satisfy before it stops:\n' +
-        `<goal>\n${condition}\n</goal>\n` +
-        'Stop-hook input JSON: $ARGUMENTS\n' +
-        'Reply with RAW JSON only — no prose, no explanation, no code fences.\n' +
-        'If the input JSON has "stop_hook_active" set to true, this gate already fired once for this turn: ' +
-        'reply with exactly {"continue":true} so the agent may stop.\n' +
-        'Otherwise reply with exactly:\n' +
-        JSON.stringify({ decision: 'block', reason }));
-}
 export function goalStopHookMatcher(managedOnly) {
     if (wireSessionStopHookPrompt === null || managedOnly || !isGoalStopHookWireArmed())
         return null;
     return {
         matcher: '',
-        hooks: [
-            {
-                type: 'prompt',
-                prompt: wireSessionStopHookCcSemantics
-                    ? wireSessionStopHookPrompt
-                    : buildGoalStopHookPrompt(wireSessionStopHookPrompt),
-            },
-        ],
+        hooks: [{ type: 'prompt', prompt: wireSessionStopHookPrompt }],
     };
 }
 export function __resetGoalStopHookForTests() {
     wireSessionStopHookPrompt = null;
-    wireSessionStopHookCcSemantics = false;
 }

package/dist/headlessPermissionModeWire.d.ts

@@ -1,13 +1,14 @@
 import { type PermissionMode, type PermissionModeField } from './permissionWireCaps.js';
+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): string | undefined;
+export declare function normalizeShellPermissionModeForWire(mode: string | undefined, permissionModes?: PermissionModesReading): string | undefined;
 export type HeadlessPermissionResolution = {
     fields: PermissionModeField;
     source: 'flag' | 'env' | 'default' | 'absent';
     warning?: string;
 };
 export declare function permissionModeFromArgv(argv: readonly string[]): string | undefined;
-export declare function resolveHeadlessPermissionMode(argv: readonly string[], env?: EnvLike): HeadlessPermissionResolution;
+export declare function resolveHeadlessPermissionMode(argv: readonly string[], env?: EnvLike, permissionModes?: PermissionModesReading): HeadlessPermissionResolution;
 export declare function _resetHeadlessPermissionModeWireForTest(): void;

package/dist/headlessPermissionModeWire.js

@@ -1,16 +1,20 @@
 import { permissionModeField } from './permissionWireCaps.js';
+import { permissionModeAdmitted } from './permissionModesCapability.js';
 import { hostEnv } from './hostEnv.js';
 import { lastFlagValue } from './argvFlagValue.js';
 import { PERMISSION_MODE_WORDS } from './taskRequestWords.js';
+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'],
     ['dontAsk', 'default'],
 ]);
-export function normalizeShellPermissionModeForWire(mode) {
+export function normalizeShellPermissionModeForWire(mode, permissionModes) {
     if (mode === undefined)
         return undefined;
+    if (mode === 'dontAsk' && permissionModeAdmitted(permissionModes, mode))
+        return mode;
     return SHELL_INTERNAL_MODE_TO_WIRE.get(mode) ?? mode;
 }
 export function permissionModeFromArgv(argv) {
@@ -27,19 +31,32 @@ export function permissionModeFromArgv(argv) {
     return undefined;
 }
 let warnedInvalidEnv = false;
-export function resolveHeadlessPermissionMode(argv, env = hostEnv()) {
+export function resolveHeadlessPermissionMode(argv, env = hostEnv(), permissionModes) {
     const flagMode = permissionModeFromArgv(argv);
     if (flagMode !== undefined) {
-        const normalized = normalizeShellPermissionModeForWire(flagMode);
-        return { fields: permissionModeField(normalized, { stampDefault: true }), source: 'flag' };
+        const snap = flagMode === 'dontAsk' ? dontAskSnapshot(permissionModes) : undefined;
+        const normalized = normalizeShellPermissionModeForWire(flagMode, snap);
+        return { fields: permissionModeField(normalized, { stampDefault: true, permissionModes: snap }), source: 'flag' };
     }
     const raw = env[HEADLESS_PERMISSION_MODE_ENV]?.trim();
     if (raw === undefined || raw === '') {
         return { fields: permissionModeField('default', { stampDefault: true }), source: 'default' };
     }
     if (HEADLESS_PERMISSION_WIRE_MODES.includes(raw)) {
+        const snap = raw === 'dontAsk' ? dontAskSnapshot(permissionModes) : undefined;
+        if (raw === 'dontAsk' && snap === undefined) {
+            const downgraded = {
+                fields: permissionModeField('default', { stampDefault: true }),
+                source: 'env',
+            };
+            if (!warnedInvalidEnv) {
+                warnedInvalidEnv = true;
+                downgraded.warning = `sema: ${HEADLESS_PERMISSION_MODE_ENV}="dontAsk" is only sent once this client knows the engine accepts that mode, and ${dontAskWithheldClause(permissionModes)} — this run uses "default"`;
+            }
+            return downgraded;
+        }
         return {
-            fields: permissionModeField(raw, { stampDefault: true }),
+            fields: permissionModeField(raw, { stampDefault: true, permissionModes: snap }),
             source: 'env',
         };
     }
@@ -53,6 +70,30 @@ export function resolveHeadlessPermissionMode(argv, env = hostEnv()) {
     }
     return resolution;
 }
+function dontAskSnapshot(reading) {
+    return permissionModeAdmitted(reading, 'dontAsk') ? { kind: 'present', modes: Object.freeze(['dontAsk']) } : undefined;
+}
+function dontAskWithheldClause(reading) {
+    if (reading === undefined)
+        return 'no such reading was supplied for this run';
+    let kind;
+    try {
+        kind = typeof reading === 'object' && reading !== null ? readOwnDataValue(reading, 'kind') : undefined;
+    }
+    catch {
+        kind = undefined;
+    }
+    switch (kind) {
+        case 'unobserved':
+            return "this engine's capabilities have not been read yet (wait for them before the first request)";
+        case 'not_reported':
+            return 'this engine does not report which modes it accepts';
+        case 'present':
+            return "this engine's list of accepted modes does not include it";
+        default:
+            return 'the reading supplied for it could not be read';
+    }
+}
 export function _resetHeadlessPermissionModeWireForTest() {
     warnedInvalidEnv = false;
 }

package/dist/hitl/allowRuleShadow.d.ts

@@ -0,0 +1,21 @@
+export interface ApprovalAllowRuleShadowMember {
+    readonly member?: string;
+    readonly known: boolean;
+    readonly entries?: readonly string[];
+    readonly omitted?: number;
+    readonly malformed?: true;
+}
+export interface AllowRuleShadowedWireMember {
+    readonly member: string;
+    readonly entries: readonly string[];
+    readonly omitted?: number;
+}
+export interface ApprovalAllowRuleShadow {
+    readonly source: 'allow_rule_shadowed' | 'legacy_shadowed_rule';
+    readonly members: readonly ApprovalAllowRuleShadowMember[];
+    readonly unreadable?: true;
+}
+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;

package/dist/hitl/allowRuleShadow.js

@@ -0,0 +1,167 @@
+import { CORE_ALLOW_RULE_MEMBERS } from '../generated/engineFactTables.js';
+const KNOWN_MEMBERS = new Set(CORE_ALLOW_RULE_MEMBERS);
+function freezeMember(m) {
+    return Object.freeze({ ...m });
+}
+function unreadable() {
+    return Object.freeze({ source: 'allow_rule_shadowed', members: Object.freeze([]), unreadable: true });
+}
+function readMemberRecord(r) {
+    if (typeof r !== 'object' || r === null || Array.isArray(r))
+        return freezeMember({ known: false, malformed: true });
+    let malformed = false;
+    const rawMember = Object.hasOwn(r, 'member') ? r.member : undefined;
+    const member = typeof rawMember === 'string' && rawMember !== '' ? rawMember : undefined;
+    if (member === undefined)
+        malformed = true;
+    let entries;
+    const rawEntries = Object.hasOwn(r, 'entries') ? r.entries : undefined;
+    if (Array.isArray(rawEntries)) {
+        const length = rawEntries.length;
+        if (typeof length === 'number' && Number.isSafeInteger(length) && length >= 0) {
+            const out = [];
+            let ok = true;
+            for (let i = 0; i < length; i++) {
+                const d = Object.getOwnPropertyDescriptor(rawEntries, i);
+                if (d === undefined || !('value' in d)) {
+                    ok = false;
+                    break;
+                }
+                const e = d.value;
+                if (typeof e !== 'string') {
+                    ok = false;
+                    break;
+                }
+                out.push(e);
+            }
+            if (ok && rawEntries.length === length)
+                entries = Object.freeze(out);
+            else
+                malformed = true;
+        }
+        else
+            malformed = true;
+    }
+    else
+        malformed = true;
+    let omitted;
+    if (Object.hasOwn(r, 'omitted')) {
+        const o = r.omitted;
+        if (typeof o === 'number' && Number.isSafeInteger(o) && o > 0)
+            omitted = o;
+        else if (o !== undefined)
+            malformed = true;
+    }
+    return freezeMember({
+        ...(member !== undefined ? { member } : {}),
+        known: member !== undefined && KNOWN_MEMBERS.has(member),
+        ...(entries !== undefined ? { entries } : {}),
+        ...(omitted !== undefined ? { omitted } : {}),
+        ...(malformed ? { malformed: true } : {}),
+    });
+}
+function readNewKeyValue(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw))
+        return unreadable();
+    const length = raw.length;
+    if (typeof length !== 'number' || !Number.isSafeInteger(length) || length <= 0)
+        return unreadable();
+    const members = [];
+    for (let i = 0; i < length; i++)
+        members.push(readMemberAt(raw, i));
+    if (raw.length !== length)
+        return unreadable();
+    return Object.freeze({ source: 'allow_rule_shadowed', members: Object.freeze(members) });
+}
+function readLegacyValue(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return undefined;
+    return Object.freeze({
+        source: 'legacy_shadowed_rule',
+        members: Object.freeze([freezeMember({ member: 'persisted', known: true, entries: Object.freeze([raw]) })]),
+    });
+}
+function ownValue(v, key) {
+    return Object.hasOwn(v, key) ? v[key] : undefined;
+}
+function keyValue(v, key) {
+    return v[key];
+}
+function readMemberAt(arr, i) {
+    const d = Object.getOwnPropertyDescriptor(arr, i);
+    return d !== undefined && 'value' in d ? readMemberRecord(d.value) : freezeMember({ known: false, malformed: true });
+}
+export function readAllowRuleShadowFromWire(carrier, leg) {
+    try {
+        if (typeof carrier !== 'object' || carrier === null)
+            return undefined;
+        let host = carrier;
+        if (leg === 'row') {
+            const rd = keyValue(carrier, 'riskDescriptor');
+            host = typeof rd === 'object' && rd !== null ? rd : undefined;
+        }
+        if (host === undefined)
+            return undefined;
+        const fresh = readNewKeyValue(keyValue(host, 'allowRuleShadowed'));
+        if (fresh !== undefined)
+            return fresh;
+        return readLegacyValue(keyValue(host, leg === 'row' ? 'shadowedRule' : 'persistedRuleShadowed'));
+    }
+    catch {
+        return unreadable();
+    }
+}
+function readStampedValue(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return unreadable();
+    const source = ownValue(raw, 'source');
+    const members = ownValue(raw, 'members');
+    if ((source !== 'allow_rule_shadowed' && source !== 'legacy_shadowed_rule') || !Array.isArray(members))
+        return unreadable();
+    const length = members.length;
+    if (typeof length !== 'number' || !Number.isSafeInteger(length))
+        return unreadable();
+    const out = [];
+    for (let i = 0; i < length; i++) {
+        const r = readMemberAt(members, i);
+        const d = Object.getOwnPropertyDescriptor(members, i);
+        const was = d !== undefined && 'value' in d && typeof d.value === 'object' && d.value !== null && d.value.malformed === true;
+        out.push(was && r.malformed !== true ? freezeMember({ ...r, malformed: true }) : r);
+    }
+    if (members.length !== length)
+        return unreadable();
+    return Object.freeze({
+        source,
+        members: Object.freeze(out),
+        ...(ownValue(raw, 'unreadable') === true || out.length === 0 ? { unreadable: true } : {}),
+    });
+}
+export function readApprovalAllowRuleShadow(card) {
+    try {
+        if (typeof card !== 'object' || card === null)
+            return undefined;
+        const stamped = keyValue(card, 'allowRuleShadow');
+        if (stamped !== undefined)
+            return readStampedValue(stamped);
+        return readAllowRuleShadowFromWire(card, 'frame');
+    }
+    catch {
+        return unreadable();
+    }
+}
+export function approvalAllowRuleShadowed(card) {
+    return readApprovalAllowRuleShadow(card) !== undefined;
+}
+export function legacyShadowedRuleTextOf(r) {
+    if (r === undefined)
+        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;
+    }
+    return undefined;
+}

package/dist/hitl/askClassPair.d.ts

@@ -0,0 +1,14 @@
+export type AskClassPairReading = {
+    readonly state: 'pair';
+    readonly askClass: string;
+    readonly classes: readonly string[];
+} | {
+    readonly state: 'absent';
+} | {
+    readonly state: 'malformed';
+};
+export declare function readAskClassPairState(v: object | null | undefined): AskClassPairReading;
+export declare function readAskClassPair(v: object | null | undefined): {
+    askClass: string;
+    classes: readonly string[];
+} | undefined;

package/dist/hitl/askClassPair.js

@@ -0,0 +1,42 @@
+const ABSENT = Object.freeze({ state: 'absent' });
+const MALFORMED = Object.freeze({ state: 'malformed' });
+export function readAskClassPairState(v) {
+    if (typeof v !== 'object' || v === null)
+        return ABSENT;
+    const hasAskClass = Object.hasOwn(v, 'askClass');
+    const hasClasses = Object.hasOwn(v, 'classes');
+    if (!hasAskClass && !hasClasses)
+        return ABSENT;
+    if (!hasAskClass || !hasClasses)
+        return MALFORMED;
+    const askClass = v.askClass;
+    if (typeof askClass !== 'string' || askClass === '')
+        return MALFORMED;
+    const raw = v.classes;
+    if (!Array.isArray(raw))
+        return MALFORMED;
+    const length = raw.length;
+    if (typeof length !== 'number' || !Number.isSafeInteger(length) || length <= 0)
+        return MALFORMED;
+    const classes = [];
+    const seen = new Set();
+    for (let i = 0; i < length; i++) {
+        const d = Object.getOwnPropertyDescriptor(raw, i);
+        if (d === undefined || !('value' in d))
+            return MALFORMED;
+        const c = d.value;
+        if (typeof c !== 'string' || c === '' || seen.has(c))
+            return MALFORMED;
+        seen.add(c);
+        classes.push(c);
+    }
+    if (raw.length !== length)
+        return MALFORMED;
+    if (classes[0] !== askClass)
+        return MALFORMED;
+    return Object.freeze({ state: 'pair', askClass, classes: Object.freeze(classes) });
+}
+export function readAskClassPair(v) {
+    const r = readAskClassPairState(v);
+    return r.state === 'pair' ? { askClass: r.askClass, classes: r.classes } : undefined;
+}

package/dist/hitl/askGateWire.js

@@ -116,6 +116,7 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
             led.forgetRunScopedState();
         }
         const seq = handoff !== undefined ? undefined : led.lastSeq();
+        led.beginStreamSegment();
         stream = deps.runsEvents(taskId.current, {
             ...(seq !== undefined ? { lastEventId: seq } : {}),
             ...(opts?.signal ? { signal: opts.signal } : {}),