@compilr-dev/cli 0.8.7 → 0.8.8

package/dist/episodes/store.d.ts

@@ -1,38 +0,0 @@
-/**
- * File-Based Episode Store
- *
- * Persists work episodes to a JSON file per project.
- * Uses an in-memory cache — all reads are synchronous, writes are async (fire-and-forget).
- */
-import type { WorkEpisode, ProjectWorkSummary, Effort, EpisodeStore } from '@compilr-dev/agents';
-export interface FileEpisodeStoreOptions {
-    /** Path to the episodes JSON file */
-    filePath: string;
-    /** Maximum episodes to keep (oldest pruned on flush). Default: 1000 */
-    maxEpisodes?: number;
-    /** Maximum age in milliseconds for cleanup. Default: 30 days */
-    maxAgeMs?: number;
-}
-export declare class FileEpisodeStore implements EpisodeStore {
-    private readonly filePath;
-    private readonly maxEpisodes;
-    private readonly maxAgeMs;
-    private _episodes;
-    private flushPromise;
-    constructor(options: FileEpisodeStoreOptions);
-    /** Lazy-load and return the in-memory episode cache */
-    private get episodes();
-    save(episode: WorkEpisode): void;
-    saveBatch(episodes: WorkEpisode[]): void;
-    getAll(): WorkEpisode[];
-    getByFiles(files: string[]): WorkEpisode[];
-    getByAgent(agentId: string): WorkEpisode[];
-    getBySession(sessionId: string): WorkEpisode[];
-    getByTimeRange(start: string, end: string): WorkEpisode[];
-    getRecent(count: number): WorkEpisode[];
-    getWorkSummary(): ProjectWorkSummary;
-    getTotalEffort(episodes?: WorkEpisode[]): Effort;
-    cleanup(maxAgeMs?: number): number;
-    private loadFromDisk;
-    private flush;
-}

package/dist/episodes/store.js

@@ -1,199 +0,0 @@
-/**
- * File-Based Episode Store
- *
- * Persists work episodes to a JSON file per project.
- * Uses an in-memory cache — all reads are synchronous, writes are async (fire-and-forget).
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import { EFFORT_ORDER } from '@compilr-dev/agents';
-// =============================================================================
-// Constants
-// =============================================================================
-const DEFAULT_MAX_EPISODES = 1000;
-const DEFAULT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
-// =============================================================================
-// Implementation
-// =============================================================================
-export class FileEpisodeStore {
-    filePath;
-    maxEpisodes;
-    maxAgeMs;
-    _episodes = null; // lazy-loaded
-    flushPromise = null;
-    constructor(options) {
-        this.filePath = options.filePath;
-        this.maxEpisodes = options.maxEpisodes ?? DEFAULT_MAX_EPISODES;
-        this.maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
-    }
-    /** Lazy-load and return the in-memory episode cache */
-    get episodes() {
-        if (this._episodes === null) {
-            this._episodes = this.loadFromDisk();
-        }
-        return this._episodes;
-    }
-    // ---------------------------------------------------------------------------
-    // Write methods
-    // ---------------------------------------------------------------------------
-    save(episode) {
-        this.episodes.push(episode);
-        void this.flush();
-    }
-    saveBatch(episodes) {
-        if (episodes.length === 0)
-            return;
-        this.episodes.push(...episodes);
-        void this.flush();
-    }
-    // ---------------------------------------------------------------------------
-    // Read methods (synchronous — read from cache)
-    // ---------------------------------------------------------------------------
-    getAll() {
-        return [...this.episodes];
-    }
-    getByFiles(files) {
-        const fileSet = new Set(files);
-        return this.episodes.filter((ep) => ep.files.some((f) => fileSet.has(f)));
-    }
-    getByAgent(agentId) {
-        return this.episodes.filter((ep) => ep.agentId === agentId);
-    }
-    getBySession(sessionId) {
-        return this.episodes.filter((ep) => ep.sessionId === sessionId);
-    }
-    getByTimeRange(start, end) {
-        return this.episodes.filter((ep) => ep.timestamp >= start && ep.timestamp <= end);
-    }
-    getRecent(count) {
-        return this.episodes.slice(-count);
-    }
-    getWorkSummary() {
-        const eps = this.episodes;
-        // Agent breakdown
-        const agentMap = new Map();
-        for (const ep of eps) {
-            const entry = agentMap.get(ep.agentId) ?? { count: 0, maxEffort: 'trivial', timeMs: 0 };
-            entry.count++;
-            if (EFFORT_ORDER.indexOf(ep.effort) > EFFORT_ORDER.indexOf(entry.maxEffort)) {
-                entry.maxEffort = ep.effort;
-            }
-            entry.timeMs += ep.durationMs ?? 0;
-            agentMap.set(ep.agentId, entry);
-        }
-        // Top files
-        const fileCount = new Map();
-        for (const ep of eps) {
-            for (const f of ep.files) {
-                fileCount.set(f, (fileCount.get(f) ?? 0) + 1);
-            }
-        }
-        const topFiles = [...fileCount.entries()]
-            .sort((a, b) => b[1] - a[1])
-            .slice(0, 10)
-            .map(([p, touchCount]) => ({ path: p, touchCount }));
-        // Uncommitted work: episodes after last git_commit episode
-        let lastCommitIdx = -1;
-        for (let i = eps.length - 1; i >= 0; i--) {
-            if (eps[i].action === 'commit') {
-                lastCommitIdx = i;
-                break;
-            }
-        }
-        const uncommittedWork = lastCommitIdx >= 0 ? eps.slice(lastCommitIdx + 1) : [...eps];
-        return {
-            episodeCount: eps.length,
-            totalEffort: this.getTotalEffort(eps),
-            timeSpentMs: eps.reduce((sum, ep) => sum + (ep.durationMs ?? 0), 0),
-            agentBreakdown: [...agentMap.entries()].map(([agentId, entry]) => ({
-                agentId,
-                episodeCount: entry.count,
-                maxEffort: entry.maxEffort,
-                timeSpentMs: entry.timeMs,
-            })),
-            topFiles,
-            uncommittedWork,
-        };
-    }
-    getTotalEffort(episodes) {
-        const eps = episodes ?? this.episodes;
-        if (eps.length === 0)
-            return 'trivial';
-        return maxEffort(eps);
-    }
-    // ---------------------------------------------------------------------------
-    // Cleanup
-    // ---------------------------------------------------------------------------
-    cleanup(maxAgeMs) {
-        const cutoff = new Date(Date.now() - (maxAgeMs ?? this.maxAgeMs)).toISOString();
-        const before = this.episodes.length;
-        this._episodes = this.episodes.filter((ep) => ep.timestamp > cutoff);
-        const removed = before - this._episodes.length;
-        if (removed > 0) {
-            void this.flush();
-        }
-        return removed;
-    }
-    // ---------------------------------------------------------------------------
-    // Internal
-    // ---------------------------------------------------------------------------
-    loadFromDisk() {
-        try {
-            if (!fs.existsSync(this.filePath))
-                return [];
-            const raw = fs.readFileSync(this.filePath, 'utf-8');
-            const data = JSON.parse(raw);
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime data from disk, version may differ
-            if (data.version === 1 && Array.isArray(data.episodes)) {
-                return data.episodes;
-            }
-            return [];
-        }
-        catch {
-            // Corrupted file — start fresh
-            return [];
-        }
-    }
-    async flush() {
-        // Coalesce concurrent flushes
-        if (this.flushPromise)
-            return this.flushPromise;
-        this.flushPromise = (async () => {
-            try {
-                const dir = path.dirname(this.filePath);
-                await fs.promises.mkdir(dir, { recursive: true });
-                // Prune to max episodes (keep most recent)
-                const eps = this.episodes;
-                const prunedEpisodes = eps.length > this.maxEpisodes ? eps.slice(-this.maxEpisodes) : eps;
-                if (prunedEpisodes !== eps) {
-                    this._episodes = prunedEpisodes;
-                }
-                const data = {
-                    version: 1,
-                    episodes: prunedEpisodes,
-                    lastCleanup: new Date().toISOString(),
-                };
-                await fs.promises.writeFile(this.filePath, JSON.stringify(data, null, 2), 'utf-8');
-            }
-            catch {
-                // Silently fail — episodes are best-effort, never crash the CLI
-            }
-            finally {
-                this.flushPromise = null;
-            }
-        })();
-        return this.flushPromise;
-    }
-}
-// =============================================================================
-// Helpers (module-private)
-// =============================================================================
-function maxEffort(episodes) {
-    let max = 'trivial';
-    for (const ep of episodes) {
-        if (EFFORT_ORDER.indexOf(ep.effort) > EFFORT_ORDER.indexOf(max)) {
-            max = ep.effort;
-        }
-    }
-    return max;
-}

package/dist/episodes/types.d.ts

@@ -1,35 +0,0 @@
-/**
- * Episodic Memory Types (CLI)
- *
- * Re-exports core types from @compilr-dev/agents and adds CLI-internal types.
- */
-export type { Effort, WorkEpisode, EffortSignals, EffortWeights, EffortSummary, ProjectWorkSummary, WorkAtRisk, EpisodeStore, } from '@compilr-dev/agents';
-/**
- * Pending tool signal — accumulated during a batch window before
- * being rolled into a WorkEpisode.
- */
-export interface PendingToolSignal {
-    /** Tool name that was invoked */
-    toolName: string;
-    /** Files affected by this tool call */
-    files: string[];
-    /** Lines changed, if known */
-    linesChanged: number;
-    /** Duration of the tool call in milliseconds */
-    durationMs: number;
-    /** Whether the tool call succeeded */
-    success: boolean;
-    /** ISO timestamp of the tool call */
-    timestamp: string;
-}
-/**
- * On-disk format for the episodes JSON file.
- */
-export interface EpisodeFile {
-    /** File format version */
-    version: 1;
-    /** All stored episodes */
-    episodes: import('@compilr-dev/agents').WorkEpisode[];
-    /** ISO timestamp of last cleanup */
-    lastCleanup: string;
-}

package/dist/episodes/types.js

@@ -1,6 +0,0 @@
-/**
- * Episodic Memory Types (CLI)
- *
- * Re-exports core types from @compilr-dev/agents and adds CLI-internal types.
- */
-export {};

package/dist/episodes/work-at-risk.d.ts

@@ -1,12 +0,0 @@
-/**
- * Work At Risk Query
- *
- * Pure function to query episodes by affected files and build a WorkAtRisk summary.
- * Used by guardrails and rehearsal to warn about destructive operations.
- */
-import type { EpisodeStore, WorkAtRisk } from '@compilr-dev/agents';
-/**
- * Query episodes that touch any of the given files and build a WorkAtRisk summary.
- * Returns null if no episodes are at risk.
- */
-export declare function queryWorkAtRisk(store: EpisodeStore, files: string[]): WorkAtRisk | null;

package/dist/episodes/work-at-risk.js

@@ -1,38 +0,0 @@
-/**
- * Work At Risk Query
- *
- * Pure function to query episodes by affected files and build a WorkAtRisk summary.
- * Used by guardrails and rehearsal to warn about destructive operations.
- */
-import { EFFORT_ORDER } from '@compilr-dev/agents';
-/**
- * Query episodes that touch any of the given files and build a WorkAtRisk summary.
- * Returns null if no episodes are at risk.
- */
-export function queryWorkAtRisk(store, files) {
-    const episodes = store.getByFiles(files);
-    if (episodes.length === 0)
-        return null;
-    // Max effort
-    let totalEffort = 'trivial';
-    for (const ep of episodes) {
-        if (EFFORT_ORDER.indexOf(ep.effort) > EFFORT_ORDER.indexOf(totalEffort)) {
-            totalEffort = ep.effort;
-        }
-    }
-    // Agent attribution: "agentId (terminalPrefix)"
-    const seen = new Set();
-    const agentAttribution = [];
-    for (const ep of episodes) {
-        const key = `${ep.agentId} (${ep.terminalPrefix})`;
-        if (!seen.has(key)) {
-            seen.add(key);
-            agentAttribution.push(key);
-        }
-    }
-    // Warning message
-    const fileCount = new Set(episodes.flatMap(ep => ep.files)).size;
-    const warningMessage = `⚠️ ${String(episodes.length)} episode(s) of work (effort: ${totalEffort}) ` +
-        `on ${String(fileCount)} file(s) by ${agentAttribution.join(', ')} would be affected.`;
-    return { episodes, totalEffort, agentAttribution, warningMessage };
-}

package/dist/episodes/work-summary-anchor.d.ts

@@ -1,23 +0,0 @@
-/**
- * Work Summary Anchor
- *
- * Manages an auto-generated anchor that summarizes work done in the current session.
- * Updated automatically after each episode batch is flushed.
- */
-import type { EpisodeStore, ProjectWorkSummary } from '@compilr-dev/agents';
-import type { AnchorManager } from '@compilr-dev/sdk';
-export interface WorkSummaryAnchorConfig {
-    store: EpisodeStore;
-    projectId: string;
-    getAnchorManager: (projectId: string) => AnchorManager;
-}
-/**
- * Build the anchor content string from the store's work summary.
- * Returns null when there are no episodes to summarize.
- */
-export declare function buildWorkSummaryContent(summary: ProjectWorkSummary): string | null;
-/**
- * Update the work summary anchor for a project.
- * Removes existing anchor (if any) and adds updated one.
- */
-export declare function updateWorkSummaryAnchor(config: WorkSummaryAnchorConfig): void;

package/dist/episodes/work-summary-anchor.js

@@ -1,73 +0,0 @@
-/**
- * Work Summary Anchor
- *
- * Manages an auto-generated anchor that summarizes work done in the current session.
- * Updated automatically after each episode batch is flushed.
- */
-const ANCHOR_TAG = 'episode-work-summary';
-/**
- * Build the anchor content string from the store's work summary.
- * Returns null when there are no episodes to summarize.
- */
-export function buildWorkSummaryContent(summary) {
-    if (summary.episodeCount === 0)
-        return null;
-    const lines = ['[Session Work Summary]'];
-    lines.push(`Episodes: ${String(summary.episodeCount)}, Effort: ${summary.totalEffort}, Time: ${formatMs(summary.timeSpentMs)}`);
-    if (summary.agentBreakdown.length > 0) {
-        const agents = summary.agentBreakdown
-            .map(a => `${a.agentId}(${String(a.episodeCount)})`)
-            .join(', ');
-        lines.push(`Agents: ${agents}`);
-    }
-    if (summary.topFiles.length > 0) {
-        const files = summary.topFiles.slice(0, 5)
-            .map(f => f.path.split('/').pop() ?? f.path)
-            .join(', ');
-        lines.push(`Top files: ${files}`);
-    }
-    if (summary.uncommittedWork.length > 0) {
-        lines.push(`Uncommitted: ${String(summary.uncommittedWork.length)} episode(s)`);
-    }
-    return lines.join('\n');
-}
-/**
- * Update the work summary anchor for a project.
- * Removes existing anchor (if any) and adds updated one.
- */
-export function updateWorkSummaryAnchor(config) {
-    const { store, projectId, getAnchorManager: getManager } = config;
-    const manager = getManager(projectId);
-    const summary = store.getWorkSummary();
-    const content = buildWorkSummaryContent(summary);
-    // Remove existing work summary anchor
-    const existing = manager.getAll().find((a) => a.tags?.includes(ANCHOR_TAG));
-    if (existing)
-        manager.remove(existing.id);
-    // Add new anchor if there's content
-    if (content) {
-        manager.add({
-            content,
-            priority: 'info',
-            scope: 'persistent',
-            tags: [ANCHOR_TAG],
-            projectId,
-        });
-    }
-}
-/**
- * Format milliseconds to a human-readable string (e.g., "2h 15m", "45s").
- */
-function formatMs(ms) {
-    if (ms < 1000)
-        return `${String(ms)}ms`;
-    const totalSeconds = Math.floor(ms / 1000);
-    if (totalSeconds < 60)
-        return `${String(totalSeconds)}s`;
-    const minutes = Math.floor(totalSeconds / 60);
-    if (minutes < 60)
-        return `${String(minutes)}m`;
-    const hours = Math.floor(minutes / 60);
-    const remainingMinutes = minutes % 60;
-    return remainingMinutes > 0 ? `${String(hours)}h ${String(remainingMinutes)}m` : `${String(hours)}h`;
-}

package/dist/tools/consult.d.ts

@@ -1,14 +0,0 @@
-/**
- * Consult Tool — Specialist-to-Specialist Sync Borrow
- *
- * The CLI surfaces the SDK's `consult` semantic via a thin wrapper around
- * the registered consult handler (same pattern as handoff). The actual
- * sub-run of the target agent lives in `handlers/delegation-handlers.ts`.
- *
- * Spec: project-docs/00-requirements/compilr-dev-sdk/consult-tool-spec.md
- */
-export declare const consultTool: import("@compilr-dev/sdk").Tool<{
-    agentId: string;
-    question: string;
-    context?: string;
-}>;

package/dist/tools/consult.js

@@ -1,73 +0,0 @@
-/**
- * Consult Tool — Specialist-to-Specialist Sync Borrow
- *
- * The CLI surfaces the SDK's `consult` semantic via a thin wrapper around
- * the registered consult handler (same pattern as handoff). The actual
- * sub-run of the target agent lives in `handlers/delegation-handlers.ts`.
- *
- * Spec: project-docs/00-requirements/compilr-dev-sdk/consult-tool-spec.md
- */
-import { defineTool } from '@compilr-dev/sdk';
-import { getConsultHandler } from '../shared-handlers.js';
-export const consultTool = defineTool({
-    name: 'consult',
-    description: 'Ask another specialist a focused question and continue the conversation yourself. ' +
-        'Use this when you need a quick opinion or expertise input from a teammate without giving up the conversation. ' +
-        'Unlike handoff, you keep ownership — the target answers and control returns to you. ' +
-        'Example: $arch can consult $pm on scope, get an answer, and continue designing.',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            agentId: {
-                type: 'string',
-                description: 'Target specialist agent ID to consult (e.g., "pm", "qa", "dev"). ' +
-                    'Cannot be yourself or "default" (use handoff to escalate to the coordinator).',
-            },
-            question: {
-                type: 'string',
-                description: 'The focused question you want answered — be specific.',
-            },
-            context: {
-                type: 'string',
-                description: 'Optional supporting material the target needs to answer well ' +
-                    '(code snippet, design constraint, current state, etc.).',
-            },
-        },
-        required: ['agentId', 'question'],
-    },
-    execute: async (input) => {
-        if (!input.agentId || input.agentId.trim().length === 0) {
-            return { success: false, error: 'agentId is required' };
-        }
-        if (!input.question || input.question.trim().length === 0) {
-            return { success: false, error: 'question is required and cannot be empty' };
-        }
-        const handler = getConsultHandler();
-        if (!handler) {
-            return {
-                success: false,
-                error: 'Consult handler not initialized. This tool requires multi-agent mode with a team.',
-            };
-        }
-        try {
-            const result = await handler({
-                agentId: input.agentId.trim(),
-                question: input.question.trim(),
-                context: input.context?.trim() || undefined,
-            });
-            if (result.error) {
-                return { success: false, error: result.error };
-            }
-            return {
-                success: true,
-                result: { answer: result.answer, agentId: result.agentId },
-            };
-        }
-        catch (err) {
-            return {
-                success: false,
-                error: `Consult failed: ${err instanceof Error ? err.message : String(err)}`,
-            };
-        }
-    },
-});

package/dist/tools/delegate-background.d.ts

@@ -1,27 +0,0 @@
-/**
- * Delegate Background Tool - Coordinator Mode
- *
- * Allows the coordinator to delegate tasks to specialists running in background.
- * Unlike the foreground `delegate` tool (which switches the active agent),
- * this tool keeps the coordinator in the foreground while the specialist
- * works independently in the background.
- *
- * Flow:
- * 1. Coordinator calls delegate_background(agentId, task)
- * 2. DelegationTracker registers the delegation
- * 3. Specialist starts as background agent (or queued if busy)
- * 4. Coordinator continues working
- * 5. On completion, coordinator is notified via completion events (Phase 2)
- */
-interface DelegateBackgroundInput {
-    /** Target specialist agent ID (e.g., 'arch', 'dev', 'qa') */
-    agentId: string;
-    /** Detailed task description for the specialist */
-    task: string;
-    /** Optional todo index to associate with this delegation */
-    todoIndex?: number;
-    /** What the specialist should produce (e.g., "architecture document") */
-    expectedOutput?: string;
-}
-export declare const delegateBackgroundTool: import("@compilr-dev/sdk").Tool<DelegateBackgroundInput>;
-export {};

package/dist/tools/delegate-background.js

@@ -1,115 +0,0 @@
-/**
- * Delegate Background Tool - Coordinator Mode
- *
- * Allows the coordinator to delegate tasks to specialists running in background.
- * Unlike the foreground `delegate` tool (which switches the active agent),
- * this tool keeps the coordinator in the foreground while the specialist
- * works independently in the background.
- *
- * Flow:
- * 1. Coordinator calls delegate_background(agentId, task)
- * 2. DelegationTracker registers the delegation
- * 3. Specialist starts as background agent (or queued if busy)
- * 4. Coordinator continues working
- * 5. On completion, coordinator is notified via completion events (Phase 2)
- */
-import { defineTool } from '@compilr-dev/sdk';
-import { getDelegateBackgroundHandler } from '../shared-handlers.js';
-// =============================================================================
-// Tool Definition
-// =============================================================================
-export const delegateBackgroundTool = defineTool({
-    name: 'delegate_background',
-    description: 'Delegate a task to a specialist running in background. ' +
-        'The specialist executes independently while you continue working. ' +
-        'You will be notified when the specialist completes. ' +
-        'Use delegation_status to check progress. ' +
-        'Prefer this over delegate — it keeps you in control and tracks status. ' +
-        'Only available to the coordinator.',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            agentId: {
-                type: 'string',
-                description: 'Target specialist agent ID (e.g., "arch", "dev", "qa")',
-            },
-            task: {
-                type: 'string',
-                description: 'Detailed task description for the specialist',
-            },
-            todoIndex: {
-                type: 'number',
-                description: 'Optional todo index to associate with this delegation',
-            },
-            expectedOutput: {
-                type: 'string',
-                description: 'What the specialist should produce (e.g., "architecture document", "implementation")',
-            },
-        },
-        required: ['agentId', 'task'],
-    },
-    execute: async (input) => {
-        try {
-            // Validate input
-            if (!input.agentId || input.agentId.trim().length === 0) {
-                return {
-                    success: false,
-                    error: 'Agent ID is required',
-                };
-            }
-            if (!input.task || input.task.trim().length === 0) {
-                return {
-                    success: false,
-                    error: 'Task description is required',
-                };
-            }
-            // Prevent self-delegation
-            if (input.agentId.trim() === 'default') {
-                return {
-                    success: false,
-                    error: 'Cannot delegate to yourself (the coordinator). Delegate to a specialist agent.',
-                };
-            }
-            // Get the delegate background handler from shared-handlers
-            const handler = getDelegateBackgroundHandler();
-            if (!handler) {
-                return {
-                    success: false,
-                    error: 'Delegate background handler not initialized. ' +
-                        'This tool requires multi-agent mode with coordinator role.',
-                };
-            }
-            // Execute background delegation
-            const result = await handler({
-                agentId: input.agentId.trim(),
-                task: input.task.trim(),
-                todoIndex: input.todoIndex,
-                expectedOutput: input.expectedOutput?.trim(),
-            });
-            if (result.error) {
-                return {
-                    success: false,
-                    error: result.error,
-                };
-            }
-            const output = {
-                delegated: true,
-                delegationId: result.delegationId,
-                status: result.status,
-                message: result.status === 'queued'
-                    ? `Task queued for $${input.agentId} (currently busy). It will start when they're free.`
-                    : `Task delegated to $${input.agentId} running in background. You'll be notified on completion.`,
-            };
-            return {
-                success: true,
-                result: output,
-            };
-        }
-        catch (err) {
-            return {
-                success: false,
-                error: `Background delegation failed: ${err instanceof Error ? err.message : String(err)}`,
-            };
-        }
-    },
-});