@rynx-ai/runtime 0.1.10 → 0.1.11-beta.10

package/dist/runner/protocol.d.ts

@@ -6,7 +6,7 @@
  * (`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 ReasoningEffort, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent } from "@rynx-ai/core";
+import { AgentRuntimeError, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent, type SessionWorkspaceSnapshot } 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 {
@@ -76,22 +76,12 @@ export type ToChild = {
     t: "live.ensure";
     reqId: string;
     localThreadId: string;
-    cwd?: string;
+    /** The two immutable Session snapshots. Provider launch/resume only
+     * projects these values and never resolves a Project or Agent. */
+    workspace: SessionWorkspaceSnapshot;
+    execution: ResolvedExecutionSnapshot;
     cols?: number;
     rows?: number;
-    /** Runtime this session co-drives (resolved from the agent spec by the
-     *  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. */
-    agentName?: string;
-    /** 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;
@@ -166,9 +156,8 @@ export type FromChild = {
     from: string;
     to: string;
     kind: "clear" | "fork";
-    agent?: string;
-    model?: string;
-    cwd?: string;
+    workspace: SessionWorkspaceSnapshot;
+    execution: ResolvedExecutionSnapshot;
     parentSessionId?: string;
 }
 /** Result of a `live.ensure`: `ok` once the requested gate is reached (pane

package/dist/runner-main.js

@@ -16,7 +16,7 @@
  * active-session display, which tolerate atomic-rename reads). A parent-of-record
  * design (ship-in / emit-out) is the remote-ready follow-up.
  */
-import { loadConfig, } from "@rynx-ai/core";
+import { loadConfig } from "@rynx-ai/core";
 import { FileCodexSessionStore, LocalAgentHost, resolveCodexSessionStorePath, } from "./host.js";
 import { RunnerSession } from "./runner/child.js";
 import { StdioRunnerTransport } from "./runner/transport.js";
@@ -33,15 +33,20 @@ for (const stream of [process.stdout, process.stderr]) {
         throw err;
     });
 }
-function main() {
+async function main() {
     const config = loadConfig();
     const sessionStore = new FileCodexSessionStore(resolveCodexSessionStorePath(config));
+    const sessionId = process.env.RYNX_RUNNER_SESSION;
+    const binding = sessionId ? await sessionStore.get(sessionId) : null;
     const executor = new LocalAgentHost({
         config,
         sessionStore,
         // The manager spawns one child per session and passes its key here so the
         // host's private CODEX_HOME is scoped to this session (see manager.spawnHandle).
-        ...(process.env.RYNX_RUNNER_SESSION ? { sessionId: process.env.RYNX_RUNNER_SESSION } : {}),
+        ...(sessionId ? { sessionId } : {}),
+        ...(binding?.runtimeHomeOwnerSessionId
+            ? { runtimeHomeSessionId: binding.runtimeHomeOwnerSessionId }
+            : {}),
     });
     const transport = new StdioRunnerTransport(process.stdin, process.stdout);
     let runner;
@@ -61,4 +66,7 @@ function main() {
     // as the protocol shutdown before ending the process.
     process.on("SIGTERM", () => runner?.shutdown());
 }
-main();
+void main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/runtime-state-paths.d.ts

@@ -0,0 +1,10 @@
+export declare function runtimeSessionDigest(sessionId: string): string;
+export declare function runtimeSessionStateDir(sessionId: string): string;
+/** Pre-standardization uid-private temp root, read only for opaque directory adoption. */
+export declare function legacyRuntimeStateRoot(): string;
+/**
+ * Adopt a pre-standardization runtime directory without interpreting Provider
+ * files. Rename when possible; cross-device filesystems fall back to an opaque
+ * recursive copy followed by removal.
+ */
+export declare function adoptLegacyRuntimeDirectory(legacyDirectory: string, canonicalDirectory: string): void;

package/dist/runtime-state-paths.js

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, renameSync, rmSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { rynxRuntimeDir } from "@rynx-ai/core";
+export function runtimeSessionDigest(sessionId) {
+    return createHash("sha256").update(sessionId).digest("hex").slice(0, 32);
+}
+export function runtimeSessionStateDir(sessionId) {
+    return join(rynxRuntimeDir(), "sessions", runtimeSessionDigest(sessionId));
+}
+/** Pre-standardization uid-private temp root, read only for opaque directory adoption. */
+export function legacyRuntimeStateRoot() {
+    const uid = typeof process.getuid === "function" ? process.getuid() : "nouid";
+    return join(tmpdir(), `rynx-${uid}`);
+}
+/**
+ * Adopt a pre-standardization runtime directory without interpreting Provider
+ * files. Rename when possible; cross-device filesystems fall back to an opaque
+ * recursive copy followed by removal.
+ */
+export function adoptLegacyRuntimeDirectory(legacyDirectory, canonicalDirectory) {
+    if (existsSync(canonicalDirectory) || !existsSync(legacyDirectory))
+        return;
+    mkdirSync(dirname(canonicalDirectory), { recursive: true, mode: 0o700 });
+    try {
+        renameSync(legacyDirectory, canonicalDirectory);
+        return;
+    }
+    catch {
+        if (existsSync(canonicalDirectory) || !existsSync(legacyDirectory))
+            return;
+    }
+    const stagingDirectory = `${canonicalDirectory}.adopt-${process.pid}-${Date.now().toString(36)}`;
+    try {
+        cpSync(legacyDirectory, stagingDirectory, {
+            recursive: true,
+            errorOnExist: true,
+            force: false,
+        });
+        try {
+            renameSync(stagingDirectory, canonicalDirectory);
+        }
+        catch (error) {
+            if (!existsSync(canonicalDirectory))
+                throw error;
+        }
+        rmSync(legacyDirectory, { recursive: true, force: true });
+    }
+    finally {
+        rmSync(stagingDirectory, { recursive: true, force: true });
+    }
+}

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

@@ -18,10 +18,19 @@ export interface ClaudeTuiArgs {
     settingSources?: string;
     /** Launch model (`--model`); omit to use claude's default. */
     model?: string;
+    /** Native Claude Code effort (`--effort`); omit to use its default. */
+    reasoningEffort?: string;
     /** Agent instructions appended to Claude Code's native system prompt. */
     appendSystemPrompt?: string;
     /** Resume a specific prior claude session (`--resume <id>`). */
     resume?: string;
+    /** Fork the resumed conversation into a new native Session. */
+    forkSession?: boolean;
+    /** Deterministic native UUID for a fork target. */
+    sessionId?: string;
+    /** Session workspace roots beyond the primary process cwd. Claude accepts
+     * these as one variadic `--add-dir` flag on fresh and resumed launches. */
+    additionalDirs?: string[];
     /** Extra claude args placed before the injected flags (rarely needed). */
     extraArgs?: string[];
 }
@@ -29,4 +38,4 @@ export interface ClaudeTuiArgs {
  * Build the `claude` argv for an interactive, co-drivable TUI:
  * `[..extra] [--resume <id>] [--model <m>] [--append-system-prompt <text>] --settings <json>`.
  */
-export declare function buildClaudeTuiArgs({ settingsJson, settingSources, model, appendSystemPrompt, resume, extraArgs, }: ClaudeTuiArgs): string[];
+export declare function buildClaudeTuiArgs({ settingsJson, settingSources, model, reasoningEffort, appendSystemPrompt, resume, forkSession, sessionId, additionalDirs, extraArgs, }: ClaudeTuiArgs): string[];

package/dist/terminal/claude-tui.js

@@ -2,14 +2,22 @@
  * Build the `claude` argv for an interactive, co-drivable TUI:
  * `[..extra] [--resume <id>] [--model <m>] [--append-system-prompt <text>] --settings <json>`.
  */
-export function buildClaudeTuiArgs({ settingsJson, settingSources, model, appendSystemPrompt, resume, extraArgs = [], }) {
+export function buildClaudeTuiArgs({ settingsJson, settingSources, model, reasoningEffort, appendSystemPrompt, resume, forkSession = false, sessionId, additionalDirs = [], extraArgs = [], }) {
     const args = [...extraArgs];
+    if (additionalDirs.length > 0)
+        args.push("--add-dir", ...additionalDirs);
     if (settingSources !== undefined)
         args.push("--setting-sources", settingSources);
     if (resume)
         args.push("--resume", resume);
+    if (forkSession)
+        args.push("--fork-session");
+    if (sessionId)
+        args.push("--session-id", sessionId);
     if (model)
         args.push("--model", model);
+    if (reasoningEffort)
+        args.push("--effort", reasoningEffort);
     if (appendSystemPrompt)
         args.push("--append-system-prompt", appendSystemPrompt);
     args.push("--settings", settingsJson);

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

@@ -29,12 +29,16 @@ export interface CodexRemoteArgs {
     configOverrides?: string[];
     /** Extra codex args that precede the attach flags (e.g. `["--model", "..."]`). */
     codexArgs?: string[];
+    /** Session workspace roots beyond the primary process cwd. Replayed on fresh
+     * launch and resume so the remote TUI uses the same immutable workspace
+     * snapshot as the App Server clients. */
+    additionalDirs?: string[];
 }
 /**
  * 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[];
+export declare function buildCodexRemoteArgs({ remoteUrl, threadId, configOverrides, codexArgs, additionalDirs, }: CodexRemoteArgs): string[];
 export interface LaunchCodexTuiOptions extends CodexRemoteArgs {
     registry: TerminalRegistry;
     /** Terminal id (one codex TUI per session — `terminal_codex_main`). */

package/dist/terminal/codex-tui.js

@@ -2,12 +2,21 @@
  * 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 = [], }) {
+export function buildCodexRemoteArgs({ remoteUrl, threadId, configOverrides = [], codexArgs = [], additionalDirs = [], }) {
     const overrideArgs = configOverrides.flatMap((override) => ["-c", override]);
+    const additionalDirArgs = additionalDirs.flatMap((dir) => ["--add-dir", dir]);
     if (threadId === undefined) {
-        return [...overrideArgs, ...codexArgs, "--remote", remoteUrl];
+        return [...overrideArgs, ...codexArgs, ...additionalDirArgs, "--remote", remoteUrl];
     }
-    return [...overrideArgs, ...codexArgs, "resume", "--remote", remoteUrl, threadId];
+    return [
+        ...overrideArgs,
+        ...codexArgs,
+        ...additionalDirArgs,
+        "resume",
+        "--remote",
+        remoteUrl,
+        threadId,
+    ];
 }
 /**
  * Create (idempotently) the codex TUI terminal in the registry, running the real

package/dist/terminal/tmux.d.ts

@@ -43,6 +43,14 @@ export interface TmuxTerminalOptions {
     /** Injectable for tests; defaults to the real `tmux` binary path. */
     tmuxBin?: string;
 }
+/** Deterministic private socket owned by one terminal name. Parent-side
+ * shutdown uses the same mapping when the runner child is too wedged to clean
+ * up its own tmux server. */
+export declare function tmuxSocketPath(name: string): string;
+/** Kill one private tmux server and verify it no longer answers. Missing
+ * sockets are already stopped; an existing socket with an unusable tmux
+ * command is unproven and returns false. */
+export declare function terminateTmuxServer(name: string, tmuxBin?: string): boolean;
 /** Is a usable `tmux` on PATH? Cheap probe for the capability gate. */
 export declare function isTmuxAvailable(tmuxBin?: string): boolean;
 export declare class TmuxTerminal {
@@ -138,7 +146,9 @@ export declare class TmuxTerminal {
     paste(text: string, bufferName?: string): void;
     /**
      * Attach a client. `role: "read-only"` passes tmux `-r` so the viewer cannot
-     * type (defense-in-depth on top of the WS bridge dropping input frames).
+     * type and `ignore-size` so even its initial PTY dimensions cannot resize the
+     * owner's pane (defense-in-depth on top of the WS bridge dropping input and
+     * resize frames).
      */
     attach(role: "owner" | "read-only", dims?: {
         cols?: number;

package/dist/terminal/tmux.js

@@ -16,7 +16,7 @@
  */
 import { execFile, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 const TMUX_TARGET = "main";
@@ -26,6 +26,58 @@ const DEFAULT_ROWS = 24;
  *  wheel-scroll (tmux copy-mode, enabled by `mouse on`) reaches as far back as
  *  the terminal shows. Mirrors reference implementation's `TerminalEnvSpec.scrollback`. */
 const DEFAULT_SCROLLBACK = 20000;
+/** Deterministic private socket owned by one terminal name. Parent-side
+ * shutdown uses the same mapping when the runner child is too wedged to clean
+ * up its own tmux server. */
+export function tmuxSocketPath(name) {
+    const key = createHash("sha256").update(name).digest("hex").slice(0, 16);
+    return join(tmpdir(), "rynx-term", `${key}.sock`);
+}
+/** Kill one private tmux server and verify it no longer answers. Missing
+ * sockets are already stopped; an existing socket with an unusable tmux
+ * command is unproven and returns false. */
+export function terminateTmuxServer(name, tmuxBin = "tmux") {
+    const socketPath = tmuxSocketPath(name);
+    if (!existsSync(socketPath))
+        return true;
+    const base = ["-u", "-S", socketPath];
+    try {
+        execFileSync(tmuxBin, [...base, "kill-server"], { stdio: "ignore" });
+    }
+    catch {
+        // A server may have exited between existsSync and kill-server. Verify below.
+    }
+    try {
+        execFileSync(tmuxBin, [...base, "has-session", "-t", TMUX_TARGET], {
+            stdio: "ignore",
+        });
+        return false;
+    }
+    catch (error) {
+        // Only a real tmux exit status proves the server/session is absent. Spawn
+        // failures (missing/unexecutable tmux) leave liveness unproven and must not
+        // unlink a socket that could still belong to a live server.
+        if (!error ||
+            typeof error !== "object" ||
+            !("status" in error) ||
+            typeof error.status !== "number") {
+            return false;
+        }
+        try {
+            // tmux custom-socket servers can exit while leaving the filesystem entry
+            // behind. Remove that verified-stale socket so process/socket inventories
+            // do not accumulate dead terminals forever.
+            unlinkSync(socketPath);
+            return true;
+        }
+        catch (unlinkError) {
+            return Boolean(unlinkError &&
+                typeof unlinkError === "object" &&
+                "code" in unlinkError &&
+                unlinkError.code === "ENOENT");
+        }
+    }
+}
 /** Is a usable `tmux` on PATH? Cheap probe for the capability gate. */
 export function isTmuxAvailable(tmuxBin = "tmux") {
     try {
@@ -76,8 +128,7 @@ export class TmuxTerminal {
         // under the unix-domain path limit (~104 chars on macOS) — a full session id
         // like `sess_<uuid>-main` under $TMPDIR would overflow it and fail with
         // "File name too long". The hash stays unique per terminal.
-        const key = createHash("sha256").update(opts.name).digest("hex").slice(0, 16);
-        this.socketPath = join(dir, `${key}.sock`);
+        this.socketPath = tmuxSocketPath(opts.name);
     }
     /** tmux argv prefix targeting this terminal's private server. */
     base() {
@@ -286,14 +337,17 @@ export class TmuxTerminal {
     }
     /**
      * Attach a client. `role: "read-only"` passes tmux `-r` so the viewer cannot
-     * type (defense-in-depth on top of the WS bridge dropping input frames).
+     * type and `ignore-size` so even its initial PTY dimensions cannot resize the
+     * owner's pane (defense-in-depth on top of the WS bridge dropping input and
+     * resize frames).
      */
     async attach(role, dims) {
         this.start();
         const spawn = this.injectedSpawn ?? (await loadPtySpawn());
-        const args = [...this.base(), "attach-session", "-t", TMUX_TARGET];
+        const args = [...this.base(), "attach-session"];
         if (role === "read-only")
-            args.push("-r");
+            args.push("-r", "-f", "ignore-size");
+        args.push("-t", TMUX_TARGET);
         const proc = spawn(this.tmuxBin, args, {
             name: "xterm-256color",
             cols: dims?.cols ?? this.cols,
@@ -353,12 +407,7 @@ export class TmuxTerminal {
     }
     /** Kill the tmux server (ends the session and all attaches). */
     kill() {
-        try {
-            execFileSync(this.tmuxBin, [...this.base(), "kill-server"], { stdio: "ignore" });
-        }
-        catch {
-            // Already gone — nothing to clean up.
-        }
+        terminateTmuxServer(this.name, this.tmuxBin);
         this.started = false;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynx-ai/runtime",
-  "version": "0.1.10",
+  "version": "0.1.11-beta.10",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rynx-ai/rynx.git",
@@ -24,9 +24,9 @@
     }
   },
   "dependencies": {
-    "node-pty": "^1.0.0",
+    "node-pty": "1.2.0-beta.15",
     "ws": "^8.21.0",
-    "@rynx-ai/core": "0.1.10"
+    "@rynx-ai/core": "0.1.11-beta.10"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"

package/dist/codex/rollout-synth.d.ts

@@ -1,42 +0,0 @@
-import { type SessionItem } from "@rynx-ai/core";
-import { type CodexLineageRuntime } from "../codex-home.js";
-export interface SynthesizeRolloutOptions {
-    threadId: string;
-    cwd: string;
-    items: SessionItem[];
-    /** The rynx session (localThreadId) — resolves the per-session private CODEX_HOME
-     *  (`codexHomePath(sessionId)`). Required unless `codexHome` is passed directly. */
-    sessionId?: string;
-    /** Override the private CODEX_HOME (tests, or a pre-resolved home). */
-    codexHome?: string;
-    /** Codex-lineage runtime whose private home/session layout is being written. */
-    runtime?: CodexLineageRuntime;
-    /** Runtime-neutral alias for `codexHome`; preferred for Traex callers. */
-    runtimeHome?: string;
-    /** codex CLI version for `session_meta` (informational for ≥0.133; presence
-     *  matters). */
-    cliVersion?: string;
-    /** `session_meta.model_provider` — an empty/unresolvable value silently drops the
-     *  carried history on resume. Defaults to `openai`. */
-    modelProvider?: string;
-    /** Clock injection (tests). */
-    now?: () => number;
-}
-interface RolloutRecord {
-    timestamp: string;
-    type: "session_meta" | "turn_context" | "response_item" | "event_msg";
-    payload: Record<string, unknown>;
-}
-/** Locate an existing rollout for `threadId` under the runtime's sessions root. */
-export declare function findCodexRollout(runtimeHome: string, threadId: string, runtime?: CodexLineageRuntime): string | null;
-/** Build the ordered rollout records (session_meta first, then per-turn
- *  turn_context + per-item response_item + per-message event_msg). */
-export declare function buildRolloutRecords(opts: SynthesizeRolloutOptions): RolloutRecord[];
-/**
- * Ensure a resumable codex rollout exists for `threadId`. No-op if one is already
- * present (codex owns its own runtime rollouts). Otherwise synthesize one from the
- * session items and write it atomically. Returns `"exists"`, `"written"`, or
- * `"skipped"` (invalid thread id / nothing to carry). Best-effort: never throws.
- */
-export declare function ensureCodexResumeRollout(opts: SynthesizeRolloutOptions): "exists" | "written" | "skipped";
-export {};