@haoyiyin/workflow 0.2.10 → 0.3.0

package/dist/src/agents/dispatcher.d.ts

@@ -1,12 +1,15 @@
 /**
- * Subagent Dispatcher - Spawns isolated subagents to do all real work
+ * Subagent Dispatcher - Spawns isolated subagents with fresh context
  *
- * Constructs prompts from contracts, manages timeouts, validates outputs,
- * and collects results. Uses a pluggable executor backend so the dispatch
- * mechanism can be swapped (process, HTTP, in-process) without changing
- * the orchestration logic.
+ * Key principle: Each subagent gets ONLY the context it needs.
+ * - No history pollution from main agent
+ * - Minimal, focused prompts
+ * - Token budget enforcement
+ * - Resilient dispatch with circuit breaker and retry
  */
 import type { SubagentConfig, SubagentContract, SubagentResult } from './types.js';
+import { TokenBudget, BudgetExceededError } from './token-budget.js';
+import { ResilientDispatcher } from './resilience.js';
 import type { Logger } from '../types.js';
 export interface ExecutorOptions {
     id: string;
@@ -24,84 +27,124 @@ export interface SubagentExecutor {
     abort(id: string): Promise<void>;
 }
 export interface ProcessExecutorConfig {
-    /** CLI command to invoke (default: "claude") */
     command: string;
-    /** CLI arguments appended after the prompt */
     args: string[];
-    /** Environment variables to forward */
     env: Record<string, string>;
 }
 /**
  * Creates a SubagentExecutor that spawns a subprocess for each dispatch.
- *
- * The executor writes the prompt to a temp file, invokes the configured
- * CLI command with `--input-file`, collects stdout/stderr, and cleans up.
  */
 export declare function createProcessExecutor(config?: Partial<ProcessExecutorConfig>): SubagentExecutor;
+export interface SubagentDispatcherConfig {
+    logger: Logger;
+    tokenBudget?: {
+        limit: number;
+        warningThreshold: number;
+    };
+    resilience?: {
+        circuitBreaker?: {
+            failureThreshold?: number;
+            successThreshold?: number;
+            timeout?: number;
+        };
+        retryPolicy?: {
+            maxRetries?: number;
+            baseDelay?: number;
+            maxDelay?: number;
+        };
+    };
+}
+export interface DispatchConfig {
+    config: SubagentConfig;
+    contract: SubagentContract;
+    fallback?: () => unknown;
+}
 export declare class SubagentDispatcher {
-    private readonly executor;
     private readonly logger;
+    private readonly tokenBudget;
+    private readonly resilientDispatcher;
     private readonly activeIds;
-    constructor(executor: SubagentExecutor, logger: Logger);
+    constructor(config: SubagentDispatcherConfig);
     /**
-     * Dispatch a single subagent with the given config and contract.
+     * Dispatch a single subagent with fresh context.
      *
-     * Constructs a structured prompt from the contract, sends it to the
-     * executor, validates the output against the optional output schema,
-     * and returns a typed SubagentResult.
+     * Steps:
+     * 1. Check token budget
+     * 2. Build fresh prompt (no history pollution)
+     * 3. Spawn subagent via resilient dispatcher
+     * 4. Parse and validate output
+     * 5. Return structured result
      */
     dispatch(config: SubagentConfig, contract: SubagentContract): Promise<SubagentResult>;
     /**
      * Dispatch multiple subagents in parallel.
      *
-     * All subagents run concurrently. Use when tasks are independent
-     * of each other (e.g. exploring multiple directories at once).
+     * Each subagent receives ONLY its own contract - no shared context pollution.
+     * Results are returned in the same order as configs.
      */
-    dispatchParallel(configs: readonly SubagentConfig[], contracts: readonly SubagentContract[]): Promise<SubagentResult[]>;
+    dispatchParallel(configs: DispatchConfig[]): Promise<SubagentResult[]>;
     /**
-     * Dispatch multiple subagents sequentially.
-     *
-     * Each subagent receives the output of all previous subagents as
-     * additional context. The pipeline stops early if a subagent fails
-     * or times out. Use when tasks form a pipeline (e.g. explore ->
-     * implement -> review -> verify).
+     * Get current health status including token usage and circuit state
      */
-    dispatchSequential(configs: readonly SubagentConfig[], contracts: readonly SubagentContract[]): Promise<SubagentResult[]>;
+    getHealth(): {
+        tokenUsage: {
+            used: number;
+            limit: number;
+            percentage: number;
+            remaining: number;
+        };
+        circuitState: string;
+        activeSubagents: number;
+    };
     /**
-     * Abort a running subagent by its ID.
+     * Reset token budget (for testing or new milestone)
      */
-    abort(id: string): Promise<void>;
+    resetBudget(): void;
     /**
-     * Build a structured subagent prompt from config and contract.
+     * Build a fresh prompt with ONLY necessary context.
      *
-     * The prompt follows the Claude Code agent tool pattern: explicit
-     * permissions, owned/read file scopes, isolation instructions,
-     * token budget, output format requirements, and the task itself.
+     * Excludes:
+     * - Main agent conversation history
+       * - Previous subagent outputs (unless explicitly passed)
+     * - Internal reasoning
+     *
+     * Includes:
+     * - Role instruction
+     * - Permissions
+     * - File scope
+     * - Token budget
+     * - Output schema
+     * - Task description
      */
-    private buildPrompt;
+    private buildFreshPrompt;
     /**
-     * Wraps a promise with a timeout. If the timeout fires first the
-     * subagent is aborted and the promise rejects.
+     * Execute a subagent process.
+     * This is the actual implementation that the resilient dispatcher wraps.
      */
-    private withTimeout;
-    /**
-     * Validate subagent output against an optional schema.
-     * The schema is a Record<string, unknown> where values are type strings
-     * like "string", "number", "boolean", "object".
-     *
-     * Returns an array of validation error messages (empty = valid).
-     */
-    private validateOutput;
+    private executeSubagent;
 }
 export interface DispatcherOptions {
-    executor?: SubagentExecutor;
-    processConfig?: Partial<ProcessExecutorConfig>;
+    logger: Logger;
+    tokenBudget?: {
+        limit: number;
+        warningThreshold: number;
+    };
+    resilience?: {
+        circuitBreaker?: {
+            failureThreshold?: number;
+            successThreshold?: number;
+            timeout?: number;
+        };
+        retryPolicy?: {
+            maxRetries?: number;
+            baseDelay?: number;
+            maxDelay?: number;
+        };
+    };
 }
 /**
  * Create a SubagentDispatcher with sensible defaults.
- *
- * If no executor is provided, a process-based executor is created
- * using `createProcessExecutor` which spawns a CLI command.
  */
-export declare function createDispatcher(logger: Logger, options?: DispatcherOptions): SubagentDispatcher;
+export declare function createDispatcher(options: DispatcherOptions): SubagentDispatcher;
+export { TokenBudget, BudgetExceededError, ResilientDispatcher };
 //# sourceMappingURL=dispatcher.d.ts.map

package/dist/src/agents/dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../../src/agents/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,cAAc,EAIf,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAM1C,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3E,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAMD,MAAM,WAAW,qBAAqB;IACpC,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAQD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,GAAE,OAAO,CAAC,qBAAqB,CAAM,GAC1C,gBAAgB,CAuFlB;AA2CD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;gBAE5B,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM;IAUtD;;;;;;OAMG;IACG,QAAQ,CACZ,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,cAAc,CAAC;IAuE1B;;;;;OAKG;IACG,gBAAgB,CACpB,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,SAAS,EAAE,SAAS,gBAAgB,EAAE,GACrC,OAAO,CAAC,cAAc,EAAE,CAAC;IA6B5B;;;;;;;OAOG;IACG,kBAAkB,CACtB,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,SAAS,EAAE,SAAS,gBAAgB,EAAE,GACrC,OAAO,CAAC,cAAc,EAAE,CAAC;IAgC5B;;OAEG;IACG,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IActC;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAyBnB;;;OAGG;IACH,OAAO,CAAC,WAAW;IA+BnB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;CAyCvB;AAyJD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAChD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,GAC9B,kBAAkB,CAIpB"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../../src/agents/dispatcher.ts"],"names":[],"mappings":"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"}