@framers/agentos 0.1.97 → 0.1.99

package/dist/api/strategies/debate.js

@@ -0,0 +1,118 @@
+/**
+ * @file debate.ts
+ * Debate strategy compiler for the Agency API.
+ *
+ * Agents argue in rounds over a shared task. Each round, every agent sees all
+ * prior arguments from every other agent, enabling progressive refinement
+ * through adversarial discourse. After all rounds complete, a synthesizer
+ * distils the collected arguments into a single coherent response.
+ */
+import { agent as createAgent } from '../agent.js';
+import { AgencyConfigError } from '../types.js';
+import { resolveAgent, checkBeforeAgent } from './shared.js';
+/**
+ * Compiles a debate execution strategy.
+ *
+ * Agents are iterated in rounds. During each round, every agent receives the
+ * original task plus all previously collected arguments, and contributes its
+ * own perspective. After `maxRounds` complete, a synthesizer agent (using the
+ * agency-level model) distils all arguments into a final answer.
+ *
+ * @param agents - Named roster of agent configs or pre-built `Agent` instances.
+ * @param agencyConfig - Agency-level configuration providing fallback model/provider/tools.
+ * @returns A {@link CompiledStrategy} with `execute` and `stream` methods.
+ * @throws {AgencyConfigError} When no agency-level model/provider is available for synthesis.
+ */
+export function compileDebate(agents, agencyConfig) {
+    if (!agencyConfig.model && !agencyConfig.provider) {
+        throw new AgencyConfigError('Debate strategy requires an agency-level model or provider for result synthesis.');
+    }
+    const maxRounds = agencyConfig.maxRounds ?? 3;
+    return {
+        async execute(prompt, opts) {
+            const agentCalls = [];
+            const entries = Object.entries(agents);
+            const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            const collectedArguments = [];
+            for (let round = 0; round < maxRounds; round++) {
+                for (const [name, agentOrConfig] of entries) {
+                    /* HITL: check beforeAgent gate before invoking this agent. */
+                    const decision = await checkBeforeAgent(name, prompt, agentCalls, agencyConfig);
+                    if (decision && !decision.approved) {
+                        /* Agent was rejected — skip this agent in this round. */
+                        continue;
+                    }
+                    const a = resolveAgent(agentOrConfig, agencyConfig);
+                    const debateContext = `Task: ${prompt}\n\n` +
+                        (collectedArguments.length > 0
+                            ? `Previous arguments:\n${collectedArguments.join('\n---\n')}`
+                            : 'You are the first to argue.') +
+                        `\n\nPresent your perspective as ${name} (round ${round + 1}/${maxRounds}).`;
+                    const start = Date.now();
+                    const result = (await a.generate(debateContext, opts));
+                    const durationMs = Date.now() - start;
+                    const resultText = result.text ?? '';
+                    const resultUsage = result.usage ?? {};
+                    const resultToolCalls = result.toolCalls ?? [];
+                    collectedArguments.push(`[${name}, round ${round + 1}]: ${resultText}`);
+                    agentCalls.push({
+                        agent: name,
+                        input: debateContext,
+                        output: resultText,
+                        toolCalls: resultToolCalls,
+                        usage: {
+                            promptTokens: resultUsage.promptTokens ?? 0,
+                            completionTokens: resultUsage.completionTokens ?? 0,
+                            totalTokens: resultUsage.totalTokens ?? 0,
+                        },
+                        durationMs,
+                    });
+                    totalUsage.promptTokens += resultUsage.promptTokens ?? 0;
+                    totalUsage.completionTokens += resultUsage.completionTokens ?? 0;
+                    totalUsage.totalTokens += resultUsage.totalTokens ?? 0;
+                }
+            }
+            /* Synthesize all arguments into a final answer using the agency-level model. */
+            const synthInstructions = agencyConfig.instructions
+                ? `\n\n${agencyConfig.instructions}`
+                : '';
+            const synthPrompt = `A debate was held on the following task:\n"${prompt}"\n\n` +
+                `All arguments:\n${collectedArguments.join('\n---\n')}\n\n` +
+                `Synthesize these perspectives into a single coherent answer.${synthInstructions}`;
+            const synthesizer = createAgent({
+                model: agencyConfig.model,
+                provider: agencyConfig.provider,
+                apiKey: agencyConfig.apiKey,
+                baseUrl: agencyConfig.baseUrl,
+                maxSteps: 1,
+            });
+            const synthesis = (await synthesizer.generate(synthPrompt, opts));
+            const synthUsage = synthesis.usage ?? {};
+            totalUsage.promptTokens += synthUsage.promptTokens ?? 0;
+            totalUsage.completionTokens += synthUsage.completionTokens ?? 0;
+            totalUsage.totalTokens += synthUsage.totalTokens ?? 0;
+            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.
+             */
+            const resultPromise = this.execute(prompt, opts);
+            const textPromise = resultPromise.then((r) => r.text ?? '');
+            return {
+                textStream: (async function* () {
+                    yield await textPromise;
+                })(),
+                fullStream: (async function* () {
+                    const text = await textPromise;
+                    yield { type: 'text', text };
+                })(),
+                text: textPromise,
+                usage: resultPromise.then((r) => r.usage),
+            };
+        },
+    };
+}
+//# sourceMappingURL=debate.js.map

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

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

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

@@ -0,0 +1,20 @@
+import type { AgencyOptions, CompiledStrategy, Agent, BaseAgentConfig } from '../types.js';
+/**
+ * Compiles a hierarchical execution strategy.
+ *
+ * A manager agent is instantiated from the agency-level model/provider/instructions.
+ * Each sub-agent in the roster is exposed as a `delegate_to_<name>` tool that the
+ * manager can invoke. When the manager calls a delegation tool, the corresponding
+ * sub-agent runs the subtask and its output is returned as the tool result.
+ *
+ * All sub-agent call records are collected and returned alongside the manager's
+ * final synthesized answer.
+ *
+ * @param agents - Named roster of agent configs or pre-built `Agent` instances.
+ * @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.
+ */
+export declare function compileHierarchical(agents: Record<string, BaseAgentConfig | Agent>, agencyConfig: AgencyOptions): CompiledStrategy;
+//# sourceMappingURL=hierarchical.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchical.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/hierarchical.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,KAAK,EACL,eAAe,EAEhB,MAAM,aAAa,CAAC;AAmBrB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CAmHlB"}

package/dist/api/strategies/hierarchical.js

@@ -0,0 +1,140 @@
+/**
+ * @file hierarchical.ts
+ * Hierarchical strategy compiler for the Agency API.
+ *
+ * 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.
+ */
+import { agent as createAgent } from '../agent.js';
+import { AgencyConfigError } from '../types.js';
+import { isAgent } from './index.js';
+import { resolveAgent, checkBeforeAgent } from './shared.js';
+/**
+ * Extracts a human-readable description from an agent config or instance.
+ *
+ * @param agentOrConfig - Either a pre-built Agent or a raw BaseAgentConfig.
+ * @returns The instructions string if available, otherwise a generic label.
+ */
+function getAgentDescription(agentOrConfig) {
+    if (!isAgent(agentOrConfig) && agentOrConfig.instructions) {
+        return agentOrConfig.instructions;
+    }
+    return 'General purpose';
+}
+/**
+ * Compiles a hierarchical execution strategy.
+ *
+ * A manager agent is instantiated from the agency-level model/provider/instructions.
+ * Each sub-agent in the roster is exposed as a `delegate_to_<name>` tool that the
+ * manager can invoke. When the manager calls a delegation tool, the corresponding
+ * sub-agent runs the subtask and its output is returned as the tool result.
+ *
+ * All sub-agent call records are collected and returned alongside the manager's
+ * final synthesized answer.
+ *
+ * @param agents - Named roster of agent configs or pre-built `Agent` instances.
+ * @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.
+ */
+export function compileHierarchical(agents, agencyConfig) {
+    if (!agencyConfig.model && !agencyConfig.provider) {
+        throw new AgencyConfigError('Hierarchical strategy requires an agency-level model or provider for the manager agent.');
+    }
+    return {
+        async execute(prompt, opts) {
+            const agentCalls = [];
+            /* Build one tool per sub-agent for the manager to delegate to. */
+            const agentTools = {};
+            for (const [name, agentOrConfig] of Object.entries(agents)) {
+                const description = getAgentDescription(agentOrConfig);
+                agentTools[`delegate_to_${name}`] = {
+                    description: `Delegate a subtask to the ${name} agent. ${description}`,
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            task: { type: 'string', description: 'The subtask to delegate' },
+                        },
+                        required: ['task'],
+                    },
+                    execute: async (args) => {
+                        /* 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. */
+                        const effectiveTask = decision?.modifications?.instructions
+                            ? `${args.task}\n\n[Additional instructions]: ${decision.modifications.instructions}`
+                            : args.task;
+                        const start = Date.now();
+                        const result = (await a.generate(effectiveTask, opts));
+                        const durationMs = Date.now() - start;
+                        const resultText = result.text ?? '';
+                        const resultUsage = result.usage ?? {};
+                        const resultToolCalls = result.toolCalls ?? [];
+                        agentCalls.push({
+                            agent: name,
+                            input: args.task,
+                            output: resultText,
+                            toolCalls: resultToolCalls,
+                            usage: {
+                                promptTokens: resultUsage.promptTokens ?? 0,
+                                completionTokens: resultUsage.completionTokens ?? 0,
+                                totalTokens: resultUsage.totalTokens ?? 0,
+                            },
+                            durationMs,
+                        });
+                        return { success: true, data: resultText };
+                    },
+                };
+            }
+            /* Build the team roster description for the manager's system prompt. */
+            const teamRoster = Object.entries(agents)
+                .map(([name, c]) => `- ${name}: ${getAgentDescription(c)}`)
+                .join('\n');
+            const managerInstructions = `You are a manager agent. Your task is to accomplish the user's goal by delegating subtasks to your team members.\n\n` +
+                `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 };
+            const manager = createAgent({
+                model: agencyConfig.model,
+                provider: agencyConfig.provider,
+                apiKey: agencyConfig.apiKey,
+                baseUrl: agencyConfig.baseUrl,
+                instructions: managerInstructions,
+                tools: mergedTools,
+                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.
+             */
+            const resultPromise = this.execute(prompt, opts);
+            const textPromise = resultPromise.then((r) => r.text ?? '');
+            return {
+                textStream: (async function* () {
+                    yield await textPromise;
+                })(),
+                fullStream: (async function* () {
+                    const text = await textPromise;
+                    yield { type: 'text', text };
+                })(),
+                text: textPromise,
+                usage: resultPromise.then((r) => r.usage),
+            };
+        },
+    };
+}
+//# sourceMappingURL=hierarchical.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,41 @@
+/**
+ * @file index.ts
+ * Strategy compiler dispatcher for the Agency API.
+ *
+ * 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.
+ */
+import type { AgencyStrategy, AgencyOptions, CompiledStrategy, Agent, BaseAgentConfig } from '../types.js';
+/**
+ * Compile an orchestration strategy into an executable {@link CompiledStrategy}.
+ *
+ * When `agencyConfig.adaptive` is `true` and the requested strategy is not
+ * already `"hierarchical"`, the compiled strategy is wrapped in an adaptive
+ * hierarchical manager that may override the default strategy at runtime
+ * based on task complexity signals.
+ *
+ * @param strategy - Strategy discriminant (e.g. `"sequential"`, `"parallel"`).
+ * @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.
+ */
+export declare function compileStrategy(strategy: AgencyStrategy, agents: Record<string, BaseAgentConfig | Agent>, agencyConfig: AgencyOptions): CompiledStrategy;
+/**
+ * Type guard that checks whether a value is a pre-built {@link Agent} instance
+ * (has a `generate` method) vs a raw {@link BaseAgentConfig} object.
+ *
+ * @param value - Either a config object or a running agent.
+ * @returns `true` when the value is a pre-built `Agent`.
+ */
+export declare function isAgent(value: BaseAgentConfig | Agent): value is Agent;
+export { compileSequential } from './sequential.js';
+export { compileParallel } from './parallel.js';
+export { compileDebate } from './debate.js';
+export { compileReviewLoop } from './review-loop.js';
+export { compileHierarchical } from './hierarchical.js';
+export { mergeDefaults, resolveAgent, checkBeforeAgent } from './shared.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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;AAOrB;;;;;;;;;;;;;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;AAmED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,KAAK,GAAG,KAAK,IAAI,KAAK,CAEtE;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,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/api/strategies/index.js

@@ -0,0 +1,95 @@
+import { compileSequential } from './sequential.js';
+import { compileParallel } from './parallel.js';
+import { compileDebate } from './debate.js';
+import { compileReviewLoop } from './review-loop.js';
+import { compileHierarchical } from './hierarchical.js';
+/**
+ * Compile an orchestration strategy into an executable {@link CompiledStrategy}.
+ *
+ * When `agencyConfig.adaptive` is `true` and the requested strategy is not
+ * already `"hierarchical"`, the compiled strategy is wrapped in an adaptive
+ * hierarchical manager that may override the default strategy at runtime
+ * based on task complexity signals.
+ *
+ * @param strategy - Strategy discriminant (e.g. `"sequential"`, `"parallel"`).
+ * @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.
+ */
+export function compileStrategy(strategy, agents, agencyConfig) {
+    /* When adaptive mode is enabled on non-hierarchical strategies, wrap with a manager. */
+    if (agencyConfig.adaptive && strategy !== 'hierarchical') {
+        return compileAdaptiveWrapper(strategy, agents, agencyConfig);
+    }
+    return compileStrategyCore(strategy, agents, agencyConfig);
+}
+/**
+ * Core strategy compiler without adaptive wrapping.
+ *
+ * @param strategy - Strategy discriminant.
+ * @param agents - Named agent roster.
+ * @param agencyConfig - Agency-level configuration.
+ * @returns A compiled strategy.
+ * @internal
+ */
+function compileStrategyCore(strategy, agents, agencyConfig) {
+    switch (strategy) {
+        case 'sequential':
+            return compileSequential(agents, agencyConfig);
+        case 'parallel':
+            return compileParallel(agents, agencyConfig);
+        case 'debate':
+            return compileDebate(agents, agencyConfig);
+        case 'review-loop':
+            return compileReviewLoop(agents, agencyConfig);
+        case 'hierarchical':
+            return compileHierarchical(agents, agencyConfig);
+        default:
+            throw new Error(`Strategy '${strategy}' not yet implemented`);
+    }
+}
+/**
+ * Wraps a non-hierarchical strategy in an adaptive hierarchical manager.
+ *
+ * The manager prompt declares the default strategy and instructs the manager
+ * that it may override strategy selection if the task clearly does not require
+ * all agents. In practice, the manager delegates to the sub-agents via tools
+ * just like the hierarchical strategy, but with the additional context of the
+ * original intended strategy.
+ *
+ * @param defaultStrategy - The user-declared default strategy.
+ * @param agents - Named agent roster.
+ * @param agencyConfig - Agency-level configuration.
+ * @returns A compiled hierarchical strategy with adaptive instructions.
+ * @internal
+ */
+function compileAdaptiveWrapper(defaultStrategy, agents, agencyConfig) {
+    const adaptiveInstructions = (agencyConfig.instructions ? agencyConfig.instructions + '\n\n' : '') +
+        `Your default strategy is "${defaultStrategy}". You may override it if the task clearly doesn't need all agents. ` +
+        `Use your judgment to decide whether to engage all team members or delegate to a subset.`;
+    const adaptiveConfig = {
+        ...agencyConfig,
+        instructions: adaptiveInstructions,
+        /* Disable adaptive on the inner call to prevent infinite recursion. */
+        adaptive: false,
+    };
+    return compileHierarchical(agents, adaptiveConfig);
+}
+/**
+ * Type guard that checks whether a value is a pre-built {@link Agent} instance
+ * (has a `generate` method) vs a raw {@link BaseAgentConfig} object.
+ *
+ * @param value - Either a config object or a running agent.
+ * @returns `true` when the value is a pre-built `Agent`.
+ */
+export function isAgent(value) {
+    return typeof value.generate === 'function';
+}
+export { compileSequential } from './sequential.js';
+export { compileParallel } from './parallel.js';
+export { compileDebate } from './debate.js';
+export { compileReviewLoop } from './review-loop.js';
+export { compileHierarchical } from './hierarchical.js';
+export { mergeDefaults, resolveAgent, checkBeforeAgent } from './shared.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +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;AAExD;;;;;;;;;;;;;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;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;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,KAA8B;IACpD,OAAO,OAAQ,KAAe,CAAC,QAAQ,KAAK,UAAU,CAAC;AACzD,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,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,17 @@
+import type { AgencyOptions, CompiledStrategy, Agent, BaseAgentConfig } from '../types.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.
+ *
+ * @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.
+ */
+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

@@ -0,0 +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;AAKrB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CAoHlB"}

package/dist/api/strategies/parallel.js

@@ -0,0 +1,122 @@
+/**
+ * @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.
+ */
+import { agent as createAgent } from '../agent.js';
+import { AgencyConfigError } from '../types.js';
+import { isAgent } from './index.js';
+import { 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.
+ *
+ * @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.
+ */
+export function compileParallel(agents, agencyConfig) {
+    if (!agencyConfig.model && !agencyConfig.provider) {
+        throw new AgencyConfigError('Parallel strategy requires an agency-level model or provider for result synthesis.');
+    }
+    return {
+        async execute(prompt, opts) {
+            /* Run every agent concurrently, gated by beforeAgent HITL. */
+            const entries = Object.entries(agents);
+            const settled = (await Promise.all(entries.map(async ([name, agentOrConfig]) => {
+                /* 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. */
+                    return null;
+                }
+                const a = isAgent(agentOrConfig)
+                    ? agentOrConfig
+                    : createAgent({ ...mergeDefaults(agentOrConfig, agencyConfig) });
+                /* Apply instruction modifications from the approval decision if any. */
+                const effectivePrompt = decision?.modifications?.instructions
+                    ? `${prompt}\n\n[Additional instructions]: ${decision.modifications.instructions}`
+                    : prompt;
+                const start = Date.now();
+                const result = (await a.generate(effectivePrompt, opts));
+                const durationMs = Date.now() - start;
+                return { name, result, durationMs };
+            }))).filter((r) => r !== null);
+            /* Collect agent call records and aggregate usage. */
+            const agentCalls = [];
+            const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            for (const { name, result, durationMs } of settled) {
+                const resultUsage = result.usage ?? {};
+                const resultToolCalls = result.toolCalls ?? [];
+                agentCalls.push({
+                    agent: name,
+                    input: prompt,
+                    output: result.text ?? '',
+                    toolCalls: resultToolCalls,
+                    usage: {
+                        promptTokens: resultUsage.promptTokens ?? 0,
+                        completionTokens: resultUsage.completionTokens ?? 0,
+                        totalTokens: resultUsage.totalTokens ?? 0,
+                    },
+                    durationMs,
+                });
+                totalUsage.promptTokens += resultUsage.promptTokens ?? 0;
+                totalUsage.completionTokens += resultUsage.completionTokens ?? 0;
+                totalUsage.totalTokens += resultUsage.totalTokens ?? 0;
+            }
+            /* Synthesize outputs using the agency-level model. */
+            const agentOutputsBlock = settled
+                .map(({ name, result }) => `--- ${name} ---\n${result.text ?? ''}`)
+                .join('\n\n');
+            const synthInstructions = agencyConfig.instructions
+                ? `\n\n${agencyConfig.instructions}`
+                : '';
+            const synthPrompt = `Multiple agents analyzed the following task:\n"${prompt}"\n\n` +
+                `${agentOutputsBlock}\n\n` +
+                `Synthesize these into a single coherent response.${synthInstructions}`;
+            const synthesizer = createAgent({
+                model: agencyConfig.model,
+                provider: agencyConfig.provider,
+                apiKey: agencyConfig.apiKey,
+                baseUrl: agencyConfig.baseUrl,
+                maxSteps: 1,
+            });
+            const synthesis = (await synthesizer.generate(synthPrompt, opts));
+            const synthUsage = synthesis.usage ?? {};
+            totalUsage.promptTokens += synthUsage.promptTokens ?? 0;
+            totalUsage.completionTokens += synthUsage.completionTokens ?? 0;
+            totalUsage.totalTokens += synthUsage.totalTokens ?? 0;
+            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.
+             */
+            const resultPromise = this.execute(prompt, opts);
+            const textPromise = resultPromise.then((r) => r.text ?? '');
+            return {
+                textStream: (async function* () {
+                    yield await textPromise;
+                })(),
+                fullStream: (async function* () {
+                    const text = await textPromise;
+                    yield { type: 'text', text };
+                })(),
+                text: textPromise,
+                usage: resultPromise.then((r) => r.usage),
+            };
+        },
+    };
+}
+//# sourceMappingURL=parallel.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,18 @@
+import type { AgencyOptions, CompiledStrategy, Agent, BaseAgentConfig } from '../types.js';
+/**
+ * Compiles a review-loop execution strategy.
+ *
+ * The first declared agent acts as the producer, the second as the reviewer.
+ * The producer generates or revises a draft, then the reviewer evaluates it.
+ * If the reviewer approves (responds with `{ "approved": true }`), the loop
+ * terminates early. Otherwise the reviewer's feedback is fed back into the
+ * 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).
+ * @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.
+ */
+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

@@ -0,0 +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;AA8BrB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CAqIlB"}