@rynx-ai/runtime 0.1.9 → 0.1.10-beta.3

package/dist/claude/transcript.js

@@ -121,6 +121,17 @@ export function parseTranscriptRecord(record, opts) {
         return [];
     const out = [];
     if (rec.type === "assistant" && message.role === "assistant") {
+        // Claude writes this zero-token synthetic filler after an accidental empty
+        // submit. It is transcript bookkeeping, not an assistant response. Filter
+        // by provider provenance and exact shape here, before normalization loses
+        // `model: "<synthetic>"`; a UI string filter could hide legitimate output.
+        if (!rec.isApiErrorMessage &&
+            message.model === "<synthetic>" &&
+            message.content.length === 1 &&
+            message.content[0]?.type === "text" &&
+            message.content[0].text === "No response requested.") {
+            return [];
+        }
         const itemId = message.id;
         const texts = [];
         for (const block of message.content) {

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

@@ -1,4 +1,5 @@
-import type { SessionItem } from "@rynx-ai/core";
+import { type SessionItem } from "@rynx-ai/core";
+import { type CodexLineageRuntime } from "../codex-home.js";
 export interface SynthesizeRolloutOptions {
     threadId: string;
     cwd: string;
@@ -8,6 +9,10 @@ export interface SynthesizeRolloutOptions {
     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;
@@ -22,8 +27,8 @@ interface RolloutRecord {
     type: "session_meta" | "turn_context" | "response_item" | "event_msg";
     payload: Record<string, unknown>;
 }
-/** Locate an existing rollout for `threadId` under `<codexHome>/sessions/**`. */
-export declare function findCodexRollout(codexHome: string, threadId: string): string | null;
+/** 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[];

package/dist/codex/rollout-synth.js

@@ -13,14 +13,19 @@
  * (codex ≥0.136 renders an empty thread without them). `turn_context` groups items
  * into turns.
  */
+import { createHash } from "node:crypto";
 import { copyFileSync, mkdirSync, readdirSync, renameSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
-import { codexHomePath, legacyCodexHomePath } from "../codex-home.js";
+import { getRuntimeProfile, resolveRuntimeHome, rynxHome, } from "@rynx-ai/core";
+import { legacyCodexHomePath, runtimeHomePath, } from "../codex-home.js";
 /** codex validates the thread id straight into a filename + resume arg. */
 const THREAD_ID_RE = /^[0-9a-fA-F-]+$/;
-/** Locate an existing rollout for `threadId` under `<codexHome>/sessions/**`. */
-export function findCodexRollout(codexHome, threadId) {
-    const root = join(codexHome, "sessions");
+function sessionsRoot(runtimeHome, runtime) {
+    return join(runtimeHome, ...getRuntimeProfile(runtime).sessionsSubpath);
+}
+/** Locate an existing rollout for `threadId` under the runtime's sessions root. */
+export function findCodexRollout(runtimeHome, threadId, runtime = "codex") {
+    const root = sessionsRoot(runtimeHome, runtime);
     const suffix = `-${threadId}.jsonl`;
     const stack = [root];
     while (stack.length) {
@@ -49,18 +54,21 @@ export function findCodexRollout(codexHome, threadId) {
  * expects) so the per-session app-server can resume it. Best-effort; gated by
  * `RYNX_CODEX_HOME_LEGACY_FALLBACK` (default on; set `0`/`false` to disable).
  */
-function adoptLegacyRollout(codexHome, threadId) {
-    const flag = process.env.RYNX_CODEX_HOME_LEGACY_FALLBACK?.trim().toLowerCase();
+function adoptLegacyRollout(runtimeHome, threadId, runtime) {
+    const flag = (process.env.RYNX_RUNTIME_HOME_LEGACY_FALLBACK
+        ?? process.env.RYNX_CODEX_HOME_LEGACY_FALLBACK)?.trim().toLowerCase();
     if (flag === "0" || flag === "false")
         return false;
-    const legacy = legacyCodexHomePath();
-    if (legacy === codexHome)
+    const legacy = runtime === "codex"
+        ? legacyCodexHomePath()
+        : resolveRuntimeHome(getRuntimeProfile(runtime));
+    if (legacy === runtimeHome)
         return false;
-    const src = findCodexRollout(legacy, threadId);
+    const src = findCodexRollout(legacy, threadId, runtime);
     if (!src)
         return false;
-    const rel = relative(join(legacy, "sessions"), src);
-    const dst = join(codexHome, "sessions", rel);
+    const rel = relative(sessionsRoot(legacy, runtime), src);
+    const dst = join(sessionsRoot(runtimeHome, runtime), rel);
     try {
         mkdirSync(join(dst, ".."), { recursive: true, mode: 0o700 });
         copyFileSync(src, dst);
@@ -79,7 +87,10 @@ function turnIdOf(responseId) {
     return responseId.startsWith("resp_codex_") ? responseId.slice("resp_codex_".length) : responseId;
 }
 function textOf(item) {
-    return item.data.content.map((p) => p.text).join("");
+    return item.data.content
+        .filter((part) => "text" in part)
+        .map((part) => part.text)
+        .join("");
 }
 /** Convert one canonical {@link SessionItem} to its codex `response_item` payload,
  *  or null for types codex doesn't carry (reasoning/terminal_command/error). */
@@ -87,9 +98,9 @@ function responseItemPayload(item) {
     switch (item.type) {
         case "message": {
             const apiType = item.data.role === "assistant" ? "output_text" : "input_text";
-            const content = item.data.content
-                .filter((p) => p.text)
-                .map((p) => ({ type: apiType, text: p.text }));
+            const content = item.data.content.flatMap((part) => "text" in part && part.text
+                ? [{ type: apiType, text: part.text }]
+                : []);
             if (content.length === 0)
                 return null;
             return { type: "message", role: item.data.role, content };
@@ -108,23 +119,41 @@ function responseItemPayload(item) {
     }
 }
 /** The `event_msg` mirror for a message (required for a VISIBLE turn on codex ≥0.136). */
-function eventMsgPayload(item) {
+function eventMsgPayload(item, sessionId) {
     const message = textOf(item).trim();
-    if (!message)
+    const localImages = item.data.role === "user" && sessionId
+        ? item.data.content.flatMap((part) => part.type === "input_image" ? [resourcePath(sessionId, part)] : [])
+        : [];
+    if (!message && localImages.length === 0)
         return null;
     if (item.data.role === "user") {
-        return { type: "user_message", message, images: [], local_images: [], text_elements: [] };
+        return {
+            type: "user_message",
+            message,
+            images: [],
+            local_images: localImages,
+            text_elements: [],
+        };
     }
     if (item.data.role === "assistant") {
         return { type: "agent_message", message, phase: "final_answer", memory_citation: null };
     }
     return null;
 }
+function resourcePath(sessionId, part) {
+    const sessionKey = createHash("sha256").update(sessionId).digest("hex").slice(0, 32);
+    const extension = part.mediaType === "image/png"
+        ? "png"
+        : part.mediaType === "image/jpeg"
+            ? "jpg"
+            : "webp";
+    return join(rynxHome(), "resources", sessionKey, `${part.resourceId}.${extension}`);
+}
 /** Build the ordered rollout records (session_meta first, then per-turn
  *  turn_context + per-item response_item + per-message event_msg). */
 export function buildRolloutRecords(opts) {
     const now = opts.now ?? (() => Date.now());
-    const modelProvider = opts.modelProvider ?? "openai";
+    const modelProvider = opts.modelProvider ?? (opts.runtime === "traex" ? "trae" : "openai");
     const cliVersion = opts.cliVersion ?? "0.0.0";
     const metaTs = iso(opts.items[0]?.createdAt ?? now());
     const records = [
@@ -147,7 +176,10 @@ export function buildRolloutRecords(opts) {
     const seenTurns = new Set();
     for (const item of opts.items) {
         const payload = responseItemPayload(item);
-        if (!payload)
+        const eventPayload = item.type === "message"
+            ? eventMsgPayload(item, opts.sessionId)
+            : null;
+        if (!payload && !eventPayload)
             continue;
         const ts = iso(item.createdAt);
         const turnId = turnIdOf(item.responseId);
@@ -159,12 +191,10 @@ export function buildRolloutRecords(opts) {
                 payload: { turn_id: turnId, cwd: opts.cwd, approval_policy: "on-request" },
             });
         }
-        records.push({ timestamp: ts, type: "response_item", payload });
-        if (item.type === "message") {
-            const evt = eventMsgPayload(item);
-            if (evt)
-                records.push({ timestamp: ts, type: "event_msg", payload: evt });
-        }
+        if (payload)
+            records.push({ timestamp: ts, type: "response_item", payload });
+        if (eventPayload)
+            records.push({ timestamp: ts, type: "event_msg", payload: eventPayload });
     }
     return records;
 }
@@ -177,14 +207,17 @@ export function buildRolloutRecords(opts) {
 export function ensureCodexResumeRollout(opts) {
     if (!THREAD_ID_RE.test(opts.threadId))
         return "skipped";
-    const codexHome = opts.codexHome ?? (opts.sessionId ? codexHomePath(opts.sessionId) : undefined);
-    if (!codexHome)
+    const runtime = opts.runtime ?? "codex";
+    const runtimeHome = opts.runtimeHome
+        ?? opts.codexHome
+        ?? (opts.sessionId ? runtimeHomePath(opts.sessionId, runtime) : undefined);
+    if (!runtimeHome)
         return "skipped"; // no session context → can't locate the home
-    if (findCodexRollout(codexHome, opts.threadId))
+    if (findCodexRollout(runtimeHome, opts.threadId, runtime))
         return "exists";
     // Back-compat: a pre-per-session rollout may live under the OLD shared home. Copy
     // it forward into this session's home so the per-session app-server can resume it.
-    if (adoptLegacyRollout(codexHome, opts.threadId))
+    if (adoptLegacyRollout(runtimeHome, opts.threadId, runtime))
         return "exists";
     const records = buildRolloutRecords(opts);
     // Nothing but the session_meta header → no history to carry; skip (a fresh
@@ -197,7 +230,7 @@ export function ensureCodexResumeRollout(opts) {
     const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
     const dd = String(d.getUTCDate()).padStart(2, "0");
     const stamp = iso(d.getTime()).slice(0, 19).replace(/:/g, "-"); // YYYY-MM-DDTHH-MM-SS
-    const dir = join(codexHome, "sessions", yyyy, mm, dd);
+    const dir = join(sessionsRoot(runtimeHome, runtime), yyyy, mm, dd);
     const target = join(dir, `rollout-${stamp}-${opts.threadId}.jsonl`);
     const tmp = `${target}.tmp`;
     try {

package/dist/codex-app-server/client.d.ts

@@ -1,4 +1,4 @@
-import type { SessionInteractionResolution } from "@rynx-ai/core";
+import type { RuntimeUserInput, SessionInteractionResolution } from "@rynx-ai/core";
 import type { AskForApproval, ClientInfo, CollaborationModeListResponse, GetAuthStatusParams, GetAuthStatusResponse, InitializeResponse, ModelListParams, ModelListResponse, ReviewStartParams, ReviewStartResponse, SandboxMode, ThreadForkParams, ThreadGoalClearParams, ThreadGoalGetParams, ThreadGoalGetResponse, ThreadGoalSetParams, ThreadListParams, ThreadListResponse, ResumedThread, ThreadResumeParams, ThreadSettingsUpdateParams, ThreadStartParams, TurnInterruptParams, TurnStartParams, TurnSteerParams, UserInput } from "./protocol.js";
 import { CodexAppServerTransport, type CodexAppServerProcessSpawner, type RpcChannel, type TransportLogger } from "./transport.js";
 import type { ResolveInteractionResult, RuntimeInteractionListener } from "../interactions.js";
@@ -121,4 +121,5 @@ export interface BuildSandboxPolicyOptions {
  */
 export declare function buildSandboxPolicy(options: BuildSandboxPolicyOptions): Record<string, unknown>;
 export declare function buildTextUserInput(message: string): UserInput[];
+export declare function buildRuntimeUserInput(input: RuntimeUserInput): UserInput[];
 export type { AskForApproval };

package/dist/codex-app-server/client.js

@@ -549,6 +549,7 @@ function buildCodexInteraction(method, params, nativeRequestId) {
                         label: question.question,
                         description: question.header || undefined,
                         required: true,
+                        ...(question.multiSelect ? { multiple: true } : {}),
                         allowOther: question.isOther,
                         options: options.map((option) => ({
                             value: option.label,
@@ -1359,6 +1360,11 @@ export function buildSandboxPolicy(options) {
 export function buildTextUserInput(message) {
     return [{ type: "text", text: message, text_elements: [] }];
 }
+export function buildRuntimeUserInput(input) {
+    return input.content.map((part) => part.type === "text"
+        ? { type: "text", text: part.text, text_elements: [] }
+        : { type: "localImage", path: part.path });
+}
 const defaultLogger = {
     log(entry) {
         console.log(JSON.stringify({

package/dist/codex-app-server/forwarder.d.ts

@@ -21,7 +21,7 @@
  * {@link CodexSessionForwarder.replayBackfill}. Backfill and the live stream are
  * de-duplicated by codex item id.
  */
-import type { AgentEvent } from "@rynx-ai/core";
+import type { AgentEvent, UserContentPart } from "@rynx-ai/core";
 import type { CodexAppServerClient } from "./client.js";
 import type { ResumedTurn } from "./protocol.js";
 export interface CodexForwarderSink {
@@ -36,7 +36,7 @@ export interface CodexForwarderSink {
     onTurnError(error: Error): void;
     /** The user's turn text (sourced from codex's `userMessage` item), so a
      *  co-driving TUI's prompt is recorded even though this process never injected it. */
-    onUserMessage?(text: string): void;
+    onUserMessage?(content: string | UserContentPart[]): void;
     /** A thread was announced on the app-server (a `--remote` TUI creating a thread,
      *  or a resume). The host persists the id + starts the subscribe loop. */
     onThreadStarted?(threadId: string): void;
@@ -44,14 +44,31 @@ export interface CodexForwarderSink {
      *  Fired once; lets a parked `thread/resume` retry (reference implementation's ready signal). */
     onThreadActive?(): void;
 }
+export interface CodexSessionForwarderOptions {
+    /** Some Codex-lineage runtimes publish the final item one frame after
+     * `turn/completed`. Keep the Turn open briefly so that item cannot create a
+     * second, permanently-running response. */
+    turnCompletionGraceMs?: number;
+    /** Some runtimes complete the final assistant message before publishing the
+     * preceding reasoning item. Briefly hold that message so canonical item order
+     * remains reasoning -> final answer. */
+    assistantMessageGraceMs?: number;
+    /** Surface Traex's provider-capacity queue as a canonical running status. */
+    surfaceQueueStatus?: boolean;
+}
 export declare class CodexSessionForwarder {
     private readonly client;
     private readonly sink;
+    private readonly options;
     private unsubscribe;
     private turnOpen;
     private currentTurnIdValue;
     private currentThreadIdValue;
     private activeSignaled;
+    private completionTimer;
+    private assistantMessageTimer;
+    private deferredAssistantMessage;
+    private pendingCompletion;
     /** Completed-item dedup keys already mirrored (live vs resume backfill). Key =
      *  `threadId:turnId:item.id`; anonymous items use a per-(thread,turn) position
      *  counter. Mirrors reference implementation `_completed_item_key` + `synced_item_keys`. */
@@ -59,7 +76,7 @@ export declare class CodexSessionForwarder {
     /** Per-(thread,turn) position counter for items lacking a stable codex id
      *  (peek-then-advance; advanced only on a successful claim). reference implementation anon path. */
     private readonly anonCounters;
-    constructor(client: CodexAppServerClient, sink: CodexForwarderSink);
+    constructor(client: CodexAppServerClient, sink: CodexForwarderSink, options?: CodexSessionForwarderOptions);
     /** Begin mirroring. Idempotent. */
     start(): void;
     stop(): void;
@@ -78,9 +95,18 @@ export declare class CodexSessionForwarder {
      */
     replayBackfill(turns: ResumedTurn[]): void;
     private handle;
+    private scheduleCompletion;
+    private refreshCompletionGrace;
+    private flushPendingCompletion;
+    private settle;
     /** Map + emit one completed codex item, deduped by a TOTAL key and routing the
      *  user echo to {@link CodexForwarderSink.onUserMessage}. Shared by live + backfill. */
     private processCompletedItem;
+    private claimCompletedItem;
+    private emitCompletedItem;
+    private shouldDeferAssistantMessage;
+    private deferAssistantMessage;
+    private flushDeferredAssistantMessage;
     /** Build a total dedup key for one completed item. Stable-id items use
      *  `threadId:turnId:item.id` — identical across replay + live, so the second
      *  delivery is dropped. Items without a codex id fall back to a per-(thread,turn)

package/dist/codex-app-server/forwarder.js

@@ -1,3 +1,4 @@
+import { codexUserContent } from "../input-resources.js";
 import { mapCodexItem, mapCodexNotification } from "./mapping.js";
 function threadIdFrom(params) {
     const p = params;
@@ -7,16 +8,17 @@ function turnIdFrom(params) {
     const p = params;
     return p?.turnId ?? p?.turn?.id;
 }
-function userMessageText(item) {
+function userMessageContent(item) {
     if (item.type !== "userMessage")
         return undefined;
-    const content = item.content ?? [];
-    const text = content
-        .filter((c) => c.type === "text" && typeof c.text === "string")
-        .map((c) => c.text)
-        .join("")
-        .trim();
-    return text || undefined;
+    const parts = codexUserContent(item.content);
+    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;
 }
 /** Whether a notification implies the thread is now active (its first turn has
  *  begun, so the rollout exists). Mirrors reference implementation's `_event_indicates_thread_active`. */
@@ -32,11 +34,16 @@ function indicatesActive(method, params) {
 export class CodexSessionForwarder {
     client;
     sink;
+    options;
     unsubscribe = null;
     turnOpen = false;
     currentTurnIdValue = null;
     currentThreadIdValue = null;
     activeSignaled = false;
+    completionTimer = null;
+    assistantMessageTimer = null;
+    deferredAssistantMessage = null;
+    pendingCompletion = null;
     /** Completed-item dedup keys already mirrored (live vs resume backfill). Key =
      *  `threadId:turnId:item.id`; anonymous items use a per-(thread,turn) position
      *  counter. Mirrors reference implementation `_completed_item_key` + `synced_item_keys`. */
@@ -44,9 +51,10 @@ export class CodexSessionForwarder {
     /** Per-(thread,turn) position counter for items lacking a stable codex id
      *  (peek-then-advance; advanced only on a successful claim). reference implementation anon path. */
     anonCounters = new Map();
-    constructor(client, sink) {
+    constructor(client, sink, options = {}) {
         this.client = client;
         this.sink = sink;
+        this.options = options;
     }
     /** Begin mirroring. Idempotent. */
     start() {
@@ -59,6 +67,8 @@ export class CodexSessionForwarder {
     stop() {
         this.unsubscribe?.();
         this.unsubscribe = null;
+        this.flushPendingCompletion();
+        this.flushDeferredAssistantMessage();
         if (this.turnOpen) {
             this.turnOpen = false;
             this.sink.onTurnEnd();
@@ -116,58 +126,160 @@ export class CodexSessionForwarder {
             this.activeSignaled = true;
             this.sink.onThreadActive?.();
         }
+        // `queue/status` is a Traex extension. Keep the shared Codex forwarder
+        // behavior unchanged unless the Traex host explicitly opts in.
+        if (method === "queue/status" && !this.options.surfaceQueueStatus)
+            return;
         const carriedTurnId = turnIdFrom(params);
-        if (carriedTurnId)
-            this.currentTurnIdValue = carriedTurnId;
         if (method === "turn/started") {
+            this.flushPendingCompletion();
+            this.flushDeferredAssistantMessage();
+            if (carriedTurnId)
+                this.currentTurnIdValue = carriedTurnId;
             this.ensureTurn();
             return;
         }
+        if (carriedTurnId)
+            this.currentTurnIdValue = carriedTurnId;
         // Completed items (user echo, assistant, tool, reasoning) go through the
         // deduped path so a resume backfill and the live stream never double them.
         if (method === "item/completed") {
             const item = params?.item;
             if (item) {
+                if (this.shouldDeferAssistantMessage(item)) {
+                    this.deferAssistantMessage(item);
+                    this.refreshCompletionGrace();
+                    return;
+                }
+                // A late reasoning item belongs before the held final answer. Any other
+                // completed item establishes that the held message was not final and
+                // must retain its original position.
+                if (item.type !== "reasoning")
+                    this.flushDeferredAssistantMessage();
                 this.processCompletedItem(item);
+                this.refreshCompletionGrace();
                 return;
             }
         }
         const mapped = mapCodexNotification(method, params);
-        if (mapped.events.length || mapped.turnCompleted || mapped.fatalError) {
+        // Provider startup/onboarding notifications that rynx does not model map
+        // to runtime_debug. They are telemetry, not evidence of a model Turn. In
+        // particular, Traex emits hook-trust lifecycle notifications while merely
+        // resuming a TUI; opening a response for those leaves Chat permanently
+        // running because no turn/completed will follow.
+        const canonicalEvents = mapped.events.filter((event) => event.type !== "runtime_debug");
+        if (canonicalEvents.some((event) => event.type !== "reasoning_delta" && event.type !== "reasoning_completed")) {
+            this.flushDeferredAssistantMessage();
+        }
+        if (canonicalEvents.length || mapped.turnCompleted || mapped.fatalError) {
             this.ensureTurn();
         }
-        for (const event of mapped.events) {
+        for (const event of canonicalEvents) {
             this.sink.onEvent(event);
         }
         if (mapped.fatalError) {
-            this.turnOpen = false;
-            this.sink.onTurnError(mapped.fatalError);
+            this.scheduleCompletion({ kind: "error", error: mapped.fatalError });
             return;
         }
         if (mapped.turnCompleted) {
-            this.turnOpen = false;
-            this.sink.onTurnEnd(mapped.usage);
+            this.scheduleCompletion({ kind: "end", ...(mapped.usage ? { usage: mapped.usage } : {}) });
+        }
+        else {
+            this.refreshCompletionGrace();
+        }
+    }
+    scheduleCompletion(completion) {
+        const graceMs = this.options.turnCompletionGraceMs ?? 0;
+        if (graceMs <= 0) {
+            this.settle(completion);
+            return;
         }
+        this.pendingCompletion = completion;
+        this.refreshCompletionGrace();
+    }
+    refreshCompletionGrace() {
+        if (!this.pendingCompletion)
+            return;
+        const graceMs = this.options.turnCompletionGraceMs ?? 0;
+        if (graceMs <= 0)
+            return;
+        if (this.completionTimer)
+            clearTimeout(this.completionTimer);
+        this.completionTimer = setTimeout(() => this.flushPendingCompletion(), graceMs);
+        this.completionTimer.unref?.();
+    }
+    flushPendingCompletion() {
+        if (this.completionTimer)
+            clearTimeout(this.completionTimer);
+        this.completionTimer = null;
+        const completion = this.pendingCompletion;
+        this.pendingCompletion = null;
+        if (completion)
+            this.settle(completion);
+    }
+    settle(completion) {
+        this.flushDeferredAssistantMessage();
+        this.turnOpen = false;
+        if (completion.kind === "error")
+            this.sink.onTurnError(completion.error);
+        else
+            this.sink.onTurnEnd(completion.usage);
     }
     /** Map + emit one completed codex item, deduped by a TOTAL key and routing the
      *  user echo to {@link CodexForwarderSink.onUserMessage}. Shared by live + backfill. */
     processCompletedItem(item) {
+        if (!this.claimCompletedItem(item))
+            return;
+        this.emitCompletedItem(item);
+    }
+    claimCompletedItem(item) {
         const { key, isAnon } = this.completedItemKey(item);
         if (this.seenCompletedItems.has(key))
-            return;
+            return false;
         this.seenCompletedItems.add(key);
         if (isAnon)
             this.advanceAnonCounter();
-        this.ensureTurn();
-        const userText = userMessageText(item);
-        if (userText !== undefined) {
-            this.sink.onUserMessage?.(userText);
+        return true;
+    }
+    emitCompletedItem(item) {
+        const userContent = userMessageContent(item);
+        if (userContent !== undefined) {
+            this.ensureTurn();
+            this.sink.onUserMessage?.(userContent);
             return;
         }
         const mapped = mapCodexItem("item/completed", item);
-        for (const event of mapped.events)
+        const canonicalEvents = mapped.events.filter((event) => event.type !== "runtime_debug");
+        if (canonicalEvents.length === 0)
+            return;
+        this.ensureTurn();
+        for (const event of canonicalEvents)
             this.sink.onEvent(event);
     }
+    shouldDeferAssistantMessage(item) {
+        if ((this.options.assistantMessageGraceMs ?? 0) <= 0 || item.type !== "agentMessage") {
+            return false;
+        }
+        return Boolean(item.text?.trim());
+    }
+    deferAssistantMessage(item) {
+        if (!this.claimCompletedItem(item))
+            return;
+        this.flushDeferredAssistantMessage();
+        this.deferredAssistantMessage = item;
+        const graceMs = this.options.assistantMessageGraceMs ?? 0;
+        this.assistantMessageTimer = setTimeout(() => this.flushDeferredAssistantMessage(), graceMs);
+        this.assistantMessageTimer.unref?.();
+    }
+    flushDeferredAssistantMessage() {
+        if (this.assistantMessageTimer)
+            clearTimeout(this.assistantMessageTimer);
+        this.assistantMessageTimer = null;
+        const item = this.deferredAssistantMessage;
+        this.deferredAssistantMessage = null;
+        if (item)
+            this.emitCompletedItem(item);
+    }
     /** Build a total dedup key for one completed item. Stable-id items use
      *  `threadId:turnId:item.id` — identical across replay + live, so the second
      *  delivery is dropped. Items without a codex id fall back to a per-(thread,turn)

package/dist/codex-app-server/mapping.js

@@ -8,6 +8,27 @@ function turnError(error, fallback) {
     }
     return new Error(fallback);
 }
+function webSearchInput(item) {
+    const action = item.action;
+    if (action?.type === "search") {
+        return {
+            id: item.id,
+            query: action.query || item.query,
+            ...(action.queries?.length ? { queries: action.queries } : {}),
+        };
+    }
+    if (action?.type === "openPage") {
+        return { id: item.id, url: action.url ?? "" };
+    }
+    if (action?.type === "findInPage") {
+        return {
+            id: item.id,
+            url: action.url ?? "",
+            pattern: action.pattern ?? "",
+        };
+    }
+    return { id: item.id, query: item.query };
+}
 /** Map one thread item (`item/started` | `item/completed`) to events. */
 export function mapCodexItem(method, item) {
     const events = [];
@@ -78,13 +99,15 @@ export function mapCodexItem(method, item) {
             return { events };
         }
         case "webSearch": {
+            const webSearch = item;
             events.push({
                 type: "tool",
                 event: isStart ? "on_tool_start" : "on_tool_end",
                 name: "web_search",
-                input: isStart
-                    ? { id: item.id, query: item.query }
-                    : undefined,
+                // `item/started` commonly has an empty top-level query. The completed
+                // item carries the real operation in `action`; pass that richer input
+                // through so the canonical layer can append a same-call argument update.
+                input: isStart || isEnd ? webSearchInput(webSearch) : undefined,
                 output: isEnd ? { id: item.id } : undefined,
                 data: { method, item },
             });
@@ -199,6 +222,17 @@ export function mapCodexNotification(method, params) {
             const p = typed.params;
             return { events, usage: p.tokenUsage };
         }
+        case "queue/status": {
+            const p = typed.params;
+            if (p.state === "ready") {
+                events.push({ type: "status" });
+                return { events };
+            }
+            const note = p.message?.trim()
+                || (p.position === null ? "Waiting for provider capacity." : `Your queue position is ${p.position}.`);
+            events.push({ type: "status", statusKind: "queue", note });
+            return { events };
+        }
         case "error": {
             const p = typed.params;
             if (p.willRetry) {