@rynx-ai/runtime 0.1.11-beta.24 → 0.1.11-beta.26

package/dist/input-resources.d.ts

@@ -3,6 +3,10 @@ import type { UserInput } from "./codex-app-server/protocol.js";
 /** Convert the provider-native user echo back to resource references. Unknown
  * local paths and remote URLs are deliberately omitted rather than exposed. */
 export declare function codexUserContent(input: readonly UserInput[]): UserContentPart[];
+/** Match the forwarder's public user echo shape exactly. Codex merges adjacent
+ * text inputs (including the internal file marker) into one string before the
+ * Host sees the completed userMessage item. */
+export declare function codexUserEchoContent(input: readonly UserInput[]): string | UserContentPart[] | undefined;
 /** Claude's native TUI has no structured image RPC. The target daemon supplies
  * only managed local paths and the marker makes the transcript echo reversible. */
 export declare function claudeInputText(input: RuntimeUserInput, attachmentToken?: string): string;

package/dist/input-resources.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { basename, extname } from "node:path";
 const CLAUDE_ATTACHMENT_TOKEN = "RYNX_ATTACHMENT_SET";
-const CLAUDE_ATTACHMENT_TOKEN_RE = /^\[RYNX_ATTACHMENT_SET (att_[0-9a-f-]{36}): inspect each RYNX_IMAGE_RESOURCE path with the Read tool before answering\.\]$/m;
+const CLAUDE_ATTACHMENT_TOKEN_RE = /^\[RYNX_ATTACHMENT_SET (att_[0-9a-f-]{36}): inspect each RYNX_IMAGE_RESOURCE or RYNX_FILE_RESOURCE path with the Read tool before answering\.\]$/m;
 /** Convert the provider-native user echo back to resource references. Unknown
  * local paths and remote URLs are deliberately omitted rather than exposed. */
 export function codexUserContent(input) {
@@ -20,21 +20,37 @@ export function codexUserContent(input) {
     }
     return parts;
 }
+/** Match the forwarder's public user echo shape exactly. Codex merges adjacent
+ * text inputs (including the internal file marker) into one string before the
+ * Host sees the completed userMessage item. */
+export function codexUserEchoContent(input) {
+    const parts = codexUserContent(input);
+    if (parts.length === 0)
+        return undefined;
+    if (parts.every((part) => part.type === "input_text")) {
+        const text = parts.map((part) => part.text).join("").trim();
+        return text || undefined;
+    }
+    return parts;
+}
 /** Claude's native TUI has no structured image RPC. The target daemon supplies
  * only managed local paths and the marker makes the transcript echo reversible. */
 export function claudeInputText(input, attachmentToken = `att_${randomUUID()}`) {
-    const images = input.content.filter((part) => part.type === "local_image");
+    const attachments = input.content.filter((part) => part.type !== "text");
     const text = input.content
         .filter((part) => part.type === "text")
         .map((part) => part.text)
         .join("");
-    if (images.length === 0)
+    if (attachments.length === 0)
         return text;
     if (!/^att_[0-9a-f-]{36}$/.test(attachmentToken)) {
         throw new Error("Claude attachment token is invalid");
     }
-    const preamble = `[${CLAUDE_ATTACHMENT_TOKEN} ${attachmentToken}: inspect each RYNX_IMAGE_RESOURCE path with the Read tool before answering.]`;
-    const markers = images.map((part) => `[[RYNX_IMAGE_RESOURCE ${JSON.stringify({ path: part.path })}]]`);
+    const preamble = `[${CLAUDE_ATTACHMENT_TOKEN} ${attachmentToken}: inspect each RYNX_IMAGE_RESOURCE or RYNX_FILE_RESOURCE path with the Read tool before answering.]`;
+    const markers = attachments.map((part) => `[[RYNX_${part.type === "local_image" ? "IMAGE" : "FILE"}_RESOURCE ${JSON.stringify({
+        path: part.path,
+        ...(part.resource.filename ? { filename: part.resource.filename } : {}),
+    })}]]`);
     return [preamble, ...markers, text]
         .filter((part, index) => index <= markers.length || part.length > 0)
         .join("\n");

package/dist/runner/child.d.ts

@@ -1,13 +1,4 @@
-/**
- * Child-side runner session. One per runner process (i.e. per session); owns the
- * single execution backend via the injected executor (a {@link LocalAgentHost}
- * in production, which in a per-session process holds exactly one backend). It
- * translates inbound {@link ToChild} control messages into the live co-drive
- * surface (bring up the session's forwarder + TUI, inject / interrupt turns) and
- * per-thread capabilities, answered against the same backend so the parent never
- * needs an app-server of its own.
- */
-import { type AgentCapabilities, type LiveSessionFailure, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionWorkspaceSnapshot } from "@rynx-ai/core";
+import { type AgentCapabilities, type LiveSessionFailure, type ResolvedExecutionSnapshot, type RuntimeTurnOptions, type RuntimeUserInput, type SessionCollaborationMode, type SessionInteractionResolution, type SessionWorkspaceSnapshot } from "@rynx-ai/core";
 import type { SessionEvent } from "@rynx-ai/core";
 import type { TerminalInjector } from "../claude/native-integration.js";
 import type { ResolveInteractionResult } from "../interactions.js";
@@ -54,15 +45,17 @@ interface LiveCodexProvider {
      * observer/forwarder, and evict the owned app-server while preserving the
      * durable native-session binding for a later cold resume. */
     teardownLiveCodexSession?(localThreadId: string, error?: Error): boolean;
-    injectMessage?(localThreadId: string, input: RuntimeUserInput | string): Promise<InjectResult>;
+    injectMessage?(localThreadId: string, input: RuntimeUserInput | string, options?: RuntimeTurnOptions): Promise<InjectResult>;
+    updateCollaborationMode?(localThreadId: string, mode: SessionCollaborationMode): Promise<void>;
     interruptLive?(localThreadId: string): Promise<boolean>;
     stopLiveCodexSession?(localThreadId: string, opts?: {
         deferClaudeInteractionCleanup?: boolean;
     }): void;
     finalizeStoppedLiveSessions?(): void;
     resolveInteraction?(localThreadId: string, interactionId: string, resolution: SessionInteractionResolution): Promise<ResolveInteractionResult>;
-    /** claude-native: hand the session's tmux pane injector to the host (which
-     *  doesn't own tmux). No-op for codex sessions (they inject via app-server). */
+    /** Hand the session's tmux pane injector to the host (which doesn't own
+     * tmux). Claude uses it for messages; Codex uses it only for TUI-local
+     * controls that the app-server cannot resolve, such as the final Plan picker. */
     attachTerminalInjector?(localThreadId: string, injector: TerminalInjector): void;
     /** Internal Provider operation used only by MachineSessionService through
      * RunnerManager. It is deliberately absent from public AgentCapabilities. */
@@ -93,6 +86,8 @@ export declare class RunnerSession {
     private readonly cancelledTerminalOpens;
     /** Session ids with a live codex forwarder started here (stopped on shutdown). */
     private readonly liveIds;
+    private mirrorQueue;
+    private readonly mirrorImageAcks;
     /** Provider name retained for asynchronous Terminal-exit diagnostics. */
     private readonly liveRuntimes;
     private shuttingDown;
@@ -106,6 +101,10 @@ export declare class RunnerSession {
      *  new session AND tells the daemon to alias the runner (terminal transfer) so
      *  the new session stays injectable. */
     private mirrorChannel;
+    private enqueueMirror;
+    private sendMirroredEvent;
+    private sendMirrorImageFrame;
+    private rejectMirrorImageAcks;
     /**
      * Eagerly bring up a session's codex-native live view. Fresh sessions connect
      * the discovery listener before launching the detached TUI; known-thread
@@ -120,6 +119,7 @@ export declare class RunnerSession {
      * already-rejected readiness promise. */
     private failCodexThreadStartup;
     private inject;
+    private updateCollaborationMode;
     private interruptLive;
     /** Launch (idempotently) the session's codex TUI pane from the executor's
      *  `codexTerminalSpec`. Shares the `${id}-main` terminal id with `term.open`,

package/dist/runner/child.js

@@ -7,9 +7,10 @@
  * per-thread capabilities, answered against the same backend so the parent never
  * needs an app-server of its own.
  */
+import { randomUUID } from "node:crypto";
 import { AgentRuntimeError, } from "@rynx-ai/core";
 import { TerminalRegistry } from "../terminal/registry.js";
-import { toWireError, } from "./protocol.js";
+import { RUNNER_IMAGE_CHUNK_CHARS, RUNNER_IMAGE_MAX_RESULT_CHARS, toWireError, } from "./protocol.js";
 import { isCodexLineageProvider } from "./startup-policy.js";
 /** Maximum time for a fresh Codex-lineage TUI to publish its native thread. */
 const CODEX_THREAD_START_TIMEOUT_MS = 30_000;
@@ -48,6 +49,7 @@ const TRAEX_STARTUP_POLL_MS = 100;
 const TRAEX_AUTHORIZATION_POLL_MS = 500;
 const TRAEX_AUTHORIZATION_WAIT_MS = 15 * 60_000;
 const TRAEX_PROMPT_RETRY_MS = 500;
+const MIRROR_IMAGE_ACK_TIMEOUT_MS = 30_000;
 function normalizeTraexPane(pane) {
     return pane.toLowerCase().replace(/\s+/g, " ").trim();
 }
@@ -63,6 +65,48 @@ function isTerminalProtocolResponse(input) {
     // Neither is evidence that the user has taken over startup prompt handling.
     return /^(?:\x1b\[(?:(?:\?|>)[0-9;]*c|[0-9;]*(?:n|R|t)|[IO])|\x1b\][0-9]+;[^\x07\x1b]*(?:\x07|\x1b\\))+$/.test(input);
 }
+function detachGeneratedImageResult(event) {
+    if (event.type !== "response.output_item.done" ||
+        event.item.type !== "function_call_output") {
+        return undefined;
+    }
+    const data = event.item.data;
+    const pending = data.__rynxGeneratedImage;
+    if (!pending?.result)
+        return undefined;
+    const { result, ...withoutResult } = pending;
+    return {
+        result,
+        event: {
+            ...event,
+            item: {
+                ...event.item,
+                data: {
+                    ...data,
+                    __rynxGeneratedImage: withoutResult,
+                },
+            },
+        },
+    };
+}
+function generatedImagePreviewUnavailable(event) {
+    if (event.type !== "response.output_item.done" ||
+        event.item.type !== "function_call_output") {
+        return event;
+    }
+    const data = event.item.data;
+    const { __rynxGeneratedImage: _omitted, ...publicData } = data;
+    return {
+        ...event,
+        item: {
+            ...event.item,
+            data: {
+                ...publicData,
+                output: `${event.item.data.output}\nImage preview unavailable.`.trim(),
+            },
+        },
+    };
+}
 export class RunnerSession {
     transport;
     executor;
@@ -78,6 +122,8 @@ export class RunnerSession {
     cancelledTerminalOpens = new Set();
     /** Session ids with a live codex forwarder started here (stopped on shutdown). */
     liveIds = new Set();
+    mirrorQueue = Promise.resolve();
+    mirrorImageAcks = new Map();
     /** Provider name retained for asynchronous Terminal-exit diagnostics. */
     liveRuntimes = new Map();
     shuttingDown = false;
@@ -90,10 +136,36 @@ export class RunnerSession {
                     transport.close();
                 });
         this.transport.onMessage((msg) => this.handle(msg));
+        this.transport.onClose((error) => {
+            this.rejectMirrorImageAcks(error ?? new Error("runner transport closed"));
+        });
         this.transport.send({ t: "ready" });
     }
     handle(msg) {
         switch (msg.t) {
+            case "mirror.image.ack": {
+                const pending = this.mirrorImageAcks.get(msg.transferId);
+                if (!pending)
+                    return;
+                if (pending.seq !== msg.seq) {
+                    pending.reject(new Error("generated image acknowledgement sequence changed"));
+                    return;
+                }
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                this.mirrorImageAcks.delete(msg.transferId);
+                pending.resolve();
+                return;
+            }
+            case "mirror.image.hold": {
+                const pending = this.mirrorImageAcks.get(msg.transferId);
+                if (!pending || pending.seq !== msg.seq)
+                    return;
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                pending.timer = undefined;
+                return;
+            }
             case "cap":
                 void this.runCap(msg.capId, msg.name, msg.args);
                 return;
@@ -149,6 +221,9 @@ export class RunnerSession {
             case "inject":
                 void this.inject(msg);
                 return;
+            case "collaboration.update":
+                void this.updateCollaborationMode(msg);
+                return;
             case "live.interrupt":
                 void this.interruptLive(msg);
                 return;
@@ -185,21 +260,92 @@ export class RunnerSession {
      *  the new session stays injectable. */
     mirrorChannel(localThreadId) {
         const target = { id: localThreadId };
-        const emit = (event) => this.transport.send({ t: "mirror", sessionId: target.id, event });
+        const emit = (event) => {
+            const sessionId = target.id;
+            this.enqueueMirror(() => this.sendMirroredEvent(sessionId, event));
+        };
         const retarget = (newId, meta) => {
             target.id = newId;
-            this.transport.send({
-                t: "rotate",
-                from: localThreadId,
-                to: newId,
-                kind: meta.kind,
-                workspace: meta.workspace,
-                execution: meta.execution,
-                ...(meta.parentSessionId ? { parentSessionId: meta.parentSessionId } : {}),
+            this.enqueueMirror(() => {
+                this.transport.send({
+                    t: "rotate",
+                    from: localThreadId,
+                    to: newId,
+                    kind: meta.kind,
+                    workspace: meta.workspace,
+                    execution: meta.execution,
+                    ...(meta.parentSessionId ? { parentSessionId: meta.parentSessionId } : {}),
+                });
             });
         };
         return { emit, retarget };
     }
+    enqueueMirror(operation) {
+        this.mirrorQueue = this.mirrorQueue.then(operation).catch((error) => {
+            if (!this.shuttingDown) {
+                this.rejectMirrorImageAcks(error instanceof Error ? error : new Error(String(error)));
+                this.shutdown();
+            }
+        });
+    }
+    async sendMirroredEvent(sessionId, event) {
+        const detached = detachGeneratedImageResult(event);
+        if (!detached) {
+            this.transport.send({ t: "mirror", sessionId, event });
+            return;
+        }
+        if (detached.result.length > RUNNER_IMAGE_MAX_RESULT_CHARS) {
+            this.transport.send({
+                t: "mirror",
+                sessionId,
+                event: generatedImagePreviewUnavailable(detached.event),
+            });
+            return;
+        }
+        const transferId = `img_${randomUUID()}`;
+        let seq = 0;
+        await this.sendMirrorImageFrame(transferId, seq, {
+            t: "mirror.image.begin",
+            transferId,
+            sessionId,
+            event: detached.event,
+            totalChars: detached.result.length,
+        });
+        for (let offset = 0; offset < detached.result.length; offset += RUNNER_IMAGE_CHUNK_CHARS) {
+            seq += 1;
+            await this.sendMirrorImageFrame(transferId, seq, {
+                t: "mirror.image.chunk",
+                transferId,
+                seq,
+                data: detached.result.slice(offset, offset + RUNNER_IMAGE_CHUNK_CHARS),
+            });
+        }
+        seq += 1;
+        await this.sendMirrorImageFrame(transferId, seq, {
+            t: "mirror.image.commit",
+            transferId,
+            seq,
+        });
+    }
+    sendMirrorImageFrame(transferId, seq, frame) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.mirrorImageAcks.delete(transferId);
+                reject(new Error("generated image transfer acknowledgement timed out"));
+            }, MIRROR_IMAGE_ACK_TIMEOUT_MS);
+            timer.unref?.();
+            this.mirrorImageAcks.set(transferId, { seq, resolve, reject, timer });
+            this.transport.send(frame);
+        });
+    }
+    rejectMirrorImageAcks(error) {
+        for (const pending of this.mirrorImageAcks.values()) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.mirrorImageAcks.clear();
+    }
     /**
      * Eagerly bring up a session's codex-native live view. Fresh sessions connect
      * the discovery listener before launching the detached TUI; known-thread
@@ -274,7 +420,7 @@ export class RunnerSession {
                         : nativePhaseError(runtime, "native_terminal_launch_failed", "Terminal failed to launch", error);
                 }
             }
-            // Omnigent's known-thread path launches `codex --remote resume` first,
+            // reference implementation's known-thread path launches `codex --remote resume` first,
             // then creates `_codex_forward_known_thread` as background work. Keep the
             // ordering explicit here: observer connection failure cannot delay or
             // reject cold-resume admission.
@@ -377,7 +523,7 @@ export class RunnerSession {
         const provider = this.liveProvider;
         try {
             const input = msg.input ?? msg.text;
-            const result = (await provider.injectMessage?.(msg.localThreadId, input))
+            const result = (await provider.injectMessage?.(msg.localThreadId, input, msg.options))
                 ?? { outcome: "notLive" };
             // App-server injection is independent of the Terminal TUI startup, so it
             // must not cancel prompt handling for the pane that is still starting.
@@ -413,6 +559,29 @@ export class RunnerSession {
             });
         }
     }
+    async updateCollaborationMode(msg) {
+        try {
+            if (!this.liveProvider.updateCollaborationMode) {
+                throw new AgentRuntimeError("Native collaboration mode is unavailable", 409, "collaboration_mode_unavailable");
+            }
+            await this.liveProvider.updateCollaborationMode(msg.localThreadId, msg.mode);
+            this.transport.send({
+                t: "collaboration.updated",
+                reqId: msg.reqId,
+                localThreadId: msg.localThreadId,
+                ok: true,
+            });
+        }
+        catch (error) {
+            this.transport.send({
+                t: "collaboration.updated",
+                reqId: msg.reqId,
+                localThreadId: msg.localThreadId,
+                ok: false,
+                error: toWireError(error),
+            });
+        }
+    }
     async interruptLive(msg) {
         const provider = this.liveProvider;
         let ok = false;
@@ -472,7 +641,7 @@ export class RunnerSession {
                         ? terminal.isAliveAsync().then((alive) => alive ? "alive" : "dead")
                         : Promise.resolve(terminal.isAlive() ? "alive" : "dead");
             void probe.then((liveness) => {
-                // A failed pane probe is inconclusive. Only Omnigent's lifecycle
+                // A failed pane probe is inconclusive. Only reference implementation's lifecycle
                 // evidence — capture target gone or explicit pane_dead — may fail it.
                 if (liveness !== "dead" ||
                     this.shuttingDown ||
@@ -600,6 +769,7 @@ export class RunnerSession {
         if (this.shuttingDown)
             return;
         this.shuttingDown = true;
+        this.rejectMirrorImageAcks(new Error("runner is shutting down"));
         this.stopLive();
         this.terminals.closeAll();
         this.liveProvider.finalizeStoppedLiveSessions?.();

package/dist/runner/manager.d.ts

@@ -16,7 +16,7 @@
  * channel.
  */
 import { spawn as nodeSpawn, type ChildProcess } from "node:child_process";
-import { type AdmissionReservation, type AgentCapabilities, type AgentRuntimeId, type AppConfig, type CapabilityResult, type ModelListResponse, type LiveSessionFailure, type InjectResult, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent, type SessionWorkspaceSnapshot, type ThreadGoal } from "@rynx-ai/core";
+import { type AdmissionReservation, type AgentCapabilities, type AgentRuntimeId, type AppConfig, type CapabilityResult, type ModelListResponse, type LiveSessionFailure, type InjectResult, type ResolvedExecutionSnapshot, type RuntimeTurnOptions, type RuntimeUserInput, type SessionCollaborationMode, type SessionInteractionResolution, type SessionEvent, type SessionWorkspaceSnapshot, type ThreadGoal } from "@rynx-ai/core";
 import { type CodexSessionStore } from "../host.js";
 import type { ResolveInteractionResult } from "../interactions.js";
 import { type TerminalOpenErrorCode, type TerminalRole } from "./protocol.js";
@@ -73,7 +73,7 @@ export interface RunnerManagerOptions {
      * created for the runner child, with direct-child fallback. */
     signalChild?: (child: ChildProcess, signal: NodeJS.Signals, processGroup: boolean) => void;
     /** Injected for tests. Best-effort close of the deterministic private tmux
-     * server owned by a Session runner; Omnigent does not verify/retry close. */
+     * server owned by a Session runner; reference implementation does not verify/retry close. */
     terminateTerminalServer?: (terminalName: string) => boolean | Promise<boolean>;
     /** Injected tmux `#{window_activity}` reader. Returns epoch seconds. */
     terminalWindowActivityAt?: (terminalName: string) => number | null | Promise<number | null>;
@@ -179,6 +179,9 @@ export declare class RunnerManager implements AgentCapabilities {
     private stopPromise;
     /** Sink for mirrored {@link SessionEvent}s from every session's forwarder. */
     private mirrorListener;
+    /** Synchronous persistence hook for native collaboration-mode reflection.
+     * It runs before the event reaches the Session bus. */
+    private collaborationModeListener;
     /** Sink for session rotations (claude `/clear`·`/fork`) — server records meta. */
     private rotateListener;
     /** Session keys with a live codex forwarder — never reaped while present. */
@@ -226,7 +229,8 @@ export declare class RunnerManager implements AgentCapabilities {
      * session's persistent codex forwarder (web- AND TUI-initiated turns). The
      * server wires this to `persistSessionEvent` (bus + canonical log).
      */
-    onMirror(listener: (sessionId: string, event: SessionEvent) => void): void;
+    onMirror(listener: (sessionId: string, event: SessionEvent) => void | Promise<void>): void;
+    onCollaborationMode(listener: (sessionId: string, mode: SessionCollaborationMode) => void): void;
     /** Register the sink for session rotations (claude `/clear`·`/fork`): the server
      *  records the new session's meta (carry-over agent/model/title). */
     onRotate(listener: (rotation: RotateInfo) => void | Promise<void>): void;
@@ -273,7 +277,7 @@ export declare class RunnerManager implements AgentCapabilities {
      * 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, input: RuntimeUserInput | string): Promise<InjectResult>;
+    injectMessage(localThreadId: string, input: RuntimeUserInput | string, options?: RuntimeTurnOptions): Promise<InjectResult>;
     private injectMessageAdmitted;
     /**
      * Interrupt a session's active live turn — the web Stop button (codex
@@ -283,6 +287,8 @@ export declare class RunnerManager implements AgentCapabilities {
     interruptLiveSession(localThreadId: string): Promise<boolean>;
     /** Resolve a native question/approval without ever spawning a new runner. */
     resolveInteraction(localThreadId: string, interactionId: string, resolution: SessionInteractionResolution): Promise<ResolveInteractionResult>;
+    /** Update a loaded Codex-lineage native thread without spawning a runner. */
+    updateCollaborationMode(localThreadId: string, mode: SessionCollaborationMode): Promise<void>;
     listModels(runtime?: AgentRuntimeId): Promise<ModelListResponse | null>;
     getGoal(localThreadId: string): Promise<CapabilityResult<ThreadGoal | null>>;
     setGoal(localThreadId: string, objective: string): Promise<CapabilityResult>;
@@ -325,6 +331,8 @@ export declare class RunnerManager implements AgentCapabilities {
     private bufferForkTargetMessage;
     private reservedForkTarget;
     private deliverForkBufferedMessage;
+    private deliverMirrorMessage;
+    private failMirrorImageTransfer;
     private deliverRotateMessage;
     private spawnHandle;
     private onChildMessage;