agent-relay-codex 0.6.1 → 0.10.0

package/live-sidecar.ts

@@ -1,988 +0,0 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { dirname, resolve } from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
-import { approvalModeFromPermissions, type ApprovalMode } from "./approval";
-import { CodexAppClient, type ClientEvent, type Thread, type ThreadStatus } from "./app-client";
-import { loadAgentRelayProfile, messageMatchesProfileChannels } from "./profile";
-import { RelayClient, RelayHttpError, type RelayAgentSession, type RelayAgentStatus, type RelayMessage } from "./relay";
-
-type AgentControlAction = "restart" | "shutdown";
-
-interface Config {
-  relayUrl: string;
-  appServerUrl: string;
-  cwd: string;
-  rig: string;
-  label?: string;
-  capabilities: string[];
-  tags: string[];
-  channels: string[];
-  profileName?: string;
-  profileMeta: Record<string, unknown>;
-  statePath: string;
-  contextPath?: string;
-  pollIntervalMs: number;
-  heartbeatIntervalMs: number;
-  threadCheckIntervalMs: number;
-  relayBackoffInitialMs: number;
-  relayBackoffMaxMs: number;
-  coalesceWindowMs: number;
-  reconnectInitialDelayMs: number;
-  reconnectMaxDelayMs: number;
-  threadMode: "auto" | "resume" | "start";
-  threadId?: string;
-  model?: string;
-  approvalPolicy?: string;
-  sandbox?: string;
-  approvalMode: ApprovalMode;
-  parentPid?: number;
-  assumeLoadedThread: boolean;
-  headless: boolean;
-}
-
-interface RuntimeState {
-  agentId: string;
-  agentInstanceId: string;
-  agentEpoch: number;
-  threadId: string;
-  activeTurnId: string | null;
-  threadStatus: ThreadStatus["type"];
-  lastSeenMessageId: number;
-  pendingMessageCount: number;
-  appConnected: boolean;
-  appServerUrl: string;
-  relayUrl: string;
-  cwd: string;
-  updatedAt: string;
-}
-
-interface DeliveryBatch {
-  messages: RelayMessage[];
-}
-
-class ThreadLostError extends Error {}
-
-export function activeClaimRenewalIds(
-  messageIds: Iterable<number>,
-  activeTurnId: string | null,
-  threadStatus: ThreadStatus["type"],
-): number[] {
-  if (!activeTurnId && threadStatus !== "active") return [];
-  return [...messageIds];
-}
-
-export function canUseSyntheticLoadedThread(threadId: string, loadedThreadIds: readonly string[]): boolean {
-  return loadedThreadIds.includes(threadId);
-}
-
-class CodexLiveSidecar {
-  private readonly relay: RelayClient;
-  private readonly logPrefix = "[codex-live]";
-  private app: CodexAppClient;
-  private agentId = "";
-  private readonly agentInstanceId = randomUUID();
-  private agentEpoch = 0;
-  private threadId = "";
-  private activeTurnId: string | null = null;
-  private threadStatus: ThreadStatus["type"] = "notLoaded";
-  private lastSeenMessageId = 0;
-  private lastHeartbeatAt = 0;
-  private lastThreadCheckAt = 0;
-  private hasSuccessfulPoll = false;
-  private relayBackoffMs = 0;
-  private lastClaimRenewalAt = 0;
-  private stopping = false;
-  private appConnected = false;
-  private draining = false;
-  private drainDueAt = 0;
-  private reconnecting: Promise<void> | null = null;
-  private relayPrimerDelivered = false;
-  private readonly pendingMessages = new Map<number, RelayMessage>();
-  private readonly activeClaimedMessageIds = new Set<number>();
-
-  constructor(private readonly config: Config) {
-    this.relay = new RelayClient(config.relayUrl, (msg) => this.log(msg));
-    this.app = this.createAppClient();
-    this.threadId = config.threadId || "";
-  }
-
-  async run(): Promise<void> {
-    mkdirSync(dirname(this.config.statePath), { recursive: true });
-    if (this.config.assumeLoadedThread && this.config.threadId) {
-      this.log(`assuming remote TUI thread ${this.config.threadId} is already loaded`);
-    }
-
-    process.on("SIGINT", () => void this.stop("SIGINT"));
-    process.on("SIGTERM", () => void this.stop("SIGTERM"));
-
-    await this.ensureAppReady();
-    if (this.stopping) return;
-
-    await this.registerRelayAgent();
-
-    while (!this.stopping) {
-      let sleepMs = this.config.pollIntervalMs;
-      try {
-        if (this.parentExited()) {
-          await this.stop("parent-exit");
-          break;
-        }
-        const now = Date.now();
-        if (now - this.lastThreadCheckAt >= this.config.threadCheckIntervalMs) {
-          this.lastThreadCheckAt = now;
-          await this.verifyCurrentThread();
-        }
-        if (now - this.lastHeartbeatAt >= this.config.heartbeatIntervalMs) {
-          await this.relay.heartbeat(this.agentId, this.agentSession());
-          this.lastHeartbeatAt = now;
-        }
-        if (now - this.lastClaimRenewalAt >= this.config.heartbeatIntervalMs) {
-          await this.renewActiveClaims();
-          this.lastClaimRenewalAt = now;
-        }
-
-        const messages = await this.relay.pollMessages(this.agentId, this.lastSeenMessageId);
-        if (!this.hasSuccessfulPoll) {
-          this.hasSuccessfulPoll = true;
-          await this.refreshRelayStatus();
-        }
-        if (messages.length > 0) {
-          const deliverableMessages = messages.filter((message) => messageMatchesProfileChannels(message, this.config.channels));
-          const skippedMessages = messages.filter((message) => !messageMatchesProfileChannels(message, this.config.channels));
-          if (skippedMessages.length > 0) this.advanceCursor(skippedMessages);
-          this.addPendingMessages(deliverableMessages);
-          this.writeState();
-        }
-
-        if (this.pendingMessages.size > 0 && now >= this.drainDueAt && !this.draining) {
-          await this.drainPendingMessages();
-        }
-        this.relayBackoffMs = 0;
-      } catch (error) {
-        if (error instanceof RelayHttpError && error.status === 404 && error.path.includes("/heartbeat")) {
-          this.log("heartbeat returned 404; re-registering relay agent");
-          await this.registerRelayAgent();
-        } else if (error instanceof RelayHttpError && error.status === 409) {
-          this.log("relay rejected this stale agent instance; stopping sidecar");
-          this.stopping = true;
-          this.writeState();
-          this.app.close();
-        } else if (error instanceof ThreadLostError) {
-          await this.stopAndUnregister(error.message);
-        } else {
-          sleepMs = this.nextRelayBackoffMs();
-          this.log(`loop error: ${describeError(error)}; retrying in ${sleepMs}ms`);
-        }
-      }
-      await this.delayWithParentCheck(sleepMs);
-    }
-  }
-
-  private async registerRelayAgent(): Promise<void> {
-    const registration = await this.relay.registerAgent({
-      relayUrl: this.config.relayUrl,
-      cwd: this.config.cwd,
-      rig: this.config.rig,
-      label: this.config.label,
-      capabilities: this.config.capabilities,
-      tags: this.config.tags,
-      channels: this.config.channels,
-      profileName: this.config.profileName,
-      profileMeta: this.config.profileMeta,
-      threadId: this.threadId,
-      model: this.config.model,
-      appServerUrl: this.config.appServerUrl,
-      approvalMode: this.config.approvalMode,
-      instanceId: this.agentInstanceId,
-    });
-    this.agentId = registration.agentId;
-    this.agentEpoch = registration.session?.epoch ?? 0;
-    this.lastSeenMessageId = this.agentEpoch > 1 ? 0 : await this.relay.getCursor();
-    this.lastHeartbeatAt = 0;
-    this.hasSuccessfulPoll = false;
-    this.log(`registered agent ${this.agentId}`);
-    this.log(`using thread ${this.threadId}`);
-    this.log(`bootstrapped relay cursor ${this.lastSeenMessageId}${this.agentEpoch > 1 ? " (resuming unread backlog)" : ""}`);
-    this.writeState();
-    await this.refreshRelayStatus();
-  }
-
-  private createAppClient(): CodexAppClient {
-    const app = new CodexAppClient(this.config.appServerUrl, (msg) => this.log(msg));
-    app.onEvent((event) => this.handleAppEvent(event));
-    app.onConnectionChange((connected) => {
-      this.appConnected = connected;
-      if (!connected) {
-        this.activeTurnId = null;
-        this.threadStatus = "notLoaded";
-        if (!this.stopping) void this.ensureAppReady();
-      }
-      void this.refreshRelayStatus();
-      this.writeState();
-    });
-    return app;
-  }
-
-  private async ensureAppReady(force = false): Promise<void> {
-    if (this.stopping) return;
-    if (this.appConnected && !force) return;
-    if (this.reconnecting) return this.reconnecting;
-
-    this.reconnecting = this.connectWithRetry(force).finally(() => {
-      this.reconnecting = null;
-    });
-    return this.reconnecting;
-  }
-
-  private async connectWithRetry(force: boolean): Promise<void> {
-    let waitMs = this.config.reconnectInitialDelayMs;
-
-    while (!this.stopping) {
-      try {
-        if (force) {
-          try {
-            this.app.close();
-          } catch {
-            // Ignore close failures during forced reconnect.
-          }
-          this.appConnected = false;
-        }
-
-        if (!this.app.isConnected()) {
-          this.app = this.createAppClient();
-          await this.app.connect();
-          await this.app.initialize();
-        }
-
-        const thread = this.threadId
-          ? await this.attachKnownThread(this.threadId)
-          : await this.resolveThread();
-        this.threadId = thread.id;
-        this.syncThreadState(thread);
-        if (this.agentId) {
-          this.log(`app connection restored for thread ${thread.id}`);
-        }
-        return;
-      } catch (error) {
-        if (error instanceof ThreadLostError) {
-          await this.stopAndUnregister(error.message);
-          return;
-        }
-        this.appConnected = false;
-        this.log(`app connection failed: ${describeError(error)}; retrying in ${waitMs}ms`);
-        await delay(waitMs);
-        waitMs = Math.min(this.config.reconnectMaxDelayMs, waitMs * 2);
-      }
-    }
-  }
-
-  private async stop(signal: string): Promise<void> {
-    if (this.stopping) return;
-    this.stopping = true;
-    this.log(`stopping on ${signal}`);
-    if (this.agentId) {
-      try {
-        await this.relay.setStatus(this.agentId, "offline", this.agentSession());
-      } catch {
-        // Best effort during shutdown.
-      }
-    }
-    this.writeState();
-    this.app.close();
-  }
-
-  private async stopAndUnregister(reason: string): Promise<void> {
-    if (this.stopping) return;
-    this.stopping = true;
-    this.log(`${reason}; unregistering relay agent and stopping sidecar`);
-    if (this.agentId) {
-      try {
-        await this.relay.unregisterAgent(this.agentId);
-      } catch (error) {
-        this.log(`failed to unregister relay agent ${this.agentId}: ${describeError(error)}`);
-        try {
-          await this.relay.setStatus(this.agentId, "offline", this.agentSession());
-        } catch {
-          // Best effort after unregister failure.
-        }
-      }
-    }
-    this.threadStatus = "notLoaded";
-    this.activeTurnId = null;
-    this.writeState();
-    this.app.close();
-  }
-
-  private parentExited(): boolean {
-    return Boolean(this.config.parentPid && !isAlive(this.config.parentPid));
-  }
-
-  private async delayWithParentCheck(ms: number): Promise<void> {
-    const deadline = Date.now() + ms;
-    while (!this.stopping && Date.now() < deadline) {
-      if (this.parentExited()) {
-        await this.stop("parent-exit");
-        return;
-      }
-      await delay(Math.min(500, Math.max(0, deadline - Date.now())));
-    }
-  }
-
-  private async attachKnownThread(threadId: string): Promise<Thread> {
-    if (this.config.assumeLoadedThread) {
-      return this.readAssumedLoadedThread(threadId);
-    }
-
-    try {
-      const resumed = await this.app.threadResume({
-        threadId,
-        cwd: this.config.cwd,
-        ...this.threadPermissions(),
-        persistExtendedHistory: false,
-      });
-      return normalizeThread(resumed.thread);
-    } catch (error) {
-      if (isThreadMissingRolloutError(error)) {
-        try {
-          return await this.readThreadWithFallback(threadId);
-        } catch {
-          // Fall through to normal resolution when the thread is neither loaded nor persisted.
-        }
-      }
-      this.log(`resume failed for thread ${threadId}: ${describeError(error)}; falling back to thread resolution`);
-      this.threadId = "";
-      return this.resolveThread();
-    }
-  }
-
-  private async resolveThread(): Promise<Thread> {
-    if (this.config.threadId && this.config.threadMode !== "start") {
-      const resumed = await this.app.threadResume({
-        threadId: this.config.threadId,
-        cwd: this.config.cwd,
-        ...this.threadPermissions(),
-        persistExtendedHistory: false,
-      });
-      return normalizeThread(resumed.thread);
-    }
-
-    if (this.config.threadMode !== "start") {
-      const loaded = await this.app.threadLoadedList(20);
-      const loadedThreads: Thread[] = [];
-      for (const loadedThreadId of loaded.data) {
-        const thread = await this.readThreadWithFallback(loadedThreadId);
-        if (thread.cwd === this.config.cwd) loadedThreads.push(thread);
-      }
-      const activeLoaded = loadedThreads
-        .sort((a, b) => b.updatedAt - a.updatedAt)
-        .find((thread) => thread.status.type === "active") ?? loadedThreads.sort((a, b) => b.updatedAt - a.updatedAt)[0];
-      if (activeLoaded) return activeLoaded;
-
-      const listed = await this.app.threadList({ cwd: this.config.cwd, limit: 10, archived: false });
-      const latest = [...listed.data].sort((a, b) => b.updatedAt - a.updatedAt)[0];
-      if (latest) {
-        const resumed = await this.app.threadResume({
-          threadId: latest.id,
-          cwd: this.config.cwd,
-          ...this.threadPermissions(),
-          persistExtendedHistory: false,
-        });
-        return normalizeThread(resumed.thread);
-      }
-    }
-
-    const started = await this.app.threadStart({
-      cwd: this.config.cwd,
-      ...this.threadPermissions(),
-      ephemeral: false,
-      sessionStartSource: "startup",
-      model: this.config.model ?? null,
-    });
-    return normalizeThread(started.thread);
-  }
-
-  private threadPermissions(): Record<string, string> {
-    const payload: Record<string, string> = {};
-    if (this.config.approvalPolicy) payload.approvalPolicy = this.config.approvalPolicy;
-    if (this.config.sandbox) payload.sandbox = this.config.sandbox;
-    return payload;
-  }
-
-  private async readAssumedLoadedThread(threadId: string): Promise<Thread> {
-    try {
-      return await this.readThreadWithFallback(threadId);
-    } catch {
-      const loaded = await this.app.threadLoadedList(100);
-      if (canUseSyntheticLoadedThread(threadId, loaded.data)) {
-        return syntheticLoadedThread(threadId, this.config.cwd);
-      }
-      throw new ThreadLostError(`codex thread ${threadId} is no longer loaded`);
-    }
-  }
-
-  private async verifyCurrentThread(): Promise<void> {
-    if (!this.threadId || !this.appConnected) return;
-    if (!this.config.assumeLoadedThread) return;
-    const thread = await this.readAssumedLoadedThread(this.threadId);
-    this.syncThreadState(thread);
-  }
-
-  private async readThreadWithFallback(threadId: string): Promise<Thread> {
-    try {
-      const read = await this.app.threadRead(threadId, true);
-      return normalizeThread(read.thread);
-    } catch (error) {
-      if (!isThreadMaterializationError(error)) throw error;
-      const read = await this.app.threadRead(threadId, false);
-      return normalizeThread(read.thread);
-    }
-  }
-
-  private syncThreadState(thread: Thread): void {
-    this.threadStatus = thread.status.type;
-    const turns = thread.turns ?? [];
-    const activeTurn = [...turns].reverse().find((turn) => turn.status === "inProgress");
-    this.activeTurnId = activeTurn?.id ?? null;
-    if (!this.activeTurnId && this.threadStatus !== "active") this.activeClaimedMessageIds.clear();
-    void this.refreshRelayStatus();
-    this.writeState();
-  }
-
-  private handleAppEvent(event: ClientEvent): void {
-    if (event.type !== "notification") return;
-    const { method, params } = event.message;
-
-    if (method === "thread/status/changed") {
-      if (params?.threadId === this.threadId && params.status && typeof params.status === "object" && "type" in params.status) {
-        const nextStatus = String(params.status.type) as ThreadStatus["type"];
-        if (this.config.assumeLoadedThread && nextStatus === "notLoaded") {
-          void this.stopAndUnregister(`codex thread ${this.threadId} reported notLoaded`);
-          return;
-        }
-        this.threadStatus = nextStatus;
-        void this.refreshRelayStatus();
-        this.writeState();
-      }
-      return;
-    }
-
-    if (method === "turn/started") {
-      if (params?.threadId === this.threadId && params.turn && typeof params.turn === "object" && "id" in params.turn) {
-        this.activeTurnId = String(params.turn.id);
-        this.threadStatus = "active";
-        void this.refreshRelayStatus();
-        this.writeState();
-      }
-      return;
-    }
-
-    if (method === "turn/completed") {
-      if (params?.threadId === this.threadId && params.turn && typeof params.turn === "object") {
-        const completedId = "id" in params.turn ? String(params.turn.id) : null;
-        if (completedId && this.activeTurnId === completedId) this.activeTurnId = null;
-        this.threadStatus = "idle";
-        this.activeClaimedMessageIds.clear();
-        void this.refreshRelayStatus();
-        this.writeState();
-      }
-    }
-  }
-
-  private async refreshRelayStatus(): Promise<void> {
-    if (!this.agentId) return;
-
-    const status: RelayAgentStatus = !this.appConnected
-      ? "online"
-      : this.activeTurnId || this.threadStatus === "active"
-        ? "busy"
-        : "idle";
-    const ready = this.hasSuccessfulPoll && this.appConnected && Boolean(this.threadId);
-
-    try {
-      await Promise.all([
-        this.relay.setStatus(this.agentId, status, this.agentSession()),
-        this.relay.setReady(this.agentId, ready, this.agentSession()),
-      ]);
-    } catch {
-      // Best-effort status sync.
-    }
-  }
-
-  private async renewActiveClaims(): Promise<void> {
-    if (!this.agentId || this.activeClaimedMessageIds.size === 0) return;
-    const renewals = activeClaimRenewalIds(this.activeClaimedMessageIds, this.activeTurnId, this.threadStatus);
-    if (renewals.length === 0) {
-      this.activeClaimedMessageIds.clear();
-      return;
-    }
-
-    for (const messageId of renewals) {
-      try {
-        const renewed = await this.relay.renewMessageClaim(messageId, this.agentId, this.agentSession());
-        if (!renewed) {
-          this.activeClaimedMessageIds.delete(messageId);
-          this.log(`claim renewal rejected for message ${messageId}`);
-        }
-      } catch (error) {
-        this.log(`claim renewal failed for message ${messageId}: ${describeError(error)}`);
-      }
-    }
-  }
-
-  private addPendingMessages(messages: RelayMessage[]): void {
-    let added = false;
-    for (const message of messages) {
-      if (this.pendingMessages.has(message.id)) continue;
-      this.pendingMessages.set(message.id, message);
-      added = true;
-    }
-
-    if (added && this.drainDueAt === 0) {
-      this.drainDueAt = Date.now() + this.config.coalesceWindowMs;
-    }
-  }
-
-  private async drainPendingMessages(): Promise<void> {
-    if (this.draining || this.pendingMessages.size === 0) return;
-
-    this.draining = true;
-    const sorted = [...this.pendingMessages.values()].sort((a, b) => a.id - b.id);
-    this.pendingMessages.clear();
-    this.drainDueAt = 0;
-
-    try {
-      await this.ensureAppReady();
-      const batches = createDeliveryBatches(sorted);
-      for (let index = 0; index < batches.length; index += 1) {
-        const batch = batches[index]!;
-        try {
-          await this.deliverBatch(batch);
-        } catch (error) {
-          this.requeueBatches(batches.slice(index));
-          this.log(`delivery error: ${describeError(error)}`);
-          await this.ensureAppReady(true);
-          break;
-        }
-      }
-    } finally {
-      this.draining = false;
-      this.writeState();
-    }
-  }
-
-  private requeueBatches(batches: DeliveryBatch[]): void {
-    for (const batch of batches) {
-      for (const message of batch.messages) {
-        this.pendingMessages.set(message.id, message);
-      }
-    }
-    if (this.pendingMessages.size > 0) {
-      this.drainDueAt = Date.now() + Math.min(this.config.coalesceWindowMs, 250);
-    }
-  }
-
-  private async deliverBatch(batch: DeliveryBatch): Promise<void> {
-    const control = firstAgentControlMessage(batch.messages);
-    if (control) {
-      await this.handleAgentControl(control.message, control.action);
-      return;
-    }
-
-    await this.ensureAppReady();
-
-    const claimedMessageIds: number[] = [];
-    for (const message of batch.messages) {
-      if (!message.claimable) continue;
-      const claimed = await this.relay.claimMessage(message.id, this.agentId, this.agentSession());
-      if (!claimed) {
-        this.log(`skipping unclaimed message ${message.id}`);
-        this.advanceCursor([message]);
-        this.writeState();
-        return;
-      }
-      claimedMessageIds.push(message.id);
-    }
-
-    const delivery = this.pickDeliveryMode(batch.messages);
-    const prompt = formatRelayPrompt(batch.messages, { includePrimer: !this.relayPrimerDelivered, headless: this.config.headless });
-    const ids = batch.messages.map((message) => message.id).join(", ");
-    this.log(`delivering message ${ids} via ${delivery}`);
-
-    if (delivery === "interrupt" && this.activeTurnId) {
-      try {
-        await this.app.turnInterrupt(this.threadId, this.activeTurnId);
-        this.activeTurnId = null;
-        this.threadStatus = "idle";
-        await this.app.settle(200);
-      } catch (error) {
-        this.log(`interrupt failed for messages ${ids}: ${describeError(error)}`);
-      }
-    }
-
-    if (delivery === "steer" && this.activeTurnId) {
-      try {
-        await this.app.turnSteer(this.threadId, this.activeTurnId, prompt);
-        for (const id of claimedMessageIds) this.activeClaimedMessageIds.add(id);
-        this.relayPrimerDelivered = true;
-        await this.markBatchRead(batch.messages);
-        this.advanceCursor(batch.messages);
-        this.writeState();
-        return;
-      } catch (error) {
-        this.log(`steer failed for messages ${ids}, falling back to start: ${describeError(error)}`);
-      }
-    }
-
-    await this.app.turnStart(this.threadId, prompt);
-    for (const id of claimedMessageIds) this.activeClaimedMessageIds.add(id);
-    this.relayPrimerDelivered = true;
-    await this.markBatchRead(batch.messages);
-    this.advanceCursor(batch.messages);
-    this.writeState();
-  }
-
-  private async handleAgentControl(message: RelayMessage, action: AgentControlAction): Promise<void> {
-    this.log(`agent control ${action} requested by message ${message.id}`);
-    await this.relay.markRead(message.id, this.agentId);
-    this.advanceCursor([message]);
-
-    if (action === "shutdown") {
-      await this.stopAndUnregister(`dashboard shutdown requested by message ${message.id}`);
-      return;
-    }
-
-    if (this.agentId) {
-      try {
-        await this.relay.unregisterAgent(this.agentId);
-      } catch (error) {
-        this.log(`failed to unregister before restart: ${describeError(error)}`);
-      }
-    }
-    this.agentEpoch = 0;
-    this.activeTurnId = null;
-    this.activeClaimedMessageIds.clear();
-    this.app.close();
-    this.appConnected = false;
-    await this.ensureAppReady(true);
-    await this.registerRelayAgent();
-    this.writeState();
-  }
-
-  private advanceCursor(messages: RelayMessage[]): void {
-    for (const message of messages) {
-      this.lastSeenMessageId = Math.max(this.lastSeenMessageId, message.id);
-    }
-  }
-
-  private async markBatchRead(messages: RelayMessage[]): Promise<void> {
-    for (const message of messages) {
-      await this.relay.markRead(message.id, this.agentId);
-    }
-  }
-
-  private agentSession(): RelayAgentSession | undefined {
-    return this.agentEpoch > 0 ? { instanceId: this.agentInstanceId, epoch: this.agentEpoch } : undefined;
-  }
-
-  private pickDeliveryMode(messages: RelayMessage[]): "start" | "steer" | "interrupt" {
-    const first = messages[0]!;
-    const meta = first.meta ?? {};
-    const requested = typeof meta.delivery === "string" ? meta.delivery : null;
-    const priority = typeof meta.priority === "string" ? meta.priority : null;
-
-    if (requested === "interrupt") return "interrupt";
-    if (requested === "start") return "start";
-    if (requested === "steer") return this.activeTurnId ? "steer" : "start";
-    if (priority === "urgent") return this.activeTurnId ? "interrupt" : "start";
-    return this.activeTurnId ? "steer" : "start";
-  }
-
-  private writeState(): void {
-    if (!this.threadId) return;
-    const updatedAt = new Date().toISOString();
-    const state: RuntimeState = {
-      agentId: this.agentId,
-      agentInstanceId: this.agentInstanceId,
-      agentEpoch: this.agentEpoch,
-      threadId: this.threadId,
-      activeTurnId: this.activeTurnId,
-      threadStatus: this.threadStatus,
-      lastSeenMessageId: this.lastSeenMessageId,
-      pendingMessageCount: this.pendingMessages.size,
-      appConnected: this.appConnected,
-      appServerUrl: this.config.appServerUrl,
-      relayUrl: this.config.relayUrl,
-      cwd: this.config.cwd,
-      updatedAt,
-    };
-    writeFileSync(this.config.statePath, JSON.stringify(state, null, 2));
-    if (this.config.contextPath) {
-      mkdirSync(dirname(this.config.contextPath), { recursive: true });
-      writeFileSync(this.config.contextPath, JSON.stringify({
-        version: 1,
-        agentId: this.agentId,
-        provider: "codex",
-        relayUrl: this.config.relayUrl,
-        cwd: this.config.cwd,
-        statePath: this.config.statePath,
-        matchEnv: [
-          { name: "AGENT_RELAY_CONTEXT_PATH", value: this.config.contextPath },
-        ],
-        updatedAt,
-      }, null, 2));
-    }
-  }
-
-  private log(message: string): void {
-    console.error(`${this.logPrefix} ${message}`);
-  }
-
-  private nextRelayBackoffMs(): number {
-    this.relayBackoffMs = this.relayBackoffMs === 0
-      ? this.config.relayBackoffInitialMs
-      : Math.min(this.config.relayBackoffMaxMs, this.relayBackoffMs * 2);
-    return this.relayBackoffMs;
-  }
-}
-
-function createDeliveryBatches(messages: RelayMessage[]): DeliveryBatch[] {
-  const batches: DeliveryBatch[] = [];
-  let current: RelayMessage[] = [];
-
-  for (const message of messages) {
-    if (shouldIsolateMessage(message)) {
-      if (current.length > 0) {
-        batches.push({ messages: current });
-        current = [];
-      }
-      batches.push({ messages: [message] });
-      continue;
-    }
-
-    current.push(message);
-  }
-
-  if (current.length > 0) batches.push({ messages: current });
-  return batches;
-}
-
-function shouldIsolateMessage(message: RelayMessage): boolean {
-  if (message.claimable) return true;
-  const meta = message.meta ?? {};
-  const delivery = typeof meta.delivery === "string" ? meta.delivery : null;
-  const priority = typeof meta.priority === "string" ? meta.priority : null;
-  return delivery === "interrupt" || delivery === "start" || delivery === "steer" || priority === "urgent";
-}
-
-export function formatRelayPrompt(
-  messages: RelayMessage[],
-  opts: { includePrimer?: boolean; headless?: boolean } = {},
-): string {
-  const includePrimer = opts.includePrimer === true;
-  const relayUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
-  const primer = [
-    "Agent Relay live-message primer:",
-    "Treat Agent Relay deliveries as live incoming messages from other agents. Respond or act on them as appropriate.",
-    ...(opts.headless ? ["This Codex session is running headless; Agent Relay is the primary user and agent communication surface."] : []),
-    "For normal replies, prefer `agent-relay /message TARGET BODY --reply-to MSG_ID`; the CLI detects this session's Agent Relay ID.",
-    "For pair chat replies, prefer `agent-relay /pair send PAIR_ID BODY`.",
-    `If the CLI is unavailable, call ${relayUrl}/api/messages or /api/pairs/{pairId}/messages directly and include AGENT_RELAY_TOKEN as X-Agent-Relay-Token when set.`,
-    "",
-  ];
-
-  if (messages.length === 1) {
-    const message = messages[0]!;
-    const lines = [
-      ...(includePrimer ? primer : []),
-      "Agent Relay message received.",
-      "",
-      formatMessageSummary(message),
-      "",
-      `Message ID: ${message.id}`,
-      `From: ${message.from}`,
-      `To: ${message.to}`,
-      `Created: ${new Date(message.createdAt).toISOString()}`,
-    ];
-
-    if (message.subject) lines.push(`Subject: ${message.subject}`);
-    if (message.replyTo) lines.push(`Reply To: ${message.replyTo}`);
-    const pairId = typeof message.payload?.pairId === "string" ? message.payload.pairId : undefined;
-    if (pairId) {
-      lines.push(`Pair ID: ${pairId}`);
-    }
-    lines.push(
-      "",
-      "Body:",
-      message.body,
-      "",
-      pairId
-        ? `Reply routing: pairId=${JSON.stringify(pairId)}.`
-        : `Reply routing: to=${JSON.stringify(message.from)}, replyTo=${message.id}.`,
-    );
-    return lines.join("\n");
-  }
-
-  const lines = [
-    ...(includePrimer ? primer : []),
-    "Agent Relay message batch received.",
-    "",
-    `Count: ${messages.length}`,
-    "",
-  ];
-
-  for (const message of messages) {
-    lines.push(
-      formatMessageSummary(message),
-      `Message ID: ${message.id}`,
-      `From: ${message.from}`,
-      `To: ${message.to}`,
-      `Created: ${new Date(message.createdAt).toISOString()}`,
-    );
-    if (message.subject) lines.push(`Subject: ${message.subject}`);
-    if (message.replyTo) lines.push(`Reply To: ${message.replyTo}`);
-    const pairId = typeof message.payload?.pairId === "string" ? message.payload.pairId : undefined;
-    if (pairId) lines.push(`Pair ID: ${pairId}`);
-    lines.push(
-      pairId
-        ? `Reply routing: pairId=${JSON.stringify(pairId)}.`
-        : `Reply routing: to=${JSON.stringify(message.from)}, replyTo=${message.id}.`,
-    );
-    lines.push("Body:", message.body, "", "---", "");
-  }
-
-  lines.push(
-    "Synthesize these messages into one coherent response or action. Use each message's Reply routing line when replying.",
-  );
-  return lines.join("\n");
-}
-
-function formatMessageSummary(message: RelayMessage): string {
-  const subject = message.subject || "message";
-  if (message.kind === "system" || message.kind === "control") return `SYSTEM [msg:${message.id}]: ${message.body}`;
-  return `[msg:${message.id}] ${message.from} -> ${message.to} | ${subject}: ${message.body}`;
-}
-
-export function agentControlActionForMessage(message: RelayMessage): AgentControlAction | null {
-  if (message.kind !== "control") return null;
-  const control = message.payload?.agentControl;
-  if (!control || typeof control !== "object" || Array.isArray(control)) return null;
-  const action = (control as { action?: unknown }).action;
-  return action === "restart" || action === "shutdown" ? action : null;
-}
-
-function firstAgentControlMessage(messages: RelayMessage[]): { message: RelayMessage; action: AgentControlAction } | null {
-  for (const message of messages) {
-    const action = agentControlActionForMessage(message);
-    if (action) return { message, action };
-  }
-  return null;
-}
-
-function normalizeThread(thread: Thread): Thread {
-  return {
-    ...thread,
-    turns: thread.turns ?? [],
-  };
-}
-
-function syntheticLoadedThread(threadId: string, cwd: string): Thread {
-  return {
-    id: threadId,
-    cwd,
-    status: { type: "idle" },
-    updatedAt: Date.now(),
-    preview: "",
-    turns: [],
-  };
-}
-
-function isThreadMaterializationError(error: unknown): boolean {
-  return describeError(error).includes("not materialized yet");
-}
-
-function isThreadMissingRolloutError(error: unknown): boolean {
-  return describeError(error).includes("no rollout found for thread id");
-}
-
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function envNumber(env: NodeJS.ProcessEnv, name: string, fallback: number): number {
-  const raw = env[name];
-  if (!raw) return fallback;
-  const parsed = Number(raw);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
-}
-
-function isAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export function parseThreadMode(raw: string | undefined): Config["threadMode"] {
-  if (raw === "auto" || raw === "resume" || raw === "start") return raw;
-  return "start";
-}
-
-export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
-  const cwd = env.AGENT_RELAY_CODEX_CWD || process.cwd();
-  const rig = env.AGENT_RELAY_CODEX_RIG || "codex-live";
-  const project = cwd.split("/").filter(Boolean).at(-1) || "unknown";
-  const profile = loadAgentRelayProfile(env, { provider: "codex", rig, project });
-
-  return {
-    relayUrl: env.AGENT_RELAY_URL || "http://127.0.0.1:4850",
-    appServerUrl: env.CODEX_APP_SERVER_URL || "ws://127.0.0.1:4501",
-    cwd,
-    rig,
-    label: profile.label,
-    capabilities: profile.capabilities,
-    tags: profile.tags,
-    channels: profile.channels,
-    profileName: profile.profileName,
-    profileMeta: profile.meta,
-    statePath: env.AGENT_RELAY_CODEX_STATE_PATH || resolve(cwd, "codex/runtime/live-state.json"),
-    contextPath: env.AGENT_RELAY_CONTEXT_PATH || undefined,
-    pollIntervalMs: envNumber(env, "AGENT_RELAY_CODEX_POLL_INTERVAL_MS", 2000),
-    heartbeatIntervalMs: envNumber(env, "AGENT_RELAY_CODEX_HEARTBEAT_INTERVAL_MS", 30000),
-    threadCheckIntervalMs: envNumber(env, "AGENT_RELAY_CODEX_THREAD_CHECK_INTERVAL_MS", 30000),
-    relayBackoffInitialMs: envNumber(env, "AGENT_RELAY_CODEX_RELAY_BACKOFF_INITIAL_MS", 2000),
-    relayBackoffMaxMs: envNumber(env, "AGENT_RELAY_CODEX_RELAY_BACKOFF_MAX_MS", 60000),
-    coalesceWindowMs: envNumber(env, "AGENT_RELAY_CODEX_COALESCE_WINDOW_MS", 600),
-    reconnectInitialDelayMs: envNumber(env, "AGENT_RELAY_CODEX_RECONNECT_INITIAL_MS", 1000),
-    reconnectMaxDelayMs: envNumber(env, "AGENT_RELAY_CODEX_RECONNECT_MAX_MS", 10000),
-    threadMode: parseThreadMode(env.CODEX_THREAD_MODE),
-    threadId: env.CODEX_THREAD_ID || undefined,
-    model: env.CODEX_MODEL || undefined,
-    approvalPolicy: env.AGENT_RELAY_CODEX_APPROVAL_POLICY || undefined,
-    sandbox: env.AGENT_RELAY_CODEX_SANDBOX || undefined,
-    approvalMode: profile.approval
-      ? profile.approval
-      : approvalModeFromPermissions({
-        approvalPolicy: env.AGENT_RELAY_CODEX_APPROVAL_POLICY,
-        sandbox: env.AGENT_RELAY_CODEX_SANDBOX,
-      }),
-    parentPid: envNumber(env, "AGENT_RELAY_CODEX_PARENT_PID", 0) || undefined,
-    assumeLoadedThread: env.AGENT_RELAY_CODEX_ASSUME_LOADED_THREAD === "1" || env.AGENT_RELAY_CODEX_ASSUME_LOADED_THREAD === "true",
-    headless: env.AGENT_RELAY_CODEX_HEADLESS === "1" || env.AGENT_RELAY_CODEX_HEADLESS === "true",
-  };
-}
-
-async function main(): Promise<void> {
-  const config = loadConfig();
-  const sidecar = new CodexLiveSidecar(config);
-  await sidecar.run();
-}
-
-if (import.meta.main) {
-  main().catch((error) => {
-    console.error(error instanceof Error ? error.stack || error.message : String(error));
-    process.exit(1);
-  });
-}