@framers/agentos 0.1.112 → 0.1.114

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

@@ -1,29 +1,72 @@
 import type { AgencyOptions, Agent, BaseAgentConfig, AgentCallRecord, ApprovalDecision } from '../types.js';
 /**
  * Type guard that checks whether a value is a pre-built {@link Agent} instance
- * (has a `generate` method) vs a raw {@link BaseAgentConfig} object.
+ * (has a `generate` method) vs a raw `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":"AAcA,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"}

package/dist/api/strategies/shared.js

@@ -2,16 +2,37 @@
  * @file shared.ts
  * Shared utilities for strategy compilers.
  *
- * Centralises `mergeDefaults()`, `resolveAgent()`, and `checkBeforeAgent()`
- * so every strategy compiler uses a single implementation.
+ * Centralises `isAgent()`, `mergeDefaults()`, `resolveAgent()`, and
+ * `checkBeforeAgent()` so every strategy compiler uses a single implementation.
+ * This avoids subtle divergence in how configs are merged or how HITL gates
+ * are evaluated across sequential, parallel, debate, review-loop, and
+ * hierarchical strategies.
+ *
+ * @see {@link compileStrategy} -- the dispatcher that selects and invokes strategy compilers.
  */
 import { agent as createAgent } from '../agent.js';
+import { mergeAdaptableTools } from '../toolAdapter.js';
 /**
  * Type guard that checks whether a value is a pre-built {@link Agent} instance
- * (has a `generate` method) vs a raw {@link BaseAgentConfig} object.
+ * (has a `generate` method) vs a raw `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 function isAgent(value) {
     return typeof value.generate === 'function';
@@ -19,30 +40,62 @@ export function isAgent(value) {
 /**
  * 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 function mergeDefaults(agentConfig, agencyConfig) {
     return {
+        // Agency-level model/provider/apiKey/baseUrl serve as defaults.
+        // They are placed BEFORE the spread of agentConfig so that agent-level
+        // values override them when present.
         model: agentConfig.model ?? agencyConfig.model,
         provider: agentConfig.provider ?? agencyConfig.provider,
         apiKey: agentConfig.apiKey ?? agencyConfig.apiKey,
         baseUrl: agentConfig.baseUrl ?? agencyConfig.baseUrl,
         ...agentConfig,
-        /* Merge tool maps: agency tools as base, agent tools overlay. */
-        tools: { ...(agencyConfig.tools ?? {}), ...(agentConfig.tools ?? {}) },
+        // Tools are merged separately because we want additive merging
+        // (agency tools + agent tools) rather than wholesale replacement.
+        tools: mergeAdaptableTools(agencyConfig.tools, agentConfig.tools),
     };
 }
 /**
  * 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 function resolveAgent(agentOrConfig, agencyConfig) {
     return isAgent(agentOrConfig)
@@ -55,20 +108,44 @@ export function resolveAgent(agentOrConfig, agencyConfig) {
  * 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 async function checkBeforeAgent(name, context, agentCalls, agencyConfig) {
     const beforeAgent = agencyConfig.hitl?.approvals?.beforeAgent;
     const handler = agencyConfig.hitl?.handler;
+    // Short-circuit: no gate configured or agent not in the approval list.
     if (!beforeAgent?.includes(name) || !handler) {
         return null;
     }
+    // Build the approval request with full run context so the human reviewer
+    // can make an informed decision.
     const request = {
         id: crypto.randomUUID(),
         type: 'agent',
@@ -83,8 +160,11 @@ export async function checkBeforeAgent(name, context, agentCalls, agencyConfig)
             elapsedMs: 0,
         },
     };
+    // Fire the approvalRequested callback so event consumers (UI, logs)
+    // can display the pending approval.
     agencyConfig.on?.approvalRequested?.(request);
     const decision = await handler(request);
+    // Fire the approvalDecided callback so event consumers know the outcome.
     agencyConfig.on?.approvalDecided?.(decision);
     return decision;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/api/strategies/shared.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,aAAa,CAAC;AASnD;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,KAA8B;IACpD,OAAO,OAAQ,KAAe,CAAC,QAAQ,KAAK,UAAU,CAAC;AACzD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,WAA4B,EAC5B,YAA2B;IAE3B,OAAO;QACL,KAAK,EAAE,WAAW,CAAC,KAAK,IAAI,YAAY,CAAC,KAAK;QAC9C,QAAQ,EAAE,WAAW,CAAC,QAAQ,IAAI,YAAY,CAAC,QAAQ;QACvD,MAAM,EAAE,WAAW,CAAC,MAAM,IAAI,YAAY,CAAC,MAAM;QACjD,OAAO,EAAE,WAAW,CAAC,OAAO,IAAI,YAAY,CAAC,OAAO;QACpD,GAAG,WAAW;QACd,iEAAiE;QACjE,KAAK,EAAE,EAAE,GAAG,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE;KACvE,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,aAAsC,EACtC,YAA2B;IAE3B,OAAO,OAAO,CAAC,aAAa,CAAC;QAC3B,CAAC,CAAC,aAAa;QACf,CAAC,CAAC,WAAW,CAAC,EAAE,GAAG,aAAa,CAAC,aAAa,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAY,EACZ,OAAe,EACf,UAA6B,EAC7B,YAA2B;IAE3B,MAAM,WAAW,GAAG,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,CAAC;IAC9D,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC;IAE3C,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAoB;QAC/B,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;QACvB,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,IAAI;QACX,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,UAAU,IAAI,uBAAuB;QAClD,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE;QAC3B,OAAO,EAAE;YACP,UAAU;YACV,WAAW,EAAE,CAAC;YACd,YAAY,EAAE,CAAC;YACf,SAAS,EAAE,CAAC;SACb;KACF,CAAC;IAEF,YAAY,CAAC,EAAE,EAAE,iBAAiB,EAAE,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,YAAY,CAAC,EAAE,EAAE,eAAe,EAAE,CAAC,QAAQ,CAAC,CAAC;IAE7C,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/api/strategies/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAUxD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,OAAO,CAAC,KAA8B;IACpD,OAAO,OAAQ,KAAe,CAAC,QAAQ,KAAK,UAAU,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,aAAa,CAC3B,WAA4B,EAC5B,YAA2B;IAE3B,OAAO;QACL,gEAAgE;QAChE,uEAAuE;QACvE,qCAAqC;QACrC,KAAK,EAAE,WAAW,CAAC,KAAK,IAAI,YAAY,CAAC,KAAK;QAC9C,QAAQ,EAAE,WAAW,CAAC,QAAQ,IAAI,YAAY,CAAC,QAAQ;QACvD,MAAM,EAAE,WAAW,CAAC,MAAM,IAAI,YAAY,CAAC,MAAM;QACjD,OAAO,EAAE,WAAW,CAAC,OAAO,IAAI,YAAY,CAAC,OAAO;QACpD,GAAG,WAAW;QACd,+DAA+D;QAC/D,kEAAkE;QAClE,KAAK,EAAE,mBAAmB,CAAC,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC;KAClE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAC1B,aAAsC,EACtC,YAA2B;IAE3B,OAAO,OAAO,CAAC,aAAa,CAAC;QAC3B,CAAC,CAAC,aAAa;QACf,CAAC,CAAC,WAAW,CAAC,EAAE,GAAG,aAAa,CAAC,aAAa,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAY,EACZ,OAAe,EACf,UAA6B,EAC7B,YAA2B;IAE3B,MAAM,WAAW,GAAG,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,CAAC;IAC9D,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC;IAE3C,uEAAuE;IACvE,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,yEAAyE;IACzE,iCAAiC;IACjC,MAAM,OAAO,GAAoB;QAC/B,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;QACvB,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,IAAI;QACX,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,UAAU,IAAI,uBAAuB;QAClD,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE;QAC3B,OAAO,EAAE;YACP,UAAU;YACV,WAAW,EAAE,CAAC;YACd,YAAY,EAAE,CAAC;YACf,SAAS,EAAE,CAAC;SACb;KACF,CAAC;IAEF,oEAAoE;IACpE,oCAAoC;IACpC,YAAY,CAAC,EAAE,EAAE,iBAAiB,EAAE,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,yEAAyE;IACzE,YAAY,CAAC,EAAE,EAAE,eAAe,EAAE,CAAC,QAAQ,CAAC,CAAC;IAE7C,OAAO,QAAQ,CAAC;AAClB,CAAC"}