@wrongstack/core 0.6.7 → 0.7.2

package/dist/multi-agent-coordinator-DGUn-5Bb.d.ts

@@ -0,0 +1,448 @@
+import { A as Agent, n as AgentInput } from './index-B2WWETRP.js';
+import { E as EventBus } from './events-AjrvHJ9V.js';
+import { c as SubagentConfig, k as TaskSpec, i as SubagentRunner, b as MultiAgentCoordinator, M as MultiAgentConfig, S as SpawnResult, l as BridgeMessage, A as AgentBridge, a as CoordinatorStatus, j as TaskResult } from './multi-agent-DenFfUv5.js';
+import { EventEmitter } from 'node:events';
+
+/**
+ * Single fleet-wide event with subagent attribution. Whatever a child
+ * agent emits on its own EventBus gets re-published here, prefixed with
+ * `subagentId` so a single subscriber can multiplex across the fleet.
+ *
+ * The director uses `FleetBus.filter('tool.executed', …)` to see every
+ * tool call across the fleet; the TUI uses
+ * `FleetBus.subscribe(id, handler)` to render a per-subagent panel.
+ */
+interface FleetEvent {
+    subagentId: string;
+    taskId?: string;
+    ts: number;
+    type: string;
+    payload: unknown;
+}
+type FleetHandler = (event: FleetEvent) => void;
+/**
+ * Fan-in for per-subagent EventBuses. Each subagent's bus is plugged in
+ * via `attach()`; the FleetBus re-emits every event with subagent
+ * attribution. Detachment is automatic via the returned disposer — call
+ * it when a subagent terminates so we don't leak listeners.
+ *
+ * The bus exposes two subscription modes: by `subagentId` (everything
+ * from one child) and by `type` (one event-type across the fleet). They
+ * compose — if you need a per-subagent + per-type slice, subscribe by
+ * type and filter on `event.subagentId` in your handler.
+ */
+declare class FleetBus {
+    private readonly byId;
+    private readonly byType;
+    private readonly any;
+    /**
+     * Hook a subagent's EventBus into the fleet. EventBus is strongly
+     * typed and doesn't expose an `onAny` hook, so we subscribe to the
+     * canonical set of event types a subagent emits during a run. New
+     * event types added to the kernel must be added here too — but the
+     * cost is a tiny single line per type, and the explicit list keeps
+     * the wire format clear.
+     *
+     * Returns a disposer that detaches every subscription; call on
+     * subagent teardown so the listeners don't outlive the run.
+     */
+    attach(subagentId: string, bus: EventBus, taskId?: string): () => void;
+    /** Subscribe to every event from one subagent. */
+    subscribe(subagentId: string, handler: FleetHandler): () => void;
+    /** Subscribe to one event type across all subagents. */
+    filter(type: string, handler: FleetHandler): () => void;
+    /** Subscribe to literally everything. The fleet roll-up uses this. */
+    onAny(handler: FleetHandler): () => void;
+    emit(event: FleetEvent): void;
+}
+/**
+ * Roll-up of token usage + cost across an entire director run. The
+ * director's `fleet_status` tool returns this so the model can reason
+ * about budget in its next turn ("the researcher already burned $0.40,
+ * lean on summaries for the next task").
+ */
+interface FleetUsage {
+    total: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        cost: number;
+    };
+    perSubagent: Record<string, SubagentUsageSnapshot>;
+}
+interface SubagentUsageSnapshot {
+    subagentId: string;
+    provider?: string;
+    model?: string;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+    toolCalls: number;
+    iterations: number;
+    startedAt: number;
+    lastEventAt: number;
+}
+/**
+ * Aggregates provider.response + tool.executed events from the FleetBus
+ * into a live `FleetUsage` snapshot. Costs are computed by the caller
+ * via a `priceLookup(subagentId)` so we don't bake provider-pricing
+ * coupling into core; the CLI/tests supply a function that resolves
+ * each subagent's per-token rates from the models registry.
+ */
+declare class FleetUsageAggregator {
+    private readonly bus;
+    private readonly priceLookup?;
+    private readonly metaLookup?;
+    private readonly perSubagent;
+    private readonly total;
+    constructor(bus: FleetBus, priceLookup?: ((subagentId: string) => {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    } | undefined) | undefined, metaLookup?: ((subagentId: string) => {
+        provider?: string;
+        model?: string;
+    } | undefined) | undefined);
+    /** Live snapshot — safe to call from a tool's execute() body. */
+    snapshot(): FleetUsage;
+    private ensure;
+    private onProviderResponse;
+    private onToolExecuted;
+    private onIterationStarted;
+}
+
+/**
+ * Caller-supplied factory that builds an isolated `Agent` for a subagent.
+ * The factory MUST construct a fresh `Context` per call — sharing context
+ * between subagents defeats isolation. Each Agent should also use either
+ * its own `EventBus` or a forwarded view, so per-subagent metrics can be
+ * attributed correctly.
+ */
+type AgentFactory = (config: SubagentConfig) => Promise<AgentFactoryResult>;
+interface AgentFactoryResult {
+    agent: Agent;
+    /** Event bus the factory wired to this agent — required for budget hookup. */
+    events: EventBus;
+    /**
+     * Optional cleanup hook invoked in the runner's `finally` block once
+     * the task ends (success, failure, abort — same exit path). Factories
+     * that own resources scoped to a single task (per-subagent JSONL
+     * writers, transient providers, throwaway containers) implement this
+     * to close them deterministically instead of relying on GC. Errors
+     * thrown here are swallowed so a flaky cleanup can't mask the task's
+     * real result.
+     */
+    dispose?: () => Promise<void> | void;
+}
+interface AgentRunnerOptions {
+    factory: AgentFactory;
+    /**
+     * Format a TaskSpec into the user input the agent will receive. Defaults
+     * to `task.description ?? ''`. Override when subagents expect structured
+     * input (e.g. JSON contracts, role-prefixed prompts).
+     */
+    formatTaskInput?: (task: TaskSpec, config: SubagentConfig) => AgentInput;
+    /**
+     * When set, the runner attaches the subagent's EventBus to this FleetBus
+     * on task start and detaches it when the task finishes. This is the
+     * injection seam that lets the TUI fleet panel observe subagent activity
+     * live — without it, FleetBus stays empty.
+     */
+    fleetBus?: FleetBus;
+}
+/**
+ * Builds a `SubagentRunner` that drives a real `Agent` per task while honoring
+ * the coordinator's budget and abort signal. This is the production adapter —
+ * the coordinator's `runner` option in CLI/TUI assemblies points here.
+ *
+ * Lifecycle per task:
+ *   1. factory(config) → fresh Agent + EventBus.
+ *   2. Subscribe to events to feed the budget (tool calls, token usage).
+ *   3. Call agent.run(input, { signal }) — the coordinator's signal cancels.
+ *   4. Map RunResult.status onto a `SubagentRunOutcome` or throw on failure.
+ *   5. Unsubscribe and let the factory's resources be GC'd.
+ *
+ * The budget is checked synchronously from event handlers — a runaway agent
+ * that crosses its tool-call limit triggers `BudgetExceededError`, which the
+ * coordinator surfaces as `status: 'failed'` on the task result.
+ */
+declare function makeAgentSubagentRunner(opts: AgentRunnerOptions): SubagentRunner;
+
+/**
+ * Catalog types for the WrongStack agent fleet.
+ *
+ * An `AgentDefinition` bundles the runtime `SubagentConfig` (id/name/role/
+ * prompt/tools) with two things the bare config lacks:
+ *   - a per-role `budget` tier (consumed by FLEET_ROSTER_BUDGETS), and
+ *   - dispatcher `capability` metadata (keywords + summary + phase) used by
+ *     the smart dispatcher to route a free-form task to the best agent.
+ *
+ * Phase files (`phase1-discovery.ts` … `phase9-meta.ts`) each export an
+ * `AgentDefinition[]`; `index.ts` aggregates them into `AGENT_CATALOG`.
+ * `fleet.ts` derives `FLEET_ROSTER` + `FLEET_ROSTER_BUDGETS` from the catalog.
+ */
+
+/** Lifecycle phase grouping. Drives statusline labels + dispatcher tie-breaks. */
+type AgentPhase = 'discovery' | 'planning' | 'build' | 'verify' | 'review' | 'domain' | 'knowledge' | 'delivery' | 'meta';
+/** Per-role budget tier. Same shape as fleet.ts `FleetRosterBudget`. */
+interface AgentBudgetTier {
+    timeoutMs?: number;
+    maxIterations?: number;
+    maxToolCalls?: number;
+    maxTokens?: number;
+    maxCostUsd?: number;
+}
+/** Dispatcher routing metadata. */
+interface AgentCapability {
+    phase: AgentPhase;
+    /**
+     * One-line capability summary. Fed to the LLM dispatcher classifier as the
+     * candidate's description, and shown to the user when explaining a routing
+     * decision. Keep it concrete and distinct from sibling agents.
+     */
+    summary: string;
+    /**
+     * Lowercased signal words/phrases for the heuristic dispatcher. A task whose
+     * description contains these scores toward this agent. Order doesn't matter;
+     * prefer specific terms ("graphql", "wcag") over generic ones ("code").
+     */
+    keywords: string[];
+}
+/** A single catalog entry: runtime config + budget tier + routing metadata. */
+interface AgentDefinition {
+    config: SubagentConfig;
+    budget: AgentBudgetTier;
+    capability: AgentCapability;
+}
+/**
+ * Budget tiers by workload weight. Deliberately generous — the project's
+ * existing roster uses multi-hour ceilings to avoid spurious timeouts on
+ * monorepo-scale work, and the auto-extend handshake raises them further when
+ * a subagent is still making progress.
+ */
+declare const LIGHT_BUDGET: AgentBudgetTier;
+declare const MEDIUM_BUDGET: AgentBudgetTier;
+declare const HEAVY_BUDGET: AgentBudgetTier;
+/**
+ * Tool allowlist presets. Agents pass the smallest set that covers their job —
+ * a planning agent should not hold `write`/`bash`, a reviewer should be
+ * read-only. Spread + extend per-agent where a role needs one extra tool.
+ */
+declare const TOOLS: {
+    /** Pure read/inspect — safe for analysis and review agents. */
+    readonly read: readonly ["read", "grep", "glob", "search", "tree"];
+    /** Read + structured inspection (logs, diffs, json, dependency audit). */
+    readonly inspect: readonly ["read", "grep", "glob", "search", "tree", "json", "diff", "logs", "audit"];
+    /** Read + edit (no shell). For agents that write code/docs but don't run it. */
+    readonly write: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch"];
+    /** Full build loop: edit + run (lint/format/typecheck/test/bash). */
+    readonly build: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch", "bash", "exec", "lint", "format", "typecheck", "test"];
+    /** Version control. */
+    readonly vcs: readonly ["read", "grep", "glob", "git", "diff"];
+    /** Dependency management + CVE audit. */
+    readonly deps: readonly ["read", "grep", "glob", "install", "outdated", "audit", "json"];
+    /** Documentation authoring. */
+    readonly docs: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "document"];
+    /** Web research. */
+    readonly research: readonly ["read", "grep", "glob", "search", "fetch"];
+};
+
+/**
+ * Smart agent dispatcher.
+ *
+ * Routes a free-form task description to the best agent in the catalog using a
+ * two-stage strategy:
+ *
+ *   1. Heuristic — keyword/phrase scoring against each agent's `capability`
+ *      metadata. Deterministic, instant, no provider call. Multi-word phrases
+ *      score higher than single words (they're more specific signals).
+ *
+ *   2. LLM fallback — when the heuristic is ambiguous (confidence below the
+ *      threshold, or no keyword hit at all) an injected `classifier` resolves
+ *      the tie. The classifier is provider-agnostic: callers wire it to any
+ *      `complete(prompt) => text` function via `makeLLMClassifier`, so core
+ *      stays free of provider dependencies and the path is unit-testable.
+ *
+ * If neither stage yields a confident pick, the dispatcher falls back to the
+ * `executor` generalist rather than failing.
+ */
+
+/** Default agent used when nothing else matches — the generalist builder. */
+declare const DEFAULT_DISPATCH_ROLE = "executor";
+interface DispatchCandidate {
+    role: string;
+    name: string;
+    score: number;
+    /** Capability keywords that matched the task text. */
+    matched: string[];
+}
+type DispatchMethod = 'heuristic' | 'llm' | 'fallback';
+interface DispatchResult {
+    role: string;
+    definition: AgentDefinition;
+    /** 0..1 — heuristic margin, or 1 when an LLM made a definite choice. */
+    confidence: number;
+    method: DispatchMethod;
+    /** Human-readable explanation of why this agent was chosen. */
+    reason: string;
+    /** Runner-up candidates (top heuristic scorers), best-first. */
+    alternatives: DispatchCandidate[];
+}
+/**
+ * Provider-agnostic classifier seam. Given the task and the candidate agents
+ * (role + summary), return the chosen role (and optional reason), or null to
+ * decline. Wire via `makeLLMClassifier`.
+ */
+type DispatchClassifier = (task: string, candidates: {
+    role: string;
+    name: string;
+    summary: string;
+}[]) => Promise<{
+    role: string;
+    reason?: string;
+} | null>;
+interface DispatchOptions {
+    /** Optional LLM fallback for ambiguous tasks. */
+    classifier?: DispatchClassifier;
+    /** Heuristic confidence below this triggers the classifier. Default 0.4. */
+    confidenceThreshold?: number;
+    /** How many top candidates to offer the classifier. Default 6. */
+    maxCandidates?: number;
+    /** Override the catalog (testing). Defaults to the full `AGENT_CATALOG`. */
+    catalog?: Record<string, AgentDefinition>;
+}
+/**
+ * Score every agent against the task. A keyword hit adds 1 point; a multi-word
+ * keyword phrase adds points equal to its word count (more specific = stronger
+ * signal). Returns candidates sorted best-first, zero-score agents dropped.
+ */
+declare function scoreAgents(task: string, catalog?: Record<string, AgentDefinition>): DispatchCandidate[];
+/**
+ * Route a task to the best agent. Async because the LLM fallback may run; the
+ * pure-heuristic path resolves without awaiting anything.
+ */
+declare function dispatchAgent(task: string, opts?: DispatchOptions): Promise<DispatchResult>;
+/**
+ * Build a `DispatchClassifier` from a minimal `complete(prompt) => text`
+ * function. The caller supplies the provider call; this owns the prompt and
+ * the parsing. Keeps `dispatcher` free of any provider import.
+ */
+declare function makeLLMClassifier(complete: (prompt: string) => Promise<string>): DispatchClassifier;
+
+interface MultiAgentCoordinatorOptions {
+    /**
+     * Callback that executes a task on behalf of a subagent. Required for
+     * `assign()` to actually run anything — without it, tasks queue forever.
+     * The coordinator provides per-subagent isolation (own budget, own signal,
+     * own bridge) and enforces timeout + concurrency.
+     */
+    runner?: SubagentRunner;
+}
+declare class DefaultMultiAgentCoordinator extends EventEmitter implements MultiAgentCoordinator {
+    readonly coordinatorId: string;
+    readonly config: MultiAgentConfig;
+    private runner?;
+    private readonly subagents;
+    private pendingTasks;
+    private completedResults;
+    private totalIterations;
+    private inFlight;
+    /**
+     * Subagents currently being stopped. Set on entry to `stop()`, cleared
+     * once `recordCompletion` lands the terminal TaskResult. Used by
+     * `runDispatched` and `findIdleSubagent` to refuse mid-flight dispatch
+     * to a subagent the caller has already asked to terminate — closes the
+     * assign+terminate race where a fresh task could land on a worker that
+     * was about to be killed.
+     */
+    private readonly terminating;
+    constructor(config: MultiAgentConfig, options?: MultiAgentCoordinatorOptions);
+    /**
+     * Replace the runner after construction. Used when the runner depends
+     * on infrastructure (e.g. FleetBus) that isn't available until after
+     * the coordinator's owning Director is built.
+     */
+    setRunner(runner: SubagentRunner): void;
+    /**
+     * Change the in-flight dispatch ceiling at runtime. Lowering does NOT
+     * preempt running tasks — already-dispatched subagents finish their
+     * current task; only future dispatches respect the new cap. Raising
+     * immediately tries to fill the freed slots from the pending queue.
+     */
+    setMaxConcurrent(n: number): void;
+    spawn(subagent: SubagentConfig): Promise<SpawnResult>;
+    assign(task: TaskSpec): Promise<void>;
+    delegate(to: string, msg: BridgeMessage): Promise<void>;
+    /**
+     * Wire up the communication bridge for a subagent. Call after spawn() once
+     * the caller has created the bidirectional connection.
+     */
+    setSubagentBridge(subagentId: string, bridge: AgentBridge): void;
+    stop(subagentId: string): Promise<void>;
+    stopAll(): Promise<void>;
+    remove(subagentId: string): Promise<void>;
+    /**
+     * Get current coordinator stats for monitoring/debugging.
+     */
+    getStats(): {
+        total: number;
+        running: number;
+        idle: number;
+        stopped: number;
+        inFlight: number;
+        pending: number;
+        completed: number;
+    };
+    getStatus(): CoordinatorStatus;
+    /** Expose snapshot of completed results — useful for callers awaiting all done. */
+    results(): readonly TaskResult[];
+    /**
+     * Wait for one or more tasks to complete and return their results.
+     * If a task is already done when called, returns immediately.
+     * Resolves to an array in the same order as `taskIds`.
+     */
+    awaitTasks(taskIds: string[]): Promise<TaskResult[]>;
+    /**
+     * Manual completion — for callers that drive subagents without a runner
+     * (e.g. external orchestrators). When a runner is configured the coordinator
+     * calls this itself.
+     */
+    completeTask(result: TaskResult): void;
+    private tryDispatchNext;
+    private canDispatch;
+    private takeNextDispatchableTask;
+    private findIdleSubagent;
+    private isIdleSubagent;
+    /**
+     * Returns true iff at least one spawned subagent could still
+     * process a task. A "live" subagent is one that is not stopped
+     * AND not mid-termination — `running` workers count because they
+     * will eventually finish and become idle.
+     *
+     * When no subagent has ever been spawned, returns `true` so a
+     * pre-spawn `assign()` simply queues (legacy behaviour). The
+     * dead-end detection only fires after `stop()` has retired every
+     * spawned worker.
+     *
+     * Used by `tryDispatchNext` to detect a dead-end pending queue.
+     */
+    private hasLiveSubagent;
+    /**
+     * Drain every pending task with a synthetic `aborted_by_parent`
+     * completion event. Same shape as the `stopAll()` drain — we go
+     * around `recordCompletion` because pending tasks were never
+     * counted in `inFlight` and routing them through would trip the
+     * underflow guard on every task after the first.
+     */
+    private drainPendingAsAborted;
+    private runDispatched;
+    private executeWithTimeout;
+    private recordCompletion;
+    private isDone;
+}
+
+export { type AgentDefinition as A, DEFAULT_DISPATCH_ROLE as D, FleetBus as F, HEAVY_BUDGET as H, LIGHT_BUDGET as L, MEDIUM_BUDGET as M, type SubagentUsageSnapshot as S, TOOLS as T, type AgentBudgetTier as a, type AgentCapability as b, type AgentFactory as c, type AgentFactoryResult as d, type AgentPhase as e, type AgentRunnerOptions as f, DefaultMultiAgentCoordinator as g, type DispatchCandidate as h, type DispatchClassifier as i, type DispatchMethod as j, type DispatchOptions as k, type DispatchResult as l, type FleetEvent as m, type FleetHandler as n, type FleetUsage as o, FleetUsageAggregator as p, type MultiAgentCoordinatorOptions as q, dispatchAgent as r, makeAgentSubagentRunner as s, makeLLMClassifier as t, scoreAgents as u };