btca-server 2.0.2 → 2.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "btca-server",
-	"version": "2.0.2",
+	"version": "2.0.4",
 	"description": "BTCA server for answering questions about your codebase using OpenCode AI",
 	"author": "Ben Davis",
 	"license": "MIT",

package/src/agent/agent.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { Effect } from 'effect';
 
 import { createAgentService } from './service.ts';
 import { load as loadConfig } from '../config/index.ts';
@@ -71,10 +72,12 @@ describe('Agent', () => {
 				vfsId
 			};
 
-			const result = await agent.ask({
-				collection,
-				question: 'What number is the answer to life according to the README?'
-			});
+			const result = await Effect.runPromise(
+				agent.ask({
+					collection,
+					question: 'What number is the answer to life according to the README?'
+				})
+			);
 
 			expect(result).toBeDefined();
 			expect(result.answer).toBeDefined();
@@ -102,10 +105,12 @@ describe('Agent', () => {
 				vfsId
 			};
 
-			const { stream, model } = await agent.askStream({
-				collection,
-				question: 'What is the capital of France according to the data file?'
-			});
+			const { stream, model } = await Effect.runPromise(
+				agent.askStream({
+					collection,
+					question: 'What is the capital of France according to the data file?'
+				})
+			);
 
 			expect(model).toBeDefined();
 			expect(model.provider).toBeDefined();
@@ -154,10 +159,12 @@ describe('Agent', () => {
 				vfsId
 			};
 
-			const result = await agent.ask({
-				collection,
-				question: 'What number is the answer according to the README?'
-			});
+			const result = await Effect.runPromise(
+				agent.ask({
+					collection,
+					question: 'What number is the answer according to the README?'
+				})
+			);
 
 			expect(result).toBeDefined();
 			expect(hasVirtualFs(vfsId)).toBe(false);
@@ -200,10 +207,12 @@ describe('Agent', () => {
 				vfsId
 			};
 
-			const { stream } = await agent.askStream({
-				collection,
-				question: 'What is the capital of France according to the README?'
-			});
+			const { stream } = await Effect.runPromise(
+				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

package/src/agent/loop.ts

@@ -57,35 +57,57 @@ export type AgentLoopResult = {
 	events: AgentEvent[];
 };
 
+const BASE_PROMPT = `
+You are btca, an expert research agent. Your job is to answer questions from the user by searching the resources at your disposal.
+
+<personality_and_writing_controls>
+- Persona: an expert professional researcher
+- Channel: internal
+- Emotional register: direct, calm, and concise
+- Formatting: bulleted/numbered lists are good + codeblocks
+- Length: be thorough with your response, don't let it get too long though
+- Default follow-through: don't ask permission to do the research, just do it and answer the question. ask for clarifications + suggest good follow up if needed
+</personality_and_writing_controls>
+
+<parallel_tool_calling>
+- When multiple retrieval or lookup steps are independent, prefer parallel tool calls to reduce wall-clock time.
+- Do not parallelize steps that have prerequisite dependencies or where one result determines the next action.
+- After parallel retrieval, pause to synthesize the results before making more calls.
+- Prefer selective parallelism: parallelize independent evidence gathering, not speculative or redundant tool use.
+</parallel_tool_calling>
+
+<tool_persistence_rules>
+- Use tools whenever they materially improve correctness, completeness, or grounding.
+- Do NOT stop early to save tool calls.
+- Keep calling tools until either:
+	1) the task is complete
+	2) you've hit a doom loop where none of the tools function or something is missing
+- If a tool returns empty/partial results, retry with a different strategy (query, filters, alternate source).
+</tool_persistence_rules>
+
+<completeness_contract>
+- Treat the task as incomplete until you have a complete answer to the user's question that's grounded
+- If any item is blocked by missing data, mark it [blocked] and state exactly what is missing.
+</completeness_contract>
+
+<dig_deeper_nudge>
+- Don't stop at the first plausible answer.
+- Look for second-order issues, edge cases, and missing constraints.
+</dig_deeper_nudge>
+
+<output_contract>
+- Return a thorough answer to the user's question with real code examples
+- Always output in proper markdown format
+- Always include sources for your answer:
+	- For git resources, source links must be full github blob urls
+	- In "Sources", format git citations as markdown links: - [repo/relative/path.ext](https://github.com/.../blob/.../repo/relative/path.ext)".'
+	- For local resources cite local file paths
+	- For npm resources cite the path in the npm package
+</output_contract>
+`;
+
 const buildSystemPrompt = (agentInstructions: string): string =>
-	[
-		'You are btca, an expert documentation search agent.',
-		'Your job is to answer questions by searching through the collection of resources.',
-		'',
-		'You have access to the following tools:',
-		'- read: Read file contents with line numbers',
-		'- grep: Search file contents using regex patterns',
-		'- glob: Find files matching glob patterns',
-		'- list: List directory contents',
-		'',
-		'Guidelines:',
-		'- Ground answers in the loaded resources. Do not rely on unstated prior knowledge.',
-		'- Search efficiently: start with one focused list/glob pass, then read likely files; only expand search when evidence is insufficient.',
-		'- Prefer targeted grep/read over broad repeated scans once candidate files are known.',
-		'- Give clear, unambiguous answers. State assumptions, prerequisites, and important version-sensitive caveats.',
-		'- For implementation/how-to questions, provide complete step-by-step instructions with commands and code snippets.',
-		'- Be concise but thorough in your responses.',
-		'- End every answer with a "Sources" section.',
-		'- For git resources, source links must be full GitHub blob URLs.',
-		'- In "Sources", format git citations as markdown links: "- [repo/relative/path.ext](https://github.com/.../blob/.../repo/relative/path.ext)".',
-		'- Do not use raw URLs as link labels.',
-		'- Do not repeat a URL in parentheses after a link.',
-		'- Do not output sources in "url (url)" format.',
-		'- For local resources, cite local file paths (no GitHub URL required).',
-		'- If you cannot find the answer, say so clearly',
-		'',
-		agentInstructions
-	].join('\n');
+	[BASE_PROMPT, agentInstructions].join('\n');
 
 const createTools = (basePath: string, vfsId?: string) => ({
 	read: tool({

package/src/agent/service.ts

@@ -87,11 +87,7 @@ export class ProviderNotConnectedError extends Error {
 }
 
 export type AgentService = {
-	askStream: (args: { collection: CollectionResult; question: string }) => Promise<{
-		stream: AsyncIterable<AgentEvent>;
-		model: { provider: string; model: string };
-	}>;
-	askStreamEffect: (args: { collection: CollectionResult; question: string }) => Effect.Effect<
+	askStream: (args: { collection: CollectionResult; question: string }) => Effect.Effect<
 		{
 			stream: AsyncIterable<AgentEvent>;
 			model: { provider: string; model: string };
@@ -99,17 +95,12 @@ export type AgentService = {
 		unknown
 	>;
 
-	ask: (args: { collection: CollectionResult; question: string }) => Promise<AgentResult>;
-	askEffect: (args: {
+	ask: (args: {
 		collection: CollectionResult;
 		question: string;
 	}) => Effect.Effect<AgentResult, unknown>;
 
-	listProviders: () => Promise<{
-		all: { id: string; models: Record<string, unknown> }[];
-		connected: string[];
-	}>;
-	listProvidersEffect: () => Effect.Effect<
+	listProviders: () => Effect.Effect<
 		{
 			all: { id: string; models: Record<string, unknown> }[];
 			connected: string[];
@@ -121,36 +112,39 @@ export type AgentService = {
 export type Service = AgentService;
 
 export const createAgentService = (config: ConfigServiceShape): AgentService => {
-	const cleanupCollection = (collection: CollectionResult) =>
-		Effect.promise(async () => {
-			if (collection.vfsId) {
-				disposeVirtualFs(collection.vfsId);
-				clearVirtualCollectionMetadata(collection.vfsId);
-			}
-			try {
-				await collection.cleanup?.();
-			} catch {
-				return;
-			}
-		});
+	const cleanupCollection = async (collection: CollectionResult) => {
+		if (collection.vfsId) {
+			disposeVirtualFs(collection.vfsId);
+			clearVirtualCollectionMetadata(collection.vfsId);
+		}
+		try {
+			await collection.cleanup?.();
+		} catch {
+			return;
+		}
+	};
 
-	const ensureProviderConnected = Effect.fn(function* () {
-		const isAuthed = yield* Effect.tryPromise(() => isAuthenticated(config.provider));
+	const ensureProviderConnected = async () => {
+		const isAuthed = await isAuthenticated(config.provider);
 		const requiresAuth = config.provider !== 'opencode' && config.provider !== 'openai-compat';
 		if (isAuthed || !requiresAuth) return;
-		const authenticated = yield* Effect.tryPromise(() => getAuthenticatedProviders());
-		yield* Effect.fail(
-			new ProviderNotConnectedError({
-				providerId: config.provider,
-				connectedProviders: authenticated
-			})
-		);
-	});
+		const authenticated = await getAuthenticatedProviders();
+		throw new ProviderNotConnectedError({
+			providerId: config.provider,
+			connectedProviders: authenticated
+		});
+	};
 
 	/**
 	 * Ask a question and stream the response using the new AI SDK loop
 	 */
-	const askStream: AgentService['askStream'] = async ({ collection, question }) => {
+	const askStreamImpl = async ({
+		collection,
+		question
+	}: {
+		collection: CollectionResult;
+		question: string;
+	}) => {
 		metricsInfo('agent.ask.start', {
 			provider: config.provider,
 			model: config.model,
@@ -158,9 +152,9 @@ export const createAgentService = (config: ConfigServiceShape): AgentService =>
 		});
 
 		try {
-			await Effect.runPromise(ensureProviderConnected());
+			await ensureProviderConnected();
 		} catch (error) {
-			await Effect.runPromise(cleanupCollection(collection));
+			await cleanupCollection(collection);
 			throw error;
 		}
 
@@ -181,7 +175,7 @@ export const createAgentService = (config: ConfigServiceShape): AgentService =>
 					yield event;
 				}
 			} finally {
-				await Effect.runPromise(cleanupCollection(collection));
+				await cleanupCollection(collection);
 			}
 		})();
 
@@ -194,103 +188,99 @@ export const createAgentService = (config: ConfigServiceShape): AgentService =>
 	/**
 	 * Ask a question and return the complete response
 	 */
-	const ask: AgentService['ask'] = async ({ collection, question }) => {
-		return Effect.runPromise(
-			Effect.gen(function* () {
-				metricsInfo('agent.ask.start', {
-					provider: config.provider,
-					model: config.model,
-					questionLength: question.length
-				});
+	const askImpl = async ({
+		collection,
+		question
+	}: {
+		collection: CollectionResult;
+		question: string;
+	}) => {
+		try {
+			metricsInfo('agent.ask.start', {
+				provider: config.provider,
+				model: config.model,
+				questionLength: question.length
+			});
 
-				yield* ensureProviderConnected();
+			await ensureProviderConnected();
 
-				const result = yield* Effect.tryPromise({
-					try: () =>
-						runAgentLoop({
-							providerId: config.provider,
-							modelId: config.model,
-							maxSteps: config.maxSteps,
-							collectionPath: collection.path,
-							vfsId: collection.vfsId,
-							agentInstructions: collection.agentInstructions,
-							question,
-							providerOptions: config.getProviderOptions(config.provider)
-						}),
-					catch: (cause) =>
-						new AgentError({
-							message: getErrorMessage(cause),
-							hint:
-								getErrorHint(cause) ??
-								'This may be a temporary issue. Try running the command again.',
-							cause
-						})
+			let result: Awaited<ReturnType<typeof runAgentLoop>>;
+			try {
+				result = await runAgentLoop({
+					providerId: config.provider,
+					modelId: config.model,
+					maxSteps: config.maxSteps,
+					collectionPath: collection.path,
+					vfsId: collection.vfsId,
+					agentInstructions: collection.agentInstructions,
+					question,
+					providerOptions: config.getProviderOptions(config.provider)
 				});
-
-				metricsInfo('agent.ask.complete', {
-					provider: config.provider,
-					model: config.model,
-					answerLength: result.answer.length,
-					eventCount: result.events.length
+			} catch (cause) {
+				throw new AgentError({
+					message: getErrorMessage(cause),
+					hint:
+						getErrorHint(cause) ?? 'This may be a temporary issue. Try running the command again.',
+					cause
 				});
+			}
 
-				return {
-					answer: result.answer,
-					model: result.model,
-					events: result.events
-				};
-			}).pipe(
-				Effect.tapError((error) =>
-					Effect.sync(() => metricsError('agent.ask.error', { error: metricsErrorInfo(error) }))
-				),
-				Effect.ensuring(cleanupCollection(collection))
-			)
-		);
+			metricsInfo('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
+			};
+		} catch (error) {
+			metricsError('agent.ask.error', { error: metricsErrorInfo(error) });
+			throw error;
+		} finally {
+			await cleanupCollection(collection);
+		}
 	};
 
 	/**
 	 * List available providers using local auth data
 	 */
-	const listProviders: AgentService['listProviders'] = async () => {
-		return Effect.runPromise(
-			Effect.gen(function* () {
-				const supportedProviders = getSupportedProviders();
-				const authenticatedProviders = yield* Effect.tryPromise(() => getAuthenticatedProviders());
-				const all = supportedProviders.map((id) => ({
-					id,
-					models: {} as Record<string, unknown>
-				}));
+	const listProvidersImpl = async () => {
+		const supportedProviders = getSupportedProviders();
+		const authenticatedProviders = await getAuthenticatedProviders();
+		const all = supportedProviders.map((id) => ({
+			id,
+			models: {} as Record<string, unknown>
+		}));
 
-				return {
-					all,
-					connected: authenticatedProviders
-				};
-			})
-		);
+		return {
+			all,
+			connected: authenticatedProviders
+		};
 	};
 
-	const askStreamEffect: AgentService['askStreamEffect'] = (args) =>
+	const askStream: AgentService['askStream'] = (args) =>
 		Effect.tryPromise({
-			try: () => askStream(args),
+			try: () => askStreamImpl(args),
 			catch: (cause) => cause
 		});
-	const askEffect: AgentService['askEffect'] = (args) =>
+	const ask: AgentService['ask'] = (args) =>
 		Effect.tryPromise({
-			try: () => ask(args),
+			try: () => askImpl(args),
 			catch: (cause) => cause
 		});
-	const listProvidersEffect: AgentService['listProvidersEffect'] = () =>
+	const listProviders: AgentService['listProviders'] = () =>
 		Effect.tryPromise({
-			try: () => listProviders(),
+			try: () => listProvidersImpl(),
 			catch: (cause) => cause
 		});
 
 	return {
 		askStream,
 		ask,
-		listProviders,
-		askStreamEffect,
-		askEffect,
-		listProvidersEffect
+		listProviders
 	};
 };