@relayflows/sdk 2.0.42 → 2.0.44

package/src/cloud-answer.ts

@@ -0,0 +1,202 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { CloudFlowError, cloudFetch, cloudRunId, isCloudRecord, type CloudConnectionOptions } from './cloud-http.js';
+import { cloudRunState } from './cloud-run-record.js';
+import { readCloudHumanWaitValue } from './cloud-human-wait.js';
+import { readSurfaceAuthority, type SurfaceModuleAuthority } from './authored-flow-loader.js';
+import type { CloudAuthoredAuthority } from './cloud-run.js';
+
+export interface CloudAnswerOptions extends CloudConnectionOptions {
+  note?: string;
+  /** Exact original source, including a copy pulled with flows sync. Never executed locally. */
+  source?: string;
+}
+
+export interface CloudResumeReceipt {
+  runId: string;
+  resumedFrom: string;
+  waitId: string;
+  answer: boolean;
+  resumedByCloud: boolean;
+}
+
+/** Preserves partial success without claiming a failed/ambiguous resume did not start. */
+export class CloudAnswerError extends Error {
+  constructor(readonly answerRecorded: boolean, readonly cause: unknown) {
+    super(answerRecorded
+      ? 'The answer is recorded, but resume could not be confirmed. Inspect Cloud status before re-running the same answer command; admission may be unknown.'
+      : 'The answer request could not be confirmed. Inspect Cloud status before retrying.');
+  }
+}
+
+const route = (runId: string): string => `/api/v1/workflows/runs/${runId}`;
+const get = (path: string, options: CloudConnectionOptions): Promise<unknown> =>
+  cloudFetch(path, options, { method: 'GET', detail: true });
+const post = (path: string, body: unknown, options: CloudConnectionOptions): Promise<unknown> =>
+  cloudFetch(path, options, { method: 'POST', body: JSON.stringify(body), detail: true });
+
+/**
+ * Accepted answer route shapes are explicit: humanWait (or wait), or openWaits,
+ * and an optional recorded answer { waitId, answer, note? }. Unknown/ambiguous
+ * shapes refuse before writes. A closed wait is retryable only with that proof.
+ */
+export async function readCloudHumanWait(runId: string, options: CloudConnectionOptions = {}) {
+  cloudRunId(runId);
+  const body = await get(`${route(runId)}/answer`, options);
+  if (!isCloudRecord(body)) throw new CloudFlowError('invalid_response', 'Cloud returned no human answer record.');
+  if (body.runId !== undefined && body.runId !== runId) {
+    throw new CloudFlowError('invalid_response', 'Cloud returned a human answer record for a different run.');
+  }
+  // An absent and a null field mean the same thing everywhere below.
+  const present = (key: string): boolean => body[key] !== undefined && body[key] !== null;
+  if (['humanWait', 'wait', 'openWaits'].filter(present).length > 1) {
+    throw new CloudFlowError('invalid_response', 'Cloud returned competing open human wait fields.');
+  }
+  const candidates = present('openWaits') ? body.openWaits
+    : [body.humanWait ?? body.wait].filter(value => value !== undefined && value !== null);
+  if (!Array.isArray(candidates) || candidates.length > 1) {
+    throw new CloudFlowError('invalid_response', 'Cloud must report at most one open human wait.');
+  }
+  const wait = readCloudHumanWaitValue(candidates[0]);
+  if (candidates.length === 1 && !wait) throw new CloudFlowError('invalid_response', 'Cloud returned an invalid open human wait.');
+  const recorded = body.answer;
+  if (recorded !== undefined && recorded !== null
+    && (!isCloudRecord(recorded) || !readCloudHumanWaitValue(recorded) || typeof recorded.answer !== 'boolean'
+      || (recorded.note !== undefined && recorded.note !== null && typeof recorded.note !== 'string'))) {
+    throw new CloudFlowError('invalid_response', 'Cloud returned an invalid recorded human answer.');
+  }
+  return { wait, recorded: isCloudRecord(recorded)
+    // Like the wait fields, a null note means absent.
+    ? { waitId: recorded.waitId as string, answer: recorded.answer as boolean,
+      note: typeof recorded.note === 'string' ? recorded.note : undefined }
+    : undefined };
+}
+
+const HEX64 = /^[a-f0-9]{64}$/u;
+
+function isSurfaceAuthority(value: unknown): value is SurfaceModuleAuthority {
+  return isCloudRecord(value) && value.packageName === '@relayflows/surface'
+    && typeof value.version === 'string' && value.version.length > 0
+    && typeof value.packageSha256 === 'string' && HEX64.test(value.packageSha256)
+    && typeof value.runtimeSha256 === 'string' && HEX64.test(value.runtimeSha256);
+}
+
+/**
+ * The admitted Surface identity. A complete stored identity is reused as-is;
+ * otherwise it is re-derived by hashing the Surface installed beside --source
+ * (never importing either), and must match the stored version.
+ */
+async function resumeSurface(stored: unknown, source?: string): Promise<SurfaceModuleAuthority> {
+  if (isSurfaceAuthority(stored)) {
+    const { packageName, version, packageSha256, runtimeSha256 } = stored;
+    return Object.freeze({ packageName, version, packageSha256, runtimeSha256 });
+  }
+  const version = isCloudRecord(stored) && typeof stored.version === 'string' && stored.version.length > 0
+    ? stored.version : undefined;
+  if (version === undefined) {
+    throw new CloudFlowError('unsupported_source', 'Cloud run lacks its Surface version; cannot rebuild the submission authority.');
+  }
+  if (source === undefined) {
+    throw new CloudFlowError('unsupported_source', `Cloud stores only the Surface version (${version}); supply --source <path> where @relayflows/surface ${version} is installed.`);
+  }
+  let local: SurfaceModuleAuthority;
+  try { local = await readSurfaceAuthority(source); }
+  catch { throw new CloudFlowError('unsupported_source', `Cannot resolve @relayflows/surface from --source; install @relayflows/surface ${version} beside it.`); }
+  if (local.version !== version) {
+    throw new CloudFlowError('unsupported_source', `The run was admitted with @relayflows/surface ${version}, but --source resolves ${local.version}.`);
+  }
+  return local;
+}
+
+/** Build from admitted bytes and authority, never re-import hosted code or resend inputs. */
+async function resumeBody(record: Record<string, unknown>, runId: string, source?: string) {
+  // A resume without the original tree/plugins is a different execution. Until
+  // Cloud exposes a complete restorable contract, refuse their presence.
+  if (['s3CodeKey', 'codeKey', 'syncCode', 'synced'].some(key => record[key] !== undefined && record[key] !== null && record[key] !== false)) {
+    throw new CloudFlowError('unsupported_source', 'Cannot resume a run with synced code: Cloud must restore its original working tree.');
+  }
+  const authority = record.relayflowV2Authority;
+  if (!isCloudRecord(authority) || !isCloudRecord(authority.source)
+    || typeof authority.source.sha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(authority.source.sha256)) {
+    throw new CloudFlowError('unsupported_source', 'Cloud run lacks source.sha256 authority; cannot verify --source bytes.');
+  }
+  for (const value of [record.extensions, authority.extensions]) {
+    if (value !== undefined && value !== null && !(Array.isArray(value) && value.length === 0)) {
+      throw new CloudFlowError('unsupported_source', 'Cannot resume a run with extensions: Cloud must expose their original submissions.');
+    }
+  }
+  let workflow = record.workflow;
+  if (source !== undefined) {
+    try { workflow = await readFile(source, 'utf8'); }
+    catch { throw new CloudFlowError('invalid_input', 'Cannot read --source; supply the original flow file.'); }
+  }
+  if (typeof workflow !== 'string' || createHash('sha256').update(workflow).digest('hex') !== authority.source.sha256) {
+    throw new CloudFlowError('unsupported_source', `Supply --source <path> with the original flow bytes (sha256 ${authority.source.sha256}); stored source is missing, truncated or different.`);
+  }
+  if (record.workspaceId !== undefined && record.workspaceId !== null && typeof record.workspaceId !== 'string') {
+    throw new CloudFlowError('invalid_response', 'Cloud returned an invalid workspaceId.');
+  }
+  // The run route takes the submission contract, not the stored attestation.
+  const authoredAuthority: CloudAuthoredAuthority = Object.freeze({
+    schemaVersion: 1,
+    sourceSha256: authority.source.sha256,
+    byteLength: Buffer.byteLength(workflow, 'utf8'),
+    surface: await resumeSurface(authority.source.surface, source),
+  });
+  return { workflow, authoredAuthority, fileType: 'ts', relayflowVersion: 'v2', resume: runId,
+    ...(typeof record.workspaceId === 'string' ? { workspaceId: record.workspaceId } : {}) };
+}
+
+/** Record a decision and resume only if Cloud still reports the original park. No POST retries. */
+export async function answerCloudFlow(runId: string, answer: boolean, options: CloudAnswerOptions = {}): Promise<CloudResumeReceipt> {
+  cloudRunId(runId);
+  const record = await get(route(runId), options);
+  const state = cloudRunState(record, runId);
+  if (state.status !== 'needs_human') throw new CloudFlowError('invalid_input', 'Run is not parked on needs_human; no answer or resume was submitted.');
+  const { wait, recorded: lastRecorded } = await readCloudHumanWait(runId, options);
+  const waitId = wait?.waitId ?? lastRecorded?.waitId;
+  // A decision recorded for an earlier gate says nothing about the open one.
+  const recorded = lastRecorded?.waitId === waitId ? lastRecorded : undefined;
+  if (!waitId || (state.humanWait && state.humanWait.waitId !== waitId)) {
+    throw new CloudFlowError('invalid_response', 'Cloud answer record does not identify the run’s parked wait.');
+  }
+  // A recorded answer that omits its optional note does not contradict --note.
+  if (recorded && (recorded.answer !== answer
+    || (recorded.note !== undefined && recorded.note !== options.note))) {
+    throw new CloudFlowError('invalid_input', 'The recorded answer differs; a closed human wait cannot be changed.');
+  }
+  const body = await resumeBody(record as Record<string, unknown>, runId, options.source);
+  let answerRecorded = recorded !== undefined;
+  try {
+    if (!answerRecorded) {
+      const accepted = await post(`${route(runId)}/answer`, { waitId, answer, ...(options.note === undefined ? {} : { note: options.note }) }, options);
+      // Only an explicit acknowledgement counts; {} or { ok: null } is not a recorded decision.
+      if (!isCloudRecord(accepted) || accepted.ok !== true || accepted.error !== undefined) {
+        throw new CloudFlowError('invalid_response', 'Cloud did not confirm the human answer.');
+      }
+      answerRecorded = true;
+    }
+    const current = cloudRunState(await get(route(runId), options), runId);
+    if (current.status !== 'needs_human') {
+      // The contract is that execution continued, not that it succeeded:
+      // failed (step_failed/budget_exceeded) ran steps after the park. Only a
+      // cancellation leaves the park without any execution.
+      if (current.status === 'cancelled') {
+        throw new CloudFlowError('invalid_response', 'Run was cancelled after the answer; it was not resumed.');
+      }
+      return { runId, resumedFrom: runId, waitId, answer, resumedByCloud: true };
+    }
+    // Parked on a later gate: Cloud already resumed past this one. Never
+    // resume (or retry this decision) against the new wait.
+    if (current.humanWait && current.humanWait.waitId !== waitId) {
+      return { runId, resumedFrom: runId, waitId, answer, resumedByCloud: true };
+    }
+    const receipt = await post('/api/v1/workflows/run', body, options);
+    if (!isCloudRecord(receipt) || !['pending', 'running'].includes(String(receipt.status))) {
+      throw new CloudFlowError('invalid_response', 'Cloud did not return an accepted resume.');
+    }
+    return { runId: cloudRunId(receipt.runId), resumedFrom: runId, waitId, answer, resumedByCloud: false };
+  } catch (error) {
+    throw new CloudAnswerError(answerRecorded, error);
+  }
+}

package/src/cloud-auth-store.ts

@@ -0,0 +1,185 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+// @agent-relay/cloud@12.4.1: types.js AUTH_FILE_PATH / DEFAULT_REFRESH_TIMEOUT_MS;
+// auth.js writeStoredAuth, AUTH_LOCK_*, requestStoredAuthRefresh. Keep together
+// for contract updates. flows additionally honours AGENT_RELAY_HOME on writes.
+const AUTH_DIRECTORY = '.agentworkforce/relay';
+const AUTH_FILE = 'cloud-auth.json';
+const DIRECTORY_MODE = 0o700;
+const FILE_MODE = 0o600;
+const LOCK_RETRY_MS = 50;
+// Interop constant: changing this can steal a live relay lock or delay recovery.
+const LOCK_STALE_MS = 30_000;
+const REFRESH_TIMEOUT_MS = 10_000;
+const REFRESH_ROUTE = '/api/v1/auth/token/refresh';
+// Deliberately shorter than relay's 30s acquire timeout for interactive reads.
+const LOCK_ACQUIRE_MS = 5_000;
+
+export interface AgentRelayCloudLogin extends Record<string, unknown> {
+  apiUrl: string;
+  accessToken: string;
+  accessTokenExpiresAt?: string;
+  refreshToken?: string;
+  refreshTokenExpiresAt?: string;
+}
+
+export function agentRelayCloudAuthPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(env['AGENT_RELAY_HOME'] ?? join(homedir(), AUTH_DIRECTORY), AUTH_FILE);
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Explicit credentials bypass this store; expired fallback logins may be refreshed. */
+export function readAgentRelayCloudLogin(
+  env: NodeJS.ProcessEnv = process.env,
+  read: (path: string) => string = path => readFileSync(path, 'utf8'),
+): AgentRelayCloudLogin | undefined {
+  try {
+    const parsed: unknown = JSON.parse(read(agentRelayCloudAuthPath(env)));
+    if (!record(parsed) || typeof parsed.apiUrl !== 'string' || typeof parsed.accessToken !== 'string'
+      || !parsed.accessToken.trim()) return undefined;
+    const login = { ...parsed } as AgentRelayCloudLogin;
+    for (const key of ['accessTokenExpiresAt', 'refreshToken', 'refreshTokenExpiresAt'] as const) {
+      if (typeof parsed[key] !== 'string') delete login[key];
+    }
+    return login;
+  } catch { return undefined; }
+}
+
+export function expiredCloudLogin(login: AgentRelayCloudLogin, now = Date.now()): boolean {
+  const expiry = Date.parse(login.accessTokenExpiresAt ?? '');
+  return Number.isFinite(expiry) && expiry <= now;
+}
+
+export function canRefreshCloudLogin(login: AgentRelayCloudLogin, now = Date.now()): boolean {
+  return typeof login.refreshToken === 'string' && !!login.refreshToken.trim()
+    && !(Date.parse(login.refreshTokenExpiresAt ?? '') <= now);
+}
+
+/** Shared transport policy; undefined lets the synchronous resolver keep its refusals. */
+export 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; }
+}
+
+export type CloudLoginRefresh =
+  | { kind: 'refreshed' | 'current' }
+  | { kind: 'refused'; status?: number }
+  | { kind: 'blocked' }
+  | { kind: 'transport'; error: unknown }
+  | { kind: 'unwritable'; error: unknown; path: string };
+
+interface RefreshOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  env?: NodeJS.ProcessEnv;
+  now?: () => number;
+  fetch?: typeof globalThis.fetch;
+  refreshTimeoutMs?: number;
+  lock?: { retryMs?: number; staleMs?: number; acquireTimeoutMs?: number };
+}
+
+async function writeLogin(path: string, login: AgentRelayCloudLogin): Promise<void> {
+  await fs.mkdir(dirname(path), { recursive: true, mode: DIRECTORY_MODE });
+  const temporaryPath = join(dirname(path), `.${basename(path)}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`);
+  try {
+    await fs.writeFile(temporaryPath, `${JSON.stringify(login, null, 2)}\n`, { encoding: 'utf8', mode: FILE_MODE });
+    await fs.chmod(temporaryPath, FILE_MODE);
+    await fs.rename(temporaryPath, path);
+  } finally {
+    await fs.rm(temporaryPath, { force: true });
+  }
+}
+
+async function requestRefresh(login: AgentRelayCloudLogin, baseUrl: string, options: RefreshOptions): Promise<{ kind: 'ready'; login: AgentRelayCloudLogin } | CloudLoginRefresh> {
+  const deadline = AbortSignal.timeout(Math.min(options.timeoutMs ?? REFRESH_TIMEOUT_MS,
+    options.refreshTimeoutMs ?? REFRESH_TIMEOUT_MS));
+  try {
+    const response = await (options.fetch ?? globalThis.fetch)(`${baseUrl}${REFRESH_ROUTE}`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ refreshToken: login.refreshToken }), redirect: 'error',
+      signal: options.signal ? AbortSignal.any([options.signal, deadline]) : deadline,
+    });
+    if (!response.ok) return { kind: 'refused', status: response.status };
+    const payload: unknown = await response.json();
+    if (!record(payload) || typeof payload.accessToken !== 'string' || !payload.accessToken.trim()
+      || /[\r\n]/u.test(payload.accessToken) || /^(?:rk|ot)_live_/u.test(payload.accessToken.trim())
+      || typeof payload.refreshToken !== 'string' || !payload.refreshToken.trim()
+      || typeof payload.accessTokenExpiresAt !== 'string'
+      || !(Date.parse(payload.accessTokenExpiresAt) > (options.now ?? Date.now)())) return { kind: 'refused' };
+    const apiUrl = typeof payload.apiUrl === 'string' && payload.apiUrl.trim() ? payload.apiUrl.trim() : login.apiUrl;
+    const refreshTokenExpiresAt = typeof payload.refreshTokenExpiresAt === 'string' && payload.refreshTokenExpiresAt.trim()
+      ? payload.refreshTokenExpiresAt.trim() : login.refreshTokenExpiresAt;
+    if (normalizeCloudBaseUrl(apiUrl) !== baseUrl
+      || (refreshTokenExpiresAt !== undefined && !Number.isFinite(Date.parse(refreshTokenExpiresAt)))) return { kind: 'refused' };
+    return { kind: 'ready', login: { ...login, apiUrl, accessToken: payload.accessToken, refreshToken: payload.refreshToken,
+      accessTokenExpiresAt: payload.accessTokenExpiresAt, refreshTokenExpiresAt } };
+  } catch (error) {
+    options.signal?.throwIfAborted();
+    if (error instanceof SyntaxError && !deadline.aborted) return { kind: 'refused' };
+    return { kind: 'transport', error: deadline.aborted ? deadline.reason : error };
+  }
+}
+
+/** Serialize rotations with relay and re-source credentials after acquiring its lock. */
+export async function refreshCloudLogin(
+  login: AgentRelayCloudLogin, baseUrl: string, options: RefreshOptions = {},
+): Promise<CloudLoginRefresh> {
+  const path = agentRelayCloudAuthPath(options.env);
+  const lockPath = `${path}.lock`;
+  const now = options.now ?? Date.now;
+  const started = now();
+  const waitMs = Math.min(options.timeoutMs ?? LOCK_ACQUIRE_MS, options.lock?.acquireTimeoutMs ?? LOCK_ACQUIRE_MS);
+  let acquired = false;
+  try {
+    options.signal?.throwIfAborted();
+    await fs.mkdir(dirname(path), { recursive: true, mode: DIRECTORY_MODE });
+    while (!acquired) {
+      options.signal?.throwIfAborted();
+      try {
+        await fs.mkdir(lockPath, { mode: DIRECTORY_MODE });
+        acquired = true;
+      } catch (error) {
+        if (!record(error) || error.code !== 'EEXIST') throw error;
+        try {
+          if (now() - (await fs.stat(lockPath)).mtimeMs > (options.lock?.staleMs ?? LOCK_STALE_MS)) {
+            await fs.rm(lockPath, { recursive: true, force: true });
+            continue;
+          }
+        } catch (error) {
+          if (!record(error) || error.code !== 'ENOENT') throw error;
+        }
+        const remaining = waitMs - (now() - started);
+        if (remaining <= 0) return { kind: 'blocked' };
+        await delay(Math.min(options.lock?.retryMs ?? LOCK_RETRY_MS, remaining), undefined, { signal: options.signal });
+      }
+    }
+    const latest = readAgentRelayCloudLogin(options.env);
+    // A replaced/deleted login belongs to the other process; never overwrite it.
+    if (!latest || latest.apiUrl !== login.apiUrl || !expiredCloudLogin(latest, now())) return { kind: 'current' };
+    if (!canRefreshCloudLogin(latest, now())) return { kind: 'current' };
+    const result = await requestRefresh(latest, baseUrl, options);
+    if (result.kind !== 'ready') return result;
+    await writeLogin(path, result.login);
+    return { kind: 'refreshed' };
+  } catch (error) {
+    options.signal?.throwIfAborted();
+    return { kind: 'unwritable', error, path };
+  } finally {
+    // Never let cleanup replace the outcome: a rotation already persisted must
+    // be used, and a cancellation must propagate. A lock left behind ages past
+    // LOCK_STALE_MS and is reclaimed by the next caller, as relay does.
+    if (acquired) await fs.rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
+  }
+}

package/src/cloud-http.ts

@@ -1,6 +1,5 @@
-import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { readAgentRelayCloudLogin, expiredCloudLogin, canRefreshCloudLogin, normalizeCloudBaseUrl, refreshCloudLogin } from './cloud-auth-store.js';
+export { agentRelayCloudAuthPath, readAgentRelayCloudLogin, type AgentRelayCloudLogin } from './cloud-auth-store.js';
 
 export interface CloudConnectionOptions {
   /** Cloud application base URL; defaults to https://agentrelay.com/cloud. */
@@ -33,6 +32,8 @@ export interface CloudRefusal {
 export type CloudConfigurationReason =
   | 'auth_missing'
   | 'auth_expired'
+  | 'auth_store_unwritable'
+  | 'auth_refresh_failed'
   | 'url_invalid'
   | 'url_mismatch'
   | 'timeout_invalid';
@@ -61,50 +62,13 @@ function configurationError(reason: CloudConfigurationReason, message: string):
   return error;
 }
 
-/**
- * The `agent-relay cloud login` credential store. Read only when neither the
- * `token` option nor `FLOWS_CLOUD_TOKEN` is set, so an explicit credential
- * always wins and this file can change shape without breaking a configured
- * caller. Its `apiUrl` becomes the default base URL for the same reason: a
- * login against one deployment must not send its token to another.
- */
-export function agentRelayCloudAuthPath(env: NodeJS.ProcessEnv = process.env): string {
-  return join(env['AGENT_RELAY_HOME'] ?? join(homedir(), '.agentworkforce/relay'), 'cloud-auth.json');
-}
-
-export interface AgentRelayCloudLogin {
-  apiUrl: string;
-  accessToken: string;
-  /** ISO-8601; the store carries it, so an expired login refuses with a real reason. */
-  accessTokenExpiresAt?: string;
-}
-
-export function readAgentRelayCloudLogin(
-  env: NodeJS.ProcessEnv = process.env,
-  read: (path: string) => string = path => readFileSync(path, 'utf8'),
-): AgentRelayCloudLogin | undefined {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(read(agentRelayCloudAuthPath(env)));
-  } catch {
-    return undefined;
-  }
-  if (!isCloudRecord(parsed) || typeof parsed.apiUrl !== 'string' || typeof parsed.accessToken !== 'string'
-    || !parsed.accessToken.trim()) return undefined;
-  return {
-    apiUrl: parsed.apiUrl, accessToken: parsed.accessToken,
-    ...(typeof parsed.accessTokenExpiresAt === 'string' ? { accessTokenExpiresAt: parsed.accessTokenExpiresAt } : {}),
-  };
-}
-
 export function cloudConnection(options: CloudConnectionOptions): { baseUrl: string; token: string } {
-  let rawToken = options.token ?? process.env['FLOWS_CLOUD_TOKEN'];
+  let rawToken = explicitCloudToken(options);
   let loginApiUrl: string | undefined;
   if (rawToken === undefined) {
     const login = readAgentRelayCloudLogin();
     if (login !== undefined) {
-      const expiresAt = login.accessTokenExpiresAt === undefined ? Number.NaN : Date.parse(login.accessTokenExpiresAt);
-      if (Number.isFinite(expiresAt) && expiresAt <= Date.now()) {
+      if (expiredCloudLogin(login)) {
         throw configurationError('auth_expired',
           'The agent-relay cloud login has expired. Run `agent-relay cloud login` again, or set FLOWS_CLOUD_TOKEN.');
       }
@@ -124,11 +88,10 @@ export function cloudConnection(options: CloudConnectionOptions): { baseUrl: str
   } catch {
     throw configurationError('url_invalid', 'FLOWS_CLOUD_URL must be an absolute Cloud application base URL.');
   }
-  if (url.protocol !== 'https:'
-    || url.username || url.password || url.search || url.hash || !/^\/[A-Za-z0-9/_-]*$/u.test(url.pathname)) {
+  const baseUrl = normalizeCloudBaseUrl(url.href);
+  if (baseUrl === undefined) {
     throw configurationError('url_invalid', 'Cloud URL must use HTTPS and a plain base path.');
   }
-  const baseUrl = `${url.origin}${url.pathname.replace(/\/+$/u, '')}`;
   // A login-store token is bound to the deployment that issued it. An explicit
   // URL that names another deployment gets no token at all — set
   // FLOWS_CLOUD_TOKEN for that deployment instead.
@@ -147,6 +110,57 @@ export function cloudConnection(options: CloudConnectionOptions): { baseUrl: str
   return { baseUrl, token };
 }
 
+function explicitCloudToken(options: CloudConnectionOptions): string | undefined {
+  return options.token ?? process.env['FLOWS_CLOUD_TOKEN'];
+}
+
+function requestTimeout(options: CloudConnectionOptions): number {
+  const timeout = options.requestTimeoutMs ?? 30_000;
+  if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 2_147_483_647) {
+    throw configurationError('timeout_invalid', 'requestTimeoutMs must be a positive 32-bit integer.');
+  }
+  return timeout;
+}
+
+async function ensureFreshCloudLogin(options: CloudConnectionOptions): Promise<void> {
+  if (explicitCloudToken(options) !== undefined) return;
+  const login = readAgentRelayCloudLogin();
+  if (!login || !expiredCloudLogin(login) || !canRefreshCloudLogin(login)) return;
+  const baseUrl = normalizeCloudBaseUrl(options.apiUrl ?? process.env['FLOWS_CLOUD_URL'] ?? login.apiUrl);
+  if (baseUrl === undefined || baseUrl !== normalizeCloudBaseUrl(login.apiUrl)) return;
+  const result = await refreshCloudLogin(login, baseUrl, { signal: options.signal, timeoutMs: requestTimeout(options) });
+  switch (result.kind) {
+    case 'current': case 'refreshed': return;
+    case 'blocked': throw new CloudFlowError('transient_error', 'Another process is refreshing the agent-relay cloud login; try again.');
+    case 'transport': throw transportError(result.error);
+    case 'unwritable': {
+      const errno = isCloudRecord(result.error) && typeof result.error.code === 'string' ? result.error.code : 'unknown error';
+      throw configurationError('auth_store_unwritable', `Cannot update the agent-relay cloud login at ${result.path} (${errno}). Check filesystem permissions and available space.`);
+    }
+    case 'refused':
+      if (result.status !== undefined && [400, 401, 403].includes(result.status)) {
+        throw configurationError('auth_expired', 'The agent-relay cloud login has expired. Run `agent-relay cloud login` again, or set FLOWS_CLOUD_TOKEN.');
+      }
+      // Only statuses a poll may retry keep http_error: read CLIs map any other
+      // http_error status (a 404 above all) to a fact about the run, not the login.
+      if (result.status !== undefined && [408, 429, 500, 502, 503, 504].includes(result.status)) {
+        throw new CloudFlowError('http_error', `Cloud login refresh failed with HTTP ${result.status}.`, result.status);
+      }
+      if (result.status !== undefined) {
+        throw configurationError('auth_refresh_failed', `Cloud login refresh failed with HTTP ${result.status}. `
+          + 'Run `agent-relay cloud login` again, or set FLOWS_CLOUD_TOKEN.');
+      }
+      throw new CloudFlowError('invalid_response', 'Cloud returned an unusable login refresh response.');
+  }
+}
+
+/** Re-read after refresh; no cache that could hide a relay-side rotation. */
+export async function resolveCloudConnection(options: CloudConnectionOptions): Promise<{ baseUrl: string; token: string }> {
+  requestTimeout(options);
+  await ensureFreshCloudLogin(options);
+  return cloudConnection(options);
+}
+
 export async function cloudRequest(
   path: string,
   options: CloudConnectionOptions,
@@ -182,11 +196,8 @@ export async function cloudFetch(
   options: CloudConnectionOptions,
   init: CloudFetchInit,
 ): Promise<unknown> {
-  const { baseUrl, token } = cloudConnection(options);
-  const timeout = options.requestTimeoutMs ?? 30_000;
-  if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 2_147_483_647) {
-    throw configurationError('timeout_invalid', 'requestTimeoutMs must be a positive 32-bit integer.');
-  }
+  const timeout = requestTimeout(options);
+  const { baseUrl, token } = await resolveCloudConnection(options);
   const bearer = init.bearerToken ?? token;
   if (/[\r\n]/u.test(bearer) || !bearer.trim()) {
     throw new CloudFlowError('invalid_response', 'Cloud issued an unusable storage credential.');

package/src/cloud-human-wait.ts

@@ -0,0 +1,23 @@
+import { HUMAN_WAIT_ID } from './authored-human.js';
+import { isCloudRecord } from './cloud-http.js';
+import { parseHumanTo, type HumanRecipient } from './human-to.js';
+
+export interface CloudHumanWait {
+  waitId: string;
+  question?: string;
+  to?: string;
+  recipient?: HumanRecipient;
+}
+
+/** Missing display fields do not invalidate an attested park. */
+export function readCloudHumanWaitValue(value: unknown): CloudHumanWait | undefined {
+  if (!isCloudRecord(value) || typeof value.waitId !== 'string' || !HUMAN_WAIT_ID.test(value.waitId)) return undefined;
+  const to = typeof value.to === 'string' ? value.to : undefined;
+  const parsed = to === undefined ? undefined : parseHumanTo(to);
+  return {
+    waitId: value.waitId,
+    ...(typeof value.question === 'string' ? { question: value.question } : {}),
+    ...(to === undefined ? {} : { to }),
+    ...(parsed?.ok ? { recipient: parsed.recipient } : {}),
+  };
+}

package/src/cloud-mirror-transport.ts

@@ -113,6 +113,7 @@ export async function registerLocalRun(
     || typeof callbackToken !== 'string' || callbackToken.length === 0) {
     throw new CloudFlowError('invalid_response', 'Cloud registered the run without a usable credential.');
   }
+  // Registration above already refreshed the store through cloudFetch.
   const { baseUrl } = cloudConnection(options);
   const runUrl = typeof result['runUrl'] === 'string' && /^https:\/\//u.test(result['runUrl'])
     ? result['runUrl']

package/src/cloud-run-record.ts

@@ -1,6 +1,6 @@
 // What a Cloud run record has to say before this client will act on it.
 //
-// One validator, two callers. `waitForCloudFlowRun` (cloud-run.ts) blocks on
+// One validator for hosted observation and answer/resume. `waitForCloudFlowRun` (cloud-run.ts) blocks on
 // it to decide when a hosted `flows run --wait` is over, and the live read
 // verbs (cli/cloud-live.ts, through `getCloudRunDetailLive`) block on it to
 // decide when `--watch` and `--follow` stop and with which exit code. Both
@@ -13,11 +13,13 @@
 // `completed` header with no valid `completionReason` attests nothing, and
 // must not become exit 0.
 
+import { readCloudHumanWaitValue, type CloudHumanWait } from './cloud-human-wait.js';
 import { RUN_COMPLETION_REASONS } from '@relayflows/surface';
 import { CloudFlowError, isCloudRecord } from './cloud-http.js';
 import type { RunCompletionReason } from './protocol.js';
 
 export type CloudRunState =
+  | { runId: string; status: 'needs_human'; completionReason: 'needs_human'; humanWait?: CloudHumanWait }
   | { runId: string; status: 'pending' | 'launching' | 'running' }
   | { runId: string; status: 'completed' | 'failed' | 'cancelled'; completionReason: RunCompletionReason };
 
@@ -29,8 +31,7 @@ const ACTIVE_RUN_STATUSES: readonly string[] = ['pending', 'launching', 'running
  *
  * The one vocabulary for the question, so `run --cloud --wait`,
  * `status --cloud --watch` and `logs --follow` cannot disagree about what
- * `launching` means. Note this is about the *run*: a `needs_human` step is
- * not a run status and never reaches here.
+ * `launching` means. A normalized `needs_human` run is terminal for now.
  */
 export function isCloudRunActive(status: string): boolean {
   return ACTIVE_RUN_STATUSES.includes(status);
@@ -49,11 +50,19 @@ export function cloudRunState(body: unknown, runId: string): CloudRunState {
     || !['pending', 'launching', 'running', 'completed', 'failed', 'cancelled'].includes(body.status)) {
     throw new CloudFlowError('invalid_response', 'Cloud returned an invalid v2 run record.');
   }
+  const report = body.result;
+  const reason = isCloudRecord(report) ? report.completionReason : undefined;
+  if (reason === 'needs_human') {
+    if (body.status !== 'failed') {
+      throw new CloudFlowError('invalid_response', `Cloud reports needs_human under status ${body.status}; expected failed.`);
+    }
+    const humanWait = readCloudHumanWaitValue(isCloudRecord(report) ? report.humanWait : undefined)
+      ?? readCloudHumanWaitValue(body.humanWait);
+    return { runId, status: 'needs_human', completionReason: 'needs_human', ...(humanWait ? { humanWait } : {}) };
+  }
   if (isCloudRunActive(body.status)) {
     return { runId, status: body.status as 'pending' | 'launching' | 'running' };
   }
-  const report = body.result;
-  const reason = isCloudRecord(report) ? report.completionReason : undefined;
   if (typeof reason !== 'string' || !(RUN_COMPLETION_REASONS as readonly string[]).includes(reason)
     || (body.status === 'completed' && (reason !== 'success' || !isCloudRecord(report) || report.ok !== true || report.status !== 'completed'))
     || (body.status === 'failed' && !['step_failed', 'budget_exceeded'].includes(reason))