@relayflows/surface 2.0.9 → 2.0.10

package/dist/step.d.ts

@@ -1,6 +1,48 @@
 /** A journal-backed step result with its postfix verification gate. */
 export interface Step<T> extends PromiseLike<T> {
-    /** Fail the step with `verification_failed` when the predicate is false. */
+    /**
+     * Attach a named data gate to this step's `verification:` field. The gate is
+     * lowered by the SDK into a slice-P journal-honest check that survives
+     * replay — its shape is data, not code, so covenant 1 (journal-as-truth)
+     * holds. See `packages/sdk/src/named-gates.ts` for the enforcement.
+     */
+    gate(config: NamedGate): Step<T>;
+    /**
+     * Predicate gates cannot be journaled — the JavaScript closure would not
+     * survive replay — so the executor refuses this branch with
+     * `unsupported_gate`. Use a `NamedGate` config-object gate above, or the
+     * declarative `verification:` field on the compiled step spec, when you
+     * need journal-honest verification.
+     */
     gate(predicate: (value: T) => boolean, because?: string): Step<T>;
 }
+/**
+ * Slice-P named data gates the authored surface can attach postfix via
+ * `.gate(config)`. The SDK's named-gate lowering enforces these exactly (see
+ * `packages/sdk/src/named-gates.ts`); the shapes here are the surface-visible
+ * subset kept in sync with `NamedDataGate` in the SDK spec.
+ */
+export type NamedGate = ReferencesInputNamedGate | SubprocessNamedGate | WordCountBoundsNamedGate | RegexMatchNamedGate;
+export interface ReferencesInputNamedGate {
+    type: 'references_input';
+    input_key: string;
+    in_output_at?: Array<string | number>;
+}
+export interface SubprocessNamedGate {
+    type: 'subprocess_gate';
+    command: string;
+    from_output?: Array<string | number>;
+}
+export interface WordCountBoundsNamedGate {
+    type: 'word_count_bounds';
+    min?: number;
+    max?: number;
+}
+export interface RegexMatchNamedGate {
+    type: 'regex_match';
+    pattern: string;
+    /** Only i, m, and s; evaluated by a non-backtracking RE2 engine. */
+    flags?: string;
+    in_output_at?: Array<string | number>;
+}
 //# sourceMappingURL=step.d.ts.map

package/dist/step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../src/step.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,WAAW,IAAI,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IAC7C,4EAA4E;IAC5E,IAAI,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;CACnE"}
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../src/step.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,WAAW,IAAI,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IAC7C;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACjC;;;;;;OAMG;IACH,IAAI,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;CACnE;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GACjB,wBAAwB,GACxB,mBAAmB,GACnB,wBAAwB,GACxB,mBAAmB,CAAC;AAExB,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CACvC"}

package/dist/triggers/github.d.ts

@@ -0,0 +1,8 @@
+import type { WebhookFilter } from "../triggers.js";
+export declare const github: Readonly<{
+    issues(filter?: WebhookFilter): import("../provider-trigger.js").ProviderTriggerSource<"github", "issues">;
+    pull_request(action?: string): import("../provider-trigger.js").ProviderTriggerSource<"github", "pull_request">;
+    pull_request_review(filter?: WebhookFilter): import("../provider-trigger.js").ProviderTriggerSource<"github", "pull_request_review">;
+    push(filter?: WebhookFilter): import("../provider-trigger.js").ProviderTriggerSource<"github", "push">;
+}>;
+//# sourceMappingURL=github.d.ts.map

package/dist/triggers/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../src/triggers/github.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,eAAO,MAAM,MAAM;oBACD,aAAa;0BAGP,MAAM;iCAGC,aAAa;kBAG5B,aAAa;EAG3B,CAAC"}

package/dist/triggers/github.js

@@ -0,0 +1,17 @@
+// GENERATED by scripts/generate-triggers.mjs — do not edit.
+import { providerTrigger, triggerArgument } from "../provider-trigger.js";
+export const github = Object.freeze({
+    issues(filter) {
+        return providerTrigger("github", "issues", filter);
+    },
+    pull_request(action) {
+        return providerTrigger("github", "pull_request", action === undefined ? undefined : { action: triggerArgument(action, "action") });
+    },
+    pull_request_review(filter) {
+        return providerTrigger("github", "pull_request_review", filter);
+    },
+    push(filter) {
+        return providerTrigger("github", "push", filter);
+    },
+});
+//# sourceMappingURL=github.js.map

package/dist/triggers/github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.js","sourceRoot":"","sources":["../../src/triggers/github.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG1E,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAClC,MAAM,CAAC,MAAsB;QAC3B,OAAO,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACrD,CAAC;IACD,YAAY,CAAC,MAAe;QAC1B,OAAO,eAAe,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IACrI,CAAC;IACD,mBAAmB,CAAC,MAAsB;QACxC,OAAO,eAAe,CAAC,QAAQ,EAAE,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,CAAC,MAAsB;QACzB,OAAO,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC;CACF,CAAC,CAAC"}

package/dist/triggers/index.d.ts

@@ -0,0 +1,8 @@
+export { github } from "./github.js";
+export { slack } from "./slack.js";
+/** Exact upstream event names, plus the generated Slack mention shorthand. */
+export declare const providerEventTypes: Readonly<{
+    github: readonly ["issues", "pull_request", "pull_request_review", "push"];
+    slack: readonly ["app_mention", "message", "reaction_added"];
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/triggers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/triggers/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB;;;EAG7B,CAAC"}

package/dist/triggers/index.js

@@ -0,0 +1,9 @@
+// GENERATED by scripts/generate-triggers.mjs — do not edit.
+export { github } from "./github.js";
+export { slack } from "./slack.js";
+/** Exact upstream event names, plus the generated Slack mention shorthand. */
+export const providerEventTypes = Object.freeze({
+    "github": Object.freeze(["issues", "pull_request", "pull_request_review", "push"]),
+    "slack": Object.freeze(["app_mention", "message", "reaction_added"]),
+});
+//# sourceMappingURL=index.js.map

package/dist/triggers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/triggers/index.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAC,cAAc,EAAC,qBAAqB,EAAC,MAAM,CAAU,CAAC;IACxF,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,aAAa,EAAC,SAAS,EAAC,gBAAgB,CAAU,CAAC;CAC5E,CAAC,CAAC"}

package/dist/triggers/slack.d.ts

@@ -0,0 +1,8 @@
+import type { WebhookFilter } from "../triggers.js";
+export declare const slack: Readonly<{
+    message(filter?: WebhookFilter): import("../provider-trigger.js").ProviderTriggerSource<"slack", "message">;
+    reaction_added(filter?: WebhookFilter): import("../provider-trigger.js").ProviderTriggerSource<"slack", "reaction_added">;
+    mention(channel: string): import("../provider-trigger.js").ProviderTriggerSource<"slack", "app_mention">;
+    reaction(emoji: string): import("../provider-trigger.js").ProviderTriggerSource<"slack", "reaction_added">;
+}>;
+//# sourceMappingURL=slack.d.ts.map

package/dist/triggers/slack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.d.ts","sourceRoot":"","sources":["../../src/triggers/slack.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,eAAO,MAAM,KAAK;qBACC,aAAa;4BAGN,aAAa;qBAGpB,MAAM;oBAGP,MAAM;EAGtB,CAAC"}

package/dist/triggers/slack.js

@@ -0,0 +1,17 @@
+// GENERATED by scripts/generate-triggers.mjs — do not edit.
+import { providerTrigger, triggerArgument } from "../provider-trigger.js";
+export const slack = Object.freeze({
+    message(filter) {
+        return providerTrigger("slack", "message", filter);
+    },
+    reaction_added(filter) {
+        return providerTrigger("slack", "reaction_added", filter);
+    },
+    mention(channel) {
+        return providerTrigger("slack", "app_mention", { channel: triggerArgument(channel, "channel") });
+    },
+    reaction(emoji) {
+        return providerTrigger("slack", "reaction_added", { reaction: triggerArgument(emoji, "emoji") });
+    },
+});
+//# sourceMappingURL=slack.js.map

package/dist/triggers/slack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.js","sourceRoot":"","sources":["../../src/triggers/slack.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG1E,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;IACjC,OAAO,CAAC,MAAsB;QAC5B,OAAO,eAAe,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IACrD,CAAC;IACD,cAAc,CAAC,MAAsB;QACnC,OAAO,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,CAAC,OAAe;QACrB,OAAO,eAAe,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,OAAO,EAAE,eAAe,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;IACnG,CAAC;IACD,QAAQ,CAAC,KAAa;QACpB,OAAO,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IACnG,CAAC;CACF,CAAC,CAAC"}

package/dist/triggers.d.ts

@@ -0,0 +1,15 @@
+export type WebhookValue = null | boolean | number | string | readonly WebhookValue[] | {
+    readonly [key: string]: WebhookValue;
+};
+/** Recursive object subset; array and scalar leaves match exactly. */
+export type WebhookFilter = {
+    readonly [key: string]: WebhookValue;
+};
+export interface TriggerSource {
+    readonly kind: "webhook";
+    readonly name: string;
+    readonly filter?: WebhookFilter;
+}
+/** Plain, immutable data. Constructing a source opens no receiver. */
+export declare function webhook(name: string, filter?: WebhookFilter): TriggerSource;
+//# sourceMappingURL=triggers.d.ts.map

package/dist/triggers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../src/triggers.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GACvD,SAAS,YAAY,EAAE,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE,CAAC;AAEvE,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,sEAAsE;AACtE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,aAAa,CAS3E"}

package/dist/triggers.js

@@ -0,0 +1,43 @@
+/** Plain, immutable data. Constructing a source opens no receiver. */
+export function webhook(name, filter) {
+    if (typeof name !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(name)) {
+        throw new TypeError("webhook name must be 1-128 letters, digits, underscores or hyphens, starting with a letter or digit");
+    }
+    if (filter === undefined)
+        return Object.freeze({ kind: "webhook", name });
+    if (filter === null || typeof filter !== "object" || Array.isArray(filter)) {
+        throw new TypeError("webhook filter must be a JSON object");
+    }
+    return Object.freeze({ kind: "webhook", name, filter: snapshot(filter) });
+}
+function snapshot(value, ancestors = new Set()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value !== "object" || value === null || ancestors.has(value)) {
+        throw new TypeError("webhook filter must contain finite, acyclic JSON data");
+    }
+    const array = Array.isArray(value);
+    if (!array && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+        throw new TypeError("webhook filter must contain plain JSON objects");
+    }
+    ancestors.add(value);
+    const entries = [];
+    for (const key of Reflect.ownKeys(value)) {
+        if (array && key === "length")
+            continue;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (typeof key !== "string" || !descriptor.enumerable || !("value" in descriptor)) {
+            throw new TypeError("webhook filter must contain JSON data properties");
+        }
+        if (array && !/^(0|[1-9][0-9]*)$/.test(key))
+            throw new TypeError("invalid JSON array property");
+        entries.push([key, snapshot(descriptor.value, ancestors)]);
+    }
+    ancestors.delete(value);
+    if (array && entries.length !== value.length)
+        throw new TypeError("webhook filter arrays must not be sparse");
+    return Object.freeze(array ? entries.map(([, item]) => item) : Object.fromEntries(entries));
+}
+//# sourceMappingURL=triggers.js.map

package/dist/triggers.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/surface",
-  "version": "2.0.9",
+  "version": "2.0.10",
   "description": "TypeScript authoring surface for Relayflows.",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,6 +15,16 @@
       "types": "./dist/runtime.d.ts",
       "import": "./dist/runtime.js",
       "require": "./dist/runtime.js"
+    },
+    "./triggers": {
+      "types": "./dist/triggers/index.d.ts",
+      "import": "./dist/triggers/index.js",
+      "require": "./dist/triggers/index.js"
+    },
+    "./triggers/*": {
+      "types": "./dist/triggers/*.d.ts",
+      "import": "./dist/triggers/*.js",
+      "require": "./dist/triggers/*.js"
     }
   },
   "files": [
@@ -22,10 +32,12 @@
     "src"
   ],
   "scripts": {
+    "gen": "node ../../scripts/generate-helpers.mjs",
+    "gen:triggers": "node ../../scripts/generate-triggers.mjs",
     "build": "tsc",
     "prepare": "bun run build",
     "typecheck": "tsc --noEmit",
-    "typecheck:regressions": "tsc -p ../../regressions/tsconfig.json",
+    "typecheck:regressions": "tsc -p ../../regressions/tsconfig.json && tsc -p tsconfig.test.json && node scripts/check-generated-helpers.mjs",
     "typecheck:examples": "tsc -p ../../examples/tsconfig.json",
     "test": "bun run build && tsc -p tsconfig.test.json && vitest run"
   },
@@ -34,6 +46,7 @@
     "node": ">=20.19.0 || >=22.12.0"
   },
   "devDependencies": {
+    "@types/node": "^22.20.2",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"
   },
@@ -41,5 +54,11 @@
     "type": "git",
     "url": "git+https://github.com/AgentWorkforce/flows.git",
     "directory": "packages/surface"
+  },
+  "peerDependencies": {
+    "@relayfile/relay-helpers": "0.4.11"
+  },
+  "dependencies": {
+    "ai-hist": "0.4.1"
   }
 }

package/src/completion.ts

@@ -22,3 +22,6 @@ export const RUN_COMPLETION_REASONS = [
 ] as const;
 
 export type RunCompletionReason = (typeof RUN_COMPLETION_REASONS)[number];
+
+/** Authored outcomes include a human handoff; it is not a kernel terminal reason. */
+export type FlowCompletionReason = RunCompletionReason | 'needs_human';

package/src/context.ts

@@ -1,5 +1,7 @@
+import type { Helpers } from "./helpers/index.js";
+import type { MemoryHelper } from "./memory.js";
 import type { CloudHelper } from "./cloud.js";
-import type { RunCompletionReason } from "./completion.js";
+import type { FlowCompletionReason } from "./completion.js";
 import type { Step } from "./step.js";
 
 export interface AgentResult {
@@ -10,9 +12,22 @@ export interface AgentResult {
 export interface AgentOptions {
   task: string;
   workspace?: string;
-  /** Overrides a named declaration's (or the flow/project default's) CLI for this step only. */
   cli?: string;
-  /** Overrides a named declaration's model for this step only. No flow/project default exists for model. */
+  model?: string;
+  /** Working directory for the CLI subprocess; defaults to the flow-runner's cwd. */
+  cwd?: string;
+  /**
+   * Dispatch transport (flows#385). `'direct'` (default) spawns the CLI as a
+   * local subprocess. `'relay'` posts to agent-relay so the agent registers
+   * as a first-class workspace participant that DMs can steer.
+   */
+  transport?: 'direct' | 'relay';
+}
+
+export interface LlmOptions {
+  /** JSON Schema checked before the result is accepted by the journal. */
+  output: Record<string, unknown>;
+  cli?: string;
   model?: string;
 }
 
@@ -22,12 +37,17 @@ export interface AgentOptions {
  * This package declares the authoring contract only. It cannot construct a
  * context or execute a step, so all effects remain behind the journal client.
  */
-export interface Ctx {
-  run(command: string): Step<string>;
+export interface Ctx extends Helpers {
+  readonly mcp: Readonly<Record<string, Readonly<Record<string, (args: unknown) => Step<unknown>>>>>;
+  /** Command lease: milliseconds or a duration such as "5m"; default 30s, maximum 15m. */
+  run(command: string, options?: { timeout?: string | number }): Step<string>;
   llm(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;
+  /** JSON Schema validates the value at runtime; narrow unknown in author code. */
+  llm(prompt: string, options: LlmOptions): Step<unknown>;
   agent(name: string, options: AgentOptions): Step<AgentResult>;
   human(question: string, options: { to: string }): Promise<boolean>;
   dispatch<T>(flow: string, input: unknown): Promise<T>;
-  done(reason: RunCompletionReason): void;
+  done(reason: FlowCompletionReason): void;
   cloud: CloudHelper;
+  memory: MemoryHelper;
 }

package/src/effect-transport.ts

@@ -0,0 +1,59 @@
+import type { RelayClientOptions, RelayTransport } from '@relayfile/relay-helpers/transport';
+import type { Step } from './step.js';
+
+/** Promise-returning client verbs become lazy, journal-owned steps. */
+export type JournalHelper<T> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => Promise<infer R>
+    ? (...args: A) => Step<R>
+    : T[K] extends (...args: infer A) => infer R ? (...args: A) => R
+    : T[K] extends object ? JournalHelper<T[K]> : T[K];
+};
+export interface HelperCall {
+  type: 'effect';
+  provider: string;
+  verb: string;
+  args: unknown[];
+}
+export type EffectDispatcher = <T>(call: HelperCall) => Step<T>;
+export interface UnavailableHelper { readonly available: false }
+export type HelperFactory = (options: RelayClientOptions) => object;
+
+const unavailableTransport: RelayTransport = {
+  async read() { throw new Error('Helper I/O requires a journaled step'); },
+  async list() { throw new Error('Helper I/O requires a journaled step'); },
+  async write() { throw new Error('Helper I/O requires a journaled step'); },
+};
+
+export function bindHelper<T extends object>(provider: string, factory: (options: RelayClientOptions) => T, dispatch: EffectDispatcher): JournalHelper<T>;
+export function bindHelper(provider: string, factory: undefined, dispatch: EffectDispatcher): UnavailableHelper;
+export function bindHelper(provider: string, factory: HelperFactory | undefined, dispatch: EffectDispatcher): object {
+  if (!factory) return Object.freeze({ available: false });
+  function wrap(client: object, prefix = ''): object {
+    return Object.fromEntries(Object.entries(client).map(([key, value]) => {
+      const verb = `${prefix}${key}`;
+      if (typeof value === 'function') return [key, key === 'path'
+        ? value.bind(client)
+        : (...args: unknown[]) => {
+          while (args.length && args.at(-1) === undefined) args.pop();
+          return dispatch({ type: 'effect', provider, verb, args });
+        }];
+      return [key, value && typeof value === 'object' ? wrap(value, `${verb}.`) : value];
+    }));
+  }
+  return wrap(factory({ transport: unavailableTransport }));
+}
+
+/** Resolve only own, generated client methods; never arbitrary prototype members. */
+export async function invokeHelper(factory: HelperFactory, call: HelperCall, transport: RelayTransport): Promise<unknown> {
+  let target: unknown = factory({ transport });
+  const parts = call.verb.split('.');
+  for (const part of parts.slice(0, -1)) {
+    if (!target || typeof target !== 'object' || !Object.hasOwn(target, part)) throw new Error('Unknown helper resource');
+    target = (target as Record<string, unknown>)[part];
+  }
+  const verb = parts.at(-1)!;
+  if (!target || typeof target !== 'object' || !Object.hasOwn(target, verb) || verb === 'path') throw new Error('Unknown helper verb');
+  const method = (target as Record<string, unknown>)[verb];
+  if (typeof method !== 'function') throw new Error('Unknown helper verb');
+  return await method.apply(target, call.args) ?? null;
+}