@autonome-research/thread-phase 3.0.0

package/dist/patterns/bounded-fanout.d.ts

@@ -0,0 +1,111 @@
+/**
+ * bounded-fanout — like parallelFanout, but caps in-flight runners.
+ *
+ * The reason this exists: most local inference setups have a hard concurrency
+ * cap (e.g. vLLM's `--max-num-seqs`). Sending 200 requests at once when the
+ * server only decodes 4 at a time gives you no extra throughput, no progress
+ * visibility, and head-of-line blocking. Bounded fanout matches concurrency
+ * to the real bottleneck and lets you observe per-item completion via the
+ * optional `onItemDone` callback.
+ *
+ * Result order matches input order, regardless of completion order.
+ *
+ * # Failure semantics
+ *
+ * Two modes via `options.mode`:
+ *
+ * - `'reject'` (default; backwards-compatible): if any runner throws, this
+ *   rejects with the first thrown error. In-flight workers stop pulling new
+ *   items but the runner already-in-flight on the failing path has already
+ *   thrown. Other in-flight runners' resolved results are discarded.
+ *
+ * - `'collect'`: never reject due to a runner throw. Each result slot is
+ *   `{ ok: true, value }` or `{ ok: false, error }`, in input order. Use
+ *   this when partial-results-on-failure is what you want — common for
+ *   batch agent runs where one item failing shouldn't drop the rest.
+ *
+ * `onItemError` fires regardless of mode, before the rejection in `'reject'`
+ * mode and once per failed item in `'collect'` mode. Use it for telemetry.
+ *
+ * # Cancellation
+ *
+ * Pass an `AbortSignal` via `options.signal`. Once aborted:
+ *
+ *   - No new items are dispatched off the cursor.
+ *   - The signal is forwarded to runners as the third argument
+ *     (`runner(item, index, signal)`), so a runner that respects it can
+ *     unwind early — e.g. by passing it into `runAgentWithTools({signal})`.
+ *
+ * Cancellation interacts with `mode`:
+ *
+ *   - `'reject'`: hard-cancel. The fanout rejects with the abort reason.
+ *     Partial results are discarded.
+ *   - `'collect'`: soft-cancel. Returns a full-length, position-stable
+ *     `FanOutResult<T>[]` — items that completed before the abort keep
+ *     their `{ ok: true, value }` or `{ ok: false, error }`, items that
+ *     were never started (or whose runner exited via the in-loop signal
+ *     check) get a synthetic `{ ok: false, error: AbortError }`. The
+ *     fanout does NOT reject. Use this when you want a soft deadline
+ *     that returns work-in-progress for downstream phases to flush.
+ *
+ * For per-item progress as items complete, use `onItemDone` (it fires in
+ * completion order, before the final result array is returned).
+ */
+export interface ItemDoneEvent<TItem, TResult> {
+    item: TItem;
+    index: number;
+    result: TResult;
+}
+export interface ItemErrorEvent<TItem> {
+    item: TItem;
+    index: number;
+    error: Error;
+}
+export type FanOutResult<TResult> = {
+    ok: true;
+    value: TResult;
+} | {
+    ok: false;
+    error: Error;
+};
+export interface BoundedFanOutOptions<TItem, TResult> {
+    items: ReadonlyArray<TItem>;
+    /** Max concurrent runners. Default 4. Clamped to [1, items.length]. */
+    concurrency?: number;
+    /** If set, only the first `maxItems` items are processed. */
+    maxItems?: number;
+    /**
+     * Per-item runner. Receives the item, its index in the (capped) list, and
+     * the cancellation signal if one was passed. Forward `signal` into any
+     * abortable downstream call (HTTP, `runAgentWithTools`) for clean
+     * mid-flight cancellation.
+     */
+    runner: (item: TItem, index: number, signal?: AbortSignal) => Promise<TResult>;
+    /** Fires once per successfully-completed item, in completion order. */
+    onItemDone?: (event: ItemDoneEvent<TItem, TResult>) => void;
+    /**
+     * Failure mode:
+     *   - `'reject'` (default): first throw rejects the whole call.
+     *   - `'collect'`: never reject; each slot is FanOutResult.
+     */
+    mode?: 'reject' | 'collect';
+    /**
+     * Fires when a runner throws. Independent of mode; in `'reject'` mode it
+     * fires before the rejection propagates so you can record context for
+     * logging, in `'collect'` mode it fires per failed item.
+     */
+    onItemError?: (event: ItemErrorEvent<TItem>) => void;
+    /**
+     * Cancellation signal. When aborted, no new items are dispatched, the
+     * signal is forwarded to runners as the third argument, and the fanout
+     * rejects with the abort reason.
+     */
+    signal?: AbortSignal;
+}
+export declare function boundedFanout<TItem, TResult>(options: BoundedFanOutOptions<TItem, TResult> & {
+    mode: 'collect';
+}): Promise<FanOutResult<TResult>[]>;
+export declare function boundedFanout<TItem, TResult>(options: BoundedFanOutOptions<TItem, TResult> & {
+    mode?: 'reject';
+}): Promise<TResult[]>;
+//# sourceMappingURL=bounded-fanout.d.ts.map

package/dist/patterns/bounded-fanout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-fanout.d.ts","sourceRoot":"","sources":["../../src/patterns/bounded-fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,MAAM,WAAW,aAAa,CAAC,KAAK,EAAE,OAAO;IAC3C,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc,CAAC,KAAK;IACnC,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;CACd;AAED,MAAM,MAAM,YAAY,CAAC,OAAO,IAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC5B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEhC,MAAM,WAAW,oBAAoB,CAAC,KAAK,EAAE,OAAO;IAClD,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IAC5B,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/E,uEAAuE;IACvE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC5D;;;;OAIG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC5B;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IACrD;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAGD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAC1C,OAAO,EAAE,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAClE,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AACpC,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAC1C,OAAO,EAAE,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,QAAQ,CAAA;CAAE,GAClE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC"}

package/dist/patterns/bounded-fanout.js

@@ -0,0 +1,151 @@
+/**
+ * bounded-fanout — like parallelFanout, but caps in-flight runners.
+ *
+ * The reason this exists: most local inference setups have a hard concurrency
+ * cap (e.g. vLLM's `--max-num-seqs`). Sending 200 requests at once when the
+ * server only decodes 4 at a time gives you no extra throughput, no progress
+ * visibility, and head-of-line blocking. Bounded fanout matches concurrency
+ * to the real bottleneck and lets you observe per-item completion via the
+ * optional `onItemDone` callback.
+ *
+ * Result order matches input order, regardless of completion order.
+ *
+ * # Failure semantics
+ *
+ * Two modes via `options.mode`:
+ *
+ * - `'reject'` (default; backwards-compatible): if any runner throws, this
+ *   rejects with the first thrown error. In-flight workers stop pulling new
+ *   items but the runner already-in-flight on the failing path has already
+ *   thrown. Other in-flight runners' resolved results are discarded.
+ *
+ * - `'collect'`: never reject due to a runner throw. Each result slot is
+ *   `{ ok: true, value }` or `{ ok: false, error }`, in input order. Use
+ *   this when partial-results-on-failure is what you want — common for
+ *   batch agent runs where one item failing shouldn't drop the rest.
+ *
+ * `onItemError` fires regardless of mode, before the rejection in `'reject'`
+ * mode and once per failed item in `'collect'` mode. Use it for telemetry.
+ *
+ * # Cancellation
+ *
+ * Pass an `AbortSignal` via `options.signal`. Once aborted:
+ *
+ *   - No new items are dispatched off the cursor.
+ *   - The signal is forwarded to runners as the third argument
+ *     (`runner(item, index, signal)`), so a runner that respects it can
+ *     unwind early — e.g. by passing it into `runAgentWithTools({signal})`.
+ *
+ * Cancellation interacts with `mode`:
+ *
+ *   - `'reject'`: hard-cancel. The fanout rejects with the abort reason.
+ *     Partial results are discarded.
+ *   - `'collect'`: soft-cancel. Returns a full-length, position-stable
+ *     `FanOutResult<T>[]` — items that completed before the abort keep
+ *     their `{ ok: true, value }` or `{ ok: false, error }`, items that
+ *     were never started (or whose runner exited via the in-loop signal
+ *     check) get a synthetic `{ ok: false, error: AbortError }`. The
+ *     fanout does NOT reject. Use this when you want a soft deadline
+ *     that returns work-in-progress for downstream phases to flush.
+ *
+ * For per-item progress as items complete, use `onItemDone` (it fires in
+ * completion order, before the final result array is returned).
+ */
+export async function boundedFanout(options) {
+    const items = options.maxItems !== undefined ? options.items.slice(0, options.maxItems) : options.items;
+    if (items.length === 0)
+        return [];
+    const concurrency = Math.max(1, Math.min(options.concurrency ?? 4, items.length));
+    const collect = options.mode === 'collect';
+    const results = new Array(items.length);
+    let cursor = 0;
+    const signal = options.signal;
+    // Already aborted before any dispatch.
+    //   - 'reject' mode: throw, matches HTTP-cancel semantics.
+    //   - 'collect' mode: short-circuit with synthetic AbortError slots so
+    //     consumers always get a full-length, position-stable array.
+    if (signal?.aborted) {
+        if (collect)
+            return fillAbortedSlots([], items.length, signal);
+        throw signalAbortError(signal);
+    }
+    const worker = async () => {
+        while (true) {
+            if (signal?.aborted)
+                return;
+            const i = cursor++;
+            if (i >= items.length)
+                return;
+            const item = items[i];
+            try {
+                const result = await options.runner(item, i, signal);
+                if (signal?.aborted)
+                    return;
+                if (collect) {
+                    results[i] = { ok: true, value: result };
+                }
+                else {
+                    results[i] = result;
+                }
+                options.onItemDone?.({ item, index: i, result });
+            }
+            catch (rawErr) {
+                const error = toError(rawErr);
+                options.onItemError?.({ item, index: i, error });
+                if (collect) {
+                    results[i] = { ok: false, error };
+                    continue; // keep draining
+                }
+                throw error; // 'reject' mode: bubble out, Promise.all will reject
+            }
+        }
+    };
+    const workers = [];
+    for (let w = 0; w < concurrency; w++)
+        workers.push(worker());
+    await Promise.all(workers);
+    // Aborted at some point after dispatch began.
+    //   - 'reject' mode: throw, partial results discarded (matches v1.0/1.1).
+    //   - 'collect' mode: soft-cancel — return what completed, fill the slots
+    //     of items that were never started (or whose runner exited via the
+    //     in-loop signal check before writing a result) with synthetic
+    //     AbortError FanOutResults. onItemError does NOT fire for these
+    //     synthetic fills — the runner never ran for them.
+    if (signal?.aborted) {
+        if (collect) {
+            return fillAbortedSlots(results, items.length, signal);
+        }
+        throw signalAbortError(signal);
+    }
+    return results;
+}
+/**
+ * Soft-cancel helper: fills any undefined slots in a collect-mode results
+ * array with synthetic { ok: false, error } AbortError entries so the
+ * returned array stays position-stable with the input items array.
+ *
+ * Items that were already recorded (whether { ok: true } or { ok: false }
+ * from a real runner error) are preserved. Items that never ran — either
+ * because the cursor never reached them or because the runner exited via
+ * the in-loop signal check before writing — get a synthetic slot.
+ */
+function fillAbortedSlots(partial, total, signal) {
+    const abortErr = signalAbortError(signal);
+    const out = new Array(total);
+    for (let i = 0; i < total; i++) {
+        out[i] = partial[i] ?? { ok: false, error: abortErr };
+    }
+    return out;
+}
+function toError(e) {
+    return e instanceof Error ? e : new Error(typeof e === 'string' ? e : JSON.stringify(e));
+}
+function signalAbortError(signal) {
+    const reason = signal.reason;
+    if (reason instanceof Error)
+        return reason;
+    const err = new Error(typeof reason === 'string' ? reason : 'aborted');
+    err.name = 'AbortError';
+    return err;
+}
+//# sourceMappingURL=bounded-fanout.js.map

package/dist/patterns/bounded-fanout.js.map

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

package/dist/patterns/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reusable phase patterns. Each pattern is a small, opinionated helper that
+ * captures a recurring shape — not a black-box framework. Compose freely.
+ */
+export { parallelPhases } from './parallel-phases.js';
+export { boundedFanout, type BoundedFanOutOptions, type ItemDoneEvent, type ItemErrorEvent, type FanOutResult, } from './bounded-fanout.js';
+export { boundedFanoutOf, BoundedFanoutOfError } from './bounded-fanout-of.js';
+export type { BoundedFanoutOfOptions, BoundedFanoutOfMode } from './bounded-fanout-of.js';
+export { intentGate, type IntentClassification, type IntentDecision, type IntentGateOptions, } from './intent-gate.js';
+export { whileCondition, type WhileConditionOptions, } from './while-condition.js';
+export { match, type MatchOptions, } from './match.js';
+export { withRetry, type WithRetryOptions, } from './with-retry.js';
+export { subPipeline, subPipelineOf, runSubPipeline, type SubPipelineOptions, type SubPipelineSource, } from './sub-pipeline.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/patterns/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE1F,OAAO,EACL,UAAU,EACV,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,EACL,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,WAAW,EACX,aAAa,EACb,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC"}

package/dist/patterns/index.js

@@ -0,0 +1,13 @@
+/**
+ * Reusable phase patterns. Each pattern is a small, opinionated helper that
+ * captures a recurring shape — not a black-box framework. Compose freely.
+ */
+export { parallelPhases } from './parallel-phases.js';
+export { boundedFanout, } from './bounded-fanout.js';
+export { boundedFanoutOf, BoundedFanoutOfError } from './bounded-fanout-of.js';
+export { intentGate, } from './intent-gate.js';
+export { whileCondition, } from './while-condition.js';
+export { match, } from './match.js';
+export { withRetry, } from './with-retry.js';
+export { subPipeline, subPipelineOf, runSubPipeline, } from './sub-pipeline.js';
+//# sourceMappingURL=index.js.map

package/dist/patterns/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EACL,aAAa,GAKd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAG/E,OAAO,EACL,UAAU,GAIX,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,GAEf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,GAEN,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,GAEV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,WAAW,EACX,aAAa,EACb,cAAc,GAGf,MAAM,mBAAmB,CAAC"}

package/dist/patterns/intent-gate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * intent-gate — classify the input cheaply, route to a fast path or continue.
+ *
+ * Common cost-control pattern: a 1-call cheap classifier decides whether the
+ * pipeline should run end-to-end (`continue`) or short-circuit to a much
+ * cheaper handler (e.g. a one-shot direct answer). The handler may produce
+ * its own output before the pipeline halts.
+ */
+import type { BasePipelineContext, Phase, PipelineEvent } from '../phase.js';
+export interface IntentClassification<TIntent extends string> {
+    intent: TIntent;
+    /** Optional rationale surfaced in the activity log. */
+    rationale?: string;
+}
+export type IntentDecision<TCtx extends BasePipelineContext> = 'continue' | {
+    stop: string;
+    /** Optional generator that yields events before the pipeline halts. */
+    handler?: (ctx: TCtx) => AsyncGenerator<PipelineEvent, void, void>;
+};
+export interface IntentGateOptions<TCtx extends BasePipelineContext, TIntent extends string> {
+    /** Run the classifier (typically a cheap LLM call). */
+    classify: (ctx: TCtx) => Promise<IntentClassification<TIntent>>;
+    /** Map a classified intent to either 'continue' or a stop directive. */
+    route: (intent: TIntent, ctx: TCtx) => IntentDecision<TCtx>;
+}
+export declare function intentGate<TCtx extends BasePipelineContext, TIntent extends string>(phaseName: string, options: IntentGateOptions<TCtx, TIntent>): Phase<TCtx>;
+//# sourceMappingURL=intent-gate.d.ts.map

package/dist/patterns/intent-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent-gate.d.ts","sourceRoot":"","sources":["../../src/patterns/intent-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7E,MAAM,WAAW,oBAAoB,CAAC,OAAO,SAAS,MAAM;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,mBAAmB,IACvD,UAAU,GACV;IACE,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,cAAc,CAAC,aAAa,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;CACpE,CAAC;AAEN,MAAM,WAAW,iBAAiB,CAAC,IAAI,SAAS,mBAAmB,EAAE,OAAO,SAAS,MAAM;IACzF,uDAAuD;IACvD,QAAQ,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;IAChE,wEAAwE;IACxE,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,KAAK,cAAc,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED,wBAAgB,UAAU,CAAC,IAAI,SAAS,mBAAmB,EAAE,OAAO,SAAS,MAAM,EACjF,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,iBAAiB,CAAC,IAAI,EAAE,OAAO,CAAC,GACxC,KAAK,CAAC,IAAI,CAAC,CAuBb"}

package/dist/patterns/intent-gate.js

@@ -0,0 +1,32 @@
+/**
+ * intent-gate — classify the input cheaply, route to a fast path or continue.
+ *
+ * Common cost-control pattern: a 1-call cheap classifier decides whether the
+ * pipeline should run end-to-end (`continue`) or short-circuit to a much
+ * cheaper handler (e.g. a one-shot direct answer). The handler may produce
+ * its own output before the pipeline halts.
+ */
+export function intentGate(phaseName, options) {
+    return {
+        name: phaseName,
+        async *run(ctx) {
+            const classification = await options.classify(ctx);
+            yield {
+                type: 'agent_activity',
+                agent: phaseName,
+                action: 'classified',
+                detail: classification.rationale
+                    ? `${classification.intent} — ${classification.rationale}`
+                    : classification.intent,
+            };
+            const decision = options.route(classification.intent, ctx);
+            if (decision === 'continue')
+                return;
+            if (decision.handler) {
+                yield* decision.handler(ctx);
+            }
+            ctx.stop = { reason: decision.stop };
+        },
+    };
+}
+//# sourceMappingURL=intent-gate.js.map

package/dist/patterns/intent-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent-gate.js","sourceRoot":"","sources":["../../src/patterns/intent-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAyBH,MAAM,UAAU,UAAU,CACxB,SAAiB,EACjB,OAAyC;IAEzC,OAAO;QACL,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG;YACZ,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YACnD,MAAM;gBACJ,IAAI,EAAE,gBAAgB;gBACtB,KAAK,EAAE,SAAS;gBAChB,MAAM,EAAE,YAAY;gBACpB,MAAM,EAAE,cAAc,CAAC,SAAS;oBAC9B,CAAC,CAAC,GAAG,cAAc,CAAC,MAAM,MAAM,cAAc,CAAC,SAAS,EAAE;oBAC1D,CAAC,CAAC,cAAc,CAAC,MAAM;aAC1B,CAAC;YAEF,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YAC3D,IAAI,QAAQ,KAAK,UAAU;gBAAE,OAAO;YAEpC,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACrB,KAAK,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC/B,CAAC;YACD,GAAG,CAAC,IAAI,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;QACvC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/patterns/match.d.ts

@@ -0,0 +1,30 @@
+/**
+ * match — keyed dispatch over phases.
+ *
+ * Routes to one of N phase lists based on a selector function. Generalizes
+ * if/else (use two cases) and replaces ad-hoc switch statements in pipeline
+ * code with a primitive the orchestrator can reason about.
+ *
+ * The selector returns one of three things:
+ *  - a key present in `cases`             → run that case's phases
+ *  - a key missing from `cases`           → run `default` if provided, else skip
+ *  - `null`                               → skip silently (no case, no default)
+ *
+ * Emits a `data` event with key `${name}.taken` and value
+ * `{ taken: key | 'default' | 'skip' }` so downstream consumers can tell
+ * which arm ran without inspecting the selector themselves.
+ *
+ * Strict dispatch is the caller's responsibility — assert inside the
+ * selector if a missing key should be a bug.
+ */
+import type { BasePipelineContext, Phase } from '../phase.js';
+export interface MatchOptions<TCtx extends BasePipelineContext, K extends string> {
+    /** Returns the key of the case to run, or null to skip. */
+    selector: (ctx: TCtx) => K | null | Promise<K | null>;
+    /** Phase lists keyed by case. */
+    cases: Record<K, Phase<TCtx>[]>;
+    /** Fallback phases when selector returns a key not in `cases`. */
+    default?: Phase<TCtx>[];
+}
+export declare function match<TCtx extends BasePipelineContext, K extends string>(phaseName: string, options: MatchOptions<TCtx, K>): Phase<TCtx>;
+//# sourceMappingURL=match.d.ts.map

package/dist/patterns/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/patterns/match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAiB,MAAM,aAAa,CAAC;AAE7E,MAAM,WAAW,YAAY,CAAC,IAAI,SAAS,mBAAmB,EAAE,CAAC,SAAS,MAAM;IAC9E,2DAA2D;IAC3D,QAAQ,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACtD,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChC,kEAAkE;IAClE,OAAO,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;CACzB;AAED,wBAAgB,KAAK,CAAC,IAAI,SAAS,mBAAmB,EAAE,CAAC,SAAS,MAAM,EACtE,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,GAC7B,KAAK,CAAC,IAAI,CAAC,CAqCb"}

package/dist/patterns/match.js

@@ -0,0 +1,58 @@
+/**
+ * match — keyed dispatch over phases.
+ *
+ * Routes to one of N phase lists based on a selector function. Generalizes
+ * if/else (use two cases) and replaces ad-hoc switch statements in pipeline
+ * code with a primitive the orchestrator can reason about.
+ *
+ * The selector returns one of three things:
+ *  - a key present in `cases`             → run that case's phases
+ *  - a key missing from `cases`           → run `default` if provided, else skip
+ *  - `null`                               → skip silently (no case, no default)
+ *
+ * Emits a `data` event with key `${name}.taken` and value
+ * `{ taken: key | 'default' | 'skip' }` so downstream consumers can tell
+ * which arm ran without inspecting the selector themselves.
+ *
+ * Strict dispatch is the caller's responsibility — assert inside the
+ * selector if a missing key should be a bug.
+ */
+export function match(phaseName, options) {
+    return {
+        name: phaseName,
+        async *run(ctx) {
+            const key = await options.selector(ctx);
+            let chosen;
+            let taken;
+            if (key === null) {
+                chosen = undefined;
+                taken = 'skip';
+            }
+            else if (Object.prototype.hasOwnProperty.call(options.cases, key)) {
+                chosen = options.cases[key];
+                taken = key;
+            }
+            else if (options.default) {
+                chosen = options.default;
+                taken = 'default';
+            }
+            else {
+                chosen = undefined;
+                taken = 'skip';
+            }
+            yield {
+                type: 'data',
+                key: `${phaseName}.taken`,
+                value: { taken },
+            };
+            if (!chosen)
+                return;
+            for (const phase of chosen) {
+                yield* phase.run(ctx);
+                if (ctx.stop)
+                    return;
+            }
+        },
+    };
+}
+//# sourceMappingURL=match.js.map

package/dist/patterns/match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","sourceRoot":"","sources":["../../src/patterns/match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAaH,MAAM,UAAU,KAAK,CACnB,SAAiB,EACjB,OAA8B;IAE9B,OAAO;QACL,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG;YACZ,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAExC,IAAI,MAAiC,CAAC;YACtC,IAAI,KAAa,CAAC;YAElB,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;gBACjB,MAAM,GAAG,SAAS,CAAC;gBACnB,KAAK,GAAG,MAAM,CAAC;YACjB,CAAC;iBAAM,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;gBACpE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBAC5B,KAAK,GAAG,GAAG,CAAC;YACd,CAAC;iBAAM,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBAC3B,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;gBACzB,KAAK,GAAG,SAAS,CAAC;YACpB,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,SAAS,CAAC;gBACnB,KAAK,GAAG,MAAM,CAAC;YACjB,CAAC;YAED,MAAM;gBACJ,IAAI,EAAE,MAAM;gBACZ,GAAG,EAAE,GAAG,SAAS,QAAQ;gBACzB,KAAK,EAAE,EAAE,KAAK,EAAE;aACjB,CAAC;YAEF,IAAI,CAAC,MAAM;gBAAE,OAAO;YAEpB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACtB,IAAI,GAAG,CAAC,IAAI;oBAAE,OAAO;YACvB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/patterns/parallel-fanout.d.ts

@@ -0,0 +1,28 @@
+/**
+ * parallel-fanout — N items, one async runner per item, results collected.
+ *
+ * The most common multi-agent pattern: "for each X, do Y." Caps concurrency
+ * optionally.
+ *
+ * Intentionally a helper, not a Phase. Compose inside your own phase:
+ *
+ *   async *run(ctx) {
+ *     const items = requireCtx(ctx, 'items', 'my-phase');
+ *     yield { type: 'phase', phase: 'my-phase', detail: `${items.length} items` };
+ *     const results = await parallelFanout({
+ *       items,
+ *       maxItems: 5,
+ *       runner: (item) => runAgentWithTools(myConfig, [...], opts),
+ *     });
+ *     ctx.results = results;
+ *   }
+ */
+export interface FanOutOptions<TItem, TResult> {
+    items: ReadonlyArray<TItem>;
+    /** If set, only the first `maxItems` items are processed. */
+    maxItems?: number;
+    /** Per-item runner. Receives the item and its index in the (capped) list. */
+    runner: (item: TItem, index: number) => Promise<TResult>;
+}
+export declare function parallelFanout<TItem, TResult>(options: FanOutOptions<TItem, TResult>): Promise<TResult[]>;
+//# sourceMappingURL=parallel-fanout.d.ts.map

package/dist/patterns/parallel-fanout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-fanout.d.ts","sourceRoot":"","sources":["../../src/patterns/parallel-fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,aAAa,CAAC,KAAK,EAAE,OAAO;IAC3C,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AAED,wBAAsB,cAAc,CAAC,KAAK,EAAE,OAAO,EACjD,OAAO,EAAE,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,OAAO,EAAE,CAAC,CAIpB"}

package/dist/patterns/parallel-fanout.js

@@ -0,0 +1,24 @@
+/**
+ * parallel-fanout — N items, one async runner per item, results collected.
+ *
+ * The most common multi-agent pattern: "for each X, do Y." Caps concurrency
+ * optionally.
+ *
+ * Intentionally a helper, not a Phase. Compose inside your own phase:
+ *
+ *   async *run(ctx) {
+ *     const items = requireCtx(ctx, 'items', 'my-phase');
+ *     yield { type: 'phase', phase: 'my-phase', detail: `${items.length} items` };
+ *     const results = await parallelFanout({
+ *       items,
+ *       maxItems: 5,
+ *       runner: (item) => runAgentWithTools(myConfig, [...], opts),
+ *     });
+ *     ctx.results = results;
+ *   }
+ */
+export async function parallelFanout(options) {
+    const items = options.maxItems !== undefined ? options.items.slice(0, options.maxItems) : options.items;
+    return Promise.all(items.map((item, i) => options.runner(item, i)));
+}
+//# sourceMappingURL=parallel-fanout.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-fanout.js","sourceRoot":"","sources":["../../src/patterns/parallel-fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAsC;IAEtC,MAAM,KAAK,GACT,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IAC5F,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/patterns/parallel-phases.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+import type { BasePipelineContext, Phase, PipelineEvent } from '../phase.js';
+export declare function parallelPhases<TCtx extends BasePipelineContext, TEvent = PipelineEvent>(phaseName: string, phases: ReadonlyArray<Phase<TCtx, TEvent>>): Phase<TCtx, TEvent>;
+//# sourceMappingURL=parallel-phases.d.ts.map

package/dist/patterns/parallel-phases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-phases.d.ts","sourceRoot":"","sources":["../../src/patterns/parallel-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7E,wBAAgB,cAAc,CAC5B,IAAI,SAAS,mBAAmB,EAChC,MAAM,GAAG,aAAa,EAEtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,GACzC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAkDrB"}