@rynx-ai/runtime 0.1.0 → 0.1.10-beta.2

package/dist/runner/child.js

@@ -7,15 +7,18 @@ export class RunnerSession {
     /** Live terminals hosted by this session, and per-attach client handles. */
     terminals = new TerminalRegistry();
     attachments = new Map();
+    /** Opens are async; a close received before attach resolves tombstones the id. */
+    pendingTerminalOpens = new Set();
+    cancelledTerminalOpens = new Set();
     /** Session ids with a live codex forwarder started here (stopped on shutdown). */
     liveIds = new Set();
+    shuttingDown = false;
     constructor({ transport, executor, onShutdown }) {
         this.transport = transport;
         this.executor = executor;
         this.onShutdown =
             onShutdown ??
                 (() => {
-                    this.terminals.closeAll();
                     transport.close();
                 });
         this.transport.onMessage((msg) => this.handle(msg));
@@ -27,7 +30,20 @@ export class RunnerSession {
                 void this.runCap(msg.capId, msg.name, msg.args);
                 return;
             case "term.open":
-                void this.openTerminal(msg);
+                if (this.pendingTerminalOpens.has(msg.attachId) || this.attachments.has(msg.attachId)) {
+                    this.transport.send({
+                        t: "term.error",
+                        attachId: msg.attachId,
+                        code: "terminal_open_failed",
+                        message: "terminal attachment id is already active",
+                    });
+                    return;
+                }
+                this.pendingTerminalOpens.add(msg.attachId);
+                void this.openTerminal(msg).finally(() => {
+                    this.pendingTerminalOpens.delete(msg.attachId);
+                    this.cancelledTerminalOpens.delete(msg.attachId);
+                });
                 return;
             case "term.input":
                 this.attachments.get(msg.attachId)?.write(Buffer.from(msg.dataB64, "base64").toString("utf8"));
@@ -36,14 +52,16 @@ export class RunnerSession {
                 this.attachments.get(msg.attachId)?.resize(msg.cols, msg.rows);
                 return;
             case "term.close": {
+                if (this.pendingTerminalOpens.has(msg.attachId)) {
+                    this.cancelledTerminalOpens.add(msg.attachId);
+                }
                 const attachment = this.attachments.get(msg.attachId);
                 this.attachments.delete(msg.attachId);
                 attachment?.kill();
                 return;
             }
-            case "approval.resolve": {
-                const provider = this.executor;
-                void provider.resolveApproval?.(msg.localThreadId, msg.approvalId, msg.decision);
+            case "interaction.resolve": {
+                void this.resolveInteraction(msg);
                 return;
             }
             case "live.ensure":
@@ -56,15 +74,31 @@ export class RunnerSession {
                 void this.interruptLive(msg);
                 return;
             case "shutdown":
-                this.stopLive();
-                this.terminals.closeAll();
-                this.onShutdown();
+                this.shutdown();
                 return;
         }
     }
     get liveProvider() {
         return this.executor;
     }
+    async resolveInteraction(msg) {
+        let result;
+        try {
+            result = await this.liveProvider.resolveInteraction?.(msg.localThreadId, msg.interactionId, msg.resolution) ?? { disposition: "not_found" };
+        }
+        catch (error) {
+            result = {
+                disposition: "invalid",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        this.transport.send({
+            t: "interaction.resolved",
+            reqId: msg.reqId,
+            localThreadId: msg.localThreadId,
+            result,
+        });
+    }
     /** The mirror channel for a session: an `emit` that forwards every canonical
      *  event to the parent under the CURRENT session id (mutable), plus a `retarget`
      *  the host calls on a `/clear`·`/fork` rotation — it re-points the mirror to the
@@ -94,20 +128,28 @@ export class RunnerSession {
      * launch the detached `codex --remote` TUI, which CREATES the codex thread. The
      * forwarder's connection sees the TUI's broadcast `thread/started`, binds, and
      * subscribes — so the TUI is usable immediately (a fresh `--remote` needs no
-     * rollout) and its turns mirror to chat (omnigent's model).
+     * rollout) and its turns mirror to chat (reference implementation's model).
      */
     async ensureLive(msg) {
         const provider = this.liveProvider;
         try {
             const { emit, retarget } = this.mirrorChannel(msg.localThreadId);
             const started = await provider.ensureLiveCodexSession?.(msg.localThreadId, emit, {
+                ...(msg.cwd ? { cwd: msg.cwd } : {}),
                 ...(msg.runtime ? { runtime: msg.runtime } : {}),
+                ...(msg.reasoningEffort ? { reasoningEffort: msg.reasoningEffort } : {}),
                 ...(msg.agentName ? { agentName: msg.agentName } : {}),
                 ...(msg.agentSpec ? { agentSpec: msg.agentSpec } : {}),
                 retargetMirror: retarget,
             });
             if (!started) {
-                this.transport.send({ t: "live.ready", reqId: msg.reqId, localThreadId: msg.localThreadId, ok: false });
+                this.transport.send({
+                    t: "live.ready",
+                    reqId: msg.reqId,
+                    localThreadId: msg.localThreadId,
+                    ok: false,
+                    error: "live provider did not start",
+                });
                 return;
             }
             this.liveIds.add(msg.localThreadId);
@@ -119,10 +161,18 @@ export class RunnerSession {
             if (!this.terminals.get(`${msg.localThreadId}-main`)?.isAlive()) {
                 await this.launchCodexPane(msg.localThreadId, msg.cols, msg.rows);
             }
-            const ready = provider.waitLiveReady
-                ? await provider.waitLiveReady(msg.localThreadId)
-                : true;
-            this.transport.send({ t: "live.ready", reqId: msg.reqId, localThreadId: msg.localThreadId, ok: ready });
+            const ready = msg.waitForReady === false
+                ? true
+                : provider.waitLiveReady
+                    ? await provider.waitLiveReady(msg.localThreadId)
+                    : true;
+            this.transport.send({
+                t: "live.ready",
+                reqId: msg.reqId,
+                localThreadId: msg.localThreadId,
+                ok: ready,
+                ...(ready ? {} : { error: "live session was not ready before timeout" }),
+            });
         }
         catch (error) {
             this.transport.send({
@@ -137,7 +187,8 @@ export class RunnerSession {
     async inject(msg) {
         const provider = this.liveProvider;
         try {
-            const outcome = (await provider.injectMessage?.(msg.localThreadId, msg.text)) ?? "notLive";
+            const input = msg.input ?? msg.text;
+            const outcome = (await provider.injectMessage?.(msg.localThreadId, input)) ?? "notLive";
             this.transport.send({ t: "injected", reqId: msg.reqId, localThreadId: msg.localThreadId, outcome });
         }
         catch (error) {
@@ -186,13 +237,27 @@ export class RunnerSession {
         this.liveProvider.attachTerminalInjector?.(localThreadId, term);
     }
     stopLive() {
-        for (const id of this.liveIds)
-            this.liveProvider.stopLiveCodexSession?.(id);
+        for (const id of this.liveIds) {
+            this.liveProvider.stopLiveCodexSession?.(id, {
+                deferClaudeInteractionCleanup: true,
+            });
+        }
         this.liveIds.clear();
     }
+    /** Stop event forwarding, kill native terminals/hooks, then synchronously
+     * scrub provider handoff files before the child process is allowed to exit. */
+    shutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        this.stopLive();
+        this.terminals.closeAll();
+        this.liveProvider.finalizeStoppedLiveSessions?.();
+        this.onShutdown();
+    }
     async openTerminal(msg) {
         try {
-            // codex/claude-native session (no explicit command): DUMB ATTACH — omnigent's
+            // codex/claude-native session (no explicit command): DUMB ATTACH — reference implementation's
             // reattach (codex_native.py:905-942, `app_server=None`). A tab switch ONLY
             // attaches an already-live pane; it NEVER ensures the forwarder or relaunches a
             // dead pane. Creation/relaunch happens on message-send (`live.ensure`) or an
@@ -202,7 +267,12 @@ export class RunnerSession {
             if (!msg.command && msg.localThreadId) {
                 const existing = this.terminals.get(msg.terminalId);
                 if (!existing || !existing.isAlive()) {
-                    this.transport.send({ t: "term.error", attachId: msg.attachId, message: "terminal not live" });
+                    this.transport.send({
+                        t: "term.error",
+                        attachId: msg.attachId,
+                        code: "terminal_not_live",
+                        message: "terminal not live",
+                    });
                     return;
                 }
                 await this.attachExisting(msg);
@@ -222,6 +292,7 @@ export class RunnerSession {
             this.transport.send({
                 t: "term.error",
                 attachId: msg.attachId,
+                code: "terminal_open_failed",
                 message: error instanceof Error ? error.message : String(error),
             });
         }
@@ -232,6 +303,16 @@ export class RunnerSession {
             cols: msg.cols,
             rows: msg.rows,
         });
+        if (this.cancelledTerminalOpens.has(msg.attachId)) {
+            attachment.kill();
+            this.transport.send({
+                t: "term.error",
+                attachId: msg.attachId,
+                code: "terminal_open_failed",
+                message: "terminal attachment was cancelled while opening",
+            });
+            return;
+        }
         this.attachments.set(msg.attachId, attachment);
         attachment.onData((chunk) => this.transport.send({
             t: "term.data",

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 RuntimeUserInput, 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,23 @@ 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;
+    /** Max wait for a setup-pane launch acknowledgement. */
+    liveStartTimeoutMs?: number;
+    /** Max wait for a Provider-native thread to become ready. */
+    liveReadyTimeoutMs?: 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 +104,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 +118,28 @@ 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 readonly liveStartTimeoutMs;
+    private readonly liveReadyTimeoutMs;
+    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 +149,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,28 +178,39 @@ export declare class RunnerManager implements AgentCapabilities {
         cols?: number;
         rows?: number;
         runtime?: AgentRuntimeId;
+        reasoningEffort?: ReasoningEffort;
         agentName?: string;
         agentSpec?: AgentSpec;
     }): Promise<boolean>;
+    /** Start the Provider pane without waiting for login/onboarding to create a
+     * native thread. This is the setup-terminal gate; callers may attach as soon
+     * as it resolves, while normal message delivery still uses ensureLiveSession. */
+    startLiveSession(localThreadId: string, opts?: {
+        cwd?: string;
+        cols?: number;
+        rows?: number;
+        runtime?: AgentRuntimeId;
+        reasoningEffort?: ReasoningEffort;
+        agentName?: string;
+        agentSpec?: AgentSpec;
+    }): Promise<boolean>;
+    private requestLiveSession;
+    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).
      */
-    injectMessage(localThreadId: string, text: string): Promise<InjectOutcome>;
+    injectMessage(localThreadId: string, input: RuntimeUserInput | string): Promise<InjectOutcome>;
     /**
      * Interrupt a session's active live turn — the web Stop button (codex
      * `turn/interrupt`, claude Escape). Best-effort: resolves false with NO spawn
      * 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 +226,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 +237,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;
 }