byterover-cli 3.1.0 → 3.3.0

package/README.md

@@ -241,6 +241,23 @@ ByteRover CLI supports 18 LLM providers out of the box. Use `brv providers conne
 
 </details>
 
+## Worktrees and Knowledge Sources
+
+> **Vocabulary**
+> - **Worktree link** — a subdirectory pointer to a parent project (`brv worktree`)
+> - **Source** — a read-only reference to another project's knowledge (`brv source`)
+> - **Origin** — where an indexed search result came from (`local` vs `shared`)
+
+ByteRover can run from a linked subdirectory without creating a nested `.brv/`.
+
+- `projectRoot`: the directory that owns `.brv/config.json`
+- `worktreeRoot`: the linked worktree directory, or `projectRoot` when unlinked
+- `clientCwd`: the shell cwd where you ran `brv`
+
+When you run `brv query` or `brv curate` from a linked worktree, implicit defaults use `worktreeRoot` so scope stays stable even if `clientCwd` drifts deeper into the package. Explicit relative paths that you pass yourself, such as `brv curate -f ./src/auth.ts`, still resolve from `clientCwd` to match normal shell behavior.
+
+Use `brv worktree add` from the project root to register a subdirectory (or sibling) as a worktree. This creates a `.brv` pointer file in the target directory that redirects to the parent project — the same pattern git uses for `git worktree`. Use `brv worktree remove` to unregister, and `brv worktree list` to inspect. To search another project's knowledge from here, use `brv source add <path>` (with `brv source list` / `brv source remove` to inspect or detach).
+
 ## Documentation
 
 Visit [**docs.byterover.dev**](https://docs.byterover.dev) for full guides on setup, integrations, and advanced usage.

package/dist/agent/infra/agent/agent-schemas.d.ts

@@ -46,13 +46,16 @@ export type ValidatedSessionConfig = z.output<typeof SessionConfigSchema>;
  */
 export declare const FileSystemConfigSchema: z.ZodObject<{
     allowedExtensions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    allowedPaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     maxFileSize: z.ZodOptional<z.ZodNumber>;
     workingDirectory: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
+    allowedPaths?: string[] | undefined;
     allowedExtensions?: string[] | undefined;
     workingDirectory?: string | undefined;
     maxFileSize?: number | undefined;
 }, {
+    allowedPaths?: string[] | undefined;
     allowedExtensions?: string[] | undefined;
     workingDirectory?: string | undefined;
     maxFileSize?: number | undefined;
@@ -101,13 +104,16 @@ export declare const AgentConfigSchema: z.ZodObject<{
     }>>;
     fileSystem: z.ZodOptional<z.ZodObject<{
         allowedExtensions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedPaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         maxFileSize: z.ZodOptional<z.ZodNumber>;
         workingDirectory: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
+        allowedPaths?: string[] | undefined;
         allowedExtensions?: string[] | undefined;
         workingDirectory?: string | undefined;
         maxFileSize?: number | undefined;
     }, {
+        allowedPaths?: string[] | undefined;
         allowedExtensions?: string[] | undefined;
         workingDirectory?: string | undefined;
         maxFileSize?: number | undefined;
@@ -185,6 +191,7 @@ export declare const AgentConfigSchema: z.ZodObject<{
         storageDir: string;
     } | undefined;
     fileSystem?: {
+        allowedPaths?: string[] | undefined;
         allowedExtensions?: string[] | undefined;
         workingDirectory?: string | undefined;
         maxFileSize?: number | undefined;
@@ -223,6 +230,7 @@ export declare const AgentConfigSchema: z.ZodObject<{
         maxBlobSize?: number | undefined;
     } | undefined;
     fileSystem?: {
+        allowedPaths?: string[] | undefined;
         allowedExtensions?: string[] | undefined;
         workingDirectory?: string | undefined;
         maxFileSize?: number | undefined;

package/dist/agent/infra/agent/agent-schemas.js

@@ -27,6 +27,7 @@ export const SessionConfigSchema = z
 export const FileSystemConfigSchema = z
     .object({
     allowedExtensions: z.array(z.string()).optional().describe('Allowed file extensions'),
+    allowedPaths: z.array(z.string()).optional().describe('Allowed paths for file operations (default: ["."])'),
     maxFileSize: z.number().positive().optional().describe('Maximum file size in bytes'),
     workingDirectory: z.string().optional().describe('Working directory for file operations'),
 })

package/dist/agent/infra/sandbox/curate-service.js

@@ -4,6 +4,7 @@
  */
 import { resolve } from 'node:path';
 import { executeCurate } from '../tools/implementations/curate-tool.js';
+import { validateWriteTarget } from '../tools/write-guard.js';
 /**
  * Default base path for knowledge storage.
  */
@@ -90,6 +91,19 @@ export class CurateService {
         // Resolve relative basePath against the working directory to ensure
         // files are written to the correct project directory, not process.cwd()
         const basePath = resolve(this.workingDirectory, rawBasePath);
+        // Source write guard: block curate to shared source context trees
+        const writeError = validateWriteTarget(basePath, this.workingDirectory);
+        if (writeError) {
+            return {
+                applied: [{
+                        message: writeError,
+                        path: rawBasePath,
+                        status: 'failed',
+                        type: 'ADD',
+                    }],
+                summary: { added: 0, deleted: 0, failed: 1, merged: 0, updated: 0 },
+            };
+        }
         // Pre-validate operations to catch common mistakes early
         const validationFailures = validateOperations(operations);
         if (validationFailures.length > 0) {

package/dist/agent/infra/sandbox/sandbox-service.js

@@ -215,6 +215,7 @@ export class SandboxService {
             curateService: this.curateService,
             fileSystem: this.fileSystem,
             parentSessionId: sessionId,
+            projectRoot: this.environmentContext?.workingDirectory,
             sandboxService: this,
             searchKnowledgeService: this.searchKnowledgeService,
             sessionManager: this.sessionManager,

package/dist/agent/infra/sandbox/tools-sdk.d.ts

@@ -62,6 +62,8 @@ export interface ListDirectoryOptions {
 export interface SearchKnowledgeOptions {
     /** Maximum number of results to return (default: 10) */
     limit?: number;
+    /** Path prefix to scope search within (e.g. "auth" or "packages/api") */
+    scope?: string;
 }
 /**
  * Result type for searchKnowledge operation.
@@ -74,6 +76,12 @@ export interface SearchKnowledgeResult {
         /** Number of other memories that reference this one */
         backlinkCount?: number;
         excerpt: string;
+        /** Origin: 'local' for this project, 'shared' for results from knowledge source */
+        origin?: 'local' | 'shared';
+        /** Alias of the shared source (undefined for local results) */
+        originAlias?: string;
+        /** Absolute path to the context tree root this result belongs to. Use join(originContextTreeRoot, path) to read. */
+        originContextTreeRoot?: string;
         /** Path to .overview.md for this entry; present when L1 overview exists */
         overviewPath?: string;
         path: string;
@@ -225,6 +233,8 @@ export interface CreateToolsSDKOptions {
     fileSystem: IFileSystem;
     /** Parent session ID for creating child sessions (required for agentQuery) */
     parentSessionId?: string;
+    /** Project root for write guard validation (blocks writes to shared source context trees) */
+    projectRoot?: string;
     /** Sandbox service for variable injection into child sessions (optional, enables contextData in agentQuery) */
     sandboxService?: ISandboxService;
     /** Search knowledge service */

package/dist/agent/infra/sandbox/tools-sdk.js

@@ -1,5 +1,6 @@
 import { ContextTreeStore } from '../map/context-tree-store.js';
 import { executeLlmMapMemory } from '../map/llm-map-memory.js';
+import { validateWriteTarget } from '../tools/write-guard.js';
 import { chunk, dedup, detectMessageBoundaries, groupBySubject, recon, recordProgress, } from './curation-helpers.js';
 /**
  * Creates a Tools SDK instance for sandbox code execution.
@@ -11,7 +12,7 @@ import { chunk, dedup, detectMessageBoundaries, groupBySubject, recon, recordPro
  * @returns ToolsSDK instance ready to be injected into sandbox context
  */
 export function createToolsSDK(options) {
-    const { commandType, contentGenerator, curateService, fileSystem, parentSessionId, sandboxService, searchKnowledgeService, sessionManager } = options;
+    const { commandType, contentGenerator, curateService, fileSystem, parentSessionId, projectRoot, sandboxService, searchKnowledgeService, sessionManager } = options;
     const isReadOnly = commandType === 'query';
     return {
         async agentQuery(prompt, options) {
@@ -156,6 +157,13 @@ export function createToolsSDK(options) {
             if (isReadOnly) {
                 throw new Error('writeFile() is disabled in read-only (query) mode');
             }
+            // Write guard: block writes to shared source context trees
+            if (projectRoot) {
+                const writeError = validateWriteTarget(filePath, projectRoot);
+                if (writeError) {
+                    throw new Error(writeError);
+                }
+            }
             return fileSystem.writeFile(filePath, content, {
                 createDirs: options?.createDirs ?? false,
             });