feat(search): use hosted search for signed-in sessions

Author: halfaipg

README.md

@@ -86,6 +86,11 @@ codebase project build --wait "build a launch waitlist page"
 
 OAuth uses Codebase Auto by default (`codebase/d4f`, in-house DeepSeek V4 Flash). Swap models live with `/model`. Set reasoning depth with `/effort`. `project build` hands a prompt to the web builder and prints the session, status, event stream, and preview URL when you pass `--wait`.
 
+Signed-in sessions also get hosted web search with no extra key. BYOK users can
+set `TAVILY_API_KEY`, `BRAVE_API_KEY`, or `SEARXNG_URL`; local search providers
+take priority over the hosted service. Run `codebase doctor` to verify which
+path is active.
+
 ## Use Codebase from an ACP client
 
 Codebase speaks the [Agent Client Protocol](https://agentclientprotocol.com/) over stdio:

docs/MIGRATION_v1_to_v2.md

@@ -29,7 +29,7 @@ and project memory all keep working.
 | `~/.codebase/config.json` | User config (theme, MCP servers, hooks) | Compatible. New fields are added; existing ones are read as before. |
 | `CLAUDE.md`, `AGENTS.md`, `CODEX.md`, `.cursorrules` | Project instructions | Identical pickup logic. |
 | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL` | Provider env vars | Identical. |
-| `GLUE_*`, `TAVILY_API_KEY`, `BRAVE_API_KEY`, `SEARXNG_URL` | Sidecar + search keys | Identical. |
+| `GLUE_*`, `TAVILY_API_KEY`, `BRAVE_API_KEY`, `SEARXNG_URL` | Sidecar + search keys | Still supported. Signed-in Codebase sessions can use hosted search without a separate search key. |
 | `CODEBASE_NOBOOT`, `CODEBASE_NOSOUND` | Behavior toggles | Identical. |
 
 If you sign in via codebase.foundation in v1, you stay signed in

src/agent/agent.ts

@@ -324,6 +324,12 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 
 	const toolContext: ToolContext = {
 		cwd,
+		...(tokenManager && {
+			platform: {
+				baseUrl: (process.env.CODEBASE_AUTH_BASE_URL ?? "https://codebase.design").replace(/\/+$/, ""),
+				getAccessToken: () => tokenManager.getAccessToken(),
+			},
+		}),
 		fileStateCache: new FileStateCache(),
 		tasks: new TaskStore({ cwd, taskListId: opts.taskListId ?? sessions.id }),
 		userQueries,

src/agent/system-prompt.test.ts

@@ -28,6 +28,12 @@ describe("buildSystemPrompt", () => {
 		expect(out).toMatch(/Issue independent tool calls together/);
 	});
 
+	it("forbids presenting invented results after a failed web search", () => {
+		const out = buildSystemPrompt();
+		expect(out).toMatch(/When web_search fails, no search occurred/);
+		expect(out).toMatch(/never invent.*links as search results/i);
+	});
+
 	it("teaches subagent dispatch for fan-out work", () => {
 		const out = buildSystemPrompt();
 		expect(out).toMatch(/dispatch_agent/);

src/agent/system-prompt.ts

@@ -60,6 +60,9 @@ export function buildSystemPrompt(opts: BuildSystemPromptOptions = {}): string {
 	lines.push(
 		"When a task fans out cleanly — multi-file audits, security reviews, broad codebase exploration — prefer dispatching subagents via dispatch_agent so each stream runs in parallel and their context stays out of your main loop. Don't also do the same searches yourself; that wastes turns and doubles the noise.",
 	);
+	lines.push(
+		"When web_search fails, no search occurred. Say that it failed and why; never invent, reconstruct from memory, or present plausible-looking links as search results.",
+	);
 	lines.push(
 		'Subagents come in types: "explore" (read-only, the default) for investigation, "general" for work that edits files or runs commands, plus any project-defined types. For parallel write work, give each general subagent isolation: "worktree" so their edits can\'t collide.',
 	);

src/diagnostics/doctor.test.ts

@@ -52,7 +52,7 @@ describe("buildDoctorReport", () => {
 		const out = buildDoctorReport({
 			cwd,
 			dataRoot,
-			env: { TAVILY_API_KEY: "configured" } as NodeJS.ProcessEnv,
+			env: {},
 			model: { provider: "codebase", id: "d4f", name: "Codebase Auto" },
 			source: "proxy",
 			mcpStatuses: [{ name: "db", connected: false, toolCount: 0, error: "spawn failed" }],
@@ -66,7 +66,7 @@ describe("buildDoctorReport", () => {
 		expect(out).toContain("config ");
 		expect(out).toContain("is not valid JSON");
 		expect(out).toContain("mcp db: spawn failed");
-		expect(out).toContain("✓ web_search configured");
+		expect(out).toContain("✓ web_search configured (Codebase hosted)");
 		expect(out).toContain("sessions for this directory: 3");
 		expect(out).toContain("subagent types: general");
 	});

src/diagnostics/doctor.ts

@@ -87,11 +87,16 @@ export function buildDoctorReport(options: DoctorReportOptions): string[] {
 		lines.push(check(s.connected, `mcp ${s.name}: ${s.toolCount} tools`, `mcp ${s.name}: ${s.error ?? "failed"}`));
 	}
 
-	const hasSearch = Boolean(env.TAVILY_API_KEY || env.BRAVE_API_KEY || env.SEARXNG_URL);
+	const localSearch = Boolean(env.TAVILY_API_KEY || env.BRAVE_API_KEY || env.SEARXNG_URL);
+	const hostedSearch = Boolean(creds && creds.source !== "byok");
 	lines.push(
-		hasSearch
-			? check(true, "web_search configured", "")
-			: info("web_search unconfigured — set TAVILY_API_KEY, BRAVE_API_KEY, or SEARXNG_URL to enable"),
+		localSearch
+			? check(true, "web_search configured (local provider)", "")
+			: hostedSearch
+				? check(true, "web_search configured (Codebase hosted)", "")
+				: info(
+						"web_search unconfigured — sign in with `codebase auth login` or set TAVILY_API_KEY, BRAVE_API_KEY, or SEARXNG_URL",
+					),
 	);
 
 	lines.push(

src/tools/types.ts

@@ -18,6 +18,14 @@ import type { TaskStore } from "./task-store.js";
  */
 export interface ToolContext {
 	cwd: string;
+	/**
+	 * Authenticated Codebase platform access. Present for OAuth/manual proxy
+	 * sessions so tools can use hosted services without exposing service keys.
+	 */
+	platform?: {
+		baseUrl: string;
+		getAccessToken: () => Promise<string>;
+	};
 	fileStateCache: FileStateCache;
 	tasks: TaskStore;
 	userQueries: UserQueryStore;

src/tools/web-search.test.ts

@@ -61,8 +61,14 @@ describe("web_search provider selection", () => {
 		expect(pickProvider({ TAVILY_API_KEY: "x", BRAVE_API_KEY: "y" }).name).toBe("tavily");
 	});
 
+	it("uses Codebase hosted search only when no local provider is configured", () => {
+		const hosted = { baseUrl: "https://codebase.design", getAccessToken: async () => "token" };
+		expect(pickProvider({}, hosted).name).toBe("codebase");
+		expect(pickProvider({ BRAVE_API_KEY: "x" }, hosted).name).toBe("brave");
+	});
+
 	it("errors with onboarding when nothing is configured", () => {
-		expect(() => pickProvider({})).toThrow(/TAVILY_API_KEY/);
+		expect(() => pickProvider({})).toThrow(/SEARCH_FAILED_NO_RESULTS/);
 	});
 });
 
@@ -140,6 +146,56 @@ describe("web_search end-to-end via mock servers", () => {
 		expect(result.details.results[0].snippet).toBe("s1");
 	});
 
+	it("uses authenticated Codebase hosted search when signed in", async () => {
+		routes["/api/v1/search"] = (req, res) => {
+			expect(req.method).toBe("POST");
+			expect(req.headers.authorization).toBe("Bearer oauth-token");
+			const chunks: Buffer[] = [];
+			req.on("data", (chunk) => chunks.push(chunk));
+			req.on("end", () => {
+				expect(JSON.parse(Buffer.concat(chunks).toString("utf8"))).toEqual({
+					query: "AIPG",
+					max_results: 4,
+				});
+				res.setHeader("Content-Type", "application/json");
+				res.end(
+					JSON.stringify({
+						query: "AIPG",
+						provider: "tavily",
+						results: [
+							{
+								title: "AI Power Grid",
+								url: "https://example.com/aipg",
+								snippet: "A sourced result.",
+							},
+						],
+						duration_ms: 12,
+					}),
+				);
+			});
+		};
+
+		const original = { ...process.env };
+		for (const key of ["TAVILY_API_KEY", "BRAVE_API_KEY", "SEARXNG_URL"]) delete process.env[key];
+		try {
+			const result = await createWebSearch({
+				...makeCtx(),
+				platform: {
+					baseUrl,
+					getAccessToken: async () => "oauth-token",
+				},
+			}).execute("call", { query: "AIPG", max_results: 4 });
+
+			expect(result.details.provider).toBe("codebase");
+			expect(result.details.results[0]).toMatchObject({
+				title: "AI Power Grid",
+				url: "https://example.com/aipg",
+			});
+		} finally {
+			Object.assign(process.env, original);
+		}
+	});
+
 	it("surfaces provider HTTP errors with the status code", async () => {
 		routes["/search"] = (_req, res) => {
 			res.statusCode = 401;

src/tools/web-search.ts

@@ -48,10 +48,11 @@ Provider auto-detected from env (highest-priority match wins):
 - TAVILY_API_KEY  → Tavily (recommended; free tier available)
 - BRAVE_API_KEY   → Brave Search
 - SEARXNG_URL     → self-hosted SearXNG instance
+- Codebase OAuth  → hosted search (when signed in)
 
-If none are set, this tool errors with onboarding instructions instead of attempting an unauthenticated fallback. Default 5 results, max 20.`;
+Local providers take priority over hosted search. If none are available, this tool errors with onboarding instructions instead of attempting an unauthenticated fallback. Default 5 results, max 20.`;
 
-export type ProviderName = "tavily" | "brave" | "searxng";
+export type ProviderName = "tavily" | "brave" | "searxng" | "codebase";
 
 interface ProviderConfig {
 	name: ProviderName;
@@ -66,15 +67,20 @@ export interface ProviderEnv {
 	SEARXNG_URL?: string;
 }
 
-export function createWebSearch(_ctx: ToolContext): AgentTool<typeof Params, WebSearchDetails> {
+export interface HostedSearchConfig {
+	baseUrl: string;
+	getAccessToken: () => Promise<string>;
+}
+
+export function createWebSearch(ctx: ToolContext): AgentTool<typeof Params, WebSearchDetails> {
 	return {
 		name: "web_search",
 		label: "Search",
 		description: DESCRIPTION,
 		parameters: Params,
 		executionMode: "parallel",
 		execute: async (_id, params, signal) => {
-			const provider = pickProvider(process.env);
+			const provider = pickProvider(process.env, ctx.platform);
 			const max = params.max_results ?? DEFAULT_RESULTS;
 			const timeout = params.timeout_ms ?? DEFAULT_TIMEOUT_MS;
 
@@ -107,7 +113,7 @@ export function createWebSearch(_ctx: ToolContext): AgentTool<typeof Params, Web
 	};
 }
 
-export function pickProvider(env: ProviderEnv): ProviderConfig {
+export function pickProvider(env: ProviderEnv, hosted?: HostedSearchConfig): ProviderConfig {
 	if (env.TAVILY_API_KEY) {
 		return tavilyProvider(env.TAVILY_API_KEY, env.TAVILY_BASE_URL);
 	}
@@ -117,12 +123,53 @@ export function pickProvider(env: ProviderEnv): ProviderConfig {
 	if (env.SEARXNG_URL) {
 		return searxngProvider(env.SEARXNG_URL);
 	}
+	if (hosted) {
+		return codebaseProvider(hosted);
+	}
 	throw new Error(
-		"web_search has no provider configured. Set one of TAVILY_API_KEY (recommended), BRAVE_API_KEY, " +
-			"or SEARXNG_URL. Tavily offers a free tier at https://tavily.com.",
+		"SEARCH_FAILED_NO_RESULTS: web_search has no provider configured. Sign in with `codebase auth login`, " +
+			"or set TAVILY_API_KEY, BRAVE_API_KEY, or SEARXNG_URL. No web results were obtained; do not invent " +
+			"or present search results.",
 	);
 }
 
+function codebaseProvider(config: HostedSearchConfig): ProviderConfig {
+	const url = `${config.baseUrl.replace(/\/+$/, "")}/api/v1/search`;
+	return {
+		name: "codebase",
+		search: async (query, max, signal) => {
+			const token = await config.getAccessToken();
+			const res = await fetch(url, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${token}`,
+					"Content-Type": "application/json",
+					Accept: "application/json",
+				},
+				body: JSON.stringify({ query, max_results: max }),
+				signal,
+			});
+			const json = (await res.json().catch(() => ({}))) as {
+				error?: string;
+				error_description?: string;
+				results?: SearchResult[];
+			};
+			if (!res.ok) {
+				const reason = json.error_description ?? json.error ?? res.statusText;
+				throw new Error(`codebase ${res.status} ${reason}`);
+			}
+			return Array.isArray(json.results)
+				? json.results.filter(
+						(result) =>
+							typeof result?.title === "string" &&
+							typeof result?.url === "string" &&
+							typeof result?.snippet === "string",
+					)
+				: [];
+		},
+	};
+}
+
 function tavilyProvider(apiKey: string, baseUrl?: string): ProviderConfig {
 	const url = `${baseUrl ?? "https://api.tavily.com"}/search`;
 	return {