@naswerks/periscope 1.0.0

package/dist/state/model.js

@@ -0,0 +1,214 @@
+import { isRefusalReason } from '../core/refusal.js';
+// ---------------------------------------------------------------------------
+// state — the coarse lifecycle
+// ---------------------------------------------------------------------------
+export const SESSION_STATES = [
+    /** The process is up; the agent has not reported itself. It has no id yet. */
+    'spawning',
+    /**
+     * The agent reported itself: id, model, tool inventory, version receipt all known.
+     *
+     * It arrives mid-turn, and the trace goes `working -> ready -> working`. That reads like a
+     * step backwards and it is not: it is literally what happens. Observed on a real session:
+     *
+     *     1 spawning -> spawning   control/create_requested
+     *     2 spawning -> spawning   control/prompt_submitted
+     *     3 spawning -> working    hook/UserPromptSubmit
+     *     4 working  -> ready      sdk-message/system/init      <- here
+     *     5 ready    -> working    hook/PreToolUse
+     *
+     * The agent emits nothing at all until a turn is queued, and `UserPromptSubmit` fires ahead of
+     * `init`, so the session is genuinely already working when it says what it is. Ordering this
+     * state earlier would mean recording it before the event that causes it.
+     *
+     * It is kept rather than collapsed for two reasons. It is the only row where the session's
+     * identity becomes known — collapse it and "what is this session" needs the transcript. And a
+     * session created but never prompted never reaches it: it sits in `spawning` until the start
+     * timeout, so the state being missing is what makes that failure legible instead of a hang.
+     */
+    'ready',
+    /** A turn is in flight. `activity` says what it is blocked on. */
+    'working',
+    /** A turn ended cleanly and the session is waiting for input. */
+    'idle',
+    /** A turn ended abnormally. The cause names which way. */
+    'errored',
+    /** An interrupt landed mid-turn. Distinct from `idle`: nobody chose to stop here. */
+    'interrupted',
+    /** Over. The cause says why, and it is never inferred from silence. */
+    'ended',
+];
+// ---------------------------------------------------------------------------
+// activity — what a working session is blocked on in the foreground
+// ---------------------------------------------------------------------------
+/**
+ * Where each activity kind's name comes from. Two are the SDK's own words; four extend it.
+ *
+ * `requesting` and `compacting` are `SDKStatus` verbatim — two values and a null. The SDK has no
+ * word for the other four situations, so this package names them, and this table is where that is
+ * recorded rather than left for a reader to guess.
+ */
+export const ACTIVITY_KINDS = [
+    /** SDK: `SDKStatus`. A model request is in flight. */
+    'requesting',
+    /** SDK: `SDKStatus`. Context compaction is running. */
+    'compacting',
+    /** This package's own. A tool call is in flight — `name` is the SDK's `tool_name`. */
+    'tool',
+    /** This package's own. A subagent is running — `name` is the SDK's `agent_type`. */
+    'subagent',
+    /** This package's own. A permission decision is outstanding — `name` is the tool it is about. */
+    'permission',
+    /** This package's own. An MCP server is asking for input — `name` is `mcp_server_name`. */
+    'elicitation',
+];
+/** Which activity kinds this package named itself, kept visible the way HOST_NOUNS is. */
+export const HOST_ACTIVITY_KINDS = ['tool', 'subagent', 'permission', 'elicitation'];
+/** SDK: `SDKStatus`'s two non-null values, adopted verbatim. */
+export const SDK_ACTIVITY_KINDS = ['requesting', 'compacting'];
+/** The display form — `tool:Bash`, `requesting`. For logs and humans; never parsed back. */
+export function formatActivity(activity) {
+    if (activity === null)
+        return 'none';
+    return activity.name === null ? activity.kind : `${activity.kind}:${activity.name}`;
+}
+export function sameActivity(left, right) {
+    if (left === null || right === null)
+        return left === right;
+    return left.kind === right.kind && left.name === right.name;
+}
+// ---------------------------------------------------------------------------
+// cause — required, and closed at compile time
+// ---------------------------------------------------------------------------
+/**
+ * Where a transition came from. A transition that cannot name its cause is not recorded.
+ *
+ * `refusal` is the sixth and it is load-bearing: a permission denial is a hook event, but a
+ * permission-path outage has no hook at all, and with five kinds the difference would have to ride
+ * `detail` — free text a reader greps instead of a fact code branches on. Conflating an outage with
+ * a deliberate "no" is the most expensive confusion a controller can make, so the two differ in
+ * `kind` and in `event`, twice over, neither of them prose.
+ */
+export const CAUSE_KINDS = ['hook', 'sdk-message', 'control', 'timeout', 'process', 'refusal'];
+/**
+ * The SDK's hook events, mirrored as values so they can be validated at runtime.
+ *
+ * Kept in step by two checks, because a list copied out of a type rots silently: `coverage.ts`
+ * declares its table `satisfies Record<HookEvent, …>` so a new SDK event breaks the build, and
+ * `pins/hook-coverage.test.ts` parses the union straight out of the shipped `sdk.d.ts` and fails
+ * when this list disagrees with it.
+ */
+export const HOOK_EVENTS = [
+    'PreToolUse',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'PostToolBatch',
+    'Notification',
+    'UserPromptSubmit',
+    'UserPromptExpansion',
+    'SessionStart',
+    'SessionEnd',
+    'Stop',
+    'StopFailure',
+    'SubagentStart',
+    'SubagentStop',
+    'PreCompact',
+    'PostCompact',
+    'PermissionRequest',
+    'PermissionDenied',
+    'Setup',
+    'TeammateIdle',
+    'TaskCreated',
+    'TaskCompleted',
+    'Elicitation',
+    'ElicitationResult',
+    'ConfigChange',
+    'WorktreeCreate',
+    'WorktreeRemove',
+    'InstructionsLoaded',
+    'CwdChanged',
+    'FileChanged',
+    'DirectoryAdded',
+    'MessageDisplay',
+];
+/**
+ * The SDK message discriminators this model names as causes — `type` for the plain kinds,
+ * `type/subtype` for the `system` family. Only the ones that can move a session appear here;
+ * `coverage.ts` accounts for all 39 members of the union, wired or declined.
+ */
+export const MESSAGE_EVENTS = [
+    'system/init',
+    'system/status',
+    'system/session_state_changed',
+    'system/compact_boundary',
+    'system/task_started',
+    'system/task_updated',
+    'system/task_notification',
+    'system/permission_denied',
+    'system/elicitation_complete',
+    'system/worker_shutting_down',
+    'assistant',
+    'result',
+];
+/**
+ * Calls the host makes on itself or is asked to make. Not SDK events — decisions.
+ *
+ * `kind` and `event` are validated independently and never as a pair. `machine.ts`'s `nameable()`
+ * checks that the kind is a declared kind and that the event is a declared event, in two separate
+ * guards — so `{kind:'hook', event:'permission_denied'}` passes while being incoherent. Pairing a
+ * cause with the right kind is the author's job, not the machine's.
+ *
+ * `permission_denied` sits here rather than in HOOK_EVENTS because a gate's deny is a call the host
+ * makes on itself: it is decided by this package, not reported to it. The SDK's `PermissionDenied`
+ * hook is a different thing that belongs to the SDK's own prompt path and does not fire for a
+ * hook-authored deny — measured — so naming it here would put an event in the trace that never
+ * happened, and would make a reader grepping traces conclude the hook fires.
+ */
+export const CONTROL_EVENTS = [
+    'create_requested',
+    'prompt_submitted',
+    'interrupt_requested',
+    'stop_requested',
+    'permission_denied',
+];
+/**
+ * The agent process's own lifecycle, as causes.
+ *
+ * These subsume `SESSION_END_CAUSES` deliberately. `sessions/session.ts` states four end causes
+ * local to the handle, and its own comment says the layer owning the declared state model maps them
+ * onto its causes. This is that layer, and this is that mapping — one cause vocabulary, not two.
+ * `state/reconciliation.test.ts` asserts the containment so it cannot drift.
+ */
+export const PROCESS_EVENTS = [
+    'process_started',
+    'stop_requested',
+    'process_ended',
+    'process_failed',
+    'start_timed_out',
+];
+export const TIMEOUT_EVENTS = ['start_timed_out', 'hook_timed_out'];
+/**
+ * The gate's expiry, named once.
+ *
+ * One concept with two spellings — `hook_timed_out` on the transition, and `hook-timed-out` as
+ * the prefix of the deny reason handed to the model — looks exactly like a declared refusal reason
+ * (its sibling branch really is one) while resolving to nothing, so a reader who looks it up finds
+ * no such name. `satisfies` ties it to the closed vocabulary above, so the two cannot drift apart
+ * without breaking the build.
+ */
+export const HOOK_TIMEOUT_EVENT = 'hook_timed_out';
+const CAUSE_EVENT_SET = new Set([
+    ...HOOK_EVENTS,
+    ...MESSAGE_EVENTS,
+    ...CONTROL_EVENTS,
+    ...PROCESS_EVENTS,
+    ...TIMEOUT_EVENTS,
+]);
+/** The runtime half. A frame decoded from the wire was never seen by the compiler. */
+export function isCauseEvent(value) {
+    return CAUSE_EVENT_SET.has(value) || isRefusalReason(value);
+}
+export function isCauseKind(value) {
+    return CAUSE_KINDS.includes(value);
+}
+//# sourceMappingURL=model.js.map

package/dist/state/observer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The one translation site: the SDK's events become this package's transitions here and nowhere
+ * else.
+ *
+ * What is consumed and what is not is decided by `coverage.ts`, not by this file. Every hook
+ * event and every message shape has a row there saying wired or declined, with a reason. This file
+ * implements the wired half; reading it alone will not tell you what was skipped, which is exactly
+ * why the table exists separately.
+ *
+ * It translates; it does not interpret. Nothing here knows what a session is for. It knows a
+ * tool call started and stopped, that a turn ended cleanly or badly, and that a task stopped
+ * holding the session. What any of that means is a controller's question.
+ *
+ * It never throws and never decides a permission. Every handler returns an empty hook output —
+ * the decision path is a separate handler on the same event, and the SDK runs both.
+ */
+import type { HookInput, SDKMessage } from '../host/agent-process.js';
+import type { Result } from '../core/result.js';
+import type { SessionTransition, TransitionCause, TransitionWhere } from './model.js';
+import type { EntryOp, SessionStateMachine } from './machine.js';
+/**
+ * Translates one session's SDK events into transitions on its machine.
+ *
+ * Per session because it holds the one correlation the SDK does not give for free: a background
+ * task is reported by `task_id`, while the entry it belongs to was opened under the tool's
+ * `tool_use_id`, and only `task_started` carries both.
+ */
+export declare class SessionObserver {
+    #private;
+    constructor(machine: SessionStateMachine);
+    get machine(): SessionStateMachine;
+    /** The first record of a session's life: someone asked for a process. */
+    created(detail: string): Result<SessionTransition>;
+    /** A turn was queued. Distinct from `UserPromptSubmit`, which is the agent confirming it. */
+    promptSubmitted(detail: string): Result<SessionTransition>;
+    interrupted(detail: string): Result<SessionTransition>;
+    /**
+     * The process is over, however it ended.
+     *
+     * Every still-open entry is marked abandoned here, not deleted. A session that died holding a
+     * tool call is the most useful thing this model can report, and erasing the entry to tidy up
+     * would destroy precisely that. The mark carries the reason and the entry keeps its age.
+     */
+    ended(cause: TransitionCause): Result<SessionTransition>;
+    /** A named condition the host itself produced — a decision path that failed rather than denied. */
+    refused(cause: TransitionCause): Result<SessionTransition>;
+    /** The working directory moved under the session, so every later transition must carry the new one. */
+    relocated(where: TransitionWhere, cause: TransitionCause): Result<SessionTransition>;
+    /** Every message the agent emits. Returns what it recorded — often nothing, by the table. */
+    observeMessage(message: SDKMessage): Result<SessionTransition>[];
+    /** One hook firing. Returns what it recorded, so a caller can assert on it. */
+    observeHook(input: HookInput): Result<SessionTransition>[];
+}
+export type { EntryOp };
+//# sourceMappingURL=observer.d.ts.map

package/dist/state/observer.js

@@ -0,0 +1,413 @@
+import { discriminatorOf } from '../host/agent-process.js';
+/**
+ * How this observer keys a permission entry. `PermissionRequest` carries no tool_use_id — see below.
+ *
+ * The name key belongs to this file's own lane — `PermissionRequest` opens it,
+ * `PermissionDenied` or the `PreToolUse` close below exits it — and to nobody else. The gate keys
+ * its hold entry by tool_use_id (`gate/outcome.ts`) precisely so the close below can never touch a
+ * hold whose decision is still outstanding: a second `PreToolUse` for the same tool would
+ * otherwise close the first call's live hold and record a resolution that never happened.
+ */
+const permissionEntry = (toolName) => `permission:${toolName}`;
+/** One compaction at a time per session, from either of the two sources that report it. */
+const COMPACTION_ENTRY = 'compaction';
+/** The model-request lane, driven by SDKStatus. */
+const REQUEST_ENTRY = 'request';
+/**
+ * Translates one session's SDK events into transitions on its machine.
+ *
+ * Per session because it holds the one correlation the SDK does not give for free: a background
+ * task is reported by `task_id`, while the entry it belongs to was opened under the tool's
+ * `tool_use_id`, and only `task_started` carries both.
+ */
+export class SessionObserver {
+    #machine;
+    /** task_id -> the entryId that task's work is recorded under. */
+    #taskEntries = new Map();
+    constructor(machine) {
+        this.#machine = machine;
+    }
+    get machine() {
+        return this.#machine;
+    }
+    /** The first record of a session's life: someone asked for a process. */
+    created(detail) {
+        return this.#machine.record({
+            to: 'spawning',
+            cause: { kind: 'control', event: 'create_requested', detail },
+        });
+    }
+    /** A turn was queued. Distinct from `UserPromptSubmit`, which is the agent confirming it. */
+    promptSubmitted(detail) {
+        return this.#machine.record({
+            to: this.#machine.state === 'spawning' ? 'spawning' : 'working',
+            cause: { kind: 'control', event: 'prompt_submitted', detail },
+        });
+    }
+    interrupted(detail) {
+        return this.#machine.record({
+            to: 'interrupted',
+            cause: { kind: 'control', event: 'interrupt_requested', detail },
+        });
+    }
+    /**
+     * The process is over, however it ended.
+     *
+     * Every still-open entry is marked abandoned here, not deleted. A session that died holding a
+     * tool call is the most useful thing this model can report, and erasing the entry to tidy up
+     * would destroy precisely that. The mark carries the reason and the entry keeps its age.
+     */
+    ended(cause) {
+        return this.#machine.record({
+            to: 'ended',
+            cause,
+            entry: { op: 'abandon-open', reason: `the session ended (${cause.event}) with this entry still open` },
+        });
+    }
+    /** A named condition the host itself produced — a decision path that failed rather than denied. */
+    refused(cause) {
+        return this.#machine.record({ to: this.#machine.state, cause });
+    }
+    /** The working directory moved under the session, so every later transition must carry the new one. */
+    relocated(where, cause) {
+        return this.#machine.record({ to: this.#machine.state, cause, where });
+    }
+    // -------------------------------------------------------------------------
+    // The SDK message stream
+    // -------------------------------------------------------------------------
+    /** Every message the agent emits. Returns what it recorded — often nothing, by the table. */
+    observeMessage(message) {
+        return this.#requestsFor(message).map((request) => this.#machine.record(request));
+    }
+    #requestsFor(message) {
+        const event = discriminatorOf(message);
+        const cause = (detail) => ({
+            kind: 'sdk-message',
+            event: event,
+            detail,
+        });
+        if (message.type === 'system' && message.subtype === 'init') {
+            return [
+                {
+                    to: 'ready',
+                    sessionId: message.session_id,
+                    cause: cause(`the agent reported itself: ${message.model} on CLI ${message.claude_code_version}`),
+                },
+            ];
+        }
+        if (message.type === 'system' && message.subtype === 'status') {
+            return statusRequests(message.status, cause);
+        }
+        if (message.type === 'system' && message.subtype === 'session_state_changed') {
+            // `requires_action` maps to `working`, not to a state of its own: what it requires is
+            // already carried by the open permission or elicitation entry, and a second representation
+            // of one fact is how two vocabularies start.
+            const to = message.state === 'idle' ? 'idle' : 'working';
+            return [{ to, cause: cause(`the agent reported session state ${message.state}`) }];
+        }
+        if (message.type === 'system' && message.subtype === 'compact_boundary') {
+            return [
+                {
+                    to: this.#machine.state,
+                    entry: { op: 'close', entryId: COMPACTION_ENTRY },
+                    cause: cause(`compaction completed (${message.compact_metadata.trigger})`),
+                },
+            ];
+        }
+        if (message.type === 'system' && message.subtype === 'task_started') {
+            // No transition of its own — this is where the join is learned. The entry itself was opened
+            // by PreToolUse under the tool_use_id, which is the id every later report has to resolve to.
+            const entryId = message.tool_use_id ?? `task:${message.task_id}`;
+            this.#taskEntries.set(message.task_id, entryId);
+            return [];
+        }
+        if (message.type === 'system' && message.subtype === 'task_updated') {
+            return this.#taskUpdateRequests(message.task_id, message.patch, cause);
+        }
+        if (message.type === 'system' && message.subtype === 'task_notification') {
+            const entryId = message.tool_use_id ?? this.#taskEntries.get(message.task_id);
+            if (entryId === undefined)
+                return [];
+            this.#taskEntries.delete(message.task_id);
+            return [
+                {
+                    to: this.#machine.state,
+                    entry: { op: 'close', entryId },
+                    cause: cause(`background task ${message.task_id} ${message.status}`),
+                },
+            ];
+        }
+        if (message.type === 'system' && message.subtype === 'worker_shutting_down') {
+            return [{ to: this.#machine.state, cause: cause(`the worker is shutting down: ${message.reason}`) }];
+        }
+        if (message.type === 'system' && message.subtype === 'model_refusal_no_fallback') {
+            return [
+                {
+                    to: this.#machine.state,
+                    cause: cause(`the model refused and no fallback ran (${message.original_model})`),
+                },
+            ];
+        }
+        if (message.type === 'result') {
+            const clean = message.subtype === 'success';
+            const why = clean
+                ? `the turn completed in ${message.duration_ms}ms`
+                : `the turn ended ${message.subtype}${'terminal_reason' in message && message.terminal_reason !== undefined ? ` (${message.terminal_reason})` : ''}`;
+            return [{ to: clean ? 'idle' : 'errored', cause: cause(why) }];
+        }
+        return [];
+    }
+    #taskUpdateRequests(taskId, patch, cause) {
+        const entryId = this.#taskEntries.get(taskId);
+        if (entryId === undefined)
+            return [];
+        // The caused moment. A task stops holding the session exactly here, because the agent said
+        // so — never on a timer, never because an entry looked old. Backgrounding is not completion:
+        // the entry stays open, keeps ageing, and still gets its exit from task_notification.
+        if (patch.is_backgrounded === true) {
+            return [
+                {
+                    to: 'idle',
+                    entry: { op: 'background', entryId },
+                    cause: cause(`task ${taskId} was backgrounded and no longer holds the session`),
+                },
+            ];
+        }
+        if (patch.status === 'completed' || patch.status === 'failed' || patch.status === 'killed') {
+            this.#taskEntries.delete(taskId);
+            return [
+                {
+                    to: this.#machine.state,
+                    entry: { op: 'close', entryId },
+                    cause: cause(`task ${taskId} ${patch.status}`),
+                },
+            ];
+        }
+        return [];
+    }
+    // -------------------------------------------------------------------------
+    // The hook lane
+    // -------------------------------------------------------------------------
+    /** One hook firing. Returns what it recorded, so a caller can assert on it. */
+    observeHook(input) {
+        return this.#hookRequests(input).map((request) => this.#machine.record(request));
+    }
+    #hookRequests(input) {
+        const cause = (detail) => ({
+            kind: 'hook',
+            event: input.hook_event_name,
+            detail,
+        });
+        switch (input.hook_event_name) {
+            case 'PreToolUse': {
+                // Two records, in order: the tool running means any outstanding permission for it
+                // resolved, and that resolution is the permission entry's exit on the allow path.
+                const requests = [];
+                const held = permissionEntry(input.tool_name);
+                if (this.#isOpen(held)) {
+                    requests.push({
+                        to: 'working',
+                        entry: { op: 'close', entryId: held },
+                        cause: cause(`the permission for ${input.tool_name} resolved and the tool is running`),
+                    });
+                }
+                requests.push({
+                    to: 'working',
+                    entry: {
+                        op: 'open',
+                        entryId: input.tool_use_id,
+                        activity: { kind: 'tool', name: input.tool_name },
+                        agentId: input.agent_id ?? null,
+                    },
+                    cause: cause(`${input.tool_name} started`),
+                });
+                return requests;
+            }
+            case 'PostToolUse':
+                return [
+                    {
+                        to: 'working',
+                        entry: { op: 'close', entryId: input.tool_use_id },
+                        cause: cause(`${input.tool_name} finished`),
+                    },
+                ];
+            case 'PostToolUseFailure':
+                return [
+                    {
+                        to: 'working',
+                        entry: { op: 'close', entryId: input.tool_use_id },
+                        cause: cause(`${input.tool_name} failed: ${input.error}`),
+                    },
+                ];
+            case 'PostToolBatch':
+                // The backstop. Closes only what is still open — emitting a close for an entry that
+                // already exited would put an event in the trace that never happened.
+                return input.tool_calls
+                    .filter((call) => this.#isOpen(call.tool_use_id))
+                    .map((call) => ({
+                    to: 'working',
+                    entry: { op: 'close', entryId: call.tool_use_id },
+                    cause: cause(`${call.tool_name} closed by the end of its batch`),
+                }));
+            case 'UserPromptSubmit':
+                return [{ to: 'working', cause: cause('a turn was submitted') }];
+            case 'Stop':
+                return [
+                    {
+                        to: 'idle',
+                        cause: cause(`the turn ended cleanly${input.background_tasks !== undefined && input.background_tasks.length > 0
+                            ? ` with ${input.background_tasks.length} background task(s) still in flight`
+                            : ''}`),
+                    },
+                ];
+            case 'StopFailure':
+                return [{ to: 'errored', cause: cause(`the turn ended abnormally: ${input.error}`) }];
+            case 'SessionStart':
+                return [{ to: this.#machine.state, cause: cause(`the session started (${input.source})`) }];
+            case 'SessionEnd':
+                return [
+                    {
+                        to: 'ended',
+                        entry: {
+                            op: 'abandon-open',
+                            reason: `the session ended (${input.reason}) with this entry still open`,
+                        },
+                        cause: cause(`the session ended: ${input.reason}`),
+                    },
+                ];
+            case 'CwdChanged':
+                return [
+                    {
+                        to: this.#machine.state,
+                        where: { ...this.#machine.where, cwd: input.new_cwd },
+                        cause: cause(`the working directory moved from ${input.old_cwd}`),
+                    },
+                ];
+            case 'SubagentStart':
+                return [
+                    {
+                        to: 'working',
+                        entry: {
+                            op: 'open',
+                            entryId: input.agent_id,
+                            activity: { kind: 'subagent', name: input.agent_type },
+                            agentId: input.agent_id,
+                        },
+                        cause: cause(`subagent ${input.agent_type} started`),
+                    },
+                ];
+            case 'SubagentStop':
+                return [
+                    {
+                        to: 'working',
+                        entry: { op: 'close', entryId: input.agent_id },
+                        cause: cause(`subagent ${input.agent_type} stopped`),
+                    },
+                ];
+            case 'PreCompact':
+                return [
+                    {
+                        to: 'working',
+                        entry: { op: 'open', entryId: COMPACTION_ENTRY, activity: { kind: 'compacting', name: null } },
+                        cause: cause(`compaction started (${input.trigger})`),
+                    },
+                ];
+            case 'PostCompact':
+                return [
+                    {
+                        to: 'working',
+                        entry: { op: 'close', entryId: COMPACTION_ENTRY },
+                        cause: cause(`compaction finished (${input.trigger})`),
+                    },
+                ];
+            case 'PermissionRequest':
+                // Keyed by tool name, because `PermissionRequestHookInput` carries no tool_use_id while
+                // `PermissionDeniedHookInput` does — there is no shared id to join on. Two simultaneous
+                // requests for the same tool would therefore share one entry; the exit still fires and the
+                // trace stays truthful, but the pair is not distinguishable. Stated rather than hidden.
+                return [
+                    {
+                        to: 'working',
+                        entry: {
+                            op: 'open',
+                            entryId: permissionEntry(input.tool_name),
+                            activity: { kind: 'permission', name: input.tool_name },
+                            agentId: input.agent_id ?? null,
+                        },
+                        cause: cause(`a permission decision for ${input.tool_name} is outstanding`),
+                    },
+                ];
+            case 'PermissionDenied':
+                // A denial. An outage in the same path arrives as cause kind `refusal` with a refusal
+                // reason — two independent discriminators apart, because an infrastructure failure
+                // wearing a denial's clothes impersonates a human "no", and that is the most expensive
+                // confusion a controller can make.
+                return [
+                    {
+                        to: 'working',
+                        entry: { op: 'close', entryId: permissionEntry(input.tool_name) },
+                        cause: cause(`${input.tool_name} was denied: ${input.reason}`),
+                    },
+                ];
+            case 'Elicitation':
+                return [
+                    {
+                        to: 'working',
+                        entry: {
+                            op: 'open',
+                            entryId: elicitationEntry(input.elicitation_id, input.mcp_server_name),
+                            activity: { kind: 'elicitation', name: input.mcp_server_name },
+                        },
+                        cause: cause(`${input.mcp_server_name} asked for input`),
+                    },
+                ];
+            case 'ElicitationResult':
+                return [
+                    {
+                        to: 'working',
+                        entry: { op: 'close', entryId: elicitationEntry(input.elicitation_id, input.mcp_server_name) },
+                        cause: cause(`${input.mcp_server_name} elicitation ${input.action}`),
+                    },
+                ];
+            default:
+                // Declined by coverage.ts, every one of them with a stated reason. This is not a silent
+                // default: the table is the map, and an event absent from it is the gap.
+                return [];
+        }
+    }
+    #isOpen(entryId) {
+        return this.#machine.openEntries().some((entry) => entry.entryId === entryId);
+    }
+}
+const elicitationEntry = (elicitationId, server) => `elicitation:${elicitationId ?? server}`;
+/**
+ * `SDKStatus` -> the request/compaction lanes. Null is the exit, not an absence of information.
+ */
+function statusRequests(status, cause) {
+    if (status === 'requesting') {
+        return [
+            {
+                to: 'working',
+                entry: { op: 'open', entryId: REQUEST_ENTRY, activity: { kind: 'requesting', name: null } },
+                cause: cause('a model request is in flight'),
+            },
+        ];
+    }
+    if (status === 'compacting') {
+        return [
+            {
+                to: 'working',
+                entry: { op: 'open', entryId: COMPACTION_ENTRY, activity: { kind: 'compacting', name: null } },
+                cause: cause('compaction is in flight'),
+            },
+        ];
+    }
+    return [
+        {
+            to: 'working',
+            entry: { op: 'close', entryId: REQUEST_ENTRY },
+            cause: cause('the model request finished'),
+        },
+    ];
+}
+//# sourceMappingURL=observer.js.map