@framers/agentos 0.1.112 → 0.1.114

package/dist/api/strategies/hierarchical.js

@@ -2,17 +2,41 @@
  * @file hierarchical.ts
  * Hierarchical strategy compiler for the Agency API.
  *
+ * ## Execution model
+ *
  * A manager agent (instantiated from the agency-level config) delegates
  * subtasks to sub-agents via tool calls. Each sub-agent is exposed as a
  * `delegate_to_<name>` tool that the manager can invoke to assign work.
  * The manager synthesizes sub-agent outputs into a final answer.
+ *
+ * ## Emergent wiring
+ *
+ * The manager does not follow a fixed execution order. It decides which
+ * agents to call, in what order, and with what subtasks -- based on the
+ * user prompt and its system instructions. This makes hierarchical the
+ * most flexible strategy, but also the most dependent on the manager
+ * model's ability to plan and delegate effectively.
+ *
+ * ## Tool-based delegation
+ *
+ * Each sub-agent becomes a tool with a JSON Schema parameter (`task: string`).
+ * The tool's `execute` function invokes the sub-agent's `generate()` and
+ * returns the result text. This leverages the LLM's native tool-calling
+ * capability for delegation, avoiding custom routing logic.
+ *
+ * @see {@link compileStrategy} -- the dispatcher that selects this compiler.
+ * @see {@link compileAdaptiveWrapper} -- wraps other strategies with a hierarchical manager.
  */
 import { agent as createAgent } from '../agent.js';
+import { mergeAdaptableTools } from '../toolAdapter.js';
 import { AgencyConfigError } from '../types.js';
 import { isAgent, resolveAgent, checkBeforeAgent } from './shared.js';
 /**
  * Extracts a human-readable description from an agent config or instance.
  *
+ * Used to build the team roster in the manager's system prompt so the manager
+ * knows what each sub-agent specialises in.
+ *
  * @param agentOrConfig - Either a pre-built Agent or a raw BaseAgentConfig.
  * @returns The instructions string if available, otherwise a generic label.
  */
@@ -37,7 +61,21 @@ function getAgentDescription(agentOrConfig) {
  * @param agencyConfig - Agency-level configuration; must include `model` or `provider`
  *   for the manager agent.
  * @returns A {@link CompiledStrategy} with `execute` and `stream` methods.
- * @throws {AgencyConfigError} When no agency-level model/provider is available for the manager.
+ * @throws {AgencyConfigError} When no agency-level model/provider is available
+ *   for the manager agent.
+ *
+ * @example
+ * ```ts
+ * const strategy = compileHierarchical(
+ *   {
+ *     researcher: { instructions: 'Find academic sources.' },
+ *     writer: { instructions: 'Write clear prose.' },
+ *   },
+ *   { model: 'openai:gpt-4o', agents: { ... } },
+ * );
+ * const result = await strategy.execute('Write a literature review on LLMs.');
+ * // The manager decided which agents to call and in what order.
+ * ```
  */
 export function compileHierarchical(agents, agencyConfig) {
     if (!agencyConfig.model && !agencyConfig.provider) {
@@ -46,7 +84,9 @@ export function compileHierarchical(agents, agencyConfig) {
     return {
         async execute(prompt, opts) {
             const agentCalls = [];
-            /* Build one tool per sub-agent for the manager to delegate to. */
+            // Build one tool per sub-agent for the manager to delegate to.
+            // The tool name follows the `delegate_to_<name>` convention so the
+            // manager can infer the agent's role from the tool name alone.
             const agentTools = {};
             for (const [name, agentOrConfig] of Object.entries(agents)) {
                 const description = getAgentDescription(agentOrConfig);
@@ -60,13 +100,13 @@ export function compileHierarchical(agents, agencyConfig) {
                         required: ['task'],
                     },
                     execute: async (args) => {
-                        /* HITL: check beforeAgent gate before delegating to this sub-agent. */
+                        // HITL: check beforeAgent gate before delegating to this sub-agent.
                         const decision = await checkBeforeAgent(name, args.task, agentCalls, agencyConfig);
                         if (decision && !decision.approved) {
                             return { success: false, data: `Agent "${name}" execution was rejected by HITL.` };
                         }
                         const a = resolveAgent(agentOrConfig, agencyConfig);
-                        /* Apply instruction modifications from the approval decision if any. */
+                        // Apply instruction modifications from the approval decision if any.
                         const effectiveTask = decision?.modifications?.instructions
                             ? `${args.task}\n\n[Additional instructions]: ${decision.modifications.instructions}`
                             : args.task;
@@ -76,6 +116,7 @@ export function compileHierarchical(agents, agencyConfig) {
                         const resultText = result.text ?? '';
                         const resultUsage = result.usage ?? {};
                         const resultToolCalls = result.toolCalls ?? [];
+                        // Record the sub-agent call for the final result's agentCalls array.
                         agentCalls.push({
                             agent: name,
                             input: args.task,
@@ -92,7 +133,8 @@ export function compileHierarchical(agents, agencyConfig) {
                     },
                 };
             }
-            /* Build the team roster description for the manager's system prompt. */
+            // Build the team roster description for the manager's system prompt.
+            // This tells the manager who is on the team and what each member does.
             const teamRoster = Object.entries(agents)
                 .map(([name, c]) => `- ${name}: ${getAgentDescription(c)}`)
                 .join('\n');
@@ -100,8 +142,9 @@ export function compileHierarchical(agents, agencyConfig) {
                 `Available team members:\n${teamRoster}\n\n` +
                 `Use the delegate_to_<name> tools to assign work. Synthesize their outputs into a final answer.` +
                 (agencyConfig.instructions ? `\n\n${agencyConfig.instructions}` : '');
-            /* Merge agency-level tools with the delegation tools. */
-            const mergedTools = { ...(agencyConfig.tools ?? {}), ...agentTools };
+            // Merge agency-level tools with the delegation tools. Agency tools
+            // (e.g. shared search, calculator) are available alongside delegation.
+            const mergedTools = mergeAdaptableTools(agencyConfig.tools, agentTools);
             const manager = createAgent({
                 model: agencyConfig.model,
                 provider: agencyConfig.provider,
@@ -109,13 +152,15 @@ export function compileHierarchical(agents, agencyConfig) {
                 baseUrl: agencyConfig.baseUrl,
                 instructions: managerInstructions,
                 tools: mergedTools,
+                // Higher maxSteps than default because the manager needs room to
+                // call multiple delegation tools before synthesizing.
                 maxSteps: agencyConfig.maxSteps ?? 10,
             });
             const result = (await manager.generate(prompt, opts));
             return { ...result, agentCalls };
         },
         stream(prompt, opts) {
-            /*
+            /**
              * For v1: streaming delegates to execute() and wraps the resolved text
              * as a single-chunk async iterable. A future version will stream the
              * manager's output in real-time.

package/dist/api/strategies/hierarchical.js.map

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

package/dist/api/strategies/index.d.ts

@@ -4,9 +4,23 @@
  *
  * Maps an {@link AgencyStrategy} discriminant to the concrete compiler that
  * produces a {@link CompiledStrategy}. Supports sequential, parallel, debate,
- * review-loop, and hierarchical strategies. When `adaptive` mode is enabled
- * on a non-hierarchical strategy, the dispatcher wraps it with an implicit
- * hierarchical manager that may override the default strategy at runtime.
+ * review-loop, hierarchical, and graph strategies.
+ *
+ * ## Adaptive mode
+ *
+ * When `adaptive` mode is enabled on a non-hierarchical strategy, the dispatcher
+ * wraps it with an implicit hierarchical manager that may override the default
+ * strategy at runtime. This works by:
+ *
+ * 1. Appending strategy-awareness instructions to the manager prompt.
+ * 2. Setting `adaptive: false` on the inner call to prevent infinite recursion.
+ * 3. Delegating to `compileHierarchical()` which creates delegation tools.
+ *
+ * The adaptive wrapper is transparent to the caller -- it still receives a
+ * standard {@link CompiledStrategy} with `execute` and `stream` methods.
+ *
+ * @see {@link compileStrategy} -- the main entry point for strategy compilation.
+ * @see {@link agency} -- the factory that calls compileStrategy during construction.
  */
 import type { AgencyStrategy, AgencyOptions, CompiledStrategy, Agent, BaseAgentConfig } from '../types.js';
 /**
@@ -21,7 +35,15 @@ import type { AgencyStrategy, AgencyOptions, CompiledStrategy, Agent, BaseAgentC
  * @param agents - Named roster of agent configs or pre-built `Agent` instances.
  * @param agencyConfig - Full agency-level configuration providing fallback values.
  * @returns A compiled strategy with `execute` and `stream` methods.
- * @throws {Error} When the requested strategy is not yet implemented.
+ * @throws {Error} When the requested strategy is not yet implemented (e.g. a
+ *         future strategy discriminant that has been added to `AgencyStrategy`
+ *         but not yet wired here).
+ *
+ * @example
+ * ```ts
+ * const strategy = compileStrategy('sequential', agents, agencyConfig);
+ * const result = await strategy.execute('Summarise AI research.');
+ * ```
  */
 export declare function compileStrategy(strategy: AgencyStrategy, agents: Record<string, BaseAgentConfig | Agent>, agencyConfig: AgencyOptions): CompiledStrategy;
 export { compileSequential } from './sequential.js';
@@ -31,4 +53,7 @@ export { compileReviewLoop } from './review-loop.js';
 export { compileHierarchical } from './hierarchical.js';
 export { compileGraph } from './graph.js';
 export { isAgent, mergeDefaults, resolveAgent, checkBeforeAgent } from './shared.js';
+export { compileAgencyToGraph, mapGraphResultToAgencyResult, mapGraphEventToAgencyEvent } from './graphCompiler.js';
+export { agentGraph, AgentGraphBuilder } from './agentGraphBuilder.js';
+export type { AgentNodeConfig } from './agentGraphBuilder.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/api/strategies/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,KAAK,EACL,eAAe,EAChB,MAAM,aAAa,CAAC;AAQrB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CAOlB;AAqED,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,KAAK,EACL,eAAe,EAChB,MAAM,aAAa,CAAC;AAQrB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CAUlB;AAgFD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AACpH,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACvE,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/api/strategies/index.js

@@ -16,10 +16,21 @@ import { compileGraph } from './graph.js';
  * @param agents - Named roster of agent configs or pre-built `Agent` instances.
  * @param agencyConfig - Full agency-level configuration providing fallback values.
  * @returns A compiled strategy with `execute` and `stream` methods.
- * @throws {Error} When the requested strategy is not yet implemented.
+ * @throws {Error} When the requested strategy is not yet implemented (e.g. a
+ *         future strategy discriminant that has been added to `AgencyStrategy`
+ *         but not yet wired here).
+ *
+ * @example
+ * ```ts
+ * const strategy = compileStrategy('sequential', agents, agencyConfig);
+ * const result = await strategy.execute('Summarise AI research.');
+ * ```
  */
 export function compileStrategy(strategy, agents, agencyConfig) {
-    /* When adaptive mode is enabled on non-hierarchical strategies, wrap with a manager. */
+    // When adaptive mode is enabled on non-hierarchical strategies, wrap with
+    // a manager that can override the strategy at runtime. Hierarchical is
+    // excluded because it IS the manager pattern -- wrapping it again would
+    // create a pointless double-manager layer.
     if (agencyConfig.adaptive && strategy !== 'hierarchical') {
         return compileAdaptiveWrapper(strategy, agents, agencyConfig);
     }
@@ -28,10 +39,15 @@ export function compileStrategy(strategy, agents, agencyConfig) {
 /**
  * Core strategy compiler without adaptive wrapping.
  *
+ * Dispatches on the strategy discriminant to the appropriate concrete compiler.
+ * Each compiler returns a {@link CompiledStrategy} with consistent `execute`
+ * and `stream` method signatures.
+ *
  * @param strategy - Strategy discriminant.
  * @param agents - Named agent roster.
  * @param agencyConfig - Agency-level configuration.
  * @returns A compiled strategy.
+ * @throws {Error} When the strategy is not recognised.
  * @internal
  */
 function compileStrategyCore(strategy, agents, agencyConfig) {
@@ -61,7 +77,13 @@ function compileStrategyCore(strategy, agents, agencyConfig) {
  * just like the hierarchical strategy, but with the additional context of the
  * original intended strategy.
  *
- * @param defaultStrategy - The user-declared default strategy.
+ * ## Recursion prevention
+ *
+ * `adaptive: false` is set on the inner config to prevent the hierarchical
+ * compiler from re-entering the adaptive wrapper, which would cause infinite
+ * recursion.
+ *
+ * @param defaultStrategy - The user-declared default strategy (e.g. `"sequential"`).
  * @param agents - Named agent roster.
  * @param agencyConfig - Agency-level configuration.
  * @returns A compiled hierarchical strategy with adaptive instructions.
@@ -74,7 +96,7 @@ function compileAdaptiveWrapper(defaultStrategy, agents, agencyConfig) {
     const adaptiveConfig = {
         ...agencyConfig,
         instructions: adaptiveInstructions,
-        /* Disable adaptive on the inner call to prevent infinite recursion. */
+        // Disable adaptive on the inner call to prevent infinite recursion.
         adaptive: false,
     };
     return compileHierarchical(agents, adaptiveConfig);
@@ -86,4 +108,6 @@ export { compileReviewLoop } from './review-loop.js';
 export { compileHierarchical } from './hierarchical.js';
 export { compileGraph } from './graph.js';
 export { isAgent, mergeDefaults, resolveAgent, checkBeforeAgent } from './shared.js';
+export { compileAgencyToGraph, mapGraphResultToAgencyResult, mapGraphEventToAgencyEvent } from './graphCompiler.js';
+export { agentGraph, AgentGraphBuilder } from './agentGraphBuilder.js';
 //# sourceMappingURL=index.js.map

package/dist/api/strategies/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/strategies/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAwB,EACxB,MAA+C,EAC/C,YAA2B;IAE3B,wFAAwF;IACxF,IAAI,YAAY,CAAC,QAAQ,IAAI,QAAQ,KAAK,cAAc,EAAE,CAAC;QACzD,OAAO,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,mBAAmB,CAC1B,QAAwB,EACxB,MAA+C,EAC/C,YAA2B;IAE3B,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,YAAY;YACf,OAAO,iBAAiB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACjD,KAAK,UAAU;YACb,OAAO,eAAe,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC/C,KAAK,QAAQ;YACX,OAAO,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC7C,KAAK,aAAa;YAChB,OAAO,iBAAiB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACjD,KAAK,cAAc;YACjB,OAAO,mBAAmB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACnD,KAAK,OAAO;YACV,OAAO,YAAY,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC5C;YACE,MAAM,IAAI,KAAK,CAAC,aAAa,QAAQ,uBAAuB,CAAC,CAAC;IAClE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,sBAAsB,CAC7B,eAA+B,EAC/B,MAA+C,EAC/C,YAA2B;IAE3B,MAAM,oBAAoB,GACxB,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,YAAY,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,6BAA6B,eAAe,sEAAsE;QAClH,yFAAyF,CAAC;IAE5F,MAAM,cAAc,GAAkB;QACpC,GAAG,YAAY;QACf,YAAY,EAAE,oBAAoB;QAClC,uEAAuE;QACvE,QAAQ,EAAE,KAAK;KAChB,CAAC;IAEF,OAAO,mBAAmB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACrD,CAAC;AAED,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/strategies/index.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAwB,EACxB,MAA+C,EAC/C,YAA2B;IAE3B,0EAA0E;IAC1E,uEAAuE;IACvE,wEAAwE;IACxE,2CAA2C;IAC3C,IAAI,YAAY,CAAC,QAAQ,IAAI,QAAQ,KAAK,cAAc,EAAE,CAAC;QACzD,OAAO,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,mBAAmB,CAC1B,QAAwB,EACxB,MAA+C,EAC/C,YAA2B;IAE3B,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,YAAY;YACf,OAAO,iBAAiB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACjD,KAAK,UAAU;YACb,OAAO,eAAe,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC/C,KAAK,QAAQ;YACX,OAAO,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC7C,KAAK,aAAa;YAChB,OAAO,iBAAiB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACjD,KAAK,cAAc;YACjB,OAAO,mBAAmB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACnD,KAAK,OAAO;YACV,OAAO,YAAY,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC5C;YACE,MAAM,IAAI,KAAK,CAAC,aAAa,QAAQ,uBAAuB,CAAC,CAAC;IAClE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,sBAAsB,CAC7B,eAA+B,EAC/B,MAA+C,EAC/C,YAA2B;IAE3B,MAAM,oBAAoB,GACxB,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,YAAY,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,6BAA6B,eAAe,sEAAsE;QAClH,yFAAyF,CAAC;IAE5F,MAAM,cAAc,GAAkB;QACpC,GAAG,YAAY;QACf,YAAY,EAAE,oBAAoB;QAClC,oEAAoE;QACpE,QAAQ,EAAE,KAAK;KAChB,CAAC;IAEF,OAAO,mBAAmB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACrD,CAAC;AAED,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AACpH,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/api/strategies/parallel.d.ts

@@ -3,15 +3,26 @@ import type { AgencyOptions, CompiledStrategy, Agent, BaseAgentConfig } from '..
  * Compiles a parallel execution strategy.
  *
  * All agents are invoked concurrently with the same prompt via
- * `Promise.all`. Once every agent has responded, a synthesis agent
- * (instantiated from the agency-level config) combines the individual
- * outputs into a single coherent response.
+ * `Promise.allSettled`. Once every agent has responded (or failed), a
+ * synthesis agent (instantiated from the agency-level config) combines the
+ * individual outputs into a single coherent response.
  *
  * @param agents - Named roster of agent configs or pre-built `Agent` instances.
  * @param agencyConfig - Agency-level configuration; must include `model` or `provider`
  *   for the synthesis step.
  * @returns A {@link CompiledStrategy} with `execute` and `stream` methods.
- * @throws {AgencyConfigError} When no agency-level model/provider is available for synthesis.
+ * @throws {AgencyConfigError} When no agency-level model/provider is available
+ *   for the synthesis step. The synthesis agent needs an LLM to combine the
+ *   parallel outputs.
+ *
+ * @example
+ * ```ts
+ * const strategy = compileParallel(
+ *   { factChecker: factAgent, writer: writeAgent },
+ *   { model: 'openai:gpt-4o', agents: { factChecker: factAgent, writer: writeAgent } },
+ * );
+ * const result = await strategy.execute('Write a fact-checked article.');
+ * ```
  */
 export declare function compileParallel(agents: Record<string, BaseAgentConfig | Agent>, agencyConfig: AgencyOptions): CompiledStrategy;
 //# sourceMappingURL=parallel.d.ts.map

package/dist/api/strategies/parallel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/parallel.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,KAAK,EACL,eAAe,EAEhB,MAAM,aAAa,CAAC;AAIrB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CAyIlB"}
+{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/parallel.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,KAAK,EACL,eAAe,EAEhB,MAAM,aAAa,CAAC;AAIrB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CAiJlB"}

package/dist/api/strategies/parallel.js

@@ -2,9 +2,27 @@
  * @file parallel.ts
  * Parallel strategy compiler for the Agency API.
  *
- * Runs all agents concurrently on the same prompt, then synthesizes their
- * outputs into a single coherent response using the agency-level model.
- * Requires an agency-level `model` or `provider` for the synthesis step.
+ * ## Execution model
+ *
+ * Runs all agents concurrently on the same prompt via `Promise.allSettled`,
+ * then synthesizes their outputs into a single coherent response using the
+ * agency-level model. Requires an agency-level `model` or `provider` for
+ * the synthesis step.
+ *
+ * ## Error handling
+ *
+ * Individual agent failures do not abort the entire run. `Promise.allSettled`
+ * collects both fulfilled and rejected outcomes. Rejected agents emit an
+ * `error` callback event and are excluded from the synthesis prompt, so the
+ * remaining agents' outputs still produce a valid result.
+ *
+ * ## HITL integration
+ *
+ * Each agent is gated by {@link checkBeforeAgent} before invocation. Rejected
+ * agents return `null` and are filtered out before synthesis.
+ *
+ * @see {@link compileStrategy} -- the dispatcher that selects this compiler.
+ * @see {@link compileSequential} -- the simpler alternative for ordered pipelines.
  */
 import { agent as createAgent } from '../agent.js';
 import { AgencyConfigError } from '../types.js';
@@ -13,15 +31,26 @@ import { isAgent, mergeDefaults, checkBeforeAgent } from './shared.js';
  * Compiles a parallel execution strategy.
  *
  * All agents are invoked concurrently with the same prompt via
- * `Promise.all`. Once every agent has responded, a synthesis agent
- * (instantiated from the agency-level config) combines the individual
- * outputs into a single coherent response.
+ * `Promise.allSettled`. Once every agent has responded (or failed), a
+ * synthesis agent (instantiated from the agency-level config) combines the
+ * individual outputs into a single coherent response.
  *
  * @param agents - Named roster of agent configs or pre-built `Agent` instances.
  * @param agencyConfig - Agency-level configuration; must include `model` or `provider`
  *   for the synthesis step.
  * @returns A {@link CompiledStrategy} with `execute` and `stream` methods.
- * @throws {AgencyConfigError} When no agency-level model/provider is available for synthesis.
+ * @throws {AgencyConfigError} When no agency-level model/provider is available
+ *   for the synthesis step. The synthesis agent needs an LLM to combine the
+ *   parallel outputs.
+ *
+ * @example
+ * ```ts
+ * const strategy = compileParallel(
+ *   { factChecker: factAgent, writer: writeAgent },
+ *   { model: 'openai:gpt-4o', agents: { factChecker: factAgent, writer: writeAgent } },
+ * );
+ * const result = await strategy.execute('Write a fact-checked article.');
+ * ```
  */
 export function compileParallel(agents, agencyConfig) {
     if (!agencyConfig.model && !agencyConfig.provider) {
@@ -29,19 +58,21 @@ export function compileParallel(agents, agencyConfig) {
     }
     return {
         async execute(prompt, opts) {
-            /* Run every agent concurrently, gated by beforeAgent HITL. */
+            // Run every agent concurrently, gated by beforeAgent HITL.
+            // Promise.allSettled is used (not Promise.all) so that individual
+            // agent failures don't abort the entire parallel run.
             const entries = Object.entries(agents);
             const allSettled = await Promise.allSettled(entries.map(async ([name, agentOrConfig]) => {
-                /* HITL: check beforeAgent gate before invoking this agent. */
+                // HITL: check beforeAgent gate before invoking this agent.
                 const decision = await checkBeforeAgent(name, prompt, [], agencyConfig);
                 if (decision && !decision.approved) {
-                    /* Agent was rejected — exclude from results. */
+                    // Agent was rejected -- exclude from results.
                     return null;
                 }
                 const a = isAgent(agentOrConfig)
                     ? agentOrConfig
                     : createAgent({ ...mergeDefaults(agentOrConfig, agencyConfig) });
-                /* Apply instruction modifications from the approval decision if any. */
+                // Apply instruction modifications from the approval decision if any.
                 const effectivePrompt = decision?.modifications?.instructions
                     ? `${prompt}\n\n[Additional instructions]: ${decision.modifications.instructions}`
                     : prompt;
@@ -50,7 +81,9 @@ export function compileParallel(agents, agencyConfig) {
                 const durationMs = Date.now() - start;
                 return { name, result, durationMs };
             }));
-            /* Log errors from rejected agents and keep only fulfilled results. */
+            // Log errors from rejected agents and keep only fulfilled results.
+            // This two-pass approach lets us collect error telemetry while still
+            // producing a valid synthesis from the successful agents.
             const settled = [];
             for (let i = 0; i < allSettled.length; i++) {
                 const outcome = allSettled[i];
@@ -65,12 +98,12 @@ export function compileParallel(agents, agencyConfig) {
                     });
                     continue;
                 }
-                /* Skip null results (HITL-rejected agents). */
+                // Skip null results (HITL-rejected agents).
                 if (outcome.value !== null) {
                     settled.push(outcome.value);
                 }
             }
-            /* Collect agent call records and aggregate usage. */
+            // Collect agent call records and aggregate usage.
             const agentCalls = [];
             const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
             for (const { name, result, durationMs } of settled) {
@@ -92,7 +125,9 @@ export function compileParallel(agents, agencyConfig) {
                 totalUsage.completionTokens += resultUsage.completionTokens ?? 0;
                 totalUsage.totalTokens += resultUsage.totalTokens ?? 0;
             }
-            /* Synthesize outputs using the agency-level model. */
+            // Synthesize outputs using the agency-level model.
+            // Each agent's output is labeled with its name so the synthesizer
+            // knows which perspective came from which agent.
             const agentOutputsBlock = settled
                 .map(({ name, result }) => `--- ${name} ---\n${result.text ?? ''}`)
                 .join('\n\n');
@@ -102,6 +137,8 @@ export function compileParallel(agents, agencyConfig) {
             const synthPrompt = `Multiple agents analyzed the following task:\n"${prompt}"\n\n` +
                 `${agentOutputsBlock}\n\n` +
                 `Synthesize these into a single coherent response.${synthInstructions}`;
+            // Create a fresh single-step synthesizer agent. maxSteps: 1 because
+            // the synthesis should be a single LLM call, not an agentic loop.
             const synthesizer = createAgent({
                 model: agencyConfig.model,
                 provider: agencyConfig.provider,
@@ -117,7 +154,7 @@ export function compileParallel(agents, agencyConfig) {
             return { ...synthesis, agentCalls, usage: totalUsage };
         },
         stream(prompt, opts) {
-            /*
+            /**
              * For v1: streaming delegates to execute() and wraps the resolved text
              * as a single-chunk async iterable. A future version will stream the
              * synthesis step in real-time.

package/dist/api/strategies/parallel.js.map

@@ -1 +1 @@
-{"version":3,"file":"parallel.js","sourceRoot":"","sources":["../../../src/api/strategies/parallel.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,aAAa,CAAC;AAQnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA+C,EAC/C,YAA2B;IAE3B,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,iBAAiB,CACzB,oFAAoF,CACrF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI;YACxB,8DAA8D;YAC9D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACvC,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,UAAU,CACzC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,aAAa,CAAC,EAAE,EAAE;gBAC1C,8DAA8D;gBAC9D,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,CAAC,CAAC;gBACxE,IAAI,QAAQ,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;oBACnC,gDAAgD;oBAChD,OAAO,IAAI,CAAC;gBACd,CAAC;gBAED,MAAM,CAAC,GAAU,OAAO,CAAC,aAAa,CAAC;oBACrC,CAAC,CAAC,aAAa;oBACf,CAAC,CAAC,WAAW,CAAC,EAAE,GAAG,aAAa,CAAC,aAAa,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC;gBAEnE,wEAAwE;gBACxE,MAAM,eAAe,GAAG,QAAQ,EAAE,aAAa,EAAE,YAAY;oBAC3D,CAAC,CAAC,GAAG,MAAM,kCAAkC,QAAQ,CAAC,aAAa,CAAC,YAAY,EAAE;oBAClF,CAAC,CAAC,MAAM,CAAC;gBAEX,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBACzB,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC,CAA4B,CAAC;gBACpF,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;gBACtC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;YACtC,CAAC,CAAC,CACH,CAAC;YAEF,sEAAsE;YACtE,MAAM,OAAO,GAAiF,EAAE,CAAC;YACjG,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC3C,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;gBAC9B,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;oBAClC,MAAM,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;oBAChC,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;oBACnG,OAAO,CAAC,KAAK,CAAC,8BAA8B,SAAS,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;oBACjF,YAAY,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC;wBACvB,KAAK,EAAE,SAAS;wBAChB,KAAK;wBACL,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;qBACtB,CAAC,CAAC;oBACH,SAAS;gBACX,CAAC;gBACD,+CAA+C;gBAC/C,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;oBAC3B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC;YAED,qDAAqD;YACrD,MAAM,UAAU,GAAsB,EAAE,CAAC;YACzC,MAAM,UAAU,GAAG,EAAE,YAAY,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;YAE5E,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,OAAO,EAAE,CAAC;gBACnD,MAAM,WAAW,GAAI,MAAM,CAAC,KAAoF,IAAI,EAAE,CAAC;gBACvH,MAAM,eAAe,GAAI,MAAM,CAAC,SAAsF,IAAI,EAAE,CAAC;gBAE7H,UAAU,CAAC,IAAI,CAAC;oBACd,KAAK,EAAE,IAAI;oBACX,KAAK,EAAE,MAAM;oBACb,MAAM,EAAG,MAAM,CAAC,IAAe,IAAI,EAAE;oBACrC,SAAS,EAAE,eAAe;oBAC1B,KAAK,EAAE;wBACL,YAAY,EAAE,WAAW,CAAC,YAAY,IAAI,CAAC;wBAC3C,gBAAgB,EAAE,WAAW,CAAC,gBAAgB,IAAI,CAAC;wBACnD,WAAW,EAAE,WAAW,CAAC,WAAW,IAAI,CAAC;qBAC1C;oBACD,UAAU;iBACX,CAAC,CAAC;gBAEH,UAAU,CAAC,YAAY,IAAI,WAAW,CAAC,YAAY,IAAI,CAAC,CAAC;gBACzD,UAAU,CAAC,gBAAgB,IAAI,WAAW,CAAC,gBAAgB,IAAI,CAAC,CAAC;gBACjE,UAAU,CAAC,WAAW,IAAI,WAAW,CAAC,WAAW,IAAI,CAAC,CAAC;YACzD,CAAC;YAED,sDAAsD;YACtD,MAAM,iBAAiB,GAAG,OAAO;iBAC9B,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,OAAO,IAAI,SAAU,MAAM,CAAC,IAAe,IAAI,EAAE,EAAE,CAAC;iBAC9E,IAAI,CAAC,MAAM,CAAC,CAAC;YAEhB,MAAM,iBAAiB,GAAG,YAAY,CAAC,YAAY;gBACjD,CAAC,CAAC,OAAO,YAAY,CAAC,YAAY,EAAE;gBACpC,CAAC,CAAC,EAAE,CAAC;YAEP,MAAM,WAAW,GACf,kDAAkD,MAAM,OAAO;gBAC/D,GAAG,iBAAiB,MAAM;gBAC1B,oDAAoD,iBAAiB,EAAE,CAAC;YAE1E,MAAM,WAAW,GAAG,WAAW,CAAC;gBAC9B,KAAK,EAAE,YAAY,CAAC,KAAK;gBACzB,QAAQ,EAAE,YAAY,CAAC,QAAQ;gBAC/B,MAAM,EAAE,YAAY,CAAC,MAAM;gBAC3B,OAAO,EAAE,YAAY,CAAC,OAAO;gBAC7B,QAAQ,EAAE,CAAC;aACZ,CAAC,CAAC;YAEH,MAAM,SAAS,GAAG,CAAC,MAAM,WAAW,CAAC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,CAAuC,CAAC;YACxG,MAAM,UAAU,GAAI,SAAS,CAAC,KAAoF,IAAI,EAAE,CAAC;YAEzH,UAAU,CAAC,YAAY,IAAI,UAAU,CAAC,YAAY,IAAI,CAAC,CAAC;YACxD,UAAU,CAAC,gBAAgB,IAAI,UAAU,CAAC,gBAAgB,IAAI,CAAC,CAAC;YAChE,UAAU,CAAC,WAAW,IAAI,UAAU,CAAC,WAAW,IAAI,CAAC,CAAC;YAEtD,OAAO,EAAE,GAAG,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QACzD,CAAC;QAED,MAAM,CAAC,MAAM,EAAE,IAAI;YACjB;;;;eAIG;YACH,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAqC,CAAC;YACrF,MAAM,WAAW,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAC,CAAC,IAAe,IAAI,EAAE,CAAC,CAAC;YAExE,OAAO;gBACL,UAAU,EAAE,CAAC,KAAK,SAAS,CAAC;oBAC1B,MAAM,MAAM,WAAW,CAAC;gBAC1B,CAAC,CAAC,EAAE;gBACJ,UAAU,EAAE,CAAC,KAAK,SAAS,CAAC;oBAC1B,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC;oBAC/B,MAAM,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC;gBACxC,CAAC,CAAC,EAAE;gBACJ,IAAI,EAAE,WAAW;gBACjB,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;aAC1C,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"parallel.js","sourceRoot":"","sources":["../../../src/api/strategies/parallel.ts"],"names":[],"mappings":"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"}

package/dist/api/strategies/review-loop.d.ts

@@ -9,10 +9,24 @@ import type { AgencyOptions, CompiledStrategy, Agent, BaseAgentConfig } from '..
  * producer for revision, up to `maxRounds` iterations.
  *
  * @param agents - Named roster of agent configs or pre-built `Agent` instances.
- *   At least two agents are required (producer + reviewer).
+ *   At least two agents are required (producer + reviewer). The first entry
+ *   is the producer, the second is the reviewer.
  * @param agencyConfig - Agency-level configuration providing fallback model/provider/tools.
  * @returns A {@link CompiledStrategy} with `execute` and `stream` methods.
  * @throws {AgencyConfigError} When fewer than two agents are provided.
+ *
+ * @example
+ * ```ts
+ * const strategy = compileReviewLoop(
+ *   {
+ *     writer: { instructions: 'Write a blog post.' },
+ *     editor: { instructions: 'Review for clarity and accuracy.' },
+ *   },
+ *   { maxRounds: 3, agents: { ... } },
+ * );
+ * const result = await strategy.execute('Write about TypeScript generics.');
+ * // result.text is the final approved draft.
+ * ```
  */
 export declare function compileReviewLoop(agents: Record<string, BaseAgentConfig | Agent>, agencyConfig: AgencyOptions): CompiledStrategy;
 //# sourceMappingURL=review-loop.d.ts.map

package/dist/api/strategies/review-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"review-loop.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/review-loop.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,KAAK,EACL,eAAe,EAEhB,MAAM,aAAa,CAAC;AA6BrB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CAqIlB"}
+{"version":3,"file":"review-loop.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/review-loop.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,KAAK,EACL,eAAe,EAEhB,MAAM,aAAa,CAAC;AAmCrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CA2IlB"}