membot 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "membot",
-	"version": "0.5.0",
+	"version": "0.5.1",
 	"description": "Versioned context store with hybrid search for AI agents. Stdio + HTTP MCP server and CLI.",
 	"type": "module",
 	"exports": {

package/patches/@evantahler%2Fmcpx@0.21.4.patch

@@ -1,7 +1,7 @@
 diff --git a/src/search/onnx-wasm-paths.ts b/src/search/onnx-wasm-paths.ts
 --- a/src/search/onnx-wasm-paths.ts
 +++ b/src/search/onnx-wasm-paths.ts
-@@ -1,31 +1,9 @@
+@@ -1,31 +1,16 @@
 -// Embed the onnxruntime-web WASM runtime files into the compiled binary
 -// (`bun build --compile`) so they survive in a single-binary distribution
 -// where the user has no node_modules.
@@ -33,12 +33,19 @@ diff --git a/src/search/onnx-wasm-paths.ts b/src/search/onnx-wasm-paths.ts
 -};
 -
 -export { wasmBinPath, wasmMjsPath };
-+// PATCHED (membot): upstream mcpx ships static `with { type: "file" }` imports
-+// of onnxruntime-web WASM assets via `../../node_modules/...`, which only
-+// resolves when mcpx is built standalone. When consumed as an npm dep those
-+// paths are unreachable and `bun build --compile` fails at build time. membot
-+// never invokes mcpx's semantic search (only `mcpx.exec()` for URL fetching),
-+// so we stub the exports — semantic.ts wraps the dynamic import in try/catch
-+// and falls back to transformers.js's default WASM loader.
-+export const wasmMjsPath = "";
-+export const wasmBinPath = "";
++// PATCHED (membot): point mcpx's onnx-wasm-paths at the onnxruntime-web installed
++// at the top of membot's node_modules. Upstream's `../../node_modules/...` only
++// resolves in mcpx's standalone repo layout; for consumers we walk up 4 levels:
++// node_modules/@evantahler/mcpx/src/search → node_modules → onnxruntime-web.
++// biome-ignore lint/suspicious/noTsIgnore: must stay as ts-ignore — relative path only resolves at runtime in consumer layout
++// @ts-ignore - dynamic-only import
++import wasmMjsPath from "../../../../onnxruntime-web/dist/ort-wasm-simd-threaded.asyncify.mjs" with {
++	type: "file",
++};
++// biome-ignore lint/suspicious/noTsIgnore: must stay as ts-ignore — relative path only resolves at runtime in consumer layout
++// @ts-ignore - dynamic-only import
++import wasmBinPath from "../../../../onnxruntime-web/dist/ort-wasm-simd-threaded.asyncify.wasm" with {
++	type: "file",
++};
++
++export { wasmBinPath, wasmMjsPath };

package/scripts/apply-patches.sh

@@ -38,11 +38,13 @@ apply_patch \
 	"node_modules/@huggingface/transformers" \
 	".membot-transformers-patch-applied"
 
-# @evantahler/mcpx — stub `src/search/onnx-wasm-paths.ts` whose static
-# `with { type: "file" }` imports use a relative path that only resolves in
-# mcpx's own repo layout. When mcpx is consumed as an npm dep those paths are
-# unreachable and `bun build --compile` fails at build time. membot never
-# invokes mcpx's semantic search, so the stubbed exports are safe.
+# @evantahler/mcpx — rewrite `src/search/onnx-wasm-paths.ts` so its static
+# `with { type: "file" }` imports of onnxruntime-web's WASM resolve from the
+# consumer's hoisted node_modules layout (../../../../onnxruntime-web/...)
+# instead of mcpx's own repo layout (../../node_modules/...). With this
+# patch in place, mcpx's semantic search runs end-to-end inside membot
+# (the agent fetcher's `mcp_search` exercises it) and `bun build --compile`
+# can bundle the WASM assets into the standalone binary.
 apply_patch \
 	"patches/@evantahler%2Fmcpx@0.21.4.patch" \
 	"node_modules/@evantahler/mcpx" \

package/src/ingest/agent-fetcher.ts

@@ -0,0 +1,564 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type {
+	Tool as AnthropicTool,
+	MessageParam,
+	ToolResultBlockParam,
+	ToolUseBlock,
+} from "@anthropic-ai/sdk/resources/messages";
+import type { LlmConfig } from "../config/schemas.ts";
+import { HelpfulError } from "../errors.ts";
+import { logger } from "../output/logger.ts";
+import { sha256Hex } from "./local-reader.ts";
+
+/** Number of times the agent may iterate. Each turn = one Claude call + tool dispatch. */
+const MAX_TURNS = 10;
+/** Bytes of content shown back to the LLM in the mcp_exec preview. The harness has the full content. */
+const PREVIEW_CHARS = 2_000;
+/** Token budget per Claude call. Should comfortably fit a tool-use response + reasoning. */
+const MAX_RESPONSE_TOKENS = 4_096;
+
+/**
+ * Outcome shape mirrored from `FetchedRemote` in fetcher.ts. We don't
+ * import that type here to avoid a cycle — the fetcher imports us.
+ */
+export interface AgentFetchedRemote {
+	bytes: Uint8Array;
+	sha256: string;
+	mimeType: string;
+	fetcher: "mcpx";
+	fetcherServer: string;
+	fetcherTool: string;
+	fetcherArgs: Record<string, unknown>;
+	sourceUrl: string;
+}
+
+/**
+ * The slice of mcpx the agent loop needs. Kept minimal so tests can
+ * stub it without spinning up a real client.
+ */
+export interface AgentMcpxAdapter {
+	search(
+		query: string,
+		options?: { keywordOnly?: boolean; semanticOnly?: boolean },
+	): Promise<{ server: string; tool: string; description?: string; score?: number; matchType?: string }[]>;
+	listTools(server?: string): Promise<{ server: string; tool: { name: string; description?: string } }[]>;
+	info(
+		server: string,
+		tool: string,
+	): Promise<{ name: string; description?: string; inputSchema?: unknown } | undefined>;
+	exec(
+		server: string,
+		tool: string,
+		args?: Record<string, unknown>,
+	): Promise<{ isError?: boolean; content?: unknown[] }>;
+}
+
+export interface AgentFetchOptions {
+	url: string;
+	mcpx: AgentMcpxAdapter;
+	llm: LlmConfig;
+	hint?: string;
+	/** Test seam: inject a pre-built Anthropic client. */
+	_testClient?: Anthropic;
+}
+
+/**
+ * Outcome of the agent loop:
+ *   - `accepted`: the agent picked a captured mcp_exec result; caller stores it as the new version.
+ *   - `fallback`: the agent gave up on mcpx (request_http_fallback, no tool calls, max turns); caller does plain HTTP.
+ *   - HelpfulError thrown: the agent reported an actionable failure (report_failure), or the loop hit a hard error.
+ */
+export type AgentFetchOutcome = { kind: "accepted"; result: AgentFetchedRemote } | { kind: "fallback"; reason: string };
+
+const FETCHER_SYSTEM_PROMPT = `You are a content fetcher. Your job is to find the right MCP tool to retrieve the content at the given URL, run it, and tell the harness which result to save.
+
+**Important: the harness captures the full result of every mcp_exec call automatically.** You only see a short preview of each result so you can verify it looks reasonable. You do NOT need to read or copy the full content — you just identify which exec call to save.
+
+**Format preference: markdown, in order of preference.**
+1. When searching with mcp_search or mcp_list_tools, prefer tools whose names indicate markdown output: anything containing "markdown", "md", "AsMarkdown", "AsMd", "AsDocmd", or similar.
+2. If no markdown-named variant exists, use mcp_info to inspect the tool's input schema for a "format", "mime_type", "output_format", or similar parameter and request "markdown" (or "md") when available.
+3. If neither is possible, run the tool anyway. The membot pipeline will normalize the captured content downstream — markdown-native tools are still preferred because they're cheaper and higher fidelity, but you do not have to find one.
+
+Workflow:
+1. Use mcp_search or mcp_list_tools to find the best tool for this URL (e.g., Google Docs tools for docs.google.com, Firecrawl for generic web pages, GitHub tools for github.com). Apply the format preference above.
+2. Use mcp_info to inspect the tool's input schema. **Required before mcp_exec on any tool you haven't called this session.** Many tools want \`document_id\`, \`repo\`, \`page_id\`, etc. — not \`url\`. Extract the right value from the URL.
+3. Call mcp_exec with arguments that conform to the schema.
+4. **Multi-step workflows are expected.** Many providers need a sequence of calls — e.g. Firecrawl: \`scrape\` returns a job id, then \`get_job_status\` polls until done, then the final result has the content; some doc providers need a \`prepare/export\` call before \`download\`; large docs may paginate. Make as many mcp_exec calls as needed. Read each preview to decide the next step.
+5. If the tool errors (input_error / auth_error / "still processing"), read the error, adjust, and retry — or pivot to a different tool.
+6. Once a successful exec preview looks like the FINAL content, call accept_content with the exec_call_id (the tool_use_id of that mcp_exec call) and the actual mime_type the tool returned. Pick the call whose result is the actual content — not an intermediate job id or status response.
+
+Terminal tools (call exactly one):
+- accept_content(exec_call_id, mime_type?) — save the content captured from a previous mcp_exec call.
+- request_http_fallback() — fall back to a basic HTTP fetch. Use only when no MCP tool can handle the URL after a genuine attempt.
+- report_failure(message) — surface an actionable message to the user (e.g., "this Google Doc is private — share it with your service account"). Use only when there is a specific next step the user must take.`;
+
+const acceptContentTool: AnthropicTool = {
+	name: "accept_content",
+	description:
+		"Save the full content captured by the harness from a previous mcp_exec call. You only need to supply the exec_call_id (the tool_use_id of that mcp_exec call). The harness already has the full content. Do NOT paste content here.",
+	input_schema: {
+		type: "object" as const,
+		properties: {
+			exec_call_id: {
+				type: "string",
+				description:
+					"The tool_use_id of the mcp_exec call whose result should be saved (the harness lists captured ids in mcp_exec previews).",
+			},
+			mime_type: {
+				type: "string",
+				description:
+					"MIME type the source tool returned (e.g. 'text/markdown', 'text/html', 'application/json'). Defaults to text/markdown.",
+			},
+		},
+		required: ["exec_call_id"],
+	},
+};
+
+const requestHttpFallbackTool: AnthropicTool = {
+	name: "request_http_fallback",
+	description: "Fall back to a basic HTTP fetch. Use only when no MCP tool can handle the URL after a genuine attempt.",
+	input_schema: { type: "object" as const, properties: {}, required: [] },
+};
+
+const reportFailureTool: AnthropicTool = {
+	name: "report_failure",
+	description:
+		"Report a fetch failure with an actionable message for the user (e.g., 'this Google Doc is private — share it with your service account'). Use only when there is a clear next step the user must take.",
+	input_schema: {
+		type: "object" as const,
+		properties: {
+			message: {
+				type: "string",
+				description: "Clear, actionable, user-facing message explaining what the user needs to do.",
+			},
+		},
+		required: ["message"],
+	},
+};
+
+const mcpSearchTool: AnthropicTool = {
+	name: "mcp_search",
+	description:
+		"Search for MCP tools by keyword + semantic similarity over the live mcpx catalog. Returns up to a handful of {server, tool, description, score} entries.",
+	input_schema: {
+		type: "object" as const,
+		properties: {
+			query: { type: "string", description: "Search query (e.g. 'fetch google docs as markdown')." },
+		},
+		required: ["query"],
+	},
+};
+
+const mcpListToolsTool: AnthropicTool = {
+	name: "mcp_list_tools",
+	description: "List available tools from configured MCP servers. Optionally filter by server name.",
+	input_schema: {
+		type: "object" as const,
+		properties: {
+			server: { type: "string", description: "Optional server name to filter on." },
+		},
+		required: [],
+	},
+};
+
+const mcpInfoTool: AnthropicTool = {
+	name: "mcp_info",
+	description:
+		"Get the full schema (name, description, input parameters) for a specific MCP tool. Required before mcp_exec on tools you haven't called this session.",
+	input_schema: {
+		type: "object" as const,
+		properties: {
+			server: { type: "string", description: "MCP server name." },
+			tool: { type: "string", description: "Tool name on the server." },
+		},
+		required: ["server", "tool"],
+	},
+};
+
+const mcpExecTool: AnthropicTool = {
+	name: "mcp_exec",
+	description:
+		"Execute a tool on an MCP server. The full result is captured by the harness keyed by tool_use_id; you receive a short preview to verify the content. To save the result, call accept_content with the exec_call_id.",
+	input_schema: {
+		type: "object" as const,
+		properties: {
+			server: { type: "string", description: "MCP server name." },
+			tool: { type: "string", description: "Tool name on the server." },
+			args: {
+				type: "object",
+				description: "Arguments object that conforms to the tool's input schema (verify via mcp_info).",
+			},
+		},
+		required: ["server", "tool"],
+	},
+};
+
+const ALL_TOOLS: AnthropicTool[] = [
+	mcpSearchTool,
+	mcpListToolsTool,
+	mcpInfoTool,
+	mcpExecTool,
+	acceptContentTool,
+	requestHttpFallbackTool,
+	reportFailureTool,
+];
+
+interface CapturedExec {
+	server: string;
+	tool: string;
+	args: Record<string, unknown>;
+	content: string;
+	mimeType: string;
+}
+
+/**
+ * Run the multi-turn fetcher agent. Mirrors botholomew's `runFetcherLoop`.
+ *
+ * Returns `{ kind: "accepted", result }` when the agent calls `accept_content`
+ * on a captured mcp_exec result. Returns `{ kind: "fallback" }` when the agent
+ * calls `request_http_fallback`, produces no tool calls, or exhausts MAX_TURNS.
+ * Throws `HelpfulError` when the agent calls `report_failure` (the actionable
+ * message becomes the error's `message`/`hint`).
+ */
+export async function agentFetch(opts: AgentFetchOptions): Promise<AgentFetchOutcome> {
+	if (!opts.llm.anthropic_api_key || opts.llm.anthropic_api_key.trim() === "") {
+		throw new HelpfulError({
+			kind: "auth_error",
+			message: `agentFetch requires ANTHROPIC_API_KEY but llm.anthropic_api_key is empty.`,
+			hint: `Set ANTHROPIC_API_KEY in your environment or under llm.anthropic_api_key in ~/.membot/config.json.`,
+		});
+	}
+
+	const client = opts._testClient ?? new Anthropic({ apiKey: opts.llm.anthropic_api_key });
+
+	const userPrompt = opts.hint
+		? `Fetch the content at: ${opts.url}\n\nAdditional guidance:\n${opts.hint}`
+		: `Fetch the content at: ${opts.url}`;
+	const messages: MessageParam[] = [{ role: "user", content: userPrompt }];
+
+	const captured = new Map<string, CapturedExec>();
+
+	for (let turn = 0; turn < MAX_TURNS; turn++) {
+		const response = await client.messages.create({
+			model: opts.llm.converter_model,
+			max_tokens: MAX_RESPONSE_TOKENS,
+			system: FETCHER_SYSTEM_PROMPT,
+			messages,
+			tools: ALL_TOOLS,
+		});
+
+		for (const block of response.content) {
+			if (block.type === "text" && block.text.trim()) {
+				logger.debug(`agent-fetch turn ${turn + 1}: ${block.text.trim()}`);
+			}
+		}
+
+		if (response.stop_reason === "max_tokens") {
+			throw new HelpfulError({
+				kind: "internal_error",
+				message: `Fetcher agent hit max_tokens (${MAX_RESPONSE_TOKENS}) on turn ${turn + 1}.`,
+				hint: `The fetched document or the agent's reasoning is too long. Try \`membot add ${opts.url} --fetcher http\` or fetch a more specific section.`,
+			});
+		}
+
+		const toolUseBlocks = response.content.filter((b): b is ToolUseBlock => b.type === "tool_use");
+		if (toolUseBlocks.length === 0) {
+			logger.debug(`agent-fetch turn ${turn + 1}: no tool calls — falling back to HTTP`);
+			return { kind: "fallback", reason: "agent stopped without selecting an outcome" };
+		}
+
+		messages.push({ role: "assistant", content: response.content });
+
+		// Terminal tools — checked in priority order.
+		const failureCall = toolUseBlocks.find((b) => b.name === "report_failure");
+		if (failureCall) {
+			const input = failureCall.input as Partial<{ message: string }>;
+			const message =
+				typeof input.message === "string" && input.message.trim()
+					? input.message.trim()
+					: "Fetch failed but the agent did not provide a message.";
+			throw new HelpfulError({
+				kind: "input_error",
+				message: `Fetcher agent reported failure for ${opts.url}: ${message}`,
+				hint: message,
+			});
+		}
+
+		const fallbackCall = toolUseBlocks.find((b) => b.name === "request_http_fallback");
+		if (fallbackCall) {
+			logger.debug(`agent-fetch turn ${turn + 1}: agent requested HTTP fallback`);
+			return { kind: "fallback", reason: "agent requested HTTP fallback" };
+		}
+
+		const acceptCall = toolUseBlocks.find((b) => b.name === "accept_content");
+		if (acceptCall) {
+			const input = acceptCall.input as Partial<{ exec_call_id: string; mime_type: string }>;
+			if (typeof input.exec_call_id !== "string") {
+				messages.push({
+					role: "user",
+					content: [
+						{
+							type: "tool_result",
+							tool_use_id: acceptCall.id,
+							content: "Invalid accept_content call: 'exec_call_id' is required.",
+							is_error: true,
+						},
+					],
+				});
+				continue;
+			}
+			const cached = captured.get(input.exec_call_id);
+			if (!cached) {
+				const validIds = [...captured.keys()];
+				messages.push({
+					role: "user",
+					content: [
+						{
+							type: "tool_result",
+							tool_use_id: acceptCall.id,
+							content: `No mcp_exec call with id "${input.exec_call_id}" was captured. Captured ids: ${validIds.length ? validIds.join(", ") : "(none yet — run mcp_exec first)"}.`,
+							is_error: true,
+						},
+					],
+				});
+				continue;
+			}
+			const claimedMime = (input.mime_type ?? cached.mimeType ?? "text/markdown").trim() || "text/markdown";
+			const bytes = new TextEncoder().encode(cached.content);
+			return {
+				kind: "accepted",
+				result: {
+					bytes,
+					sha256: sha256Hex(bytes),
+					mimeType: claimedMime,
+					fetcher: "mcpx",
+					fetcherServer: cached.server,
+					fetcherTool: cached.tool,
+					fetcherArgs: cached.args,
+					sourceUrl: opts.url,
+				},
+			};
+		}
+
+		// Discovery / exec tools — execute in parallel, feed results back.
+		const toolResults: ToolResultBlockParam[] = await Promise.all(
+			toolUseBlocks.map((toolUse) => dispatchAgentTool(toolUse, opts.mcpx, captured)),
+		);
+		messages.push({ role: "user", content: toolResults });
+	}
+
+	logger.debug(`agent-fetch: max turns (${MAX_TURNS}) exceeded — falling back to HTTP`);
+	return { kind: "fallback", reason: `agent exceeded MAX_TURNS=${MAX_TURNS}` };
+}
+
+/** Execute one agent tool call and produce the tool_result block fed back to Claude. */
+async function dispatchAgentTool(
+	toolUse: ToolUseBlock,
+	mcpx: AgentMcpxAdapter,
+	captured: Map<string, CapturedExec>,
+): Promise<ToolResultBlockParam> {
+	try {
+		switch (toolUse.name) {
+			case "mcp_search":
+				return await runMcpSearch(toolUse, mcpx);
+			case "mcp_list_tools":
+				return await runMcpListTools(toolUse, mcpx);
+			case "mcp_info":
+				return await runMcpInfo(toolUse, mcpx);
+			case "mcp_exec":
+				return await runMcpExec(toolUse, mcpx, captured);
+			default:
+				return {
+					type: "tool_result",
+					tool_use_id: toolUse.id,
+					content: `Unknown tool: ${toolUse.name}`,
+					is_error: true,
+				};
+		}
+	} catch (err) {
+		return {
+			type: "tool_result",
+			tool_use_id: toolUse.id,
+			content: `Error: ${err instanceof Error ? err.message : String(err)}`,
+			is_error: true,
+		};
+	}
+}
+
+async function runMcpSearch(toolUse: ToolUseBlock, mcpx: AgentMcpxAdapter): Promise<ToolResultBlockParam> {
+	const input = toolUse.input as Partial<{ query: string }>;
+	if (typeof input.query !== "string" || !input.query.trim()) {
+		return { type: "tool_result", tool_use_id: toolUse.id, content: "mcp_search requires 'query'.", is_error: true };
+	}
+	try {
+		const results = await mcpx.search(input.query);
+		return {
+			type: "tool_result",
+			tool_use_id: toolUse.id,
+			content: JSON.stringify(
+				{
+					results: results.slice(0, 10).map((r) => ({
+						server: r.server,
+						tool: r.tool,
+						description: r.description ?? "",
+						score: r.score ?? 0,
+					})),
+					hint:
+						results.length > 0
+							? "Use mcp_info to read the input schema before mcp_exec."
+							: "No results. Try broader terms or mcp_list_tools.",
+				},
+				null,
+				2,
+			),
+		};
+	} catch (err) {
+		return {
+			type: "tool_result",
+			tool_use_id: toolUse.id,
+			content: `mcp_search failed: ${err instanceof Error ? err.message : String(err)}. Try mcp_list_tools instead.`,
+			is_error: true,
+		};
+	}
+}
+
+async function runMcpListTools(toolUse: ToolUseBlock, mcpx: AgentMcpxAdapter): Promise<ToolResultBlockParam> {
+	const input = toolUse.input as Partial<{ server: string }>;
+	const tools = await mcpx.listTools(input.server);
+	const mapped = tools.map((t) => ({ server: t.server, name: t.tool.name, description: t.tool.description ?? "" }));
+	return {
+		type: "tool_result",
+		tool_use_id: toolUse.id,
+		content: JSON.stringify(
+			{
+				tools: mapped,
+				hint:
+					mapped.length > 0
+						? "Use mcp_info on a {server, name} pair before mcp_exec."
+						: "No tools. mcpx may not be configured.",
+			},
+			null,
+			2,
+		),
+	};
+}
+
+async function runMcpInfo(toolUse: ToolUseBlock, mcpx: AgentMcpxAdapter): Promise<ToolResultBlockParam> {
+	const input = toolUse.input as Partial<{ server: string; tool: string }>;
+	if (typeof input.server !== "string" || typeof input.tool !== "string") {
+		return {
+			type: "tool_result",
+			tool_use_id: toolUse.id,
+			content: "mcp_info requires 'server' and 'tool'.",
+			is_error: true,
+		};
+	}
+	const tool = await mcpx.info(input.server, input.tool);
+	if (!tool) {
+		return {
+			type: "tool_result",
+			tool_use_id: toolUse.id,
+			content: `Tool "${input.tool}" not found on server "${input.server}". Use mcp_search or mcp_list_tools.`,
+			is_error: true,
+		};
+	}
+	return {
+		type: "tool_result",
+		tool_use_id: toolUse.id,
+		content: JSON.stringify(
+			{
+				name: tool.name,
+				description: tool.description ?? "",
+				input_schema: tool.inputSchema ?? {},
+				hint: `Call mcp_exec with server='${input.server}', tool='${tool.name}', and args matching this schema.`,
+			},
+			null,
+			2,
+		),
+	};
+}
+
+async function runMcpExec(
+	toolUse: ToolUseBlock,
+	mcpx: AgentMcpxAdapter,
+	captured: Map<string, CapturedExec>,
+): Promise<ToolResultBlockParam> {
+	const input = toolUse.input as Partial<{ server: string; tool: string; args: Record<string, unknown> }>;
+	if (typeof input.server !== "string" || typeof input.tool !== "string") {
+		return {
+			type: "tool_result",
+			tool_use_id: toolUse.id,
+			content: "mcp_exec requires 'server' and 'tool'.",
+			is_error: true,
+		};
+	}
+	const args = (input.args ?? {}) as Record<string, unknown>;
+
+	let result: { isError?: boolean; content?: unknown[] };
+	try {
+		result = await mcpx.exec(input.server, input.tool, args);
+	} catch (err) {
+		return {
+			type: "tool_result",
+			tool_use_id: toolUse.id,
+			content: `mcp_exec ${input.server}/${input.tool} threw: ${err instanceof Error ? err.message : String(err)}. Use mcp_info to verify the schema, then retry — or pivot to a different tool.`,
+			is_error: true,
+		};
+	}
+
+	const text = extractText(result);
+
+	if (result.isError === true) {
+		return {
+			type: "tool_result",
+			tool_use_id: toolUse.id,
+			content: `mcp_exec ${input.server}/${input.tool} returned isError=true: ${text}\n\nUse mcp_info to check the schema, fix the args, and retry — or try a different tool.`,
+			is_error: true,
+		};
+	}
+
+	if (!text?.trim()) {
+		return {
+			type: "tool_result",
+			tool_use_id: toolUse.id,
+			content: `mcp_exec ${input.server}/${input.tool} returned empty content. Try a different tool or different args.`,
+			is_error: true,
+		};
+	}
+
+	captured.set(toolUse.id, { server: input.server, tool: input.tool, args, content: text, mimeType: "text/markdown" });
+	const preview =
+		text.length > PREVIEW_CHARS
+			? `${text.slice(0, PREVIEW_CHARS)}\n\n[... ${text.length - PREVIEW_CHARS} more chars truncated. Full content (${text.length} chars total) is captured by the harness with exec_call_id="${toolUse.id}". Call accept_content with this id to save it.]`
+			: `${text}\n\n[Full content (${text.length} chars) captured by the harness with exec_call_id="${toolUse.id}". Call accept_content with this id to save it.]`;
+	return { type: "tool_result", tool_use_id: toolUse.id, content: preview };
+}
+
+/**
+ * Extract a single string out of an MCP CallToolResult envelope. Mirrors
+ * the heterogeneous shapes mcpx tools return; tolerates string content,
+ * `text` fields, and the array-of-content-blocks shape.
+ */
+function extractText(result: { content?: unknown } | unknown): string {
+	if (typeof result === "string") return result;
+	if (!result || typeof result !== "object") return "";
+	const r = result as Record<string, unknown>;
+	if (typeof r.text === "string") return r.text;
+	if (typeof r.content === "string") return r.content;
+	if (typeof r.markdown === "string") return r.markdown;
+	if (Array.isArray(r.content)) {
+		const out: string[] = [];
+		for (const c of r.content) {
+			if (c && typeof c === "object") {
+				const inner = c as Record<string, unknown>;
+				if (typeof inner.text === "string") out.push(inner.text);
+			}
+		}
+		if (out.length > 0) return out.join("\n\n");
+	}
+	try {
+		return JSON.stringify(result);
+	} catch {
+		return "";
+	}
+}

package/src/ingest/fetcher.ts

@@ -1,6 +1,9 @@
+import type { LlmConfig } from "../config/schemas.ts";
 import { DEFAULTS } from "../constants.ts";
 import { asHelpful, HelpfulError } from "../errors.ts";
 import { logger } from "../output/logger.ts";
+import type { AgentMcpxAdapter } from "./agent-fetcher.ts";
+import { agentFetch } from "./agent-fetcher.ts";
 import { sha256Hex } from "./local-reader.ts";
 
 export interface FetchedRemote {
@@ -14,38 +17,40 @@ export interface FetchedRemote {
 	sourceUrl: string;
 }
 
-export interface McpxToolDescriptor {
-	server: string;
-	tool: { name: string; description?: string };
-}
-
-export interface McpxSearchHit {
-	server: string;
-	tool: { name: string; description?: string };
-	score?: number;
-}
-
 export interface FetchOptions {
 	/**
 	 * User-provided hint. Free-form keyword (e.g. "firecrawl", "github",
 	 * "google-docs", "http"). Special-cased: "http" forces plain fetch.
-	 * Otherwise the hint is used as a search query against the live
-	 * mcpx tool catalog — we never hardcode server names.
+	 * Otherwise the hint is passed verbatim to the agent loop as extra
+	 * guidance about which provider to prefer.
 	 */
 	hint?: string;
-	/** Live mcpx adapter. Use listTools/search/exec to find a fetcher on the fly. */
-	mcpx?: {
-		exec(server: string, tool: string, args: Record<string, unknown>): Promise<unknown>;
-		listTools(): Promise<McpxToolDescriptor[]>;
-		search?(query: string): Promise<McpxSearchHit[]>;
-	} | null;
+	/** Live mcpx adapter the agent loop drives via search/list/info/exec. */
+	mcpx?: AgentMcpxAdapter | null;
+	/**
+	 * LLM config. The agent loop needs an Anthropic key; without one the
+	 * mcpx path is skipped and we fall back to plain HTTP.
+	 */
+	llm?: LlmConfig;
 }
 
 /**
- * Fetch a remote URL, preferring an mcpx-managed server (Firecrawl, Google
- * Docs, GitHub, …) for known providers and falling back to a plain `fetch`
- * otherwise. The chosen invocation (server/tool/args) is returned alongside
- * the bytes so the caller can persist it on the row for replay-on-refresh.
+ * Fetch a remote URL.
+ *
+ * - `--fetcher http` (or no mcpx, or no LLM key) → plain HTTP.
+ * - Otherwise → multi-turn agent loop: Claude is given mcpx tools
+ *   (search/list/info/exec) and decides how to retrieve the URL,
+ *   including multi-step flows (start a job → poll → download).
+ *   The agent's selected mcp_exec invocation is recorded on the
+ *   returned row so refresh can replay it deterministically without
+ *   another agent round-trip.
+ *
+ * If the agent decides plain HTTP is the right call (`request_http_fallback`,
+ * no tool calls, max turns) we transparently fall through to `httpFetch`.
+ * If the agent reports an actionable failure, we surface that as a
+ * `HelpfulError`. If mcpx is configured but the LLM key is missing AND
+ * the HTTP fallback also fails, we surface an `auth_error` naming the env
+ * var so users see the real cause instead of a misleading 401.
  */
 export async function fetchRemote(url: string, options: FetchOptions = {}): Promise<FetchedRemote> {
 	const mcpx = options.mcpx;
@@ -54,8 +59,46 @@ export async function fetchRemote(url: string, options: FetchOptions = {}): Prom
 	if (hint === "http") return httpFetch(url);
 	if (!mcpx) return httpFetch(url);
 
-	const tried = await tryMcpx(url, mcpx, hint);
-	if (tried) return tried;
+	const apiKey = options.llm?.anthropic_api_key?.trim();
+	if (!apiKey) {
+		// No way to drive the agent. Try HTTP; if that fails, the user
+		// almost certainly wanted mcpx — surface a clear key-missing error.
+		try {
+			return await httpFetch(url);
+		} catch (err) {
+			if (err instanceof HelpfulError && err.kind === "network_error") {
+				throw new HelpfulError({
+					kind: "auth_error",
+					message: `${url} couldn't be fetched directly (${err.message}). Membot has mcpx configured, but routing through it requires Claude to translate the URL into the right tool arguments — and ANTHROPIC_API_KEY isn't set.`,
+					hint: `Set ANTHROPIC_API_KEY in your environment (or under llm.anthropic_api_key in ~/.membot/config.json), then retry. To force the HTTP path explicitly, run \`membot add ${url} --fetcher http\`.`,
+				});
+			}
+			throw err;
+		}
+	}
+
+	let outcome: Awaited<ReturnType<typeof agentFetch>>;
+	try {
+		outcome = await agentFetch({ url, mcpx, llm: options.llm!, hint });
+	} catch (err) {
+		if (err instanceof HelpfulError) throw err;
+		logger.warn(`agent-fetch failed (${err instanceof Error ? err.message : String(err)}) — falling back to HTTP`);
+		return httpFetch(url);
+	}
+
+	if (outcome.kind === "accepted") {
+		return {
+			bytes: outcome.result.bytes,
+			sha256: outcome.result.sha256,
+			mimeType: outcome.result.mimeType,
+			fetcher: "mcpx",
+			fetcherServer: outcome.result.fetcherServer,
+			fetcherTool: outcome.result.fetcherTool,
+			fetcherArgs: outcome.result.fetcherArgs,
+			sourceUrl: url,
+		};
+	}
+	logger.debug(`agent-fetch fell back to HTTP: ${outcome.reason}`);
 	return httpFetch(url);
 }
 
@@ -71,7 +114,7 @@ async function httpFetch(url: string): Promise<FetchedRemote> {
 		throw asHelpful(
 			err,
 			`while fetching ${url}`,
-			`Check your network and that ${url} is reachable. For mcpx-managed sources (gdocs/github/firecrawl), set --fetcher firecrawl etc.`,
+			`Check your network and that ${url} is reachable. For mcpx-managed sources (gdocs/github/firecrawl), set ANTHROPIC_API_KEY so membot can drive an mcpx tool.`,
 			"network_error",
 		);
 	}
@@ -79,7 +122,7 @@ async function httpFetch(url: string): Promise<FetchedRemote> {
 		throw new HelpfulError({
 			kind: "network_error",
 			message: `HTTP ${resp.status} ${resp.statusText}: ${url}`,
-			hint: "Verify the URL is reachable and not gated behind auth. For private docs use mcpx via --fetcher.",
+			hint: "Verify the URL is reachable and not gated behind auth. For private docs use mcpx (set ANTHROPIC_API_KEY).",
 		});
 	}
 	const bytes = new Uint8Array(await resp.arrayBuffer());
@@ -98,183 +141,13 @@ async function httpFetch(url: string): Promise<FetchedRemote> {
 }
 
 /**
- * Attempt to fetch via mcpx by discovering a suitable tool at runtime.
- *
- * Strategy:
- *   1. If the user passed a hint, search for it via mcpx.search() (semantic
- *      tool search over the live catalog). The hint is the user's free-text
- *      label for which provider they want — we never assume server names.
- *   2. Otherwise, fall back to a host-based search query (e.g. URL host
- *      "github.com" → search for "github fetch markdown").
- *   3. From the returned candidates, prefer tools whose name or description
- *      signals markdown output. Failing that, the first tool that takes a
- *      URL-shaped argument.
- *   4. Execute the tool with `{ url, format: "markdown" }`-shaped args.
- *      If exec fails, return null so the caller falls back to plain HTTP.
- */
-async function tryMcpx(
-	url: string,
-	mcpx: NonNullable<FetchOptions["mcpx"]>,
-	hint: string | undefined,
-): Promise<FetchedRemote | null> {
-	const candidates = await discoverCandidates(url, mcpx, hint);
-	if (candidates.length === 0) return null;
-
-	const chosen = pickTool(candidates);
-	if (!chosen) return null;
-
-	const args = buildArgs(chosen.tool.name, url);
-	let result: unknown;
-	try {
-		result = await mcpx.exec(chosen.server, chosen.tool.name, args);
-	} catch (err) {
-		logger.warn(
-			`mcpx: ${chosen.server}/${chosen.tool.name} failed (${err instanceof Error ? err.message : String(err)})`,
-		);
-		return null;
-	}
-
-	const text = extractText(result);
-	if (!text || text.trim().length === 0) return null;
-	const bytes = new TextEncoder().encode(text);
-	return {
-		bytes,
-		sha256: sha256Hex(bytes),
-		mimeType: "text/markdown",
-		fetcher: "mcpx",
-		fetcherServer: chosen.server,
-		fetcherTool: chosen.tool.name,
-		fetcherArgs: args,
-		sourceUrl: url,
-	};
-}
-
-/**
- * Build a list of candidate fetcher tools by querying mcpx's live catalog.
- * Tries semantic search first (using the hint or the URL's host as the
- * query) then falls back to listing all tools and filtering by name. Never
- * hardcodes a server name — the catalog is the source of truth.
- */
-async function discoverCandidates(
-	url: string,
-	mcpx: NonNullable<FetchOptions["mcpx"]>,
-	hint: string | undefined,
-): Promise<McpxToolDescriptor[]> {
-	const host = safeHost(url);
-	const queries = buildQueries(hint, host);
-
-	if (mcpx.search) {
-		for (const q of queries) {
-			try {
-				const hits = await mcpx.search(q);
-				if (hits.length > 0) {
-					return hits.slice(0, 5).map((h) => ({ server: h.server, tool: h.tool }));
-				}
-			} catch (err) {
-				logger.debug(`mcpx: search(${q}) failed (${err instanceof Error ? err.message : String(err)})`);
-			}
-		}
-	}
-
-	let tools: McpxToolDescriptor[];
-	try {
-		tools = await mcpx.listTools();
-	} catch (err) {
-		logger.debug(`mcpx: listTools failed (${err instanceof Error ? err.message : String(err)})`);
-		return [];
-	}
-
-	const lowercaseHaystack = (t: McpxToolDescriptor) =>
-		`${t.server} ${t.tool.name} ${t.tool.description ?? ""}`.toLowerCase();
-
-	if (hint) {
-		const needle = hint.toLowerCase();
-		const matched = tools.filter((t) => lowercaseHaystack(t).includes(needle));
-		if (matched.length > 0) return matched;
-	}
-
-	if (host) {
-		const tokens = host.split(".");
-		const matched = tools.filter((t) => tokens.some((tok) => tok.length > 2 && lowercaseHaystack(t).includes(tok)));
-		if (matched.length > 0) return matched;
-	}
-
-	// Fall back to any tool that looks like a URL fetcher.
-	return tools.filter((t) => /fetch|scrape|http|url/i.test(`${t.tool.name} ${t.tool.description ?? ""}`));
-}
-
-/** Compose semantic-search queries to feed mcpx.search. */
-function buildQueries(hint: string | undefined, host: string | null): string[] {
-	const out: string[] = [];
-	if (hint) out.push(`${hint} fetch markdown`);
-	if (host) out.push(`fetch ${host} as markdown`, `scrape ${host}`);
-	out.push("fetch URL as markdown", "scrape webpage to markdown");
-	return out;
-}
-
-/** URL → hostname or null. */
-function safeHost(url: string): string | null {
-	try {
-		return new URL(url).hostname.toLowerCase();
-	} catch {
-		return null;
-	}
-}
-
-/**
- * Among the candidate tools, prefer one whose name or description signals
- * markdown output (contains "markdown", "md", "Docmd", etc.). Falls back
- * to anything that looks like a generic fetch/scrape verb, and finally
- * to the first candidate so we always try something.
- */
-function pickTool(tools: McpxToolDescriptor[]): McpxToolDescriptor | null {
-	const score = (t: McpxToolDescriptor) => {
-		const hay = `${t.tool.name} ${t.tool.description ?? ""}`.toLowerCase();
-		let s = 0;
-		if (/markdown|docmd|asmd|\bmd\b/.test(hay)) s += 5;
-		if (/scrape|extract|fetch|get|read/.test(hay)) s += 2;
-		if (/url|web|html|page/.test(hay)) s += 1;
-		return s;
-	};
-	const sorted = [...tools].sort((a, b) => score(b) - score(a));
-	return sorted[0] ?? null;
-}
-
-/**
- * Build the argument object the mcpx fetcher tool likely accepts. We can't
- * know the schema without calling info(), so we build a permissive bag with
- * the common shapes (`{url, format: "markdown", formats: ["markdown"]}`)
- * and trust the underlying tool to ignore unknown fields.
+ * Detect MCP `CallToolResult` envelopes that signal tool failure. MCP
+ * tool errors don't throw — they return `{ isError: true, content: [...] }`
+ * — so callers must check this explicitly before treating the content
+ * as a successful payload. Used by the refresh runner; the agent loop
+ * has its own preview-aware check.
  */
-function buildArgs(toolName: string, url: string): Record<string, unknown> {
-	const args: Record<string, unknown> = { url };
-	if (/markdown|md/i.test(toolName)) args.format = "markdown";
-	args.formats = ["markdown"];
-	return args;
-}
-
-/** Pull a string out of the heterogeneous shapes mcpx tools return. */
-function extractText(result: unknown): string {
-	if (typeof result === "string") return result;
-	if (result && typeof result === "object") {
-		const maybe = result as Record<string, unknown>;
-		if (typeof maybe.text === "string") return maybe.text;
-		if (typeof maybe.content === "string") return maybe.content;
-		if (typeof maybe.markdown === "string") return maybe.markdown;
-		if (Array.isArray(maybe.content)) {
-			const out: string[] = [];
-			for (const c of maybe.content) {
-				if (c && typeof c === "object") {
-					const inner = c as Record<string, unknown>;
-					if (typeof inner.text === "string") out.push(inner.text);
-				}
-			}
-			if (out.length > 0) return out.join("\n\n");
-		}
-	}
-	try {
-		return JSON.stringify(result);
-	} catch {
-		return "";
-	}
+export function isMcpToolError(result: unknown): boolean {
+	if (!result || typeof result !== "object") return false;
+	return (result as { isError?: unknown }).isError === true;
 }

package/src/ingest/ingest.ts

@@ -3,6 +3,7 @@ import { upsertBlob } from "../db/blobs.ts";
 import { insertChunksForVersion, rebuildFts } from "../db/chunks.ts";
 import { type FetcherKind, getCurrent, insertVersion, millisIso, type SourceType } from "../db/files.ts";
 import { asHelpful, HelpfulError } from "../errors.ts";
+import { logger } from "../output/logger.ts";
 import { chunkDeterministic } from "./chunker.ts";
 import { convert } from "./converter/index.ts";
 import { describe } from "./describer.ts";
@@ -188,12 +189,32 @@ async function ingestUrl(
 ): Promise<IngestResult> {
 	const mcpxAdapter = ctx.mcpx
 		? {
-				async listTools() {
-					const tools = await ctx.mcpx!.listTools();
-					return tools;
+				async search(query: string, options?: { keywordOnly?: boolean; semanticOnly?: boolean }) {
+					try {
+						const results = await ctx.mcpx!.search(query, options);
+						return results.map((r) => ({
+							server: r.server,
+							tool: r.tool,
+							description: r.description ?? undefined,
+							score: r.score,
+							matchType: r.matchType ?? undefined,
+						}));
+					} catch (err) {
+						logger.debug(`mcpx.search(${query}) failed: ${err instanceof Error ? err.message : String(err)}`);
+						return [];
+					}
 				},
-				async exec(server: string, tool: string, args: Record<string, unknown>) {
-					return ctx.mcpx!.exec(server, tool, args);
+				async listTools(server?: string) {
+					const tools = await ctx.mcpx!.listTools(server);
+					return tools.map((t) => ({ server: t.server, tool: { name: t.tool.name, description: t.tool.description } }));
+				},
+				async info(server: string, tool: string) {
+					const t = await ctx.mcpx!.info(server, tool);
+					if (!t) return undefined;
+					return { name: t.name, description: t.description, inputSchema: t.inputSchema };
+				},
+				async exec(server: string, tool: string, args?: Record<string, unknown>) {
+					return ctx.mcpx!.exec(server, tool, args ?? {});
 				},
 			}
 		: null;
@@ -212,7 +233,11 @@ async function ingestUrl(
 	};
 
 	try {
-		const fetched = await fetchRemote(url, { hint: input.fetcher_hint, mcpx: mcpxAdapter });
+		const fetched = await fetchRemote(url, {
+			hint: input.fetcher_hint,
+			mcpx: mcpxAdapter,
+			llm: ctx.config.llm,
+		});
 		result.mime_type = fetched.mimeType;
 		result.size_bytes = fetched.bytes.byteLength;
 		result.fetcher = fetched.fetcher;
@@ -583,6 +608,7 @@ function summarize(entries: IngestEntryResult[]): IngestResult {
 }
 
 function errorMessage(err: unknown): string {
+	if (err instanceof HelpfulError) return `${err.message} — ${err.hint}`;
 	if (err instanceof Error) return err.message;
 	return String(err);
 }

package/src/refresh/runner.ts

@@ -8,7 +8,7 @@ import { chunkDeterministic } from "../ingest/chunker.ts";
 import { convert } from "../ingest/converter/index.ts";
 import { describe } from "../ingest/describer.ts";
 import { embed } from "../ingest/embedder.ts";
-import { fetchRemote } from "../ingest/fetcher.ts";
+import { fetchRemote, isMcpToolError } from "../ingest/fetcher.ts";
 import { mimeFromPath, readLocalFile, sha256Hex } from "../ingest/local-reader.ts";
 import { buildSearchText } from "../ingest/search-text.ts";
 
@@ -192,6 +192,14 @@ async function replayFetch(
 	if (cur.fetcher === "mcpx" && cur.fetcher_server && cur.fetcher_tool && mcpx) {
 		const args = cur.fetcher_args ?? {};
 		const result = await mcpx.exec(cur.fetcher_server, cur.fetcher_tool, args);
+		if (isMcpToolError(result)) {
+			const detail = extractText(result).trim();
+			throw new HelpfulError({
+				kind: "network_error",
+				message: `mcpx tool ${cur.fetcher_server}/${cur.fetcher_tool} returned isError=true${detail ? `: ${detail}` : ""}`,
+				hint: `Re-add with a working fetcher: \`membot remove ${cur.logical_path}\` then \`membot add ${cur.source_path} --fetcher http\` (or another --fetcher hint).`,
+			});
+		}
 		const text = extractText(result);
 		const bytes = new TextEncoder().encode(text);
 		return {