@relayflows/sdk 2.0.20 → 2.0.22

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
@@ -31,6 +54,19 @@ export function decodeProviderResult(result: WorkerCliResult, kind: 'claude' | '
   return usageResult(result, terminal.usage, text);
 }
 
+/**
+ * Claude's terminal `stream-json` frame, recognised line by line as it
+ * streams. `failed` mirrors the exit status Claude gives that result: an
+ * error flag or a non-success subtype is a failed run.
+ */
+export function claudeResultOutcome(line: string): { failed: boolean } | undefined {
+  if (!line.includes('"result"')) return undefined;
+  let frame: unknown;
+  try { frame = JSON.parse(line); } catch { return undefined; }
+  if (!record(frame) || frame.type !== 'result') return undefined;
+  return { failed: frame.is_error === true || (typeof frame.subtype === 'string' && frame.subtype !== 'success') };
+}
+
 /** Optional wrapper result envelope; existing opaque text output stays valid. */
 export function decodeWrapperResult(result: WorkerCliResult): WorkerCliResult {
   let value: unknown;

package/src/worker.ts

@@ -10,6 +10,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';
 
@@ -110,7 +111,7 @@ export class AgentWorker extends EventEmitter {
     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 +143,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 +166,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 +176,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) {