@relayflows/sdk 2.0.15 → 2.0.17

package/dist/cloud-deploy.js

@@ -0,0 +1,192 @@
+import { randomBytes, createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { loadAuthoredFlow } from './authored-flow-loader.js';
+import { CloudFlowError, cloudFetch, cloudRequest, isCloudRecord, } 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'];
+/** Settings Cloud's launcher prefilter reads per provider (`flow-trigger-sources.ts`). */
+const PROVIDER_SETTINGS = {
+    // `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 const FLOW_AGENT_HARNESSES = ['claude', 'codex'];
+export function parseAgentHarnesses(value) {
+    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.includes(a))) {
+        throw new CloudFlowError('invalid_input', `--agents takes one or two of ${FLOW_AGENT_HARNESSES.join(', ')}, got "${value}".`);
+    }
+    return agents;
+}
+export function parseRepository(value) {
+    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) {
+    const colon = value.indexOf(':');
+    const provider = (colon === -1 ? value : value.slice(0, colon)).trim();
+    if (!FLOW_TRIGGER_PROVIDERS.includes(provider)) {
+        throw new CloudFlowError('invalid_input', `Unknown trigger provider "${provider}"; expected one of ${FLOW_TRIGGER_PROVIDERS.join(', ')}.`);
+    }
+    const allowed = PROVIDER_SETTINGS[provider];
+    const settings = {};
+    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, settings };
+}
+export async function deployToCloud(input, options = {}) {
+    if (!/\.flow\.ts$/iu.test(input.path)) {
+        throw new CloudFlowError('unsupported_source', 'flows deploy takes one authored .flow.ts source.');
+    }
+    let bytes;
+    try {
+        bytes = await readFile(input.path);
+    }
+    catch (error) {
+        throw new CloudFlowError('invalid_input', `Cannot read ${input.path}: ${error.code ?? 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;
+    let definition;
+    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 async function listCloudDeployments(options = {}) {
+    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) => {
+        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) => isCloudRecord(s) && typeof s.provider === 'string' && FLOW_TRIGGER_PROVIDERS.includes(s.provider)
+            ? [{ provider: s.provider,
+                    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, options = {}) {
+    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.');
+    }
+}
+//# sourceMappingURL=cloud-deploy.js.map

package/dist/cloud-deploy.js.map

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

package/dist/cloud-http.d.ts

@@ -7,16 +7,66 @@ export interface CloudConnectionOptions {
     /** Bounds each HTTP request, never the hosted run. Defaults to 30 seconds. */
     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 declare class CloudFlowError extends Error {
-    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';
     readonly status?: number | undefined;
-    constructor(code: 'configuration' | 'unsupported_source' | 'invalid_input' | 'invalid_response' | 'http_error' | 'transport_error' | 'transient_error', message: string, status?: number | undefined);
+    readonly refusal?: CloudRefusal | undefined;
+    constructor(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, status?: number | undefined, refusal?: CloudRefusal | undefined);
+}
+/**
+ * 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 declare function agentRelayCloudAuthPath(env?: NodeJS.ProcessEnv): string;
+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 declare function readAgentRelayCloudLogin(env?: NodeJS.ProcessEnv, read?: (path: string) => string): AgentRelayCloudLogin | undefined;
 export declare function cloudConnection(options: CloudConnectionOptions): {
     baseUrl: string;
     token: string;
 };
 export declare function cloudRequest(path: string, options: CloudConnectionOptions, body?: unknown): Promise<unknown>;
+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 declare function cloudFetch(path: string, options: CloudConnectionOptions, init: CloudFetchInit): Promise<unknown>;
 export declare function cloudRunId(value: unknown): string;
 export declare function isCloudRecord(value: unknown): value is Record<string, unknown>;
 //# sourceMappingURL=cloud-http.d.ts.map

package/dist/cloud-http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloud-http.d.ts","sourceRoot":"","sources":["../src/cloud-http.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,cAAe,SAAQ,KAAK;IAErC,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,oBAAoB,GAAG,eAAe,GAAG,kBAAkB,GAAG,YAAY,GAAG,iBAAiB,GAAG,iBAAiB;IAEnJ,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;gBAFf,IAAI,EAAE,eAAe,GAAG,oBAAoB,GAAG,eAAe,GAAG,kBAAkB,GAAG,YAAY,GAAG,iBAAiB,GAAG,iBAAiB,EACnJ,OAAO,EAAE,MAAM,EACN,MAAM,CAAC,EAAE,MAAM,YAAA;CAK3B;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAkBnG;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,sBAAsB,EAC/B,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,OAAO,CAAC,CAgClB;AAGD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKjD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E"}
+{"version":3,"file":"cloud-http.d.ts","sourceRoot":"","sources":["../src/cloud-http.ts"],"names":[],"mappings":"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"}

package/dist/cloud-http.js

@@ -1,22 +1,66 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 export class CloudFlowError extends Error {
     code;
     status;
-    constructor(code, message, status) {
+    refusal;
+    constructor(code, message, status, refusal) {
         super(message);
         this.code = code;
         this.status = status;
+        this.refusal = refusal;
         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 = process.env) {
+    return join(env['AGENT_RELAY_HOME'] ?? join(homedir(), '.agentworkforce/relay'), 'cloud-auth.json');
+}
+export function readAgentRelayCloudLogin(env = process.env, read = path => readFileSync(path, 'utf8')) {
+    let parsed;
+    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) {
-    const rawToken = options.token ?? process.env['FLOWS_CLOUD_TOKEN'];
+    let rawToken = options.token ?? process.env['FLOWS_CLOUD_TOKEN'];
+    let loginApiUrl;
+    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).');
+        throw new CloudFlowError('configuration', '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;
     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.');
@@ -25,21 +69,52 @@ export function cloudConnection(options) {
         || 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;
+        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, options, body) {
+    return cloudFetch(path, options, body === undefined
+        ? { method: 'GET' }
+        : { method: 'POST', body: JSON.stringify(body), contentType: 'application/json' });
+}
+/** One authenticated Cloud request. Every transport error is typed; no retries. */
+export async function cloudFetch(path, options, init) {
     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;
     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',
@@ -51,7 +126,21 @@ export async function cloudRequest(path, options, body) {
     }
     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;
+        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();
@@ -63,6 +152,43 @@ export async function cloudRequest(path, options, body) {
         throw new CloudFlowError('invalid_response', 'Cloud returned a non-JSON response.');
     }
 }
+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) {
+    let body;
+    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) => {
+        if (!isCloudRecord(value))
+            return undefined;
+        const out = {};
+        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) {
     if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/u.test(value)) {

package/dist/cloud-http.js.map

@@ -1 +1 @@
-{"version":3,"file":"cloud-http.js","sourceRoot":"","sources":["../src/cloud-http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cloud-http.js","sourceRoot":"","sources":["../src/cloud-http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAqBjC,MAAM,OAAO,cAAe,SAAQ,KAAK;IAE5B;IAIA;IACA;IANX,YACW,IAEW,EACpB,OAAe,EACN,MAAe,EACf,OAAsB;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAPN,SAAI,GAAJ,IAAI,CAEO;QAEX,WAAM,GAAN,MAAM,CAAS;QACf,YAAO,GAAP,OAAO,CAAe;QAG/B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC1E,OAAO,IAAI,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,uBAAuB,CAAC,EAAE,iBAAiB,CAAC,CAAC;AACtG,CAAC;AASD,MAAM,UAAU,wBAAwB,CACtC,MAAyB,OAAO,CAAC,GAAG,EACpC,OAAiC,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC;IAEnE,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,WAAW,KAAK,QAAQ;WACpG,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE;QAAE,OAAO,SAAS,CAAC;IAClD,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW;QACtD,GAAG,CAAC,OAAO,MAAM,CAAC,oBAAoB,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,MAAM,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAA+B;IAC7D,IAAI,QAAQ,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACjE,IAAI,WAA+B,CAAC;IACpC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,wBAAwB,EAAE,CAAC;QACzC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,SAAS,GAAG,KAAK,CAAC,oBAAoB,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;YACjH,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;gBAC1D,MAAM,IAAI,cAAc,CAAC,eAAe,EACtC,yGAAyG,CAAC,CAAC;YAC/G,CAAC;YACD,QAAQ,GAAG,KAAK,CAAC,WAAW,CAAC;YAC7B,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC,IAAI,CAAC,QAAS,CAAC,IAAI,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,cAAc,CAAC,eAAe,EACtC,oGAAoG;cAClG,4CAA4C,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,WAAW,IAAI,8BAA8B,CAAC,CAAC;IACnH,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,cAAc,CAAC,eAAe,EAAE,iEAAiE,CAAC,CAAC;IAC/G,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ;WACxB,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1G,MAAM,IAAI,cAAc,CAAC,eAAe,EAAE,iDAAiD,CAAC,CAAC;IAC/F,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC;IACpE,6EAA6E;IAC7E,+DAA+D;IAC/D,iDAAiD;IACjD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,MAA0B,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;YACnC,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC;QACnE,CAAC;QAAC,MAAM,CAAC;YAAC,MAAM,GAAG,SAAS,CAAC;QAAC,CAAC;QAC/B,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,MAAM,IAAI,cAAc,CAAC,eAAe,EACtC,8CAA8C,WAAW,SAAS,OAAO,IAAI;kBAC3E,uFAAuF,CAAC,CAAC;QAC/F,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,OAA+B,EAC/B,IAAc;IAEd,OAAO,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,KAAK,SAAS;QACjD,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE;QACnB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC,CAAC;AACvF,CAAC;AAqBD,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAY,EACZ,OAA+B,EAC/B,IAAoB;IAEpB,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,OAAO,CAAC,gBAAgB,IAAI,MAAM,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,IAAI,OAAO,GAAG,aAAa,EAAE,CAAC;QAC7E,MAAM,IAAI,cAAc,CAAC,eAAe,EAAE,qDAAqD,CAAC,CAAC;IACnG,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,IAAI,KAAK,CAAC;IACzC,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAC7C,MAAM,IAAI,cAAc,CAAC,kBAAkB,EAAE,8CAA8C,CAAC,CAAC;IAC/F,CAAC;IACD,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,GAAG,IAAI,EAAE,EAAE;YAC1C,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,MAAM,EAAE;gBACjC,cAAc,EAAE,IAAI,CAAC,WAAW,IAAI,kBAAkB;aACvD;YACD,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YAC/G,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ;YAC/E,oEAAoE;YACpE,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;QACjC,MAAM,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,8EAA8E;QAC9E,yEAAyE;QACzE,wEAAwE;QACxE,IAAI,OAAiC,CAAC;QACtC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,OAAO,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YAC9C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;gBACjC,MAAM,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YACnE,CAAC;QACH,CAAC;QACD,MAAM,IAAI,cAAc,CAAC,YAAY,EAAE,OAAO,KAAK,SAAS;YAC1D,CAAC,CAAC,kCAAkC,QAAQ,CAAC,MAAM,GAAG;YACtD,CAAC,CAAC,kBAAkB,OAAO,CAAC,IAAI,MAAM,OAAO,CAAC,KAAK,EAAE,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;QACjC,IAAI,CAAC,CAAC,KAAK,YAAY,WAAW,CAAC;YAAE,MAAM,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACtG,MAAM,IAAI,cAAc,CAAC,kBAAkB,EAAE,qCAAqC,CAAC,CAAC;IACtF,CAAC;AACH,CAAC;AAED,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAE1C;;;;GAIG;AACH,KAAK,UAAU,iBAAiB,CAAC,QAAkB;IACjD,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,yEAAyE;QACzE,wDAAwD;QACxD,IAAI,KAAK,YAAY,WAAW;YAAE,OAAO,SAAS,CAAC;QACnD,MAAM,KAAK,CAAC;IACd,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,SAAS,CAAC;IACxG,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;IACpE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/C,MAAM,WAAW,GAAG,CAAC,KAAc,EAA4B,EAAE;QAC/D,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC5C,MAAM,GAAG,GAA+C,EAAE,CAAC;QAC3D,IAAI,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,WAAW,CAAC,MAAM,IAAI,GAAG;YAAE,GAAG,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;QAClH,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;YAAE,GAAG,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QACpH,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC3G,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,cAAc,CAAC,kBAAkB,EAAE,0EAA0E,CAAC,CAAC;IAC3H,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,MAAM,KAAK,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/D,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3D,MAAM,SAAS,GAAG,CAAC,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,CAAC;WACtE,CAAC,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW;YACxD,yBAAyB,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,gBAAgB,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3H,OAAO,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,iBAAiB,EACzE,SAAS,CAAC,CAAC,CAAC,0CAA0C,CAAC,CAAC,CAAC,mFAAmF,CAAC,CAAC;AAClJ,CAAC"}

package/dist/cloud-run.d.ts

@@ -1,3 +1,4 @@
+import { type ScheduleTriggerSource } from '@relayflows/surface';
 import type { RunCompletionReason } from './protocol.js';
 import type { FlowSpec } from './spec.js';
 import { type JsonValue } from './json-value.js';
@@ -11,6 +12,23 @@ 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;
@@ -19,6 +37,12 @@ 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;
@@ -26,6 +50,8 @@ export interface CloudAuthoredAuthority {
     readonly byteLength: number;
     readonly surface: SurfaceModuleAuthority;
 }
+/** The request-body fields a submission contributes; identical for a run and a schedule. */
+export declare function cloudSubmissionBody(submission: CloudSubmission): Record<string, unknown>;
 export type CloudRunState = {
     runId: string;
     status: 'pending' | 'launching' | 'running';
@@ -34,6 +60,33 @@ export type CloudRunState = {
     status: 'completed' | 'failed' | 'cancelled';
     completionReason: RunCompletionReason;
 };
+/**
+ * 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.
+ */
+/**
+ * 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 declare function prepareCloudSubmission(flow: CloudFlowSource, options?: {
+    input?: JsonValue;
+    signal?: AbortSignal;
+}): Promise<CloudSubmission>;
 /**
  * Submit a declarative flow to Cloud's pinned v2 runtime. Compilation only
  * happens here; Cloud owns provisioning and the Rust engine owns execution.

package/dist/cloud-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloud-run.d.ts","sourceRoot":"","sources":["../src/cloud-run.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAOzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAoB,KAAK,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAC1F,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAC1D,MAAM,WAAW,iBAAkB,SAAQ,sBAAsB;IAC/D,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mGAAmG;IACnG,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AACD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;IAC9B,qGAAqG;IACrG,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;CAC1C;AACD,MAAM,MAAM,aAAa,GACrB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAA;CAAE,GAC9D;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;IAAC,gBAAgB,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAE3G;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,eAAe,EACrB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,CAsF1B;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,aAAa,CAAC,CAoBxB;AAED,4FAA4F;AAC5F,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,sBAAsB,GAAG;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,OAAO,CAAC,aAAa,CAAC,CAuBxB"}
+{"version":3,"file":"cloud-run.d.ts","sourceRoot":"","sources":["../src/cloud-run.ts"],"names":[],"mappings":"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"}