byterover-cli 3.0.1 → 3.2.0

package/dist/agent/infra/map/abstract-queue.js

@@ -0,0 +1,218 @@
+import { appendFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { generateFileAbstracts } from './abstract-generator.js';
+const QUEUE_TRACE_ENABLED = process.env.BRV_QUEUE_TRACE === '1';
+const LOG_PATH = process.env.BRV_SESSION_LOG;
+function queueLog(message) {
+    if (!QUEUE_TRACE_ENABLED || !LOG_PATH)
+        return;
+    try {
+        appendFileSync(LOG_PATH, `${new Date().toISOString()} [abstract-queue] ${message}\n`);
+    }
+    catch {
+        // ignore — tracing must never block queue progress
+    }
+}
+/**
+ * Background queue for generating L0/L1 abstract files (.abstract.md, .overview.md).
+ *
+ * - Generator is injected lazily via setGenerator() (mirrors rebindMapTools pattern)
+ * - Items arriving before setGenerator() are buffered and processed once generator is set
+ * - Writes status to <projectRoot>/.brv/_queue_status.json after each state transition
+ * - Retries up to maxAttempts with exponential backoff (500ms base)
+ * - drain() waits for all pending/processing items to complete (for graceful shutdown)
+ */
+export class AbstractGenerationQueue {
+    projectRoot;
+    maxAttempts;
+    drainResolvers = [];
+    failed = 0;
+    generator;
+    onBeforeProcess;
+    pending = [];
+    processed = 0;
+    processing = false;
+    /** Number of items currently in retry backoff (removed from pending but not yet re-enqueued). */
+    retrying = 0;
+    statusDirCreated = false;
+    statusWriteFailed = false;
+    statusWritePromise = Promise.resolve();
+    constructor(projectRoot, maxAttempts = 3) {
+        this.projectRoot = projectRoot;
+        this.maxAttempts = maxAttempts;
+    }
+    /**
+     * Wait for all pending items to finish processing (graceful shutdown).
+     * Includes items currently in retry backoff so drain() does not resolve prematurely.
+     */
+    async drain() {
+        queueLog(`drain:start idle=${this.isIdle()} pending=${this.pending.length} retrying=${this.retrying} processing=${this.processing}`);
+        if (this.isIdle()) {
+            await this.statusWritePromise.catch(() => { });
+            queueLog('drain:resolved-immediate');
+            return;
+        }
+        await new Promise((resolve) => {
+            this.drainResolvers.push(resolve);
+            this.resolveDrainersIfIdle();
+        });
+        queueLog('drain:resolved-deferred');
+    }
+    /**
+     * Add a file to the abstract generation queue.
+     */
+    enqueue(item) {
+        // Guard against paths that must never trigger abstract generation:
+        // - derived artifacts (.abstract.md, .overview.md) — would produce .abstract.abstract.md
+        // - summary index files (_index.md) — domain/topic summaries, not knowledge nodes
+        // - hierarchy scaffolding (context.md) — helper files, not leaf knowledge entries
+        const fileName = item.contextPath.split('/').at(-1) ?? item.contextPath;
+        if (fileName === 'context.md' ||
+            fileName === '_index.md' ||
+            item.contextPath.endsWith('.abstract.md') ||
+            item.contextPath.endsWith('.overview.md')) {
+            return;
+        }
+        this.pending.push({ attempts: 0, contextPath: item.contextPath, fullContent: item.fullContent });
+        queueLog(`enqueue path=${item.contextPath} pending=${this.pending.length} retrying=${this.retrying} processing=${this.processing}`);
+        this.queueStatusWrite();
+        this.scheduleNext();
+    }
+    /**
+     * Return current queue status snapshot.
+     */
+    getStatus() {
+        return {
+            failed: this.failed,
+            // Items in retry backoff are still pending work — include them so the status
+            // does not falsely report the queue as idle during backoff windows.
+            pending: this.pending.length + this.retrying,
+            processed: this.processed,
+            processing: this.processing,
+        };
+    }
+    /**
+     * Set a callback that runs before each item is processed.
+     * Used to refresh OAuth tokens before LLM calls.
+     */
+    setBeforeProcess(fn) {
+        this.onBeforeProcess = fn;
+    }
+    /**
+     * Inject the LLM generator. Triggers processing of any buffered items.
+     */
+    setGenerator(generator) {
+        this.generator = generator;
+        this.scheduleNext();
+    }
+    isIdle() {
+        return this.pending.length === 0 && !this.processing && this.retrying === 0;
+    }
+    async processNext() {
+        if (!this.generator || this.processing || this.pending.length === 0) {
+            this.resolveDrainersIfIdle();
+            return;
+        }
+        this.processing = true;
+        this.queueStatusWrite();
+        const item = this.pending.shift();
+        queueLog(`process:start path=${item.contextPath} remaining=${this.pending.length} retrying=${this.retrying}`);
+        try {
+            // Refresh credentials before each generation (OAuth tokens may expire)
+            try {
+                await this.onBeforeProcess?.();
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                console.debug(`[AbstractQueue] token refresh failed, proceeding with existing generator: ${msg}`);
+            }
+            const { abstractContent, overviewContent } = await generateFileAbstracts(item.fullContent, this.generator);
+            // Derive sibling paths: replace .md with .abstract.md and .overview.md
+            const abstractPath = item.contextPath.replace(/\.md$/, '.abstract.md');
+            const overviewPath = item.contextPath.replace(/\.md$/, '.overview.md');
+            await Promise.all([
+                writeFile(abstractPath, abstractContent, 'utf8'),
+                writeFile(overviewPath, overviewContent, 'utf8'),
+            ]);
+            this.processed++;
+            queueLog(`process:success path=${item.contextPath} processed=${this.processed}`);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            console.debug(`[AbstractQueue] ${item.contextPath} attempt ${item.attempts + 1}/${this.maxAttempts}: ${msg}`);
+            item.attempts++;
+            if (item.attempts < this.maxAttempts) {
+                // Exponential backoff: 500ms, 1000ms, 2000ms, ...
+                const delay = 500 * 2 ** (item.attempts - 1);
+                this.retrying++;
+                this.queueStatusWrite();
+                setTimeout(() => {
+                    this.retrying--;
+                    this.pending.unshift(item);
+                    queueLog(`process:retry-requeue path=${item.contextPath} pending=${this.pending.length} retrying=${this.retrying}`);
+                    this.queueStatusWrite();
+                    this.scheduleNext();
+                }, delay);
+            }
+            else {
+                this.failed++;
+                queueLog(`process:failed path=${item.contextPath} failed=${this.failed}`);
+            }
+        }
+        finally {
+            this.processing = false;
+            queueLog(`process:finally path=${item.contextPath} pending=${this.pending.length} retrying=${this.retrying} processed=${this.processed} failed=${this.failed}`);
+            this.queueStatusWrite();
+        }
+        this.scheduleNext();
+        this.resolveDrainersIfIdle();
+    }
+    queueStatusWrite() {
+        this.statusWritePromise = this.statusWritePromise
+            .catch(() => { })
+            .then(async () => this.writeStatusFile());
+    }
+    resolveDrainersIfIdle() {
+        if (!this.isIdle() || this.drainResolvers.length === 0) {
+            return;
+        }
+        queueLog(`drain:idle pending=${this.pending.length} retrying=${this.retrying} processed=${this.processed} failed=${this.failed}`);
+        const resolvers = this.drainResolvers.splice(0);
+        const settledStatusWrite = this.statusWritePromise.catch(() => { });
+        for (const resolve of resolvers) {
+            settledStatusWrite.then(() => resolve()).catch(() => { });
+        }
+    }
+    scheduleNext() {
+        if (!this.generator || this.processing || this.pending.length === 0) {
+            this.resolveDrainersIfIdle();
+            return;
+        }
+        // eslint-disable-next-line no-void
+        setImmediate(() => { void this.processNext(); });
+    }
+    async writeStatusFile() {
+        const statusPath = join(this.projectRoot, '.brv', '_queue_status.json');
+        try {
+            if (!this.statusDirCreated) {
+                await mkdir(join(this.projectRoot, '.brv'), { recursive: true });
+                this.statusDirCreated = true;
+            }
+            await writeFile(statusPath, JSON.stringify(this.getStatus()), 'utf8');
+            this.statusWriteFailed = false;
+        }
+        catch (error) {
+            const errorCode = typeof error === 'object' && error !== null && 'code' in error
+                ? error.code
+                : undefined;
+            if (errorCode === 'ENOENT') {
+                return;
+            }
+            if (!this.statusWriteFailed) {
+                this.statusWriteFailed = true;
+                console.debug(`[AbstractGenerationQueue] Failed to write queue status: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+}

package/dist/agent/infra/memory/memory-deduplicator.d.ts

@@ -0,0 +1,44 @@
+import type { Memory } from '../../core/domain/memory/types.js';
+import type { IContentGenerator } from '../../core/interfaces/i-content-generator.js';
+/**
+ * A draft memory extracted from a session, before deduplication.
+ */
+export interface DraftMemory {
+    category: string;
+    content: string;
+    tags?: string[];
+}
+/**
+ * Deduplication decision for a single draft memory.
+ */
+export type DeduplicationAction = {
+    action: 'CREATE';
+    memory: DraftMemory;
+} | {
+    action: 'MERGE';
+    memory: DraftMemory;
+    mergedContent: string;
+    targetId: string;
+} | {
+    action: 'SKIP';
+    memory: DraftMemory;
+};
+/**
+ * LLM-based deduplicator for agent-extracted memories.
+ *
+ * For each draft, checks against existing memories via an LLM call.
+ * DECISIONS category drafts always result in CREATE (immutable log).
+ */
+export declare class MemoryDeduplicator {
+    private readonly generator;
+    constructor(generator: IContentGenerator);
+    /**
+     * Deduplicate a list of draft memories against existing stored memories.
+     *
+     * @param drafts - Draft memories to check
+     * @param existing - Existing memories to compare against
+     * @returns Deduplication action for each draft
+     */
+    deduplicate(drafts: DraftMemory[], existing: Memory[]): Promise<DeduplicationAction[]>;
+    private deduplicateSingle;
+}

package/dist/agent/infra/memory/memory-deduplicator.js

@@ -0,0 +1,88 @@
+import { randomUUID } from 'node:crypto';
+import { streamToText } from '../llm/stream-to-text.js';
+const SYSTEM_PROMPT = `You are a memory deduplication assistant. Given a new draft memory and a list of existing memories, decide one of:
+- CREATE: the draft is new and should be stored as-is
+- MERGE: the draft overlaps with an existing memory; provide merged content
+- SKIP: the draft is already covered by an existing memory
+
+Respond with ONLY a JSON object:
+{"action": "CREATE"}
+{"action": "MERGE", "targetId": "<id>", "mergedContent": "<combined content>"}
+{"action": "SKIP"}`;
+const DEDUPLICATION_CONCURRENCY = 4;
+/**
+ * LLM-based deduplicator for agent-extracted memories.
+ *
+ * For each draft, checks against existing memories via an LLM call.
+ * DECISIONS category drafts always result in CREATE (immutable log).
+ */
+export class MemoryDeduplicator {
+    generator;
+    constructor(generator) {
+        this.generator = generator;
+    }
+    /**
+     * Deduplicate a list of draft memories against existing stored memories.
+     *
+     * @param drafts - Draft memories to check
+     * @param existing - Existing memories to compare against
+     * @returns Deduplication action for each draft
+     */
+    async deduplicate(drafts, existing) {
+        if (existing.length === 0) {
+            return drafts.map((memory) => ({ action: 'CREATE', memory }));
+        }
+        const actions = Array.from({ length: drafts.length });
+        const concurrency = Math.min(DEDUPLICATION_CONCURRENCY, drafts.length);
+        const worker = async (workerIndex) => {
+            for (let draftIndex = workerIndex; draftIndex < drafts.length; draftIndex += concurrency) {
+                const draft = drafts[draftIndex];
+                if (draft.category === 'DECISIONS') {
+                    actions[draftIndex] = { action: 'CREATE', memory: draft };
+                    continue;
+                }
+                // eslint-disable-next-line no-await-in-loop
+                actions[draftIndex] = await this.deduplicateSingle(draft, existing);
+            }
+        };
+        await Promise.all(Array.from({ length: concurrency }, async (_, workerIndex) => worker(workerIndex)));
+        return actions;
+    }
+    async deduplicateSingle(draft, existing) {
+        const existingSummary = JSON.stringify(existing.map((m) => ({ content: m.content.slice(0, 300), id: m.id })));
+        const prompt = `## Draft Memory (category: ${draft.category})
+${draft.content}
+
+## Existing Memories (JSON)
+${existingSummary}
+
+Decide: CREATE, MERGE (with targetId and mergedContent), or SKIP.`;
+        try {
+            // Use streaming — ChatGPT OAuth Codex endpoint requires stream: true
+            const responseText = await streamToText(this.generator, {
+                config: { maxTokens: 300, temperature: 0 },
+                contents: [{ content: prompt, role: 'user' }],
+                model: 'default',
+                systemPrompt: SYSTEM_PROMPT,
+                taskId: randomUUID(),
+            });
+            // Strip markdown code fences — some providers wrap JSON in ```json ... ```
+            const jsonText = responseText.replace(/^```(?:json)?\s*\n?/i, '').replace(/\n?```\s*$/i, '').trim();
+            const parsed = JSON.parse(jsonText);
+            const targetExists = parsed.targetId ? existing.some((memory) => memory.id === parsed.targetId) : false;
+            if (parsed.action === 'MERGE' && targetExists && parsed.mergedContent && parsed.targetId) {
+                return { action: 'MERGE', memory: draft, mergedContent: parsed.mergedContent, targetId: parsed.targetId };
+            }
+            if (parsed.action === 'SKIP') {
+                return { action: 'SKIP', memory: draft };
+            }
+            return { action: 'CREATE', memory: draft };
+        }
+        catch (error) {
+            // On any error, default to CREATE (fail-open)
+            const msg = error instanceof Error ? error.message : String(error);
+            console.debug(`[MemoryDeduplicator] Failed for ${draft.category}: ${msg}`);
+            return { action: 'CREATE', memory: draft };
+        }
+    }
+}

package/dist/agent/infra/memory/memory-manager.d.ts

@@ -20,6 +20,7 @@ import type { ILogger } from '../../core/interfaces/i-logger.js';
  */
 export declare class MemoryManager {
     private blobStorage;
+    private static readonly MEMORY_ID_LENGTH;
     private static readonly MEMORY_KEY_PREFIX;
     private readonly logger;
     constructor(blobStorage: IBlobStorage, logger?: ILogger);

package/dist/agent/infra/memory/memory-manager.js

@@ -105,6 +105,7 @@ const ListMemoriesOptionsSchema = z
  */
 export class MemoryManager {
     blobStorage;
+    static MEMORY_ID_LENGTH = 12;
     static MEMORY_KEY_PREFIX = 'memory-';
     logger;
     constructor(blobStorage, logger) {
@@ -468,11 +469,11 @@ export class MemoryManager {
         if (!key.startsWith(MemoryManager.MEMORY_KEY_PREFIX)) {
             return false;
         }
-        // Memory keys have format: memory-{id}
-        // Attachment keys have format: memory-{id}-{suffix}
-        // Count dashes: memory keys have 1 dash, attachments have 2+
-        const dashCount = (key.match(/-/g) || []).length;
-        return dashCount === 1;
+        // Memory keys have format: memory-{id} where id is a fixed-length nanoid(12).
+        // Attachment keys append an extra suffix: memory-{id}-{suffix}.
+        // A valid memory id may itself contain '-', so counting dashes is incorrect.
+        const suffix = key.slice(MemoryManager.MEMORY_KEY_PREFIX.length);
+        return suffix.length === MemoryManager.MEMORY_ID_LENGTH;
     }
     /**
      * Load all memories from blob storage

package/dist/agent/infra/sandbox/curate-service.d.ts

@@ -3,13 +3,15 @@
  * Wraps the curate-tool logic for use in the sandbox's tools.* SDK.
  */
 import type { CurateOperation, CurateOptions, CurateResult, DetectDomainsInput, DetectDomainsResult, ICurateService } from '../../core/interfaces/i-curate-service.js';
+import type { AbstractGenerationQueue } from '../map/abstract-queue.js';
 /**
  * Curate service implementation.
  * Provides curate and domain detection operations for the sandbox.
  */
 export declare class CurateService implements ICurateService {
+    private readonly abstractQueue?;
     private readonly workingDirectory;
-    constructor(workingDirectory?: string);
+    constructor(workingDirectory?: string, abstractQueue?: AbstractGenerationQueue | undefined);
     /**
      * Execute curate operations on knowledge topics.
      *
@@ -33,4 +35,4 @@ export declare class CurateService implements ICurateService {
  * @param workingDirectory - Working directory for resolving relative paths
  * @returns CurateService instance
  */
-export declare function createCurateService(workingDirectory?: string): ICurateService;
+export declare function createCurateService(workingDirectory?: string, abstractQueue?: AbstractGenerationQueue): ICurateService;

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.
  */
@@ -72,8 +73,10 @@ function validateOperations(operations) {
  * Provides curate and domain detection operations for the sandbox.
  */
 export class CurateService {
+    abstractQueue;
     workingDirectory;
-    constructor(workingDirectory) {
+    constructor(workingDirectory, abstractQueue) {
+        this.abstractQueue = abstractQueue;
         this.workingDirectory = workingDirectory ?? process.cwd();
     }
     /**
@@ -88,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) {
@@ -104,10 +120,7 @@ export class CurateService {
             };
         }
         // Call the underlying executeCurate function from curate-tool
-        const result = await executeCurate({
-            basePath,
-            operations,
-        });
+        const result = await executeCurate({ basePath, operations }, undefined, this.abstractQueue);
         return result;
     }
     /**
@@ -146,6 +159,6 @@ export class CurateService {
  * @param workingDirectory - Working directory for resolving relative paths
  * @returns CurateService instance
  */
-export function createCurateService(workingDirectory) {
-    return new CurateService(workingDirectory);
+export function createCurateService(workingDirectory, abstractQueue) {
+    return new CurateService(workingDirectory, abstractQueue);
 }

package/dist/agent/infra/sandbox/local-sandbox.d.ts

@@ -22,6 +22,8 @@ export declare class LocalSandbox {
     /** Value set by setFinalResult() — signals early exit */
     private finalResult?;
     private outputBuffer;
+    /** Async tool calls started inside the sandbox, including unawaited ones. */
+    private pendingToolPromises;
     /** Current stdout cap in chars (undefined = unlimited) */
     private stdoutCap?;
     /** Running count of chars written to outputBuffer in current execution */
@@ -50,9 +52,12 @@ export declare class LocalSandbox {
      * @param updates - Key-value pairs to add to context
      */
     updateContext(updates: Record<string, unknown>): void;
+    private awaitPendingToolPromises;
     /**
      * Push a line to stdout, respecting the optional character cap.
      * When the cap is reached, appends a truncation notice and drops further output.
      */
     private pushStdout;
+    private trackPromise;
+    private wrapToolObject;
 }

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

@@ -87,6 +87,8 @@ export class LocalSandbox {
     /** Value set by setFinalResult() — signals early exit */
     finalResult;
     outputBuffer = [];
+    /** Async tool calls started inside the sandbox, including unawaited ones. */
+    pendingToolPromises = new Set();
     /** Current stdout cap in chars (undefined = unlimited) */
     stdoutCap;
     /** Running count of chars written to outputBuffer in current execution */
@@ -118,7 +120,7 @@ export class LocalSandbox {
         };
         // Inject Tools SDK if provided (for file system operations)
         if (toolsSDK) {
-            sandbox.tools = toolsSDK;
+            sandbox.tools = this.wrapToolObject(toolsSDK);
         }
         // Inject environment context as `env` object if provided
         if (environmentContext) {
@@ -152,6 +154,7 @@ export class LocalSandbox {
         this.outputBuffer = [];
         this.errorBuffer = [];
         this.finalResult = undefined;
+        this.pendingToolPromises.clear();
         this.stdoutCap = config?.maxStdoutChars;
         this.stdoutCharsWritten = 0;
         this.stdoutTruncated = false;
@@ -192,6 +195,8 @@ export class LocalSandbox {
                     }
                 }
             }
+            const elapsedMs = performance.now() - startTime;
+            await this.awaitPendingToolPromises(Math.max(0, timeout - elapsedMs));
         }
         catch (error) {
             const errorMessage = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
@@ -243,6 +248,32 @@ export class LocalSandbox {
             this.context[key] = value;
         }
     }
+    async awaitPendingToolPromises(timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        /* eslint-disable no-await-in-loop */
+        while (this.pendingToolPromises.size > 0) {
+            const pending = [...this.pendingToolPromises];
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                throw new Error('Async execution timeout');
+            }
+            let timeoutId;
+            try {
+                await Promise.race([
+                    Promise.allSettled(pending),
+                    new Promise((_, reject) => {
+                        timeoutId = setTimeout(() => reject(new Error('Async execution timeout')), remaining);
+                    }),
+                ]);
+            }
+            finally {
+                if (timeoutId !== undefined) {
+                    clearTimeout(timeoutId);
+                }
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+    }
     /**
      * Push a line to stdout, respecting the optional character cap.
      * When the cap is reached, appends a truncation notice and drops further output.
@@ -263,4 +294,29 @@ export class LocalSandbox {
         this.stdoutCharsWritten += line.length + 1; // +1 for join newline
         this.outputBuffer.push(line);
     }
+    trackPromise(promise) {
+        const trackedPromise = promise.finally(() => {
+            this.pendingToolPromises.delete(trackedPromise);
+        });
+        this.pendingToolPromises.add(trackedPromise);
+        return trackedPromise;
+    }
+    wrapToolObject(value) {
+        if (typeof value === 'function') {
+            const original = value;
+            const wrapped = (...args) => {
+                const result = original(...args);
+                const isPromiseLike = result !== null &&
+                    typeof result === 'object' &&
+                    typeof result.then === 'function';
+                return isPromiseLike ? this.trackPromise(Promise.resolve(result)) : result;
+            };
+            return wrapped;
+        }
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            const wrappedEntries = Object.entries(value).map(([key, child]) => ([key, this.wrapToolObject(child)]));
+            return Object.fromEntries(wrappedEntries);
+        }
+        return value;
+    }
 }

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,11 +76,19 @@ 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;
         /** Top backlink source paths (max 3) */
         relatedPaths?: string[];
         score: number;
-        /** Symbol kind: 'domain' | 'topic' | 'subtopic' | 'context' | 'archive_stub' */
+        /** Symbol kind: 'domain' | 'topic' | 'subtopic' | 'context' | 'archive_stub' | 'summary' */
         symbolKind?: string;
         /** Resolved hierarchical path in the symbol tree */
         symbolPath?: string;
@@ -223,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,
             });