@relayflows/sdk 2.0.13 → 2.0.15

package/src/cli/direct-run.ts

@@ -14,6 +14,8 @@ import { JournalClient } from '../journal-client.js';
 import { inputFailureReport } from './check.js';
 import { checkAuthoredTriggers } from './check-triggers.js';
 import {
+  authoredCompletion,
+  authoredStepFailure,
   connect,
   emptyReport,
   fromCheckReport,
@@ -98,31 +100,7 @@ export async function runDirectFlow(
         `authored flow "${result.name}" completed without a journal step`,
       ));
     }
-    if (result.completionReason === 'needs_human') {
-      return {
-        exitCode: 3,
-        report: {
-          ...base, ok: false, runId: result.rootRunId, socketPath, status: 'parked',
-          completedSteps: result.journalSteps.length,
-          diagnostics: [...base.diagnostics, {
-            severity: 'parked', kind: 'run_parked',
-            message: `Flow "${result.name}" needs_human; see the journal for accumulated blockers.`,
-          }],
-        },
-      };
-    }
-    return {
-      exitCode: 0,
-      report: {
-        ...base,
-        ok: true,
-        runId: result.rootRunId,
-        socketPath,
-        status: 'completed',
-        completionReason: result.completionReason,
-        completedSteps: result.journalSteps.length,
-      },
-    };
+    return authoredCompletion('run', base, socketPath, result, result.rootRunId);
   } catch (caught) {
     if (caught instanceof McpPreflightError) return {
       exitCode: 2, report: fromCheckReport('run', caught.report),
@@ -190,33 +168,12 @@ export async function runDirectFlow(
         },
       };
     }
-    // A step that ran and failed is a run failure, not a protocol failure.
-    // Routing it through `protocolFailure` reported `relayflowd could not
-    // complete the run request` — which says the daemon broke — and left the
-    // report with no `status`, so the summary line printed `RUN <id> unknown`
-    // about a run whose outcome was known exactly. The diagnostic carried up
-    // from `classifyOutcome` already names the step, its exit code and its
-    // output tail; this branch is what lets it reach the terminal. Mirrors
-    // the `McpStepError` branch above, which had this shape all along.
+    // A step that ran and failed is a run failure, not a protocol failure. The
+    // diagnostic carried up from `classifyOutcome` already names the step, its
+    // exit code and its output tail; this branch is what lets it reach the
+    // terminal. `resumeFlow` takes the same branch, through the same helper.
     if (error instanceof AuthoredFlowExecutionError && error.code === 'step_failed') {
-      return {
-        exitCode: 1,
-        report: {
-          ...base,
-          ok: false,
-          runId: error.runId,
-          socketPath,
-          status: 'failed',
-          completionReason: 'step_failed',
-          diagnostics: [...base.diagnostics, {
-            severity: 'failure',
-            kind: 'step_failed',
-            // The `code: ` prefix `AuthoredFlowExecutionError` adds is
-            // redundant once the diagnostic is labelled `[step_failed]`.
-            message: error.message.replace(/^step_failed: /, ''),
-          }],
-        },
-      };
+      return authoredStepFailure('run', base, socketPath, error);
     }
     const runId = error instanceof AuthoredFlowExecutionError ? error.runId : undefined;
     return protocolFailure('run', base, socketPath, error, runId);

package/src/cli/run.ts

@@ -22,6 +22,7 @@ import type {
   RunStatus,
 } from '../protocol.js';
 import type { StepType } from '../spec.js';
+import type { LoweredCompletionReason } from '../authored-flow-executor.js';
 import {
   checkFlow,
   type CheckReport,
@@ -191,21 +192,7 @@ export async function resumeFlow(
         lifecycle: options,
       });
       if (result === undefined) throw new Error('authored root disappeared during resume');
-      return {
-        exitCode: result.completionReason === 'needs_human' ? 3 : 0,
-        report: {
-          ...base,
-          ok: result.completionReason === 'success',
-          runId,
-          socketPath,
-          status: result.completionReason === 'needs_human' ? 'parked' : 'completed',
-          ...(result.completionReason === 'success'
-            ? { completionReason: 'success' as const }
-            : { diagnostics: [{ severity: 'parked' as const, kind: 'run_parked' as const,
-              message: `Flow "${result.name}" needs_human; see the journal for accumulated blockers.` }] }),
-          completedSteps: result.journalSteps.length,
-        },
-      };
+      return authoredCompletion('resume', base, socketPath, result, runId);
     }
     // resumeHelperEffect subsumes the old resumeSlackEffect: it handles the
     // slack effect resume plus every other provider from N's codegen. The
@@ -231,6 +218,14 @@ export async function resumeFlow(
       return { exitCode: 2, report: { ...base, runId, socketPath,
         diagnostics: [{ severity: 'refusal', kind: error.code, message: error.message }] } };
     }
+    // Same classification the run path gets. Resuming an authored root whose
+    // `f.agent` step failed is a step failure, not a protocol failure, and
+    // leaving it on `protocolFailure` meant `flows run` printed the evidence
+    // while `flows resume` still printed `protocol_error` and
+    // `RUN <id> unknown` for the identical failure.
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'step_failed') {
+      return authoredStepFailure('resume', base, socketPath, error, runId);
+    }
     if (!(error instanceof JournalProtocolError) || error.code !== 'run_not_found') {
       return protocolFailure('resume', base, socketPath, error, runId);
     }
@@ -258,6 +253,121 @@ export async function resumeFlow(
   }
 }
 
+/**
+ * A step that ran and failed, reported as the run failure it is.
+ *
+ * Shared by `runDirectFlow` and `resumeFlow` on purpose. The first cut of this
+ * fix classified the run path and left resume on `protocolFailure`, so `flows
+ * run` became diagnosable while `flows resume` still printed `protocol_error`
+ * and `RUN <id> unknown` for the same failed step — and the surface doc claimed
+ * both were fixed. One function is what stops the two paths drifting again.
+ *
+ * `protocolFailure` is wrong here twice over: it blames the daemon for a run it
+ * drove correctly, and it produces a report with no `status`, which is the
+ * whole of what `RUN <id> unknown` ever meant.
+ */
+export function authoredStepFailure(
+  command: RunCommand,
+  base: CheckReport | RunReport,
+  socketPath: string,
+  error: AuthoredFlowExecutionError,
+  fallbackRunId?: string,
+): RunExecution {
+  // The failing step runs as its own kernel run, so the error's run id is the
+  // one whose journal holds the evidence. The resume target is the fallback.
+  const runId = error.runId ?? fallbackRunId;
+  return {
+    exitCode: 1,
+    report: {
+      ...fromBase(command, base),
+      ok: false,
+      ...(runId === undefined ? {} : { runId }),
+      socketPath,
+      status: 'failed',
+      completionReason: 'step_failed',
+      diagnostics: [...base.diagnostics, {
+        severity: 'failure',
+        kind: 'step_failed',
+        // The `step_failed: ` prefix `AuthoredFlowExecutionError` adds is
+        // redundant once the diagnostic is labelled `[step_failed]`.
+        message: error.message.replace(/^step_failed: /, ''),
+      }],
+    },
+  };
+}
+
+/**
+ * An authored body that returned its own terminal verdict, reported as that verdict.
+ *
+ * Shared by `runDirectFlow` and `resumeFlow` for the reason `authoredStepFailure`
+ * is shared: the run and resume paths had already drifted once, and the
+ * `needs_human` report was duplicated verbatim in both files.
+ *
+ * This is NOT `authoredStepFailure`, even though a `step_failed` verdict lands
+ * on the same exit code and report shape. That function describes a step that
+ * ran and failed, and carries the failing step's evidence. Here every step
+ * succeeded and the BODY declared the outcome, so there is no failing step to
+ * name — routing this through the other helper would invent one.
+ */
+export function authoredCompletion(
+  command: RunCommand,
+  base: RunReport,
+  socketPath: string,
+  result: { name: string; completionReason: LoweredCompletionReason; journalSteps: readonly unknown[] },
+  runId: string | undefined,
+): RunExecution {
+  const common: RunReport = {
+    ...fromBase(command, base),
+    ...(runId === undefined ? {} : { runId }),
+    socketPath,
+    completedSteps: result.journalSteps.length,
+  };
+  switch (result.completionReason) {
+    case 'success':
+      return {
+        exitCode: 0,
+        report: { ...common, ok: true, status: 'completed', completionReason: 'success' },
+      };
+    case 'needs_human':
+      return {
+        exitCode: 3,
+        report: {
+          ...common, ok: false, status: 'parked',
+          diagnostics: [...base.diagnostics, {
+            severity: 'parked', kind: 'run_parked',
+            message: `Flow "${result.name}" needs_human; see the journal for accumulated blockers.`,
+          }],
+        },
+      };
+    case 'step_failed':
+      // A declared run failure. Exit 1, not the parked 3: nothing here is
+      // waiting for a human to recover it, and exit 3 is the local kit's
+      // manual-approval stop. `status: failed` with this `completionReason` is
+      // also the only terminal shape Cloud accepts for a non-success run
+      // (see cloud-run.ts).
+      return {
+        exitCode: 1,
+        report: {
+          ...common, ok: false, status: 'failed', completionReason: 'step_failed',
+          diagnostics: [...base.diagnostics, {
+            severity: 'failure', kind: 'step_failed',
+            message: `Flow "${result.name}" declared done("step_failed"): its own checks did not pass. `
+              + 'No step failed, so there is no step-level evidence to inspect; the journal holds '
+              + 'every step the flow ran before it decided.',
+          }],
+        },
+      };
+  }
+  // Exhaustive by construction. A fourth lowered completion has to choose its
+  // own exit code and wording here; it must not inherit "its own checks did not
+  // pass", which would state something the body never declared. Letting an
+  // unlisted reason fall through to the failure branch is how a reporting-side
+  // copy of the same vocabulary drifts from the executor's — the defect this
+  // change exists to close — so it is a compile error, not a wrong report.
+  const unreachable: never = result.completionReason;
+  throw new Error(`unreachable authored completion: ${String(unreachable)}`);
+}
+
 /**
  * Get a live daemon, then open the socket to it.
  *