@framers/agentos 0.1.112 → 0.1.114

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

@@ -1 +1 @@
-{"version":3,"file":"debate.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/debate.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,KAAK,EACL,eAAe,EAEhB,MAAM,aAAa,CAAC;AAIrB;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CAiHlB"}
+{"version":3,"file":"debate.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/debate.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,KAAK,EACL,eAAe,EAEhB,MAAM,aAAa,CAAC;AAIrB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CAwHlB"}

package/dist/api/strategies/debate.js

@@ -2,10 +2,28 @@
  * @file debate.ts
  * Debate strategy compiler for the Agency API.
  *
+ * ## Execution model
+ *
  * 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.
+ *
+ * ## Why debate?
+ *
+ * Debate is effective for tasks where multiple perspectives lead to better
+ * outcomes: ethical reasoning, policy analysis, creative brainstorming,
+ * risk assessment. Each agent is forced to defend its position while
+ * considering others, reducing blind spots.
+ *
+ * ## Round structure
+ *
+ * For `N` agents and `R` rounds, the total agent calls are `N * R` plus one
+ * synthesis call. In each round, agents are called in declaration order.
+ * Each agent receives the full argument history from all prior agents/rounds.
+ *
+ * @see {@link compileStrategy} -- the dispatcher that selects this compiler.
+ * @see {@link compileReviewLoop} -- an alternative iterative strategy with explicit approval.
  */
 import { agent as createAgent } from '../agent.js';
 import { AgencyConfigError } from '../types.js';
@@ -20,13 +38,26 @@ import { resolveAgent, checkBeforeAgent } from './shared.js';
  *
  * @param agents - Named roster of agent configs or pre-built `Agent` instances.
  * @param agencyConfig - Agency-level configuration providing fallback model/provider/tools.
+ *   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.
+ *
+ * @example
+ * ```ts
+ * const strategy = compileDebate(
+ *   { optimist: { instructions: 'Argue the positive case.' }, pessimist: { instructions: 'Argue the risks.' } },
+ *   { model: 'openai:gpt-4o', maxRounds: 2, agents: { ... } },
+ * );
+ * const result = await strategy.execute('Should we adopt this new technology?');
+ * ```
  */
 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.');
     }
+    // Default to 3 rounds when not specified -- enough for meaningful discourse
+    // without excessive token consumption.
     const maxRounds = agencyConfig.maxRounds ?? 3;
     return {
         async execute(prompt, opts) {
@@ -36,13 +67,16 @@ export function compileDebate(agents, agencyConfig) {
             const collectedArguments = [];
             for (let round = 0; round < maxRounds; round++) {
                 for (const [name, agentOrConfig] of entries) {
-                    /* HITL: check beforeAgent gate before invoking this agent. */
+                    // 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. */
+                        // Agent was rejected -- skip this agent in this round.
                         continue;
                     }
                     const a = resolveAgent(agentOrConfig, agencyConfig);
+                    // Build the debate context: original task + all prior arguments.
+                    // The first agent in the first round sees "You are the first to argue."
+                    // which prevents confusion about missing prior context.
                     const debateContext = `Task: ${prompt}\n\n` +
                         (collectedArguments.length > 0
                             ? `Previous arguments:\n${collectedArguments.join('\n---\n')}`
@@ -54,6 +88,8 @@ export function compileDebate(agents, agencyConfig) {
                     const resultText = result.text ?? '';
                     const resultUsage = result.usage ?? {};
                     const resultToolCalls = result.toolCalls ?? [];
+                    // Label each argument with the agent name and round for traceability
+                    // in the synthesis prompt.
                     collectedArguments.push(`[${name}, round ${round + 1}]: ${resultText}`);
                     agentCalls.push({
                         agent: name,
@@ -72,7 +108,7 @@ export function compileDebate(agents, agencyConfig) {
                     totalUsage.totalTokens += resultUsage.totalTokens ?? 0;
                 }
             }
-            /* Synthesize all arguments into a final answer using the agency-level model. */
+            // Synthesize all arguments into a final answer using the agency-level model.
             const synthInstructions = agencyConfig.instructions
                 ? `\n\n${agencyConfig.instructions}`
                 : '';
@@ -94,7 +130,7 @@ export function compileDebate(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/debate.js.map

@@ -1 +1 @@
-{"version":3,"file":"debate.js","sourceRoot":"","sources":["../../../src/api/strategies/debate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,aAAa,CAAC;AAQnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAA0B,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAErF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC3B,MAA+C,EAC/C,YAA2B;IAE3B,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,iBAAiB,CACzB,kFAAkF,CACnF,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,YAAY,CAAC,SAAS,IAAI,CAAC,CAAC;IAE9C,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI;YACxB,MAAM,UAAU,GAAsB,EAAE,CAAC;YACzC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACvC,MAAM,UAAU,GAAG,EAAE,YAAY,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;YAC5E,MAAM,kBAAkB,GAAa,EAAE,CAAC;YAExC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC;gBAC/C,KAAK,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,OAAO,EAAE,CAAC;oBAC5C,8DAA8D;oBAC9D,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;oBAChF,IAAI,QAAQ,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;wBACnC,yDAAyD;wBACzD,SAAS;oBACX,CAAC;oBAED,MAAM,CAAC,GAAG,YAAY,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;oBAEpD,MAAM,aAAa,GACjB,SAAS,MAAM,MAAM;wBACrB,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC;4BAC5B,CAAC,CAAC,wBAAwB,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE;4BAC9D,CAAC,CAAC,6BAA6B,CAAC;wBAClC,mCAAmC,IAAI,WAAW,KAAK,GAAG,CAAC,IAAI,SAAS,IAAI,CAAC;oBAE/E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;oBACzB,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC,CAA4B,CAAC;oBAClF,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;oBAEtC,MAAM,UAAU,GAAI,MAAM,CAAC,IAAe,IAAI,EAAE,CAAC;oBACjD,MAAM,WAAW,GAAI,MAAM,CAAC,KAAoF,IAAI,EAAE,CAAC;oBACvH,MAAM,eAAe,GAAI,MAAM,CAAC,SAAsF,IAAI,EAAE,CAAC;oBAE7H,kBAAkB,CAAC,IAAI,CAAC,IAAI,IAAI,WAAW,KAAK,GAAG,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC;oBAExE,UAAU,CAAC,IAAI,CAAC;wBACd,KAAK,EAAE,IAAI;wBACX,KAAK,EAAE,aAAa;wBACpB,MAAM,EAAE,UAAU;wBAClB,SAAS,EAAE,eAAe;wBAC1B,KAAK,EAAE;4BACL,YAAY,EAAE,WAAW,CAAC,YAAY,IAAI,CAAC;4BAC3C,gBAAgB,EAAE,WAAW,CAAC,gBAAgB,IAAI,CAAC;4BACnD,WAAW,EAAE,WAAW,CAAC,WAAW,IAAI,CAAC;yBAC1C;wBACD,UAAU;qBACX,CAAC,CAAC;oBAEH,UAAU,CAAC,YAAY,IAAI,WAAW,CAAC,YAAY,IAAI,CAAC,CAAC;oBACzD,UAAU,CAAC,gBAAgB,IAAI,WAAW,CAAC,gBAAgB,IAAI,CAAC,CAAC;oBACjE,UAAU,CAAC,WAAW,IAAI,WAAW,CAAC,WAAW,IAAI,CAAC,CAAC;gBACzD,CAAC;YACH,CAAC;YAED,gFAAgF;YAChF,MAAM,iBAAiB,GAAG,YAAY,CAAC,YAAY;gBACjD,CAAC,CAAC,OAAO,YAAY,CAAC,YAAY,EAAE;gBACpC,CAAC,CAAC,EAAE,CAAC;YAEP,MAAM,WAAW,GACf,8CAA8C,MAAM,OAAO;gBAC3D,mBAAmB,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM;gBAC3D,+DAA+D,iBAAiB,EAAE,CAAC;YAErF,MAAM,WAAW,GAAG,WAAW,CAAC;gBAC9B,KAAK,EAAE,YAAY,CAAC,KAAK;gBACzB,QAAQ,EAAE,YAAY,CAAC,QAAQ;gBAC/B,MAAM,EAAE,YAAY,CAAC,MAAM;gBAC3B,OAAO,EAAE,YAAY,CAAC,OAAO;gBAC7B,QAAQ,EAAE,CAAC;aACZ,CAAC,CAAC;YAEH,MAAM,SAAS,GAAG,CAAC,MAAM,WAAW,CAAC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,CAAuC,CAAC;YACxG,MAAM,UAAU,GAAI,SAAS,CAAC,KAAoF,IAAI,EAAE,CAAC;YAEzH,UAAU,CAAC,YAAY,IAAI,UAAU,CAAC,YAAY,IAAI,CAAC,CAAC;YACxD,UAAU,CAAC,gBAAgB,IAAI,UAAU,CAAC,gBAAgB,IAAI,CAAC,CAAC;YAChE,UAAU,CAAC,WAAW,IAAI,UAAU,CAAC,WAAW,IAAI,CAAC,CAAC;YAEtD,OAAO,EAAE,GAAG,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QACzD,CAAC;QAED,MAAM,CAAC,MAAM,EAAE,IAAI;YACjB;;;;eAIG;YACH,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAqC,CAAC;YACrF,MAAM,WAAW,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAC,CAAC,IAAe,IAAI,EAAE,CAAC,CAAC;YAExE,OAAO;gBACL,UAAU,EAAE,CAAC,KAAK,SAAS,CAAC;oBAC1B,MAAM,MAAM,WAAW,CAAC;gBAC1B,CAAC,CAAC,EAAE;gBACJ,UAAU,EAAE,CAAC,KAAK,SAAS,CAAC;oBAC1B,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC;oBAC/B,MAAM,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC;gBACxC,CAAC,CAAC,EAAE;gBACJ,IAAI,EAAE,WAAW;gBACjB,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;aAC1C,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"debate.js","sourceRoot":"","sources":["../../../src/api/strategies/debate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,aAAa,CAAC;AAQnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAA0B,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,aAAa,CAC3B,MAA+C,EAC/C,YAA2B;IAE3B,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,iBAAiB,CACzB,kFAAkF,CACnF,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,uCAAuC;IACvC,MAAM,SAAS,GAAG,YAAY,CAAC,SAAS,IAAI,CAAC,CAAC;IAE9C,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI;YACxB,MAAM,UAAU,GAAsB,EAAE,CAAC;YACzC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACvC,MAAM,UAAU,GAAG,EAAE,YAAY,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;YAC5E,MAAM,kBAAkB,GAAa,EAAE,CAAC;YAExC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC;gBAC/C,KAAK,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,OAAO,EAAE,CAAC;oBAC5C,2DAA2D;oBAC3D,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;oBAChF,IAAI,QAAQ,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;wBACnC,uDAAuD;wBACvD,SAAS;oBACX,CAAC;oBAED,MAAM,CAAC,GAAG,YAAY,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;oBAEpD,iEAAiE;oBACjE,wEAAwE;oBACxE,wDAAwD;oBACxD,MAAM,aAAa,GACjB,SAAS,MAAM,MAAM;wBACrB,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC;4BAC5B,CAAC,CAAC,wBAAwB,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE;4BAC9D,CAAC,CAAC,6BAA6B,CAAC;wBAClC,mCAAmC,IAAI,WAAW,KAAK,GAAG,CAAC,IAAI,SAAS,IAAI,CAAC;oBAE/E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;oBACzB,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC,CAA4B,CAAC;oBAClF,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;oBAEtC,MAAM,UAAU,GAAI,MAAM,CAAC,IAAe,IAAI,EAAE,CAAC;oBACjD,MAAM,WAAW,GAAI,MAAM,CAAC,KAAoF,IAAI,EAAE,CAAC;oBACvH,MAAM,eAAe,GAAI,MAAM,CAAC,SAAsF,IAAI,EAAE,CAAC;oBAE7H,qEAAqE;oBACrE,2BAA2B;oBAC3B,kBAAkB,CAAC,IAAI,CAAC,IAAI,IAAI,WAAW,KAAK,GAAG,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC;oBAExE,UAAU,CAAC,IAAI,CAAC;wBACd,KAAK,EAAE,IAAI;wBACX,KAAK,EAAE,aAAa;wBACpB,MAAM,EAAE,UAAU;wBAClB,SAAS,EAAE,eAAe;wBAC1B,KAAK,EAAE;4BACL,YAAY,EAAE,WAAW,CAAC,YAAY,IAAI,CAAC;4BAC3C,gBAAgB,EAAE,WAAW,CAAC,gBAAgB,IAAI,CAAC;4BACnD,WAAW,EAAE,WAAW,CAAC,WAAW,IAAI,CAAC;yBAC1C;wBACD,UAAU;qBACX,CAAC,CAAC;oBAEH,UAAU,CAAC,YAAY,IAAI,WAAW,CAAC,YAAY,IAAI,CAAC,CAAC;oBACzD,UAAU,CAAC,gBAAgB,IAAI,WAAW,CAAC,gBAAgB,IAAI,CAAC,CAAC;oBACjE,UAAU,CAAC,WAAW,IAAI,WAAW,CAAC,WAAW,IAAI,CAAC,CAAC;gBACzD,CAAC;YACH,CAAC;YAED,6EAA6E;YAC7E,MAAM,iBAAiB,GAAG,YAAY,CAAC,YAAY;gBACjD,CAAC,CAAC,OAAO,YAAY,CAAC,YAAY,EAAE;gBACpC,CAAC,CAAC,EAAE,CAAC;YAEP,MAAM,WAAW,GACf,8CAA8C,MAAM,OAAO;gBAC3D,mBAAmB,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM;gBAC3D,+DAA+D,iBAAiB,EAAE,CAAC;YAErF,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/graphCompiler.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @file graphCompiler.ts
+ * Compiles agency() strategy configurations into CompiledExecutionGraph IR.
+ *
+ * This bridge enables the high-level agency() API to leverage the full
+ * GraphRuntime DAG engine, gaining:
+ *  - Checkpointing / mid-run persistence
+ *  - Structured state passing (scratch/artifacts)
+ *  - Conditional edge routing
+ *  - Guardrail nodes
+ *  - Parallel node execution
+ *  - Serializable IR
+ *
+ * Each strategy maps to a different graph topology:
+ *  - sequential: A -> B -> C -> END
+ *  - parallel: START -> [A, B, C] -> synthesize -> END
+ *  - debate: round-based chains with a final synthesizer
+ *  - review-loop: producer -> reviewer -> conditional back-edge
+ *  - hierarchical: manager GMI node with delegation tool calls
+ *
+ * @see {@link compileAgencyToGraph} -- the main entry point.
+ * @see {@link GraphRuntime} -- the engine that executes the compiled graph.
+ */
+import type { CompiledExecutionGraph } from '../../orchestration/ir/types.js';
+import type { AgencyOptions } from '../types.js';
+/**
+ * Compiles an agency configuration into a CompiledExecutionGraph
+ * that can be executed by GraphRuntime.
+ *
+ * Each sub-agent becomes a GMI node in the graph. The strategy
+ * determines how nodes are connected:
+ * - sequential: A -> B -> C -> END
+ * - parallel: START -> [A, B, C] -> synthesize -> END
+ * - debate: round-based sequential chain -> synthesize -> END
+ * - review-loop: produce -> review -> (conditional) produce/END
+ * - hierarchical: manager GMI node -> END (delegation via tool calls)
+ *
+ * The compiled graph carries:
+ * - Proper state reducers for scratch field merging
+ * - Checkpoint policy for mid-run persistence
+ * - Schema declarations for input/scratch/artifacts
+ *
+ * @param config - The full AgencyOptions with agents, strategy, and settings.
+ * @param prompt - The user's input prompt to inject into the graph's initial state.
+ * @returns A CompiledExecutionGraph ready for GraphRuntime.invoke() or .stream().
+ *
+ * @example
+ * ```ts
+ * const graph = compileAgencyToGraph(agencyConfig, 'Summarise AI research.');
+ * const runtime = new GraphRuntime({ checkpointStore, nodeExecutor });
+ * const result = await runtime.invoke(graph, { prompt: 'Summarise AI research.' });
+ * ```
+ */
+export declare function compileAgencyToGraph(config: AgencyOptions, prompt: string): CompiledExecutionGraph;
+/**
+ * Maps the final GraphState from a GraphRuntime run back to the shape
+ * expected by the agency API's GenerateTextResult.
+ *
+ * Extracts the final text output from artifacts/scratch and constructs
+ * the agentCalls array from the graph's diagnostic node timings.
+ *
+ * @param finalOutput - The artifacts payload returned by GraphRuntime.invoke().
+ * @param config - The original agency configuration (used for metadata).
+ * @returns An object compatible with the agency execute() return shape.
+ */
+export declare function mapGraphResultToAgencyResult(finalOutput: unknown, config: AgencyOptions): Record<string, unknown>;
+/**
+ * Maps a GraphEvent from the runtime's stream into an AgencyStreamPart.
+ *
+ * Translates the lower-level graph events (node_start, node_end, text_delta)
+ * into the agency-level event vocabulary (agent-start, agent-end, text).
+ *
+ * @param event - A GraphEvent from GraphRuntime.stream().
+ * @param config - The original agency configuration (used for metadata).
+ * @returns An AgencyStreamPart, or null if the event has no agency-level equivalent.
+ */
+export declare function mapGraphEventToAgencyEvent(event: {
+    type: string;
+    [key: string]: unknown;
+}, config: AgencyOptions): {
+    type: string;
+    [key: string]: unknown;
+} | null;
+//# sourceMappingURL=graphCompiler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graphCompiler.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/graphCompiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,sBAAsB,EAIvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EACV,aAAa,EAGd,MAAM,aAAa,CAAC;AAqiBrB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,GACb,sBAAsB,CAiDxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,OAAO,EACpB,MAAM,EAAE,aAAa,GACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAezB;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAC/C,MAAM,EAAE,aAAa,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAAG,IAAI,CAiCjD"}