agent-relay-runner 0.120.5 → 0.121.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.120.5",
+  "version": "0.121.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "agent-relay-providers": "0.104.3",
-    "agent-relay-sdk": "0.2.110",
+    "agent-relay-sdk": "0.2.112",
     "callmux": "0.23.0"
   },
   "devDependencies": {

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.120.5",
+  "version": "0.121.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapters/claude-transcript-tail.ts

@@ -0,0 +1,128 @@
+import { open, stat } from "node:fs/promises";
+import { LatestTurnStepAccumulator, type TurnStep } from "./claude-transcript";
+
+const FINGERPRINT_BYTES = 4096;
+
+export interface ClaudeTranscriptFileIdentity {
+  dev: number;
+  ino: number;
+  birthtimeMs: number;
+}
+
+interface TailFingerprint {
+  offset: number;
+  bytes: Buffer;
+}
+
+export interface IncrementalTranscriptPollResult {
+  available: boolean;
+  changed: boolean;
+  reset: boolean;
+  steps: TurnStep[];
+  transcriptLooksComplete: boolean;
+}
+
+export class IncrementalClaudeTranscriptTail {
+  private offset = 0;
+  private pending = Buffer.alloc(0);
+  private identity: ClaudeTranscriptFileIdentity | undefined;
+  private fingerprint: TailFingerprint | undefined;
+  private readonly accumulator = new LatestTurnStepAccumulator();
+
+  async poll(path: string): Promise<IncrementalTranscriptPollResult> {
+    let fileStat: Awaited<ReturnType<typeof stat>>;
+    try {
+      fileStat = await stat(path);
+    } catch {
+      return this.result({ available: false, changed: false, reset: false });
+    }
+
+    const nextIdentity = { dev: fileStat.dev, ino: fileStat.ino, birthtimeMs: fileStat.birthtimeMs };
+    const replaced = this.identity !== undefined && !sameIdentity(this.identity, nextIdentity);
+    const truncated = this.offset > fileStat.size;
+    let reset = replaced || truncated;
+    if (!reset && this.identity && this.fingerprint && fileStat.size >= this.offset) {
+      reset = !(await this.fingerprintMatches(path));
+    }
+    if (reset) this.reset(nextIdentity);
+    else if (!this.identity) this.identity = nextIdentity;
+
+    if (this.offset === fileStat.size) {
+      return this.result({ available: true, changed: false, reset });
+    }
+
+    const length = fileStat.size - this.offset;
+    const buffer = Buffer.alloc(length);
+    let bytesRead = 0;
+    const handle = await open(path, "r");
+    try {
+      const read = await handle.read(buffer, 0, length, this.offset);
+      bytesRead = read.bytesRead;
+    } finally {
+      await handle.close();
+    }
+
+    this.offset += bytesRead;
+    const delta = buffer.subarray(0, bytesRead);
+    this.updateFingerprint(delta);
+    const changed = bytesRead > 0 && this.consume(delta);
+    return this.result({ available: true, changed, reset });
+  }
+
+  private reset(identity: ClaudeTranscriptFileIdentity): void {
+    this.offset = 0;
+    this.pending = Buffer.alloc(0);
+    this.fingerprint = undefined;
+    this.identity = identity;
+    this.accumulator.reset();
+  }
+
+  private async fingerprintMatches(path: string): Promise<boolean> {
+    if (!this.fingerprint) return true;
+    const buffer = Buffer.alloc(this.fingerprint.bytes.length);
+    const handle = await open(path, "r");
+    try {
+      const read = await handle.read(buffer, 0, buffer.length, this.fingerprint.offset);
+      return read.bytesRead === buffer.length && buffer.equals(this.fingerprint.bytes);
+    } finally {
+      await handle.close();
+    }
+  }
+
+  private updateFingerprint(delta: Buffer): void {
+    if (!delta.length) return;
+    const previous = this.fingerprint?.bytes ?? Buffer.alloc(0);
+    const combined = previous.length ? Buffer.concat([previous, delta]) : delta;
+    const bytes = Buffer.from(combined.subarray(Math.max(0, combined.length - FINGERPRINT_BYTES)));
+    this.fingerprint = { offset: this.offset - bytes.length, bytes };
+  }
+
+  private consume(delta: Buffer): boolean {
+    if (!delta.length) return false;
+    const combined = this.pending.length ? Buffer.concat([this.pending, delta]) : delta;
+    const lastNewline = combined.lastIndexOf(0x0a);
+    if (lastNewline === -1) {
+      this.pending = Buffer.from(combined);
+      return false;
+    }
+
+    const complete = combined.subarray(0, lastNewline + 1);
+    this.pending = Buffer.from(combined.subarray(lastNewline + 1));
+    this.accumulator.appendJsonl(complete.toString("utf8"));
+    return true;
+  }
+
+  private result(input: { available: boolean; changed: boolean; reset: boolean }): IncrementalTranscriptPollResult {
+    return {
+      ...input,
+      steps: this.accumulator.steps,
+      transcriptLooksComplete: this.accumulator.transcriptLooksComplete,
+    };
+  }
+}
+
+function sameIdentity(a: ClaudeTranscriptFileIdentity, b: ClaudeTranscriptFileIdentity): boolean {
+  return a.dev === b.dev && a.ino === b.ino && a.birthtimeMs === b.birthtimeMs;
+}
+
+export const sameClaudeTranscriptFileIdentityForTests = sameIdentity;

package/src/adapters/claude-transcript.ts

@@ -21,7 +21,7 @@ interface TranscriptBlock {
   is_error?: boolean;
 }
 
-interface TurnStep {
+export interface TurnStep {
   type: "narration" | "reasoning" | "tool";
   text: string;
   label?: string;
@@ -83,20 +83,9 @@ function assistantText(entry: TranscriptEntry): string {
  * assistant block is written to disk.
  */
 export function transcriptLooksComplete(jsonl: string): boolean {
-  const lines = jsonl.split("\n");
-  let lastAssistantStopReason: string | undefined;
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    try {
-      const entry = JSON.parse(trimmed) as TranscriptEntry;
-      if (isSidechainEntry(entry)) continue;
-      if (entry.type === "assistant") lastAssistantStopReason = entry.message?.stop_reason;
-    } catch {
-      continue;
-    }
-  }
-  return lastAssistantStopReason === "end_turn";
+  const state = new LatestTurnStepAccumulator();
+  state.appendJsonl(jsonl);
+  return state.transcriptLooksComplete;
 }
 
 /**
@@ -251,34 +240,65 @@ export function extractFinalAssistantMessageAfterEntry(jsonl: string, afterEntry
  * tailer can emit only the ones it hasn't seen yet.
  */
 export function extractLatestTurnSteps(jsonl: string): TurnStep[] {
-  const lines = jsonl.split("\n");
-  let steps: TurnStep[] = [];
-  for (const line of lines) {
+  const state = new LatestTurnStepAccumulator();
+  state.appendJsonl(jsonl);
+  return state.steps;
+}
+
+export class LatestTurnStepAccumulator {
+  private latestSteps: TurnStep[] = [];
+  private lastAssistantStopReason: string | undefined;
+  private parsedEntries = 0;
+
+  get steps(): TurnStep[] {
+    return [...this.latestSteps];
+  }
+
+  get transcriptLooksComplete(): boolean {
+    return this.lastAssistantStopReason === "end_turn";
+  }
+
+  get entryCount(): number {
+    return this.parsedEntries;
+  }
+
+  reset(): void {
+    this.latestSteps = [];
+    this.lastAssistantStopReason = undefined;
+    this.parsedEntries = 0;
+  }
+
+  appendJsonl(jsonl: string): void {
+    for (const line of jsonl.split("\n")) this.appendLine(line);
+  }
+
+  appendLine(line: string): void {
     const trimmed = line.trim();
-    if (!trimmed) continue;
+    if (!trimmed) return;
     let entry: TranscriptEntry;
     try {
       entry = JSON.parse(trimmed) as TranscriptEntry;
     } catch {
-      continue;
+      return;
     }
-    if (isSidechainEntry(entry)) continue;
+    this.parsedEntries += 1;
+    if (isSidechainEntry(entry)) return;
+    if (entry.type === "assistant") this.lastAssistantStopReason = entry.message?.stop_reason;
     if (isRealUserPrompt(entry)) {
-      steps = [];
-      continue;
+      this.latestSteps = [];
+      return;
     }
-    if (entry.type !== "assistant") continue;
+    if (entry.type !== "assistant") return;
     for (const b of blocks(entry.message)) {
       if (b.type === "text" && typeof b.text === "string" && b.text.trim()) {
-        steps.push({ type: "narration", text: b.text.trim() });
+        this.latestSteps.push({ type: "narration", text: b.text.trim() });
       } else if (b.type === "thinking" && typeof b.thinking === "string" && b.thinking.trim()) {
-        steps.push({ type: "reasoning", text: b.thinking.trim() });
+        this.latestSteps.push({ type: "reasoning", text: b.thinking.trim() });
       } else if (b.type === "tool_use" && typeof b.name === "string" && b.name) {
-        steps.push({ type: "tool", label: b.name, text: summarizeToolUse(b.name, b.input) });
+        this.latestSteps.push({ type: "tool", label: b.name, text: summarizeToolUse(b.name, b.input) });
       }
     }
   }
-  return steps;
 }
 
 /**

package/src/mcp-outbox.ts

@@ -1,5 +1,6 @@
 import type { SendMessageInput } from "agent-relay-sdk";
 import type { RelayHttpClient } from "agent-relay-sdk";
+import { errMessage } from "agent-relay-sdk";
 import { relayMcpEndpoint } from "./relay-mcp";
 import type { OutboxRecord } from "./outbox";
 import { deliverContinuationArchiveRecord } from "./continuation-archive";
@@ -27,6 +28,23 @@ export async function deliverRunnerOutboxEvent(input: RunnerOutboxDelivery): Pro
       });
       return;
     }
+    if (record.kind === "session-message-batch") {
+      const messages = Array.isArray((record.payload as { messages?: unknown }).messages)
+        ? (record.payload as { messages: SendMessageInput[] }).messages
+        : [];
+      const batch = messages.map((message, index) => ({
+        ...message,
+        occurredAt: typeof message.occurredAt === "number" ? message.occurredAt : record.occurredAt,
+        idempotencyKey: message.idempotencyKey ?? `${record.idempotencyKey}:${index}`,
+      }));
+      try {
+        await http.sendMessages(batch);
+      } catch (error) {
+        if (!isDeterministicValidationError(error)) throw error;
+        await deliverSessionBatchItems(input, batch);
+      }
+      return;
+    }
     if (record.kind === "insight") {
       await http.recordInsightObservation({
         ...(record.payload as Parameters<RelayHttpClient["recordInsightObservation"]>[0]),
@@ -55,6 +73,22 @@ export async function deliverRunnerOutboxEvent(input: RunnerOutboxDelivery): Pro
   }
 }
 
+async function deliverSessionBatchItems(input: RunnerOutboxDelivery, messages: SendMessageInput[]): Promise<void> {
+  for (const message of messages) {
+    try {
+      await input.http.sendMessage(message);
+    } catch (error) {
+      if (!isDeterministicValidationError(error)) throw error;
+      logger.warn("outbox", `dropping invalid session batch item: ${errMessage(error)}`);
+    }
+  }
+}
+
+function isDeterministicValidationError(error: unknown): boolean {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  return status === 400 || status === 413 || status === 422;
+}
+
 export async function deliverBufferedMcpCall(input: {
   record: OutboxRecord;
   relayUrl: string;

package/src/runner-core.ts

@@ -17,6 +17,7 @@ import { startControlServer, type ControlServer, type ResolvedPermissionPrompt }
 import { ReplyObligationCache, obligationRequiresExplicitReply, responseCaptureReplyRoute } from "./reply-obligation-cache";
 import { Outbox, type OutboxRecord } from "./outbox";
 import { extractLastAssistantTurn, extractLastAssistantTurnAfterEntry, countTranscriptEntries, extractFinalAssistantMessage, extractFinalAssistantMessageAfterEntry, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptLooksComplete } from "./adapters/claude-transcript";
+import { IncrementalClaudeTranscriptTail } from "./adapters/claude-transcript-tail";
 import { getManifest } from "agent-relay-providers";
 import { profileUsesProviderHostGlobals } from "./profile-home";
 import { RELAY_MCP_TOKEN_ENV, relayMcpEndpoint, resolveSharedMcpUrl } from "./relay-mcp";
@@ -147,8 +148,10 @@ const INITIAL_PROMPT_FIRST_READY_TIMEOUT_MS = 30_000;
 const INITIAL_PROMPT_RETRY_READY_TIMEOUT_MS = 10_000;
 const MAX_INITIAL_PROMPT_ATTEMPTS = 6;
 // Reasoning tailer poll cadence (item 5). Coarse on purpose — reasoning is a
-// discreet progress signal, not a token stream, so ~1.2s keeps it light.
+// discreet progress signal, not a token stream; each tick reads only appended
+// transcript bytes.
 const REASONING_POLL_MS = 1_200;
+const SESSION_MIRROR_BATCH_MAX = 100;
 interface RunnerTimelineEvent {
   status: string;
   id?: string;
@@ -160,9 +163,7 @@ interface RunnerTimelineEvent {
 }
 
 interface ReasoningTailState {
-  timer: ReturnType<typeof setInterval>;
-  seen: Set<string>;
-  emittedNarrationKeys: Set<string>;
+  timer: ReturnType<typeof setInterval>; emittedNarrationKeys: Set<string>;
   poll(): Promise<void>;
 }
 
@@ -182,6 +183,7 @@ export class AgentRunner {
   // their own FIFO queue stops one transient trace failure from head-of-line blocking real-message
   // delivery (and vice versa); its backoff is capped low since a stale live-mirror frame is cheap.
   private readonly sessionOutbox: Outbox;
+  private sessionBatchSeq = 0;
   private readonly insights: RunnerInsights;
   private readonly busyReconciler: BusyReconciler;
   private readonly claudeQuotaHarvest: ClaudeQuotaHarvest;
@@ -1535,6 +1537,39 @@ export class AgentRunner {
     });
   }
 
+  private publishSessionEventsBatch(inputs: Array<{
+    from: string;
+    to: string;
+    body: string;
+    session: MessageSessionMeta;
+    replyTo?: number;
+  }>): void {
+    for (let i = 0; i < inputs.length; i += SESSION_MIRROR_BATCH_MAX) {
+      const chunk = inputs.slice(i, i + SESSION_MIRROR_BATCH_MAX);
+      if (chunk.length === 1) {
+        this.publishSessionEvent(chunk[0]!);
+        continue;
+      }
+      const messages = chunk.map((input) => {
+        const stepId = input.session.stepId;
+        return {
+          from: input.from,
+          to: input.to,
+          ...(input.replyTo ? { replyTo: input.replyTo } : {}),
+          kind: "session",
+          body: input.body,
+          ...(stepId ? { idempotencyKey: `session-step:${input.from}:${input.session.turnId ?? ""}:${stepId}` } : {}),
+          payload: { session: { provider: this.options.provider, ...input.session } },
+        } satisfies SendMessageInput;
+      });
+      this.sessionOutbox.enqueue({
+        kind: "session-message-batch",
+        idempotencyKey: `session-batch:${this.agentId}:${++this.sessionBatchSeq}:${messages.length}`,
+        payload: { messages },
+      });
+    }
+  }
+
   // Map queued records to HTTP calls. Throw to retry, return to ack/delete.
   private async deliverOutboxEvent(record: OutboxRecord): Promise<void> {
     await deliverRunnerOutboxEvent({
@@ -1827,6 +1862,7 @@ export class AgentRunner {
     // so two identical steps in one turn — same tool, same input — both surface (#265).
     const seen = new Set<string>();
     const emittedNarrationKeys = new Set<string>();
+    const transcriptTail = new IncrementalClaudeTranscriptTail();
     const turnIdAtStart = this.currentTurnId;
     // On the first poll the new prompt usually hasn't landed in the transcript yet,
     // so extractLatestTurnSteps still returns the PRIOR (completed) turn. Seed those
@@ -1838,24 +1874,25 @@ export class AgentRunner {
     let seeded = false;
     let pendingPoll = Promise.resolve();
     const pollBody = async (): Promise<void> => {
-      let jsonl: string;
-      try { jsonl = await readFile(transcriptPath, "utf8"); } catch { return; }
-      let steps: ReturnType<typeof extractLatestTurnSteps>;
-      try { steps = extractLatestTurnSteps(jsonl); } catch { return; }
-      const keyed = stepDedupKeys(steps).map((sig, i) => ({ sig, step: steps[i]! }));
+      const result = await transcriptTail.poll(transcriptPath);
+      if (!result.available) return;
+      if (result.reset) { seen.clear(); emittedNarrationKeys.clear(); seeded = false; }
+      if (!result.changed && (seeded || (!result.steps.length && !result.transcriptLooksComplete))) return;
+      const keyed = stepDedupKeys(result.steps).map((sig, i) => ({ sig, step: result.steps[i]! }));
       if (!seeded) {
         seeded = true;
-        if (transcriptLooksComplete(jsonl)) {
+        if (result.transcriptLooksComplete) {
           for (const { sig } of keyed) seen.add(sig);
         }
       }
       const turnId = this.currentTurnId ?? turnIdAtStart;
       let emitted = 0;
+      const batch: Array<{ from: string; to: string; body: string; session: MessageSessionMeta }> = [];
       for (const { sig, step } of keyed) {
         if (seen.has(sig)) continue;
         seen.add(sig);
         emitted += 1;
-        this.publishSessionEvent({
+        batch.push({
           from: this.agentId,
           to: "user",
           body: step.text,
@@ -1863,6 +1900,7 @@ export class AgentRunner {
         });
         if (step.type === "narration") emittedNarrationKeys.add(sig);
       }
+      this.publishSessionEventsBatch(batch);
       if (emitted) this.sessionDebug(`reasoning tail emitted ${emitted} step(s) (turn ${turnId ?? "?"}, ${seen.size} total)`);
     };
     const poll = (): Promise<void> => {
@@ -1870,7 +1908,7 @@ export class AgentRunner {
       pendingPoll = next.catch(() => {});
       return next;
     };
-    this.reasoningTail = { seen, emittedNarrationKeys, poll, timer: setInterval(() => { void poll(); }, REASONING_POLL_MS) };
+    this.reasoningTail = { emittedNarrationKeys, poll, timer: setInterval(() => { void poll(); }, REASONING_POLL_MS) };
     this.sessionLog(`reasoning tail started (turn ${turnIdAtStart ?? "?"})`);
     void poll();
   }