@relayflows/sdk 2.0.29 → 2.0.31

package/src/cli/cloud-read.ts

@@ -13,14 +13,15 @@
 // facts beneath it) so a reader who knows one knows the other.
 
 import { canonicalize } from '../canonical.js';
-import { CloudFlowError, type CloudConnectionOptions } from '../cloud-http.js';
 import {
   getCloudRunDetail, getCloudRunLog, getCloudRunSteps, listCloudRuns,
   type CloudRunDetail, type CloudStep,
 } from '../cloud-read.js';
 import { parseAgentTranscript, renderAgentTranscript } from '../cloud-transcript.js';
 import { redact } from '../redact.js';
-import { formatDuration } from './status.js';
+import { errorLines, instant, safe, thousands } from './cloud-format.js';
+import { fail, refusalFor, RUN_ID_REQUIRED, type CloudReadOptions } from './cloud-refusal.js';
+import { renderCloudStatus, scrubRun, scrubSteps } from './cloud-status-view.js';
 import type { CliIo } from '../cli.js';
 
 export interface RunsArgs {
@@ -35,17 +36,13 @@ export interface LogsArgs {
   step: string | undefined;
   raw: boolean;
   json: boolean;
+  /** `--follow`: append new runner output until the run is terminal (cli/cloud-live.ts). */
+  follow: boolean;
 }
 
 /** Enough runs to recognise the one you mean; `--limit` raises it. */
 export const DEFAULT_RUN_LIMIT = 20;
 
-/** Injected by tests; production takes the ambient clock and environment. */
-export interface CloudReadOptions extends CloudConnectionOptions {
-  env?: NodeJS.ProcessEnv;
-  now?: () => number;
-}
-
 export function parseRunsArgs(args: readonly string[]): RunsArgs | undefined {
   let limit: number | undefined;
   let json = false;
@@ -69,6 +66,7 @@ export function parseLogsArgs(args: readonly string[]): LogsArgs | undefined {
   let step: string | undefined;
   let raw = false;
   let json = false;
+  let follow = false;
   const positionals: string[] = [];
   for (let index = 0; index < args.length; index += 1) {
     const argument = args[index]!;
@@ -78,6 +76,9 @@ export function parseLogsArgs(args: readonly string[]): LogsArgs | undefined {
     } else if (argument === '--raw') {
       if (raw) return undefined;
       raw = true;
+    } else if (argument === '--follow') {
+      if (follow) return undefined;
+      follow = true;
     } else if (argument === '--step') {
       const value = args[++index];
       if (step !== undefined || value === undefined || value.length === 0 || value.startsWith('-')) return undefined;
@@ -89,147 +90,7 @@ export function parseLogsArgs(args: readonly string[]): LogsArgs | undefined {
     }
   }
   if (positionals.length !== 1) return undefined;
-  return { command: 'logs', runId: positionals[0]!, step, raw, json };
-}
-
-/**
- * Every way these verbs can refuse, as a code and a sentence.
- *
- * Each one names the thing to do next. A missing credential names
- * `agent-relay cloud login` because that is the command that fixes it; a 404
- * names `flows runs` because the usual cause is a run id from another
- * workspace, and the list is how you find yours.
- */
-interface Refusal { code: string; message: string; exit: 1 | 2 }
-
-function refusalFor(error: unknown, subject: string, env: NodeJS.ProcessEnv): Refusal {
-  const clean = (message: string): string => redact(message, env);
-  if (error instanceof CloudFlowError) {
-    if (error.code === 'configuration') {
-      switch (error.reason) {
-        case 'auth_missing':
-          return {
-            code: 'cloud_auth_missing', exit: 2,
-            message: 'No Cloud credential. Sign in with `agent-relay cloud login`, or set FLOWS_CLOUD_TOKEN to a '
-              + 'Cloud API token with workflow:runs:read (and workflow:logs:read for `flows logs`).',
-          };
-        case 'auth_expired':
-          return { code: 'cloud_auth_expired', exit: 2, message: clean(error.message) };
-        case 'url_mismatch':
-          return { code: 'cloud_url_mismatch', exit: 2, message: clean(error.message) };
-        default:
-          return { code: 'cloud_configuration', exit: 2, message: clean(error.message) };
-      }
-    }
-    if (error.code === 'http_error') {
-      if (error.status === 401) {
-        return {
-          code: 'cloud_auth_rejected', exit: 2,
-          message: 'Cloud rejected the credential (HTTP 401). The token is unknown or revoked; '
-            + 'sign in again with `agent-relay cloud login`.',
-        };
-      }
-      if (error.status === 403) {
-        return {
-          code: 'cloud_forbidden', exit: 2,
-          message: `The credential is valid but not allowed to read ${subject} (HTTP 403). `
-            + 'A run-scoped sandbox token may only read its own run; a workspace token needs '
-            + 'workflow:runs:read, and workflow:logs:read or workflow:invoke:read for logs.',
-        };
-      }
-      if (error.status === 404) {
-        return {
-          code: 'cloud_run_not_found', exit: 2,
-          message: `Cloud has no ${subject} visible to this credential (HTTP 404). `
-            + 'It may belong to another workspace; `flows runs` lists the ones this credential can read.',
-        };
-      }
-      return { code: 'cloud_http_error', exit: 1, message: clean(error.message) };
-    }
-    if (error.code === 'invalid_input') return { code: 'invalid_invocation', exit: 2, message: clean(error.message) };
-    if (error.code === 'transient_error' || error.code === 'transport_error') {
-      return { code: error.code === 'transient_error' ? 'cloud_unreachable' : 'cloud_transport_failed', exit: 1, message: clean(error.message) };
-    }
-    return { code: 'cloud_invalid_response', exit: 1, message: clean(error.message) };
-  }
-  return { code: 'cloud_read_failed', exit: 1, message: clean(error instanceof Error ? error.message : String(error)) };
-}
-
-function fail(refusal: Refusal, json: boolean, io: CliIo): 1 | 2 {
-  if (json) io.stdout(canonicalize({ v: 1, ok: false, code: refusal.code, message: refusal.message }));
-  else io.stderr(`REFUSED [${refusal.code}] ${refusal.message}`);
-  return refusal.exit;
-}
-
-function thousands(value: number): string {
-  return String(value).replace(/\B(?=(\d{3})+(?!\d))/gu, ',');
-}
-
-function dollars(value: number): string {
-  return `$${value.toFixed(6).replace(/0+$/u, '').replace(/\.$/u, '')}`;
-}
-
-/** Agent- and flow-authored names cannot inject terminal control sequences. */
-function safe(text: string): string {
-  return text.replace(/[\u0000-\u001F\u007F-\u009F]/gu, '?');
-}
-
-/**
- * Render a run's `error` as readable lines rather than one control-char smear.
- *
- * Cloud stores the runner's terminal output in this field, newlines and all, so
- * passing it through `safe()` alone turns a 200-line tail into a single line of
- * `?` separators. Long runs are dominated by lease renewals — one line every
- * 10s for the life of every agent step, differing only in the deadline — which
- * are worth counting, not reading.
- *
- * Collapsing is deliberately narrow: two adjacent lines merge only when they
- * are character-for-character identical once a trailing integer is masked. A
- * shared prefix is NOT line identity — runner lines put the step name, reason
- * or message after a long fixed prefix, so collapsing on a prefix would hide
- * distinct diagnostics behind a similarity count. The final line never
- * collapses into an earlier one, because that is where the failure is.
- */
-const TRAILING_NUMBER = /\d+(?=\D{0,2}$)/u;
-
-export function errorLines(text: string, indent: string): string[] {
-  const raw = text.split(/\r\n|\r|\n/u).map((line) => line.trimEnd()).filter((line) => line !== '');
-  if (raw.length === 0) return [];
-
-  const key = (line: string): string => line.replace(TRAILING_NUMBER, '#');
-  const collapsed: { line: string; count: number }[] = [];
-  raw.forEach((line, index) => {
-    const previous = collapsed.at(-1);
-    const isLast = index === raw.length - 1;
-    if (previous !== undefined && !isLast && key(previous.line) === key(line)) previous.count += 1;
-    else collapsed.push({ line, count: 1 });
-  });
-
-  const rendered = collapsed.map(({ line, count }) =>
-    count === 1 ? safe(line) : `${safe(line)}  (${count} times, differing only in a number)`);
-
-  const HEAD = 2;
-  const TAIL = 12;
-  if (rendered.length <= HEAD + TAIL + 1) return rendered.map((line) => `${indent}${line}`);
-  const elided = rendered.length - HEAD - TAIL;
-  return [
-    ...rendered.slice(0, HEAD),
-    `… ${elided} more line${elided === 1 ? '' : 's'} (full text: --json)`,
-    ...rendered.slice(-TAIL),
-  ].map((line) => `${indent}${line}`);
-}
-
-/** ISO-8601 to the second: a list column, not a timestamp to do arithmetic on. */
-function instant(value: string | null): string {
-  if (value === null) return 'unknown';
-  const parsed = Date.parse(value);
-  return Number.isFinite(parsed) ? new Date(parsed).toISOString().replace(/\.\d{3}Z$/u, 'Z') : 'unknown';
-}
-
-function ago(value: string | null, now: number): string {
-  if (value === null) return 'unknown';
-  const parsed = Date.parse(value);
-  return Number.isFinite(parsed) ? `${formatDuration(now - parsed)} ago` : 'unknown';
+  return { command: 'logs', runId: positionals[0]!, step, raw, json, follow };
 }
 
 // ---------------------------------------------------------------- flows runs
@@ -361,113 +222,6 @@ export async function runCloudLogsCli(
 
 // -------------------------------------------------------- flows status --cloud
 
-const GLYPH: Record<string, string> = {
-  completed: '✓', succeeded: '✓', failed: '✗', cancelled: '✗', running: '↻', pending: '○', queued: '○',
-};
-
-function glyph(step: CloudStep): string {
-  if (step.status === 'completed' && step.completion_reason !== null && step.completion_reason !== 'success') return '✗';
-  return GLYPH[step.status] ?? '○';
-}
-
-/** The `steps N: 3 done · 1 running` line, counted off whatever Cloud called each status. */
-function stepCounts(steps: readonly CloudStep[]): string {
-  const counts = new Map<string, number>();
-  for (const step of steps) counts.set(step.status, (counts.get(step.status) ?? 0) + 1);
-  const parts = [...counts].map(([status, count]) => `${count} ${status}`);
-  return `steps ${steps.length}${parts.length === 0 ? '' : `: ${parts.join(' · ')}`}`;
-}
-
-function renderStep(step: CloudStep, runId: string, idWidth: number): string[] {
-  const cells = [
-    safe(step.step_name).slice(0, 24).padEnd(idWidth),
-    step.step_type.padEnd(13),
-    step.status.padEnd(11),
-  ];
-  const attempts = step.attempts.length;
-  if (attempts > 0) cells.push(`${attempts} attempt${attempts === 1 ? '' : 's'}`);
-  if (step.duration_ms !== null) cells.push(formatDuration(step.duration_ms));
-  if (step.completion_reason !== null) cells.push(safe(step.completion_reason));
-  if (step.gate !== null) cells.push(`gate: ${safe(step.gate.gate)} ${safe(step.gate.verdict)}`);
-  const lines = [`  ${glyph(step)} ${cells.join('  ')}`.trimEnd()];
-
-  if (step.gate !== null && step.gate.verdict !== 'pass' && step.gate.detail.length > 0) {
-    lines.push(`        gate: ${safe(step.gate.gate)} ${step.gate.verdict.toUpperCase()} — ${JSON.stringify(safe(step.gate.detail))}`);
-  }
-  const transcript = step.transcript;
-  if (transcript !== null) {
-    const facts = [
-      transcript.model === null ? null : safe(transcript.model),
-      transcript.num_turns === null ? null : `${transcript.num_turns} turn${transcript.num_turns === 1 ? '' : 's'}`,
-      transcript.total_calls === null ? null : `${transcript.total_calls} tool call${transcript.total_calls === 1 ? '' : 's'}`,
-      transcript.total_cost_usd === null ? null : dollars(transcript.total_cost_usd),
-    ].filter((fact): fact is string => fact !== null);
-    lines.push(`      transcript (attempt ${transcript.attempt ?? step.attempts.length})${facts.length === 0 ? '' : `: ${facts.join(' · ')}`}`);
-    if (transcript.frames_total !== null || transcript.bytes_total !== null) {
-      const frames = transcript.frames_total === null ? ''
-        : `${thousands(transcript.frames_kept ?? transcript.frames_total)} of ${thousands(transcript.frames_total)} frames`;
-      const bytes = transcript.bytes_total === null ? '' : `${thousands(transcript.bytes_total)} bytes`;
-      const cut = transcript.truncated ? ', truncated' : '';
-      lines.push(`        ${[frames, bytes].filter((part) => part.length > 0).join(', ')}${cut}`);
-    }
-    if (transcript.tokens_in !== null || transcript.tokens_out !== null) {
-      const cache = [
-        transcript.cache_read === null ? null : `${thousands(transcript.cache_read)} cache read`,
-        transcript.cache_creation === null ? null : `${thousands(transcript.cache_creation)} cache write`,
-      ].filter((part): part is string => part !== null);
-      lines.push(`        ${thousands(transcript.tokens_in ?? 0)} in / ${thousands(transcript.tokens_out ?? 0)} out`
-        + `${cache.length === 0 ? '' : ` · ${cache.join(' · ')}`}`);
-    }
-    if (transcript.tools.length > 0) {
-      lines.push(`        tools: ${transcript.tools.map((tool) =>
-        `${safe(tool.name)} ×${tool.calls ?? 0}${tool.errors ? ` (${tool.errors} error${tool.errors === 1 ? '' : 's'})` : ''}`).join(', ')}`);
-    }
-    for (const call of transcript.last_calls) {
-      const excerpt = call.input_excerpt === null ? '' : ` ${safe(call.input_excerpt).slice(0, 120)}`;
-      lines.push(`        call ${call.seq ?? '?'} ${safe(call.name)}${excerpt} → ${thousands(call.result_bytes ?? 0)} bytes`);
-    }
-    lines.push(`        artifacts: ${transcript.artifacts.length === 0
-      ? 'none' : transcript.artifacts.slice(0, 10).map(safe).join(', ')}`);
-  }
-  if (step.sandbox_id.length > 0) lines.push(`      logs: flows logs ${runId} --step ${safe(step.sandbox_id)}`);
-  return lines;
-}
-
-function renderCloudStatus(run: CloudRunDetail, steps: readonly CloudStep[], now: number): string[] {
-  let tokensIn = 0;
-  let tokensOut = 0;
-  let cost = 0;
-  for (const step of steps) {
-    tokensIn += step.tokens_in ?? 0;
-    tokensOut += step.tokens_out ?? 0;
-    cost += step.cost_usd ?? 0;
-  }
-  // Summed from the step rows, because the run record carries no total. Cloud
-  // stores `costUsd` as a float, so this is a float sum — not the exact decimal
-  // addition the local journal fold does (run-state.ts `addDollars`). Shown to
-  // six places and labelled `spend`, the same word the local view uses.
-  const spend = `${thousands(tokensIn)} in / ${thousands(tokensOut)} out / ${dollars(cost)}`;
-  const finished = run.completion_reason === null ? '' : `   finished ${safe(run.completion_reason)}`;
-  const lines = [
-    `RUN ${run.run_id}   ${safe(run.name)}   ${run.status}   started ${ago(run.created_at, now)}${finished}   spend ${spend}`,
-    stepCounts(steps),
-  ];
-  if (run.authority !== null) {
-    const facts = [
-      run.authority.surface_version === null ? null : `surface ${run.authority.surface_version}`,
-      run.authority.artifact_sha256 === null ? null : `artifact ${run.authority.artifact_sha256.slice(0, 12)}`,
-      run.authority.source_commit === null ? null : `commit ${run.authority.source_commit.slice(0, 12)}`,
-    ].filter((fact): fact is string => fact !== null);
-    if (facts.length > 0) lines.push(`authority ${facts.join(' · ')}`);
-  }
-  if (run.pull_request_url !== null) lines.push(`pr ${run.pull_request_url}`);
-  if (run.error !== null) lines.push('error', ...errorLines(run.error, '  '));
-  lines.push('');
-  const idWidth = Math.max(4, ...steps.map((step) => Math.min(24, step.step_name.length)));
-  for (const step of steps) lines.push(...renderStep(step, run.run_id, idWidth));
-  return lines;
-}
-
 export async function runCloudStatusCli(
   args: { runId?: string; json: boolean },
   io: CliIo,
@@ -475,13 +229,7 @@ export async function runCloudStatusCli(
 ): Promise<0 | 1 | 2> {
   const env = options.env ?? process.env;
   const now = (options.now ?? Date.now)();
-  if (args.runId === undefined || args.runId.length === 0) {
-    return fail({
-      code: 'run_unknown', exit: 2,
-      message: '`flows status --cloud` needs the hosted run id; `flows runs` lists them. '
-        + '(Without --cloud the run id defaults to RELAYFLOW_RUN_ID inside a step.)',
-    }, args.json, io);
-  }
+  if (args.runId === undefined || args.runId.length === 0) return fail(RUN_ID_REQUIRED, args.json, io);
   let run: CloudRunDetail;
   let steps: CloudStep[];
   try {
@@ -490,25 +238,8 @@ export async function runCloudStatusCli(
   } catch (error) {
     return fail(refusalFor(error, `run ${args.runId}`, env), args.json, io);
   }
-  const scrubbed: CloudRunDetail = {
-    ...run,
-    name: redact(run.name, env),
-    error: run.error === null ? null : redact(run.error, env),
-  };
-  const scrubbedSteps = steps.map((step) => ({
-    ...step,
-    output_summary: step.output_summary === null ? null : redact(step.output_summary, env),
-    gate: step.gate === null ? null : { ...step.gate, detail: redact(step.gate.detail, env) },
-    transcript: step.transcript === null ? null : {
-      ...step.transcript,
-      model: step.transcript.model === null ? null : redact(step.transcript.model, env),
-      last_calls: step.transcript.last_calls.map((call) => ({
-        ...call,
-        input_excerpt: call.input_excerpt === null ? null : redact(call.input_excerpt, env),
-      })),
-      artifacts: step.transcript.artifacts.map((path) => redact(path, env)),
-    },
-  }));
+  const scrubbed = scrubRun(run, env);
+  const scrubbedSteps = scrubSteps(steps, env);
   if (args.json) {
     io.stdout(canonicalize({ v: 1, ok: true, run: scrubbed, steps: scrubbedSteps, now_ms: now }));
     return 0;

package/src/cli/cloud-refusal.ts

@@ -0,0 +1,113 @@
+// Every way a hosted read can refuse, as a code, a sentence and an exit.
+//
+// Moved out of `cli/cloud-read.ts` when the live views needed to refuse in
+// exactly the same words: `flows status --cloud --watch` that meets a 404 must
+// say what `flows status --cloud` says, or a reader would have to learn two
+// vocabularies for one failure. A dependency-only module — it imports no other
+// Cloud CLI module, so the one-shot and live entry points can both use it with
+// no import cycle between them.
+
+import { canonicalize } from '../canonical.js';
+import { CloudFlowError, type CloudConnectionOptions } from '../cloud-http.js';
+import { redact } from '../redact.js';
+import type { CliIo } from '../cli.js';
+
+/** Injected by tests; production takes the ambient clock and environment. */
+export interface CloudReadOptions extends CloudConnectionOptions {
+  env?: NodeJS.ProcessEnv;
+  now?: () => number;
+}
+
+/**
+ * Every way these verbs can refuse, as a code and a sentence.
+ *
+ * Each one names the thing to do next. A missing credential names
+ * `agent-relay cloud login` because that is the command that fixes it; a 404
+ * names `flows runs` because the usual cause is a run id from another
+ * workspace, and the list is how you find yours.
+ */
+export interface Refusal { code: string; message: string; exit: 1 | 2 }
+
+export function refusalFor(error: unknown, subject: string, env: NodeJS.ProcessEnv): Refusal {
+  const clean = (message: string): string => redact(message, env);
+  if (error instanceof CloudFlowError) {
+    if (error.code === 'configuration') {
+      switch (error.reason) {
+        case 'auth_missing':
+          return {
+            code: 'cloud_auth_missing', exit: 2,
+            message: 'No Cloud credential. Sign in with `agent-relay cloud login`, or set FLOWS_CLOUD_TOKEN to a '
+              + 'Cloud API token with workflow:runs:read (and workflow:logs:read for `flows logs`).',
+          };
+        case 'auth_expired':
+          return { code: 'cloud_auth_expired', exit: 2, message: clean(error.message) };
+        case 'url_mismatch':
+          return { code: 'cloud_url_mismatch', exit: 2, message: clean(error.message) };
+        default:
+          return { code: 'cloud_configuration', exit: 2, message: clean(error.message) };
+      }
+    }
+    if (error.code === 'http_error') {
+      if (error.status === 401) {
+        return {
+          code: 'cloud_auth_rejected', exit: 2,
+          message: 'Cloud rejected the credential (HTTP 401). The token is unknown or revoked; '
+            + 'sign in again with `agent-relay cloud login`.',
+        };
+      }
+      if (error.status === 403) {
+        return {
+          code: 'cloud_forbidden', exit: 2,
+          message: `The credential is valid but not allowed to read ${subject} (HTTP 403). `
+            + 'A run-scoped sandbox token may only read its own run; a workspace token needs '
+            + 'workflow:runs:read, and workflow:logs:read or workflow:invoke:read for logs.',
+        };
+      }
+      if (error.status === 404) {
+        return {
+          code: 'cloud_run_not_found', exit: 2,
+          message: `Cloud has no ${subject} visible to this credential (HTTP 404). `
+            + 'It may belong to another workspace; `flows runs` lists the ones this credential can read.',
+        };
+      }
+      return { code: 'cloud_http_error', exit: 1, message: clean(error.message) };
+    }
+    if (error.code === 'invalid_input') return { code: 'invalid_invocation', exit: 2, message: clean(error.message) };
+    if (error.code === 'transient_error' || error.code === 'transport_error') {
+      return { code: error.code === 'transient_error' ? 'cloud_unreachable' : 'cloud_transport_failed', exit: 1, message: clean(error.message) };
+    }
+    return { code: 'cloud_invalid_response', exit: 1, message: clean(error.message) };
+  }
+  return { code: 'cloud_read_failed', exit: 1, message: clean(error instanceof Error ? error.message : String(error)) };
+}
+
+export function fail(refusal: Refusal, json: boolean, io: CliIo): 1 | 2 {
+  if (json) io.stdout(canonicalize({ v: 1, ok: false, code: refusal.code, message: refusal.message }));
+  else io.stderr(`REFUSED [${refusal.code}] ${refusal.message}`);
+  return refusal.exit;
+}
+
+/**
+ * `flows status --cloud` with no run id.
+ *
+ * Shared by the one-shot and watched forms so both name the same remedy: a
+ * hosted run has no ambient id the way a step inside a local run does.
+ */
+export const RUN_ID_REQUIRED: Refusal = {
+  code: 'run_unknown', exit: 2,
+  message: '`flows status --cloud` needs the hosted run id; `flows runs` lists them. '
+    + '(Without --cloud the run id defaults to RELAYFLOW_RUN_ID inside a step.)',
+};
+
+/**
+ * A read that a poll can retry rather than end on.
+ *
+ * The same set `waitForCloudFlowRun` retries: the failure says the request did
+ * not complete, not that the request was wrong. Anything else — a 404, a
+ * rejected credential, a response this client cannot trust — ends the command
+ * through `refusalFor`, exactly as it ends a one-shot read.
+ */
+export function isTransientRead(error: unknown): boolean {
+  return error instanceof CloudFlowError && (error.code === 'transient_error'
+    || (error.code === 'http_error' && [408, 429, 500, 502, 503, 504].includes(error.status ?? 0)));
+}