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

package/dist/runner/protocol.d.ts

@@ -6,7 +6,8 @@
  * (`live.ensure` / `inject` / `live.interrupt`) plus per-thread capabilities and
  * terminal attachment; the reply channels mirror each request's `reqId`.
  */
-import { AgentRuntimeError, type AgentRuntimeId, type AgentSpec, type SessionEvent } from "@rynx-ai/core";
+import { AgentRuntimeError, type AgentRuntimeId, type AgentSpec, type ReasoningEffort, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent } from "@rynx-ai/core";
+import type { ResolveInteractionResult } from "../interactions.js";
 /** A runtime error flattened for the wire; rebuilt parent-side as `AgentRuntimeError`. */
 export interface WireError {
     message: string;
@@ -18,14 +19,15 @@ export interface WireError {
 export type CapName = "getGoal" | "setGoal" | "clearGoal" | "forkSession";
 /** A live terminal role: `owner` is read-write, `read-only` a viewer. */
 export type TerminalRole = "owner" | "read-only";
-/** A codex approval decision the user returns for an interactive approval. */
-export type ApprovalDecisionWire = "acceptForSession" | "accept" | "decline" | "cancel";
+/** Stable reason for a terminal attach failure. `terminal_not_live` is an
+ * expected, retryable absence; `terminal_open_failed` is an infrastructure error. */
+export type TerminalOpenErrorCode = "terminal_not_live" | "terminal_open_failed";
 /** Outcome of an `inject`. `injected` = the app-server / tmux accepted the turn.
  *  `notLive` = no live forwarder for this session (caller may use the run path).
  *  `notReady` = live but not ready within the park window; `failed` = injection
  *  threw. For BOTH notReady and failed the caller reports an error and MUST NOT
  *  re-run the turn (re-running would double-write alongside the forwarder).
- *  Mirrors omnigent's "inject failure ⇒ response.failed, never re-run locally". */
+ *  Mirrors reference implementation's "inject failure ⇒ response.failed, never re-run locally". */
 export type InjectOutcome = "injected" | "notLive" | "notReady" | "failed";
 /** Parent → child. Terminal PTY bytes ride `term.input` base64-encoded so the
  *  NDJSON line framing stays intact (raw bytes contain newlines). */
@@ -60,10 +62,11 @@ export type ToChild = {
     t: "term.close";
     attachId: string;
 } | {
-    t: "approval.resolve";
+    t: "interaction.resolve";
+    reqId: string;
     localThreadId: string;
-    approvalId: string;
-    decision: ApprovalDecisionWire;
+    interactionId: string;
+    resolution: SessionInteractionResolution;
 }
 /** Eagerly bring up a session's live codex TUI + forwarder (codex-native), so
  *  its turns mirror to the bus regardless of whether the web has attached the
@@ -80,6 +83,8 @@ export type ToChild = {
      *  control plane), so live picks the right backend per agent — not the
      *  global default. Absent ⇒ host falls back to the store record / default. */
     runtime?: AgentRuntimeId;
+    /** Model-advertised reasoning effort for the live TUI and turn/start. */
+    reasoningEffort?: ReasoningEffort;
     /** The session's preset agent id, so the host can load its spec and apply
      *  the agent's model / skills / instructions to the live launch (not just
      *  the runtime). Absent for inline-config or agent-less sessions. */
@@ -87,16 +92,24 @@ export type ToChild = {
     /** An inline agent spec (console session created from an inline config
      *  rather than a preset id) — same purpose as `agentName`. */
     agentSpec?: AgentSpec;
+    /** Setup terminals only need the Provider pane to exist. Message delivery
+     *  keeps the default and waits until the native thread is actually bound. */
+    waitForReady?: boolean;
 }
 /** Inject a user turn into the session's live codex thread (`turn/start` or
  *  `turn/steer`). The forwarder mirrors the output — this is the single-writer
  *  web send path. The child replies `injected` (echoing `reqId`). */
- | {
+ | ({
     t: "inject";
     reqId: string;
     localThreadId: string;
+} & ({
+    input: RuntimeUserInput;
+    text?: never;
+} | {
     text: string;
-}
+    input?: never;
+}))
 /** Interrupt the session's active turn — the web Stop button. codex: app-server
  *  `turn/interrupt`; claude: an Escape keystroke to the pane. The child replies
  *  `interrupted` (echoing `reqId`). */
@@ -135,6 +148,7 @@ export type FromChild = {
 } | {
     t: "term.error";
     attachId: string;
+    code: TerminalOpenErrorCode;
     message: string;
 }
 /** A canonical {@link SessionEvent} mirrored by the session's persistent codex
@@ -157,8 +171,8 @@ export type FromChild = {
     cwd?: string;
     parentSessionId?: string;
 }
-/** Result of a `live.ensure`: `ok` once the codex thread is bound (or a no-op
- *  for a non-codex / non-live session). Echoes the request `reqId`. */
+/** Result of a `live.ensure`: `ok` once the requested gate is reached (pane
+ *  started for setup, otherwise native thread bound). Echoes `reqId`. */
  | {
     t: "live.ready";
     reqId: string;
@@ -184,6 +198,11 @@ export type FromChild = {
     localThreadId: string;
     ok: boolean;
     error?: string;
+} | {
+    t: "interaction.resolved";
+    reqId: string;
+    localThreadId: string;
+    result: ResolveInteractionResult;
 };
 /** Encode a message as a single NDJSON line (newline included). */
 export declare function encodeMessage(msg: ToChild | FromChild): string;

package/dist/runner-main.js

@@ -44,9 +44,12 @@ function main() {
         ...(process.env.RYNX_RUNNER_SESSION ? { sessionId: process.env.RYNX_RUNNER_SESSION } : {}),
     });
     const transport = new StdioRunnerTransport(process.stdin, process.stdout);
-    transport.onClose(() => process.exit(0));
-    // eslint-disable-next-line no-new -- the session wires itself to the transport.
-    new RunnerSession({
+    let runner;
+    transport.onClose(() => {
+        runner?.shutdown();
+        process.exit(0);
+    });
+    runner = new RunnerSession({
         transport,
         executor,
         onShutdown: () => {
@@ -54,8 +57,8 @@ function main() {
             process.exit(0);
         },
     });
-    // A parent SIGTERM (idle reap / shutdown) ends the process; the OS tears down
-    // the child app-server / PTY with it.
-    process.on("SIGTERM", () => process.exit(0));
+    // A parent SIGTERM (idle reap / shutdown) uses the same ordered cleanup path
+    // as the protocol shutdown before ending the process.
+    process.on("SIGTERM", () => runner?.shutdown());
 }
 main();

package/dist/runtime-status.js

@@ -3,7 +3,7 @@
  *
  * The parent control plane no longer holds an execution backend (runners own
  * the codex app-server / claude PTY), so it must answer "is this runtime usable
- * on this machine?" without spinning one up. This mirrors omnigent's model,
+ * on this machine?" without spinning one up. This mirrors reference implementation's model,
  * where readiness is `which(binary) + a usable credential` rather than a live
  * app-server. For codex/traex that is a one-shot `<bin> login status` (no
  * app-server); for claude it reuses {@link readClaudeStatus} (SDK + credentials).

package/dist/terminal/claude-tui.d.ts

@@ -11,10 +11,15 @@
  * launch so the daemon-spawned TUI never blocks on a first-run prompt.
  */
 export interface ClaudeTuiArgs {
-    /** The claude `--settings` JSON (hook registration). */
+    /** Claude `--settings` value: a JSON document or private settings path. */
     settingsJson: string;
+    /** Comma-separated native setting sources. An empty string isolates a
+     * managed session from host/project hooks while keeping explicit settings. */
+    settingSources?: string;
     /** Launch model (`--model`); omit to use claude's default. */
     model?: string;
+    /** Agent instructions appended to Claude Code's native system prompt. */
+    appendSystemPrompt?: string;
     /** Resume a specific prior claude session (`--resume <id>`). */
     resume?: string;
     /** Extra claude args placed before the injected flags (rarely needed). */
@@ -22,6 +27,6 @@ export interface ClaudeTuiArgs {
 }
 /**
  * Build the `claude` argv for an interactive, co-drivable TUI:
- * `[..extra] [--resume <id>] [--model <m>] --settings <json>`.
+ * `[..extra] [--resume <id>] [--model <m>] [--append-system-prompt <text>] --settings <json>`.
  */
-export declare function buildClaudeTuiArgs({ settingsJson, model, resume, extraArgs, }: ClaudeTuiArgs): string[];
+export declare function buildClaudeTuiArgs({ settingsJson, settingSources, model, appendSystemPrompt, resume, extraArgs, }: ClaudeTuiArgs): string[];

package/dist/terminal/claude-tui.js

@@ -1,13 +1,17 @@
 /**
  * Build the `claude` argv for an interactive, co-drivable TUI:
- * `[..extra] [--resume <id>] [--model <m>] --settings <json>`.
+ * `[..extra] [--resume <id>] [--model <m>] [--append-system-prompt <text>] --settings <json>`.
  */
-export function buildClaudeTuiArgs({ settingsJson, model, resume, extraArgs = [], }) {
+export function buildClaudeTuiArgs({ settingsJson, settingSources, model, appendSystemPrompt, resume, extraArgs = [], }) {
     const args = [...extraArgs];
+    if (settingSources !== undefined)
+        args.push("--setting-sources", settingSources);
     if (resume)
         args.push("--resume", resume);
     if (model)
         args.push("--model", model);
+    if (appendSystemPrompt)
+        args.push("--append-system-prompt", appendSystemPrompt);
     args.push("--settings", settingsJson);
     return args;
 }

package/dist/terminal/codex-tui.d.ts

@@ -1,10 +1,10 @@
 /**
- * codex-native live-terminal launcher (Phase D). Encodes omnigent's verified
+ * codex-native live-terminal launcher (Phase D). Encodes reference implementation's verified
  * co-drive recipe: a separate `codex` TUI process attaches to the session's
  * already-running app-server over `--remote` and resumes the SAME thread, so the
  * TUI, the structured data channel, and the web bridge all drive one thread.
  *
- * Two facts carried over from omnigent's working implementation
+ * Two facts carried over from reference implementation's working implementation
  * (`codex_native_app_server.build_codex_remote_args`):
  *  - the app-server must listen on a multi-client transport (`ws://IP:PORT` or
  *    `unix://PATH`) — stdio only admits the one client that spawned it, so it
@@ -31,7 +31,7 @@ export interface CodexRemoteArgs {
     codexArgs?: string[];
 }
 /**
- * Build the `codex` argv tail for an app-server-backed TUI. Mirrors omnigent's
+ * Build the `codex` argv tail for an app-server-backed TUI. Mirrors reference implementation's
  * `build_codex_remote_args` exactly: overrides → codexArgs → (resume) → --remote.
  */
 export declare function buildCodexRemoteArgs({ remoteUrl, threadId, configOverrides, codexArgs, }: CodexRemoteArgs): string[];

package/dist/terminal/codex-tui.js

@@ -1,5 +1,5 @@
 /**
- * Build the `codex` argv tail for an app-server-backed TUI. Mirrors omnigent's
+ * Build the `codex` argv tail for an app-server-backed TUI. Mirrors reference implementation's
  * `build_codex_remote_args` exactly: overrides → codexArgs → (resume) → --remote.
  */
 export function buildCodexRemoteArgs({ remoteUrl, threadId, configOverrides = [], codexArgs = [], }) {

package/dist/terminal/registry.d.ts

@@ -3,7 +3,7 @@
  *
  * Owns terminal lifecycle. Read-only vs read-write is decided PURELY by the
  * requested role (the caller derives it from the viewer's permission level),
- * exactly like omnigent's terminal attach (`terminal_attach.py`: `read_only`
+ * exactly like reference implementation's terminal attach (`terminal_attach.py`: `read_only`
  * from the URL → `-r`). There is deliberately NO stateful "first owner wins,
  * later owners downgraded" slot: that rynx-only mechanism leaked its owner slot
  * across a detach (the release ran on the attachment's `onExit`, which the

package/dist/terminal/registry.js

@@ -3,7 +3,7 @@
  *
  * Owns terminal lifecycle. Read-only vs read-write is decided PURELY by the
  * requested role (the caller derives it from the viewer's permission level),
- * exactly like omnigent's terminal attach (`terminal_attach.py`: `read_only`
+ * exactly like reference implementation's terminal attach (`terminal_attach.py`: `read_only`
  * from the URL → `-r`). There is deliberately NO stateful "first owner wins,
  * later owners downgraded" slot: that rynx-only mechanism leaked its owner slot
  * across a detach (the release ran on the attachment's `onExit`, which the

package/dist/terminal/tmux.d.ts

@@ -64,7 +64,7 @@ export declare class TmuxTerminal {
      *  command. Idempotent: a second call is a no-op once the session exists. */
     start(): void;
     /**
-     * Apply omnigent's tmux option suite to the private server (inner/terminal.py).
+     * Apply reference implementation's tmux option suite to the private server (inner/terminal.py).
      * These are NOT cosmetic — several fix real co-drive behavior that the tmux
      * defaults break:
      *  - `mouse on`: the web terminal's wheel scrolls the pane's scrollback (and
@@ -83,7 +83,7 @@ export declare class TmuxTerminal {
      *    inner CLI exits so its last output stays capturable and `#{pane_dead}` reads
      *    the exit (liveness probe), instead of the server vanishing.
      *  - `MouseDown3*` unbinds: no right-click menu to spawn extra panes/windows.
-     *  - `status off`: hide tmux chrome. omnigent keeps the status line only to show
+     *  - `status off`: hide tmux chrome. reference implementation keeps the status line only to show
      *    a conversation link; rynx has none, so the whole line (and its
      *    `[main] 0:node*` window list) is hidden.
      * `-q`/`-gq`/`-sq` keep an older tmux that lacks an option from failing launch.
@@ -95,12 +95,12 @@ export declare class TmuxTerminal {
      *  `remain-on-exit on` the session/server deliberately outlive the inner CLI's
      *  exit (a dead pane shows tmux's "Pane is dead"), so `has-session` succeeding
      *  no longer implies a live process. Alive only when the session exists AND its
-     *  pane process has not exited. Mirrors omnigent's `_terminal.is_alive`. */
+     *  pane process has not exited. Mirrors reference implementation's `_terminal.is_alive`. */
     isAlive(): boolean;
     /** Async pane-liveness probe — MUST NOT block the event loop. The attach
      *  pane-death watcher polls this on an interval; a synchronous `execFileSync`
      *  there stalls the runner child's event loop (freezing the PTY stream → the
-     *  terminal appears "stuck"). omnigent's `_tmux_session_alive` uses an async
+     *  terminal appears "stuck"). reference implementation's `_tmux_session_alive` uses an async
      *  subprocess + timeout for exactly this reason. */
     private isAliveAsync;
     /** Type literal text into the pane (agent injection / co-drive from a
@@ -119,11 +119,11 @@ export declare class TmuxTerminal {
     sendEnter(): void;
     /** Interrupt the pane's running TUI turn with an Escape key — codex/claude both
      *  cancel an in-flight response on a single Esc ("esc to interrupt"). A key NAME
-     *  (no `-l`) so tmux interprets it. Mirrors omnigent's `inject_interrupt`. */
+     *  (no `-l`) so tmux interprets it. Mirrors reference implementation's `inject_interrupt`. */
     interrupt(): void;
     /** Clear the current input line before an injection so leftover keystrokes
      *  can't prepend to the pasted draft. `C-a` (Home) + `C-k` (kill-to-end) is
-     *  the safe pair — `C-u` only clears backwards from the cursor (omnigent). */
+     *  the safe pair — `C-u` only clears backwards from the cursor (reference implementation). */
     clearInputLine(): void;
     /** Send one or more tmux key NAMES (e.g. `Enter`, `C-a`) to the pane. */
     private sendKeyNames;

package/dist/terminal/tmux.js

@@ -24,7 +24,7 @@ const DEFAULT_COLS = 80;
 const DEFAULT_ROWS = 24;
 /** tmux pane scrollback depth. Matches the browser xterm `scrollback` so a
  *  wheel-scroll (tmux copy-mode, enabled by `mouse on`) reaches as far back as
- *  the terminal shows. Mirrors omnigent's `TerminalEnvSpec.scrollback`. */
+ *  the terminal shows. Mirrors reference implementation's `TerminalEnvSpec.scrollback`. */
 const DEFAULT_SCROLLBACK = 20000;
 /** Is a usable `tmux` on PATH? Cheap probe for the capability gate. */
 export function isTmuxAvailable(tmuxBin = "tmux") {
@@ -42,7 +42,7 @@ async function loadPtySpawn() {
 }
 /** Ensure a UTF-8 locale so tmux renders multibyte (CJK) output correctly. A
  *  pm2/systemd-spawned daemon often has no LANG/LC_*, so tmux treats CJK bytes as
- *  single-byte and mangles Chinese. omnigent inherits a UTF-8 locale from its launch
+ *  single-byte and mangles Chinese. reference implementation inherits a UTF-8 locale from its launch
  *  env; a pm2 daemon may not — so inject one when none is present. */
 function withUtf8Locale(env) {
     const hasUtf8 = [env.LC_ALL, env.LC_CTYPE, env.LANG].some((v) => v != null && /utf-?8/i.test(v));
@@ -121,7 +121,7 @@ export class TmuxTerminal {
         this.started = true;
     }
     /**
-     * Apply omnigent's tmux option suite to the private server (inner/terminal.py).
+     * Apply reference implementation's tmux option suite to the private server (inner/terminal.py).
      * These are NOT cosmetic — several fix real co-drive behavior that the tmux
      * defaults break:
      *  - `mouse on`: the web terminal's wheel scrolls the pane's scrollback (and
@@ -140,7 +140,7 @@ export class TmuxTerminal {
      *    inner CLI exits so its last output stays capturable and `#{pane_dead}` reads
      *    the exit (liveness probe), instead of the server vanishing.
      *  - `MouseDown3*` unbinds: no right-click menu to spawn extra panes/windows.
-     *  - `status off`: hide tmux chrome. omnigent keeps the status line only to show
+     *  - `status off`: hide tmux chrome. reference implementation keeps the status line only to show
      *    a conversation link; rynx has none, so the whole line (and its
      *    `[main] 0:node*` window list) is hidden.
      * `-q`/`-gq`/`-sq` keep an older tmux that lacks an option from failing launch.
@@ -170,7 +170,7 @@ export class TmuxTerminal {
             ["unbind-key", "-q", "-T", "root", "M-MouseDown3Status"],
             ["unbind-key", "-q", "-T", "root", "MouseDown3StatusLeft"],
             ["unbind-key", "-q", "-T", "root", "M-MouseDown3StatusLeft"],
-            // hide tmux chrome (no conversation link to show, unlike omnigent)
+            // hide tmux chrome (no conversation link to show, unlike reference implementation)
             ["set-option", "-g", "status", "off"],
         ];
         const argv = [...this.base()];
@@ -186,7 +186,7 @@ export class TmuxTerminal {
      *  `remain-on-exit on` the session/server deliberately outlive the inner CLI's
      *  exit (a dead pane shows tmux's "Pane is dead"), so `has-session` succeeding
      *  no longer implies a live process. Alive only when the session exists AND its
-     *  pane process has not exited. Mirrors omnigent's `_terminal.is_alive`. */
+     *  pane process has not exited. Mirrors reference implementation's `_terminal.is_alive`. */
     isAlive() {
         if (!this.started)
             return false;
@@ -205,7 +205,7 @@ export class TmuxTerminal {
     /** Async pane-liveness probe — MUST NOT block the event loop. The attach
      *  pane-death watcher polls this on an interval; a synchronous `execFileSync`
      *  there stalls the runner child's event loop (freezing the PTY stream → the
-     *  terminal appears "stuck"). omnigent's `_tmux_session_alive` uses an async
+     *  terminal appears "stuck"). reference implementation's `_tmux_session_alive` uses an async
      *  subprocess + timeout for exactly this reason. */
     isAliveAsync() {
         if (!this.started)
@@ -251,13 +251,13 @@ export class TmuxTerminal {
     }
     /** Interrupt the pane's running TUI turn with an Escape key — codex/claude both
      *  cancel an in-flight response on a single Esc ("esc to interrupt"). A key NAME
-     *  (no `-l`) so tmux interprets it. Mirrors omnigent's `inject_interrupt`. */
+     *  (no `-l`) so tmux interprets it. Mirrors reference implementation's `inject_interrupt`. */
     interrupt() {
         this.sendKeyNames("Escape");
     }
     /** Clear the current input line before an injection so leftover keystrokes
      *  can't prepend to the pasted draft. `C-a` (Home) + `C-k` (kill-to-end) is
-     *  the safe pair — `C-u` only clears backwards from the cursor (omnigent). */
+     *  the safe pair — `C-u` only clears backwards from the cursor (reference implementation). */
     clearInputLine() {
         this.sendKeyNames("C-a", "C-k");
     }
@@ -305,7 +305,7 @@ export class TmuxTerminal {
         // process alive (so `proc.onExit` never fires) while tmux paints "Pane is dead".
         // Poll `#{pane_dead}` and synthesize an exit so the web bridge closes the WS and
         // shows the dead-pane overlay instead of leaking tmux's "Pane is dead" text
-        // (omnigent: the server closes the socket on pane death → StatusOverlay).
+        // (reference implementation: the server closes the socket on pane death → StatusOverlay).
         // Multi-listener, not a single slot: the runner child (and any future
         // subscriber) register `onExit`; a single-slot setter would let a later
         // `onExit` silently CLOBBER an earlier one (that clobber is exactly how the

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@rynx-ai/runtime",
-  "version": "0.1.0",
+  "version": "0.1.10-beta.2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rynx-ai/rynx.git",
+    "directory": "packages/runtime"
+  },
   "description": "Runtime host that drives local coding-agent CLIs (codex / traex / claude) behind one AgentExecutor + AgentCapabilities contract.",
   "type": "module",
   "publishConfig": {
@@ -21,12 +26,12 @@
   "dependencies": {
     "node-pty": "^1.0.0",
     "ws": "^8.21.0",
-    "@rynx-ai/core": "0.1.0"
+    "@rynx-ai/core": "0.1.10-beta.2"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/runner-main.js dist/claude/native-hook-main.js dist/claude/native-message-display-main.js dist/claude/native-status-main.js"
+    "build": "node ../../scripts/verify-node-pty.cjs && rm -rf dist && tsc -p tsconfig.json && chmod +x dist/runner-main.js dist/claude/native-hook-main.js dist/claude/native-message-display-main.js dist/claude/native-status-main.js"
   }
 }