peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/dispatch/slice-dag.js

@@ -0,0 +1,238 @@
+/**
+ * Slice DAG model — 2.7.0 slice-dag-dispatcher MVP (slice 1.2.a).
+ *
+ * Pure function module. No I/O. No external state.
+ *
+ * Types:
+ *   - `SliceNode` — a single unit of work (e.g. "implement CLI dispatch").
+ *   - `DependsOn` — directed edge from `to` to `from` (i.e. `to` runs after `from`).
+ *   - `SliceDag` — `{ nodes, edges }`. The graph MUST be a DAG.
+ *
+ * Constraints (validated by `validateDag`):
+ *   1. No cycles.
+ *   2. Node IDs are globally unique.
+ *   3. Every edge endpoints reference existing node IDs.
+ *   4. Node `role` is a non-empty string (whitelist hint, not a strict check).
+ *
+ * Why this lives outside `sub-agent-dispatcher.ts`:
+ *   The dispatcher is a per-IDE adapter; the DAG is a logical plan. Keeping
+ *   them split keeps the adapter file IDE-shape-focused and the DAG file
+ *   plan-shape-focused. Both are pure.
+ *
+ * Hash stability:
+ *   `serializeDag` sorts nodes by `id` and edges by `(from, to)` so the
+ *   resulting JSON string is stable across object-literal ordering. The
+ *   SHA-256 hash is therefore reproducible for the same logical DAG.
+ */
+import { createHash } from 'node:crypto';
+export const SLICE_COMPLEXITIES = [
+    'trivial',
+    'simple',
+    'complex'
+];
+export function isSliceComplexity(value) {
+    return SLICE_COMPLEXITIES.includes(value);
+}
+/** Thrown by `validateDag` when the graph violates one of the constraints. */
+export class InvalidSliceDagError extends Error {
+    path;
+    code = 'INVALID_SLICE_DAG';
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = 'InvalidSliceDagError';
+    }
+}
+/** Thrown by `topologicalLevels` when the graph has a cycle (defensive). */
+export class SliceDagCycleError extends Error {
+    cyclePath;
+    code = 'SLICE_DAG_CYCLE';
+    constructor(cyclePath) {
+        super(`cycle detected in slice DAG: ${cyclePath.join(' -> ')}`);
+        this.cyclePath = cyclePath;
+        this.name = 'SliceDagCycleError';
+    }
+}
+/**
+ * Validate a SliceDag. Throws `InvalidSliceDagError` on the first violation.
+ * Pure. Cheap. No I/O.
+ */
+export function validateDag(dag) {
+    if (!dag || !Array.isArray(dag.nodes) || !Array.isArray(dag.edges)) {
+        throw new InvalidSliceDagError('dag must have nodes and edges arrays');
+    }
+    if (dag.nodes.length === 0) {
+        throw new InvalidSliceDagError('dag must have at least one node');
+    }
+    const seen = new Set();
+    for (const n of dag.nodes) {
+        if (!n || typeof n.id !== 'string' || n.id.length === 0) {
+            throw new InvalidSliceDagError('every node must have a non-empty id');
+        }
+        if (typeof n.role !== 'string' || n.role.length === 0) {
+            throw new InvalidSliceDagError(`node ${n.id} must have a non-empty role`);
+        }
+        if (seen.has(n.id)) {
+            throw new InvalidSliceDagError(`duplicate node id: ${n.id}`);
+        }
+        seen.add(n.id);
+    }
+    for (const e of dag.edges) {
+        if (!e || typeof e.from !== 'string' || typeof e.to !== 'string') {
+            throw new InvalidSliceDagError('every edge must have string from/to');
+        }
+        if (!seen.has(e.from)) {
+            throw new InvalidSliceDagError(`edge references unknown node: ${e.from}`);
+        }
+        if (!seen.has(e.to)) {
+            throw new InvalidSliceDagError(`edge references unknown node: ${e.to}`);
+        }
+        if (e.from === e.to) {
+            throw new InvalidSliceDagError(`self-loop not allowed: ${e.from}`);
+        }
+    }
+    // v2.15.0 follow-up — G12: validate optional new fields ONLY when present
+    // (老 DAG 不强制要求新字段,保持向后兼容).
+    for (const n of dag.nodes) {
+        if (n.foundation !== undefined && typeof n.foundation !== 'boolean') {
+            throw new InvalidSliceDagError(`node ${n.id} foundation must be boolean when present`);
+        }
+        if (n.upstreamSync !== undefined && typeof n.upstreamSync !== 'boolean') {
+            throw new InvalidSliceDagError(`node ${n.id} upstreamSync must be boolean when present`);
+        }
+        if (n.complexity !== undefined && !isSliceComplexity(n.complexity)) {
+            throw new InvalidSliceDagError(`node ${n.id} complexity must be one of ${SLICE_COMPLEXITIES.join('|')} when present`);
+        }
+    }
+    // v2.15.0 follow-up — G12 defensive rule: foundation slice can only
+    // depend on another foundation slice. Business depending on foundation
+    // is the main use case; foundation depending on business is a smell.
+    const foundationSet = new Set(dag.nodes.filter((n) => n.foundation === true).map((n) => n.id));
+    for (const e of dag.edges) {
+        if (foundationSet.has(e.to) && !foundationSet.has(e.from)) {
+            throw new InvalidSliceDagError(`foundation slice ${e.to} cannot depend on non-foundation slice ${e.from}`);
+        }
+    }
+}
+/**
+ * Compute topological levels. Each level is an array of node IDs that can
+ * run in parallel. Throws `SliceDagCycleError` on cycle (defensive;
+ * `validateDag` should have caught it).
+ *
+ * Algorithm: Kahn's algorithm. O(V + E).
+ */
+export function topologicalLevels(dag) {
+    validateDag(dag);
+    const indeg = new Map();
+    const adj = new Map();
+    // v2.15.0 follow-up — G12: priority sets for foundation / upstreamSync.
+    const foundationSet = new Set(dag.nodes.filter((n) => n.foundation === true).map((n) => n.id));
+    const upstreamSyncSet = new Set(dag.nodes.filter((n) => n.upstreamSync === true).map((n) => n.id));
+    for (const n of dag.nodes) {
+        indeg.set(n.id, 0);
+        adj.set(n.id, []);
+    }
+    for (const e of dag.edges) {
+        // Edge `from -> to` means `to` depends on `from`; `to` has one more incoming.
+        indeg.set(e.to, (indeg.get(e.to) ?? 0) + 1);
+        adj.get(e.from)?.push(e.to);
+    }
+    const levels = [];
+    let frontier = dag.nodes.map((n) => n.id).filter((id) => (indeg.get(id) ?? 0) === 0);
+    const consumed = new Set();
+    while (frontier.length > 0) {
+        // v2.15.0 follow-up — G12: sort frontier by (foundation desc,
+        // upstreamSync desc, id asc). Stable across calls.
+        const sortedFrontier = [...frontier].sort((a, b) => {
+            const aF = foundationSet.has(a) ? 1 : 0;
+            const bF = foundationSet.has(b) ? 1 : 0;
+            if (aF !== bF)
+                return bF - aF;
+            const aU = upstreamSyncSet.has(a) ? 1 : 0;
+            const bU = upstreamSyncSet.has(b) ? 1 : 0;
+            if (aU !== bU)
+                return bU - aU;
+            return a < b ? -1 : a > b ? 1 : 0;
+        });
+        levels.push(sortedFrontier);
+        const next = [];
+        for (const id of sortedFrontier) {
+            consumed.add(id);
+            for (const succ of adj.get(id) ?? []) {
+                const d = (indeg.get(succ) ?? 0) - 1;
+                indeg.set(succ, d);
+                if (d === 0 && !consumed.has(succ)) {
+                    next.push(succ);
+                }
+            }
+        }
+        frontier = next;
+    }
+    if (consumed.size !== dag.nodes.length) {
+        // Find a cycle path for the error message.
+        const remaining = dag.nodes.map((n) => n.id).filter((id) => !consumed.has(id));
+        throw new SliceDagCycleError(remaining);
+    }
+    return levels;
+}
+/**
+ * Return the next set of node IDs that are ready to run given the set of
+ * completed node IDs. A node is ready when all of its `from` predecessors
+ * are in `completed`.
+ */
+export function sliceReadyToRun(dag, completed) {
+    validateDag(dag);
+    const done = new Set(completed);
+    const predecessors = new Map();
+    for (const n of dag.nodes) {
+        predecessors.set(n.id, []);
+    }
+    for (const e of dag.edges) {
+        predecessors.get(e.to)?.push(e.from);
+    }
+    const ready = [];
+    for (const n of dag.nodes) {
+        if (done.has(n.id))
+            continue;
+        const preds = predecessors.get(n.id) ?? [];
+        if (preds.every((p) => done.has(p))) {
+            ready.push(n.id);
+        }
+    }
+    return ready.sort();
+}
+/**
+ * Serialize the DAG into a deterministic JSON string. Node IDs are sorted;
+ * edges are sorted by `(from, to)`. The result is suitable for SHA-256
+ * hashing and for byte-stable diffs.
+ */
+export function serializeDag(dag) {
+    validateDag(dag);
+    const nodes = [...dag.nodes]
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+        .map((n) => ({
+        id: n.id,
+        role: n.role,
+        ...(n.label !== undefined ? { label: n.label } : {}),
+        ...(n.prompt !== undefined ? { prompt: n.prompt } : {}),
+        // v2.15.0 follow-up — G12: include new fields in serialization
+        // (only when present, preserving hash stability for old DAGs).
+        ...(n.foundation !== undefined ? { foundation: n.foundation } : {}),
+        ...(n.upstreamSync !== undefined ? { upstreamSync: n.upstreamSync } : {}),
+        ...(n.complexity !== undefined ? { complexity: n.complexity } : {})
+    }));
+    const edges = [...dag.edges]
+        .sort((a, b) => {
+        if (a.from !== b.from)
+            return a.from < b.from ? -1 : 1;
+        if (a.to !== b.to)
+            return a.to < b.to ? -1 : 1;
+        return 0;
+    })
+        .map((e) => ({ from: e.from, to: e.to }));
+    return JSON.stringify({ nodes, edges });
+}
+/** SHA-256 hash of the serialized DAG. Stable across runs. */
+export function hashDag(dag) {
+    return createHash('sha256').update(serializeDag(dag)).digest('hex');
+}

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

@@ -0,0 +1,239 @@
+/**
+ * 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>>;
+    /**
+     * Slice 2026-06-23-audit-4th #C2: toolCall version. The IDE's
+     * arg shape can change between versions (e.g. Claude Code's
+     * `subagent_type: "general-purpose"` may become
+     * `subagent_type: "claude-code-3.5"` in a future release). The
+     * dispatcher stamps this on `buildToolCall`; the dispatch record
+     * propagates it so a future reader can detect "this record is for
+     * v2.0 Task, current IDE is v3.0" without inspecting args.
+     * Pre-versioning records default to '2.0.0' on read.
+     */
+    readonly toolCallVersion?: string;
+}
+/**
+ * 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;
+    /**
+    * 2.7.0 slice-dag-dispatcher MVP: join barrier for a batch of dispatched
+    * sub-agents. Returns one BatchResult per dispatch in the batch.
+    *
+    * Default implementation in this MVP (1.2): claude-code holds an
+    * in-process Promise queue (LRU-keyed by batchId); the four non-Claude
+    * IDEs (trae / trae-cn / codex / cursor) return a
+    * `awaitByLlm: true` marker so the calling LLM holds the await itself
+    * — envelope shape is uniform. Real per-IDE implementations land in
+    * 1.3.
+    *
+    * `nullSubAgentDispatcher` throws `SubAgentNotSupportedError` here.
+    */
+    awaitBatch?(input: SubAgentAwaitBatchInput): Promise<readonly SubAgentBatchResult[]>;
+}
+/**
+ * 2.7.0 slice-dag-dispatcher MVP: input to the optional `awaitBatch` method.
+ * MVP dispatch is one batch per top-level `peaks sub-agent dispatch --from-dag`
+ * call; `batchId` is the same one returned in the dispatch envelope.
+ */
+export interface SubAgentAwaitBatchInput {
+    readonly batchId: string;
+    readonly dispatchCount: number;
+    /** Per-dispatch record path; CLI already has this from the dispatch envelope. */
+    readonly recordPaths: readonly string[];
+    /** Optional cap on how long the join should wait. */
+    readonly timeoutMs?: number;
+}
+/**
+ * 2.7.0 slice-dag-dispatcher MVP: per-dispatch result of a join barrier.
+ * The CLI returns one of these per dispatch in the batch.
+ */
+export interface SubAgentBatchResult {
+    readonly dispatchIndex: number;
+    readonly recordPath: string;
+    readonly status: 'done' | 'failed' | 'cancelled' | 'timeout';
+    readonly durationMs: number;
+    readonly note: string | null;
+}
+/**
+ * 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:
+ * - The dispatcher's return shape is uniform across both adapters
+ * — a single byte-equality test can verify the placeholder
+ * contract.
+ * - Future real Trae dogfood can replace the body of
+ * `buildToolCall` without breaking the adapter contract.
+ *
+ * Slice #014: the legacy `subAgentToolMatcher: 'Task'` install entry
+ * is gone — the field is removed from `IdeAdapter`. Slice #009+
+ * dispatched sub-agents directly, not via a PreToolUse hook. The Trae
+ * dispatcher remains a placeholder so the dispatch surface is uniform
+ * across adapters.
+ *
+ * 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;
+/**
+ * Trae-CN dispatcher. Mirrors Trae's shape with a separate label so
+ * the CLI's IDE detection can distinguish a Trae install region
+ * (Trae-CN differs in skill install path / log location only;
+ * dispatch surface is identical per slice #011 framework rule).
+ *
+ * Slice 1.3: real `awaitBatch` — same polling core as Trae.
+ */
+export declare const traeCnSubAgentDispatcher: SubAgentDispatcher;
+/**
+ * Codex (OpenAI CLI IDE) dispatcher.
+ *
+ * Slice #13 noted Codex's sub-agent tool name is TBD; per slice #009
+ * rationale, the dispatcher mirrors Claude Code's shape so the
+ * adapter contract stays uniform. Slice 1.3 promotes Codex from
+ * `awaitByLlmFallback` to a real `awaitBatch` (file-based polling,
+ * Codex default 45s — Codex's documented heartbeat is slightly
+ * slower per slice #13 R-3).
+ */
+export declare const codexSubAgentDispatcher: SubAgentDispatcher;
+/**
+ * Cursor dispatcher. UNVERIFIED — Cursor sub-agent tool name TBD on
+ * real dogfood. Byte-level identical to claude-code by design (slice
+ * #012 framing).
+ *
+ * Slice 1.3: real `awaitBatch` — file-based polling, Cursor default
+ * 30s.
+ */
+export declare const cursorSubAgentDispatcher: 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);
+}
+/**
+ * Real awaitBatch for claude-code (MVP). In 1.2, dispatch + await are
+ * both in the same process; we record the batch size and resolve after
+ * `dispatchCount` heartbeats land for the given `recordPaths`, or after
+ * `timeoutMs` elapses (per-dispatch `timeout` status).
+ *
+ * Implementation contract (MVP):
+ *  - We poll each `recordPaths[i]` for an `outcome: success | failed` or
+ *    `status: done | failed` field; if absent after `timeoutMs`, that
+ *    dispatch is reported as `timeout`.
+ *  - The poll interval is 50ms (fast enough for unit tests, cheap enough
+ *    for the MVP; the real cross-process version uses heartbeat polling).
+ */
+export declare function awaitClaudeCodeBatch(input: SubAgentAwaitBatchInput): Promise<readonly SubAgentBatchResult[]>;
+/**
+ * Slice 1.3 — shared per-IDE polling core for trae / trae-cn / codex /
+ * cursor. Same polling loop shape as `awaitClaudeCodeBatch`, with
+ * per-IDE default timeout + note prefix. The 4 IDEs differ only in
+ * (a) `defaultTimeoutMs` (Trae / Trae-CN / Cursor = 30s, Codex = 45s
+ * per slice #13 R-3) and (b) the `note` label surfaced when an IDE
+ * times out (so 1.4 dogfood can attribute a timeout to the right
+ * IDE).
+ *
+ * MVP rationale (per Karpathy §2 Simplicity First): the 4 IDEs
+ * currently share the same file-based polling transport. The only
+ * per-IDE distinction is the timeout + label. Future per-IDE
+ * divergence (real IPC / shell hooks) is a 1.4 dogfood concern —
+ * here we keep the dispatcher interface uniform while each IDE's
+ * `awaitBatch` is now a real implementation rather than the 1.2
+ * `awaitByLlmFallback` marker.
+ */
+export interface PollDispatchRecordsOptions {
+    readonly ide: 'trae' | 'trae-cn' | 'codex' | 'cursor';
+    readonly defaultTimeoutMs: number;
+    readonly notePrefix: string;
+}
+export declare function pollDispatchRecords(input: SubAgentAwaitBatchInput, opts: PollDispatchRecordsOptions): Promise<readonly SubAgentBatchResult[]>;
+/**
+ * 1.2 fallback for trae / trae-cn / codex / cursor. Deprecated by
+ * slice 1.3 — kept exported for legacy callers + back-compat tests
+ * (the 1.2 marker is still a valid envelope shape; the 1.4 dogfood
+ * tests can compare the marker note vs the 1.3 real note to verify
+ * per-IDE attribution).
+ */
+export declare function awaitByLlmFallback(input: SubAgentAwaitBatchInput, ide: string): Promise<readonly SubAgentBatchResult[]>;
+/**
+ * In-process awaiter registration hook (used by `peaks sub-agent dispatch`
+ * to attach a resolver; not part of the dispatcher public surface).
+ * Reserved for slice 1.3 cross-process upgrade.
+ */
+export declare function registerClaudeCodeAwaiter(batchId: string, awaiter: Promise<readonly SubAgentBatchResult[]>): void;