@relayflows/sdk 2.0.17 → 2.0.19

package/src/progress.ts

@@ -1,8 +1,10 @@
 import type { CompletionReason } from './protocol.js';
 import type { StepType } from './spec.js';
+import { AuthoredHumanParked } from './authored-flow-error.js';
 
 export interface ProgressEvent {
-  type: 'step.started' | 'step.running' | 'step.completed' | 'step.failed';
+  /** `step.parked`: an `f.human` reached without an answer; the run parks, nothing failed. */
+  type: 'step.started' | 'step.running' | 'step.completed' | 'step.failed' | 'step.parked';
   stepId: string;
   stepType: StepType;
   elapsedMs: number;
@@ -12,13 +14,15 @@ export interface ProgressEvent {
 /** Pure terminal rendering: caller owns the event source, clock, and output. */
 export function renderProgress(events: Iterable<ProgressEvent>): string[] {
   return Array.from(events, event => {
-    const icon = { 'step.started': '○', 'step.running': '↻', 'step.completed': '✓', 'step.failed': '✗' }[event.type];
+    const icon = { 'step.started': '○', 'step.running': '↻', 'step.completed': '✓', 'step.failed': '✗', 'step.parked': '⏸' }[event.type];
     const state = event.type.slice('step.'.length);
+    // A parked `f.human` is a question, not a step type the kernel ran.
+    const kind = event.type === 'step.parked' ? 'human' : event.stepType;
     const agent = event.stepType === 'agent' ? ` [agent: ${state === 'started' ? 'preparing' : state}]` : '';
     const reason = event.completionReason ? ` completionReason: ${event.completionReason}` : '';
     // Agent-authored names cannot inject terminal control sequences.
     const name = event.stepId.replace(/[\x00-\x1f\x7f-\x9f]/g, '?');
-    return `${icon} ${name} (${event.stepType})${agent} ${(Math.max(0, event.elapsedMs) / 1000).toFixed(2)}s${reason}`;
+    return `${icon} ${name} (${kind})${agent} ${(Math.max(0, event.elapsedMs) / 1000).toFixed(2)}s${reason}`;
   });
 }
 
@@ -45,7 +49,10 @@ export async function observeStep<T>(
     publish({ type: 'step.completed', stepId, stepType, elapsedMs: performance.now() - started, completionReason: 'success' });
     return result;
   } catch (error) {
-    publish({ type: 'step.failed', stepId, stepType, elapsedMs: performance.now() - started });
+    publish({
+      type: error instanceof AuthoredHumanParked ? 'step.parked' : 'step.failed',
+      stepId, stepType, elapsedMs: performance.now() - started,
+    });
     throw error;
   }
 }

package/src/protocol.ts

@@ -52,6 +52,7 @@ export type Verb =
   | 'effect.record'
   | 'effect.confirm'
   | 'step.complete'
+  | 'step.wait'
   | 'event.emit'
   | 'event.submit'
   | 'stream.append'
@@ -329,6 +330,27 @@ export interface StepCompleteParams {
 }
 export type StepCompleteResult = RunOutcome;
 
+/**
+ * Park a leased attempt on a durable human question (`wait.human`, kernel
+ * DESIGN.md §1.5). The attempt is not completed and no iteration is charged;
+ * the lease is released once the wait is journaled. The answer arrives through
+ * `event.emit` with `event_key` = `wait_id`, which closes the wait as
+ * `human_responded` and makes the step runnable for a fresh attempt.
+ */
+export interface StepWaitParams {
+  run_id: string;
+  step_id: string;
+  attempt: number;
+  idempotency_key: string;
+  /** Names the question for the life of the run; the kernel refuses a reuse. */
+  wait_id: string;
+  prompt: string;
+  requested_of: string;
+  options?: string[];
+  timeout_at_ms?: number;
+}
+export type StepWaitResult = RunOutcome;
+
 export interface EventEmitParams {
   run_id: string;
   event_key: string;
@@ -401,6 +423,7 @@ export interface VerbContract {
   'effect.record': { params: EffectRecordParams; result: EffectRecordResult };
   'effect.confirm': { params: EffectConfirmParams; result: EffectConfirmResult };
   'step.complete': { params: StepCompleteParams; result: StepCompleteResult };
+  'step.wait': { params: StepWaitParams; result: StepWaitResult };
   'event.emit': { params: EventEmitParams; result: EventEmitResult };
   'event.submit': { params: EventSubmitParams; result: EventSubmitResult };
   'stream.append': { params: StreamAppendParams; result: StreamAppendResult };

package/src/relay-cli.ts

@@ -0,0 +1,117 @@
+import { readFileSync } from 'node:fs';
+
+import { runCli } from './cli.js';
+import { CLI_VERBS, CLI_VERB_NAMES, type CliCommandSpec } from './cli-commands.js';
+
+/**
+ * The `@relayflows/sdk/relay-cli` entrypoint: a mountable CLI surface.
+ *
+ * `agent-relay` mounts this as `agent-relay flows`. The surface is a thin
+ * projection over the CLI this package already ships -- `commands` comes from
+ * the same `CLI_VERBS` table `parseArgs` dispatches on, and `run` delegates
+ * straight to `runCli`. No command is reimplemented here, and
+ * `packages/relayflows/bin/flows.js` keeps calling `runCli` on the same path.
+ *
+ * Structurally typed against `@agent-relay/cli-surface` without importing it,
+ * so `dist/relay-cli.d.ts` has no dependency on the contract package and this
+ * package gains no runtime dependency on relay. `tests/relay-cli-surface.test.ts`
+ * asserts the assignability and runs the contract's own conformance checks.
+ */
+
+/** Host-supplied output sink. Mirrors `RelayCliIo`. */
+export interface RelayCliIo {
+  stdout(chunk: string): void;
+  stderr(chunk: string): void;
+}
+
+/** A mountable product CLI. Mirrors `RelayCliSurface`. */
+export interface RelayCliSurface {
+  id: string;
+  version: string;
+  contract: 1;
+  commands: readonly CliCommandSpec[];
+  run(argv: readonly string[], io: RelayCliIo): Promise<number>;
+}
+
+/** Options for {@link createRelayCliSurface}. */
+export interface CreateRelayCliSurfaceOptions {
+  /**
+   * Cancellation for the long-running verbs, owned by the host.
+   *
+   * A surface must install no global signal handlers, so one is always passed
+   * to `runCli` -- a never-aborting signal when the host supplies none. Pass a
+   * real one to get graceful cancellation (for example, the
+   * "Stopped observing; the hosted run has not been cancelled" path on
+   * `run --cloud --wait`) instead of the host's SIGINT killing the process.
+   */
+  signal?: AbortSignal;
+}
+
+/** Exit code for an argv the surface cannot route, per the contract. */
+const EXIT_UNKNOWN_COMMAND = 2;
+
+/** Drop `variants` -- the routing detail the host has no use for. */
+function toCommandSpec(verb: CliCommandSpec & { variants?: unknown }): CliCommandSpec {
+  const { variants: _variants, ...spec } = verb;
+  return spec;
+}
+
+/**
+ * Read this package's version from its own manifest.
+ *
+ * Resolved from `import.meta.url` rather than imported, because `package.json`
+ * sits outside `rootDir` and a hardcoded literal would silently go stale at the
+ * next release. `src/` and `dist/` are both one level below the manifest, so
+ * the same relative path is correct before and after a build.
+ */
+function packageVersion(): string {
+  try {
+    const manifest: unknown = JSON.parse(
+      readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+    );
+    const version = (manifest as { version?: unknown }).version;
+    return typeof version === 'string' && version.length > 0 ? version : '0.0.0';
+  } catch {
+    // A surface that cannot read its own manifest is still perfectly runnable;
+    // refusing to mount over a cosmetic field would be the worse failure.
+    return '0.0.0';
+  }
+}
+
+/**
+ * Build the relayflows CLI surface.
+ *
+ * @param options - Host-supplied cancellation.
+ * @returns A surface whose `run` resolves to an exit code, writes only through
+ *   the supplied io, and installs no process signal handlers.
+ */
+export function createRelayCliSurface(
+  options: CreateRelayCliSurfaceOptions = {},
+): RelayCliSurface {
+  return {
+    id: 'relayflows',
+    version: packageVersion(),
+    contract: 1,
+    commands: CLI_VERBS.map(toCommandSpec),
+    async run(argv: readonly string[], io: RelayCliIo): Promise<number> {
+      const verb = argv[0];
+      // `runCli` would refuse this too, but with the full usage block. Naming
+      // the offending token is the more useful answer when the host has just
+      // routed `agent-relay flows <typo>` here.
+      if (verb !== undefined && !verb.startsWith('-') && !CLI_VERB_NAMES.has(verb)) {
+        io.stderr(`error: '${verb}' is not a command of relayflows\n`);
+        io.stderr("Run 'agent-relay flows --help' for the available commands.\n");
+        return EXIT_UNKNOWN_COMMAND;
+      }
+      return runCli(
+        argv,
+        // `CliIo` is line-oriented and the contract's io is chunk-oriented, so
+        // the terminator is added here rather than by every call site.
+        { stdout: (line) => io.stdout(`${line}\n`), stderr: (line) => io.stderr(`${line}\n`) },
+        // Always pass a signal: that is what keeps `runCli` from installing the
+        // SIGINT/SIGTERM handlers the standalone binary still relies on.
+        { signal: options.signal ?? new AbortController().signal },
+      );
+    },
+  };
+}