peaks-cli 1.3.2 → 1.3.3

package/dist/src/hooks/pre-tool-use-sub-agent.d.ts

@@ -0,0 +1,28 @@
+import { type HookGuardResult } from '../cli/commands/sub-agent-dispatch-guard.js';
+/**
+ * Read the prompt size from the LLM platform's hook stdin. Different
+ * LLMs send different payload shapes; we accept the most common:
+ *   - Claude Code: `{"tool_name": "Bash", "tool_input": {"command": "..."}}`
+ *   - Trae: `{"tool_name": "terminal", "tool_input": {"command": "..."}}`
+ *
+ * The hook reads the `command` (or `prompt`) field and computes the
+ * byte length. If neither field is present, returns 0 (always passes).
+ */
+export declare function readPromptSizeFromHookStdin(stdin: unknown): number;
+/**
+ * Execute the hook guard via spawnSync. Returns the parsed result or
+ * a fallback (allow: true) on subprocess failure.
+ *
+ * Prefer the in-process `evaluateHookGuard` (no subprocess) when the
+ * hook is called from a TypeScript context. Use `runHookGuardSubprocess`
+ * only when the hook needs to be invoked from a non-TypeScript caller
+ * (e.g. a shell script that wraps the peaks CLI).
+ */
+export declare function runHookGuardSubprocess(prompt: string): HookGuardResult;
+/**
+ * Main entry point for the hook. Reads the LLM platform's stdin,
+ * computes the prompt size, and returns the guard result. Used by
+ * the LLM platform's hook JSON to decide whether to allow the tool
+ * call.
+ */
+export declare function runHookGuard(stdin: unknown): HookGuardResult;

package/dist/src/hooks/pre-tool-use-sub-agent.js

@@ -0,0 +1,105 @@
+/**
+ * G9.5 PreToolUse hook execution body.
+ *
+ * Wraps `peaks sub-agent-dispatch-guard` for LLM platform integration.
+ * The hook reads the prompt size from the LLM platform's hook stdin
+ * (Claude Code / Trae / etc.), invokes the guard CLI, and returns
+ * `{allow: true/false, reason, suggest}` JSON to the LLM platform.
+ *
+ * The hook is registered via `peaks hooks install` in the LLM
+ * platform's `settings.json` `PreToolUse` array. Only IDEs with
+ * `IdeAdapter.promptSizeAware: true` get the hook installed.
+ *
+ * The hook layer is the **strictest** layer in the G9 chain (RL-30).
+ * The CLI 兜底 layer (`peaks sub-agent dispatch --force`) can override
+ * the 80% threshold; the hook layer CANNOT.
+ */
+import { spawnSync } from 'node:child_process';
+import { evaluateHookGuard } from '../cli/commands/sub-agent-dispatch-guard.js';
+/**
+ * Read the prompt size from the LLM platform's hook stdin. Different
+ * LLMs send different payload shapes; we accept the most common:
+ *   - Claude Code: `{"tool_name": "Bash", "tool_input": {"command": "..."}}`
+ *   - Trae: `{"tool_name": "terminal", "tool_input": {"command": "..."}}`
+ *
+ * The hook reads the `command` (or `prompt`) field and computes the
+ * byte length. If neither field is present, returns 0 (always passes).
+ */
+export function readPromptSizeFromHookStdin(stdin) {
+    if (stdin === null || typeof stdin !== 'object') {
+        return 0;
+    }
+    const obj = stdin;
+    const toolInput = obj.tool_input;
+    if (toolInput === null || typeof toolInput !== 'object') {
+        return 0;
+    }
+    const ti = toolInput;
+    const candidates = ['command', 'prompt', 'text', 'input'];
+    for (const key of candidates) {
+        const v = ti[key];
+        if (typeof v === 'string') {
+            return Buffer.byteLength(v, 'utf8');
+        }
+    }
+    return 0;
+}
+/**
+ * Execute the hook guard via spawnSync. Returns the parsed result or
+ * a fallback (allow: true) on subprocess failure.
+ *
+ * Prefer the in-process `evaluateHookGuard` (no subprocess) when the
+ * hook is called from a TypeScript context. Use `runHookGuardSubprocess`
+ * only when the hook needs to be invoked from a non-TypeScript caller
+ * (e.g. a shell script that wraps the peaks CLI).
+ */
+export function runHookGuardSubprocess(prompt) {
+    const result = spawnSync('node', [
+        process.argv[1] ?? 'peaks',
+        'sub-agent-dispatch-guard',
+        '--prompt', prompt,
+        '--json'
+    ], { encoding: 'utf8' });
+    if (result.status !== 0) {
+        // Fallback: allow (don't block the dispatch on a guard subprocess failure).
+        return {
+            schema: 'peaks-hook-guard/v1',
+            allow: true,
+            code: 'OK',
+            reason: `guard subprocess failed (status ${result.status}); falling through`,
+            suggest: null,
+            tier: 'ok',
+            ratio: 0,
+            bytesUsed: 0,
+            capacityBytes: 0,
+            warnings: ['HOOK_GUARD_SUBPROCESS_FAILED']
+        };
+    }
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        return {
+            schema: 'peaks-hook-guard/v1',
+            allow: true,
+            code: 'OK',
+            reason: 'guard subprocess produced unparseable JSON; falling through',
+            suggest: null,
+            tier: 'ok',
+            ratio: 0,
+            bytesUsed: 0,
+            capacityBytes: 0,
+            warnings: ['HOOK_GUARD_SUBPROCESS_INVALID_JSON']
+        };
+    }
+}
+/**
+ * Main entry point for the hook. Reads the LLM platform's stdin,
+ * computes the prompt size, and returns the guard result. Used by
+ * the LLM platform's hook JSON to decide whether to allow the tool
+ * call.
+ */
+export function runHookGuard(stdin) {
+    const promptSize = readPromptSizeFromHookStdin(stdin);
+    return evaluateHookGuard(promptSize);
+}

package/dist/src/services/config/config-types.d.ts

@@ -61,7 +61,7 @@ export type PeaksConfig = {
     /**
      * Sub-agent progress surfacing knobs. The `peaks progress watch`
      * CLI (intended to be run in a separate terminal tab while the
-     * LLM is working) reads `.peaks/<sid>/system/subagent-progress.json`
+     * LLM is working) reads `.peaks/_sub_agents/<sid>/subagent-progress.json`
      * and renders elapsed / spinner / sub-step in real time. The
      * `enabled` flag is a kill-switch for users who find the watch
      * distracting; the `heartbeatIntervalMs` lets power users tune

package/dist/src/services/context/artifact-meta.d.ts

@@ -0,0 +1,72 @@
+export type ArtifactStatus = 'created' | 'finalized' | 'partial' | 'failed';
+export interface ArtifactMeta {
+    readonly path: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly status: ArtifactStatus;
+    /** Mandatory literal `false`. The type system rejects `true`. */
+    readonly contentInlined: false;
+    /** 1-2 sentence description, ≤ 200 chars. Allowed in main context. */
+    readonly summary: string | null;
+    /** ISO8601. */
+    readonly writtenAt: string;
+    /** Request id this artifact belongs to. */
+    readonly rid: string;
+    /** Sub-agent role string. */
+    readonly role: string;
+    /** Sequence number when same role is dispatched multiple times. */
+    readonly idx: number;
+}
+export interface ContextImpact {
+    readonly promptSize: number;
+    readonly artifactSizes: readonly number[];
+    readonly batchTotalSize: number;
+    /** `high` if `batchTotalSize > 4MB` OR any `artifactSize > 1MB`. */
+    readonly contextWarning: 'normal' | 'high' | 'critical';
+}
+/**
+ * Compute the sha256 hex digest of a file. Throws if the file does not
+ * exist or is not readable. Caller is expected to handle ENOENT as
+ * `code: 'ARTIFACT_NOT_FOUND'` and treat 0-byte files as `status: 'failed'`.
+ */
+export declare function computeSha256(filePath: string): string;
+/**
+ * Build an `ArtifactMeta` from on-disk file. Computes size + sha256.
+ *
+ * `status` semantics:
+ *   - `'created'`   — file exists, non-empty, sha256 succeeded
+ *   - `'failed'`    — file is 0 bytes (R-2 / G7.4.e: do not silently succeed)
+ *   - `'partial'`   — caller-provided (e.g. sub-agent reports unfinished work)
+ *   - `'finalized'` — caller-provided (e.g. sub-agent reports complete)
+ */
+export declare function buildArtifactMeta(opts: {
+    path: string;
+    rid: string;
+    role: string;
+    idx: number;
+    summary: string | null;
+    status?: ArtifactStatus;
+    /** Override sha256 / size (e.g. when caller already computed them). */
+    precomputed?: {
+        size: number;
+        sha256: string;
+    };
+    /** Override the writtenAt timestamp. */
+    writtenAt?: string;
+}): ArtifactMeta;
+/**
+ * Build a `ContextImpact` from a prompt size + artifact sizes.
+ * Computes `contextWarning` per the G7.3 rule:
+ *   - `'critical'` if any artifact > ARTIFACT_MAX_SIZE_BYTES
+ *   - `'high'`     if total > BATCH_TOTAL_HIGH_BYTES (4MB)
+ *   - `'normal'`   otherwise
+ */
+export declare function buildContextImpact(opts: {
+    promptSize: number;
+    artifactSizes: readonly number[];
+}): ContextImpact;
+export declare const ARTIFACT_LIMITS: {
+    readonly ARTIFACT_MAX_SIZE_BYTES: number;
+    readonly BATCH_TOTAL_HIGH_BYTES: number;
+    readonly ARTIFACT_SUMMARY_MAX_CHARS: 200;
+};

package/dist/src/services/context/artifact-meta.js

@@ -0,0 +1,105 @@
+/**
+ * G7 — sub-agent context minimal-occupation (RL-17..RL-22, AC-38..AC-43).
+ *
+ * `ArtifactMeta` is what the dispatch record stores per sub-agent artifact
+ * instead of the full content. The `contentInlined: false` literal is the
+ * API contract: the type system rejects `true`, so main LLM context can
+ * never accidentally be flooded with inlined artifact bodies.
+ *
+ * The artifact's content lives on disk at `path`; the meta is ~200 chars
+ * (path + size + sha256 + status + summary), so 3 sub-agents × ~200 chars
+ * = ~600 chars net context increase per batch instead of 3MB+.
+ *
+ * Path convention (G7.4.c):
+ *   `.peaks/_sub_agents/<sid>/artifacts/<rid>-<role>-<idx>.<ext>`
+ *
+ * See: `.peaks/memory/sub-agent-context-minimal-occupation.md` for the
+ * full G7 rule.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+const ARTIFACT_MAX_SIZE_BYTES = 1024 * 1024; // 1MB
+const BATCH_TOTAL_HIGH_BYTES = 4 * 1024 * 1024; // 4MB
+/**
+ * Compute the sha256 hex digest of a file. Throws if the file does not
+ * exist or is not readable. Caller is expected to handle ENOENT as
+ * `code: 'ARTIFACT_NOT_FOUND'` and treat 0-byte files as `status: 'failed'`.
+ */
+export function computeSha256(filePath) {
+    const content = readFileSync(filePath);
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Build an `ArtifactMeta` from on-disk file. Computes size + sha256.
+ *
+ * `status` semantics:
+ *   - `'created'`   — file exists, non-empty, sha256 succeeded
+ *   - `'failed'`    — file is 0 bytes (R-2 / G7.4.e: do not silently succeed)
+ *   - `'partial'`   — caller-provided (e.g. sub-agent reports unfinished work)
+ *   - `'finalized'` — caller-provided (e.g. sub-agent reports complete)
+ */
+export function buildArtifactMeta(opts) {
+    let size;
+    let sha256;
+    let status = opts.status ?? 'created';
+    if (opts.precomputed) {
+        size = opts.precomputed.size;
+        sha256 = opts.precomputed.sha256;
+    }
+    else {
+        const stat = statSync(opts.path);
+        size = stat.size;
+        if (size === 0) {
+            // 0-byte artifact: cannot compute meaningful sha256; mark as failed.
+            sha256 = '0'.repeat(64);
+            status = 'failed';
+        }
+        else {
+            sha256 = computeSha256(opts.path);
+        }
+    }
+    const summary = opts.summary;
+    if (summary !== null && summary.length > 200) {
+        throw new Error(`ArtifactMeta summary must be ≤ 200 chars (got ${summary.length})`);
+    }
+    return {
+        path: opts.path,
+        size,
+        sha256,
+        status,
+        contentInlined: false,
+        summary,
+        writtenAt: opts.writtenAt ?? new Date().toISOString(),
+        rid: opts.rid,
+        role: opts.role,
+        idx: opts.idx
+    };
+}
+/**
+ * Build a `ContextImpact` from a prompt size + artifact sizes.
+ * Computes `contextWarning` per the G7.3 rule:
+ *   - `'critical'` if any artifact > ARTIFACT_MAX_SIZE_BYTES
+ *   - `'high'`     if total > BATCH_TOTAL_HIGH_BYTES (4MB)
+ *   - `'normal'`   otherwise
+ */
+export function buildContextImpact(opts) {
+    const batchTotalSize = opts.promptSize + opts.artifactSizes.reduce((a, b) => a + b, 0);
+    let contextWarning = 'normal';
+    if (opts.artifactSizes.some((s) => s > ARTIFACT_MAX_SIZE_BYTES)) {
+        contextWarning = 'critical';
+    }
+    else if (batchTotalSize > BATCH_TOTAL_HIGH_BYTES) {
+        contextWarning = 'high';
+    }
+    return {
+        promptSize: opts.promptSize,
+        artifactSizes: opts.artifactSizes,
+        batchTotalSize,
+        contextWarning
+    };
+}
+export const ARTIFACT_LIMITS = {
+    ARTIFACT_MAX_SIZE_BYTES,
+    BATCH_TOTAL_HIGH_BYTES,
+    ARTIFACT_SUMMARY_MAX_CHARS: 200
+};

package/dist/src/services/context/context-guard.d.ts

@@ -0,0 +1,49 @@
+/**
+ * G9 — forced compression gate (RL-27..RL-32).
+ *
+ * The CLI 兜底 layer. Validates prompt size against the threshold
+ * table in `threshold.ts` and returns a decision. The PreToolUse hook
+ * layer (`peaks sub-agent-dispatch-guard`) re-runs the same logic
+ * without `--force` (RL-30 strict).
+ *
+ * Decision codes:
+ *   - `OK`                          — under 50%
+ *   - `CONTEXT_SOFT_WARN`           — 50-75%, suggest --use-headroom
+ *   - `CONTEXT_NEAR_LIMIT`          — 75-80%, mandatory --use-headroom suggestion
+ *   - `PROMPT_TOO_LARGE`            — 80-90%, hard reject (allow = false)
+ *   - `PROMPT_EMERGENCY`            — ≥ 90%, hard reject + emergency
+ *   - `FORCED_OVER_THRESHOLD`       — user passed --force at CLI; allow = true
+ *
+ * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`.
+ */
+import { tierToCode, type ThresholdEvaluation } from './threshold.js';
+export type ContextGuardCode = 'OK' | 'CONTEXT_SOFT_WARN' | 'CONTEXT_NEAR_LIMIT' | 'PROMPT_TOO_LARGE' | 'PROMPT_EMERGENCY' | 'FORCED_OVER_THRESHOLD';
+export interface ContextGuardDecision {
+    readonly allow: boolean;
+    readonly code: ContextGuardCode;
+    readonly warnings: readonly string[];
+    readonly suggest: string | null;
+    readonly evaluation: ThresholdEvaluation;
+    /** ISO8601 timestamp when --force override was applied. null otherwise. */
+    readonly forcedAt: string | null;
+}
+export interface ContextGuardOptions {
+    /** Pass `true` to allow override at the ≥ 80% tier. CLI-only; hook layer MUST NOT set this. */
+    readonly force?: boolean;
+    /** Override the default 256K context capacity (e.g. for tests). */
+    readonly capacityBytes?: number;
+}
+/**
+ * Evaluate a prompt size against the G9.3 threshold table.
+ *
+ * The `force` option is the **only** path that lets a ≥ 80% prompt
+ * through. The hook layer (PreToolUse) MUST NOT accept this option;
+ * it is enforced by the `peaks sub-agent-dispatch-guard` atom's
+ * command-line parser, which does not declare a `--force` flag.
+ */
+export declare function evaluatePromptSize(promptSize: number, opts?: ContextGuardOptions): ContextGuardDecision;
+/**
+ * Re-export of `tierToCode` for callers that want a stable mapping
+ * without depending on the threshold module directly.
+ */
+export { tierToCode };

package/dist/src/services/context/context-guard.js

@@ -0,0 +1,91 @@
+/**
+ * G9 — forced compression gate (RL-27..RL-32).
+ *
+ * The CLI 兜底 layer. Validates prompt size against the threshold
+ * table in `threshold.ts` and returns a decision. The PreToolUse hook
+ * layer (`peaks sub-agent-dispatch-guard`) re-runs the same logic
+ * without `--force` (RL-30 strict).
+ *
+ * Decision codes:
+ *   - `OK`                          — under 50%
+ *   - `CONTEXT_SOFT_WARN`           — 50-75%, suggest --use-headroom
+ *   - `CONTEXT_NEAR_LIMIT`          — 75-80%, mandatory --use-headroom suggestion
+ *   - `PROMPT_TOO_LARGE`            — 80-90%, hard reject (allow = false)
+ *   - `PROMPT_EMERGENCY`            — ≥ 90%, hard reject + emergency
+ *   - `FORCED_OVER_THRESHOLD`       — user passed --force at CLI; allow = true
+ *
+ * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`.
+ */
+import { CONTEXT_CAPACITY_DEFAULT_BYTES, evaluateThresholdTier, tierToCode } from './threshold.js';
+const NEAR_LIMIT_SUGGEST = 'Consider --use-headroom to compress prompt.';
+const SOFT_WARN_SUGGEST = 'Use --use-headroom to compress prompt proactively.';
+const HARD_REJECT_SUGGEST = 'Trim prompt to < 80% of context capacity. Pass --force at CLI to override (NOT allowed at hook layer).';
+const EMERGENCY_SUGGEST = 'Prompt exceeds 90% of context. Trim aggressively or split into multiple dispatches.';
+/**
+ * Evaluate a prompt size against the G9.3 threshold table.
+ *
+ * The `force` option is the **only** path that lets a ≥ 80% prompt
+ * through. The hook layer (PreToolUse) MUST NOT accept this option;
+ * it is enforced by the `peaks sub-agent-dispatch-guard` atom's
+ * command-line parser, which does not declare a `--force` flag.
+ */
+export function evaluatePromptSize(promptSize, opts = {}) {
+    const capacity = opts.capacityBytes ?? CONTEXT_CAPACITY_DEFAULT_BYTES;
+    const evaluation = evaluateThresholdTier(promptSize, capacity);
+    const tier = evaluation.tier;
+    let allow;
+    let code;
+    let suggest;
+    let forcedAt = null;
+    switch (tier) {
+        case 'ok':
+            allow = true;
+            code = 'OK';
+            suggest = null;
+            break;
+        case 'soft-warn':
+            allow = true;
+            code = 'CONTEXT_SOFT_WARN';
+            suggest = SOFT_WARN_SUGGEST;
+            break;
+        case 'near-limit':
+            allow = true;
+            code = 'CONTEXT_NEAR_LIMIT';
+            suggest = NEAR_LIMIT_SUGGEST;
+            break;
+        case 'hard-reject':
+            allow = false;
+            code = 'PROMPT_TOO_LARGE';
+            suggest = HARD_REJECT_SUGGEST;
+            break;
+        case 'emergency':
+            allow = false;
+            code = 'PROMPT_EMERGENCY';
+            suggest = EMERGENCY_SUGGEST;
+            break;
+    }
+    // --force override (CLI only; hook layer never reaches this branch)
+    if (!allow && opts.force === true) {
+        allow = true;
+        code = 'FORCED_OVER_THRESHOLD';
+        suggest = 'Override applied at CLI. Hook layer will still reject.';
+        forcedAt = new Date().toISOString();
+    }
+    const warnings = [...evaluation.warnings];
+    if (forcedAt !== null && !warnings.includes('FORCED_OVER_THRESHOLD')) {
+        warnings.push('FORCED_OVER_THRESHOLD');
+    }
+    return {
+        allow,
+        code,
+        warnings,
+        suggest,
+        evaluation,
+        forcedAt
+    };
+}
+/**
+ * Re-export of `tierToCode` for callers that want a stable mapping
+ * without depending on the threshold module directly.
+ */
+export { tierToCode };

package/dist/src/services/context/dispatch-context-guard.d.ts

@@ -0,0 +1,27 @@
+/** Build the canonical artifact path for a given session/rid/role/idx/ext. */
+export declare function artifactPath(projectRoot: string, sid: string, rid: string, role: string, idx: number, ext?: string): string;
+/** Build the canonical shared channel path. */
+export declare function sharedChannelPath(projectRoot: string, sid: string, rid: string, batchId: string): string;
+/**
+ * Assert that `artifactPath` lives under
+ * `projectRoot/.peaks/_sub_agents/<sid>/artifacts/`. Rejects
+ * symlink/junction escapes and `..` segments.
+ *
+ * Throws an Error with `.code = 'INVALID_ARTIFACT_PATH'` on rejection.
+ */
+export declare function assertSafeArtifactPath(artifactPathInput: string, projectRoot: string): string;
+/**
+ * Assert that `channelPath` lives under
+ * `projectRoot/.peaks/_sub_agents/<sid>/shared/`. Same R-2 logic as
+ * `assertSafeArtifactPath` but with a different canonical subdir.
+ *
+ * Throws an Error with `.code = 'INVALID_SHARED_CHANNEL_PATH'` on rejection.
+ */
+export declare function assertSafeSharedChannelPath(channelPathInput: string, projectRoot: string): string;
+/**
+ * Soft-warn check on the artifact file name pattern. Returns null if
+ * the name matches `<rid>-<role>-<idx>.<ext>`, otherwise returns a
+ * warning string. Does NOT reject (the path is still in the canonical
+ * dir; the warning is for human/audit readability per G7.4.c).
+ */
+export declare function checkArtifactNameConvention(artifactPathInput: string): string | null;