peaks-loop 4.0.0-beta.3 → 4.0.0-beta.30

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

@@ -0,0 +1,460 @@
+/**
+ * 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, statSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { assertSafeDispatchRecordPath, dispatchRecordPath } from '../security/safe-settings-path.js';
+import { withFileLockSync } from 'peaks-loop-shared-channel';
+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,
+        // Slice 2026-06-23-audit-4th #C2: propagate toolCallVersion.
+        // The dispatcher's buildToolCall already stamps it (claude-code 2.0.0
+        // etc.); we re-default to '2.0.0' if absent so the on-disk record
+        // is self-describing without reading the dispatcher source.
+        toolCall: { ...toolCall, toolCallVersion: toolCall.toolCallVersion ?? '2.0.0' },
+        batchId,
+        heartbeats: [],
+        lastBeatAt: null,
+        status: 'queued'
+    };
+    writeAtomic(safePath, record);
+    // Slice 2026-06-23-audit-4th #A4: register the path in the
+    // session's active-dispatches index so a future restart can
+    // discover in-flight records without scanning the directory.
+    // The index is best-effort (no lock): the on-disk record is the
+    // source of truth; the index is purely a hint for the LLM-side
+    // runner. A crash between writeAtomic and the index write is
+    // non-fatal — the next restart scans the directory anyway.
+    registerActiveDispatch({
+        projectRoot,
+        sessionId,
+        recordPath: safePath,
+        requestId,
+        role,
+        batchId,
+        now
+    });
+    return { path: safePath, record };
+}
+function activeDispatchIndexPath(projectRoot, sessionId) {
+    return resolve(projectRoot, '.peaks', '_sub_agents', sessionId, 'active-dispatches.json');
+}
+function registerActiveDispatch(input) {
+    const indexPath = activeDispatchIndexPath(input.projectRoot, input.sessionId);
+    const dir = dirname(indexPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    let index = {};
+    try {
+        if (existsSync(indexPath)) {
+            const raw = readFileSync(indexPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed === 'object' && parsed !== null) {
+                for (const [k, v] of Object.entries(parsed)) {
+                    if (typeof v === 'object' && v !== null && 'recordPath' in v) {
+                        index[k] = v;
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // Corrupt index — start fresh. The on-disk record is the source of truth.
+        index = {};
+    }
+    index[input.recordPath] = {
+        recordPath: input.recordPath,
+        requestId: input.requestId,
+        role: input.role,
+        batchId: input.batchId,
+        createdAt: input.now().toISOString(),
+        status: 'queued'
+    };
+    const tmp = `${indexPath}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify(index, null, 2) + '\n', 'utf8');
+    renameSync(tmp, indexPath);
+}
+function unregisterActiveDispatch(input) {
+    const indexPath = activeDispatchIndexPath(input.projectRoot, input.sessionId);
+    if (!existsSync(indexPath))
+        return;
+    let index = {};
+    try {
+        const raw = readFileSync(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null) {
+            for (const [k, v] of Object.entries(parsed)) {
+                if (typeof v === 'object' && v !== null && 'recordPath' in v) {
+                    index[k] = v;
+                }
+            }
+        }
+    }
+    catch {
+        return;
+    }
+    if (input.recordPath in index) {
+        index[input.recordPath] = { ...index[input.recordPath], status: input.status };
+        if (input.status === 'done' || input.status === 'failed' || input.status === 'cancelled' || input.status === 'no-execution') {
+            delete index[input.recordPath];
+        }
+        const tmp = `${indexPath}.tmp-${process.pid}-${Date.now()}`;
+        writeFileSync(tmp, JSON.stringify(index, null, 2) + '\n', 'utf8');
+        renameSync(tmp, indexPath);
+    }
+}
+/**
+ * Slice 2026-06-23-audit-4th #A4: read the active-dispatches index
+ * for a session. Returns the current map<recordPath, entry>. Used
+ * by the LLM-side runner to discover in-flight records on restart.
+ * Returns an empty map when the index file is missing or corrupt
+ * (the on-disk records directory is the next fallback).
+ */
+export function readActiveDispatchIndex(projectRoot, sessionId) {
+    const indexPath = activeDispatchIndexPath(projectRoot, sessionId);
+    if (!existsSync(indexPath))
+        return {};
+    try {
+        const raw = readFileSync(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v === 'object' && v !== null && 'recordPath' in v && 'role' in v) {
+                out[k] = v;
+            }
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** Slice 2026-06-23-audit-4th #A3: default TTL for dispatch records. */
+export const DISPATCH_RECORD_TTL_DAYS = 30;
+/**
+ * Slice 2026-06-23-audit-4th #A3: is this dispatch record an orphan
+ * (older than DISPATCH_RECORD_TTL_DAYS or already GC'd)? Mirrors
+ * `isOrphanChannel` in shared-channel.ts so a future
+ * `peaks sub-agent cleanup` umbrella can run all three sweeps
+ * (shared channel + dispatch record + contract) in one pass.
+ */
+export function isOrphanDispatchRecord(opts) {
+    if (!existsSync(opts.recordPath))
+        return true;
+    const s = statSync(opts.recordPath);
+    const now = opts.now ?? new Date();
+    const ageMs = now.getTime() - s.mtimeMs;
+    const ttlMs = DISPATCH_RECORD_TTL_DAYS * 24 * 60 * 60 * 1000;
+    return ageMs > ttlMs;
+}
+/** 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)
+    };
+    // Slice 2026-06-23-audit-3rd #3: wrap the read-then-write in a file
+    // lock. Without the lock, a heartbeat arriving 100ms before
+    // markCompleted can be silently discarded — the parent's view of the
+    // sub-agent shows "completed" but the last progress update is lost.
+    return withFileLockSync(recordPath, () => {
+        // Re-read under the lock — the file may have been mutated between
+        // our pre-lock `readRecord` above and lock acquisition (heartbeats
+        // and markCompleted share the same record file).
+        const lockedExisting = readRecord(recordPath);
+        const lockedHeartbeats = applyTruncation([
+            ...lockedExisting.heartbeats,
+            entry
+        ]).heartbeats;
+        const lockedNext = {
+            ...lockedExisting,
+            heartbeats: lockedHeartbeats,
+            lastBeatAt: entry.at,
+            status: mapStatusToAggregate(status, lockedExisting.status)
+        };
+        writeAtomic(recordPath, lockedNext);
+        // Recompute truncated flag from the locked-read result so the
+        // caller sees the actual post-lock truncation state.
+        return {
+            record: lockedNext,
+            truncated: lockedHeartbeats.length < lockedExisting.heartbeats.length + 1
+        };
+    });
+}
+/** 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) {
+    // Slice 2026-06-23-audit-3rd #3: lock + re-read so a concurrent
+    // heartbeat arriving just before markCompleted is preserved in the
+    // final record.
+    const result = withFileLockSync(input.recordPath, () => {
+        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 };
+    });
+    // Slice 2026-06-23-audit-4th #A4: update the active-dispatches
+    // index. Best-effort (the on-disk record is the source of truth);
+    // we only attempt the update when the trusted projectRoot is
+    // available so a malicious recordPath cannot redirect the index
+    // write (audit-3rd #1 anti-pattern).
+    if (typeof input.projectRoot === 'string' && input.projectRoot.length > 0) {
+        try {
+            unregisterActiveDispatch({
+                projectRoot: input.projectRoot,
+                sessionId: result.record.sessionId,
+                recordPath: input.recordPath,
+                status: input.status
+            });
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            /* best-effort */
+        }
+    }
+    return result;
+}
+/** Mark a record as disposed (reducer ran). */
+export function markDisposed(recordPath, now = () => new Date()) {
+    // Lock + re-read (see markCompleted).
+    return withFileLockSync(recordPath, () => {
+        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');
+    // Slice 2026-06-23-audit-4th #C2: preserve toolCallVersion on read.
+    // Pre-versioning records default to '2.0.0' (the pre-#C2 implicit
+    // shape; matches the version stamped by every current dispatcher).
+    const rawToolCall = obj.toolCall;
+    if (!isObject(rawToolCall) || typeof rawToolCall.name !== 'string') {
+        throw new Error('Dispatch record toolCall must be { name, args }');
+    }
+    const toolCall = {
+        name: rawToolCall.name,
+        args: (isObject(rawToolCall.args) ? rawToolCall.args : {}),
+        ...(typeof rawToolCall.toolCallVersion === 'string' ? { toolCallVersion: rawToolCall.toolCallVersion } : { toolCallVersion: '2.0.0' })
+    };
+    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);
+    // Slice 2026-06-23-audit-3rd #11: skip mkdirSync when the dir already
+    // exists (every heartbeat + every dispatch read-modify-write).
+    if (!existsSync(dir)) {
+        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/services/ide/adapters/zcode-adapter.d.ts

@@ -0,0 +1,40 @@
+import type { IdeAdapter } from '../ide-types.js';
+/**
+ * Helper exported for tests + internal use: the default location of the
+ * z-code v2 config file on the host filesystem.
+ */
+export declare function defaultZcodeConfigPath(): string;
+/**
+ * Resolve the active model id from a parsed z-code config payload
+ * (the `~/.zcode/v2/config.json` root object). Pure / exported for
+ * unit tests so the file-IO seam and the resolution seam are
+ * independently verifiable.
+ *
+ * Resolution order (Slice C §"z-code config 解析路径"):
+ *   P1. env var `PEAKS_ZCODE_ACTIVE_PROVIDER_UUID` (test seam +
+ *       manual pin for the user).
+ *   P2. The provider whose top-level UUID key is NOT prefixed
+ *       `builtin:` — this matches the user-installed provider
+ *       pattern. Within that provider, prefer its `models` first
+ *       key (insertion order — z-code writes the active model
+ *       first in the picker).
+ *   P3. The first provider with `enabled: true`.
+ *   P4. The first provider in the object (insertion order) — last
+ *       resort. Returns undefined if there are zero providers.
+ *
+ * Returns `undefined` when nothing matches.
+ */
+export declare function resolveZcodeCurrentModel(config: unknown, envOverride?: string | undefined): string | undefined;
+/**
+ * The async adapter method that `detectCurrentIdeModel()` calls.
+ *
+ * Resolution order:
+ *   1. `PEAKS_ZCODE_ACTIVE_PROVIDER_UUID` env var override (test seam
+ *      + manual pin).
+ *   2. `PEAKS_ZCODE_CONFIG_PATH` env var override (test seam for a
+ *      fixture file). Falls back to `~/.zcode/v2/config.json`.
+ *   3. Returns `undefined` when the file is missing / malformed
+ *      (consistent with the cross-IDE contract).
+ */
+export declare function detectZcodeCurrentModel(): Promise<string | undefined>;
+export declare const ZCODE_ADAPTER: IdeAdapter;