@relayflows/sdk 2.0.34 → 2.0.35

package/src/cloud-mirror-step.ts

@@ -152,6 +152,8 @@ export interface MirroredJournal {
   children: string[];
   /** Authored graph hints by step id, from an authored root's step index. */
   hints: Map<string, { label?: string; after?: string[] }>;
+  /** Authored completion receipts are durable evidence, not graph nodes. */
+  hidden: string[];
 }
 
 type Payload = Record<string, unknown>;
@@ -507,6 +509,7 @@ export function mirrorJournal(
     transcripts,
     children: index.children,
     hints: index.hints,
+    hidden: index.hidden,
   };
 }
 
@@ -522,7 +525,11 @@ export function mirrorJournal(
 function authoredIndex(
   events: readonly JournalEvent[],
   env: NodeJS.ProcessEnv,
-): { children: string[]; hints: Map<string, { label?: string; after?: string[] }> } {
+): {
+  children: string[];
+  hints: Map<string, { label?: string; after?: string[] }>;
+  hidden: string[];
+} {
   const messages: unknown[] = [];
   for (const event of events) {
     if (event.entry_type !== 'stream.appended') continue;
@@ -531,8 +538,15 @@ function authoredIndex(
   }
   const children: string[] = [];
   const hints = new Map<string, { label?: string; after?: string[] }>();
+  const hidden: string[] = [];
   for (const entry of foldAuthoredStepRecords(messages).values()) {
     if (/^[A-Za-z0-9][A-Za-z0-9_-]*$/u.test(entry.runId)) children.push(entry.runId);
+    // This is the executor's durable verdict receipt, not an authored unit of
+    // work. Only an entry in the authored root index can be hidden here, so a
+    // declarative step coincidentally named `complete-N` remains visible.
+    if (/(?:^|--)complete-[1-9][0-9]*$/.test(entry.step)) {
+      hidden.push(`${entry.runId}/${entry.step}`);
+    }
     const name = label(entry.label, env);
     const after = entry.after === undefined
       ? undefined
@@ -546,7 +560,7 @@ function authoredIndex(
       ...(after === undefined ? {} : { after }),
     });
   }
-  return { children, hints };
+  return { children, hints, hidden };
 }
 
 /**

package/src/cloud-mirror.ts

@@ -287,6 +287,7 @@ export function createRunMirror(options: RunMirrorOptions): RunMirror {
   const finals = new Map<string, { journalRunId: string; row: FinalStep }>();
   const transcripts = new Map<string, { stepName: string; attempts: Array<{ attempt: number; path: string }> }>();
   const hints = new Map<string, { label?: string; after?: string[] }>();
+  const hidden = new Set<string>();
   /** Live steps the cache cap dropped, by identity, so a capped view owns up to it. */
   const evicted = new Set<string>();
   /** Finished steps past the report cap, by identity. Counted, never sent. */
@@ -318,6 +319,7 @@ export function createRunMirror(options: RunMirrorOptions): RunMirror {
 
   const remember = (journalRunId: string, step: SnapshotStep, order: number): void => {
     const key = `${journalRunId}/${step.stepName}`;
+    if (hidden.has(key)) return;
     const existing = steps.get(key);
     const changed = existing === undefined || fingerprint(existing.step) !== fingerprint(step);
     steps.set(key, { step, order, changedAt: changed ? now() : existing!.changedAt });
@@ -365,19 +367,30 @@ export function createRunMirror(options: RunMirrorOptions): RunMirror {
         continue;
       }
       for (const child of folded.children) admit(child);
+      for (const key of folded.hidden) {
+        hidden.add(key);
+        steps.delete(key);
+        finals.delete(key);
+        transcripts.delete(key);
+      }
       for (const [key, hint] of folded.hints) {
         // Merge, never replace: a completion record can omit a label or an
         // edge the admission carried, and the view must not lose a step's
         // name between them.
         const existing = hints.get(key);
         hints.set(key, {
-          ...(hint.label ?? existing?.label ? { label: hint.label ?? existing?.label } : {}),
-          ...(hint.after ?? existing?.after ? { after: hint.after ?? existing?.after } : {}),
+          // The root's authored index is scanned before the child journal and
+          // carries causal edges across child runs. A child spec only knows
+          // its own single-step graph (`depends_on: []`), so it may fill a
+          // missing field but must never erase the root's richer answer.
+          ...(existing?.label ?? hint.label ? { label: existing?.label ?? hint.label } : {}),
+          ...(existing?.after ?? hint.after ? { after: existing?.after ?? hint.after } : {}),
         });
       }
       folded.steps.forEach((step, order) => remember(runId, step, order));
       for (const row of folded.finals) {
         const key = `${runId}/${row.stepName}`;
+        if (hidden.has(key)) continue;
         // The report cap bounds what this process holds, not just what it
         // sends: a run with ten thousand steps must not grow its own mirror.
         // Steps past it are counted by identity, so a step read twice is one

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) });
+}