@relayflows/sdk 2.0.15 → 2.0.17

package/src/cloud-deploy.ts

@@ -0,0 +1,247 @@
+import { randomBytes, createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { loadAuthoredFlow } from './authored-flow-loader.js';
+import {
+  CloudFlowError, cloudFetch, cloudRequest, isCloudRecord, type CloudConnectionOptions,
+} from './cloud-http.js';
+
+/**
+ * Hosted listener deployment: the CLI form of the agentrelay.com onboarding's
+ * deploy wizard. `POST /api/v1/flows/deploy` stores one self-contained
+ * authored source and creates a proactive listener whose watch rules match
+ * the chosen ticket sources on the workspace's relayfile projections. There
+ * is no webhook to register: the GitHub App installation (or Slack/Linear/
+ * Jira/Shortcut connection) is the ingress, and each matching ticket launches
+ * a run of the stored source with `{ approver, issue, event }` as its input,
+ * inside a fresh branch of the deployment's repository.
+ */
+
+export const FLOW_TRIGGER_PROVIDERS = ['github', 'linear', 'jira', 'shortcut', 'slack'] as const;
+export type FlowTriggerProvider = (typeof FLOW_TRIGGER_PROVIDERS)[number];
+
+/** Settings Cloud's launcher prefilter reads per provider (`flow-trigger-sources.ts`). */
+const PROVIDER_SETTINGS: Record<FlowTriggerProvider, readonly string[]> = {
+  // `events`: `issues` (default) or `pull_request` — which GitHub records
+  // wake the listener (AgentWorkforce/cloud#3772).
+  github: ['repository', 'labels', 'contains', 'events'],
+  slack: ['channel', 'contains'],
+  linear: ['team', 'contains'],
+  jira: ['project', 'contains'],
+  shortcut: ['workspace', 'contains'],
+};
+const MAX_SOURCE_BYTES = 256_000;
+const MAX_SETTING_LENGTH = 500;
+const REPO_OWNER = /^[A-Za-z0-9-]{1,39}$/u;
+const REPO_NAME = /^[A-Za-z0-9_.-]{1,100}$/u;
+
+export interface FlowTriggerSource {
+  provider: FlowTriggerProvider;
+  settings: Record<string, string>;
+}
+
+export interface DeployToCloudInput {
+  path: string;
+  repository: { owner: string; name: string };
+  sources: FlowTriggerSource[];
+  /** The `f.human` approver handle every launched run receives as `input.approver`. */
+  approver: string;
+  /** Defaults to the flow's declared name. */
+  name?: string;
+  /** Coding-agent harnesses the flow uses; Cloud checks their credentials are connected. Default `["claude"]`. */
+  agents?: FlowAgentHarness[];
+  /** Save without activating: no connection checks, no listener until activated. */
+  draft?: boolean;
+}
+
+export const FLOW_AGENT_HARNESSES = ['claude', 'codex'] as const;
+export type FlowAgentHarness = (typeof FLOW_AGENT_HARNESSES)[number];
+
+export function parseAgentHarnesses(value: string): FlowAgentHarness[] {
+  const agents = value.split(',').map(a => a.trim()).filter(Boolean);
+  if (agents.length === 0 || agents.length > 2 || new Set(agents).size !== agents.length
+    || !agents.every(a => (FLOW_AGENT_HARNESSES as readonly string[]).includes(a))) {
+    throw new CloudFlowError('invalid_input', `--agents takes one or two of ${FLOW_AGENT_HARNESSES.join(', ')}, got "${value}".`);
+  }
+  return agents as FlowAgentHarness[];
+}
+
+export interface CloudDeployment {
+  agentId: string;
+  name: string;
+  status: string;
+  repository: { owner: string; name: string };
+  sources: FlowTriggerSource[];
+  sourceSha256: string;
+}
+
+export function parseRepository(value: string): { owner: string; name: string } {
+  const [owner, name, extra] = value.replace(/^https?:\/\/github\.com\//iu, '').replace(/\.git$/iu, '').split('/');
+  if (!owner || !name || extra !== undefined || !REPO_OWNER.test(owner) || !REPO_NAME.test(name)) {
+    throw new CloudFlowError('invalid_input', `Expected --repo <owner>/<name>, got "${value}".`);
+  }
+  return { owner, name };
+}
+
+/** `github`, `github:labels=agent,contains=urgent`, `slack:channel=#eng`. */
+export function parseTriggerSource(value: string): FlowTriggerSource {
+  const colon = value.indexOf(':');
+  const provider = (colon === -1 ? value : value.slice(0, colon)).trim();
+  if (!(FLOW_TRIGGER_PROVIDERS as readonly string[]).includes(provider)) {
+    throw new CloudFlowError('invalid_input',
+      `Unknown trigger provider "${provider}"; expected one of ${FLOW_TRIGGER_PROVIDERS.join(', ')}.`);
+  }
+  const allowed = PROVIDER_SETTINGS[provider as FlowTriggerProvider];
+  const settings: Record<string, string> = {};
+  if (colon !== -1) {
+    for (const pair of value.slice(colon + 1).split(',')) {
+      const eq = pair.indexOf('=');
+      const key = (eq === -1 ? pair : pair.slice(0, eq)).trim();
+      const setting = eq === -1 ? '' : pair.slice(eq + 1).trim();
+      if (!allowed.includes(key)) {
+        throw new CloudFlowError('invalid_input',
+          `"${key}" is not a ${provider} trigger setting; ${provider} accepts ${allowed.join(', ')}.`);
+      }
+      if (!setting || setting.length > MAX_SETTING_LENGTH || key in settings) {
+        throw new CloudFlowError('invalid_input', `Trigger setting "${key}" must be given once with a non-empty value.`);
+      }
+      if (key === 'events') {
+        // Cloud's enum is lowercase; send it that way whatever the shell typed.
+        const events = setting.toLowerCase();
+        if (!['issues', 'pull_request'].includes(events)) {
+          throw new CloudFlowError('invalid_input', `github events must be "issues" or "pull_request", got "${setting}".`);
+        }
+        settings[key] = events;
+        continue;
+      }
+      settings[key] = setting;
+    }
+  }
+  return { provider: provider as FlowTriggerProvider, settings };
+}
+
+export async function deployToCloud(
+  input: DeployToCloudInput, options: CloudConnectionOptions = {},
+): Promise<CloudDeployment> {
+  if (!/\.flow\.ts$/iu.test(input.path)) {
+    throw new CloudFlowError('unsupported_source', 'flows deploy takes one authored .flow.ts source.');
+  }
+  let bytes: Buffer;
+  try {
+    bytes = await readFile(input.path);
+  } catch (error) {
+    throw new CloudFlowError('invalid_input',
+      `Cannot read ${input.path}: ${(error as NodeJS.ErrnoException).code ?? (error as Error).message}.`);
+  }
+  const source = bytes.toString('utf8');
+  if (!bytes.length || Buffer.from(source, 'utf8').compare(bytes) !== 0) {
+    throw new CloudFlowError('invalid_input', 'Authored source must be nonempty, lossless UTF-8.');
+  }
+  if (bytes.length > MAX_SOURCE_BYTES) {
+    throw new CloudFlowError('invalid_input', `Authored source exceeds Cloud's ${MAX_SOURCE_BYTES}-byte deploy limit.`);
+  }
+  let loaded: Awaited<ReturnType<typeof loadAuthoredFlow>>;
+  let definition: ReturnType<typeof loaded.getDefinition>;
+  try {
+    loaded = await loadAuthoredFlow(input.path);
+    definition = loaded.getDefinition(loaded.handle);
+  } catch (error) {
+    if (error instanceof CloudFlowError) throw error;
+    // A source that does not load is an authoring problem, refused before HTTP.
+    throw new CloudFlowError('unsupported_source',
+      `${input.path} is not a loadable authored flow: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (loaded.graph.length !== 1) {
+    throw new CloudFlowError('unsupported_source',
+      'Cloud deploys one self-contained .flow.ts source without use dependencies.');
+  }
+  if (input.sources.length === 0 || input.sources.length > 10) {
+    throw new CloudFlowError('invalid_input', 'Give between one and ten --on trigger sources.');
+  }
+  if (new Set(input.sources.map(s => s.provider)).size !== input.sources.length) {
+    throw new CloudFlowError('invalid_input', 'Each trigger provider can be given once.');
+  }
+  const approver = input.approver.trim();
+  if (!approver) throw new CloudFlowError('invalid_input', '--approver must name who approves f.human questions.');
+  const name = (input.name ?? definition.name).trim();
+  if (!name || name.length > 100) throw new CloudFlowError('invalid_input', 'Deployment name must be 1-100 characters.');
+  // A GitHub source scoped to nothing would wake on every repository the
+  // installation covers; default it to the deployment's own repository.
+  const sources = input.sources.map(s => s.provider === 'github' && s.settings['repository'] === undefined
+    ? { ...s, settings: { ...s.settings, repository: `${input.repository.owner}/${input.repository.name}` } }
+    : s);
+  options.signal?.throwIfAborted();
+
+  const whoami = await cloudRequest('/api/v1/auth/whoami', options);
+  const workspace = isCloudRecord(whoami) && isCloudRecord(whoami.currentWorkspace) ? whoami.currentWorkspace : undefined;
+  if (workspace === undefined || typeof workspace.id !== 'string' || !workspace.id) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not report a current workspace for this credential.');
+  }
+  const agents = input.agents ?? ['claude'];
+  const result = await cloudFetch('/api/v1/flows/deploy', options, { method: 'POST', detail: true, body: JSON.stringify({
+    workspaceId: workspace.id,
+    mode: input.draft ? 'draft' : 'activate',
+    name,
+    // The onboarding's workflow-shape label; the CLI deploys authored source as-is.
+    workflow: 'flows-cli',
+    source,
+    handoffId: `flows-cli-${randomBytes(8).toString('hex')}`,
+    inputs: { approver, agents },
+    repository: input.repository,
+    sources,
+  }) });
+  if (!isCloudRecord(result) || typeof result.agentId !== 'string' || typeof result.status !== 'string') {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return a deployment.');
+  }
+  return {
+    agentId: result.agentId, name, status: result.status,
+    repository: input.repository, sources,
+    sourceSha256: createHash('sha256').update(bytes).digest('hex'),
+  };
+}
+
+export interface CloudDeploymentSummary {
+  agentId: string;
+  name: string;
+  status: string;
+  repository?: { owner: string; name: string };
+  sources: FlowTriggerSource[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export async function listCloudDeployments(options: CloudConnectionOptions = {}): Promise<CloudDeploymentSummary[]> {
+  const payload = await cloudRequest('/api/v1/agents/flow-deployments', options);
+  if (!isCloudRecord(payload) || !Array.isArray(payload.deployments)) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return a deployments list.');
+  }
+  return payload.deployments.map((row): CloudDeploymentSummary => {
+    if (!isCloudRecord(row) || typeof row.agentId !== 'string' || typeof row.name !== 'string') {
+      throw new CloudFlowError('invalid_response', 'Cloud returned a malformed deployment row.');
+    }
+    const repository = isCloudRecord(row.repository) && typeof row.repository.owner === 'string'
+      && typeof row.repository.name === 'string' ? { owner: row.repository.owner, name: row.repository.name } : undefined;
+    const sources = Array.isArray(row.sources) ? row.sources.flatMap((s): FlowTriggerSource[] =>
+      isCloudRecord(s) && typeof s.provider === 'string' && (FLOW_TRIGGER_PROVIDERS as readonly string[]).includes(s.provider)
+        ? [{ provider: s.provider as FlowTriggerProvider,
+            settings: Object.fromEntries(Object.entries(isCloudRecord(s.settings) ? s.settings : {})
+              .flatMap(([k, v]) => typeof v === 'string' ? [[k, v]] : typeof v === 'boolean' ? [[k, String(v)]] : [])) }]
+        : []) : [];
+    return {
+      agentId: row.agentId, name: row.name, status: typeof row.status === 'string' ? row.status : 'unknown',
+      ...(repository === undefined ? {} : { repository }), sources,
+      ...(typeof row.createdAt === 'string' ? { createdAt: row.createdAt } : {}),
+      ...(typeof row.updatedAt === 'string' ? { updatedAt: row.updatedAt } : {}),
+    };
+  });
+}
+
+const LISTENER_ID = /^[A-Za-z0-9_-]{1,128}$/u;
+
+/** `DELETE /api/v1/flows/listeners/<id>`: the listener stops; past runs and their journals stay. */
+export async function undeployFromCloud(agentId: string, options: CloudConnectionOptions = {}): Promise<void> {
+  if (!LISTENER_ID.test(agentId)) throw new CloudFlowError('invalid_input', `"${agentId}" is not a deployment id.`);
+  const result = await cloudFetch(`/api/v1/flows/listeners/${encodeURIComponent(agentId)}`, options, { method: 'DELETE', detail: true });
+  if (!isCloudRecord(result) || result.status !== 'deleted') {
+    throw new CloudFlowError('invalid_response', 'Cloud did not confirm the deletion.');
+  }
+}

package/src/cloud-http.ts

@@ -1,3 +1,7 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
 export interface CloudConnectionOptions {
   /** Cloud application base URL; defaults to https://agentrelay.com/cloud. */
   apiUrl?: string;
@@ -8,27 +12,89 @@ export interface CloudConnectionOptions {
   requestTimeoutMs?: number;
 }
 
+/** A refusal Cloud answered as JSON: only these fields are ever read. */
+export interface CloudRefusal {
+  code: string;
+  error: string;
+  /** Version-only descriptions, when a route names what it wanted vs. got. */
+  expected?: { packageName?: string; version?: string };
+  received?: { packageName?: string; version?: string };
+}
+
 export class CloudFlowError extends Error {
   constructor(
-    readonly code: 'configuration' | 'unsupported_source' | 'invalid_input' | 'invalid_response' | 'http_error' | 'transport_error' | 'transient_error',
+    readonly code: 'configuration' | 'unsupported_source' | 'invalid_input' | 'invalid_response' | 'http_error'
+      | 'transport_error' | 'transient_error' | 'unsupported_storage_backend' | 'sync_too_large' | 'sync_unsupported'
+      | 'patch_conflict',
     message: string,
     readonly status?: number,
+    readonly refusal?: CloudRefusal,
   ) {
     super(message);
     this.name = 'CloudFlowError';
   }
 }
 
+/**
+ * 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 } {
-  const rawToken = options.token ?? process.env['FLOWS_CLOUD_TOKEN'];
+  let rawToken = options.token ?? process.env['FLOWS_CLOUD_TOKEN'];
+  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()) {
+        throw new CloudFlowError('configuration',
+          'The agent-relay cloud login has expired. Run `agent-relay cloud login` again, or set FLOWS_CLOUD_TOKEN.');
+      }
+      rawToken = login.accessToken;
+      loginApiUrl = login.apiUrl;
+    }
+  }
   const token = rawToken?.trim();
   if (!token || /[\r\n]/u.test(rawToken!) || /^(?:rk|ot)_live_/u.test(token)) {
     throw new CloudFlowError('configuration',
-      'Set FLOWS_CLOUD_TOKEN to a scoped Cloud API token (workflow:invoke:write and workflow:runs:read).');
+      'Set FLOWS_CLOUD_TOKEN to a scoped Cloud API token (workflow:invoke:write and workflow:runs:read), '
+      + 'or sign in with `agent-relay cloud login`.');
   }
   let url: URL;
   try {
-    url = new URL(options.apiUrl ?? process.env['FLOWS_CLOUD_URL'] ?? 'https://agentrelay.com/cloud');
+    url = new URL(options.apiUrl ?? process.env['FLOWS_CLOUD_URL'] ?? loginApiUrl ?? 'https://agentrelay.com/cloud');
   } catch {
     throw new CloudFlowError('configuration', 'FLOWS_CLOUD_URL must be an absolute Cloud application base URL.');
   }
@@ -36,26 +102,79 @@ export function cloudConnection(options: CloudConnectionOptions): { baseUrl: str
     || url.username || url.password || url.search || url.hash || !/^\/[A-Za-z0-9/_-]*$/u.test(url.pathname)) {
     throw new CloudFlowError('configuration', 'Cloud URL must use HTTPS and a plain base path.');
   }
-  return { baseUrl: `${url.origin}${url.pathname.replace(/\/+$/u, '')}`, token };
+  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.
+  if (loginApiUrl !== undefined) {
+    let issued: string | undefined;
+    try {
+      const login = new URL(loginApiUrl);
+      issued = `${login.origin}${login.pathname.replace(/\/+$/u, '')}`;
+    } catch { issued = undefined; }
+    if (issued !== baseUrl) {
+      throw new CloudFlowError('configuration',
+        `The agent-relay cloud login was issued for ${loginApiUrl}, not ${baseUrl}. `
+        + 'Set FLOWS_CLOUD_TOKEN for that deployment, or unset FLOWS_CLOUD_URL to use the login.');
+    }
+  }
+  return { baseUrl, token };
 }
 
 export async function cloudRequest(
   path: string,
   options: CloudConnectionOptions,
   body?: unknown,
+): Promise<unknown> {
+  return cloudFetch(path, options, body === undefined
+    ? { method: 'GET' }
+    : { method: 'POST', body: JSON.stringify(body), contentType: 'application/json' });
+}
+
+export interface CloudFetchInit {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: string | Uint8Array;
+  contentType?: string;
+  /**
+   * A run-scoped token issued by Cloud for one upload (the `prepare` receipt's
+   * storage credential). Used instead of the configured token for that request
+   * only; it is never persisted or logged.
+   */
+  bearerToken?: string;
+  /**
+   * On a non-2xx response, read a `{ code, error }` refusal from the body and
+   * name it. Only those two string fields are ever surfaced, so a route that
+   * answers with structured refusals (the deploy routes) can explain itself
+   * without this client echoing arbitrary response bodies.
+   */
+  detail?: boolean;
+}
+
+/** One authenticated Cloud request. Every transport error is typed; no retries. */
+export async function cloudFetch(
+  path: string,
+  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 new CloudFlowError('configuration', 'requestTimeoutMs must be a positive 32-bit integer.');
   }
+  const bearer = init.bearerToken ?? token;
+  if (/[\r\n]/u.test(bearer) || !bearer.trim()) {
+    throw new CloudFlowError('invalid_response', 'Cloud issued an unusable storage credential.');
+  }
   const deadline = AbortSignal.timeout(timeout);
   let response: Response;
   try {
     response = await fetch(`${baseUrl}${path}`, {
-      method: body === undefined ? 'GET' : 'POST',
-      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
-      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      method: init.method,
+      headers: {
+        authorization: `Bearer ${bearer}`,
+        'content-type': init.contentType ?? 'application/json',
+      },
+      ...(init.body === undefined ? {} : { body: typeof init.body === 'string' ? init.body : new Blob([init.body]) }),
       signal: options.signal ? AbortSignal.any([options.signal, deadline]) : deadline,
       // A redirect must never carry the credential to a different origin.
       redirect: 'error',
@@ -66,7 +185,20 @@ export async function cloudRequest(
   }
   if (!response.ok) {
     // Do not echo server response bodies: they may contain credentials or source.
-    throw new CloudFlowError('http_error', `Cloud request failed with HTTP ${response.status}.`, response.status);
+    // Reading the body is itself a transport step: a cancellation or timeout
+    // there keeps its own classification instead of becoming an http_error.
+    let refusal: CloudRefusal | undefined;
+    if (init.detail) {
+      try {
+        refusal = await structuredRefusal(response);
+      } catch (error) {
+        options.signal?.throwIfAborted();
+        throw transportError(deadline.aborted ? deadline.reason : error);
+      }
+    }
+    throw new CloudFlowError('http_error', refusal === undefined
+      ? `Cloud request failed with HTTP ${response.status}.`
+      : `Cloud refused (${refusal.code}): ${refusal.error}`, response.status, refusal);
   }
   try {
     return await response.json();
@@ -77,6 +209,38 @@ export async function cloudRequest(
   }
 }
 
+const REFUSAL_CODE = /^[a-z0-9_]{1,64}$/u;
+
+/**
+ * Routes answer either `{ code, error }` or a bare `{ error: "<code>" }`;
+ * both are read, and an optional `expected`/`received` pair is reduced to
+ * package name and version. Nothing else in the body is looked at.
+ */
+async function structuredRefusal(response: Response): Promise<CloudRefusal | undefined> {
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch (error) {
+    // Only a body that is not JSON is "no structured refusal"; an aborted or
+    // timed-out read is a transport failure and propagates.
+    if (error instanceof SyntaxError) return undefined;
+    throw error;
+  }
+  if (!isCloudRecord(body) || typeof body.error !== 'string' || body.error.length > 500) return undefined;
+  const code = typeof body.code === 'string' ? body.code : body.error;
+  if (!REFUSAL_CODE.test(code)) return undefined;
+  const versionOnly = (value: unknown): CloudRefusal['expected'] => {
+    if (!isCloudRecord(value)) return undefined;
+    const out: { packageName?: string; version?: string } = {};
+    if (typeof value.packageName === 'string' && value.packageName.length <= 100) out.packageName = value.packageName;
+    if (typeof value.version === 'string' && /^[0-9A-Za-z.+-]{1,64}$/u.test(value.version)) out.version = value.version;
+    return out;
+  };
+  const expected = versionOnly(body.expected);
+  const received = versionOnly(body.received);
+  return { code, error: body.error, ...(expected ? { expected } : {}), ...(received ? { received } : {}) };
+}
+
 // Defensive path-segment constraint; accepting a new server ID format needs an SDK change.
 export function cloudRunId(value: unknown): string {
   if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/u.test(value)) {