@bastani/atomic 0.5.3-1 → 0.5.4-0

package/dist/sdk/components/workflow-picker-panel.d.ts

@@ -0,0 +1,120 @@
+/** @jsxImportSource @opentui/react */
+/**
+ * WorkflowPickerPanel — interactive TUI for `atomic workflow -a <agent>`.
+ *
+ * Telescope-style fuzzy picker with a two-phase flow:
+ *
+ *   1. PICK   — filter workflows scoped to the current agent, navigate with
+ *               ↑/↓ or ⌃j/⌃k, press ↵ to lock in a selection.
+ *   2. PROMPT — fill the workflow's declared input schema (one field per
+ *               declared `WorkflowInput`). Free-form workflows fall back to
+ *               a single `prompt` text field.
+ *
+ * Pressing ⌃s in the prompt phase validates required fields and opens a
+ * CONFIRM modal that shows the fully-composed shell command before
+ * submission. y/↵ confirms, n/esc cancels back to the form.
+ *
+ * Lifecycle:
+ *
+ *   const panel = await WorkflowPickerPanel.create({ agent, workflows });
+ *   const result = await panel.waitForSelection();
+ *   panel.destroy();
+ *   if (result) await executeWorkflow({ ... });
+ *
+ * `waitForSelection()` resolves with `null` if the user exits without
+ * committing (esc in PICK phase, or ⌃c anywhere) and with a
+ * `{ workflow, inputs }` record if they confirm the run.
+ */
+import { type CliRenderer } from "@opentui/core";
+import { type TerminalTheme } from "../runtime/theme.js";
+import type { AgentType, WorkflowInput } from "../types.js";
+import type { WorkflowWithMetadata } from "../runtime/discovery.js";
+export interface PickerTheme {
+    background: string;
+    backgroundPanel: string;
+    backgroundElement: string;
+    surface: string;
+    text: string;
+    textMuted: string;
+    textDim: string;
+    primary: string;
+    success: string;
+    error: string;
+    warning: string;
+    info: string;
+    mauve: string;
+    border: string;
+    borderActive: string;
+}
+export declare function buildPickerTheme(base: TerminalTheme): PickerTheme;
+type Source = "local" | "global" | "builtin";
+/** The payload the picker resolves with on successful submission. */
+export interface WorkflowPickerResult {
+    /** The workflow the user committed to running. */
+    workflow: WorkflowWithMetadata;
+    /** Populated form values, one per declared input (or { prompt } for free-form). */
+    inputs: Record<string, string>;
+}
+/**
+ * Subsequence fuzzy match — Telescope-style. Returns a score (lower =
+ * better) or null for no match. Adjacent matches are rewarded; jumps over
+ * non-matching characters are penalized proportionally to the gap.
+ */
+export declare function fuzzyMatch(query: string, target: string): number | null;
+interface ListEntry {
+    workflow: WorkflowWithMetadata;
+    section: Source;
+}
+interface ListRow {
+    kind: "section" | "entry";
+    source?: Source;
+    entry?: ListEntry;
+}
+export declare function buildEntries(query: string, workflows: WorkflowWithMetadata[]): ListEntry[];
+export declare function buildRows(entries: ListEntry[], query: string): ListRow[];
+export declare function isFieldValid(field: WorkflowInput, value: string): boolean;
+interface PickerAppProps {
+    theme: PickerTheme;
+    agent: AgentType;
+    workflows: WorkflowWithMetadata[];
+    onSubmit: (result: WorkflowPickerResult) => void;
+    onCancel: () => void;
+}
+export declare function WorkflowPicker({ theme, agent, workflows, onSubmit, onCancel, }: PickerAppProps): import("react").ReactNode;
+export interface WorkflowPickerPanelOptions {
+    agent: AgentType;
+    /** Pre-loaded workflows to show. Must already be filtered to `agent`. */
+    workflows: WorkflowWithMetadata[];
+}
+/**
+ * Imperative shell around the React picker tree — mirrors the
+ * {@link OrchestratorPanel} lifecycle so both panels can be used
+ * interchangeably by the CLI command layer.
+ */
+export declare class WorkflowPickerPanel {
+    private renderer;
+    private root;
+    private destroyed;
+    private resolveSelection;
+    private selectionPromise;
+    private constructor();
+    /**
+     * Create a new WorkflowPickerPanel. Initialises a CLI renderer and
+     * mounts the interactive tree. The caller should `await
+     * waitForSelection()` and then call `destroy()` regardless of outcome.
+     */
+    static create(options: WorkflowPickerPanelOptions): Promise<WorkflowPickerPanel>;
+    /** Create with an externally-provided renderer (e.g. a test renderer). */
+    static createWithRenderer(renderer: CliRenderer, options: WorkflowPickerPanelOptions): WorkflowPickerPanel;
+    /**
+     * Resolve with the user's selection once they confirm, or `null` if
+     * they exit the picker without committing. Idempotent — subsequent
+     * calls return the same promise.
+     */
+    waitForSelection(): Promise<WorkflowPickerResult | null>;
+    /** Tear down the CLI renderer. Idempotent. */
+    destroy(): void;
+    private handleSubmit;
+    private handleCancel;
+}
+export {};

package/dist/sdk/define-workflow.d.ts

@@ -57,7 +57,7 @@ export declare class WorkflowBuilder<A extends AgentType = AgentType> {
  *       {},
  *       async (s) => {
  *         // s.client: CopilotClient, s.session: CopilotSession
- *         await s.session.sendAndWait({ prompt: s.userPrompt });
+ *         await s.session.sendAndWait({ prompt: s.inputs.prompt ?? "" });
  *         s.save(await s.session.getMessages());
  *       },
  *     );

package/dist/sdk/index.js

@@ -5,7 +5,7 @@ import {
   discoverWorkflows,
   executeWorkflow,
   findWorkflow
-} from "../chunk-mn870nrv.js";
+} from "../chunk-xkxndz5g.js";
 
 // src/sdk/errors.ts
 class MissingDependencyError extends Error {

package/dist/sdk/runtime/discovery.d.ts

@@ -7,7 +7,7 @@
  *
  * Project-local workflows take precedence over global ones with the same name.
  */
-import type { AgentType } from "../types.js";
+import type { AgentType, WorkflowInput } from "../types.js";
 export interface DiscoveredWorkflow {
     name: string;
     agent: AgentType;
@@ -22,10 +22,64 @@ export declare const AGENTS: AgentType[];
 export declare const WORKFLOWS_GITIGNORE: string;
 /**
  * Discover all available workflows from built-in, global, and local sources.
- * Optionally filter by agent. Precedence: local > global > builtin.
+ * Optionally filter by agent.
+ *
+ * **Merge precedence:** `builtin > local > global`.
+ *
+ * Builtin names are **strictly reserved** — a user-defined local or
+ * global workflow whose name matches any built-in workflow is dropped
+ * entirely from discovery. It will not be registered, returned from
+ * `findWorkflow`, appear in the interactive picker, or show up in
+ * `atomic workflow -l`. This protects SDK-shipped workflows (e.g.
+ * `ralph`) from being silently overridden or even visibly "competing
+ * with" a user's own definition, which would otherwise be confusing
+ * when someone tries to run the canonical version.
+ *
+ * Reservation is by **name only**, across all agents: if a builtin
+ * defines `ralph` for any agent, a local `ralph` for any other agent is
+ * also dropped. Local still overrides global for every non-builtin
+ * name, so project-scoped customisation of user-scoped workflows
+ * continues to work.
+ *
+ * By default, the result is **merged by precedence** — if a workflow is
+ * defined in both local and global sources, only the higher-precedence
+ * entry is returned. This is the right shape for `findWorkflow`, which
+ * needs the single resolved entry per (name, agent) pair.
+ *
+ * Pass `{ merge: false }` to get the **unmerged** result — local and
+ * global contribute their entries independently, so `--list` can show
+ * both a local and a global copy of the same workflow when they coexist
+ * on disk. (Builtin reservation still applies in both modes.)
  */
-export declare function discoverWorkflows(projectRoot?: string, agentFilter?: AgentType): Promise<DiscoveredWorkflow[]>;
+export declare function discoverWorkflows(projectRoot?: string, agentFilter?: AgentType, options?: {
+    merge?: boolean;
+}): Promise<DiscoveredWorkflow[]>;
 /**
  * Find a specific workflow by name and agent.
  */
 export declare function findWorkflow(name: string, agent: AgentType, projectRoot?: string): Promise<DiscoveredWorkflow | null>;
+/**
+ * A discovered workflow enriched with the metadata the picker needs to
+ * render it: the human description and the declared input schema.
+ *
+ * Populated by {@link loadWorkflowsMetadata}, which runs each discovered
+ * workflow through {@link WorkflowLoader.loadWorkflow} and extracts just
+ * the display-relevant fields — the full compiled definition is
+ * discarded after extraction so re-imports during execution are cheap.
+ */
+export interface WorkflowWithMetadata extends DiscoveredWorkflow {
+    /** Workflow description, empty string when none was declared. */
+    description: string;
+    /** Declared input schema, empty array for free-form workflows. */
+    inputs: readonly WorkflowInput[];
+}
+/**
+ * Load metadata (description + inputs) for a batch of discovered workflows.
+ *
+ * Workflows that fail to import are **skipped silently** so one broken
+ * entry can never prevent the picker from rendering. Callers that need
+ * to surface load errors (e.g. `atomic workflow -n broken`) should use
+ * {@link WorkflowLoader.loadWorkflow} directly — that path produces
+ * structured error reports.
+ */
+export declare function loadWorkflowsMetadata(discovered: DiscoveredWorkflow[]): Promise<WorkflowWithMetadata[]>;

package/dist/sdk/runtime/executor.d.ts

@@ -19,8 +19,13 @@ export interface WorkflowRunOptions {
     definition: WorkflowDefinition;
     /** Agent type */
     agent: AgentType;
-    /** The user's prompt */
-    prompt: string;
+    /**
+     * Structured inputs for this run. Free-form workflows model their
+     * single positional prompt as `{ prompt: "..." }` so workflow
+     * authors can read `ctx.inputs.prompt` uniformly regardless of
+     * whether the workflow declares a schema. Empty record is valid.
+     */
+    inputs?: Record<string, string>;
     /** Absolute path to the workflow's index.ts file (from discovery) */
     workflowFile: string;
     /** Project root (defaults to cwd) */
@@ -41,6 +46,14 @@ export declare function escBash(s: string): string;
  * variable expansion.  Null bytes are stripped for safety.
  */
 export declare function escPwsh(s: string): string;
+/**
+ * Decode the ATOMIC_WF_INPUTS env var (base64-encoded JSON) into a
+ * `Record<string, string>`. Returns an empty record when the variable
+ * is missing, malformed, or does not decode to a string-map object —
+ * structured inputs are optional, so a corrupt payload must never
+ * prevent free-form workflows from running.
+ */
+export declare function parseInputsEnv(raw: string | undefined): Record<string, string>;
 /**
  * Called by `atomic workflow -n <name> -a <agent> <prompt>`.
  *

package/dist/sdk/runtime/tmux.d.ts

@@ -5,6 +5,9 @@
  * creating sessions, splitting panes, spawning commands, capturing output,
  * sending keystrokes, and pane state detection.
  */
+import type { Subprocess } from "bun";
+/** Dedicated tmux socket name — isolates Atomic sessions from the user's default server. */
+export declare const SOCKET_NAME = "atomic";
 /**
  * Resolve the terminal multiplexer binary for the current platform.
  *
@@ -120,6 +123,12 @@ export declare function sessionExists(sessionName: string): boolean;
  * Attach to an existing tmux session (takes over the current terminal).
  */
 export declare function attachSession(sessionName: string): void;
+/**
+ * Spawn an interactive attach-session process.
+ * Encapsulates binary resolution, config injection, and socket isolation.
+ * Used by all async attach call sites (executor, chat).
+ */
+export declare function spawnMuxAttach(sessionName: string): Subprocess;
 /**
  * Switch the current tmux client to a different session.
  * Use this instead of `attachSession` when already inside tmux to avoid

package/dist/sdk/types.d.ts

@@ -62,6 +62,40 @@ export type ProviderClient<A extends AgentType> = ClientMap[A];
 /** The `s.session` type in a stage callback, resolved by agent type. */
 export type ProviderSession<A extends AgentType> = SessionMap[A];
 export type { CopilotClient, CopilotClientOptions, CopilotSession, CopilotSessionConfig, OpencodeClient, OpencodeSession, ClaudeClientWrapper, ClaudeSessionWrapper, ClaudeQueryDefaults, };
+/**
+ * Supported field types for a workflow's declared inputs.
+ *
+ * - `"string"` — single-line free-form input (short values, identifiers, paths)
+ * - `"text"`   — multi-line free-form input (long prose, prompts, specs)
+ * - `"enum"`   — one of a fixed list of allowed `values`
+ */
+export type WorkflowInputType = "string" | "text" | "enum";
+/**
+ * A declared input for a workflow. When a workflow provides an `inputs`
+ * array, the CLI materialises one `--<name>` flag per input (and the
+ * interactive picker renders one field per input) so users can pass
+ * structured values rather than a single free-form prompt.
+ *
+ * Leaving `inputs` unset (or empty) signals that the workflow consumes a
+ * single free-form prompt instead — the legacy
+ * `atomic workflow -n <name> -a <agent> "prompt"` form.
+ */
+export interface WorkflowInput {
+    /** Field name — also the CLI flag (`--<name>`) and form field identifier. */
+    name: string;
+    /** Input kind — see {@link WorkflowInputType}. */
+    type: WorkflowInputType;
+    /** Whether the field must be non-empty before the workflow can run. */
+    required?: boolean;
+    /** Short human description shown as the field caption. */
+    description?: string;
+    /** Placeholder text shown when the field is empty. */
+    placeholder?: string;
+    /** Default value pre-filled into the field. Enums use this to pick their initial value. */
+    default?: string;
+    /** Allowed values — required when `type` is `"enum"`. */
+    values?: string[];
+}
 /**
  * A transcript from a completed session.
  * Provides both the file path and rendered text content.
@@ -134,8 +168,16 @@ export interface SessionContext<A extends AgentType = AgentType> {
     client: ProviderClient<A>;
     /** Provider-specific session (auto-created by runtime) */
     session: ProviderSession<A>;
-    /** The original user prompt from the CLI invocation */
-    userPrompt: string;
+    /**
+     * Structured inputs for this workflow run. Populated from CLI flags
+     * (`--<name>=<value>`) or the interactive picker.
+     *
+     * Free-form workflows (no declared `inputs` schema) receive their
+     * single positional prompt under the `prompt` key — so
+     * `s.inputs.prompt` is the canonical way to read the user's prompt
+     * regardless of whether the workflow is structured or free-form.
+     */
+    inputs: Record<string, string>;
     /** Which agent is running */
     agent: A;
     /**
@@ -171,8 +213,16 @@ export interface SessionContext<A extends AgentType = AgentType> {
  * Does not have session-specific fields (paneId, save, etc.).
  */
 export interface WorkflowContext<A extends AgentType = AgentType> {
-    /** The original user prompt from the CLI invocation */
-    userPrompt: string;
+    /**
+     * Structured inputs for this workflow run. Populated from CLI flags
+     * (`--<name>=<value>`) or the interactive picker.
+     *
+     * Free-form workflows (no declared `inputs` schema) receive their
+     * single positional prompt under the `prompt` key — so
+     * `ctx.inputs.prompt` is the canonical way to read the user's prompt
+     * regardless of whether the workflow is structured or free-form.
+     */
+    inputs: Record<string, string>;
     /** Which agent is running */
     agent: A;
     /**
@@ -201,6 +251,13 @@ export interface WorkflowOptions {
     name: string;
     /** Human-readable description */
     description?: string;
+    /**
+     * Optional declared inputs. When provided, the CLI materialises one
+     * `--<name>` flag per entry and the interactive picker renders one form
+     * field per entry. Leave unset to keep the workflow free-form (a single
+     * positional prompt argument).
+     */
+    inputs?: WorkflowInput[];
 }
 /**
  * A compiled workflow definition — the sealed output of defineWorkflow().compile().
@@ -209,6 +266,8 @@ export interface WorkflowDefinition<A extends AgentType = AgentType> {
     readonly __brand: "WorkflowDefinition";
     readonly name: string;
     readonly description: string;
+    /** Declared input schema — empty array for free-form workflows. */
+    readonly inputs: readonly WorkflowInput[];
     /** The workflow's entry point. Called by the executor with a WorkflowContext. */
     readonly run: (ctx: WorkflowContext<A>) => Promise<void>;
 }

package/dist/sdk/workflows/builtin/deep-research-codebase/claude/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * deep-research-codebase / claude
+ *
+ * A deterministically-orchestrated, distributed version of the
+ * `research-codebase` skill. The research-codebase skill spawns
+ * codebase-locator / codebase-analyzer / codebase-pattern-finder /
+ * codebase-research-locator / codebase-research-analyzer /
+ * codebase-online-researcher sub-agents on the fly via LLM judgment;
+ * this workflow spawns the same agents on a deterministic schedule
+ * driven by the codebase's lines of code.
+ *
+ * Topology:
+ *
+ *           ┌─→ codebase-scout
+ *   parent ─┤
+ *           └─→ research-history
+ *                     │
+ *                     ▼
+ *   ┌──────────────────────────────────────────────────┐
+ *   │  explorer-1   explorer-2   ...   explorer-N      │   (Promise.all)
+ *   └──────────────────────────────────────────────────┘
+ *                     │
+ *                     ▼
+ *                aggregator
+ *
+ * Stage 1a — codebase-scout
+ *   Pure-TypeScript: lists files (git ls-files), counts LOC (batched wc -l),
+ *   renders a depth-bounded ASCII tree, and bin-packs directories into N
+ *   partitions where N is determined by the LOC heuristic. Then makes one
+ *   short LLM call to produce an architectural orientation that primes the
+ *   downstream explorers. Returns structured data via `handle.result` and
+ *   the agent's prose via `ctx.transcript(handle)`.
+ *
+ * Stage 1b — research-history (parallel sibling of scout)
+ *   Dispatches the codebase-research-locator and codebase-research-analyzer
+ *   sub-agents over the project's existing research/ directory to surface
+ *   prior decisions, completed investigations, and unresolved questions.
+ *   Output is consumed via session transcript (≤400 words) and feeds into
+ *   the aggregator as supplementary context.
+ *
+ * Stage 2 — explorer-1..N (parallel; depends on scout + history)
+ *   Each explorer is a coordinator that dispatches specialized sub-agents
+ *   over its assigned partition (single LOC-balanced slice of the codebase):
+ *     - codebase-locator       → finds relevant files in the partition
+ *     - codebase-analyzer      → documents how the most relevant files work
+ *     - codebase-pattern-finder → finds existing pattern examples
+ *     - codebase-online-researcher → (conditional) external library docs
+ *   The explorer never reads files directly — it orchestrates specialists
+ *   and writes a synthesized findings document to a known scratch path.
+ *
+ * Stage 3 — aggregator
+ *   Reads each explorer's scratch file by path (file-based handoff to keep
+ *   the aggregator's own context lean — we deliberately do NOT inline N
+ *   transcripts into the prompt). Folds in the research-history overview
+ *   as supplementary context. Synthesizes a single research document at
+ *   research/docs/YYYY-MM-DD-<slug>.md.
+ *
+ * Context-engineering decisions are documented at each stage below.
+ */
+declare const _default: import("../../../index.ts").WorkflowDefinition<"claude">;
+export default _default;

package/dist/sdk/workflows/builtin/deep-research-codebase/copilot/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * deep-research-codebase / copilot
+ *
+ * Copilot replica of the Claude deep-research-codebase workflow. The Claude
+ * version dispatches specialist sub-agents (codebase-locator, codebase-
+ * analyzer, etc.) inside a single explorer session via `@"name (agent)"`
+ * syntax — a Claude-specific feature. Copilot sessions are bound to a single
+ * agent for their entire lifetime, so we keep the SAME graph topology
+ * (scout ∥ history → explorer-1..N → aggregator) but drive each explorer
+ * through the locate → analyze → patterns → synthesize sequence inline using
+ * the default agent's built-in file tools.
+ *
+ * Topology (identical to Claude version):
+ *
+ *           ┌─→ codebase-scout
+ *   parent ─┤
+ *           └─→ research-history
+ *                     │
+ *                     ▼
+ *   ┌──────────────────────────────────────────────────┐
+ *   │  explorer-1   explorer-2   ...   explorer-N      │   (Promise.all)
+ *   └──────────────────────────────────────────────────┘
+ *                     │
+ *                     ▼
+ *                aggregator
+ *
+ * Copilot-specific concerns baked in:
+ *
+ *  • F10 — every `sendAndWait` passes an explicit 30-minute timeout. The SDK
+ *    default is 60 seconds; a timeout THROWS and aborts the entire stage.
+ *    Explorers can easily exceed 60s on large partitions.
+ *
+ *  • F5 — every `ctx.stage()` call is a FRESH session with no memory of prior
+ *    stages. We forward the scout overview, history overview, and partition
+ *    assignment explicitly into each explorer's first prompt. The aggregator
+ *    gets the same plus the explorer scratch file paths.
+ *
+ *  • F9 — `s.save()` receives `SessionEvent[]` via `s.session.getMessages()`
+ *    (Copilot's correct shape). Passing anything else breaks downstream
+ *    `transcript()` reads.
+ *
+ *  • F6 — every prompt explicitly requires trailing prose AFTER any tool
+ *    call, so `transcript()` is never empty. A Copilot turn whose final
+ *    message is a tool call produces an empty assistant.message terminator
+ *    (F1); trailing prose is our insurance.
+ */
+declare const _default: import("../../../index.ts").WorkflowDefinition<"copilot">;
+export default _default;

package/dist/sdk/workflows/builtin/deep-research-codebase/helpers/heuristic.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Determine how many parallel explorer sub-agents to spawn for the
+ * deep-research-codebase workflow, based on lines of code in the codebase.
+ *
+ * The heuristic balances coverage against coordination overhead:
+ *   - Too few explorers leave parts of the codebase under-investigated.
+ *   - Too many explorers flood the aggregator with redundant findings,
+ *     burn tokens on coordination, and exhaust tmux/process budgets.
+ *
+ * Tier choices were anchored to the rough sizes of common project shapes:
+ *
+ *   <    5,000 LOC →  2 explorers   scripts, single-purpose tools
+ *   <   25,000 LOC →  3 explorers   small libraries, CLI utilities
+ *   <  100,000 LOC →  5 explorers   medium applications
+ *   <  500,000 LOC →  7 explorers   large applications, small monorepos
+ *   <2,000,000 LOC →  9 explorers   large monorepos
+ *   ≥2,000,000 LOC → 12 explorers   massive monorepos (hard cap)
+ *
+ * The hard cap of 12 prevents runaway parallelism: each explorer is a
+ * Claude tmux pane plus an LLM session, so the cost grows linearly in
+ * tokens, processes, and walltime as well as in aggregator context.
+ */
+export declare function calculateExplorerCount(loc: number): number;
+/** Human-readable rationale for the heuristic decision — surfaced in logs/prompts. */
+export declare function explainHeuristic(loc: number, count: number): string;

package/dist/sdk/workflows/builtin/deep-research-codebase/helpers/prompts.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Prompt builders for the deep-research-codebase workflow.
+ *
+ * Context-engineering principles applied throughout:
+ *   - Position-aware placement: the research question is repeated at the
+ *     TOP and BOTTOM of every prompt (recall is 85-95% at the edges and
+ *     drops to 76-82% in the middle — see context-fundamentals).
+ *   - Informativity over exhaustiveness: each explorer prompt contains
+ *     only that explorer's partition, never the full file list.
+ *   - Explicit trailing commentary (F6): every prompt asks the agent to
+ *     produce a short text summary AFTER any tool/file output, so the
+ *     transcript is not empty when downstream stages read it.
+ *   - File-based handoff (filesystem-context skill): explorer findings
+ *     are written to disk and the aggregator reads them by path, instead
+ *     of inlining N transcripts into the aggregator's prompt.
+ *   - Documentarian role: every prompt explicitly forbids critique or
+ *     improvement suggestions; we are recording what exists.
+ */
+import type { PartitionUnit } from "./scout.js";
+/** Slugify the user's prompt for use in the final research filename. */
+export declare function slugifyPrompt(prompt: string): string;
+export declare function buildScoutPrompt(opts: {
+    question: string;
+    tree: string;
+    totalLoc: number;
+    totalFiles: number;
+    explorerCount: number;
+    partitionPreview: PartitionUnit[][];
+}): string;
+export declare function buildExplorerPrompt(opts: {
+    question: string;
+    index: number;
+    total: number;
+    partition: PartitionUnit[];
+    scoutOverview: string;
+    scratchPath: string;
+    root: string;
+}): string;
+/**
+ * The research-history scout dispatches specialized sub-agents to surface
+ * historical context from the project's `research/` directory:
+ *   - codebase-research-locator → finds prior research docs about the topic
+ *   - codebase-research-analyzer → extracts key insights from the most
+ *     relevant docs
+ *
+ * Output is consumed via session transcript (not file write) — kept short
+ * (≤400 words) so the aggregator can embed it cheaply.
+ */
+export declare function buildHistoryPrompt(opts: {
+    question: string;
+    root: string;
+}): string;
+/**
+ * Generic explorer prompt (Copilot / OpenCode). Drives a single default-agent
+ * session through the locate → analyze → patterns → synthesize sequence using
+ * built-in tools directly, instead of Claude's sub-agent dispatch.
+ */
+export declare function buildExplorerPromptGeneric(opts: {
+    question: string;
+    index: number;
+    total: number;
+    partition: PartitionUnit[];
+    scoutOverview: string;
+    historyOverview: string;
+    scratchPath: string;
+    root: string;
+}): string;
+/**
+ * Generic research-history prompt (Copilot / OpenCode). A single default-agent
+ * session searches the project's research/ directory using its own file tools,
+ * instead of dispatching Claude's codebase-research-locator / analyzer
+ * sub-agents.
+ */
+export declare function buildHistoryPromptGeneric(opts: {
+    question: string;
+    root: string;
+}): string;
+export declare function buildAggregatorPrompt(opts: {
+    question: string;
+    totalLoc: number;
+    totalFiles: number;
+    explorerCount: number;
+    explorerFiles: {
+        index: number;
+        scratchPath: string;
+        partition: PartitionUnit[];
+    }[];
+    finalPath: string;
+    scoutOverview: string;
+    historyOverview: string;
+}): string;

package/dist/sdk/workflows/builtin/deep-research-codebase/helpers/scout.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Codebase scout: deterministic helpers for the deep-research-codebase workflow.
+ *
+ * Responsibilities:
+ *   1. Discover the codebase root (git toplevel, falling back to cwd).
+ *   2. List all source files, respecting .gitignore when in a git repo.
+ *   3. Count lines of code per file using batched `wc -l`.
+ *   4. Render a compact directory tree (depth-bounded) for prompt context.
+ *   5. Build "partition units" by aggregating LOC at depth-1, then drilling
+ *      down on any unit that is too large to live in a single explorer.
+ *   6. Bin-pack partition units into N balanced groups (largest-first).
+ *
+ * Everything here is pure TypeScript + child_process — no LLM calls.
+ */
+/** Per-file LOC + path. */
+export type FileStats = {
+    path: string;
+    loc: number;
+};
+/**
+ * A "partition unit" is the atomic chunk of work that gets bin-packed into
+ * an explorer. It is always one directory (possibly drilled down to depth 2)
+ * with all of the code files that live anywhere underneath it.
+ */
+export type PartitionUnit = {
+    /** Repo-relative path, e.g. "src/cli" or "packages/foo/src". */
+    path: string;
+    loc: number;
+    fileCount: number;
+    /** Repo-relative file paths inside this unit (full recursive listing). */
+    files: string[];
+};
+export type CodebaseScout = {
+    /** Absolute path to the repository root. */
+    root: string;
+    totalLoc: number;
+    totalFiles: number;
+    /** Compact rendered directory tree (depth-bounded) for prompt context. */
+    tree: string;
+    /** Partition units, sorted by LOC descending. */
+    units: PartitionUnit[];
+};
+/** Resolve the project root. Prefers `git rev-parse --show-toplevel`. */
+export declare function getCodebaseRoot(): string;
+/**
+ * Run the full scout: list files, count LOC, render tree, build partition units.
+ */
+export declare function scoutCodebase(root: string): CodebaseScout;
+/**
+ * Bin-pack partition units into `count` balanced groups. Greedy
+ * largest-first: assign each unit to the currently-lightest bin.
+ *
+ * If there are fewer units than requested bins, the result has exactly
+ * `units.length` non-empty bins (we never return empty bins).
+ */
+export declare function partitionUnits(units: PartitionUnit[], count: number): PartitionUnit[][];