byterover-cli 3.5.0 → 3.6.0

package/dist/server/infra/process/task-router.js

@@ -38,6 +38,7 @@ export class TaskRouter {
     completedTasks = new Map();
     getAgentForProject;
     lifecycleHooks;
+    preDispatchCheck;
     projectRegistry;
     projectRouter;
     resolveClientProjectPath;
@@ -49,6 +50,7 @@ export class TaskRouter {
         this.agentPool = options.agentPool;
         this.getAgentForProject = options.getAgentForProject;
         this.lifecycleHooks = options.lifecycleHooks ?? [];
+        this.preDispatchCheck = options.preDispatchCheck;
         this.projectRegistry = options.projectRegistry;
         this.projectRouter = options.projectRouter;
         this.resolveClientProjectPath = options.resolveClientProjectPath;
@@ -170,7 +172,7 @@ export class TaskRouter {
         }
     }
     handleTaskCompleted(data) {
-        const { result, taskId } = data;
+        const { logId: eventLogId, result, taskId } = data;
         const task = this.tasks.get(taskId);
         transportLog(`Task completed: ${taskId}`);
         // Collect synchronous completion data from hooks (e.g. pendingReviewCount from CurateLogHandler).
@@ -187,24 +189,29 @@ export class TaskRouter {
                 }
             }
         }
+        // Prefer logId from lifecycle hooks (curate), fall back to executor-provided logId (dream)
+        const resolvedLogId = task?.logId ?? eventLogId;
         if (task) {
             this.transport.sendTo(task.clientId, TransportTaskEventNames.COMPLETED, {
-                ...(task.logId ? { logId: task.logId } : {}),
+                ...(resolvedLogId ? { logId: resolvedLogId } : {}),
                 ...hookData,
                 result,
                 taskId,
             });
         }
         broadcastToProjectRoom(this.projectRegistry, this.projectRouter, task?.projectPath, TransportTaskEventNames.COMPLETED, {
-            ...(task?.logId ? { logId: task.logId } : {}),
+            ...(resolvedLogId ? { logId: resolvedLogId } : {}),
             ...hookData,
             result,
             taskId,
         }, task?.clientId);
         this.moveToCompleted(taskId);
-        // Notify pool so it can clear busy flag and drain queued tasks
-        if (task?.projectPath) {
-            this.agentPool?.notifyTaskCompleted(task.projectPath);
+        // Notify pool so it can clear busy flag and drain queued tasks.
+        // Fallback to data.projectPath for daemon-submitted tasks (e.g. idle dream)
+        // that bypass handleTaskCreate and are not registered in this.tasks.
+        const projectPath = task?.projectPath ?? data.projectPath;
+        if (projectPath) {
+            this.agentPool?.notifyTaskCompleted(projectPath);
         }
         // Notify hooks (fire-and-forget)
         if (task) {
@@ -303,6 +310,27 @@ export class TaskRouter {
             ...(logId ? { logId } : {}),
             taskId,
         });
+        // ── Daemon-side pre-dispatch gate (dream uses this for gates 1-3) ────────
+        // Runs after ack so the client has a logId to correlate; short-circuits with
+        // task:completed + skip-reason when ineligible. Mirrors the idle-trigger
+        // pattern in brv-server.ts:260 for the CLI dispatch path.
+        if (this.preDispatchCheck) {
+            let check = { eligible: true };
+            try {
+                check = await this.preDispatchCheck(data, projectPath);
+            }
+            catch (error_) {
+                transportLog(`preDispatchCheck threw for task ${taskId}, proceeding with dispatch: ${error_ instanceof Error ? error_.message : String(error_)}`);
+            }
+            if (!check.eligible) {
+                transportLog(`Task ${taskId} (type=${data.type}) skipped by daemon pre-check: ${check.skipResult}`);
+                // Use the skip-specific handler so the pool's activeTasks counter and
+                // onTaskCompleted hooks aren't notified for a task that never reached
+                // submitTask. See handleTaskSkippedByPreCheck for rationale.
+                this.handleTaskSkippedByPreCheck(taskId, check.skipResult);
+                return { taskId };
+            }
+        }
         // ── Submit to AgentPool (fire-and-forget) ─────────────────────────────────
         const executeMsg = {
             clientId,
@@ -310,6 +338,7 @@ export class TaskRouter {
             ...(data.clientCwd ? { clientCwd: data.clientCwd } : {}),
             ...(data.files?.length ? { files: data.files } : {}),
             ...(data.folderPath ? { folderPath: data.folderPath } : {}),
+            ...(data.force === undefined ? {} : { force: data.force }),
             ...(projectPath ? { projectPath } : {}),
             taskId,
             type: data.type,
@@ -386,15 +415,44 @@ export class TaskRouter {
             taskId,
         }, task?.clientId);
         this.moveToCompleted(taskId);
-        // Notify pool so it can clear busy flag and drain queued tasks
-        if (task?.projectPath) {
-            this.agentPool?.notifyTaskCompleted(task.projectPath);
+        // Notify pool so it can clear busy flag and drain queued tasks.
+        // Fallback to data.projectPath for daemon-submitted tasks (e.g. idle dream).
+        const errorProjectPath = task?.projectPath ?? data.projectPath;
+        if (errorProjectPath) {
+            this.agentPool?.notifyTaskCompleted(errorProjectPath);
         }
         // Notify hooks (fire-and-forget)
         if (task) {
             this.notifyHooksError(taskId, error.message, task).catch(() => { });
         }
     }
+    /**
+     * Emit `task:completed` for a task that the daemon's pre-dispatch gate skipped
+     * before it ever reached `AgentPool.submitTask`.
+     *
+     * Distinct from {@link handleTaskCompleted}:
+     *   - does NOT call `agentPool.notifyTaskCompleted` (the pool's `activeTasks`
+     *     counter was never incremented, so decrementing here would undercount real
+     *     load and let `drainQueue` dispatch an extra queued task)
+     *   - does NOT fire `onTaskCompleted` lifecycle hooks (counters/metrics that
+     *     act on completed tasks should not see pre-check skips as completions)
+     *
+     * Still emits the event to the client and the project room so REPL/TUI
+     * receive the skip result, and still calls `moveToCompleted` so the task is
+     * removed from the active set.
+     */
+    handleTaskSkippedByPreCheck(taskId, result) {
+        const task = this.tasks.get(taskId);
+        transportLog(`Task skipped by pre-dispatch gate: ${taskId}`);
+        if (task) {
+            this.transport.sendTo(task.clientId, TransportTaskEventNames.COMPLETED, {
+                result,
+                taskId,
+            });
+        }
+        broadcastToProjectRoom(this.projectRegistry, this.projectRouter, task?.projectPath, TransportTaskEventNames.COMPLETED, { result, taskId }, task?.clientId);
+        this.moveToCompleted(taskId);
+    }
     handleTaskStarted(data) {
         const { taskId } = data;
         const task = this.tasks.get(taskId);

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 {};