byterover-cli 3.5.1 → 3.6.1

package/dist/server/infra/process/transport-handlers.d.ts

@@ -32,12 +32,16 @@ import type { ITaskLifecycleHook } from '../../core/interfaces/process/i-task-li
 import type { IProjectRegistry } from '../../core/interfaces/project/i-project-registry.js';
 import type { IProjectRouter } from '../../core/interfaces/routing/i-project-router.js';
 import type { ITransportServer } from '../../core/interfaces/transport/i-transport-server.js';
+import type { PreDispatchCheck } from './task-router.js';
+export type { PreDispatchCheck, PreDispatchCheckResult } from './task-router.js';
 export type { TaskInfo } from './types.js';
 type TransportHandlersOptions = {
     agentPool?: IAgentPool;
     clientManager?: IClientManager;
     /** Lifecycle hooks for task events (e.g. CurateLogHandler). */
     lifecycleHooks?: ITaskLifecycleHook[];
+    /** Optional daemon-side gate run before dispatching a task to the agent pool. */
+    preDispatchCheck?: PreDispatchCheck;
     projectRegistry?: IProjectRegistry;
     projectRouter?: IProjectRouter;
     transport: ITransportServer;

package/dist/server/infra/process/transport-handlers.js

@@ -42,6 +42,7 @@ export class TransportHandlers {
             agentPool: options.agentPool,
             getAgentForProject: (projectPath) => this.connectionCoordinator.getAgentForProject(projectPath),
             lifecycleHooks: options.lifecycleHooks,
+            preDispatchCheck: options.preDispatchCheck,
             projectRegistry: options.projectRegistry,
             projectRouter: options.projectRouter,
             resolveClientProjectPath: (clientId) => options.clientManager?.getClient(clientId)?.projectPath,

package/dist/server/infra/storage/file-curate-log-store.js

@@ -57,7 +57,7 @@ const CurateLogEntryFileSchema = z.discriminatedUnion('status', [
 ]);
 // ── FileCurateLogStore ────────────────────────────────────────────────────────
 const ID_PATTERN = new RegExp(`^${CURATE_LOG_ID_PREFIX}-\\d+$`);
-const DEFAULT_MAX_ENTRIES = 100;
+const DEFAULT_MAX_ENTRIES = 1000;
 /** Entries stuck in "processing" longer than this are considered interrupted (daemon was killed). */
 const STALE_PROCESSING_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes
 /**

package/dist/server/infra/storage/file-query-log-store.d.ts

@@ -0,0 +1,81 @@
+import type { QueryLogEntry } from '../../core/domain/entities/query-log-entry.js';
+import type { IQueryLogStore, QueryLogStatus, QueryLogTier } from '../../core/interfaces/storage/i-query-log-store.js';
+type FileQueryLogStoreOptions = {
+    baseDir: string;
+    maxAgeDays?: number;
+    maxEntries?: number;
+};
+/**
+ * File-based implementation of IQueryLogStore.
+ *
+ * Each log entry is stored as a JSON file:
+ *   {baseDir}/query-log/qry-{timestamp_ms}.json
+ *
+ * Writes are atomic (tmp → rename). Reads validate with Zod and return undefined
+ * for corrupt/missing files. Prunes by age (default 30 days) then by count (default 1000).
+ */
+export declare class FileQueryLogStore implements IQueryLogStore {
+    private lastTimestamp;
+    private readonly logDir;
+    private readonly maxAgeDays;
+    private readonly maxEntries;
+    private pruneInFlight;
+    constructor(opts: FileQueryLogStoreOptions);
+    /**
+     * Retrieve an entry by ID. Returns undefined if:
+     * - ID format is invalid (security: prevents path traversal)
+     * - File does not exist
+     * - File content fails Zod validation (corrupted)
+     */
+    getById(id: string): Promise<QueryLogEntry | undefined>;
+    /**
+     * Generate the next monotonic log entry ID in the format `qry-{timestamp_ms}`.
+     * Guaranteed to increase even if called multiple times in the same millisecond.
+     *
+     * Note: monotonicity is instance-local. A new instance resets `lastTimestamp` to 0
+     * and relies on wall-clock time. Two instances pointing at the same baseDir could
+     * theoretically collide in the same millisecond, but this is practically impossible
+     * given the sequential task queue (max concurrency = 1 per project).
+     */
+    getNextId(): Promise<string>;
+    /**
+     * List entries sorted newest-first (by timestamp embedded in filename).
+     * Filters (status, tier, after, before) are applied before limit.
+     * Reads stop early once `limit` matches are found, so filtered queries with small limits
+     * are O(matches) rather than O(total entries). Skips corrupt entries silently.
+     */
+    list({ after, before, limit, status, tier, }?: {
+        after?: number;
+        before?: number;
+        limit?: number;
+        status?: QueryLogStatus[];
+        tier?: QueryLogTier[];
+    }): Promise<QueryLogEntry[]>;
+    /**
+     * Persist a log entry atomically (write to tmp, then rename).
+     * On rename failure, cleans up the tmp file. After saving, prunes by age then by count (best-effort).
+     */
+    save(entry: QueryLogEntry): Promise<void>;
+    private entryPath;
+    /**
+     * Schedule a prune pass without blocking the caller.
+     * Deduplicates concurrent calls — only one prune runs at a time.
+     */
+    private firePrune;
+    private pruneOldest;
+    /**
+     * If a "processing" entry is older than STALE_PROCESSING_THRESHOLD_MS, the daemon
+     * was killed before it could finalize it. Rewrite it as "error" on disk (best-effort)
+     * and return the corrected entry so the display shows "interrupted" instead of processing.
+     *
+     * Uses writeAtomic directly (not save) to skip the prune cascade — list() with N stale
+     * entries would otherwise trigger N concurrent prune passes.
+     */
+    private resolveStale;
+    /**
+     * Atomic write: write to a tmp file with random UUID suffix, then rename.
+     * On failure, cleans up the tmp file and re-throws the original error.
+     */
+    private writeAtomic;
+}
+export {};

package/dist/server/infra/storage/file-query-log-store.js

@@ -0,0 +1,249 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { QUERY_LOG_DIR, QUERY_LOG_ID_PREFIX } from '../../constants.js';
+import { QUERY_LOG_TIERS } from '../../core/domain/entities/query-log-entry.js';
+const QueryLogMatchedDocFileSchema = z.object({
+    path: z.string(),
+    score: z.number(),
+    title: z.string(),
+});
+const QueryLogSearchMetadataFileSchema = z.object({
+    cacheFingerprint: z.string().optional(),
+    resultCount: z.number(),
+    topScore: z.number(),
+    totalFound: z.number(),
+});
+const QueryLogTimingFileSchema = z.object({
+    durationMs: z.number(),
+});
+// Single source of truth: tier validation is derived from QUERY_LOG_TIERS at runtime.
+// Adding/removing a tier in the entity automatically updates schema validation.
+const QUERY_LOG_TIER_SET = new Set(QUERY_LOG_TIERS);
+const QueryLogTierSchema = z.custom((val) => QUERY_LOG_TIER_SET.has(val), { message: 'Invalid query log tier' });
+const QueryLogEntryBaseSchema = z.object({
+    id: z.string(),
+    matchedDocs: z.array(QueryLogMatchedDocFileSchema),
+    query: z.string(),
+    searchMetadata: QueryLogSearchMetadataFileSchema.optional(),
+    startedAt: z.number(),
+    taskId: z.string(),
+    tier: QueryLogTierSchema.optional(),
+    timing: QueryLogTimingFileSchema.optional(),
+});
+const QueryLogEntryFileSchema = z.discriminatedUnion('status', [
+    QueryLogEntryBaseSchema.extend({ status: z.literal('processing') }),
+    QueryLogEntryBaseSchema.extend({
+        completedAt: z.number(),
+        response: z.string().optional(),
+        status: z.literal('completed'),
+    }),
+    QueryLogEntryBaseSchema.extend({
+        completedAt: z.number(),
+        error: z.string(),
+        status: z.literal('error'),
+    }),
+    QueryLogEntryBaseSchema.extend({
+        completedAt: z.number(),
+        status: z.literal('cancelled'),
+    }),
+]);
+const ID_PATTERN = new RegExp(`^${QUERY_LOG_ID_PREFIX}-\\d+$`);
+const DEFAULT_MAX_ENTRIES = 1000;
+const DEFAULT_MAX_AGE_DAYS = 30;
+/** Entries stuck in "processing" longer than this are considered interrupted (daemon was killed). */
+const STALE_PROCESSING_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes
+/**
+ * File-based implementation of IQueryLogStore.
+ *
+ * Each log entry is stored as a JSON file:
+ *   {baseDir}/query-log/qry-{timestamp_ms}.json
+ *
+ * Writes are atomic (tmp → rename). Reads validate with Zod and return undefined
+ * for corrupt/missing files. Prunes by age (default 30 days) then by count (default 1000).
+ */
+export class FileQueryLogStore {
+    lastTimestamp = 0;
+    logDir;
+    maxAgeDays;
+    maxEntries;
+    pruneInFlight = false;
+    constructor(opts) {
+        this.logDir = join(opts.baseDir, QUERY_LOG_DIR);
+        this.maxAgeDays = opts.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS;
+        this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    }
+    /**
+     * Retrieve an entry by ID. Returns undefined if:
+     * - ID format is invalid (security: prevents path traversal)
+     * - File does not exist
+     * - File content fails Zod validation (corrupted)
+     */
+    async getById(id) {
+        if (!ID_PATTERN.test(id))
+            return undefined;
+        try {
+            const raw = await readFile(this.entryPath(id), 'utf8');
+            const parsed = QueryLogEntryFileSchema.safeParse(JSON.parse(raw));
+            if (!parsed.success)
+                return undefined;
+            return await this.resolveStale(parsed.data);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Generate the next monotonic log entry ID in the format `qry-{timestamp_ms}`.
+     * Guaranteed to increase even if called multiple times in the same millisecond.
+     *
+     * Note: monotonicity is instance-local. A new instance resets `lastTimestamp` to 0
+     * and relies on wall-clock time. Two instances pointing at the same baseDir could
+     * theoretically collide in the same millisecond, but this is practically impossible
+     * given the sequential task queue (max concurrency = 1 per project).
+     */
+    async getNextId() {
+        const now = Date.now();
+        this.lastTimestamp = now <= this.lastTimestamp ? this.lastTimestamp + 1 : now;
+        return `${QUERY_LOG_ID_PREFIX}-${this.lastTimestamp}`;
+    }
+    /**
+     * List entries sorted newest-first (by timestamp embedded in filename).
+     * Filters (status, tier, after, before) are applied before limit.
+     * Reads stop early once `limit` matches are found, so filtered queries with small limits
+     * are O(matches) rather than O(total entries). Skips corrupt entries silently.
+     */
+    async list({ after, before, limit, status, tier, } = {}) {
+        let files;
+        try {
+            const entries = await readdir(this.logDir, { withFileTypes: true });
+            files = entries
+                .filter((e) => e.isFile() && e.name.endsWith('.json') && ID_PATTERN.test(e.name.slice(0, -5)))
+                .map((e) => e.name)
+                .sort()
+                .reverse(); // newest-first (lexicographic descending)
+        }
+        catch {
+            return [];
+        }
+        // Sequential read with early termination once limit matches are found.
+        // Avoids scanning all files for queries like list({status: ['error'], limit: 1}).
+        const results = [];
+        const targetCount = limit ?? Number.POSITIVE_INFINITY;
+        for (const filename of files) {
+            if (results.length >= targetCount)
+                break;
+            const id = filename.slice(0, -5);
+            // eslint-disable-next-line no-await-in-loop -- early termination requires sequential reads
+            const entry = await this.getById(id);
+            if (!entry)
+                continue;
+            if (status?.length && !status.includes(entry.status))
+                continue;
+            if (tier?.length && (entry.tier === undefined || !tier.includes(entry.tier)))
+                continue;
+            if (after !== undefined && entry.startedAt < after)
+                continue;
+            if (before !== undefined && entry.startedAt > before)
+                continue;
+            results.push(entry);
+        }
+        return results;
+    }
+    /**
+     * Persist a log entry atomically (write to tmp, then rename).
+     * On rename failure, cleans up the tmp file. After saving, prunes by age then by count (best-effort).
+     */
+    async save(entry) {
+        await mkdir(this.logDir, { recursive: true });
+        await this.writeAtomic(this.entryPath(entry.id), JSON.stringify(entry, null, 2));
+        this.firePrune();
+    }
+    entryPath(id) {
+        return join(this.logDir, `${id}.json`);
+    }
+    /**
+     * Schedule a prune pass without blocking the caller.
+     * Deduplicates concurrent calls — only one prune runs at a time.
+     */
+    firePrune() {
+        if (this.pruneInFlight)
+            return;
+        this.pruneInFlight = true;
+        this.pruneOldest()
+            .catch(() => { })
+            .finally(() => {
+            this.pruneInFlight = false;
+        });
+    }
+    async pruneOldest() {
+        const dirEntries = await readdir(this.logDir, { withFileTypes: true });
+        const files = dirEntries
+            .filter((e) => e.isFile() && e.name.endsWith('.json') && ID_PATTERN.test(e.name.slice(0, -5)))
+            .map((e) => e.name)
+            .sort(); // oldest-first
+        // Phase 1: Age-based pruning (skip if maxAgeDays === 0)
+        let remaining = files;
+        if (this.maxAgeDays > 0) {
+            const cutoff = Date.now() - this.maxAgeDays * 86_400_000;
+            const expired = [];
+            const kept = [];
+            for (const f of files) {
+                const ts = Number(f.slice(QUERY_LOG_ID_PREFIX.length + 1, -5)); // extract timestamp from "qry-{ts}.json"
+                if (ts < cutoff) {
+                    expired.push(f);
+                }
+                else {
+                    kept.push(f);
+                }
+            }
+            if (expired.length > 0) {
+                await Promise.all(expired.map((f) => rm(join(this.logDir, f), { force: true }).catch(() => { })));
+            }
+            remaining = kept;
+        }
+        // Phase 2: Count-based pruning
+        if (remaining.length <= this.maxEntries)
+            return;
+        const toDelete = remaining.slice(0, remaining.length - this.maxEntries);
+        await Promise.all(toDelete.map((f) => rm(join(this.logDir, f), { force: true }).catch(() => { })));
+    }
+    /**
+     * If a "processing" entry is older than STALE_PROCESSING_THRESHOLD_MS, the daemon
+     * was killed before it could finalize it. Rewrite it as "error" on disk (best-effort)
+     * and return the corrected entry so the display shows "interrupted" instead of processing.
+     *
+     * Uses writeAtomic directly (not save) to skip the prune cascade — list() with N stale
+     * entries would otherwise trigger N concurrent prune passes.
+     */
+    async resolveStale(entry) {
+        if (entry.status !== 'processing')
+            return entry;
+        if (Date.now() - entry.startedAt <= STALE_PROCESSING_THRESHOLD_MS)
+            return entry;
+        const recovered = {
+            ...entry,
+            completedAt: Date.now(),
+            error: 'Interrupted (daemon terminated)',
+            status: 'error',
+        };
+        this.writeAtomic(this.entryPath(recovered.id), JSON.stringify(recovered, null, 2)).catch(() => { });
+        return recovered;
+    }
+    /**
+     * Atomic write: write to a tmp file with random UUID suffix, then rename.
+     * On failure, cleans up the tmp file and re-throws the original error.
+     */
+    async writeAtomic(filePath, content) {
+        const tmpPath = `${filePath}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(tmpPath, content, 'utf8');
+            await rename(tmpPath, filePath);
+        }
+        catch (error) {
+            await rm(tmpPath, { force: true }).catch(() => { });
+            throw error;
+        }
+    }
+}

package/dist/server/infra/transport/handlers/config-handler.js

@@ -13,7 +13,7 @@ export class ConfigHandler {
         this.transport.onRequest(ConfigEvents.GET_ENVIRONMENT, () => {
             const config = getCurrentConfig();
             return {
-                apiBaseUrl: config.apiBaseUrl,
+                iamBaseUrl: config.iamBaseUrl,
                 isDevelopment: isDevelopment(),
                 webAppUrl: config.webAppUrl,
             };

package/dist/server/infra/usecase/curate-log-use-case.js

@@ -67,8 +67,12 @@ export class CurateLogUseCase {
         }
         this.log();
         this.log('Input:');
-        if (entry.input.context)
-            this.log(`  Context: ${entry.input.context.slice(0, 200)}${entry.input.context.length > 200 ? '...' : ''}`);
+        if (entry.input.context) {
+            const [firstLine, ...rest] = entry.input.context.split('\n');
+            this.log(`  Context: ${firstLine}`);
+            for (const line of rest)
+                this.log(`  ${line}`);
+        }
         if (entry.input.files?.length)
             this.log(`  Files:   ${entry.input.files.join(', ')}`);
         if (entry.input.folders?.length)
@@ -89,7 +93,7 @@ export class CurateLogUseCase {
         if (entry.status === 'completed' && entry.response) {
             this.log();
             this.log('Response:');
-            this.log(`  ${entry.response.slice(0, 500)}${entry.response.length > 500 ? '...' : ''}`);
+            this.log(entry.response.split('\n').map((line) => `  ${line}`).join('\n'));
         }
     }
     async showList({ after, before, detail, format, limit, status }) {

package/dist/server/infra/usecase/query-log-summary-narrative-formatter.d.ts

@@ -0,0 +1,15 @@
+import type { QueryLogSummary } from '../../core/interfaces/usecase/i-query-log-summary-use-case.js';
+export declare function formatQueryLogSummaryNarrative(summary: QueryLogSummary): string;
+/**
+ * Describe the time period as a human-readable label.
+ *
+ * Two formats:
+ * - 'short': "last 1h", "last 24h", "last 7d" (for text summary header)
+ * - 'long': "in the last hour", "in the last 24 hours" (for narrative prose)
+ *
+ * Only produces a period label when we have a clear relative window
+ * (--since/--last without --before). Bounded or ambiguous ranges
+ * return empty string (short) or "in the selected period" (long).
+ */
+export declare function describePeriod(period: QueryLogSummary['period'], format?: 'long' | 'short'): string;
+export declare function formatDurationMs(ms: number): string;

package/dist/server/infra/usecase/query-log-summary-narrative-formatter.js

@@ -0,0 +1,79 @@
+const NARRATIVE_TOP_DOCS = 2;
+const NARRATIVE_TOP_GAPS = 2;
+const MS_PER_HOUR = 3_600_000;
+const MS_PER_DAY = 86_400_000;
+export function formatQueryLogSummaryNarrative(summary) {
+    const periodLabel = describePeriod(summary.period);
+    if (summary.totalQueries === 0) {
+        return `No queries recorded ${periodLabel}. Your knowledge base is ready — try asking a question!`;
+    }
+    const paragraphs = [];
+    paragraphs.push(buildOverviewParagraph(summary, periodLabel));
+    if (summary.totalMatchedDocs > 0 && summary.topRecalledDocs.length > 0) {
+        paragraphs.push(buildTopDocsParagraph(summary));
+    }
+    paragraphs.push(buildGapsParagraph(summary));
+    return paragraphs.join('\n\n');
+}
+/**
+ * Describe the time period as a human-readable label.
+ *
+ * Two formats:
+ * - 'short': "last 1h", "last 24h", "last 7d" (for text summary header)
+ * - 'long': "in the last hour", "in the last 24 hours" (for narrative prose)
+ *
+ * Only produces a period label when we have a clear relative window
+ * (--since/--last without --before). Bounded or ambiguous ranges
+ * return empty string (short) or "in the selected period" (long).
+ */
+export function describePeriod(period, format = 'long') {
+    if (period.from > 0 && period.to === 0) {
+        const spanMs = Date.now() - period.from;
+        const hours = Math.round(spanMs / MS_PER_HOUR);
+        const days = Math.round(spanMs / MS_PER_DAY);
+        if (format === 'short') {
+            if (hours <= 1)
+                return 'last 1h';
+            if (hours <= 24)
+                return 'last 24h';
+            return `last ${days}d`;
+        }
+        if (hours <= 1)
+            return 'in the last hour';
+        if (hours <= 24)
+            return 'in the last 24 hours';
+        return `in the last ${days} days`;
+    }
+    return format === 'short' ? 'selected period' : 'in the selected period';
+}
+function buildOverviewParagraph(summary, periodLabel) {
+    const { byStatus, cacheHitRate, coverageRate, queriesWithoutMatches, responseTime, totalQueries } = summary;
+    const answered = byStatus.completed - queriesWithoutMatches;
+    const coveragePct = Math.round(coverageRate * 100);
+    const cachePct = Math.round(cacheHitRate * 100);
+    return (`Your team asked ${totalQueries} questions ${periodLabel}. ` +
+        `ByteRover answered ${answered} from curated knowledge ` +
+        `(${coveragePct}% coverage), with ${cachePct}% served from cache. ` +
+        `Average response time was ${formatDurationMs(responseTime.avgMs)}.`);
+}
+function buildTopDocsParagraph(summary) {
+    const topDocs = summary.topRecalledDocs.slice(0, NARRATIVE_TOP_DOCS);
+    const docsList = topDocs.map((doc) => `${doc.path} (${doc.count} queries)`).join(', ');
+    return `Most useful knowledge: ${docsList}.`;
+}
+function buildGapsParagraph(summary) {
+    if (summary.knowledgeGaps.length === 0) {
+        return 'Every question was answered from curated knowledge.';
+    }
+    const unansweredCount = summary.queriesWithoutMatches;
+    const topGaps = summary.knowledgeGaps.slice(0, NARRATIVE_TOP_GAPS);
+    const gapsList = topGaps.map((gap) => `"${gap.topic}"`).join(' and ');
+    return (`${unansweredCount} question${unansweredCount === 1 ? '' : 's'} couldn't be answered — ` +
+        `consider curating more about ${gapsList}.`);
+}
+export function formatDurationMs(ms) {
+    if (ms >= 1000) {
+        return `${(ms / 1000).toFixed(1)}s`;
+    }
+    return `${Math.round(ms)}ms`;
+}

package/dist/server/infra/usecase/query-log-summary-use-case.d.ts

@@ -0,0 +1,13 @@
+import type { ITerminal } from '../../core/interfaces/i-terminal.js';
+import type { IQueryLogStore } from '../../core/interfaces/storage/i-query-log-store.js';
+import type { IQueryLogSummaryUseCase } from '../../core/interfaces/usecase/i-query-log-summary-use-case.js';
+type QueryLogSummaryUseCaseDeps = {
+    queryLogStore: IQueryLogStore;
+    terminal: ITerminal;
+};
+export declare class QueryLogSummaryUseCase implements IQueryLogSummaryUseCase {
+    private readonly deps;
+    constructor(deps: QueryLogSummaryUseCaseDeps);
+    run(options: Parameters<IQueryLogSummaryUseCase['run']>[0]): Promise<void>;
+}
+export {};