@wrongstack/core 0.1.10 → 0.3.1

package/dist/{agent-bridge-6KPqsFx6.d.ts → agent-bridge-C3DUGjSb.d.ts}

@@ -1,4 +1,4 @@
-import { n as BridgeTransport, o as BridgeMessage, A as AgentBridge, p as AgentBridgeConfig } from './multi-agent-fmkRHtof.js';
+import { B as BridgeTransport, l as BridgeMessage, A as AgentBridge, m as AgentBridgeConfig } from './multi-agent-B9a6sflH.js';
 
 /**
  * In-memory pub/sub transport for agent-to-agent messaging.

package/dist/{compactor-B4mQZXf2.d.ts → compactor-BUU6Zm_3.d.ts}

@@ -1,4 +1,4 @@
-import { a0 as Context } from './context-BmM2xGUZ.js';
+import { a0 as Context } from './context-IovtuTf8.js';
 
 interface CompactReport {
     before: number;

package/dist/{config-BU9f_5yH.d.ts → config-CKLYPkCi.d.ts}

@@ -1,5 +1,5 @@
 import { W as WireFamily } from './models-registry-Y2xbog0E.js';
-import { P as Permission } from './context-BmM2xGUZ.js';
+import { P as Permission } from './context-IovtuTf8.js';
 
 interface ContextConfig {
     warnThreshold: number;

package/dist/{context-BmM2xGUZ.d.ts → context-IovtuTf8.d.ts}

@@ -238,6 +238,8 @@ interface Tool<I = unknown, O = unknown> {
     name: string;
     description: string;
     usageHint?: string;
+    /** Optional category for grouping in help lists and system prompts. */
+    category?: string;
     inputSchema: JSONSchema;
     permission: Permission;
     mutating: boolean;
@@ -659,6 +661,14 @@ interface SessionStore {
 }
 interface SessionWriter {
     readonly id: string;
+    /**
+     * Absolute path to the JSONL file this writer appends to, when one
+     * exists. In-memory writers (tests, ephemeral sessions) leave it
+     * undefined. Observability surfaces (`/fleet log`, FleetPanel) use
+     * this to tell the user *where* the transcript lives without
+     * having to recompute the path from session metadata.
+     */
+    readonly transcriptPath?: string;
     append(event: SessionEvent): Promise<void>;
     close(): Promise<void>;
 }

package/dist/coordination/index.d.ts

@@ -1,17 +1,17 @@
-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 { M as MultiAgentConfig, i as SubagentRunner, c as SubagentConfig, k as TaskSpec, j as TaskResult, a as CoordinatorStatus, b as MultiAgentCoordinator, S as SpawnResult, l as BridgeMessage, A as AgentBridge } from '../multi-agent-B9a6sflH.js';
+export { n as BudgetExceededError, o as BudgetKind, p as BudgetLimits, q as BudgetUsage, r as SubagentBudget } from '../multi-agent-B9a6sflH.js';
+import { q as SessionWriter, u as Tool, o as SessionStore } from '../context-IovtuTf8.js';
+import { I as InMemoryAgentBridge } from '../agent-bridge-C3DUGjSb.js';
+export { a as InMemoryBridgeTransport, c as createMessage } from '../agent-bridge-C3DUGjSb.js';
+import { E as EventBus } from '../events-CNB9PALO.js';
 import { EventEmitter } from 'node:events';
-import { A as Agent, n as AgentInput } from '../plugin-DJk6LL8B.js';
+import { r as Agent, u as AgentInput } from '../index-BDb0cAMP.js';
+import '../logger-BMQgxvdy.js';
+import '../system-prompt-Dk1qm8ey.js';
 import '../observability-BhnVLBLS.js';
-import '../renderer-rk_1Swwc.js';
-import '../secret-scrubber-CicHLN4G.js';
-import '../config-BU9f_5yH.js';
+import '../secret-scrubber-CgG2tV2B.js';
+import '../config-CKLYPkCi.js';
 import '../models-registry-Y2xbog0E.js';
-import '../logger-BMQgxvdy.js';
 
 /**
  * Single fleet-wide event with subagent attribution. Whatever a child
@@ -202,6 +202,29 @@ interface DirectorOptions {
      * `maxSpawnDepth` this bounds the chain.
      */
     spawnDepth?: number;
+    /**
+     * Absolute path to a director-state checkpoint file. When set, the
+     * director writes an incremental snapshot of pending/running/completed
+     * tasks + spawned subagents on every state mutation. Distinct from
+     * `manifestPath`: the manifest is a final record written on shutdown,
+     * the checkpoint is a live mirror useful for crash recovery and the
+     * `wstack resume` "you had N tasks in flight" banner.
+     */
+    stateCheckpointPath?: string;
+    /**
+     * Session writer the director should forward task lifecycle events to
+     * (`agent_spawned`, `task_created`, `task_completed`, `task_failed`).
+     * When omitted these events stay in-memory only — useful for tests but
+     * lossy in production. Production callers (the CLI) pass the same
+     * writer the host Agent uses so all events land in a single JSONL.
+     */
+    sessionWriter?: SessionWriter;
+    /**
+     * Debounce window for periodic manifest writes triggered by spawn/
+     * assign/complete events. Default: 2000ms. Pass 0 to disable periodic
+     * writes (the manifest will then only be written on `shutdown()`).
+     */
+    manifestDebounceMs?: number;
 }
 /**
  * Thrown by `Director.spawn()` when a configured spawn cap (`maxSpawns`,
@@ -262,7 +285,34 @@ declare class Director {
     readonly spawnDepth: number;
     /** Live spawn counter for `maxSpawns` enforcement. */
     private spawnCount;
+    /** Optional checkpoint mirror — writes the live task graph + roster to disk. */
+    private readonly stateCheckpoint;
+    /** Optional session writer for emitting task_* / agent_* lifecycle events. */
+    private readonly sessionWriter;
+    /** Debounce timer for periodic manifest writes. */
+    private manifestTimer;
+    private readonly manifestDebounceMs;
+    /** Resolves task descriptions back from `assign()` so completion events
+     *  can also carry a human-readable title. */
+    private readonly taskDescriptions;
+    /** Snapshot of which subagent owns each task — drives state-checkpoint
+     *  status updates without re-walking the manifest. */
+    private readonly taskOwners;
+    /**
+     * Handle to the coordinator-side `task.completed` listener so we can
+     * unsubscribe in `shutdown()`. Without this, repeated Director
+     * construction (e.g. tests, hot reloads) accumulates listeners on a
+     * cached coordinator and slowly drifts the EventEmitter past its
+     * default cap.
+     */
+    private taskCompletedListener;
     constructor(opts: DirectorOptions);
+    /** Best-effort session-writer append. Swallows failures — the director
+     *  must not break a fleet run because the session JSONL handle closed. */
+    private appendSessionEvent;
+    /** Debounced manifest writer. A burst of spawn/assign/complete events
+     *  collapses into one write. Set `manifestDebounceMs` to 0 to disable. */
+    private scheduleManifest;
     /**
      * Spawn a subagent. Identical to the coordinator's `spawn()` but
      * captures provider/model metadata for the usage aggregator and
@@ -317,6 +367,16 @@ declare class Director {
      * — calling shutdown twice is a no-op on the second invocation.
      */
     shutdown(): Promise<void>;
+    /**
+     * Funnel for shutdown-phase errors. We can't throw — `shutdown()` is
+     * called from process-exit paths where an uncaught throw would lose
+     * the manifest write that comes after. But we MUST NOT silently
+     * swallow either — a persistent bridge-close failure would otherwise
+     * mask a real bug. `process.emitWarning` is the right tier:
+     * surfaces on stderr by default, lets the host plug a warning
+     * listener for structured collection, and never affects exit code.
+     */
+    private logShutdownError;
     /**
      * Hand a task to the coordinator. Returns the assigned task id so
      * callers can wait on it via `awaitTasks([id])`. The coordinator's
@@ -353,6 +413,18 @@ declare class Director {
      */
     completedResults(): TaskResult[];
     snapshot(): FleetUsage;
+    /**
+     * Look up provider/model metadata for a spawned subagent. Returns
+     * undefined when the subagent id is unknown (not yet spawned, or
+     * already torn down). Callers — notably the TUI fleet panel — use
+     * this to render human-readable provider/model tags next to each
+     * subagent row without reaching into private state.
+     */
+    getSubagentMeta(id: string): {
+        provider?: string;
+        model?: string;
+        name?: string;
+    } | undefined;
     /**
      * Compose the leader/director-agent system prompt: fleet preamble +
      * (optional) roster summary + user base prompt. Pass the result to your
@@ -391,6 +463,78 @@ declare class Director {
     tools(roster?: Record<string, SubagentConfig>): Tool[];
 }
 
+/**
+ * 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.
+ */
+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;
+}
+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;
+    /**
+     * 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;
+    /**
+     * 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;
+}
+/**
+ * `delegate` — the only multi-agent tool a regular (non-director) agent
+ * ever needs. It bundles spawn + assign + await into a single call and
+ * transparently auto-promotes the host into director mode on first use.
+ *
+ * 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.
+ */
+declare function createDelegateTool(opts: CreateDelegateToolOptions): Tool;
+
 interface MultiAgentCoordinatorOptions {
     /**
      * Callback that executes a task on behalf of a subagent. Required for
@@ -403,13 +547,28 @@ interface MultiAgentCoordinatorOptions {
 declare class DefaultMultiAgentCoordinator extends EventEmitter implements MultiAgentCoordinator {
     readonly coordinatorId: string;
     readonly config: MultiAgentConfig;
-    private readonly runner?;
+    private runner?;
     private readonly subagents;
     private pendingTasks;
     private completedResults;
     private totalIterations;
     private inFlight;
+    /**
+     * Subagents currently being stopped. Set on entry to `stop()`, cleared
+     * once `recordCompletion` lands the terminal TaskResult. Used by
+     * `runDispatched` and `findIdleSubagent` to refuse mid-flight dispatch
+     * to a subagent the caller has already asked to terminate — closes the
+     * assign+terminate race where a fresh task could land on a worker that
+     * was about to be killed.
+     */
+    private readonly terminating;
     constructor(config: MultiAgentConfig, options?: MultiAgentCoordinatorOptions);
+    /**
+     * Replace the runner after construction. Used when the runner depends
+     * on infrastructure (e.g. FleetBus) that isn't available until after
+     * the coordinator's owning Director is built.
+     */
+    setRunner(runner: SubagentRunner): void;
     spawn(subagent: SubagentConfig): Promise<SpawnResult>;
     assign(task: TaskSpec): Promise<void>;
     delegate(to: string, msg: BridgeMessage): Promise<void>;
@@ -432,6 +591,28 @@ declare class DefaultMultiAgentCoordinator extends EventEmitter implements Multi
     private tryDispatchNext;
     private canDispatch;
     private findIdleSubagent;
+    /**
+     * Returns true iff at least one spawned subagent could still
+     * process a task. A "live" subagent is one that is not stopped
+     * AND not mid-termination — `running` workers count because they
+     * will eventually finish and become idle.
+     *
+     * When no subagent has ever been spawned, returns `true` so a
+     * pre-spawn `assign()` simply queues (legacy behaviour). The
+     * dead-end detection only fires after `stop()` has retired every
+     * spawned worker.
+     *
+     * Used by `tryDispatchNext` to detect a dead-end pending queue.
+     */
+    private hasLiveSubagent;
+    /**
+     * Drain every pending task with a synthetic `aborted_by_parent`
+     * completion event. Same shape as the `stopAll()` drain — we go
+     * around `recordCompletion` because pending tasks were never
+     * counted in `inFlight` and routing them through would trip the
+     * underflow guard on every task after the first.
+     */
+    private drainPendingAsAborted;
     private runDispatched;
     private executeWithTimeout;
     private recordCompletion;
@@ -450,6 +631,16 @@ interface AgentFactoryResult {
     agent: Agent;
     /** Event bus the factory wired to this agent — required for budget hookup. */
     events: EventBus;
+    /**
+     * Optional cleanup hook invoked in the runner's `finally` block once
+     * the task ends (success, failure, abort — same exit path). Factories
+     * that own resources scoped to a single task (per-subagent JSONL
+     * writers, transient providers, throwaway containers) implement this
+     * to close them deterministically instead of relying on GC. Errors
+     * thrown here are swallowed so a flaky cleanup can't mask the task's
+     * real result.
+     */
+    dispose?: () => Promise<void> | void;
 }
 interface AgentRunnerOptions {
     factory: AgentFactory;
@@ -459,6 +650,13 @@ interface AgentRunnerOptions {
      * input (e.g. JSON contracts, role-prefixed prompts).
      */
     formatTaskInput?: (task: TaskSpec, config: SubagentConfig) => AgentInput;
+    /**
+     * When set, the runner attaches the subagent's EventBus to this FleetBus
+     * on task start and detaches it when the task finishes. This is the
+     * injection seam that lets the TUI fleet panel observe subagent activity
+     * live — without it, FleetBus stays empty.
+     */
+    fleetBus?: FleetBus;
 }
 /**
  * Builds a `SubagentRunner` that drives a real `Agent` per task while honoring
@@ -691,4 +889,4 @@ 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 };
+export { ALL_FLEET_AGENTS, AUDIT_LOG_AGENT, type AgentFactory, type AgentFactoryResult, type AgentRunnerOptions, BUG_HUNTER_AGENT, type CreateDelegateToolOptions, DEFAULT_DIRECTOR_PREAMBLE, DEFAULT_SUBAGENT_BASELINE, DefaultMultiAgentCoordinator, type DelegateHost, 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, createDelegateTool, makeAgentSubagentRunner, makeDirectorSessionFactory, rosterSummaryFromConfigs };