@wrongstack/core 0.308.5 → 0.308.7

package/dist/coordination/agents/index.js

@@ -1655,6 +1655,7 @@ var BUNDLED_AGENT_SKILLS = [
 var skillSet = (...names) => names;
 var ROLE_SKILL_SETS = {
   explore: skillSet("research-web", "node-modern", "typescript-strict"),
+  "explore-companion": skillSet("node-modern", "typescript-strict"),
   search: skillSet("bug-hunter", "typescript-strict", "research-web"),
   research: skillSet("research-web", "tech-stack", "security-scanner", "api-design"),
   analyst: skillSet("sdd", "api-design", "testing", "security-scanner"),

package/dist/coordination/agents/role-skills.d.ts

@@ -19,6 +19,7 @@ export type BundledAgentSkill = (typeof BUNDLED_AGENT_SKILLS)[number];
  */
 export declare const ROLE_SKILL_SETS: {
     readonly explore: ("api-design" | "audit-log" | "bug-hunter" | "chimera" | "data-governance" | "docker-deploy" | "git-flow" | "mnemosyne" | "multi-agent" | "node-modern" | "observability" | "output-standards" | "plugin-author" | "prompt-engineering" | "react-modern" | "refactor-planner" | "research-web" | "sdd" | "security-scanner" | "skill-creator" | "tech-stack" | "testing" | "typescript-strict" | "wrongstack-mailbox")[];
+    readonly 'explore-companion': ("api-design" | "audit-log" | "bug-hunter" | "chimera" | "data-governance" | "docker-deploy" | "git-flow" | "mnemosyne" | "multi-agent" | "node-modern" | "observability" | "output-standards" | "plugin-author" | "prompt-engineering" | "react-modern" | "refactor-planner" | "research-web" | "sdd" | "security-scanner" | "skill-creator" | "tech-stack" | "testing" | "typescript-strict" | "wrongstack-mailbox")[];
     readonly search: ("api-design" | "audit-log" | "bug-hunter" | "chimera" | "data-governance" | "docker-deploy" | "git-flow" | "mnemosyne" | "multi-agent" | "node-modern" | "observability" | "output-standards" | "plugin-author" | "prompt-engineering" | "react-modern" | "refactor-planner" | "research-web" | "sdd" | "security-scanner" | "skill-creator" | "tech-stack" | "testing" | "typescript-strict" | "wrongstack-mailbox")[];
     readonly research: ("api-design" | "audit-log" | "bug-hunter" | "chimera" | "data-governance" | "docker-deploy" | "git-flow" | "mnemosyne" | "multi-agent" | "node-modern" | "observability" | "output-standards" | "plugin-author" | "prompt-engineering" | "react-modern" | "refactor-planner" | "research-web" | "sdd" | "security-scanner" | "skill-creator" | "tech-stack" | "testing" | "typescript-strict" | "wrongstack-mailbox")[];
     readonly analyst: ("api-design" | "audit-log" | "bug-hunter" | "chimera" | "data-governance" | "docker-deploy" | "git-flow" | "mnemosyne" | "multi-agent" | "node-modern" | "observability" | "output-standards" | "plugin-author" | "prompt-engineering" | "react-modern" | "refactor-planner" | "research-web" | "sdd" | "security-scanner" | "skill-creator" | "tech-stack" | "testing" | "typescript-strict" | "wrongstack-mailbox")[];

package/dist/coordination/explore-companion.d.ts

@@ -0,0 +1,191 @@
+/**
+ * ExploreCompanion — state-triggered background codebase explorer.
+ *
+ * Runs behind a leader agent executing the main task. It watches the live
+ * EventBus for signals of the leader's IN-PROGRESS state and converts them
+ * into narrow, read-only exploration probes assigned to a resident
+ * `explore-companion` subagent (see docs/architecture/explore-companion-
+ * subagent.md). The companion never blocks the leader: probes are
+ * fire-and-forget (`onProbe` → spawn/assign), and findings travel back via
+ * mailbox `result`/`btw` messages that the mailbox loop folds into the
+ * leader's context before its next step.
+ *
+ * Watched signals (each independently toggleable):
+ *   - edit on an unread file — the leader edits a path it never read;
+ *   - zero-hit search — a search/grep returned no results;
+ *   - unfamiliar read — the leader reads a path not yet probed;
+ *   - todo flip — a leader todo transitions to in_progress
+ *     (requires `leaderAgentId`);
+ *   - error symbol — an `error` event names a file/symbol token;
+ *   - mailbox ask — an `ask`/`assign` message from the leader addressed
+ *     to the companion.
+ *
+ * Design lineage: BrainMonitor (watch bus → cooldown → engage, session
+ * filter, single engagement in flight, host-intent start/stop/reconfigure)
+ * generalized from "steer the leader" to "assign exploration probes".
+ *
+ * Non-interference guarantees (also pinned by tests):
+ *   - never blocks the leader — onProbe is called without awaiting the
+ *     resident's task completion;
+ *   - one probe in flight, a capped pending queue with drop-oldest;
+ *   - per-subject cooldown so a busy leader cannot stack probes on the
+ *     same file/symbol;
+ *   - subagent events are filtered out via the leader-session check;
+ *   - probe failures are swallowed — the leader's work never breaks
+ *     because the companion's spawn/assign rejected a probe.
+ *
+ * @module explore-companion
+ */
+import type { EventBus } from '../kernel/events.js';
+import { type Mailbox } from './mailbox-types.js';
+/** Which observed work-state signal produced a probe. */
+export type ExploreProbeSource = 'edit_unread_file' | 'search_zero_hits' | 'unfamiliar_read' | 'todo_in_progress' | 'error_symbol' | 'mailbox_ask';
+/** A narrow exploration task scoped to the leader's current work. */
+export interface ExploreProbe {
+    id: string;
+    /** Human-readable question for the companion agent. */
+    probe: string;
+    /** Optional file/symbol hint so the companion starts index-first. */
+    hint?: {
+        file?: string;
+        symbol?: string;
+    } | undefined;
+    /** What the leader was doing when the trigger fired. */
+    context?: string | undefined;
+    source: ExploreProbeSource;
+    /**
+     * Dedupe key (`file:<path>`, `search:<query>`, `token:<symbol>`,
+     * `todo:<id>`, `mail:<id>`). Probes with a subject probed within
+     * `cooldownMs` are skipped.
+     */
+    subject: string;
+    createdAt: number;
+}
+/** Per-signal kill switches. Omitted = enabled. */
+export interface ExploreCompanionSignalToggles {
+    editUnreadFile?: boolean | undefined;
+    searchZeroHits?: boolean | undefined;
+    unfamiliarRead?: boolean | undefined;
+    todoInProgress?: boolean | undefined;
+    errorSymbol?: boolean | undefined;
+    mailboxAsk?: boolean | undefined;
+}
+export interface ExploreCompanionOptions {
+    /** Live bus the leader's tool/error/todo events fire on. */
+    events: EventBus;
+    /** Project mailbox the companion polls for explicit asks and acks them. */
+    mailbox: Mailbox;
+    /**
+     * Leader session id used to filter out subagent events. The companion
+     * subscribes to global events (tool.executed, error, session.agents_updated)
+     * which fire for BOTH the leader and subagents. When set, any event whose
+     * `sessionId` differs from this value is skipped. Events without a
+     * `sessionId` field always pass through (backward compatibility). Pass a
+     * lazy getter when the session id may change at runtime.
+     */
+    leaderSessionId: string | (() => string | undefined);
+    /**
+     * Leader agent id whose todo list is diffed for the todo-in-progress
+     * signal. Optional: when absent, the todo signal engages nothing (the
+     * `session.agents_updated` snapshot lists leader + subagents and only the
+     * leader's own todo flips should trigger probes).
+     */
+    leaderAgentId?: string | (() => string | undefined) | undefined;
+    /**
+     * Assign (or spawn) a probe on the resident companion. Called without
+     * awaiting the resident's task completion — the leader is never blocked.
+     */
+    onProbe: (probe: ExploreProbe) => Promise<{
+        subagentId: string;
+        taskId: string;
+    }>;
+    /** Mailbox identity of the companion; used to poll + ack asks. Default 'explore-companion'. */
+    companionAgentId?: string | undefined;
+    /** Minimum gap between probes on the same subject (ms). Default 120_000. */
+    cooldownMs?: number | undefined;
+    /** Cap on the pending probe queue; oldest dropped when full. Default 8. */
+    maxPending?: number | undefined;
+    /** Mailbox poll interval for explicit asks (ms). Default 5_000. */
+    pollIntervalMs?: number | undefined;
+    /** Master kill switch. Default true; false makes `start()` a no-op. */
+    enabled?: boolean | undefined;
+    /** Per-signal kill switches. Omitted signals stay enabled. */
+    signals?: ExploreCompanionSignalToggles | undefined;
+    /**
+     * Tool names whose successful execution counts as a file edit for the
+     * edit-unread-file signal. Replaces the built-in set; matched
+     * case-insensitively. Same contract as BrainMonitor.fileEditTools.
+     */
+    fileEditTools?: readonly string[] | undefined;
+    /**
+     * Tool names whose successful zero-result run fires the zero-hit signal.
+     * Replaces the built-in set; matched case-insensitively.
+     */
+    searchTools?: readonly string[] | undefined;
+    /** Injectable clock for tests. Default Date.now. */
+    now?: (() => number) | undefined;
+}
+/** The subset re-applicable to a running companion via `reconfigure()`. */
+export type ExploreCompanionTunables = Partial<Pick<ExploreCompanionOptions, 'cooldownMs' | 'maxPending' | 'pollIntervalMs' | 'enabled' | 'signals' | 'fileEditTools' | 'searchTools' | 'companionAgentId'>>;
+/** Mailbox identity the companion polls/acks under by default. */
+export declare const DEFAULT_EXPLORE_COMPANION_AGENT_ID = "explore-companion";
+/** Default per-subject probe cooldown (120s, same as BrainMonitor). */
+export declare const DEFAULT_PROBE_COOLDOWN_MS = 120000;
+/** Default pending probe queue cap. */
+export declare const DEFAULT_MAX_PENDING_PROBES = 8;
+/** Default mailbox poll interval for explicit asks. */
+export declare const DEFAULT_MAILBOX_POLL_INTERVAL_MS = 5000;
+/** Tools whose successful execution mutates a file we can treat as an edit. */
+export declare const DEFAULT_EXPLORE_EDIT_TOOLS: readonly string[];
+/** Tools whose successful zero-result run is a "search came up empty" signal. */
+export declare const DEFAULT_EXPLORE_SEARCH_TOOLS: readonly string[];
+/**
+ * Render a probe into the JSON task contract the `explore-companion` prompt
+ * accepts: `{ "probe", "hint", "context" }`. Hosts use this to build the
+ * subagent task text from a structured probe.
+ */
+export declare function buildProbeTaskText(probe: ExploreProbe): string;
+export declare class ExploreCompanion {
+    private readonly opts;
+    private readonly unsubscribers;
+    /** Paths the leader has read (readSet) — feeds edit-unread + unfamiliar-read. */
+    private readonly readSet;
+    /** subject → last probe time; cooldown gate. Survives detach/reconfigure. */
+    private readonly probedAt;
+    /** todo id → last observed status, per leader agent. */
+    private readonly todoSeen;
+    private readonly pending;
+    private inFlight;
+    private pollTimer;
+    private running;
+    private hostStarted;
+    private cfg;
+    constructor(opts: ExploreCompanionOptions);
+    private resolveConfig;
+    /** Resolve the leader's own session id for event filtering. */
+    private resolveLeaderSessionId;
+    /** Resolve the leader's agent id for todo diffing (optional signal). */
+    private resolveLeaderAgentId;
+    /** Re-apply tunables to a (possibly running) companion. */
+    reconfigure(next: ExploreCompanionTunables): boolean;
+    /** Begin watching. Idempotent; a disabled companion records intent only. */
+    start(): void;
+    /** Stop watching and drop the host's intent to watch. */
+    stop(): void;
+    /** True while the watchers are attached. */
+    isRunning(): boolean;
+    /** Number of probes queued but not yet dispatched (for status surfaces). */
+    pendingCount(): number;
+    private attach;
+    /** Tear down watchers without touching host intent. Cooldowns survive. */
+    private detach;
+    private trackToolExecuted;
+    private trackAgentTodos;
+    private trackError;
+    private pollMailbox;
+    private cooldownOk;
+    private now;
+    private engage;
+    private drain;
+}
+//# sourceMappingURL=explore-companion.d.ts.map

package/dist/coordination/fleet.d.ts

@@ -24,6 +24,20 @@ export declare const REFACTOR_PLANNER_AGENT: SubagentConfig;
  * Use for: CI checks, pre-release audits, dependency vulnerability scanning.
  */
 export declare const SECURITY_SCANNER_AGENT: SubagentConfig;
+/**
+ * Explore Companion — state-triggered background codebase explorer.
+ * Runs behind a leader agent: triggered by the in-progress state of the
+ * work (unread-file edits, zero-hit searches, todo flips, explicit asks),
+ * scans the codebase read-only, and feeds findings back via mailbox
+ * `result`/`btw` + `submit_result`. See
+ * docs/architecture/explore-companion-subagent.md.
+ *
+ * Operational role — deliberately NOT in ALL_AGENT_DEFINITIONS (like
+ * `shadow-agent`), so the free-form dispatcher never routes to it and the
+ * 75-definition catalog count stays intact. Probes are assigned, never
+ * awaited; idle reaping comes from the FLEET_ROSTER_BUDGETS entry.
+ */
+export declare const EXPLORE_COMPANION_AGENT: SubagentConfig;
 /** Generic template used directly or cloned into project-specific roles. */
 export declare const GENERIC_AGENT: SubagentConfig;
 export declare const FLEET_ROSTER: Record<string, SubagentConfig>;

package/dist/coordination/index.d.ts

@@ -9,6 +9,7 @@ export { BrainTraceRecorder, type BrainTraceRecorderOptions } from './brain-trac
 export { type BugFinding, type CollabBudgetConfig, type CollabBudgetOverrides, type CollabBudgetWarningPayload, type CollabDebugReport, CollabSession, type CollabSessionOptions, type CriticConcern, type CriticEvaluation, type DirectorAlert, DirectorAlertLevel, type DirectorCancelCollabPayload, type RefactorPhase, type RefactorPlan, type SharedFileEntry, type SharedFileSnapshot, } from './collab-debug.js';
 export { assessCommitSafety, type CommitSafetyOptions, type CommitSafetyReport, } from './commit-safety.js';
 export { type CreateDelegateToolOptions, createDelegateTool, type DelegateHost, } from './delegate-tool.js';
+export { buildProbeTaskText, DEFAULT_EXPLORE_COMPANION_AGENT_ID, DEFAULT_EXPLORE_EDIT_TOOLS, DEFAULT_EXPLORE_SEARCH_TOOLS, DEFAULT_MAILBOX_POLL_INTERVAL_MS, DEFAULT_MAX_PENDING_PROBES, DEFAULT_PROBE_COOLDOWN_MS, ExploreCompanion, type ExploreCompanionOptions, type ExploreCompanionSignalToggles, type ExploreCompanionTunables, type ExploreProbe, type ExploreProbeSource, } from './explore-companion.js';
 export { DEPENDENCY_FILE_PATTERNS, type DependencyWatcherConfig, type DepWatchEntry, makeDependencyWatcherConfig, } from './dep-watcher.js';
 export { attachDepWatcherBridge, type DepWatcherBridgeOptions, } from './dep-watcher-bridge.js';
 export { Director, FleetCostCapError, FleetSpawnBudgetError, FleetTokenCapError, type TaskResultNotification, } from './director.js';