instar 0.28.113 → 0.28.114

package/dist/providers/primitives/transport/agenticSessionHeadless.d.ts

@@ -0,0 +1,87 @@
+/**
+ * AgenticSessionHeadless — multi-turn agent session, tools enabled, no human.
+ *
+ * The workhorse primitive for autonomous instar jobs. Spawns a session that
+ * receives an initial prompt + capability grant, runs to completion (or until
+ * killed by control primitives), and streams events as it works.
+ *
+ * Maps to:
+ *   - Claude: `claude --dangerously-skip-permissions -p PROMPT` in tmux
+ *   - Codex: `codex exec --json PROMPT` with optional `--sandbox` flag
+ *   - Codex app-server: `thread/start` JSON-RPC method
+ *
+ * Distinct from AgenticSessionInteractive because there's no human in the
+ * loop — all permissions are either pre-granted or auto-approved by the
+ * adapter (with the StopGateInterceptor primitive making the decisions).
+ *
+ * Distinct from WarmSessionInbox because the session is single-prompt:
+ * the prompt arrives at start, the session runs, and ends. No mid-session
+ * message injection from an inbox.
+ */
+import type { CancellationOptions, ModelTier, ProviderSpecific, SessionHandle } from '../../types.js';
+import type { CanonicalEvent } from '../../events.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface AgenticSessionHeadless {
+    readonly capability: typeof CapabilityFlag.AgenticSessionHeadless;
+    /**
+     * Spawn a headless agent session.
+     *
+     * Returns immediately with a SessionHandle and an event stream. Caller
+     * consumes the event stream to observe the session's progress. The
+     * session terminates when:
+     *   - The agent emits a final response (most common)
+     *   - The caller aborts via `options.signal`
+     *   - A timeout from `options.timeoutMs` expires
+     *   - A control primitive (HardKill, Interrupt) is invoked on the handle
+     *   - The provider terminates for an external reason (quota, crash, etc.)
+     *
+     * In all cases, the event stream emits a `session-lifecycle` event with
+     * `lifecycleKind: 'ended'` as the final event before closing.
+     */
+    start(options: AgenticSessionHeadlessOptions): Promise<AgenticSessionHandle>;
+}
+export interface AgenticSessionHeadlessOptions extends CancellationOptions {
+    /** Initial prompt / instructions for the agent. */
+    prompt: string;
+    /** Model tier. */
+    model?: ModelTier;
+    /** Working directory for tools that read/write files. */
+    workingDirectory?: string;
+    /** Maximum session duration in minutes (separate from options.timeoutMs). */
+    maxDurationMinutes?: number;
+    /**
+     * Tool capability configuration (allowlists, sandbox modes, paths).
+     * Concrete shape is provider-defined; pass through capability primitives.
+     */
+    capabilities?: SessionCapabilityConfig;
+    /**
+     * Environment variables to inject into the session's tool subprocesses.
+     * Adapters MUST scrub sensitive variables (e.g. nested-session markers).
+     */
+    env?: Readonly<Record<string, string>>;
+    /** Optional system message prepended to the agent's instructions. */
+    system?: string;
+}
+/**
+ * Marker type for capability config. Each adapter knows how to interpret
+ * its own shape; the abstraction does not need to enumerate keys. Use the
+ * dedicated capability primitives (ToolAllowlist, PathAllowlist, etc.) to
+ * construct these in a portable way.
+ */
+export type SessionCapabilityConfig = Readonly<Record<string, unknown>>;
+export interface AgenticSessionHandle {
+    /** Opaque handle. Pass to other primitives (HardKill, Interrupt, etc.). */
+    readonly handle: SessionHandle;
+    /**
+     * Event stream for this session. Iterate to observe progress; the stream
+     * closes after a `session-lifecycle.ended` event is emitted.
+     *
+     * Implementations SHOULD support multiple consumers (tee the stream).
+     * If they don't, document the single-consumer constraint and throw on
+     * second iteration attempt.
+     */
+    readonly events: AsyncIterable<CanonicalEvent>;
+    /** Adapter-specific extension fields. */
+    readonly providerSpecific?: ProviderSpecific;
+}
+//# sourceMappingURL=agenticSessionHeadless.d.ts.map

package/dist/providers/primitives/transport/agenticSessionHeadless.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agenticSessionHeadless.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/transport/agenticSessionHeadless.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,SAAS,EACT,gBAAgB,EAChB,aAAa,EACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,sBAAsB,CAAC;IAElE;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC9E;AAED,MAAM,WAAW,6BAA8B,SAAQ,mBAAmB;IACxE,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,uBAAuB,CAAC;IACvC;;;OAGG;IACH,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvC,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAExE,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC/C,yCAAyC;IACzC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAC9C"}

package/dist/providers/primitives/transport/agenticSessionHeadless.js

@@ -0,0 +1,22 @@
+/**
+ * AgenticSessionHeadless — multi-turn agent session, tools enabled, no human.
+ *
+ * The workhorse primitive for autonomous instar jobs. Spawns a session that
+ * receives an initial prompt + capability grant, runs to completion (or until
+ * killed by control primitives), and streams events as it works.
+ *
+ * Maps to:
+ *   - Claude: `claude --dangerously-skip-permissions -p PROMPT` in tmux
+ *   - Codex: `codex exec --json PROMPT` with optional `--sandbox` flag
+ *   - Codex app-server: `thread/start` JSON-RPC method
+ *
+ * Distinct from AgenticSessionInteractive because there's no human in the
+ * loop — all permissions are either pre-granted or auto-approved by the
+ * adapter (with the StopGateInterceptor primitive making the decisions).
+ *
+ * Distinct from WarmSessionInbox because the session is single-prompt:
+ * the prompt arrives at start, the session runs, and ends. No mid-session
+ * message injection from an inbox.
+ */
+export {};
+//# sourceMappingURL=agenticSessionHeadless.js.map

package/dist/providers/primitives/transport/agenticSessionHeadless.js.map

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

package/dist/providers/primitives/transport/agenticSessionInteractive.d.ts

@@ -0,0 +1,72 @@
+/**
+ * AgenticSessionInteractive — multi-turn agent session, tools enabled,
+ * human at a TTY.
+ *
+ * Used for: setup wizards, conversational onboarding, debug sessions where
+ * the human is expected to type into the same terminal. Distinct from
+ * AgenticSessionHeadless because the TTY is owned by the user, not the
+ * abstraction.
+ *
+ * The most important difference: the abstraction does NOT control input
+ * after startup. The user types. The abstraction may observe (via events
+ * if the provider supports them) but cannot inject.
+ *
+ * Maps to:
+ *   - Claude: bare `claude` with `stdio: 'inherit'`
+ *   - Codex: bare `codex` with `stdio: 'inherit'`
+ *
+ * Why this is a distinct primitive: in the post-2026-06-15 billing world,
+ * interactive sessions draw from Anthropic's Max subscription rather than
+ * the Agent SDK credit pot. The routing policy uses the capability flag
+ * to choose between this and AgenticSessionHeadless based on quota state.
+ *
+ * Note: this primitive is for sessions where a USER is at the terminal.
+ * For programmatic "interactive-mode" usage (the interactive-pool strategy
+ * for subscription compatibility), use a `WarmSessionInbox` adapter that
+ * internally drives a `claude` REPL via tmux. The capability boundary is
+ * "human controls the TTY" vs. "instar drives a TTY-bound process."
+ */
+import type { CancellationOptions, ProviderSpecific, SessionHandle } from '../../types.js';
+import type { CanonicalEvent } from '../../events.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface AgenticSessionInteractive {
+    readonly capability: typeof CapabilityFlag.AgenticSessionInteractive;
+    /**
+     * Launch an interactive session attached to the current TTY.
+     *
+     * The current process's stdio is connected to the spawned agent. Returns
+     * a handle and event stream (events only populate if the provider
+     * supports out-of-band observability while a human owns the TTY — most
+     * don't, so events may be empty for the lifetime of the session).
+     */
+    launch(options: AgenticSessionInteractiveOptions): Promise<AgenticSessionInteractiveHandle>;
+}
+export interface AgenticSessionInteractiveOptions extends CancellationOptions {
+    /**
+     * Optional initial slash-command or prompt to pre-fill. E.g., a setup
+     * wizard might launch with `/setup-wizard` already populated.
+     */
+    initialInput?: string;
+    /** Working directory. */
+    workingDirectory?: string;
+    /** Environment variables to inject (adapter scrubs sensitive markers). */
+    env?: Readonly<Record<string, string>>;
+}
+export interface AgenticSessionInteractiveHandle {
+    readonly handle: SessionHandle;
+    /**
+     * Event stream — typically empty or sparse while the TTY is human-owned.
+     * Closes when the user exits the session.
+     */
+    readonly events: AsyncIterable<CanonicalEvent>;
+    /**
+     * Promise that resolves when the user closes the session. Use this
+     * instead of consuming `events` if you only need to await completion.
+     */
+    readonly waitForExit: Promise<{
+        exitCode: number;
+        durationMs: number;
+    }>;
+    readonly providerSpecific?: ProviderSpecific;
+}
+//# sourceMappingURL=agenticSessionInteractive.d.ts.map

package/dist/providers/primitives/transport/agenticSessionInteractive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agenticSessionInteractive.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/transport/agenticSessionInteractive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,yBAAyB,CAAC;IAErE;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,EAAE,gCAAgC,GAAG,OAAO,CAAC,+BAA+B,CAAC,CAAC;CAC7F;AAED,MAAM,WAAW,gCAAiC,SAAQ,mBAAmB;IAC3E;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yBAAyB;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAC9C"}

package/dist/providers/primitives/transport/agenticSessionInteractive.js

@@ -0,0 +1,30 @@
+/**
+ * AgenticSessionInteractive — multi-turn agent session, tools enabled,
+ * human at a TTY.
+ *
+ * Used for: setup wizards, conversational onboarding, debug sessions where
+ * the human is expected to type into the same terminal. Distinct from
+ * AgenticSessionHeadless because the TTY is owned by the user, not the
+ * abstraction.
+ *
+ * The most important difference: the abstraction does NOT control input
+ * after startup. The user types. The abstraction may observe (via events
+ * if the provider supports them) but cannot inject.
+ *
+ * Maps to:
+ *   - Claude: bare `claude` with `stdio: 'inherit'`
+ *   - Codex: bare `codex` with `stdio: 'inherit'`
+ *
+ * Why this is a distinct primitive: in the post-2026-06-15 billing world,
+ * interactive sessions draw from Anthropic's Max subscription rather than
+ * the Agent SDK credit pot. The routing policy uses the capability flag
+ * to choose between this and AgenticSessionHeadless based on quota state.
+ *
+ * Note: this primitive is for sessions where a USER is at the terminal.
+ * For programmatic "interactive-mode" usage (the interactive-pool strategy
+ * for subscription compatibility), use a `WarmSessionInbox` adapter that
+ * internally drives a `claude` REPL via tmux. The capability boundary is
+ * "human controls the TTY" vs. "instar drives a TTY-bound process."
+ */
+export {};
+//# sourceMappingURL=agenticSessionInteractive.js.map

package/dist/providers/primitives/transport/agenticSessionInteractive.js.map

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

package/dist/providers/primitives/transport/agenticSessionRpc.d.ts

@@ -0,0 +1,83 @@
+/**
+ * AgenticSessionRpc — JSON-RPC driven agent session.
+ *
+ * A session controlled via a structured JSON-RPC channel rather than via
+ * stdin/stdout/tmux. The adapter exposes a narrow surface (start, steer,
+ * interrupt, observe) regardless of how rich the underlying RPC is.
+ *
+ * Used for:
+ *   - A2A protocol (Instar's existing A2A gateway)
+ *   - Codex app-server `thread/start` + `turn/start` JSON-RPC
+ *   - Future: any "structured remote control" pattern
+ *
+ * Maps to:
+ *   - Codex: `codex remote-control` (stdio JSON-RPC); the canonical
+ *     mapping. Codex exposes a vastly richer surface (fs/*, command/*,
+ *     plugin/*, config/*) — that lives behind the optional
+ *     `AppServerControlPlane` capability (Phase 2 step 7), not here.
+ *   - Anthropic: no native RPC; adapter wraps an AgenticSession-headless
+ *     and presents an RPC-shaped facade for callers that need consistency.
+ *
+ * Why distinct from AgenticSession-headless: the input model is different.
+ * Headless takes a prompt at start and runs to completion. RPC takes a
+ * series of `turn/start` calls and can be steered mid-task with `turn/steer`.
+ * The lifecycle is "always-on" until explicitly closed, like WarmSessionInbox,
+ * but the channel is structured RPC rather than file-based messages.
+ */
+import type { CancellationOptions, ProviderSpecific, SessionHandle } from '../../types.js';
+import type { CanonicalEvent } from '../../events.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface AgenticSessionRpc {
+    readonly capability: typeof CapabilityFlag.AgenticSessionRpc;
+    /** Open an RPC-driven session. */
+    start(options: AgenticSessionRpcOptions): Promise<AgenticSessionRpcHandle>;
+    /**
+     * Start a new turn within an existing session. The promise resolves when
+     * the turn has been accepted (not when it completes — observe events for
+     * completion).
+     */
+    startTurn(handle: SessionHandle, turn: TurnRequest, options?: CancellationOptions): Promise<{
+        turnId: string;
+    }>;
+    /**
+     * Steer an in-flight turn with additional input. Adapters that don't
+     * support mid-turn steering throw UnsupportedCapabilityError.
+     */
+    steerTurn(handle: SessionHandle, turnId: string, input: string, options?: CancellationOptions): Promise<void>;
+    /** Cancel an in-flight turn (without closing the session). */
+    interruptTurn(handle: SessionHandle, turnId: string, options?: CancellationOptions): Promise<void>;
+    /** Close the session and release its resources. */
+    close(handle: SessionHandle, options?: CancellationOptions): Promise<void>;
+}
+export interface AgenticSessionRpcOptions extends CancellationOptions {
+    /** Transport for the RPC channel. */
+    transport: 'stdio' | 'unix-socket' | 'tcp' | 'websocket';
+    /** Transport-specific endpoint (socket path, host:port, ws URL). */
+    endpoint?: string;
+    /** Optional model tier (provider may override per turn). */
+    model?: import('../../types.js').ModelTier;
+    /** Working directory. */
+    workingDirectory?: string;
+    /** Optional initial capabilities/configuration for the session. */
+    initialConfig?: Readonly<Record<string, unknown>>;
+}
+export interface TurnRequest {
+    /** Prompt or message text for this turn. */
+    prompt: string;
+    /** Optional per-turn metadata (correlation id, task name, etc.). */
+    metadata?: Readonly<Record<string, unknown>>;
+}
+export interface AgenticSessionRpcHandle {
+    readonly handle: SessionHandle;
+    /** Event stream for the session's lifetime. */
+    readonly events: AsyncIterable<CanonicalEvent>;
+    /**
+     * Whether the underlying provider exposes the rich app-server control
+     * plane (fs/command/plugin/config RPC methods). If true, the adapter
+     * also implements the optional `AppServerControlPlane` capability. If
+     * false, this is just a narrow RPC wrapper around an agent session.
+     */
+    readonly hasControlPlane: boolean;
+    readonly providerSpecific?: ProviderSpecific;
+}
+//# sourceMappingURL=agenticSessionRpc.d.ts.map

package/dist/providers/primitives/transport/agenticSessionRpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agenticSessionRpc.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/transport/agenticSessionRpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,iBAAiB,CAAC;IAE7D,kCAAkC;IAClC,KAAK,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAE3E;;;;OAIG;IACH,SAAS,CACP,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE/B;;;OAGG;IACH,SAAS,CACP,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,8DAA8D;IAC9D,aAAa,CACX,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,mDAAmD;IACnD,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E;AAED,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE,qCAAqC;IACrC,SAAS,EAAE,OAAO,GAAG,aAAa,GAAG,KAAK,GAAG,WAAW,CAAC;IACzD,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,gBAAgB,EAAE,SAAS,CAAC;IAC3C,yBAAyB;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC/C;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAC9C"}

package/dist/providers/primitives/transport/agenticSessionRpc.js

@@ -0,0 +1,28 @@
+/**
+ * AgenticSessionRpc — JSON-RPC driven agent session.
+ *
+ * A session controlled via a structured JSON-RPC channel rather than via
+ * stdin/stdout/tmux. The adapter exposes a narrow surface (start, steer,
+ * interrupt, observe) regardless of how rich the underlying RPC is.
+ *
+ * Used for:
+ *   - A2A protocol (Instar's existing A2A gateway)
+ *   - Codex app-server `thread/start` + `turn/start` JSON-RPC
+ *   - Future: any "structured remote control" pattern
+ *
+ * Maps to:
+ *   - Codex: `codex remote-control` (stdio JSON-RPC); the canonical
+ *     mapping. Codex exposes a vastly richer surface (fs/*, command/*,
+ *     plugin/*, config/*) — that lives behind the optional
+ *     `AppServerControlPlane` capability (Phase 2 step 7), not here.
+ *   - Anthropic: no native RPC; adapter wraps an AgenticSession-headless
+ *     and presents an RPC-shaped facade for callers that need consistency.
+ *
+ * Why distinct from AgenticSession-headless: the input model is different.
+ * Headless takes a prompt at start and runs to completion. RPC takes a
+ * series of `turn/start` calls and can be steered mid-task with `turn/steer`.
+ * The lifecycle is "always-on" until explicitly closed, like WarmSessionInbox,
+ * but the channel is structured RPC rather than file-based messages.
+ */
+export {};
+//# sourceMappingURL=agenticSessionRpc.js.map

package/dist/providers/primitives/transport/agenticSessionRpc.js.map

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

package/dist/providers/primitives/transport/oneShotCompletion.d.ts

@@ -0,0 +1,56 @@
+/**
+ * OneShotCompletion — single prompt → single text response, no tools.
+ *
+ * The lightest-weight primitive. Used for: classification, routing decisions,
+ * scoring, summarization, validation checks. The IntelligenceProvider
+ * interface in src/core/types.ts will be re-expressed in terms of this
+ * primitive during Phase 3 refactoring.
+ *
+ * Maps to:
+ *   - Claude headless: `claude -p PROMPT --max-turns 1 --output-format text`
+ *   - Claude interactive: REPL session, inject prompt, capture response
+ *   - OpenAI Codex: `codex exec PROMPT --output-last-message <path>`
+ *   - OpenAI Responses API directly (no agent loop)
+ *   - Local Ollama: HTTP POST /api/generate
+ *
+ * What this primitive does NOT do:
+ *   - Multi-turn conversation (use AgenticSession* variants)
+ *   - Tool calls (use AgenticSession* variants)
+ *   - File system access (use AgenticSession* variants)
+ *   - Streaming output (use AgenticSession-headless and consume events)
+ *
+ * Implementations SHOULD return as quickly as the provider allows. Callers
+ * SHOULD use a low maxTokens budget when the response is expected to be short.
+ */
+import type { CancellationOptions, ModelTier, ProviderSpecific, UsageReport } from '../../types.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface OneShotCompletion {
+    readonly capability: typeof CapabilityFlag.OneShotCompletion;
+    /**
+     * Send a single prompt, get a single text response.
+     *
+     * Implementations MUST throw a ProviderError subclass on failure. They
+     * MUST honor `options.signal` for cancellation. They SHOULD honor
+     * `options.timeoutMs` and throw TimeoutError when exceeded.
+     */
+    evaluate(prompt: string, options?: OneShotCompletionOptions): Promise<OneShotCompletionResult>;
+}
+export interface OneShotCompletionOptions extends CancellationOptions {
+    /** Model tier preference. Adapter resolves to a concrete model. */
+    model?: ModelTier;
+    /** Maximum tokens in the response. */
+    maxTokens?: number;
+    /** Sampling temperature, 0-1. Lower = more deterministic. */
+    temperature?: number;
+    /** Optional system message / instructions prepended to the prompt. */
+    system?: string;
+}
+export interface OneShotCompletionResult {
+    /** The model's text response, trimmed. */
+    text: string;
+    /** Usage data if the provider reports it. May be null even when authoritative. */
+    usage: UsageReport | null;
+    /** Adapter-specific extension fields. */
+    providerSpecific?: ProviderSpecific;
+}
+//# sourceMappingURL=oneShotCompletion.d.ts.map

package/dist/providers/primitives/transport/oneShotCompletion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oneShotCompletion.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/transport/oneShotCompletion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,iBAAiB,CAAC;IAE7D;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAChG;AAED,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE,mEAAmE;IACnE,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,yCAAyC;IACzC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC"}

package/dist/providers/primitives/transport/oneShotCompletion.js

@@ -0,0 +1,26 @@
+/**
+ * OneShotCompletion — single prompt → single text response, no tools.
+ *
+ * The lightest-weight primitive. Used for: classification, routing decisions,
+ * scoring, summarization, validation checks. The IntelligenceProvider
+ * interface in src/core/types.ts will be re-expressed in terms of this
+ * primitive during Phase 3 refactoring.
+ *
+ * Maps to:
+ *   - Claude headless: `claude -p PROMPT --max-turns 1 --output-format text`
+ *   - Claude interactive: REPL session, inject prompt, capture response
+ *   - OpenAI Codex: `codex exec PROMPT --output-last-message <path>`
+ *   - OpenAI Responses API directly (no agent loop)
+ *   - Local Ollama: HTTP POST /api/generate
+ *
+ * What this primitive does NOT do:
+ *   - Multi-turn conversation (use AgenticSession* variants)
+ *   - Tool calls (use AgenticSession* variants)
+ *   - File system access (use AgenticSession* variants)
+ *   - Streaming output (use AgenticSession-headless and consume events)
+ *
+ * Implementations SHOULD return as quickly as the provider allows. Callers
+ * SHOULD use a low maxTokens budget when the response is expected to be short.
+ */
+export {};
+//# sourceMappingURL=oneShotCompletion.js.map

package/dist/providers/primitives/transport/oneShotCompletion.js.map

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

package/dist/providers/primitives/transport/structuredOneShot.d.ts

@@ -0,0 +1,70 @@
+/**
+ * StructuredOneShot — single prompt → schema-validated JSON response.
+ *
+ * Distinct from OneShotCompletion because schema-shape affects which
+ * providers can satisfy it. Some providers (OpenAI) have native
+ * `response_format: json_schema` enforcement; others (Anthropic via CLI)
+ * require prompt-engineering the JSON and validating caller-side.
+ *
+ * Used for: stall-triage diagnosis (returns TriageDiagnosis JSON), content
+ * classification with confidence scores, structured extraction.
+ *
+ * Maps to:
+ *   - Claude: prompt-engineered JSON via `claude -p`, caller validates
+ *   - OpenAI Responses API: `response_format: { type: 'json_schema', schema }`
+ *   - Codex: `codex exec` + prompt-side JSON request, validate caller-side
+ *
+ * The interface accepts a generic schema-validation function so callers
+ * can use Zod, JSON Schema, ajv, or hand-rolled validators. Adapters MAY
+ * use the schema to drive provider-side enforcement when supported, but
+ * MUST still call the caller's validator on the result for consistency.
+ */
+import type { CancellationOptions, ModelTier, ProviderSpecific, UsageReport } from '../../types.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface StructuredOneShot {
+    readonly capability: typeof CapabilityFlag.StructuredOneShot;
+    /**
+     * Send a prompt and get a typed, validated response.
+     *
+     * The caller provides a `validate` function that returns `{ ok: true, value }`
+     * or `{ ok: false, error }`. Implementations call the validator; on
+     * `ok: false` the implementation MAY retry up to `options.maxRetries` (default 1)
+     * with a follow-up "your response failed validation; here's why" prompt before
+     * giving up and throwing.
+     *
+     * @typeParam T - The validated response shape.
+     */
+    evaluate<T>(prompt: string, validate: SchemaValidator<T>, options?: StructuredOneShotOptions): Promise<StructuredOneShotResult<T>>;
+}
+export type SchemaValidator<T> = (raw: string) => SchemaValidationResult<T>;
+export type SchemaValidationResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+export interface StructuredOneShotOptions extends CancellationOptions {
+    model?: ModelTier;
+    maxTokens?: number;
+    temperature?: number;
+    system?: string;
+    /** Max number of retry attempts on validation failure. Default: 1. */
+    maxRetries?: number;
+    /**
+     * Optional JSON Schema for provider-side enforcement. Adapters that
+     * support native structured output (OpenAI) MAY use this. Adapters
+     * that don't ignore it. Schema MUST still match what `validate` accepts.
+     */
+    jsonSchema?: Readonly<Record<string, unknown>>;
+}
+export interface StructuredOneShotResult<T> {
+    value: T;
+    /** Raw text the model produced (useful for debugging validation issues). */
+    raw: string;
+    /** How many validation attempts were needed (1 = first try succeeded). */
+    attempts: number;
+    usage: UsageReport | null;
+    providerSpecific?: ProviderSpecific;
+}
+//# sourceMappingURL=structuredOneShot.d.ts.map

package/dist/providers/primitives/transport/structuredOneShot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuredOneShot.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/transport/structuredOneShot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,iBAAiB,CAAC;IAE7D;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,CAAC,EACR,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,EAC5B,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC;CACxC;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,KAAK,sBAAsB,CAAC,CAAC,CAAC,CAAC;AAE5E,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAChC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,KAAK,EAAE,CAAC,CAAC;IACT,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC"}

package/dist/providers/primitives/transport/structuredOneShot.js

@@ -0,0 +1,23 @@
+/**
+ * StructuredOneShot — single prompt → schema-validated JSON response.
+ *
+ * Distinct from OneShotCompletion because schema-shape affects which
+ * providers can satisfy it. Some providers (OpenAI) have native
+ * `response_format: json_schema` enforcement; others (Anthropic via CLI)
+ * require prompt-engineering the JSON and validating caller-side.
+ *
+ * Used for: stall-triage diagnosis (returns TriageDiagnosis JSON), content
+ * classification with confidence scores, structured extraction.
+ *
+ * Maps to:
+ *   - Claude: prompt-engineered JSON via `claude -p`, caller validates
+ *   - OpenAI Responses API: `response_format: { type: 'json_schema', schema }`
+ *   - Codex: `codex exec` + prompt-side JSON request, validate caller-side
+ *
+ * The interface accepts a generic schema-validation function so callers
+ * can use Zod, JSON Schema, ajv, or hand-rolled validators. Adapters MAY
+ * use the schema to drive provider-side enforcement when supported, but
+ * MUST still call the caller's validator on the result for consistency.
+ */
+export {};
+//# sourceMappingURL=structuredOneShot.js.map

package/dist/providers/primitives/transport/structuredOneShot.js.map

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

package/dist/providers/primitives/transport/warmSessionInbox.d.ts

@@ -0,0 +1,94 @@
+/**
+ * WarmSessionInbox — long-lived agent session, file-based message inbox.
+ *
+ * A persistent agent process that receives messages via a file-system
+ * inbox and processes them sequentially. The session lives across many
+ * messages, retaining context and warm state.
+ *
+ * Used for:
+ *   - Threadline's ListenerSessionManager (long-lived listener for
+ *     incoming agent messages)
+ *   - Interactive-pool fallback path (Phase 3b) — N long-lived `claude`
+ *     REPLs in tmux, work routed through them to draw from subscription
+ *     rather than Agent SDK credit pot
+ *   - Future: any "always-on agent" pattern
+ *
+ * Maps to:
+ *   - Claude: long-lived REPL in tmux + tmux send-keys for prompt injection
+ *   - Codex: long-lived `codex remote-control` + `turn/steer` JSON-RPC
+ *
+ * Inbox file format is provider-agnostic (JSONL with `{message, fromAgent,
+ * timestamp}` entries). The adapter polls the inbox or uses a wake signal
+ * (socket) to detect new messages.
+ *
+ * Lifecycle:
+ *   1. start(options) → spawn the session, return handle
+ *   2. send(handle, message) → append to inbox, agent picks it up
+ *   3. session emits events as it processes
+ *   4. session may be retired when capacity threshold reached
+ *      (compaction risk, message count limit, idle timeout)
+ *   5. retire(handle) → graceful shutdown
+ */
+import type { CancellationOptions, ModelTier, ProviderSpecific, SessionHandle } from '../../types.js';
+import type { CanonicalEvent } from '../../events.js';
+import { CapabilityFlag } from '../../capabilities.js';
+export interface WarmSessionInbox {
+    readonly capability: typeof CapabilityFlag.WarmSessionInbox;
+    /** Spawn a warm session and return its handle. */
+    start(options: WarmSessionInboxOptions): Promise<WarmSessionInboxHandle>;
+    /**
+     * Deliver a message to the session's inbox. Returns when the message has
+     * been written to the inbox file (not when it's been processed). To
+     * observe the agent's response, consume the events stream and filter for
+     * events tagged with the `correlationId` returned here.
+     */
+    send(handle: SessionHandle, message: WarmInboxMessage, options?: CancellationOptions): Promise<{
+        correlationId: string;
+        deliveredAt: string;
+    }>;
+    /**
+     * Gracefully shut down a warm session. Drains the inbox, lets the agent
+     * finish in-flight processing, then closes. Use HardKill for forced
+     * termination.
+     */
+    retire(handle: SessionHandle, options?: CancellationOptions): Promise<void>;
+}
+export interface WarmSessionInboxOptions extends CancellationOptions {
+    /** Inbox file path. Adapter creates if absent. */
+    inboxPath: string;
+    /** Working directory for the session. */
+    workingDirectory?: string;
+    /** Model tier. */
+    model?: ModelTier;
+    /** Optional initial system prompt for the warm session. */
+    system?: string;
+    /** Environment variables to inject. */
+    env?: Readonly<Record<string, string>>;
+    /**
+     * Maximum number of messages this session should process before retiring.
+     * Adapter MAY auto-retire and respawn when reached. Useful for bounding
+     * context-window growth.
+     */
+    maxMessagesBeforeRetire?: number;
+    /** Idle timeout before auto-retire (milliseconds). */
+    idleRetireMs?: number;
+}
+export interface WarmInboxMessage {
+    /** Message content. */
+    content: string;
+    /** Optional sender identity for the agent's context. */
+    fromAgent?: string;
+    /** Optional structured metadata. */
+    metadata?: Readonly<Record<string, unknown>>;
+}
+export interface WarmSessionInboxHandle {
+    readonly handle: SessionHandle;
+    /** Event stream covering all messages processed by this session. */
+    readonly events: AsyncIterable<CanonicalEvent>;
+    /** Current message count, for capacity awareness. */
+    readonly messageCount: () => number;
+    /** Is the session ready to accept messages? */
+    readonly isReady: () => boolean;
+    readonly providerSpecific?: ProviderSpecific;
+}
+//# sourceMappingURL=warmSessionInbox.d.ts.map

package/dist/providers/primitives/transport/warmSessionInbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warmSessionInbox.d.ts","sourceRoot":"","sources":["../../../../src/providers/primitives/transport/warmSessionInbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,SAAS,EACT,gBAAgB,EAChB,aAAa,EACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,cAAc,CAAC,gBAAgB,CAAC;IAE5D,kDAAkD;IAClD,KAAK,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAEzE;;;;;OAKG;IACH,IAAI,CACF,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EACzB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE3D;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kBAAkB;IAClB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvC;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC/C,qDAAqD;IACrD,QAAQ,CAAC,YAAY,EAAE,MAAM,MAAM,CAAC;IACpC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAC9C"}