btca-server 1.0.63 → 1.0.71

package/README.md

@@ -140,7 +140,6 @@ Example config.toml:
 provider = "anthropic"
 model = "claude-3-7-sonnet-20250219"
 resourcesDirectory = "~/.btca/resources"
-collectionsDirectory = "~/.btca/collections"
 
 [[resources]]
 type = "local"
@@ -158,6 +157,10 @@ branch = "main"
 
 - `PORT`: Server port (default: 8080)
 - `OPENCODE_API_KEY`: OpenCode AI API key (required)
+- `OPENROUTER_API_KEY`: OpenRouter API key (required when provider is `openrouter`)
+- `OPENROUTER_BASE_URL`: Override OpenRouter base URL (optional)
+- `OPENROUTER_HTTP_REFERER`: Optional OpenRouter header for rankings
+- `OPENROUTER_X_TITLE`: Optional OpenRouter header for rankings
 
 ## TypeScript Types
 

package/package.json

@@ -1,12 +1,12 @@
 {
 	"name": "btca-server",
-	"version": "1.0.63",
+	"version": "1.0.71",
 	"description": "BTCA server for answering questions about your codebase using OpenCode AI",
 	"author": "Ben Davis",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/bmdavis419/better-context",
+		"url": "git+https://github.com/davis7dotsh/better-context.git",
 		"directory": "apps/server"
 	},
 	"keywords": [
@@ -69,7 +69,9 @@
 		"@btca/shared": "workspace:*",
 		"@opencode-ai/sdk": "^1.1.28",
 		"ai": "^6.0.49",
+		"better-result": "^2.6.0",
 		"hono": "^4.7.11",
+		"just-bash": "^2.7.0",
 		"opencode-ai": "^1.1.36",
 		"zod": "^3.25.76"
 	}

package/src/agent/agent.test.ts

@@ -6,6 +6,11 @@ import os from 'node:os';
 import { Agent } from './service.ts';
 import { Config } from '../config/index.ts';
 import type { CollectionResult } from '../collections/types.ts';
+import {
+	getVirtualCollectionMetadata,
+	setVirtualCollectionMetadata
+} from '../collections/virtual-metadata.ts';
+import { VirtualFs } from '../vfs/virtual-fs.ts';
 
 describe('Agent', () => {
 	let testDir: string;
@@ -41,21 +46,22 @@ describe('Agent', () => {
 	// Run with: BTCA_RUN_INTEGRATION_TESTS=1 bun test
 	describe.skipIf(!process.env.BTCA_RUN_INTEGRATION_TESTS)('Agent.ask (integration)', () => {
 		it('asks a question and receives an answer', async () => {
-			// Create a simple collection directory with a test file
-			const collectionPath = path.join(testDir, 'test-collection');
-			await fs.mkdir(collectionPath, { recursive: true });
-			await fs.writeFile(
-				path.join(collectionPath, 'README.md'),
-				'# Test Documentation\n\nThis is a test file. The answer to life is 42.'
-			);
-
 			process.chdir(testDir);
 			const config = await Config.load();
 			const agent = Agent.create(config);
 
+			const vfsId = VirtualFs.create();
+			await VirtualFs.mkdir('/', { recursive: true }, vfsId);
+			await VirtualFs.writeFile(
+				'/README.md',
+				'# Test Documentation\n\nThis is a test file. The answer to life is 42.',
+				vfsId
+			);
+
 			const collection: CollectionResult = {
-				path: collectionPath,
-				agentInstructions: 'This is a test collection with a README file.'
+				path: '/',
+				agentInstructions: 'This is a test collection with a README file.',
+				vfsId
 			};
 
 			const result = await agent.ask({
@@ -75,17 +81,18 @@ describe('Agent', () => {
 		}, 60000);
 
 		it('handles askStream and receives events', async () => {
-			const collectionPath = path.join(testDir, 'stream-collection');
-			await fs.mkdir(collectionPath, { recursive: true });
-			await fs.writeFile(path.join(collectionPath, 'data.txt'), 'The capital of France is Paris.');
-
 			process.chdir(testDir);
 			const config = await Config.load();
 			const agent = Agent.create(config);
 
+			const vfsId = VirtualFs.create();
+			await VirtualFs.mkdir('/', { recursive: true }, vfsId);
+			await VirtualFs.writeFile('/data.txt', 'The capital of France is Paris.', vfsId);
+
 			const collection: CollectionResult = {
-				path: collectionPath,
-				agentInstructions: 'Simple test collection.'
+				path: '/',
+				agentInstructions: 'Simple test collection.',
+				vfsId
 			};
 
 			const { stream, model } = await agent.askStream({
@@ -107,5 +114,96 @@ describe('Agent', () => {
 			const textEvents = events.filter((e) => e.type === 'text-delta');
 			expect(textEvents.length).toBeGreaterThan(0);
 		}, 60000);
+
+		it('cleans up virtual collections after ask', async () => {
+			process.chdir(testDir);
+			const config = await Config.load();
+			const agent = Agent.create(config);
+
+			const vfsId = VirtualFs.create();
+			await VirtualFs.mkdir('/', { recursive: true }, vfsId);
+			await VirtualFs.mkdir('/docs', { recursive: true }, vfsId);
+			await VirtualFs.writeFile('/docs/README.md', 'Virtual README\nThe answer is 42.', vfsId);
+
+			setVirtualCollectionMetadata({
+				vfsId,
+				collectionKey: 'virtual-test',
+				createdAt: new Date().toISOString(),
+				resources: [
+					{
+						name: 'docs',
+						fsName: 'docs',
+						type: 'local',
+						path: '/docs',
+						repoSubPaths: [],
+						loadedAt: new Date().toISOString()
+					}
+				]
+			});
+
+			const collection: CollectionResult = {
+				path: '/',
+				agentInstructions: 'This is a virtual collection with a README file.',
+				vfsId
+			};
+
+			const result = await agent.ask({
+				collection,
+				question: 'What number is the answer according to the README?'
+			});
+
+			expect(result).toBeDefined();
+			expect(VirtualFs.has(vfsId)).toBe(false);
+			expect(getVirtualCollectionMetadata(vfsId)).toBeUndefined();
+		}, 60000);
+
+		it('cleans up virtual collections after askStream', async () => {
+			process.chdir(testDir);
+			const config = await Config.load();
+			const agent = Agent.create(config);
+
+			const vfsId = VirtualFs.create();
+			await VirtualFs.mkdir('/', { recursive: true }, vfsId);
+			await VirtualFs.mkdir('/docs', { recursive: true }, vfsId);
+			await VirtualFs.writeFile(
+				'/docs/README.md',
+				'Virtual README\nThe capital of France is Paris.',
+				vfsId
+			);
+
+			setVirtualCollectionMetadata({
+				vfsId,
+				collectionKey: 'virtual-stream-test',
+				createdAt: new Date().toISOString(),
+				resources: [
+					{
+						name: 'docs',
+						fsName: 'docs',
+						type: 'local',
+						path: '/docs',
+						repoSubPaths: [],
+						loadedAt: new Date().toISOString()
+					}
+				]
+			});
+
+			const collection: CollectionResult = {
+				path: '/',
+				agentInstructions: 'This is a virtual collection with a README file.',
+				vfsId
+			};
+
+			const { stream } = await agent.askStream({
+				collection,
+				question: 'What is the capital of France according to the README?'
+			});
+
+			for await (const _event of stream) {
+				// drain stream to trigger cleanup
+			}
+
+			expect(VirtualFs.has(vfsId)).toBe(false);
+			expect(getVirtualCollectionMetadata(vfsId)).toBeUndefined();
+		}, 60000);
 	});
 });

package/src/agent/loop.ts

@@ -25,6 +25,7 @@ export namespace AgentLoop {
 		providerId: string;
 		modelId: string;
 		collectionPath: string;
+		vfsId?: string;
 		agentInstructions: string;
 		question: string;
 		maxSteps?: number;
@@ -65,13 +66,13 @@ export namespace AgentLoop {
 	/**
 	 * Create the tools for the agent
 	 */
-	function createTools(basePath: string) {
+	function createTools(basePath: string, vfsId?: string) {
 		return {
 			read: tool({
 				description: 'Read the contents of a file. Returns the file contents with line numbers.',
 				inputSchema: ReadTool.Parameters,
 				execute: async (params: ReadTool.ParametersType) => {
-					const result = await ReadTool.execute(params, { basePath });
+					const result = await ReadTool.execute(params, { basePath, vfsId });
 					return result.output;
 				}
 			}),
@@ -81,7 +82,7 @@ export namespace AgentLoop {
 					'Search for a regex pattern in file contents. Returns matching lines with file paths and line numbers.',
 				inputSchema: GrepTool.Parameters,
 				execute: async (params: GrepTool.ParametersType) => {
-					const result = await GrepTool.execute(params, { basePath });
+					const result = await GrepTool.execute(params, { basePath, vfsId });
 					return result.output;
 				}
 			}),
@@ -91,7 +92,7 @@ export namespace AgentLoop {
 					'Find files matching a glob pattern (e.g. "**/*.ts", "src/**/*.js"). Returns a list of matching file paths sorted by modification time.',
 				inputSchema: GlobTool.Parameters,
 				execute: async (params: GlobTool.ParametersType) => {
-					const result = await GlobTool.execute(params, { basePath });
+					const result = await GlobTool.execute(params, { basePath, vfsId });
 					return result.output;
 				}
 			}),
@@ -101,7 +102,7 @@ export namespace AgentLoop {
 					'List the contents of a directory. Returns files and subdirectories with their types.',
 				inputSchema: ListTool.Parameters,
 				execute: async (params: ListTool.ParametersType) => {
-					const result = await ListTool.execute(params, { basePath });
+					const result = await ListTool.execute(params, { basePath, vfsId });
 					return result.output;
 				}
 			})
@@ -111,8 +112,8 @@ export namespace AgentLoop {
 	/**
 	 * Get initial context by listing the collection directory
 	 */
-	async function getInitialContext(collectionPath: string): Promise<string> {
-		const result = await ListTool.execute({ path: '.' }, { basePath: collectionPath });
+	async function getInitialContext(collectionPath: string, vfsId?: string) {
+		const result = await ListTool.execute({ path: '.' }, { basePath: collectionPath, vfsId });
 		return `Collection contents:\n${result.output}`;
 	}
 
@@ -124,6 +125,7 @@ export namespace AgentLoop {
 			providerId,
 			modelId,
 			collectionPath,
+			vfsId,
 			agentInstructions,
 			question,
 			maxSteps = 40
@@ -133,7 +135,7 @@ export namespace AgentLoop {
 		const model = await Model.getModel(providerId, modelId);
 
 		// Get initial context
-		const initialContext = await getInitialContext(collectionPath);
+		const initialContext = await getInitialContext(collectionPath, vfsId);
 
 		// Build messages
 		const messages: ModelMessage[] = [
@@ -144,7 +146,7 @@ export namespace AgentLoop {
 		];
 
 		// Create tools
-		const tools = createTools(collectionPath);
+		const tools = createTools(collectionPath, vfsId);
 
 		// Collect events
 		const events: AgentEvent[] = [];
@@ -218,6 +220,7 @@ export namespace AgentLoop {
 			providerId,
 			modelId,
 			collectionPath,
+			vfsId,
 			agentInstructions,
 			question,
 			maxSteps = 40
@@ -227,7 +230,7 @@ export namespace AgentLoop {
 		const model = await Model.getModel(providerId, modelId);
 
 		// Get initial context
-		const initialContext = await getInitialContext(collectionPath);
+		const initialContext = await getInitialContext(collectionPath, vfsId);
 
 		// Build messages
 		const messages: ModelMessage[] = [
@@ -238,7 +241,7 @@ export namespace AgentLoop {
 		];
 
 		// Create tools
-		const tools = createTools(collectionPath);
+		const tools = createTools(collectionPath, vfsId);
 
 		// Run streamText with tool execution
 		const result = streamText({

package/src/agent/service.ts

@@ -8,12 +8,15 @@ import {
 	type Config as OpenCodeConfig,
 	type OpencodeClient
 } from '@opencode-ai/sdk';
+import { Result } from 'better-result';
 
 import { Config } from '../config/index.ts';
 import { CommonHints, type TaggedErrorOptions } from '../errors.ts';
 import { Metrics } from '../metrics/index.ts';
 import { Auth, getSupportedProviders } from '../providers/index.ts';
 import type { CollectionResult } from '../collections/types.ts';
+import { clearVirtualCollectionMetadata } from '../collections/virtual-metadata.ts';
+import { VirtualFs } from '../vfs/virtual-fs.ts';
 import type { AgentResult, TrackedInstance, InstanceInfo } from './types.ts';
 import { AgentLoop } from './loop.ts';
 
@@ -110,10 +113,14 @@ export namespace Agent {
 			super(`Provider "${args.providerId}" is not connected`);
 			this.providerId = args.providerId;
 			this.connectedProviders = args.connectedProviders;
+			const baseHint =
+				args.providerId === 'openrouter'
+					? 'Set OPENROUTER_API_KEY to authenticate OpenRouter.'
+					: CommonHints.RUN_AUTH;
 			if (args.connectedProviders.length > 0) {
-				this.hint = `${CommonHints.RUN_AUTH} Connected providers: ${args.connectedProviders.join(', ')}.`;
+				this.hint = `${baseHint} Connected providers: ${args.connectedProviders.join(', ')}.`;
 			} else {
-				this.hint = `${CommonHints.RUN_AUTH} No providers are currently connected.`;
+				this.hint = `${baseHint} No providers are currently connected.`;
 			}
 		}
 	}
@@ -226,11 +233,11 @@ export namespace Agent {
 		server: { close(): void; url: string };
 		baseUrl: string;
 	}> => {
-		const maxAttempts = 10;
-		for (let attempt = 0; attempt < maxAttempts; attempt++) {
-			const port = Math.floor(Math.random() * 3000) + 3000;
-			const created = await createOpencode({ port, config: args.ocConfig }).catch(
-				(err: unknown) => {
+		const tryCreateOpencode = async (port: number) => {
+			const result = await Result.tryPromise(() => createOpencode({ port, config: args.ocConfig }));
+			return result.match({
+				ok: (created) => created,
+				err: (err) => {
 					const error = err as { cause?: Error };
 					if (error?.cause instanceof Error && error.cause.stack?.includes('port')) return null;
 					throw new AgentError({
@@ -239,7 +246,13 @@ export namespace Agent {
 						cause: err
 					});
 				}
-			);
+			});
+		};
+
+		const maxAttempts = 10;
+		for (let attempt = 0; attempt < maxAttempts; attempt++) {
+			const port = Math.floor(Math.random() * 3000) + 3000;
+			const created = await tryCreateOpencode(port);
 
 			if (created) {
 				const baseUrl = `http://localhost:${port}`;
@@ -272,10 +285,17 @@ export namespace Agent {
 				questionLength: question.length
 			});
 
+			const cleanup = () => {
+				if (!collection.vfsId) return;
+				VirtualFs.dispose(collection.vfsId);
+				clearVirtualCollectionMetadata(collection.vfsId);
+			};
+
 			// Validate provider is authenticated
 			const isAuthed = await Auth.isAuthenticated(config.provider);
 			if (!isAuthed && config.provider !== 'opencode') {
 				const authenticated = await Auth.getAuthenticatedProviders();
+				cleanup();
 				throw new ProviderNotConnectedError({
 					providerId: config.provider,
 					connectedProviders: authenticated
@@ -283,13 +303,23 @@ export namespace Agent {
 			}
 
 			// Create a generator that wraps the AgentLoop stream
-			const eventGenerator = AgentLoop.stream({
-				providerId: config.provider,
-				modelId: config.model,
-				collectionPath: collection.path,
-				agentInstructions: collection.agentInstructions,
-				question
-			});
+			const eventGenerator = (async function* () {
+				try {
+					const stream = AgentLoop.stream({
+						providerId: config.provider,
+						modelId: config.model,
+						collectionPath: collection.path,
+						vfsId: collection.vfsId,
+						agentInstructions: collection.agentInstructions,
+						question
+					});
+					for await (const event of stream) {
+						yield event;
+					}
+				} finally {
+					cleanup();
+				}
+			})();
 
 			return {
 				stream: eventGenerator,
@@ -307,45 +337,60 @@ export namespace Agent {
 				questionLength: question.length
 			});
 
+			const cleanup = () => {
+				if (!collection.vfsId) return;
+				VirtualFs.dispose(collection.vfsId);
+				clearVirtualCollectionMetadata(collection.vfsId);
+			};
+
 			// Validate provider is authenticated
 			const isAuthed = await Auth.isAuthenticated(config.provider);
 			if (!isAuthed && config.provider !== 'opencode') {
 				const authenticated = await Auth.getAuthenticatedProviders();
+				cleanup();
 				throw new ProviderNotConnectedError({
 					providerId: config.provider,
 					connectedProviders: authenticated
 				});
 			}
 
-			try {
-				const result = await AgentLoop.run({
+			const runResult = await Result.tryPromise(() =>
+				AgentLoop.run({
 					providerId: config.provider,
 					modelId: config.model,
 					collectionPath: collection.path,
+					vfsId: collection.vfsId,
 					agentInstructions: collection.agentInstructions,
 					question
-				});
+				})
+			);
 
-				Metrics.info('agent.ask.complete', {
-					provider: config.provider,
-					model: config.model,
-					answerLength: result.answer.length,
-					eventCount: result.events.length
-				});
+			cleanup();
 
-				return {
-					answer: result.answer,
-					model: result.model,
-					events: result.events
-				};
-			} catch (error) {
-				Metrics.error('agent.ask.error', { error: Metrics.errorInfo(error) });
-				throw new AgentError({
-					message: 'Failed to get response from AI',
-					hint: 'This may be a temporary issue. Try running the command again.',
-					cause: error
-				});
-			}
+			return runResult.match({
+				ok: (result) => {
+					Metrics.info('agent.ask.complete', {
+						provider: config.provider,
+						model: config.model,
+						answerLength: result.answer.length,
+						eventCount: result.events.length
+					});
+
+					return {
+						answer: result.answer,
+						model: result.model,
+						events: result.events
+					};
+				},
+				err: (error) => {
+					Metrics.error('agent.ask.error', { error: Metrics.errorInfo(error) });
+					throw new AgentError({
+						message: 'Failed to get response from AI',
+						hint: 'This may be a temporary issue. Try running the command again.',
+						cause: error
+					});
+				}
+			});
 		};
 
 		/**
@@ -353,31 +398,11 @@ export namespace Agent {
 		 * This still spawns a full OpenCode instance for clients that need it
 		 */
 		const getOpencodeInstance: Service['getOpencodeInstance'] = async ({ collection }) => {
-			const ocConfig = buildOpenCodeConfig({
-				agentInstructions: collection.agentInstructions,
-				providerId: config.provider,
-				providerTimeoutMs: config.providerTimeoutMs
-			});
-			const { server, baseUrl } = await createOpencodeInstance({
-				collectionPath: collection.path,
-				ocConfig
-			});
-
-			// Register the instance for lifecycle management
-			const instanceId = generateInstanceId();
-			registerInstance(instanceId, server, collection.path);
-
-			Metrics.info('agent.oc.instance.ready', {
-				baseUrl,
-				collectionPath: collection.path,
-				instanceId
+			throw new AgentError({
+				message: 'OpenCode instance not available',
+				hint: 'BTCA uses virtual collections only. Use the btca ask/stream APIs instead.',
+				cause: new Error('Virtual collections are not compatible with filesystem-based OpenCode')
 			});
-
-			return {
-				url: baseUrl,
-				model: { provider: config.provider, model: config.model },
-				instanceId
-			};
 		};
 
 		/**
@@ -413,20 +438,23 @@ export namespace Agent {
 				return { closed: false };
 			}
 
-			try {
-				instance.server.close();
-				unregisterInstance(instanceId);
-				Metrics.info('agent.instance.closed', { instanceId });
-				return { closed: true };
-			} catch (cause) {
-				Metrics.error('agent.instance.close.err', {
-					instanceId,
-					error: Metrics.errorInfo(cause)
-				});
-				// Still remove from registry even if close failed
-				unregisterInstance(instanceId);
-				return { closed: true };
-			}
+			const closeResult = Result.try(() => instance.server.close());
+			return closeResult.match({
+				ok: () => {
+					unregisterInstance(instanceId);
+					Metrics.info('agent.instance.closed', { instanceId });
+					return { closed: true };
+				},
+				err: (cause) => {
+					Metrics.error('agent.instance.close.err', {
+						instanceId,
+						error: Metrics.errorInfo(cause)
+					});
+					// Still remove from registry even if close failed
+					unregisterInstance(instanceId);
+					return { closed: true };
+				}
+			});
 		};
 
 		/**
@@ -450,17 +478,20 @@ export namespace Agent {
 			let closed = 0;
 
 			for (const instance of instances) {
-				try {
-					instance.server.close();
-					closed++;
-				} catch (cause) {
-					Metrics.error('agent.instance.close.err', {
-						instanceId: instance.id,
-						error: Metrics.errorInfo(cause)
-					});
-					// Count as closed even if there was an error
-					closed++;
-				}
+				const closeResult = Result.try(() => instance.server.close());
+				closeResult.match({
+					ok: () => {
+						closed++;
+					},
+					err: (cause) => {
+						Metrics.error('agent.instance.close.err', {
+							instanceId: instance.id,
+							error: Metrics.errorInfo(cause)
+						});
+						// Count as closed even if there was an error
+						closed++;
+					}
+				});
 			}
 
 			instanceRegistry.clear();