@relayflows/surface 2.0.53 → 2.0.54

package/dist/signals.d.ts

@@ -0,0 +1,77 @@
+/** The longest hold Cloud's signal GET accepts, and the default. */
+export declare const SIGNAL_MAX_WAIT_MS = 25000;
+/** Cloud's run ID for this hosted run (not the engine's `RELAYFLOW_RUN_ID`). */
+export declare const HOSTED_RUN_ID_ENV = "RELAYFLOW_V2_CLOUD_RUN_ID";
+/** The run-bound, GET-only `workflow:signals:read` bearer Cloud gives the authored process. */
+export declare const HOSTED_SIGNAL_READ_TOKEN_ENV = "RELAYFLOW_V2_SIGNAL_READ_TOKEN";
+/** The Cloud application base URL the Flows CLI uses. */
+export declare const CLOUD_URL_ENV = "FLOWS_CLOUD_URL";
+export declare const DEFAULT_CLOUD_URL = "https://agentrelay.com/cloud";
+export type SignalErrorCode = "configuration" | "invalid_input" | "invalid_response" | "http_error" | "transport_error" | "transient_error";
+/** Set only for `configuration`: which local setting is missing or wrong. */
+export type SignalConfigurationReason = "run_id_missing" | "auth_missing" | "url_invalid" | "timeout_invalid";
+export declare class SignalError extends Error {
+    readonly code: SignalErrorCode;
+    readonly status?: number | undefined;
+    reason?: SignalConfigurationReason;
+    constructor(code: SignalErrorCode, message: string, status?: number | undefined);
+}
+export interface WaitForSignalOptions {
+    /** Hold per request, 0–25000 ms. Defaults to 25000. */
+    waitMs?: number;
+    /** Cancels the wait; the caller's abort reason is rethrown unchanged. */
+    signal?: AbortSignal;
+    /** Defaults to `process.env.RELAYFLOW_V2_CLOUD_RUN_ID`. */
+    runId?: string;
+    /** Defaults to `process.env.FLOWS_CLOUD_URL`, then https://agentrelay.com/cloud. */
+    apiUrl?: string;
+    /** Defaults to `process.env.RELAYFLOW_V2_SIGNAL_READ_TOKEN`. */
+    token?: string;
+    /** Bounds each held request; must exceed `waitMs`. Defaults to 30000. */
+    requestTimeoutMs?: number;
+}
+/** Builds the error a caller sees; lets the SDK keep throwing `CloudFlowError`. */
+export type SignalErrorFactory = (code: Exclude<SignalErrorCode, "configuration">, message: string, status?: number) => Error;
+/**
+ * The seams `@relayflows/sdk` supplies to share this implementation. Not part
+ * of the authored-flow surface; use {@link waitForSignal} in a flow.
+ */
+export interface SignalWaitHooks {
+    /** Resolved before every held request so a rotated credential is picked up. */
+    connection(): Promise<{
+        baseUrl: string;
+        token: string;
+    }> | {
+        baseUrl: string;
+        token: string;
+    };
+    error?: SignalErrorFactory;
+    /** Abort-aware sleep used for the fast-204 backoff. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<unknown>;
+}
+/** Validates both path segments, run ID first, before any request. */
+export declare function signalPath(runId: unknown, name: unknown, error?: SignalErrorFactory): string;
+/**
+ * The shared held-GET loop. A normally held 204 re-arms immediately; a fast
+ * 204 (under one second) backs off 250 ms doubling to a 5 s cap, so a proxy or
+ * broken server cannot turn the wait into a hot loop. The backoff resets after
+ * a normally held 204.
+ *
+ * `@relayflows/sdk` calls this with its own connection resolver and error
+ * class; authored flows should call {@link waitForSignal}.
+ */
+export declare function holdSignalWait(runId: unknown, name: unknown, options: Pick<WaitForSignalOptions, "waitMs" | "signal" | "requestTimeoutMs">, hooks: SignalWaitHooks): Promise<unknown>;
+/**
+ * Wait for this hosted run's completion signal and return its JSON payload.
+ *
+ * ```ts
+ * import { waitForSignal } from "@relayflows/surface/signals";
+ * const done = await waitForSignal("native_done");
+ * ```
+ *
+ * Call it in the authored flow body, not inside an `f.run` command: only the
+ * authored process holds the run-bound read token. The wait has no overall
+ * deadline; pass `signal` (e.g. `AbortSignal.timeout(ms)`) to bound it.
+ */
+export declare function waitForSignal(name: string, options?: WaitForSignalOptions): Promise<unknown>;
+//# sourceMappingURL=signals.d.ts.map

package/dist/signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../src/signals.ts"],"names":[],"mappings":"AAeA,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,8BAA8B,CAAC;AAC7D,+FAA+F;AAC/F,eAAO,MAAM,4BAA4B,mCAAmC,CAAC;AAC7E,yDAAyD;AACzD,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAC/C,eAAO,MAAM,iBAAiB,iCAAiC,CAAC;AAUhE,MAAM,MAAM,eAAe,GACvB,eAAe,GACf,eAAe,GACf,kBAAkB,GAClB,YAAY,GACZ,iBAAiB,GACjB,iBAAiB,CAAC;AAEtB,6EAA6E;AAC7E,MAAM,MAAM,yBAAyB,GACjC,gBAAgB,GAChB,cAAc,GACd,aAAa,GACb,iBAAiB,CAAC;AAEtB,qBAAa,WAAY,SAAQ,KAAK;IAIlC,QAAQ,CAAC,IAAI,EAAE,eAAe;IAE9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAL1B,MAAM,CAAC,EAAE,yBAAyB,CAAC;gBAGxB,IAAI,EAAE,eAAe,EAC9B,OAAO,EAAE,MAAM,EACN,MAAM,CAAC,EAAE,MAAM,YAAA;CAK3B;AAED,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,mFAAmF;AACnF,MAAM,MAAM,kBAAkB,GAAG,CAC/B,IAAI,EAAE,OAAO,CAAC,eAAe,EAAE,eAAe,CAAC,EAC/C,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,KACZ,KAAK,CAAC;AAEX;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,UAAU,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/F,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,uDAAuD;IACvD,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChE;AAeD,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,GAAE,kBAAgC,GAAG,MAAM,CASzG;AAyBD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,QAAQ,GAAG,kBAAkB,CAAC,EAC7E,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,OAAO,CAAC,CA4DlB;AAqBD;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,OAAO,CAAC,CAOtG"}

package/dist/signals.js

@@ -0,0 +1,197 @@
+/**
+ * Hosted completion signals: `@relayflows/surface/signals`.
+ *
+ * Hosted Cloud runs materialize only `@relayflows/surface` next to the flow
+ * source, so this module must stay importable on its own: no imports beyond
+ * Node built-ins, and Cloud is reached through the global `fetch`. It is the
+ * single implementation of the held-GET signal wait; `@relayflows/sdk`'s
+ * `waitForCloudSignal` delegates to {@link holdSignalWait}.
+ *
+ * Call {@link waitForSignal} from the authored flow body. The run-bound read
+ * credential lives only in that process; `f.run` children and agents never
+ * receive it.
+ */
+import { setTimeout as delay } from "node:timers/promises";
+/** The longest hold Cloud's signal GET accepts, and the default. */
+export const SIGNAL_MAX_WAIT_MS = 25_000;
+/** Cloud's run ID for this hosted run (not the engine's `RELAYFLOW_RUN_ID`). */
+export const HOSTED_RUN_ID_ENV = "RELAYFLOW_V2_CLOUD_RUN_ID";
+/** The run-bound, GET-only `workflow:signals:read` bearer Cloud gives the authored process. */
+export const HOSTED_SIGNAL_READ_TOKEN_ENV = "RELAYFLOW_V2_SIGNAL_READ_TOKEN";
+/** The Cloud application base URL the Flows CLI uses. */
+export const CLOUD_URL_ENV = "FLOWS_CLOUD_URL";
+export const DEFAULT_CLOUD_URL = "https://agentrelay.com/cloud";
+const SIGNAL_NAME = /^[A-Za-z0-9_-]{1,80}$/u;
+const RUN_ID = /^[A-Za-z0-9_-]{1,128}$/u;
+const MAX_TIMER_MS = 2_147_483_647;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const FAST_204_MS = 1_000;
+const FAST_204_INITIAL_BACKOFF_MS = 250;
+const FAST_204_MAX_BACKOFF_MS = 5_000;
+export class SignalError extends Error {
+    code;
+    status;
+    reason;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "SignalError";
+    }
+}
+const signalError = (code, message, status) => new SignalError(code, message, status);
+function configurationError(reason, message) {
+    const error = new SignalError("configuration", message);
+    error.reason = reason;
+    return error;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Validates both path segments, run ID first, before any request. */
+export function signalPath(runId, name, error = signalError) {
+    // Defensive path-segment constraint; accepting a new server ID format needs a Surface change.
+    if (typeof runId !== "string" || !RUN_ID.test(runId)) {
+        throw error("invalid_response", "Cloud run ID must contain only letters, digits, underscores, or hyphens.");
+    }
+    if (typeof name !== "string" || !SIGNAL_NAME.test(name)) {
+        throw error("invalid_input", "Signal name must contain only letters, digits, underscores, or hyphens (1–80 characters).");
+    }
+    return `/api/v1/workflows/runs/${runId}/signals/${name}`;
+}
+/** Same classification as the SDK's Cloud transport: retryable network faults are transient. */
+function transportError(cause, error) {
+    const inner = cause instanceof Error ? cause.cause : undefined;
+    const code = isRecord(inner) ? inner.code : undefined;
+    const transient = (cause instanceof Error && cause.name === "TimeoutError")
+        || ["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "ETIMEDOUT",
+            "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT", "UND_ERR_SOCKET"].includes(String(code));
+    return transient
+        ? error("transient_error", "Cloud transport temporarily unavailable.")
+        : error("transport_error", "Cloud transport failed; check TLS and the configured URL (redirects are refused).");
+}
+function normalizeCloudBaseUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash
+            || !/^\/[A-Za-z0-9/_-]*$/u.test(url.pathname))
+            return undefined;
+        return `${url.origin}${url.pathname.replace(/\/+$/u, "")}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The shared held-GET loop. A normally held 204 re-arms immediately; a fast
+ * 204 (under one second) backs off 250 ms doubling to a 5 s cap, so a proxy or
+ * broken server cannot turn the wait into a hot loop. The backoff resets after
+ * a normally held 204.
+ *
+ * `@relayflows/sdk` calls this with its own connection resolver and error
+ * class; authored flows should call {@link waitForSignal}.
+ */
+export async function holdSignalWait(runId, name, options, hooks) {
+    const error = hooks.error ?? signalError;
+    const sleep = hooks.sleep ?? ((ms, signal) => delay(ms, undefined, { signal }));
+    const path = signalPath(runId, name, error);
+    const waitMs = options.waitMs ?? SIGNAL_MAX_WAIT_MS;
+    if (!Number.isSafeInteger(waitMs) || waitMs < 0 || waitMs > SIGNAL_MAX_WAIT_MS) {
+        throw error("invalid_input", "Signal waitMs must be an integer from 0 to 25000.");
+    }
+    const requestTimeout = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    if (!Number.isSafeInteger(requestTimeout) || requestTimeout <= waitMs) {
+        throw error("invalid_input", `Signal requestTimeoutMs must exceed ${waitMs / 1000} seconds.`);
+    }
+    let fast204BackoffMs = FAST_204_INITIAL_BACKOFF_MS;
+    for (;;) {
+        options.signal?.throwIfAborted();
+        const { baseUrl, token } = await hooks.connection();
+        const deadline = AbortSignal.timeout(requestTimeout);
+        const requestStartedAt = performance.now();
+        let response;
+        try {
+            response = await fetch(`${baseUrl}${path}?waitMs=${waitMs}`, {
+                method: "GET",
+                headers: { authorization: `Bearer ${token}` },
+                signal: options.signal ? AbortSignal.any([options.signal, deadline]) : deadline,
+                // A redirect must never carry the credential to a different origin.
+                redirect: "error",
+            });
+        }
+        catch (cause) {
+            options.signal?.throwIfAborted();
+            throw transportError(deadline.aborted ? deadline.reason : cause, error);
+        }
+        if (response.status === 204) {
+            if (performance.now() - requestStartedAt < FAST_204_MS) {
+                try {
+                    await sleep(fast204BackoffMs, options.signal);
+                }
+                catch (cause) {
+                    options.signal?.throwIfAborted();
+                    throw cause;
+                }
+                fast204BackoffMs = Math.min(fast204BackoffMs * 2, FAST_204_MAX_BACKOFF_MS);
+            }
+            else {
+                fast204BackoffMs = FAST_204_INITIAL_BACKOFF_MS;
+            }
+            continue;
+        }
+        // Do not echo server response bodies: they may contain credentials or source.
+        if (!response.ok)
+            throw error("http_error", `Cloud signal wait failed with HTTP ${response.status}.`, response.status);
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch (cause) {
+            options.signal?.throwIfAborted();
+            if (!(cause instanceof SyntaxError))
+                throw transportError(deadline.aborted ? deadline.reason : cause, error);
+            throw error("invalid_response", "Cloud returned an invalid signal.");
+        }
+        if (!isRecord(body) || !Object.hasOwn(body, "payload") || typeof body.acceptedAt !== "number") {
+            throw error("invalid_response", "Cloud returned an invalid signal.");
+        }
+        return body.payload;
+    }
+}
+function hostedConnection(options) {
+    const requestTimeout = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    if (requestTimeout > MAX_TIMER_MS) {
+        throw configurationError("timeout_invalid", "requestTimeoutMs must be a positive 32-bit integer.");
+    }
+    const rawToken = options.token ?? process.env[HOSTED_SIGNAL_READ_TOKEN_ENV];
+    const token = rawToken?.trim();
+    if (!token || /[\r\n]/u.test(rawToken) || /^(?:rk|ot)_live_/u.test(token)) {
+        throw configurationError("auth_missing", `waitForSignal needs a Cloud signal-read token: pass { token }, or call it from a hosted run's authored body, where ${HOSTED_SIGNAL_READ_TOKEN_ENV} is set.`);
+    }
+    const raw = options.apiUrl ?? process.env[CLOUD_URL_ENV] ?? DEFAULT_CLOUD_URL;
+    const baseUrl = normalizeCloudBaseUrl(raw);
+    if (baseUrl === undefined) {
+        throw configurationError("url_invalid", "Cloud URL must be an absolute HTTPS base URL with a plain path.");
+    }
+    return { baseUrl, token };
+}
+/**
+ * Wait for this hosted run's completion signal and return its JSON payload.
+ *
+ * ```ts
+ * import { waitForSignal } from "@relayflows/surface/signals";
+ * const done = await waitForSignal("native_done");
+ * ```
+ *
+ * Call it in the authored flow body, not inside an `f.run` command: only the
+ * authored process holds the run-bound read token. The wait has no overall
+ * deadline; pass `signal` (e.g. `AbortSignal.timeout(ms)`) to bound it.
+ */
+export async function waitForSignal(name, options = {}) {
+    const runId = options.runId ?? process.env[HOSTED_RUN_ID_ENV];
+    if (runId === undefined || runId === "") {
+        throw configurationError("run_id_missing", `waitForSignal needs a Cloud run ID: pass { runId }, or call it from a hosted run, where ${HOSTED_RUN_ID_ENV} is set.`);
+    }
+    return holdSignalWait(runId, name, options, { connection: () => hostedConnection(options) });
+}
+//# sourceMappingURL=signals.js.map

package/dist/signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.js","sourceRoot":"","sources":["../src/signals.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/surface",
-  "version": "2.0.53",
+  "version": "2.0.54",
   "description": "TypeScript authoring surface for Relayflows.",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,6 +25,11 @@
       "types": "./dist/triggers/*.d.ts",
       "import": "./dist/triggers/*.js",
       "require": "./dist/triggers/*.js"
+    },
+    "./signals": {
+      "types": "./dist/signals.d.ts",
+      "import": "./dist/signals.js",
+      "require": "./dist/signals.js"
     }
   },
   "files": [

package/src/signals.ts

@@ -0,0 +1,258 @@
+/**
+ * Hosted completion signals: `@relayflows/surface/signals`.
+ *
+ * Hosted Cloud runs materialize only `@relayflows/surface` next to the flow
+ * source, so this module must stay importable on its own: no imports beyond
+ * Node built-ins, and Cloud is reached through the global `fetch`. It is the
+ * single implementation of the held-GET signal wait; `@relayflows/sdk`'s
+ * `waitForCloudSignal` delegates to {@link holdSignalWait}.
+ *
+ * Call {@link waitForSignal} from the authored flow body. The run-bound read
+ * credential lives only in that process; `f.run` children and agents never
+ * receive it.
+ */
+import { setTimeout as delay } from "node:timers/promises";
+
+/** The longest hold Cloud's signal GET accepts, and the default. */
+export const SIGNAL_MAX_WAIT_MS = 25_000;
+/** Cloud's run ID for this hosted run (not the engine's `RELAYFLOW_RUN_ID`). */
+export const HOSTED_RUN_ID_ENV = "RELAYFLOW_V2_CLOUD_RUN_ID";
+/** The run-bound, GET-only `workflow:signals:read` bearer Cloud gives the authored process. */
+export const HOSTED_SIGNAL_READ_TOKEN_ENV = "RELAYFLOW_V2_SIGNAL_READ_TOKEN";
+/** The Cloud application base URL the Flows CLI uses. */
+export const CLOUD_URL_ENV = "FLOWS_CLOUD_URL";
+export const DEFAULT_CLOUD_URL = "https://agentrelay.com/cloud";
+
+const SIGNAL_NAME = /^[A-Za-z0-9_-]{1,80}$/u;
+const RUN_ID = /^[A-Za-z0-9_-]{1,128}$/u;
+const MAX_TIMER_MS = 2_147_483_647;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const FAST_204_MS = 1_000;
+const FAST_204_INITIAL_BACKOFF_MS = 250;
+const FAST_204_MAX_BACKOFF_MS = 5_000;
+
+export type SignalErrorCode =
+  | "configuration"
+  | "invalid_input"
+  | "invalid_response"
+  | "http_error"
+  | "transport_error"
+  | "transient_error";
+
+/** Set only for `configuration`: which local setting is missing or wrong. */
+export type SignalConfigurationReason =
+  | "run_id_missing"
+  | "auth_missing"
+  | "url_invalid"
+  | "timeout_invalid";
+
+export class SignalError extends Error {
+  reason?: SignalConfigurationReason;
+
+  constructor(
+    readonly code: SignalErrorCode,
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message);
+    this.name = "SignalError";
+  }
+}
+
+export interface WaitForSignalOptions {
+  /** Hold per request, 0–25000 ms. Defaults to 25000. */
+  waitMs?: number;
+  /** Cancels the wait; the caller's abort reason is rethrown unchanged. */
+  signal?: AbortSignal;
+  /** Defaults to `process.env.RELAYFLOW_V2_CLOUD_RUN_ID`. */
+  runId?: string;
+  /** Defaults to `process.env.FLOWS_CLOUD_URL`, then https://agentrelay.com/cloud. */
+  apiUrl?: string;
+  /** Defaults to `process.env.RELAYFLOW_V2_SIGNAL_READ_TOKEN`. */
+  token?: string;
+  /** Bounds each held request; must exceed `waitMs`. Defaults to 30000. */
+  requestTimeoutMs?: number;
+}
+
+/** Builds the error a caller sees; lets the SDK keep throwing `CloudFlowError`. */
+export type SignalErrorFactory = (
+  code: Exclude<SignalErrorCode, "configuration">,
+  message: string,
+  status?: number,
+) => Error;
+
+/**
+ * The seams `@relayflows/sdk` supplies to share this implementation. Not part
+ * of the authored-flow surface; use {@link waitForSignal} in a flow.
+ */
+export interface SignalWaitHooks {
+  /** Resolved before every held request so a rotated credential is picked up. */
+  connection(): Promise<{ baseUrl: string; token: string }> | { baseUrl: string; token: string };
+  error?: SignalErrorFactory;
+  /** Abort-aware sleep used for the fast-204 backoff. */
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<unknown>;
+}
+
+const signalError: SignalErrorFactory = (code, message, status) =>
+  new SignalError(code, message, status);
+
+function configurationError(reason: SignalConfigurationReason, message: string): SignalError {
+  const error = new SignalError("configuration", message);
+  error.reason = reason;
+  return error;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Validates both path segments, run ID first, before any request. */
+export function signalPath(runId: unknown, name: unknown, error: SignalErrorFactory = signalError): string {
+  // Defensive path-segment constraint; accepting a new server ID format needs a Surface change.
+  if (typeof runId !== "string" || !RUN_ID.test(runId)) {
+    throw error("invalid_response", "Cloud run ID must contain only letters, digits, underscores, or hyphens.");
+  }
+  if (typeof name !== "string" || !SIGNAL_NAME.test(name)) {
+    throw error("invalid_input", "Signal name must contain only letters, digits, underscores, or hyphens (1–80 characters).");
+  }
+  return `/api/v1/workflows/runs/${runId}/signals/${name}`;
+}
+
+/** Same classification as the SDK's Cloud transport: retryable network faults are transient. */
+function transportError(cause: unknown, error: SignalErrorFactory): Error {
+  const inner = cause instanceof Error ? cause.cause : undefined;
+  const code = isRecord(inner) ? inner.code : undefined;
+  const transient = (cause instanceof Error && cause.name === "TimeoutError")
+    || ["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "ETIMEDOUT",
+      "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT", "UND_ERR_SOCKET"].includes(String(code));
+  return transient
+    ? error("transient_error", "Cloud transport temporarily unavailable.")
+    : error("transport_error", "Cloud transport failed; check TLS and the configured URL (redirects are refused).");
+}
+
+function normalizeCloudBaseUrl(raw: string): string | undefined {
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash
+      || !/^\/[A-Za-z0-9/_-]*$/u.test(url.pathname)) return undefined;
+    return `${url.origin}${url.pathname.replace(/\/+$/u, "")}`;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The shared held-GET loop. A normally held 204 re-arms immediately; a fast
+ * 204 (under one second) backs off 250 ms doubling to a 5 s cap, so a proxy or
+ * broken server cannot turn the wait into a hot loop. The backoff resets after
+ * a normally held 204.
+ *
+ * `@relayflows/sdk` calls this with its own connection resolver and error
+ * class; authored flows should call {@link waitForSignal}.
+ */
+export async function holdSignalWait(
+  runId: unknown,
+  name: unknown,
+  options: Pick<WaitForSignalOptions, "waitMs" | "signal" | "requestTimeoutMs">,
+  hooks: SignalWaitHooks,
+): Promise<unknown> {
+  const error = hooks.error ?? signalError;
+  const sleep = hooks.sleep ?? ((ms: number, signal?: AbortSignal) => delay(ms, undefined, { signal }));
+  const path = signalPath(runId, name, error);
+  const waitMs = options.waitMs ?? SIGNAL_MAX_WAIT_MS;
+  if (!Number.isSafeInteger(waitMs) || waitMs < 0 || waitMs > SIGNAL_MAX_WAIT_MS) {
+    throw error("invalid_input", "Signal waitMs must be an integer from 0 to 25000.");
+  }
+  const requestTimeout = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  if (!Number.isSafeInteger(requestTimeout) || requestTimeout <= waitMs) {
+    throw error("invalid_input", `Signal requestTimeoutMs must exceed ${waitMs / 1000} seconds.`);
+  }
+  let fast204BackoffMs = FAST_204_INITIAL_BACKOFF_MS;
+  for (;;) {
+    options.signal?.throwIfAborted();
+    const { baseUrl, token } = await hooks.connection();
+    const deadline = AbortSignal.timeout(requestTimeout);
+    const requestStartedAt = performance.now();
+    let response: Response;
+    try {
+      response = await fetch(`${baseUrl}${path}?waitMs=${waitMs}`, {
+        method: "GET",
+        headers: { authorization: `Bearer ${token}` },
+        signal: options.signal ? AbortSignal.any([options.signal, deadline]) : deadline,
+        // A redirect must never carry the credential to a different origin.
+        redirect: "error",
+      });
+    } catch (cause) {
+      options.signal?.throwIfAborted();
+      throw transportError(deadline.aborted ? deadline.reason : cause, error);
+    }
+    if (response.status === 204) {
+      if (performance.now() - requestStartedAt < FAST_204_MS) {
+        try {
+          await sleep(fast204BackoffMs, options.signal);
+        } catch (cause) {
+          options.signal?.throwIfAborted();
+          throw cause;
+        }
+        fast204BackoffMs = Math.min(fast204BackoffMs * 2, FAST_204_MAX_BACKOFF_MS);
+      } else {
+        fast204BackoffMs = FAST_204_INITIAL_BACKOFF_MS;
+      }
+      continue;
+    }
+    // Do not echo server response bodies: they may contain credentials or source.
+    if (!response.ok) throw error("http_error", `Cloud signal wait failed with HTTP ${response.status}.`, response.status);
+    let body: unknown;
+    try {
+      body = await response.json();
+    } catch (cause) {
+      options.signal?.throwIfAborted();
+      if (!(cause instanceof SyntaxError)) throw transportError(deadline.aborted ? deadline.reason : cause, error);
+      throw error("invalid_response", "Cloud returned an invalid signal.");
+    }
+    if (!isRecord(body) || !Object.hasOwn(body, "payload") || typeof body.acceptedAt !== "number") {
+      throw error("invalid_response", "Cloud returned an invalid signal.");
+    }
+    return body.payload;
+  }
+}
+
+function hostedConnection(options: WaitForSignalOptions): { baseUrl: string; token: string } {
+  const requestTimeout = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  if (requestTimeout > MAX_TIMER_MS) {
+    throw configurationError("timeout_invalid", "requestTimeoutMs must be a positive 32-bit integer.");
+  }
+  const rawToken = options.token ?? process.env[HOSTED_SIGNAL_READ_TOKEN_ENV];
+  const token = rawToken?.trim();
+  if (!token || /[\r\n]/u.test(rawToken!) || /^(?:rk|ot)_live_/u.test(token)) {
+    throw configurationError("auth_missing",
+      `waitForSignal needs a Cloud signal-read token: pass { token }, or call it from a hosted run's authored body, where ${HOSTED_SIGNAL_READ_TOKEN_ENV} is set.`);
+  }
+  const raw = options.apiUrl ?? process.env[CLOUD_URL_ENV] ?? DEFAULT_CLOUD_URL;
+  const baseUrl = normalizeCloudBaseUrl(raw);
+  if (baseUrl === undefined) {
+    throw configurationError("url_invalid", "Cloud URL must be an absolute HTTPS base URL with a plain path.");
+  }
+  return { baseUrl, token };
+}
+
+/**
+ * Wait for this hosted run's completion signal and return its JSON payload.
+ *
+ * ```ts
+ * import { waitForSignal } from "@relayflows/surface/signals";
+ * const done = await waitForSignal("native_done");
+ * ```
+ *
+ * Call it in the authored flow body, not inside an `f.run` command: only the
+ * authored process holds the run-bound read token. The wait has no overall
+ * deadline; pass `signal` (e.g. `AbortSignal.timeout(ms)`) to bound it.
+ */
+export async function waitForSignal(name: string, options: WaitForSignalOptions = {}): Promise<unknown> {
+  const runId = options.runId ?? process.env[HOSTED_RUN_ID_ENV];
+  if (runId === undefined || runId === "") {
+    throw configurationError("run_id_missing",
+      `waitForSignal needs a Cloud run ID: pass { runId }, or call it from a hosted run, where ${HOSTED_RUN_ID_ENV} is set.`);
+  }
+  return holdSignalWait(runId, name, options, { connection: () => hostedConnection(options) });
+}