peaks-cli 1.3.2 → 1.3.4

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

@@ -0,0 +1,192 @@
+/**
+ * G7.4 path safety + G8 path safety — R-2 symlink/junction guard for
+ * sub-agent artifact + shared channel paths.
+ *
+ * Slice #009's `assertSafeDispatchRecordPath` covers the dispatch record
+ * path. This module covers two adjacent paths under the same canonical
+ * root (`.peaks/_sub_agents/<sid>/`):
+ *
+ *   - `artifacts/<rid>-<role>-<idx>.<ext>`   (G7 write-artifact)
+ *   - `shared/<batchId>.json`                (G8 share / shared-read)
+ *
+ * Both reuse the same R-2 logic: reject `..` segments BEFORE the OS
+ * resolver collapses them (POSIX normalize silently drops `..`), reject
+ * absolute paths that escape the canonical root, resolve symlinks via
+ * `realpathSync` and re-check the resolved path.
+ *
+ * The canonical-root pattern is intentionally identical to the slice #009
+ * helper, so future audits can reuse one mental model: "all sub-agent
+ * state files must live under `.peaks/_sub_agents/<sid>/` and pass the
+ * same R-2 guard."
+ */
+import { realpathSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+const SUB_AGENTS_DIR = '_sub_agents';
+const ARTIFACTS_SUBDIR = 'artifacts';
+const SHARED_SUBDIR = 'shared';
+const ARTIFACT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*\.[A-Za-z0-9]+$/;
+const BATCH_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Build the canonical artifact path for a given session/rid/role/idx/ext. */
+export function artifactPath(projectRoot, sid, rid, role, idx, ext = 'md') {
+    if (typeof role !== 'string' || role.length === 0) {
+        throw new Error('artifactPath: role must be non-empty');
+    }
+    if (!Number.isInteger(idx) || idx < 1) {
+        throw new Error(`artifactPath: idx must be positive integer (got ${idx})`);
+    }
+    const safeSid = sanitizeSegment(sid, 'sessionId');
+    const safeRid = sanitizeSegment(rid, 'requestId');
+    const safeRole = sanitizeSegment(role, 'role');
+    const safeExt = ext.replace(/[^A-Za-z0-9]/g, '');
+    if (safeExt.length === 0) {
+        throw new Error(`artifactPath: ext must be alphanumeric (got "${ext}")`);
+    }
+    return resolve(projectRoot, '.peaks', SUB_AGENTS_DIR, safeSid, ARTIFACTS_SUBDIR, `${safeRid}-${safeRole}-${String(idx).padStart(3, '0')}.${safeExt}`);
+}
+/** Build the canonical shared channel path. */
+export function sharedChannelPath(projectRoot, sid, rid, batchId) {
+    if (typeof batchId !== 'string' || batchId.length === 0) {
+        throw new Error('sharedChannelPath: batchId must be non-empty');
+    }
+    const safeSid = sanitizeSegment(sid, 'sessionId');
+    const safeRid = sanitizeSegment(rid, 'requestId');
+    if (!BATCH_ID_PATTERN.test(batchId)) {
+        throw new Error(`sharedChannelPath: batchId must match ${BATCH_ID_PATTERN} (got "${batchId}")`);
+    }
+    return resolve(projectRoot, '.peaks', SUB_AGENTS_DIR, safeSid, SHARED_SUBDIR, `${safeRid}-${batchId}.json`);
+}
+/**
+ * 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 function assertSafeArtifactPath(artifactPathInput, projectRoot) {
+    if (!isAbsolute(artifactPathInput)) {
+        throw invalidPathError(artifactPathInput, 'must be absolute');
+    }
+    const rawSegments = artifactPathInput.split(/[\\/]/);
+    if (rawSegments.includes('..')) {
+        throw invalidPathError(artifactPathInput, 'must not contain .. segments');
+    }
+    const expected = resolve(projectRoot, '.peaks', SUB_AGENTS_DIR);
+    const rel = relative(expected, artifactPathInput);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw invalidPathError(artifactPathInput, 'must be under .peaks/_sub_agents/');
+    }
+    let realArtifact;
+    let realRoot;
+    try {
+        const parent = dirname(artifactPathInput);
+        const realParent = realpathSync(parent);
+        realArtifact = resolve(realParent, artifactPathInput.slice(parent.length + 1));
+        realRoot = realpathSync(projectRoot);
+    }
+    catch {
+        const fallback = resolve(projectRoot, '.peaks', SUB_AGENTS_DIR);
+        const rel2 = relative(fallback, artifactPathInput);
+        if (rel2.startsWith('..') || isAbsolute(rel2)) {
+            throw invalidPathError(artifactPathInput, 'must be under .peaks/_sub_agents/');
+        }
+        return artifactPathInput;
+    }
+    const realRel = relative(realRoot, realArtifact);
+    if (realRel.startsWith('..') || isAbsolute(realRel)) {
+        throw invalidPathError(artifactPathInput, 'symlink/junction escapes project root');
+    }
+    const realExpected = resolve(realRoot, '.peaks', SUB_AGENTS_DIR);
+    const realRelExpected = relative(realExpected, realArtifact);
+    if (realRelExpected.startsWith('..') || isAbsolute(realRelExpected)) {
+        throw invalidPathError(artifactPathInput, 'must be under .peaks/_sub_agents/');
+    }
+    return realArtifact;
+}
+/**
+ * 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 function assertSafeSharedChannelPath(channelPathInput, projectRoot) {
+    if (!isAbsolute(channelPathInput)) {
+        throw invalidPathErrorShared(channelPathInput, 'must be absolute');
+    }
+    const rawSegments = channelPathInput.split(/[\\/]/);
+    if (rawSegments.includes('..')) {
+        throw invalidPathErrorShared(channelPathInput, 'must not contain .. segments');
+    }
+    const expected = resolve(projectRoot, '.peaks', SUB_AGENTS_DIR);
+    const rel = relative(expected, channelPathInput);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw invalidPathErrorShared(channelPathInput, 'must be under .peaks/_sub_agents/shared/');
+    }
+    let realChannel;
+    let realRoot;
+    try {
+        const parent = dirname(channelPathInput);
+        const realParent = realpathSync(parent);
+        realChannel = resolve(realParent, channelPathInput.slice(parent.length + 1));
+        realRoot = realpathSync(projectRoot);
+    }
+    catch {
+        const fallback = resolve(projectRoot, '.peaks', SUB_AGENTS_DIR);
+        const rel2 = relative(fallback, channelPathInput);
+        if (rel2.startsWith('..') || isAbsolute(rel2)) {
+            throw invalidPathErrorShared(channelPathInput, 'must be under .peaks/_sub_agents/shared/');
+        }
+        return channelPathInput;
+    }
+    const realRel = relative(realRoot, realChannel);
+    if (realRel.startsWith('..') || isAbsolute(realRel)) {
+        throw invalidPathErrorShared(channelPathInput, 'symlink/junction escapes project root');
+    }
+    const realExpected = resolve(realRoot, '.peaks', SUB_AGENTS_DIR);
+    const realRelExpected = relative(realExpected, realChannel);
+    if (realRelExpected.startsWith('..') || isAbsolute(realRelExpected)) {
+        throw invalidPathErrorShared(channelPathInput, 'must be under .peaks/_sub_agents/shared/');
+    }
+    return realChannel;
+}
+/**
+ * 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 function checkArtifactNameConvention(artifactPathInput) {
+    const base = artifactPathInput.split(/[\\/]/).pop() ?? '';
+    if (ARTIFACT_NAME_PATTERN.test(base)) {
+        return null;
+    }
+    return `Artifact file name does not match <rid>-<role>-<idx>.<ext> convention: ${base}`;
+}
+function sanitizeSegment(value, field) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${field} must be non-empty`);
+    }
+    if (value.length > 256) {
+        throw new Error(`${field} must be ≤ 256 chars (got ${value.length})`);
+    }
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x20 || code === 0x7F) {
+            throw new Error(`${field} must not contain whitespace or control characters`);
+        }
+    }
+    if (value.includes('..') || value.includes('/') || value.includes('\\')) {
+        throw new Error(`${field} must not contain '..' or path separators`);
+    }
+    return value;
+}
+function invalidPathError(path, reason) {
+    const e = new Error(`Invalid artifact path: ${reason} (path: ${path})`);
+    e.code = 'INVALID_ARTIFACT_PATH';
+    return e;
+}
+function invalidPathErrorShared(path, reason) {
+    const e = new Error(`Invalid shared channel path: ${reason} (path: ${path})`);
+    e.code = 'INVALID_SHARED_CHANNEL_PATH';
+    return e;
+}

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

@@ -0,0 +1,34 @@
+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/src/services/context/headroom-client.js

@@ -0,0 +1,117 @@
+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/src/services/context/shared-channel.d.ts

@@ -0,0 +1,92 @@
+export interface SharedChannelEntry {
+    readonly at: string;
+    readonly from: string;
+    readonly key: string;
+    readonly value: Readonly<Record<string, unknown>>;
+    readonly valueSize: number;
+}
+export interface SharedChannel {
+    readonly batchId: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly entries: Readonly<Record<string, SharedChannelEntry>>;
+}
+export declare const SHARED_CHANNEL_MAX_VALUE_BYTES: number;
+export declare const SHARED_CHANNEL_SOFT_VALUE_WARN = 1024;
+export declare const SHARED_CHANNEL_MAX_FILE_BYTES: number;
+export declare const SHARED_CHANNEL_TTL_DAYS = 30;
+export type WriteSharedEntryResult = {
+    readonly ok: true;
+    readonly entry: SharedChannelEntry;
+    readonly channelSize: number;
+    readonly lastWriteWins: boolean;
+    readonly softWarning: boolean;
+} | {
+    readonly ok: false;
+    readonly code: 'VALUE_TOO_LARGE' | 'INVALID_BATCH_ID' | 'WRITE_ERROR';
+    readonly message: string;
+};
+/**
+ * Write a shared entry to the per-batch channel file. Atomic-write
+ * (tmp + rename). Returns the new entry + channel size + last-write-wins
+ * flag (true if the key already existed; the new value overwrites).
+ *
+ * RL-25 size limit: `value ≥ 64KB` is hard-rejected with `VALUE_TOO_LARGE`.
+ * `value > 1KB and < 64KB` is a soft warning (returned in the result).
+ */
+export declare function writeSharedEntry(opts: {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+    batchId: string;
+    key: string;
+    from: string;
+    value: Record<string, unknown>;
+}): WriteSharedEntryResult;
+/**
+ * Read the shared channel for a batch. Returns the channel with all
+ * matching entries. Filters: `--since` (ISO8601) and `--key` (glob
+ * pattern; simple `*` wildcard, no regex).
+ *
+ * If the channel file does not exist, returns an empty channel
+ * (this is the dispatcher's "fresh batch" view).
+ */
+export declare function readSharedChannel(opts: {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+    batchId: string;
+    since?: string;
+    keyPattern?: string;
+}): SharedChannel;
+/**
+ * Garbage-collect a single channel. Returns true if the file was
+ * deleted, false if it did not exist.
+ */
+export declare function gcChannel(opts: {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+    batchId: string;
+}): boolean;
+/**
+ * Check if a channel file is older than `SHARED_CHANNEL_TTL_DAYS` days
+ * and should be GC'd as an orphan. Returns true if file is missing
+ * (already GC'd) or older than TTL.
+ */
+export declare function isOrphanChannel(opts: {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+    batchId: string;
+    now?: Date;
+}): boolean;
+/**
+ * Compile a simple key pattern with `*` wildcards to a matcher. Only
+ * `*` is special; everything else is a literal. `*` matches zero or
+ * more characters. Examples:
+ *   "rd.*"       matches "rd.completed", "rd.found-blocker"
+ *   "*.completed" matches "rd.completed", "qa.completed"
+ *   "*"           matches everything
+ */
+export declare function compileKeyPattern(pattern: string): (key: string) => boolean;