@relayflows/surface 2.0.34 → 2.0.36

package/dist/activity.d.ts

@@ -0,0 +1,46 @@
+/** A duration in whole milliseconds or an unambiguous wall-clock literal. */
+export type ActivityDuration = number | string;
+/**
+ * Opaque provider event preserved by the journal. Providers may add fields;
+ * bodies must re-read provider state instead of treating this payload as truth.
+ */
+export interface EventFrame {
+    readonly type: string;
+    readonly payload?: unknown;
+    readonly [field: string]: unknown;
+}
+export type Wake = {
+    readonly kind: "events";
+    readonly events: readonly EventFrame[];
+    readonly offset: number;
+} | {
+    readonly kind: "idle";
+} | {
+    readonly kind: "deadline";
+    readonly pending: {
+        readonly from: number;
+        readonly to: number;
+    } | null;
+} | {
+    readonly kind: "overflow";
+    readonly retained: number;
+    readonly bytes: number;
+    readonly from: number;
+};
+/** Bounds are required so a body-level subscription cannot keep a run open forever. */
+export interface ActivityOptions {
+    /** Coalesce a burst until this long after its most recent frame. Defaults to zero. */
+    readonly settle?: ActivityDuration;
+    /** Per wake: return idle after this long without a buffered matching frame. */
+    readonly idle: ActivityDuration;
+    /** Absolute cap fixed when the subscription is opened. */
+    readonly deadline: ActivityDuration;
+    /** Include events caused by the run identity. Defaults to false. */
+    readonly includeSelf?: boolean;
+}
+/** A durable, bounded cursor over matching provider events. */
+export interface Activity {
+    next(): Promise<Wake>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=activity.d.ts.map

package/dist/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,MAAM,MAAM,IAAI,GACZ;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5F;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CAAE,GACtG;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5G,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,oEAAoE;IACpE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,+DAA+D;AAC/D,MAAM,WAAW,QAAQ;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/activity.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=activity.js.map

package/dist/activity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.js","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":""}

package/dist/context.d.ts

@@ -3,6 +3,8 @@ import type { MemoryHelper } from "./memory.js";
 import type { CloudCapabilities, CloudHelper } from "./cloud.js";
 import type { FlowCompletionReason } from "./completion.js";
 import type { Step } from "./step.js";
+import type { Activity, ActivityOptions } from "./activity.js";
+import type { TriggerSource } from "./triggers.js";
 export interface AgentResult {
     summary: string;
     /**
@@ -94,6 +96,15 @@ export interface LlmOptions {
     cli?: string;
     model?: string;
 }
+/** Durable receipt returned after a statically declared child flow succeeds. */
+export interface DispatchResult {
+    /** The child flow's declared name. */
+    name: string;
+    /** `success`; every other child verdict rejects the dispatch. */
+    completionReason: 'success';
+    /** The child's journaled completion detail, when it supplied one. */
+    completionDetail?: string;
+}
 /** The optional second argument to {@link Ctx.done}. */
 export interface DoneOptions {
     /** Why the flow reached this verdict; redacted, bounded, and journaled. */
@@ -133,6 +144,8 @@ export interface Ctx extends Helpers {
     /** 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>;
+    /** Open a durable, bounded event subscription for this running body. */
+    on(source: TriggerSource, options: ActivityOptions): Activity;
     /**
      * Ask a person a yes/no question and park until they answer. The run
      * parks durably (kernel `wait.human`); `flows answer <run> <wait> yes|no`
@@ -143,7 +156,12 @@ export interface Ctx extends Helpers {
     human(question: string, options: {
         to: string;
     }): Step<boolean>;
-    dispatch<T>(flow: string, input: unknown): Promise<T>;
+    /**
+     * Run a direct child declared in this flow's `use` header. The child shares
+     * this durable root, budget, worker capacity and Cloud graph; arbitrary
+     * paths and undeclared flow names are refused before the child body runs.
+     */
+    dispatch(flow: string, input: unknown): Step<DispatchResult>;
     /**
      * Run every installed implementation of a named hook in lock order and
      * AND-compose the booleans. With no implementations this is a journaled

package/dist/context.d.ts.map

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

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export type { EnrollmentReceipt, Heartbeat, JournalStep, RunJournal, ScheduleState, WorkerSummary, CloudHelper, CloudCapabilities, CloudBabysitterTurnCapability, CloudBabysitterTurnDelivery, CloudBabysitterTurnReceipt, } from "./cloud.js";
-export type { AgentOptions, AgentResult, DoneOptions, PermissionsSpec, LlmOptions, RunOptions, RunResult, Ctx } from "./context.js";
+export type { AgentOptions, AgentResult, DispatchResult, DoneOptions, PermissionsSpec, LlmOptions, RunOptions, RunResult, Ctx } from "./context.js";
+export type { Activity, ActivityDuration, ActivityOptions, EventFrame, Wake } from "./activity.js";
 export { COMPLETION_DETAIL_MAX_CODE_POINTS, COMPLETION_REASONS, RUN_COMPLETION_REASONS, FLOW_COMPLETION_REASONS, type CompletionReason, type RunCompletionReason, type FlowCompletionReason, } from "./completion.js";
 export type { Step, NamedGate, ReferencesInputNamedGate, SubprocessNamedGate, WordCountBoundsNamedGate, RegexMatchNamedGate, } from "./step.js";
 export { flow, type FlowHandle, type TriggeredFlowHandle, type FlowHeader, } from "./flow.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,iBAAiB,EACjB,SAAS,EACT,WAAW,EACX,UAAU,EACV,aAAa,EACb,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACpI,OAAO,EACL,iCAAiC,EACjC,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,IAAI,EACJ,SAAS,EACT,wBAAwB,EACxB,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,IAAI,EACJ,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,2BAA2B,EAC3B,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnH,OAAO,EAAE,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9H,OAAO,EACL,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,SAAS,EAC1F,KAAK,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,GACrF,MAAM,eAAe,CAAC;AACvB,cAAc,qBAAqB,CAAC;AACpC,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,iBAAiB,EACjB,SAAS,EACT,WAAW,EACX,UAAU,EACV,aAAa,EACb,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACpJ,YAAY,EAAE,QAAQ,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACnG,OAAO,EACL,iCAAiC,EACjC,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,IAAI,EACJ,SAAS,EACT,wBAAwB,EACxB,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,IAAI,EACJ,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,2BAA2B,EAC3B,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnH,OAAO,EAAE,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9H,OAAO,EACL,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,SAAS,EAC1F,KAAK,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,GACrF,MAAM,eAAe,CAAC;AACvB,cAAc,qBAAqB,CAAC;AACpC,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,iCAAiC,EACjC,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,GAIxB,MAAM,iBAAiB,CAAC;AASzB,OAAO,EACL,IAAI,GAIL,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,2BAA2B,GAO5B,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,OAAO,EAAwF,MAAM,eAAe,CAAC;AAC9H,OAAO,EACL,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,SAAS,GAE3F,MAAM,eAAe,CAAC;AACvB,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,OAAO,EACL,iCAAiC,EACjC,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,GAIxB,MAAM,iBAAiB,CAAC;AASzB,OAAO,EACL,IAAI,GAIL,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,2BAA2B,GAO5B,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,OAAO,EAAwF,MAAM,eAAe,CAAC;AAC9H,OAAO,EACL,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,SAAS,GAE3F,MAAM,eAAe,CAAC;AACvB,cAAc,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/surface",
-  "version": "2.0.34",
+  "version": "2.0.36",
   "description": "TypeScript authoring surface for Relayflows.",
   "type": "module",
   "main": "./dist/index.js",

package/src/activity.ts

@@ -0,0 +1,36 @@
+/** A duration in whole milliseconds or an unambiguous wall-clock literal. */
+export type ActivityDuration = number | string;
+
+/**
+ * Opaque provider event preserved by the journal. Providers may add fields;
+ * bodies must re-read provider state instead of treating this payload as truth.
+ */
+export interface EventFrame {
+  readonly type: string;
+  readonly payload?: unknown;
+  readonly [field: string]: unknown;
+}
+
+export type Wake =
+  | { readonly kind: "events"; readonly events: readonly EventFrame[]; readonly offset: number }
+  | { readonly kind: "idle" }
+  | { readonly kind: "deadline"; readonly pending: { readonly from: number; readonly to: number } | null }
+  | { readonly kind: "overflow"; readonly retained: number; readonly bytes: number; readonly from: number };
+
+/** Bounds are required so a body-level subscription cannot keep a run open forever. */
+export interface ActivityOptions {
+  /** Coalesce a burst until this long after its most recent frame. Defaults to zero. */
+  readonly settle?: ActivityDuration;
+  /** Per wake: return idle after this long without a buffered matching frame. */
+  readonly idle: ActivityDuration;
+  /** Absolute cap fixed when the subscription is opened. */
+  readonly deadline: ActivityDuration;
+  /** Include events caused by the run identity. Defaults to false. */
+  readonly includeSelf?: boolean;
+}
+
+/** A durable, bounded cursor over matching provider events. */
+export interface Activity {
+  next(): Promise<Wake>;
+  close(): Promise<void>;
+}

package/src/context.ts

@@ -3,6 +3,8 @@ import type { MemoryHelper } from "./memory.js";
 import type { CloudCapabilities, CloudHelper } from "./cloud.js";
 import type { FlowCompletionReason } from "./completion.js";
 import type { Step } from "./step.js";
+import type { Activity, ActivityOptions } from "./activity.js";
+import type { TriggerSource } from "./triggers.js";
 
 export interface AgentResult {
   summary: string;
@@ -101,6 +103,16 @@ export interface LlmOptions {
   model?: string;
 }
 
+/** Durable receipt returned after a statically declared child flow succeeds. */
+export interface DispatchResult {
+  /** The child flow's declared name. */
+  name: string;
+  /** `success`; every other child verdict rejects the dispatch. */
+  completionReason: 'success';
+  /** The child's journaled completion detail, when it supplied one. */
+  completionDetail?: string;
+}
+
 /** The optional second argument to {@link Ctx.done}. */
 export interface DoneOptions {
   /** Why the flow reached this verdict; redacted, bounded, and journaled. */
@@ -135,6 +147,8 @@ export interface Ctx extends Helpers {
   /** 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>;
+  /** Open a durable, bounded event subscription for this running body. */
+  on(source: TriggerSource, options: ActivityOptions): Activity;
   /**
    * Ask a person a yes/no question and park until they answer. The run
    * parks durably (kernel `wait.human`); `flows answer <run> <wait> yes|no`
@@ -143,7 +157,12 @@ export interface Ctx extends Helpers {
    * recorded with the question; it is not a delivery address.
    */
   human(question: string, options: { to: string }): Step<boolean>;
-  dispatch<T>(flow: string, input: unknown): Promise<T>;
+  /**
+   * Run a direct child declared in this flow's `use` header. The child shares
+   * this durable root, budget, worker capacity and Cloud graph; arbitrary
+   * paths and undeclared flow names are refused before the child body runs.
+   */
+  dispatch(flow: string, input: unknown): Step<DispatchResult>;
   /**
    * Run every installed implementation of a named hook in lock order and
    * AND-compose the booleans. With no implementations this is a journaled

package/src/index.ts

@@ -11,7 +11,8 @@ export type {
   CloudBabysitterTurnDelivery,
   CloudBabysitterTurnReceipt,
 } from "./cloud.js";
-export type { AgentOptions, AgentResult, DoneOptions, PermissionsSpec, LlmOptions, RunOptions, RunResult, Ctx } from "./context.js";
+export type { AgentOptions, AgentResult, DispatchResult, DoneOptions, PermissionsSpec, LlmOptions, RunOptions, RunResult, Ctx } from "./context.js";
+export type { Activity, ActivityDuration, ActivityOptions, EventFrame, Wake } from "./activity.js";
 export {
   COMPLETION_DETAIL_MAX_CODE_POINTS,
   COMPLETION_REASONS,