@relayflows/sdk 2.0.15 → 2.0.17

package/src/cloud-run.ts

@@ -1,4 +1,4 @@
-import { RUN_COMPLETION_REASONS } from '@relayflows/surface';
+import { RUN_COMPLETION_REASONS, type ScheduleTriggerSource } from '@relayflows/surface';
 import type { RunCompletionReason } from './protocol.js';
 import { readFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
@@ -10,9 +10,10 @@ import type { FlowSpec } from './spec.js';
 import { snapshotJsonValue, type JsonValue } from './json-value.js';
 import { loadAuthoredFlow, type SurfaceModuleAuthority } from './authored-flow-loader.js';
 import {
-  CloudFlowError, cloudConnection, cloudRequest, cloudRunId, isCloudRecord,
+  CloudFlowError, cloudConnection, cloudFetch, cloudRequest, cloudRunId, isCloudRecord,
   type CloudConnectionOptions,
 } from './cloud-http.js';
+import { packWorkingTree, prepareCloudSync, uploadCloudCode } from './cloud-sync.js';
 
 export type CloudFlowSource = FlowSpec | { path: string };
 export interface RunInCloudOptions extends CloudConnectionOptions {
@@ -20,6 +21,21 @@ export interface RunInCloudOptions extends CloudConnectionOptions {
   workspaceId?: string;
   /** Exact JSON input. Required at runtime for authored .flow.ts; refused for declarative source. */
   input?: JsonValue;
+  /**
+   * Upload this working tree before submission so the hosted run executes
+   * inside it (v1's `--sync-code`). Cloud-API storage only; see cloud-sync.ts.
+   * The submitted flow still travels as source in the request body, so it
+   * must remain self-contained: sibling imports inside the tree are not
+   * resolved by the hosted runner.
+   */
+  syncCode?: { root: string };
+  /**
+   * Called immediately before the one non-idempotent request, the run
+   * submission. Everything before it (prepare, pack, upload) is safe to
+   * retry, so a caller classifying an interruption can tell "nothing was
+   * admitted" from "admission unknown".
+   */
+  onSubmit?: () => void;
 }
 export interface CloudRunReceipt {
   runId: string;
@@ -28,6 +44,8 @@ export interface CloudRunReceipt {
   specHash: string;
   /** Authenticated run API resource; this is not a public sharing URL. */
   apiUrl: string;
+  /** Present when a working tree was synced: what was uploaded, by count and size. */
+  synced?: { files: number; bytes: number; skippedLinks: string[] };
 }
 export interface CloudAuthoredAuthority {
   readonly schemaVersion: 1;
@@ -35,6 +53,17 @@ export interface CloudAuthoredAuthority {
   readonly byteLength: number;
   readonly surface: SurfaceModuleAuthority;
 }
+/** The request-body fields a submission contributes; identical for a run and a schedule. */
+export function cloudSubmissionBody(submission: CloudSubmission): Record<string, unknown> {
+  return {
+    workflow: submission.workflow,
+    fileType: submission.fileType,
+    relayflowVersion: 'v2',
+    ...(submission.authoredAuthority === undefined ? {} : { authoredAuthority: submission.authoredAuthority }),
+    ...(submission.inputPresent ? { inputs: submission.inputs } : {}),
+  };
+}
+
 export type CloudRunState =
   | { runId: string; status: 'pending' | 'launching' | 'running' }
   | { runId: string; status: 'completed' | 'failed' | 'cancelled'; completionReason: RunCompletionReason };
@@ -44,13 +73,31 @@ export type CloudRunState =
  * happens here; Cloud owns provisioning and the Rust engine owns execution.
  * Returns acceptance, not completion. No local daemon, CLI probe, or node up.
  */
-export async function runInCloud(
+/**
+ * What a Cloud submission carries, before any request: the exact source or
+ * canonical spec, the pinned authority for authored source, the input, and a
+ * local correlation hash. Shared by `runInCloud` and `scheduleInCloud`, so a
+ * schedule stores exactly what a run would send.
+ */
+export interface CloudSubmission {
+  readonly workflow: string;
+  readonly fileType: 'yaml' | 'ts';
+  readonly authoredAuthority?: CloudAuthoredAuthority;
+  readonly inputs?: JsonValue;
+  readonly inputPresent: boolean;
+  readonly specHash: string;
+  /** The authored flow's declared name, or the spec name. */
+  readonly name: string;
+  /** Authored `schedule.*` handlers, for `flows schedule` to pick up. */
+  readonly schedules: readonly ScheduleTriggerSource[];
+}
+
+export async function prepareCloudSubmission(
   flow: CloudFlowSource,
-  options: RunInCloudOptions = {},
-): Promise<CloudRunReceipt> {
-  const { baseUrl } = cloudConnection(options);
+  options: { input?: JsonValue; signal?: AbortSignal } = {},
+): Promise<CloudSubmission> {
   let spec: FlowSpec | undefined;
-  let authored: { source: string; authority: CloudAuthoredAuthority } | undefined;
+  let authored: { source: string; authority: CloudAuthoredAuthority; name: string; schedules: ScheduleTriggerSource[] } | undefined;
   const inputPresent = Object.prototype.hasOwnProperty.call(options, 'input');
   let authoredInput: JsonValue | undefined;
   try {
@@ -62,14 +109,27 @@ export async function runInCloud(
         if (!bytes.length || Buffer.from(source, 'utf8').compare(bytes) !== 0) {
           throw new CloudFlowError('invalid_input', 'Authored source must be nonempty, lossless UTF-8.');
         }
-        const loaded = await loadAuthoredFlow(flow.path);
-        loaded.getDefinition(loaded.handle);
+        let loaded: Awaited<ReturnType<typeof loadAuthoredFlow>>;
+        let definition: ReturnType<typeof loaded.getDefinition>;
+        try {
+          loaded = await loadAuthoredFlow(flow.path);
+          definition = loaded.getDefinition(loaded.handle);
+        } catch (error) {
+          // An authored source that does not load is an authoring problem, and
+          // the most common one is `@relayflows/surface` not being resolvable
+          // from the flow's directory. Name it; do not call it a spec problem.
+          throw new CloudFlowError('unsupported_source',
+            `${flow.path} is not a loadable authored flow: ${error instanceof Error ? error.message : String(error)}. `
+            + 'Run `flows check` on it from the same directory.');
+        }
         if (loaded.graph.length !== 1) {
           throw new CloudFlowError('unsupported_source',
             'Cloud authored submission currently accepts one self-contained .flow.ts source without use dependencies.');
         }
         authored = {
           source,
+          name: definition.name,
+          schedules: definition.handlers.flatMap(h => h.trigger.kind === 'schedule' ? [h.trigger] : []),
           authority: Object.freeze({
             schemaVersion: 1,
             sourceSha256: createHash('sha256').update(bytes).digest('hex'),
@@ -112,27 +172,86 @@ export async function runInCloud(
     throw new CloudFlowError('invalid_input', 'Cannot read or compile the declarative flow. Check the file path and YAML/JSON spec.');
   }
   options.signal?.throwIfAborted();
-  const hash = authored === undefined
-    ? specHash(toKernelSpec(spec!))
-    : createHash('sha256').update(canonicalize({
-        authority: authored.authority,
-        input: authoredInput,
-      })).digest('hex');
-  const result = await cloudRequest('/api/v1/workflows/run', options, {
+  if (authored === undefined) {
+    const kernel = toKernelSpec(spec!);
     // JSON is a YAML subset. Sending canonical data preserves the exact spec
     // while using the server's existing YAML-to-config admission path.
-    workflow: authored?.source ?? canonicalize(spec),
-    fileType: authored === undefined ? 'yaml' : 'ts',
-    relayflowVersion: 'v2',
-    ...(authored === undefined ? {} : { authoredAuthority: authored.authority }),
-    ...(authored === undefined ? {} : { inputs: authoredInput }),
-    ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
-  });
+    return { workflow: canonicalize(spec), fileType: 'yaml', inputPresent: false, specHash: specHash(kernel),
+      name: spec!.name ?? "flow", schedules: [] };
+  }
+  return {
+    workflow: authored.source, fileType: 'ts', authoredAuthority: authored.authority,
+    inputs: authoredInput, inputPresent: true, name: authored.name, schedules: authored.schedules,
+    specHash: createHash('sha256').update(canonicalize({ authority: authored.authority, input: authoredInput })).digest('hex'),
+  };
+}
+
+/**
+ * Submit a declarative flow to Cloud's pinned v2 runtime. Compilation only
+ * happens here; Cloud owns provisioning and the Rust engine owns execution.
+ * Returns acceptance, not completion. No local daemon, CLI probe, or node up.
+ */
+export async function runInCloud(
+  flow: CloudFlowSource,
+  options: RunInCloudOptions = {},
+): Promise<CloudRunReceipt> {
+  const { baseUrl } = cloudConnection(options);
+  const submission = await prepareCloudSubmission(flow, options);
+  const hash = submission.specHash;
+  // Sync before submission: `prepare` reserves the run ID and the upload lands
+  // under it, so the run request below names code Cloud already holds. A
+  // refused backend or failed upload therefore never leaves a launched run
+  // pointing at a tree that is not there.
+  let synced: { runId: string; codeKey: string; files: number; bytes: number; skippedLinks: string[] } | undefined;
+  if (options.syncCode !== undefined) {
+    const prepared = await prepareCloudSync(options);
+    options.signal?.throwIfAborted();
+    const packed = await packWorkingTree(options.syncCode.root);
+    try {
+      options.signal?.throwIfAborted();
+      await uploadCloudCode(prepared, packed, options);
+    } finally {
+      packed.dispose();
+    }
+    synced = { runId: prepared.runId, codeKey: prepared.codeKey, files: packed.files.length, bytes: packed.bytes,
+      skippedLinks: packed.skippedLinks };
+  }
+  options.signal?.throwIfAborted();
+  options.onSubmit?.();
+  let result: unknown;
+  try {
+    result = await cloudFetch('/api/v1/workflows/run', options, { method: 'POST', detail: true, body: JSON.stringify({
+      ...cloudSubmissionBody(submission),
+      ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
+      ...(synced === undefined ? {} : { runId: synced.runId, s3CodeKey: synced.codeKey }),
+    }) });
+  } catch (error) {
+    // Cloud accepts exactly one authored Surface (the one its sandbox runs).
+    // A CLI on another release is refused with this code; say which side is
+    // which instead of leaving the user with a bare 400 (flows#461).
+    if (error instanceof CloudFlowError && submission.authoredAuthority !== undefined
+      && error.refusal?.code === 'relayflow_v2_authored_authority_invalid') {
+      const expected = error.refusal.expected?.version;
+      throw new CloudFlowError('unsupported_source',
+        `Cloud refused this authored flow's Surface: it runs @relayflows/surface ${expected ?? '(version not reported)'} `
+        + `and this CLI authored against ${submission.authoredAuthority.surface.version}. `
+        + 'Install the matching relayflows release, or deploy the flow with `flows deploy`, which uses Cloud\'s own Surface.',
+        error.status, error.refusal);
+    }
+    throw error;
+  }
   if (!isCloudRecord(result) || (result.status !== 'pending' && result.status !== 'running')) {
     throw new CloudFlowError('invalid_response', 'Cloud did not return an accepted run.');
   }
   const runId = cloudRunId(result.runId);
-  return { runId, status: result.status, specHash: hash, apiUrl: `${baseUrl}/api/v1/workflows/runs/${runId}` };
+  if (synced !== undefined && runId !== synced.runId) {
+    throw new CloudFlowError('invalid_response',
+      `Cloud accepted run ${runId} but the synced code was uploaded for ${synced.runId}.`);
+  }
+  return {
+    runId, status: result.status, specHash: hash, apiUrl: `${baseUrl}/api/v1/workflows/runs/${runId}`,
+    ...(synced === undefined ? {} : { synced: { files: synced.files, bytes: synced.bytes, skippedLinks: synced.skippedLinks } }),
+  };
 }
 
 export async function getCloudFlowRun(

package/src/cloud-schedule.ts

@@ -0,0 +1,158 @@
+import { cronGrid, everyToMs, parseCron, type ScheduleTriggerSource } from '@relayflows/surface';
+import { CloudFlowError, cloudFetch, cloudRequest, isCloudRecord, type CloudConnectionOptions } from './cloud-http.js';
+import { cloudSubmissionBody, prepareCloudSubmission, type CloudFlowSource } from './cloud-run.js';
+import type { JsonValue } from './json-value.js';
+
+/**
+ * Hosted schedules. `POST /api/v1/workflows/schedules` stores a workflow
+ * request and relaycron fires it on the cron; each fire replays the stored
+ * request through the same `/workflows/run` admission a `flows run --cloud`
+ * takes. So a schedule sends exactly what a run sends — `prepareCloudSubmission`
+ * — wrapped in the schedule envelope. Nothing runs at schedule time.
+ */
+
+export interface ScheduleInCloudInput {
+  flow: CloudFlowSource;
+  /** Five-field cron. Exactly one of `cron` or `every`, or neither to use the flow's declared `schedule.*`. */
+  cron?: string;
+  /** Fixed interval such as `5m`; lowered to a cron the server accepts. */
+  every?: string;
+  /** IANA zone the cron is evaluated in; default UTC. */
+  tz?: string;
+  /** Authored input, as `flows run --cloud --input`. */
+  input?: JsonValue;
+  /** Defaults to the flow's declared name. */
+  name?: string;
+}
+
+export interface CloudSchedule {
+  id: string;
+  name: string;
+  cronExpression: string;
+  timezone: string;
+  status: string;
+  createdAt?: string;
+  lastTriggeredAt?: string;
+  lastTriggeredRunId?: string;
+  lastTriggerStatus?: string;
+}
+
+const SCHEDULE_ID = /^[A-Za-z0-9_-]{1,128}$/u;
+
+/** `every("5m")` as a cron the server accepts; only intervals cron can express exactly. */
+export function everyToCron(every: string): string {
+  const ms = everyToMs(every);
+  const minutes = ms / 60_000;
+  if (Number.isInteger(minutes) && minutes >= 1 && minutes < 60 && 60 % minutes === 0) return `*/${minutes} * * * *`;
+  if (minutes === 60) return '0 * * * *';
+  const hours = ms / 3_600_000;
+  if (Number.isInteger(hours) && hours > 1 && hours < 24 && 24 % hours === 0) return `0 */${hours} * * *`;
+  if (hours === 24) return '0 0 * * *';
+  throw new CloudFlowError('invalid_input',
+    `--every ${every} has no exact cron: use a divisor of an hour (1m-30m), 1h, a divisor of a day (2h-12h), or 1d; or give --cron.`);
+}
+
+/** The cron a declared `schedule.*` source means on Cloud. */
+export function declaredScheduleCron(source: ScheduleTriggerSource): { cron: string; tz?: string } {
+  if (source.cron !== undefined) return { cron: source.cron, ...(source.tz === undefined ? {} : { tz: source.tz }) };
+  const minutes = (source.intervalMs ?? 0) / 60_000;
+  const every = Number.isInteger(minutes) ? `${minutes}m` : `${Math.round((source.intervalMs ?? 0) / 1000)}s`;
+  return { cron: everyToCron(every) };
+}
+
+function assertTimeZone(tz: string): string {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: tz });
+  } catch {
+    throw new CloudFlowError('invalid_input', `--tz ${JSON.stringify(tz)} is not a known IANA zone.`);
+  }
+  return tz;
+}
+
+export async function scheduleInCloud(
+  input: ScheduleInCloudInput, options: CloudConnectionOptions = {},
+): Promise<CloudSchedule> {
+  if (input.cron !== undefined && input.every !== undefined) {
+    throw new CloudFlowError('invalid_input', 'Give --cron or --every, not both.');
+  }
+  const submission = await prepareCloudSubmission(input.flow, {
+    ...(Object.prototype.hasOwnProperty.call(input, 'input') ? { input: input.input } : {}),
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+  });
+  let cron: string;
+  let tz = input.tz;
+  if (input.cron !== undefined) {
+    try { parseCron(input.cron); } catch (error) {
+      throw new CloudFlowError('invalid_input', `--cron: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    cron = input.cron.trim();
+  } else if (input.every !== undefined) {
+    cron = everyToCron(input.every);
+  } else {
+    if (submission.schedules.length !== 1) {
+      throw new CloudFlowError('invalid_input', submission.schedules.length === 0
+        ? 'The flow declares no schedule.* handler; give --cron or --every.'
+        : 'The flow declares several schedules; say which with --cron or --every.');
+    }
+    const declared = declaredScheduleCron(submission.schedules[0]!);
+    cron = declared.cron;
+    tz ??= declared.tz;
+  }
+  const timezone = tz === undefined ? 'UTC' : assertTimeZone(tz);
+  const name = (input.name ?? submission.name).trim();
+  if (!name) throw new CloudFlowError('invalid_input', 'Schedule name must not be empty.');
+  options.signal?.throwIfAborted();
+  const result = await cloudFetch('/api/v1/workflows/schedules', options, {
+    method: 'POST', detail: true,
+    body: JSON.stringify({
+      name,
+      schedule_type: 'cron',
+      cron_expression: cron,
+      timezone,
+      workflowRequest: cloudSubmissionBody(submission),
+    }),
+  });
+  const record = isCloudRecord(result) && isCloudRecord(result.schedule) ? result.schedule : undefined;
+  if (record === undefined) throw new CloudFlowError('invalid_response', 'Cloud did not return a schedule.');
+  return toCloudSchedule(record);
+}
+
+function toCloudSchedule(row: Record<string, unknown>): CloudSchedule {
+  if (typeof row.id !== 'string' || !SCHEDULE_ID.test(row.id) || typeof row.name !== 'string') {
+    throw new CloudFlowError('invalid_response', 'Cloud returned a malformed schedule.');
+  }
+  const optional = (key: string): Record<string, string> =>
+    typeof row[key] === 'string' ? { [key]: row[key] as string } : {};
+  return {
+    id: row.id, name: row.name,
+    cronExpression: typeof row.cronExpression === 'string' ? row.cronExpression : '',
+    timezone: typeof row.timezone === 'string' ? row.timezone : 'UTC',
+    status: typeof row.status === 'string' ? row.status : 'unknown',
+    ...optional('createdAt'), ...optional('lastTriggeredAt'), ...optional('lastTriggeredRunId'), ...optional('lastTriggerStatus'),
+  };
+}
+
+export async function listCloudSchedules(options: CloudConnectionOptions = {}): Promise<CloudSchedule[]> {
+  const payload = await cloudRequest('/api/v1/workflows/schedules', options);
+  if (!isCloudRecord(payload) || !Array.isArray(payload.schedules)) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return a schedules list.');
+  }
+  return payload.schedules.map(row => {
+    if (!isCloudRecord(row)) throw new CloudFlowError('invalid_response', 'Cloud returned a malformed schedule row.');
+    return toCloudSchedule(row);
+  });
+}
+
+export async function unscheduleInCloud(scheduleId: string, options: CloudConnectionOptions = {}): Promise<void> {
+  if (!SCHEDULE_ID.test(scheduleId)) throw new CloudFlowError('invalid_input', `"${scheduleId}" is not a schedule id.`);
+  const result = await cloudFetch(`/api/v1/workflows/schedules/${encodeURIComponent(scheduleId)}`, options,
+    { method: 'DELETE', detail: true });
+  if (!isCloudRecord(result) || result.deleted !== true) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not confirm the deletion.');
+  }
+}
+
+/** Exposed for previews: the tick grid a UTC cron amounts to, if it is exactly one. */
+export function cronIntervalMs(cron: string): number | undefined {
+  return cronGrid(parseCron(cron))?.intervalMs;
+}