agentfootprint 1.8.0 → 1.10.0

package/dist/esm/exportTrace.js

@@ -0,0 +1,72 @@
+/**
+ * exportTrace — capture an agent run's full state into a portable JSON
+ * blob for sharing externally (paste into a viewer, ship to support, log
+ * for debugging, store in a database).
+ *
+ * Defaults to **redacted** output: snapshots come from
+ * `getSnapshot({ redact: true })` (footprintjs 4.14+), so values for keys
+ * listed in `RedactionPolicy.keys` / matching `patterns` arrive as
+ * `'REDACTED'` instead of raw. The commit log is already redacted at
+ * write-time. Combined with `emitPatterns` (also redacted at origin), the
+ * exported trace is safe to share when the caller has configured a policy.
+ *
+ * **Without a redaction policy, this helper still emits a trace — but
+ * `sharedState` will contain raw values.** Configure `setRedactionPolicy`
+ * before calling this for any externally shared trace.
+ *
+ * @example
+ * ```ts
+ * import { Agent, exportTrace, anthropic } from 'agentfootprint';
+ *
+ * const agent = Agent.create({ provider: anthropic('claude-sonnet-4') })
+ *   .system('You are a customer support agent.')
+ *   .build();
+ *
+ * await agent.run('My credit card 4242-4242-4242-4242 was declined');
+ *
+ * // Configure policy on the underlying executor for full safety
+ * // (concept-level recorder API for this is a follow-up).
+ * const trace = exportTrace(agent);
+ * console.log(JSON.stringify(trace, null, 2));
+ * // → paste into the playground viewer, send to support, etc.
+ * ```
+ */
+/**
+ * Capture a full execution trace from any runner exposing the standard
+ * introspection surface (`getSnapshot`, `getNarrative*`, `getSpec`).
+ * All of those methods are optional — missing methods skip the field.
+ *
+ * Always returns a JSON-stringify-safe object.
+ */
+export function exportTrace(runner, options) {
+    const redact = options?.redact !== false; // default true
+    const r = runner;
+    // `getSnapshot` may be the older 0-arg form — still safe to call with
+    // an arg (JS ignores extras), but keep our intent explicit so older
+    // overloads with strict signatures don't trip the type checker.
+    let snapshot;
+    try {
+        snapshot = r.getSnapshot?.({ redact });
+    }
+    catch {
+        // Fall back to the 0-arg form if the runner's signature rejects the
+        // options object (older custom runners). Result will be raw — caller
+        // is responsible for the safety implication when this happens.
+        try {
+            snapshot = r.getSnapshot?.();
+        }
+        catch {
+            snapshot = undefined;
+        }
+    }
+    return {
+        schemaVersion: 1,
+        exportedAt: new Date().toISOString(),
+        redacted: redact,
+        snapshot,
+        narrativeEntries: r.getNarrativeEntries?.(),
+        narrative: r.getNarrative?.(),
+        spec: r.getSpec?.(),
+    };
+}
+//# sourceMappingURL=exportTrace.js.map

package/dist/esm/exportTrace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exportTrace.js","sourceRoot":"","sources":["../../src/exportTrace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AA4DH;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,MAAkB,EAAE,OAA4B;IAC1E,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC,CAAC,eAAe;IACzD,MAAM,CAAC,GAAG,MAA0B,CAAC;IAErC,sEAAsE;IACtE,oEAAoE;IACpE,gEAAgE;IAChE,IAAI,QAAiB,CAAC;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,oEAAoE;QACpE,qEAAqE;QACrE,+DAA+D;QAC/D,IAAI,CAAC;YACH,QAAQ,GAAI,CAAC,CAAC,WAA2C,EAAE,EAAE,CAAC;QAChE,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG,SAAS,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,QAAQ,EAAE,MAAM;QAChB,QAAQ;QACR,gBAAgB,EAAE,CAAC,CAAC,mBAAmB,EAAE,EAAE;QAC3C,SAAS,EAAE,CAAC,CAAC,YAAY,EAAE,EAAE;QAC7B,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE;KACpB,CAAC;AACJ,CAAC"}

package/dist/esm/index.js

@@ -13,6 +13,8 @@
  */
 // ── Concepts (Builders + Runners) ───────────────────────────
 export { Agent, AgentRunner, LLMCall, LLMCallRunner, RAG, RAGRunner, FlowChart, FlowChartRunner, Swarm, SwarmRunner, Parallel, ParallelRunner, Conditional, ConditionalRunner, } from './concepts';
+// ── Trace export (paste-into-viewer / share-with-support workflow) ─
+export { exportTrace } from './exportTrace';
 // ── Tools ───────────────────────────────────────────────────
 export { defineTool, askHuman, ToolRegistry } from './tools';
 // ── Providers (core — you can't build an agent without these) ─

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+DAA+D;AAC/D,OAAO,EACL,KAAK,EACL,WAAW,EACX,OAAO,EACP,aAAa,EACb,GAAG,EACH,SAAS,EACT,SAAS,EACT,eAAe,EACf,KAAK,EACL,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAQpB,+DAA+D;AAC/D,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7D,iEAAiE;AACjE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAuBlF,+DAA+D;AAC/D,OAAO,EACL,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,SAAS,CAAC;AAEjB,+DAA+D;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AA0BnC,8DAA8D;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,uEAAuE;AACvE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGnF,+DAA+D;AAC/D,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+DAA+D;AAC/D,OAAO,EACL,KAAK,EACL,WAAW,EACX,OAAO,EACP,aAAa,EACb,GAAG,EACH,SAAS,EACT,SAAS,EACT,eAAe,EACf,KAAK,EACL,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAQpB,sEAAsE;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,+DAA+D;AAC/D,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7D,iEAAiE;AACjE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAuBlF,+DAA+D;AAC/D,OAAO,EACL,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,SAAS,CAAC;AAEjB,+DAA+D;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AA0BnC,8DAA8D;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,uEAAuE;AACvE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGnF,+DAA+D;AAC/D,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/esm/patterns/index.js

@@ -0,0 +1,18 @@
+/**
+ * agentfootprint/patterns — canonical agent composition patterns.
+ *
+ * Each pattern is a thin factory over the existing concepts (`FlowChart`,
+ * `Parallel`, `Conditional`, `Agent`, `LLMCall`, `RAG`, `Swarm`). No new
+ * primitives. The source of each file shows the composition — read it to
+ * learn how to build your own.
+ *
+ * @example
+ * ```ts
+ * import { treeOfThoughts, reflexion, planExecute, mapReduce } from 'agentfootprint/patterns';
+ * ```
+ */
+export { planExecute } from './planExecute';
+export { mapReduce } from './mapReduce';
+export { treeOfThoughts } from './treeOfThoughts';
+export { reflexion } from './reflexion';
+//# sourceMappingURL=index.js.map

package/dist/esm/patterns/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/esm/patterns/mapReduce.js

@@ -0,0 +1,60 @@
+/**
+ * mapReduce — fan-out map over N pre-bound mappers, then reduce.
+ *
+ * Each mapper is a runner with its own input already bound (prepare them with
+ * the slice they should process). `Parallel.mergeWithLLM` or a custom reduce
+ * function combines the results. Under the hood: a single `Parallel` with N
+ * branches and one merge strategy.
+ *
+ * Why: map-reduce is a common shape — summarize N documents, compare N
+ * candidates, evaluate a prompt against N rubrics. Keeping it as a named
+ * pattern teaches the shape; each mapper / reducer is still a regular runner.
+ *
+ * @example
+ * ```ts
+ * import { LLMCall, anthropic } from 'agentfootprint';
+ * import { mapReduce } from 'agentfootprint/patterns';
+ *
+ * const documents = [doc1, doc2, doc3];
+ * const provider = anthropic('claude-sonnet-4');
+ *
+ * const pipeline = mapReduce({
+ *   provider,
+ *   mappers: documents.map((doc, i) => ({
+ *     id: `doc-${i}`,
+ *     description: `Summarize doc ${i}`,
+ *     runner: LLMCall.create({ provider })
+ *       .system(`Summarize this document:\n\n${doc}`)
+ *       .build(),
+ *   })),
+ *   reduce: { mode: 'llm', prompt: 'Combine the summaries into a single report.' },
+ * });
+ *
+ * const result = await pipeline.run('Produce the report');
+ * ```
+ */
+import { Parallel } from '../concepts/Parallel';
+/**
+ * Build a map-reduce pipeline. Returns a `ParallelRunner` — plug it into
+ * `FlowChart`, `Conditional`, or `Agent.route()` like any other runner.
+ */
+export function mapReduce(options) {
+    if (options.mappers.length < 2) {
+        throw new Error('mapReduce requires at least 2 mappers. Use a single runner directly if you only have one.');
+    }
+    const builder = Parallel.create({
+        provider: options.provider,
+        name: options.name ?? 'mapReduce',
+    });
+    for (const m of options.mappers) {
+        builder.agent(m.id, m.runner, m.description);
+    }
+    if (options.reduce.mode === 'llm') {
+        builder.mergeWithLLM(options.reduce.prompt);
+    }
+    else {
+        builder.merge(options.reduce.fn);
+    }
+    return builder.build();
+}
+//# sourceMappingURL=mapReduce.js.map

package/dist/esm/patterns/mapReduce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapReduce.js","sourceRoot":"","sources":["../../../src/patterns/mapReduce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,QAAQ,EAA0C,MAAM,sBAAsB,CAAC;AAwBxF;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,2FAA2F,CAC5F,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,WAAW;KAClC,CAAC,CAAC;IACH,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAChC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QAClC,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;AACzB,CAAC"}

package/dist/esm/patterns/planExecute.js

@@ -0,0 +1,43 @@
+/**
+ * planExecute — Planner → Executor composition.
+ *
+ * Two runners chained sequentially: the planner takes the user request and
+ * produces a plan; the executor takes that plan (as the planner's output) and
+ * carries it out. Pure composition over `FlowChart` — no new primitives,
+ * readable as a teaching example.
+ *
+ * Why: separating planning from execution is often cheaper (small model
+ * plans, capable model executes) and safer (plan visible in narrative before
+ * any tool fires).
+ *
+ * @example
+ * ```ts
+ * import { Agent, anthropic } from 'agentfootprint';
+ * import { planExecute } from 'agentfootprint/patterns';
+ *
+ * const planner = Agent.create({ provider: anthropic('claude-haiku-4-5') })
+ *   .system('Produce a numbered plan. Do not execute.')
+ *   .build();
+ *
+ * const executor = Agent.create({ provider: anthropic('claude-sonnet-4') })
+ *   .system('Execute the given plan step by step.')
+ *   .tools([...])
+ *   .build();
+ *
+ * const runner = planExecute({ planner, executor });
+ * const result = await runner.run('Research competitors and draft a brief.');
+ * ```
+ */
+import { FlowChart } from '../concepts/FlowChart';
+/**
+ * Build a planner → executor pipeline. Returns a `FlowChartRunner` — plug it
+ * into `Parallel`, `FlowChart`, `Conditional`, or `Agent.route()` like any
+ * other runner.
+ */
+export function planExecute(options) {
+    return FlowChart.create()
+        .agent('plan', options.planName ?? 'Plan', options.planner)
+        .agent('execute', options.executeName ?? 'Execute', options.executor)
+        .build();
+}
+//# sourceMappingURL=planExecute.js.map

package/dist/esm/patterns/planExecute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planExecute.js","sourceRoot":"","sources":["../../../src/patterns/planExecute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,SAAS,EAAwB,MAAM,uBAAuB,CAAC;AAcxE;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,OAAO,SAAS,CAAC,MAAM,EAAE;SACtB,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,IAAI,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC;SAC1D,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,WAAW,IAAI,SAAS,EAAE,OAAO,CAAC,QAAQ,CAAC;SACpE,KAAK,EAAE,CAAC;AACb,CAAC"}

package/dist/esm/patterns/reflexion.js

@@ -0,0 +1,58 @@
+/**
+ * reflexion — Solve → Critique → Improve (single-pass).
+ *
+ * Three runners chained sequentially: a solver produces a draft, a critic
+ * reviews it, an improver integrates the critique. Shinn et al. 2023's
+ * Reflexion pattern has a quality-gated loop; this is the simplest form —
+ * one reflection pass. For multi-iteration Reflexion, wrap this pattern
+ * inside `Conditional` to rerun while a quality predicate fails.
+ *
+ * Why: a single self-review pass catches a surprising number of errors in
+ * reasoning / code / plans. Exposing the three runners individually lets
+ * users pick cheap models for critic/improver while keeping a strong solver.
+ *
+ * Under the hood:
+ *   FlowChart[ solver, critic, improver ]
+ *
+ * Each runner receives the previous runner's output as its input message.
+ *
+ * @example
+ * ```ts
+ * import { Agent, anthropic } from 'agentfootprint';
+ * import { reflexion } from 'agentfootprint/patterns';
+ *
+ * const provider = anthropic('claude-sonnet-4');
+ *
+ * const reviewer = reflexion({
+ *   solver: Agent.create({ provider }).system('Draft an answer.').build(),
+ *   critic: Agent.create({ provider }).system('List weaknesses in the draft.').build(),
+ *   improver: Agent.create({ provider })
+ *     .system('Apply the critique to improve the draft.')
+ *     .build(),
+ * });
+ *
+ * const result = await reviewer.run('Explain monads in plain English.');
+ * ```
+ *
+ * For multi-iteration Reflexion (loop until quality gate passes), compose
+ * with `Conditional`:
+ * ```ts
+ * import { Conditional } from 'agentfootprint';
+ * const iterative = Conditional.create()
+ *   .when((s) => qualityOf(s) < 0.8, reviewer)
+ *   .otherwise(doneRunner)
+ *   .build();
+ * ```
+ */
+import { FlowChart } from '../concepts/FlowChart';
+/**
+ * Build a Solve → Critique → Improve pipeline. Returns a `FlowChartRunner`.
+ */
+export function reflexion(options) {
+    return FlowChart.create()
+        .agent('solve', options.solveName ?? 'Solve', options.solver)
+        .agent('critique', options.critiqueName ?? 'Critique', options.critic)
+        .agent('improve', options.improveName ?? 'Improve', options.improver)
+        .build();
+}
+//# sourceMappingURL=reflexion.js.map

package/dist/esm/patterns/reflexion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflexion.js","sourceRoot":"","sources":["../../../src/patterns/reflexion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,SAAS,EAAwB,MAAM,uBAAuB,CAAC;AAgBxE;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,OAAO,SAAS,CAAC,MAAM,EAAE;SACtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,IAAI,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC;SAC5D,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,YAAY,IAAI,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC;SACrE,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,WAAW,IAAI,SAAS,EAAE,OAAO,CAAC,QAAQ,CAAC;SACpE,KAAK,EAAE,CAAC;AACb,CAAC"}

package/dist/esm/patterns/treeOfThoughts.js

@@ -0,0 +1,71 @@
+/**
+ * treeOfThoughts — N parallel thinkers → one judge picks best.
+ *
+ * Fan out N parallel thinkers (each a runner, typically same prompt + higher
+ * temperature variance), format their outputs as context, then hand to a
+ * judge runner that picks or synthesizes the best answer.
+ *
+ * Why: for problems where one-shot answers are often wrong, generating
+ * multiple independent attempts and judging them catches errors that a
+ * single chain-of-thought would miss. Tree-of-Thoughts (Yao et al. 2023)
+ * formalized this pattern.
+ *
+ * Under the hood:
+ *   FlowChart[ Parallel({ t0, t1, ..., tN-1, merge: labelled-concat }),
+ *              judge ]
+ *
+ * The merge step concatenates each thinker's output under its id so the
+ * judge sees them as labeled candidates. The judge receives that
+ * concatenation as its input string.
+ *
+ * @example
+ * ```ts
+ * import { Agent, LLMCall, anthropic } from 'agentfootprint';
+ * import { treeOfThoughts } from 'agentfootprint/patterns';
+ *
+ * const provider = anthropic('claude-sonnet-4');
+ *
+ * const tot = treeOfThoughts({
+ *   provider,
+ *   branches: 3,
+ *   thinker: (i) =>
+ *     LLMCall.create({ provider }).system(`Thinker ${i + 1}: propose a different solution.`).build(),
+ *   judge: Agent.create({ provider })
+ *     .system('Pick the single best answer and explain why.')
+ *     .build(),
+ * });
+ *
+ * const result = await tot.run('What is the fastest sort for nearly-sorted data?');
+ * ```
+ */
+import { FlowChart } from '../concepts/FlowChart';
+import { Parallel } from '../concepts/Parallel';
+/**
+ * Build a Tree-of-Thoughts pipeline. Returns a `FlowChartRunner`.
+ *
+ * Throws if `branches < 2` — use a single runner directly when you don't need
+ * multiple candidates. Throws if `branches > 10` (Parallel's cap).
+ */
+export function treeOfThoughts(options) {
+    if (options.branches < 2) {
+        throw new Error(`treeOfThoughts requires at least 2 branches (got ${options.branches}). Use a single runner for 1-candidate flows.`);
+    }
+    const parallel = Parallel.create({
+        provider: options.provider,
+        name: `${options.name ?? 'treeOfThoughts'}:thinkers`,
+    });
+    for (let i = 0; i < options.branches; i++) {
+        parallel.agent(`thinker-${i}`, options.thinker(i), `Thinker ${i + 1}`);
+    }
+    // Merge: label each thought so the judge can reference them by id.
+    // Kept as a pure function so the merge itself uses no LLM call — the judge
+    // is the only decision-maker and should be budgeted as such.
+    parallel.merge((results) => Object.entries(results)
+        .map(([id, r]) => `=== ${id} ===\n${r.content}`)
+        .join('\n\n'));
+    return FlowChart.create()
+        .agent('thinkers', 'Think', parallel.build())
+        .agent('judge', 'Judge', options.judge)
+        .build();
+}
+//# sourceMappingURL=treeOfThoughts.js.map

package/dist/esm/patterns/treeOfThoughts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeOfThoughts.js","sourceRoot":"","sources":["../../../src/patterns/treeOfThoughts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,SAAS,EAAwB,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAqB,MAAM,sBAAsB,CAAC;AAmBnE;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAA8B;IAC3D,IAAI,OAAO,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,oDAAoD,OAAO,CAAC,QAAQ,+CAA+C,CACpH,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC/B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,IAAI,gBAAgB,WAAW;KACrD,CAAC,CAAC;IACH,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,mEAAmE;IACnE,2EAA2E;IAC3E,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAqC,EAAE,EAAE,CACvD,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;SACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/C,IAAI,CAAC,MAAM,CAAC,CAChB,CAAC;IAEF,OAAO,SAAS,CAAC,MAAM,EAAE;SACtB,KAAK,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;SAC5C,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC;SACtC,KAAK,EAAE,CAAC;AACb,CAAC"}

package/dist/esm/patterns.barrel.js

@@ -0,0 +1,8 @@
+/**
+ * agentfootprint/patterns — canonical composition patterns.
+ *
+ * See `src/patterns/index.ts` for the patterns themselves. This file is the
+ * subpath barrel used by package.json `exports['./patterns']`.
+ */
+export * from './patterns/index';
+//# sourceMappingURL=patterns.barrel.js.map

package/dist/esm/patterns.barrel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.barrel.js","sourceRoot":"","sources":["../../src/patterns.barrel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,kBAAkB,CAAC"}

package/dist/exportTrace.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * exportTrace — capture an agent run's full state into a portable JSON
+ * blob for sharing externally (paste into a viewer, ship to support, log
+ * for debugging, store in a database).
+ *
+ * Defaults to **redacted** output: snapshots come from
+ * `getSnapshot({ redact: true })` (footprintjs 4.14+), so values for keys
+ * listed in `RedactionPolicy.keys` / matching `patterns` arrive as
+ * `'REDACTED'` instead of raw. The commit log is already redacted at
+ * write-time. Combined with `emitPatterns` (also redacted at origin), the
+ * exported trace is safe to share when the caller has configured a policy.
+ *
+ * **Without a redaction policy, this helper still emits a trace — but
+ * `sharedState` will contain raw values.** Configure `setRedactionPolicy`
+ * before calling this for any externally shared trace.
+ *
+ * @example
+ * ```ts
+ * import { Agent, exportTrace, anthropic } from 'agentfootprint';
+ *
+ * const agent = Agent.create({ provider: anthropic('claude-sonnet-4') })
+ *   .system('You are a customer support agent.')
+ *   .build();
+ *
+ * await agent.run('My credit card 4242-4242-4242-4242 was declined');
+ *
+ * // Configure policy on the underlying executor for full safety
+ * // (concept-level recorder API for this is a follow-up).
+ * const trace = exportTrace(agent);
+ * console.log(JSON.stringify(trace, null, 2));
+ * // → paste into the playground viewer, send to support, etc.
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportTrace = void 0;
+/**
+ * Capture a full execution trace from any runner exposing the standard
+ * introspection surface (`getSnapshot`, `getNarrative*`, `getSpec`).
+ * All of those methods are optional — missing methods skip the field.
+ *
+ * Always returns a JSON-stringify-safe object.
+ */
+function exportTrace(runner, options) {
+    const redact = options?.redact !== false; // default true
+    const r = runner;
+    // `getSnapshot` may be the older 0-arg form — still safe to call with
+    // an arg (JS ignores extras), but keep our intent explicit so older
+    // overloads with strict signatures don't trip the type checker.
+    let snapshot;
+    try {
+        snapshot = r.getSnapshot?.({ redact });
+    }
+    catch {
+        // Fall back to the 0-arg form if the runner's signature rejects the
+        // options object (older custom runners). Result will be raw — caller
+        // is responsible for the safety implication when this happens.
+        try {
+            snapshot = r.getSnapshot?.();
+        }
+        catch {
+            snapshot = undefined;
+        }
+    }
+    return {
+        schemaVersion: 1,
+        exportedAt: new Date().toISOString(),
+        redacted: redact,
+        snapshot,
+        narrativeEntries: r.getNarrativeEntries?.(),
+        narrative: r.getNarrative?.(),
+        spec: r.getSpec?.(),
+    };
+}
+exports.exportTrace = exportTrace;
+//# sourceMappingURL=exportTrace.js.map

package/dist/exportTrace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exportTrace.js","sourceRoot":"","sources":["../src/exportTrace.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;;;AA4DH;;;;;;GAMG;AACH,SAAgB,WAAW,CAAC,MAAkB,EAAE,OAA4B;IAC1E,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC,CAAC,eAAe;IACzD,MAAM,CAAC,GAAG,MAA0B,CAAC;IAErC,sEAAsE;IACtE,oEAAoE;IACpE,gEAAgE;IAChE,IAAI,QAAiB,CAAC;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,oEAAoE;QACpE,qEAAqE;QACrE,+DAA+D;QAC/D,IAAI,CAAC;YACH,QAAQ,GAAI,CAAC,CAAC,WAA2C,EAAE,EAAE,CAAC;QAChE,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG,SAAS,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,QAAQ,EAAE,MAAM;QAChB,QAAQ;QACR,gBAAgB,EAAE,CAAC,CAAC,mBAAmB,EAAE,EAAE;QAC3C,SAAS,EAAE,CAAC,CAAC,YAAY,EAAE,EAAE;QAC7B,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE;KACpB,CAAC;AACJ,CAAC;AA9BD,kCA8BC"}

package/dist/index.js

@@ -13,8 +13,8 @@
  *   agentfootprint/stream        → Real-time lifecycle events
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolUsageRecorder = exports.TokenRecorder = exports.quickBind = exports.AgentPattern = exports.defineInstruction = exports.agentLoop = exports.LLMError = exports.urlImage = exports.base64Image = exports.imageBlock = exports.textBlock = exports.toolResultMessage = exports.assistantMessage = exports.userMessage = exports.systemMessage = exports.postgresStore = exports.dynamoStore = exports.redisStore = exports.InMemoryStore = exports.BrowserOpenAIAdapter = exports.BrowserAnthropicAdapter = exports.BedrockAdapter = exports.OpenAIAdapter = exports.AnthropicAdapter = exports.bedrock = exports.ollama = exports.openai = exports.anthropic = exports.createProvider = exports.MockRetriever = exports.mockRetriever = exports.MockAdapter = exports.mock = exports.ToolRegistry = exports.askHuman = exports.defineTool = exports.ConditionalRunner = exports.Conditional = exports.ParallelRunner = exports.Parallel = exports.SwarmRunner = exports.Swarm = exports.FlowChartRunner = exports.FlowChart = exports.RAGRunner = exports.RAG = exports.LLMCallRunner = exports.LLMCall = exports.AgentRunner = exports.Agent = void 0;
-exports.CostRecorder = exports.TurnRecorder = void 0;
+exports.TokenRecorder = exports.quickBind = exports.AgentPattern = exports.defineInstruction = exports.agentLoop = exports.LLMError = exports.urlImage = exports.base64Image = exports.imageBlock = exports.textBlock = exports.toolResultMessage = exports.assistantMessage = exports.userMessage = exports.systemMessage = exports.postgresStore = exports.dynamoStore = exports.redisStore = exports.InMemoryStore = exports.BrowserOpenAIAdapter = exports.BrowserAnthropicAdapter = exports.BedrockAdapter = exports.OpenAIAdapter = exports.AnthropicAdapter = exports.bedrock = exports.ollama = exports.openai = exports.anthropic = exports.createProvider = exports.MockRetriever = exports.mockRetriever = exports.MockAdapter = exports.mock = exports.ToolRegistry = exports.askHuman = exports.defineTool = exports.exportTrace = exports.ConditionalRunner = exports.Conditional = exports.ParallelRunner = exports.Parallel = exports.SwarmRunner = exports.Swarm = exports.FlowChartRunner = exports.FlowChart = exports.RAGRunner = exports.RAG = exports.LLMCallRunner = exports.LLMCall = exports.AgentRunner = exports.Agent = void 0;
+exports.CostRecorder = exports.TurnRecorder = exports.ToolUsageRecorder = void 0;
 // ── Concepts (Builders + Runners) ───────────────────────────
 var concepts_1 = require("./concepts");
 Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return concepts_1.Agent; } });
@@ -31,6 +31,9 @@ Object.defineProperty(exports, "Parallel", { enumerable: true, get: function ()
 Object.defineProperty(exports, "ParallelRunner", { enumerable: true, get: function () { return concepts_1.ParallelRunner; } });
 Object.defineProperty(exports, "Conditional", { enumerable: true, get: function () { return concepts_1.Conditional; } });
 Object.defineProperty(exports, "ConditionalRunner", { enumerable: true, get: function () { return concepts_1.ConditionalRunner; } });
+// ── Trace export (paste-into-viewer / share-with-support workflow) ─
+var exportTrace_1 = require("./exportTrace");
+Object.defineProperty(exports, "exportTrace", { enumerable: true, get: function () { return exportTrace_1.exportTrace; } });
 // ── Tools ───────────────────────────────────────────────────
 var tools_1 = require("./tools");
 Object.defineProperty(exports, "defineTool", { enumerable: true, get: function () { return tools_1.defineTool; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;;AAEH,+DAA+D;AAC/D,uCAeoB;AAdlB,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,mGAAA,OAAO,OAAA;AACP,yGAAA,aAAa,OAAA;AACb,+FAAA,GAAG,OAAA;AACH,qGAAA,SAAS,OAAA;AACT,qGAAA,SAAS,OAAA;AACT,2GAAA,eAAe,OAAA;AACf,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,oGAAA,QAAQ,OAAA;AACR,0GAAA,cAAc,OAAA;AACd,uGAAA,WAAW,OAAA;AACX,6GAAA,iBAAiB,OAAA;AASnB,+DAA+D;AAC/D,iCAA6D;AAApD,mGAAA,UAAU,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAAE,qGAAA,YAAY,OAAA;AAE3C,iEAAiE;AACjE,uCAA6F;AAApF,gGAAA,IAAI,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxE,mCAA8D;AAArD,mGAAA,SAAS,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,iGAAA,OAAO,OAAA;AAC3C,uCAA6E;AAApE,4GAAA,gBAAgB,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxD,uCAA2E;AAAlE,mHAAA,uBAAuB,OAAA;AAAE,gHAAA,oBAAoB,OAAA;AACtD,uDAA2D;AAAlD,yGAAA,aAAa,OAAA;AACtB,mDAAkF;AAAzE,oGAAA,UAAU,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,uGAAA,aAAa,OAAA;AAuB/C,+DAA+D;AAC/D,iCASiB;AARf,sGAAA,aAAa,OAAA;AACb,oGAAA,WAAW,OAAA;AACX,yGAAA,gBAAgB,OAAA;AAChB,0GAAA,iBAAiB,OAAA;AACjB,kGAAA,SAAS,OAAA;AACT,mGAAA,UAAU,OAAA;AACV,oGAAA,WAAW,OAAA;AACX,iGAAA,QAAQ,OAAA;AAGV,+DAA+D;AAC/D,iCAAmC;AAA1B,iGAAA,QAAQ,OAAA;AA0BjB,8DAA8D;AAC9D,uCAAuC;AAA9B,qGAAA,SAAS,OAAA;AAGlB,uEAAuE;AACvE,6DAAmF;AAA1E,wHAAA,iBAAiB,OAAA;AAAE,mHAAA,YAAY,OAAA;AAAE,gHAAA,SAAS,OAAA;AAGnD,+DAA+D;AAC/D,mDAAgG;AAAvF,+GAAA,aAAa,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,8GAAA,YAAY,OAAA;AAAE,8GAAA,YAAY,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;;AAEH,+DAA+D;AAC/D,uCAeoB;AAdlB,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,mGAAA,OAAO,OAAA;AACP,yGAAA,aAAa,OAAA;AACb,+FAAA,GAAG,OAAA;AACH,qGAAA,SAAS,OAAA;AACT,qGAAA,SAAS,OAAA;AACT,2GAAA,eAAe,OAAA;AACf,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,oGAAA,QAAQ,OAAA;AACR,0GAAA,cAAc,OAAA;AACd,uGAAA,WAAW,OAAA;AACX,6GAAA,iBAAiB,OAAA;AASnB,sEAAsE;AACtE,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AAGpB,+DAA+D;AAC/D,iCAA6D;AAApD,mGAAA,UAAU,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAAE,qGAAA,YAAY,OAAA;AAE3C,iEAAiE;AACjE,uCAA6F;AAApF,gGAAA,IAAI,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxE,mCAA8D;AAArD,mGAAA,SAAS,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,iGAAA,OAAO,OAAA;AAC3C,uCAA6E;AAApE,4GAAA,gBAAgB,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxD,uCAA2E;AAAlE,mHAAA,uBAAuB,OAAA;AAAE,gHAAA,oBAAoB,OAAA;AACtD,uDAA2D;AAAlD,yGAAA,aAAa,OAAA;AACtB,mDAAkF;AAAzE,oGAAA,UAAU,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,uGAAA,aAAa,OAAA;AAuB/C,+DAA+D;AAC/D,iCASiB;AARf,sGAAA,aAAa,OAAA;AACb,oGAAA,WAAW,OAAA;AACX,yGAAA,gBAAgB,OAAA;AAChB,0GAAA,iBAAiB,OAAA;AACjB,kGAAA,SAAS,OAAA;AACT,mGAAA,UAAU,OAAA;AACV,oGAAA,WAAW,OAAA;AACX,iGAAA,QAAQ,OAAA;AAGV,+DAA+D;AAC/D,iCAAmC;AAA1B,iGAAA,QAAQ,OAAA;AA0BjB,8DAA8D;AAC9D,uCAAuC;AAA9B,qGAAA,SAAS,OAAA;AAGlB,uEAAuE;AACvE,6DAAmF;AAA1E,wHAAA,iBAAiB,OAAA;AAAE,mHAAA,YAAY,OAAA;AAAE,gHAAA,SAAS,OAAA;AAGnD,+DAA+D;AAC/D,mDAAgG;AAAvF,+GAAA,aAAa,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,8GAAA,YAAY,OAAA;AAAE,8GAAA,YAAY,OAAA"}

package/dist/patterns/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * agentfootprint/patterns — canonical agent composition patterns.
+ *
+ * Each pattern is a thin factory over the existing concepts (`FlowChart`,
+ * `Parallel`, `Conditional`, `Agent`, `LLMCall`, `RAG`, `Swarm`). No new
+ * primitives. The source of each file shows the composition — read it to
+ * learn how to build your own.
+ *
+ * @example
+ * ```ts
+ * import { treeOfThoughts, reflexion, planExecute, mapReduce } from 'agentfootprint/patterns';
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reflexion = exports.treeOfThoughts = exports.mapReduce = exports.planExecute = void 0;
+var planExecute_1 = require("./planExecute");
+Object.defineProperty(exports, "planExecute", { enumerable: true, get: function () { return planExecute_1.planExecute; } });
+var mapReduce_1 = require("./mapReduce");
+Object.defineProperty(exports, "mapReduce", { enumerable: true, get: function () { return mapReduce_1.mapReduce; } });
+var treeOfThoughts_1 = require("./treeOfThoughts");
+Object.defineProperty(exports, "treeOfThoughts", { enumerable: true, get: function () { return treeOfThoughts_1.treeOfThoughts; } });
+var reflexion_1 = require("./reflexion");
+Object.defineProperty(exports, "reflexion", { enumerable: true, get: function () { return reflexion_1.reflexion; } });
+//# 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;;;;;;;;;;;;GAYG;;;AAEH,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AAGpB,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAGlB,mDAAkD;AAAzC,gHAAA,cAAc,OAAA;AAGvB,yCAAwC;AAA/B,sGAAA,SAAS,OAAA"}

package/dist/patterns/mapReduce.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * mapReduce — fan-out map over N pre-bound mappers, then reduce.
+ *
+ * Each mapper is a runner with its own input already bound (prepare them with
+ * the slice they should process). `Parallel.mergeWithLLM` or a custom reduce
+ * function combines the results. Under the hood: a single `Parallel` with N
+ * branches and one merge strategy.
+ *
+ * Why: map-reduce is a common shape — summarize N documents, compare N
+ * candidates, evaluate a prompt against N rubrics. Keeping it as a named
+ * pattern teaches the shape; each mapper / reducer is still a regular runner.
+ *
+ * @example
+ * ```ts
+ * import { LLMCall, anthropic } from 'agentfootprint';
+ * import { mapReduce } from 'agentfootprint/patterns';
+ *
+ * const documents = [doc1, doc2, doc3];
+ * const provider = anthropic('claude-sonnet-4');
+ *
+ * const pipeline = mapReduce({
+ *   provider,
+ *   mappers: documents.map((doc, i) => ({
+ *     id: `doc-${i}`,
+ *     description: `Summarize doc ${i}`,
+ *     runner: LLMCall.create({ provider })
+ *       .system(`Summarize this document:\n\n${doc}`)
+ *       .build(),
+ *   })),
+ *   reduce: { mode: 'llm', prompt: 'Combine the summaries into a single report.' },
+ * });
+ *
+ * const result = await pipeline.run('Produce the report');
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapReduce = void 0;
+const Parallel_1 = require("../concepts/Parallel");
+/**
+ * Build a map-reduce pipeline. Returns a `ParallelRunner` — plug it into
+ * `FlowChart`, `Conditional`, or `Agent.route()` like any other runner.
+ */
+function mapReduce(options) {
+    if (options.mappers.length < 2) {
+        throw new Error('mapReduce requires at least 2 mappers. Use a single runner directly if you only have one.');
+    }
+    const builder = Parallel_1.Parallel.create({
+        provider: options.provider,
+        name: options.name ?? 'mapReduce',
+    });
+    for (const m of options.mappers) {
+        builder.agent(m.id, m.runner, m.description);
+    }
+    if (options.reduce.mode === 'llm') {
+        builder.mergeWithLLM(options.reduce.prompt);
+    }
+    else {
+        builder.merge(options.reduce.fn);
+    }
+    return builder.build();
+}
+exports.mapReduce = mapReduce;
+//# sourceMappingURL=mapReduce.js.map

package/dist/patterns/mapReduce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapReduce.js","sourceRoot":"","sources":["../../src/patterns/mapReduce.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;;;AAEH,mDAAwF;AAwBxF;;;GAGG;AACH,SAAgB,SAAS,CAAC,OAAyB;IACjD,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,2FAA2F,CAC5F,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,mBAAQ,CAAC,MAAM,CAAC;QAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,WAAW;KAClC,CAAC,CAAC;IACH,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAChC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QAClC,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;AACzB,CAAC;AAnBD,8BAmBC"}

package/dist/patterns/planExecute.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * planExecute — Planner → Executor composition.
+ *
+ * Two runners chained sequentially: the planner takes the user request and
+ * produces a plan; the executor takes that plan (as the planner's output) and
+ * carries it out. Pure composition over `FlowChart` — no new primitives,
+ * readable as a teaching example.
+ *
+ * Why: separating planning from execution is often cheaper (small model
+ * plans, capable model executes) and safer (plan visible in narrative before
+ * any tool fires).
+ *
+ * @example
+ * ```ts
+ * import { Agent, anthropic } from 'agentfootprint';
+ * import { planExecute } from 'agentfootprint/patterns';
+ *
+ * const planner = Agent.create({ provider: anthropic('claude-haiku-4-5') })
+ *   .system('Produce a numbered plan. Do not execute.')
+ *   .build();
+ *
+ * const executor = Agent.create({ provider: anthropic('claude-sonnet-4') })
+ *   .system('Execute the given plan step by step.')
+ *   .tools([...])
+ *   .build();
+ *
+ * const runner = planExecute({ planner, executor });
+ * const result = await runner.run('Research competitors and draft a brief.');
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planExecute = void 0;
+const FlowChart_1 = require("../concepts/FlowChart");
+/**
+ * Build a planner → executor pipeline. Returns a `FlowChartRunner` — plug it
+ * into `Parallel`, `FlowChart`, `Conditional`, or `Agent.route()` like any
+ * other runner.
+ */
+function planExecute(options) {
+    return FlowChart_1.FlowChart.create()
+        .agent('plan', options.planName ?? 'Plan', options.planner)
+        .agent('execute', options.executeName ?? 'Execute', options.executor)
+        .build();
+}
+exports.planExecute = planExecute;
+//# sourceMappingURL=planExecute.js.map