byterover-cli 3.5.1 → 3.6.0

package/dist/server/config/environment.js

@@ -1,3 +1,4 @@
+import { API_V1_PATH } from '../constants.js';
 const isEnvironment = (value) => value === 'development' || value === 'production';
 /**
  * Current environment - set at runtime by the launcher scripts.
@@ -17,25 +18,43 @@ const DEFAULTS = {
         production: ['read', 'write'],
     },
 };
+const normalizeUrl = (url) => url.replace(/\/+$/, '');
+const assertRootDomain = (name, url) => {
+    if (new URL(url).pathname !== '/') {
+        throw new Error(`${name} must not include a path component. Provide the root domain only (e.g., https://example.com).`);
+    }
+};
+/**
+ * Reads a required environment variable and normalizes it by removing any trailing slash.
+ * This normalization applies to all required variables (including BRV_GIT_REMOTE_BASE_URL
+ * and BRV_WEB_APP_URL, which may carry paths) to prevent double slashes when joining URLs.
+ */
 const readRequiredEnv = (name) => {
-    const value = process.env[name];
+    const value = process.env[name]?.trim();
     if (!value) {
         throw new Error(`Missing required environment variable: ${name}. Ensure .env files are loaded via dotenv.`);
     }
-    return value;
+    return normalizeUrl(value);
+};
+export const getCurrentConfig = () => {
+    const iamBaseUrl = readRequiredEnv('BRV_IAM_BASE_URL');
+    assertRootDomain('BRV_IAM_BASE_URL', iamBaseUrl);
+    const cogitBaseUrl = readRequiredEnv('BRV_COGIT_BASE_URL');
+    assertRootDomain('BRV_COGIT_BASE_URL', cogitBaseUrl);
+    const oidcBase = `${iamBaseUrl}${API_V1_PATH}/oidc`;
+    return {
+        authorizationUrl: `${oidcBase}/authorize`,
+        clientId: DEFAULTS.clientId,
+        cogitBaseUrl,
+        gitRemoteBaseUrl: readRequiredEnv('BRV_GIT_REMOTE_BASE_URL'),
+        hubRegistryUrl: DEFAULTS.hubRegistryUrl,
+        iamBaseUrl,
+        issuerUrl: oidcBase,
+        llmBaseUrl: readRequiredEnv('BRV_LLM_BASE_URL'),
+        scopes: [...DEFAULTS.scopes[ENVIRONMENT]],
+        tokenUrl: `${oidcBase}/token`,
+        webAppUrl: readRequiredEnv('BRV_WEB_APP_URL'),
+    };
 };
-export const getCurrentConfig = () => ({
-    apiBaseUrl: readRequiredEnv('BRV_API_BASE_URL'),
-    authorizationUrl: readRequiredEnv('BRV_AUTHORIZATION_URL'),
-    clientId: DEFAULTS.clientId,
-    cogitApiBaseUrl: readRequiredEnv('BRV_COGIT_API_BASE_URL'),
-    gitRemoteBaseUrl: readRequiredEnv('BRV_GIT_REMOTE_BASE_URL'),
-    hubRegistryUrl: DEFAULTS.hubRegistryUrl,
-    issuerUrl: readRequiredEnv('BRV_ISSUER_URL'),
-    llmApiBaseUrl: readRequiredEnv('BRV_LLM_API_BASE_URL'),
-    scopes: [...DEFAULTS.scopes[ENVIRONMENT]],
-    tokenUrl: readRequiredEnv('BRV_TOKEN_URL'),
-    webAppUrl: readRequiredEnv('BRV_WEB_APP_URL'),
-});
 export const getGitRemoteBaseUrl = () => process.env.BRV_GIT_REMOTE_BASE_URL ?? 'https://byterover.dev';
 export const isDevelopment = () => ENVIRONMENT === 'development';

package/dist/server/constants.d.ts

@@ -1,4 +1,5 @@
 export declare const BRV_DIR = ".brv";
+export declare const API_V1_PATH = "/api/v1";
 export declare const PROJECT_CONFIG_FILE = "config.json";
 export declare const BRV_CONFIG_VERSION = "0.0.1";
 export declare const WORKTREES_DIR = "worktrees";
@@ -56,6 +57,10 @@ export declare const AGENT_PROCESS_READY_TIMEOUT_MS = 30000;
 export declare const AGENT_PROCESS_STOP_TIMEOUT_MS = 5000;
 export declare const CURATE_LOG_DIR = "curate-log";
 export declare const CURATE_LOG_ID_PREFIX = "cur";
+export declare const QUERY_LOG_DIR = "query-log";
+export declare const QUERY_LOG_ID_PREFIX = "qry";
+export declare const DREAM_LOG_DIR = "dream-log";
+export declare const DREAM_LOG_ID_PREFIX = "drm";
 export declare const REVIEW_BACKUPS_DIR = "review-backups";
 export declare const SUMMARY_INDEX_FILE = "_index.md";
 export declare const ARCHIVE_DIR = "_archived";

package/dist/server/constants.js

@@ -1,4 +1,5 @@
 export const BRV_DIR = '.brv';
+export const API_V1_PATH = '/api/v1';
 export const PROJECT_CONFIG_FILE = 'config.json';
 export const BRV_CONFIG_VERSION = '0.0.1';
 // Worktree linking (git-style: .brv is a file pointing to parent project)
@@ -76,6 +77,12 @@ export const AGENT_PROCESS_STOP_TIMEOUT_MS = 5000; // 5s max wait for child proc
 // Curate log
 export const CURATE_LOG_DIR = 'curate-log';
 export const CURATE_LOG_ID_PREFIX = 'cur';
+// Query log
+export const QUERY_LOG_DIR = 'query-log';
+export const QUERY_LOG_ID_PREFIX = 'qry';
+// Dream log
+export const DREAM_LOG_DIR = 'dream-log';
+export const DREAM_LOG_ID_PREFIX = 'drm';
 // Review backups (stores pre-curate file content for local HITL review diffs)
 export const REVIEW_BACKUPS_DIR = 'review-backups';
 // === Hierarchical DAG (summary, archive, manifest) ===

package/dist/server/core/domain/entities/query-log-entry.d.ts

@@ -0,0 +1,61 @@
+/** Valid resolution tiers. Add/remove here — the type updates automatically. */
+export declare const QUERY_LOG_TIERS: readonly [0, 1, 2, 3, 4];
+export type QueryLogTier = (typeof QUERY_LOG_TIERS)[number];
+export type TierKey = `tier${QueryLogTier}`;
+/** Named tier constants — single source of truth for tier assignments in QueryExecutor. */
+export declare const TIER_EXACT_CACHE: QueryLogTier;
+export declare const TIER_FUZZY_CACHE: QueryLogTier;
+export declare const TIER_DIRECT_SEARCH: QueryLogTier;
+export declare const TIER_OPTIMIZED_LLM: QueryLogTier;
+export declare const TIER_FULL_AGENTIC: QueryLogTier;
+/** Human-readable labels for each resolution tier (used in detail view). */
+export declare const QUERY_LOG_TIER_LABELS: Record<QueryLogTier, string>;
+/** Abbreviated tier labels for summary display. */
+export declare const QUERY_LOG_TIER_SHORT_LABELS: Record<QueryLogTier, string>;
+/** Tiers considered cache hits for cache-hit-rate calculation. */
+export declare const CACHE_TIERS: readonly [0, 1];
+export type ByTier = Record<TierKey, number> & {
+    unknown: number;
+};
+export declare function emptyByTier(): ByTier;
+/** Valid query log statuses. Add/remove here — the type updates automatically. */
+export declare const QUERY_LOG_STATUSES: readonly ["cancelled", "completed", "error", "processing"];
+export type QueryLogStatus = (typeof QUERY_LOG_STATUSES)[number];
+export type QueryLogMatchedDoc = {
+    path: string;
+    score: number;
+    title: string;
+};
+export type QueryLogSearchMetadata = {
+    cacheFingerprint?: string;
+    resultCount: number;
+    topScore: number;
+    totalFound: number;
+};
+type QueryLogBase = {
+    id: string;
+    matchedDocs: QueryLogMatchedDoc[];
+    query: string;
+    searchMetadata?: QueryLogSearchMetadata;
+    startedAt: number;
+    taskId: string;
+    tier?: QueryLogTier;
+    timing?: {
+        durationMs: number;
+    };
+};
+export type QueryLogEntry = (QueryLogBase & {
+    completedAt: number;
+    error: string;
+    status: 'error';
+}) | (QueryLogBase & {
+    completedAt: number;
+    response?: string;
+    status: 'completed';
+}) | (QueryLogBase & {
+    completedAt: number;
+    status: 'cancelled';
+}) | (QueryLogBase & {
+    status: 'processing';
+});
+export {};

package/dist/server/core/domain/entities/query-log-entry.js

@@ -0,0 +1,40 @@
+// ── Single source of truth: runtime arrays → derived types ───────────────────
+// Tiers originate from QueryExecutor (src/server/infra/executor/query-executor.ts).
+// Statuses track the entry lifecycle. Both are domain concepts.
+/** Valid resolution tiers. Add/remove here — the type updates automatically. */
+export const QUERY_LOG_TIERS = [0, 1, 2, 3, 4];
+/** Named tier constants — single source of truth for tier assignments in QueryExecutor. */
+export const TIER_EXACT_CACHE = 0;
+export const TIER_FUZZY_CACHE = 1;
+export const TIER_DIRECT_SEARCH = 2;
+export const TIER_OPTIMIZED_LLM = 3;
+export const TIER_FULL_AGENTIC = 4;
+/** Human-readable labels for each resolution tier (used in detail view). */
+export const QUERY_LOG_TIER_LABELS = {
+    [TIER_DIRECT_SEARCH]: 'direct search',
+    [TIER_EXACT_CACHE]: 'exact cache hit',
+    [TIER_FULL_AGENTIC]: 'full agentic',
+    [TIER_FUZZY_CACHE]: 'fuzzy cache match',
+    [TIER_OPTIMIZED_LLM]: 'optimized LLM',
+};
+/** Abbreviated tier labels for summary display. */
+export const QUERY_LOG_TIER_SHORT_LABELS = {
+    [TIER_DIRECT_SEARCH]: 'direct',
+    [TIER_EXACT_CACHE]: 'exact',
+    [TIER_FULL_AGENTIC]: 'agentic',
+    [TIER_FUZZY_CACHE]: 'fuzzy',
+    [TIER_OPTIMIZED_LLM]: 'LLM',
+};
+/** Tiers considered cache hits for cache-hit-rate calculation. */
+export const CACHE_TIERS = [TIER_EXACT_CACHE, TIER_FUZZY_CACHE];
+// Single `as` contained here — TS cannot prove loop exhaustiveness over template literal keys.
+export function emptyByTier() {
+    const obj = {};
+    for (const t of QUERY_LOG_TIERS) {
+        obj[`tier${t}`] = 0;
+    }
+    obj.unknown = 0;
+    return obj;
+}
+/** Valid query log statuses. Add/remove here — the type updates automatically. */
+export const QUERY_LOG_STATUSES = ['cancelled', 'completed', 'error', 'processing'];

package/dist/server/core/domain/transport/schemas.d.ts

@@ -405,6 +405,7 @@ export declare const TransportTaskEventNames: {
     readonly CREATED: "task:created";
     readonly ERROR: "task:error";
     readonly EXECUTE: "task:execute";
+    readonly QUERY_RESULT: "task:queryResult";
     readonly STARTED: "task:started";
 };
 export declare const LlmEventNames: {
@@ -509,33 +510,41 @@ export declare const TaskExecuteSchema: z.ZodObject<{
     files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     /** Folder path for curate-folder task type */
     folderPath: z.ZodOptional<z.ZodString>;
+    /** Force flag for dream tasks (skip time/activity/queue gates) */
+    force: z.ZodOptional<z.ZodBoolean>;
     /** Project path this task belongs to (for multi-project routing) */
     projectPath: z.ZodOptional<z.ZodString>;
     /** Unique task identifier */
     taskId: z.ZodString;
+    /** Dream trigger source — how this dream was initiated */
+    trigger: z.ZodOptional<z.ZodEnum<["agent-idle", "cli", "manual"]>>;
     /** Task type */
-    type: z.ZodEnum<["curate", "curate-folder", "query", "search"]>;
+    type: z.ZodEnum<["curate", "curate-folder", "dream", "query", "search"]>;
     /** Workspace root for scoped query/curate */
     worktreeRoot: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    type: "curate" | "query" | "search" | "curate-folder";
+    type: "curate" | "query" | "search" | "curate-folder" | "dream";
     content: string;
     taskId: string;
     clientId: string;
     files?: string[] | undefined;
+    force?: boolean | undefined;
     clientCwd?: string | undefined;
     folderPath?: string | undefined;
     projectPath?: string | undefined;
+    trigger?: "manual" | "agent-idle" | "cli" | undefined;
     worktreeRoot?: string | undefined;
 }, {
-    type: "curate" | "query" | "search" | "curate-folder";
+    type: "curate" | "query" | "search" | "curate-folder" | "dream";
     content: string;
     taskId: string;
     clientId: string;
     files?: string[] | undefined;
+    force?: boolean | undefined;
     clientCwd?: string | undefined;
     folderPath?: string | undefined;
     projectPath?: string | undefined;
+    trigger?: "manual" | "agent-idle" | "cli" | undefined;
     worktreeRoot?: string | undefined;
 }>;
 /**
@@ -750,6 +759,8 @@ export declare const TaskCompletedEventSchema: z.ZodObject<{
     clientId: z.ZodOptional<z.ZodString>;
     /** Log entry ID from CurateLogHandler, if applicable */
     logId: z.ZodOptional<z.ZodString>;
+    /** Project path — used by TaskRouter to notify pool for daemon-submitted tasks */
+    projectPath: z.ZodOptional<z.ZodString>;
     result: z.ZodString;
     taskId: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -757,11 +768,92 @@ export declare const TaskCompletedEventSchema: z.ZodObject<{
     taskId: string;
     logId?: string | undefined;
     clientId?: string | undefined;
+    projectPath?: string | undefined;
 }, {
     result: string;
     taskId: string;
     logId?: string | undefined;
     clientId?: string | undefined;
+    projectPath?: string | undefined;
+}>;
+/**
+ * task:queryResult - Query execution metadata (Agent → Daemon, before task:completed)
+ * Carries tier/timing/matchedDocs from QueryExecutor for QueryLogHandler.
+ * Response string is NOT included — it arrives via task:completed.
+ */
+export declare const TaskQueryResultEventSchema: z.ZodObject<{
+    matchedDocs: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        score: z.ZodNumber;
+        title: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        title: string;
+        score: number;
+    }, {
+        path: string;
+        title: string;
+        score: number;
+    }>, "many">;
+    searchMetadata: z.ZodOptional<z.ZodObject<{
+        cacheFingerprint: z.ZodOptional<z.ZodString>;
+        resultCount: z.ZodNumber;
+        topScore: z.ZodNumber;
+        totalFound: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        totalFound: number;
+        resultCount: number;
+        topScore: number;
+        cacheFingerprint?: string | undefined;
+    }, {
+        totalFound: number;
+        resultCount: number;
+        topScore: number;
+        cacheFingerprint?: string | undefined;
+    }>>;
+    taskId: z.ZodString;
+    tier: z.ZodType<0 | 3 | 1 | 2 | 4, z.ZodTypeDef, 0 | 3 | 1 | 2 | 4>;
+    timing: z.ZodObject<{
+        durationMs: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        durationMs: number;
+    }, {
+        durationMs: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    taskId: string;
+    matchedDocs: {
+        path: string;
+        title: string;
+        score: number;
+    }[];
+    tier: 0 | 3 | 1 | 2 | 4;
+    timing: {
+        durationMs: number;
+    };
+    searchMetadata?: {
+        totalFound: number;
+        resultCount: number;
+        topScore: number;
+        cacheFingerprint?: string | undefined;
+    } | undefined;
+}, {
+    taskId: string;
+    matchedDocs: {
+        path: string;
+        title: string;
+        score: number;
+    }[];
+    tier: 0 | 3 | 1 | 2 | 4;
+    timing: {
+        durationMs: number;
+    };
+    searchMetadata?: {
+        totalFound: number;
+        resultCount: number;
+        topScore: number;
+        cacheFingerprint?: string | undefined;
+    } | undefined;
 }>;
 /**
  * Structured error object
@@ -806,6 +898,8 @@ export declare const TaskErrorEventSchema: z.ZodObject<{
     }>;
     /** Log entry ID from CurateLogHandler, if applicable */
     logId: z.ZodOptional<z.ZodString>;
+    /** Project path — used by TaskRouter to notify pool for daemon-submitted tasks */
+    projectPath: z.ZodOptional<z.ZodString>;
     taskId: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     error: {
@@ -817,6 +911,7 @@ export declare const TaskErrorEventSchema: z.ZodObject<{
     taskId: string;
     logId?: string | undefined;
     clientId?: string | undefined;
+    projectPath?: string | undefined;
 }, {
     error: {
         message: string;
@@ -827,6 +922,7 @@ export declare const TaskErrorEventSchema: z.ZodObject<{
     taskId: string;
     logId?: string | undefined;
     clientId?: string | undefined;
+    projectPath?: string | undefined;
 }>;
 /**
  * llmservice:response - LLM text output
@@ -945,7 +1041,8 @@ export type TaskStartedEvent = z.infer<typeof TaskStartedEventSchema>;
 export type TaskCompletedEvent = z.infer<typeof TaskCompletedEventSchema>;
 export type TaskErrorData = z.infer<typeof TaskErrorDataSchema>;
 export type TaskErrorEvent = z.infer<typeof TaskErrorEventSchema>;
-export declare const TaskTypeSchema: z.ZodEnum<["curate", "curate-folder", "query", "search"]>;
+export type TaskQueryResultEvent = z.infer<typeof TaskQueryResultEventSchema>;
+export declare const TaskTypeSchema: z.ZodEnum<["curate", "curate-folder", "dream", "query", "search"]>;
 /**
  * Request to create a new task
  */
@@ -958,28 +1055,32 @@ export declare const TaskCreateRequestSchema: z.ZodObject<{
     files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     /** Folder path for curate-folder task type */
     folderPath: z.ZodOptional<z.ZodString>;
+    /** Force flag for dream tasks (skip time/activity/queue gates) */
+    force: z.ZodOptional<z.ZodBoolean>;
     /** Project path this task belongs to (for multi-project routing) */
     projectPath: z.ZodOptional<z.ZodString>;
     /** Task ID - generated by Client UseCase (UUID v4) */
     taskId: z.ZodString;
     /** Task type */
-    type: z.ZodEnum<["curate", "curate-folder", "query", "search"]>;
+    type: z.ZodEnum<["curate", "curate-folder", "dream", "query", "search"]>;
     /** Workspace root for scoped query/curate (stable linked root or projectRoot if unlinked) */
     worktreeRoot: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    type: "curate" | "query" | "search" | "curate-folder";
+    type: "curate" | "query" | "search" | "curate-folder" | "dream";
     content: string;
     taskId: string;
     files?: string[] | undefined;
+    force?: boolean | undefined;
     clientCwd?: string | undefined;
     folderPath?: string | undefined;
     projectPath?: string | undefined;
     worktreeRoot?: string | undefined;
 }, {
-    type: "curate" | "query" | "search" | "curate-folder";
+    type: "curate" | "query" | "search" | "curate-folder" | "dream";
     content: string;
     taskId: string;
     files?: string[] | undefined;
+    force?: boolean | undefined;
     clientCwd?: string | undefined;
     folderPath?: string | undefined;
     projectPath?: string | undefined;

package/dist/server/core/domain/transport/schemas.js

@@ -8,6 +8,7 @@
  * - Zod schemas provide runtime validation for transport messages
  */
 import { z } from 'zod';
+import { QUERY_LOG_TIERS } from '../../domain/entities/query-log-entry.js';
 // ============================================================================
 // Zod Schemas for Runtime Validation (mirrors domain types)
 // ============================================================================
@@ -216,6 +217,8 @@ export const TransportTaskEventNames = {
     ERROR: 'task:error',
     // Internal (Transport → Agent)
     EXECUTE: 'task:execute',
+    // Query metadata (Agent → Daemon, before task:completed)
+    QUERY_RESULT: 'task:queryResult',
     STARTED: 'task:started',
 };
 export const LlmEventNames = {
@@ -309,12 +312,16 @@ export const TaskExecuteSchema = z.object({
     files: z.array(z.string()).optional(),
     /** Folder path for curate-folder task type */
     folderPath: z.string().optional(),
+    /** Force flag for dream tasks (skip time/activity/queue gates) */
+    force: z.boolean().optional(),
     /** Project path this task belongs to (for multi-project routing) */
     projectPath: z.string().optional(),
     /** Unique task identifier */
     taskId: z.string(),
+    /** Dream trigger source — how this dream was initiated */
+    trigger: z.enum(['agent-idle', 'cli', 'manual']).optional(),
     /** Task type */
-    type: z.enum(['curate', 'curate-folder', 'query', 'search']),
+    type: z.enum(['curate', 'curate-folder', 'dream', 'query', 'search']),
     /** Workspace root for scoped query/curate */
     worktreeRoot: z.string().optional(),
 });
@@ -407,9 +414,30 @@ export const TaskCompletedEventSchema = z.object({
     clientId: z.string().optional(),
     /** Log entry ID from CurateLogHandler, if applicable */
     logId: z.string().optional(),
+    /** Project path — used by TaskRouter to notify pool for daemon-submitted tasks */
+    projectPath: z.string().optional(),
     result: z.string(),
     taskId: z.string(),
 });
+/**
+ * task:queryResult - Query execution metadata (Agent → Daemon, before task:completed)
+ * Carries tier/timing/matchedDocs from QueryExecutor for QueryLogHandler.
+ * Response string is NOT included — it arrives via task:completed.
+ */
+export const TaskQueryResultEventSchema = z.object({
+    matchedDocs: z.array(z.object({ path: z.string(), score: z.number(), title: z.string() })),
+    searchMetadata: z
+        .object({
+        cacheFingerprint: z.string().optional(),
+        resultCount: z.number(),
+        topScore: z.number(),
+        totalFound: z.number(),
+    })
+        .optional(),
+    taskId: z.string(),
+    tier: z.custom((val) => new Set(QUERY_LOG_TIERS).has(val), { message: 'Invalid query log tier' }),
+    timing: z.object({ durationMs: z.number() }),
+});
 /**
  * Structured error object
  * Matches TaskErrorData interface in task-error.ts
@@ -428,6 +456,8 @@ export const TaskErrorEventSchema = z.object({
     error: TaskErrorDataSchema,
     /** Log entry ID from CurateLogHandler, if applicable */
     logId: z.string().optional(),
+    /** Project path — used by TaskRouter to notify pool for daemon-submitted tasks */
+    projectPath: z.string().optional(),
     taskId: z.string(),
 });
 /**
@@ -475,7 +505,7 @@ export const LlmToolResultEventSchema = z.object({
 // ============================================================================
 // Request/Response Schemas (for client → server commands)
 // ============================================================================
-export const TaskTypeSchema = z.enum(['curate', 'curate-folder', 'query', 'search']);
+export const TaskTypeSchema = z.enum(['curate', 'curate-folder', 'dream', 'query', 'search']);
 /**
  * Request to create a new task
  */
@@ -488,6 +518,8 @@ export const TaskCreateRequestSchema = z.object({
     files: z.array(z.string()).optional(),
     /** Folder path for curate-folder task type */
     folderPath: z.string().optional(),
+    /** Force flag for dream tasks (skip time/activity/queue gates) */
+    force: z.boolean().optional(),
     /** Project path this task belongs to (for multi-project routing) */
     projectPath: z.string().optional(),
     /** Task ID - generated by Client UseCase (UUID v4) */

package/dist/server/core/interfaces/executor/i-query-executor.d.ts

@@ -1,4 +1,5 @@
 import type { ICipherAgent } from '../../../../agent/core/interfaces/i-cipher-agent.js';
+import type { QueryLogMatchedDoc, QueryLogSearchMetadata, QueryLogTier } from '../../domain/entities/query-log-entry.js';
 /**
  * Options for executing query with an injected agent.
  * Agent uses its default session (Single-Session pattern).
@@ -11,6 +12,26 @@ export interface QueryExecuteOptions {
     /** Stable workspace root for scoping search and cache isolation */
     worktreeRoot?: string;
 }
+/**
+ * Structured result from QueryExecutor containing the response string
+ * plus metadata about how the query was resolved.
+ *
+ * Consumed by QueryLogHandler (ENG-1893) to persist query log entries.
+ */
+export type QueryExecutorResult = {
+    /** Documents matched during search (empty for cache hits) */
+    matchedDocs: QueryLogMatchedDoc[];
+    /** The response string (includes attribution footer) */
+    response: string;
+    /** Search statistics (undefined for cache-only tiers 0/1) */
+    searchMetadata?: QueryLogSearchMetadata;
+    /** Resolution tier: 0=exact cache, 1=fuzzy cache, 2=direct search, 3=optimized LLM, 4=full agentic */
+    tier: QueryLogTier;
+    /** Wall-clock timing from method entry to return */
+    timing: {
+        durationMs: number;
+    };
+};
 /**
  * IQueryExecutor - Executes query tasks with an injected CipherAgent.
  *
@@ -28,7 +49,7 @@ export interface IQueryExecutor {
      *
      * @param agent - Long-lived CipherAgent (managed by caller)
      * @param options - Execution options (query)
-     * @returns Result string from agent execution
+     * @returns Structured result with response, tier, timing, and search metadata
      */
-    executeWithAgent(agent: ICipherAgent, options: QueryExecuteOptions): Promise<string>;
+    executeWithAgent(agent: ICipherAgent, options: QueryExecuteOptions): Promise<QueryExecutorResult>;
 }

package/dist/server/core/interfaces/i-terminal.d.ts

@@ -0,0 +1,3 @@
+export interface ITerminal {
+    log(msg?: string): void;
+}

package/dist/server/core/interfaces/i-terminal.js

@@ -0,0 +1 @@
+export {};

package/dist/server/core/interfaces/storage/i-query-log-store.d.ts

@@ -0,0 +1,23 @@
+import type { QueryLogEntry, QueryLogStatus, QueryLogTier } from '../../domain/entities/query-log-entry.js';
+export { QUERY_LOG_STATUSES, QUERY_LOG_TIERS } from '../../domain/entities/query-log-entry.js';
+export type { QueryLogStatus, QueryLogTier } from '../../domain/entities/query-log-entry.js';
+export interface IQueryLogStore {
+    /** Retrieve an entry by ID. Returns undefined if not found or if the file is corrupt. */
+    getById(id: string): Promise<QueryLogEntry | undefined>;
+    /** Generate the next monotonic log entry ID. */
+    getNextId(): Promise<string>;
+    /** List entries sorted newest-first. Filters are applied before limit. */
+    list(options?: {
+        /** Include only entries with startedAt >= after (ms timestamp). */
+        after?: number;
+        /** Include only entries with startedAt <= before (ms timestamp). */
+        before?: number;
+        limit?: number;
+        /** Include only entries matching these statuses. */
+        status?: QueryLogStatus[];
+        /** Include only entries matching these tiers. */
+        tier?: QueryLogTier[];
+    }): Promise<QueryLogEntry[]>;
+    /** Persist (create or overwrite) a log entry. Best-effort — callers should handle errors. */
+    save(entry: QueryLogEntry): Promise<void>;
+}

package/dist/server/core/interfaces/storage/i-query-log-store.js

@@ -0,0 +1,2 @@
+// Re-export domain types — single source of truth is in the entity.
+export { QUERY_LOG_STATUSES, QUERY_LOG_TIERS } from '../../domain/entities/query-log-entry.js';

package/dist/server/core/interfaces/usecase/i-query-log-summary-use-case.d.ts

@@ -0,0 +1,44 @@
+import type { ByTier } from '../../domain/entities/query-log-entry.js';
+export type QueryLogSummary = {
+    byStatus: {
+        cancelled: number;
+        completed: number;
+        error: number;
+    };
+    byTier: ByTier;
+    cacheHitRate: number;
+    coverageRate: number;
+    knowledgeGaps: {
+        count: number;
+        exampleQueries: string[];
+        topic: string;
+    }[];
+    period: {
+        from: number;
+        to: number;
+    };
+    queriesWithoutMatches: number;
+    responseTime: {
+        avgMs: number;
+        p50Ms: number;
+        p95Ms: number;
+    };
+    topRecalledDocs: {
+        count: number;
+        path: string;
+    }[];
+    topTopics: {
+        count: number;
+        topic: string;
+    }[];
+    totalMatchedDocs: number;
+    totalQueries: number;
+};
+export type QueryLogSummaryFormat = 'json' | 'narrative' | 'text';
+export interface IQueryLogSummaryUseCase {
+    run(options: {
+        after?: number;
+        before?: number;
+        format?: QueryLogSummaryFormat;
+    }): Promise<void>;
+}

package/dist/server/core/interfaces/usecase/i-query-log-summary-use-case.js

@@ -0,0 +1 @@
+export {};

package/dist/server/core/interfaces/usecase/i-query-log-use-case.d.ts

@@ -0,0 +1,13 @@
+import type { QueryLogStatus, QueryLogTier } from '../storage/i-query-log-store.js';
+export interface IQueryLogUseCase {
+    run(options: {
+        after?: number;
+        before?: number;
+        detail?: boolean;
+        format?: 'json' | 'text';
+        id?: string;
+        limit?: number;
+        status?: QueryLogStatus[];
+        tier?: QueryLogTier[];
+    }): Promise<void>;
+}

package/dist/server/core/interfaces/usecase/i-query-log-use-case.js

@@ -0,0 +1,3 @@
+// Interface driven by brv query-log view command (ENG-1897).
+// Full implementation in ENG-1895.
+export {};