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

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

@@ -1,238 +0,0 @@
-/**
- * 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/src/services/dispatch/sub-agent-dispatcher.d.ts

@@ -1,239 +0,0 @@
-/**
- * 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;