@autonome-research/thread-phase 3.0.0

package/dist/patterns/parallel-phases.js

@@ -0,0 +1,77 @@
+/**
+ * parallel-phases — run several phases concurrently as one composite phase.
+ *
+ * The framework treats pipelines as an ordered array, which covers linear
+ * flow, conditional skip (`intentGate`), and self-iteration
+ * (`whileCondition`). The one DAG shape it doesn't natively express is
+ * "run two independent branches at the same time, then continue when
+ * both finish." That's what this pattern is for.
+ *
+ * Semantics:
+ *   - Sub-phases share the parent `ctx`. If two branches both write to the
+ *     same field, last-write-wins. Keep branches' ctx writes disjoint.
+ *   - Events from all branches interleave into the composite phase's
+ *     output stream in arrival order.
+ *   - If a sub-phase throws, the composite re-throws (after letting other
+ *     branches finish what they're doing — no in-flight cancellation).
+ *   - If a sub-phase sets `ctx.stop`, sibling branches still run to
+ *     completion. The orchestrator's stop check fires AFTER the composite
+ *     phase returns, halting subsequent top-level phases.
+ *
+ * For data-dependent fan-in, write each branch's output to a distinct ctx
+ * field; a downstream phase reads them all via `requireCtx`. That's a
+ * complete DAG-edge expression without a graph framework.
+ */
+export function parallelPhases(phaseName, phases) {
+    return {
+        name: phaseName,
+        async *run(ctx) {
+            if (phases.length === 0)
+                return;
+            // Producer/consumer: each sub-phase pushes events into a shared queue;
+            // the composite generator drains the queue and yields downstream.
+            const queue = [];
+            let resolveWaiter = null;
+            const wake = () => {
+                const fn = resolveWaiter;
+                resolveWaiter = null;
+                fn?.();
+            };
+            const wait = () => new Promise((r) => (resolveWaiter = r));
+            let errored = null;
+            let running = phases.length;
+            const drain = async (phase) => {
+                try {
+                    for await (const ev of phase.run(ctx)) {
+                        queue.push(ev);
+                        wake();
+                        if (errored)
+                            return;
+                    }
+                }
+                catch (err) {
+                    if (!errored)
+                        errored = err;
+                }
+                finally {
+                    running--;
+                    wake();
+                }
+            };
+            const allDone = Promise.all(phases.map(drain));
+            while (running > 0 || queue.length > 0) {
+                if (errored && queue.length === 0)
+                    break;
+                if (queue.length === 0) {
+                    await Promise.race([wait(), allDone]);
+                    continue;
+                }
+                yield queue.shift();
+            }
+            await allDone;
+            if (errored)
+                throw errored;
+        },
+    };
+}
+//# sourceMappingURL=parallel-phases.js.map

package/dist/patterns/parallel-phases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-phases.js","sourceRoot":"","sources":["../../src/patterns/parallel-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,MAAM,UAAU,cAAc,CAI5B,SAAiB,EACjB,MAA0C;IAE1C,OAAO;QACL,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG;YACZ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YAEhC,uEAAuE;YACvE,kEAAkE;YAClE,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,IAAI,aAAa,GAAwB,IAAI,CAAC;YAC9C,MAAM,IAAI,GAAG,GAAG,EAAE;gBAChB,MAAM,EAAE,GAAG,aAAa,CAAC;gBACzB,aAAa,GAAG,IAAI,CAAC;gBACrB,EAAE,EAAE,EAAE,CAAC;YACT,CAAC,CAAC;YACF,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC;YAEjE,IAAI,OAAO,GAAY,IAAI,CAAC;YAC5B,IAAI,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;YAE5B,MAAM,KAAK,GAAG,KAAK,EAAE,KAA0B,EAAiB,EAAE;gBAChE,IAAI,CAAC;oBACH,IAAI,KAAK,EAAE,MAAM,EAAE,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;wBACtC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;wBACf,IAAI,EAAE,CAAC;wBACP,IAAI,OAAO;4BAAE,OAAO;oBACtB,CAAC;gBACH,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAI,CAAC,OAAO;wBAAE,OAAO,GAAG,GAAG,CAAC;gBAC9B,CAAC;wBAAS,CAAC;oBACT,OAAO,EAAE,CAAC;oBACV,IAAI,EAAE,CAAC;gBACT,CAAC;YACH,CAAC,CAAC;YAEF,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;YAE/C,OAAO,OAAO,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvC,IAAI,OAAO,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;oBAAE,MAAM;gBACzC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACvB,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;oBACtC,SAAS;gBACX,CAAC;gBACD,MAAM,KAAK,CAAC,KAAK,EAAG,CAAC;YACvB,CAAC;YAED,MAAM,OAAO,CAAC;YACd,IAAI,OAAO;gBAAE,MAAM,OAAO,CAAC;QAC7B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/patterns/preflight-confidence.d.ts

@@ -0,0 +1,20 @@
+/**
+ * preflight-confidence — assess feasibility before spending big-model tokens.
+ *
+ * Run a fast, cheap check (often a metadata read or small LLM call) that
+ * returns a typed score. The pipeline can either surface the score and
+ * continue, or stop on insufficient signal.
+ */
+import type { BasePipelineContext, Phase } from '../phase.js';
+export interface PreflightOptions<TCtx extends BasePipelineContext, TScore> {
+    /** Compute the score. May be an LLM call, metadata read, or pure logic. */
+    assess: (ctx: TCtx) => Promise<TScore>;
+    /** Stash the score on ctx (typed by the caller's context type). */
+    writeTo: (ctx: TCtx, score: TScore) => void;
+    /** Optional: human-readable description appended as a `content` event. */
+    describe?: (score: TScore) => string;
+    /** Optional: return a non-null reason to halt the pipeline. */
+    stopIf?: (score: TScore) => string | null;
+}
+export declare function preflightConfidence<TCtx extends BasePipelineContext, TScore>(phaseName: string, options: PreflightOptions<TCtx, TScore>): Phase<TCtx>;
+//# sourceMappingURL=preflight-confidence.d.ts.map

package/dist/patterns/preflight-confidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight-confidence.d.ts","sourceRoot":"","sources":["../../src/patterns/preflight-confidence.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAE9D,MAAM,WAAW,gBAAgB,CAAC,IAAI,SAAS,mBAAmB,EAAE,MAAM;IACxE,2EAA2E;IAC3E,MAAM,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,mEAAmE;IACnE,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,wBAAgB,mBAAmB,CAAC,IAAI,SAAS,mBAAmB,EAAE,MAAM,EAC1E,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,GACtC,KAAK,CAAC,IAAI,CAAC,CAgCb"}

package/dist/patterns/preflight-confidence.js

@@ -0,0 +1,38 @@
+/**
+ * preflight-confidence — assess feasibility before spending big-model tokens.
+ *
+ * Run a fast, cheap check (often a metadata read or small LLM call) that
+ * returns a typed score. The pipeline can either surface the score and
+ * continue, or stop on insufficient signal.
+ */
+export function preflightConfidence(phaseName, options) {
+    return {
+        name: phaseName,
+        async *run(ctx) {
+            let score;
+            try {
+                score = await options.assess(ctx);
+            }
+            catch (err) {
+                const e = err;
+                yield {
+                    type: 'agent_activity',
+                    agent: phaseName,
+                    action: 'error',
+                    detail: e.message?.slice(0, 120),
+                };
+                return;
+            }
+            options.writeTo(ctx, score);
+            yield { type: 'data', key: phaseName, value: score };
+            if (options.describe) {
+                yield { type: 'content', content: `${options.describe(score)}\n` };
+            }
+            const stopReason = options.stopIf?.(score);
+            if (stopReason !== null && stopReason !== undefined) {
+                ctx.stop = { reason: stopReason };
+            }
+        },
+    };
+}
+//# sourceMappingURL=preflight-confidence.js.map

package/dist/patterns/preflight-confidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight-confidence.js","sourceRoot":"","sources":["../../src/patterns/preflight-confidence.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,MAAM,UAAU,mBAAmB,CACjC,SAAiB,EACjB,OAAuC;IAEvC,OAAO;QACL,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG;YACZ,IAAI,KAAa,CAAC;YAClB,IAAI,CAAC;gBACH,KAAK,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpC,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,MAAM,CAAC,GAAG,GAA2B,CAAC;gBACtC,MAAM;oBACJ,IAAI,EAAE,gBAAgB;oBACtB,KAAK,EAAE,SAAS;oBAChB,MAAM,EAAE,OAAO;oBACf,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;iBACjC,CAAC;gBACF,OAAO;YACT,CAAC;YAED,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAE5B,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;YAErD,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACrB,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACrE,CAAC;YAED,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;YAC3C,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBACpD,GAAG,CAAC,IAAI,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;YACpC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/patterns/spot-check.d.ts

@@ -0,0 +1,19 @@
+/**
+ * spot-check — verify a sample of typed claims from a prior phase.
+ *
+ * Pattern: extract a list of claims from an upstream artifact (synthesis,
+ * report, draft), verify a capped subset in parallel, stash the results.
+ */
+import type { BasePipelineContext, Phase } from '../phase.js';
+export interface SpotCheckOptions<TCtx extends BasePipelineContext, TClaim, TResult> {
+    /** Pull the candidate claims from ctx (typically off a prior phase's output). */
+    extractClaims: (ctx: TCtx) => TClaim[];
+    /** Verify a single claim. Often runs an agent with read-only tools. */
+    verify: (claim: TClaim, ctx: TCtx) => Promise<TResult>;
+    /** Stash results on ctx. */
+    writeTo: (ctx: TCtx, results: TResult[]) => void;
+    /** Cap concurrent verifications. Default 5. */
+    maxClaims?: number;
+}
+export declare function spotCheck<TCtx extends BasePipelineContext, TClaim, TResult>(phaseName: string, options: SpotCheckOptions<TCtx, TClaim, TResult>): Phase<TCtx>;
+//# sourceMappingURL=spot-check.d.ts.map

package/dist/patterns/spot-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spot-check.d.ts","sourceRoot":"","sources":["../../src/patterns/spot-check.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAG9D,MAAM,WAAW,gBAAgB,CAAC,IAAI,SAAS,mBAAmB,EAAE,MAAM,EAAE,OAAO;IACjF,iFAAiF;IACjF,aAAa,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,MAAM,EAAE,CAAC;IACvC,uEAAuE;IACvE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,4BAA4B;IAC5B,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACjD,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,SAAS,CAAC,IAAI,SAAS,mBAAmB,EAAE,MAAM,EAAE,OAAO,EACzE,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,GAC/C,KAAK,CAAC,IAAI,CAAC,CA4Bb"}

package/dist/patterns/spot-check.js

@@ -0,0 +1,33 @@
+/**
+ * spot-check — verify a sample of typed claims from a prior phase.
+ *
+ * Pattern: extract a list of claims from an upstream artifact (synthesis,
+ * report, draft), verify a capped subset in parallel, stash the results.
+ */
+import { parallelFanout } from './parallel-fanout.js';
+export function spotCheck(phaseName, options) {
+    return {
+        name: phaseName,
+        async *run(ctx) {
+            const allClaims = options.extractClaims(ctx);
+            const max = options.maxClaims ?? 5;
+            const claims = allClaims.slice(0, max);
+            yield {
+                type: 'phase',
+                phase: phaseName,
+                detail: `Verifying ${claims.length}/${allClaims.length} claim(s)`,
+                counts: { claims: claims.length, total: allClaims.length },
+            };
+            if (claims.length === 0) {
+                options.writeTo(ctx, []);
+                return;
+            }
+            const results = await parallelFanout({
+                items: claims,
+                runner: (claim) => options.verify(claim, ctx),
+            });
+            options.writeTo(ctx, results);
+        },
+    };
+}
+//# sourceMappingURL=spot-check.js.map

package/dist/patterns/spot-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spot-check.js","sourceRoot":"","sources":["../../src/patterns/spot-check.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAatD,MAAM,UAAU,SAAS,CACvB,SAAiB,EACjB,OAAgD;IAEhD,OAAO;QACL,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG;YACZ,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;YAC7C,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC;YACnC,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YAEvC,MAAM;gBACJ,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,SAAS;gBAChB,MAAM,EAAE,aAAa,MAAM,CAAC,MAAM,IAAI,SAAS,CAAC,MAAM,WAAW;gBACjE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE;aAC3D,CAAC;YAEF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACxB,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBACzB,OAAO;YACT,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC;gBACnC,KAAK,EAAE,MAAM;gBACb,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC;aAC9C,CAAC,CAAC;YAEH,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/patterns/sub-pipeline.d.ts

@@ -0,0 +1,84 @@
+/**
+ * subPipeline — compose a registered (or inline) pipeline as a phase
+ * inside another pipeline.
+ *
+ * Two surface forms:
+ *
+ *   - **`subPipeline(name, options)`** — higher-order pattern returning a
+ *     `Phase<TOuterCtx>`. Compose like any other phase.
+ *   - **`runSubPipeline(spec, options)`** — free function for imperative
+ *     use inside phase bodies. Returns `{ ctx, summary }`.
+ *
+ * The inner pipeline gets:
+ *   - a fresh `PipelineCache` (cache scopes are isolated)
+ *   - the outer ctx's `signal` (cancellation propagates down)
+ *
+ * Events from the inner pipeline flatten into the outer event stream
+ * via `yield*` — JobStore consumers, SSE listeners, and the orchestrator
+ * see one continuous stream.
+ */
+import type { BasePipelineContext, Phase } from '../phase.js';
+/**
+ * The inner pipeline spec. Either a direct `{ phases, ctx }` object, or a
+ * lazy resolver returning one (or `undefined` if not found). The CLI uses
+ * the resolver form to look up registered pipelines by name without making
+ * the core depend on the Registry.
+ */
+export type SubPipelineSource<TInnerCtx extends BasePipelineContext> = {
+    phases: ReadonlyArray<Phase<TInnerCtx>>;
+    ctx: TInnerCtx;
+} | (() => {
+    phases: ReadonlyArray<Phase<TInnerCtx>>;
+    ctx: TInnerCtx;
+} | undefined);
+export interface SubPipelineOptions<TOuterCtx extends BasePipelineContext, TInnerCtx extends BasePipelineContext> {
+    /** Inner pipeline source: direct object or lazy resolver. */
+    pipeline: SubPipelineSource<TInnerCtx>;
+    /**
+     * Map outer ctx to the inner pipeline's starting ctx. Optional — if
+     * omitted, the inner pipeline starts with its own ctx as supplied by the
+     * source (the outer's `signal` is still wired in either way).
+     */
+    mapInput?: (outer: TOuterCtx) => TInnerCtx;
+    /**
+     * Merge the inner pipeline's terminal state back into outer ctx. Optional
+     * — if omitted, the inner's outputs are discarded.
+     */
+    mapOutput?: (outer: TOuterCtx, inner: TInnerCtx) => void;
+}
+/** A higher-order pattern returning a `Phase<TOuterCtx>`. */
+export declare function subPipeline<TOuterCtx extends BasePipelineContext, TInnerCtx extends BasePipelineContext>(name: string, options: SubPipelineOptions<TOuterCtx, TInnerCtx>): Phase<TOuterCtx>;
+/**
+ * Type-inferred convenience over `subPipeline` for the direct-object case.
+ * `TInnerCtx` is inferred from `source.ctx`, so callers only spell the outer
+ * ctx generic (and often not even that):
+ *
+ *   subPipelineOf('inner', innerSpec, { mapOutput: ... })
+ *
+ * vs. the more verbose `subPipeline<MyOuter, MyInner>(...)`. For the lazy
+ * registry-lookup case, use `subPipeline` directly — the resolver form needs
+ * explicit generics anyway.
+ */
+export declare function subPipelineOf<TInnerCtx extends BasePipelineContext, TOuterCtx extends BasePipelineContext = BasePipelineContext>(name: string, source: {
+    phases: ReadonlyArray<Phase<TInnerCtx>>;
+    ctx: TInnerCtx;
+}, mapping?: Omit<SubPipelineOptions<TOuterCtx, TInnerCtx>, 'pipeline'>): Phase<TOuterCtx>;
+/**
+ * Imperative form: invoke an inner pipeline from inside a phase body.
+ * Returns the inner ctx (post-run) and the pipeline summary. Phase
+ * exceptions in the inner pipeline propagate as rejections.
+ */
+export declare function runSubPipeline<TInnerCtx extends BasePipelineContext>(source: SubPipelineSource<TInnerCtx>, options?: {
+    /** Optional outer signal to propagate into the inner pipeline's ctx. */
+    signal?: AbortSignal;
+    /** Optional override of the inner ctx (otherwise source's ctx is used). */
+    ctx?: TInnerCtx;
+}): Promise<{
+    ctx: TInnerCtx;
+    summary: {
+        status: 'completed' | 'stopped';
+        reason?: string;
+        eventCount: number;
+    };
+}>;
+//# sourceMappingURL=sub-pipeline.d.ts.map

package/dist/patterns/sub-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-pipeline.d.ts","sourceRoot":"","sources":["../../src/patterns/sub-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EACV,mBAAmB,EACnB,KAAK,EAEN,MAAM,aAAa,CAAC;AAGrB;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,SAAS,SAAS,mBAAmB,IAC/D;IAAE,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAAC,GAAG,EAAE,SAAS,CAAA;CAAE,GAC3D,CAAC,MAAM;IAAE,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAAC,GAAG,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CAAC,CAAC;AAEpF,MAAM,WAAW,kBAAkB,CACjC,SAAS,SAAS,mBAAmB,EACrC,SAAS,SAAS,mBAAmB;IAErC,6DAA6D;IAC7D,QAAQ,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,SAAS,CAAC;IAC3C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CAC1D;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CACzB,SAAS,SAAS,mBAAmB,EACrC,SAAS,SAAS,mBAAmB,EAErC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kBAAkB,CAAC,SAAS,EAAE,SAAS,CAAC,GAChD,KAAK,CAAC,SAAS,CAAC,CA8BlB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,SAAS,SAAS,mBAAmB,EACrC,SAAS,SAAS,mBAAmB,GAAG,mBAAmB,EAE3D,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;IAAE,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACnE,OAAO,CAAC,EAAE,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,UAAU,CAAC,GACnE,KAAK,CAAC,SAAS,CAAC,CAKlB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,SAAS,SAAS,mBAAmB,EAErC,MAAM,EAAE,iBAAiB,CAAC,SAAS,CAAC,EACpC,OAAO,GAAE;IACP,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,SAAS,CAAC;CACZ,GACL,OAAO,CAAC;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE;QAAE,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,CA4BhH"}

package/dist/patterns/sub-pipeline.js

@@ -0,0 +1,90 @@
+/**
+ * subPipeline — compose a registered (or inline) pipeline as a phase
+ * inside another pipeline.
+ *
+ * Two surface forms:
+ *
+ *   - **`subPipeline(name, options)`** — higher-order pattern returning a
+ *     `Phase<TOuterCtx>`. Compose like any other phase.
+ *   - **`runSubPipeline(spec, options)`** — free function for imperative
+ *     use inside phase bodies. Returns `{ ctx, summary }`.
+ *
+ * The inner pipeline gets:
+ *   - a fresh `PipelineCache` (cache scopes are isolated)
+ *   - the outer ctx's `signal` (cancellation propagates down)
+ *
+ * Events from the inner pipeline flatten into the outer event stream
+ * via `yield*` — JobStore consumers, SSE listeners, and the orchestrator
+ * see one continuous stream.
+ */
+import { runPipeline } from '../orchestrator.js';
+import { PipelineCache } from '../cache.js';
+/** A higher-order pattern returning a `Phase<TOuterCtx>`. */
+export function subPipeline(name, options) {
+    return {
+        name,
+        async *run(outer) {
+            const source = typeof options.pipeline === 'function'
+                ? options.pipeline()
+                : options.pipeline;
+            if (!source) {
+                throw new Error(`subPipeline "${name}": pipeline resolver returned undefined`);
+            }
+            const inner = options.mapInput
+                ? options.mapInput(outer)
+                : source.ctx;
+            // Isolate the inner pipeline's cache; propagate the outer's signal.
+            inner.cache = new PipelineCache();
+            inner.signal = outer.signal;
+            yield* runPipeline(source.phases, inner);
+            options.mapOutput?.(outer, inner);
+        },
+    };
+}
+/**
+ * Type-inferred convenience over `subPipeline` for the direct-object case.
+ * `TInnerCtx` is inferred from `source.ctx`, so callers only spell the outer
+ * ctx generic (and often not even that):
+ *
+ *   subPipelineOf('inner', innerSpec, { mapOutput: ... })
+ *
+ * vs. the more verbose `subPipeline<MyOuter, MyInner>(...)`. For the lazy
+ * registry-lookup case, use `subPipeline` directly — the resolver form needs
+ * explicit generics anyway.
+ */
+export function subPipelineOf(name, source, mapping) {
+    return subPipeline(name, {
+        pipeline: source,
+        ...mapping,
+    });
+}
+/**
+ * Imperative form: invoke an inner pipeline from inside a phase body.
+ * Returns the inner ctx (post-run) and the pipeline summary. Phase
+ * exceptions in the inner pipeline propagate as rejections.
+ */
+export async function runSubPipeline(source, options = {}) {
+    const resolved = typeof source === 'function' ? source() : source;
+    if (!resolved) {
+        throw new Error('runSubPipeline: pipeline resolver returned undefined');
+    }
+    const inner = options.ctx ?? resolved.ctx;
+    inner.cache = new PipelineCache();
+    if (options.signal)
+        inner.signal = options.signal;
+    let eventCount = 0;
+    let stopReason;
+    for await (const event of runPipeline(resolved.phases, inner)) {
+        eventCount++;
+        if (event.type === 'done') {
+            stopReason = event.reason;
+        }
+    }
+    return {
+        ctx: inner,
+        summary: stopReason !== undefined
+            ? { status: 'stopped', reason: stopReason, eventCount }
+            : { status: 'completed', eventCount },
+    };
+}
+//# sourceMappingURL=sub-pipeline.js.map

package/dist/patterns/sub-pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-pipeline.js","sourceRoot":"","sources":["../../src/patterns/sub-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA+B5C,6DAA6D;AAC7D,MAAM,UAAU,WAAW,CAIzB,IAAY,EACZ,OAAiD;IAEjD,OAAO;QACL,IAAI;QACJ,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK;YACd,MAAM,MAAM,GACV,OAAO,OAAO,CAAC,QAAQ,KAAK,UAAU;gBACpC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE;gBACpB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;YACvB,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CACb,gBAAgB,IAAI,yCAAyC,CAC9D,CAAC;YACJ,CAAC;YAED,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ;gBAC5B,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;gBACzB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;YAEf,oEAAoE;YACnE,KAAkC,CAAC,KAAK,GAAG,IAAI,aAAa,EAAE,CAAC;YAChE,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YAE5B,KAAK,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAGtC,CAAC;YAEF,OAAO,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAI3B,IAAY,EACZ,MAAmE,EACnE,OAAoE;IAEpE,OAAO,WAAW,CAAuB,IAAI,EAAE;QAC7C,QAAQ,EAAE,MAAM;QAChB,GAAG,OAAO;KACX,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAGlC,MAAoC,EACpC,UAKI,EAAE;IAEN,MAAM,QAAQ,GACZ,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IACnD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC;IACzC,KAAkC,CAAC,KAAK,GAAG,IAAI,aAAa,EAAE,CAAC;IAChE,IAAI,OAAO,CAAC,MAAM;QAAE,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAElD,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,UAA8B,CAAC;IAEnC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,WAAW,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;QAC9D,UAAU,EAAE,CAAC;QACb,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1B,UAAU,GAAI,KAA6B,CAAC,MAAM,CAAC;QACrD,CAAC;IACH,CAAC;IAED,OAAO;QACL,GAAG,EAAE,KAAK;QACV,OAAO,EACL,UAAU,KAAK,SAAS;YACtB,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE;YACvD,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE;KAC1C,CAAC;AACJ,CAAC"}

package/dist/patterns/synthesize-with-followup.d.ts

@@ -0,0 +1,35 @@
+/**
+ * synthesize-with-followup — synthesizer reviews its own output and may
+ * request another round of upstream work.
+ *
+ * Loop:
+ *   1. Synthesizer produces draft text (typically streaming).
+ *   2. extractFollowUp inspects the draft for explicit "I need more on X".
+ *   3. If present and budget allows, doFollowUp runs whatever upstream phases
+ *      need to re-run, then we loop.
+ *   4. Otherwise the loop exits and the final text is written to ctx.
+ */
+import type { BasePipelineContext, Phase, PipelineEvent } from '../phase.js';
+export interface SynthesizeWithFollowupOptions<TCtx extends BasePipelineContext, TFollowUp> {
+    /**
+     * Run the synthesizer. May yield events (typically streamed `content`).
+     * Returns the final text via the generator's return value.
+     */
+    synthesize: (ctx: TCtx, iteration: number) => AsyncGenerator<PipelineEvent, string, void>;
+    /**
+     * Inspect the synthesizer output. Return null if synthesis is complete,
+     * or a typed follow-up directive if more work is needed.
+     */
+    extractFollowUp: (output: string) => TFollowUp | null;
+    /**
+     * Run whatever extra work the follow-up requested (often re-runs of
+     * upstream phases). May yield events.
+     */
+    doFollowUp: (ctx: TCtx, followUp: TFollowUp, iteration: number) => AsyncGenerator<PipelineEvent, void, void>;
+    /** Stash the final synthesized text on ctx. */
+    writeTo: (ctx: TCtx, text: string) => void;
+    /** Cap iterations. Default 2 (one synthesis + one follow-up). */
+    maxIterations?: number;
+}
+export declare function synthesizeWithFollowup<TCtx extends BasePipelineContext, TFollowUp>(phaseName: string, options: SynthesizeWithFollowupOptions<TCtx, TFollowUp>): Phase<TCtx>;
+//# sourceMappingURL=synthesize-with-followup.d.ts.map

package/dist/patterns/synthesize-with-followup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesize-with-followup.d.ts","sourceRoot":"","sources":["../../src/patterns/synthesize-with-followup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7E,MAAM,WAAW,6BAA6B,CAAC,IAAI,SAAS,mBAAmB,EAAE,SAAS;IACxF;;;OAGG;IACH,UAAU,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,KAAK,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAC1F;;;OAGG;IACH,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,CAAC;IACtD;;;OAGG;IACH,UAAU,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,KAAK,cAAc,CAAC,aAAa,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7G,+CAA+C;IAC/C,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,SAAS,mBAAmB,EAAE,SAAS,EAChF,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,6BAA6B,CAAC,IAAI,EAAE,SAAS,CAAC,GACtD,KAAK,CAAC,IAAI,CAAC,CAmCb"}

package/dist/patterns/synthesize-with-followup.js

@@ -0,0 +1,45 @@
+/**
+ * synthesize-with-followup — synthesizer reviews its own output and may
+ * request another round of upstream work.
+ *
+ * Loop:
+ *   1. Synthesizer produces draft text (typically streaming).
+ *   2. extractFollowUp inspects the draft for explicit "I need more on X".
+ *   3. If present and budget allows, doFollowUp runs whatever upstream phases
+ *      need to re-run, then we loop.
+ *   4. Otherwise the loop exits and the final text is written to ctx.
+ */
+export function synthesizeWithFollowup(phaseName, options) {
+    return {
+        name: phaseName,
+        async *run(ctx) {
+            const max = options.maxIterations ?? 2;
+            let finalText = '';
+            for (let iter = 0; iter < max; iter++) {
+                const synthGen = options.synthesize(ctx, iter);
+                let stepText = '';
+                while (true) {
+                    const next = await synthGen.next();
+                    if (next.done) {
+                        stepText = next.value;
+                        break;
+                    }
+                    yield next.value;
+                }
+                finalText = stepText;
+                const followUp = options.extractFollowUp(stepText);
+                if (!followUp || iter === max - 1)
+                    break;
+                yield {
+                    type: 'agent_activity',
+                    agent: phaseName,
+                    action: 'follow_up',
+                    detail: `iteration ${iter + 1} requested more work`,
+                };
+                yield* options.doFollowUp(ctx, followUp, iter);
+            }
+            options.writeTo(ctx, finalText);
+        },
+    };
+}
+//# sourceMappingURL=synthesize-with-followup.js.map

package/dist/patterns/synthesize-with-followup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesize-with-followup.js","sourceRoot":"","sources":["../../src/patterns/synthesize-with-followup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA0BH,MAAM,UAAU,sBAAsB,CACpC,SAAiB,EACjB,OAAuD;IAEvD,OAAO;QACL,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG;YACZ,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,IAAI,CAAC,CAAC;YACvC,IAAI,SAAS,GAAG,EAAE,CAAC;YAEnB,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC;gBACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBAC/C,IAAI,QAAQ,GAAG,EAAE,CAAC;gBAClB,OAAO,IAAI,EAAE,CAAC;oBACZ,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;oBACnC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;wBACd,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC;wBACtB,MAAM;oBACR,CAAC;oBACD,MAAM,IAAI,CAAC,KAAK,CAAC;gBACnB,CAAC;gBACD,SAAS,GAAG,QAAQ,CAAC;gBAErB,MAAM,QAAQ,GAAG,OAAO,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;gBACnD,IAAI,CAAC,QAAQ,IAAI,IAAI,KAAK,GAAG,GAAG,CAAC;oBAAE,MAAM;gBAEzC,MAAM;oBACJ,IAAI,EAAE,gBAAgB;oBACtB,KAAK,EAAE,SAAS;oBAChB,MAAM,EAAE,WAAW;oBACnB,MAAM,EAAE,aAAa,IAAI,GAAG,CAAC,sBAAsB;iBACpD,CAAC;gBACF,KAAK,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;YACjD,CAAC;YAED,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAClC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/patterns/while-condition.d.ts

@@ -0,0 +1,31 @@
+/**
+ * while-condition — a general convergence loop.
+ *
+ * Runs `body` repeatedly while `predicate(ctx)` is true, capped at
+ * `maxIterations`. Predicate is async and runs *before* each iteration —
+ * an immediately-false predicate produces zero body executions, like a
+ * standard `while` loop.
+ *
+ * Exits via one of:
+ *  - predicate returns false       → emits a `data` event with key
+ *                                    `${name}.converged` and value
+ *                                    `{ iterations }`.
+ *  - maxIterations reached         → sets ctx.stop with a reason naming
+ *                                    the pattern; emits `data` event
+ *                                    `${name}.max-iterations`.
+ *  - body sets ctx.stop            → propagates immediately.
+ *
+ * Body composition: pass a list of phases — they run in order each
+ * iteration, sharing ctx. Use `parallelPhases` if you want them concurrent.
+ */
+import type { BasePipelineContext, Phase } from '../phase.js';
+export interface WhileConditionOptions<TCtx extends BasePipelineContext> {
+    /** Predicate evaluated before each iteration. Loop continues while true. */
+    predicate: (ctx: TCtx) => boolean | Promise<boolean>;
+    /** Phases to run each iteration. */
+    body: Phase<TCtx>[];
+    /** Hard cap on iterations to prevent runaway loops. Default: 10. */
+    maxIterations?: number;
+}
+export declare function whileCondition<TCtx extends BasePipelineContext>(phaseName: string, options: WhileConditionOptions<TCtx>): Phase<TCtx>;
+//# sourceMappingURL=while-condition.d.ts.map

package/dist/patterns/while-condition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"while-condition.d.ts","sourceRoot":"","sources":["../../src/patterns/while-condition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAiB,MAAM,aAAa,CAAC;AAE7E,MAAM,WAAW,qBAAqB,CAAC,IAAI,SAAS,mBAAmB;IACrE,4EAA4E;IAC5E,SAAS,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD,oCAAoC;IACpC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;IACpB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,cAAc,CAAC,IAAI,SAAS,mBAAmB,EAC7D,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,qBAAqB,CAAC,IAAI,CAAC,GACnC,KAAK,CAAC,IAAI,CAAC,CA0Cb"}

package/dist/patterns/while-condition.js

@@ -0,0 +1,59 @@
+/**
+ * while-condition — a general convergence loop.
+ *
+ * Runs `body` repeatedly while `predicate(ctx)` is true, capped at
+ * `maxIterations`. Predicate is async and runs *before* each iteration —
+ * an immediately-false predicate produces zero body executions, like a
+ * standard `while` loop.
+ *
+ * Exits via one of:
+ *  - predicate returns false       → emits a `data` event with key
+ *                                    `${name}.converged` and value
+ *                                    `{ iterations }`.
+ *  - maxIterations reached         → sets ctx.stop with a reason naming
+ *                                    the pattern; emits `data` event
+ *                                    `${name}.max-iterations`.
+ *  - body sets ctx.stop            → propagates immediately.
+ *
+ * Body composition: pass a list of phases — they run in order each
+ * iteration, sharing ctx. Use `parallelPhases` if you want them concurrent.
+ */
+export function whileCondition(phaseName, options) {
+    const max = options.maxIterations ?? 10;
+    return {
+        name: phaseName,
+        async *run(ctx) {
+            let iterations = 0;
+            while (iterations < max) {
+                const shouldContinue = await options.predicate(ctx);
+                if (!shouldContinue) {
+                    yield {
+                        type: 'data',
+                        key: `${phaseName}.converged`,
+                        value: { iterations },
+                    };
+                    return;
+                }
+                yield {
+                    type: 'agent_activity',
+                    agent: phaseName,
+                    action: 'iteration',
+                    detail: `${iterations + 1}/${max}`,
+                };
+                for (const phase of options.body) {
+                    yield* phase.run(ctx);
+                    if (ctx.stop)
+                        return;
+                }
+                iterations++;
+            }
+            yield {
+                type: 'data',
+                key: `${phaseName}.max-iterations`,
+                value: { iterations },
+            };
+            ctx.stop = { reason: `${phaseName}: max iterations (${max}) reached` };
+        },
+    };
+}
+//# sourceMappingURL=while-condition.js.map

package/dist/patterns/while-condition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"while-condition.js","sourceRoot":"","sources":["../../src/patterns/while-condition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAaH,MAAM,UAAU,cAAc,CAC5B,SAAiB,EACjB,OAAoC;IAEpC,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;IAExC,OAAO;QACL,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG;YACZ,IAAI,UAAU,GAAG,CAAC,CAAC;YAEnB,OAAO,UAAU,GAAG,GAAG,EAAE,CAAC;gBACxB,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;gBACpD,IAAI,CAAC,cAAc,EAAE,CAAC;oBACpB,MAAM;wBACJ,IAAI,EAAE,MAAM;wBACZ,GAAG,EAAE,GAAG,SAAS,YAAY;wBAC7B,KAAK,EAAE,EAAE,UAAU,EAAE;qBACtB,CAAC;oBACF,OAAO;gBACT,CAAC;gBAED,MAAM;oBACJ,IAAI,EAAE,gBAAgB;oBACtB,KAAK,EAAE,SAAS;oBAChB,MAAM,EAAE,WAAW;oBACnB,MAAM,EAAE,GAAG,UAAU,GAAG,CAAC,IAAI,GAAG,EAAE;iBACnC,CAAC;gBAEF,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;oBACjC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;oBACtB,IAAI,GAAG,CAAC,IAAI;wBAAE,OAAO;gBACvB,CAAC;gBAED,UAAU,EAAE,CAAC;YACf,CAAC;YAED,MAAM;gBACJ,IAAI,EAAE,MAAM;gBACZ,GAAG,EAAE,GAAG,SAAS,iBAAiB;gBAClC,KAAK,EAAE,EAAE,UAAU,EAAE;aACtB,CAAC;YACF,GAAG,CAAC,IAAI,GAAG,EAAE,MAAM,EAAE,GAAG,SAAS,qBAAqB,GAAG,WAAW,EAAE,CAAC;QACzE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/patterns/with-retry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * with-retry — higher-order phase wrapper for retrying flaky work.
+ *
+ * Wraps any `Phase` and retries it on failure. Failure means either:
+ *  - the inner phase throws an exception, OR
+ *  - the inner phase yields then sets `ctx.stop` (a clean failure signal)
+ *
+ * Both default to retryable. Override with `isFailure(ctx, error?)` if a
+ * specific `ctx.stop.reason` should *not* trigger a retry (e.g. user
+ * cancellation, terminal validation error).
+ *
+ * Retries are bounded by `maxAttempts` (default 3) and spaced with
+ * exponential backoff starting at `baseDelayMs` (default 1000).
+ *
+ * Idempotence is the caller's responsibility. The wrapper does NOT
+ * snapshot/restore ctx between attempts — a partially-applied mutation
+ * from a failed attempt is visible to the retry. Pass `resetState` if
+ * you need to undo partial work before each retry.
+ *
+ * Events emitted by the inner phase pass through unmodified. The wrapper
+ * additionally emits `data` events with key `${phase.name}.attempt`.
+ */
+import type { BasePipelineContext, Phase } from '../phase.js';
+export interface WithRetryOptions<TCtx extends BasePipelineContext> {
+    /** Maximum total attempts including the first. Default: 3. */
+    maxAttempts?: number;
+    /** Base delay for exponential backoff, in milliseconds. Default: 1000. */
+    baseDelayMs?: number;
+    /** Decide whether the most recent attempt counts as a failure. Default: ctx.stop is set OR an error was thrown. */
+    isFailure?: (ctx: TCtx, error?: unknown) => boolean;
+    /** Called before each retry (not before the first attempt). */
+    onRetry?: (ctx: TCtx, attempt: number, error?: unknown) => void;
+    /** Called between attempts. Use to undo partial mutations from the failed attempt. */
+    resetState?: (ctx: TCtx) => void;
+}
+export declare function withRetry<TCtx extends BasePipelineContext>(phase: Phase<TCtx>, options?: WithRetryOptions<TCtx>): Phase<TCtx>;
+//# sourceMappingURL=with-retry.d.ts.map

package/dist/patterns/with-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-retry.d.ts","sourceRoot":"","sources":["../../src/patterns/with-retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAiB,MAAM,aAAa,CAAC;AAE7E,MAAM,WAAW,gBAAgB,CAAC,IAAI,SAAS,mBAAmB;IAChE,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mHAAmH;IACnH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;IACpD,+DAA+D;IAC/D,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAChE,sFAAsF;IACtF,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,IAAI,CAAC;CAClC;AAID,wBAAgB,SAAS,CAAC,IAAI,SAAS,mBAAmB,EACxD,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAClB,OAAO,GAAE,gBAAgB,CAAC,IAAI,CAAM,GACnC,KAAK,CAAC,IAAI,CAAC,CAwDb"}