@wrongstack/core 0.284.1 → 0.286.0

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"}