byterover-cli 2.0.0 → 2.1.0

package/dist/server/infra/cogit/context-tree-to-push-context-mapper.js

@@ -1,4 +1,5 @@
 import { CogitPushContext } from '../../core/domain/entities/cogit-push-context.js';
+import { isExcludedFromSync } from '../context-tree/derived-artifact.js';
 /**
  * Maps context file contents to CogitPushContext instances for the CoGit API.
  * Converts file reader output to the format expected by the push service.
@@ -7,21 +8,27 @@ import { CogitPushContext } from '../../core/domain/entities/cogit-push-context.
  * @returns Array of CogitPushContext instances ready for the push API
  */
 export const mapToPushContexts = (params) => {
-    const addedContextFiles = params.addedFiles.map((file) => new CogitPushContext({
+    const addedContextFiles = params.addedFiles
+        .filter((file) => !isExcludedFromSync(file.path))
+        .map((file) => new CogitPushContext({
         content: file.content,
         operation: 'add',
         path: file.path,
         tags: file.tags,
         title: file.title,
     }));
-    const editedContextFiles = params.modifiedFiles.map((file) => new CogitPushContext({
+    const editedContextFiles = params.modifiedFiles
+        .filter((file) => !isExcludedFromSync(file.path))
+        .map((file) => new CogitPushContext({
         content: file.content,
         operation: 'edit',
         path: file.path,
         tags: file.tags,
         title: file.title,
     }));
-    const deletedContextFiles = params.deletedPaths.map((deletedPath) => new CogitPushContext({
+    const deletedContextFiles = params.deletedPaths
+        .filter((deletedPath) => !isExcludedFromSync(deletedPath))
+        .map((deletedPath) => new CogitPushContext({
         content: '',
         operation: 'delete',
         path: deletedPath,

package/dist/server/infra/connectors/skill/skill-connector.d.ts

@@ -39,6 +39,10 @@ export declare class SkillConnector implements IConnector {
      * Write files to a named skill subdirectory for the given agent.
      * Used by hub install to write downloaded skill files to e.g. `.claude/skills/{skillName}/`.
      *
+     * @param agent - Agent connector target
+     * @param skillName - Skill folder name to create under the connector path
+     * @param files - Skill files to write
+     * @param options - Optional install scope
      * @param options.scope - 'global' writes to home dir, 'project' (default) writes to project root
      */
     writeSkillFiles(agent: Agent, skillName: string, files: Array<{

package/dist/server/infra/connectors/skill/skill-connector.js

@@ -216,6 +216,10 @@ export class SkillConnector {
      * Write files to a named skill subdirectory for the given agent.
      * Used by hub install to write downloaded skill files to e.g. `.claude/skills/{skillName}/`.
      *
+     * @param agent - Agent connector target
+     * @param skillName - Skill folder name to create under the connector path
+     * @param files - Skill files to write
+     * @param options - Optional install scope
      * @param options.scope - 'global' writes to home dir, 'project' (default) writes to project root
      */
     async writeSkillFiles(agent, skillName, files, options) {

package/dist/server/infra/context-tree/children-hash.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Children hash utility for summary staleness detection.
+ *
+ * Computes a deterministic hash from child paths and their content hashes.
+ * Including paths (not just content hashes) ensures that renames and moves
+ * are detected as structural changes.
+ */
+/**
+ * Compute a deterministic hash of children for staleness detection.
+ *
+ * The hash includes both the relative path and content hash of each child,
+ * sorted by path for determinism. This detects:
+ * - Content changes (different contentHash)
+ * - Renames/moves (different path, same contentHash)
+ * - Additions/deletions (different set of paths)
+ */
+export declare function computeChildrenHash(children: Array<{
+    contentHash: string;
+    path: string;
+}>): string;

package/dist/server/infra/context-tree/children-hash.js

@@ -0,0 +1,22 @@
+/**
+ * Children hash utility for summary staleness detection.
+ *
+ * Computes a deterministic hash from child paths and their content hashes.
+ * Including paths (not just content hashes) ensures that renames and moves
+ * are detected as structural changes.
+ */
+import { computeContentHash } from './hash-utils.js';
+/**
+ * Compute a deterministic hash of children for staleness detection.
+ *
+ * The hash includes both the relative path and content hash of each child,
+ * sorted by path for determinism. This detects:
+ * - Content changes (different contentHash)
+ * - Renames/moves (different path, same contentHash)
+ * - Additions/deletions (different set of paths)
+ */
+export function computeChildrenHash(children) {
+    const sorted = [...children].sort((a, b) => a.path.localeCompare(b.path));
+    const input = sorted.map((c) => `${c.path}:${c.contentHash}`).join('\n');
+    return computeContentHash(input);
+}

package/dist/server/infra/context-tree/derived-artifact.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Derived-artifact predicates for the Hierarchical DAG architecture.
+ *
+ * Three predicates with clear separation of concerns:
+ * - isDerivedArtifact()  — non-searchable derived content (excluded from query fingerprint)
+ * - isArchiveStub()      — searchable stubs (included in BM25 index and fingerprint)
+ * - isExcludedFromSync() — union of above (excluded from snapshot/sync/merge/push)
+ */
+/**
+ * Returns true if the given relative path is a derived artifact
+ * that should be excluded from snapshot tracking, CoGit sync,
+ * and query cache fingerprinting.
+ *
+ * Derived artifacts: _index.md, _manifest.json, _archived/*.full.md
+ * NOTE: _archived/*.stub.md are NOT derived — they are searchable.
+ */
+export declare function isDerivedArtifact(relativePath: string): boolean;
+/**
+ * Returns true if the path is an archive stub (.stub.md inside _archived/).
+ * Stubs are searchable but excluded from snapshot/sync.
+ */
+export declare function isArchiveStub(relativePath: string): boolean;
+/**
+ * Returns true if the path should be excluded from snapshot tracking,
+ * CoGit sync (push/pull/merge), and writer operations.
+ * This includes ALL derived artifacts plus searchable stubs.
+ */
+export declare function isExcludedFromSync(relativePath: string): boolean;

package/dist/server/infra/context-tree/derived-artifact.js

@@ -0,0 +1,48 @@
+/**
+ * Derived-artifact predicates for the Hierarchical DAG architecture.
+ *
+ * Three predicates with clear separation of concerns:
+ * - isDerivedArtifact()  — non-searchable derived content (excluded from query fingerprint)
+ * - isArchiveStub()      — searchable stubs (included in BM25 index and fingerprint)
+ * - isExcludedFromSync() — union of above (excluded from snapshot/sync/merge/push)
+ */
+import { ARCHIVE_DIR, FULL_ARCHIVE_EXTENSION, MANIFEST_FILE, STUB_EXTENSION, SUMMARY_INDEX_FILE } from '../../constants.js';
+import { toUnixPath } from './path-utils.js';
+/**
+ * Returns true if the given relative path is a derived artifact
+ * that should be excluded from snapshot tracking, CoGit sync,
+ * and query cache fingerprinting.
+ *
+ * Derived artifacts: _index.md, _manifest.json, _archived/*.full.md
+ * NOTE: _archived/*.stub.md are NOT derived — they are searchable.
+ */
+export function isDerivedArtifact(relativePath) {
+    const normalized = toUnixPath(relativePath);
+    const segments = normalized.split('/');
+    const fileName = segments.at(-1) ?? '';
+    if (fileName === SUMMARY_INDEX_FILE)
+        return true;
+    if (fileName === MANIFEST_FILE)
+        return true;
+    if (segments.includes(ARCHIVE_DIR) && fileName.endsWith(FULL_ARCHIVE_EXTENSION))
+        return true;
+    return false;
+}
+/**
+ * Returns true if the path is an archive stub (.stub.md inside _archived/).
+ * Stubs are searchable but excluded from snapshot/sync.
+ */
+export function isArchiveStub(relativePath) {
+    const normalized = toUnixPath(relativePath);
+    const segments = normalized.split('/');
+    const fileName = segments.at(-1) ?? '';
+    return segments.includes(ARCHIVE_DIR) && fileName.endsWith(STUB_EXTENSION);
+}
+/**
+ * Returns true if the path should be excluded from snapshot tracking,
+ * CoGit sync (push/pull/merge), and writer operations.
+ * This includes ALL derived artifacts plus searchable stubs.
+ */
+export function isExcludedFromSync(relativePath) {
+    return isDerivedArtifact(relativePath) || isArchiveStub(relativePath);
+}

package/dist/server/infra/context-tree/file-context-tree-archive-service.d.ts

@@ -0,0 +1,37 @@
+/**
+ * File-based implementation of IContextTreeArchiveService.
+ *
+ * Archives low-importance context entries into _archived/ with:
+ * - .full.md: lossless preserved original content
+ * - .stub.md: searchable ghost cue (~220 tokens) with lineage pointers
+ *
+ * Archive naming preserves relative paths to avoid collisions:
+ *   auth/jwt-tokens/refresh-flow.md → _archived/auth/jwt-tokens/refresh-flow.stub.md
+ *
+ * Fail-open: any error during ghost cue generation falls back to deterministic truncation.
+ */
+import type { ICipherAgent } from '../../../agent/core/interfaces/i-cipher-agent.js';
+import type { ArchiveResult, DrillDownResult } from '../../core/domain/knowledge/summary-types.js';
+import type { IContextTreeArchiveService } from '../../core/interfaces/context-tree/i-context-tree-archive-service.js';
+export declare class FileContextTreeArchiveService implements IContextTreeArchiveService {
+    archiveEntry(relativePath: string, agent: ICipherAgent, directory?: string): Promise<ArchiveResult>;
+    drillDown(stubPath: string, directory?: string): Promise<DrillDownResult>;
+    findArchiveCandidates(directory?: string): Promise<string[]>;
+    restoreEntry(stubPath: string, directory?: string): Promise<string>;
+    /**
+     * Extract importance score from frontmatter. Returns 50 if not found.
+     */
+    private extractImportance;
+    /**
+     * Generate a ghost cue using LLM with deterministic fallback.
+     */
+    private generateGhostCue;
+    /**
+     * Parse FrontmatterScoring fields from content frontmatter.
+     */
+    private parseScoring;
+    /**
+     * Recursively scan context tree for archive candidates.
+     */
+    private scanForCandidates;
+}

package/dist/server/infra/context-tree/file-context-tree-archive-service.js

@@ -0,0 +1,219 @@
+/* eslint-disable camelcase */
+/**
+ * File-based implementation of IContextTreeArchiveService.
+ *
+ * Archives low-importance context entries into _archived/ with:
+ * - .full.md: lossless preserved original content
+ * - .stub.md: searchable ghost cue (~220 tokens) with lineage pointers
+ *
+ * Archive naming preserves relative paths to avoid collisions:
+ *   auth/jwt-tokens/refresh-flow.md → _archived/auth/jwt-tokens/refresh-flow.stub.md
+ *
+ * Fail-open: any error during ghost cue generation falls back to deterministic truncation.
+ */
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { dirname, extname, join } from 'node:path';
+import { ARCHIVE_DIR, ARCHIVE_IMPORTANCE_THRESHOLD, BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, DEFAULT_GHOST_CUE_MAX_TOKENS, FULL_ARCHIVE_EXTENSION, STUB_EXTENSION, } from '../../constants.js';
+import { applyDecay } from '../../core/domain/knowledge/memory-scoring.js';
+import { estimateTokens } from '../executor/pre-compaction/compaction-escalation.js';
+import { isArchiveStub, isDerivedArtifact } from './derived-artifact.js';
+import { toUnixPath } from './path-utils.js';
+import { generateArchiveStubContent, parseArchiveStubFrontmatter } from './summary-frontmatter.js';
+export class FileContextTreeArchiveService {
+    async archiveEntry(relativePath, agent, directory) {
+        const baseDir = directory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const originalFullPath = join(contextTreeDir, relativePath);
+        // Read original content
+        const content = await readFile(originalFullPath, 'utf8');
+        const originalTokenCount = estimateTokens(content);
+        // Compute archive paths: replace extension with .stub.md / .full.md
+        const pathWithoutExt = relativePath.slice(0, -extname(relativePath).length);
+        const stubRelPath = join(ARCHIVE_DIR, `${pathWithoutExt}${STUB_EXTENSION}`);
+        const fullRelPath = join(ARCHIVE_DIR, `${pathWithoutExt}${FULL_ARCHIVE_EXTENSION}`);
+        const stubFullPath = join(contextTreeDir, stubRelPath);
+        const fullFullPath = join(contextTreeDir, fullRelPath);
+        // Create parent directories under _archived/
+        await mkdir(dirname(stubFullPath), { recursive: true });
+        // Write .full.md — verbatim original content (lossless)
+        await writeFile(fullFullPath, content, 'utf8');
+        // Generate ghost cue via LLM (fail-open to deterministic truncation)
+        const ghostCue = await this.generateGhostCue(agent, content);
+        const ghostCueTokenCount = estimateTokens(ghostCue);
+        // Parse frontmatter to get importance for eviction metadata
+        const importance = this.extractImportance(content);
+        // Write .stub.md with archive stub frontmatter
+        const stubContent = generateArchiveStubContent({
+            evicted_at: new Date().toISOString(),
+            evicted_importance: importance,
+            original_path: relativePath,
+            original_token_count: originalTokenCount,
+            points_to: toUnixPath(fullRelPath),
+            type: 'archive_stub',
+        }, ghostCue);
+        await writeFile(stubFullPath, stubContent, 'utf8');
+        // Delete original file
+        await unlink(originalFullPath);
+        return {
+            fullPath: toUnixPath(fullRelPath),
+            ghostCueTokenCount,
+            originalPath: relativePath,
+            stubPath: toUnixPath(stubRelPath),
+        };
+    }
+    async drillDown(stubPath, directory) {
+        const baseDir = directory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const stubFullPath = join(contextTreeDir, stubPath);
+        // Parse stub to get points_to
+        const stubContent = await readFile(stubFullPath, 'utf8');
+        const fm = parseArchiveStubFrontmatter(stubContent);
+        if (!fm) {
+            throw new Error(`Invalid archive stub: ${stubPath}`);
+        }
+        // Read full content
+        const fullPath = join(contextTreeDir, fm.points_to);
+        const fullContent = await readFile(fullPath, 'utf8');
+        return {
+            fullContent,
+            originalPath: fm.original_path,
+            tokenCount: estimateTokens(fullContent),
+        };
+    }
+    async findArchiveCandidates(directory) {
+        const baseDir = directory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const candidates = [];
+        await this.scanForCandidates(contextTreeDir, contextTreeDir, candidates);
+        return candidates;
+    }
+    async restoreEntry(stubPath, directory) {
+        const baseDir = directory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const stubFullPath = join(contextTreeDir, stubPath);
+        // Parse stub to get original_path and points_to
+        const stubContent = await readFile(stubFullPath, 'utf8');
+        const fm = parseArchiveStubFrontmatter(stubContent);
+        if (!fm) {
+            throw new Error(`Invalid archive stub: ${stubPath}`);
+        }
+        // Read full content
+        const fullPath = join(contextTreeDir, fm.points_to);
+        const fullContent = await readFile(fullPath, 'utf8');
+        // Write to original path (restore)
+        const restoredPath = join(contextTreeDir, fm.original_path);
+        await mkdir(dirname(restoredPath), { recursive: true });
+        await writeFile(restoredPath, fullContent, 'utf8');
+        // Delete stub and full archive files
+        await unlink(stubFullPath);
+        await unlink(fullPath);
+        return fm.original_path;
+    }
+    /**
+     * Extract importance score from frontmatter. Returns 50 if not found.
+     */
+    extractImportance(content) {
+        const match = /^importance:\s*(\d+(?:\.\d+)?)/m.exec(content);
+        return match ? Number.parseFloat(match[1]) : 50;
+    }
+    /**
+     * Generate a ghost cue using LLM with deterministic fallback.
+     */
+    async generateGhostCue(agent, content) {
+        try {
+            const taskId = `ghost_cue_${Date.now()}`;
+            const sessionId = await agent.createTaskSession(taskId, 'query');
+            try {
+                const prompt = `Summarize the following knowledge entry in ~${DEFAULT_GHOST_CUE_MAX_TOKENS} tokens or less. Output ONLY the summary. Preserve key entity names and relationships.
+
+<content>
+${content.slice(0, 8000)}
+</content>`;
+                const response = await agent.executeOnSession(sessionId, prompt, {
+                    executionContext: {
+                        clearHistory: true,
+                        commandType: 'query',
+                        maxIterations: 1,
+                        maxTokens: DEFAULT_GHOST_CUE_MAX_TOKENS * 4, // chars ≈ tokens * 4
+                        temperature: 0.3,
+                    },
+                    taskId,
+                });
+                if (response && response.trim().length > 20) {
+                    return response.trim();
+                }
+            }
+            finally {
+                await agent.deleteTaskSession(sessionId);
+            }
+        }
+        catch {
+            // Fall through to deterministic fallback
+        }
+        // Deterministic fallback: truncate content
+        return `${content.replaceAll(/\s+/g, ' ').trim().slice(0, 320)}...`;
+    }
+    /**
+     * Parse FrontmatterScoring fields from content frontmatter.
+     */
+    parseScoring(content) {
+        const scoring = {};
+        const importanceMatch = /^importance:\s*(\d+(?:\.\d+)?)/m.exec(content);
+        if (importanceMatch)
+            scoring.importance = Number.parseFloat(importanceMatch[1]);
+        const maturityMatch = /^maturity:\s*['"]?(core|draft|validated)['"]?/m.exec(content);
+        if (maturityMatch)
+            scoring.maturity = maturityMatch[1];
+        const updatedMatch = /^updatedAt:\s*['"]?(.+?)['"]?\s*$/m.exec(content);
+        if (updatedMatch)
+            scoring.updatedAt = updatedMatch[1];
+        return scoring;
+    }
+    /**
+     * Recursively scan context tree for archive candidates.
+     */
+    async scanForCandidates(currentDir, contextTreeDir, candidates) {
+        const { readdir: readdirFs } = await import('node:fs/promises');
+        let entries;
+        try {
+            entries = await readdirFs(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        const now = Date.now();
+        /* eslint-disable no-await-in-loop */
+        for (const entry of entries) {
+            const entryName = entry.name;
+            const fullPath = join(currentDir, entryName);
+            if (entry.isDirectory()) {
+                if (entryName === ARCHIVE_DIR)
+                    continue;
+                await this.scanForCandidates(fullPath, contextTreeDir, candidates);
+            }
+            else if (entry.isFile() && entryName.endsWith(CONTEXT_FILE_EXTENSION)) {
+                const relativePath = toUnixPath(fullPath.slice(contextTreeDir.length + 1));
+                if (isDerivedArtifact(relativePath) || isArchiveStub(relativePath))
+                    continue;
+                try {
+                    const content = await readFile(fullPath, 'utf8');
+                    const scoring = this.parseScoring(content);
+                    // Only archive draft entries below importance threshold
+                    if (scoring.maturity !== 'draft')
+                        continue;
+                    const daysSinceUpdate = scoring.updatedAt
+                        ? (now - new Date(scoring.updatedAt).getTime()) / (1000 * 60 * 60 * 24)
+                        : 0;
+                    const decayed = applyDecay(scoring, daysSinceUpdate);
+                    if ((decayed.importance ?? 50) < ARCHIVE_IMPORTANCE_THRESHOLD) {
+                        candidates.push(relativePath);
+                    }
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+    }
+}

package/dist/server/infra/context-tree/file-context-tree-manifest-service.d.ts

@@ -0,0 +1,50 @@
+/**
+ * File-based implementation of IContextTreeManifestService.
+ *
+ * Builds and reads the context manifest (_manifest.json) which allocates
+ * context tree entries into three lanes (summaries, contexts, stubs)
+ * with token budgets for efficient query context injection.
+ *
+ * Freshness check uses source_fingerprint (hash of sorted path:mtime:size)
+ * to detect additions, modifications, and deletions. Stat-only, no file reads.
+ *
+ * Tradeoff: rare false-fresh cases where content changes but mtime+size
+ * are preserved. Acceptable because writeFile() updates mtime and the next
+ * curate run will rebuild the manifest anyway.
+ */
+import type { ContextManifest, LaneTokens, ResolvedEntry } from '../../core/domain/knowledge/summary-types.js';
+import type { IContextTreeManifestService } from '../../core/interfaces/context-tree/i-context-tree-manifest-service.js';
+export interface ManifestServiceConfig {
+    baseDirectory?: string;
+}
+export declare class FileContextTreeManifestService implements IContextTreeManifestService {
+    private readonly config;
+    constructor(config?: ManifestServiceConfig);
+    buildManifest(directory?: string, laneBudgets?: LaneTokens): Promise<ContextManifest>;
+    readManifest(directory?: string): Promise<ContextManifest | null>;
+    readManifestIfFresh(directory?: string): Promise<ContextManifest | null>;
+    resolveForInjection(manifest: ContextManifest, _query?: string, directory?: string): Promise<ResolvedEntry[]>;
+    /**
+     * Allocate entries into a lane respecting the token budget.
+     * Entries are already sorted by priority (caller responsibility).
+     */
+    private allocateLane;
+    /**
+     * Compute source fingerprint from stat data (path:mtime:size).
+     * Stat-only — no file reads required.
+     */
+    private computeSourceFingerprint;
+    /**
+     * Recursively scan _archived/ directory for .stub.md files.
+     */
+    private scanArchivedStubs;
+    /**
+     * Recursively scan context tree, collecting entries for manifest building.
+     */
+    private scanForManifest;
+    /**
+     * Recursively collect stat data for all source files (for fingerprint).
+     * Excludes derived artifacts.
+     */
+    private scanSourceStats;
+}