@parall/codex-agent 1.59.0 → 1.61.0

package/src/instructions-refresh.ts

@@ -80,7 +80,7 @@ export type RefreshOutcome =
   // turn/start rejection rotate the persisted main thread in this state.
   | 'stalled';
 
-class CompactionStalledError extends Error {}
+export class CompactionStalledError extends Error {}
 
 export class MainThreadInstructionsRefresher {
   /**
@@ -188,23 +188,14 @@ export class MainThreadInstructionsRefresher {
       return 'adopted-baseline';
     }
     if (this.compactUnsupported) return 'unsupported';
-    // The waiter registers its notification tap BEFORE the request goes out:
-    // the response and the compaction-turn notifications can arrive in one
-    // stdout chunk, and the client's line loop dispatches notifications
-    // synchronously — a tap registered only after `await sendRequest` resolves
-    // (a queued microtask) would miss every one of them and hang on the
-    // timeout.
-    const compaction = this.watchForCompaction(client, taps, threadId);
     try {
-      await client.sendRequest('thread/compact/start', { threadId });
-      await compaction.done;
+      await this.runCompaction({ client, taps, threadId });
       this.opts.sessionManager.recordEffectiveInstructionsSha(sessionKey, canonicalSha);
       log?.info?.(
         `platform instructions refreshed on persisted thread ${threadId} (compaction rebuilt initial context from the resumed configuration)`,
       );
       return 'refreshed';
     } catch (err) {
-      compaction.cancel();
       if (err instanceof CompactionStalledError) {
         log?.warn?.(
           `platform instructions refresh stalled (${errToString(err)}); bouncing the subprocess before the next turn`,
@@ -212,7 +203,6 @@ export class MainThreadInstructionsRefresher {
         return 'stalled';
       }
       if (err instanceof JsonRpcError && err.code === JSON_RPC_METHOD_NOT_FOUND) {
-        this.compactUnsupported = true;
         log?.warn?.(
           'thread/compact/start not supported by this codex CLI; the persisted thread keeps its previous platform instructions until it is replaced or the CLI is upgraded (tools still refresh live via the capability shim dir)',
         );
@@ -225,6 +215,57 @@ export class MainThreadInstructionsRefresher {
     }
   }
 
+  /** True once this subprocess rejected thread/compact/start with -32601. */
+  isCompactUnsupported(): boolean {
+    return this.compactUnsupported;
+  }
+
+  /**
+   * The unconditional compaction primitive — one `thread/compact/start`
+   * awaited to its turn close — shared by the instructions refresh (which
+   * decides WHETHER to run it by sha) and the idle auto-compact (which runs
+   * it whenever the server asks). Throws like the refresh's inner path:
+   * CompactionStalledError past budget/abort + interrupt grace, JsonRpcError
+   * -32601 (also latches compactUnsupported for this subprocess), or a plain
+   * Error for a turn that closed without compacting.
+   */
+  async runCompaction(args: {
+    client: JsonRpcStdioClient;
+    taps: NotificationTapSource;
+    threadId: string;
+    signal?: AbortSignal;
+  }): Promise<void> {
+    const { client, taps, threadId, signal } = args;
+    // The waiter registers its notification tap BEFORE the request goes out:
+    // the response and the compaction-turn notifications can arrive in one
+    // stdout chunk, and the client's line loop dispatches notifications
+    // synchronously — a tap registered only after `await sendRequest` resolves
+    // (a queued microtask) would miss every one of them and hang on the
+    // timeout.
+    const compaction = this.watchForCompaction(client, taps, threadId, signal);
+    try {
+      await client.sendRequest('thread/compact/start', { threadId });
+      await compaction.done;
+    } catch (err) {
+      compaction.cancel();
+      if (err instanceof JsonRpcError && err.code === JSON_RPC_METHOD_NOT_FOUND) {
+        this.compactUnsupported = true;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * A compaction that completed outside the refresh path (idle auto-compact)
+   * rebuilt the model-visible context from the canonical configuration: the
+   * effective plane now equals whatever this process opened the thread with.
+   */
+  recordCompacted(sessionKey: string, threadId: string): void {
+    const canonical = this.canonicalByThread.get(threadId);
+    if (canonical === undefined) return;
+    this.opts.sessionManager.recordEffectiveInstructionsSha(sessionKey, sha256Hex(canonical));
+  }
+
   /**
    * Compaction runs as its own turn on the thread:
    *   turn/started → item/started{contextCompaction} →
@@ -250,6 +291,7 @@ export class MainThreadInstructionsRefresher {
     client: JsonRpcStdioClient,
     taps: NotificationTapSource,
     threadId: string,
+    signal?: AbortSignal,
   ): { done: Promise<void>; cancel: () => void } {
     const timeoutMs = this.opts.compactTimeoutMs ?? DEFAULT_COMPACT_TIMEOUT_MS;
     const graceMs = this.opts.interruptGraceMs ?? COMPACT_INTERRUPT_GRACE_MS;
@@ -261,17 +303,24 @@ export class MainThreadInstructionsRefresher {
       let settled = false;
       let unregister = () => {};
       let graceTimer: NodeJS.Timeout | undefined;
+      const onAbort = () => expire('aborted by the caller');
       const finish = (err?: Error) => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
         if (graceTimer) clearTimeout(graceTimer);
+        signal?.removeEventListener('abort', onAbort);
         unregister();
         if (err) reject(err);
         else resolve();
       };
-      const timer = setTimeout(() => {
+      // Budget exhausted (timer) or the caller aborted (idle auto-compact
+      // budget): interrupt best-effort and hold the grace for the turn to
+      // close; past it the turn may still be running → stalled.
+      const expire = (why: string) => {
+        if (settled || interrupted) return;
         interrupted = true;
+        clearTimeout(timer);
         if (compactionTurnId) {
           // Best-effort and non-lethal: an unanswered interrupt must expire
           // with the grace window, not arm the client's default assume-hung
@@ -288,12 +337,15 @@ export class MainThreadInstructionsRefresher {
           () =>
             finish(
               new CompactionStalledError(
-                `compaction did not complete within ${timeoutMs}ms (interrupt grace elapsed; the compaction turn may still be running)`,
+                `compaction did not complete (${why}; interrupt grace elapsed; the compaction turn may still be running)`,
               ),
             ),
           graceMs,
         );
-      }, timeoutMs);
+      };
+      const timer = setTimeout(() => expire(`within ${timeoutMs}ms`), timeoutMs);
+      if (signal?.aborted) onAbort();
+      else signal?.addEventListener('abort', onAbort, { once: true });
       // Cancellation resolves (never rejects): the caller cancels only when
       // the request itself already failed, and that error is what it reports.
       cancel = () => finish();
@@ -305,8 +357,28 @@ export class MainThreadInstructionsRefresher {
           // notifications can arrive after that; waiting out the timeout
           // would stall the dispatch for the full budget on a dead client.
           if (notificationThreadId === undefined || notificationThreadId === threadId) {
-            const msg = (params as { message?: unknown })?.message;
-            finish(new Error(`app-server error during compaction: ${String(msg ?? 'unknown')}`));
+            // v2 ErrorNotification: { threadId?, turnId?, error: { message,
+            // codexErrorInfo? }, willRetry }. The adapter's synthetic
+            // disposal broadcast still carries a top-level `message`.
+            const p = params as {
+              message?: unknown;
+              willRetry?: unknown;
+              error?: { message?: unknown; codexErrorInfo?: unknown };
+            };
+            // A retryable error keeps the turn alive — codex retries the
+            // model call itself and the compaction still completes or fails
+            // through turn/completed; bailing here would report a failure
+            // for a compaction that is still running.
+            if (p?.willRetry === true) return;
+            const msg = p?.error?.message ?? p?.message;
+            const info = p?.error?.codexErrorInfo;
+            const infoText =
+              info == null ? '' : ` (${typeof info === 'string' ? info : JSON.stringify(info)})`;
+            finish(
+              new Error(
+                `app-server error during compaction: ${String(msg ?? 'unknown')}${infoText}`,
+              ),
+            );
           }
           return;
         }
@@ -326,7 +398,7 @@ export class MainThreadInstructionsRefresher {
             finish(
               new Error(
                 interrupted
-                  ? `compaction did not complete within ${timeoutMs}ms (turn closed after interrupt)`
+                  ? 'compaction did not complete within budget (turn closed after interrupt)'
                   : `compaction turn ended without completing (status=${status ?? 'unknown'})`,
               ),
             );

package/src/runtime-turn.ts

@@ -0,0 +1,64 @@
+import {
+  projectRuntimeEvent,
+  type RuntimeEvent,
+  RuntimeTurnBase,
+  type RuntimeTurnTrigger,
+} from '@parall/agent-core';
+import { TurnSink } from './turn-sink.js';
+
+/**
+ * One turn of a thread the app-server runs that no dispatch started — a
+ * `spawn_agent` subagent thread. Its notifications are routed into `sink`
+ * by the adapter; the gateway drains `events` as a turn of the subagent's
+ * child session (the first event announces that session with its parent).
+ */
+export class CodexRuntimeTurn extends RuntimeTurnBase {
+  readonly sink: TurnSink;
+
+  constructor(
+    sessionKey: string,
+    readonly trigger: Extract<RuntimeTurnTrigger, { kind: 'subagent' }>,
+    private readonly opts: {
+      parentSessionKey?: string;
+      onDetach: (reason: string) => void;
+    },
+  ) {
+    super(sessionKey, trigger, opts.onDetach);
+    this.sink = new TurnSink(() => this.touch());
+  }
+
+  protected async *drain(): AsyncGenerator<RuntimeEvent> {
+    yield {
+      type: 'runtime_session',
+      runtimeSessionId: this.trigger.threadId,
+      runtimeLaneKey: this.sessionKey,
+      ...(this.opts.parentSessionKey ? { parentSessionKey: this.opts.parentSessionKey } : {}),
+    };
+    let sawError = false;
+    let sawOutcome = false;
+    while (true) {
+      const envelope = await this.sink.next();
+      if (envelope.kind === 'turn_end') {
+        // A real turn/completed carries its threadId; the sink's close()
+        // sentinel does not — the thread died or the bridge stopped.
+        if (envelope.threadId) return;
+        if (!sawError) {
+          yield {
+            type: 'error',
+            message: 'subagent turn ended without turn/completed',
+            groupKey: this.groupKey,
+          };
+        }
+        if (!sawOutcome) yield { type: 'turn_outcome', outcome: 'runtime_crash' };
+        return;
+      }
+      const event =
+        envelope.kind === 'error'
+          ? { type: 'error' as const, message: envelope.message }
+          : envelope.event;
+      if (event.type === 'error') sawError = true;
+      if (event.type === 'turn_outcome') sawOutcome = true;
+      yield projectRuntimeEvent(event, this.groupKey);
+    }
+  }
+}

package/src/session-manager.ts

@@ -51,6 +51,12 @@ export class CodexSessionManager {
     return this.threadIds.get(sessionKey);
   }
 
+  /** The session (main or fork) that owns a thread the bridge opened. */
+  getSessionKey(threadId: string): string | undefined {
+    for (const [sessionKey, id] of this.threadIds) if (id === threadId) return sessionKey;
+    return undefined;
+  }
+
   recordThreadId(sessionKey: string, threadId: string) {
     // An effective-instructions sha is a fact about one specific thread.
     // Recording a DIFFERENT thread id under the same session invalidates it;

package/src/turn-sink.ts

@@ -1,4 +1,5 @@
 import type { RuntimeEvent } from '@parall/agent-core';
+import { AsyncQueue } from '@parall/agent-core/internal/async-queue';
 import { EventMapper } from './event-mapping.js';
 
 export type TurnEventEnvelope =
@@ -6,12 +7,14 @@ export type TurnEventEnvelope =
   | { kind: 'turn_end'; threadId?: string }
   | { kind: 'error'; message: string };
 
-/** Per-turn buffered sink backed by an unbounded promise queue. */
+/**
+ * Per-turn buffered sink between notification routing and the turn's
+ * drain. Envelopes queued before close() still drain (a final error pushed
+ * by handleSubprocessClose must reach the consumer before turn_end).
+ */
 export class TurnSink {
   readonly mapper = new EventMapper();
-  private readonly queue: TurnEventEnvelope[] = [];
-  private resolver: ((value: TurnEventEnvelope) => void) | null = null;
-  private closed = false;
+  private readonly queue = new AsyncQueue<TurnEventEnvelope>();
 
   constructor(private readonly noteActivity?: () => void) {}
 
@@ -20,41 +23,21 @@ export class TurnSink {
   }
 
   push(envelope: TurnEventEnvelope) {
-    if (this.closed) return;
-    if (this.resolver) {
-      const r = this.resolver;
-      this.resolver = null;
-      r(envelope);
-      return;
-    }
     this.queue.push(envelope);
   }
 
-  next(): Promise<TurnEventEnvelope> {
-    // Drain any queued envelopes first, even after close(). Otherwise a final
-    // error envelope enqueued right before close() (e.g. by
-    // handleSubprocessClose) is silently dropped because the consumer would
-    // see turn_end before it.
-    const pending = this.queue.shift();
-    if (pending) return Promise.resolve(pending);
-    if (this.closed) {
-      return Promise.resolve({ kind: 'turn_end' });
-    }
-    return new Promise((resolve) => {
-      this.resolver = resolve;
-    });
+  async next(): Promise<TurnEventEnvelope> {
+    const result = await this.queue.next();
+    return result.done ? { kind: 'turn_end' } : result.value;
   }
 
   close() {
-    this.closed = true;
-    const r = this.resolver;
-    this.resolver = null;
-    r?.({ kind: 'turn_end' });
+    this.queue.close();
   }
 
   /** True once close() ran — the sink's terminal state (queued envelopes may
    * still drain via next()). */
   get isClosed(): boolean {
-    return this.closed;
+    return this.queue.isClosed;
   }
 }