kagent-ts 0.1.4 → 0.1.5

package/dist/orchestrator/orchestrator-agent.d.ts

@@ -0,0 +1,152 @@
+import { Agent, AgentConfig } from "../core/agent";
+import { SessionState, SessionStatus } from "../session/session-types";
+/**
+ * Configuration for the OrchestratorAgent.
+ */
+export interface OrchestratorAgentConfig extends AgentConfig {
+    /**
+     * Maximum orchestration rounds (Decompose + N × Dispatch-Synthesize-Adapt).
+     * Each round dispatches a batch of ready nodes, synthesises results, and
+     * optionally generates new nodes for the next round.
+     *
+     * Default: 3.
+     */
+    maxRounds?: number;
+    /**
+     * Maximum number of task nodes that can run in parallel during dispatch.
+     * Default: 5.
+     */
+    maxParallelNodes?: number;
+    /**
+     * Maximum total task nodes across all rounds before the orchestrator
+     * forces synthesis. Prevents unbounded task graph growth.
+     * Default: 20.
+     */
+    maxTotalNodes?: number;
+}
+/**
+ * Orchestrator Agent that decomposes user requests into a DAG of sub-tasks,
+ * dispatches them to sub-agents, synthesises results, and adapts the plan
+ * based on what is learned.
+ *
+ * ## Execution flow:
+ * ```
+ * User Input
+ *   ↓
+ * [1. Decompose]  LLM analyses request → TaskGraph (DAG of sub-agent tasks)
+ *   ↓
+ * ┌─ Loop (up to maxRounds rounds) ─────────────────────────────┐
+ * │                                                              │
+ * │ [2. Dispatch]  Topological execution of ready nodes           │
+ * │     - Nodes with no pending deps are spawned in parallel      │
+ * │     - Parent waits for all ready nodes to complete            │
+ * │     - Results are injected into context                       │
+ * │                                                              │
+ * │ [3. Synthesize]  LLM reviews all results → isComplete?       │
+ * │     ├─ YES → return finalAnswer                              │
+ * │     └─ NO  → produce gaps list                               │
+ * │                                                              │
+ * │ [4. Adapt]  LLM turns gaps into new TaskNodes                │
+ * │     - New nodes appended to task graph                        │
+ * │     - Loop back to Dispatch                                   │
+ * │                                                              │
+ * └──────────────────────────────────────────────────────────────┘
+ *   ↓
+ * Final Answer
+ * ```
+ *
+ * ## Session persistence
+ * When `enableCheckpointing` is set, the agent saves the full task graph
+ * state so orchestration can resume after interruption.
+ */
+export declare class OrchestratorAgent extends Agent {
+    private maxRounds;
+    private maxParallelNodes;
+    private maxTotalNodes;
+    /** The current task graph. */
+    private taskGraph;
+    /** How many dispatch rounds have been completed. */
+    private completedRounds;
+    /** Internal flag: when true, run() skips state reset (used by resume()). */
+    private _skipStateReset;
+    constructor(config: OrchestratorAgentConfig);
+    /**
+     * Return the SubAgentManager, throwing a clear error if sub-agents were
+     * not configured. The Orchestrator cannot function without sub-agents.
+     */
+    private getSubAgentManager;
+    run(input: string): Promise<string>;
+    /**
+     * Ask the LLM to decompose the user's request into a TaskGraph.
+     *
+     * Sends a dedicated prompt with the list of available sub-agents so the
+     * LLM knows what it can delegate to.
+     */
+    private decompose;
+    /**
+     * Execute all ready nodes in the task graph using topological wave-front
+     * dispatch. Nodes with no pending dependencies run in parallel (up to
+     * `maxParallelNodes`), then their dependants become ready.
+     *
+     * This method blocks until all currently ready (and transitively ready)
+     * nodes have completed.
+     */
+    private dispatchReadyNodes;
+    /**
+     * Return nodes whose dependencies are all completed and that haven't
+     * been dispatched yet, limited by maxParallelNodes.
+     */
+    private getReadyNodes;
+    /**
+     * Busy-wait until all given nodes have resolved (completed or failed).
+     */
+    private pollUntilNodesComplete;
+    /**
+     * Resolve `{{node_id.output}}` template references in a node's input.
+     */
+    private resolveInputTemplate;
+    /**
+     * Ask the LLM to review all completed node results and determine whether
+     * the information is sufficient to answer the user.
+     */
+    private synthesize;
+    /**
+     * Build a formatted string of all completed node results for the
+     * synthesis LLM prompt.
+     */
+    private formatCompletedResults;
+    /**
+     * Ask the LLM to generate new task nodes to fill the gaps identified
+     * during synthesis.
+     */
+    private adapt;
+    /**
+     * Force a final synthesis when rounds are exhausted or the orchestrator
+     * is stuck. Asks the LLM to produce the best answer it can with whatever
+     * results are available.
+     */
+    private forceSynthesize;
+    /**
+     * Agent type identifier for session metadata.
+     */
+    protected getAgentType(): "orchestrator";
+    /**
+     * Include orchestrator state in session checkpoints.
+     */
+    protected buildBaseSessionState(status: SessionStatus): SessionState;
+    /**
+     * Restore orchestrator state from a saved session.
+     */
+    protected loadAndRestoreSession(sessionId: string): SessionState;
+    /**
+     * Resume a previously interrupted orchestration session.
+     *
+     * Restores messages, system prompt, and the full task graph so the
+     * orchestrator can continue from where it left off.
+     *
+     * @param sessionId The session ID to resume.
+     * @param input     New user input to continue the conversation.
+     */
+    resume(sessionId: string, input: string): Promise<string>;
+}
+//# sourceMappingURL=orchestrator-agent.d.ts.map

package/dist/orchestrator/orchestrator-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-agent.d.ts","sourceRoot":"","sources":["../../src/orchestrator/orchestrator-agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAMnD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAgCvE;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,WAAW;IAC1D;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAG1C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,aAAa,CAAS;IAI9B,8BAA8B;IAC9B,OAAO,CAAC,SAAS,CAA4B;IAE7C,oDAAoD;IACpD,OAAO,CAAC,eAAe,CAAK;IAE5B,4EAA4E;IAC5E,OAAO,CAAC,eAAe,CAAS;gBAEpB,MAAM,EAAE,uBAAuB;IAc3C;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAkBpB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiKzC;;;;;OAKG;YACW,SAAS;IAqEvB;;;;;;;OAOG;YACW,kBAAkB;IAyDhC;;;OAGG;IACH,OAAO,CAAC,aAAa;IAyBrB;;OAEG;YACW,sBAAsB;IAsCpC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;OAGG;YACW,UAAU;IA2DxB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAqB9B;;;OAGG;YACW,KAAK;IAoEnB;;;;OAIG;YACW,eAAe;IAiF7B;;OAEG;IACH,SAAS,CAAC,YAAY,IAAI,cAAc;IAIxC;;OAEG;IACH,SAAS,CAAC,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY;IAapE;;OAEG;IACH,SAAS,CAAC,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY;IAchE;;;;;;;;OAQG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAKhE"}