@relayflows/surface 2.0.8 → 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.8",
+  "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,6 +12,23 @@ export interface AgentResult {
 export interface AgentOptions {
   task: string;
   workspace?: string;
+  cli?: string;
+  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;
 }
 
 /**
@@ -18,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;
+}

package/src/flow.ts

@@ -1,21 +1,29 @@
+import { helperProviders } from "./helpers/providers.js";
+import type { Helpers } from "./helpers/index.js";
+type HelperTools = Partial<Record<keyof Helpers, boolean>>;
 import type { Ctx } from "./context.js";
+import { webhook, type TriggerSource } from "./triggers.js";
 
 /** Optional escalation header; the empty header is the common case. */
 export interface FlowHeader {
+  /** Relative paths to reusable authored flows composed by this body. */
+  use?: string[];
   identity?: string;
   memory?: { script?: boolean; agent?: boolean };
-  budget?: string;
-  tools?: { relayfile?: string[]; mcp?: string[] };
+  budget?: string | { tokens?: number; dollars?: number; wallclock?: string };
+  tools?: HelperTools & { relayfile?: string[]; mcp?: string[] };
   workspace?: string;
 }
 
 export type FlowBody<Input = unknown> = (f: Ctx, input: Input) => Promise<void>;
 
 export interface ReadonlyFlowHeader {
+  readonly use?: readonly string[];
   readonly identity?: string;
   readonly memory?: Readonly<{ script?: boolean; agent?: boolean }>;
-  readonly budget?: string;
-  readonly tools?: Readonly<{
+  readonly budget?: string | Readonly<{ tokens?: number; dollars?: number; wallclock?: string }>;
+  readonly tools?: Readonly<HelperTools & {
+    slack?: boolean;
     relayfile?: readonly string[];
     mcp?: readonly string[];
   }>;
@@ -27,15 +35,25 @@ export interface AuthoredFlowDefinition<Input = unknown> {
   readonly name: string;
   readonly header: ReadonlyFlowHeader;
   readonly body: FlowBody<Input>;
+  readonly handlers: readonly TriggerHandler[];
+}
+
+export interface TriggerHandler {
+  readonly trigger: TriggerSource;
+  readonly body: FlowBody;
 }
 
 /** Opaque authored-flow handle. Execution stays behind the journal runtime. */
 export interface FlowHandle {
   readonly name: string;
+  on<Event = Record<string, unknown>>(trigger: TriggerSource, body: FlowBody<Event>): TriggeredFlowHandle;
 }
 
+export interface TriggeredFlowHandle extends FlowHandle {}
+
 const definitions = new WeakMap<object, AuthoredFlowDefinition>();
 
+export function flow(name: string, header?: FlowHeader): FlowHandle;
 export function flow<Input = unknown>(name: string, body: FlowBody<Input>): FlowHandle;
 export function flow<Input = unknown>(
   name: string,
@@ -44,7 +62,7 @@ export function flow<Input = unknown>(
 ): FlowHandle;
 export function flow<Input = unknown>(
   name: string,
-  headerOrBody: FlowHeader | FlowBody<Input>,
+  headerOrBody: FlowHeader | FlowBody<Input> = {},
   body?: FlowBody<Input>,
 ): FlowHandle {
   const flowBody = typeof headerOrBody === "function" ? headerOrBody : body;
@@ -53,7 +71,7 @@ export function flow<Input = unknown>(
   if (name.trim().length === 0) {
     throw new TypeError("flow name must not be empty");
   }
-  if (typeof flowBody !== "function") {
+  if (flowBody !== undefined && typeof flowBody !== "function") {
     throw new TypeError(`flow "${name}" requires a body`);
   }
   assertFlowHeader(header, name);
@@ -61,9 +79,28 @@ export function flow<Input = unknown>(
   const definition: AuthoredFlowDefinition<Input> = Object.freeze({
     name,
     header: freezeHeader(header),
-    body: flowBody,
+    body: flowBody ?? (async () => { throw new TypeError(`flow "${name}" has no direct-run body`); }),
+    handlers: Object.freeze([]),
+  });
+  return makeHandle(definition as AuthoredFlowDefinition);
+}
+
+function makeHandle(definition: AuthoredFlowDefinition): FlowHandle {
+  const handle = { name: definition.name } as FlowHandle;
+  Object.defineProperty(handle, "on", {
+    value: <Event>(trigger: TriggerSource, body: FlowBody<Event>): TriggeredFlowHandle => {
+      if (typeof body !== "function") throw new TypeError("trigger handler requires a body");
+      assertHeaderObject(trigger, "trigger");
+      assertKnownKeys(trigger, ["kind", "name", "filter"], "trigger");
+      if (trigger.kind !== "webhook") throw new TypeError("unsupported trigger kind");
+      const source = webhook(trigger.name, trigger.filter);
+      return makeHandle(Object.freeze({
+        ...definition,
+        handlers: Object.freeze([...definition.handlers, Object.freeze({ trigger: source, body: body as FlowBody })]),
+      }));
+    },
   });
-  const handle: FlowHandle = Object.freeze({ name });
+  Object.freeze(handle);
   // One map holds definitions of many input types, so it is stored at the
   // default parameterisation and `getFlowDefinition<Input>` re-parameterises on
   // the way out. The cast is needed because `body` puts `Input` in a parameter
@@ -71,7 +108,7 @@ export function flow<Input = unknown>(
   // assignable to `AuthoredFlowDefinition<unknown>` even though every read
   // recovers the author's own type. Sound here because the handle-to-definition
   // pairing is 1:1 and both sides are keyed by the same authored flow.
-  definitions.set(handle, definition as AuthoredFlowDefinition);
+  definitions.set(handle, definition);
   return handle;
 }
 
@@ -79,7 +116,7 @@ export function flow<Input = unknown>(
  * Runtime bridge used by the SDK after it imports an authored `.flow.ts`.
  * The root package deliberately does not re-export this accessor.
  */
-export function getFlowDefinition<Input = unknown>(handle: FlowHandle): AuthoredFlowDefinition<Input> {
+export function getFlowDefinition<Input = unknown>(handle: Pick<FlowHandle, "name">): AuthoredFlowDefinition<Input> {
   if ((typeof handle !== "object" && typeof handle !== "function") || handle === null) {
     throw new TypeError("expected an @relayflows/surface flow handle");
   }
@@ -114,6 +151,7 @@ function isStoredDefinition(
 
 function freezeHeader(header: FlowHeader): ReadonlyFlowHeader {
   const unknownFields = Object.keys(header).filter((field) => ![
+    "use",
     "identity",
     "memory",
     "budget",
@@ -129,6 +167,8 @@ function freezeHeader(header: FlowHeader): ReadonlyFlowHeader {
   const tools = header.tools === undefined
     ? undefined
     : Object.freeze({
+        ...Object.fromEntries(helperProviders.filter(p => header.tools?.[p.namespace] !== undefined)
+          .map(p => [p.namespace, header.tools![p.namespace]])),
         ...(header.tools.relayfile === undefined
           ? {}
           : { relayfile: Object.freeze([...header.tools.relayfile]) }),
@@ -137,9 +177,10 @@ function freezeHeader(header: FlowHeader): ReadonlyFlowHeader {
           : { mcp: Object.freeze([...header.tools.mcp]) }),
       });
   return Object.freeze({
+    ...(header.use === undefined ? {} : { use: Object.freeze([...header.use]) }),
     ...(header.identity === undefined ? {} : { identity: header.identity }),
     ...(memory === undefined ? {} : { memory }),
-    ...(header.budget === undefined ? {} : { budget: header.budget }),
+    ...(header.budget === undefined ? {} : { budget: typeof header.budget === "string" ? header.budget : Object.freeze({ ...header.budget }) }),
     ...(tools === undefined ? {} : { tools }),
     ...(header.workspace === undefined ? {} : { workspace: header.workspace }),
   });
@@ -150,12 +191,27 @@ function assertFlowHeader(value: unknown, flowName: string): asserts value is Fl
   assertHeaderObject(value, at);
   assertKnownKeys(
     value,
-    ["identity", "memory", "budget", "tools", "workspace"],
+    ["use", "identity", "memory", "budget", "tools", "workspace"],
     at,
   );
   assertOptionalString(value, "identity", at);
-  assertOptionalString(value, "budget", at);
+  if (value.budget !== undefined && typeof value.budget !== "string") {
+    assertHeaderObject(value.budget, `${at}.budget`);
+    assertKnownKeys(value.budget, ["tokens", "dollars", "wallclock"], `${at}.budget`);
+    assertOptionalString(value.budget, "wallclock", at);
+    for (const key of ["tokens", "dollars"]) {
+      if (value.budget[key] !== undefined && typeof value.budget[key] !== "number") throw new TypeError(`budget_syntax_invalid: ${key} must be a number`);
+    }
+  }
   assertOptionalString(value, "workspace", at);
+  assertOptionalStringArray(value, "use", at);
+  if (value.use !== undefined) {
+    for (const path of value.use as string[]) {
+      if (!/^(?:\.\/|\.\.\/).+\.flow\.ts$/.test(path) || /[?#\\\\]/.test(path)) {
+        throw new TypeError(`${at}.use: expected relative .flow.ts paths`);
+      }
+    }
+  }
 
   if (value.memory !== undefined) {
     assertHeaderObject(value.memory, `${at}.memory`);
@@ -172,9 +228,10 @@ function assertFlowHeader(value: unknown, flowName: string): asserts value is Fl
     assertHeaderObject(value.tools, `${at}.tools`);
     assertKnownKeys(
       value.tools,
-      ["relayfile", "mcp"],
+      ["relayfile", "mcp", ...helperProviders.map(p => p.namespace)],
       `${at}.tools`,
     );
+    for (const { namespace } of helperProviders) assertOptionalBoolean(value.tools, namespace, `${at}.tools`);
     assertOptionalStringArray(value.tools, "relayfile", `${at}.tools`);
     assertOptionalStringArray(value.tools, "mcp", `${at}.tools`);
   }
@@ -238,8 +295,13 @@ function assertOptionalStringArray(
   const candidate = value[key];
   if (
     candidate !== undefined
-    && (!Array.isArray(candidate) || candidate.some((item) => typeof item !== "string"))
+    && (!Array.isArray(candidate) || Array.from(candidate).some((item) => typeof item !== "string"))
   ) {
     throw new TypeError(`${at}.${key}: expected an array of strings`);
   }
+  if (key === "use" && Array.isArray(candidate)
+    && (candidate.some((item) => item.trim().length === 0)
+      || new Set(candidate).size !== candidate.length)) {
+    throw new TypeError(`${at}.${key}: expected unique nonempty paths`);
+  }
 }