@wrongstack/core 0.284.0 → 0.285.0

package/dist/coordination/delegate-tool.d.ts

@@ -0,0 +1,101 @@
+import type { EventBus } from '../kernel/events.js';
+import type { SubagentConfig } from '../types/multi-agent.js';
+import type { Tool } from '../types/tool.js';
+import type { Director } from './director.js';
+/**
+ * Opaque host interface so this factory doesn't have to depend on the
+ * CLI's `MultiAgentHost`. Any caller that exposes the same three
+ * methods can wire `delegate` — including test doubles.
+ */
+export interface DelegateHost {
+    /** True if a Director is already attached and running. */
+    isDirectorMode(): boolean;
+    /** Build (or return the cached) Director when director mode is on. */
+    ensureDirector(): Promise<Director | null>;
+    /**
+     * Force-promote a non-director session into director mode at runtime.
+     * Returns the Director, or null when promotion is impossible (e.g. a
+     * non-director coordinator has already spawned subagents in the
+     * legacy code path).
+     */
+    promoteToDirector(): Promise<Director | null>;
+    /**
+     * Optional: when promotion fails, return the human-readable reason.
+     * Used to render an actionable error to the calling model instead of
+     * the prior opaque "Director could not be activated" message.
+     * Implementations may return null when they don't track the reason.
+     */
+    getPromotionBlockReason?(): string | null;
+}
+export interface CreateDelegateToolOptions {
+    host: DelegateHost;
+    /**
+     * Roster used to resolve `role` strings into full `SubagentConfig`s.
+     * Typically `FLEET_ROSTER`. When omitted, `delegate({ role })` calls
+     * fail and only the explicit `name + provider + model` path works.
+     */
+    roster?: Record<string, SubagentConfig>;
+    /**
+     * Default await timeout in milliseconds. `delegate` blocks until the
+     * subagent's task resolves; without a cap, a stuck worker would hang
+     * the host indefinitely. Set generously (default: 4 hours) so the
+     * orchestrator can run multi-step refactors / monorepo audits
+     * without being killed for being slow — the orchestrator must
+     * decide per-call when a task needs to be cut short.
+     */
+    defaultTimeoutMs?: number | undefined;
+    /**
+     * Absolute directory under which per-subagent JSONL transcripts live —
+     * matches `MultiAgentHostOptions.sessionsRoot`. When set, the delegate
+     * tool reads the subagent's transcript on timeout / budget-exhaustion
+     * to extract partial output, so the host LLM gets *something* useful
+     * back instead of just an error.
+     */
+    sessionsRoot?: string | undefined;
+    /**
+     * The directorRunId used to namespace transcripts (typically the host
+     * session id). Combined with `sessionsRoot` to locate per-subagent
+     * JSONLs at `<sessionsRoot>/<runId>/<subagentId>.jsonl`.
+     */
+    directorRunId?: string | undefined;
+    /**
+     * Buffer subtracted from the caller's `timeoutMs` before passing it
+     * to the subagent. Gives the host a window to detect a subagent that
+     * has gone silent and surface a partial result rather than a generic
+     * timeout. Default: 60_000 ms (raised from 30s to give subagents
+     * more headroom before the host kills them).
+     */
+    subagentTimeoutBufferMs?: number | undefined;
+    /**
+     * Host EventBus. When supplied, `delegate` emits `delegate.started`
+     * (before it blocks on the subagent) and `delegate.completed` (once the
+     * subagent settles) so UIs / the Telegram bridge can render readable
+     * start/finish lines instead of inferring them from the truncated
+     * `tool.executed` JSON preview. Optional — emits are best-effort and a
+     * missing bus never affects delegation behaviour.
+     */
+    events?: EventBus | undefined;
+}
+/**
+ * `delegate` — the compact multi-agent tool exposed after Director mode is
+ * enabled. It bundles spawn + assign + await into a single call.
+ *
+ * The model never has to ask "are we in director mode?" — it just calls
+ * `delegate({ role, task })` and gets back a `TaskResult`. The cost of
+ * that ergonomic packaging is that `delegate` cannot be used for
+ * parallel work as-is; the model must fire multiple `delegate` calls in
+ * parallel through the provider's parallel-tool-call surface, or escalate
+ * to the explicit `spawn_subagent` + `assign_task` + `await_tasks` flow
+ * when it wants fan-out it controls itself.
+ */
+export declare function createDelegateTool(opts: CreateDelegateToolOptions): Tool;
+/**
+ * Per-kind orchestrator hint. Returned alongside the structured error
+ * so the calling model has a concrete next step instead of "task
+ * failed, good luck". Returns undefined for success / unknown kinds —
+ * the caller checks for presence before including in output.
+ */
+export declare function hintForKind(kind: string | undefined, retryable: boolean | undefined, backoffMs: number | undefined, partial?: {
+    lastAssistantText?: string | undefined;
+} | undefined): string | undefined;
+//# sourceMappingURL=delegate-tool.d.ts.map

package/dist/coordination/delegate-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-tool.d.ts","sourceRoot":"","sources":["../../src/coordination/delegate-tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAc,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAM9C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,cAAc,IAAI,OAAO,CAAC;IAC1B,sEAAsE;IACtE,cAAc,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC3C;;;;;OAKG;IACH,iBAAiB,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC9C;;;;;OAKG;IACH,uBAAuB,CAAC,IAAI,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,YAAY,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,IAAI,CAicxE;AAwBD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,SAAS,EAAE,OAAO,GAAG,SAAS,EAC9B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,CAAC,EAAE;IAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,SAAS,GAC/D,MAAM,GAAG,SAAS,CAkDpB"}

package/dist/coordination/dep-watcher-bridge.d.ts

@@ -0,0 +1,47 @@
+/**
+ * dep-watcher-bridge — Bridges the file-watcher plugin's custom events
+ * to the dependency watcher → mailbox pipeline.
+ *
+ * The file-watcher plugin emits `file-watcher:changed` custom events
+ * when files change. This module subscribes to those events, filters
+ * for dependency manifests (package.json, go.mod, etc.), and posts
+ * assign messages to the inter-agent mailbox for tech-stack audit.
+ *
+ * Returns a dispose function that unsubscribes from the event bus.
+ *
+ * @module dep-watcher-bridge
+ */
+import type { EventBus } from '../kernel/events.js';
+import type { Mailbox } from './mailbox-types.js';
+export interface DepWatcherBridgeOptions {
+    /** The event bus to subscribe to (same bus the file-watcher plugin emits on). */
+    events: EventBus;
+    /** The mailbox instance where dep-change notifications will be posted. */
+    mailbox: Mailbox;
+    /** Absolute project root — used to build watch paths and match file patterns. */
+    projectRoot: string;
+    /** Agent id the tech-stack audit tasks should target. Default: 'tech-stack'. */
+    targetAgent?: string | undefined;
+    /** Agent id of the watcher/sender. Default: 'dep-watcher'. */
+    watcherAgentId?: string | undefined;
+    /** Debounce window in ms. Default: 3000 (3 seconds). */
+    debounceMs?: number | undefined;
+}
+/**
+ * Wire the file-watcher's `file-watcher:changed` events into the
+ * dependency watcher → mailbox pipeline.
+ *
+ * Returns a dispose function. Call it to unsubscribe when the
+ * session ends or the watcher is no longer needed.
+ *
+ * Usage:
+ *   const dispose = attachDepWatcherBridge({
+ *     events: ctx.events,
+ *     mailbox: new DefaultMailbox(sessionDir),
+ *     projectRoot: ctx.projectRoot,
+ *   });
+ *   // ... session runs ...
+ *   dispose(); // clean up on exit
+ */
+export declare function attachDepWatcherBridge(opts: DepWatcherBridgeOptions): () => void;
+//# sourceMappingURL=dep-watcher-bridge.d.ts.map

package/dist/coordination/dep-watcher-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dep-watcher-bridge.d.ts","sourceRoot":"","sources":["../../src/coordination/dep-watcher-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGlD,MAAM,WAAW,uBAAuB;IACtC,iFAAiF;IACjF,MAAM,EAAE,QAAQ,CAAC;IACjB,0EAA0E;IAC1E,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,uBAAuB,GAC5B,MAAM,IAAI,CA4CZ"}

package/dist/coordination/dep-watcher.d.ts

@@ -0,0 +1,74 @@
+/**
+ * dep-watcher — File-change → Mailbox bridge for dependency monitoring.
+ *
+ * Watches dependency manifest files (package.json, go.mod, Cargo.toml, etc.)
+ * and when they change (create/update), posts a message to the inter-agent
+ * mailbox. A tech-stack analysis agent can then pick up the message and
+ * run a full tech-stack validation, feeding results back to the coding LLM.
+ *
+ * This module is a *config factory*, not a watcher itself. It produces
+ * configuration that the file-watcher plugin (`watch_start`) can consume,
+ * plus a callback that posts to a Mailbox instance.
+ *
+ * Usage:
+ *   const cfg = makeDependencyWatcherConfig({
+ *     projectRoot: '/path/to/project',
+ *     mailbox,
+ *     targetAgent: 'tech-stack-agent',
+ *   });
+ *   // cfg.watchPaths   → pass to watch_start
+ *   // cfg.onChange     → call on file-watcher:changed events
+ *
+ * @module dep-watcher
+ */
+import type { Mailbox } from './mailbox-types.js';
+/**
+ * Files that declare project dependencies. When any of these change
+ * (create/update), a mailbox message triggers a tech-stack audit.
+ */
+export declare const DEPENDENCY_FILE_PATTERNS: ReadonlyArray<string>;
+export interface DepWatchEntry {
+    /** Relative path from project root that changed. */
+    path: string;
+    /** Event type from the file watcher: 'change', 'add', 'delete' (rare). */
+    event: string;
+    /** ISO8601 timestamp of when the change was detected. */
+    timestamp: string;
+}
+export interface DependencyWatcherConfig {
+    /** Paths to pass to `watch_start` — the project-root-relative dependency files. */
+    watchPaths: string[];
+    /** Callback to invoke when a dependency file changes. Posts to mailbox. */
+    onChange: (entry: DepWatchEntry) => Promise<void>;
+    /** Debounce window in ms — multiple changes to the same file within this window are collapsed. */
+    debounceMs: number;
+    /** Cancel all in-flight debounce timers. Call when the file watcher is
+     *  stopped (session end / project switch) so pending setTimeouts — each
+     *  holding a closure over the mailbox + entry — don't leak. */
+    dispose: () => void;
+}
+export interface DependencyWatcherOptions {
+    /** Absolute path to the project root. */
+    projectRoot: string;
+    /** The mailbox instance where messages will be posted. */
+    mailbox: Mailbox;
+    /** Agent id that should receive the tech-stack audit task. */
+    targetAgent?: string | undefined;
+    /** Agent id of the watcher (sender). */
+    watcherAgentId?: string | undefined;
+    /** Debounce window in ms. Default: 3000 (3 seconds). */
+    debounceMs?: number | undefined;
+    /** Only watch these specific patterns. Defaults to DEPENDENCY_FILE_PATTERNS. */
+    patterns?: string[] | undefined;
+}
+/**
+ * Build a dependency watcher configuration. The returned `watchPaths` can be
+ * passed directly to the `watch_start` tool, and `onChange` should be wired
+ * to the `file-watcher:changed` custom event.
+ *
+ * When a dependency file changes, `onChange` posts a high-priority `assign`
+ * message to the mailbox targeting the tech-stack agent, with the changed
+ * file path and event type in the body.
+ */
+export declare function makeDependencyWatcherConfig(opts: DependencyWatcherOptions): DependencyWatcherConfig;
+//# sourceMappingURL=dep-watcher.d.ts.map

package/dist/coordination/dep-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dep-watcher.d.ts","sourceRoot":"","sources":["../../src/coordination/dep-watcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAIlD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,aAAa,CAAC,MAAM,CAmC1D,CAAC;AAIF,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,mFAAmF;IACnF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC;IACnB;;mEAE+D;IAC/D,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,wCAAwC;IACxC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACjC;AAID;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,wBAAwB,GAC7B,uBAAuB,CAiHzB"}

package/dist/coordination/director/director-errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Director-specific error types. Extracted to keep the Director class
+ * focused on orchestration logic.
+ */
+export declare class FleetSpawnBudgetError extends Error {
+    readonly kind: 'max_spawns' | 'max_spawn_depth';
+    readonly limit: number;
+    readonly observed: number;
+    constructor(kind: 'max_spawns' | 'max_spawn_depth', limit: number, observed: number, message?: string | undefined);
+}
+export declare class FleetCostCapError extends Error {
+    readonly kind: 'max_cost_usd';
+    readonly limit: number;
+    readonly observed: number;
+    constructor(limit: number, observed: number);
+}
+export declare class FleetTokenCapError extends Error {
+    readonly kind: 'max_tokens';
+    readonly limit: number;
+    readonly observed: number;
+    constructor(limit: number, observed: number);
+}
+export declare class FleetContextOverflowError extends Error {
+    readonly kind: 'max_context_load';
+    readonly limit: number;
+    readonly observed: number;
+    constructor(limit: number, observed: number);
+}
+//# sourceMappingURL=director-errors.d.ts.map

package/dist/coordination/director/director-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"director-errors.d.ts","sourceRoot":"","sources":["../../../src/coordination/director/director-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,iBAAiB,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,YACE,IAAI,EAAE,YAAY,GAAG,iBAAiB,EACtC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,EAW7B;CACF;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,YAAY,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAQ1C;CACF;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,YAAY,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAQ1C;CACF;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,YAAY,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAQ1C;CACF"}

package/dist/coordination/director-construction.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Director construction helpers.
+ *
+ * The `Director` constructor was historically a single 300+ line function
+ * that interleaved field assignments with two pieces of event-listener
+ * wiring: the `task.completed` listener on the coordinator (which mirrors
+ * completions into the in-memory wait table, the on-disk checkpoint, and
+ * the session JSONL event stream) and the `budget.threshold_reached`
+ * filter on the FleetBus (which implements the heartbeat-driven timeout
+ * policy and the per-kind auto-extension logic).
+ *
+ * Both wirings were inlined because they close over a lot of Director
+ * private state (`completed`, `taskWaiters`, `taskDescriptions`,
+ * `appendSessionEvent`, `scheduleManifest`, `recordExtension`,
+ * `maxBudgetExtensions`, `maxFleetCostUsd`, etc.). Pulling them out
+ * without losing the closures requires a narrow `DirectorInternals`
+ * shape — exactly what this module exposes.
+ *
+ * The constructor itself stays a member-initializer; the helpers below
+ * are called *during* construction, after the relevant fields are
+ * populated. Each helper ends with `coordinator.on(...)` /
+ * `fleet.filter(...)` registration so the listener is wired exactly
+ * once, at construction time.
+ */
+import type { TaskResult, TaskSpec } from '../types/multi-agent.js';
+/** Cap on the in-memory `completed` map. Trimmed oldest-first when exceeded. */
+export declare const MAX_COMPLETED = 10000;
+/** Narrow shape the wiring helpers need from a partially-constructed Director.
+ *  The helpers accept a `Director` instance (structural typing — the class
+ *  exposes every field this interface requires), so the constructor can pass
+ *  `this` directly without an explicit cast.
+ *
+ *  Note: Private/protected members cannot be picked via Pick<> because keyof
+ *  only returns public keys. We define the interface explicitly rather than
+ *  deriving from Director to include private fields the wiring code needs. */
+export interface DirectorInternals {
+    id: string;
+    directorRunId: string;
+    completed: Map<string, import('../types/multi-agent.js').TaskResult>;
+    taskWaiters: Map<string, {
+        promise: Promise<import('../types/multi-agent.js').TaskResult>;
+        resolve: (r: import('../types/multi-agent.js').TaskResult) => void;
+    }>;
+    taskDescriptions: Map<string, string>;
+    stateCheckpoint: import('../storage/director-state.js').DirectorStateCheckpoint | null;
+    usage: import('./fleet-bus.js').FleetUsageAggregator;
+    fleetManager: import('./fleet-manager.js').FleetManager | undefined;
+    fleet: import('./fleet-bus.js').FleetBus;
+    coordinator: import('./icoordinator.js').ICoordinator;
+    maxBudgetExtensions: number;
+    maxFleetCostUsd: number;
+    recordExtension: (subagentId: string, taskId: string | undefined, kind: string, newLimit: number) => void;
+    appendSessionEvent: (event: Parameters<import('../types/session.js').SessionWriter['append']>[0]) => Promise<void>;
+    scheduleManifest: () => void;
+    brain: import('./brain.js').BrainArbiter | undefined;
+}
+export { TIMEOUT_PREEMPT_FRACTION } from './subagent-budget.js';
+/**
+ * Wire the coordinator's `task.completed` event into the Director's
+ * in-memory wait table, the on-disk state checkpoint, and the session
+ * JSONL event stream.
+ *
+ * Mirrors coordinator completion events into:
+ * - `d.completed` (capped at `Director.MAX_COMPLETED`, oldest-first trim)
+ * - `d.taskWaiters` (resolve and clear the matching waiter)
+ * - `d.stateCheckpoint.recordTaskStatus(...)` + `setUsage(...)`
+ * - session event stream via `d.appendSessionEvent(...)`
+ * - fleet manifest via `d.fleetManager?.flushManifest()` or `d.scheduleManifest()`
+ *
+ * Returns the listener so the Director can call `coordinator.off(...)`
+ * during `shutdown()`.
+ */
+export declare function wireTaskCompletedListener(d: DirectorInternals): (payload: {
+    task: TaskSpec;
+    result: TaskResult;
+}) => void;
+/**
+ * Wire the FleetBus's `budget.threshold_reached` filter with the
+ * Director's auto-extend/deny policy. Implements:
+ *
+ * - Heartbeat-driven timeout policy: while a subagent keeps executing
+ *   tools it never dies on time; once it stops making progress between
+ *   grants, deny. Wall-clock time alone is never a reliable "stuck" signal.
+ * - Per-kind auto-extension with `maxBudgetExtensions` cap.
+ * - Brain-decision routing when a brain arbiter is configured.
+ * - Collab-subagent passthrough (BugHunter / RefactorPlanner / Critic
+ *   own their own budget routing via the CollabSession).
+ */
+export declare function wireBudgetHandler(d: DirectorInternals): void;
+//# sourceMappingURL=director-construction.d.ts.map

package/dist/coordination/director-construction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"director-construction.d.ts","sourceRoot":"","sources":["../../src/coordination/director-construction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEpE,gFAAgF;AAChF,eAAO,MAAM,aAAa,QAAS,CAAC;AAEpC;;;;;;;8EAO8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,yBAAyB,EAAE,UAAU,CAAC,CAAC;IACrE,WAAW,EAAE,GAAG,CACd,MAAM,EACN;QAAE,OAAO,EAAE,OAAO,CAAC,OAAO,yBAAyB,EAAE,UAAU,CAAC,CAAC;QAAC,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,yBAAyB,EAAE,UAAU,KAAK,IAAI,CAAA;KAAE,CACvI,CAAC;IACF,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,EAAE,OAAO,8BAA8B,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACvF,KAAK,EAAE,OAAO,gBAAgB,EAAE,oBAAoB,CAAC;IACrD,YAAY,EAAE,OAAO,oBAAoB,EAAE,YAAY,GAAG,SAAS,CAAC;IACpE,KAAK,EAAE,OAAO,gBAAgB,EAAE,QAAQ,CAAC;IACzC,WAAW,EAAE,OAAO,mBAAmB,EAAE,YAAY,CAAC;IACtD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1G,kBAAkB,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,qBAAqB,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnH,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,KAAK,EAAE,OAAO,YAAY,EAAE,YAAY,GAAG,SAAS,CAAC;CACtD;AAyBD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAShE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,iBAAiB,GAAG,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,KAAK,IAAI,CAiEzH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,CA2J5D"}

package/dist/coordination/director-prompts.d.ts

@@ -0,0 +1,119 @@
+/**
+ * System-prompt composition helpers for the Director ecosystem.
+ *
+ * Two callers need composed prompts:
+ *
+ *   1. The **leader** (the director's own Agent) — needs a preamble that
+ *      explains the fleet protocol: when to spawn, when to await, how to
+ *      roll up, and the eight orchestration tools it owns.
+ *
+ *   2. Each **subagent** — needs a baseline that explains it has a parent
+ *      it can call via the bridge, a role-specific block, the task brief,
+ *      and finally any per-spawn `systemPromptOverride` from `SubagentConfig`.
+ *
+ * Both composers are pure functions: feed them parts, they return a string.
+ * No I/O, no side effects, no implicit defaults beyond the ones exported
+ * here. Callers (CLI multi-agent factory, Director itself) decide which
+ * parts to fill in — that keeps the composition seam visible and testable.
+ */
+/**
+ * Default fleet-protocol preamble injected at the **front** of the
+ * director-agent's system prompt.
+ */
+export declare const DEFAULT_DIRECTOR_PREAMBLE: string;
+/**
+ * Default baseline prepended to every subagent's system prompt.
+ */
+export declare const DEFAULT_SUBAGENT_BASELINE: string;
+/** Parts the leader-prompt composer accepts. All optional. */
+export interface DirectorPromptParts {
+    /** The user's existing leader system prompt — typically what was passed
+     *  via `MultiAgentConfig.leaderSystemPrompt`. */
+    basePrompt?: string | undefined;
+    /** Override the built-in fleet preamble. Pass empty string to suppress. */
+    directorPreamble?: string | undefined;
+    /** Optional roster summary block — a short list of pre-configured roles
+     *  the director can spawn (e.g. "researcher, coder, reviewer"). Helps
+     *  small models discover the available shapes without scanning tools. */
+    rosterSummary?: string | undefined;
+}
+/**
+ * Compose the leader/director's system prompt. Order:
+ *   1. Director preamble (fleet protocol)
+ *   2. Roster summary (optional, when provided)
+ *   3. User base prompt (the per-project leader prompt)
+ *
+ * Sections are separated by a blank line. Empty parts are skipped so the
+ * output never contains stray blank-line runs.
+ */
+export declare function composeDirectorPrompt(parts?: DirectorPromptParts): string;
+/** Parts the subagent-prompt composer accepts. Layered from generic to
+ *  specific; later layers override earlier ones when they conflict. */
+export interface SubagentPromptParts {
+    /** Base persona/identity for *every* subagent. Defaults to the bridge
+     *  contract baseline. Pass empty string to suppress. */
+    baseline?: string | undefined;
+    /** Role-specific block, e.g. "You are a code reviewer. Focus on…". */
+    role?: string | undefined;
+    /** Task brief — usually the same string the runner passes as user input,
+     *  but exposed here in case the factory wants it duplicated in the
+     *  system prompt for reinforcement. */
+    task?: string | undefined;
+    /**
+     * Absolute path to a shared scratchpad directory the whole fleet can
+     * read/write. When set, the composer adds a "Shared notes" block that
+     * tells the subagent where to drop findings and where to look for
+     * sibling output. This is the cheap fleet-coordination channel —
+     * agents don't need each other's transcripts, just each other's
+     * conclusions. Falls between `task` and `override` so the override
+     * can still narrow or replace it.
+     */
+    sharedScratchpad?: string | undefined;
+    /**
+     * Optional skill body content injected into the subagent's system prompt.
+     * Use this to provide domain-specific knowledge (SKILL.md bodies) to
+     * subagents that need it. Placed after `sharedScratchpad` and before
+     * `override` so the override can still narrow or replace it.
+     */
+    skills?: string | undefined;
+    /** Final per-spawn override from `SubagentConfig.systemPromptOverride`.
+     *  Added last so it wins on conflict — that's by design: the spawn site
+     *  knows the most about what this specific subagent should do. */
+    override?: string | undefined;
+}
+/**
+ * Compose a subagent's system prompt. Order:
+ *   1. Baseline (bridge contract)
+ *   2. Role
+ *   3. Task brief
+ *   4. Shared scratchpad
+ *   5. Skills (domain knowledge from SKILL.md)
+ *   6. Per-spawn override
+ *
+ * Same blank-line-separated joining as the director composer.
+ *
+ * Layering rationale: the baseline never needs to change between
+ * subagents; the role is the "what kind of worker is this"; the task is
+ * the "what should you do *now*"; skills provide reusable domain knowledge
+ * (e.g. bug-hunting patterns, security scanning rules); the override is
+ * the spawn-site escape hatch ("…and respond only in JSON"). Putting
+ * override last means it never gets squashed by something earlier in the chain.
+ */
+export declare function composeSubagentPrompt(parts?: SubagentPromptParts): string;
+/**
+ * Render a short bullet list summarising a roster — useful for stuffing
+ * into `composeDirectorPrompt({ rosterSummary })` so the director model
+ * can see available roles without scanning tool descriptions.
+ *
+ * Each entry: `- <role-id>: <name>[ (provider/model)] — <prompt-headline>`
+ * The prompt headline is the first non-empty line of `config.prompt`,
+ * truncated to 80 chars. Skipped entirely when the role has no prompt.
+ */
+export declare function rosterSummaryFromConfigs(roster: Record<string, {
+    name: string;
+    provider?: string | undefined;
+    model?: string | undefined;
+    prompt?: string | undefined;
+    role?: string | undefined;
+}>): string;
+//# sourceMappingURL=director-prompts.d.ts.map

package/dist/coordination/director-prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"director-prompts.d.ts","sourceRoot":"","sources":["../../src/coordination/director-prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;GAGG;AACH,eAAO,MAAM,yBAAyB,QAErC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,yBAAyB,QAErC,CAAC;AAEF,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC;qDACiD;IACjD,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;6EAEyE;IACzE,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,GAAE,mBAAwB,GAAG,MAAM,CAW7E;AAED;uEACuE;AACvE,MAAM,WAAW,mBAAmB;IAClC;4DACwD;IACxD,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;2CAEuC;IACvC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B;;sEAEkE;IAClE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,GAAE,mBAAwB,GAAG,MAAM,CA4B7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CACZ,MAAM,EACN;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CACpI,GACA,MAAM,CAWR"}

package/dist/coordination/director-session.d.ts

@@ -0,0 +1,68 @@
+import type { SessionStore, SessionWriter } from '../types/session.js';
+/**
+ * Per-subagent session factory.
+ *
+ * Director runs produce many parallel transcripts — one per spawned
+ * subagent — and we want them all rooted under the same director-run
+ * directory so a future `wstack replay <runId>` can rehydrate the whole
+ * fleet from a single tree.
+ *
+ * The factory builds (or accepts) a `SessionStore` whose `dir` points at
+ * `<sessionsRoot>/<directorRunId>/`, and returns a small `create()`
+ * function that the orchestration layer calls per-spawn. Each call
+ * yields a fresh `SessionWriter` whose JSONL file lives in that
+ * directory, named by either the caller-supplied `subagentId` (preferred,
+ * so the file name is human-readable) or a derived id.
+ *
+ * **Why a thin factory instead of plumbing options through every spawn
+ * site?** Because the director is the only caller that needs this
+ * isolation pattern, and shoving `sessionStore` options into
+ * `SubagentConfig` would leak storage details into a config shape that
+ * agents and the coordinator have no business knowing about.
+ */
+export interface DirectorSessionFactoryOptions {
+    /**
+     * Either a parent directory where `<directorRunId>/` will be created,
+     * or a pre-built `SessionStore` whose `dir` already points at the
+     * director run directory. Tests pass an in-memory store for isolation;
+     * production code passes the path under `~/.wrongstack/sessions/`.
+     */
+    store?: SessionStore | undefined;
+    sessionsRoot?: string | undefined;
+    /**
+     * Director run id — namespaces all subagent JSONLs under one folder.
+     * Defaults to a timestamped id; supplied explicitly when resuming a
+     * prior fleet manifest.
+     */
+    directorRunId?: string | undefined;
+    /**
+     * Session-level trace ID for correlating subagent storage events with
+     * the parent session's trace in observability pipelines.
+     */
+    traceId?: string | undefined;
+}
+export interface DirectorSessionFactory {
+    /** Absolute directory where this director run's transcripts live. */
+    readonly dir: string;
+    /** The director run id used to namespace the directory. */
+    readonly directorRunId: string;
+    /**
+     * Create a fresh `SessionWriter` for the named subagent. Each
+     * subagent gets its own JSONL file. The writer's `id` matches the
+     * supplied `subagentId` so disk paths line up with in-memory ids.
+     */
+    createSubagentSession(args: {
+        subagentId: string;
+        provider?: string | undefined;
+        model?: string | undefined;
+        title?: string | undefined;
+    }): Promise<SessionWriter>;
+}
+/**
+ * Build a `DirectorSessionFactory`. Pass either a pre-configured
+ * `SessionStore` (tests) or a `sessionsRoot` path (production). When
+ * neither is supplied the factory throws — there's no sane default for
+ * "where do these JSONLs live".
+ */
+export declare function makeDirectorSessionFactory(opts: DirectorSessionFactoryOptions): DirectorSessionFactory;
+//# sourceMappingURL=director-session.d.ts.map

package/dist/coordination/director-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"director-session.d.ts","sourceRoot":"","sources":["../../src/coordination/director-session.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,qBAAqB,CAAC,IAAI,EAAE;QAC1B,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC9B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC5B,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,6BAA6B,GAClC,sBAAsB,CAyCxB"}

package/dist/coordination/director-tools.d.ts

@@ -0,0 +1,65 @@
+import type { SubagentConfig } from '../types/multi-agent.js';
+import type { Tool } from '../types/tool.js';
+import { type Director } from './director.js';
+export declare function makeSpawnTool(director: Director, roster?: Record<string, SubagentConfig>): Tool;
+export declare function makeQualityGateTool(director: Director, roster?: Record<string, SubagentConfig>): Tool;
+export declare function makeAssignTool(director: Director): Tool;
+export declare function makeKanbanQueueTool(director: Director, roster?: Record<string, SubagentConfig>): Tool;
+export declare function makeAwaitTasksTool(director: Director): Tool;
+export declare function makeAskTool(director: Director): Tool;
+/**
+ * Retrieve a previously stored `ask_subagent` answer by its store key.
+ * The key was returned as `_answerKey` in the ask_subagent response.
+ * Use this only for large responses that were stored out-of-context.
+ */
+export declare function makeAskResultTool(director: Director): Tool;
+export declare function makeRollUpTool(director: Director): Tool;
+export declare function makeTerminateTool(director: Director): Tool;
+export declare function makeTerminateAllTool(director: Director): Tool;
+/**
+ * Unified fleet observation tool — consolidates the former fleet_status,
+ * fleet_usage, fleet_session, and fleet_health tools under a single `action`
+ * parameter (status, usage, health, session).
+ *
+ * These four are all read-only fleet queries; merging them into one tool
+ * reduces tool-schema token overhead (4 × ~150 tokens → 1 × ~250 tokens)
+ * and eliminates model confusion when choosing between similar tools.
+ */
+export declare function makeFleetTool(director: Director): Tool;
+/**
+ * Collaborative debugging session: BugHunter, RefactorPlanner, and Critic
+ * run in parallel on the same target files, with findings flowing through
+ * the FleetBus (bug.found → refactor.plan → critic.evaluation).
+ *
+ * Returns a structured CollabDebugReport containing all bug findings,
+ * refactor plans, critic evaluations, and an overall verdict.
+ */
+export declare function makeCollabDebugTool(director: Director): Tool;
+/**
+ * Tool for subagents to emit structured events on the FleetBus.
+ * Custom event types are extensible; known collab events are schema-validated
+ * and restricted to their owning role before the Director routes them.
+ * Common event types in collaborative sessions:
+ *   bug.found        — BugHunter emits per-finding
+ *   refactor.plan    — RefactorPlanner emits per-plan
+ *   critic.evaluation — Critic emits per-evaluation
+ *
+ * The payload structure is event-type-specific. Use null for empty payloads.
+ */
+export declare function makeFleetEmitTool(director: Director): Tool;
+/**
+ * Signal that the director's work is satisfied and the fleet should wind down.
+ *
+ * Once called:
+ * - `spawn_subagent` throws — no new subagents can be created
+ * - `assign_task` synthesizes an immediate `aborted_by_parent` completion
+ *   for any queued task (callers awaiting those tasks unblock immediately)
+ * - Running subagents are NOT killed — they finish naturally; no new
+ *   tasks are dispatched to them
+ *
+ * Use this when you are satisfied with the results and want the fleet to
+ * stop spawning without forcibly stopping in-flight work. Call
+ * `terminate_subagent` separately for any subagent you need to stop immediately.
+ */
+export declare function makeWorkCompleteTool(director: Director): Tool;
+//# sourceMappingURL=director-tools.d.ts.map

package/dist/coordination/director-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"director-tools.d.ts","sourceRoot":"","sources":["../../src/coordination/director-tools.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,yBAAyB,CAAC;AACpF,OAAO,KAAK,EAAc,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAIzD,OAAO,EACL,KAAK,QAAQ,EAId,MAAM,eAAe,CAAC;AAevB,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,IAAI,CAuJ/F;AA+CD,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,QAAQ,EAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GACtC,IAAI,CA+LN;AA8SD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CA4CvD;AAwBD,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,QAAQ,EAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GACtC,IAAI,CA+PN;AAgMD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CA0D3D;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CA6CpD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CA+B1D;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CA6BvD;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAmB1D;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAqB7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAoHtD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CA+E5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAwC1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAiB7D"}