@relayflows/sdk 2.0.21 → 2.0.23

package/src/cli/step-failure.ts

@@ -34,18 +34,33 @@ export async function stepFailureDetails(
   const snapshot = await client.runGet(runId);
   let fromSeq = 1;
   const failures = new Map<string, StepFailedDetails>();
+  // `runGet`'s `StepSnapshot` carries only `type`, `state` and an optional
+  // lease deadline — neither the attempt number nor the attempt budget. Both
+  // are journal facts: the envelope's `attempt` counts the attempt, and
+  // `step.attempt.started` records the `max_iterations` the kernel is
+  // enforcing (relayflowd-core/src/entry.rs `AttemptStartedPayload`). They are
+  // collected on the same walk and reported only when the journal held them.
+  const budgets = new Map<string, number>();
   while (true) {
     const { entries } = await client.journalRead(runId, fromSeq, 100);
     if (entries.length === 0) break;
     for (const raw of entries) {
       const entry = record(raw);
       const seq = entry?.['seq'];
-      if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < fromSeq) {
+      if (entry === undefined || typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < fromSeq) {
         throw new Error('invalid journal sequence in step failure inspection');
       }
       fromSeq = seq + 1;
-      const stepId = entry?.['step_id'];
-      if (entry?.['entry_type'] !== 'step.completed' || typeof stepId !== 'string') continue;
+      const stepId = entry['step_id'];
+      if (typeof stepId !== 'string') continue;
+      if (entry['entry_type'] === 'step.attempt.started') {
+        const maxIterations = record(entry['payload'])?.['max_iterations'];
+        if (typeof maxIterations === 'number' && Number.isSafeInteger(maxIterations) && maxIterations > 0) {
+          budgets.set(stepId, maxIterations);
+        }
+        continue;
+      }
+      if (entry['entry_type'] !== 'step.completed') continue;
       // A later completion supersedes an earlier failed attempt.
       failures.delete(stepId);
       const payload = record(entry['payload']);
@@ -59,10 +74,14 @@ export async function stepFailureDetails(
       if (payload['disposition'] !== 'step_done'
         || typeof completionReason !== 'string' || completionReason === 'success') continue;
       const stepType = snapshot.steps[stepId]?.type;
+      const attempt = entry['attempt'];
+      const maxIterations = budgets.get(stepId);
       failures.set(stepId, {
         stepId,
         completionReason,
         ...(stepType === undefined ? {} : { stepType }),
+        ...(typeof attempt === 'number' && Number.isSafeInteger(attempt) && attempt > 0 ? { attempt } : {}),
+        ...(maxIterations === undefined ? {} : { maxIterations }),
         ...evidence(payload),
       });
     }
@@ -70,6 +89,52 @@ export async function stepFailureDetails(
   return [...failures.values()].at(-1);
 }
 
+/**
+ * The evidence half of a `step_failed` diagnostic; `renderInspection` adds the
+ * rest. Each field is printed only when the journal actually carried it — an
+ * agent step has no exit code to report, and inventing `exit=undefined` (which
+ * is what the deterministic-only version printed for one) is worse than
+ * silence on that field.
+ *
+ * `attempt=N/M` is here for `retries_exhausted`, which is the kernel's terminal
+ * reason for "the attempt budget was consumed" (kernel/DESIGN.md) and is
+ * accurate kernel vocabulary that reads in English as though retries happened.
+ * A deterministic step gets the default budget of one, so a single failed
+ * attempt with no retry at all terminates as `retries_exhausted`. The
+ * vocabulary does not change (AGENTS.md rule 7); printing the facts beside it
+ * stops it being misread. Unknown values are omitted rather than defaulted —
+ * an absent budget must not be reported as one attempt.
+ *
+ * Lives next to `StepFailedDetails`'s extractor rather than in `cli/run.ts` so
+ * the authored `f.run` path can render the same grammar without importing the
+ * run lifecycle (which would be a cycle).
+ */
+export function renderStepEvidence(details: StepFailedDetails): string {
+  return ` Step ${JSON.stringify(details.stepId)}`
+    + (details.stepType === undefined ? '' : ` (${details.stepType})`)
+    + ` completionReason: ${details.completionReason}`
+    + renderAttempt(details)
+    + (details.exitCode === undefined ? '' : ` exit=${details.exitCode}`)
+    + '.'
+    + (details.detail === undefined ? '' : `\nDetail: ${details.detail}`)
+    + (details.stdoutTail ? `\nStdout (last 1,024 bytes):\n${details.stdoutTail}` : '')
+    + (details.stderrTail ? `\nStderr (last 1,024 bytes):\n${details.stderrTail}` : '')
+    + (details.transcriptPath === undefined ? '' : `\nTranscript: ${details.transcriptPath}`);
+}
+
+function renderAttempt(details: StepFailedDetails): string {
+  if (details.attempt === undefined) return '';
+  return ` attempt=${details.attempt}`
+    + (details.maxIterations === undefined ? '' : `/${details.maxIterations}`);
+}
+
+/** The `Inspect:`/`Journal:` tail every `step_failed` message ends with. */
+export function renderInspection(where: { hint?: string; journalPath?: string }): string {
+  if (where.hint === undefined) return '';
+  return `\nInspect: ${where.hint}`
+    + (where.journalPath === undefined ? '' : `\nJournal: ${where.journalPath}`);
+}
+
 /**
  * Where to look, derived from the run id and data dir ALONE.
  *
@@ -108,28 +173,53 @@ export function inspectionHint(
  * it does not. A truncated render (the daemon caps at 2,000 chars and appends
  * a truncation note) will not parse; that falls through to the raw string,
  * which is still the account of what went wrong.
+ *
+ * An agent or llm completion now also carries `trajectory_tail.transcript`
+ * (agent-transcript.ts) on every attempt. That object is not process-shaped,
+ * so it must not shadow the render that is: the first candidate that carries
+ * an exit code or a tail wins. The digest contributes what only it has — the
+ * failure excerpt the worker picked out of the provider's frames, and the
+ * path of the transcript file.
  */
 function evidence(payload: Record<string, unknown>): Partial<StepFailedDetails> {
   const detail = record(payload['verification'])?.['detail'];
-  const structured = record(payload['output'])
-    ?? record(payload['trajectory_tail'])
-    ?? (typeof detail === 'string' ? parsed(detail) : undefined);
+  const candidates = [
+    record(payload['output']),
+    record(payload['trajectory_tail']),
+    typeof detail === 'string' ? parsed(detail) : undefined,
+  ].filter((candidate): candidate is Record<string, unknown> => candidate !== undefined);
+  const structured = candidates.find(processShaped) ?? candidates[0];
   const exitCode = structured?.['exit_code'];
   const stdout = structured?.['stdout_tail'];
   const stderr = structured?.['stderr_tail'];
-  const structuredShape = typeof exitCode === 'number'
-    || typeof stdout === 'string' || typeof stderr === 'string';
+  const structuredShape = structured !== undefined && processShaped(structured);
+  const transcript = record(record(payload['trajectory_tail'])?.['transcript']);
+  const failure = record(transcript?.['failure']);
+  const excerpt = failure?.['excerpt'];
+  const transcriptPath = record(transcript?.['file'])?.['path'];
+  // The excerpt is the worker's own pick of the failure; a `stderr` excerpt
+  // is the same bytes as `stderrTail`, so it is not printed twice.
+  const excerptDetail = typeof excerpt === 'string' && excerpt.length > 0
+    && !(failure?.['kind'] === 'stderr' && typeof stderr === 'string')
+    ? tail(excerpt) : undefined;
   return {
     ...(typeof exitCode === 'number' && Number.isSafeInteger(exitCode) ? { exitCode } : {}),
     ...(typeof stdout === 'string' && stdout.length > 0 ? { stdoutTail: tail(stdout) } : {}),
     ...(typeof stderr === 'string' ? { stderrTail: tail(stderr) } : {}),
     // Keep the daemon's account only when it was NOT just a render of the
     // fields above — otherwise the same bytes print twice.
-    ...(typeof detail === 'string' && detail.length > 0 && !structuredShape
-      ? { detail: tail(detail) } : {}),
+    ...(excerptDetail !== undefined ? { detail: excerptDetail }
+      : typeof detail === 'string' && detail.length > 0 && !structuredShape
+        ? { detail: tail(detail) } : {}),
+    ...(typeof transcriptPath === 'string' && transcriptPath.length > 0 ? { transcriptPath } : {}),
   };
 }
 
+function processShaped(value: Record<string, unknown>): boolean {
+  return typeof value['exit_code'] === 'number'
+    || typeof value['stdout_tail'] === 'string' || typeof value['stderr_tail'] === 'string';
+}
+
 function parsed(value: string): Record<string, unknown> | undefined {
   try {
     return record(JSON.parse(value));

package/src/cli-commands.ts

@@ -1,4 +1,5 @@
 import { DEFAULT_DATA_DIR } from './daemon-connection.js';
+import { DEFAULT_RUN_LIMIT } from './cli/cloud-read.js';
 import type { ParsedArgs } from './cli.js';
 
 /**
@@ -181,6 +182,17 @@ export const CLI_VERBS = [
     ],
     variants: ['hn-monitor'],
   },
+  {
+    name: 'logs',
+    description: 'Read a hosted run’s runner log, or one agent step’s transcript, from Cloud',
+    args: [{ name: 'run-id', description: 'Hosted run id, as `flows runs` lists it', required: true }],
+    options: [
+      { flags: '--step <name>', description: 'Show that agent step’s transcript instead of the runner log' },
+      { flags: '--raw', description: 'Print the transcript JSONL unrendered (still redacted)' },
+      JSON_OPTION,
+    ],
+    variants: ['logs'],
+  },
   {
     name: 'observer',
     description: 'Mint a read-only observer link without running a flow',
@@ -231,6 +243,15 @@ export const CLI_VERBS = [
     ],
     variants: ['run', 'cloud-run'],
   },
+  {
+    name: 'runs',
+    description: 'List the hosted runs this Cloud credential can read, newest first',
+    options: [
+      { flags: '--limit <n>', description: 'How many runs to show', defaultValue: DEFAULT_RUN_LIMIT },
+      JSON_OPTION,
+    ],
+    variants: ['runs'],
+  },
   {
     name: 'schedule',
     description: 'Register a flow to run in Cloud on a cron or interval, or on the one it declares',
@@ -265,6 +286,18 @@ export const CLI_VERBS = [
     ],
     variants: ['serve-webhook'],
   },
+  {
+    name: 'status',
+    description: 'Show a run’s steps, attempts, leases and last verdicts from its journal, or from Cloud with --cloud',
+    args: [{ name: 'run-id', description: 'Run to inspect; defaults to RELAYFLOW_RUN_ID inside a step', required: false }],
+    options: [
+      JSON_OPTION,
+      DATA_DIR_OPTION,
+      { flags: '--tail <n>', description: 'Lines of each agent attempt’s transcript tail to show' },
+      { flags: '--cloud', description: 'Read the run from Cloud instead of a local journal; needs the run id' },
+    ],
+    variants: ['status'],
+  },
   {
     name: 'sync',
     description: 'Apply a hosted run’s code changes to a local tree (replaces `agent-relay cloud sync`)',

package/src/cli.ts

@@ -24,6 +24,12 @@ import { checkAuthoredTriggers } from './cli/check-triggers.js';
 import { parseWebhookArgs, runServeWebhook } from './cli/serve-webhook.js';
 import { runDirectFlow } from './cli/direct-run.js';
 import { parseReplayArgs, replayJournal, type ReplayArgs } from './cli/replay.js';
+import { parseStatusArgs, runStatus, type StatusArgs } from './cli/status.js';
+import {
+  parseLogsArgs, parseRunsArgs, runCloudLogsCli, runCloudRunsCli, runCloudStatusCli,
+  type LogsArgs, type RunsArgs,
+} from './cli/cloud-read.js';
+import { transcriptTailSource } from './transcript-tail.js';
 import { checkTypeScriptFlow } from './cli/check-typescript.js';
 import { runCloudCli } from './cli/cloud-run.js';
 import { runCloudSyncCli } from './cli/cloud-sync.js';
@@ -59,6 +65,7 @@ type CliExitCode = 0 | 1 | 2 | 3;
 export type ParsedArgs =
   | { command: 'add'; value: string }
   | ReplayArgs
+  | StatusArgs
   | BuildArgs
   | DeployArgs
   | { command: 'serve-webhook'; dataDir: string; port: number; admitted?: readonly string[] }
@@ -74,6 +81,8 @@ export type ParsedArgs =
   | { command: 'run'; bucket: string | undefined; reuseFromRunId: string | undefined; localAgent: boolean; dataDir: string; input: string | undefined; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
   | { command: 'resume'; localAgent: boolean; dataDir: string; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
   | { command: 'answer'; dataDir: string; json: boolean; spawn: boolean; note: string | undefined; by: string | undefined; runId: string; waitId: string; answer: boolean }
+  | RunsArgs
+  | LogsArgs
   | { command: 'observer'; dataDir: string }
   | { command: 'hn-monitor'; sub: 'start'; dataDir: string; specPath: string; pollIntervalMs: number | undefined }
   | { command: 'tick'; sub: 'start'; dataDir: string; specPath: string; scheduleId: string;
@@ -104,6 +113,10 @@ const USAGE = [
   'flows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <run-id>',
   'flows answer [--json] [--no-spawn] [--data-dir <dir>] [--note <text>] [--by <identity>] <run-id> <wait-id> <yes|no>',
   'flows replay [--allow-human-influenced] [--json] [--data-dir <dir>] <run-id> [--at <step-id>]',
+  'flows status [--json] [--data-dir <dir>] [--tail <n>] [<run-id>]',
+  'flows status --cloud [--json] <run-id>',
+  'flows runs [--limit <n>] [--json]',
+  'flows logs [--step <name>] [--raw] [--json] <run-id>',
   'flows observer [--data-dir <dir>]',
   'flows hn-monitor start [--data-dir <dir>] [--poll-interval-ms <n>] <spec.json>',
 ].join('\n');
@@ -195,6 +208,17 @@ export async function runCli(
   if (parsed.command === 'schedules') return runCloudSchedulesCli(parsed, io);
   if (parsed.command === 'unschedule') return runCloudUnscheduleCli(parsed, io);
   if (parsed.command === 'replay') return replayJournal(parsed, io);
+  // Daemon-free like `check`: reads one journal file and nothing else, so it
+  // works inside a step of a run whose daemon is gone (kernel/DAEMON-LIFECYCLE.md §4).
+  if (parsed.command === 'status') {
+    // One verb, two sources. `--cloud` never reaches `runStatus`, so the
+    // offline reader stays offline (cli/status.ts).
+    return parsed.cloud === true
+      ? runCloudStatusCli(parsed, io)
+      : runStatus(parsed, io, { tails: transcriptTailSource() });
+  }
+  if (parsed.command === 'runs') return runCloudRunsCli(parsed, io);
+  if (parsed.command === 'logs') return runCloudLogsCli(parsed, io);
   if (parsed.command === 'answer') {
     const execution = await answerFlow(parsed.runId, parsed.waitId, parsed.answer, parsed.dataDir, {
       ...(parsed.note === undefined ? {} : { note: parsed.note }),
@@ -498,6 +522,9 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   if (command === undefined || !CLI_VERB_NAMES.has(command)) return undefined;
   if (command === 'add') return args.length === 2 ? { command: 'add', value: args[1]! } : undefined;
   if (command === 'replay') return parseReplayArgs(args.slice(1));
+  if (command === 'status') return parseStatusArgs(args.slice(1));
+  if (command === 'runs') return parseRunsArgs(args.slice(1));
+  if (command === 'logs') return parseLogsArgs(args.slice(1));
   if (command === 'build') return parseBuildArgs(args.slice(1));
   if (command === 'deploy') {
     // The positional decides the form: an authored source deploys a hosted

package/src/cloud-http.ts

@@ -21,7 +21,26 @@ export interface CloudRefusal {
   received?: { packageName?: string; version?: string };
 }
 
+/**
+ * Narrows a `configuration` failure to the thing that was wrong.
+ *
+ * `configuration` has always covered every local misconfiguration, and its
+ * message says which. A caller that must answer with a *code* — the read
+ * verbs print `REFUSED [cloud_auth_missing]` and name `agent-relay cloud
+ * login` — cannot get that from prose without matching on it. Optional and
+ * additive: every existing `catch` on `code === 'configuration'` is unchanged.
+ */
+export type CloudConfigurationReason =
+  | 'auth_missing'
+  | 'auth_expired'
+  | 'url_invalid'
+  | 'url_mismatch'
+  | 'timeout_invalid';
+
 export class CloudFlowError extends Error {
+  /** Set only for `configuration`; see {@link CloudConfigurationReason}. */
+  reason?: CloudConfigurationReason;
+
   constructor(
     readonly code: 'configuration' | 'unsupported_source' | 'invalid_input' | 'invalid_response' | 'http_error'
       | 'transport_error' | 'transient_error' | 'unsupported_storage_backend' | 'sync_too_large' | 'sync_unsupported'
@@ -35,6 +54,13 @@ export class CloudFlowError extends Error {
   }
 }
 
+/** A `configuration` refusal that also carries its {@link CloudConfigurationReason}. */
+function configurationError(reason: CloudConfigurationReason, message: string): CloudFlowError {
+  const error = new CloudFlowError('configuration', message);
+  error.reason = reason;
+  return error;
+}
+
 /**
  * The `agent-relay cloud login` credential store. Read only when neither the
  * `token` option nor `FLOWS_CLOUD_TOKEN` is set, so an explicit credential
@@ -79,7 +105,7 @@ export function cloudConnection(options: CloudConnectionOptions): { baseUrl: str
     if (login !== undefined) {
       const expiresAt = login.accessTokenExpiresAt === undefined ? Number.NaN : Date.parse(login.accessTokenExpiresAt);
       if (Number.isFinite(expiresAt) && expiresAt <= Date.now()) {
-        throw new CloudFlowError('configuration',
+        throw configurationError('auth_expired',
           'The agent-relay cloud login has expired. Run `agent-relay cloud login` again, or set FLOWS_CLOUD_TOKEN.');
       }
       rawToken = login.accessToken;
@@ -88,7 +114,7 @@ export function cloudConnection(options: CloudConnectionOptions): { baseUrl: str
   }
   const token = rawToken?.trim();
   if (!token || /[\r\n]/u.test(rawToken!) || /^(?:rk|ot)_live_/u.test(token)) {
-    throw new CloudFlowError('configuration',
+    throw configurationError('auth_missing',
       'Set FLOWS_CLOUD_TOKEN to a scoped Cloud API token (workflow:invoke:write and workflow:runs:read), '
       + 'or sign in with `agent-relay cloud login`.');
   }
@@ -96,11 +122,11 @@ export function cloudConnection(options: CloudConnectionOptions): { baseUrl: str
   try {
     url = new URL(options.apiUrl ?? process.env['FLOWS_CLOUD_URL'] ?? loginApiUrl ?? 'https://agentrelay.com/cloud');
   } catch {
-    throw new CloudFlowError('configuration', 'FLOWS_CLOUD_URL must be an absolute Cloud application base URL.');
+    throw configurationError('url_invalid', 'FLOWS_CLOUD_URL must be an absolute Cloud application base URL.');
   }
   if (url.protocol !== 'https:'
     || url.username || url.password || url.search || url.hash || !/^\/[A-Za-z0-9/_-]*$/u.test(url.pathname)) {
-    throw new CloudFlowError('configuration', 'Cloud URL must use HTTPS and a plain base path.');
+    throw configurationError('url_invalid', 'Cloud URL must use HTTPS and a plain base path.');
   }
   const baseUrl = `${url.origin}${url.pathname.replace(/\/+$/u, '')}`;
   // A login-store token is bound to the deployment that issued it. An explicit
@@ -113,7 +139,7 @@ export function cloudConnection(options: CloudConnectionOptions): { baseUrl: str
       issued = `${login.origin}${login.pathname.replace(/\/+$/u, '')}`;
     } catch { issued = undefined; }
     if (issued !== baseUrl) {
-      throw new CloudFlowError('configuration',
+      throw configurationError('url_mismatch',
         `The agent-relay cloud login was issued for ${loginApiUrl}, not ${baseUrl}. `
         + 'Set FLOWS_CLOUD_TOKEN for that deployment, or unset FLOWS_CLOUD_URL to use the login.');
     }
@@ -159,7 +185,7 @@ export async function cloudFetch(
   const { baseUrl, token } = cloudConnection(options);
   const timeout = options.requestTimeoutMs ?? 30_000;
   if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 2_147_483_647) {
-    throw new CloudFlowError('configuration', 'requestTimeoutMs must be a positive 32-bit integer.');
+    throw configurationError('timeout_invalid', 'requestTimeoutMs must be a positive 32-bit integer.');
   }
   const bearer = init.bearerToken ?? token;
   if (/[\r\n]/u.test(bearer) || !bearer.trim()) {