instar 0.28.113 → 0.28.115

package/dist/providers/primitives/control/contextScopeControl.js

@@ -0,0 +1,24 @@
+/**
+ * ContextScopeControl — control what context the session loads at startup.
+ *
+ * Providers automatically load instruction files (CLAUDE.md / AGENTS.md)
+ * and settings from various scopes (user-global, project, current-dir).
+ * Sometimes callers want to exclude project context (e.g., for
+ * lightweight classification calls that shouldn't pick up the agent's
+ * personality).
+ *
+ * Maps to:
+ *   - Claude: `--setting-sources` CLI flag (e.g., `user` to exclude
+ *     project CLAUDE.md). The existing ClaudeCliIntelligenceProvider
+ *     uses this to keep judgment calls clean.
+ *   - Codex: `project_doc_max_bytes`, `project_doc_fallback_filenames`,
+ *     `trusted-project gating` in config.toml. AGENTS.md cascade is
+ *     root→cwd with override files (richer than Claude's monolithic).
+ *
+ * Asymmetric on cascade semantics: Claude has a flat priority (project >
+ * user > builtin), Codex has a layered cascade. The abstraction presents
+ * a uniform `scopes: ('builtin' | 'user' | 'project' | 'directory')[]`
+ * include-list; adapters translate.
+ */
+export {};
+//# sourceMappingURL=contextScopeControl.js.map

package/dist/providers/primitives/control/contextScopeControl.js.map

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

package/dist/providers/primitives/control/credentialStorageProvider.d.ts

@@ -0,0 +1,48 @@
+/**
+ * CredentialStorageProvider — persistent storage for provider credentials.
+ *
+ * Distinct from AuthCredentialInjection (spawn-time injection). This
+ * primitive manages the credentials themselves: storing, retrieving,
+ * rotating, multi-account switching.
+ *
+ * Maps to:
+ *   - Claude: macOS Keychain (service name "Claude Code-credentials"),
+ *     fall back to `~/.claude/` config file
+ *   - Codex: `cli_auth_credentials_store = "file" | "keyring" | "auto"`
+ *     in `~/.codex/config.toml` — first-class backend abstraction
+ *
+ * Codex exposes the backend choice as a config key; Claude infers it. The
+ * abstraction surfaces both: `getBackend()` always works; `setBackend()`
+ * works on Codex and throws UnsupportedCapabilityError on Claude.
+ *
+ * The "account" concept: most providers allow multiple credentials stored
+ * concurrently and selected per-session. Instar's existing
+ * `AccountSwitcher` (in monitoring/) is a consumer of this.
+ */
+import type { CancellationOptions } from '../../types.js';
+import type { ProviderCredential } from './authCredentialInjection.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface CredentialStorageProvider {
+    readonly capability: typeof CapabilityFlag.CredentialStorageProvider;
+    /** Which storage backend is currently active. */
+    getBackend(): CredentialBackend;
+    /**
+     * Set the storage backend. Adapters that don't support runtime switching
+     * (Claude) throw UnsupportedCapabilityError.
+     */
+    setBackend(backend: CredentialBackend, options?: CancellationOptions): Promise<void>;
+    /** List all stored account labels. */
+    listAccounts(options?: CancellationOptions): Promise<ReadonlyArray<string>>;
+    /** Retrieve a credential by account label. Returns null if absent. */
+    get(accountLabel: string, options?: CancellationOptions): Promise<ProviderCredential | null>;
+    /** Store a credential under an account label. Overwrites if present. */
+    set(accountLabel: string, credential: ProviderCredential, options?: CancellationOptions): Promise<void>;
+    /** Remove a credential. */
+    remove(accountLabel: string, options?: CancellationOptions): Promise<void>;
+    /** Which account is currently selected as default for new sessions. */
+    getActiveAccount(options?: CancellationOptions): Promise<string | null>;
+    /** Set the active account. */
+    setActiveAccount(accountLabel: string, options?: CancellationOptions): Promise<void>;
+}
+export type CredentialBackend = 'file' | 'keyring' | 'auto';
+//# sourceMappingURL=credentialStorageProvider.d.ts.map

package/dist/providers/primitives/control/credentialStorageProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentialStorageProvider.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/control/credentialStorageProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,yBAAyB,CAAC;IAErE,iDAAiD;IACjD,UAAU,IAAI,iBAAiB,CAAC;IAEhC;;;OAGG;IACH,UAAU,CACR,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,sCAAsC;IACtC,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAE5E,sEAAsE;IACtE,GAAG,CACD,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAEtC,wEAAwE;IACxE,GAAG,CACD,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,kBAAkB,EAC9B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,2BAA2B;IAC3B,MAAM,CACJ,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,uEAAuE;IACvE,gBAAgB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAExE,8BAA8B;IAC9B,gBAAgB,CACd,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC"}

package/dist/providers/primitives/control/credentialStorageProvider.js

@@ -0,0 +1,23 @@
+/**
+ * CredentialStorageProvider — persistent storage for provider credentials.
+ *
+ * Distinct from AuthCredentialInjection (spawn-time injection). This
+ * primitive manages the credentials themselves: storing, retrieving,
+ * rotating, multi-account switching.
+ *
+ * Maps to:
+ *   - Claude: macOS Keychain (service name "Claude Code-credentials"),
+ *     fall back to `~/.claude/` config file
+ *   - Codex: `cli_auth_credentials_store = "file" | "keyring" | "auto"`
+ *     in `~/.codex/config.toml` — first-class backend abstraction
+ *
+ * Codex exposes the backend choice as a config key; Claude infers it. The
+ * abstraction surfaces both: `getBackend()` always works; `setBackend()`
+ * works on Codex and throws UnsupportedCapabilityError on Claude.
+ *
+ * The "account" concept: most providers allow multiple credentials stored
+ * concurrently and selected per-session. Instar's existing
+ * `AccountSwitcher` (in monitoring/) is a consumer of this.
+ */
+export {};
+//# sourceMappingURL=credentialStorageProvider.js.map

package/dist/providers/primitives/control/credentialStorageProvider.js.map

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

package/dist/providers/primitives/control/hardKill.d.ts

@@ -0,0 +1,39 @@
+/**
+ * HardKill — force-terminate a session.
+ *
+ * The nuclear option: stop the session NOW regardless of state. For
+ * graceful shutdown, use the transport primitive's native close/retire/end
+ * method instead. HardKill is for unresponsive sessions, runaway loops,
+ * security responses, and emergency cleanup.
+ *
+ * Maps to:
+ *   - Claude tmux session: `tmux kill-session -t <session>`
+ *   - Codex CLI process: SIGTERM then SIGKILL escalation
+ *   - Codex app-server: `thread/closed` after `turn/interrupt` if needed
+ *
+ * Implementations SHOULD attempt graceful kill first (SIGTERM equivalent)
+ * and escalate to forceful kill (SIGKILL equivalent) after a short grace
+ * period. The escalation is implementation-specific; consumers see only
+ * "session is gone."
+ */
+import type { CancellationOptions, SessionHandle } from '../../types.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface HardKill {
+    readonly capability: typeof CapabilityFlag.HardKill;
+    /**
+     * Force-terminate the session. Returns when the session is confirmed
+     * dead — adapters MUST verify the process actually exited before
+     * resolving.
+     */
+    kill(session: SessionHandle, options?: HardKillOptions): Promise<void>;
+}
+export interface HardKillOptions extends CancellationOptions {
+    /**
+     * Grace period (ms) for graceful shutdown before escalating to forceful
+     * kill. Default: 5000.
+     */
+    graceMs?: number;
+    /** Optional reason for the kill, recorded in audit logs. */
+    reason?: string;
+}
+//# sourceMappingURL=hardKill.d.ts.map

package/dist/providers/primitives/control/hardKill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hardKill.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/control/hardKill.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,QAAQ;IACvB,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,QAAQ,CAAC;IAEpD;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxE;AAED,MAAM,WAAW,eAAgB,SAAQ,mBAAmB;IAC1D;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/providers/primitives/control/hardKill.js

@@ -0,0 +1,20 @@
+/**
+ * HardKill — force-terminate a session.
+ *
+ * The nuclear option: stop the session NOW regardless of state. For
+ * graceful shutdown, use the transport primitive's native close/retire/end
+ * method instead. HardKill is for unresponsive sessions, runaway loops,
+ * security responses, and emergency cleanup.
+ *
+ * Maps to:
+ *   - Claude tmux session: `tmux kill-session -t <session>`
+ *   - Codex CLI process: SIGTERM then SIGKILL escalation
+ *   - Codex app-server: `thread/closed` after `turn/interrupt` if needed
+ *
+ * Implementations SHOULD attempt graceful kill first (SIGTERM equivalent)
+ * and escalate to forceful kill (SIGKILL equivalent) after a short grace
+ * period. The escalation is implementation-specific; consumers see only
+ * "session is gone."
+ */
+export {};
+//# sourceMappingURL=hardKill.js.map

package/dist/providers/primitives/control/hardKill.js.map

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

package/dist/providers/primitives/control/idleBound.d.ts

@@ -0,0 +1,48 @@
+/**
+ * IdleBound — kill or restart a session that's been idle too long.
+ *
+ * Distinct from TimeoutBound (which enforces total wall-clock duration).
+ * IdleBound triggers when the session has been waiting at the idle prompt
+ * (no model activity, no input) for longer than N minutes.
+ *
+ * Used by Instar's existing `idlePromptKillMinutes` on SessionManager.
+ * Prevents unbounded session accumulation when an agent finishes early
+ * but the session is left running.
+ *
+ * Maps to:
+ *   - Claude: external watchdog detects idle marker in tmux capture-pane
+ *     and kills the session
+ *   - Codex: app-server `thread/idle` notifications + external watchdog
+ *   - Both: NEITHER has native idle-timeout config (capability flag
+ *     `NativeIdleBound` is false for both adapters); the primitive
+ *     wraps external enforcement
+ */
+import type { CancellationOptions, SessionHandle } from '../../types.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface IdleBound {
+    readonly capability: typeof CapabilityFlag.IdleBound;
+    /**
+     * Set idle behavior for a session.
+     */
+    setIdlePolicy(session: SessionHandle, policy: IdlePolicy, options?: CancellationOptions): Promise<void>;
+    /** Read the current idle policy, or null if none set. */
+    getIdlePolicy(session: SessionHandle, options?: CancellationOptions): Promise<IdlePolicy | null>;
+    /** Clear the idle policy (session can be idle indefinitely). */
+    clearIdlePolicy(session: SessionHandle, options?: CancellationOptions): Promise<void>;
+}
+export interface IdlePolicy {
+    /** Minutes of idle time before action triggers. */
+    idleMinutes: number;
+    /** What to do when idle threshold is reached. */
+    action: 'hard-kill' | 'graceful-end' | 'restart' | 'notify-only';
+    /** Optional reason recorded when action fires. */
+    reason?: string;
+    /**
+     * Topics/sessions that should NEVER be reaped regardless of idle time.
+     * Used by Instar's protectedSessions concept. Mostly redundant if the
+     * caller is setting policy per-session, but useful when a generic policy
+     * applies to many sessions.
+     */
+    protectFromReaping?: boolean;
+}
+//# sourceMappingURL=idleBound.d.ts.map

package/dist/providers/primitives/control/idleBound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idleBound.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/control/idleBound.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;;OAEG;IACH,aAAa,CACX,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,yDAAyD;IACzD,aAAa,CACX,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE9B,gEAAgE;IAChE,eAAe,CACb,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,MAAM,EAAE,WAAW,GAAG,cAAc,GAAG,SAAS,GAAG,aAAa,CAAC;IACjE,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B"}

package/dist/providers/primitives/control/idleBound.js

@@ -0,0 +1,21 @@
+/**
+ * IdleBound — kill or restart a session that's been idle too long.
+ *
+ * Distinct from TimeoutBound (which enforces total wall-clock duration).
+ * IdleBound triggers when the session has been waiting at the idle prompt
+ * (no model activity, no input) for longer than N minutes.
+ *
+ * Used by Instar's existing `idlePromptKillMinutes` on SessionManager.
+ * Prevents unbounded session accumulation when an agent finishes early
+ * but the session is left running.
+ *
+ * Maps to:
+ *   - Claude: external watchdog detects idle marker in tmux capture-pane
+ *     and kills the session
+ *   - Codex: app-server `thread/idle` notifications + external watchdog
+ *   - Both: NEITHER has native idle-timeout config (capability flag
+ *     `NativeIdleBound` is false for both adapters); the primitive
+ *     wraps external enforcement
+ */
+export {};
+//# sourceMappingURL=idleBound.js.map

package/dist/providers/primitives/control/idleBound.js.map

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

package/dist/providers/primitives/control/inputInjection.d.ts

@@ -0,0 +1,46 @@
+/**
+ * InputInjection — send input to a running session mid-flight.
+ *
+ * For interactive REPL sessions, this is how instar injects prompts after
+ * the session has started. The transport primitives establish the session;
+ * this control primitive feeds it.
+ *
+ * Maps to:
+ *   - Claude tmux session: `tmux send-keys -t <session> -l "<text>"` + Enter
+ *   - Codex app-server: `turn/steer` JSON-RPC method
+ *   - Codex CLI in tmux: same tmux send-keys pattern
+ *
+ * Composes with WarmSessionInbox (which provides a structured inbox channel
+ * — preferred for portability) and AgenticSessionRpc (which has native
+ * `steerTurn`). InputInjection is the lower-level primitive used by
+ * adapters internally and exposed for direct use when needed.
+ */
+import type { CancellationOptions, SessionHandle } from '../../types.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface InputInjection {
+    readonly capability: typeof CapabilityFlag.InputInjection;
+    /**
+     * Inject text input into the session. By default, appends a newline
+     * (treats input as a complete prompt). Adapters MUST handle escaping
+     * and special characters safely — callers pass plain text.
+     */
+    send(session: SessionHandle, input: string, options?: InputInjectionOptions): Promise<void>;
+    /**
+     * Send a control sequence (Ctrl-C, Ctrl-D, Escape, arrow keys, etc.).
+     * Distinct from text input because some providers route these through
+     * a different mechanism.
+     */
+    sendKey(session: SessionHandle, key: ControlKey, options?: CancellationOptions): Promise<void>;
+}
+export interface InputInjectionOptions extends CancellationOptions {
+    /** Whether to append Enter/newline after the text. Default: true. */
+    submitOnEnter?: boolean;
+    /**
+     * Whether to wait briefly between the text and the newline (gives the
+     * provider time to process bracketed-paste sequences). Default: 500ms
+     * for tmux providers; ignored for structured-RPC providers.
+     */
+    paddingMs?: number;
+}
+export type ControlKey = 'Enter' | 'Escape' | 'Tab' | 'BackTab' | 'Backspace' | 'Delete' | 'C-c' | 'C-d' | 'C-z' | 'C-l' | 'Up' | 'Down' | 'Left' | 'Right';
+//# sourceMappingURL=inputInjection.d.ts.map

package/dist/providers/primitives/control/inputInjection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputInjection.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/control/inputInjection.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,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,cAAc,CAAC;IAE1D;;;;OAIG;IACH,IAAI,CACF,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CACL,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,UAAU,EACf,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,qEAAqE;IACrE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,UAAU,GAClB,OAAO,GACP,QAAQ,GACR,KAAK,GACL,SAAS,GACT,WAAW,GACX,QAAQ,GACR,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,IAAI,GACJ,MAAM,GACN,MAAM,GACN,OAAO,CAAC"}

package/dist/providers/primitives/control/inputInjection.js

@@ -0,0 +1,19 @@
+/**
+ * InputInjection — send input to a running session mid-flight.
+ *
+ * For interactive REPL sessions, this is how instar injects prompts after
+ * the session has started. The transport primitives establish the session;
+ * this control primitive feeds it.
+ *
+ * Maps to:
+ *   - Claude tmux session: `tmux send-keys -t <session> -l "<text>"` + Enter
+ *   - Codex app-server: `turn/steer` JSON-RPC method
+ *   - Codex CLI in tmux: same tmux send-keys pattern
+ *
+ * Composes with WarmSessionInbox (which provides a structured inbox channel
+ * — preferred for portability) and AgenticSessionRpc (which has native
+ * `steerTurn`). InputInjection is the lower-level primitive used by
+ * adapters internally and exposed for direct use when needed.
+ */
+export {};
+//# sourceMappingURL=inputInjection.js.map

package/dist/providers/primitives/control/inputInjection.js.map

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

package/dist/providers/primitives/control/intelligenceCallQueue.d.ts

@@ -0,0 +1,106 @@
+/**
+ * IntelligenceCallQueue — quota-aware concurrent LLM dispatch.
+ *
+ * Sits between application modules that need LLM access and the underlying
+ * OneShotCompletion / StructuredOneShot primitives. Coordinates:
+ *   - Concurrency limits (don't run more than N in parallel against the
+ *     same provider quota)
+ *   - Deduplication (collapse identical in-flight requests)
+ *   - Batching (when the provider supports request bundling)
+ *   - Daily/weekly spend caps (refuse calls above a budget threshold)
+ *   - Per-tier rate limits (Haiku separate from Sonnet pool)
+ *   - AbortSignal coordination across modules
+ *
+ * Instar's existing `LlmQueue` is the in-tree consumer of this pattern;
+ * primitives like PresenceProxy, PromiseBeacon, StallTriageNurse all
+ * compete for the same provider quota and need this coordination.
+ *
+ * This primitive is provider-agnostic; the queue logic doesn't depend on
+ * which provider is underneath. The provider abstraction surfaces it so
+ * that routing policies can use it as the actual dispatch point rather
+ * than calling primitives directly.
+ */
+import type { CancellationOptions, ModelTier } from '../../types.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface IntelligenceCallQueue {
+    readonly capability: typeof CapabilityFlag.IntelligenceCallQueue;
+    /**
+     * Enqueue a call for execution. Returns when the call has been accepted;
+     * the actual result is delivered via the provided `onResult` callback or
+     * via awaiting the returned promise's resolved value.
+     *
+     * Honors options:
+     *   - dedupeKey: collapse identical pending requests
+     *   - priority: tier within the queue
+     *   - costEstimate: pre-check against budget caps
+     */
+    enqueue<T>(request: IntelligenceCallRequest<T>, options?: IntelligenceCallQueueOptions): Promise<T>;
+    /**
+     * Read current queue state for observability dashboards.
+     */
+    status(options?: CancellationOptions): Promise<QueueStatus>;
+    /**
+     * Update queue policy at runtime. Useful for adjusting concurrency
+     * limits when adapting to provider rate-limit feedback.
+     */
+    setPolicy(policy: Partial<IntelligenceCallQueuePolicy>, options?: CancellationOptions): Promise<void>;
+}
+export interface IntelligenceCallRequest<T> {
+    /** Logical request identifier — used for dedup and audit. */
+    requestId: string;
+    /** Module/source emitting this call (for fairness and attribution). */
+    source: string;
+    /** Model tier. */
+    model: ModelTier;
+    /**
+     * The actual execution function. The queue calls this when the request
+     * reaches the head and any concurrency/budget guards have cleared.
+     */
+    execute: () => Promise<T>;
+    /** Optional estimated cost in USD for pre-budget checks. */
+    estimatedCostUsd?: number;
+}
+export interface IntelligenceCallQueueOptions extends CancellationOptions {
+    /**
+     * Deduplication key. If a pending request has the same key, the new
+     * request shares its result. Default: undefined (no dedup).
+     */
+    dedupeKey?: string;
+    /** Priority — higher number = earlier in queue. Default: 0. */
+    priority?: number;
+    /** Estimated cost for pre-budget check (overrides request.estimatedCostUsd). */
+    costEstimate?: number;
+}
+export interface QueueStatus {
+    /** Currently executing calls. */
+    inFlight: number;
+    /** Waiting calls. */
+    queued: number;
+    /** Total calls completed this session. */
+    completed: number;
+    /** Total cost spent this billing period (best-effort). */
+    spentUsd: number;
+    /** Per-tier breakdown. */
+    byTier: ReadonlyMap<ModelTier, {
+        inFlight: number;
+        queued: number;
+    }>;
+}
+export interface IntelligenceCallQueuePolicy {
+    /** Max concurrent calls overall. */
+    maxConcurrent: number;
+    /** Max concurrent per tier (overrides overall when set). */
+    maxConcurrentByTier: Partial<Record<ModelTier, number>>;
+    /** Daily spend cap in USD. Refuses calls above this. */
+    dailySpendCapUsd?: number;
+    /** Per-tier daily spend cap. */
+    dailySpendCapByTierUsd: Partial<Record<ModelTier, number>>;
+    /**
+     * Action when caps are exceeded. 'refuse' rejects with QuotaError.
+     * 'defer' queues until the next reset window. 'estimate-only' refuses
+     * only when the estimate is provided and known to exceed; without an
+     * estimate, lets the call through.
+     */
+    capOverflowAction: 'refuse' | 'defer' | 'estimate-only';
+}
+//# sourceMappingURL=intelligenceCallQueue.d.ts.map

package/dist/providers/primitives/control/intelligenceCallQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intelligenceCallQueue.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/control/intelligenceCallQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,qBAAqB,CAAC;IAEjE;;;;;;;;;OASG;IACH,OAAO,CAAC,CAAC,EACP,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,EACnC,OAAO,CAAC,EAAE,4BAA4B,GACrC,OAAO,CAAC,CAAC,CAAC,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAE5D;;;OAGG;IACH,SAAS,CACP,MAAM,EAAE,OAAO,CAAC,2BAA2B,CAAC,EAC5C,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1B,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA6B,SAAQ,mBAAmB;IACvE;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,MAAM,EAAE,WAAW,CAAC,SAAS,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,2BAA2B;IAC1C,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,mBAAmB,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;IACxD,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gCAAgC;IAChC,sBAAsB,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3D;;;;;OAKG;IACH,iBAAiB,EAAE,QAAQ,GAAG,OAAO,GAAG,eAAe,CAAC;CACzD"}

package/dist/providers/primitives/control/intelligenceCallQueue.js

@@ -0,0 +1,24 @@
+/**
+ * IntelligenceCallQueue — quota-aware concurrent LLM dispatch.
+ *
+ * Sits between application modules that need LLM access and the underlying
+ * OneShotCompletion / StructuredOneShot primitives. Coordinates:
+ *   - Concurrency limits (don't run more than N in parallel against the
+ *     same provider quota)
+ *   - Deduplication (collapse identical in-flight requests)
+ *   - Batching (when the provider supports request bundling)
+ *   - Daily/weekly spend caps (refuse calls above a budget threshold)
+ *   - Per-tier rate limits (Haiku separate from Sonnet pool)
+ *   - AbortSignal coordination across modules
+ *
+ * Instar's existing `LlmQueue` is the in-tree consumer of this pattern;
+ * primitives like PresenceProxy, PromiseBeacon, StallTriageNurse all
+ * compete for the same provider quota and need this coordination.
+ *
+ * This primitive is provider-agnostic; the queue logic doesn't depend on
+ * which provider is underneath. The provider abstraction surfaces it so
+ * that routing policies can use it as the actual dispatch point rather
+ * than calling primitives directly.
+ */
+export {};
+//# sourceMappingURL=intelligenceCallQueue.js.map

package/dist/providers/primitives/control/intelligenceCallQueue.js.map

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

package/dist/providers/primitives/control/interrupt.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Interrupt — cancel an in-flight model turn without ending the session.
+ *
+ * Distinct from HardKill (which ends the entire session) and from
+ * AbortError on the start call (which can only interrupt at start). This
+ * primitive interrupts the model mid-generation — the session continues
+ * and accepts new input, but the current turn is abandoned.
+ *
+ * Maps to:
+ *   - Claude tmux session: send Ctrl-C via tmux send-keys; the REPL
+ *     interrupts the current generation and returns to the idle prompt
+ *   - Codex app-server: `turn/interrupt` JSON-RPC method
+ *   - Codex CLI process: SIGINT (not as clean — process may exit)
+ *
+ * Used by:
+ *   - Stall triage (interrupt a stuck tool call, let user re-prompt)
+ *   - User-initiated cancellation in long-running sessions
+ *   - StopGateInterceptor refusals that need to actually stop generation
+ *
+ * Implementations MUST leave the session in an usable state after
+ * interrupt. If the provider's interrupt mechanism is destructive (kills
+ * the session), the adapter MUST report `supportedKind === 'non-destructive'`
+ * as `false` so consumers can decide.
+ */
+import type { CancellationOptions, SessionHandle } from '../../types.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface Interrupt {
+    readonly capability: typeof CapabilityFlag.Interrupt;
+    /**
+     * Cancel the current in-flight turn. Returns when the turn is confirmed
+     * canceled and the session is back at idle. Adapter SHOULD timeout if
+     * the cancel takes too long.
+     */
+    interrupt(session: SessionHandle, options?: InterruptOptions): Promise<void>;
+    /**
+     * Whether interrupt is non-destructive (session continues usable).
+     * Callers checking this can decide whether to interrupt or hard-kill.
+     */
+    isNonDestructive(): boolean;
+}
+export interface InterruptOptions extends CancellationOptions {
+    /** Optional reason recorded in audit logs / session events. */
+    reason?: string;
+}
+//# sourceMappingURL=interrupt.d.ts.map

package/dist/providers/primitives/control/interrupt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interrupt.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/control/interrupt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;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;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7E;;;OAGG;IACH,gBAAgB,IAAI,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAiB,SAAQ,mBAAmB;IAC3D,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/providers/primitives/control/interrupt.js

@@ -0,0 +1,26 @@
+/**
+ * Interrupt — cancel an in-flight model turn without ending the session.
+ *
+ * Distinct from HardKill (which ends the entire session) and from
+ * AbortError on the start call (which can only interrupt at start). This
+ * primitive interrupts the model mid-generation — the session continues
+ * and accepts new input, but the current turn is abandoned.
+ *
+ * Maps to:
+ *   - Claude tmux session: send Ctrl-C via tmux send-keys; the REPL
+ *     interrupts the current generation and returns to the idle prompt
+ *   - Codex app-server: `turn/interrupt` JSON-RPC method
+ *   - Codex CLI process: SIGINT (not as clean — process may exit)
+ *
+ * Used by:
+ *   - Stall triage (interrupt a stuck tool call, let user re-prompt)
+ *   - User-initiated cancellation in long-running sessions
+ *   - StopGateInterceptor refusals that need to actually stop generation
+ *
+ * Implementations MUST leave the session in an usable state after
+ * interrupt. If the provider's interrupt mechanism is destructive (kills
+ * the session), the adapter MUST report `supportedKind === 'non-destructive'`
+ * as `false` so consumers can decide.
+ */
+export {};
+//# sourceMappingURL=interrupt.js.map

package/dist/providers/primitives/control/interrupt.js.map

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

package/dist/providers/primitives/control/stopGateInterceptor.d.ts

@@ -0,0 +1,55 @@
+/**
+ * StopGateInterceptor — intercept the provider's "I'm about to stop" signal,
+ * decide whether to let it stop or continue with a follow-up prompt.
+ *
+ * Maps to:
+ *   - Claude: Stop hook event with `decision: 'block', reason: '...'`
+ *     response continues the session
+ *   - Codex: same — Stop hook returning `{"decision":"block","reason":"..."}`
+ *     produces a continuation prompt (intentionally Claude-compatible)
+ *
+ * Used by Instar's existing UnjustifiedStopGate to keep sessions running
+ * when they prematurely declare "I'm done" but there's clearly more to do
+ * (plan files not finished, tests not run, etc.).
+ *
+ * The interceptor is registered with the provider via the HookEventReceiver
+ * primitive (Stop event kind). This primitive provides the higher-level
+ * decision API; underneath, an adapter uses HookEventReceiver to subscribe
+ * to Stop events and reply with the decision.
+ */
+import type { CancellationOptions, ProviderSpecific, SessionHandle } from '../../types.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface StopGateInterceptor {
+    readonly capability: typeof CapabilityFlag.StopGateInterceptor;
+    /**
+     * Register a decision callback for Stop events. The callback is invoked
+     * each time the agent declares it's done; its return value tells the
+     * provider whether to honor the stop or continue with a follow-up prompt.
+     *
+     * Returns an unsubscribe function. Registering a second handler replaces
+     * the first (one handler per session is sufficient).
+     */
+    register(session: SessionHandle, handler: StopGateHandler, options?: CancellationOptions): Promise<() => Promise<void>>;
+}
+export type StopGateHandler = (context: StopGateContext) => Promise<StopGateDecision> | StopGateDecision;
+export interface StopGateContext {
+    session: SessionHandle;
+    /** The session's last visible output, for context. */
+    recentOutput: string;
+    /** Provider-native payload for the Stop event. */
+    rawPayload: Readonly<Record<string, unknown>>;
+    /** ISO 8601 UTC timestamp of the Stop event. */
+    timestamp: string;
+    providerSpecific?: ProviderSpecific;
+}
+export type StopGateDecision = 
+/** Honor the stop — let the session end. */
+{
+    kind: 'allow';
+}
+/** Don't stop — continue with this follow-up instruction. */
+ | {
+    kind: 'continue';
+    reason: string;
+};
+//# sourceMappingURL=stopGateInterceptor.d.ts.map

package/dist/providers/primitives/control/stopGateInterceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stopGateInterceptor.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/control/stopGateInterceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,mBAAmB,CAAC;IAE/D;;;;;;;OAOG;IACH,QAAQ,CACN,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACjC;AAED,MAAM,MAAM,eAAe,GAAG,CAC5B,OAAO,EAAE,eAAe,KACrB,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,aAAa,CAAC;IACvB,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9C,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED,MAAM,MAAM,gBAAgB;AAC1B,4CAA4C;AAC1C;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE;AACnB,6DAA6D;GAC3D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/providers/primitives/control/stopGateInterceptor.js

@@ -0,0 +1,21 @@
+/**
+ * StopGateInterceptor — intercept the provider's "I'm about to stop" signal,
+ * decide whether to let it stop or continue with a follow-up prompt.
+ *
+ * Maps to:
+ *   - Claude: Stop hook event with `decision: 'block', reason: '...'`
+ *     response continues the session
+ *   - Codex: same — Stop hook returning `{"decision":"block","reason":"..."}`
+ *     produces a continuation prompt (intentionally Claude-compatible)
+ *
+ * Used by Instar's existing UnjustifiedStopGate to keep sessions running
+ * when they prematurely declare "I'm done" but there's clearly more to do
+ * (plan files not finished, tests not run, etc.).
+ *
+ * The interceptor is registered with the provider via the HookEventReceiver
+ * primitive (Stop event kind). This primitive provides the higher-level
+ * decision API; underneath, an adapter uses HookEventReceiver to subscribe
+ * to Stop events and reply with the decision.
+ */
+export {};
+//# sourceMappingURL=stopGateInterceptor.js.map