@wrongstack/core 0.284.0 → 0.285.0

package/dist/coordination/icoordinator.d.ts

@@ -0,0 +1,97 @@
+import type { SubagentConfig } from '../types/multi-agent.js';
+import type { TaskSpec, TaskResult, CoordinatorStatus } from '../types/multi-agent.js';
+export type { TaskSpec, TaskResult } from '../types/multi-agent.js';
+/**
+ * Interface for a fleet coordinator. Implemented by both `Director`
+ * (full LLM-driven orchestration with fleet policy) and
+ * `DefaultMultiAgentCoordinator` (direct API-driven, no fleet policy).
+ *
+ * External callers — CLI slash commands, tests, the delegate tool —
+ * use this to stay agnostic to the orchestration mode.
+ *
+ * The interface captures the **orchestration contract**: spawn, assign,
+ * terminate, await, and query. Fleet-level policy (cost caps, manifest
+ * writing, checkpointing) lives behind this surface and is optional
+ * from the caller's perspective.
+ *
+ * @example
+ * ```typescript
+ * let coordinator: ICoordinator = isDirectorMode
+ *   ? new Director({ config, ... })
+ *   : new DefaultMultiAgentCoordinator(config);
+ * const id = await coordinator.spawn({ name: 'worker', role: 'researcher' });
+ * await coordinator.assign({ id: 't-1', description: 'research X', subagentId: id });
+ * const results = await coordinator.awaitTasks(['t-1']);
+ * ```
+ */
+export interface ICoordinator {
+    /** Stable identifier for this coordinator instance. */
+    readonly coordinatorId: string;
+    /**
+     * Spawn a new subagent and return its id. In director mode this
+     * enforces fleet-wide spawn caps and cost limits; in raw coordinator
+     * mode it is a direct pass-through.
+     */
+    spawn(config: SubagentConfig): Promise<string>;
+    /**
+     * Assign a task to a subagent (or to the fleet for auto-routing).
+     * Returns the assigned task id.
+     */
+    assign(task: {
+        id: string;
+        description: string;
+        subagentId?: string | undefined;
+    }): Promise<string>;
+    /**
+     * Synchronously ask a subagent something via the in-memory bridge.
+     * The subagent must have been spawned and must handle `bridge.subscribe()`
+     * in its task loop. Returns the reply payload or throws on timeout.
+     *
+     * Only available in director mode — raw coordinator has no bridge.
+     */
+    ask<T = unknown>(subagentId: string, payload: unknown, timeoutMs?: number): Promise<T> | undefined;
+    /**
+     * 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[]>;
+    /**
+     * Gracefully stop a single subagent. The subagent finishes its current
+     * in-flight work and exits cleanly — it does not hard-kill.
+     */
+    terminate(subagentId: string): Promise<void>;
+    /**
+     * Stop all subagents. In-flight tasks are allowed to complete;
+     * no new tasks are dispatched.
+     */
+    terminateAll(): Promise<void>;
+    /**
+     * Stop a subagent and remove it from the coordinator. Releases all
+     * associated resources (AbortController, budget state). The subagent
+     * entry is deleted so the id can be reused in a future spawn.
+     */
+    remove(subagentId: string): Promise<void>;
+    /**
+     * Live coordinator status — subagent list, pending task count,
+     * completed task count, iteration totals.
+     */
+    status(): CoordinatorStatus;
+    /**
+     * Snapshot of completed task results. In director mode this returns
+     * every `TaskResult` from the fleet; in raw coordinator mode this
+     * may return an empty array if the coordinator doesn't cache results.
+     */
+    completedResults(): TaskResult[];
+    /**
+     * Subscribe to coordinator lifecycle events. Currently supports
+     * `task.completed` — the payload carries the task spec and result.
+     *
+     * Returns a disposer function; call it to unsubscribe.
+     */
+    on(event: 'task.completed', handler: (payload: {
+        task: TaskSpec;
+        result: TaskResult;
+    }) => void): () => void;
+}
+//# sourceMappingURL=icoordinator.d.ts.map

package/dist/coordination/icoordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icoordinator.d.ts","sourceRoot":"","sources":["../../src/coordination/icoordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACvF,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/C;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpG;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAEnG;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAErD;;;OAGG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C;;;OAGG;IACH,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B;;;;OAIG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;;OAGG;IACH,MAAM,IAAI,iBAAiB,CAAC;IAE5B;;;;OAIG;IACH,gBAAgB,IAAI,UAAU,EAAE,CAAC;IAEjC;;;;;OAKG;IACH,EAAE,CACA,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,KAAK,IAAI,GACjE,MAAM,IAAI,CAAC;CACf"}

package/dist/coordination/ifleet-manager.d.ts

@@ -0,0 +1,177 @@
+import type { SubagentConfig } from '../types/multi-agent.js';
+import type { FleetBus, FleetUsage } from './fleet-bus.js';
+import type { WorktreeTaskStateUpdate } from './worktree-task-runner.js';
+/**
+ * Interface for fleet-level lifecycle and policy. Covers:
+ * - Spawn lifecycle hooks (canSpawn check, recordSpawn after-effects)
+ * - Budget enforcement (fleet-wide cost cap, spawn count/depth caps)
+ * - Fleet manifest assembly and writing
+ * - Subagent metadata and usage tracking
+ *
+ * `FleetBus` is pure event fan-out and implements no policy.
+ * `FleetManager` encapsulates all fleet-level policy decisions.
+ * `Director` currently owns all of this — this interface lets us
+ * extract it into a swappable component in Phase 5.
+ */
+export interface IFleetManager {
+    /** The FleetBus this manager publishes lifecycle events to. */
+    readonly fleetBus: FleetBus;
+    /**
+     * Snapshot of fleet-wide token usage and cost rollup.
+     * Safe to call from a tool's execute() body.
+     */
+    snapshot(): FleetUsage;
+    /**
+     * Per-subagent metadata captured at spawn time (provider/model/name).
+     * Returns undefined if the subagent is not known to this manager.
+     */
+    getSubagentMeta(id: string): {
+        provider?: string | undefined;
+        model?: string | undefined;
+        name?: string | undefined;
+    } | undefined;
+    /**
+     * Called before a spawn is recorded. Returns a reason string if the
+     * spawn should be rejected (budget cap, depth limit, cost cap, context
+     * overload, etc.), or null to proceed. Director.spawn() calls this
+     * internally.
+     */
+    canSpawn(config: SubagentConfig): {
+        kind: 'max_spawns' | 'max_spawn_depth' | 'max_cost_usd' | 'max_tokens' | 'max_context_load';
+        limit: number;
+        observed: number;
+    } | null;
+    /** Current fleet-wide token/cost ceiling and remaining headroom. */
+    budgetSnapshot?: (() => {
+        maxSpawns: number;
+        usedSpawns: number;
+        remainingSpawns: number;
+        maxTokens: number;
+        usedTokens: number;
+        remainingTokens: number;
+        maxCostUsd: number;
+        usedCostUsd: number;
+        remainingCostUsd: number;
+    }) | undefined;
+    /**
+     * Update the leader agent's current context pressure (tokens used in the
+     * full API request: messages + systemPrompt + toolDefs). The fleet manager
+     * checks this before allowing a new spawn to prevent the leader from
+     * overflowing its context window while orchestrating subagents.
+     */
+    setLeaderContextPressure(tokens: number): void;
+    /**
+     * Assign a memorable nickname (e.g. "Einstein (Bug Hunter)") and mark it
+     * as used so it is never reused. The nickname is written back to `config.name`
+     * so the coordinator and manifest both see the human-readable name.
+     *
+     * NOTE: This only assigns the nickname. The caller MUST call `recordSpawn`
+     * after `coordinator.spawn()` returns with the real subagentId.
+     *
+     * Returns the assigned nickname string.
+     */
+    assignNicknameAndRecord(config: SubagentConfig): string;
+    /**
+     * Readonly view of already-assigned nickname keys. Used by `Director.spawn()`
+     * to avoid assigning the same nickname twice across the fleet.
+     */
+    readonly usedNicknames: ReadonlySet<string>;
+    /**
+     * Called after a spawn succeeds. Records metadata for the usage
+     * aggregator and manifest.
+     *
+     * @param priceLookup Per-token rate lookup for cost calculation.
+     *   When omitted the cost column in usage snapshots stays at 0.
+     */
+    recordSpawn(subagentId: string, config: SubagentConfig, priceLookup?: Record<string, number>): void;
+    /**
+     * Write the fleet manifest to disk. Returns the path written
+     * or null when no manifest path is configured.
+     */
+    writeManifest(): Promise<string | null>;
+    /**
+     * Bypass the debounce timer and write the manifest immediately.
+     * Clears any pending debounce timer before writing.
+     */
+    flushManifest(): Promise<void>;
+    /**
+     * Aggregate fleet-wide status: pending tasks with descriptions and
+     * live subagent snapshot from the coordinator. Used by
+     * `MultiAgentHost.status()` to eliminate host-side state duplication.
+     */
+    getFleetStatus(): {
+        pending: {
+            taskId: string;
+            description: string;
+            subagentId: string;
+        }[];
+        live: {
+            subagentId: string;
+            status: string;
+            task?: string | undefined;
+        }[];
+    };
+    /**
+     * Register a pending task with its description. Called by
+     * `MultiAgentHost.spawn()` after `_spawnAndAssign()` returns so
+     * the description is available in `status()` without host-side storage.
+     */
+    addPendingTask(taskId: string, subagentId: string, description: string): void;
+    /** Record the latest git-worktree lifecycle state for a task. */
+    recordTaskWorktree(update: WorktreeTaskStateUpdate): void;
+    /**
+     * Remove a pending task. Called when the task completes so the
+     * pending list stays accurate.
+     */
+    removePendingTask(taskId: string): void;
+    /**
+     * Wire the coordinator so `getFleetStats()` can delegate to it.
+     * Called by `Director` after constructing the coordinator so
+     * FleetManager's stats reflect live subagent data.
+     */
+    setCoordinator(coordinator: {
+        getStats(): {
+            total: number;
+            running: number;
+            idle: number;
+            stopped: number;
+            inFlight: number;
+            pending: number;
+            completed: number;
+        };
+    }): void;
+    /**
+     * Coordinator stats snapshot for the TUI and monitoring tools.
+     * Returns actionable counts (total/running/idle/stopped/inFlight/
+     * pending/completed) plus per-subagent status details.
+     * Delegates to the coordinator when available; returns zeros
+     * if the coordinator has not yet been set.
+     */
+    getFleetStats(): {
+        total: number;
+        running: number;
+        idle: number;
+        stopped: number;
+        inFlight: number;
+        pending: number;
+        completed: number;
+        subagentStatuses: {
+            subagentId: string;
+            taskId: string;
+            status: string;
+            assigned: boolean;
+        }[];
+    };
+    /**
+     * Called when a subagent is removed so the fleet manager can clean up
+     * associated state (nickname slots, pending tasks, etc.).
+     */
+    removeSubagent(subagentId: string): void;
+    /**
+     * Release all resources held by the fleet manager.
+     * Clears any pending manifest debounce timer and disposes the usage aggregator.
+     * Call this when the fleet manager is no longer needed (e.g. process shutdown).
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=ifleet-manager.d.ts.map

package/dist/coordination/ifleet-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ifleet-manager.d.ts","sourceRoot":"","sources":["../../src/coordination/ifleet-manager.ts"],"names":[],"mappings":"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"}

package/dist/coordination/in-memory-transport.d.ts

@@ -0,0 +1,12 @@
+import type { BridgeMessage, BridgeTransport } from '../types/agent-bridge.js';
+/**
+ * In-memory pub/sub transport for agent-to-agent messaging.
+ * Subscribers register by agentId and receive messages via callback.
+ */
+export declare class InMemoryBridgeTransport implements BridgeTransport {
+    private readonly subs;
+    send(msg: BridgeMessage, to: string): Promise<void>;
+    subscribe(agentId: string, handler: (msg: BridgeMessage) => void): () => void;
+    close(agentId: string): Promise<void>;
+}
+//# sourceMappingURL=in-memory-transport.d.ts.map

package/dist/coordination/in-memory-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-transport.d.ts","sourceRoot":"","sources":["../../src/coordination/in-memory-transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE/E;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,eAAe;IAC7D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwD;IAE7E,IAAI,CAAC,GAAG,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BlD;IAED,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI,CAI5E;IAED,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpC;CACF"}