@relayflows/sdk 2.0.17 → 2.0.18

package/src/cli/cloud-connect-cli.ts

@@ -0,0 +1,130 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { parse as parseYaml } from 'yaml';
+import { loadAuthoredFlow } from '../authored-flow-loader.js';
+import { ensureIntegrationsConnected, type ConnectPrompt, type ConnectionsOutcome } from '../cloud-connect.js';
+import { CloudFlowError, cloudRequest, isCloudRecord, type CloudConnectionOptions } from '../cloud-http.js';
+import { CompileError, compileSpec, kernelToAuthoring } from '../compile.js';
+import { FLOW_HARNESSES, flowRequirements, type FlowRequirements, type FlowRequirementsContext } from '../flow-requirements.js';
+import { readProjectConfig } from './check.js';
+import type { CliIo } from '../cli.js';
+
+/**
+ * The hosted verbs' shared "are the integrations connected?" step. It runs
+ * before `flows deploy`, `flows schedule` and `flows run --cloud` submit
+ * anything, so a flow that would fail at its first `f.slack.post` with
+ * `helper_slack.credential_missing` is connected — or refused — first.
+ *
+ * The flow is read the same way the submission reads it (authored loader or
+ * YAML compile); a source that does not load is left for the submission to
+ * refuse with its own, better diagnostic, so this step never masks one.
+ */
+
+export interface FlowConnectionsInput extends FlowRequirementsContext {
+  path: string;
+  /** `undefined` refuses a missing integration instead of prompting (`--no-connect`, `--json`, no TTY). */
+  prompt: ConnectPrompt | undefined;
+  /** Known already (deploy resolved it); otherwise `whoami` supplies it. */
+  workspaceId?: string;
+}
+
+export async function flowRequirementsForPath(
+  path: string, context: FlowRequirementsContext = {},
+): Promise<FlowRequirements | undefined> {
+  const projectCli = context.projectCli ?? projectCliFor(path);
+  const withCli = { ...context, ...(projectCli === undefined ? {} : { projectCli }) };
+  try {
+    if (/\.flow\.ts$/iu.test(path)) {
+      const loaded = await loadAuthoredFlow(path);
+      return flowRequirements(loaded.getDefinition(loaded.handle), withCli);
+    }
+    if (!/\.(?:ya?ml|json)$/iu.test(path)) return undefined;
+    const parsed: unknown = parseYaml(await readFile(path, 'utf8'));
+    let spec;
+    try {
+      spec = compileSpec(parsed);
+    } catch (error) {
+      if (!(error instanceof CompileError)) throw error;
+      spec = compileSpec(kernelToAuthoring(parsed));
+    }
+    return flowRequirements(spec, withCli);
+  } catch {
+    return undefined;
+  }
+}
+
+function projectCliFor(path: string): string | undefined {
+  try {
+    return readProjectConfig(dirname(resolve(path))).cli;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `whoami`'s current workspace: the one every hosted verb submits into. */
+export async function currentWorkspaceId(options: CloudConnectionOptions): Promise<string> {
+  const whoami = await cloudRequest('/api/v1/auth/whoami', options);
+  const workspace = isCloudRecord(whoami) && isCloudRecord(whoami.currentWorkspace) ? whoami.currentWorkspace : undefined;
+  if (workspace === undefined || typeof workspace.id !== 'string' || !workspace.id) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not report a current workspace for this credential.');
+  }
+  return workspace.id;
+}
+
+/**
+ * Connects (or refuses on) every integration `path` requires. Nothing is
+ * contacted when the flow requires no integration, so a flow with no
+ * helpers, sources or repository submits exactly as before; the derived
+ * requirements still come back so a later harness refusal can name its remedy.
+ * `undefined` only when the source does not load — the submission says why.
+ */
+export async function ensureFlowConnections(
+  input: FlowConnectionsInput, options: CloudConnectionOptions = {},
+): Promise<{ requirements: FlowRequirements; outcome: ConnectionsOutcome } | undefined> {
+  const requirements = await flowRequirementsForPath(input.path, input);
+  if (requirements === undefined) return undefined;
+  if (requirements.integrations.length === 0) return { requirements, outcome: { ready: [], connected: [] } };
+  const workspaceId = input.workspaceId ?? await currentWorkspaceId(options);
+  const outcome = await ensureIntegrationsConnected(requirements, {
+    ...options, workspaceId, ...(input.prompt === undefined ? {} : { prompt: input.prompt }),
+  });
+  return { requirements, outcome };
+}
+
+/**
+ * A terminal prompt, or nothing. `--json` output is for a machine, and a
+ * pipe cannot answer a question, so both refuse instead of asking; `--no-connect`
+ * is the explicit form of the same choice.
+ */
+export function cliConnectPrompt(
+  io: CliIo, { noConnect, json }: { noConnect: boolean; json: boolean },
+  streams: { stdin: NodeJS.ReadStream; stdout: NodeJS.WriteStream } = { stdin: process.stdin, stdout: process.stdout },
+): ConnectPrompt | undefined {
+  if (noConnect || json || !streams.stdin.isTTY || !streams.stdout.isTTY) return undefined;
+  return {
+    info: line => io.stderr(line),
+    confirm: question => new Promise(resolveAnswer => {
+      const rl = createInterface({ input: streams.stdin, output: streams.stdout });
+      rl.question(question, answer => {
+        rl.close();
+        resolveAnswer(/^\s*(?:y(?:es)?)?\s*$/iu.test(answer));
+      });
+    }),
+  };
+}
+
+/**
+ * Cloud refuses a run or activation whose coding-agent credential is missing
+ * (`flow_model_not_connected`, `cli_credentials_missing`); there is no status
+ * route to ask first, so the refusal is where the remedy is named.
+ */
+export function harnessRemedy(error: unknown, harnesses: readonly string[]): string {
+  if (!(error instanceof CloudFlowError) || error.refusal === undefined) return '';
+  if (!['flow_model_not_connected', 'cli_credentials_missing'].includes(error.refusal.code)) return '';
+  if (/agent-relay cloud connect/u.test(error.refusal.error)) return '';
+  const message = error.refusal.error.toLowerCase();
+  const named = FLOW_HARNESSES.filter(harness => message.includes(harness));
+  const targets = named.length > 0 ? named : harnesses.length > 0 ? harnesses : ['claude'];
+  return ` Connect it with: ${targets.map(harness => `agent-relay cloud connect ${harness}`).join('; ')}.`;
+}

package/src/cli/cloud-deploy.ts

@@ -3,6 +3,8 @@ import {
   deployToCloud, listCloudDeployments, parseAgentHarnesses, parseRepository, parseTriggerSource, undeployFromCloud,
   type FlowTriggerSource,
 } from '../cloud-deploy.js';
+import { describeFlowRequirements } from '../flow-requirements.js';
+import { cliConnectPrompt, flowRequirementsForPath, harnessRemedy } from './cloud-connect-cli.js';
 import type { CliIo } from '../cli.js';
 
 export interface CloudDeployArgs {
@@ -14,12 +16,14 @@ export interface CloudDeployArgs {
   name: string | undefined;
   agents: string | undefined;
   draft: boolean;
+  /** Refuse a missing integration instead of offering to connect it. */
+  noConnect: boolean;
   json: boolean;
 }
 
 /**
  * `flows deploy <flow.ts> --repo <owner/name> --on <provider>[:k=v,…] [--on …]
- *   --approver <handle> [--name <n>] [--json]`
+ *   --approver <handle> [--name <n>] [--agents <list>] [--draft] [--no-connect] [--json]`
  *
  * Parsed here rather than in `parseDeployArgs` because the two `deploy` forms
  * share nothing but the word: the digest form copies a sealed bundle into a
@@ -32,6 +36,7 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
   let name: string | undefined;
   let agents: string | undefined;
   let draft = false;
+  let noConnect = false;
   let json = false;
   const on: string[] = [];
   for (let i = 0; i < args.length; i++) {
@@ -46,6 +51,11 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
       draft = true;
       continue;
     }
+    if (arg === '--no-connect') {
+      if (noConnect) return undefined;
+      noConnect = true;
+      continue;
+    }
     if (arg === '--agents') {
       const next = args[i + 1];
       if (agents !== undefined || next === undefined || next.startsWith('-')) return undefined;
@@ -68,7 +78,7 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
     value = arg;
   }
   if (value === undefined || repo === undefined || on.length === 0) return undefined;
-  return { command: 'cloud-deploy', value, repo, on, approver, name, agents, draft, json };
+  return { command: 'cloud-deploy', value, repo, on, approver, name, agents, draft, noConnect, json };
 }
 
 function describeSource(source: FlowTriggerSource): string {
@@ -77,11 +87,19 @@ function describeSource(source: FlowTriggerSource): string {
 }
 
 export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promise<0 | 1 | 2> {
+  const agents = args.agents === undefined ? undefined : parseAgentHarnessesOr(args.agents);
+  // What the source declares, so a harness refusal names the right remedy
+  // even when `--agents` was not given; the loader's own failure is reported
+  // by deployToCloud, not here.
+  let harnesses: readonly string[] = agents instanceof CloudFlowError ? [] : agents ?? [];
   try {
     if (args.approver === undefined) {
       throw new CloudFlowError('invalid_input',
         '--approver <handle> is required: every launched run receives it as input.approver for f.human.');
     }
+    if (agents instanceof CloudFlowError) throw agents;
+    const connect = cliConnectPrompt(io, { noConnect: args.noConnect, json: args.json });
+    if (agents === undefined) harnesses = (await flowRequirementsForPath(args.value))?.harnesses ?? [];
     const deployment = await deployToCloud({
       path: args.value,
       repository: parseRepository(args.repo),
@@ -89,7 +107,8 @@ export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promi
       approver: args.approver,
       draft: args.draft,
       ...(args.name === undefined ? {} : { name: args.name }),
-      ...(args.agents === undefined ? {} : { agents: parseAgentHarnesses(args.agents) }),
+      ...(agents === undefined ? {} : { agents }),
+      ...(connect === undefined ? {} : { connect }),
     });
     if (args.json) {
       io.stdout(JSON.stringify({ ok: true, ...deployment }));
@@ -99,12 +118,24 @@ export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promi
     io.stdout(`  flow: ${deployment.name} (${args.value}, sha256 ${deployment.sourceSha256.slice(0, 12)})`);
     io.stdout(`  repository: ${deployment.repository.owner}/${deployment.repository.name}`);
     for (const source of deployment.sources) io.stdout(`  on: ${describeSource(source)}`);
+    const requires = describeFlowRequirements(deployment.requirements);
+    if (requires) io.stdout(`  requires: ${requires}`);
+    for (const provider of deployment.connected) io.stdout(`  connected: ${provider}`);
     io.stdout(deployment.status === 'draft'
       ? 'Saved without activating; activate it from the Cloud dashboard, or redeploy without --draft.'
       : 'Each matching ticket launches a run of this source in a fresh branch; list with: flows deployments');
     return 0;
   } catch (error) {
-    return reportCloudFailure(error, args.json, io);
+    return reportCloudFailure(error, args.json, io, harnesses);
+  }
+}
+
+function parseAgentHarnessesOr(value: string): ReturnType<typeof parseAgentHarnesses> | CloudFlowError {
+  try {
+    return parseAgentHarnesses(value);
+  } catch (error) {
+    if (error instanceof CloudFlowError) return error;
+    throw error;
   }
 }
 
@@ -140,9 +171,11 @@ export async function runCloudUndeployCli({ agentId, json }: { agentId: string;
   }
 }
 
-function reportCloudFailure(error: unknown, json: boolean, io: CliIo): 1 | 2 {
+function reportCloudFailure(error: unknown, json: boolean, io: CliIo, harnesses: readonly string[] = []): 1 | 2 {
   const code = error instanceof CloudFlowError ? error.code : 'cloud_deploy_failed';
   let message = error instanceof Error ? error.message : 'Cloud deploy failed.';
+  // Cloud names the missing coding-agent credential on activation; say how it is connected.
+  message += harnessRemedy(error, harnesses);
   // The deploy routes take a browser session or a `cli:auth` token. A
   // deployment (CI) token gets 403 `session_required`; say what fixes it.
   if (error instanceof CloudFlowError && error.status === 403) {
@@ -152,6 +185,7 @@ function reportCloudFailure(error: unknown, json: boolean, io: CliIo): 1 | 2 {
   if (json) io.stdout(JSON.stringify({ ok: false, code, message }));
   else io.stderr(`${code}: ${message}`);
   return error instanceof CloudFlowError
-    && (['configuration', 'unsupported_source', 'invalid_input'].includes(error.code) || error.status === 403 || error.status === 401)
+    && (['configuration', 'unsupported_source', 'invalid_input', 'integration_not_connected'].includes(error.code)
+      || error.status === 403 || error.status === 401)
     ? 2 : 1;
 }

package/src/cli/cloud-run.ts

@@ -2,12 +2,13 @@ import { CloudFlowError } from '../cloud-http.js';
 import { runInCloud, waitForCloudFlowRun, type RunInCloudOptions } from '../cloud-run.js';
 import { DirectInputError, isAuthoredFlowPath, parseDirectInput } from '../direct-input.js';
 import { snapshotJsonValue } from '../json-value.js';
+import { cliConnectPrompt, ensureFlowConnections, harnessRemedy } from './cloud-connect-cli.js';
 import type { CliIo } from '../cli.js';
 
 /** Presentation only: the central CLI parser owns argv; the SDK owns the lifecycle. */
 export async function runCloudCli(
-  { value: path, json, wait, input, syncCode }: {
-    value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean;
+  { value: path, json, wait, input, syncCode, noConnect = false }: {
+    value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean; noConnect?: boolean;
   },
   io: CliIo,
 ): Promise<0 | 1 | 2> {
@@ -20,6 +21,7 @@ export async function runCloudCli(
   // packing or upload — admitted nothing and is safe to retry; only an
   // interrupted submission has unknown admission.
   let submitting = false;
+  let harnesses: readonly string[] = [];
   try {
     const options: RunInCloudOptions = { signal: controller.signal, onSubmit: () => { submitting = true; } };
     if (isAuthoredFlowPath(path)) {
@@ -32,6 +34,15 @@ export async function runCloudCli(
         throw error;
       }
     }
+    // After local validation, before anything is packed or uploaded: a helper
+    // the run would call against an unconnected integration is connected
+    // here, or refused here. A command that is going to be refused for its
+    // arguments must not first open a browser.
+    const connections = await ensureFlowConnections({
+      path, prompt: cliConnectPrompt(io, { noConnect, json }),
+    }, { signal: controller.signal });
+    harnesses = connections?.requirements.harnesses ?? [];
+    for (const provider of connections?.outcome.connected ?? []) if (!json) io.stdout(`CONNECTED ${provider}`);
     // The tree is the invoking directory, as with v1: the flow path is where
     // the body lives, not the boundary of what the run may read.
     if (syncCode) options.syncCode = { root: process.cwd() };
@@ -65,11 +76,12 @@ export async function runCloudCli(
         : submitting
           ? 'Submission interrupted before a receipt was received. Admission is unknown; Cloud may have started the run. Do not resubmit blindly.'
           : 'Interrupted before the run was submitted; nothing was admitted. Safe to run again.'
-      : error instanceof Error ? error.message : 'Cloud run failed.';
+      : (error instanceof Error ? error.message : 'Cloud run failed.') + harnessRemedy(error, harnesses);
     if (json) io.stdout(JSON.stringify({ ok: false, code, message, ...(runId ? { runId } : {}) }));
     else io.stderr(`${code}: ${message}${runId ? ` (run ${runId})` : ''}`);
     return error instanceof CloudFlowError
-      && (['configuration', 'unsupported_source', 'invalid_input', 'unsupported_storage_backend', 'sync_too_large', 'sync_unsupported'].includes(error.code)
+      && (['configuration', 'unsupported_source', 'invalid_input', 'unsupported_storage_backend', 'sync_too_large', 'sync_unsupported',
+        'integration_not_connected'].includes(error.code)
         || (runId === undefined && error.code === 'http_error' && [401, 403].includes(error.status ?? 0))) ? 2 : 1;
   } finally {
     process.off('SIGINT', abort);

package/src/cli/cloud-schedule.ts

@@ -1,7 +1,8 @@
 import { CloudFlowError } from '../cloud-http.js';
-import { listCloudSchedules, scheduleInCloud, unscheduleInCloud, type CloudSchedule } from '../cloud-schedule.js';
+import { listCloudSchedules, scheduleInCloud, unscheduleInCloud, validateScheduleArgs, type CloudSchedule } from '../cloud-schedule.js';
 import { DirectInputError, isAuthoredFlowPath, parseDirectInput } from '../direct-input.js';
 import { snapshotJsonValue, type JsonValue } from '../json-value.js';
+import { cliConnectPrompt, ensureFlowConnections, harnessRemedy } from './cloud-connect-cli.js';
 import type { CliIo } from '../cli.js';
 
 export interface CloudScheduleArgs {
@@ -12,12 +13,14 @@ export interface CloudScheduleArgs {
   tz: string | undefined;
   input: string | undefined;
   name: string | undefined;
+  /** Refuse a missing integration instead of offering to connect it. */
+  noConnect: boolean;
   json: boolean;
 }
 
 /**
  * `flows schedule <flow.yaml|flow.ts> [--cron "<expr>" | --every <n><s|m|h|d>]
- *   [--tz <IANA>] [--input <json|file>] [--name <n>] [--json]`
+ *   [--tz <IANA>] [--input <json|file>] [--name <n>] [--no-connect] [--json]`
  *
  * With neither `--cron` nor `--every`, the flow's own `schedule.*` handler
  * supplies the cron, so a declared schedule and its hosted registration
@@ -29,6 +32,7 @@ export function parseCloudScheduleArgs(args: readonly string[]): CloudScheduleAr
     cron: undefined, every: undefined, tz: undefined, input: undefined, name: undefined,
   };
   let json = false;
+  let noConnect = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]!;
     if (arg === '--json') {
@@ -36,6 +40,11 @@ export function parseCloudScheduleArgs(args: readonly string[]): CloudScheduleAr
       json = true;
       continue;
     }
+    if (arg === '--no-connect') {
+      if (noConnect) return undefined;
+      noConnect = true;
+      continue;
+    }
     if (arg === '--cron' || arg === '--every' || arg === '--tz' || arg === '--input' || arg === '--name') {
       const key = arg.slice(2) as keyof typeof flags;
       const next = args[i + 1];
@@ -51,7 +60,7 @@ export function parseCloudScheduleArgs(args: readonly string[]): CloudScheduleAr
   if (value === undefined) return undefined;
   if (flags.cron !== undefined && flags.every !== undefined) return undefined;
   if (flags.input !== undefined && !isAuthoredFlowPath(value)) return undefined;
-  return { command: 'schedule', value, ...flags, json };
+  return { command: 'schedule', value, ...flags, noConnect, json };
 }
 
 function describe(schedule: CloudSchedule): string {
@@ -61,6 +70,7 @@ function describe(schedule: CloudSchedule): string {
 }
 
 export async function runCloudScheduleCli(args: CloudScheduleArgs, io: CliIo): Promise<0 | 1 | 2> {
+  let harnesses: readonly string[] = [];
   try {
     let input: JsonValue | undefined;
     let inputPresent = false;
@@ -73,6 +83,18 @@ export async function runCloudScheduleCli(args: CloudScheduleArgs, io: CliIo): P
         throw error;
       }
     }
+    validateScheduleArgs({
+      ...(args.cron === undefined ? {} : { cron: args.cron }),
+      ...(args.every === undefined ? {} : { every: args.every }),
+      ...(args.tz === undefined ? {} : { tz: args.tz }),
+    });
+    // Each fire runs the flow as this workspace, so what it needs connected
+    // is checked once here — after the arguments are known to be good, so a
+    // refused command never opens a browser first — and before the schedule exists.
+    const connections = await ensureFlowConnections({
+      path: args.value, prompt: cliConnectPrompt(io, { noConnect: args.noConnect, json: args.json }),
+    });
+    harnesses = connections?.requirements.harnesses ?? [];
     const schedule = await scheduleInCloud({
       flow: { path: args.value },
       ...(args.cron === undefined ? {} : { cron: args.cron }),
@@ -86,10 +108,11 @@ export async function runCloudScheduleCli(args: CloudScheduleArgs, io: CliIo): P
       return 0;
     }
     io.stdout(`SCHEDULED ${describe(schedule)}`);
+    for (const provider of connections?.outcome.connected ?? []) io.stdout(`  connected: ${provider}`);
     io.stdout('Each fire submits this exact source through the same admission as flows run --cloud; list with: flows schedules');
     return 0;
   } catch (error) {
-    return reportFailure(error, args.json, io);
+    return reportFailure(error, args.json, io, harnesses);
   }
 }
 
@@ -120,9 +143,10 @@ export async function runCloudUnscheduleCli(
   }
 }
 
-function reportFailure(error: unknown, json: boolean, io: CliIo): 1 | 2 {
+function reportFailure(error: unknown, json: boolean, io: CliIo, harnesses: readonly string[] = []): 1 | 2 {
   const code = error instanceof CloudFlowError ? error.code : 'cloud_schedule_failed';
   let message = error instanceof Error ? error.message : 'Cloud schedule failed.';
+  message += harnessRemedy(error, harnesses);
   // The schedule routes take a browser session or a `cli:auth` token.
   if (error instanceof CloudFlowError && error.status === 403) {
     message += ' Scheduling needs an interactive `cli:auth` credential: run `agent-relay cloud login`.';
@@ -130,6 +154,7 @@ function reportFailure(error: unknown, json: boolean, io: CliIo): 1 | 2 {
   if (json) io.stdout(JSON.stringify({ ok: false, code, message }));
   else io.stderr(`${code}: ${message}`);
   return error instanceof CloudFlowError
-    && (['configuration', 'unsupported_source', 'invalid_input'].includes(error.code) || error.status === 403 || error.status === 401)
+    && (['configuration', 'unsupported_source', 'invalid_input', 'integration_not_connected'].includes(error.code)
+      || error.status === 403 || error.status === 401)
     ? 2 : 1;
 }

package/src/cli/direct-run.ts

@@ -8,6 +8,7 @@ import {
   AuthoredFlowExecutionError,
 } from '../authored-flow-executor.js';
 import { executeDurableAuthoredFlow } from '../authored-root.js';
+import { AuthoredHumanParked } from '../authored-flow-error.js';
 import { AuthoredFlowLoadError } from '../authored-flow-loader.js';
 import { DirectInputError, parseDirectInput } from '../direct-input.js';
 import { JournalClient } from '../journal-client.js';
@@ -15,6 +16,7 @@ import { inputFailureReport } from './check.js';
 import { checkAuthoredTriggers } from './check-triggers.js';
 import {
   authoredCompletion,
+  authoredHumanParked,
   authoredStepFailure,
   connect,
   emptyReport,
@@ -175,6 +177,9 @@ export async function runDirectFlow(
     if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
       return authoredStepFailure('run', base, socketPath, error);
     }
+    if (error instanceof AuthoredHumanParked) {
+      return authoredHumanParked('run', base, socketPath, error, { dataDir, localAgent: options.localAgent === true });
+    }
     const runId = error instanceof AuthoredFlowExecutionError ? error.runId : undefined;
     return protocolFailure('run', base, socketPath, error, runId);
   } finally {

package/src/cli/run.ts

@@ -2,7 +2,8 @@ import { parseDigestReference } from '../bundle-transport.js';
 import { prepareDigestRun } from './run-digest.js';
 import { reuseSummary } from './reuse.js';
 import { resumeHelperEffect } from '../authored-helper-effect.js';
-import { AuthoredFlowExecutionError } from '../authored-flow-error.js';
+import { AuthoredFlowExecutionError, AuthoredHumanParked, type AuthoredHumanWait } from '../authored-flow-error.js';
+import { answerCommand, resumeCommand } from '../authored-human.js';
 import { join, resolve } from 'node:path';
 import type { ProgressEvent } from '../progress.js';
 import { toKernelSpec } from '../compile.js';
@@ -29,7 +30,7 @@ import {
 } from './check.js';
 
 export type RunExitCode = 0 | 1 | 2 | 3;
-export type RunCommand = 'run' | 'resume';
+export type RunCommand = 'run' | 'resume' | 'answer';
 
 export interface ParkedStep {
   id: string;
@@ -53,6 +54,12 @@ export interface RunReport {
   completedSteps?: number;
   reuse?: { fromRunId: string; reusedSteps: number; executedSteps: number };
   parkedStep?: ParkedStep;
+  /** The open `f.human` question a parked authored run is waiting on. */
+  humanWait?: AuthoredHumanWait;
+  /** `flows answer` only: the answer it recorded. */
+  answer?: { waitId: string; answer: boolean; note?: string };
+  /** The invocation that continues this run, when one is known. */
+  next?: string;
   projectConfigPath?: string;
   resolutions: CheckReport['resolutions'];
   diagnostics: Array<CheckReport['diagnostics'][number] | RunDiagnostic>;
@@ -226,6 +233,9 @@ export async function resumeFlow(
     if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
       return authoredStepFailure('resume', base, socketPath, error, runId);
     }
+    if (error instanceof AuthoredHumanParked) {
+      return authoredHumanParked('resume', base, socketPath, error, { dataDir, localAgent: options.localAgent === true });
+    }
     if (!(error instanceof JournalProtocolError) || error.code !== 'run_not_found') {
       return protocolFailure('resume', base, socketPath, error, runId);
     }
@@ -298,6 +308,42 @@ export function authoredStepFailure(
   };
 }
 
+/**
+ * An authored body parked on an unanswered `f.human`: exit 3, like every
+ * other park, but the diagnostic names the question, who it is for, and the
+ * exact `flows answer` invocation — the run is waiting on a person, not on a
+ * worker. Shared by `run` and `resume` so the two never drift.
+ */
+export function authoredHumanParked(
+  command: RunCommand,
+  base: CheckReport | RunReport,
+  socketPath: string,
+  error: AuthoredHumanParked,
+  where: { dataDir?: string; localAgent: boolean },
+): RunExecution {
+  const runId = error.runId!;
+  return {
+    exitCode: 3,
+    report: {
+      ...fromBase(command, base),
+      ok: false,
+      runId,
+      socketPath,
+      status: 'parked',
+      parkedStep: { id: 'authored-root', type: 'agent' },
+      humanWait: error.wait,
+      diagnostics: [...base.diagnostics, {
+        severity: 'parked',
+        kind: 'run_parked',
+        message: `Run "${runId}" is waiting for ${error.wait.to} to answer ${error.wait.waitId}: `
+          + `${JSON.stringify(error.wait.question)}\n`
+          + `Answer with: ${answerCommand(runId, error.wait.waitId, where.dataDir)}\n`
+          + `Then continue with: ${resumeCommand(runId, where.dataDir, where.localAgent)}`,
+      }],
+    },
+  };
+}
+
 /**
  * An authored body that returned its own terminal verdict, reported as that verdict.
  *