agent-relay-server 0.122.0 → 0.123.0

package/runner/src/codex-version.ts

@@ -0,0 +1,63 @@
+// #1096 review, finding 4 — Codex hooks (CODEX_HOME/hooks.json with Claude-compatible
+// event names) are only consumed by Codex >= 0.124. An older Codex silently ignores the
+// file, so writing it and reporting `provisioning.hooks: applied` would be a lie. This
+// module probes the installed Codex version once and answers whether hook delivery is
+// actually honored, so the assembler can emit a truthful projection (a LOUD warning when
+// the guard cannot fire) instead of a silent absence.
+//
+// TODO(#1096): a post-deploy LIVE check is still owed — assert that a Codex >= 0.124 actually
+// executes CODEX_HOME/hooks.json for these event names (Stop/PreToolUse/…), not just that the
+// version string clears the gate. The version probe is necessary but not sufficient.
+
+import { codexVersionOverrideFromEnv } from "./config";
+
+// Codex releases from this version on ship stable hooks with Claude-compatible events.
+const CODEX_HOOKS_MIN_VERSION = [0, 124, 0] as const;
+
+let cachedProbe: boolean | undefined;
+
+export function codexVersionSupportsHooks(version: string): boolean {
+  const parts = version.split(".").map((n) => parseInt(n, 10));
+  const major = Number.isFinite(parts[0]) ? parts[0]! : 0;
+  const minor = Number.isFinite(parts[1]) ? parts[1]! : 0;
+  const patch = Number.isFinite(parts[2]) ? parts[2]! : 0;
+  const [rMajor, rMinor, rPatch] = CODEX_HOOKS_MIN_VERSION;
+  if (major !== rMajor) return major > rMajor;
+  if (minor !== rMinor) return minor > rMinor;
+  return patch >= rPatch;
+}
+
+export function parseCodexVersion(output: string): string | null {
+  const match = output.match(/(\d+)\.(\d+)\.(\d+)/);
+  return match ? match[0] : null;
+}
+
+function probeCodexVersion(command: string): string | null {
+  try {
+    const result = Bun.spawnSync([command, "--version"], { stdout: "pipe", stderr: "ignore" });
+    if (result.exitCode !== 0) return null;
+    return parseCodexVersion(result.stdout.toString());
+  } catch {
+    return null;
+  }
+}
+
+// Whether the installed Codex actually consumes managed hooks. An explicit
+// AGENT_RELAY_CODEX_VERSION override wins (deterministic tests + operator escape hatch);
+// otherwise the real `codex --version` is probed once and cached. An UNKNOWN version (probe
+// failed / Codex not installed) is treated as supported: we neither block launches nor cry
+// wolf on a machine that can't be inspected — we only claim "not applied" when we can PROVE
+// the version is too old.
+export function codexHooksSupported(command = "codex"): boolean {
+  const override = codexVersionOverrideFromEnv();
+  if (override !== undefined) return override.trim() === "" ? true : codexVersionSupportsHooks(override.trim());
+  if (cachedProbe !== undefined) return cachedProbe;
+  const version = probeCodexVersion(command);
+  cachedProbe = version ? codexVersionSupportsHooks(version) : true;
+  return cachedProbe;
+}
+
+// Test-only: drop the memoized probe so a suite can re-probe under a changed environment.
+export function resetCodexHooksProbeCache(): void {
+  cachedProbe = undefined;
+}

package/runner/src/config.ts

@@ -82,6 +82,13 @@ function relayUrlFromEnv(): string | undefined {
   return process.env.AGENT_RELAY_URL;
 }
 
+// #1096 — override for the Codex hooks version gate (finding 4). An explicit version string
+// bypasses the `codex --version` probe: deterministic in tests, and an operator escape hatch
+// when the probe can't run. Empty string means "assume supported".
+export function codexVersionOverrideFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_CODEX_VERSION;
+}
+
 function textEnvOrFile(name: string): string | undefined {
   const inline = process.env[name];
   if (inline) return inline;

package/runner/src/context-probe-state.ts

@@ -0,0 +1,6 @@
+import { readContextProbeState } from "agent-relay-sdk/context-probe";
+import { contextStateDirFromEnv } from "./config";
+
+export function readRunnerContextProbeState(agentId: string) {
+  return readContextProbeState(agentId, contextStateDirFromEnv());
+}

package/runner/src/continuation-archive.ts

@@ -0,0 +1,179 @@
+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;
+const encoder = new TextEncoder();
+const fatalUtf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+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 encoded = encoder.encode(segment);
+  const bytes = encoded.byteLength;
+  if (bytes <= CONTINUATION_ARCHIVE_MAX_GENERATION_BYTES) {
+    return { segment, keptBytes: bytes, droppedBytes: 0 };
+  }
+  const bounded = decodeUtf8Prefix(encoded, 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 decodeUtf8Prefix(bytes: Uint8Array, maxBytes: number): string {
+  let end = Math.min(maxBytes, bytes.byteLength);
+  while (end > 0) {
+    try {
+      return fatalUtf8Decoder.decode(bytes.subarray(0, end));
+    } catch {
+      end -= 1;
+    }
+  }
+  return "";
+}
+
+function utf8Bytes(value: string): number {
+  return encoder.encode(value).byteLength;
+}