@sema-agent/client-core 0.97.1 → 0.99.0

package/dist/pluginHooksWire.d.ts

@@ -1,10 +1,11 @@
 import type { WireHooksConfig } from './finalVerifyWire.js';
-import type { PluginHookSource } from './host.js';
+import type { PluginHookSource, SessionHookOrigin, SessionHookSource } from './host.js';
+import { type HooksSalvageDrop, type HooksSalvageMask, type HooksSalvageRejection } from './settingsHooksSalvage.js';
 export declare const ENGINE_FIRED_HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PreCompact", "PostCompact", "Stop", "StopFailure", "UserPromptSubmit"];
 export type EngineFiredHookEvent = (typeof ENGINE_FIRED_HOOK_EVENTS)[number];
 export declare const PLUGIN_HOOK_DISPOSITIONS: readonly ["engine", "shell", "not_run"];
 export type PluginHookDisposition = (typeof PLUGIN_HOOK_DISPOSITIONS)[number];
-export declare const PLUGIN_HOOK_REASONS: readonly ["projected", "shell_event", "no_executor", "engine_not_local", "engine_locality_unknown", "engine_capability_absent", "engine_capability_unknown", "not_command", "sensitive_options", "engine_limit", "shell_form_user_config", "user_config_unset", "malformed_entry", "engine_hooks_off", "engine_hooks_unknown", "engine_type_skipped", "engine_llm_limit", "engine_unconfirmed", "engine_elsewhere"];
+export declare const PLUGIN_HOOK_REASONS: readonly ["projected", "shell_event", "no_executor", "engine_not_local", "engine_locality_unknown", "engine_capability_absent", "engine_capability_unknown", "not_command", "sensitive_options", "engine_limit", "shell_form_user_config", "user_config_unset", "malformed_entry", "engine_hooks_off", "engine_hooks_unknown", "engine_type_skipped", "engine_llm_limit", "engine_unconfirmed", "engine_elsewhere", "hooks_module", "scope_unsupported", "source_incomplete"];
 export type PluginHookReason = (typeof PLUGIN_HOOK_REASONS)[number];
 export declare const PLUGIN_HOOK_EXCLUSION_REASONS: readonly ["workspace_untrusted", "governance_unreadable", "policy_disable_all", "startup_mode", "managed_plugins_only", "prompt_not_user_authored"];
 export type PluginHookExclusionReason = (typeof PLUGIN_HOOK_EXCLUSION_REASONS)[number];
@@ -48,6 +49,28 @@ export interface SettingsHookExclusion {
     readonly hookIndex: number;
     readonly reason: PluginHookExclusionReason;
 }
+export interface SettingsHooksSalvageRow {
+    readonly source: HookSettingsSource;
+    readonly outcome: 'loaded-partial' | 'rejected';
+    readonly dropped: readonly HooksSalvageDrop[];
+    readonly rejections: readonly HooksSalvageRejection[];
+    readonly notice: string;
+}
+export interface PluginHookModuleVerdict {
+    readonly pluginId: string;
+    readonly pluginName: string;
+    readonly disposition: PluginHookDisposition;
+    readonly reason: PluginHookReason;
+}
+export interface SessionHookVerdict {
+    readonly origin: SessionHookOrigin;
+    readonly name: string;
+    readonly event: string;
+    readonly groupIndex: number;
+    readonly hookIndex: number;
+    readonly disposition: PluginHookDisposition;
+    readonly reason: PluginHookReason;
+}
 export interface HooksWireEngineFacts {
     readonly ownedByThisShell: boolean | null;
     readonly pluginHooksCapable: boolean | null;
@@ -62,6 +85,11 @@ export interface HooksWirePlan {
     readonly settingsDropped: readonly SettingsHookDrop[];
     readonly settingsVerdicts: readonly SettingsHookVerdict[];
     readonly settingsExcluded: readonly SettingsHookExclusion[];
+    readonly settingsSalvage: readonly SettingsHooksSalvageRow[];
+    readonly moduleVerdicts: readonly PluginHookModuleVerdict[];
+    readonly sessionVerdicts: readonly SessionHookVerdict[];
+    readonly sessionReader: PluginHookReaderState;
+    readonly closedBy: Extract<PluginHookExclusionReason, 'workspace_untrusted' | 'governance_unreadable' | 'policy_disable_all'> | null;
     readonly wire: WireHooksConfig | undefined;
 }
 export interface HooksWirePlanOptions {
@@ -70,7 +98,9 @@ export interface HooksWirePlanOptions {
     readonly shellHookEvents?: readonly string[];
     readonly shellHookTypesByEvent?: Readonly<Record<string, readonly string[]>>;
     readonly promptAuthoredByUser?: boolean;
+    readonly suppressedLocally?: readonly string[];
 }
+export declare function hooksWirePlanShapeOf(v: unknown): 'plan' | 'not' | 'threw';
 export declare const ENGINE_HOOK_LIMITS: {
     readonly maxGroupsPerEvent: 16;
     readonly maxEntriesPerEvent: 32;
@@ -102,15 +132,27 @@ export interface PluginHookDecisionInput {
     readonly shellRuns: ShellRunsHook;
     readonly promptAuthoredByUser: boolean;
     readonly occupied: ReadonlyMap<string, EventOccupancy>;
+    readonly suppressedLocally?: ReadonlySet<string>;
 }
 export interface PluginHookDecision {
     readonly verdicts: readonly PluginHookVerdict[];
+    readonly modules: readonly PluginHookModuleVerdict[];
     readonly excluded: readonly PluginHookExclusion[];
     readonly projected: ReadonlyMap<string, readonly WireHookGroup[]>;
     readonly unreadable: number;
 }
 export declare function decidePluginHooks(input: PluginHookDecisionInput): PluginHookDecision;
-export declare function filterSettingsHookGroups(source: HookSettingsSource, event: string, groups: readonly WireHookGroup[], execFormCapable: boolean, shellRunsType: (type: string | undefined) => boolean, failLoudMcpTool: boolean, judge?: SettingsHookJudge): SettingsHookFilterResult;
+export interface SessionHookDecisionInput {
+    readonly sources: readonly SessionHookSource[];
+    readonly engine: HooksWireEngineFacts;
+    readonly shellRuns: ShellRunsHook;
+    readonly promptAuthoredByUser: boolean;
+}
+export declare function decideSessionHooks(input: SessionHookDecisionInput): {
+    readonly verdicts: readonly SessionHookVerdict[];
+    readonly unreadable: number;
+};
+export declare function filterSettingsHookGroups(source: HookSettingsSource, event: string, groups: readonly WireHookGroup[], execFormCapable: boolean, shellRunsType: (type: string | undefined) => boolean, judge: SettingsHookJudge, mask?: HooksSalvageMask): SettingsHookFilterResult;
 export interface SettingsHookFilterResult {
     readonly groups: WireHookGroup[];
     readonly drops: SettingsHookDrop[];
@@ -140,4 +182,5 @@ export declare function pluginHookReasonText(reason: PluginHookReason): string;
 export declare function settingsHookDropText(reason: SettingsHookDropReason): string;
 export declare function pluginHookExecutorLabel(v: PluginHookVerdict): string;
 export declare function hooksNotRunNotice(plan: HooksWirePlan): readonly string[];
+export declare function userPromptSubmitExecutorOf(plan: HooksWirePlan): 'shell' | 'engine' | 'unknown' | 'none';
 export {};

package/dist/pluginHooksWire.js

@@ -1,5 +1,6 @@
 import { displayUntrusted } from './displayUntrusted.js';
 import { SETTINGS_ENGINE_OWNED_HOOK_EVENTS } from './generated/settingsSchemaTables.js';
+import { HOOK_SETTINGS_SOURCE_TEXT, hooksSalvageMaskOf, salvageSettingsHooksEntries, } from './settingsHooksSalvage.js';
 export const ENGINE_FIRED_HOOK_EVENTS = SETTINGS_ENGINE_OWNED_HOOK_EVENTS;
 export const PLUGIN_HOOK_DISPOSITIONS = ['engine', 'shell', 'not_run'];
 export const PLUGIN_HOOK_REASONS = [
@@ -22,6 +23,9 @@ export const PLUGIN_HOOK_REASONS = [
     'engine_llm_limit',
     'engine_unconfirmed',
     'engine_elsewhere',
+    'hooks_module',
+    'scope_unsupported',
+    'source_incomplete',
 ];
 export const PLUGIN_HOOK_EXCLUSION_REASONS = [
     'workspace_untrusted',
@@ -32,6 +36,43 @@ export const PLUGIN_HOOK_EXCLUSION_REASONS = [
     'prompt_not_user_authored',
 ];
 export const SETTINGS_HOOK_DROP_REASONS = ['exec_form_unsupported', 'mcp_tool_unsupported'];
+export function hooksWirePlanShapeOf(v) {
+    try {
+        if (typeof v !== 'object' || v === null || Array.isArray(v))
+            return 'not';
+        const o = v;
+        for (const k of PLAN_KEYS)
+            if (!Object.hasOwn(o, k) && !LATER_PLAN_KEYS.has(k))
+                return 'not';
+        const reader = o.pluginReader;
+        const engineFacts = o.engine;
+        const wire = o.wire;
+        const arrayOrAbsent = (k) => !Object.hasOwn(o, k) || Array.isArray(o[k]);
+        return Array.isArray(o.verdicts) &&
+            Array.isArray(o.excluded) &&
+            Array.isArray(o.settingsDropped) &&
+            arrayOrAbsent('settingsVerdicts') &&
+            arrayOrAbsent('settingsExcluded') &&
+            arrayOrAbsent('settingsSalvage') &&
+            arrayOrAbsent('moduleVerdicts') &&
+            arrayOrAbsent('sessionVerdicts') &&
+            (!Object.hasOwn(o, 'sessionReader') || o.sessionReader === 'present' || o.sessionReader === 'absent' || o.sessionReader === 'failed') &&
+            (!Object.hasOwn(o, 'closedBy') || o.closedBy === null || o.closedBy === 'workspace_untrusted' || o.closedBy === 'governance_unreadable' || o.closedBy === 'policy_disable_all') &&
+            (reader === 'present' || reader === 'absent' || reader === 'failed') &&
+            typeof engineFacts === 'object' &&
+            engineFacts !== null &&
+            (wire === undefined || (typeof wire === 'object' && wire !== null && !Array.isArray(wire)))
+            ? 'plan'
+            : 'not';
+    }
+    catch {
+        return 'threw';
+    }
+}
+const PLAN_KEYS = ['engine', 'pluginReader', 'verdicts', 'excluded', 'settingsDropped', 'settingsVerdicts', 'settingsExcluded', 'settingsSalvage', 'moduleVerdicts', 'sessionVerdicts', 'sessionReader', 'closedBy', 'wire'];
+const LATER_PLAN_KEYS = new Set(['settingsVerdicts', 'settingsExcluded', 'settingsSalvage', 'moduleVerdicts', 'sessionVerdicts', 'sessionReader', 'closedBy']);
+const _planKeysPin = [true, true];
+void _planKeysPin;
 export const ENGINE_HOOK_LIMITS = { maxGroupsPerEvent: 16, maxEntriesPerEvent: 32, maxCommandChars: 8192, maxLlmEntriesPerEvent: 4 };
 const ENGINE_HOOK_TYPE_RUNS = new Set(['command', 'http', 'prompt', 'agent']);
 const COMPACTION_EVENTS = new Set(['PreCompact', 'PostCompact']);
@@ -39,6 +80,8 @@ const judged = (disposition, reason) => ({ kind: 'judged', disposition, reason }
 function hookExecutorOf(x) {
     if (x.event === 'UserPromptSubmit' && !x.promptAuthoredByUser)
         return { kind: 'excluded', reason: 'prompt_not_user_authored' };
+    if (x.source === 'session')
+        return judged(x.shellRuns ? 'shell' : 'not_run', 'scope_unsupported');
     if (x.source === 'settings') {
         const why = x.powershell
             ? { reason: 'engine_type_skipped', certain: true }
@@ -172,15 +215,25 @@ export function occupancyOf(wire) {
 export function decidePluginHooks(input) {
     const verdicts = [];
     const excluded = [];
+    const modules = [];
     const candidates = new Map();
     let unreadable = 0;
     const fallback = (event, type, reason) => input.shellRuns(event, typeof type === 'string' ? type : undefined) ? { disposition: 'shell', reason } : { disposition: 'not_run', reason };
     input.plugins.forEach((p, pluginIndex) => {
-        if (!isRecord(p) || !isRecord(p.hooks)) {
+        if (!isRecord(p)) {
+            unreadable++;
+            return;
+        }
+        if (p.hooksModule === true && input.exclusion === undefined && !(input.managedOnly && p.managed !== true)) {
+            modules.push({ pluginId: typeof p.id === 'string' ? p.id : '', pluginName: typeof p.name === 'string' ? p.name : '', disposition: 'not_run', reason: 'hooks_module' });
+        }
+        if (!isRecord(p.hooks)) {
             unreadable++;
             return;
         }
         const src = p;
+        const sv = salvageSettingsHooksEntries({ hooks: p.hooks });
+        const pieceMask = hooksSalvageMaskOf(sv.outcome === 'loaded-partial' ? sv.dropped : []);
         const sourceOk = nonEmptyString(p.id) && nonEmptyString(p.name) && nonEmptyString(p.root) && nonEmptyString(p.dataDir);
         const pluginId = typeof p.id === 'string' ? p.id : '';
         const pluginName = typeof p.name === 'string' ? p.name : '';
@@ -207,7 +260,15 @@ export function decidePluginHooks(input) {
                         return;
                     }
                     const entryType = isRecord(entry) && typeof entry.type === 'string' ? entry.type : undefined;
-                    const shape = sourceOk ? classifyEntry(entry, src.options) : { kind: 'malformed' };
+                    if (!sourceOk) {
+                        verdicts.push({ ...key, disposition: 'not_run', reason: 'source_incomplete' });
+                        return;
+                    }
+                    if (!pieceMask.eventDropped(event) && pieceMask.entryDropped(event, groupIndex, hookIndex)) {
+                        verdicts.push({ ...key, disposition: 'not_run', reason: 'malformed_entry' });
+                        return;
+                    }
+                    const shape = classifyEntry(entry, src.options);
                     if (shape.kind === 'malformed') {
                         verdicts.push({ ...key, disposition: 'not_run', reason: 'malformed_entry' });
                         return;
@@ -299,7 +360,79 @@ export function decidePluginHooks(input) {
         }
         projected.set(event, groupsOut);
     }
-    return { verdicts, excluded, projected, unreadable };
+    const suppressed = input.suppressedLocally;
+    if (suppressed !== undefined && suppressed.size > 0) {
+        for (const v of verdicts) {
+            if (v.disposition !== 'shell' || !suppressed.has(v.pluginId))
+                continue;
+            v.disposition = 'not_run';
+            if (!ENGINE_EVENTS.has(v.event))
+                v.reason = 'no_executor';
+        }
+    }
+    return { verdicts, excluded, modules, projected, unreadable };
+}
+const SESSION_HOOK_ORIGINS = new Set(['skill', 'agent', 'sdk_host']);
+const LOCAL_REGISTRATION_TYPES = new Set(['callback', 'function']);
+const isLocalRegistration = (e) => isRecord(e) && typeof e.type === 'string' && LOCAL_REGISTRATION_TYPES.has(e.type);
+const JUDGE_STAND_IN = Object.freeze({ type: 'command', command: 'true' });
+function sessionHooksForJudge(hooks) {
+    const out = {};
+    for (const [event, groups] of Object.entries(hooks)) {
+        out[event] = Array.isArray(groups)
+            ? groups.map((g) => isRecord(g) && Array.isArray(g.hooks) && g.hooks.some(isLocalRegistration)
+                ? { ...g, hooks: g.hooks.map((e) => (isLocalRegistration(e) ? JUDGE_STAND_IN : e)) }
+                : g)
+            : groups;
+    }
+    return out;
+}
+export function decideSessionHooks(input) {
+    const out = [];
+    let unreadable = 0;
+    for (const src of input.sources) {
+        if (!isRecord(src) || typeof src.origin !== 'string' || !SESSION_HOOK_ORIGINS.has(src.origin) || !isRecord(src.hooks)) {
+            unreadable++;
+            continue;
+        }
+        const origin = src.origin;
+        const name = typeof src.name === 'string' ? src.name : '';
+        const sv = salvageSettingsHooksEntries({ hooks: sessionHooksForJudge(src.hooks) });
+        const rejectedWhole = sv.outcome === 'rejected';
+        const mask = hooksSalvageMaskOf(sv.outcome === 'loaded-partial' ? sv.dropped : []);
+        for (const [event, groups] of Object.entries(src.hooks)) {
+            if (!Array.isArray(groups)) {
+                unreadable++;
+                continue;
+            }
+            ;
+            groups.forEach((group, groupIndex) => {
+                if (!isRecord(group) || !Array.isArray(group.hooks)) {
+                    unreadable++;
+                    return;
+                }
+                ;
+                group.hooks.forEach((entry, hookIndex) => {
+                    const key = { origin, name, event, groupIndex, hookIndex };
+                    const type = isRecord(entry) && typeof entry.type === 'string' ? entry.type : undefined;
+                    if (rejectedWhole || (!mask.eventDropped(event) && mask.entryDropped(event, groupIndex, hookIndex)) || type === undefined) {
+                        out.push({ ...key, disposition: 'not_run', reason: 'malformed_entry' });
+                        return;
+                    }
+                    const shellRuns = input.shellRuns(event, type);
+                    if (!ENGINE_EVENTS.has(event)) {
+                        out.push({ ...key, ...(shellRuns ? { disposition: 'shell', reason: 'shell_event' } : { disposition: 'not_run', reason: 'no_executor' }) });
+                        return;
+                    }
+                    const ex = hookExecutorOf({ source: 'session', event, powershell: false, llmPosition: 0, engine: input.engine, shellRuns, promptAuthoredByUser: input.promptAuthoredByUser });
+                    if (ex.kind === 'excluded')
+                        return;
+                    out.push({ ...key, disposition: ex.disposition, reason: ex.reason });
+                });
+            });
+        }
+    }
+    return { verdicts: out, unreadable };
 }
 const SHELL_INERT_COMMAND = /^[A-Za-z0-9_./:+-]+$/;
 function carriesArgs(entry) {
@@ -312,15 +445,16 @@ function carriesArgs(entry) {
     }
     return true;
 }
-export function filterSettingsHookGroups(source, event, groups, execFormCapable, shellRunsType, failLoudMcpTool, judge) {
+export function filterSettingsHookGroups(source, event, groups, execFormCapable, shellRunsType, judge, mask) {
     const drops = [];
     const verdicts = [];
     const excluded = [];
     const out = [];
     let stripped = 0;
     const engineEvent = ENGINE_EVENTS.has(event);
-    const keepMcpTool = failLoudMcpTool && engineEvent;
     groups.forEach((group, groupIndex) => {
+        if (mask !== undefined && mask.groupDropped(event, groupIndex))
+            return;
         if (!isRecord(group) || !Array.isArray(group.hooks)) {
             out.push(group);
             return;
@@ -328,12 +462,14 @@ export function filterSettingsHookGroups(source, event, groups, execFormCapable,
         const kept = [];
         let changed = false;
         group.hooks.forEach((entry, hookIndex) => {
+            if (mask !== undefined && mask.entryDropped(event, groupIndex, hookIndex)) {
+                changed = true;
+                return;
+            }
             const reason = !isRecord(entry)
                 ? undefined
                 : entry.type === 'mcp_tool'
-                    ? keepMcpTool
-                        ? undefined
-                        : 'mcp_tool_unsupported'
+                    ? 'mcp_tool_unsupported'
                     : entry.type === 'command' && carriesArgs(entry) && !execFormCapable
                         ? 'exec_form_unsupported'
                         : undefined;
@@ -342,7 +478,7 @@ export function filterSettingsHookGroups(source, event, groups, execFormCapable,
                 changed = true;
                 return;
             }
-            if (judge !== undefined && engineEvent && isRecord(entry) && judgeableSettingsEntry(entry)) {
+            if (engineEvent && isRecord(entry) && judgeableSettingsEntry(entry)) {
                 const ex = judge(event, group, entry);
                 if (ex.kind === 'excluded') {
                     excluded.push({ source, event, groupIndex, hookIndex, reason: ex.reason });
@@ -668,18 +804,15 @@ const REASON_TEXT = {
     engine_llm_limit: 'the engine may skip prompt or agent hooks after the first four on one event',
     engine_unconfirmed: 'it is sent to the engine, which is expected to run it, but this client cannot confirm that',
     engine_elsewhere: 'it is not confirmed that the engine was started by this client on this machine, so this client runs it itself',
+    hooks_module: 'hooks registered in code by a plugin module run neither in the engine nor in this client',
+    scope_unsupported: 'hooks registered for a skill, an agent or by the host application are not sent to the engine, and this client does not run this event',
+    source_incomplete: 'the plugin was reported without its id, name, root folder or data folder',
 };
 const DROP_TEXT = {
     exec_form_unsupported: 'exec-form hooks (with "args") are sent to the engine only once it reports support for them',
     mcp_tool_unsupported: 'MCP tool hooks are not supported by the engine',
 };
-const SOURCE_TEXT = {
-    policySettings: 'Managed settings',
-    userSettings: 'User settings',
-    projectSettings: 'Project settings',
-    localSettings: 'Local settings',
-    flagSettings: 'Flag settings',
-};
+const SOURCE_TEXT = HOOK_SETTINGS_SOURCE_TEXT;
 export function pluginHookReasonText(reason) {
     return REASON_TEXT[reason];
 }
@@ -789,5 +922,75 @@ export function hooksNotRunNotice(plan) {
         const events = row.events.map((e) => noticeLabel(e)).join(', ');
         lines.push(`${SOURCE_TEXT[row.source]}: ${events} ${row.count === 1 ? 'hook' : 'hooks'} will not run — ${pluginHookReasonText(row.reason)}.`);
     }
+    const moduleRows = plan.moduleVerdicts;
+    for (const raw of Array.isArray(moduleRows) ? moduleRows : []) {
+        if (!isRecord(raw) || ownField(raw, 'disposition') !== 'not_run')
+            continue;
+        const reason = ownField(raw, 'reason');
+        const name = ownField(raw, 'pluginName');
+        if (typeof reason !== 'string' || !REASON_SET.has(reason))
+            continue;
+        lines.push(`Plugin "${noticeLabel(typeof name === 'string' ? name : '') || '(unnamed)'}": hooks module will not run — ${pluginHookReasonText(reason)}.`);
+    }
+    const sessionRows = plan.sessionVerdicts;
+    const bySession = new Map();
+    for (const raw of Array.isArray(sessionRows) ? sessionRows : []) {
+        if (!isRecord(raw) || ownField(raw, 'disposition') !== 'not_run')
+            continue;
+        const origin = ownField(raw, 'origin');
+        const name = ownField(raw, 'name');
+        const reason = ownField(raw, 'reason');
+        const event = ownField(raw, 'event');
+        if (typeof origin !== 'string' || !SESSION_HOOK_ORIGINS.has(origin) || typeof reason !== 'string' || !REASON_SET.has(reason) || typeof event !== 'string')
+            continue;
+        const nm = typeof name === 'string' ? name : '';
+        const k = `${origin}\u0000${nm}\u0000${reason}`;
+        const row = bySession.get(k) ?? { origin: origin, name: nm, reason: reason, events: [], count: 0 };
+        if (!row.events.includes(event))
+            row.events.push(event);
+        row.count++;
+        bySession.set(k, row);
+    }
+    for (const row of bySession.values()) {
+        const events = row.events.map((e) => noticeLabel(e)).join(', ');
+        const who = row.origin === 'sdk_host' ? 'Host application hooks' : `${row.origin === 'skill' ? 'Skill' : 'Agent'} "${noticeLabel(row.name) || '(unnamed)'}"`;
+        lines.push(`${who}: ${events} ${row.count === 1 ? 'hook' : 'hooks'} will not run — ${pluginHookReasonText(row.reason)}.`);
+    }
+    const salvageRows = plan.settingsSalvage;
+    for (const row of Array.isArray(salvageRows) ? salvageRows : []) {
+        const notice = isRecord(row) ? ownField(row, 'notice') : undefined;
+        if (typeof notice === 'string' && notice.length > 0)
+            lines.push(notice);
+    }
     return lines;
 }
+export function userPromptSubmitExecutorOf(plan) {
+    try {
+        const p = plan;
+        if (!isRecord(p))
+            return 'unknown';
+        const verdicts = ownField(p, 'verdicts');
+        if (!Array.isArray(verdicts))
+            return 'unknown';
+        const rows = [...verdicts];
+        for (const k of ['settingsVerdicts', 'sessionVerdicts']) {
+            const v = ownField(p, k);
+            if (v === undefined)
+                continue;
+            if (!Array.isArray(v))
+                return 'unknown';
+            rows.push(...v);
+        }
+        const ups = rows.filter((r) => isRecord(r) && ownField(r, 'event') === 'UserPromptSubmit').map((r) => ownField(r, 'disposition'));
+        if (ups.length === 0)
+            return 'none';
+        if (ups.some((d) => d === 'engine'))
+            return 'engine';
+        if (ups.every((d) => d === 'shell'))
+            return 'shell';
+        return 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/preemptWire.d.ts

@@ -0,0 +1,44 @@
+import type { AssistantTaskStatus, CancelAck } from '@sema-agent/sdk';
+import { type SdkRunTerminalStatus } from './terminalStatuses.js';
+export type PreemptParkedStatus = 'suspended' | 'needs_review';
+export type PreemptOutcome = {
+    readonly kind: 'yield-requested';
+    readonly taskId: string;
+} | {
+    readonly kind: 'not-eligible';
+    readonly taskId: string;
+} | {
+    readonly kind: 'already-ended';
+    readonly taskId: string;
+    readonly status: SdkRunTerminalStatus;
+} | {
+    readonly kind: 'already-parked';
+    readonly status?: PreemptParkedStatus;
+} | {
+    readonly kind: 'approval-settled';
+} | {
+    readonly kind: 'not-found';
+} | {
+    readonly kind: 'unconfirmed';
+    readonly why: 'transport' | 'server-error' | 'unreadable-answer';
+    readonly status?: number;
+} | {
+    readonly kind: 'refused';
+    readonly status: number;
+    readonly errorCode?: string;
+} | {
+    readonly kind: 'no-run';
+} | {
+    readonly kind: 'cancelled-instead';
+    readonly ack: CancelAck;
+} | {
+    readonly kind: 'unavailable';
+};
+export type PreemptReading = Exclude<PreemptOutcome, {
+    readonly kind: 'no-run' | 'cancelled-instead' | 'unavailable';
+}> | {
+    readonly kind: 'lane-absent';
+};
+export declare function preemptReadingOfAck(taskId: string, ack: AssistantTaskStatus): PreemptReading;
+export declare function preemptReadingOfError(e: {} | null | undefined): PreemptReading;
+export declare function preemptReceiptLine(outcome: PreemptOutcome): string;

package/dist/preemptWire.js

@@ -0,0 +1,83 @@
+import { isAssistantLaneAbsent } from './assistantInbox.js';
+import { atMostOnceVerdictOf } from './atMostOnce.js';
+import { readOwnDataValue } from './ownKey.js';
+import { isSdkRunTerminal } from './terminalStatuses.js';
+import { isDisplayableWireCode, readErrorString } from './wireFailureShape.js';
+const ALREADY_SUSPENDED = 'conflict.already_suspended';
+const APPROVAL_SETTLED = 'conflict.approval_settled';
+function own(v, key) {
+    try {
+        return readOwnDataValue(v, key);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function preemptReadingOfAck(taskId, ack) {
+    const body = ack;
+    const unreadable = { kind: 'unconfirmed', why: 'unreadable-answer' };
+    if (body === null || typeof body !== 'object')
+        return unreadable;
+    const echoed = own(body, 'taskId');
+    const status = own(body, 'status');
+    if (echoed !== taskId || typeof status !== 'string' || status === '')
+        return unreadable;
+    if (status === 'preempting')
+        return { kind: 'yield-requested', taskId };
+    if (status === 'running')
+        return { kind: 'not-eligible', taskId };
+    if (status === 'suspended' || status === 'needs_review')
+        return { kind: 'already-parked', status };
+    if (isSdkRunTerminal(status))
+        return { kind: 'already-ended', taskId, status };
+    return unreadable;
+}
+export function preemptReadingOfError(e) {
+    if (isAssistantLaneAbsent(e))
+        return { kind: 'lane-absent' };
+    const v = atMostOnceVerdictOf(e);
+    if (v.delivery === 'rejected' && v.status !== undefined) {
+        if (v.status === 409 && v.code === ALREADY_SUSPENDED) {
+            const word = e === null || e === undefined ? undefined : readErrorString(e, 'status');
+            return { kind: 'already-parked', ...(word === 'suspended' || word === 'needs_review' ? { status: word } : {}) };
+        }
+        if (v.status === 409 && v.code === APPROVAL_SETTLED)
+            return { kind: 'approval-settled' };
+        if (v.status === 404)
+            return { kind: 'not-found' };
+        return { kind: 'refused', status: v.status, ...(v.code !== undefined ? { errorCode: v.code } : {}) };
+    }
+    if (v.status !== undefined)
+        return { kind: 'unconfirmed', why: 'server-error', status: v.status };
+    return { kind: 'unconfirmed', why: 'transport' };
+}
+export function preemptReceiptLine(outcome) {
+    switch (outcome.kind) {
+        case 'yield-requested':
+            return 'Asked the run to yield — it will pause at its next clean turn boundary and can be resumed later.';
+        case 'not-eligible':
+            return 'This run cannot be asked to yield (it is a verification or cascade leg), so nothing changed and it keeps running — stop it instead if it has to end.';
+        case 'already-ended':
+            return isSdkRunTerminal(outcome.status)
+                ? `The run had already ended (${outcome.status}), so there was nothing to yield.`
+                : 'The run had already ended, so there was nothing to yield.';
+        case 'already-parked':
+            return 'The run is already paused waiting on a decision, so there is nothing to yield — answer what it is waiting on, or stop it.';
+        case 'approval-settled':
+            return 'The approval this run was waiting on was decided at the same moment, so the yield request did not apply — check the run and ask again if it is still active.';
+        case 'not-found':
+            return 'No such run is visible to you, so nothing was asked.';
+        case 'unconfirmed':
+            return 'The yield request was sent but no confirmation came back — it may or may not have been applied, so check the run before asking again.';
+        case 'refused':
+            return outcome.errorCode !== undefined && isDisplayableWireCode(outcome.errorCode)
+                ? `The engine refused the yield request (${outcome.status} ${outcome.errorCode}).`
+                : `The engine refused the yield request (${outcome.status}).`;
+        case 'no-run':
+            return 'There is no run in flight to yield.';
+        case 'cancelled-instead':
+            return 'Yielding is not available on this engine, so the run was stopped instead — that is a hard stop and the run cannot be resumed.';
+        case 'unavailable':
+            return 'Yielding is not available on this engine, so nothing was sent.';
+    }
+}

package/dist/printModelStatus.d.ts

@@ -0,0 +1,63 @@
+import type { SDKAssistantMessageError } from '@sema-agent/agent-types';
+import { type RetryStatus, type RetryStatusArmLike, type RetryStatusNotice } from './retryStatus.js';
+export declare const PRINT_MODEL_STATUS_SUBTYPE = "_sema_model_status";
+export declare const PRINT_LAST_MODEL_STATUS_KEY = "_sema_last_model_status";
+export interface PrintModelStatusCtx {
+    readonly sessionId: string;
+    readonly nowMs: number;
+    readonly mintUuid: () => string;
+    readonly model?: string;
+}
+export interface PrintModelStatusPayload {
+    readonly kind: RetryStatus['kind'];
+    readonly terminal?: true;
+    readonly attempt?: number;
+    readonly max_retries?: number;
+    readonly retry_delay_ms?: number;
+    readonly error_status?: number;
+    readonly provider_condition?: string;
+    readonly err_class?: string;
+    readonly elapsed_ms?: number;
+    readonly timeout_ms?: number;
+    readonly model?: string;
+    readonly phase: RetryStatusNotice['phase'];
+    readonly recourse?: NonNullable<RetryStatusNotice['recourse']>;
+    readonly message: string;
+}
+export interface PrintApiRetryFrame {
+    readonly type: 'system';
+    readonly subtype: 'api_retry';
+    readonly attempt: number;
+    readonly max_retries: number;
+    readonly retry_delay_ms: number;
+    readonly error_status: number | null;
+    readonly error: SDKAssistantMessageError;
+    readonly _sema_provider_condition?: string;
+    readonly _sema_model?: string;
+    readonly _sema_message: string;
+    readonly uuid: string;
+    readonly session_id: string;
+}
+export interface PrintModelStatusSupersetFrame {
+    readonly type: 'system';
+    readonly subtype: typeof PRINT_MODEL_STATUS_SUBTYPE;
+    readonly _sema_model_status: PrintModelStatusPayload & {
+        readonly refresh?: true;
+    };
+    readonly uuid: string;
+    readonly session_id: string;
+}
+export type PrintModelStatusFrame = PrintApiRetryFrame | PrintModelStatusSupersetFrame;
+export interface PrintModelStatusResultFields {
+    readonly _sema_last_model_status?: PrintModelStatusPayload;
+}
+export interface PrintLaneArmLike extends RetryStatusArmLike {
+    readonly type?: string;
+    readonly event?: RetryStatusArmLike;
+}
+export interface PrintModelStatusTracker {
+    take(msg: PrintLaneArmLike | null | undefined, ctx: PrintModelStatusCtx): PrintModelStatusFrame | null;
+    beginTurn(): void;
+    resultFields(nowMs: number): PrintModelStatusResultFields;
+}
+export declare function createPrintModelStatusTracker(): PrintModelStatusTracker;