@parall/codex-agent 1.59.0 → 1.61.0

package/src/app-server-protocol.ts

@@ -34,6 +34,43 @@ export function extractTurnId(result: unknown): string | undefined {
   return undefined;
 }
 
+/**
+ * The `thread` object a `thread/started` notification carries. Subagent
+ * threads (`spawn_agent`) report `threadSource: "subAgent"` plus the parent
+ * thread and the agent's nickname/role; other fields are tolerated absent.
+ */
+export type CodexThreadInfo = {
+  id: string;
+  parentThreadId?: string;
+  source?: string;
+  nickname?: string;
+  role?: string;
+};
+
+export function extractThreadInfo(params: unknown): CodexThreadInfo | undefined {
+  if (!params || typeof params !== 'object') return undefined;
+  const p = params as Record<string, unknown>;
+  const thread = (p.thread && typeof p.thread === 'object' ? p.thread : p) as Record<
+    string,
+    unknown
+  >;
+  const id =
+    typeof thread.id === 'string'
+      ? thread.id
+      : typeof p.threadId === 'string'
+        ? p.threadId
+        : undefined;
+  if (!id) return undefined;
+  const str = (value: unknown) => (typeof value === 'string' && value.trim() ? value : undefined);
+  return {
+    id,
+    parentThreadId: str(thread.parentThreadId),
+    source: str(thread.threadSource) ?? str(thread.source),
+    nickname: str(thread.agentNickname),
+    role: str(thread.agentRole),
+  };
+}
+
 export function extractThreadIdFromNotification(params: unknown): string | undefined {
   if (!params || typeof params !== 'object') return undefined;
   const p = params as Record<string, unknown>;

package/src/compact.ts

@@ -0,0 +1,132 @@
+import type { CompactOpts, CompactResult, GatewayLogger } from '@parall/agent-core';
+import type { OpenDispatchOutcome } from './dispatch.js';
+import {
+  CompactionStalledError,
+  type MainThreadInstructionsRefresher,
+  type NotificationTapSource,
+} from './instructions-refresh.js';
+import { JSON_RPC_METHOD_NOT_FOUND, JsonRpcError } from './jsonrpc-client.js';
+
+/**
+ * Idle auto-compact on the Codex bridge (idle-auto-compact-design.md §3.4):
+ * open the MAIN thread exactly the way a dispatch would (start/resume + the
+ * instructions reconcile), then run the unconditional compaction primitive
+ * as a tap-only turn — no TurnSink, no activeTurnIds entry, so it is neither
+ * a user turn nor a steer target (PFB-84 bookkeeping untouched). Outcomes
+ * follow the refresh path's posture: a stalled compaction quarantines the
+ * main lane and bounces the subprocess; -32601 latches unsupported for the
+ * subprocess lifetime.
+ *
+ * The host is the narrow slice of CodexAppServerAdapter this needs; the
+ * adapter's `compact()` is a thin delegate.
+ */
+export interface CodexCompactHost {
+  log?: GatewayLogger;
+  taps: NotificationTapSource;
+  refresher: Pick<
+    MainThreadInstructionsRefresher,
+    'isCompactUnsupported' | 'runCompaction' | 'recordCompacted'
+  >;
+  isMainSession(sessionKey: string): boolean;
+  isMainLaneQuarantined(): boolean;
+  /** Quarantine the main lane and request a subprocess restart (applied when free). */
+  quarantineAndBounce(log?: GatewayLogger): Promise<void>;
+  applyPendingRestart(log?: GatewayLogger): Promise<void>;
+  /** Open the main thread with restart gating (openingDispatches) held. */
+  openMainThread(sessionKey: string, log?: GatewayLogger): Promise<OpenDispatchOutcome>;
+  hasActiveTurn(threadId: string): boolean;
+  /** Run `fn` as tap-only work on the thread: restart-gated, no unrouted-notification warnings. */
+  withTapOnlyTurn<T>(threadId: string, fn: () => Promise<T>): Promise<T>;
+}
+
+export async function runCodexCompact(
+  host: CodexCompactHost,
+  { sessionKey, signal, log }: CompactOpts,
+): Promise<CompactResult> {
+  const logger = log ?? host.log;
+  if (!host.isMainSession(sessionKey)) {
+    return { status: 'unsupported', detail: 'compact is only supported on the main session' };
+  }
+  if (signal.aborted) return { status: 'timeout' };
+  if (host.isMainLaneQuarantined()) {
+    await host.applyPendingRestart(logger);
+    if (host.isMainLaneQuarantined()) {
+      return {
+        status: 'failed',
+        detail:
+          'main lane quarantined after a stalled compaction; the subprocess restart is still deferred behind an active turn',
+      };
+    }
+  }
+  if (host.refresher.isCompactUnsupported()) {
+    return {
+      status: 'unsupported',
+      detail: 'thread/compact/start not supported by this codex CLI',
+    };
+  }
+  await host.applyPendingRestart(logger);
+  const opened = await host.openMainThread(sessionKey, logger);
+  if (!opened.ok) return { status: 'failed', detail: opened.message };
+  if (opened.reconcile === 'stalled') {
+    // Same posture as dispatch(): the refresh compaction may still be
+    // running on the thread — never rotate it; quarantine and bounce.
+    await host.quarantineAndBounce(logger);
+    return {
+      status: 'timeout',
+      detail:
+        'instructions-refresh compaction stalled while opening the thread; subprocess bounced',
+    };
+  }
+  if (opened.reconcile === 'unsupported') {
+    return {
+      status: 'unsupported',
+      detail: 'thread/compact/start not supported by this codex CLI',
+    };
+  }
+  if (opened.reconcile === 'refreshed') {
+    // The open just ran a compaction of this very thread (instructions
+    // refresh) — the history is already folded; a second one is waste.
+    return { status: 'done', detail: 'compacted by the instructions refresh during open' };
+  }
+  if (signal.aborted) {
+    return { status: 'timeout', detail: 'budget elapsed while opening the thread' };
+  }
+  const { client, threadId } = opened;
+  if (host.hasActiveTurn(threadId)) {
+    return { status: 'failed', detail: 'a turn is active on the main thread' };
+  }
+  let stalled = false;
+  try {
+    return await host.withTapOnlyTurn(threadId, async () => {
+      try {
+        await host.refresher.runCompaction({ client, taps: host.taps, threadId, signal });
+        host.refresher.recordCompacted(sessionKey, threadId);
+        return { status: 'done' } as CompactResult;
+      } catch (err) {
+        if (err instanceof CompactionStalledError) {
+          // Budget elapsed (the gateway's abort or the refresher's own
+          // ceiling) and the turn ignored the interrupt: the compaction is
+          // torn down with the subprocess below.
+          stalled = true;
+          return { status: 'timeout', detail: errToString(err) };
+        }
+        if (err instanceof JsonRpcError && err.code === JSON_RPC_METHOD_NOT_FOUND) {
+          return { status: 'unsupported', detail: errToString(err) };
+        }
+        return { status: 'failed', detail: errToString(err) };
+      }
+    });
+  } finally {
+    if (stalled) {
+      // The compaction turn may still be running: quarantine the main lane
+      // and bounce the subprocess (deferred behind an active fork turn,
+      // retried by the next main dispatch) — exactly the dispatch posture.
+      await host.quarantineAndBounce(logger);
+    }
+  }
+}
+
+function errToString(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/src/dispatch.ts

@@ -3,15 +3,20 @@ import { randomUUID } from 'node:crypto';
 import * as path from 'node:path';
 import type {
   CleanupForkOpts,
+  CompactOpts,
+  CompactResult,
   DispatchAdapter,
   DispatchInputLifecycle,
   DispatchOpts,
   ForkOpts,
   ForkSessionHandle,
   GatewayLogger,
+  RuntimeActivityEvent,
+  RuntimeBusyState,
   RuntimeEvent,
 } from '@parall/agent-core';
 import type { PreparedLocalImage } from '@parall/agent-core/internal/attachment-input';
+import { isRuntimeBusy, projectRuntimeEvent, RuntimeActivityPort } from '@parall/agent-core';
 import {
   appendPreparedLocalAttachmentRefs,
   pinLocalAttachmentPaths,
@@ -25,6 +30,8 @@ import {
 } from './app-server-protocol.js';
 import type { CodexAgentConfig } from './config.js';
 import { normalizeApprovalPolicy, normalizeSandbox } from './config.js';
+import { runCodexCompact } from './compact.js';
+import { ForeignThreadRegistry } from './foreign-threads.js';
 import { CodexInjectionRegistry } from './injection-registry.js';
 import {
   MainThreadInstructionsRefresher,
@@ -32,6 +39,7 @@ import {
   type RefreshOutcome,
 } from './instructions-refresh.js';
 import { JsonRpcStdioClient } from './jsonrpc-client.js';
+import type { CodexRuntimeTurn } from './runtime-turn.js';
 import { answerServerRequest } from './server-requests.js';
 import type { CodexSessionManager } from './session-manager.js';
 import { buildThreadConfigOverrides } from './thread-config.js';
@@ -124,6 +132,9 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   private readonly instructionsRefresher: MainThreadInstructionsRefresher;
   private stopping = false;
   private lastUnroutedNotificationWarnAt = 0;
+  /** Subagent threads and their runtime-initiated turns (foreign-threads.ts). */
+  private readonly foreignThreads: ForeignThreadRegistry;
+  private readonly activity: RuntimeActivityPort;
 
   /**
    * Store an active turn sink keyed by threadId. If a sink already exists for
@@ -152,6 +163,19 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       compactTimeoutMs: opts.instructionsCompactTimeoutMs,
       interruptGraceMs: opts.instructionsInterruptGraceMs,
     });
+    this.activity = new RuntimeActivityPort('CodexAppServerAdapter', opts.log);
+    this.foreignThreads = new ForeignThreadRegistry({
+      sessionManager: opts.sessionManager,
+      log: opts.log,
+      activity: this.activity,
+      // A restart deferred behind subagent work must not starve once it ends.
+      afterTurnClosed: () => {
+        if (!this.restartRequested) return;
+        void this.applyPendingRestart().catch((err) =>
+          this.opts.log?.warn?.(`deferred restart failed: ${errToString(err)}`),
+        );
+      },
+    });
   }
 
   /** Register a listener for every server notification; returns unregister. */
@@ -249,6 +273,51 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     sink.close();
   }
 
+  /** Idle auto-compact (compact.ts): the compaction primitive as a tap-only main-thread turn. */
+  compact(opts: CompactOpts): Promise<CompactResult> {
+    return runCodexCompact(
+      {
+        log: this.opts.log,
+        taps: this,
+        refresher: this.instructionsRefresher,
+        isMainSession: (sessionKey) => this.opts.sessionManager.isMain(sessionKey),
+        isMainLaneQuarantined: () => this.mainLaneQuarantined,
+        quarantineAndBounce: async (log) => {
+          this.mainLaneQuarantined = true;
+          this.requestProcessRestart();
+          await this.applyPendingRestart(log);
+        },
+        applyPendingRestart: (log) => this.applyPendingRestart(log),
+        openMainThread: (sessionKey, log) =>
+          this.withOpening(() => this.openDispatchTarget(sessionKey, true, log)),
+        hasActiveTurn: (threadId) => this.activeTurns.has(threadId),
+        withTapOnlyTurn: async (threadId, fn) => {
+          this.reconcilingThreadIds.add(threadId);
+          try {
+            return await this.withOpening(fn);
+          } finally {
+            this.reconcilingThreadIds.delete(threadId);
+          }
+        },
+      },
+      opts,
+    );
+  }
+
+  /**
+   * Real work on the subprocess that predates any TurnSink (thread open,
+   * a tap-only compaction turn): counted so applyPendingRestart cannot
+   * stop() the subprocess out from under it.
+   */
+  private async withOpening<T>(fn: () => Promise<T>): Promise<T> {
+    this.openingDispatches += 1;
+    try {
+      return await fn();
+    } finally {
+      this.openingDispatches -= 1;
+    }
+  }
+
   hasPendingInjections(sessionKey: string): boolean {
     return this.injections.hasPending(sessionKey);
   }
@@ -261,6 +330,32 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     this.injections.markDrained(sessionKey, deliveryKey);
   }
 
+  // --- runtime-initiated work -------------------------------------------------
+
+  subscribeRuntimeActivity(handler: (event: RuntimeActivityEvent) => void): () => void {
+    return this.activity.subscribe(handler);
+  }
+
+  /**
+   * Busy = a dispatch turn, a dispatch opening its thread (possibly running
+   * the instructions-refresh compaction turn), or a subagent thread's turn
+   * is executing. Live subagent threads between turns are reported as
+   * background work, not busy.
+   */
+  isBusy(): boolean {
+    return isRuntimeBusy(this.busyState());
+  }
+
+  busyState(): RuntimeBusyState {
+    return {
+      activeTurns:
+        this.activeTurns.size +
+        (this.openingDispatches > 0 || this.reconcilingThreadIds.size > 0 ? 1 : 0) +
+        this.foreignThreads.openTurns(),
+      backgroundWork: this.foreignThreads.size,
+    };
+  }
+
   async *dispatch({
     event,
     bodyForAgent,
@@ -324,13 +419,9 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       // compaction turn BEFORE any TurnSink exists, and a concurrent fork
       // dispatch hitting a pending restart in that window would otherwise
       // stop() the subprocess out from under it.
-      this.openingDispatches += 1;
-      let opened: OpenDispatchOutcome;
-      try {
-        opened = await this.openDispatchTarget(sessionKey, isMainSession, log);
-      } finally {
-        this.openingDispatches -= 1;
-      }
+      const opened = await this.withOpening(() =>
+        this.openDispatchTarget(sessionKey, isMainSession, log),
+      );
       if (!opened.ok) {
         yield { type: 'error', message: opened.message };
         return;
@@ -521,34 +612,14 @@ export class CodexAppServerAdapter implements DispatchAdapter {
           sawTurnEnd = true;
           break;
         }
-        if (envelope.kind === 'error') {
-          yield { type: 'error', message: envelope.message };
-          continue;
-        }
-        const runtimeEvent = envelope.event;
-        if (runtimeEvent.type === 'error') {
-          yield runtimeEvent;
-          continue;
-        }
-        if (runtimeEvent.type === 'runtime_session') {
-          yield runtimeEvent;
-          continue;
-        }
-        if (runtimeEvent.type === 'text') {
-          // Layer 0 symmetric output contract: Codex's plain text is never
-          // projected as a chat message. Outbound messages must come from the
-          // agent explicitly invoking `@parall/cli messages send` / `dm` via
-          // the shell/exec tool. Text events are still yielded so agent-core
-          // records them as suppressed session steps for audit.
-          yield { ...runtimeEvent, project: false, groupKey };
-          continue;
-        }
-        if (runtimeEvent.type === 'turn_outcome') {
-          // Turn-boundary summary — no groupKey, passed through as-is.
-          yield runtimeEvent;
-          continue;
-        }
-        yield { ...runtimeEvent, groupKey };
+        // Layer 0 symmetric output contract (projectRuntimeEvent): Codex's
+        // plain text is never projected as a chat message — outbound
+        // messages come from the agent invoking `parall messages send` /
+        // `dm`; text is still yielded as a suppressed audit step.
+        yield projectRuntimeEvent(
+          envelope.kind === 'error' ? { type: 'error', message: envelope.message } : envelope.event,
+          groupKey,
+        );
       }
     } finally {
       releasePreparedAttachments();
@@ -757,7 +828,9 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   private openingDispatches = 0;
 
   private async applyPendingRestart(log?: GatewayLogger): Promise<void> {
-    if (!this.restartRequested || this.activeTurns.size > 0 || this.openingDispatches > 0) return;
+    // isBusy folds in subagent turns: a capability change must not SIGTERM
+    // the app-server under a running spawn_agent thread.
+    if (!this.restartRequested || this.isBusy()) return;
     this.restartRequested = false;
     (log ?? this.opts.log)?.info?.(
       'restarting codex app-server after a capability change (the fresh-process thread/resume applies the refreshed developerInstructions to the persisted thread configuration; the model-visible context is reconciled before the next turn)',
@@ -783,6 +856,9 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     this.instructionsRefresher.clearThreadState();
     // The (possible) zombie compaction turn dies with the subprocess.
     this.mainLaneQuarantined = false;
+    // Subagent threads die with the app-server: end their open turns
+    // (runtime_crash) and close their child sessions before the client goes.
+    this.foreignThreads.dropAll('lost: Codex app-server stopped');
     this.notifyTapsDisposed('Codex app-server stopped');
     if (client) client.dispose(new Error('adapter stopped'));
     if (proc && proc.exitCode === null && proc.signalCode === null) {
@@ -801,6 +877,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       this.activeTurns.clear();
       this.activeTurnIds.clear();
       this.injections.clear();
+      this.foreignThreads.dropAll('lost: Codex app-server disposed');
       this.client = null;
       this.proc = null;
       this.initialized = false;
@@ -984,6 +1061,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     this.resumedThreadIds.clear();
     this.instructionsRefresher.clearThreadState();
     this.mainLaneQuarantined = false;
+    this.foreignThreads.dropAll(`lost: Codex app-server ${reason}`);
     this.notifyTapsDisposed(`Codex app-server ${reason}`);
     this.client = null;
     this.proc = null;
@@ -1076,6 +1154,10 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       // successful instructions refresh and burn the shared rate-limit
       // window that exists to surface REAL orphaned turns.
       if (this.reconcilingThreadIds.has(threadId)) return;
+      // Subagent threads and their turns are runtime-initiated work: routed
+      // into their own sinks and surfaced to the gateway as child-session
+      // turns instead of being dropped.
+      if (this.foreignThreads.route(method, params, threadId)) return;
       // Notifications for a thread with no registered sink are dropped. A
       // sustained stream of these means a turn is running that nothing is
       // consuming (threadId mismatch, sink torn down early) — the dispatch
@@ -1107,7 +1189,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   }
 }
 
-type OpenDispatchOutcome =
+export type OpenDispatchOutcome =
   | { ok: true; client: JsonRpcStdioClient; threadId: string; reconcile?: RefreshOutcome }
   | { ok: false; message: string };
 

package/src/foreign-threads.ts

@@ -0,0 +1,187 @@
+import type { GatewayLogger, RuntimeActivityPort } from '@parall/agent-core';
+import { extractThreadInfo } from './app-server-protocol.js';
+import { CodexRuntimeTurn } from './runtime-turn.js';
+import type { CodexSessionManager } from './session-manager.js';
+import type { TurnEventEnvelope } from './turn-sink.js';
+
+/**
+ * Threads the app-server runs that no dispatch opened — `spawn_agent`
+ * subagent threads (`thread/started` with `threadSource: "subAgent"`), or a
+ * thread whose turn showed up with no `thread/started` (bridge restarted
+ * mid-subagent). Each is a child session of its parent thread's session;
+ * every `turn/started`…`turn/completed` on it is a RuntimeInitiatedTurn
+ * (runtime-initiated-turns-design.md §5).
+ */
+export type ForeignThread = {
+  threadId: string;
+  sessionKey: string;
+  parentThreadId?: string;
+  parentSessionKey: string;
+  nickname?: string;
+  role?: string;
+  turn?: CodexRuntimeTurn;
+};
+
+export type ForeignThreadHost = {
+  sessionManager: CodexSessionManager;
+  log?: GatewayLogger;
+  /** Turns opened and child sessions closed go to the gateway through it. */
+  activity: RuntimeActivityPort;
+  /** A subagent turn ended — a deferred restart may apply now. */
+  afterTurnClosed(): void;
+};
+
+export class ForeignThreadRegistry {
+  private readonly threads = new Map<string, ForeignThread>();
+
+  constructor(private readonly host: ForeignThreadHost) {}
+
+  /** Live (registered, not closed) subagent threads. */
+  get size(): number {
+    return this.threads.size;
+  }
+
+  openTurns(): number {
+    let count = 0;
+    for (const thread of this.threads.values()) if (thread.turn) count += 1;
+    return count;
+  }
+
+  /**
+   * Notifications for a thread no dispatch owns. Returns false when the
+   * caller should keep treating the frame as unroutable.
+   */
+  route(method: string, params: unknown, threadId: string): boolean {
+    if (method === 'thread/started') {
+      if (this.host.sessionManager.getSessionKey(threadId) || this.threads.has(threadId)) {
+        return true;
+      }
+      const info = extractThreadInfo(params);
+      // Only subagent spawns become child sessions; our own thread/start and
+      // thread/fork echoes (source appServer) are bound by their responses.
+      if (!info || info.source !== 'subAgent') return true;
+      this.register(info);
+      return true;
+    }
+    let thread = this.threads.get(threadId);
+    if (method === 'thread/closed' || method === 'thread/archived' || method === 'thread/deleted') {
+      if (!thread) return false;
+      this.close(thread, method.slice('thread/'.length));
+      return true;
+    }
+    if (!thread) {
+      // A turn on a thread we never saw start: our own thread without a
+      // sink is a genuine orphan (keep the warn); anything else is adopted
+      // under the main session (bridge restarted mid-subagent).
+      if (this.host.sessionManager.getSessionKey(threadId)) return false;
+      if (method !== 'turn/started' && method !== 'turn/completed' && !method.startsWith('item/')) {
+        return false;
+      }
+      thread = this.register({ id: threadId });
+    }
+    if (method === 'turn/started') {
+      if (thread.turn) thread.turn.touch();
+      else this.openTurn(thread);
+      return true;
+    }
+    if (!thread.turn) {
+      if (method !== 'turn/completed' && !method.startsWith('item/')) return true;
+      this.openTurn(thread);
+    }
+    const turn = thread.turn as CodexRuntimeTurn;
+    turn.sink.touchActivity();
+    for (const event of turn.sink.mapper.map(method, params)) {
+      turn.sink.push({ kind: 'runtime', event });
+    }
+    if (method === 'turn/completed') {
+      this.endTurn(thread, { kind: 'turn_end', threadId });
+      this.host.log?.info?.(
+        `runtime-initiated turn ${turn.groupKey} on subagent thread ${threadId} completed`,
+      );
+    }
+    return true;
+  }
+
+  /** Subagent threads die with the app-server: end open turns, close child sessions. */
+  dropAll(reason: string): void {
+    for (const thread of [...this.threads.values()]) {
+      this.close(thread, reason);
+    }
+  }
+
+  private register(info: {
+    id: string;
+    parentThreadId?: string;
+    nickname?: string;
+    role?: string;
+  }): ForeignThread {
+    // A subagent may itself spawn subagents: resolve the parent against the
+    // live foreign threads first, then main / fork threads, else main.
+    const parentSessionKey =
+      (info.parentThreadId
+        ? (this.threads.get(info.parentThreadId)?.sessionKey ??
+          this.host.sessionManager.getSessionKey(info.parentThreadId))
+        : undefined) ?? this.host.sessionManager.mainSessionKey;
+    const thread: ForeignThread = {
+      threadId: info.id,
+      sessionKey: `codex-sub:${info.id}`,
+      parentThreadId: info.parentThreadId,
+      parentSessionKey,
+      nickname: info.nickname,
+      role: info.role,
+    };
+    this.threads.set(info.id, thread);
+    this.host.log?.info?.(
+      `subagent thread ${info.id} registered (parent ${info.parentThreadId ?? 'unknown'} → ${parentSessionKey}${info.nickname ? `, ${info.nickname}` : ''}${info.role ? ` / ${info.role}` : ''}); ${this.threads.size} live`,
+    );
+    return thread;
+  }
+
+  private openTurn(thread: ForeignThread): void {
+    const turn = new CodexRuntimeTurn(
+      thread.sessionKey,
+      {
+        kind: 'subagent',
+        threadId: thread.threadId,
+        ...(thread.parentThreadId ? { parentThreadId: thread.parentThreadId } : {}),
+        ...(thread.nickname ? { nickname: thread.nickname } : {}),
+        ...(thread.role ? { role: thread.role } : {}),
+      },
+      {
+        parentSessionKey: thread.parentSessionKey,
+        onDetach: (reason) => {
+          if (thread.turn !== turn) return;
+          this.endTurn(thread, { kind: 'error', message: `subagent turn detached: ${reason}` });
+        },
+      },
+    );
+    thread.turn = turn;
+    this.host.log?.info?.(
+      `runtime-initiated turn ${turn.groupKey} opened on subagent thread ${thread.threadId}`,
+    );
+    this.host.activity.surfaceTurn(turn);
+  }
+
+  /** The thread's open turn is over: last envelope, sink closed, restart re-driven. */
+  private endTurn(thread: ForeignThread, last: TurnEventEnvelope): void {
+    const turn = thread.turn;
+    if (!turn) return;
+    thread.turn = undefined;
+    turn.sink.push(last);
+    turn.sink.close();
+    this.host.afterTurnClosed();
+  }
+
+  private close(thread: ForeignThread, reason: string): void {
+    if (this.threads.get(thread.threadId) !== thread) return;
+    this.threads.delete(thread.threadId);
+    this.endTurn(thread, {
+      kind: 'error',
+      message: `subagent thread ${thread.threadId} ${reason}`,
+    });
+    this.host.log?.info?.(
+      `subagent thread ${thread.threadId} ${reason}; ${this.threads.size} live`,
+    );
+    this.host.activity.emit({ kind: 'session_closed', sessionKey: thread.sessionKey, reason });
+  }
+}

package/src/index.ts

@@ -20,6 +20,7 @@ import {
   llmSource,
   identityFromMe,
   initAgentTelemetry,
+  resolveServiceVersion,
 } from '@parall/agent-core';
 import { ApiError, ParallClient, ParallWs } from '@parall/sdk';
 import {
@@ -74,7 +75,11 @@ function resolveProviderEnv(): void {
 async function main() {
   // Before any fetch: long-lived HTTP connections for every bridge→api call.
   configureHttpKeepAlive();
-  const telemetry = await initAgentTelemetry('parall-codex-agent', 'codex');
+  const telemetry = await initAgentTelemetry('parall-codex-agent', 'codex', {
+    apiUrl: process.env.PRLL_API_URL,
+    apiKey: process.env.PRLL_API_KEY,
+    serviceVersion: resolveServiceVersion(import.meta.url),
+  });
   activeLog = createOtelLogger('agent', 'codex-agent');
   try {
     resolveProviderEnv();
@@ -291,6 +296,12 @@ async function main() {
       onSessionStale: () => {
         sessionManager.clearMainThread();
       },
+      // The app-server outlives one dispatch (subagent threads keep running
+      // after the parent turn): stop it INSIDE the gateway's shutdown so the
+      // runtime turns it ends still land their steps and idle/close writes
+      // before the step and lifecycle flushes — the finally below runs after
+      // those windows have closed.
+      onBeforeDisconnect: () => adapter.stop(),
     });
 
     const abortController = new AbortController();