@rynx-ai/runtime 0.1.0 → 0.1.9

package/dist/runner/manager.d.ts

@@ -16,9 +16,25 @@
  * channel.
  */
 import { spawn as nodeSpawn } from "node:child_process";
-import { type AgentCapabilities, type AgentRuntimeId, type AgentSpec, type AppConfig, type CapabilityResult, type ModelListResponse, type SessionEvent, type ThreadGoal } from "@rynx-ai/core";
+import { type AgentCapabilities, type AgentRuntimeId, type AgentSpec, type AppConfig, type CapabilityResult, type ModelListResponse, type ReasoningEffort, type SessionInteractionResolution, type SessionEvent, type ThreadGoal } from "@rynx-ai/core";
 import { type CodexSessionStore } from "../host.js";
-import { type InjectOutcome, type TerminalRole } from "./protocol.js";
+import type { ResolveInteractionResult } from "../interactions.js";
+import { type InjectOutcome, type TerminalOpenErrorCode, type TerminalRole } from "./protocol.js";
+/** Runtime-local context attached to one Session runner process. The provider is
+ * intentionally generic: package-specific resources stay in the composition
+ * root that implements this port. */
+export interface RunnerSessionContext {
+    /** Extra environment for the runner child. Validated and copied at spawn. */
+    readonly childEnv: Readonly<Record<string, string>>;
+    /** Rebind resources before a child-published Session rotation becomes visible. */
+    rotate(newSessionId: string): void;
+    /** Release the context. RunnerManager calls this exactly once. */
+    close(): void;
+}
+/** Optional synchronous factory for per-Session runner context. */
+export interface RunnerSessionContextProvider {
+    open(sessionId: string): RunnerSessionContext;
+}
 export interface RunnerManagerOptions {
     config: AppConfig;
     /** Shared session store (used by the backend-free status probe). */
@@ -29,12 +45,19 @@ export interface RunnerManagerOptions {
     idleTtlMs?: number;
     /** Background reap sweep interval (ms); `0` disables the timer (tests). */
     reapIntervalMs?: number;
+    /** Grace period between SIGTERM and SIGKILL during runner shutdown. */
+    shutdownGraceMs?: number;
+    /** Final bounded wait for child exit after SIGKILL. */
+    shutdownKillGraceMs?: number;
     /** Injected for tests. */
     spawn?: typeof nodeSpawn;
     now?: () => number;
     /** Extra env merged into every spawned runner child — e.g. the control-plane
      *  URL + token so a claude-native PermissionRequest hook can POST back. */
     childEnv?: Record<string, string>;
+    /** Optional lifecycle context for Session runners. The shared `__cap__`
+     * runner never opens one. */
+    sessionContextProvider?: RunnerSessionContextProvider;
 }
 /** A session rotation reported by a runner child (claude `/clear`·`/fork`): the
  *  new session `to` is now aliased to `from`'s runner; carries meta to carry over. */
@@ -77,6 +100,13 @@ export interface ParentTerminal {
     resize(cols: number, rows: number): void;
     close(): void;
 }
+/** A typed attach failure so transport adapters can distinguish an expected
+ * absent pane from an infrastructure failure without matching error strings. */
+export declare class TerminalOpenError extends Error {
+    readonly code: TerminalOpenErrorCode;
+    readonly name = "TerminalOpenError";
+    constructor(message: string, code: TerminalOpenErrorCode);
+}
 export declare class RunnerManager implements AgentCapabilities {
     private readonly config;
     private readonly sessionStore;
@@ -84,16 +114,26 @@ export declare class RunnerManager implements AgentCapabilities {
     private readonly idleTtlMs;
     private readonly spawn;
     private readonly childEnv;
+    private readonly sessionContextProvider;
     private readonly now;
     private readonly defaultRuntime;
     private readonly handles;
+    /** Every spawned child that has not exited (or failed to spawn), including
+     *  handles already removed from routing by stopRunner/idle reap. */
+    private readonly childHandles;
     private readonly reapTimer;
+    private readonly shutdownGraceMs;
+    private readonly shutdownKillGraceMs;
+    private stopping;
+    private stopPromise;
     /** Sink for mirrored {@link SessionEvent}s from every session's forwarder. */
     private mirrorListener;
     /** Sink for session rotations (claude `/clear`·`/fork`) — server records meta. */
     private rotateListener;
     /** Session keys with a live codex forwarder — never reaped while present. */
     private readonly liveSessionKeys;
+    /** Last live-start error per local session, surfaced by the control API. */
+    private readonly liveErrors;
     constructor(opts: RunnerManagerOptions);
     /**
      * Open a live terminal on the session's runner child (spawning it if needed).
@@ -103,6 +143,15 @@ export declare class RunnerManager implements AgentCapabilities {
      * bridge calls it directly.
      */
     openTerminal(localThreadId: string, opts: OpenTerminalOptions): ParentTerminal;
+    /**
+     * Attach to a Session runner that is already live. Unlike {@link openTerminal},
+     * this never creates a child, including when liveness changes between lookup
+     * and attach.
+     */
+    openLiveTerminal(localThreadId: string, opts: OpenTerminalOptions): ParentTerminal;
+    private openTerminalOnHandle;
+    /** Whether this process already owns a live runner for the Session. Read-only; never spawns. */
+    hasLiveSession(localThreadId: string): boolean;
     /**
      * Register the sink for mirrored {@link SessionEvent}s produced by every
      * session's persistent codex forwarder (web- AND TUI-initiated turns). The
@@ -123,11 +172,13 @@ export declare class RunnerManager implements AgentCapabilities {
         cols?: number;
         rows?: number;
         runtime?: AgentRuntimeId;
+        reasoningEffort?: ReasoningEffort;
         agentName?: string;
         agentSpec?: AgentSpec;
     }): Promise<boolean>;
+    lastLiveSessionError(localThreadId: string): string | undefined;
     /**
-     * Inject a user turn into a session's live codex thread — omnigent's
+     * Inject a user turn into a session's live codex thread — reference implementation's
      * single-writer web send (`turn/start` / `turn/steer`); the forwarder mirrors
      * all output. Resolves true when the app-server accepted the turn, false when
      * the session has no live forwarder (caller falls back to the run path).
@@ -139,12 +190,8 @@ export declare class RunnerManager implements AgentCapabilities {
      * when the session has no live runner (nothing to interrupt).
      */
     interruptLiveSession(localThreadId: string): Promise<boolean>;
-    /**
-     * Deliver a user's interactive-approval decision to the session's runner
-     * child (Phase D). Best-effort: no-op if the runner isn't live (the pending
-     * approval would have died with it). The child routes it to its codex client.
-     */
-    resolveApproval(localThreadId: string, approvalId: string, decision: "acceptForSession" | "accept" | "decline" | "cancel"): void;
+    /** Resolve a native question/approval without ever spawning a new runner. */
+    resolveInteraction(localThreadId: string, interactionId: string, resolution: SessionInteractionResolution): Promise<ResolveInteractionResult>;
     listModels(runtime?: AgentRuntimeId): Promise<ModelListResponse | null>;
     getGoal(localThreadId: string): Promise<CapabilityResult<ThreadGoal | null>>;
     setGoal(localThreadId: string, objective: string): Promise<CapabilityResult>;
@@ -160,7 +207,7 @@ export declare class RunnerManager implements AgentCapabilities {
     }): Promise<import("../host.js").CodexRuntimeStatus>;
     /** Stop the runner bound to one session (if any), rejecting its in-flight work. */
     stopRunner(localThreadId: string): void;
-    /** Kill every runner. Call on server shutdown. */
+    /** Stop every runner and join all child exits. Idempotent across concurrent calls. */
     stop(): Promise<void>;
     /** Forward a capability to a runner child. Session-less caps (listModels/status)
      *  use the shared `CAP_KEY` child; per-thread caps pass the session's key so they
@@ -171,5 +218,7 @@ export declare class RunnerManager implements AgentCapabilities {
     private onChildMessage;
     /** Mark a handle dead and reject every pending run/cap with the exit reason. */
     private failHandle;
+    private terminateHandle;
     private reapIdle;
+    private openSessionContext;
 }