instar 0.28.113 → 0.28.115

package/dist/providers/primitives/observability/hookEventReceiver.d.ts

@@ -0,0 +1,88 @@
+/**
+ * HookEventReceiver — receive provider-emitted lifecycle hook events.
+ *
+ * Providers that support hook scripts (Claude Code, Codex CLI) can be
+ * configured to POST event payloads to an HTTP endpoint as they reach
+ * specific lifecycle points. Instar receives these via the
+ * HookEventReceiver primitive.
+ *
+ * Asymmetric across providers:
+ *   - Claude Code: 10+ hook event types (PostToolUse, SubagentStart,
+ *     SubagentStop, Stop, WorktreeCreate, WorktreeRemove, TaskCompleted,
+ *     SessionEnd, PreCompact, InstructionsLoaded, UserPromptSubmit)
+ *   - Codex: 6 hook event types (SessionStart, PreToolUse, PostToolUse,
+ *     PermissionRequest, UserPromptSubmit, Stop). Notably lacks Subagent
+ *     and PreCompact events.
+ *
+ * The abstraction exposes a union of all known event kinds with explicit
+ * per-event capability flags. Consumers can check `supportedEventKinds()`
+ * to discover what the current provider actually emits.
+ *
+ * For events the provider doesn't natively emit (Codex's lack of
+ * SubagentStart, e.g.), the adapter MAY synthesize them from other
+ * signals (Codex app-server `thread/started` notifications). When it
+ * does, set `synthesized: true` on the emitted event.
+ *
+ * Mapping intentionally compatible: Codex's hook return contract (JSON
+ * stdin/stdout, exit code 2 semantics) is deliberately Claude-compatible.
+ */
+import type { CancellationOptions, ProviderSpecific, SessionHandle } from '../../types.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface HookEventReceiver {
+    readonly capability: typeof CapabilityFlag.HookEventReceiver;
+    /** Which lifecycle event kinds this provider emits. */
+    supportedEventKinds(): ReadonlySet<HookEventKind>;
+    /**
+     * Subscribe to incoming hook events. Adapter manages the HTTP listener
+     * lifecycle and hook-script installation; consumer just iterates.
+     */
+    subscribe(options?: HookSubscribeOptions): AsyncIterable<HookEvent>;
+    /**
+     * Reply to a specific hook event with a decision payload. Required for
+     * gating hooks (Stop, PreToolUse, PermissionRequest) that the provider
+     * waits on. Adapter routes the reply back to the originating hook script.
+     */
+    reply(eventId: string, decision: HookDecision, options?: CancellationOptions): Promise<void>;
+}
+export type HookEventKind = 'session-start' | 'session-end' | 'pre-tool-use' | 'post-tool-use' | 'user-prompt-submit' | 'stop' | 'subagent-start' | 'subagent-stop' | 'worktree-create' | 'worktree-remove' | 'task-completed' | 'pre-compact' | 'instructions-loaded' | 'permission-request';
+export interface HookEvent {
+    /** Stable identifier for replying to this event. */
+    id: string;
+    kind: HookEventKind;
+    /** Session that triggered the event. */
+    session: SessionHandle;
+    /** ISO 8601 UTC timestamp. */
+    timestamp: string;
+    /**
+     * Provider's native payload for this event. Shape varies by kind and
+     * provider — consumers that need cross-provider portability should
+     * derive what they need from the typed top-level fields above and use
+     * `payload` only as escape hatch.
+     */
+    payload: Readonly<Record<string, unknown>>;
+    /** Whether this event was synthesized from a different signal. */
+    synthesized: boolean;
+    providerSpecific?: ProviderSpecific;
+}
+export interface HookSubscribeOptions extends CancellationOptions {
+    /** Restrict to a subset of event kinds. */
+    kinds?: ReadonlyArray<HookEventKind>;
+    /** Restrict to events from a specific session. */
+    session?: SessionHandle;
+}
+/**
+ * Decision payload for hooks that gate execution. The shape mirrors what
+ * both Claude and Codex accept (JSON to stdout from hook script):
+ *   { "decision": "approve" | "block" | "ask", "reason"?: string,
+ *     "stopReason"?: string }
+ *
+ * `decision: 'ask'` is provider-specific (Claude supports it for some
+ * gates; Codex doesn't). Adapter ignores or maps when unsupported.
+ */
+export interface HookDecision {
+    decision: 'approve' | 'block' | 'ask';
+    reason?: string;
+    /** For Stop hooks: continuation prompt when decision is 'block'. */
+    stopReason?: string;
+}
+//# sourceMappingURL=hookEventReceiver.d.ts.map

package/dist/providers/primitives/observability/hookEventReceiver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hookEventReceiver.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/observability/hookEventReceiver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,iBAAiB,CAAC;IAE7D,uDAAuD;IACvD,mBAAmB,IAAI,WAAW,CAAC,aAAa,CAAC,CAAC;IAElD;;;OAGG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IAEpE;;;;OAIG;IACH,KAAK,CACH,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,MAAM,aAAa,GAErB,eAAe,GACf,aAAa,GACb,cAAc,GACd,eAAe,GACf,oBAAoB,GACpB,MAAM,GAEN,gBAAgB,GAChB,eAAe,GACf,iBAAiB,GACjB,iBAAiB,GACjB,gBAAgB,GAChB,aAAa,GACb,qBAAqB,GAErB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,CAAC;IACpB,wCAAwC;IACxC,OAAO,EAAE,aAAa,CAAC;IACvB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3C,kEAAkE;IAClE,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D,2CAA2C;IAC3C,KAAK,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IACrC,kDAAkD;IAClD,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/providers/primitives/observability/hookEventReceiver.js

@@ -0,0 +1,30 @@
+/**
+ * HookEventReceiver — receive provider-emitted lifecycle hook events.
+ *
+ * Providers that support hook scripts (Claude Code, Codex CLI) can be
+ * configured to POST event payloads to an HTTP endpoint as they reach
+ * specific lifecycle points. Instar receives these via the
+ * HookEventReceiver primitive.
+ *
+ * Asymmetric across providers:
+ *   - Claude Code: 10+ hook event types (PostToolUse, SubagentStart,
+ *     SubagentStop, Stop, WorktreeCreate, WorktreeRemove, TaskCompleted,
+ *     SessionEnd, PreCompact, InstructionsLoaded, UserPromptSubmit)
+ *   - Codex: 6 hook event types (SessionStart, PreToolUse, PostToolUse,
+ *     PermissionRequest, UserPromptSubmit, Stop). Notably lacks Subagent
+ *     and PreCompact events.
+ *
+ * The abstraction exposes a union of all known event kinds with explicit
+ * per-event capability flags. Consumers can check `supportedEventKinds()`
+ * to discover what the current provider actually emits.
+ *
+ * For events the provider doesn't natively emit (Codex's lack of
+ * SubagentStart, e.g.), the adapter MAY synthesize them from other
+ * signals (Codex app-server `thread/started` notifications). When it
+ * does, set `synthesized: true` on the emitted event.
+ *
+ * Mapping intentionally compatible: Codex's hook return contract (JSON
+ * stdin/stdout, exit code 2 semantics) is deliberately Claude-compatible.
+ */
+export {};
+//# sourceMappingURL=hookEventReceiver.js.map

package/dist/providers/primitives/observability/hookEventReceiver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hookEventReceiver.js","sourceRoot":"","sources":["../../../../src/providers/primitives/observability/hookEventReceiver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}

package/dist/providers/primitives/observability/interactivePromptObserver.d.ts

@@ -0,0 +1,65 @@
+/**
+ * InteractivePromptObserver — detect when the agent is waiting on user input.
+ *
+ * Some agent CLIs emit interactive prompts at runtime — permission
+ * confirmations, plan-mode review, file-overwrite warnings. The
+ * abstraction observes these so instar can: auto-approve known-safe ones,
+ * surface unknown ones to the user via Telegram, or block hostile ones.
+ *
+ * Asymmetric across providers:
+ *   - Codex app-server: STRUCTURED. Emits
+ *     `item/commandExecution/requestApproval` and similar notifications
+ *     with parsed payloads. Capability flag `StructuredApprovalEvents` is true.
+ *   - Claude TUI: SCRAPED. Adapter parses terminal output for known
+ *     patterns ("Do you want to create...?", "❯ ", "Esc to cancel · Tab to amend").
+ *     Capability flag `StructuredApprovalEvents` is false; events carry
+ *     `source: 'scraped'`.
+ *
+ * Consumers should NOT branch on `StructuredApprovalEvents`. The abstraction
+ * presents both paths through the same event type. The flag matters for
+ * routing policy (preferring structured-event providers in trust-sensitive
+ * contexts) but not for ordinary event consumption.
+ */
+import type { CancellationOptions, SessionHandle } from '../../types.js';
+import type { InteractivePromptEvent } from '../../events.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface InteractivePromptObserver {
+    readonly capability: typeof CapabilityFlag.InteractivePromptObserver;
+    /** Whether the adapter parses structured events or scrapes terminal output. */
+    source(): 'structured' | 'scraped' | 'mixed';
+    /** Subscribe to prompt events from any session. */
+    subscribe(options?: PromptObserverOptions): AsyncIterable<InteractivePromptEvent>;
+    /**
+     * Respond to a prompt. Maps to:
+     *   - Structured providers: send a `requestApproval` reply via app-server
+     *   - Scraped providers: tmux send-keys to inject the user's choice
+     */
+    respond(session: SessionHandle, promptId: string, response: PromptResponse, options?: CancellationOptions): Promise<void>;
+}
+export interface PromptObserverOptions extends CancellationOptions {
+    /** Filter to specific session. */
+    session?: SessionHandle;
+    /** Filter to specific prompt kinds. */
+    kinds?: ReadonlyArray<InteractivePromptEvent['promptKind']>;
+}
+export type PromptResponse = 
+/** Yes / approve / accept. */
+{
+    kind: 'approve';
+}
+/** No / deny / cancel. */
+ | {
+    kind: 'deny';
+    reason?: string;
+}
+/** For selection prompts: pick a specific choice. */
+ | {
+    kind: 'select';
+    value: string;
+}
+/** For prompts that accept free-form input. */
+ | {
+    kind: 'input';
+    text: string;
+};
+//# sourceMappingURL=interactivePromptObserver.d.ts.map

package/dist/providers/primitives/observability/interactivePromptObserver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactivePromptObserver.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/observability/interactivePromptObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,yBAAyB,CAAC;IAErE,+EAA+E;IAC/E,MAAM,IAAI,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC;IAE7C,mDAAmD;IACnD,SAAS,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,aAAa,CAAC,sBAAsB,CAAC,CAAC;IAElF;;;;OAIG;IACH,OAAO,CACL,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,kCAAkC;IAClC,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,uCAAuC;IACvC,KAAK,CAAC,EAAE,aAAa,CAAC,sBAAsB,CAAC,YAAY,CAAC,CAAC,CAAC;CAC7D;AAED,MAAM,MAAM,cAAc;AACxB,8BAA8B;AAC5B;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE;AACrB,0BAA0B;GACxB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE;AACnC,qDAAqD;GACnD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACnC,+CAA+C;GAC7C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/providers/primitives/observability/interactivePromptObserver.js

@@ -0,0 +1,24 @@
+/**
+ * InteractivePromptObserver — detect when the agent is waiting on user input.
+ *
+ * Some agent CLIs emit interactive prompts at runtime — permission
+ * confirmations, plan-mode review, file-overwrite warnings. The
+ * abstraction observes these so instar can: auto-approve known-safe ones,
+ * surface unknown ones to the user via Telegram, or block hostile ones.
+ *
+ * Asymmetric across providers:
+ *   - Codex app-server: STRUCTURED. Emits
+ *     `item/commandExecution/requestApproval` and similar notifications
+ *     with parsed payloads. Capability flag `StructuredApprovalEvents` is true.
+ *   - Claude TUI: SCRAPED. Adapter parses terminal output for known
+ *     patterns ("Do you want to create...?", "❯ ", "Esc to cancel · Tab to amend").
+ *     Capability flag `StructuredApprovalEvents` is false; events carry
+ *     `source: 'scraped'`.
+ *
+ * Consumers should NOT branch on `StructuredApprovalEvents`. The abstraction
+ * presents both paths through the same event type. The flag matters for
+ * routing policy (preferring structured-event providers in trust-sensitive
+ * contexts) but not for ordinary event consumption.
+ */
+export {};
+//# sourceMappingURL=interactivePromptObserver.js.map

package/dist/providers/primitives/observability/interactivePromptObserver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactivePromptObserver.js","sourceRoot":"","sources":["../../../../src/providers/primitives/observability/interactivePromptObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG"}

package/dist/providers/primitives/observability/liveOutputStream.d.ts

@@ -0,0 +1,56 @@
+/**
+ * LiveOutputStream — real-time observation of a session's output.
+ *
+ * Provides a snapshot or tail of the session's live output buffer at any
+ * point during its execution. Used for: dashboards, watchdog detection,
+ * stall triage, debugging.
+ *
+ * Distinct from the session's `events` stream (which is structured) — this
+ * is the raw output as the user/agent sees it. For tmux-based providers,
+ * this is `capture-pane` output. For pure-API providers, it's the
+ * concatenation of message deltas plus tool I/O.
+ *
+ * Maps to:
+ *   - Claude tmux session: `tmux capture-pane -t <session> -p -S -N`
+ *   - Codex CLI process: stdout/stderr capture
+ *   - Codex app-server: subscribe to item.*.delta notifications and assemble
+ */
+import type { CancellationOptions, SessionHandle } from '../../types.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface LiveOutputStream {
+    readonly capability: typeof CapabilityFlag.LiveOutputStream;
+    /** Snapshot the last N lines of output for this session. */
+    snapshot(session: SessionHandle, options?: SnapshotOptions): Promise<OutputSnapshot>;
+    /**
+     * Subscribe to incremental output. Returns an async iterable of chunks
+     * as they arrive. Closes when the session ends or `signal` aborts.
+     */
+    tail(session: SessionHandle, options?: TailOptions): AsyncIterable<OutputChunk>;
+}
+export interface SnapshotOptions extends CancellationOptions {
+    /** Max number of lines to return from the end of the buffer. Default: 200. */
+    maxLines?: number;
+    /** Whether to include ANSI escape codes. Default: false (stripped). */
+    includeAnsi?: boolean;
+}
+export interface OutputSnapshot {
+    /** The captured output text. */
+    text: string;
+    /** Wall-clock time the snapshot was taken (ISO 8601 UTC). */
+    capturedAt: string;
+    /** Whether the buffer was truncated to fit maxLines. */
+    truncated: boolean;
+}
+export interface TailOptions extends CancellationOptions {
+    /** Whether to emit the existing buffer first before tailing new output. */
+    includeBacklog?: boolean;
+    /** Buffer-flush interval in ms. Lower = more frequent updates. Default: 250. */
+    flushIntervalMs?: number;
+}
+export interface OutputChunk {
+    /** Text content of this chunk. */
+    text: string;
+    /** Timestamp the chunk was produced. */
+    emittedAt: string;
+}
+//# sourceMappingURL=liveOutputStream.d.ts.map

package/dist/providers/primitives/observability/liveOutputStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveOutputStream.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/observability/liveOutputStream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,gBAAgB,CAAC;IAE5D,4DAA4D;IAC5D,QAAQ,CACN,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC,CAAC;IAE3B;;;OAGG;IACH,IAAI,CACF,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,WAAW,GACpB,aAAa,CAAC,WAAW,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,eAAgB,SAAQ,mBAAmB;IAC1D,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,WAAY,SAAQ,mBAAmB;IACtD,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gFAAgF;IAChF,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/providers/primitives/observability/liveOutputStream.js

@@ -0,0 +1,19 @@
+/**
+ * LiveOutputStream — real-time observation of a session's output.
+ *
+ * Provides a snapshot or tail of the session's live output buffer at any
+ * point during its execution. Used for: dashboards, watchdog detection,
+ * stall triage, debugging.
+ *
+ * Distinct from the session's `events` stream (which is structured) — this
+ * is the raw output as the user/agent sees it. For tmux-based providers,
+ * this is `capture-pane` output. For pure-API providers, it's the
+ * concatenation of message deltas plus tool I/O.
+ *
+ * Maps to:
+ *   - Claude tmux session: `tmux capture-pane -t <session> -p -S -N`
+ *   - Codex CLI process: stdout/stderr capture
+ *   - Codex app-server: subscribe to item.*.delta notifications and assemble
+ */
+export {};
+//# sourceMappingURL=liveOutputStream.js.map

package/dist/providers/primitives/observability/liveOutputStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveOutputStream.js","sourceRoot":"","sources":["../../../../src/providers/primitives/observability/liveOutputStream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/providers/primitives/observability/processLifecycle.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ProcessLifecycle — observe the OS-level process state of a session.
+ *
+ * Sessions usually run as subprocess (claude CLI, codex CLI) — this
+ * primitive reports whether the underlying process is alive, what its PID
+ * is, and signals when it exits. Used by orphan-process reapers,
+ * memory-pressure monitors, and crash detection.
+ *
+ * Maps to:
+ *   - Claude tmux: pid from tmux pane info; alive via `kill -0 <pid>`
+ *   - Codex CLI: same pattern when CLI is spawned as subprocess
+ *   - Codex app-server: server's `/readyz` / `/healthz` HTTP probes
+ *
+ * Distinct from session-level lifecycle events (those describe the agent's
+ * progress); this primitive is about the host process. A session can be
+ * "active" but its process can have crashed — both states matter for
+ * different consumers.
+ */
+import type { CancellationOptions, SessionHandle } from '../../types.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface ProcessLifecycle {
+    readonly capability: typeof CapabilityFlag.ProcessLifecycle;
+    /** Get the current process state for a session. */
+    state(session: SessionHandle, options?: CancellationOptions): Promise<ProcessState>;
+    /** Subscribe to state changes for a session. */
+    subscribe(session: SessionHandle): AsyncIterable<ProcessStateChange>;
+}
+export interface ProcessState {
+    /** Is the underlying process still alive? */
+    alive: boolean;
+    /** PID (or set of PIDs for compound processes). */
+    pids: ReadonlyArray<number>;
+    /** When the process(es) started, ISO 8601. */
+    startedAt: string;
+    /** Memory usage in bytes (resident set size). May be null if not queryable. */
+    rssBytes?: number;
+    /** CPU usage as a percentage of one core. May be null if not queryable. */
+    cpuPercent?: number;
+}
+export interface ProcessStateChange {
+    session: SessionHandle;
+    /** What changed. */
+    kind: 'died' | 'restarted' | 'memory-pressure' | 'cpu-spike';
+    state: ProcessState;
+    timestamp: string;
+}
+//# sourceMappingURL=processLifecycle.d.ts.map

package/dist/providers/primitives/observability/processLifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processLifecycle.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/observability/processLifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,gBAAgB,CAAC;IAE5D,mDAAmD;IACnD,KAAK,CACH,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB,gDAAgD;IAChD,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,KAAK,EAAE,OAAO,CAAC;IACf,mDAAmD;IACnD,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,aAAa,CAAC;IACvB,oBAAoB;IACpB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,iBAAiB,GAAG,WAAW,CAAC;IAC7D,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/providers/primitives/observability/processLifecycle.js

@@ -0,0 +1,20 @@
+/**
+ * ProcessLifecycle — observe the OS-level process state of a session.
+ *
+ * Sessions usually run as subprocess (claude CLI, codex CLI) — this
+ * primitive reports whether the underlying process is alive, what its PID
+ * is, and signals when it exits. Used by orphan-process reapers,
+ * memory-pressure monitors, and crash detection.
+ *
+ * Maps to:
+ *   - Claude tmux: pid from tmux pane info; alive via `kill -0 <pid>`
+ *   - Codex CLI: same pattern when CLI is spawned as subprocess
+ *   - Codex app-server: server's `/readyz` / `/healthz` HTTP probes
+ *
+ * Distinct from session-level lifecycle events (those describe the agent's
+ * progress); this primitive is about the host process. A session can be
+ * "active" but its process can have crashed — both states matter for
+ * different consumers.
+ */
+export {};
+//# sourceMappingURL=processLifecycle.js.map

package/dist/providers/primitives/observability/processLifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processLifecycle.js","sourceRoot":"","sources":["../../../../src/providers/primitives/observability/processLifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/providers/primitives/observability/sessionId.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SessionId — provider-side session identification and lookup.
+ *
+ * Most providers assign their own UUID/ID to each session, separate from
+ * the abstraction's SessionHandle. This primitive bridges between them
+ * and lets callers correlate cross-system references (e.g., a log line
+ * referencing a Claude session UUID can be mapped back to the
+ * SessionHandle that issued it).
+ *
+ * Used by:
+ *   - TopicResumeMap (server/routes.ts) — currently stores `claudeSessionId`
+ *   - ThreadResumeMap (threadline/) — same
+ *   - Migration to v1.0.0: rename `claudeSessionId` → `providerSessionId`
+ *     using this primitive's lookup
+ *
+ * Maps to:
+ *   - Claude: UUID written to JSONL filename + hook payloads
+ *   - Codex: UUIDv7 visible in `/status`, rollout filename, `thread.started` event
+ */
+import type { CancellationOptions, SessionHandle } from '../../types.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface SessionId {
+    readonly capability: typeof CapabilityFlag.SessionId;
+    /** Get the provider-side ID for a SessionHandle. */
+    providerIdFor(session: SessionHandle, options?: CancellationOptions): Promise<string | null>;
+    /**
+     * Reverse lookup: find the SessionHandle for a provider-side ID.
+     * Returns null if no active session matches (the session may have
+     * ended, in which case the resume index can still find it).
+     */
+    handleFor(providerSessionId: string, options?: CancellationOptions): Promise<SessionHandle | null>;
+}
+//# sourceMappingURL=sessionId.d.ts.map

package/dist/providers/primitives/observability/sessionId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionId.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/observability/sessionId.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,SAAS,CAAC;IAErD,oDAAoD;IACpD,aAAa,CACX,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE1B;;;;OAIG;IACH,SAAS,CACP,iBAAiB,EAAE,MAAM,EACzB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;CAClC"}

package/dist/providers/primitives/observability/sessionId.js

@@ -0,0 +1,21 @@
+/**
+ * SessionId — provider-side session identification and lookup.
+ *
+ * Most providers assign their own UUID/ID to each session, separate from
+ * the abstraction's SessionHandle. This primitive bridges between them
+ * and lets callers correlate cross-system references (e.g., a log line
+ * referencing a Claude session UUID can be mapped back to the
+ * SessionHandle that issued it).
+ *
+ * Used by:
+ *   - TopicResumeMap (server/routes.ts) — currently stores `claudeSessionId`
+ *   - ThreadResumeMap (threadline/) — same
+ *   - Migration to v1.0.0: rename `claudeSessionId` → `providerSessionId`
+ *     using this primitive's lookup
+ *
+ * Maps to:
+ *   - Claude: UUID written to JSONL filename + hook payloads
+ *   - Codex: UUIDv7 visible in `/status`, rollout filename, `thread.started` event
+ */
+export {};
+//# sourceMappingURL=sessionId.js.map

package/dist/providers/primitives/observability/sessionId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionId.js","sourceRoot":"","sources":["../../../../src/providers/primitives/observability/sessionId.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/providers/primitives/observability/subagentLifecycleObserver.d.ts

@@ -0,0 +1,53 @@
+/**
+ * SubagentLifecycleObserver — track subagent (child session) spawns and exits.
+ *
+ * Many agentic providers can spawn helper sessions ("subagents") via a
+ * Task tool or equivalent. Observing these lifecycles matters for
+ * resource accounting, watchdog coverage, and stall triage.
+ *
+ * Asymmetric across providers:
+ *   - Claude: native SubagentStart / SubagentStop hook events. Capability
+ *     flag `SubagentLifecycleHooks` is true.
+ *   - Codex: no native subagent hook events. Adapter synthesizes from
+ *     app-server `thread/started` / `thread/closed` notifications.
+ *     Capability flag `SubagentLifecycleHooks` is false; the observer
+ *     still works but the events are tagged `synthesized: true`.
+ *
+ * Distinct from HookEventReceiver because:
+ *   1. Subagent observation is critical enough that callers shouldn't have
+ *      to discover whether the provider has the right hook events.
+ *   2. Some providers (Codex) need synthesis from non-hook signals; this
+ *      primitive encapsulates that.
+ */
+import type { CancellationOptions, SessionHandle } from '../../types.js';
+import type { SubagentLifecycleEvent } from '../../events.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface SubagentLifecycleObserver {
+    readonly capability: typeof CapabilityFlag.SubagentLifecycleObserver;
+    /** Whether the provider's events are native hooks or synthesized. */
+    isNative(): boolean;
+    /**
+     * Subscribe to subagent lifecycle events. Returns an async iterable
+     * that emits when child sessions start, complete, or fail.
+     */
+    subscribe(options?: SubagentObserverOptions): AsyncIterable<SubagentLifecycleEvent>;
+    /**
+     * Get a one-shot snapshot of active subagents for a parent session.
+     * Useful for "what's running right now?" queries without subscribing.
+     */
+    active(parent: SessionHandle, options?: CancellationOptions): Promise<ReadonlyArray<ActiveSubagent>>;
+}
+export interface SubagentObserverOptions extends CancellationOptions {
+    /** Restrict to subagents of a specific parent session. */
+    parent?: SessionHandle;
+    /** Restrict to specific lifecycle kinds. */
+    kinds?: ReadonlyArray<SubagentLifecycleEvent['lifecycleKind']>;
+}
+export interface ActiveSubagent {
+    child: SessionHandle;
+    parent: SessionHandle;
+    startedAt: string;
+    /** Best-effort purpose / description from the parent's spawn request. */
+    purpose?: string;
+}
+//# sourceMappingURL=subagentLifecycleObserver.d.ts.map

package/dist/providers/primitives/observability/subagentLifecycleObserver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagentLifecycleObserver.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/observability/subagentLifecycleObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,yBAAyB,CAAC;IAErE,qEAAqE;IACrE,QAAQ,IAAI,OAAO,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,aAAa,CAAC,sBAAsB,CAAC,CAAC;IAEpF;;;OAGG;IACH,MAAM,CACJ,MAAM,EAAE,aAAa,EACrB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,0DAA0D;IAC1D,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,aAAa,CAAC,sBAAsB,CAAC,eAAe,CAAC,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/providers/primitives/observability/subagentLifecycleObserver.js

@@ -0,0 +1,23 @@
+/**
+ * SubagentLifecycleObserver — track subagent (child session) spawns and exits.
+ *
+ * Many agentic providers can spawn helper sessions ("subagents") via a
+ * Task tool or equivalent. Observing these lifecycles matters for
+ * resource accounting, watchdog coverage, and stall triage.
+ *
+ * Asymmetric across providers:
+ *   - Claude: native SubagentStart / SubagentStop hook events. Capability
+ *     flag `SubagentLifecycleHooks` is true.
+ *   - Codex: no native subagent hook events. Adapter synthesizes from
+ *     app-server `thread/started` / `thread/closed` notifications.
+ *     Capability flag `SubagentLifecycleHooks` is false; the observer
+ *     still works but the events are tagged `synthesized: true`.
+ *
+ * Distinct from HookEventReceiver because:
+ *   1. Subagent observation is critical enough that callers shouldn't have
+ *      to discover whether the provider has the right hook events.
+ *   2. Some providers (Codex) need synthesis from non-hook signals; this
+ *      primitive encapsulates that.
+ */
+export {};
+//# sourceMappingURL=subagentLifecycleObserver.js.map

package/dist/providers/primitives/observability/subagentLifecycleObserver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagentLifecycleObserver.js","sourceRoot":"","sources":["../../../../src/providers/primitives/observability/subagentLifecycleObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/dist/providers/primitives/observability/usageMeterProvider.d.ts

@@ -0,0 +1,76 @@
+/**
+ * UsageMeterProvider — query provider's authoritative usage/quota state.
+ *
+ * Reads cumulative usage and remaining quota from the provider's own
+ * accounting. Distinct from per-call `UsageReport` (which describes a
+ * single completion) — this primitive answers "where do I stand on my
+ * subscription limits / API quotas right now?"
+ *
+ * Asymmetric across providers:
+ *   - Anthropic: public OAuth usage API (`GET /api/oauth/usage`,
+ *     `GET /api/oauth/profile`). Capability flag `PublicUsageApi` is true.
+ *   - Codex: no documented public quota endpoint. Internal
+ *     `/backend-api/wham/usage` (undocumented, unstable) and
+ *     `account/rateLimits/read` JSON-RPC method on the app-server.
+ *     Capability flag `PublicUsageApi` is false; the adapter SHOULD fall
+ *     back to local accounting (sum `turn.completed.usage` per call) when
+ *     no authoritative source is available.
+ *
+ * Callers who care about exact billable spend MUST check `isAuthoritative`
+ * before trusting the data. Estimated/local-accounting data is still
+ * useful for "are we near the cap?" decisions.
+ */
+import type { CancellationOptions } from '../../types.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface UsageMeterProvider {
+    readonly capability: typeof CapabilityFlag.UsageMeterProvider;
+    /**
+     * Whether this adapter reads usage from an authoritative provider API
+     * (true for Anthropic), or estimates locally (true for Codex). When
+     * false, the data is best-effort and may diverge from the provider's
+     * actual accounting.
+     */
+    isAuthoritative(): boolean;
+    /** Read the current usage snapshot. */
+    read(options?: CancellationOptions): Promise<UsageSnapshot | null>;
+}
+export interface UsageSnapshot {
+    /** When this snapshot was taken. */
+    capturedAt: string;
+    /** Whether the data came from a provider API or local accounting. */
+    source: 'authoritative' | 'estimated';
+    /** Per-window usage. Most providers expose multiple windows simultaneously. */
+    windows: ReadonlyArray<UsageWindow>;
+    /**
+     * Special: the dedicated Agent SDK credit pot Anthropic introduced
+     * 2026-06-15. Distinct from the subscription quota windows because it
+     * has different semantics (drains first, no rollover, per-individual).
+     * Null on providers that don't have this concept.
+     */
+    agentSdkCredit?: AgentSdkCreditSnapshot | null;
+}
+export interface UsageWindow {
+    /** Window granularity. */
+    granularity: 'session' | 'hour' | '5-hour' | 'day' | 'week' | 'month';
+    /** When the window resets to zero. */
+    resetsAt: string;
+    /** Used percentage (0-100). */
+    usedPercent: number;
+    /** Used absolute count, if the provider reports it. Units are provider-specific. */
+    usedAbsolute?: number;
+    /** Limit absolute count, if the provider reports it. */
+    limitAbsolute?: number;
+    /** Best-effort label for the units (e.g., 'messages', 'tokens', 'requests'). */
+    unit?: string;
+}
+export interface AgentSdkCreditSnapshot {
+    /** USD balance remaining in the credit pot. */
+    remainingUsd: number;
+    /** USD total this billing period. */
+    totalUsd: number;
+    /** When the credit refreshes. */
+    resetsAt: string;
+    /** Whether overage to API rates is enabled. */
+    overageEnabled: boolean;
+}
+//# sourceMappingURL=usageMeterProvider.d.ts.map

package/dist/providers/primitives/observability/usageMeterProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageMeterProvider.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/observability/usageMeterProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,kBAAkB,CAAC;IAE9D;;;;;OAKG;IACH,eAAe,IAAI,OAAO,CAAC;IAE3B,uCAAuC;IACvC,IAAI,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,MAAM,EAAE,eAAe,GAAG,WAAW,CAAC;IACtC,+EAA+E;IAC/E,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACpC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,WAAW,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;IACtE,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,cAAc,EAAE,OAAO,CAAC;CACzB"}