peaks-loop 4.1.3 → 4.1.4

package/dist/cli/commands/dispatch-dag-envelope.js

@@ -0,0 +1,49 @@
+import { ok } from 'peaks-loop-shared/result';
+/**
+ * Per-slice scheduling metadata (foundation / upstreamSync / complexity) for
+ * the level-1 slices the envelope surfaces.
+ */
+function sliceMetaFor(ids, dag, isSliceComplexity) {
+    return ids.map((id) => {
+        const node = dag.nodes.find((n) => n.id === id);
+        return {
+            id,
+            foundation: node?.foundation === true,
+            upstreamSync: node?.upstreamSync === true,
+            complexity: node?.complexity !== undefined && isSliceComplexity(node.complexity)
+                ? node.complexity
+                : null
+        };
+    });
+}
+/** The `ok('sub-agent.dispatch', …)` envelope for a completed `--from-dag` run. */
+export function buildDagSuccessEnvelope(input) {
+    const { role, ide, fromDag, batchId, levelsTotal, emittedSliceIds, emittedToolCalls, firstLevelWaves, existingContractCount, dag, isSliceComplexity } = input;
+    const dispatchCount = emittedSliceIds.length;
+    return ok('sub-agent.dispatch', {
+        envelopeVersion: '2.1.0',
+        role,
+        ide,
+        fromDag,
+        batchId,
+        dispatchCount,
+        levelsTotal,
+        firstLevel: emittedSliceIds,
+        firstLevelWaves,
+        toolCalls: emittedToolCalls,
+        existingContractCount,
+        expectedCompletionSeconds: 60,
+        artifactsPublicPaths: [],
+        orchestratorVisibleHint: `⏳ Spawning ${dispatchCount} sub-agents via Task tool from DAG ${fromDag}, batch-id=${batchId} (ETA ~60s)`,
+        sliceMeta: sliceMetaFor(emittedSliceIds, dag, isSliceComplexity),
+        nextActions: [
+            'Execute each toolCall in your IDE; on completion, write the slice contract to .peaks/_runtime/<sid>/dispatch/contracts/<slice-id>.json.',
+            'Re-invoke `peaks sub-agent dispatch --from-dag <file>` with the same batch-id to advance to the next level once all current-level slices have written contracts.'
+        ]
+    }, [], [
+        'MVP (1.2) plans the first level via runLayeredDag orchestrator (cancel-on-fail path active); the LLM drives subsequent levels by re-invoking this command after contract writes.',
+        existingContractCount > 0
+            ? `Injected ${existingContractCount} upstream contract(s) into downstream-level prompts via formatContractInjection.`
+            : 'No upstream contracts found; first-level prompts have empty ancestor blocks.'
+    ]);
+}

package/dist/cli/commands/dispatch-dag-failure.d.ts

@@ -0,0 +1,18 @@
+import { type ProgramIO } from '../cli-helpers.js';
+/** One refusal from the `--from-dag` path, as the fields the envelope needs. */
+export type DagFailure = {
+    readonly role: string;
+    readonly code: string;
+    readonly message: string;
+    readonly extra?: Record<string, unknown>;
+    readonly nextActions: readonly string[];
+};
+/**
+ * Emit a `sub-agent.dispatch` failure envelope and mark the process failed.
+ *
+ * Returns `null` so every caller can read `if (readDag(...) === null) return;`
+ * — the three statements (print, exit code, return) are one decision and stay
+ * together, which is also what keeps each call site inside
+ * `max-lines-per-function`.
+ */
+export declare function emitDagFailure(io: ProgramIO, asJson: boolean, failure: DagFailure): null;

package/dist/cli/commands/dispatch-dag-failure.js

@@ -0,0 +1,16 @@
+import { fail } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+/**
+ * Emit a `sub-agent.dispatch` failure envelope and mark the process failed.
+ *
+ * Returns `null` so every caller can read `if (readDag(...) === null) return;`
+ * — the three statements (print, exit code, return) are one decision and stay
+ * together, which is also what keeps each call site inside
+ * `max-lines-per-function`.
+ */
+export function emitDagFailure(io, asJson, failure) {
+    const { role, code, message, extra, nextActions } = failure;
+    printResult(io, fail('sub-agent.dispatch', code, message, { role, toolCall: null, dispatchRecordPath: null, ...extra }, [...nextActions]), asJson);
+    process.exitCode = 1;
+    return null;
+}

package/dist/cli/commands/dispatch-dag-preflight.d.ts

@@ -0,0 +1,51 @@
+import type { SliceDag } from '../../services/dispatch/slice-dag.js';
+import type { ProgramIO } from '../cli-helpers.js';
+import { type DispatchOptions } from './sub-agent-shared.js';
+/** The three things every refusal in this path needs to be emitted. */
+export type DagScope = {
+    readonly role: string;
+    readonly asJson: boolean;
+    readonly io: ProgramIO;
+};
+/** Identity every `--from-dag` envelope is stamped with. */
+export type DagIds = {
+    readonly projectRoot: string;
+    readonly sid: string;
+    readonly rid: string;
+    readonly batchId: string;
+};
+/**
+ * Resolve the project root + the four ids the DAG envelope reports.
+ *
+ * The sid falls back through `PEAKS_SESSION_ID` and the canonical binding
+ * before the `unknown-sid` sentinel; the rid keeps its `unknown-rid` default
+ * when the caller passed none.
+ */
+export declare function resolveDagIds(options: DispatchOptions): DagIds;
+/**
+ * Lazy-load the three heavy modules only when `--from-dag` is actually used.
+ *
+ * The warm-path single dispatch does NOT load slice-dag / dag-orchestrator /
+ * contract-store (slice 9 perf); the dynamic-import promise resolves on first
+ * call and ESM caches the module for subsequent calls in the same process.
+ */
+export declare function loadDagRuntime(): Promise<{
+    readFileSync: typeof import("fs").readFileSync;
+    validateDag: typeof import("../../services/dispatch/slice-dag.js").validateDag;
+    topologicalLevels: typeof import("../../services/dispatch/slice-dag.js").topologicalLevels;
+    isSliceComplexity: typeof import("../../services/dispatch/slice-dag-types.js").isSliceComplexity;
+    runLayeredDag: typeof import("../../services/code/dag-orchestrator.js").runLayeredDag;
+    listContracts: typeof import("../../services/dispatch/contract-store.js").listContracts;
+    hashContract: typeof import("../../services/dispatch/contract-store.js").hashContract;
+}>;
+export type DagRuntime = Awaited<ReturnType<typeof loadDagRuntime>>;
+/** Read + `JSON.parse` + `validateDag` the DAG file; `null` once refused. */
+export declare function readDagOrFail(runtime: DagRuntime, fromDag: string, scope: DagScope): SliceDag | null;
+/**
+ * Each DAG node must map to an explicitly prepared workflow graph node before
+ * sub-agent dispatch. The mapping is the `graphNode` annotation on the node,
+ * or — as a back-compat fallback — the node id itself.
+ */
+export declare function assertGraphNodesMapped(dag: SliceDag, scope: DagScope): true | null;
+/** Topologically order the DAG's nodes; `null` once the failure is emitted. */
+export declare function topologicalLevelsOrFail(runtime: DagRuntime, dag: SliceDag, fromDag: string, scope: DagScope): readonly (readonly string[])[] | null;

package/dist/cli/commands/dispatch-dag-preflight.js

@@ -0,0 +1,105 @@
+import { randomUUID } from 'node:crypto';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { emitDagFailure } from './dispatch-dag-failure.js';
+/**
+ * Resolve the project root + the four ids the DAG envelope reports.
+ *
+ * The sid falls back through `PEAKS_SESSION_ID` and the canonical binding
+ * before the `unknown-sid` sentinel; the rid keeps its `unknown-rid` default
+ * when the caller passed none.
+ */
+export function resolveDagIds(options) {
+    const projectRoot = options.project ?? process.cwd();
+    return {
+        projectRoot,
+        sid: options.sessionId ??
+            process.env.PEAKS_SESSION_ID ??
+            getCurrentSessionId(projectRoot) ??
+            'unknown-sid',
+        rid: options.requestId ?? 'unknown-rid',
+        batchId: options.batchId ?? randomUUID()
+    };
+}
+/**
+ * Lazy-load the three heavy modules only when `--from-dag` is actually used.
+ *
+ * The warm-path single dispatch does NOT load slice-dag / dag-orchestrator /
+ * contract-store (slice 9 perf); the dynamic-import promise resolves on first
+ * call and ESM caches the module for subsequent calls in the same process.
+ */
+export async function loadDagRuntime() {
+    const [{ readFileSync }, sliceDagMod, dagOrchestratorMod, contractStoreMod] = await Promise.all([
+        import('node:fs'),
+        import('../../services/dispatch/slice-dag.js'),
+        import('../../services/code/dag-orchestrator.js'),
+        import('../../services/dispatch/contract-store.js')
+    ]);
+    return {
+        readFileSync,
+        validateDag: sliceDagMod.validateDag,
+        topologicalLevels: sliceDagMod.topologicalLevels,
+        isSliceComplexity: sliceDagMod.isSliceComplexity,
+        runLayeredDag: dagOrchestratorMod.runLayeredDag,
+        listContracts: contractStoreMod.listContracts,
+        hashContract: contractStoreMod.hashContract
+    };
+}
+/** Read + `JSON.parse` + `validateDag` the DAG file; `null` once refused. */
+export function readDagOrFail(runtime, fromDag, scope) {
+    try {
+        const raw = runtime.readFileSync(fromDag, 'utf8');
+        const parsed = JSON.parse(raw);
+        runtime.validateDag(parsed);
+        return parsed;
+    }
+    catch (err) {
+        return emitDagFailure(scope.io, scope.asJson, {
+            role: scope.role,
+            code: 'INVALID_DAG',
+            message: `failed to read or validate DAG from ${fromDag}: ${err.message}`,
+            nextActions: [
+                'Check the JSON file at the given path; the DAG must have {nodes, edges} and pass validateDag().'
+            ]
+        });
+    }
+}
+/**
+ * Each DAG node must map to an explicitly prepared workflow graph node before
+ * sub-agent dispatch. The mapping is the `graphNode` annotation on the node,
+ * or — as a back-compat fallback — the node id itself.
+ */
+export function assertGraphNodesMapped(dag, scope) {
+    for (const node of dag.nodes) {
+        const graphNodeId = node.graphNode;
+        const candidate = typeof graphNodeId === 'string' && graphNodeId.length > 0 ? graphNodeId : node.id;
+        if (typeof candidate === 'string' && candidate.length > 0)
+            continue;
+        return emitDagFailure(scope.io, scope.asJson, {
+            role: scope.role,
+            code: 'PEAKS_GRAPH_NODE_REQUIRED',
+            message: `DAG node ${node.id} has no graph-node mapping (RD §4 D4c)`,
+            extra: { dagNodeId: node.id },
+            nextActions: [
+                'Annotate the DAG node with `graphNode: "<id>"` so each dispatch can bind a prepared graph node.'
+            ]
+        });
+    }
+    return true;
+}
+/** Topologically order the DAG's nodes; `null` once the failure is emitted. */
+export function topologicalLevelsOrFail(runtime, dag, fromDag, scope) {
+    try {
+        return runtime.topologicalLevels(dag);
+    }
+    catch (err) {
+        return emitDagFailure(scope.io, scope.asJson, {
+            role: scope.role,
+            code: 'INVALID_DAG',
+            message: `topologicalLevels failed for ${fromDag}: ${err.message}`,
+            nextActions: [
+                'The DAG passed validateDag() but topologicalLevels threw (likely a cycle that slipped past validateDag, or a runtime invariant).',
+                'Inspect the DAG file with the editor and re-invoke dispatch. (No peaks scan dag CLI ships in 2.7.0; if you need a programmatic DAG validator, import validateDag / topologicalLevels from src/services/dispatch/slice-dag.ts directly.)'
+            ]
+        });
+    }
+}

package/dist/cli/commands/dispatch-dag-runners.d.ts

@@ -0,0 +1,48 @@
+import type { SubAgentDispatcher, SubAgentToolCall } from '../../services/dispatch/sub-agent-dispatcher.js';
+import type { SliceDag } from '../../services/dispatch/slice-dag.js';
+import type { DispatchSpec, SliceOutcome } from '../../services/code/dag-orchestrator.js';
+import type { SliceContract, WriteContractInput } from '../../services/dispatch/contract-store.js';
+/** What the CLI runner collected while `runLayeredDag` walked the levels. */
+export type DagEmissions = {
+    readonly toolCalls: SubAgentToolCall[];
+    readonly sliceIds: string[];
+};
+/** The resolved IDE + sub-agent dispatcher the `--from-dag` path runs on. */
+export type DagDispatcher = {
+    readonly ide: string;
+    readonly dispatcher: SubAgentDispatcher;
+};
+/** Detect the IDE and resolve its sub-agent dispatcher. */
+export declare function resolveDagDispatcher(projectRoot: string): DagDispatcher;
+/**
+ * When every first-level node declares `files`, refine the level into
+ * file-overlap waves so the LLM fans out without serializing on a shared
+ * file. Emitted additively; nodes without `files` yield `null` (legacy
+ * envelope).
+ */
+export declare function planFirstLevelWaves(dag: SliceDag, levelArr: readonly (readonly string[])[]): readonly import("../../services/dispatch/file-overlap-wave-planner.js").FileOverlapWave[] | null;
+/**
+ * The CLI runner: emit the per-slice `buildToolCall` descriptor for the first
+ * topological level, then return `done`.
+ *
+ * Returning `done` (not `cancelled`) exercises `runLayeredDag`'s join barrier
+ * and cancel-on-fail path end to end; the placeholder `publicSurface` is
+ * intentionally empty because the real surface arrives later via
+ * `peaks contract write`.
+ */
+export declare function makeCliRunner(args: {
+    firstLevelIds: ReadonlySet<string>;
+    dispatcher: SubAgentDispatcher;
+    ids: {
+        readonly rid: string;
+        readonly sid: string;
+    };
+    emissions: DagEmissions;
+}): (spec: DispatchSpec) => Promise<SliceOutcome>;
+/**
+ * Placeholder contract writer. The CLI writes nothing to disk here — the
+ * LLM-side runner does that via `peaks contract write` — but the returned
+ * placeholder must stay shape-valid: `contractHash` has to be a real SHA-256
+ * hex string computed from the slice identity (`sliceId|sessionId`).
+ */
+export declare function makeNoopWriter(hashContract: (partial: WriteContractInput) => string, sid: string): (sliceId: string) => SliceContract;

package/dist/cli/commands/dispatch-dag-runners.js

@@ -0,0 +1,73 @@
+import { detectInstalledIde } from '../../services/ide/ide-detector.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import { planFileOverlapWaves } from '../../services/dispatch/file-overlap-wave-planner.js';
+/** Detect the IDE and resolve its sub-agent dispatcher. */
+export function resolveDagDispatcher(projectRoot) {
+    const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
+    return { ide, dispatcher: getAdapter(ide).subAgentDispatcher };
+}
+/**
+ * When every first-level node declares `files`, refine the level into
+ * file-overlap waves so the LLM fans out without serializing on a shared
+ * file. Emitted additively; nodes without `files` yield `null` (legacy
+ * envelope).
+ */
+export function planFirstLevelWaves(dag, levelArr) {
+    const descriptors = [...(levelArr[0] ?? [])].map((id) => ({
+        id,
+        files: dag.nodes.find((n) => n.id === id)?.files ?? []
+    }));
+    const allHaveFiles = descriptors.every((d) => d.files.length > 0);
+    return descriptors.length > 0 && allHaveFiles ? planFileOverlapWaves(descriptors).waves : null;
+}
+/**
+ * The CLI runner: emit the per-slice `buildToolCall` descriptor for the first
+ * topological level, then return `done`.
+ *
+ * Returning `done` (not `cancelled`) exercises `runLayeredDag`'s join barrier
+ * and cancel-on-fail path end to end; the placeholder `publicSurface` is
+ * intentionally empty because the real surface arrives later via
+ * `peaks contract write`.
+ */
+export function makeCliRunner(args) {
+    const { firstLevelIds, dispatcher, ids, emissions } = args;
+    return async (spec) => {
+        const toolCall = dispatcher.buildToolCall({
+            role: spec.role,
+            prompt: spec.prompt,
+            requestId: ids.rid,
+            sessionId: ids.sid
+        });
+        if (firstLevelIds.has(spec.sliceId)) {
+            emissions.toolCalls.push(toolCall);
+            emissions.sliceIds.push(spec.sliceId);
+        }
+        return { status: 'done', publicSurface: { exports: [], types: [], publicSignatures: [] } };
+    };
+}
+/**
+ * Placeholder contract writer. The CLI writes nothing to disk here — the
+ * LLM-side runner does that via `peaks contract write` — but the returned
+ * placeholder must stay shape-valid: `contractHash` has to be a real SHA-256
+ * hex string computed from the slice identity (`sliceId|sessionId`).
+ */
+export function makeNoopWriter(hashContract, sid) {
+    return (sliceId) => {
+        const partial = {
+            sliceId,
+            sessionId: sid,
+            exports: [],
+            types: [],
+            publicSignatures: []
+        };
+        return {
+            sliceId,
+            sessionId: sid,
+            completedAt: new Date(0).toISOString(),
+            exports: [],
+            types: [],
+            publicSignatures: [],
+            contractHash: hashContract(partial)
+        };
+    };
+}

package/dist/cli/commands/dispatch-from-dag.d.ts

@@ -1,3 +1,30 @@
+/**
+ * The `--from-dag` path of `peaks sub-agent dispatch`.
+ *
+ * Pulled out of `dispatch-commands.ts` to honor the file-size cap (Karpathy #2
+ * Simplicity First). The single-dispatch action stays in `dispatch-commands.ts`;
+ * the DAG-dispatch path lives here because the two share no logic — the
+ * warm-path single dispatch does NOT load slice-dag / dag-orchestrator /
+ * contract-store (slice 9 perf), while the `--from-dag` codepath loads all
+ * three on first call.
+ *
+ * 2.7.0 slice-dag-dispatcher MVP: read a SliceDag from a file and run it
+ * through `runLayeredDag`. The orchestrator's `runSlice` is a thin wrapper
+ * that emits the per-IDE `buildToolCall` envelope for each topological level.
+ *
+ * 1.2 MVP scope: this dispatches the FIRST topological level synchronously
+ * (returns the dispatch specs); subsequent levels are not surfaced in the CLI
+ * envelope because the LLM-side runner must actually execute each
+ * `buildToolCall` and write the resulting contract before level 2+ can be
+ * safely auto-advanced. The LLM re-invokes `peaks sub-agent dispatch --from-dag
+ * <file> --batch-id <id>` after writing level-1 contracts, which causes
+ * `runLayeredDag` to plan level 2+ with the level-1 ancestor contracts spliced
+ * into their dispatch prompts.
+ *
+ * Internally, `runLayeredDag` DOES iterate all levels so its join-barrier +
+ * cancel-on-fail path is exercised end-to-end during the MVP emit; only the
+ * CLI envelope is filtered to level-1 toolCalls (see `firstLevelIds`).
+ */
 import { type ProgramIO } from '../cli-helpers.js';
 import { type DispatchOptions } from './sub-agent-shared.js';
 export declare function runDispatchFromDag(role: string, options: DispatchOptions, asJson: boolean, io: ProgramIO): Promise<void>;