@framers/agentos 0.1.111 → 0.1.113

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":"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"}
+{"version":3,"file":"parallel.js","sourceRoot":"","sources":["../../../src/api/strategies/parallel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;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;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;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,2DAA2D;YAC3D,kEAAkE;YAClE,sDAAsD;YACtD,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,2DAA2D;gBAC3D,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,8CAA8C;oBAC9C,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,qEAAqE;gBACrE,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,mEAAmE;YACnE,qEAAqE;YACrE,0DAA0D;YAC1D,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,4CAA4C;gBAC5C,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;oBAC3B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC;YAED,kDAAkD;YAClD,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,mDAAmD;YACnD,kEAAkE;YAClE,iDAAiD;YACjD,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,oEAAoE;YACpE,kEAAkE;YAClE,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"}

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"}

package/dist/api/strategies/review-loop.js

@@ -7,6 +7,12 @@ import { resolveAgent, checkBeforeAgent } from './shared.js';
  * When the response is not valid JSON, or lacks an `approved` boolean, the entire
  * text is treated as feedback and the draft is considered not approved.
  *
+ * ## Why parse gracefully?
+ *
+ * LLMs frequently wrap JSON in markdown code fences or add prose around it.
+ * By falling back to "not approved with full text as feedback", we ensure the
+ * loop always makes progress instead of crashing on malformed JSON.
+ *
  * @param text - Raw reviewer output text.
  * @returns Parsed review with approval status and feedback string.
  */
@@ -21,7 +27,7 @@ function parseReview(text) {
         }
     }
     catch {
-        /* Not valid JSON — fall through to treat entire text as feedback. */
+        // Not valid JSON -- fall through to treat entire text as feedback.
     }
     return { approved: false, feedback: text };
 }
@@ -35,16 +41,32 @@ function parseReview(text) {
  * 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 function compileReviewLoop(agents, agencyConfig) {
     const entries = Object.entries(agents);
     if (entries.length < 2) {
         throw new AgencyConfigError('Review-loop strategy requires at least two agents (producer + reviewer).');
     }
+    // Default to 3 rounds when not specified -- enough for meaningful revision
+    // without excessive back-and-forth.
     const maxRounds = agencyConfig.maxRounds ?? 3;
     const [producerName, producerConfig] = entries[0];
     const [reviewerName, reviewerConfig] = entries[1];
@@ -57,13 +79,16 @@ export function compileReviewLoop(agents, agencyConfig) {
             let draft = '';
             let feedback = '';
             for (let round = 0; round < maxRounds; round++) {
-                /* ---- HITL: check beforeAgent gate for the producer ---- */
+                // ---- HITL: check beforeAgent gate for the producer ----
                 const prodDecision = await checkBeforeAgent(producerName, prompt, agentCalls, agencyConfig);
                 if (prodDecision && !prodDecision.approved) {
-                    /* Producer rejected — terminate the loop early. */
+                    // Producer rejected -- terminate the loop early.
+                    // The current draft (empty or from a prior round) becomes the final output.
                     break;
                 }
-                /* ---- Producer creates or revises ---- */
+                // ---- Producer creates or revises ----
+                // On the first round, the producer sees the original task.
+                // On subsequent rounds, it sees the task + its prior draft + reviewer feedback.
                 const prodPrompt = round === 0
                     ? prompt
                     : `${prompt}\n\nYour previous draft:\n${draft}\n\nReviewer feedback:\n${feedback}\n\nRevise your work.`;
@@ -89,13 +114,13 @@ export function compileReviewLoop(agents, agencyConfig) {
                 totalUsage.promptTokens += prodUsage.promptTokens ?? 0;
                 totalUsage.completionTokens += prodUsage.completionTokens ?? 0;
                 totalUsage.totalTokens += prodUsage.totalTokens ?? 0;
-                /* ---- HITL: check beforeAgent gate for the reviewer ---- */
+                // ---- HITL: check beforeAgent gate for the reviewer ----
                 const revDecision = await checkBeforeAgent(reviewerName, prompt, agentCalls, agencyConfig);
                 if (revDecision && !revDecision.approved) {
-                    /* Reviewer rejected — accept the current draft and break. */
+                    // Reviewer rejected -- accept the current draft and break.
                     break;
                 }
-                /* ---- Reviewer evaluates ---- */
+                // ---- Reviewer evaluates ----
                 const revPrompt = `Review this work for the task: "${prompt}"\n\n` +
                     `Draft:\n${draft}\n\n` +
                     `Respond with JSON: { "approved": true/false, "feedback": "..." }`;
@@ -120,7 +145,8 @@ export function compileReviewLoop(agents, agencyConfig) {
                 totalUsage.promptTokens += revUsage.promptTokens ?? 0;
                 totalUsage.completionTokens += revUsage.completionTokens ?? 0;
                 totalUsage.totalTokens += revUsage.totalTokens ?? 0;
-                /* Parse the review decision. */
+                // Parse the review decision. If approved, exit the loop early.
+                // If not, capture feedback for the next producer revision.
                 const review = parseReview(revText);
                 if (review.approved)
                     break;
@@ -129,7 +155,7 @@ export function compileReviewLoop(agents, agencyConfig) {
             return { text: draft, 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
              * producer's output in real-time during the final round.

package/dist/api/strategies/review-loop.js.map

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

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

@@ -5,11 +5,21 @@ import type { AgencyOptions, CompiledStrategy, Agent, BaseAgentConfig } from '..
  * Agents are invoked one-by-one in their declared iteration order. Each agent
  * after the first receives a prompt that includes both the original task and
  * the preceding agent's output, enabling progressive refinement chains such as
- * researcher -> editor -> reviewer.
+ * `researcher -> editor -> reviewer`.
  *
  * @param agents - Named roster of agent configs or pre-built `Agent` instances.
+ *                 Iteration order of `Object.entries()` determines execution order.
  * @param agencyConfig - Agency-level configuration providing fallback model/provider/tools.
  * @returns A {@link CompiledStrategy} with `execute` and `stream` methods.
+ *
+ * @example
+ * ```ts
+ * const strategy = compileSequential(
+ *   { researcher: { instructions: 'Find info.' }, writer: { instructions: 'Write summary.' } },
+ *   agencyConfig,
+ * );
+ * const result = await strategy.execute('Summarise recent AI research.');
+ * ```
  */
 export declare function compileSequential(agents: Record<string, BaseAgentConfig | Agent>, agencyConfig: AgencyOptions): CompiledStrategy;
 //# sourceMappingURL=sequential.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sequential.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/sequential.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,KAAK,EACL,eAAe,EAIhB,MAAM,aAAa,CAAC;AAGrB;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CAqNlB"}
+{"version":3,"file":"sequential.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/sequential.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,KAAK,EACL,eAAe,EAIhB,MAAM,aAAa,CAAC;AAGrB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CA2NlB"}

package/dist/api/strategies/sequential.js

@@ -2,9 +2,24 @@
  * @file sequential.ts
  * Sequential strategy compiler for the Agency API.
  *
+ * ## Execution model
+ *
  * Iterates agents in declaration order. Each agent receives the previous
  * agent's output as context, forming a chain where the final agent's response
  * is the overall result. Token usage is aggregated across all agent calls.
+ *
+ * This is the simplest and most common strategy -- ideal for pipelines like
+ * `researcher -> editor -> reviewer` where each step builds on the previous.
+ *
+ * ## HITL integration
+ *
+ * Each agent is gated by {@link checkBeforeAgent} before invocation. If the
+ * HITL handler rejects an agent, it is skipped and the chain continues with
+ * the next agent using the same context (the rejected agent's contribution
+ * is simply omitted).
+ *
+ * @see {@link compileStrategy} -- the dispatcher that selects this compiler.
+ * @see {@link checkBeforeAgent} -- the HITL gate applied before each agent.
  */
 import { agent as createAgent } from '../agent.js';
 import { isAgent, mergeDefaults, checkBeforeAgent } from './shared.js';
@@ -14,11 +29,21 @@ import { isAgent, mergeDefaults, checkBeforeAgent } from './shared.js';
  * Agents are invoked one-by-one in their declared iteration order. Each agent
  * after the first receives a prompt that includes both the original task and
  * the preceding agent's output, enabling progressive refinement chains such as
- * researcher -> editor -> reviewer.
+ * `researcher -> editor -> reviewer`.
  *
  * @param agents - Named roster of agent configs or pre-built `Agent` instances.
+ *                 Iteration order of `Object.entries()` determines execution order.
  * @param agencyConfig - Agency-level configuration providing fallback model/provider/tools.
  * @returns A {@link CompiledStrategy} with `execute` and `stream` methods.
+ *
+ * @example
+ * ```ts
+ * const strategy = compileSequential(
+ *   { researcher: { instructions: 'Find info.' }, writer: { instructions: 'Write summary.' } },
+ *   agencyConfig,
+ * );
+ * const result = await strategy.execute('Summarise recent AI research.');
+ * ```
  */
 export function compileSequential(agents, agencyConfig) {
     return {
@@ -28,16 +53,21 @@ export function compileSequential(agents, agencyConfig) {
             let lastResult = null;
             const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
             for (const [name, agentOrConfig] of Object.entries(agents)) {
-                /* HITL: check beforeAgent gate before invoking this agent. */
+                // HITL: check beforeAgent gate before invoking this agent.
+                // Returns null when no gate applies; returns a decision when the
+                // agent is in the approval list.
                 const decision = await checkBeforeAgent(name, context, agentCalls, agencyConfig);
                 if (decision && !decision.approved) {
-                    /* Agent was rejected — skip and continue to the next agent. */
+                    // Agent was rejected by HITL -- skip and continue to the next
+                    // agent in the chain. The context remains unchanged.
                     continue;
                 }
                 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.
+                // This allows the human reviewer to inject additional guidance into
+                // the agent's context without modifying the original prompt.
                 const effectiveContext = decision?.modifications?.instructions
                     ? `${context}\n\n[Additional instructions]: ${decision.modifications.instructions}`
                     : context;
@@ -62,20 +92,21 @@ export function compileSequential(agents, agencyConfig) {
                 totalUsage.promptTokens += resultUsage.promptTokens ?? 0;
                 totalUsage.completionTokens += resultUsage.completionTokens ?? 0;
                 totalUsage.totalTokens += resultUsage.totalTokens ?? 0;
-                /* Chain: subsequent agents see the original task plus previous output. */
+                // Chain: subsequent agents see the original task plus previous output.
+                // This ensures each agent has full context without losing the original prompt.
                 context = `Original task: ${prompt}\n\nPrevious agent (${name}) output:\n${resultText}`;
                 lastResult = result;
             }
             return { ...lastResult, agentCalls, usage: totalUsage };
         },
         stream(prompt, opts) {
-            /*
+            /**
              * Real streaming for the sequential strategy: yields per-agent
              * `agent-start` and `agent-end` events bracketing each agent's text
              * tokens, plus agency-level start/end events wrapping the whole run.
              *
              * `fullStream` emits the full {@link AgencyStreamPart} union so callers
-             * can observe every agent transition.  `textStream` filters to just the
+             * can observe every agent transition. `textStream` filters to just the
              * `text` parts so the result stays compatible with `StreamTextResult`.
              *
              * Usage accounting is collected per-agent and summed into a final total.
@@ -147,7 +178,7 @@ export function compileSequential(agents, agencyConfig) {
                     durationMs: totalDurationMs,
                 };
             }
-            /*
+            /**
              * Because an `AsyncGenerator` can only be iterated once, we materialise
              * a single generator and share it between `fullStream`, `textStream`,
              * `text`, and `usage` by buffering all events.

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

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

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

@@ -3,27 +3,70 @@ import type { AgencyOptions, Agent, BaseAgentConfig, AgentCallRecord, ApprovalDe
  * Type guard that checks whether a value is a pre-built {@link Agent} instance
  * (has a `generate` method) vs a raw {@link BaseAgentConfig} object.
  *
+ * Uses duck-typing on the `generate` method rather than `instanceof` because
+ * Agent instances may come from different module copies (e.g. nested agencies
+ * created in separate compilation contexts). Duck-typing is more resilient
+ * to this scenario.
+ *
  * @param value - Either a config object or a running agent.
- * @returns `true` when the value is a pre-built `Agent`.
+ * @returns `true` when the value is a pre-built `Agent` with a callable `generate`.
+ *
+ * @example
+ * ```ts
+ * const agentOrConfig: BaseAgentConfig | Agent = getFromRoster('worker');
+ * if (isAgent(agentOrConfig)) {
+ *   // agentOrConfig.generate() is callable
+ * } else {
+ *   // agentOrConfig is a raw config, needs agent() factory
+ * }
+ * ```
  */
 export declare function isAgent(value: BaseAgentConfig | Agent): value is Agent;
 /**
  * Merge agency-level defaults into an agent config.
  *
- * Agent-level values take precedence; tools are merged (agency tools serve as
- * a base layer, agent tools override on name collision).
+ * Agent-level values take precedence over agency-level defaults. Tools are
+ * merged additively: agency tools serve as a base layer and agent tools
+ * override on name collision. This lets an agency provide a shared tool
+ * set while individual agents can override or extend it.
  *
- * @param agentConfig - Per-agent configuration.
- * @param agencyConfig - Agency-level fallback values.
+ * @param agentConfig - Per-agent configuration (takes precedence).
+ * @param agencyConfig - Agency-level fallback values (base layer).
  * @returns A merged config suitable for passing to `agent()`.
+ *
+ * @example
+ * ```ts
+ * const merged = mergeDefaults(
+ *   { instructions: 'Write code.' },
+ *   { model: 'openai:gpt-4o', tools: { search: searchTool } },
+ * );
+ * // merged.model === 'openai:gpt-4o' (agency default)
+ * // merged.instructions === 'Write code.' (agent override)
+ * // merged.tools contains `search` from agency
+ * ```
+ *
+ * @see {@link resolveAgent} -- calls this internally before creating an agent.
  */
 export declare function mergeDefaults(agentConfig: BaseAgentConfig, agencyConfig: AgencyOptions): BaseAgentConfig;
 /**
  * Resolves an agent-or-config value into a usable {@link Agent} instance.
  *
+ * If the value is already a pre-built Agent, it is returned as-is.
+ * If it is a raw BaseAgentConfig, agency defaults are merged and a new
+ * Agent is created via the `agent()` factory.
+ *
  * @param agentOrConfig - Either a pre-built Agent or a raw BaseAgentConfig.
  * @param agencyConfig - Agency-level fallback values for config merging.
  * @returns A ready-to-call Agent instance.
+ *
+ * @example
+ * ```ts
+ * const agent = resolveAgent(roster['worker'], agencyConfig);
+ * const result = await agent.generate('Do the task.');
+ * ```
+ *
+ * @see {@link isAgent} -- determines whether the value needs factory creation.
+ * @see {@link mergeDefaults} -- applies agency-level fallback values.
  */
 export declare function resolveAgent(agentOrConfig: BaseAgentConfig | Agent, agencyConfig: AgencyOptions): Agent;
 /**
@@ -32,13 +75,34 @@ export declare function resolveAgent(agentOrConfig: BaseAgentConfig | Agent, age
  * When the agency-level `hitl.approvals.beforeAgent` list includes the agent
  * name, this function invokes the HITL handler and returns the decision.
  * If the agent name is not in the approval list, or no handler is configured,
- * returns `null` (meaning "no gate — proceed normally").
+ * returns `null` (meaning "no gate -- proceed normally").
+ *
+ * ## Why return `null` instead of `{ approved: true }`?
+ *
+ * Returning `null` lets callers distinguish between "no gate configured"
+ * (null -- proceed without any HITL overhead) and "gate evaluated, approved"
+ * (`{ approved: true }` -- proceed but may carry instruction modifications
+ * from the approver).
  *
  * @param name - The agent's declared name in the roster.
  * @param context - The input/context string the agent would receive.
  * @param agentCalls - Agent call records accumulated so far in this run.
- * @param agencyConfig - The full agency configuration.
+ *                     Included in the approval request for context.
+ * @param agencyConfig - The full agency configuration containing HITL settings.
  * @returns The approval decision, or `null` when no gate applies.
+ *
+ * @example
+ * ```ts
+ * const decision = await checkBeforeAgent('researcher', prompt, calls, config);
+ * if (decision && !decision.approved) {
+ *   // Agent was rejected by HITL -- skip or abort.
+ *   return;
+ * }
+ * // Proceed with agent invocation.
+ * ```
+ *
+ * @see {@link HitlConfig} -- defines the approval triggers and handler.
+ * @see {@link ApprovalRequest} -- the shape passed to the handler.
  */
 export declare function checkBeforeAgent(name: string, context: string, agentCalls: AgentCallRecord[], agencyConfig: AgencyOptions): Promise<ApprovalDecision | null>;
 //# sourceMappingURL=shared.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/shared.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,aAAa,EACb,KAAK,EACL,eAAe,EACf,eAAe,EAEf,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,KAAK,GAAG,KAAK,IAAI,KAAK,CAEtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,eAAe,EAC5B,YAAY,EAAE,aAAa,GAC1B,eAAe,CAUjB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,aAAa,EAAE,eAAe,GAAG,KAAK,EACtC,YAAY,EAAE,aAAa,GAC1B,KAAK,CAIP;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,eAAe,EAAE,EAC7B,YAAY,EAAE,aAAa,GAC1B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CA4BlC"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/shared.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,aAAa,EACb,KAAK,EACL,eAAe,EACf,eAAe,EAEf,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,KAAK,GAAG,KAAK,IAAI,KAAK,CAEtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,eAAe,EAC5B,YAAY,EAAE,aAAa,GAC1B,eAAe,CAcjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAC1B,aAAa,EAAE,eAAe,GAAG,KAAK,EACtC,YAAY,EAAE,aAAa,GAC1B,KAAK,CAIP;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,eAAe,EAAE,EAC7B,YAAY,EAAE,aAAa,GAC1B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAkClC"}