@relayflows/sdk 2.0.17 → 2.0.18

package/src/flow-requirements.ts

@@ -0,0 +1,201 @@
+import { helperProviders } from '@relayflows/surface/runtime';
+import type { TriggerSource } from '@relayflows/surface';
+import { providerDeclaration } from './provider-trigger-contract.js';
+import type { FlowSpec } from './spec.js';
+import { helperCall } from './yaml-helpers.js';
+
+/**
+ * What a flow needs from the workspace it deploys into, read from inert
+ * declarations only: the header, the trigger sources, and the text of the
+ * body. Nothing here executes a body or opens a socket, so the same answer is
+ * available to `flows check`, to the hosted verbs before they submit, and to
+ * Cloud's deploy wizard from the source alone.
+ *
+ * Helper use is recognised exactly as `preflightHelpers` recognises it — a
+ * `tools.<namespace>: true` flag or a `f.<namespace>` reference in the body —
+ * so a flow that preflight would refuse for a missing mount is a flow whose
+ * integration this module names. Coding-agent harnesses come from the `cli:`
+ * each `f.agent`/`f.llm` call declares, else the project default, else Cloud's
+ * default (`claude`): the same precedence `resolveCli` applies at run time.
+ */
+
+export const FLOW_HARNESSES = ['claude', 'codex', 'gemini'] as const;
+export type FlowHarness = (typeof FLOW_HARNESSES)[number];
+
+export interface FlowIntegrationRequirement {
+  /** Cloud integration provider id (`slack`, `github`, `linear`, …). */
+  provider: string;
+  /** `tools`: a header declaration; `source`: a trigger or deploy target; `helper`: body use without a flag, or a YAML helper step. */
+  from: 'tools' | 'source' | 'helper';
+  /** The declaration that requires it, as a reader would name it: `tools.slack`, `--on github`, `f.slack`. */
+  detail: string;
+}
+
+export interface FlowHarnessRequirement {
+  harness: FlowHarness;
+  /** `agent "review"`, `llm step`, `step "draft"`, or `default`. */
+  detail: string;
+}
+
+export interface FlowRequirements {
+  integrations: FlowIntegrationRequirement[];
+  harnesses: FlowHarness[];
+  /** One entry per harness, naming the first declaration that needs it. */
+  harnessUses: FlowHarnessRequirement[];
+  /** MCP servers `tools.mcp` names; the workspace must declare each in `flows.json`. */
+  mcp: string[];
+}
+
+export interface FlowRequirementsContext {
+  /** Trigger sources the deployment listens on (`--on`, or the wizard's chosen sources). */
+  sources?: readonly { provider: string }[];
+  /** Set when the deployment targets a repository: every launched run needs GitHub. */
+  repository?: boolean | { owner: string; name: string };
+  /** The nearest `flows.json` `cli`, when one applies. */
+  projectCli?: string;
+}
+
+/** The inert subset of an authored definition this module reads. */
+export interface RequirementsFlowDefinition {
+  readonly header?: { readonly tools?: Readonly<Record<string, unknown>> };
+  readonly body?: Function;
+  readonly handlers?: readonly { readonly trigger: TriggerSource }[];
+}
+
+export function flowRequirements(
+  flow: RequirementsFlowDefinition | FlowSpec,
+  context: FlowRequirementsContext = {},
+): FlowRequirements {
+  const integrations = new Map<string, FlowIntegrationRequirement>();
+  const harnessUses = new Map<FlowHarness, FlowHarnessRequirement>();
+  const mcp = new Set<string>();
+  const declare = (requirement: FlowIntegrationRequirement): void => {
+    if (!integrations.has(requirement.provider)) integrations.set(requirement.provider, requirement);
+  };
+  const need = (harness: FlowHarness | undefined, detail: string): void => {
+    if (harness !== undefined && !harnessUses.has(harness)) harnessUses.set(harness, { harness, detail });
+  };
+  const fallback = harnessFromCli(context.projectCli) ?? 'claude';
+
+  if (isCompiledSpec(flow)) {
+    for (const step of flow.steps) {
+      // Preflight owns shape refusals; a malformed step is simply not a worker step here.
+      if (typeof step !== 'object' || step === null || (step.type !== 'llm' && step.type !== 'agent')) continue;
+      // A YAML helper step (`slack: { post: … }`) compiles to an agent step
+      // carrying a helper envelope: it needs the provider's mount, not a harness.
+      const helper = step.type === 'agent' ? compiledHelper(step) : undefined;
+      if (helper !== undefined) {
+        declare({ provider: helper, from: 'helper', detail: `step "${step.id}"` });
+        continue;
+      }
+      const named = step.type === 'agent' && step.agent !== undefined ? flow.agents?.[step.agent]?.cli : undefined;
+      const cli = step.cli ?? named ?? flow.cli;
+      need(cli === undefined ? fallback : harnessFromCli(cli), `step "${step.id}"`);
+    }
+  } else {
+    const tools = flow.header?.tools ?? {};
+    for (const { provider, namespace } of helperProviders) {
+      if (tools[namespace] === true) declare({ provider, from: 'tools', detail: `tools.${namespace}` });
+    }
+    for (const entry of stringList(tools['relayfile'])) {
+      const provider = entry.split('/')[0]?.trim();
+      if (provider) declare({ provider, from: 'tools', detail: 'tools.relayfile' });
+    }
+    for (const server of stringList(tools['mcp'])) mcp.add(server);
+    for (const handler of flow.handlers ?? []) {
+      const declaration = providerDeclaration(handler.trigger);
+      if (declaration !== undefined) {
+        declare({ provider: declaration.provider, from: 'source', detail: `on ${declaration.provider} ${declaration.type}` });
+      }
+    }
+    // Only the default body is scanned for helper and worker calls: hosted
+    // deployments and schedules dispatch the default body with the trigger's
+    // payload as input, and handler bodies are not dispatched yet (flows #301).
+    // A handler's *trigger* is still a requirement — it is what wakes the flow.
+    const text = typeof flow.body === 'function' ? Function.prototype.toString.call(flow.body) : '';
+    const root = contextParameter(text);
+    if (root !== undefined) {
+      for (const { provider, namespace } of helperProviders) {
+        if (helperReference(root, namespace).test(text)) declare({ provider, from: 'helper', detail: `f.${namespace}` });
+      }
+      for (const use of workerCalls(root, text)) need(use.cli === undefined ? fallback : harnessFromCli(use.cli), use.detail);
+    }
+  }
+
+  for (const source of context.sources ?? []) {
+    declare({ provider: source.provider, from: 'source', detail: `--on ${source.provider}` });
+  }
+  if (context.repository) declare({ provider: 'github', from: 'source', detail: 'deploy target' });
+
+  const uses = [...harnessUses.values()];
+  return {
+    integrations: [...integrations.values()],
+    harnesses: uses.map(use => use.harness),
+    harnessUses: uses,
+    mcp: [...mcp],
+  };
+}
+
+/** `slack (tools.slack), github (deploy target), claude (agent "review")` — the `REQUIRES` line's body. */
+export function describeFlowRequirements(requirements: FlowRequirements): string {
+  return [
+    ...requirements.integrations.map(integration => `${integration.provider} (${integration.detail})`),
+    ...requirements.harnessUses.map(use => `${use.harness} (${use.detail})`),
+    ...requirements.mcp.map(server => `mcp ${server} (tools.mcp)`),
+  ].join(', ');
+}
+
+/** `claude`, `/opt/bin/codex`, `gemini.exe` → the Cloud harness; anything else is not one. */
+export function harnessFromCli(cli: string | undefined): FlowHarness | undefined {
+  if (cli === undefined) return undefined;
+  const base = cli.trim().split(/[\\/]/u).pop()?.replace(/\.(?:exe|cmd|bat)$/iu, '').toLowerCase();
+  return (FLOW_HARNESSES as readonly string[]).includes(base ?? '') ? base as FlowHarness : undefined;
+}
+
+/** The provider of a compiled YAML helper step, or undefined for an ordinary agent step or a malformed envelope. */
+function compiledHelper(step: Parameters<typeof helperCall>[0]): string | undefined {
+  try {
+    return helperCall(step)?.provider;
+  } catch {
+    return undefined;
+  }
+}
+
+function isCompiledSpec(flow: RequirementsFlowDefinition | FlowSpec): flow is FlowSpec {
+  return Array.isArray((flow as FlowSpec).steps) && typeof (flow as FlowSpec).version === 'string';
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+}
+
+/** The body's first parameter (`f` in `async (f, input) => …`), escaped for a pattern. */
+function contextParameter(body: string): string | undefined {
+  const parameter = body.match(/^(?:async\s+)?(?:function(?:\s+[\w$]+)?\s*)?(?:\(\s*([\w$]+)|([\w$]+)\s*=>)/u);
+  return (parameter?.[1] ?? parameter?.[2])?.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+/** Same recognition as `preflightHelpers`: `f.slack`, `f .slack`, `f["slack"]`. */
+function helperReference(root: string, namespace: string): RegExp {
+  return new RegExp(`(?:^|[^\\w$.])${root}\\s*(?:\\.\\s*${namespace}\\b|\\[\\s*['"]${namespace}['"]\\s*\\])`, 'u');
+}
+
+interface WorkerCall { detail: string; cli?: string }
+
+/**
+ * Each `f.agent(name, { cli })` / `f.llm(prompt, { cli })` call and the CLI it
+ * declares. The options object is read only up to the next worker call, so a
+ * `cli:` belongs to the call it follows; a call without one takes the default.
+ */
+function workerCalls(root: string, body: string): WorkerCall[] {
+  const call = new RegExp(`(?:^|[^\\w$.])${root}\\s*\\.\\s*(agent|llm)\\s*\\(\\s*(?:(['"\`])([^'"\`]*)\\2)?`, 'gu');
+  const starts = [...body.matchAll(call)];
+  return starts.map((match, index) => {
+    const slice = body.slice(match.index! + match[0].length, starts[index + 1]?.index ?? body.length);
+    const cli = slice.match(/(?:^|[^\w$])cli\s*:\s*(['"`])([^'"`]*)\1/u)?.[2];
+    const detail = match[1] === 'agent'
+      ? (match[3] ? `agent ${JSON.stringify(match[3])}` : 'agent step')
+      : 'llm step';
+    return { detail, ...(cli === undefined ? {} : { cli }) };
+  });
+}

package/src/index.ts

@@ -76,6 +76,14 @@ export {
   deployToCloud, listCloudDeployments, undeployFromCloud, parseRepository, parseTriggerSource, FLOW_TRIGGER_PROVIDERS,
   type DeployToCloudInput, type CloudDeployment, type CloudDeploymentSummary, type FlowTriggerSource, type FlowTriggerProvider,
 } from './cloud-deploy.js';
+export {
+  ensureIntegrationsConnected, integrationConnected, providerLabel,
+  type ConnectPrompt, type EnsureConnectionsOptions, type ConnectionsOutcome,
+} from './cloud-connect.js';
+export {
+  flowRequirements, describeFlowRequirements, harnessFromCli, FLOW_HARNESSES,
+  type FlowRequirements, type FlowRequirementsContext, type FlowIntegrationRequirement, type FlowHarnessRequirement, type FlowHarness,
+} from './flow-requirements.js';
 
 export { canonicalize, specHash } from './canonical.js';
 export {

package/src/journal-client.ts

@@ -386,6 +386,26 @@ export class JournalClient extends EventEmitter {
   }
 
   /** Satisfy `wait.event`; a human response arrives here too. */
+  /**
+   * Park the dispatched attempt this connection holds on a human question.
+   * Releases the lease; the caller must not heartbeat or complete afterwards.
+   */
+  stepWait(
+    runId: string,
+    stepId: string,
+    attempt: number,
+    idempotencyKey: string,
+    wait: { wait_id: string; prompt: string; requested_of: string; options?: string[]; timeout_at_ms?: number },
+  ): Promise<VerbContract['step.wait']['result']> {
+    return this.request('step.wait', {
+      run_id: runId,
+      step_id: stepId,
+      attempt,
+      idempotency_key: idempotencyKey,
+      ...wait,
+    });
+  }
+
   eventEmit(runId: string, eventKey: string, payload: unknown): Promise<VerbContract['event.emit']['result']> {
     return this.request('event.emit', { run_id: runId, event_key: eventKey, payload });
   }

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 };