peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/compact/suggest-service.js

@@ -0,0 +1,203 @@
+/**
+ * `peaks compact suggest` — strategic-compact service layer.
+ *
+ * Mirrors the ECC `suggest-compact.js` PreToolUse hook's two-signal
+ * suggestion logic but as a deterministic, machine-enforced CLI
+ * primitive. Two signals:
+ *
+ *   1. Context size (primary) — read latest usage row from
+ *      `.peaks/_runtime/<sid>/usage.jsonl`. Suggest at
+ *      COMPACT_CONTEXT_THRESHOLD (default 160k on 200k window, 250k
+ *      on 1M window) and re-remind every COMPACT_CONTEXT_INTERVAL
+ *      tokens (default 60k). A 1M window is detected when observed
+ *      tokens exceed 200k AND the `modelKind: '1m'` marker is on
+ *      the latest usage row, or when PEAKS_MODEL_KIND=1m is set.
+ *
+ *   2. Tool-call count (secondary) — read latest tool-call counter
+ *      from the same usage.jsonl. Suggest at COMPACT_THRESHOLD
+ *      (default 50) and re-remind every 25 calls.
+ *
+ * If usage.jsonl is absent (no peaks-loop session yet), fall back to
+ * PEAKS_CONTEXT_TOKENS / PEAKS_TOOL_CALLS env vars. If neither signal
+ * is available, the primitive returns `shouldSuggest: false` and a
+ * `dataUnavailable: true` flag — never throws.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { lookupPhaseTransition, buildSuggestedCompactMessage, SURVIVAL_TABLE } from './decision-tables.js';
+/** Snapshot of the survival table for the dry-run envelope. */
+const SURVIVAL_TABLE_PERSISTS = SURVIVAL_TABLE.persists;
+const SURVIVAL_TABLE_LOST = SURVIVAL_TABLE.lost;
+/** Default tool-call threshold before first suggestion. */
+export const DEFAULT_TOOL_CALL_THRESHOLD = 50;
+/** Default additional tool calls before the suggestion repeats. */
+export const TOOL_CALL_REMIND_STEP = 25;
+/** Default context-size threshold on a 200k window. */
+export const DEFAULT_CONTEXT_THRESHOLD_200K = 160_000;
+/** Default context-size threshold on a 1M window. */
+export const DEFAULT_CONTEXT_THRESHOLD_1M = 250_000;
+/** Default re-remind interval for context size. */
+export const DEFAULT_CONTEXT_INTERVAL = 60_000;
+function readLatestUsageRow(projectRoot, sessionId) {
+    const path = join(projectRoot, '.peaks', '_runtime', sessionId, 'usage.jsonl');
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+        if (lines.length === 0)
+            return null;
+        const last = lines[lines.length - 1];
+        if (last === undefined)
+            return null;
+        return JSON.parse(last);
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function parseIntEnv(env, key, fallback) {
+    const raw = env[key];
+    if (typeof raw !== 'string' || raw.length === 0)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function detectWindowKind(env, observedTokens, rowModelKind) {
+    if (rowModelKind === '1m')
+        return '1m';
+    if (env['PEAKS_MODEL_KIND'] === '1m')
+        return '1m';
+    // Heuristic from SKILL.md: a `[1m]` model marker OR observed tokens
+    // already exceed the 200k window. We use observed as the second
+    // signal only.
+    if (observedTokens > DEFAULT_CONTEXT_THRESHOLD_200K)
+        return '1m';
+    return '200k';
+}
+export function suggestCompact(options) {
+    const env = options.env ?? process.env;
+    const contextThreshold = parseIntEnv(env, 'COMPACT_CONTEXT_THRESHOLD', 0);
+    const contextInterval = parseIntEnv(env, 'COMPACT_CONTEXT_INTERVAL', DEFAULT_CONTEXT_INTERVAL);
+    const toolCallThreshold = parseIntEnv(env, 'COMPACT_THRESHOLD', DEFAULT_TOOL_CALL_THRESHOLD);
+    let tokensUsed = 0;
+    let toolCalls = 0;
+    let modelKind;
+    let source = 'none';
+    if (options.sessionId !== null) {
+        const row = readLatestUsageRow(options.projectRoot, options.sessionId);
+        if (row !== null) {
+            if (typeof row.tokens === 'number' && Number.isFinite(row.tokens))
+                tokensUsed = row.tokens;
+            if (typeof row.toolCalls === 'number' && Number.isFinite(row.toolCalls))
+                toolCalls = row.toolCalls;
+            if (typeof row.modelKind === 'string')
+                modelKind = row.modelKind;
+            source = 'usage-jsonl';
+        }
+    }
+    if (source === 'none') {
+        const envTokens = env['PEAKS_CONTEXT_TOKENS'];
+        if (typeof envTokens === 'string' && envTokens.length > 0) {
+            const parsed = Number.parseInt(envTokens, 10);
+            if (Number.isFinite(parsed) && parsed >= 0) {
+                tokensUsed = parsed;
+                source = 'env-vars';
+            }
+        }
+        const envCalls = env['PEAKS_TOOL_CALLS'];
+        if (typeof envCalls === 'string' && envCalls.length > 0) {
+            const parsed = Number.parseInt(envCalls, 10);
+            if (Number.isFinite(parsed) && parsed >= 0) {
+                toolCalls = parsed;
+                source = 'env-vars';
+            }
+        }
+    }
+    const windowKind = detectWindowKind(env, tokensUsed, modelKind);
+    const windowCapacity = windowKind === '1m' ? 1_000_000 : 200_000;
+    const effectiveContextThreshold = contextThreshold > 0
+        ? contextThreshold
+        : (windowKind === '1m' ? DEFAULT_CONTEXT_THRESHOLD_1M : DEFAULT_CONTEXT_THRESHOLD_200K);
+    const ratio = windowCapacity > 0 ? tokensUsed / windowCapacity : 0;
+    const dataUnavailable = tokensUsed === 0 && toolCalls === 0;
+    // Two-signal suggestion. The context signal is primary: the LLM
+    // gets a real "/compact" recommendation only when context-size OR
+    // tool-count crosses the threshold AND we have non-zero data.
+    let shouldSuggest = false;
+    let reason = 'below-threshold';
+    if (!dataUnavailable) {
+        if (contextThreshold !== 0 && tokensUsed >= effectiveContextThreshold) {
+            shouldSuggest = true;
+            const overBy = tokensUsed - effectiveContextThreshold;
+            reason = `context >= ${effectiveContextThreshold} on ${windowKind} window (over by ${overBy} tokens)`;
+        }
+        else if (toolCalls >= toolCallThreshold) {
+            shouldSuggest = true;
+            reason = `tool-calls >= ${toolCallThreshold} (count=${toolCalls})`;
+        }
+    }
+    return {
+        shouldSuggest,
+        reason,
+        ratio,
+        windowKind,
+        tokensUsed,
+        toolCalls,
+        thresholds: {
+            contextTokens: effectiveContextThreshold,
+            contextInterval,
+            toolCalls: toolCallThreshold
+        },
+        dataUnavailable,
+        source
+    };
+}
+export function dryRunCompact(options) {
+    const suggest = suggestCompact({
+        projectRoot: options.projectRoot,
+        sessionId: options.sessionId,
+        ...(options.env !== undefined ? { env: options.env } : {})
+    });
+    const hasPhase = options.from !== undefined && options.to !== undefined;
+    const recommend = hasPhase
+        ? buildRecommendEnvelope(options.from, options.to)
+        : {
+            from: null,
+            to: null,
+            shouldCompact: false,
+            severity: null,
+            rationale: null,
+            suggestedMessage: null
+        };
+    // Action threshold: either suggest-signal OR recommend=yes. The LLM
+    // is the final arbiter; the primitive just surfaces the composite
+    // signal.
+    const action = suggest.shouldSuggest || recommend.shouldCompact ? 'compact' : 'skip';
+    return {
+        action,
+        suggest,
+        recommend,
+        survival: { persists: SURVIVAL_TABLE_PERSISTS, lost: SURVIVAL_TABLE_LOST }
+    };
+}
+function buildRecommendEnvelope(from, to) {
+    const lookup = lookupPhaseTransition(from, to);
+    const shouldCompact = lookup.severity === 'yes' || lookup.severity === 'maybe';
+    return {
+        from,
+        to,
+        shouldCompact,
+        severity: lookup.severity,
+        rationale: lookup.rationale,
+        suggestedMessage: buildSuggestedCompactMessage(from, to, lookup.severity)
+    };
+}
+export function buildRecommendEnvelopePure(from, to) {
+    return buildRecommendEnvelope(from, to);
+}
+// Re-export phase primitives for callers that don't want to traverse
+// decision-tables. The CLI command file imports `isPhase` from here
+// to keep the validation path co-located with the recommend envelope
+// builder.
+export { PHASE_TRANSITIONS, lookupPhaseTransition, buildSuggestedCompactMessage, PHASES, isPhase, SURVIVAL_TABLE } from './decision-tables.js';

package/dist/services/compact-history/compact-history-service.d.ts

@@ -0,0 +1,41 @@
+export interface CompactHistoryEvent {
+    readonly schemaVersion: 1;
+    readonly ts: string;
+    readonly target: 'main' | 'sub-agent' | 'worker';
+    readonly mode: 'standard' | 'partial' | 'aggressive';
+    readonly ide: string;
+    readonly pathway: string;
+    readonly beforeRatio: number;
+    readonly redLine: boolean;
+    readonly ok: boolean;
+    readonly checkpointPath: string;
+    readonly dispatchMessage: string;
+}
+export type CompactHistoryReadResult = {
+    readonly kind: 'file-missing';
+    readonly path: string;
+} | {
+    readonly kind: 'empty';
+    readonly path: string;
+} | {
+    readonly kind: 'ok';
+    readonly path: string;
+    readonly events: ReadonlyArray<CompactHistoryEvent>;
+    readonly parseErrors: ReadonlyArray<{
+        readonly line: number;
+        readonly raw: string;
+    }>;
+};
+export declare function readCompactHistory(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+}): CompactHistoryReadResult;
+export interface CompactHistorySummary {
+    readonly totalCompacts: number;
+    readonly lastTs: string | null;
+    readonly lastBeforeRatio: number | null;
+    readonly lastRedLine: boolean;
+    readonly redLineCount: number;
+    readonly failedCount: number;
+}
+export declare function summarizeCompactHistory(events: ReadonlyArray<CompactHistoryEvent>): CompactHistorySummary;

package/dist/services/compact-history/compact-history-service.js

@@ -0,0 +1,62 @@
+// src/services/compact-history/compact-history-service.ts
+//
+// Slice 2026-07-30-compact-visibility (slice 1/4). Pure-function
+// reader for the .peaks/_runtime/<sessionId>/compact-history.jsonl
+// file that auto-compact-orchestrator now appends to on every
+// dispatch. The CLI surface `peaks compact history` and the
+// statusline indicator both consume this service.
+//
+// The file is one JSON event per line. Malformed lines are
+// surfaced as { kind: 'parse-error', line, raw } records so the
+// caller (CLI / statusline) can warn without aborting the whole
+// read.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function readCompactHistory(input) {
+    const path = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'compact-history.jsonl');
+    if (!existsSync(path)) {
+        return { kind: 'file-missing', path };
+    }
+    const raw = readFileSync(path, 'utf8');
+    const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+    if (lines.length === 0) {
+        return { kind: 'empty', path };
+    }
+    const events = [];
+    const parseErrors = [];
+    lines.forEach((line, idx) => {
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.beforeRatio !== 'number' || typeof parsed.ts !== 'string') {
+                parseErrors.push({ line: idx + 1, raw: line });
+                return;
+            }
+            events.push(parsed);
+        }
+        catch {
+            parseErrors.push({ line: idx + 1, raw: line });
+        }
+    });
+    return { kind: 'ok', path, events, parseErrors };
+}
+export function summarizeCompactHistory(events) {
+    if (events.length === 0) {
+        return {
+            totalCompacts: 0,
+            lastTs: null,
+            lastBeforeRatio: null,
+            lastRedLine: false,
+            redLineCount: 0,
+            failedCount: 0,
+        };
+    }
+    const last = events[events.length - 1];
+    return {
+        totalCompacts: events.length,
+        lastTs: last.ts,
+        lastBeforeRatio: last.beforeRatio,
+        lastRedLine: last.redLine,
+        redLineCount: events.filter((e) => e.redLine).length,
+        failedCount: events.filter((e) => !e.ok).length,
+    };
+}

package/dist/services/compact-statusline/compact-statusline-service.d.ts

@@ -0,0 +1,16 @@
+export interface CompactStatuslineState {
+    readonly kind: 'missing' | 'idle' | 'pending' | 'red-line' | 'just-compacted';
+    readonly label: string;
+    readonly detail?: string;
+}
+export declare function decideCompactStatusline(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string | null;
+    readonly now: number;
+}): CompactStatuslineState;
+/**
+ * Plain-text render: just the label. The LLM embeds this in
+ * the Claude Code statusline. Pure: no side effects, no I/O
+ * beyond the two file reads.
+ */
+export declare function renderCompactStatusline(state: CompactStatuslineState): string;

package/dist/services/compact-statusline/compact-statusline-service.js

@@ -0,0 +1,83 @@
+// src/services/compact-statusline/compact-statusline-service.ts
+//
+// Slice 2026-07-30-compact-visibility (slice 3/4). Pure helper
+// for the 'peaks statusline compact' indicator. Reads
+// .peaks/_runtime/<sessionId>/auto-compact-pending.json +
+// compact-history.jsonl and decides the single-line text
+// the LLM should embed in Claude Code's statusline.
+//
+// State machine:
+//   - pending: a 'block' intent is sitting in
+//     auto-compact-pending.json → 'compact pending (<ratio>)'
+//   - redLine: pending.redLine === true → 'REDLINE 0.95'
+//   - just-compacted: history has an event within the last
+//     30 seconds → 'just compacted (<from>→<to>)'
+//   - idle: nothing recent → '--'
+//   - missing: no session binding or no orchestrator run yet
+//     → '' (empty)
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+const JUST_COMPACTED_WINDOW_MS = 30_000;
+export function decideCompactStatusline(input) {
+    if (input.sessionId === null) {
+        return { kind: 'missing', label: '' };
+    }
+    const runtimeDir = join(input.projectRoot, '.peaks', '_runtime', input.sessionId);
+    const pendingPath = join(runtimeDir, 'txt', 'auto-compact-pending.json');
+    const historyPath = join(runtimeDir, 'compact-history.jsonl');
+    // Priority 1: a pending compact intent.
+    if (existsSync(pendingPath)) {
+        try {
+            const raw = readFileSync(pendingPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed.pending === true) {
+                if (parsed.redLine === true) {
+                    return {
+                        kind: 'red-line',
+                        label: `REDLINE ${(parsed.ratio ?? 0).toFixed(2)}`,
+                        detail: pendingPath,
+                    };
+                }
+                return {
+                    kind: 'pending',
+                    label: `compact pending (${(parsed.ratio ?? 0).toFixed(2)})`,
+                    detail: pendingPath,
+                };
+            }
+        }
+        catch { /* fall through to history check */ }
+    }
+    // Priority 2: the most recent history event is within 30s.
+    if (existsSync(historyPath)) {
+        try {
+            const mtimeMs = statSync(historyPath).mtimeMs;
+            if (input.now - mtimeMs <= JUST_COMPACTED_WINDOW_MS) {
+                const raw = readFileSync(historyPath, 'utf8');
+                const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+                const last = lines[lines.length - 1];
+                if (last !== undefined) {
+                    const parsed = JSON.parse(last);
+                    const from = (parsed.beforeRatio ?? 0).toFixed(2);
+                    const to = (parsed.ok === false) ? 'failed' : '0.0?';
+                    return {
+                        kind: 'just-compacted',
+                        label: parsed.redLine === true
+                            ? `just compacted (REDLINE ${from}→?)`
+                            : `just compacted (${from}→${to})`,
+                        detail: historyPath,
+                    };
+                }
+            }
+        }
+        catch { /* fall through to idle */ }
+    }
+    return { kind: 'idle', label: '--' };
+}
+/**
+ * Plain-text render: just the label. The LLM embeds this in
+ * the Claude Code statusline. Pure: no side effects, no I/O
+ * beyond the two file reads.
+ */
+export function renderCompactStatusline(state) {
+    return state.label;
+}

package/dist/services/complexity/complexity-estimator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * v2.15.0 follow-up — G10: complexity estimator.
+ *
+ * 12 Gaps memory: the G2 complexity tier drives user-attended vs overnight
+ * scheduling. This service estimates the complexity of a set of files
+ * based on LOC + a few cheap heuristics.
+ *
+ * Tier thresholds (G2 12 Gaps memory):
+ *   - trivial : ≤ 50 lines, no async, no IO
+ *   - simple  : ≤ 200 lines, ≤ 3 exports
+ *   - complex : > 200 lines, OR many exports, OR has async/await
+ *
+ * Pure function. CLI: `peaks complexity estimate --files <list>`.
+ */
+export type ComplexityTier = 'trivial' | 'simple' | 'complex';
+export interface FileComplexity {
+    readonly file: string;
+    readonly lines: number;
+    readonly exports: number;
+    readonly hasAsync: boolean;
+    readonly tier: ComplexityTier;
+}
+export interface ComplexityEstimate {
+    readonly files: readonly FileComplexity[];
+    readonly overall: ComplexityTier;
+    readonly summary: {
+        trivial: number;
+        simple: number;
+        complex: number;
+    };
+}
+export declare function estimateFileComplexity(file: string): FileComplexity | null;
+export declare function aggregateTier(tiers: readonly ComplexityTier[]): ComplexityTier;
+export declare function estimateComplexity(projectRoot: string, files: readonly string[]): ComplexityEstimate;

package/dist/services/complexity/complexity-estimator.js

@@ -0,0 +1,64 @@
+/**
+ * v2.15.0 follow-up — G10: complexity estimator.
+ *
+ * 12 Gaps memory: the G2 complexity tier drives user-attended vs overnight
+ * scheduling. This service estimates the complexity of a set of files
+ * based on LOC + a few cheap heuristics.
+ *
+ * Tier thresholds (G2 12 Gaps memory):
+ *   - trivial : ≤ 50 lines, no async, no IO
+ *   - simple  : ≤ 200 lines, ≤ 3 exports
+ *   - complex : > 200 lines, OR many exports, OR has async/await
+ *
+ * Pure function. CLI: `peaks complexity estimate --files <list>`.
+ */
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+function countMatches(content, regex) {
+    return (content.match(regex) ?? []).length;
+}
+export function estimateFileComplexity(file) {
+    if (!existsSync(file))
+        return null;
+    const stat = statSync(file);
+    if (!stat.isFile())
+        return null;
+    let content;
+    try {
+        content = readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        console.warn(`estimateFileComplexity: failed to read ${file}: ${err.message}`);
+        return null;
+    }
+    const lines = content.split('\n').length;
+    const exports = countMatches(content, /^export\s+/gm);
+    const hasAsync = /\basync\s+(function|\([^)]*\)\s*=>|[a-zA-Z_$][a-zA-Z0-9_$]*\s*\()/m.test(content);
+    let tier = 'trivial';
+    if (lines > 200 || exports > 10 || hasAsync)
+        tier = 'complex';
+    else if (lines > 50 || exports > 3)
+        tier = 'simple';
+    return { file, lines, exports, hasAsync, tier };
+}
+export function aggregateTier(tiers) {
+    if (tiers.some((t) => t === 'complex'))
+        return 'complex';
+    if (tiers.some((t) => t === 'simple'))
+        return 'simple';
+    return 'trivial';
+}
+export function estimateComplexity(projectRoot, files) {
+    const results = [];
+    for (const f of files) {
+        const path = resolve(projectRoot, f);
+        const c = estimateFileComplexity(path);
+        if (c !== null)
+            results.push(c);
+    }
+    const summary = { trivial: 0, simple: 0, complex: 0 };
+    for (const r of results) {
+        summary[r.tier]++;
+    }
+    return { files: results, overall: aggregateTier(results.map((r) => r.tier)), summary };
+}

package/dist/services/config/config-migration.d.ts

@@ -0,0 +1,45 @@
+export declare const CONFIG_SCHEMA_VERSION_V2 = "2.0.0";
+/**
+ * Slim 2.0 schema for `~/.peaks/config.json`. After migration,
+ * the only meaningful fields are `version` + `ocr.llm.*`; everything
+ * else lives in sidecar files (`providers.json`, `proxy.json`,
+ * `workspaces.json`) or per-project `preferences.json`. The type is
+ * intentionally permissive: extra keys are ignored at runtime, not
+ * rejected, so a hand-written or partially-migrated file does not
+ * fail the loader.
+ */
+export interface ConfigV2 {
+    readonly version: typeof CONFIG_SCHEMA_VERSION_V2;
+}
+export declare function isConfigV2(raw: unknown): raw is ConfigV2;
+/**
+ * Per-project fields that the 1.x → 2.0 migration moves
+ * from `~/.peaks/config.json` (global) to `<project>/.peaks/preferences.json`
+ * (per-project). Per spec §10.4 line 1215: "economyMode / swarmMode
+ * 字段从 global 迁移到当前 workspace 的 .peaks/preferences.json".
+ */
+declare const PER_PROJECT_FIELDS: readonly ["economyMode", "swarmMode"];
+type PerProjectField = (typeof PER_PROJECT_FIELDS)[number];
+export interface MigrationOptions {
+    currentProjectRoot: string;
+}
+export interface MigrationPlan {
+    alreadyAtV2: boolean;
+    detectedSchemaVersion: string | null;
+    newConfigSchemaVersion: string;
+    /** Field names that would be migrated on apply (1.x → 2.0). */
+    willMigrateFields: readonly PerProjectField[];
+}
+export interface MigrationResult extends MigrationPlan {
+    applied: boolean;
+    backupPath?: string;
+    newConfigPath?: string;
+    error?: string;
+}
+export declare function globalConfigPath(): string;
+export declare function backupConfigPath(): string;
+export declare function planMigration(opts: MigrationOptions): MigrationPlan;
+export declare function executeMigration(opts: MigrationOptions & {
+    apply: boolean;
+}): MigrationResult;
+export {};