btca-server 2.0.3 → 2.0.4

package/package.json

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

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/collections/service.test.ts

@@ -4,31 +4,45 @@ import os from 'node:os';
 import path from 'node:path';
 
 import type { ConfigService } from '../config/index.ts';
+import type { ResourceDefinition } from '../resources/schema.ts';
 import type { ResourcesService } from '../resources/service.ts';
+import type { BtcaFsResource } from '../resources/types.ts';
 import { createCollectionsService } from './service.ts';
 import { disposeVirtualFs, existsInVirtualFs } from '../vfs/virtual-fs.ts';
 
-const createLocalResource = (name: string, resourcePath: string) => ({
+const createFsResource = ({
+	name,
+	resourcePath,
+	type = 'local',
+	repoSubPaths = [],
+	specialAgentInstructions = ''
+}: {
+	name: string;
+	resourcePath: string;
+	type?: BtcaFsResource['type'];
+	repoSubPaths?: readonly string[];
+	specialAgentInstructions?: string;
+}) => ({
 	_tag: 'fs-based' as const,
 	name,
 	fsName: name,
-	type: 'local' as const,
-	repoSubPaths: [],
-	specialAgentInstructions: '',
+	type,
+	repoSubPaths,
+	specialAgentInstructions,
 	getAbsoluteDirectoryPath: async () => resourcePath
 });
 
-const createConfigMock = () =>
+const createConfigMock = (definitions: Record<string, ResourceDefinition> = {}) =>
 	({
-		getResource: () => undefined
+		getResource: (name: string) => definitions[name]
 	}) as unknown as ConfigService;
 
-const createResourcesMock = (resourcePath: string) =>
+const createResourcesMock = (loadPromise: ResourcesService['loadPromise']) =>
 	({
 		load: () => {
 			throw new Error('Not implemented in test');
 		},
-		loadPromise: async () => createLocalResource('repo', resourcePath)
+		loadPromise
 	}) as unknown as ResourcesService;
 
 const runGit = (cwd: string, args: string[]) => {
@@ -55,7 +69,7 @@ describe('createCollectionsService', () => {
 		const resourcePath = await fs.mkdtemp(path.join(os.tmpdir(), 'btca-collections-git-'));
 		const collections = createCollectionsService({
 			config: createConfigMock(),
-			resources: createResourcesMock(resourcePath)
+			resources: createResourcesMock(async () => createFsResource({ name: 'repo', resourcePath }))
 		});
 
 		try {
@@ -89,7 +103,7 @@ describe('createCollectionsService', () => {
 		const resourcePath = await fs.mkdtemp(path.join(os.tmpdir(), 'btca-collections-local-'));
 		const collections = createCollectionsService({
 			config: createConfigMock(),
-			resources: createResourcesMock(resourcePath)
+			resources: createResourcesMock(async () => createFsResource({ name: 'repo', resourcePath }))
 		});
 
 		try {
@@ -109,6 +123,129 @@ describe('createCollectionsService', () => {
 					false
 				);
 				expect(await existsInVirtualFs('/repo/dist/bundle.js', collection.vfsId)).toBe(false);
+				expect(collection.agentInstructions).not.toContain('<special_notes>');
+			} finally {
+				await cleanupCollection(collection);
+			}
+		} finally {
+			await fs.rm(resourcePath, { recursive: true, force: true });
+		}
+	});
+
+	it('includes git citation metadata in agent instructions', async () => {
+		const resourcePath = await fs.mkdtemp(path.join(os.tmpdir(), 'btca-collections-git-meta-'));
+		const collections = createCollectionsService({
+			config: createConfigMock({
+				docs: {
+					type: 'git',
+					name: 'docs',
+					url: 'https://github.com/example/repo.git',
+					branch: 'main',
+					searchPath: 'guides',
+					specialNotes: 'Prefer the guides folder.'
+				}
+			}),
+			resources: createResourcesMock(async () =>
+				createFsResource({
+					name: 'docs',
+					resourcePath,
+					type: 'git',
+					repoSubPaths: ['guides'],
+					specialAgentInstructions: 'Prefer the guides folder.'
+				})
+			)
+		});
+
+		try {
+			await fs.writeFile(path.join(resourcePath, 'README.md'), 'hello\n');
+			runGit(resourcePath, ['init', '-q']);
+			runGit(resourcePath, ['config', 'user.email', 'test@example.com']);
+			runGit(resourcePath, ['config', 'user.name', 'BTCA Test']);
+			runGit(resourcePath, ['add', 'README.md']);
+			runGit(resourcePath, ['commit', '-m', 'init']);
+
+			const collection = await collections.loadPromise({ resourceNames: ['docs'] });
+
+			try {
+				expect(collection.agentInstructions).toContain(
+					'<repo_url>https://github.com/example/repo</repo_url>'
+				);
+				expect(collection.agentInstructions).toContain('<repo_branch>main</repo_branch>');
+				expect(collection.agentInstructions).toContain(
+					'<github_blob_prefix>https://github.com/example/repo/blob/main</github_blob_prefix>'
+				);
+				expect(collection.agentInstructions).toContain(
+					'<citation_rule>Convert virtual paths under ./docs/ to repo-relative paths, then encode each path segment for GitHub URLs.</citation_rule>'
+				);
+				expect(collection.agentInstructions).toContain('<path>./docs/guides</path>');
+				expect(collection.agentInstructions).toContain('<repo_commit>');
+				expect(collection.agentInstructions).toContain(
+					'<special_notes>Prefer the guides folder.</special_notes>'
+				);
+			} finally {
+				await cleanupCollection(collection);
+			}
+		} finally {
+			await fs.rm(resourcePath, { recursive: true, force: true });
+		}
+	});
+
+	it('includes npm citation metadata in agent instructions', async () => {
+		const resourcePath = await fs.mkdtemp(path.join(os.tmpdir(), 'btca-collections-npm-meta-'));
+		const collections = createCollectionsService({
+			config: createConfigMock({
+				react: {
+					type: 'npm',
+					name: 'react',
+					package: 'react',
+					version: '19.0.0',
+					specialNotes: 'Use package docs.'
+				}
+			}),
+			resources: createResourcesMock(async () =>
+				createFsResource({
+					name: 'react',
+					resourcePath,
+					type: 'npm',
+					specialAgentInstructions: 'Use package docs.'
+				})
+			)
+		});
+
+		try {
+			await fs.writeFile(
+				path.join(resourcePath, '.btca-npm-meta.json'),
+				JSON.stringify({
+					packageName: 'react',
+					resolvedVersion: '19.0.0',
+					packageUrl: 'https://www.npmjs.com/package/react'
+				})
+			);
+			await fs.writeFile(path.join(resourcePath, 'README.md'), 'react docs\n');
+
+			const collection = await collections.loadPromise({ resourceNames: ['react'] });
+
+			try {
+				expect(collection.agentInstructions).toContain('<npm_package>react</npm_package>');
+				expect(collection.agentInstructions).toContain('<npm_version>19.0.0</npm_version>');
+				expect(collection.agentInstructions).toContain(
+					'<npm_url>https://www.npmjs.com/package/react</npm_url>'
+				);
+				expect(collection.agentInstructions).toContain(
+					'<npm_citation_alias>npm:react@19.0.0</npm_citation_alias>'
+				);
+				expect(collection.agentInstructions).toContain(
+					'<npm_file_url_prefix>https://unpkg.com/react@19.0.0</npm_file_url_prefix>'
+				);
+				expect(collection.agentInstructions).toContain(
+					'<citation_rule>In Sources, cite npm files using npm:react@19.0.0/&lt;file&gt; and link them to https://unpkg.com/react@19.0.0/&lt;file&gt;. Do not cite encoded virtual folder names.</citation_rule>'
+				);
+				expect(collection.agentInstructions).toContain(
+					'<citation_example>https://unpkg.com/react@19.0.0/package.json</citation_example>'
+				);
+				expect(collection.agentInstructions).toContain(
+					'<special_notes>Use package docs.</special_notes>'
+				);
 			} finally {
 				await cleanupCollection(collection);
 			}

package/src/collections/service.ts

@@ -36,56 +36,110 @@ export type CollectionsService = {
 	}) => Promise<CollectionResult>;
 };
 
-const encodePathSegments = (value: string) => value.split('/').map(encodeURIComponent).join('/');
+const escapeXml = (value: string) =>
+	value
+		.replaceAll('&', '&amp;')
+		.replaceAll('<', '&lt;')
+		.replaceAll('>', '&gt;')
+		.replaceAll('"', '&quot;')
+		.replaceAll("'", '&apos;');
+
+const getResourceTypeLabel = (resource: BtcaFsResource) => {
+	if (resource.type === 'git') return 'git repo';
+	if (resource.type === 'npm') return 'npm package';
+	return 'local directory';
+};
 
 const trimGitSuffix = (url: string) => url.replace(/\.git$/u, '').replace(/\/+$/u, '');
+
+const encodePathSegments = (value: string) => value.split('/').map(encodeURIComponent).join('/');
+
+const xmlLine = (tag: string, value?: string) =>
+	value ? `\t\t<${tag}>${escapeXml(value)}</${tag}>` : '';
+
+const xmlPathBlock = (tag: string, values: readonly string[], prefix = '') =>
+	values.length === 0
+		? ''
+		: [
+				`\t\t<${tag}>`,
+				...values.map((value) => `\t\t\t<path>${escapeXml(`${prefix}${value}`)}</path>`),
+				`\t\t</${tag}>`
+			].join('\n');
+
 const getNpmCitationAlias = (metadata?: VirtualResourceMetadata) => {
 	if (!metadata?.package) return undefined;
 	return `npm:${metadata.package}@${metadata.version ?? 'latest'}`;
 };
 
+const getNpmFileUrlPrefix = (metadata?: VirtualResourceMetadata) => {
+	if (!metadata?.package || !metadata?.version) return undefined;
+	return `https://unpkg.com/${metadata.package}@${metadata.version}`;
+};
+
 const createCollectionInstructionBlock = (
 	resource: BtcaFsResource,
 	metadata?: VirtualResourceMetadata
-): string => {
-	const focusLines = resource.repoSubPaths.map(
-		(subPath) => `Focus: ./${resource.fsName}/${subPath}`
-	);
+) => {
+	const repoUrl =
+		resource.type === 'git' && metadata?.url ? trimGitSuffix(metadata.url) : undefined;
 	const gitRef = metadata?.branch ?? metadata?.commit;
-	const githubPrefix =
-		resource.type === 'git' && metadata?.url && gitRef
-			? `${trimGitSuffix(metadata.url)}/blob/${encodeURIComponent(gitRef)}`
-			: undefined;
+	const githubBlobPrefix =
+		repoUrl && gitRef ? `${repoUrl}/blob/${encodeURIComponent(gitRef)}` : undefined;
 	const npmCitationAlias = resource.type === 'npm' ? getNpmCitationAlias(metadata) : undefined;
-	const lines = [
-		`## Resource: ${resource.name}`,
-		FS_RESOURCE_SYSTEM_NOTE,
-		`Path: ./${resource.fsName}`,
-		resource.type === 'git' && metadata?.url ? `Repo URL: ${trimGitSuffix(metadata.url)}` : '',
-		resource.type === 'git' && metadata?.branch ? `Repo Branch: ${metadata.branch}` : '',
-		resource.type === 'git' && metadata?.commit ? `Repo Commit: ${metadata.commit}` : '',
-		resource.type === 'npm' && metadata?.package ? `NPM Package: ${metadata.package}` : '',
-		resource.type === 'npm' && metadata?.version ? `NPM Version: ${metadata.version}` : '',
-		resource.type === 'npm' && metadata?.url ? `NPM URL: ${metadata.url}` : '',
-		npmCitationAlias ? `NPM Citation Alias: ${npmCitationAlias}` : '',
-		githubPrefix ? `GitHub Blob Prefix: ${githubPrefix}` : '',
-		githubPrefix
-			? `GitHub Citation Rule: Convert virtual paths under ./${resource.fsName}/ to repo-relative paths, then encode each path segment for GitHub URLs (example segment: "+page.server.js" -> "${encodeURIComponent('+page.server.js')}").`
-			: '',
-		githubPrefix
-			? `GitHub Citation Example: ${githubPrefix}/${encodePathSegments('src/routes/blog/+page.server.js')}`
-			: '',
-		resource.type !== 'git'
-			? 'Citation Rule: Cite local file paths only for this resource (no GitHub URL).'
-			: '',
-		npmCitationAlias
-			? `NPM Citation Rule: In "Sources", cite npm files using "${npmCitationAlias}/<file>" (for example, "${npmCitationAlias}/README.md"). Do not cite encoded virtual folder names.`
-			: '',
-		...focusLines,
-		resource.specialAgentInstructions ? `Notes: ${resource.specialAgentInstructions}` : ''
-	].filter(Boolean);
-
-	return lines.join('\n');
+	const npmFileUrlPrefix = resource.type === 'npm' ? getNpmFileUrlPrefix(metadata) : undefined;
+
+	return [
+		'\t<resource>',
+		`\t\t<name>${escapeXml(resource.name)}</name>`,
+		`\t\t<type>${getResourceTypeLabel(resource)}</type>`,
+		`\t\t<system_note>${escapeXml(FS_RESOURCE_SYSTEM_NOTE)}</system_note>`,
+		`\t\t<path>${escapeXml(`./${resource.fsName}`)}</path>`,
+		xmlLine('repo_url', repoUrl),
+		xmlLine('repo_branch', resource.type === 'git' ? metadata?.branch : undefined),
+		xmlLine('repo_commit', resource.type === 'git' ? metadata?.commit : undefined),
+		xmlLine('npm_package', resource.type === 'npm' ? metadata?.package : undefined),
+		xmlLine('npm_version', resource.type === 'npm' ? metadata?.version : undefined),
+		xmlLine('npm_url', resource.type === 'npm' ? metadata?.url : undefined),
+		xmlLine('npm_citation_alias', npmCitationAlias),
+		xmlLine('npm_file_url_prefix', npmFileUrlPrefix),
+		xmlLine('github_blob_prefix', githubBlobPrefix),
+		xmlLine(
+			'citation_rule',
+			githubBlobPrefix
+				? `Convert virtual paths under ./${resource.fsName}/ to repo-relative paths, then encode each path segment for GitHub URLs.`
+				: resource.type === 'npm' && npmCitationAlias
+					? `In Sources, cite npm files using ${npmCitationAlias}/<file> and link them to ${npmFileUrlPrefix ?? 'the exact file URL prefix'}/<file>. Do not cite encoded virtual folder names.`
+					: 'Cite local file paths only for this resource.'
+		),
+		xmlLine(
+			'citation_example',
+			githubBlobPrefix
+				? `${githubBlobPrefix}/${encodePathSegments('src/routes/blog/+page.server.js')}`
+				: resource.type === 'npm' && npmCitationAlias && npmFileUrlPrefix
+					? `${npmFileUrlPrefix}/package.json`
+					: undefined
+		),
+		xmlPathBlock('focus_paths', resource.repoSubPaths, `./${resource.fsName}/`),
+		xmlLine('special_notes', resource.specialAgentInstructions),
+		'\t</resource>'
+	]
+		.filter(Boolean)
+		.join('\n');
+};
+
+const createCollectionInstructions = (
+	resources: readonly BtcaFsResource[],
+	metadataResources: readonly VirtualResourceMetadata[]
+) => {
+	const metadataByName = new Map(metadataResources.map((resource) => [resource.name, resource]));
+
+	return [
+		'<available_resources>',
+		...resources.map((resource) =>
+			createCollectionInstructionBlock(resource, metadataByName.get(resource.name))
+		),
+		'</available_resources>'
+	].join('\n');
 };
 
 const ignoreErrors = async (action: () => Promise<unknown>) => {
@@ -400,16 +454,9 @@ export const createCollectionsService = (args: {
 					resources: metadataResources
 				});
 
-				const metadataByName = new Map(
-					metadataResources.map((resource) => [resource.name, resource])
-				);
-				const instructionBlocks = loadedResources.map((resource) =>
-					createCollectionInstructionBlock(resource, metadataByName.get(resource.name))
-				);
-
 				return {
 					path: collectionPath,
-					agentInstructions: instructionBlocks.join('\n\n'),
+					agentInstructions: createCollectionInstructions(loadedResources, metadataResources),
 					vfsId,
 					cleanup: async () => {
 						await cleanupResources(loadedResources);