@relayflows/sdk 2.0.21 → 2.0.23

package/src/transcript-tail.ts

@@ -0,0 +1,193 @@
+// Bounded transcript tails: the last 64 KiB of an agent attempt's stdout and
+// stderr, on disk beside its `pty.sock`.
+//
+// Nothing else holds the transcript. The worker buffers it in memory and
+// publishes it live to the sidechannel; a failed agent attempt's output is
+// nulled in the journal (machine.rs), leaving at most 2,000 chars of gate
+// `detail`. So "why did my last attempt end" was unanswerable from disk.
+//
+// These files are evidence, not the record: best-effort, bounded, rewritten
+// in place, never a reason for a step to fail. The journal remains truth.
+// The file is raw; `flows status` redacts on read, which is the same trust
+// boundary as `pty.sock` today (same OS user, mode 0600).
+
+import { mkdir, open, readFile, rename } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { ptySocketPath } from './pty-sidechannel.js';
+import { redact } from './redact.js';
+import type { StepTails, TailSource, TranscriptTail } from './cli/status.js';
+import type { StepView } from './run-state.js';
+
+export const TAIL_CAPACITY_BYTES = 64 * 1024;
+/** At most four rewrites a second, however fast the agent talks. */
+export const TAIL_FLUSH_INTERVAL_MS = 250;
+/**
+ * How long a spawn's completion will wait for the final tail flush. Transcript
+ * evidence is best-effort, so a stalled filesystem must cost the step this
+ * much and no more — past it the invocation settles and the close runs on.
+ */
+export const TAIL_CLOSE_TIMEOUT_MS = 2_000;
+
+export type TailStream = 'stdout' | 'stderr';
+
+export interface TailIdentity {
+  dataDir: string;
+  runId: string;
+  stepId: string;
+  attempt: number;
+}
+
+/** The first line of every tail file, so a stale file is never mistaken for this attempt's. */
+export interface TailHeader {
+  v: 1;
+  run_id: string;
+  step_id: string;
+  attempt: number;
+  started_at_ms: number;
+}
+
+export function transcriptTailPath(identity: TailIdentity, stream: TailStream): string {
+  if (!Number.isSafeInteger(identity.attempt) || identity.attempt < 0) throw new Error('Invalid transcript tail attempt');
+  return join(dirname(ptySocketPath(identity)), `attempt-${identity.attempt}.${stream}.tail`);
+}
+
+export interface TranscriptTailWriter {
+  append(chunk: Buffer): void;
+  /** Flush what is pending and stop. Resolves once the last write has settled, success or not. */
+  close(): Promise<void>;
+}
+
+/**
+ * A ring of the last {@link TAIL_CAPACITY_BYTES} bytes, flushed to
+ * `attempt-<n>.<stream>.tail` at most every {@link TAIL_FLUSH_INTERVAL_MS}.
+ * A write failure is reported once as a process warning and then ignored:
+ * the attempt continues, and `flows status` will say no transcript is on disk.
+ */
+export function openTranscriptTail(
+  identity: TailIdentity,
+  stream: TailStream,
+  startedAtMs = Date.now(),
+  warn: (message: string) => void = (message) => process.emitWarning(message),
+): TranscriptTailWriter {
+  const path = transcriptTailPath(identity, stream);
+  const header = JSON.stringify({ v: 1, run_id: identity.runId, step_id: identity.stepId, attempt: identity.attempt, started_at_ms: startedAtMs } satisfies TailHeader);
+  const ring: Buffer[] = [];
+  let ringBytes = 0;
+  let dirty = false;
+  let closed = false;
+  let failed = false;
+  let timer: NodeJS.Timeout | undefined;
+  let inFlight: Promise<void> = Promise.resolve();
+
+  const flush = (): Promise<void> => {
+    if (!dirty || failed) return inFlight;
+    dirty = false;
+    const body = Buffer.concat([Buffer.from(`${header}\n`), ...ring]);
+    inFlight = inFlight.then(async () => {
+      // Write beside, then rename over: a reader never sees a torn file.
+      const staging = `${path}.tmp`;
+      await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+      const file = await open(staging, 'w', 0o600);
+      try { await file.writeFile(body); } finally { await file.close(); }
+      await rename(staging, path);
+    }).catch((error: unknown) => {
+      if (failed) return;
+      failed = true;
+      warn(`Transcript tail for ${identity.runId}/${identity.stepId} attempt ${identity.attempt} (${stream}) could not be written; the step continues without it: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    return inFlight;
+  };
+
+  return {
+    append(chunk) {
+      if (closed || failed || chunk.length === 0) return;
+      if (chunk.length >= TAIL_CAPACITY_BYTES) {
+        ring.splice(0, ring.length, Buffer.from(chunk.subarray(chunk.length - TAIL_CAPACITY_BYTES)));
+        ringBytes = TAIL_CAPACITY_BYTES;
+      } else {
+        ring.push(Buffer.from(chunk));
+        ringBytes += chunk.length;
+        while (ringBytes > TAIL_CAPACITY_BYTES) {
+          const excess = ringBytes - TAIL_CAPACITY_BYTES;
+          const head = ring[0]!;
+          if (head.length <= excess) { ring.shift(); ringBytes -= head.length; } else { ring[0] = head.subarray(excess); ringBytes -= excess; }
+        }
+      }
+      dirty = true;
+      if (timer === undefined) {
+        timer = setTimeout(() => { timer = undefined; void flush(); }, TAIL_FLUSH_INTERVAL_MS);
+        timer.unref();
+      }
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      if (timer !== undefined) { clearTimeout(timer); timer = undefined; }
+      await flush();
+    },
+  };
+}
+
+/** A tail file parsed and checked against the attempt it claims to be. */
+export interface ReadTail {
+  header: TailHeader;
+  /** Bytes of transcript on disk, after the header line. */
+  bytes: number;
+  text: string;
+}
+
+/**
+ * Read one tail file. `undefined` when absent, unparseable, or written for a
+ * different attempt — or for this attempt number but before the journal says
+ * the attempt began, which is a file left by an earlier life of this data dir.
+ */
+export async function readTranscriptTail(
+  identity: TailIdentity,
+  stream: TailStream,
+  attemptStartedAtMs: number | null,
+): Promise<ReadTail | undefined> {
+  let raw: Buffer;
+  try {
+    raw = await readFile(transcriptTailPath(identity, stream));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+  const newline = raw.indexOf(10);
+  if (newline < 0) return undefined;
+  let header: unknown;
+  try { header = JSON.parse(raw.subarray(0, newline).toString('utf8')); } catch { return undefined; }
+  if (header === null || typeof header !== 'object') return undefined;
+  const claimed = header as Partial<TailHeader>;
+  if (claimed.v !== 1 || claimed.run_id !== identity.runId || claimed.step_id !== identity.stepId
+    || claimed.attempt !== identity.attempt || typeof claimed.started_at_ms !== 'number') return undefined;
+  if (attemptStartedAtMs !== null && claimed.started_at_ms < attemptStartedAtMs) return undefined;
+  const body = raw.subarray(newline + 1);
+  return { header: claimed as TailHeader, bytes: body.length, text: body.toString('utf8') };
+}
+
+/**
+ * Redact the whole tail before splitting it. A direct agent inherits the
+ * worker's environment, so it can print a multiline secret; splitting first
+ * meant no line held the whole value and `replaceAll` matched none of them.
+ */
+function lastLines(text: string, count: number, env: NodeJS.ProcessEnv): string[] {
+  const lines = redact(text, env).split('\n');
+  if (lines.at(-1) === '') lines.pop();
+  return lines.slice(Math.max(0, lines.length - count));
+}
+
+/** The {@link TailSource} `flows status` uses: this step's latest attempt, redacted. */
+export function transcriptTailSource(env: NodeJS.ProcessEnv = process.env): TailSource {
+  return {
+    async read(dataDir: string, runId: string, step: StepView, lines: number): Promise<StepTails> {
+      if (step.type !== 'agent' || step.attempt === 0) return null;
+      const identity = { dataDir, runId, stepId: step.id, attempt: step.attempt };
+      const tail = async (stream: TailStream): Promise<TranscriptTail | null> => {
+        const read = await readTranscriptTail(identity, stream, step.started_at_ms);
+        return read === undefined ? null : { attempt: step.attempt, bytes: read.bytes, lines: lastLines(read.text, lines, env) };
+      };
+      return { stdout: await tail('stdout'), stderr: await tail('stderr') };
+    },
+  };
+}

package/src/worker-cli.ts

@@ -1,7 +1,9 @@
-import { resolve } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
 import { diffWorkspaceFiles, snapshotWorkspaceFiles } from './agent-artifacts.js';
 import { claudeResultOutcome, decodeProviderResult, decodeWrapperResult, requirePricedUsage } from './worker-usage.js';
 import { openSidechannel, type SidechannelContext } from './pty-sidechannel.js';
+import { openTranscriptWriter, transcriptPath, type TranscriptDigest, type TranscriptFile, type TranscriptWriter } from './agent-transcript.js';
 import { spawn } from 'node:child_process';
 import { StringDecoder } from 'node:string_decoder';
 import { childStop } from './child-stop.js';
@@ -19,6 +21,9 @@ import {
   type WrapperSessionLimits,
 } from './wrapper-session.js';
 import { wrapperEnvironment } from './wrapper-runtime.js';
+import { redactRelayError } from './redact.js';
+import { applyStepEnvironment } from './step-env.js';
+import { TAIL_CLOSE_TIMEOUT_MS, openTranscriptTail, type TranscriptTailWriter } from './transcript-tail.js';
 import {
   runAgentRelayTask,
   AgentRelayTransportError,
@@ -52,6 +57,15 @@ export interface WorkerCliResult {
    * agent runs on another host.
    */
   artifacts?: string[];
+  /**
+   * The attempt's transcript digest (`agent-transcript.ts`): provider result
+   * metadata, tool calls summarized, final text, failure excerpt, and — when
+   * the spawn had a sidechannel context with an attempt — the pointer to the
+   * redacted, capped `stream-json` file. Journaled in `trajectory_tail`, never
+   * in `output`. Present for Claude/Codex executions; absent for wrappers and
+   * the relay transport, which stream no provider frames through this process.
+   */
+  transcript?: TranscriptDigest;
 }
 
 /**
@@ -95,23 +109,39 @@ export async function runAgentCli(
   // workspace to change. Executions sharing a working directory are
   // serialized around their snapshot-spawn-snapshot interval, so one agent's
   // writes are never attributed to a concurrent one in the same directory.
+  //
+  // Bookkeeping written during that interval is not agent-authored content,
+  // and when the data dir sits under the cwd (a local `--data-dir` inside the
+  // project) all of it lands inside the scanned tree: this process's own
+  // transcript file and two `flows status --tail` tails, and the run journals
+  // the daemon appends to while the agent runs. So the whole data dir is
+  // dropped from the diff. Anything left in reports the kernel's own state
+  // back to the kernel as the step's artifacts, where an `artifact_exists`
+  // gate then reads it.
   const artifactRoot = mode === 'agent' ? resolve(cwd ?? process.cwd()) : undefined;
   return artifactRoot === undefined
     ? execute()
     : serializedByDirectory(artifactRoot, async () => {
       const before = await snapshotWorkspaceFiles(artifactRoot);
       const result = await execute();
-      return { ...result, artifacts: diffWorkspaceFiles(before, await snapshotWorkspaceFiles(artifactRoot)) };
+      const kernelData = sidechannel === undefined ? undefined : realPath(resolve(sidechannel.dataDir));
+      const artifacts = diffWorkspaceFiles(before, await snapshotWorkspaceFiles(artifactRoot))
+        .filter(path => !under(realPath(resolve(artifactRoot, path)), kernelData));
+      return { ...result, artifacts };
     });
 
   async function execute(): Promise<WorkerCliResult> {
   if (kind === 'relayflows-wrapper-v1') {
+    // The closed allowlist admits no ambient RELAYFLOW_* value; the four
+    // discovery names are set from this dispatch, exactly as for a direct spawn.
+    const wrapperEnv = wrapperEnvironment(process.env);
+    applyStepEnvironment(wrapperEnv, sidechannel);
     return requirePricedUsage(decodeWrapperResult(await runWrapperSession(
       cli,
       instruction,
       wakeContext,
       effectiveModel,
-      wrapperEnvironment(process.env),
+      wrapperEnv,
       wrapperLimits,
       signal,
       cwd,
@@ -121,6 +151,9 @@ export async function runAgentCli(
   const env: NodeJS.ProcessEnv = { ...process.env };
   delete env[WAKE_CONTEXT_ENV];
   delete env[MODEL_ENV];
+  // Where this attempt's journal is, so the agent can run `flows status` on
+  // itself. Only a worker with a data dir knows; an ad-hoc spawn exports nothing.
+  applyStepEnvironment(env, sidechannel);
   const invocation = mode === 'llm' ? llmExecution(kind, instruction, effectiveModel) : agentExecution(kind, instruction, effectiveModel);
 
   if (wakeContext !== undefined) {
@@ -142,10 +175,51 @@ export async function runAgentCli(
   const args = [...invocation.args];
   args.splice(args.length - 1, 0, ...(kind === 'claude' ? ['--output-format', 'stream-json', '--verbose'] : ['--json']));
   const completion = kind === 'claude' ? claudeResultOutcome : undefined;
-  return requirePricedUsage(decodeProviderResult(await spawnInvocation(cli, { ...invocation, args }, env, signal, sidechannel, cwd, completion), kind), effectiveModel);
+  return requirePricedUsage(decodeProviderResult(await spawnInvocation(cli, { ...invocation, args }, env, signal, sidechannel, cwd, completion), kind, env), effectiveModel);
   }
 }
 
+function openTails(context: SidechannelContext): { stdout: TranscriptTailWriter; stderr: TranscriptTailWriter } | undefined {
+  // Same rule as the per-attempt transcript file: no attempt, no tails.
+  const attempt = context.attempt;
+  if (attempt === undefined) return undefined;
+  const identity = { dataDir: context.dataDir, runId: context.runId, stepId: context.stepId, attempt };
+  try {
+    return { stdout: openTranscriptTail(identity, 'stdout'), stderr: openTranscriptTail(identity, 'stderr') };
+  } catch {
+    // An id the path cannot carry; the sidechannel declined it the same way.
+    return undefined;
+  }
+}
+
+/**
+ * Whether `path` is `directory` or anything beneath it, both symlink-free.
+ *
+ * The artifact exclusion is a subtree, not a list of names, because the files
+ * to exclude are not all knowable in advance. The attempt's own transcript and
+ * tails are (they derive from the attempt identity), but the daemon decides on
+ * its own when to write which run journal, and a journal appended to inside
+ * the snapshot interval is indistinguishable in a diff from a file the agent
+ * wrote. Excluding the directory covers both, and covers them without reading
+ * the result: the transcript pointer there is optional — `finish` drops it
+ * when the close outruns `TAIL_CLOSE_TIMEOUT_MS` and `discardTranscript` drops
+ * it on abort, while the file stays on disk — so an exclusion built from it
+ * lost the transcript exactly when the close was slow (flows#495).
+ *
+ * `false` when there is no data dir to exclude, which is exactly when this
+ * process has nowhere to write.
+ */
+function under(path: string | undefined, directory: string | undefined): boolean {
+  if (path === undefined || directory === undefined) return false;
+  return path === directory || path.startsWith(directory.endsWith(sep) ? directory : directory + sep);
+}
+
+/** Symlink-free form of a path, or the path itself when it cannot be resolved. */
+function realPath(path: string | undefined): string | undefined {
+  if (path === undefined) return undefined;
+  try { return realpathSync(path); } catch { return path; }
+}
+
 /** One agent at a time per canonical working directory, for the artifact interval. */
 const directoryQueues = new Map<string, Promise<unknown>>();
 function serializedByDirectory<T>(directory: string, task: () => Promise<T>): Promise<T> {
@@ -191,14 +265,6 @@ async function runViaAgentRelay(
   }
 }
 
-function redactRelayError(message: string): string {
-  for (const key of ['RELAY_AGENT_TOKEN', 'RELAY_API_KEY']) {
-    const secret = process.env[key];
-    if (secret) message = message.replaceAll(secret, '[redacted]');
-  }
-  return message.replace(/\b(?:at|rk|nt|ot|br|arr)_(?:live_)?[A-Za-z0-9_-]+/g, '[redacted]');
-}
-
 /**
  * How long a CLI that has reported its final result may take to exit. Claude
  * Code in print mode waits, after its result, for every background task it
@@ -220,11 +286,27 @@ async function spawnInvocation(
   let writeInput: (bytes: Buffer) => Promise<boolean> = async () => false;
   let canDrive = () => false;
   let driven = false;
+  // The transcript file lives beside the PTY socket and is named by attempt.
+  // Its absence (no data dir, no attempt, unwritable dir) costs the step
+  // nothing: the digest is built from the buffered frames regardless. Opened
+  // BEFORE the sidechannel: once `onReady` has fired, a drive peer's HELLO may
+  // arrive at any time, and nothing may sit between that and the spawn that
+  // arms `canDrive`.
+  const writer: TranscriptWriter | undefined = sidechannel?.attempt === undefined ? undefined
+    : await openTranscriptWriter(transcriptPath(sidechannel, sidechannel.attempt), env);
   const channel = sidechannel === undefined ? undefined : await openSidechannel({
     ...sidechannel,
     onDrive() { driven = true; sidechannel.onDrive(); },
   }, bytes => writeInput(bytes), () => canDrive());
-  if (signal?.aborted) { channel?.close(); signal.throwIfAborted(); }
+  // Tee the transcript into bounded tail files beside the socket. Evidence
+  // for `flows status --tail`, never the record; a failure here is a warning.
+  const tails = sidechannel === undefined ? undefined : openTails(sidechannel);
+  if (signal?.aborted) {
+    channel?.close();
+    void writer?.close();
+    void tails?.stdout.close(); void tails?.stderr.close();
+    signal.throwIfAborted();
+  }
   return new Promise((resolve) => {
     // Always a group of its own off Windows, so every stop — and
     // `reapOnExit` — reaches the whole agent tree, lease-bound or not.
@@ -257,7 +339,7 @@ async function spawnInvocation(
     let graceTimer: NodeJS.Timeout | undefined;
     const decoder = new StringDecoder('utf8');
     let partialLine = '';
-    const finish = (result: WorkerCliResult): void => {
+    const finish = (result: WorkerCliResult, discardTranscript = false): void => {
       if (settled) return;
       settled = true;
       if (inputTimer !== undefined) clearTimeout(inputTimer);
@@ -265,11 +347,42 @@ async function spawnInvocation(
       if (timer !== undefined) clearTimeout(timer);
       if (graceTimer !== undefined) clearTimeout(graceTimer);
       signal?.removeEventListener('abort', onAbort);
-      resolve(result);
+      if (writer === undefined && tails === undefined) { resolve(result); return; }
+      if (writer !== undefined) {
+        const rest = partialLine + decoder.end();
+        if (rest.length > 0) writer.write(rest);
+      }
+      // Two independent pieces of evidence close here: the per-attempt
+      // transcript, whose descriptor rides back on the result as the digest's
+      // file pointer, and the `flows status --tail` tails, which nothing reads
+      // from the result.
+      //
+      // Neither may hold a step open. A stalled write would leave
+      // `runAgentCli` unresolved forever, and every later abort or timeout is
+      // already a no-op once `settled` is true — so the whole close is raced
+      // against a bounded deadline and the result stands either way. Past the
+      // deadline the transcript pointer is dropped rather than waited for: a
+      // completion without a pointer is recoverable, a step that never
+      // completes is not.
+      // The writer's result is recorded the moment it lands, not read out of
+      // the combined race: the two closes are independent, and a stalled tail
+      // must not throw away a transcript that finished and is on disk.
+      let transcriptFile: TranscriptFile | undefined;
+      const closedWriter = writer === undefined
+        ? Promise.resolve()
+        : writer.close().then((file) => { transcriptFile = file; }, () => {});
+      const closedTails = tails === undefined
+        ? Promise.resolve()
+        : Promise.all([tails.stdout.close(), tails.stderr.close()]).then(() => undefined, () => undefined);
+      const deadline = new Promise<void>((done) => setTimeout(done, TAIL_CLOSE_TIMEOUT_MS).unref?.());
+      void Promise.race([Promise.all([closedWriter, closedTails]), deadline]).then(() => {
+        resolve(discardTranscript || transcriptFile === undefined
+          ? result : { ...result, transcript: { file: transcriptFile } });
+      }, () => resolve(result));
     };
     const onAbort = (): void => {
       stop.kill();
-      finish({ exit_code: null, stdout_tail: '', stderr_tail: 'Agent execution aborted: lease ownership lost.' });
+      finish({ exit_code: null, stdout_tail: '', stderr_tail: 'Agent execution aborted: lease ownership lost.' }, true);
     };
     /**
      * Same invariant as `wrapper-session.ts`: `'close'` and `'error'` are
@@ -306,15 +419,23 @@ async function spawnInvocation(
     child.stdout.on('data', (chunk: Buffer) => {
       stdout.push(chunk);
       channel?.publish(chunk);
-      if (completion === undefined || graceTimer !== undefined) return;
+      // The tails take raw bytes, so they are fed before any line splitting
+      // and regardless of what the writer or the detector still wants.
+      tails?.stdout.append(chunk);
+      // Lines are split whenever a writer or a completion detector wants
+      // them; the detector stops looking once a result has been seen, the
+      // writer keeps every line to the end.
+      if (writer === undefined && (completion === undefined || graceTimer !== undefined)) return;
       const lines = (partialLine + decoder.write(chunk)).split('\n');
       partialLine = lines.pop() ?? '';
       for (const line of lines) {
+        writer?.write(line);
+        if (completion === undefined || graceTimer !== undefined) continue;
         const outcome = completion(line);
         if (outcome !== undefined) onResult(outcome);
       }
     });
-    child.stderr.on('data', (chunk: Buffer) => { stderr.push(chunk); channel?.publish(chunk); });
+    child.stderr.on('data', (chunk: Buffer) => { stderr.push(chunk); channel?.publish(chunk); tails?.stderr.append(chunk); });
     child.once('error', (error) => finishOnChildExit({
       exit_code: null,
       stdout_tail: Buffer.concat(stdout).toString('utf8'),

package/src/worker-usage.ts

@@ -1,12 +1,21 @@
 import type { WorkerCliResult } from './worker-cli.js';
 import { MODEL_PRICING } from './model-pricing.js';
+import { FAILURE_EXCERPT_MAX_BYTES, buildTranscriptDigest, redactText, utf8Tail } from './agent-transcript.js';
 
 type RecordValue = Record<string, unknown>;
 const record = (value: unknown): value is RecordValue => typeof value === 'object' && value !== null && !Array.isArray(value);
 const count = (value: unknown): value is number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
 
+/**
+ * A completion this decoder refuses. The refusal is appended to stderr, and a
+ * digest already built from the frames gets it as its failure — otherwise the
+ * digest would still describe the attempt as the provider reported it.
+ */
 function invalid(result: WorkerCliResult, detail: string): WorkerCliResult {
-  return { ...result, exit_code: null, stderr_tail: `${result.stderr_tail}\n${detail}`.trim() };
+  const stderr_tail = `${result.stderr_tail}\n${detail}`.trim();
+  const transcript = result.transcript === undefined ? undefined : { ...result.transcript,
+    failure: { kind: 'stderr' as const, excerpt: utf8Tail(redactText(stderr_tail), FAILURE_EXCERPT_MAX_BYTES) } };
+  return { ...result, exit_code: null, stderr_tail, ...(transcript === undefined ? {} : { transcript }) };
 }
 
 function usageResult(result: WorkerCliResult, usage: unknown, output: unknown): WorkerCliResult {
@@ -18,12 +27,26 @@ function usageResult(result: WorkerCliResult, usage: unknown, output: unknown):
     tokens_input: usage.input_tokens, tokens_output: usage.output_tokens };
 }
 
-/** Provider envelopes are execution metadata, never the authored output. */
-export function decodeProviderResult(result: WorkerCliResult, kind: 'claude' | 'codex'): WorkerCliResult {
+/**
+ * Provider envelopes are execution metadata, never the authored output. The
+ * same frames also yield the transcript digest (`agent-transcript.ts`): the
+ * metered `tokens_input/output` stay the budget source, and the provider's own
+ * cost, model, tool calls and failure ride beside them in `transcript`.
+ */
+export function decodeProviderResult(
+  result: WorkerCliResult,
+  kind: 'claude' | 'codex',
+  env: NodeJS.ProcessEnv = process.env,
+): WorkerCliResult {
   const frames: RecordValue[] = [];
   for (const line of result.stdout_tail.split('\n')) {
     try { const frame: unknown = JSON.parse(line); if (record(frame)) frames.push(frame); } catch { /* Plain text remains output. */ }
   }
+  const decoded = decodeUsage(result, frames, kind);
+  return { ...decoded, transcript: { ...result.transcript, ...buildTranscriptDigest(frames, kind, decoded, env) } };
+}
+
+function decodeUsage(result: WorkerCliResult, frames: RecordValue[], kind: 'claude' | 'codex'): WorkerCliResult {
   const terminal = [...frames].reverse().find(f => kind === 'claude' ? f.type === 'result' : f.type === 'turn.completed');
   if (terminal === undefined) return result;
   const text = kind === 'claude' ? terminal.result : frames

package/src/worker.ts

@@ -1,3 +1,4 @@
+import { communicationInstruction } from './communication/spec.js';
 import { workerSpend } from './worker-spend.js';
 import type { WorkerCliResult } from './worker-cli.js';
 import { EventEmitter } from 'node:events';
@@ -10,6 +11,7 @@ import { withWorkerLease } from './worker-lease.js';
 import { workerInstruction } from './worker-input.js';
 import { helperCall } from './yaml-helpers.js';
 import { completeHelperDispatch } from './yaml-helper-effect.js';
+import { ARTIFACT_PATHS_MAX, boundTranscriptDigest, type TranscriptDigest } from './agent-transcript.js';
 
 export { MODEL_ENV, WAKE_CONTEXT_ENV } from './worker-cli.js';
 
@@ -17,6 +19,7 @@ export interface AgentWorkerOptions {
   workerId: string;
   pins: Pins;
   capacity?: number;
+  requiredStreams?: string[];
   dataDir?: string;
   onPtyReady?: (path: string) => void;
 }
@@ -59,6 +62,7 @@ export class AgentWorker extends EventEmitter {
         ['agent'],
         this.options.pins,
         this.options.capacity,
+        this.options.requiredStreams,
       );
       this.attached = true;
     } catch (error) {
@@ -105,12 +109,19 @@ export class AgentWorker extends EventEmitter {
       await completeHelperDispatch(this.client, dispatch, helper, this.options.dataDir);
       return;
     }
+    const communication = communicationInstruction(spec.instruction);
+    if (communication) {
+      if (!this.options.dataDir) throw new Error('Agent communication requires a worker data directory');
+      const { completeCommunicationDispatch } = await import('./communication/worker.js');
+      await completeCommunicationDispatch(this.client, dispatch, communication, this.options.dataDir);
+      return;
+    }
     let humanIntervention = false;
     const effectiveModel = typeof spec.cli === 'string' ? resolveCliModel(spec.cli, spec.model) : spec.model;
     const completed: WorkerCliResult = await withWorkerLease(this.client, dispatch, signal =>
       typeof spec.cli === 'string' && typeof spec.instruction === 'string'
         ? runAgentCli(spec.cli, workerInstruction(spec.instruction, dispatch), dispatch.wake_context, effectiveModel, undefined, signal, 'agent', this.options.dataDir === undefined ? undefined : {
-          dataDir: this.options.dataDir, runId: dispatch.run_id, stepId: dispatch.step_id,
+          dataDir: this.options.dataDir, runId: dispatch.run_id, stepId: dispatch.step_id, attempt: dispatch.attempt,
           onReady: this.options.onPtyReady, onDrive: () => { humanIntervention = true; },
         }, typeof spec.cwd === 'string' ? spec.cwd : undefined,
           spec.transport === 'relay' ? 'relay' : 'direct',
@@ -142,8 +153,20 @@ export class AgentWorker extends EventEmitter {
     // or `summary` never asked for. An agent that answers with a JSON object
     // therefore journals no artifacts; gate such a step on a deterministic
     // check instead. The relay transport reports none (the agent ran elsewhere).
+    //
+    // `transcript` is not part of the wrapper either: it is evidence about the
+    // attempt, journaled in `trajectory_tail` below on success and failure
+    // alike, where the kernel already accepts and bounds it (16 KiB).
+    const { transcript, ...wrapper } = result;
     const output = result.relay_task?.status === 'completed' && result.exit_code === 0
-      ? result.relay_task.output : parseJsonOutput(result.stdout_tail) ?? result;
+      ? result.relay_task.output : parseJsonOutput(result.stdout_tail) ?? wrapper;
+    const trajectoryTail = {
+      ...(result.relay_task === undefined ? {} : { relay_task: {
+        invocation_id: result.relay_task.invocation_id, status: result.relay_task.status,
+        task_execution: result.relay_task.task_execution, error: result.relay_task.error,
+      } }),
+      ...(transcript === undefined ? {} : { transcript: transcriptDigest(transcript, dispatch.attempt, result) }),
+    };
 
     await this.client.stepComplete(
       dispatch.run_id,
@@ -153,10 +176,7 @@ export class AgentWorker extends EventEmitter {
       completionReason,
       {
         output,
-        ...(result.relay_task === undefined ? {} : { trajectory_tail: { relay_task: {
-          invocation_id: result.relay_task.invocation_id, status: result.relay_task.status,
-          task_execution: result.relay_task.task_execution, error: result.relay_task.error,
-        } } }),
+        ...(Object.keys(trajectoryTail).length === 0 ? {} : { trajectory_tail: trajectoryTail }),
         ...(humanIntervention ? { human_intervention: true } : {}),
         ...(usage !== undefined ? { usage } : {}),
         started_pins: dispatch.pins,
@@ -166,6 +186,22 @@ export class AgentWorker extends EventEmitter {
   }
 }
 
+/**
+ * The digest as journaled: the attempt and exit code (dropped from `output` on
+ * the JSON path by design) and the artifact paths folded in, then bounded to
+ * `TRANSCRIPT_DIGEST_MAX_BYTES` with every cut stated on the digest itself.
+ */
+function transcriptDigest(transcript: TranscriptDigest, attempt: number, result: WorkerCliResult): TranscriptDigest {
+  return boundTranscriptDigest({
+    attempt,
+    exit_code: result.exit_code,
+    ...transcript,
+    ...(result.artifacts === undefined ? {} : { artifacts: {
+      count: result.artifacts.length, paths: result.artifacts.slice(0, ARTIFACT_PATHS_MAX),
+    } }),
+  });
+}
+
 /**
  * Return an object-shaped JSON payload parsed from `stdout`, or
  * `null` when stdout is empty, non-JSON, or JSON-of-a-scalar/array.

package/src/wrapper-runtime.ts

@@ -25,7 +25,13 @@ export interface WrapperIdentity {
   fingerprint: string;
 }
 
-/** Build a wrapper environment from a closed list; ambient credentials never cross. */
+/**
+ * Build a wrapper environment from a closed list; ambient credentials never
+ * cross. The step discovery names (`RELAYFLOW_DATA_DIR`, `RELAYFLOW_RUN_ID`,
+ * `RELAYFLOW_STEP_ID`, `RELAYFLOW_ATTEMPT`) are deliberately not on the list:
+ * an ambient value is a parent step's identity, not this one's, so the worker
+ * sets them from the dispatch after this filter (step-env.ts).
+ */
 export function wrapperEnvironment(source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = {};
   for (const name of WRAPPER_ENV_ALLOWLIST) {