peaks-cli 1.3.2 → 1.3.4

package/dist/src/services/dispatch/dispatch-record-writer.d.ts

@@ -0,0 +1,93 @@
+import type { SubAgentToolCall } from './sub-agent-dispatcher.js';
+/** G6.3 Heartbeat entry — single update written by a running sub-agent. */
+export interface Heartbeat {
+    readonly at: string;
+    readonly status: HeartbeatStatus;
+    readonly progress: number;
+    readonly note: string | null;
+}
+export type HeartbeatStatus = 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'stale';
+export type DispatchRecordStatus = 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'cancelled' | 'no-execution' | 'stale';
+export type DispatchOutcome = 'success' | 'failed' | 'timeout' | 'cancelled' | 'no-execution';
+/** G2+G5+G6 dispatch record schema (AC-26 + AC-34). */
+export interface DispatchRecord {
+    readonly version: 2;
+    readonly createdAt: string;
+    readonly completedAt: string | null;
+    readonly outcome: DispatchOutcome;
+    readonly artifactPaths: readonly string[];
+    readonly disposed: boolean;
+    readonly disposedAt: string | null;
+    readonly role: string;
+    readonly requestId: string;
+    readonly sessionId: string;
+    readonly prompt: string;
+    readonly toolCall: SubAgentToolCall;
+    /** G5 batch id (AC-27) — uuid-like opaque token grouping one batch. */
+    readonly batchId: string;
+    /** G6 fields (AC-34) — backward compat: defaults on read. */
+    readonly heartbeats: readonly Heartbeat[];
+    readonly lastBeatAt: string | null;
+    readonly status: DispatchRecordStatus;
+}
+/** Input for the initial write. */
+export type WriteInitialDispatchInput = {
+    projectRoot: string;
+    sessionId: string;
+    requestId: string;
+    role: string;
+    prompt: string;
+    toolCall: SubAgentToolCall;
+    batchId: string;
+    /** Override the timestamp (testing). */
+    now?: () => Date;
+};
+/** Heartbeat write input. */
+export type AppendHeartbeatInput = {
+    recordPath: string;
+    status: HeartbeatStatus;
+    progress: number;
+    note?: string;
+    now?: () => Date;
+};
+/** Lifecycle transition input. */
+export type LifecycleInput = {
+    recordPath: string;
+    outcome: DispatchOutcome;
+    status: DispatchRecordStatus;
+    artifactPaths?: readonly string[];
+    now?: () => Date;
+};
+/** Write a new dispatch record (G2 + G5 + G6). Returns the absolute path. */
+export declare function writeInitialDispatchRecord(input: WriteInitialDispatchInput): {
+    path: string;
+    record: DispatchRecord;
+};
+/** Append a heartbeat (G6). Idempotent on (at, status) — append-only. */
+export declare function appendHeartbeat(input: AppendHeartbeatInput): {
+    record: DispatchRecord;
+    truncated: boolean;
+};
+/** Apply truncation: keep most recent 100, mark truncated flag. */
+export declare function applyTruncation(entries: readonly Heartbeat[]): {
+    heartbeats: Heartbeat[];
+    truncated: boolean;
+};
+/** Mark a record as completed (success / failed / cancelled / no-execution). */
+export declare function markCompleted(input: LifecycleInput): {
+    record: DispatchRecord;
+};
+/** Mark a record as disposed (reducer ran). */
+export declare function markDisposed(recordPath: string, now?: () => Date): {
+    record: DispatchRecord;
+};
+/**
+ * Read a dispatch record with backward-compat defaults. Old records
+ * missing G5 / G6 fields are upgraded on read (no error, no overwrite).
+ */
+export declare function readRecord(recordPath: string): DispatchRecord;
+/** Read multiple records from a list of paths. Tolerates missing files. */
+export declare function readRecords(paths: readonly string[]): DispatchRecord[];
+declare function isDispatchStatus(v: unknown): v is DispatchRecordStatus;
+declare function isOutcome(v: unknown): v is DispatchOutcome;
+export { isDispatchStatus, isOutcome };

package/dist/src/services/dispatch/dispatch-record-writer.js

@@ -0,0 +1,261 @@
+/**
+ * Dispatch record writer — slice 2026-06-07-sub-agent-dispatch-decouple (G2 + G5 + G6).
+ *
+ * Owns the on-disk format of `.peaks/_sub_agents/<sid>/dispatch-<rid>-<ts>.json`:
+ *   - G2: atomic write helper (mkdirSync recursive + tmp + rename) and
+ *     R-2 guard (path must live under `.peaks/_sub_agents/<sid>/`).
+ *   - G5: lifecycle schema (`createdAt` / `completedAt` / `outcome` /
+ *     `artifactPaths` / `disposed` / `disposedAt`) per AC-26 + RL-6..RL-9.
+ *   - G6: heartbeat schema upgrade per AC-33/AC-34 — `heartbeats[]` +
+ *     `lastBeatAt` + `status` aggregate. Read-side backward compat
+ *     supplies defaults for old records missing the G6 fields.
+ *
+ * The write helpers are intentionally small and pure:
+ *   - `writeInitialDispatchRecord`: append a new dispatch record at the
+ *     start of a sub-agent dispatch (called by `peaks sub-agent dispatch`).
+ *   - `appendHeartbeat`: append one heartbeat to an existing record
+ *     (called by `peaks sub-agent heartbeat`).
+ *   - `markCompleted` / `markFailed` / `markCancelled` / `markNoExecution`:
+ *     lifecycle transitions called by the reducer.
+ *
+ * All writes are atomic (tmp + rename) so a process crash mid-write
+ * cannot leave a half-truncated JSON file. All reads tolerate missing
+ * G6 fields (backward compat) and the G5 schema fields default to
+ * `null` / `false` / `'no-execution'` if the file was written by an
+ * older peaks build.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { assertSafeDispatchRecordPath, dispatchRecordPath } from '../security/safe-settings-path.js';
+const MAX_PROMPT_BYTES = 256 * 1024;
+/** Write a new dispatch record (G2 + G5 + G6). Returns the absolute path. */
+export function writeInitialDispatchRecord(input) {
+    const { projectRoot, sessionId, requestId, role, prompt, toolCall, batchId } = input;
+    const now = input.now ?? (() => new Date());
+    if (prompt.length > MAX_PROMPT_BYTES) {
+        const err = new Error(`prompt exceeds ${MAX_PROMPT_BYTES} bytes (got ${prompt.length}); ` +
+            `truncate or split into multiple dispatches`);
+        err.code = 'PROMPT_TOO_LARGE';
+        throw err;
+    }
+    const path = dispatchRecordPath(projectRoot, sessionId, requestId, now());
+    const safePath = assertSafeDispatchRecordPath(path, projectRoot);
+    const record = {
+        version: 2,
+        createdAt: now().toISOString(),
+        completedAt: null,
+        outcome: 'no-execution',
+        artifactPaths: [],
+        disposed: false,
+        disposedAt: null,
+        role,
+        requestId,
+        sessionId,
+        prompt,
+        toolCall,
+        batchId,
+        heartbeats: [],
+        lastBeatAt: null,
+        status: 'queued'
+    };
+    writeAtomic(safePath, record);
+    return { path: safePath, record };
+}
+/** Append a heartbeat (G6). Idempotent on (at, status) — append-only. */
+export function appendHeartbeat(input) {
+    const { recordPath, status, progress, note } = input;
+    const now = input.now ?? (() => new Date());
+    if (!Number.isInteger(progress) || progress < 0 || progress > 100) {
+        const err = new Error(`progress must be integer 0..100 (got ${progress})`);
+        err.code = 'INVALID_PROGRESS';
+        throw err;
+    }
+    if (note !== undefined && note.length > 200) {
+        const err = new Error(`note must be ≤ 200 chars (got ${note.length})`);
+        err.code = 'NOTE_TOO_LONG';
+        throw err;
+    }
+    const existing = readRecord(recordPath);
+    const entry = {
+        at: now().toISOString(),
+        status,
+        progress,
+        note: note ?? null
+    };
+    const { heartbeats, truncated } = applyTruncation([...existing.heartbeats, entry]);
+    const next = {
+        ...existing,
+        heartbeats,
+        lastBeatAt: entry.at,
+        status: mapStatusToAggregate(status, existing.status)
+    };
+    writeAtomic(recordPath, next);
+    return { record: next, truncated };
+}
+/** Apply truncation: keep most recent 100, mark truncated flag. */
+export function applyTruncation(entries) {
+    if (entries.length <= 100) {
+        return { heartbeats: [...entries], truncated: false };
+    }
+    return { heartbeats: entries.slice(-100), truncated: true };
+}
+function mapStatusToAggregate(latest, current) {
+    // 'stale' is a poller-driven warning and must not be overwritten by
+    // a normal heartbeat that arrives after the stale flag was set.
+    if (current === 'stale') {
+        return 'stale';
+    }
+    return latest;
+}
+/** Mark a record as completed (success / failed / cancelled / no-execution). */
+export function markCompleted(input) {
+    const existing = readRecord(input.recordPath);
+    const next = {
+        ...existing,
+        completedAt: (input.now ?? (() => new Date()))().toISOString(),
+        outcome: input.outcome,
+        status: input.status,
+        artifactPaths: input.artifactPaths ?? existing.artifactPaths
+    };
+    writeAtomic(input.recordPath, next);
+    return { record: next };
+}
+/** Mark a record as disposed (reducer ran). */
+export function markDisposed(recordPath, now = () => new Date()) {
+    const existing = readRecord(recordPath);
+    const next = {
+        ...existing,
+        disposed: true,
+        disposedAt: now().toISOString()
+    };
+    writeAtomic(recordPath, next);
+    return { record: next };
+}
+/**
+ * Read a dispatch record with backward-compat defaults. Old records
+ * missing G5 / G6 fields are upgraded on read (no error, no overwrite).
+ */
+export function readRecord(recordPath) {
+    if (!existsSync(recordPath)) {
+        const err = new Error(`Dispatch record not found: ${recordPath}`);
+        err.code = 'RECORD_NOT_FOUND';
+        err.path = recordPath;
+        throw err;
+    }
+    const raw = readFileSync(recordPath, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const err = new Error(`Invalid dispatch record JSON: ${error.message}`);
+        err.code = 'INVALID_RECORD_JSON';
+        throw err;
+    }
+    return upgradeRecord(parsed);
+}
+/** Read multiple records from a list of paths. Tolerates missing files. */
+export function readRecords(paths) {
+    const out = [];
+    for (const p of paths) {
+        try {
+            out.push(readRecord(p));
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'RECORD_NOT_FOUND') {
+                continue;
+            }
+            throw error;
+        }
+    }
+    return out;
+}
+function upgradeRecord(parsed) {
+    if (!isObject(parsed)) {
+        throw new Error('Dispatch record root must be an object');
+    }
+    const obj = parsed;
+    const role = stringField(obj, 'role');
+    const requestId = stringField(obj, 'requestId');
+    const sessionId = stringField(obj, 'sessionId');
+    const prompt = stringField(obj, 'prompt');
+    const toolCall = obj.toolCall;
+    if (!isObject(toolCall) || typeof toolCall.name !== 'string') {
+        throw new Error('Dispatch record toolCall must be { name, args }');
+    }
+    const createdAt = stringField(obj, 'createdAt');
+    const heartbeats = Array.isArray(obj.heartbeats)
+        ? obj.heartbeats.filter(isValidHeartbeat)
+        : [];
+    const lastBeatAt = typeof obj.lastBeatAt === 'string' ? obj.lastBeatAt : null;
+    const status = isDispatchStatus(obj.status) ? obj.status : 'no-execution';
+    const completedAt = typeof obj.completedAt === 'string' ? obj.completedAt : null;
+    const outcome = isOutcome(obj.outcome) ? obj.outcome : 'no-execution';
+    const artifactPaths = Array.isArray(obj.artifactPaths)
+        ? obj.artifactPaths.filter((p) => typeof p === 'string')
+        : [];
+    const disposed = obj.disposed === true;
+    const disposedAt = typeof obj.disposedAt === 'string' ? obj.disposedAt : null;
+    const batchId = typeof obj.batchId === 'string' && obj.batchId.length > 0
+        ? obj.batchId
+        : 'legacy-batch';
+    return {
+        version: 2,
+        createdAt,
+        completedAt,
+        outcome,
+        artifactPaths,
+        disposed,
+        disposedAt,
+        role,
+        requestId,
+        sessionId,
+        prompt,
+        toolCall,
+        batchId,
+        heartbeats,
+        lastBeatAt,
+        status
+    };
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function stringField(obj, key) {
+    const v = obj[key];
+    if (typeof v !== 'string') {
+        throw new Error(`Dispatch record field '${key}' must be a string (got ${typeof v})`);
+    }
+    return v;
+}
+function isValidHeartbeat(v) {
+    if (!isObject(v))
+        return false;
+    return (typeof v.at === 'string' &&
+        isHeartbeatStatus(v.status) &&
+        typeof v.progress === 'number' &&
+        (v.note === null || typeof v.note === 'string'));
+}
+function isHeartbeatStatus(v) {
+    return (v === 'queued' || v === 'running' || v === 'finalizing' ||
+        v === 'done' || v === 'failed' || v === 'stale');
+}
+function isDispatchStatus(v) {
+    return (v === 'queued' || v === 'running' || v === 'finalizing' ||
+        v === 'done' || v === 'failed' || v === 'cancelled' ||
+        v === 'no-execution' || v === 'stale');
+}
+function isOutcome(v) {
+    return (v === 'success' || v === 'failed' || v === 'timeout' ||
+        v === 'cancelled' || v === 'no-execution');
+}
+export { isDispatchStatus, isOutcome };
+function writeAtomic(path, record) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    const safeTmp = resolve(dir, tmp.split(/[\\/]/).pop());
+    writeFileSync(safeTmp, JSON.stringify(record, null, 2) + '\n', 'utf8');
+    renameSync(safeTmp, path);
+}

package/dist/src/services/dispatch/heartbeat-truncator.d.ts

@@ -0,0 +1,26 @@
+/**
+ * G6.4 / RL-16 — heartbeat truncation helper.
+ *
+ * Each dispatch record keeps an append-only `heartbeats[]` array so
+ * reducers / auditors can reconstruct what the sub-agent did. Without
+ * a cap, a long-running sub-agent can blow the record JSON past 1 MB
+ * (a 30s cadence over a 1-hour run = 120 entries * ~120 bytes = ~14 KB;
+ * a 5s cadence over 24h = 17 000 entries * ~120 bytes = ~2 MB). The
+ * 100-entry cap is LLM-friendly: stale heartbeats are not informative
+ * once the poller has read them, so dropping the oldest ones is a
+ * non-event.
+ *
+ * Pure helper; no IO. The writer in `dispatch-record-writer.ts` calls
+ * this on every `appendHeartbeat`. Exposed as a separate module so
+ * tests can pin the contract.
+ */
+import type { Heartbeat } from './dispatch-record-writer.js';
+export declare const HEARTBEAT_TRUNCATE_LIMIT = 100;
+export interface TruncationResult {
+    readonly heartbeats: readonly Heartbeat[];
+    readonly truncated: boolean;
+    /** The number of entries dropped by this truncation. */
+    readonly dropped: number;
+}
+/** Apply the 100-entry cap. Returns the most recent N entries + a flag. */
+export declare function truncateHeartbeats(entries: readonly Heartbeat[]): TruncationResult;

package/dist/src/services/dispatch/heartbeat-truncator.js

@@ -0,0 +1,13 @@
+export const HEARTBEAT_TRUNCATE_LIMIT = 100;
+/** Apply the 100-entry cap. Returns the most recent N entries + a flag. */
+export function truncateHeartbeats(entries) {
+    if (entries.length <= HEARTBEAT_TRUNCATE_LIMIT) {
+        return { heartbeats: [...entries], truncated: false, dropped: 0 };
+    }
+    const start = entries.length - HEARTBEAT_TRUNCATE_LIMIT;
+    return {
+        heartbeats: entries.slice(start),
+        truncated: true,
+        dropped: start
+    };
+}

package/dist/src/services/dispatch/leak-detector.d.ts

@@ -0,0 +1,11 @@
+import { type DispatchRecord } from './dispatch-record-writer.js';
+export declare const DEFAULT_LEAK_THRESHOLD_MS: number;
+export interface LeakedRecord {
+    readonly path: string;
+    readonly record: DispatchRecord;
+    readonly ageMs: number;
+}
+export declare function findLeakedDispatchRecords(projectRoot: string, sessionId: string, options?: {
+    now?: () => Date;
+    thresholdMs?: number;
+}): readonly LeakedRecord[];

package/dist/src/services/dispatch/leak-detector.js

@@ -0,0 +1,72 @@
+/**
+ * Slice #009 / G5 RL-7 — dispatch record leak detector.
+ *
+ * After peaks-solo's reducer consumes a batch, any dispatch record that
+ * is still `disposed === false` AND was created more than `thresholdMs`
+ * ago is a **leak**. This helper scans the on-disk records under
+ * `.peaks/_sub_agents/<sid>/` and returns the leaked ones. The CLI or
+ * the reducer's next-batch step emits a user-visible warning when the
+ * list is non-empty.
+ *
+ * Threshold: 1h (configurable). Rationale: the longest empirical
+ * peaks-rd / peaks-qa fan-out + reducer cycle is < 60s; the threshold
+ * gives slow slices headroom without hiding leaks for the next session.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDispatchStatus, isOutcome } from './dispatch-record-writer.js';
+export const DEFAULT_LEAK_THRESHOLD_MS = 60 * 60 * 1000; // 1 hour
+export function findLeakedDispatchRecords(projectRoot, sessionId, options = {}) {
+    const now = options.now ?? (() => new Date());
+    const thresholdMs = options.thresholdMs ?? DEFAULT_LEAK_THRESHOLD_MS;
+    const nowMs = now().getTime();
+    const dir = join(projectRoot, '.peaks', '_sub_agents', sessionId);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        if (!entry.startsWith('dispatch-') || !entry.endsWith('.json'))
+            continue;
+        const fullPath = join(dir, entry);
+        let raw;
+        try {
+            raw = readFileSync(fullPath, 'utf8');
+        }
+        catch {
+            continue; // skip unreadable files
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            continue; // skip malformed files
+        }
+        if (!isRecordShape(parsed))
+            continue;
+        if (parsed.disposed === true)
+            continue;
+        const createdMs = Date.parse(parsed.createdAt);
+        if (Number.isNaN(createdMs))
+            continue;
+        const ageMs = nowMs - createdMs;
+        if (ageMs < thresholdMs)
+            continue;
+        out.push({ path: fullPath, record: parsed, ageMs });
+    }
+    return out;
+}
+function isRecordShape(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const obj = v;
+    return (typeof obj.createdAt === 'string' &&
+        typeof obj.role === 'string' &&
+        typeof obj.requestId === 'string' &&
+        typeof obj.sessionId === 'string' &&
+        typeof obj.prompt === 'string' &&
+        isOutcome(obj.outcome) &&
+        isDispatchStatus(obj.status) &&
+        typeof obj.disposed === 'boolean' &&
+        Array.isArray(obj.artifactPaths));
+}

package/dist/src/services/dispatch/sub-agent-dispatcher.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Slice #009 — SubAgentDispatcher abstraction.
+ *
+ * Per-IDE contract: given a sub-agent role + prompt + request/session ids,
+ * return a tool-call descriptor that the calling LLM should execute in
+ * its native environment. The CLI is IDE-agnostic; per-IDE tool names
+ * (Claude Code's `Task`, Trae's UNVERIFIED placeholder) are encapsulated
+ * here, never leaked to SKILL.md.
+ *
+ * Why this exists:
+ *   - Prior SKILL.md hardcoded `Task(subagent_type="general-purpose", ...)`
+ *     which made peaks-cli depend on Claude Code's specific sub-agent
+ *     tool name. Adding a new IDE (Trae, future Cursor, etc.) required
+ *     editing every SKILL.md that mentioned sub-agent dispatch.
+ *   - This file (plus the per-IDE adapter wiring) collapses all
+ *     per-IDE sub-agent specifics to a single `SubAgentDispatcher`
+ *     instance per adapter. SKILL.md now only references
+ *     `peaks sub-agent dispatch <role>`, and the IDE-private tool
+ *     name flows through the returned `data.toolCall` at runtime.
+ *
+ * Cross-reference: PRD #002 G1 (AC-1..AC-5); RD tech-doc-002 §2.
+ */
+/**
+ * Role string namespace. Soft whitelist — the CLI does NOT hard-validate
+ * specific role names. Empirically observed (peaks-qa SKILL.md): 3 top
+ * roles + 3 sub-roles + arbitrary business subdivisions:
+ *
+ *   - top:           rd | qa | ui | txt | general-purpose
+ *   - qa sub-roles:  qa-business | qa-perf | qa-security
+ *   - business细分:  qa-business-regression | qa-business-api
+ *                    | qa-business-frontend | ...
+ *   - promotable:    prd-business | prd-technical | prd-ux |
+ *                    ui-visual | ui-flow | ui-component | ...
+ *
+ * Any non-empty string is a valid role. CLI emits a "soft whitelist"
+ * hint in --help but does not reject unknown values.
+ */
+export type SubAgentRole = string;
+/**
+ * IDE-private tool-call descriptor. The LLM, upon receiving this in
+ * the CLI's JSON envelope, must invoke the tool named `name` in its
+ * own environment with the provided `args`.
+ */
+export interface SubAgentToolCall {
+    readonly name: string;
+    readonly args: Readonly<Record<string, unknown>>;
+}
+/**
+ * Input to `buildToolCall`. The CLI assembles this from the user's
+ * command-line args (role, prompt) + state-machine lookups
+ * (requestId, sessionId).
+ */
+export interface SubAgentDispatchInput {
+    readonly role: SubAgentRole;
+    readonly prompt: string;
+    readonly requestId: string;
+    readonly sessionId: string;
+}
+/**
+ * Per-IDE sub-agent dispatcher contract. Each IdeAdapter exposes
+ * one of these; the CLI calls `buildToolCall` after validating
+ * `supportsRole` (and `null-dispatcher` is the fallback when an
+ * IDE cannot dispatch sub-agents at all).
+ */
+export interface SubAgentDispatcher {
+    /**
+     * Short label used in envelope `ide` field and CLI help text.
+     * e.g. "claude-code" / "trae" / "null".
+     */
+    readonly label: string;
+    /**
+     * Whether this dispatcher supports dispatching a given role.
+     * claude-code returns true for all non-empty strings; trae is
+     * byte-identical (UNVERIFIED pending real Trae dogfood);
+     * null-dispatcher always returns false.
+     */
+    supportsRole(role: SubAgentRole): boolean;
+    /**
+     * Build the IDE-specific tool call descriptor for a dispatch.
+     * Must be pure: no I/O, no side effects. The CLI wraps the
+     * returned descriptor in its JSON envelope.
+     */
+    buildToolCall(input: SubAgentDispatchInput): SubAgentToolCall;
+}
+/**
+ * Claude Code dispatcher. Real, byte-level implementation.
+ *
+ *   - `supportsRole`: any non-empty string (Claude Code's
+ *     `general-purpose` sub-agent accepts any prompt).
+ *   - `buildToolCall`: returns `{name: 'Task', args: {subagent_type,
+ *     description, prompt}}` — the exact shape the `Task` tool
+ *     in Claude Code expects.
+ */
+export declare const claudeCodeSubAgentDispatcher: SubAgentDispatcher;
+/**
+ * Trae dispatcher. UNVERIFIED — Trae sub-agent tool name TBD on real
+ * dogfood. Byte-level identical to claude-code by design so:
+ *   1. The slice #008 `subAgentToolMatcher: 'Task'` install entry
+ *      stays byte-stable (the generated `.trae/settings.json` does
+ *      not change).
+ *   2. The dispatcher's return shape is uniform across both
+ *      adapters — a single byte-equality test can verify the
+ *      placeholder contract.
+ *
+ * When real Trae dogfood lands, replace the body of `buildToolCall`
+ * with Trae's actual sub-agent tool name + args shape. The interface
+ * stays the same; only the per-IDE wiring breaks (intentionally).
+ */
+export declare const traeSubAgentDispatcher: SubAgentDispatcher;
+/**
+ * Null dispatcher for IDEs that cannot dispatch sub-agents at all
+ * (e.g. a CLI-only IDE that has no LLM tool surface). Used as the
+ * fallback by future unsupported-IDE adapters. The CLI returns
+ * `{ok: false, code: "IDE_NOT_SUPPORTED"}` when the dispatcher's
+ * `supportsRole` returns false.
+ */
+export declare const nullSubAgentDispatcher: SubAgentDispatcher;
+/**
+ * Thrown by `nullSubAgentDispatcher.buildToolCall` and any future
+ * dispatcher that does not support a given role. The CLI catches
+ * this and returns the IDE_NOT_SUPPORTED error envelope.
+ */
+export declare class SubAgentNotSupportedError extends Error {
+    readonly role: SubAgentRole;
+    readonly code: "IDE_NOT_SUPPORTED";
+    constructor(role: SubAgentRole);
+}