@relayflows/sdk 2.0.34 → 2.0.36

package/src/protocol.ts

@@ -53,8 +53,16 @@ export type Verb =
   | 'effect.confirm'
   | 'step.complete'
   | 'step.wait'
+  | 'subscription.park'
   | 'event.emit'
   | 'event.submit'
+  | 'subscription.open'
+  | 'subscription.activate'
+  | 'subscription.deliver'
+  | 'subscription.inspect'
+  | 'subscription.fence_overflow'
+  | 'subscription.next'
+  | 'subscription.close'
   | 'channel.append'
   | 'channel.receive'
   | 'channel.ack'
@@ -362,6 +370,10 @@ export interface EventEmitParams {
   run_id: string;
   event_key: string;
   payload: unknown;
+  /** Provider delivery id for body activities. Required by Cloud; optional for legacy exact waits. */
+  delivery_id?: string;
+  /** Provider actor identity, used by the local router adapter for self filtering. */
+  actor?: string;
 }
 export interface EventEmitResult {
   matched: number;
@@ -388,6 +400,111 @@ export interface EventSubmitResult {
   run?: unknown;
 }
 
+/** Body-level activity open; the server acknowledges only after its fenced binding is durable. */
+export interface SubscriptionOpenParams {
+  run_id: string;
+  subscription_id: string;
+  event_types: string[];
+  pattern?: Record<string, unknown>;
+  settle_ms: number;
+  idle_ms: number;
+  deadline_ms: number;
+  include_self: boolean;
+}
+export type SubscriptionOpenResult =
+  | {
+    /** Immutable snapshot from the durable `subscription.prepared` entry. */
+    state: 'prepared';
+    subscription_id: string;
+    event_types: string[];
+    pattern?: Record<string, unknown>;
+    stream: string;
+    settle_ms: number;
+    idle_ms: number;
+    deadline_at_ms: number;
+    include_self: boolean;
+  }
+  | {
+    state: 'active';
+    subscription_id: string;
+    stream: string;
+    deadline_at_ms: number;
+  };
+
+/** Cloud supplies this receipt only after it has durably fenced its binding. */
+export interface SubscriptionActivateParams {
+  run_id: string;
+  subscription_id: string;
+  ingress_offset: number;
+  router_binding: Record<string, unknown>;
+}
+export interface SubscriptionActivateResult {
+  state: 'active';
+  subscription_id: string;
+  stream: string;
+  deadline_at_ms: number;
+}
+
+/** Targeted Cloud ingress; receipt must equal the journaled activation receipt. */
+export interface SubscriptionDeliverParams {
+  run_id: string;
+  subscription_id: string;
+  router_binding: Record<string, unknown>;
+  delivery_id: string;
+  frame: unknown;
+}
+export interface SubscriptionDeliverResult {
+  /** False for an idempotent duplicate or a frame that closes on overflow. */
+  appended: boolean;
+  reason?: 'duplicate' | 'overflow';
+}
+
+/** Read-only projection of the kernel's durable subscription records. */
+export interface SubscriptionSnapshot {
+  subscriptionId: string;
+  state: 'prepared' | 'active' | 'closed';
+  completionReason?: 'closed' | 'run_completed' | 'canceled' | 'deadline' | 'overflow';
+  routerBinding?: Record<string, unknown>;
+  ingressOffset?: number;
+  unreadFrames: number;
+  unreadBytes: number;
+  settleMs: number;
+  idleAtMs?: number;
+  deadlineAtMs: number;
+}
+export interface SubscriptionInspectParams { run_id: string }
+export interface SubscriptionInspectResult { subscriptions: SubscriptionSnapshot[] }
+export interface SubscriptionFenceOverflowParams {
+  run_id: string;
+  subscription_id: string;
+  router_binding: Record<string, unknown>;
+}
+export interface SubscriptionFenceOverflowResult { fenced: true }
+
+export interface SubscriptionNextParams {
+  run_id: string;
+  subscription_id: string;
+  /** Internal durable receipt for the prior normal wake, supplied with the next pull. */
+  acknowledge_wait_id?: string;
+  /** Body call ordinal: replay this pull's durable wake across process restarts. */
+  sequence?: number;
+}
+export type SubscriptionNextResult =
+  | { kind: 'suspended'; subscription_id: string; stream: string; deadline_at_ms: number }
+  | { kind: 'events'; events: unknown[]; offset: number; acknowledge_wait_id?: string }
+  | { kind: 'idle'; acknowledge_wait_id?: string }
+  | { kind: 'deadline'; pending: { from: number; to: number } | null }
+  | { kind: 'overflow'; retained: number; bytes: number; from: number };
+
+export interface SubscriptionCloseParams {
+  run_id: string;
+  subscription_id: string;
+  completion_reason: 'closed' | 'run_completed' | 'canceled';
+}
+export interface SubscriptionCloseResult {
+  closed: string;
+}
+
 export interface StreamAppendParams {
   run_id: string;
   stream: string;
@@ -441,8 +558,20 @@ export interface VerbContract {
   'effect.confirm': { params: EffectConfirmParams; result: EffectConfirmResult };
   'step.complete': { params: StepCompleteParams; result: StepCompleteResult };
   'step.wait': { params: StepWaitParams; result: StepWaitResult };
+  'subscription.park': {
+    params: { run_id: string; step_id: string; attempt: number; idempotency_key: string;
+      subscription_id: string; phase: 'activation' | 'event_wait' };
+    result: RunOutcome;
+  };
   'event.emit': { params: EventEmitParams; result: EventEmitResult };
   'event.submit': { params: EventSubmitParams; result: EventSubmitResult };
+  'subscription.open': { params: SubscriptionOpenParams; result: SubscriptionOpenResult };
+  'subscription.activate': { params: SubscriptionActivateParams; result: SubscriptionActivateResult };
+  'subscription.deliver': { params: SubscriptionDeliverParams; result: SubscriptionDeliverResult };
+  'subscription.inspect': { params: SubscriptionInspectParams; result: SubscriptionInspectResult };
+  'subscription.fence_overflow': { params: SubscriptionFenceOverflowParams; result: SubscriptionFenceOverflowResult };
+  'subscription.next': { params: SubscriptionNextParams; result: SubscriptionNextResult };
+  'subscription.close': { params: SubscriptionCloseParams; result: SubscriptionCloseResult };
   'stream.append': { params: StreamAppendParams; result: StreamAppendResult };
   'stream.read': { params: StreamReadParams; result: StreamReadResult };
   'journal.read': { params: JournalReadParams; result: JournalReadResult };

package/src/step-settling.ts

@@ -0,0 +1,19 @@
+/**
+ * A step's LAST settling `step.completed`: the verdict the kernel settled the
+ * step on. `retry` and `park` completions record an attempt the kernel did
+ * NOT settle it on (relayflowd-core `Disposition`) — crash recovery's
+ * `crashed`, a `worker_error` with iterations left — and precede the attempt
+ * that did, so neither the first completion nor a completion count is the
+ * step's verdict. Shared by the authored reader and the Bun result verifier,
+ * which must agree on which completion a claim is judged against.
+ */
+export function settlingCompletion<T>(entries: readonly T[], stepId: string): T | undefined {
+  return entries.filter(entry => {
+    if (typeof entry !== 'object' || entry === null) return false;
+    const { entry_type: type, step_id: step, payload } = entry as Record<string, unknown>;
+    if (type !== 'step.completed' || step !== stepId) return false;
+    const disposition = typeof payload === 'object' && payload !== null
+      ? (payload as Record<string, unknown>)['disposition'] : undefined;
+    return disposition !== 'retry' && disposition !== 'park';
+  }).at(-1);
+}

package/src/worker-slots.ts

@@ -7,6 +7,16 @@ export function isAgentCapacity(value: unknown): value is number {
   return Number.isInteger(value) && (value as number) >= 1 && (value as number) <= MAX_LOCAL_AGENT_CAPACITY;
 }
 
+export interface WorkerSlotScope {
+  run<T>(work: () => Promise<T>): Promise<T>;
+  /** Refuse this flow's queued/future work without closing the shared pool. */
+  close(reason: unknown): void;
+}
+
+interface ScopeState {
+  closed?: { readonly reason: unknown };
+}
+
 /**
  * First-come admission to a worker that holds `capacity` dispatches at once.
  *
@@ -19,7 +29,11 @@ export function isAgentCapacity(value: unknown): value is number {
  */
 export class WorkerSlots {
   private held = 0;
-  private readonly waiting: Array<{ resolve: () => void; reject: (reason: unknown) => void }> = [];
+  private readonly waiting: Array<{
+    resolve: () => void;
+    reject: (reason: unknown) => void;
+    scope?: ScopeState;
+  }> = [];
   private closed: { readonly reason: unknown } | undefined;
 
   constructor(readonly capacity: number) {
@@ -27,18 +41,37 @@ export class WorkerSlots {
   }
 
   async run<T>(work: () => Promise<T>): Promise<T> {
+    return this.runInScope(work);
+  }
+
+  /** One independently closable admission scope over this shared capacity. */
+  scope(): WorkerSlotScope {
+    const scope: ScopeState = {};
+    return Object.freeze({
+      run: <T>(work: () => Promise<T>) => this.runInScope(work, scope),
+      close: (reason: unknown) => this.closeScope(scope, reason),
+    });
+  }
+
+  private async runInScope<T>(work: () => Promise<T>, scope?: ScopeState): Promise<T> {
     if (this.closed !== undefined) throw this.closed.reason;
+    if (scope?.closed !== undefined) throw scope.closed.reason;
     if (this.held < this.capacity) this.held++;
     // A released slot is handed straight to the next waiter, so `held` never
     // dips below capacity while anyone is queued and no later caller can jump it.
     else {
-      await new Promise<void>((resolve, reject) => this.waiting.push({ resolve, reject }));
+      await new Promise<void>((resolve, reject) => this.waiting.push({ resolve, reject, scope }));
       // Woken with the slot, but the body may have failed in between (see release).
       const closed = this.closedReason();
       if (closed !== undefined) {
         this.release();
         throw closed.reason;
       }
+      const scopeClosed = scopeClosedReason(scope);
+      if (scopeClosed !== undefined) {
+        this.release();
+        throw scopeClosed.reason;
+      }
     }
     try {
       return await work();
@@ -66,17 +99,28 @@ export class WorkerSlots {
       return;
     }
     setImmediate(() => {
-      if (this.closed === undefined) {
+      if (this.closed === undefined && next.scope?.closed === undefined) {
         next.resolve();
         return;
       }
       // Closed meanwhile. `close` could not see this waiter (already taken off
       // the queue), so refuse it here, and pass the slot on instead of leaking it.
-      next.reject(this.closed.reason);
+      next.reject(this.closed?.reason ?? next.scope!.closed!.reason);
       this.release();
     });
   }
 
+  private closeScope(scope: ScopeState, reason: unknown): void {
+    if (scope.closed !== undefined) return;
+    scope.closed = { reason };
+    for (let index = this.waiting.length - 1; index >= 0; index--) {
+      const waiter = this.waiting[index]!;
+      if (waiter.scope !== scope) continue;
+      this.waiting.splice(index, 1);
+      waiter.reject(reason);
+    }
+  }
+
   /**
    * Refuse every queued and future admission with `reason`; work already
    * holding a slot is not interrupted. The authored body calls this when it
@@ -90,3 +134,18 @@ export class WorkerSlots {
     for (const waiter of this.waiting.splice(0)) waiter.reject(reason);
   }
 }
+
+/** Read through a call so a check after an `await` is not narrowed away. */
+function scopeClosedReason(scope?: ScopeState): { readonly reason: unknown } | undefined {
+  return scope?.closed;
+}
+
+/** One run-tree-wide capacity pool, shared by parent and child flows. */
+export interface AuthoredWorkerSlots {
+  readonly agent: WorkerSlots;
+  readonly llm: WorkerSlots;
+}
+
+export function authoredWorkerSlots(capacity: number): AuthoredWorkerSlots {
+  return Object.freeze({ agent: new WorkerSlots(capacity), llm: new WorkerSlots(capacity) });
+}