agent-relay-runner 0.52.0 → 0.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapters/codex.ts

@@ -392,6 +392,21 @@ export class CodexAdapter implements ProviderAdapter {
             updatedAt: Date.now(),
           },
         });
+      } else if (event.message.method === CODEX_MCP_ELICITATION_METHOD && isCodexHeadless(process)) {
+        // Codex routes per-MCP-tool-call approval through the MCP elicitation channel
+        // (request_id `mcp_tool_call_approval_*`): even with `approval_policy="never"`, a
+        // downstream server's elicitation — or codex's own per-call approval gate — is
+        // forwarded to the app-server client as `mcpServer/elicitation/request`. A headless
+        // managed agent has no human to answer it; the old -32601 reject makes codex resolve
+        // the elicitation as `Decline`, so the MCP tool call dies with "user rejected MCP tool
+        // call" — stranding read-only recon/reviewer workers with no egress to report back
+        // over the bus (#395). The agent is already bounded by its scoped relay token + the
+        // codex sandbox, so auto-accept (spec-compliant `{ action: "accept" }`, not codex's
+        // legacy `{ decision: "approved" }`) so the agent's reporting/recon MCP tools run.
+        const client = process.meta?.client as CodexAppClient | undefined;
+        const serverName = isRecord(event.message.params) ? stringValue(event.message.params.serverName) : undefined;
+        logger.info("codex", `auto-accepting headless MCP elicitation from ${serverName ?? "unknown server"} so the agent's MCP tools can run (#395)`);
+        client?.respondToServerRequest(event.message.id, codexHeadlessElicitationResponse());
       } else {
         const client = process.meta?.client as CodexAppClient | undefined;
         logger.warn("codex", `rejecting unknown Codex server-request method: ${event.message.method}`);
@@ -683,6 +698,25 @@ function codexItemTypeFromMethod(method: string): string | undefined {
   return match?.[1];
 }
 
+// Codex forwards MCP elicitation (incl. its per-tool-call approval gate) to the app-server
+// client under this server-request method (#395). See handleCodexEvent for why a headless
+// agent must answer it instead of rejecting it.
+export const CODEX_MCP_ELICITATION_METHOD = "mcpServer/elicitation/request";
+
+// A managed agent with no attended TUI (the spawn intent, `config.headless`) has no human to
+// resolve an elicitation. Such agents are the #395 case; interactive (TUI) sessions leave the
+// elicitation to the human in the attached terminal.
+function isCodexHeadless(process: ManagedProcess): boolean {
+  return (process.meta?.config as RunnerSpawnConfig | undefined)?.headless === true;
+}
+
+// Spec-compliant auto-accept for a headless agent's MCP elicitation. `action` (not codex's
+// legacy `decision`) is the load-bearing field; `content: {}` approves codex's per-tool-call
+// gate and any no-required-field form without fabricating runtime field values for the agent.
+export function codexHeadlessElicitationResponse(): Record<string, unknown> {
+  return { action: "accept", content: {}, _meta: null };
+}
+
 function codexApprovalFromServerRequest(message: { id: string | number; method: string; params?: unknown }): { pending: PendingCodexApproval; view: Record<string, unknown> } | null {
   if (!isRecord(message.params)) return null;
   const method = message.method;

package/src/continuation-archive.ts

@@ -0,0 +1,176 @@
+import type { RelayHttpClient } from "agent-relay-sdk";
+import type { OutboxRecord } from "./outbox";
+
+const CONTINUATION_ARCHIVE_MAX_POST_BODY_BYTES = 64 * 1024;
+const CONTINUATION_ARCHIVE_CHUNK_TARGET_BYTES = 56 * 1024;
+const CONTINUATION_ARCHIVE_MAX_GENERATION_BYTES = 8 * 1024 * 1024;
+
+interface ContinuationArchiveOutboxPayload {
+  agentId: string;
+  segment: string;
+  generation?: number;
+  deliveredChunks?: number;
+  totalChunks?: number;
+}
+
+interface ContinuationArchiveResponse {
+  archive?: { generation?: unknown };
+}
+
+export function boundContinuationArchiveSegment(segment: string): { segment: string; keptBytes: number; droppedBytes: number } {
+  const bytes = utf8Bytes(segment);
+  if (bytes <= CONTINUATION_ARCHIVE_MAX_GENERATION_BYTES) {
+    return { segment, keptBytes: bytes, droppedBytes: 0 };
+  }
+  const bounded = takeUtf8Prefix(segment, CONTINUATION_ARCHIVE_MAX_GENERATION_BYTES);
+  const keptBytes = utf8Bytes(bounded);
+  return { segment: bounded.trimEnd(), keptBytes, droppedBytes: bytes - keptBytes };
+}
+
+export async function deliverContinuationArchiveRecord(input: {
+  record: OutboxRecord;
+  http: Pick<RelayHttpClient, "recordContinuationArchive">;
+  updatePayload: (seq: number, payload: unknown) => void;
+  sessionLog: (message: string) => void;
+}): Promise<void> {
+  const payload = input.record.payload as ContinuationArchiveOutboxPayload;
+  let segment = payload.segment;
+  if (!payload.agentId || typeof segment !== "string") throw new Error("invalid continuation archive outbox payload");
+
+  const bounded = boundContinuationArchiveSegment(segment);
+  if (bounded.droppedBytes > 0) {
+    segment = bounded.segment;
+    input.sessionLog(`continuation archive truncated at ${bounded.keptBytes} bytes; dropped ${bounded.droppedBytes} bytes before delivery`);
+    input.updatePayload(input.record.seq, { ...payload, segment, deliveredChunks: 0, totalChunks: undefined, generation: undefined });
+  }
+
+  const chunks = splitContinuationArchiveSegment({
+    agentId: payload.agentId,
+    segment,
+    occurredAt: input.record.occurredAt,
+  });
+  const knownGeneration = Number.isSafeInteger(payload.generation) ? payload.generation : undefined;
+  const deliveredChunks = knownGeneration === undefined ? 0 : Math.max(0, Math.min(payload.deliveredChunks ?? 0, chunks.length));
+  let generation = knownGeneration;
+
+  for (let index = deliveredChunks; index < chunks.length; index += 1) {
+    const request = {
+      agentId: payload.agentId,
+      segment: chunks[index]!,
+      occurredAt: input.record.occurredAt,
+      ...(generation !== undefined ? { generation } : {}),
+    };
+    assertContinuationArchivePostFits(request);
+    const response = await input.http.recordContinuationArchive(request) as ContinuationArchiveResponse;
+    const returnedGeneration = archiveGeneration(response);
+    if (generation === undefined) {
+      if (returnedGeneration === undefined) throw new Error("continuation archive response missing generation");
+      generation = returnedGeneration;
+    } else if (returnedGeneration !== undefined && returnedGeneration !== generation) {
+      throw new Error(`continuation archive generation mismatch: expected ${generation}, got ${returnedGeneration}`);
+    }
+    input.updatePayload(input.record.seq, {
+      ...payload,
+      segment,
+      generation,
+      deliveredChunks: index + 1,
+      totalChunks: chunks.length,
+    } satisfies ContinuationArchiveOutboxPayload);
+  }
+}
+
+function splitContinuationArchiveSegment(input: { agentId: string; segment: string; occurredAt: number }): string[] {
+  const chunks: string[] = [];
+  let current = "";
+  for (const line of transcriptLines(input.segment)) {
+    if (!line) continue;
+    if (fitsContinuationArchiveChunk(input.agentId, line, input.occurredAt)) {
+      const next = current ? current + line : line;
+      if (utf8Bytes(next) <= CONTINUATION_ARCHIVE_CHUNK_TARGET_BYTES && fitsContinuationArchiveChunk(input.agentId, next, input.occurredAt)) {
+        current = next;
+        continue;
+      }
+      if (current) chunks.push(current.trimEnd());
+      current = line;
+      continue;
+    }
+    if (current) {
+      chunks.push(current.trimEnd());
+      current = "";
+    }
+    chunks.push(...splitLongContinuationArchiveLine(input.agentId, line, input.occurredAt));
+  }
+  if (current) chunks.push(current.trimEnd());
+  return chunks.filter((chunk) => chunk.length > 0);
+}
+
+function transcriptLines(segment: string): string[] {
+  const lines = segment.match(/[^\n]*(?:\n|$)/g) ?? [segment];
+  return lines.filter((line) => line.length > 0);
+}
+
+function splitLongContinuationArchiveLine(agentId: string, line: string, occurredAt: number): string[] {
+  const chars = Array.from(line);
+  const chunks: string[] = [];
+  let offset = 0;
+  while (offset < chars.length) {
+    let low = 1;
+    let high = chars.length - offset;
+    let best = 0;
+    while (low <= high) {
+      const mid = Math.floor((low + high) / 2);
+      const candidate = chars.slice(offset, offset + mid).join("");
+      if (utf8Bytes(candidate) <= CONTINUATION_ARCHIVE_CHUNK_TARGET_BYTES && fitsContinuationArchiveChunk(agentId, candidate, occurredAt)) {
+        best = mid;
+        low = mid + 1;
+      } else {
+        high = mid - 1;
+      }
+    }
+    if (best === 0) throw new Error("continuation archive chunk budget cannot fit one character");
+    chunks.push(chars.slice(offset, offset + best).join(""));
+    offset += best;
+  }
+  return chunks;
+}
+
+function fitsContinuationArchiveChunk(agentId: string, segment: string, occurredAt: number): boolean {
+  return continuationArchivePostBytes({
+    agentId,
+    segment,
+    occurredAt,
+    generation: Number.MAX_SAFE_INTEGER,
+  }) < CONTINUATION_ARCHIVE_MAX_POST_BODY_BYTES;
+}
+
+function assertContinuationArchivePostFits(input: { agentId: string; segment: string; occurredAt: number; generation?: number }): void {
+  const bytes = continuationArchivePostBytes(input);
+  if (bytes >= CONTINUATION_ARCHIVE_MAX_POST_BODY_BYTES) {
+    throw new Error(`continuation archive chunk JSON body is ${bytes} bytes; max is ${CONTINUATION_ARCHIVE_MAX_POST_BODY_BYTES - 1}`);
+  }
+}
+
+function continuationArchivePostBytes(input: { agentId: string; segment: string; occurredAt: number; generation?: number }): number {
+  return utf8Bytes(JSON.stringify(input));
+}
+
+function archiveGeneration(response: ContinuationArchiveResponse): number | undefined {
+  const generation = response.archive?.generation;
+  return typeof generation === "number" && Number.isSafeInteger(generation) && generation >= 0 ? generation : undefined;
+}
+
+function takeUtf8Prefix(value: string, maxBytes: number): string {
+  let used = 0;
+  let out = "";
+  for (const char of value) {
+    const bytes = utf8Bytes(char);
+    if (used + bytes > maxBytes) break;
+    out += char;
+    used += bytes;
+  }
+  return out;
+}
+
+function utf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}

package/src/outbox.ts

@@ -298,6 +298,11 @@ export class Outbox {
     return (this.db.query("SELECT count(*) AS n FROM outbox WHERE poisoned = 0").get() as { n: number }).n;
   }
 
+  updatePayload(seq: number, payload: unknown): void {
+    const payloadJson = JSON.stringify(payload ?? null);
+    this.db.query("UPDATE outbox SET payload = ? WHERE seq = ? AND poisoned = 0").run(payloadJson, seq);
+  }
+
   poisonedCount(): number {
     return (this.db.query("SELECT count(*) AS n FROM outbox WHERE poisoned = 1").get() as { n: number }).n;
   }

package/src/runner.ts

@@ -21,6 +21,7 @@ import { RelayMcpProxy } from "./relay-mcp-proxy";
 import { runtimeMetadata } from "./version";
 import { logger, parseLogLevel } from "./logger";
 import { ensureSessionScratch, reapSessionScratch, sweepStaleSessions, type SessionScratchLayout } from "./session-scratch";
+import { boundContinuationArchiveSegment, deliverContinuationArchiveRecord } from "./continuation-archive";
 
 // A destructive session transition. The runner runs end-of-session work (Insights
 // capture, #183/#184) before the invasive operation and, during that window, presents a
@@ -1289,9 +1290,7 @@ export class AgentRunner {
     });
   }
 
-  // The outbox transport: map a queued record to its HTTP call. Throw to retry, return to
-  // ack (delete). occurredAt + idempotencyKey are injected from the record so retries are
-  // exactly-once server-side and carry true event time.
+  // Map queued records to HTTP calls. Throw to retry, return to ack/delete.
   private async deliverOutboxEvent(record: OutboxRecord): Promise<void> {
     try {
       if (record.kind === "session-message") {
@@ -1310,10 +1309,7 @@ export class AgentRunner {
         return;
       }
       if (record.kind === "continuation-archive") {
-        await this.http.recordContinuationArchive({
-          ...(record.payload as Parameters<RelayHttpClient["recordContinuationArchive"]>[0]),
-          occurredAt: record.occurredAt,
-        });
+        await deliverContinuationArchiveRecord({ record, http: this.http, updatePayload: (seq, payload) => this.outbox.updatePayload(seq, payload), sessionLog: (message) => this.sessionLog(message) });
         return;
       }
       if (record.kind === "mcp-tool-call") {
@@ -1510,14 +1506,16 @@ export class AgentRunner {
     const segment = archive.slice(this.archiveObservedChars).trim();
     this.archiveObservedChars = archive.length;
     if (!segment) return;
+    const bounded = boundContinuationArchiveSegment(segment);
+    if (bounded.droppedBytes > 0) this.sessionLog(`continuation archive truncated at ${bounded.keptBytes} bytes; dropped ${bounded.droppedBytes} bytes (${reason})`);
     this.outbox.enqueue({
       kind: "continuation-archive",
       payload: {
         agentId: this.agentId,
-        segment,
+        segment: bounded.segment,
       },
     });
-    this.sessionLog(`continuation archive queued (${segment.length} chars, ${reason})`);
+    this.sessionLog(`continuation archive queued (${bounded.segment.length} chars, ${reason})`);
   }
 
   private async captureContextRatio(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {