peaks-loop 4.1.3 → 4.1.4

package/dist/cli/commands/context-layer-command.js

@@ -0,0 +1,34 @@
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fetchContextLayer, isContextLayer } from './context-layer-fetchers.js';
+/** The two advisory `nextActions` a loaded layer reports. */
+function layerActions(payload) {
+    return [
+        `${payload.layer} loaded: ${payload.byteSize} bytes across ${payload.files.length} file(s)`,
+        payload.warnings.length > 0
+            ? `${payload.warnings.length} warning(s); see envelope.warnings`
+            : null
+    ].filter((x) => typeof x === 'string');
+}
+export function registerContextLayerCommand(context, io) {
+    addJsonOption(context
+        .command('layer')
+        .description('Fetch a context layer (L0 = full SKILL.md; L1 = first paragraph; L2 = index; L3 = fuzzy search by --query)')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--level <L0|L1|L2|L3>', 'context layer to load')
+        .option('--query <text>', 'fuzzy search query (required for L3)')).action(async (options) => {
+        try {
+            if (!isContextLayer(options.level)) {
+                printResult(io, fail('context.layer', 'INVALID_LEVEL', `level must be one of L0, L1, L2, L3 (got ${options.level})`, { provided: options.level }, ['Pass --level L0|L1|L2|L3']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const payload = await fetchContextLayer(options.level, options.project, options.query ?? '');
+            printResult(io, ok('context.layer', payload, [], layerActions(payload)), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('context.layer', 'CONTEXT_LAYER_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path and --level value']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/context-layer-fetchers.d.ts

@@ -0,0 +1,15 @@
+export type ContextLayer = 'L0' | 'L1' | 'L2' | 'L3';
+export interface LayerPayload {
+    readonly layer: ContextLayer;
+    readonly description: string;
+    readonly files: readonly {
+        path: string;
+        bytes: number;
+    }[];
+    readonly content: string;
+    readonly byteSize: number;
+    readonly warnings: readonly string[];
+}
+/** Dispatch one layer by its validated `L0|L1|L2|L3` id. */
+export declare function fetchContextLayer(level: ContextLayer, projectRoot: string, query: string): Promise<LayerPayload>;
+export declare function isContextLayer(value: string): value is ContextLayer;

package/dist/cli/commands/context-layer-fetchers.js

@@ -0,0 +1,162 @@
+/**
+ * The four context layers the `peaks context layer` verb can fetch.
+ *
+ *   - L0: full read (every SKILL.md in full)
+ *   - L1: summary (one paragraph per skill + the skill list)
+ *   - L2: index (just names + paths)
+ *   - L3: fuzzy search by query (delegates to peaks memory search)
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { searchMemory } from '../../services/memory/memory-search-service.js';
+import { getErrorMessage } from '../cli-helpers.js';
+const SKILLS_DIR = 'skills';
+/** Fallback preview length for a skill whose body has no blank-line paragraph break. */
+const L1_PREVIEW_CHARS = 400;
+/** How much of an L3 hit's description is echoed into the search listing. */
+const L3_DESCRIPTION_CHARS = 120;
+function readSkillsDir(projectRoot) {
+    const skillsRoot = join(projectRoot, SKILLS_DIR);
+    if (!existsSync(skillsRoot))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const skillMd = join(skillsRoot, entry.name, 'SKILL.md');
+        if (existsSync(skillMd)) {
+            out.push(`skills/${entry.name}/SKILL.md`);
+        }
+    }
+    return out;
+}
+function readSkillFile(projectRoot, relPath) {
+    const abs = join(projectRoot, relPath);
+    try {
+        return readFileSync(abs, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+/** Concatenate every SKILL.md in full. */
+async function fetchL0(projectRoot) {
+    const files = readSkillsDir(projectRoot);
+    const warnings = [];
+    let content = '';
+    let byteSize = 0;
+    const sizes = [];
+    for (const rel of files) {
+        const body = readSkillFile(projectRoot, rel);
+        if (body.length === 0) {
+            warnings.push(`failed to read ${rel}`);
+            continue;
+        }
+        content += `## ${rel}\n\n${body}\n\n`;
+        sizes.push({ path: rel, bytes: body.length });
+        byteSize += body.length;
+    }
+    return {
+        layer: 'L0',
+        description: 'full read: every SKILL.md concatenated',
+        files: sizes,
+        content,
+        byteSize,
+        warnings
+    };
+}
+/** One paragraph (or a bounded preview) per skill. */
+async function fetchL1(projectRoot) {
+    const files = readSkillsDir(projectRoot);
+    const warnings = [];
+    let content = '';
+    let byteSize = 0;
+    const sizes = [];
+    for (const rel of files) {
+        const body = readSkillFile(projectRoot, rel);
+        if (body.length === 0) {
+            warnings.push(`failed to read ${rel}`);
+            continue;
+        }
+        const firstPara = body.split(/\r?\n\r?\n/, 2)[0] ?? body.slice(0, L1_PREVIEW_CHARS);
+        content += `## ${rel}\n\n${firstPara}\n\n`;
+        sizes.push({ path: rel, bytes: firstPara.length });
+        byteSize += firstPara.length;
+    }
+    return {
+        layer: 'L1',
+        description: 'summary: first paragraph per skill',
+        files: sizes,
+        content,
+        byteSize,
+        warnings
+    };
+}
+/** Names and paths only, no bodies. */
+async function fetchL2(projectRoot) {
+    const files = readSkillsDir(projectRoot);
+    const content = files.map((f) => `- ${f}`).join('\n') + '\n';
+    const byteSize = content.length;
+    return {
+        layer: 'L2',
+        description: 'index: skill paths only (no body)',
+        files: files.map((f) => ({ path: f, bytes: 0 })),
+        content,
+        byteSize,
+        warnings: []
+    };
+}
+/** Top 10 memory-search hits for `query`; a failure rides `warnings`. */
+async function fetchL3(projectRoot, query) {
+    const warnings = [];
+    if (query.trim().length === 0) {
+        warnings.push('empty query; L3 requires a --query string for fuzzy search');
+        return {
+            layer: 'L3',
+            description: 'fuzzy search (empty query)',
+            files: [],
+            content: '',
+            byteSize: 0,
+            warnings
+        };
+    }
+    try {
+        const hits = searchMemory({ projectRoot, query, limit: 10 });
+        const lines = [];
+        for (const hit of hits) {
+            lines.push(`- [${hit.score.toFixed(2)}] ${hit.sourcePath}: ${hit.description.slice(0, L3_DESCRIPTION_CHARS)}`);
+        }
+        const content = lines.join('\n') + '\n';
+        return {
+            layer: 'L3',
+            description: 'fuzzy search: top 10 hits from memory index',
+            files: hits.map((h) => ({ path: h.sourcePath, bytes: h.description.length })),
+            content,
+            byteSize: content.length,
+            warnings
+        };
+    }
+    catch (error) {
+        return {
+            layer: 'L3',
+            description: 'fuzzy search (failed)',
+            files: [],
+            content: '',
+            byteSize: 0,
+            warnings: [`L3 search failed: ${getErrorMessage(error)}`]
+        };
+    }
+}
+/** Dispatch one layer by its validated `L0|L1|L2|L3` id. */
+export async function fetchContextLayer(level, projectRoot, query) {
+    if (level === 'L0')
+        return fetchL0(projectRoot);
+    if (level === 'L1')
+        return fetchL1(projectRoot);
+    if (level === 'L2')
+        return fetchL2(projectRoot);
+    return fetchL3(projectRoot, query);
+}
+export function isContextLayer(value) {
+    return value === 'L0' || value === 'L1' || value === 'L2' || value === 'L3';
+}

package/dist/cli/commands/context-status-command.d.ts

@@ -0,0 +1,17 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export type ContextThresholdOptions = {
+    promptSize: string;
+    capacity?: string;
+    inFlightBatch?: boolean;
+    autoTrigger?: boolean;
+    json?: boolean;
+};
+/** `--capacity` override, or `undefined` to let the monitor use its default. */
+export declare function capacityOf(opts: ContextThresholdOptions): number | undefined;
+/**
+ * Parse `--prompt-size`, refusing a non-finite or negative value; `null` once
+ * the refusal envelope for `command` has been printed.
+ */
+export declare function requirePromptSize(command: string, opts: ContextThresholdOptions, io: ProgramIO): number | null;
+export declare function registerContextStatusCommand(context: Command, io: ProgramIO): void;

package/dist/cli/commands/context-status-command.js

@@ -0,0 +1,41 @@
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { evaluateMainSessionThreshold } from '../../services/context/main-session-monitor.js';
+import { detectIdeFromEnv } from '../../services/context/ide-detect.js';
+/** `--capacity` override, or `undefined` to let the monitor use its default. */
+export function capacityOf(opts) {
+    return opts.capacity !== undefined ? Number(opts.capacity) : undefined;
+}
+/**
+ * Parse `--prompt-size`, refusing a non-finite or negative value; `null` once
+ * the refusal envelope for `command` has been printed.
+ */
+export function requirePromptSize(command, opts, io) {
+    const promptSize = Number(opts.promptSize);
+    if (Number.isFinite(promptSize) && promptSize >= 0)
+        return promptSize;
+    printResult(io, fail(command, 'INVALID_PROMPT_SIZE', `prompt-size must be a non-negative number (got "${opts.promptSize}")`, { provided: opts.promptSize }, ['Pass --prompt-size <bytes>']), opts.json);
+    process.exitCode = 1;
+    return null;
+}
+export function registerContextStatusCommand(context, io) {
+    addJsonOption(context
+        .command('status')
+        .description('v2.11.0 D6: report main-session threshold tier for a given prompt size (no trigger dispatched). Useful for `--json` probes before invoking `peaks context check --auto-trigger`.')
+        .requiredOption('--prompt-size <bytes>', 'estimated prompt size in bytes')
+        .option('--capacity <bytes>', 'override the 256K default capacity (test seam)', '262144')).action((opts) => {
+        try {
+            const promptSize = requirePromptSize('context.status', opts, io);
+            if (promptSize === null)
+                return;
+            const evaluation = evaluateMainSessionThreshold(promptSize, capacityOf(opts));
+            printResult(io, ok('context.status', { ...evaluation, ide: detectIdeFromEnv() }, [...evaluation.warnings], [`Main-session tier=${evaluation.tier} (${(evaluation.ratio * 100).toFixed(0)}%)`]), opts.json);
+        }
+        catch (err) {
+            printResult(io, fail('context.status', 'CONTEXT_STATUS_FAILED', getErrorMessage(err), null, [
+                'Verify --prompt-size is a non-negative number'
+            ]), opts.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/contract-write-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerContractCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/contract-write-command.js

@@ -0,0 +1,144 @@
+// src/cli/commands/contract-write-command.ts
+//
+// `peaks contract write` — persist a finished slice's public surface (exports /
+// types / publicSignatures) to
+// `.peaks/_runtime/<sessionId>/dispatch/contracts/<slice-id>.json`, where the
+// orchestrator picks it up on the next dispatch run. Extracted from
+// `governance-classify-contract-commands.ts` (which had merged
+// `contract-commands.ts` and `classify-classify-commands.ts` verbatim); the
+// registered name, description, options, refusal codes and envelope are
+// unchanged.
+//
+// The guards and the write are separate functions because the merged file had
+// all three inline in one 151-line registrar, and every branch there was over
+// the per-function line cap on its own.
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { writeContract } from '../../services/dispatch/contract-store.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+const INPUT_LIMIT_BYTES = 256 * 1024;
+/** Split a comma-separated flag value into a trimmed string array. */
+function splitCsv(value) {
+    if (value === undefined)
+        return [];
+    return value
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+export function registerContractCommands(program, io) {
+    const contract = program
+        .command('contract')
+        .description('Slice contract store (skill-first / CLI-auxiliary). These commands ' +
+        'are primitives that peaks-code / peaks-rd SKILL.md compose. The LLM-side ' +
+        'runner (the IDE-resident sub-agent that finished a slice) calls ' +
+        "`peaks contract write` to persist the slice's public surface; the " +
+        'orchestrator picks it up on the next dispatch run via listContracts() ' +
+        'and splices it into downstream prompts via formatContractInjection().');
+    addJsonOption(contractWriteCommand(contract)).action((options) => {
+        const envelope = contractWriteEnvelope(options);
+        printResult(io, envelope, options.json === true);
+        if (!envelope.ok)
+            process.exitCode = 1;
+    });
+}
+// peaks contract write --project <root> --session-id <sid>
+//   --slice-id <id> --exports <a,b> --types <x,y> --signatures <s1,s2>
+//   [--broadcast-to <b1,b2>] [--completed-at <iso>]
+function contractWriteCommand(contract) {
+    return contract
+        .command('write')
+        .description("2.7.0 slice-dag-dispatcher MVP: persist a finished slice's public " +
+        'surface (exports / types / publicSignatures) to disk at ' +
+        '.peaks/_runtime/<sessionId>/dispatch/contracts/<slice-id>.json. ' +
+        'The orchestrator picks it up on the next dispatch run. Idempotent: ' +
+        're-running with the same inputs overwrites in place; the SHA-256 ' +
+        'contractHash is content-derived so a contract write from a different ' +
+        'runner (re-execution) is detected as a content change.')
+        .option('--project <path>', 'target project root (defaults to cwd)')
+        .option('--session-id <sid>', 'session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback "unknown-sid")')
+        .requiredOption('--slice-id <id>', 'slice id; must be non-empty; used as the contract filename basename')
+        .option('--exports <list>', 'comma-separated public export names (e.g. "validateDag,topologicalLevels")')
+        .option('--types <list>', 'comma-separated public type names (e.g. "SliceDag,SliceNode")')
+        .option('--signatures <list>', 'comma-separated public function/method signatures (e.g. "validateDag(dag: SliceDag): void")')
+        .option('--broadcast-to <list>', 'comma-separated downstream slice ids that should auto-inherit this contract (e.g. "B,C")')
+        .option('--completed-at <iso>', 'ISO 8601 timestamp; defaults to now()');
+}
+/** The written-contract envelope, or the refusal the caller earned. */
+function contractWriteEnvelope(options) {
+    const projectRoot = options.project ?? process.cwd();
+    const sid = options.sessionId ??
+        process.env['PEAKS_SESSION_ID'] ??
+        getCurrentSessionId(projectRoot) ??
+        'unknown-sid';
+    const lists = {
+        exports: splitCsv(options.exports),
+        types: splitCsv(options.types),
+        signatures: splitCsv(options.signatures),
+        broadcastTo: splitCsv(options.broadcastTo)
+    };
+    const refusal = contractWriteRefusal(options, sid, lists);
+    if (refusal !== null)
+        return refusal;
+    try {
+        const result = writeContract(projectRoot, sid, contractWriteInput(options, sid, lists));
+        return ok('contract.write', contractWriteData(result), [], [
+            'Contract written; orchestrator will pick it up on the next `peaks sub-agent dispatch --from-dag` run.',
+            'Re-running with the same inputs is idempotent (overwrites in place).'
+        ]);
+    }
+    catch (err) {
+        return fail('contract.write', 'WRITE_ERROR', getErrorMessage(err), { path: null, contract: null }, [
+            'See error message; check that --project is a writable directory and --slice-id is a valid filename basename (no path separators).'
+        ]);
+    }
+}
+/**
+ * The `writeContract` input: `--broadcast-to` and `--completed-at` ride only
+ * when the caller set them, so an absent flag never becomes an empty value.
+ */
+function contractWriteInput(options, sid, lists) {
+    return {
+        // The refusal above already rejected `undefined` / empty.
+        sliceId: options.sliceId,
+        sessionId: sid,
+        exports: lists.exports,
+        types: lists.types,
+        publicSignatures: lists.signatures,
+        ...(lists.broadcastTo.length > 0 ? { broadcastTo: lists.broadcastTo } : {}),
+        ...(options.completedAt !== undefined ? { completedAt: options.completedAt } : {})
+    };
+}
+/** The written contract, counted per surface — never the raw store row. */
+function contractWriteData(result) {
+    return {
+        path: result.path,
+        contractHash: result.contract.contractHash,
+        sliceId: result.contract.sliceId,
+        sessionId: result.contract.sessionId,
+        completedAt: result.contract.completedAt,
+        exportCount: result.contract.exports.length,
+        typeCount: result.contract.types.length,
+        signatureCount: result.contract.publicSignatures.length,
+        broadcastTo: result.contract.broadcastTo ?? []
+    };
+}
+/** The two pre-write refusals (missing slice id, oversized input), or `null`. */
+function contractWriteRefusal(options, sid, lists) {
+    const sliceId = options.sliceId;
+    if (sliceId === undefined || sliceId.length === 0) {
+        return fail('contract.write', 'MISSING_SLICE_ID', '--slice-id is required', { path: null, contract: null }, ['Re-run with --slice-id <id> (must be non-empty; used as the contract filename basename).']);
+    }
+    // Cap the combined input to protect the file IO from runaway values
+    // (e.g. a 10MB comma-separated --signatures flag).
+    const inputSize = sliceId.length +
+        sid.length +
+        lists.exports.join(',').length +
+        lists.types.join(',').length +
+        lists.signatures.join(',').length +
+        lists.broadcastTo.join(',').length +
+        (options.completedAt?.length ?? 0);
+    if (inputSize <= INPUT_LIMIT_BYTES)
+        return null;
+    return fail('contract.write', 'INPUT_TOO_LARGE', `combined input size ${inputSize} bytes exceeds ${INPUT_LIMIT_BYTES} (likely oversized --exports/--types/--signatures lists)`, { path: null, contract: null }, ['Split the slice into smaller surfaces or omit optional fields.']);
+}

package/dist/cli/commands/core/doctor-bindings.d.ts

@@ -0,0 +1,17 @@
+export type BindingSource = 'canonical' | 'legacy';
+/** One stale entry in the project-level binding. */
+export type StaleInstance = {
+    sid: string;
+    callerId: string;
+    lastHeartbeat: string;
+};
+export declare const STALE_TTL_MS = 300000;
+export declare function listStaleInstances(projectRoot: string, ttlMs?: number): StaleInstance[];
+/** The `staleBinding` block every doctor envelope carries. */
+export declare function staleBindingSection(ttlMs: number, staleInstances: readonly StaleInstance[], droppedStale: readonly string[]): {
+    ttlMs: number;
+    staleCount: number;
+    staleInstances: readonly StaleInstance[];
+    droppedCount: number;
+    droppedSids: readonly string[];
+};

package/dist/cli/commands/core/doctor-bindings.js

@@ -0,0 +1,30 @@
+import { readBinding } from '../../../services/session/binding-store.js';
+// threshold is exposed as a CLI flag so users can tune it for
+// long-running sessions. 300000 ms = 5 minutes.
+export const STALE_TTL_MS = 300_000;
+// in the project-level binding. Used by `peaks doctor` and surfaced as
+// a warning in the report. Returns the stale entry descriptors.
+export function listStaleInstances(projectRoot, ttlMs = STALE_TTL_MS) {
+    const binding = readBinding(projectRoot);
+    if (!binding)
+        return [];
+    const cutoff = Date.now() - ttlMs;
+    const stale = [];
+    for (const [sid, inst] of Object.entries(binding.instances)) {
+        const t = Date.parse(inst.lastHeartbeat);
+        if (Number.isFinite(t) && t < cutoff) {
+            stale.push({ sid, callerId: inst.callerId, lastHeartbeat: inst.lastHeartbeat });
+        }
+    }
+    return stale;
+}
+/** The `staleBinding` block every doctor envelope carries. */
+export function staleBindingSection(ttlMs, staleInstances, droppedStale) {
+    return {
+        ttlMs,
+        staleCount: staleInstances.length,
+        staleInstances,
+        droppedCount: droppedStale.length,
+        droppedSids: droppedStale
+    };
+}

package/dist/cli/commands/core/doctor-command.d.ts

@@ -1,18 +1,4 @@
-import type { Command } from 'commander';
-import { type ProgramIO } from '../../cli-helpers.js';
-/**
- * the doctor envelope. The `checks` array (one object per check, each with a
- * full message) and the stale-binding instance list collapse to counts +
- * names-of-first-N; the summary counters and log section are scalars and are
- * kept verbatim. ≤ 2 KB by construction.
- */
-export declare function buildDoctorSummary(data: Record<string, unknown>): Record<string, unknown>;
-export type BindingSource = 'canonical' | 'legacy';
-export type DoctorLogsSection = {
-    logDir: string;
-    todayFile: string;
-    sizeBytes: number;
-    retentionDays: number;
-    level: string;
-};
-export declare function registerDoctorCommand(program: Command, io: ProgramIO): void;
+export type { BindingSource, StaleInstance } from './doctor-bindings.js';
+export type { DoctorLogsSection } from './doctor-logs.js';
+export { buildDoctorSummary } from './doctor-summary.js';
+export { registerDoctorCommand } from './doctor-run-command.js';