peaks-loop 4.0.24 → 4.0.26

package/skills/peaks-code/references/envelope-contract.md

@@ -33,19 +33,14 @@ Top-level fields (post-2.1.0):
 - `envelopeVersion: '2.1.0'`
 - `role: string` — sub-agent role string
 - `ide: string` — detected IDE label (`claude-code` etc.)
-- `originalPromptSize: number` — bytes of the un-compressed prompt
-- `promptSize: number` — bytes after headroom compression (or
-  equal to `originalPromptSize` when `--use-headroom` is off or
-  unavailable)
+- `originalPromptSize: number` — bytes of the caller-supplied prompt
+- `promptSize: number` — bytes of the composed dispatch prompt
 - `toolCall: { name: string; args: Record<string, unknown> }` —
   the per-IDE tool-call descriptor the LLM must execute
 - `dispatchRecordPath: string` — absolute path to the dispatch
   record on disk
 - `batchId: string` — uuid-like opaque token grouping one batch
 - `dispatchedInBatch: number` — current count after this dispatch
-- `headroomCompressed: boolean` — true if headroom-ai actually
-  reduced the prompt
-- `headroomResult: { mode, compressed, compressionRatio, tokensSaved, warning } | null`
 - `forcedAt: string | null` — ISO8601 when `--force` overrode
   the G9 hard-reject tier
 - `contextImpact: { promptBytes, artifactBytes, totalBytes }`

package/skills/peaks-code/references/sub-agent-dispatch.md

@@ -51,8 +51,8 @@ peaks sub-agent dispatch <role> --prompt <text> [--request-id <rid>] [--session-
 > scrollback. The dispatch record on disk (gitignored under
 > `.peaks/_sub_agents/`) keeps the prompt for the sub-agent to read;
 > CLI stdout stays metadata-only. Surface `originalPromptSize` +
-> `promptSize` so the LLM-side runner can still reason about headroom
-> without seeing the content. The prompt content the LLM should pass
+> `promptSize` so the LLM-side runner can still reason about the size
+> delta without seeing the content. The prompt content the LLM should pass
 > through lives in `data.toolCall.args.prompt` (the IDE-arg the
 > consumer passes to the tool), NOT in the outer envelope.
 
@@ -77,8 +77,6 @@ peaks sub-agent dispatch <role> --prompt <text> [--request-id <rid>] [--session-
     "dispatchRecordPath": ".peaks/_sub_agents/2026-06-06-session-5b1095/dispatch-002-2026-06-07-...-...json",
     "batchId": "<uuid>",
     "dispatchedInBatch": 3,
-    "headroomCompressed": false,
-    "headroomResult": null,
     "forcedAt": null,
     "contextImpact": {
       "promptBytes": 4321,

package/dist/services/context/headroom-client.d.ts

@@ -1,34 +0,0 @@
-export type HeadroomMode = 'balanced' | 'aggressive' | 'conservative';
-export interface HeadroomResult {
-    readonly compressed: boolean;
-    readonly originalSize: number;
-    readonly compressedSize: number;
-    readonly compressionRatio: number;
-    readonly mode: HeadroomMode;
-    /** `'HEADROOM_UNAVAILABLE'` on fallback; `null` on success. */
-    readonly warning: string | null;
-    /** Compressed prompt body. `null` if no compression happened. */
-    readonly compressedPrompt: string | null;
-    /** Tokens saved (from the SDK). 0 on fallback. */
-    readonly tokensSaved: number;
-}
-/**
- * Compress a prompt via headroom-ai. The `fallback: true` option is
- * non-negotiable: if the proxy daemon is unavailable, the SDK returns
- * `result.compressed = false` and the original messages; we surface
- * that as `HEADROOM_UNAVAILABLE` warning + G7 metadata-only fallback.
- */
-export declare function compressPrompt(prompt: string, mode?: HeadroomMode): Promise<HeadroomResult>;
-/**
- * Bridge interface: when `--use-headroom` is set, share entries written
- * via `peaks sub-agent share` MAY also flow through headroom's
- * `SharedContext`. Slice #010 implements a peak-internal shared channel
- * (see `shared-channel.ts`); the headroom-side `SharedContext` is a
- * separate concept that future slices can layer on. For now this
- * function is a stub that returns the peak-internal channel ID, which
- * is enough to demonstrate the bridge contract.
- */
-export declare function buildSharedContextBridge(batchId: string): {
-    peakChannelId: string;
-    headroomContextId: string;
-};

package/dist/services/context/headroom-client.js

@@ -1,117 +0,0 @@
-const DEFAULT_TIMEOUT_MS = 30_000;
-const DEFAULT_MODEL = 'claude-sonnet-4-5-20250929';
-// Approximate 1 token = 4 bytes for English text. This is a rough
-// heuristic; the SDK does its own tokenization internally.
-const BYTES_PER_TOKEN = 4;
-/**
- * Compress a prompt via headroom-ai. The `fallback: true` option is
- * non-negotiable: if the proxy daemon is unavailable, the SDK returns
- * `result.compressed = false` and the original messages; we surface
- * that as `HEADROOM_UNAVAILABLE` warning + G7 metadata-only fallback.
- */
-export async function compressPrompt(prompt, mode = 'balanced') {
-    const originalSize = Buffer.byteLength(prompt, 'utf8');
-    let compressFn = null;
-    try {
-        const mod = await import('headroom-ai');
-        if (typeof mod.compress === 'function') {
-            compressFn = mod.compress;
-        }
-    }
-    catch {
-        return fallback(originalSize, mode);
-    }
-    if (compressFn === null) {
-        return fallback(originalSize, mode);
-    }
-    const messages = [
-        { role: 'user', content: prompt }
-    ];
-    const opts = {
-        model: DEFAULT_MODEL,
-        timeout: DEFAULT_TIMEOUT_MS,
-        fallback: true, // CRITICAL: return original messages if proxy is down
-        retries: 1
-    };
-    if (mode === 'aggressive') {
-        opts.tokenBudget = Math.max(1, Math.floor(originalSize * 0.20 / BYTES_PER_TOKEN));
-    }
-    else if (mode === 'conservative') {
-        opts.tokenBudget = Math.max(1, Math.floor(originalSize * 0.70 / BYTES_PER_TOKEN));
-    }
-    else {
-        // balanced: target ~60% reduction
-        opts.tokenBudget = Math.max(1, Math.floor(originalSize * 0.40 / BYTES_PER_TOKEN));
-    }
-    let result;
-    try {
-        result = await compressFn(messages, opts);
-    }
-    catch {
-        return fallback(originalSize, mode);
-    }
-    if (result.compressed === false) {
-        return {
-            compressed: false,
-            originalSize,
-            compressedSize: originalSize,
-            compressionRatio: 1.0,
-            mode,
-            warning: 'HEADROOM_UNAVAILABLE',
-            compressedPrompt: null,
-            tokensSaved: 0
-        };
-    }
-    const compressedContent = extractContent(result.messages);
-    if (compressedContent === null) {
-        return fallback(originalSize, mode);
-    }
-    const compressedSize = Buffer.byteLength(compressedContent, 'utf8');
-    return {
-        compressed: true,
-        originalSize,
-        compressedSize,
-        compressionRatio: compressedSize / originalSize,
-        mode,
-        warning: null,
-        compressedPrompt: compressedContent,
-        tokensSaved: result.tokensSaved ?? 0
-    };
-}
-function fallback(originalSize, mode) {
-    return {
-        compressed: false,
-        originalSize,
-        compressedSize: originalSize,
-        compressionRatio: 1.0,
-        mode,
-        warning: 'HEADROOM_UNAVAILABLE',
-        compressedPrompt: null,
-        tokensSaved: 0
-    };
-}
-function extractContent(messages) {
-    if (!Array.isArray(messages) || messages.length === 0) {
-        return null;
-    }
-    const last = messages[messages.length - 1];
-    if (typeof last.content === 'string') {
-        return last.content;
-    }
-    return null;
-}
-/**
- * Bridge interface: when `--use-headroom` is set, share entries written
- * via `peaks sub-agent share` MAY also flow through headroom's
- * `SharedContext`. Slice #010 implements a peak-internal shared channel
- * (see `shared-channel.ts`); the headroom-side `SharedContext` is a
- * separate concept that future slices can layer on. For now this
- * function is a stub that returns the peak-internal channel ID, which
- * is enough to demonstrate the bridge contract.
- */
-export function buildSharedContextBridge(batchId) {
-    return {
-        peakChannelId: batchId,
-        headroomContextId: `headroom-ctx-${batchId}`
-    };
-}

package/dist/services/context/headroom-prefs.d.ts

@@ -1,46 +0,0 @@
-/**
- * Headroom preferences resolver (slice 2026-06-14-fzf-headroom-rollout).
- *
- * Pure functions that turn `ProjectPreferences.headroom.*` + CLI
- * overrides into a single decision the dispatch path can act on.
- * No IO. No side effects. Easy to test in isolation.
- *
- * Two distinct decisions:
- *  1. `resolveHeadroomOptions` — should we compress the dispatch prompt?
- *     Used by `peaks sub-agent dispatch`. Returns one of:
- *       - `{ mode: <m>, blocked: null }`   → compress with mode <m>
- *       - `{ mode: null, blocked: null }`  → skip compression (no --use-headroom)
- *       - `{ mode: null, blocked: 'HEADROOM_DISABLED_BY_PREFERENCE' }` → hard fail
- *  2. `shouldCompressResults` — should we compress search-result text?
- *     Used by `peaks memory search` / `peaks retrospective search`.
- *     Non-blocking: returns a `reason` instead of a `blocked` code.
- *
- * Precedence (dispatch):
- *   1. `headroom.enabled = false`  → hard block (regardless of --use-headroom)
- *   2. `headroom.enabled = true` + `--headroom-mode <m>` → use <m>
- *   3. `headroom.enabled = true` + `--use-headroom` (no --headroom-mode) →
- *      use `perTouchpoint.subAgentDispatch` (preferred) else `defaultMode`
- *   4. no `--use-headroom` → mode = null (compression skipped)
- */
-import type { HeadroomMode, ProjectPreferences } from '../preferences/preferences-types.js';
-export type HeadroomTouchpoint = keyof ProjectPreferences['headroom']['perTouchpoint'];
-export type HeadroomBlockCode = 'HEADROOM_DISABLED_BY_PREFERENCE';
-export interface ResolvedHeadroomOptions {
-    /** The mode to use for compression, or null if not compressing. */
-    readonly mode: HeadroomMode | null;
-    /** Hard-block reason; null when compression is allowed (or simply not requested). */
-    readonly blocked: HeadroomBlockCode | null;
-}
-export interface ResolveCliOverrides {
-    readonly useHeadroom: boolean;
-    readonly headroomMode?: string;
-}
-export declare function isHeadroomMode(value: string | undefined): value is HeadroomMode;
-export declare function resolveHeadroomOptions(prefs: ProjectPreferences['headroom'], cliOverrides: ResolveCliOverrides): ResolvedHeadroomOptions;
-export interface ShouldCompressDecision {
-    readonly compress: boolean;
-    readonly mode: HeadroomMode;
-    /** Non-null reason if not compressing. */
-    readonly reason: 'DISABLED' | 'BELOW_THRESHOLD' | null;
-}
-export declare function shouldCompressResults(prefs: ProjectPreferences['headroom'], joinedBytes: number, touchpoint: HeadroomTouchpoint): ShouldCompressDecision;

package/dist/services/context/headroom-prefs.js

@@ -1,34 +0,0 @@
-const VALID_MODES = new Set([
-    'balanced',
-    'aggressive',
-    'conservative'
-]);
-export function isHeadroomMode(value) {
-    return typeof value === 'string' && VALID_MODES.has(value);
-}
-export function resolveHeadroomOptions(prefs, cliOverrides) {
-    // (1) Hard block when preference disables headroom entirely.
-    if (cliOverrides.useHeadroom === true && prefs.enabled === false) {
-        return { mode: null, blocked: 'HEADROOM_DISABLED_BY_PREFERENCE' };
-    }
-    // (4) No --use-headroom → no compression.
-    if (cliOverrides.useHeadroom !== true) {
-        return { mode: null, blocked: null };
-    }
-    // (2) CLI --headroom-mode wins (even if preference is set, CLI overrides).
-    if (isHeadroomMode(cliOverrides.headroomMode)) {
-        return { mode: cliOverrides.headroomMode, blocked: null };
-    }
-    // (3) Preference path: perTouchpoint > defaultMode > 'balanced'.
-    const touchpointMode = prefs.perTouchpoint.subAgentDispatch;
-    return { mode: touchpointMode ?? prefs.defaultMode, blocked: null };
-}
-export function shouldCompressResults(prefs, joinedBytes, touchpoint) {
-    if (prefs.enabled === false) {
-        return { compress: false, mode: prefs.defaultMode, reason: 'DISABLED' };
-    }
-    if (joinedBytes < prefs.compressMinBytes) {
-        return { compress: false, mode: prefs.perTouchpoint[touchpoint], reason: 'BELOW_THRESHOLD' };
-    }
-    return { compress: true, mode: prefs.perTouchpoint[touchpoint], reason: null };
-}

package/skills/peaks-code/references/headroom-integration.md

@@ -1,107 +0,0 @@
-# Headroom Integration — G7.7 opt-in compression channel
-
-> Slice #010 (G7.7 headroom-ai integration route).
-> Source: https://github.com/chopratejas/headroom
-> Package: `headroom-ai@0.22.4` (Apache-2.0, MIT-compatible).
-> See: `THIRD_PARTY_LICENSES.md` for the license record.
-
-## Why headroom-ai is justified (R-14)
-
-The dev-preference red line "非必要不添加新的 dep" is preserved:
-headroom-ai is the only opt-in mechanism for G7.7 + G9 to compress
-sub-agent prompts that exceed the 75% / 80% threshold. Without
-headroom-ai, `--use-headroom` is a no-op and the only fallback is
-`--force` override at CLI.
-
-The user's explicit reference (https://github.com/chopratejas/headroom)
-is the basis for the dev-preference override.
-
-## API shape (real SDK, not the PRD's spec)
-
-```ts
-import { compress } from 'headroom-ai';
-
-const result = await compress(messages, {
-  model: 'claude-sonnet-4-5-20250929',
-  baseUrl: 'http://localhost:8787',  // local proxy; not used in slice #010
-  apiKey: 'hr_...',                   // Headroom Cloud; not used in slice #010
-  timeout: 30_000,
-  fallback: true,                     // CRITICAL: return original messages if proxy is dead
-  retries: 1,
-  tokenBudget: 4000,                  // compress to fit this limit
-  hooks: new MyHooks(),               // pre/post compression hooks
-});
-
-result.messages          // compressed messages
-result.tokensBefore      // original token count
-result.tokensAfter       // compressed token count
-result.tokensSaved       // tokens removed
-result.compressionRatio  // tokensAfter / tokensBefore
-result.transformsApplied // e.g. ['router:smart_crusher:0.35']
-result.compressed        // false if fallback kicked in
-```
-
-`fallback: true` is the key option: if the proxy is unavailable, the SDK
-returns the original messages + `result.compressed: false` instead of
-throwing. This makes the failure mode non-blocking (RL-22d / RL-32).
-
-## Mode table (peaks wrapper)
-
-The peaks wrapper maps the user-facing `HeadroomMode` to the SDK's
-`tokenBudget` option. Slice #010 does not consume the SDK's internal
-"audit" / "optimize" / "simulate" modes (those are SDK-internal);
-
-| Mode | tokenBudget | Use case |
-|---|---|---|
-| `balanced` (default) | promptSize * 0.40 / 4 | General sub-agent dispatch |
-| `aggressive` | promptSize * 0.20 / 4 | Last-resort large prompt |
-| `conservative` | promptSize * 0.70 / 4 | Sensitive code analysis, accuracy-critical |
-
-The `0.40 / 4` factor approximates 60% byte reduction (1 token ≈ 4 bytes
-for English text). The SDK does its own tokenization internally; the
-`tokenBudget` is a hint, not a hard cap.
-
-## Failure semantics (RL-22d / RL-32)
-
-- `result.compressed === false` → `code: "HEADROOM_UNAVAILABLE"` warning
-- `compress()` throws (network error, JSON parse error) → caught and treated as `HEADROOM_UNAVAILABLE`
-- Import failure (headroom-ai not installed) → caught and treated as `HEADROOM_UNAVAILABLE`
-- **NOT blocking** — peak falls back to G7 metadata-only and continues dispatch
-
-## CCR reversible hydration (slice #011+ TODO)
-
-The PRD mentions "CCR (Cross-Context Reversible)" as a benefit of
-headroom. In the SDK, this is implemented via the `hooks` option on
-`compress()`. A pre/post hook can persist the `ccrHashes` to disk,
-and a later `rehydrate()` call can re-hydrate the compressed prompt
-to the original. Slice #010 does NOT consume CCR — it only uses
-compression. R-17 (CCR for aggressive / conservative modes) is
-deferred to slice #011+.
-
-## Cross-platform behavior (R-19)
-
-- In-process compression (the SDK's library mode) is platform-agnostic.
-- The long-running `headroom proxy` daemon is platform-specific
-  (Unix socket on Linux/macOS, named pipe on Windows). Slice #010
-  does NOT consume the proxy daemon.
-- All headroom-ai calls in slice #010 go through the in-process SDK
-  with `fallback: true`. The peak wrapper at
-  `src/services/context/headroom-client.ts` catches all errors and
-  treats them as fallback.
-
-## What slice #010 does NOT do
-
-- Does NOT install the `headroom proxy` daemon (N-7).
-- Does NOT consume headroom's `SharedContext` directly (G7.7.3 in the
-  PRD); the peak-internal `SharedChannel` (G8) is the cross-sub-agent
-  state store. `buildSharedContextBridge()` is a stub that returns
-  the peak-internal channel ID + a placeholder headroom context ID.
-- Does NOT use the SDK's `audit` / `optimize` / `simulate` modes
-  (those are SDK-internal; the peak wrapper exposes
-  `balanced` / `aggressive` / `conservative` to the user).
-
-## Security + license
-
-- License: Apache-2.0 (MIT-compatible) — see `THIRD_PARTY_LICENSES.md`.
-- Pinned version: exact `0.22.4` (no `^` / `~` range) per dev-preference.
-- `pnpm audit` ran on install; no new high-severity vulnerabilities.