@relayflows/sdk 2.0.18 → 2.0.20

package/dist/human-to.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Who an `f.human(question, { to })` question is for, parsed from the
+ * author's `to` string. This is the delivery contract Cloud reads (the local
+ * kit records it, Cloud delivers it), so the forms are fixed here and
+ * documented in docs/SURFACE.md §5 Human gates:
+ *
+ *   "slack:#eng"        → post in the Slack channel; anyone there may answer
+ *   "slack:@khaliq"     → DM the Slack user; only they may answer
+ *   "github:@khaliq"    → comment on the triggering issue / pull request,
+ *                         mentioning the handle; only they may answer
+ *   "khaliq"            → the deploy's approver, on whichever channel the run
+ *                         was triggered from (Cloud resolves; the local kit
+ *                         only records it)
+ *
+ * Anything else — an unknown provider (`email:x`), a provider with no target
+ * (`slack:`), a GitHub channel (`github:#eng`), a target with whitespace or
+ * other characters no handle carries — is refused as `human_to_invalid`
+ * rather than turned into a delivery target that would silently reach no one.
+ */
+export type HumanRecipient = {
+    readonly provider: 'slack';
+    readonly kind: 'channel' | 'user';
+    readonly target: string;
+} | {
+    readonly provider: 'github';
+    readonly kind: 'user';
+    readonly target: string;
+} | {
+    readonly provider: 'approver';
+    readonly kind: 'user';
+    readonly target: string;
+};
+export type HumanRecipientParse = {
+    readonly ok: true;
+    readonly recipient: HumanRecipient;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export declare function parseHumanTo(to: string): HumanRecipientParse;
+/** The parsed recipient of a `to` already accepted by `f.human` (`parseHumanTo` ok). */
+export declare function parseHumanRecipient(to: string): HumanRecipient;
+/** The Cloud integration a recipient needs connected: none for the approver, none for a malformed `to`. */
+export declare function humanRecipientProvider(to: string): 'slack' | 'github' | undefined;
+//# sourceMappingURL=human-to.d.ts.map

package/dist/human-to.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-to.d.ts","sourceRoot":"","sources":["../src/human-to.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1F;IAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAMpD,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,mBAAmB,CAwB5D;AAED,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,CAI9D;AAED,2GAA2G;AAC3G,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAIjF"}

package/dist/human-to.js

@@ -0,0 +1,49 @@
+/** A Slack channel name, or a Slack / GitHub / approver handle: one word, no spaces or quotes. */
+const TARGET = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/u;
+const PROVIDER_FORM = /^([A-Za-z][A-Za-z0-9_-]*)\s*:(.*)$/su;
+export function parseHumanTo(to) {
+    const trimmed = to.trim();
+    if (trimmed === '')
+        return { ok: false, reason: 'to is empty' };
+    const match = PROVIDER_FORM.exec(trimmed);
+    if (match === null) {
+        const target = trimmed.replace(/^@/u, '');
+        if (!TARGET.test(target))
+            return { ok: false, reason: `"${trimmed}" is not a handle (one word: letters, digits, . _ -)` };
+        return { ok: true, recipient: { provider: 'approver', kind: 'user', target } };
+    }
+    const provider = match[1].toLowerCase();
+    const rest = match[2].trim();
+    if (provider !== 'slack' && provider !== 'github') {
+        return { ok: false, reason: `"${provider}:" is not a delivery provider; use "slack:#channel", "slack:@user", "github:@user" or a bare approver handle` };
+    }
+    if (rest === '')
+        return { ok: false, reason: `"${provider}:" names no ${provider === 'slack' ? 'channel or user' : 'user'}` };
+    if (rest.startsWith('#')) {
+        if (provider === 'github')
+            return { ok: false, reason: `"${trimmed}": GitHub has no channels; use "github:@user"` };
+        const target = rest.slice(1);
+        if (!TARGET.test(target))
+            return { ok: false, reason: `"${trimmed}" is not a Slack channel name` };
+        return { ok: true, recipient: { provider: 'slack', kind: 'channel', target } };
+    }
+    const target = rest.replace(/^@/u, '');
+    if (!TARGET.test(target))
+        return { ok: false, reason: `"${trimmed}" is not a ${provider === 'slack' ? 'Slack' : 'GitHub'} handle` };
+    return { ok: true, recipient: { provider, kind: 'user', target } };
+}
+/** The parsed recipient of a `to` already accepted by `f.human` (`parseHumanTo` ok). */
+export function parseHumanRecipient(to) {
+    const parsed = parseHumanTo(to);
+    if (!parsed.ok)
+        throw new Error(`f.human to ${parsed.reason}`);
+    return parsed.recipient;
+}
+/** The Cloud integration a recipient needs connected: none for the approver, none for a malformed `to`. */
+export function humanRecipientProvider(to) {
+    const parsed = parseHumanTo(to);
+    if (!parsed.ok || parsed.recipient.provider === 'approver')
+        return undefined;
+    return parsed.recipient.provider;
+}
+//# sourceMappingURL=human-to.js.map

package/dist/human-to.js.map

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

package/dist/index.d.ts

@@ -5,12 +5,13 @@ export type { StepSpend } from './protocol.js';
 export { SPEC_SCHEMA_VERSION } from './spec.js';
 export { CloudFlowError, type CloudConnectionOptions } from './cloud-http.js';
 export { runInCloud, getCloudFlowRun, waitForCloudFlowRun, type CloudFlowSource, type RunInCloudOptions, type CloudRunReceipt, type CloudRunState, } from './cloud-run.js';
-export { downloadCloudPatch, applyCloudPatch, packWorkingTree, patchedPaths, MAX_SYNC_BYTES, type CloudPatch, type PackedTree, } from './cloud-sync.js';
+export { downloadCloudPatch, downloadCloudPatchSet, applyCloudPatch, packWorkingTree, patchedPaths, excludedPatchPaths, CLOUD_SYNC_PATCH_EXCLUDES, MAX_SYNC_BYTES, type CloudPatch, type CloudPathPatch, type CloudPatchSet, type PackedTree, type ApplyCloudPatchOptions, type AppliedCloudPatch, } from './cloud-sync.js';
 export { scheduleInCloud, listCloudSchedules, unscheduleInCloud, everyToCron, declaredScheduleCron, type ScheduleInCloudInput, type CloudSchedule, } from './cloud-schedule.js';
 export { prepareCloudSubmission, cloudSubmissionBody, type CloudSubmission } from './cloud-run.js';
 export { deployToCloud, listCloudDeployments, undeployFromCloud, parseRepository, parseTriggerSource, FLOW_TRIGGER_PROVIDERS, type DeployToCloudInput, type CloudDeployment, type CloudDeploymentSummary, type FlowTriggerSource, type FlowTriggerProvider, } from './cloud-deploy.js';
 export { ensureIntegrationsConnected, integrationConnected, providerLabel, type ConnectPrompt, type EnsureConnectionsOptions, type ConnectionsOutcome, } from './cloud-connect.js';
 export { flowRequirements, describeFlowRequirements, harnessFromCli, FLOW_HARNESSES, type FlowRequirements, type FlowRequirementsContext, type FlowIntegrationRequirement, type FlowHarnessRequirement, type FlowHarness, } from './flow-requirements.js';
+export { parseHumanTo, parseHumanRecipient, humanRecipientProvider, type HumanRecipient, type HumanRecipientParse } from './human-to.js';
 export { canonicalize, specHash } from './canonical.js';
 export { compileAndHash, compileSpec, compileYaml, compileYamlToCanonicalJson, kernelToAuthoring, toKernelSpec, CompileError, } from './compile.js';
 export { validateSpec, type ValidationResult } from './validate.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -5,12 +5,13 @@ export { MODEL_PRICING } from './model-pricing.js';
 export { SPEC_SCHEMA_VERSION } from './spec.js';
 export { CloudFlowError } from './cloud-http.js';
 export { runInCloud, getCloudFlowRun, waitForCloudFlowRun, } from './cloud-run.js';
-export { downloadCloudPatch, applyCloudPatch, packWorkingTree, patchedPaths, MAX_SYNC_BYTES, } from './cloud-sync.js';
+export { downloadCloudPatch, downloadCloudPatchSet, applyCloudPatch, packWorkingTree, patchedPaths, excludedPatchPaths, CLOUD_SYNC_PATCH_EXCLUDES, MAX_SYNC_BYTES, } from './cloud-sync.js';
 export { scheduleInCloud, listCloudSchedules, unscheduleInCloud, everyToCron, declaredScheduleCron, } from './cloud-schedule.js';
 export { prepareCloudSubmission, cloudSubmissionBody } from './cloud-run.js';
 export { deployToCloud, listCloudDeployments, undeployFromCloud, parseRepository, parseTriggerSource, FLOW_TRIGGER_PROVIDERS, } from './cloud-deploy.js';
 export { ensureIntegrationsConnected, integrationConnected, providerLabel, } from './cloud-connect.js';
 export { flowRequirements, describeFlowRequirements, harnessFromCli, FLOW_HARNESSES, } from './flow-requirements.js';
+export { parseHumanTo, parseHumanRecipient, humanRecipientProvider } from './human-to.js';
 export { canonicalize, specHash } from './canonical.js';
 export { compileAndHash, compileSpec, compileYaml, compileYamlToCanonicalJson, kernelToAuthoring, toKernelSpec, CompileError, } from './compile.js';
 export { validateSpec } from './validate.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,yEAAyE;AACzE,yBAAyB;AAqDzB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EAAE,cAAc,EAA+B,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EACL,UAAU,EAAE,eAAe,EAAE,mBAAmB,GAEjD,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,kBAAkB,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,GAEnF,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,WAAW,EAAE,oBAAoB,GAE1F,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAwB,MAAM,gBAAgB,CAAC;AACnG,OAAO,EACL,aAAa,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,sBAAsB,GAEpH,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,2BAA2B,EAAE,oBAAoB,EAAE,aAAa,GAEjE,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,gBAAgB,EAAE,wBAAwB,EAAE,cAAc,EAAE,cAAc,GAE3E,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,cAAc,EACd,WAAW,EACX,WAAW,EACX,0BAA0B,EAC1B,iBAAiB,EACjB,YAAY,EACZ,YAAY,GACb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAyB,MAAM,eAAe,CAAC;AAEpE,OAAO,EACL,yBAAyB,GAG1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,SAAS,EACT,gBAAgB,GAUjB,MAAM,gBAAgB,CAAC;AAMxB,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,GAInB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,MAAM,EAA2D,MAAM,UAAU,CAAC;AA6C3F,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,aAAa,EAA6B,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,WAAW,EAA2B,MAAM,aAAa,CAAC;AAEnE,OAAO,EACL,mBAAmB,EACnB,gBAAgB,GAIjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,GAInB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,uBAAuB,GAIxB,MAAM,6BAA6B,CAAC;AAErC,iFAAiF;AACjF,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,GAInB,MAAM,gBAAgB,CAAC;AAExB,uEAAuE;AACvE,yEAAyE;AACzE,4EAA4E;AAC5E,2BAA2B;AAC3B,OAAO,EACL,iBAAiB,GAGlB,MAAM,yBAAyB,CAAC;AAEjC,2EAA2E;AAC3E,6EAA6E;AAC7E,oEAAoE;AACpE,gCAAgC;AAChC,OAAO,EACL,YAAY,EACZ,cAAc,EACd,aAAa,EACb,OAAO,EACP,aAAa,EACb,oBAAoB,EACpB,wBAAwB,EACxB,eAAe,GAMhB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,UAAU,EAA4C,MAAM,kBAAkB,CAAC;AAExF,OAAO,EAAE,cAAc,EAAsB,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,iBAAiB,EAAyB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/relay-cli.d.ts

@@ -0,0 +1,50 @@
+import { type CliCommandSpec } from './cli-commands.js';
+/**
+ * The `@relayflows/sdk/relay-cli` entrypoint: a mountable CLI surface.
+ *
+ * `agent-relay` mounts this as `agent-relay flows`. The surface is a thin
+ * projection over the CLI this package already ships -- `commands` comes from
+ * the same `CLI_VERBS` table `parseArgs` dispatches on, and `run` delegates
+ * straight to `runCli`. No command is reimplemented here, and
+ * `packages/relayflows/bin/flows.js` keeps calling `runCli` on the same path.
+ *
+ * Structurally typed against `@agent-relay/cli-surface` without importing it,
+ * so `dist/relay-cli.d.ts` has no dependency on the contract package and this
+ * package gains no runtime dependency on relay. `tests/relay-cli-surface.test.ts`
+ * asserts the assignability and runs the contract's own conformance checks.
+ */
+/** Host-supplied output sink. Mirrors `RelayCliIo`. */
+export interface RelayCliIo {
+    stdout(chunk: string): void;
+    stderr(chunk: string): void;
+}
+/** A mountable product CLI. Mirrors `RelayCliSurface`. */
+export interface RelayCliSurface {
+    id: string;
+    version: string;
+    contract: 1;
+    commands: readonly CliCommandSpec[];
+    run(argv: readonly string[], io: RelayCliIo): Promise<number>;
+}
+/** Options for {@link createRelayCliSurface}. */
+export interface CreateRelayCliSurfaceOptions {
+    /**
+     * Cancellation for the long-running verbs, owned by the host.
+     *
+     * A surface must install no global signal handlers, so one is always passed
+     * to `runCli` -- a never-aborting signal when the host supplies none. Pass a
+     * real one to get graceful cancellation (for example, the
+     * "Stopped observing; the hosted run has not been cancelled" path on
+     * `run --cloud --wait`) instead of the host's SIGINT killing the process.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Build the relayflows CLI surface.
+ *
+ * @param options - Host-supplied cancellation.
+ * @returns A surface whose `run` resolves to an exit code, writes only through
+ *   the supplied io, and installs no process signal handlers.
+ */
+export declare function createRelayCliSurface(options?: CreateRelayCliSurfaceOptions): RelayCliSurface;
+//# sourceMappingURL=relay-cli.d.ts.map

package/dist/relay-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-cli.d.ts","sourceRoot":"","sources":["../src/relay-cli.ts"],"names":[],"mappings":"AAGA,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnF;;;;;;;;;;;;;GAaG;AAEH,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,CAAC,CAAC;IACZ,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IACpC,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/D;AAED,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAiCD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,eAAe,CA2BjB"}

package/dist/relay-cli.js

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import { runCli } from './cli.js';
+import { CLI_VERBS, CLI_VERB_NAMES } from './cli-commands.js';
+/** Exit code for an argv the surface cannot route, per the contract. */
+const EXIT_UNKNOWN_COMMAND = 2;
+/** Drop `variants` -- the routing detail the host has no use for. */
+function toCommandSpec(verb) {
+    const { variants: _variants, ...spec } = verb;
+    return spec;
+}
+/**
+ * Read this package's version from its own manifest.
+ *
+ * Resolved from `import.meta.url` rather than imported, because `package.json`
+ * sits outside `rootDir` and a hardcoded literal would silently go stale at the
+ * next release. `src/` and `dist/` are both one level below the manifest, so
+ * the same relative path is correct before and after a build.
+ */
+function packageVersion() {
+    try {
+        const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        const version = manifest.version;
+        return typeof version === 'string' && version.length > 0 ? version : '0.0.0';
+    }
+    catch {
+        // A surface that cannot read its own manifest is still perfectly runnable;
+        // refusing to mount over a cosmetic field would be the worse failure.
+        return '0.0.0';
+    }
+}
+/**
+ * Build the relayflows CLI surface.
+ *
+ * @param options - Host-supplied cancellation.
+ * @returns A surface whose `run` resolves to an exit code, writes only through
+ *   the supplied io, and installs no process signal handlers.
+ */
+export function createRelayCliSurface(options = {}) {
+    return {
+        id: 'relayflows',
+        version: packageVersion(),
+        contract: 1,
+        commands: CLI_VERBS.map(toCommandSpec),
+        async run(argv, io) {
+            const verb = argv[0];
+            // `runCli` would refuse this too, but with the full usage block. Naming
+            // the offending token is the more useful answer when the host has just
+            // routed `agent-relay flows <typo>` here.
+            if (verb !== undefined && !verb.startsWith('-') && !CLI_VERB_NAMES.has(verb)) {
+                io.stderr(`error: '${verb}' is not a command of relayflows\n`);
+                io.stderr("Run 'agent-relay flows --help' for the available commands.\n");
+                return EXIT_UNKNOWN_COMMAND;
+            }
+            return runCli(argv, 
+            // `CliIo` is line-oriented and the contract's io is chunk-oriented, so
+            // the terminator is added here rather than by every call site.
+            { stdout: (line) => io.stdout(`${line}\n`), stderr: (line) => io.stderr(`${line}\n`) }, 
+            // Always pass a signal: that is what keeps `runCli` from installing the
+            // SIGINT/SIGTERM handlers the standalone binary still relies on.
+            { signal: options.signal ?? new AbortController().signal });
+        },
+    };
+}
+//# sourceMappingURL=relay-cli.js.map

package/dist/relay-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-cli.js","sourceRoot":"","sources":["../src/relay-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAuB,MAAM,mBAAmB,CAAC;AA8CnF,wEAAwE;AACxE,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAE/B,qEAAqE;AACrE,SAAS,aAAa,CAAC,IAA6C;IAClE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,cAAc;IACrB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAY,IAAI,CAAC,KAAK,CAClC,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAClE,CAAC;QACF,MAAM,OAAO,GAAI,QAAkC,CAAC,OAAO,CAAC;QAC5D,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;QAC3E,sEAAsE;QACtE,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,UAAwC,EAAE;IAE1C,OAAO;QACL,EAAE,EAAE,YAAY;QAChB,OAAO,EAAE,cAAc,EAAE;QACzB,QAAQ,EAAE,CAAC;QACX,QAAQ,EAAE,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC;QACtC,KAAK,CAAC,GAAG,CAAC,IAAuB,EAAE,EAAc;YAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YACrB,wEAAwE;YACxE,uEAAuE;YACvE,0CAA0C;YAC1C,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7E,EAAE,CAAC,MAAM,CAAC,WAAW,IAAI,oCAAoC,CAAC,CAAC;gBAC/D,EAAE,CAAC,MAAM,CAAC,8DAA8D,CAAC,CAAC;gBAC1E,OAAO,oBAAoB,CAAC;YAC9B,CAAC;YACD,OAAO,MAAM,CACX,IAAI;YACJ,uEAAuE;YACvE,+DAA+D;YAC/D,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE;YACtF,wEAAwE;YACxE,iEAAiE;YACjE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC,MAAM,EAAE,CAC3D,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/sdk",
-  "version": "2.0.18",
+  "version": "2.0.20",
   "description": "TypeScript-first authoring SDK for Relayflows. Compiles specs; speaks the journal protocol.",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,6 +24,10 @@
     "./cli": {
       "types": "./dist/cli.d.ts",
       "import": "./dist/cli.js"
+    },
+    "./relay-cli": {
+      "types": "./dist/relay-cli.d.ts",
+      "import": "./dist/relay-cli.js"
     }
   },
   "files": [
@@ -45,7 +49,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@relayfile/adapter-core": "0.5.26",
     "@relayfile/relay-helpers": "0.4.11",
-    "@relayflows/surface": "2.0.18",
+    "@relayflows/surface": "2.0.20",
     "@types/js-yaml": "^4.0.9",
     "ai-hist": "0.4.1",
     "ajv": "^8.17.1",
@@ -55,6 +59,7 @@
     "yaml": "^2.5.1"
   },
   "devDependencies": {
+    "@agent-relay/cli-surface": "^12.2.4",
     "@types/node": "^22.7.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"

package/src/authored-flow-error.ts

@@ -1,3 +1,4 @@
+import type { HumanRecipient } from './human-to.js';
 import type {
   CompletionReason as ProtocolCompletionReason,
   RunCompletionReason as ProtocolRunCompletionReason,
@@ -28,6 +29,8 @@ export type AuthoredFlowExecutionErrorCode =
   | 'human_parked'
   /** A recorded answer to `f.human` was not `{ answer: boolean }`. */
   | 'human_answer_invalid'
+  /** `f.human`'s `to` is not one of the documented recipient forms (human-to.ts). */
+  | 'human_to_invalid'
   | 'unsupported_header'
   | 'unsettled_derived_work'
   | 'unsupported_promise_lifecycle'
@@ -52,6 +55,8 @@ export interface AuthoredHumanWait {
   readonly waitId: string;
   readonly question: string;
   readonly to: string;
+  /** `to` parsed into its delivery form (human-to.ts); Cloud delivers by it. */
+  readonly recipient?: HumanRecipient;
 }
 
 /**

package/src/authored-flow-executor.ts

@@ -36,6 +36,7 @@ import {
   type AuthoredFlowExecutionErrorCode,
 } from './authored-flow-error.js';
 import { readHumanAnswer } from './authored-human.js';
+import { parseHumanTo } from './human-to.js';
 import {
   AuthoredFlowOperation,
   stopAuthoredOperations,
@@ -431,6 +432,13 @@ export async function executeAuthoredFlow<Input = undefined>(
       if (typeof humanOptions?.to !== 'string' || humanOptions.to.trim() === '') {
         throw new AuthoredFlowExecutionError('human_answer_invalid', 'f.human requires { to } naming who answers');
       }
+      // Refused before an ordinal is consumed or anything is journaled: a
+      // malformed `to` would otherwise park the run on a question Cloud can
+      // deliver to no one (docs/SURFACE.md §5 lists the four forms).
+      const parsedTo = parseHumanTo(humanOptions.to);
+      if (!parsedTo.ok) {
+        throw new AuthoredFlowExecutionError('human_to_invalid', `f.human to ${parsedTo.reason}`);
+      }
       const id = `human-${nextStep++}`;
       const to = humanOptions.to;
       // Hoisted like `llmOp`/`runOp`: the start closure reads the caller's

package/src/cli/answer.ts

@@ -1,3 +1,4 @@
+import { parseHumanRecipient } from '../human-to.js';
 import { userInfo } from 'node:os';
 import { readAuthoredRootMetadata } from '../authored-root.js';
 import { HUMAN_WAIT_ID, humanAnswerPayload, readHumanAnswer, readOpenHumanWaits, resumeCommand } from '../authored-human.js';
@@ -75,7 +76,7 @@ export async function answerFlow(
       report: {
         ...base, ok: true, runId, socketPath, status: snapshot.status,
         answer: { waitId, answer, ...(options.note === undefined ? {} : { note: options.note }) },
-        humanWait: { waitId, question: wait.question, to: wait.to },
+        humanWait: { waitId, question: wait.question, to: wait.to, recipient: parseHumanRecipient(wait.to) },
         next: resumeCommand(runId, dataDir, root?.localAgentStream !== undefined),
         diagnostics: [],
       },

package/src/cli/build.ts

@@ -12,14 +12,20 @@ import type { FlowSpec } from '../spec.js';
 
 export interface BuildArgs { command: 'build'; value: string; out?: string; verify: boolean; json: boolean }
 
+/**
+ * `--verify` is an ordinary flag, not a leading mode token: the command surface
+ * lists it beside `--out` and `--json`, so every order the help implies has to
+ * parse (`build --verify --json <dir>` and `build <dir> --verify` alike).
+ *
+ * `--out` is the one combination genuinely refused: it names where a build
+ * writes, and a verify builds nothing, so accepting the pair would silently
+ * ignore the destination. The surface says so in the option's description.
+ */
 export function parseBuildArgs(args: readonly string[]): BuildArgs | undefined {
-  if (args[0] === '--verify') {
-    return args.length === 2 && !args[1]!.startsWith('-')
-      ? { command: 'build', value: args[1]!, verify: true, json: false } : undefined;
-  }
   let out: string | undefined;
   let value: string | undefined;
   let json = false;
+  let verify = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]!;
     if (arg === '--out') {
@@ -28,10 +34,14 @@ export function parseBuildArgs(args: readonly string[]): BuildArgs | undefined {
     } else if (arg === '--json') {
       if (json) return undefined;
       json = true;
+    } else if (arg === '--verify') {
+      if (verify) return undefined;
+      verify = true;
     } else if (arg.startsWith('-') || value !== undefined) return undefined;
     else value = arg;
   }
-  return value === undefined ? undefined : { command: 'build', value, out, verify: false, json };
+  if (value === undefined || (verify && out !== undefined)) return undefined;
+  return { command: 'build', value, out, verify, json };
 }
 
 /**
@@ -49,7 +59,11 @@ function emitBuildCheckReport(report: CheckReport, json: boolean, io: CliIo): vo
 export async function runBuild(args: BuildArgs, io: CliIo): Promise<0 | 2> {
   try {
     if (args.verify) {
-      io.stdout(`VERIFIED sha256:${await verifyBundle(args.value)}`);
+      const digest = `sha256:${await verifyBundle(args.value)}`;
+      // `--json` is declared on the verb, not on one of its forms: a verify
+      // under it emits the same single object a `--json` consumer parses.
+      if (args.json) io.stdout(JSON.stringify({ ok: true, verified: true, bundle: args.value, digest }));
+      else io.stdout(`VERIFIED ${digest}`);
       return 0;
     }
     // Gate the build on the same preflight pipeline `flows check` uses.

package/src/cli/cloud-run.ts

@@ -11,11 +11,13 @@ export async function runCloudCli(
     value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean; noConnect?: boolean;
   },
   io: CliIo,
+  /**
+   * Cancellation, owned by the caller. `runCli` supplies either the embedder's
+   * signal or one it drives from SIGINT/SIGTERM itself, so no process-wide
+   * handler is installed here.
+   */
+  signal: AbortSignal,
 ): Promise<0 | 1 | 2> {
-  const controller = new AbortController();
-  const abort = (): void => controller.abort();
-  process.once('SIGINT', abort);
-  process.once('SIGTERM', abort);
   let runId: string | undefined;
   // Flips at the run submission. An interruption before it — during prepare,
   // packing or upload — admitted nothing and is safe to retry; only an
@@ -23,7 +25,7 @@ export async function runCloudCli(
   let submitting = false;
   let harnesses: readonly string[] = [];
   try {
-    const options: RunInCloudOptions = { signal: controller.signal, onSubmit: () => { submitting = true; } };
+    const options: RunInCloudOptions = { signal, onSubmit: () => { submitting = true; } };
     if (isAuthoredFlowPath(path)) {
       // Same parse as a local direct run, so a file-or-inline argument means
       // the same thing on both sides of `--cloud`.
@@ -40,7 +42,7 @@ export async function runCloudCli(
     // arguments must not first open a browser.
     const connections = await ensureFlowConnections({
       path, prompt: cliConnectPrompt(io, { noConnect, json }),
-    }, { signal: controller.signal });
+    }, { signal });
     harnesses = connections?.requirements.harnesses ?? [];
     for (const provider of connections?.outcome.connected ?? []) if (!json) io.stdout(`CONNECTED ${provider}`);
     // The tree is the invoking directory, as with v1: the flow path is where
@@ -62,16 +64,16 @@ export async function runCloudCli(
       if (json) io.stdout(JSON.stringify({ ok: true, ...receipt }));
       return 0;
     }
-    const run = await waitForCloudFlowRun(receipt.runId, { signal: controller.signal });
+    const run = await waitForCloudFlowRun(receipt.runId, { signal });
     const ok = run.status === 'completed';
     if (json) io.stdout(JSON.stringify({ ok, ...receipt, ...run }));
     else io.stdout(`${run.status.toUpperCase()} ${run.runId} completionReason: ${'completionReason' in run ? run.completionReason : 'unavailable'}`);
     return ok ? 0 : 1;
   } catch (error) {
-    const code = controller.signal.aborted
+    const code = signal.aborted
       ? runId ? 'observation_aborted' : submitting ? 'admission_unknown' : 'submission_aborted'
       : error instanceof CloudFlowError ? error.code : 'cloud_run_failed';
-    const message = controller.signal.aborted
+    const message = signal.aborted
       ? runId ? 'Stopped observing; the hosted run has not been cancelled.'
         : submitting
           ? 'Submission interrupted before a receipt was received. Admission is unknown; Cloud may have started the run. Do not resubmit blindly.'
@@ -83,8 +85,5 @@ export async function runCloudCli(
       && (['configuration', 'unsupported_source', 'invalid_input', 'unsupported_storage_backend', 'sync_too_large', 'sync_unsupported',
         'integration_not_connected'].includes(error.code)
         || (runId === undefined && error.code === 'http_error' && [401, 403].includes(error.status ?? 0))) ? 2 : 1;
-  } finally {
-    process.off('SIGINT', abort);
-    process.off('SIGTERM', abort);
   }
 }

package/src/cli/cloud-sync.ts

@@ -1,5 +1,7 @@
 import { CloudFlowError } from '../cloud-http.js';
-import { applyCloudPatch, downloadCloudPatch, patchedPaths } from '../cloud-sync.js';
+import {
+  applyCloudPatch, downloadCloudPatchSet, excludedPatchPaths, patchedPaths, type CloudPathPatch,
+} from '../cloud-sync.js';
 import type { CliIo } from '../cli.js';
 
 /**
@@ -7,23 +9,50 @@ import type { CliIo } from '../cli.js';
  * and apply it here. The patch is the sandbox's own `git diff` against the
  * uploaded baseline, so applying it reproduces exactly what the run's steps
  * wrote — no re-execution, no re-upload.
+ *
+ * The agent runtime's own bookkeeping inside that tree is dropped on the way
+ * in (`CLOUD_SYNC_PATCH_EXCLUDES`); `--dry-run` prints the patch instead of
+ * applying it, and a run that produced one patch per mounted path is shown but
+ * never applied, because no single `--dir` is the right destination for all of
+ * them.
  */
 export async function runCloudSyncCli(
-  { runId, json, root }: { runId: string; json: boolean; root: string },
+  { runId, json, root, dryRun }: { runId: string; json: boolean; root: string; dryRun: boolean },
   io: CliIo,
 ): Promise<0 | 1 | 2> {
   try {
-    const { patch, hasChanges } = await downloadCloudPatch(runId, {});
-    if (!hasChanges || !patch.trim()) {
+    const set = await downloadCloudPatchSet(runId, {});
+    // A single-tree run can answer `hasChanges: true` with an empty body. The
+    // multi-path branch already discounts those (`patch.trim() !== ''` in
+    // `downloadCloudPatchSet`), and so did `agent-relay cloud sync`, which this
+    // command replaces. Without the same guard an empty patch reaches `git
+    // apply`, which fails as `patch_conflict` instead of reporting NO CHANGES.
+    const hasChanges = set.kind === 'single' ? set.hasChanges && set.patch.trim() !== '' : set.hasChanges;
+    if (!hasChanges) {
       if (json) io.stdout(JSON.stringify({ ok: true, runId, hasChanges: false, applied: false }));
       else io.stdout(`NO CHANGES ${runId}`);
       return 0;
     }
-    applyCloudPatch(root, patch);
-    const files = patchedPaths(patch);
-    if (json) io.stdout(JSON.stringify({ ok: true, runId, hasChanges: true, applied: true, files }));
+    if (set.kind === 'multi-path') {
+      const changed = set.patches.filter(entry => entry.hasChanges && entry.patch.trim() !== '');
+      if (!dryRun) {
+        throw new CloudFlowError('sync_unsupported',
+          `Run ${runId} produced ${changed.length} path-scoped patch${changed.length === 1 ? '' : 'es'} `
+          + `(${changed.map(entry => entry.name).join(', ')}); flows sync applies single-tree runs only. `
+          + 'Inspect them with --dry-run, then apply each in its own repository.');
+      }
+      reportMultiPathDryRun(runId, changed, json, io);
+      return 0;
+    }
+    if (dryRun) {
+      reportDryRun(runId, set.patch, json, io);
+      return 0;
+    }
+    const { files, excluded } = applyCloudPatch(root, set.patch);
+    if (json) io.stdout(JSON.stringify({ ok: true, runId, hasChanges: true, applied: true, files, excluded }));
     else {
-      io.stdout(`APPLIED ${runId}: ${files.length} file${files.length === 1 ? '' : 's'}${files.length ? `\n  ${files.join('\n  ')}` : ''}`);
+      io.stdout(`APPLIED ${runId}: ${files.length} file${files.length === 1 ? '' : 's'}${indented(files)}`);
+      if (excluded.length) io.stdout(`SKIPPED agent runtime paths: ${excluded.length}${indented(excluded)}`);
       io.stdout('Applied to the working tree, uncommitted: review with git diff before keeping it.');
     }
     return 0;
@@ -35,3 +64,51 @@ export async function runCloudSyncCli(
     return error instanceof CloudFlowError && ['configuration', 'sync_unsupported', 'patch_conflict'].includes(error.code) ? 2 : 1;
   }
 }
+
+/** A single-tree patch, shown rather than applied. */
+function reportDryRun(runId: string, patch: string, json: boolean, io: CliIo): void {
+  const excluded = excludedPatchPaths(patch);
+  const files = patchedPaths(patch).filter(path => !excluded.includes(path));
+  if (json) {
+    // The patch travels in the payload, not on stdout beside it: a --json
+    // consumer parses one object, and a diff printed alongside it is not JSON.
+    io.stdout(JSON.stringify({
+      ok: true, runId, hasChanges: true, applied: false, dryRun: true, files, excluded, patch,
+    }));
+    return;
+  }
+  io.stdout(`DRY RUN ${runId}: ${files.length} file${files.length === 1 ? '' : 's'} would be written${indented(files)}`);
+  if (excluded.length) io.stdout(`Would skip agent runtime paths: ${excluded.length}${indented(excluded)}`);
+  emitPatch(patch, io);
+}
+
+/** Every changed path-scoped patch, shown; applying them is not this command's call. */
+function reportMultiPathDryRun(
+  runId: string, changed: readonly CloudPathPatch[], json: boolean, io: CliIo,
+): void {
+  if (json) {
+    io.stdout(JSON.stringify({
+      ok: true, runId, hasChanges: true, applied: false, dryRun: true, multiPath: true,
+      patches: changed.map(({ name, patch }) => {
+        const excluded = excludedPatchPaths(patch);
+        return { name, files: patchedPaths(patch).filter(path => !excluded.includes(path)), excluded, patch };
+      }),
+    }));
+    return;
+  }
+  io.stdout(`DRY RUN ${runId}: ${changed.length} path-scoped patch${changed.length === 1 ? '' : 'es'}`);
+  io.stdout('Each targets its own repository; apply them there, not with --dir.');
+  for (const { name, patch } of changed) {
+    io.stdout(`--- patch for path "${name}" ---`);
+    emitPatch(patch, io);
+  }
+}
+
+/** Write a diff through the line-oriented io without gaining or losing a newline. */
+function emitPatch(patch: string, io: CliIo): void {
+  for (const line of patch.replace(/\n$/u, '').split('\n')) io.stdout(line);
+}
+
+function indented(paths: readonly string[]): string {
+  return paths.length ? `\n  ${paths.join('\n  ')}` : '';
+}