@wrongstack/core 0.1.7 → 0.1.8

package/dist/defaults/index.d.ts

@@ -1,7 +1,7 @@
 import { g as Logger, f as LogLevel, P as PathResolver, r as ModelsRegistry, O as EventBus, z as ResolvedModel, j as MemoryStore, i as MemoryScope, S as SecretScrubber, t as PermissionPolicy, I as InputReader, s as PermissionDecision, B as RetryPolicy, E as ErrorHandler, a as Compactor, R as RecoveryDecision, H as SkillLoader, J as SkillManifest, G as SkillEntry, b as Config, c as ConfigLoader, d as ConfigStore, C as CompactReport, a0 as MiddlewareHandler, p as ModelsDevPayload, A as ResolvedProvider, W as WireFamily, n as ModeStore, l as ModeConfig, k as Mode, M as MCPServerConfig } from '../mode-Pjt5vMS6.js';
 import { u as TokenCounter, U as Usage, C as CacheStats, p as SessionStore, o as SessionMetadata, r as SessionWriter, l as ResumedSession, S as SessionData, q as SessionSummary, c as ContentBlock, v as Tool, a0 as Context, i as ProviderError, h as Provider, M as Message, F as ToolUseBlock, B as ToolResultBlock, n as SessionEvent } from '../provider-txgB0Oq9.js';
-import { h as AttachmentStore, A as AddAttachmentInput, g as AttachmentRef, d as Attachment, S as SecretVault, x as MultiAgentCoordinator, w as MultiAgentConfig, a9 as SubagentRunner, a5 as SubagentConfig, X as SpawnResult, al as TaskSpec, B as BridgeMessage, a as AgentBridge, l as CoordinatorStatus, aj as TaskResult, aC as Agent, aE as AgentInput, j as BridgeTransport, b as AgentBridgeConfig, o as DoneCondition, aM as RunResult, a4 as Specification, Y as SpecAnalysis, a3 as SpecValidationResult, af as TaskGraph, ag as TaskNode, ae as TaskFilter, ak as TaskSort, ai as TaskProgress, an as TaskType, ah as TaskPriority, at as ToolExecutorOptions, au as ToolExecutorStrategy, ao as ToolBatchResult, O as SessionReader, n as DefaultSessionReaderOptions, N as SessionQuery, T as SessionSummaryLite, R as SessionSearchQuery, Q as SessionSearchHit, L as SessionExportOptions, u as MetricsSink, s as MetricLabels, v as MetricsSnapshot, q as HealthRegistry, H as HealthCheck, c as AggregateHealth, aw as Tracer, W as Span } from '../session-reader-7AutWHut.js';
-export { aG as BudgetExceededError, aH as BudgetKind, aI as BudgetLimits, aJ as BudgetUsage, aN as SubagentBudget } from '../session-reader-7AutWHut.js';
+import { h as AttachmentStore, A as AddAttachmentInput, g as AttachmentRef, d as Attachment, S as SecretVault, x as MultiAgentCoordinator, w as MultiAgentConfig, a9 as SubagentRunner, a5 as SubagentConfig, X as SpawnResult, al as TaskSpec, B as BridgeMessage, a as AgentBridge, l as CoordinatorStatus, aj as TaskResult, aC as Agent, aE as AgentInput, j as BridgeTransport, b as AgentBridgeConfig, o as DoneCondition, aM as RunResult, a4 as Specification, Y as SpecAnalysis, a3 as SpecValidationResult, af as TaskGraph, ag as TaskNode, ae as TaskFilter, ak as TaskSort, ai as TaskProgress, an as TaskType, ah as TaskPriority, at as ToolExecutorOptions, au as ToolExecutorStrategy, ao as ToolBatchResult, O as SessionReader, n as DefaultSessionReaderOptions, N as SessionQuery, T as SessionSummaryLite, R as SessionSearchQuery, Q as SessionSearchHit, L as SessionExportOptions, u as MetricsSink, s as MetricLabels, v as MetricsSnapshot, q as HealthRegistry, H as HealthCheck, c as AggregateHealth, aw as Tracer, W as Span } from '../session-reader-9sOTgmeC.js';
+export { aG as BudgetExceededError, aH as BudgetKind, aI as BudgetLimits, aJ as BudgetUsage, aN as SubagentBudget } from '../session-reader-9sOTgmeC.js';
 import { a as WstackPaths } from '../wstack-paths-BGu2INTm.js';
 import { EventEmitter } from 'node:events';
 
@@ -882,6 +882,118 @@ interface AgentRunnerOptions {
  */
 declare function makeAgentSubagentRunner(opts: AgentRunnerOptions): SubagentRunner;
 
+/**
+ * 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;
+}
+
 /**
  * In-memory pub/sub transport for agent-to-agent messaging.
  * Subscribers register by agentId and receive messages via callback.
@@ -910,6 +1022,382 @@ declare class InMemoryAgentBridge implements AgentBridge {
 }
 declare function createMessage<T = unknown>(type: BridgeMessage['type'], from: string, payload: T, to?: string): BridgeMessage<T>;
 
+/**
+ * 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;
+}
+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;
+    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[];
+}
+
+/**
+ * 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;
+    /** 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;
+
 type AutonomousResult = RunResult & {
     toolCalls: number;
     reason?: string;
@@ -950,6 +1438,7 @@ declare class AutonomousRunner {
     private readonly doneChecker;
     constructor(opts: AutonomousRunnerOptions);
     run(): Promise<AutonomousResult>;
+    private runLoop;
     stop(): void;
 }
 
@@ -1714,4 +2203,4 @@ declare const sentinelServer: () => MCPServerConfig;
 /** Everything bundled — full set of built-in servers. Useful for `wstack mcp add --all`. */
 declare const allServers: () => Record<string, MCPServerConfig>;
 
-export { type AbandonedSession, type AgentFactory, type AgentFactoryResult, type AgentRunnerOptions, type AttachmentStoreOptions, AutoCompactionMiddleware, AutonomousRunner, type AutonomousRunnerOptions, type CompactorOptions, type ConfigLoaderOptions, type ConfigMigration, ConfigMigrationError, type ConfigSource, type ContextManagerAction, type ContextManagerInput, type ContextManagerResult, type ContextManagerToolOptions, DEFAULT_CONFIG_MIGRATIONS, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultErrorHandler, DefaultHealthRegistry, DefaultLogger, type DefaultLoggerOptions, DefaultMemoryStore, DefaultModeStore, DefaultModelsRegistry, type DefaultModelsRegistryOptions, DefaultMultiAgentCoordinator, DefaultPathResolver, DefaultPermissionPolicy, DefaultRetryPolicy, DefaultSecretScrubber, DefaultSecretVault, DefaultSessionReader, DefaultSessionStore, DefaultSkillLoader, DefaultTaskStore, DefaultTokenCounter, type DoneCheckResult, DoneConditionChecker, type GeneratedTask, HybridCompactor, InMemoryAgentBridge, InMemoryBridgeTransport, InMemoryMetricsSink, IntelligentCompactor, type IntelligentCompactorOptions, LLMSelector, type LLMSelectorOptions, type MemoryStoreOptions, type MetricsServerHandle, type MetricsServerOptions, type MigrationContext, type MigrationResult, type ModeLoaderOptions, type MultiAgentCoordinatorOptions, NoopMetricsSink, NoopTracer, OTelTracer, type OtlpMetricsExporterHandle, type OtlpMetricsExporterOptions, type OtlpTraceExporterHandle, type OtlpTraceExporterOptions, PROMETHEUS_CONTENT_TYPE, type PermissionPolicyOptions, type PersistedQueueItem, QueueStore, RecoveryLock, type RecoveryLockOptions, type SecretVaultOptions, SelectiveCompactor, type SelectiveCompactorOptions, type SessionStoreOptions, type SkillLoaderOptions, SpecDrivenDev, type SpecDrivenDevOptions, SpecParser, TaskFlow, type TaskFlowEventMap, type TaskFlowEventName, type TaskFlowExecutionContext, type TaskFlowOptions, type TaskFlowPhase, TaskGenerator, type TaskGeneratorOptions, type TaskStore, TaskTracker, type TaskTrackerOptions, type TaskTransition, ToolExecutor, allServers, awsServer, blockServer, braveSearchServer, buildOtlpMetricsRequest, buildOtlpTracesRequest, classifyFamily, context7Server, contextManagerTool, createContextManagerTool, createMessage, decryptConfigSecrets, encryptConfigSecrets, everArtServer, filesystemServer, githubServer, googleMapsServer, loadProjectModes, loadUserModes, makeAgentSubagentRunner, migratePlaintextSecrets, renderPrometheus, rewriteConfigEncrypted, runConfigMigrations, sentinelServer, slackServer, startMetricsServer, startOtlpMetricsExporter, startOtlpTraceExporter, wireMetricsToEvents };
+export { type AbandonedSession, type AgentFactory, type AgentFactoryResult, type AgentRunnerOptions, type AttachmentStoreOptions, AutoCompactionMiddleware, AutonomousRunner, type AutonomousRunnerOptions, type CompactorOptions, type ConfigLoaderOptions, type ConfigMigration, ConfigMigrationError, type ConfigSource, type ContextManagerAction, type ContextManagerInput, type ContextManagerResult, type ContextManagerToolOptions, DEFAULT_CONFIG_MIGRATIONS, DEFAULT_DIRECTOR_PREAMBLE, DEFAULT_SUBAGENT_BASELINE, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultErrorHandler, DefaultHealthRegistry, DefaultLogger, type DefaultLoggerOptions, DefaultMemoryStore, DefaultModeStore, DefaultModelsRegistry, type DefaultModelsRegistryOptions, DefaultMultiAgentCoordinator, DefaultPathResolver, DefaultPermissionPolicy, DefaultRetryPolicy, DefaultSecretScrubber, DefaultSecretVault, DefaultSessionReader, DefaultSessionStore, DefaultSkillLoader, DefaultTaskStore, DefaultTokenCounter, Director, type DirectorPromptParts, type DirectorSessionFactory, type DirectorSessionFactoryOptions, type DoneCheckResult, DoneConditionChecker, FleetBus, type FleetEvent, type FleetHandler, type FleetUsage, FleetUsageAggregator, type GeneratedTask, HybridCompactor, InMemoryAgentBridge, InMemoryBridgeTransport, InMemoryMetricsSink, IntelligentCompactor, type IntelligentCompactorOptions, LLMSelector, type LLMSelectorOptions, type MemoryStoreOptions, type MetricsServerHandle, type MetricsServerOptions, type MigrationContext, type MigrationResult, type ModeLoaderOptions, type MultiAgentCoordinatorOptions, NoopMetricsSink, NoopTracer, OTelTracer, type OtlpMetricsExporterHandle, type OtlpMetricsExporterOptions, type OtlpTraceExporterHandle, type OtlpTraceExporterOptions, PROMETHEUS_CONTENT_TYPE, type PermissionPolicyOptions, type PersistedQueueItem, QueueStore, RecoveryLock, type RecoveryLockOptions, type SecretVaultOptions, SelectiveCompactor, type SelectiveCompactorOptions, type SessionStoreOptions, type SkillLoaderOptions, SpecDrivenDev, type SpecDrivenDevOptions, SpecParser, type SubagentPromptParts, type SubagentUsageSnapshot, TaskFlow, type TaskFlowEventMap, type TaskFlowEventName, type TaskFlowExecutionContext, type TaskFlowOptions, type TaskFlowPhase, TaskGenerator, type TaskGeneratorOptions, type TaskStore, TaskTracker, type TaskTrackerOptions, type TaskTransition, ToolExecutor, allServers, awsServer, blockServer, braveSearchServer, buildOtlpMetricsRequest, buildOtlpTracesRequest, classifyFamily, composeDirectorPrompt, composeSubagentPrompt, context7Server, contextManagerTool, createContextManagerTool, createMessage, decryptConfigSecrets, encryptConfigSecrets, everArtServer, filesystemServer, githubServer, googleMapsServer, loadProjectModes, loadUserModes, makeAgentSubagentRunner, makeDirectorSessionFactory, migratePlaintextSecrets, renderPrometheus, rewriteConfigEncrypted, rosterSummaryFromConfigs, runConfigMigrations, sentinelServer, slackServer, startMetricsServer, startOtlpMetricsExporter, startOtlpTraceExporter, wireMetricsToEvents };