@wrongstack/core 0.1.8 → 0.1.10

package/dist/coordination/index.d.ts

@@ -0,0 +1,694 @@
+import { M as MultiAgentConfig, k as SubagentRunner, g as SubagentConfig, m as TaskSpec, l as TaskResult, d as CoordinatorStatus, e as MultiAgentCoordinator, f as SpawnResult, o as BridgeMessage, A as AgentBridge } from '../multi-agent-fmkRHtof.js';
+export { B as BudgetExceededError, a as BudgetKind, b as BudgetLimits, c as BudgetUsage, S as SubagentBudget } from '../multi-agent-fmkRHtof.js';
+import { u as Tool, q as SessionWriter, o as SessionStore } from '../context-BmM2xGUZ.js';
+import { I as InMemoryAgentBridge } from '../agent-bridge-6KPqsFx6.js';
+export { a as InMemoryBridgeTransport, c as createMessage } from '../agent-bridge-6KPqsFx6.js';
+import { E as EventBus } from '../events-BMNaEFZl.js';
+import { EventEmitter } from 'node:events';
+import { A as Agent, n as AgentInput } from '../plugin-DJk6LL8B.js';
+import '../observability-BhnVLBLS.js';
+import '../renderer-rk_1Swwc.js';
+import '../secret-scrubber-CicHLN4G.js';
+import '../config-BU9f_5yH.js';
+import '../models-registry-Y2xbog0E.js';
+import '../logger-BMQgxvdy.js';
+
+/**
+ * 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;
+}
+
+/**
+ * Director — high-level orchestrator that owns a `MultiAgentCoordinator`,
+ * a `FleetBus`, and a `FleetUsageAggregator`. Exposes a small imperative
+ * API (`spawn`, `assign`, `awaitTasks`, `terminate`, `status`, `usage`)
+ * that's easy to test, and a `tools()` factory that wraps the same API
+ * as agent-callable `Tool`s so an LLM can drive the orchestration.
+ *
+ * This class is intentionally *not* an `Agent`. It's a coordinator +
+ * observability surface. To make it LLM-driven, construct an Agent
+ * with `director.tools()` registered. That keeps the construction
+ * symmetric with how other agents are built and avoids smuggling a
+ * heavy LLM dependency into core just for the director path.
+ */
+interface DirectorOptions {
+    config: MultiAgentConfig;
+    runner?: SubagentRunner;
+    /**
+     * When set, the director writes a `fleet.json` manifest to this path
+     * recording every spawned subagent (id, provider, model, role, task
+     * ids). Used by `wstack replay <runId>` to rehydrate a fleet. Pass an
+     * absolute file path — the directory must already exist (the
+     * director-session factory creates it when used together).
+     */
+    manifestPath?: string;
+    /**
+     * Optional roster used by `leaderSystemPrompt()` to render a roles
+     * summary into the leader's preamble. Same shape as the roster passed
+     * to `tools()` — typically the same value.
+     */
+    roster?: Record<string, SubagentConfig>;
+    /**
+     * Override the built-in fleet preamble (see `DEFAULT_DIRECTOR_PREAMBLE`).
+     * Pass an empty string to suppress the preamble entirely.
+     */
+    directorPreamble?: string;
+    /**
+     * Override the built-in subagent baseline (see
+     * `DEFAULT_SUBAGENT_BASELINE`). Pass an empty string to suppress.
+     */
+    subagentBaseline?: string;
+    /**
+     * Absolute path to a directory the fleet can use as a shared scratchpad
+     * (read + write by every subagent). When set, the director creates it on
+     * construction and `subagentSystemPrompt()` automatically injects a
+     * "Shared notes" block telling subagents where to drop their findings.
+     * This is the cheap fleet-coordination channel — agents don't need each
+     * other's transcripts, just each other's conclusions.
+     *
+     * Convention: under a fleet run rooted at `<sessionsRoot>/<runId>/`,
+     * pass `<sessionsRoot>/<runId>/shared/` here.
+     */
+    sharedScratchpadPath?: string;
+    /**
+     * Maximum number of spawns this director can perform across its
+     * lifetime. Default: unlimited. Acts as a hard fleet-wide cost cap —
+     * a runaway leader that keeps spawning workers gets cut off cleanly
+     * instead of burning provider tokens until the user kills the
+     * process. The N+1-th spawn call rejects with a `DirectorBudgetError`.
+     */
+    maxSpawns?: number;
+    /**
+     * Maximum nesting depth for spawns. The director constructed by the
+     * user is at depth `spawnDepth` (default 0); any subagent that itself
+     * acts as a director would construct its own `Director` with
+     * `spawnDepth: parent.spawnDepth + 1`. When `spawnDepth >= maxSpawnDepth`,
+     * `spawn()` rejects. Default: 2 (root director can spawn workers; a
+     * worker that becomes a sub-director cannot itself spawn further).
+     * This stops infinite recursive director chains from a hostile or
+     * confused prompt.
+     */
+    maxSpawnDepth?: number;
+    /**
+     * Current spawn-chain depth for this director instance. Defaults to 0.
+     * A nested director should pass `parent.spawnDepth + 1`. Together with
+     * `maxSpawnDepth` this bounds the chain.
+     */
+    spawnDepth?: number;
+}
+/**
+ * Thrown by `Director.spawn()` when a configured spawn cap (`maxSpawns`,
+ * `maxSpawnDepth`) is hit. Distinct error class so callers — including
+ * the `spawn_subagent` tool surface — can recognize the budget case and
+ * report it cleanly instead of treating it like an unexpected failure.
+ */
+declare class DirectorBudgetError 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);
+}
+declare class Director {
+    readonly id: string;
+    readonly fleet: FleetBus;
+    readonly usage: FleetUsageAggregator;
+    /**
+     * Director-side bridge endpoint. Subagents are wired to the same
+     * in-memory transport so the director can `ask()` them synchronously
+     * and they can `send()` progress back. Exposed so external code (e.g.
+     * the TUI) can subscribe to inbound messages.
+     */
+    readonly bridge: InMemoryAgentBridge;
+    private readonly transport;
+    private readonly coordinator;
+    /** Resolves with the matching `TaskResult` the first time the
+     *  coordinator emits `task.completed` for a given task id. Each entry
+     *  is created lazily on first poll/await and cleared once consumed. */
+    private readonly taskWaiters;
+    /** Cache of completed results in case the consumer asks AFTER the
+     *  coordinator already fired the event — `awaitTasks(['t-1'])` after
+     *  t-1 finished should resolve immediately, not hang. */
+    private readonly completed;
+    /** Per-subagent provider/model metadata, captured at spawn time so the
+     *  FleetUsageAggregator's metaLookup can surface readable rows. */
+    private readonly subagentMeta;
+    private readonly priceLookups;
+    /** Bridge endpoints we created per subagent (so we can `stop()` them
+     *  on shutdown and free transport subscriptions). */
+    private readonly subagentBridges;
+    /** Tracks per-spawn config + assigned task ids for manifest writing. */
+    private readonly manifestEntries;
+    private readonly manifestPath?;
+    private readonly roster?;
+    private readonly directorPreamble;
+    private readonly subagentBaseline;
+    /** Absolute path to the fleet's shared scratchpad directory, or null
+     *  when none was configured. Exposed as a readonly getter for callers
+     *  that need to surface the path to the user (e.g. the CLI logging
+     *  the location after `--director` boots). */
+    readonly sharedScratchpadPath: string | null;
+    /** Spawn cap (lifetime total). Infinity means unlimited. */
+    readonly maxSpawns: number;
+    /** Nesting cap. The N-th director in a chain has `spawnDepth = N-1`. */
+    readonly maxSpawnDepth: number;
+    /** This director's position in a director chain. Root director = 0. */
+    readonly spawnDepth: number;
+    /** Live spawn counter for `maxSpawns` enforcement. */
+    private spawnCount;
+    constructor(opts: DirectorOptions);
+    /**
+     * Spawn a subagent. Identical to the coordinator's `spawn()` but
+     * captures provider/model metadata for the usage aggregator and
+     * lets the FleetBus attach to the runner's EventBus when the task
+     * actually runs (see `attachSubagentBus`).
+     *
+     * Caller-supplied `priceLookup` is optional but recommended — without
+     * it the `cost` column in `usage.snapshot()` stays at 0.
+     */
+    spawn(config: SubagentConfig, priceLookup?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    }): Promise<string>;
+    /**
+     * Synchronously ask a subagent something via the bridge. Sends a
+     * `task` message addressed to the subagent and awaits a matching
+     * reply (matched by message id). Subagent runners that handle these
+     * requests subscribe to `ctx.bridge` and reply with a message whose
+     * `id` equals the incoming request's id (see `InMemoryAgentBridge`'s
+     * `request<T>` implementation).
+     *
+     * Returns the response payload directly (the bridge wrapper is
+     * unwrapped for ergonomics). Times out after `timeoutMs` (default
+     * matches the bridge's own default of 30s) — surface those rejections
+     * to the caller as actionable errors instead of letting tools hang.
+     */
+    ask<T = unknown>(subagentId: string, payload: unknown, timeoutMs?: number): Promise<T>;
+    /**
+     * Read completed task results and format them as a structured text
+     * block the director's LLM can paste into its own context. The
+     * Director keeps every completed `TaskResult` in `completed` so this
+     * is a pure read — no bridge round-trip, cheap to call.
+     *
+     * The returned string is intentionally markdown-flavored: headers per
+     * subagent, a one-line meta row (iter / tools / ms), and the task's
+     * result text. Pass `style: 'json'` for a programmatic shape instead
+     * (useful when the director model is doing structured-output work).
+     */
+    rollUp(taskIds: string[], style?: 'markdown' | 'json'): string;
+    /**
+     * Write the fleet manifest to `manifestPath`. Returns the path written
+     * or null when no path was configured. Captures every spawn + its
+     * assigned tasks — paired with per-subagent JSONLs, this is enough to
+     * replay an entire director run.
+     */
+    writeManifest(): Promise<string | null>;
+    /**
+     * Tear down the director: stop every subagent, close every bridge
+     * endpoint, and (when configured) write the final manifest. Idempotent
+     * — calling shutdown twice is a no-op on the second invocation.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Hand a task to the coordinator. Returns the assigned task id so
+     * callers can wait on it via `awaitTasks([id])`. The coordinator's
+     * concurrency limit applies — the task may queue before running.
+     */
+    assign(task: TaskSpec): Promise<string>;
+    /**
+     * Block until every task id resolves. Returns results in the same
+     * order as the input. If any task hasn't completed by the time this
+     * is called, the promise hangs until it does — pair with a timeout
+     * at the caller if that's a concern. Resolves immediately for ids
+     * whose results were already cached.
+     */
+    awaitTasks(taskIds: string[]): Promise<TaskResult[]>;
+    terminate(subagentId: string): Promise<void>;
+    terminateAll(): Promise<void>;
+    status(): CoordinatorStatus;
+    /**
+     * Subscribe to coordinator events. Currently only `task.completed` is
+     * exposed (the others are internal lifecycle). Returns an unsubscribe
+     * function. External callers (e.g. the CLI's `MultiAgentHost`) use this
+     * to drive their own pending/results tracking without poking the
+     * coordinator directly.
+     */
+    on(event: 'task.completed', handler: (payload: {
+        task: TaskSpec;
+        result: TaskResult;
+    }) => void): () => void;
+    /**
+     * Snapshot of every task that has resolved (success, failed, timeout,
+     * stopped) since the director started. Returned in completion order
+     * via the internal map's iteration order. Used by `/fleet status` to
+     * paint the completed table without reaching into private state.
+     */
+    completedResults(): TaskResult[];
+    snapshot(): FleetUsage;
+    /**
+     * Compose the leader/director-agent system prompt: fleet preamble +
+     * (optional) roster summary + user base prompt. Pass the result to your
+     * leader Agent's `ctx.systemPrompt` when constructing it.
+     *
+     * `basePrompt` defaults to `config.leaderSystemPrompt` so callers can
+     * use the no-arg form when the multi-agent config already carries it.
+     */
+    leaderSystemPrompt(basePrompt?: string): string;
+    /**
+     * Compose a subagent's system prompt for a given `SubagentConfig`:
+     * baseline + role + task + per-spawn override. Returned by value — does
+     * not mutate the config. Factories (the user-supplied `AgentFactory`)
+     * should call this when building each subagent's Agent so the bridge
+     * contract, role context, and override are all surfaced.
+     *
+     * When `taskBrief` is omitted the Task section is dropped. Pass the
+     * actual task description here to reinforce it in the system prompt
+     * (the runner already passes it as user input — duplicating in the
+     * system prompt is optional but improves anchoring on small models).
+     */
+    subagentSystemPrompt(config: SubagentConfig, taskBrief?: string): string;
+    /**
+     * Build the tool set the LLM-driven director uses to orchestrate.
+     * Returns an array of `Tool` definitions; register these on the
+     * director's `Agent` to expose `spawn_subagent`, `assign_task`, etc.
+     * Each tool's `execute()` delegates straight to the matching method
+     * above.
+     *
+     * Tools all carry `permission: 'auto'` — the *user* has already
+     * approved running the director when they kicked off the run, so
+     * gating individual orchestration calls behind a confirm prompt
+     * would just be noise. The actual subagent tools they spawn are
+     * still permission-checked normally.
+     */
+    tools(roster?: Record<string, SubagentConfig>): Tool[];
+}
+
+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 readonly runner?;
+    private readonly subagents;
+    private pendingTasks;
+    private completedResults;
+    private totalIterations;
+    private inFlight;
+    constructor(config: MultiAgentConfig, options?: MultiAgentCoordinatorOptions);
+    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>;
+    getStatus(): CoordinatorStatus;
+    /** Expose snapshot of completed results — useful for callers awaiting all done. */
+    results(): readonly 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 findIdleSubagent;
+    private runDispatched;
+    private executeWithTimeout;
+    private recordCompletion;
+    private isDone;
+}
+
+/**
+ * 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;
+}
+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;
+}
+/**
+ * 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;
+
+/**
+ * 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.
+ */
+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;
+    sessionsRoot?: string;
+    /**
+     * 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;
+}
+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;
+        model?: string;
+        title?: string;
+    }): 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".
+ */
+declare function makeDirectorSessionFactory(opts: DirectorSessionFactoryOptions): DirectorSessionFactory;
+
+/**
+ * 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. Kept deliberately short — long preambles
+ * crowd out the user's leader prompt and the LLM stops attending. The tool
+ * descriptions live on the tool definitions themselves; this preamble only
+ * teaches *when* to reach for them.
+ */
+declare const DEFAULT_DIRECTOR_PREAMBLE = "You are the Director of a multi-agent fleet. You orchestrate worker\nsubagents by spawning them, assigning tasks, awaiting completions, and\nrolling up their outputs into your next decision.\n\nCore fleet tools available to you:\n  - spawn_subagent       \u2014 create a worker with a chosen provider / model / role\n  - assign_task          \u2014 hand a piece of work to a specific subagent\n  - await_tasks          \u2014 block until named task ids complete (parallel-safe)\n  - ask_subagent         \u2014 synchronously query a running subagent via the bridge\n  - roll_up              \u2014 aggregate finished tasks into a markdown/json summary\n  - terminate_subagent   \u2014 abort a stuck worker (use sparingly)\n  - fleet_status         \u2014 snapshot of all subagents and pending tasks\n  - fleet_usage          \u2014 token + cost breakdown per subagent and total\n\nWorking rules:\n  1. Decompose first. Before spawning, decide which sub-tasks are\n     independent and can run in parallel. Sequential work doesn't need a\n     subagent \u2014 do it yourself.\n  2. Match worker to job. Cheap/fast model for triage, capable model for\n     synthesis. Different providers per sibling is allowed and encouraged.\n  3. Always pair an assign with an await. Don't fire-and-forget; you owe\n     the user a single coherent answer at the end.\n  4. Roll up before deciding. After await_tasks resolves, call roll_up so\n     the results are folded back into your context in a compact form.\n  5. Budget is real. Check fleet_usage periodically. If a subagent is\n     thrashing, terminate it rather than letting cost climb silently.\n  6. Never claim a subagent's work as your own without verifying it. If a\n     result looks wrong, ask_subagent for clarification before passing it\n     to the user.";
+/**
+ * Default baseline prepended to every subagent's system prompt. Tells the
+ * subagent its place in the hierarchy and the bridge contract — without
+ * this, a subagent has no way to know it *can* ask the parent for
+ * clarification, and it will hallucinate answers when context is missing.
+ *
+ * Bridge contract: subagents may `send` progress and `request` answers, but
+ * MAY NOT exfiltrate the parent's full system prompt or tools list. The
+ * baseline reinforces this in plain text — the actual enforcement is at
+ * the bridge transport layer.
+ */
+declare const DEFAULT_SUBAGENT_BASELINE = "You are a subagent operating under a Director. You were spawned to handle\na specific slice of a larger plan \u2014 do that slice well and report back.\n\nBridge contract:\n  - You have a parent (the Director). You may call `request` on the\n    parent bridge to ask a clarifying question. Use this sparingly; the\n    parent is also working.\n  - You MAY NOT request the parent's system prompt, tool list, or other\n    subagents' context. Those are not yours to read.\n  - Your final task output is what the Director sees. Be concise,\n    structured, and self-contained \u2014 assume the Director will paste your\n    output into its own context.";
+/** Parts the leader-prompt composer accepts. All optional. */
+interface DirectorPromptParts {
+    /** The user's existing leader system prompt — typically what was passed
+     *  via `MultiAgentConfig.leaderSystemPrompt`. */
+    basePrompt?: string;
+    /** Override the built-in fleet preamble. Pass empty string to suppress. */
+    directorPreamble?: string;
+    /** 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;
+}
+/**
+ * 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.
+ */
+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. */
+interface SubagentPromptParts {
+    /** Base persona/identity for *every* subagent. Defaults to the bridge
+     *  contract baseline. Pass empty string to suppress. */
+    baseline?: string;
+    /** Role-specific block, e.g. "You are a code reviewer. Focus on…". */
+    role?: string;
+    /** 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;
+    /**
+     * 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;
+    /** 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;
+}
+/**
+ * Compose a subagent's system prompt. Order:
+ *   1. Baseline (bridge contract)
+ *   2. Role
+ *   3. Task brief
+ *   4. 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*"; 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.
+ */
+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.
+ */
+declare function rosterSummaryFromConfigs(roster: Record<string, {
+    name: string;
+    provider?: string;
+    model?: string;
+    prompt?: string;
+    role?: string;
+}>): string;
+
+/**
+ * Pre-built subagent role configurations for the WrongStack fleet.
+ * These can be passed to `MultiAgentHost.spawn()` or used as templates
+ * for the director's roster.
+ */
+
+/**
+ * Audit Log Agent — analyzes session logs, event streams, and traces.
+ * Use for: post-mortems, trend analysis, operational insights.
+ */
+declare const AUDIT_LOG_AGENT: SubagentConfig;
+/**
+ * Bug Hunter Agent — systematic bug and code smell detection.
+ * Use for: pre-refactoring health checks, code review, regression prevention.
+ */
+declare const BUG_HUNTER_AGENT: SubagentConfig;
+/**
+ * Refactor Planner Agent — structured refactoring planning.
+ * Use for: large rewrites, technical debt reduction, architecture improvements.
+ */
+declare const REFACTOR_PLANNER_AGENT: SubagentConfig;
+/**
+ * Security Scanner Agent — vulnerability and secret detection.
+ * Use for: CI checks, pre-release audits, dependency vulnerability scanning.
+ */
+declare const SECURITY_SCANNER_AGENT: SubagentConfig;
+/** All pre-built agents in a map for easy lookup by role. */
+declare const FLEET_ROSTER: Record<string, SubagentConfig>;
+/** Quick-access list for spawning all at once. */
+declare const ALL_FLEET_AGENTS: SubagentConfig[];
+
+export { ALL_FLEET_AGENTS, AUDIT_LOG_AGENT, type AgentFactory, type AgentFactoryResult, type AgentRunnerOptions, BUG_HUNTER_AGENT, DEFAULT_DIRECTOR_PREAMBLE, DEFAULT_SUBAGENT_BASELINE, DefaultMultiAgentCoordinator, Director, DirectorBudgetError, type DirectorPromptParts, type DirectorSessionFactory, type DirectorSessionFactoryOptions, FLEET_ROSTER, FleetBus, type FleetEvent, type FleetHandler, type FleetUsage, FleetUsageAggregator, InMemoryAgentBridge, type MultiAgentCoordinatorOptions, REFACTOR_PLANNER_AGENT, SECURITY_SCANNER_AGENT, type SubagentPromptParts, type SubagentUsageSnapshot, composeDirectorPrompt, composeSubagentPrompt, makeAgentSubagentRunner, makeDirectorSessionFactory, rosterSummaryFromConfigs };