@nghyane/arcane 0.1.0

package/src/web/search/providers/zai.ts

@@ -0,0 +1,352 @@
+/**
+ * Z.AI Web Search Provider
+ *
+ * Calls Z.AI's remote MCP server (`webSearchPrime`) and adapts results into
+ * the unified SearchResponse shape used by the web search tool.
+ */
+import { getEnvApiKey } from "@nghyane/arcane-ai";
+import { getAgentDbPath } from "@nghyane/arcane-utils/dirs";
+import { AgentStorage } from "../../../session/agent-storage";
+
+import type { SearchResponse, SearchSource } from "../../../web/search/types";
+import { SearchProviderError } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+
+const ZAI_MCP_URL = "https://api.z.ai/api/mcp/web_search_prime/mcp";
+const ZAI_TOOL_NAME = "webSearchPrime";
+const DEFAULT_NUM_RESULTS = 10;
+
+export interface ZaiSearchParams {
+	query: string;
+	num_results?: number;
+}
+
+interface ZaiSearchResult {
+	title?: string;
+	content?: string;
+	link?: string;
+	url?: string;
+	media?: string;
+	publish_date?: string;
+	publishedDate?: string;
+}
+
+interface ZaiWebSearchResponse {
+	id?: string;
+	request_id?: string;
+	requestId?: string;
+	search_result?: ZaiSearchResult[];
+	results?: ZaiSearchResult[];
+}
+
+interface JsonRpcError {
+	code?: number;
+	message?: string;
+}
+
+interface JsonRpcPayload {
+	result?: unknown;
+	error?: JsonRpcError;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+	return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
+}
+
+function asString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+/**
+ * Finds Z.AI API credentials from environment or saved auth storage.
+ * Priority: ZAI_API_KEY env var, then credentials stored under provider "zai".
+ */
+export async function findApiKey(): Promise<string | null> {
+	const envKey = getEnvApiKey("zai");
+	if (envKey) return envKey;
+
+	try {
+		const storage = await AgentStorage.open(getAgentDbPath());
+		const records = storage.listAuthCredentials("zai");
+		for (const record of records) {
+			const credential = record.credential;
+			if (credential.type === "api_key" && credential.key.trim().length > 0) {
+				return credential.key;
+			}
+			if (credential.type === "oauth" && credential.access.trim().length > 0) {
+				return credential.access;
+			}
+		}
+	} catch {
+		return null;
+	}
+
+	return null;
+}
+
+function dateToAgeSeconds(dateStr: string | undefined): number | undefined {
+	if (!dateStr) return undefined;
+	try {
+		const date = new Date(dateStr);
+		if (Number.isNaN(date.getTime())) return undefined;
+		return Math.floor((Date.now() - date.getTime()) / 1000);
+	} catch {
+		return undefined;
+	}
+}
+
+async function callZaiTool(apiKey: string, args: Record<string, unknown>): Promise<unknown> {
+	const response = await fetch(ZAI_MCP_URL, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${apiKey}`,
+			"Content-Type": "application/json",
+			Accept: "application/json, text/event-stream",
+		},
+		body: JSON.stringify({
+			jsonrpc: "2.0",
+			id: crypto.randomUUID(),
+			method: "tools/call",
+			params: {
+				name: ZAI_TOOL_NAME,
+				arguments: args,
+			},
+		}),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new SearchProviderError("zai", `Z.AI MCP error (${response.status}): ${errorText}`, response.status);
+	}
+
+	const rawText = await response.text();
+
+	const parsedMessages: unknown[] = [];
+	for (const line of rawText.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed.startsWith("data:")) continue;
+		const data = trimmed.slice(5).trim();
+		if (!data) continue;
+		try {
+			parsedMessages.push(JSON.parse(data));
+		} catch {
+			// Ignore non-JSON data events.
+		}
+	}
+
+	if (parsedMessages.length === 0) {
+		try {
+			parsedMessages.push(JSON.parse(rawText));
+		} catch {
+			throw new SearchProviderError("zai", "Failed to parse Z.AI MCP response", 500);
+		}
+	}
+
+	const parsed = parsedMessages[parsedMessages.length - 1];
+	const parsedRecord = asRecord(parsed);
+	const directErrorCode = typeof parsedRecord?.code === "number" ? parsedRecord.code : undefined;
+	const directErrorSuccess = parsedRecord?.success;
+	const directErrorMessage =
+		asString(parsedRecord?.msg) ?? asString(parsedRecord?.message) ?? asString(parsedRecord?.error_message);
+	if (directErrorSuccess === false && directErrorMessage) {
+		throw new SearchProviderError(
+			"zai",
+			`Z.AI API error${directErrorCode ? ` (${directErrorCode})` : ""}: ${directErrorMessage}`,
+			directErrorCode,
+		);
+	}
+
+	const payload = parsed as JsonRpcPayload;
+	if (payload.error) {
+		const status = typeof payload.error.code === "number" ? payload.error.code : 400;
+		throw new SearchProviderError(
+			"zai",
+			`Z.AI MCP error${payload.error.code ? ` (${payload.error.code})` : ""}: ${payload.error.message ?? "Unknown error"}`,
+			status,
+		);
+	}
+
+	const resultRecord = asRecord(payload.result);
+	if (resultRecord?.isError === true) {
+		const content = Array.isArray(resultRecord.content) ? resultRecord.content : [];
+		const errorText = content
+			.map(item => asString(asRecord(item)?.text))
+			.filter((text): text is string => text !== undefined)
+			.join("\n")
+			.trim();
+		const statusMatch = errorText.match(/MCP error\s*(-?\d+)/i);
+		const statusCode = statusMatch ? Math.abs(Number.parseInt(statusMatch[1], 10)) : 400;
+		throw new SearchProviderError("zai", errorText || "Z.AI MCP tool call failed", statusCode);
+	}
+
+	if (payload.result !== undefined) {
+		return payload.result;
+	}
+
+	return parsed;
+}
+
+async function callZaiSearch(apiKey: string, params: ZaiSearchParams): Promise<unknown> {
+	const count = params.num_results ?? DEFAULT_NUM_RESULTS;
+	const attempts: Record<string, unknown>[] = [
+		{ query: params.query, count },
+		{ search_query: params.query, count },
+		{ search_query: params.query, search_engine: "search-prime", count },
+	];
+
+	let lastError: unknown;
+	for (let i = 0; i < attempts.length; i++) {
+		try {
+			return await callZaiTool(apiKey, attempts[i]);
+		} catch (error) {
+			lastError = error;
+			const isLastAttempt = i === attempts.length - 1;
+			if (isLastAttempt) {
+				throw error;
+			}
+			if (!(error instanceof SearchProviderError)) {
+				throw error;
+			}
+			const message = error.message.toLowerCase();
+			const looksLikeArgError =
+				error.status === 400 ||
+				message.includes("invalid") ||
+				message.includes("argument") ||
+				message.includes("search_query") ||
+				message.includes("query");
+			if (!looksLikeArgError) {
+				throw error;
+			}
+		}
+	}
+
+	throw lastError ?? new SearchProviderError("zai", "Z.AI search failed", 500);
+}
+
+function getSearchResults(value: unknown): ZaiSearchResult[] {
+	if (Array.isArray(value)) {
+		return value as ZaiSearchResult[];
+	}
+	const obj = asRecord(value);
+	if (!obj) return [];
+
+	const searchResult = obj.search_result;
+	if (Array.isArray(searchResult)) return searchResult as ZaiSearchResult[];
+
+	const results = obj.results;
+	if (Array.isArray(results)) return results as ZaiSearchResult[];
+
+	return [];
+}
+
+function parseSearchPayload(rawResult: unknown): {
+	results: ZaiSearchResult[];
+	answer?: string;
+	requestId?: string;
+} {
+	const candidates: unknown[] = [rawResult];
+	const textParts: string[] = [];
+
+	const root = asRecord(rawResult);
+	if (root) {
+		if (root.structuredContent) candidates.push(root.structuredContent);
+		if (root.data) candidates.push(root.data);
+		if (root.result) candidates.push(root.result);
+
+		const content = root.content;
+		if (Array.isArray(content)) {
+			for (const part of content) {
+				const partObj = asRecord(part);
+				const text = asString(partObj?.text);
+				if (!text) continue;
+				textParts.push(text);
+				try {
+					candidates.push(JSON.parse(text));
+				} catch {
+					// Not JSON payload; keep as fallback answer text.
+				}
+			}
+		}
+	}
+
+	for (const candidate of candidates) {
+		const results = getSearchResults(candidate);
+		if (results.length > 0) {
+			const obj = asRecord(candidate) as ZaiWebSearchResponse | null;
+			return {
+				results,
+				answer: textParts.length > 0 ? textParts.join("\n\n") : undefined,
+				requestId: obj?.request_id ?? obj?.requestId ?? obj?.id,
+			};
+		}
+	}
+
+	return {
+		results: [],
+		answer: textParts.length > 0 ? textParts.join("\n\n") : undefined,
+	};
+}
+
+function toSources(results: ZaiSearchResult[]): SearchSource[] {
+	const sources: SearchSource[] = [];
+	for (const result of results) {
+		const url = asString(result.link) ?? asString(result.url);
+		if (!url) continue;
+
+		const publishedDate = asString(result.publish_date) ?? asString(result.publishedDate);
+		sources.push({
+			title: asString(result.title) ?? url,
+			url,
+			snippet: asString(result.content),
+			publishedDate,
+			ageSeconds: dateToAgeSeconds(publishedDate),
+			author: asString(result.media),
+		});
+	}
+	return sources;
+}
+
+/** Execute Z.AI web search via remote MCP endpoint. */
+export async function searchZai(params: ZaiSearchParams): Promise<SearchResponse> {
+	const apiKey = await findApiKey();
+	if (!apiKey) {
+		throw new Error("Z.AI credentials not found. Set ZAI_API_KEY or login with 'arc /login zai'.");
+	}
+
+	const rawResult = await callZaiSearch(apiKey, params);
+	const payload = parseSearchPayload(rawResult);
+	let sources = toSources(payload.results);
+
+	if (params.num_results && sources.length > params.num_results) {
+		sources = sources.slice(0, params.num_results);
+	}
+
+	return {
+		provider: "zai",
+		answer: payload.answer,
+		sources,
+		requestId: payload.requestId,
+	};
+}
+
+/** Search provider for Z.AI web search MCP. */
+export class ZaiProvider extends SearchProvider {
+	readonly id = "zai";
+	readonly label = "Z.AI";
+
+	async isAvailable(): Promise<boolean> {
+		try {
+			return !!(await findApiKey());
+		} catch {
+			return false;
+		}
+	}
+
+	search(params: SearchParams): Promise<SearchResponse> {
+		return searchZai({
+			query: params.query,
+			num_results: params.numSearchResults ?? params.limit,
+		});
+	}
+}

package/src/web/search/render.ts

@@ -0,0 +1,299 @@
+/**
+ * Web Search TUI Rendering
+ *
+ * Tree-based rendering with collapsed/expanded states for web search results.
+ */
+
+import type { Component } from "@nghyane/arcane-tui";
+import { Text, visibleWidth, wrapTextWithAnsi } from "@nghyane/arcane-tui";
+import type { RenderResultOptions } from "../../extensibility/custom-tools/types";
+import type { Theme } from "../../modes/theme/theme";
+import {
+	formatAge,
+	formatCount,
+	formatExpandHint,
+	formatMoreItems,
+	formatStatusIcon,
+	getDomain,
+	getPreviewLines,
+	PREVIEW_LIMITS,
+	TRUNCATE_LENGTHS,
+	truncateToWidth,
+} from "../../tools/render-utils";
+import { renderStatusLine, renderTreeList } from "../../tui";
+import { CachedOutputBlock } from "../../tui/output-block";
+import { getSearchProvider } from "./provider";
+import type { SearchResponse } from "./types";
+
+const MAX_COLLAPSED_ANSWER_LINES = PREVIEW_LIMITS.COLLAPSED_LINES;
+const MAX_EXPANDED_ANSWER_LINES = PREVIEW_LIMITS.EXPANDED_LINES;
+const MAX_ANSWER_LINE_LEN = TRUNCATE_LENGTHS.LINE;
+const MAX_SNIPPET_LINES = 2;
+const MAX_SNIPPET_LINE_LEN = TRUNCATE_LENGTHS.LINE;
+const MAX_COLLAPSED_ITEMS = PREVIEW_LIMITS.COLLAPSED_ITEMS;
+const MAX_QUERY_PREVIEW = 2;
+const MAX_QUERY_LEN = 90;
+const MAX_REQUEST_ID_LEN = 36;
+
+function renderFallbackText(contentText: string, expanded: boolean, theme: Theme): Component {
+	const lines = contentText.split("\n").filter(line => line.trim());
+	const maxLines = expanded ? lines.length : 6;
+	const displayLines = lines.slice(0, maxLines).map(line => truncateToWidth(line.trim(), 110));
+	const remaining = lines.length - displayLines.length;
+
+	const headerIcon = formatStatusIcon("warning", theme);
+	const expandHint = formatExpandHint(theme, expanded, remaining > 0);
+	let text = `${headerIcon} ${theme.fg("dim", "Response")}${expandHint}`;
+
+	if (displayLines.length === 0) {
+		text += `\n ${theme.fg("dim", theme.tree.last)} ${theme.fg("muted", "No response data")}`;
+		return new Text(text, 0, 0);
+	}
+
+	for (let i = 0; i < displayLines.length; i++) {
+		const isLast = i === displayLines.length - 1 && remaining === 0;
+		const branch = isLast ? theme.tree.last : theme.tree.branch;
+		text += `\n ${theme.fg("dim", branch)} ${theme.fg("dim", displayLines[i])}`;
+	}
+
+	if (!expanded && remaining > 0) {
+		text += `\n ${theme.fg("dim", theme.tree.last)} ${theme.fg("muted", formatMoreItems(remaining, "line"))}`;
+	}
+
+	return new Text(text, 0, 0);
+}
+
+export interface SearchRenderDetails {
+	response: SearchResponse;
+	error?: string;
+}
+
+/** Render web search result with tree-based layout */
+export function renderSearchResult(
+	result: { content: Array<{ type: string; text?: string }>; details?: SearchRenderDetails },
+	options: RenderResultOptions,
+	theme: Theme,
+	args?: {
+		query?: string;
+		provider?: string;
+		allowLongAnswer?: boolean;
+		maxAnswerLines?: number;
+	},
+): Component {
+	const details = result.details;
+
+	// Handle error case
+	if (details?.error) {
+		return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
+	}
+
+	const rawText = result.content?.find(block => block.type === "text")?.text?.trim() ?? "";
+	const response = details?.response;
+	if (!response) {
+		return renderFallbackText(rawText, options.expanded, theme);
+	}
+
+	const sources = Array.isArray(response.sources) ? response.sources : [];
+	const sourceCount = sources.length;
+	const citations = Array.isArray(response.citations) ? response.citations : [];
+	const citationCount = citations.length;
+	const searchQueries = Array.isArray(response.searchQueries)
+		? response.searchQueries.filter(item => typeof item === "string")
+		: [];
+	const provider = response.provider;
+
+	// Get answer text
+	const answerText = typeof response.answer === "string" ? response.answer.trim() : "";
+	const contentText = answerText || rawText;
+	const answerLines = contentText
+		? contentText
+				.split("\n")
+				.filter(l => l.trim())
+				.map(l => l.trim())
+		: [];
+	const totalAnswerLines = answerLines.length;
+
+	const providerLabel = provider !== "none" ? getSearchProvider(provider).label : "None";
+	const queryPreview = args?.query
+		? truncateToWidth(args.query, 80)
+		: searchQueries[0]
+			? truncateToWidth(searchQueries[0], 80)
+			: undefined;
+	const header = renderStatusLine(
+		{
+			icon: sourceCount > 0 ? "success" : "warning",
+			title: "Web Search",
+			description: providerLabel,
+			meta: [formatCount("source", sourceCount)],
+		},
+		theme,
+	);
+
+	const metaLines: string[] = [];
+	metaLines.push(`${theme.fg("muted", "Provider:")} ${theme.fg("text", providerLabel)}`);
+	if (response.authMode)
+		metaLines.push(
+			`${theme.fg("muted", "Auth:")} ${theme.fg("text", response.authMode === "oauth" ? "OAuth" : response.authMode === "api_key" ? "API key" : response.authMode)}`,
+		);
+	if (response.model) metaLines.push(`${theme.fg("muted", "Model:")} ${theme.fg("text", response.model)}`);
+	metaLines.push(`${theme.fg("muted", "Sources:")} ${theme.fg("text", String(sourceCount))}`);
+	if (citationCount > 0)
+		metaLines.push(`${theme.fg("muted", "Citations:")} ${theme.fg("text", String(citationCount))}`);
+	if (response.usage) {
+		const usageParts: string[] = [];
+		if (response.usage.inputTokens !== undefined) usageParts.push(`in ${response.usage.inputTokens}`);
+		if (response.usage.outputTokens !== undefined) usageParts.push(`out ${response.usage.outputTokens}`);
+		if (response.usage.totalTokens !== undefined) usageParts.push(`total ${response.usage.totalTokens}`);
+		if (response.usage.searchRequests !== undefined) usageParts.push(`search ${response.usage.searchRequests}`);
+		if (usageParts.length > 0)
+			metaLines.push(`${theme.fg("muted", "Usage:")} ${theme.fg("text", usageParts.join(theme.sep.dot))}`);
+	}
+	if (response.requestId) {
+		metaLines.push(
+			`${theme.fg("muted", "Request:")} ${theme.fg("text", truncateToWidth(response.requestId, MAX_REQUEST_ID_LEN))}`,
+		);
+	}
+	if (searchQueries.length > 0) {
+		const queriesPreview = searchQueries.slice(0, MAX_QUERY_PREVIEW);
+		const queryList = queriesPreview.map(q => truncateToWidth(q, MAX_QUERY_LEN));
+		const suffix = searchQueries.length > queriesPreview.length ? "…" : "";
+		metaLines.push(`${theme.fg("muted", "Queries:")} ${theme.fg("text", queryList.join("; "))}${suffix}`);
+	}
+
+	const outputBlock = new CachedOutputBlock();
+
+	return {
+		render(width: number): string[] {
+			// Read mutable state at render time
+			const { expanded } = options;
+
+			// Expanded-dependent computations
+			const answerLimit = expanded ? MAX_EXPANDED_ANSWER_LINES : MAX_COLLAPSED_ANSWER_LINES;
+			const answerPreview = contentText
+				? args?.allowLongAnswer
+					? answerLines.slice(0, args.maxAnswerLines ?? answerLines.length)
+					: getPreviewLines(contentText, answerLimit, MAX_ANSWER_LINE_LEN)
+				: [];
+			const remainingAnswer = totalAnswerLines - answerPreview.length;
+
+			const sourceTree = renderTreeList(
+				{
+					items: sources,
+					expanded,
+					maxCollapsed: MAX_COLLAPSED_ITEMS,
+					itemType: "source",
+					renderItem: src => {
+						const titleText =
+							typeof src.title === "string" && src.title.trim()
+								? src.title
+								: typeof src.url === "string" && src.url.trim()
+									? src.url
+									: "Untitled";
+						const title = truncateToWidth(titleText, 70);
+						const url = typeof src.url === "string" ? src.url : "";
+						const domain = url ? getDomain(url) : "";
+						const age =
+							formatAge(src.ageSeconds) || (typeof src.publishedDate === "string" ? src.publishedDate : "");
+						const metaParts: string[] = [];
+						if (domain) metaParts.push(theme.fg("dim", `(${domain})`));
+						if (typeof src.author === "string" && src.author.trim())
+							metaParts.push(theme.fg("muted", src.author));
+						if (age) metaParts.push(theme.fg("muted", age));
+						const metaSep = theme.fg("dim", theme.sep.dot);
+						const metaSuffix = metaParts.length > 0 ? ` ${metaParts.join(metaSep)}` : "";
+						const srcLines: string[] = [`${theme.fg("accent", title)}${metaSuffix}`];
+						const snippetText = typeof src.snippet === "string" ? src.snippet : "";
+						if (snippetText.trim()) {
+							const snippetLines = getPreviewLines(snippetText, MAX_SNIPPET_LINES, MAX_SNIPPET_LINE_LEN);
+							for (const snippetLine of snippetLines) {
+								srcLines.push(theme.fg("muted", `${theme.format.dash} ${snippetLine}`));
+							}
+						}
+						if (url) srcLines.push(theme.fg("mdLinkUrl", url));
+						return srcLines;
+					},
+				},
+				theme,
+			);
+
+			// Build answer section
+			const answerState = sourceCount > 0 ? "success" : "warning";
+			const borderColor: "warning" | "dim" = answerState === "warning" ? "warning" : "dim";
+			const border = (t: string) => theme.fg(borderColor, t);
+			const contentPrefix = border(`${theme.boxSharp.vertical} `);
+			const contentSuffix = border(theme.boxSharp.vertical);
+			const contentWidth = Math.max(0, width - visibleWidth(contentPrefix) - visibleWidth(contentSuffix));
+			const answerTreeLines = answerPreview.length > 0 ? answerPreview : ["No answer text returned"];
+			const answerTree = renderTreeList(
+				{
+					items: answerTreeLines,
+					expanded: true,
+					maxCollapsed: answerTreeLines.length,
+					itemType: "line",
+					renderItem: (line, context) => {
+						const coloredLine =
+							line === "No answer text returned" ? theme.fg("muted", line) : theme.fg("dim", line);
+						if (!args?.allowLongAnswer) {
+							return coloredLine;
+						}
+						const prefixWidth = visibleWidth(context.continuePrefix);
+						const wrapWidth = Math.max(10, contentWidth - prefixWidth);
+						return wrapTextWithAnsi(coloredLine, wrapWidth);
+					},
+				},
+				theme,
+			);
+			if (remainingAnswer > 0) {
+				answerTree.push(theme.fg("muted", formatMoreItems(remainingAnswer, "line")));
+			}
+
+			return outputBlock.render(
+				{
+					header,
+					state: sourceCount > 0 ? "success" : "warning",
+					sections: [
+						...(queryPreview
+							? [
+									{
+										lines: [`${theme.fg("muted", "Query:")} ${theme.fg("text", queryPreview)}`],
+									},
+								]
+							: []),
+						{
+							label: theme.fg("toolTitle", "Answer"),
+							lines: answerTree,
+						},
+						{
+							label: theme.fg("toolTitle", "Sources"),
+							lines: sourceTree.length > 0 ? sourceTree : [theme.fg("muted", "No sources returned")],
+						},
+						{ label: theme.fg("toolTitle", "Metadata"), lines: metaLines },
+					],
+					width,
+				},
+				theme,
+			);
+		},
+		invalidate() {
+			outputBlock.invalidate();
+		},
+	};
+}
+
+/** Render web search call (query preview) */
+export function renderSearchCall(
+	args: { query?: string; provider?: string; [key: string]: unknown },
+	_options: RenderResultOptions,
+	theme: Theme,
+): Component {
+	const provider = args.provider ?? "auto";
+	const query = truncateToWidth(args.query ?? "", 80);
+	const text = renderStatusLine({ icon: "pending", title: "Web Search", description: query, meta: [provider] }, theme);
+	return new Text(text, 0, 0);
+}
+
+export const webSearchToolRenderer = {
+	renderCall: renderSearchCall,
+	renderResult: renderSearchResult,
+	mergeCallAndResult: true,
+};