Skip to content

LLM Wiki is a cross-platform desktop application that turns your documents into an organized, interlinked knowledge base — automatically. Instead of traditional RAG (retrieve-and-answer from scratch every time), the LLM incrementally builds and maintains a persistent wiki from your sources。

TypeScript

feat: add rust backend chat agent

nash_su3b13c84505f0
diff --git a/README.md b/README.md
index 4d105984..f7c2df02 100644
--- a/README.md
+++ b/README.md
@@ -421,6 +421,7 @@ LLM Wiki ships a built-in local HTTP API at `http://127.0.0.1:19828` (token-prot
- `PATCH /api/v1/projects/{id}/reviews/{reviewId}` — update one Review item (JSON body `{ "resolved": true, "action": "label" }`; `resolved` defaults to true, pass false to reopen)
- `POST /api/v1/projects/{id}/reviews/resolve` — bulk-resolve Review items (JSON body `{ "ids": [...], "action": "label" }`), returns `{ resolved, notFound, count }`; the Review tab's Refresh button re-reads the result from disk
- `POST /api/v1/projects/{id}/search` — **hybrid** retrieval (keyword + vector) returning `mode`, `tokenHits`, `vectorHits`, per-result `vectorScore`
+- `POST /api/v1/projects/{id}/chat` — non-streaming backend Agent chat endpoint returning an assistant message, references, usage, and tool events for wiki/source/web/AnyTXT retrieval; `mode: "deep"` broadens evidence collection, while the full Deep Research workspace remains available in the desktop UI
- `GET /api/v1/projects/{id}/graph` — wikilinks graph
- `POST /api/v1/projects/{id}/sources/rescan` — trigger a backend rescan
diff --git a/mcp-server/README.md b/mcp-server/README.md
index 4dec94d8..bcdfd3ca 100644
--- a/mcp-server/README.md
+++ b/mcp-server/README.md
@@ -58,6 +58,7 @@ When API unauthenticated mode is enabled, omit `LLM_WIKI_API_TOKEN`. If MCP acce
- `llm_wiki_read_file`: read an allowed text file such as `wiki/index.md`.
- `llm_wiki_reviews`: list Review tab items. Defaults to unresolved items and supports `status`, `type`, and `limit` filters.
- `llm_wiki_search`: search with the app's shared keyword/vector backend.
+- `llm_wiki_chat`: ask the backend Agent chat endpoint and receive answer text, references, usage, and tool events. `mode: deep` broadens backend evidence collection; full Deep Research workflows still live in the desktop app.
- `llm_wiki_graph`: query the app's knowledge graph endpoint.
- `llm_wiki_rescan_sources`: trigger a Source Watch rescan using the user's configured rules.
diff --git a/mcp-server/src/api-client.ts b/mcp-server/src/api-client.ts
index cebb08d2..af078330 100644
--- a/mcp-server/src/api-client.ts
+++ b/mcp-server/src/api-client.ts
@@ -37,6 +37,46 @@ export interface ApiSearchResponse {
vectorHits?: number
}
+export interface ApiChatReference {
+ title: string
+ path: string
+ kind: string
+ snippet?: string
+ score?: number
+}
+
+export interface ApiChatToolEvent {
+ tool: string
+ status: string
+ detail?: string
+}
+
+export interface ApiChatEvent {
+ type: string
+ [key: string]: unknown
+}
+
+export interface ApiChatUsage {
+ promptChars?: number
+ completionChars?: number
+ referenceCount?: number
+ toolEventCount?: number
+}
+
+export interface ApiChatResponse {
+ projectId?: string
+ sessionId: string
+ mode?: string
+ message: {
+ role: string
+ content: string
+ }
+ references: ApiChatReference[]
+ toolEvents: ApiChatToolEvent[]
+ events: ApiChatEvent[]
+ usage?: ApiChatUsage
+}
+
export interface ApiGraphNode {
id: string
label: string
@@ -193,6 +233,50 @@ export class LlmWikiApiClient {
}
}
+ async chat(projectId = "current", message: string, options: { sessionId?: string; mode?: string; topK?: number; includeContent?: boolean; wiki?: boolean; web?: boolean; anytxt?: boolean; skills?: string[]; persistSession?: boolean } = {}): Promise<ApiChatResponse> {
+ const json = await this.request(`/projects/${encodeURIComponent(projectId)}/chat`, {
+ method: "POST",
+ body: {
+ message,
+ sessionId: options.sessionId,
+ persistSession: options.persistSession,
+ mode: options.mode,
+ topK: options.topK,
+ includeContent: options.includeContent,
+ tools: {
+ wiki: options.wiki ?? true,
+ web: options.web ?? false,
+ anytxt: options.anytxt ?? false,
+ },
+ skills: options.skills,
+ },
+ })
+ const msg = requireObject(json.message, "chat message")
+ return {
+ projectId: typeof json.projectId === "string" ? json.projectId : undefined,
+ sessionId: typeof json.sessionId === "string" ? json.sessionId : "",
+ mode: typeof json.mode === "string" ? json.mode : undefined,
+ message: {
+ role: typeof msg.role === "string" ? msg.role : "assistant",
+ content: typeof msg.content === "string" ? msg.content : "",
+ },
+ references: Array.isArray(json.references) ? json.references.map(parseChatReference) : [],
+ toolEvents: Array.isArray(json.toolEvents) ? json.toolEvents.map(parseChatToolEvent) : [],
+ events: Array.isArray(json.events) ? json.events.map(parseChatEvent) : [],
+ usage: parseChatUsage(json.usage),
+ }
+ }
+
+ async cancelChat(projectId = "current", sessionId: string): Promise<{ sessionId: string; cancelled: boolean }> {
+ const json = await this.request(`/projects/${encodeURIComponent(projectId)}/chat/${encodeURIComponent(sessionId)}/cancel`, {
+ method: "POST",
+ })
+ return {
+ sessionId: typeof json.sessionId === "string" ? json.sessionId : sessionId,
+ cancelled: json.cancelled === true,
+ }
+ }
+
async graph(projectId = "current", options: { q?: string; nodeType?: string; limit?: number } = {}): Promise<{ nodes: ApiGraphNode[]; edges: ApiGraphEdge[] }> {
const params = new URLSearchParams()
if (options.q) params.set("q", options.q)
@@ -284,6 +368,45 @@ function parseSearchResult(value: unknown): ApiSearchResult {
}
}
+function parseChatReference(value: unknown): ApiChatReference {
+ const obj = requireObject(value, "chat reference")
+ return {
+ title: String(obj.title ?? ""),
+ path: String(obj.path ?? ""),
+ kind: String(obj.kind ?? "wiki"),
+ snippet: typeof obj.snippet === "string" ? obj.snippet : undefined,
+ score: numberOrUndefined(obj.score),
+ }
+}
+
+function parseChatToolEvent(value: unknown): ApiChatToolEvent {
+ const obj = requireObject(value, "chat tool event")
+ return {
+ tool: String(obj.tool ?? ""),
+ status: String(obj.status ?? ""),
+ detail: typeof obj.detail === "string" ? obj.detail : undefined,
+ }
+}
+
+function parseChatEvent(value: unknown): ApiChatEvent {
+ const obj = requireObject(value, "chat event")
+ return {
+ ...obj,
+ type: String(obj.type ?? ""),
+ }
+}
+
+function parseChatUsage(value: unknown): ApiChatUsage | undefined {
+ if (value === undefined || value === null) return undefined
+ const obj = requireObject(value, "chat usage")
+ return {
+ promptChars: numberOrUndefined(obj.promptChars),
+ completionChars: numberOrUndefined(obj.completionChars),
+ referenceCount: numberOrUndefined(obj.referenceCount),
+ toolEventCount: numberOrUndefined(obj.toolEventCount),
+ }
+}
+
function parseReviewStatus(value: unknown): ApiReviewStatus {
return value === "resolved" || value === "all" ? value : "unresolved"
}
diff --git a/mcp-server/src/index.ts b/mcp-server/src/index.ts
index 10cb65b3..352ad031 100644
--- a/mcp-server/src/index.ts
+++ b/mcp-server/src/index.ts
@@ -13,6 +13,7 @@ import {
type ApiGraphNode,
type ApiReviewItem,
type ApiReviewsResponse,
+ type ApiChatResponse,
type ApiSearchResult,
} from "./api-client.js"
import { VERSION } from "./version.js"
@@ -103,6 +104,31 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
additionalProperties: false,
},
},
+ {
+ name: "llm_wiki_chat",
+ description: "Ask the LLM Wiki backend Agent a question about a project. This initial backend Agent uses the desktop API's shared retrieval service and returns references.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ project_id: { type: "string", description: "Project UUID, project path, or 'current'. Defaults to current." },
+ message: { type: "string", description: "User message or question." },
+ session_id: { type: "string", description: "Optional caller-managed session id." },
+ mode: { type: "string", enum: ["fast", "standard", "deep", "local_first"], description: "Agent mode. Defaults to standard." },
+ top_k: { type: "number", description: "Maximum wiki references to retrieve. The API clamps to its configured maximum." },
+ include_content: { type: "boolean", description: "Include full page content in retrieval when supported by the API. Defaults to false." },
+ wiki: { type: "boolean", description: "Enable wiki retrieval. Defaults to true." },
+ web: { type: "boolean", description: "Enable backend web.search when the Agent router decides external search is useful. Defaults to false." },
+ anytxt: { type: "boolean", description: "Enable backend anytxt.search for source/local-file questions when AnyTXT is configured. Defaults to false." },
+ skills: {
+ type: "array",
+ items: { type: "string" },
+ description: "Optional project skills to inject from .llm-wiki/skills.",
+ },
+ },
+ required: ["message"],
+ additionalProperties: false,
+ },
+ },
{
name: "llm_wiki_graph",
description: "Query the project knowledge graph through the desktop app API.",
@@ -179,6 +205,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
})
return textResult(formatSearchResults(query, search))
}
+ case "llm_wiki_chat": {
+ await assertMcpEnabled()
+ const message = stringArg(args.message, "message")
+ const chat = await client.chat(projectId(args), message, {
+ sessionId: optionalStringArg(args.session_id),
+ mode: enumArg(args.mode, ["fast", "standard", "deep", "local_first"] as const, "standard"),
+ topK: numberArg(args.top_k),
+ includeContent: boolArg(args.include_content, false),
+ wiki: boolArg(args.wiki, true),
+ web: boolArg(args.web, false),
+ anytxt: boolArg(args.anytxt, false),
+ skills: stringArrayArg(args.skills),
+ persistSession: optionalStringArg(args.session_id) !== undefined,
+ })
+ return textResult(formatChatResponse(chat))
+ }
case "llm_wiki_graph": {
await assertMcpEnabled()
const graph = await client.graph(projectId(args), {
@@ -252,6 +294,11 @@ function enumArg<T extends string>(value: unknown, allowed: readonly T[], fallba
return typeof value === "string" && allowed.includes(value as T) ? value as T : fallback
}
+function stringArrayArg(value: unknown): string[] | undefined {
+ if (!Array.isArray(value)) return undefined
+ return value.filter((item): item is string => typeof item === "string" && item.trim() !== "")
+}
+
function truncateText(value: string, maxBytes: number): string {
const bytes = Buffer.byteLength(value, "utf8")
if (bytes <= maxBytes) return value
@@ -304,6 +351,43 @@ function formatSearchResults(query: string, search: { results: ApiSearchResult[]
return lines.join("\n")
}
+function formatChatResponse(chat: ApiChatResponse): string {
+ const lines = [
+ "# LLM Wiki Agent response",
+ "",
+ `Session: ${chat.sessionId || "(none)"}`,
+ chat.mode ? `Mode: ${chat.mode}` : null,
+ chat.projectId ? `Project: ${chat.projectId}` : null,
+ chat.usage
+ ? `Usage: promptChars=${chat.usage.promptChars ?? 0}, completionChars=${chat.usage.completionChars ?? 0}, references=${chat.usage.referenceCount ?? chat.references.length}`
+ : null,
+ "",
+ chat.message.content || "(empty response)",
+ "",
+ ].filter((line): line is string => line !== null)
+
+ if (chat.references.length > 0) {
+ lines.push("## References")
+ chat.references.forEach((reference, index) => {
+ lines.push(`${index + 1}. ${reference.title || reference.path}`)
+ lines.push(` Kind: ${reference.kind}`)
+ lines.push(` Path: ${reference.path}`)
+ if (typeof reference.score === "number") lines.push(` Score: ${reference.score.toFixed(6)}`)
+ if (reference.snippet) lines.push(` Snippet: ${reference.snippet}`)
+ })
+ lines.push("")
+ }
+
+ if (chat.toolEvents.length > 0) {
+ lines.push("## Tool events")
+ chat.toolEvents.forEach((event) => {
+ lines.push(`- ${event.tool}: ${event.status}${event.detail ? ` (${event.detail})` : ""}`)
+ })
+ }
+
+ return lines.join("\n")
+}
+
function formatReviews(response: ApiReviewsResponse): string {
const { reviews } = response
if (reviews.length === 0) return `No ${response.status} review items found.`
diff --git a/mcp-server/test/api-client.test.ts b/mcp-server/test/api-client.test.ts
index 23ddad00..678a852a 100644
--- a/mcp-server/test/api-client.test.ts
+++ b/mcp-server/test/api-client.test.ts
@@ -67,6 +67,76 @@ test("search posts JSON body to current project", async () => {
assert.equal(results.results[0]?.vectorScore, 0.9)
})
+test("chat posts agent request and parses references", async () => {
+ let url = ""
+ let body = ""
+ const fetchImpl = async (requestUrl: string | URL | Request, init?: RequestInit): Promise<Response> => {
+ url = String(requestUrl)
+ body = String(init?.body ?? "")
+ return new Response(JSON.stringify({
+ ok: true,
+ projectId: "p1",
+ sessionId: "s1",
+ mode: "standard",
+ message: { role: "assistant", content: "answer" },
+ references: [{ title: "A", path: "wiki/a.md", kind: "wiki", snippet: "hit", score: 0.5 }],
+ toolEvents: [{ tool: "wiki.search", status: "completed", detail: "1 result" }],
+ events: [{ type: "toolEnd", tool: "wiki.search" }],
+ usage: { promptChars: 100, completionChars: 6, referenceCount: 1, toolEventCount: 1 },
+ }), { status: 200 })
+ }
+
+ const client = new LlmWikiApiClient({ baseUrl: "http://localhost:19828", fetchImpl })
+ const response = await client.chat("current", "question", {
+ sessionId: "s1",
+ mode: "standard",
+ topK: 4,
+ includeContent: true,
+ wiki: true,
+ web: false,
+ anytxt: true,
+ skills: ["reviewer"],
+ })
+
+ assert.equal(url, "http://localhost:19828/api/v1/projects/current/chat")
+ assert.deepEqual(JSON.parse(body), {
+ message: "question",
+ sessionId: "s1",
+ mode: "standard",
+ topK: 4,
+ includeContent: true,
+ tools: { wiki: true, web: false, anytxt: true },
+ skills: ["reviewer"],
+ })
+ assert.equal(response.sessionId, "s1")
+ assert.equal(response.message.content, "answer")
+ assert.equal(response.references[0]?.path, "wiki/a.md")
+ assert.equal(response.toolEvents[0]?.tool, "wiki.search")
+ assert.equal(response.events[0]?.type, "toolEnd")
+ assert.equal(response.usage?.promptChars, 100)
+})
+
+test("cancelChat posts to the chat cancellation endpoint", async () => {
+ let url = ""
+ let method = ""
+ const fetchImpl = async (requestUrl: string | URL | Request, init?: RequestInit): Promise<Response> => {
+ url = String(requestUrl)
+ method = String(init?.method ?? "")
+ return new Response(JSON.stringify({
+ ok: true,
+ sessionId: "s1",
+ cancelled: true,
+ }), { status: 200 })
+ }
+
+ const client = new LlmWikiApiClient({ baseUrl: "http://localhost:19828", fetchImpl })
+ const response = await client.cancelChat("current", "s1")
+
+ assert.equal(url, "http://localhost:19828/api/v1/projects/current/chat/s1/cancel")
+ assert.equal(method, "POST")
+ assert.deepEqual(response, { sessionId: "s1", cancelled: true })
+})
+
test("graph parses nodeType from API graph nodes", async () => {
const fetchImpl = async (): Promise<Response> => (
new Response(JSON.stringify({
diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml
index 61955de8..d0c367f7 100644
--- a/src-tauri/Cargo.toml
+++ b/src-tauri/Cargo.toml
@@ -29,7 +29,7 @@ tauri-plugin-dialog = "2.7.1"
pdfium-render = "0.9"
tauri-plugin-store = "2.4.2"
tauri-plugin-http = { version = "2", features = ["unsafe-headers"] }
-reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls", "stream"] }
tiny_http = "0.12"
zip = "2"
calamine = "0.34.0"
diff --git a/src-tauri/src/agent/cancel.rs b/src-tauri/src/agent/cancel.rs
new file mode 100644
index 00000000..7b4016cb
--- /dev/null
+++ b/src-tauri/src/agent/cancel.rs
@@ -0,0 +1,163 @@
+use std::collections::HashMap;
+use std::sync::{
+ atomic::{AtomicBool, Ordering},
+ Arc, Mutex,
+};
+use std::time::Duration;
+
+// Cancellation is shared by Tauri commands and the local HTTP API. Keep the
+// registry backend-owned so UI disconnects, API clients, and MCP clients all
+// observe the same run cancellation semantics.
+#[derive(Debug)]
+pub struct AgentCancellationToken {
+ cancelled: Arc<AtomicBool>,
+ key: String,
+ registry: Arc<Mutex<HashMap<String, Arc<AtomicBool>>>>,
+}
+
+impl AgentCancellationToken {
+ pub fn is_cancelled(&self) -> bool {
+ self.cancelled.load(Ordering::Relaxed)
+ }
+
+ pub fn check(&self) -> Result<(), String> {
+ if self.is_cancelled() {
+ Err("Agent turn cancelled".to_string())
+ } else {
+ Ok(())
+ }
+ }
+
+ pub async fn cancelled(&self) {
+ while !self.is_cancelled() {
+ tokio::time::sleep(Duration::from_millis(50)).await;
+ }
+ }
+}
+
+impl Drop for AgentCancellationToken {
+ fn drop(&mut self) {
+ // Normal completion calls `finish`, but Drop is the safety net for
+ // panics, early returns, and aborted tasks. The remove is idempotent.
+ if let Ok(mut tokens) = self.registry.lock() {
+ tokens.remove(&self.key);
+ }
+ }
+}
+
+#[derive(Debug, Default, Clone)]
+pub struct AgentCancellationRegistry {
+ tokens: Arc<Mutex<HashMap<String, Arc<AtomicBool>>>>,
+}
+
+impl AgentCancellationRegistry {
+ pub fn start(
+ &self,
+ project_id: &str,
+ session_id: &str,
+ run_id: &str,
+ ) -> AgentCancellationToken {
+ let token = Arc::new(AtomicBool::new(false));
+ let key = cancel_key(project_id, session_id, run_id);
+ self.tokens
+ .lock()
+ .unwrap()
+ .insert(key.clone(), token.clone());
+ AgentCancellationToken {
+ cancelled: token,
+ key,
+ registry: self.tokens.clone(),
+ }
+ }
+
+ pub fn cancel(&self, project_id: &str, session_id: &str, run_id: Option<&str>) -> bool {
+ let key_prefix = format!(
+ "{}::{}::",
+ normalize_key(project_id),
+ normalize_key(session_id)
+ );
+ let token = {
+ let tokens = self.tokens.lock().unwrap();
+ if let Some(run_id) = run_id {
+ tokens
+ .get(&cancel_key(project_id, session_id, run_id))
+ .cloned()
+ } else {
+ tokens
+ .iter()
+ .find(|(key, _)| key.starts_with(&key_prefix))
+ .map(|(_, token)| token.clone())
+ }
+ };
+ let Some(token) = token else {
+ return false;
+ };
+ token.store(true, Ordering::Relaxed);
+ true
+ }
+
+ pub fn finish(&self, project_id: &str, session_id: &str, run_id: &str) {
+ self.tokens
+ .lock()
+ .unwrap()
+ .remove(&cancel_key(project_id, session_id, run_id));
+ }
+}
+
+fn cancel_key(project_id: &str, session_id: &str, run_id: &str) -> String {
+ format!(
+ "{}::{}::{}",
+ normalize_key(project_id),
+ normalize_key(session_id),
+ normalize_key(run_id)
+ )
+}
+
+fn normalize_key(value: &str) -> String {
+ value.replace(['\\', '/'], "_")
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn cancellation_registry_marks_active_session() {
+ let registry = AgentCancellationRegistry::default();
+ let token = registry.start("p1", "s1", "r1");
+ assert!(!token.is_cancelled());
+ assert!(registry.cancel("p1", "s1", Some("r1")));
+ assert!(token.is_cancelled());
+ }
+
+ #[test]
+ fn cancellation_registry_returns_false_for_missing_session() {
+ let registry = AgentCancellationRegistry::default();
+ assert!(!registry.cancel("p1", "missing", None));
+ }
+
+ #[test]
+ fn cancellation_registry_isolates_projects_and_runs() {
+ let registry = AgentCancellationRegistry::default();
+ let p1 = registry.start("p1", "same", "r1");
+ let p2 = registry.start("p2", "same", "r1");
+ assert!(registry.cancel("p1", "same", Some("r1")));
+ assert!(p1.is_cancelled());
+ assert!(!p2.is_cancelled());
+
+ let r2 = registry.start("p2", "same", "r2");
+ registry.finish("p2", "same", "r1");
+ assert!(registry.cancel("p2", "same", Some("r2")));
+ assert!(r2.is_cancelled());
+ }
+
+ #[test]
+ fn cancellation_token_drop_removes_registry_entry() {
+ let registry = AgentCancellationRegistry::default();
+ {
+ let _token = registry.start("p1", "s1", "r1");
+ assert!(registry.cancel("p1", "s1", Some("r1")));
+ }
+ assert!(!registry.cancel("p1", "s1", Some("r1")));
+ }
+}
diff --git a/src-tauri/src/agent/context.rs b/src-tauri/src/agent/context.rs
new file mode 100644
index 00000000..41fcaad2
--- /dev/null
+++ b/src-tauri/src/agent/context.rs
@@ -0,0 +1,231 @@
+use std::fs;
+use std::path::Path;
+
+use super::router::{QueryIntent, RouterDecision};
+use super::skills::AgentSkill;
+use super::types::{AgentConversationMessage, AgentReference};
+
+const MAX_OVERVIEW_CHARS: usize = 8_000;
+const MAX_SCHEMA_CHARS: usize = 6_000;
+const MAX_HISTORY_CHARS: usize = 12_000;
+const MAX_REFERENCE_CHARS: usize = 24_000;
+const MAX_SKILL_CHARS: usize = 18_000;
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ProjectContext {
+ pub overview: Option<String>,
+ pub schema: Option<String>,
+}
+
+pub fn load_project_context(project_path: &str) -> ProjectContext {
+ let root = Path::new(project_path);
+ ProjectContext {
+ overview: read_trimmed(root.join("overview.md"), MAX_OVERVIEW_CHARS)
+ .or_else(|| read_trimmed(root.join("wiki").join("overview.md"), MAX_OVERVIEW_CHARS)),
+ schema: read_trimmed(root.join("schema.md"), MAX_SCHEMA_CHARS)
+ .or_else(|| read_trimmed(root.join("wiki").join("schema.md"), MAX_SCHEMA_CHARS)),
+ }
+}
+
+#[derive(Debug, Clone)]
+pub struct AgentContextInput<'a> {
+ pub query: &'a str,
+ pub project: &'a ProjectContext,
+ pub router: &'a RouterDecision,
+ pub history: &'a [AgentConversationMessage],
+ pub skills: &'a [AgentSkill],
+ pub references: &'a [AgentReference],
+ pub retrieval_summary: &'a str,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BuiltAgentContext {
+ pub system: String,
+ pub user: String,
+}
+
+pub fn build_agent_context(input: AgentContextInput<'_>) -> BuiltAgentContext {
+ BuiltAgentContext {
+ system: build_system_context(input.project, input.router, input.skills),
+ user: build_user_context(input),
+ }
+}
+
+fn build_system_context(
+ project: &ProjectContext,
+ router: &RouterDecision,
+ skills: &[AgentSkill],
+) -> String {
+ let mut out = [
+ "You are the LLM Wiki backend Agent.",
+ "Answer using the current project context, available tools, and cited references.",
+ "If evidence is insufficient, say what is missing instead of inventing facts.",
+ "When using references, mention the relevant page paths naturally.",
+ "Do not claim that internet or local-source search is unavailable when those tools are enabled; use the provided tool context and tool hints.",
+ ]
+ .join("\n");
+
+ out.push_str("\n\nTool policy:\n");
+ out.push_str("- wiki.search can search generated wiki pages.\n");
+ if router.should_hint_web {
+ out.push_str("- web.search is available when current or external information is useful.\n");
+ }
+ if router.should_hint_anytxt {
+ out.push_str(
+ "- anytxt.search is available for local or remote file content indexed by AnyTXT.\n",
+ );
+ }
+ out.push_str(&format!(
+ "- Router hint: {:?}. {}\n",
+ router.intent, router.rationale
+ ));
+
+ if let Some(overview) = project.overview.as_deref().filter(|v| !v.trim().is_empty()) {
+ out.push_str("\n\nProject overview:\n");
+ out.push_str(&trim_chars(overview, MAX_OVERVIEW_CHARS));
+ }
+ if let Some(schema) = project.schema.as_deref().filter(|v| !v.trim().is_empty()) {
+ out.push_str("\n\nProject schema:\n");
+ out.push_str(&trim_chars(schema, MAX_SCHEMA_CHARS));
+ }
+ if !skills.is_empty() {
+ out.push_str("\n\nActive skills:\n");
+ let mut remaining = MAX_SKILL_CHARS;
+ for skill in skills {
+ if remaining == 0 {
+ break;
+ }
+ let rendered = format!(
+ "\n## {}\n{}\n{}",
+ skill.name,
+ skill.description.trim(),
+ skill.instructions.trim()
+ );
+ let piece = trim_chars(&rendered, remaining);
+ remaining = remaining.saturating_sub(piece.len());
+ out.push_str(&piece);
+ out.push('\n');
+ }
+ }
+ out
+}
+
+fn build_user_context(input: AgentContextInput<'_>) -> String {
+ let mut out = String::new();
+ if !input.history.is_empty() {
+ out.push_str("Recent conversation history:\n");
+ let mut history = String::new();
+ for item in input.history.iter().rev().take(12).rev() {
+ history.push_str(&format!(
+ "{}: {}\n",
+ item.role,
+ collapse_whitespace(&item.content)
+ ));
+ }
+ out.push_str(&trim_chars(&history, MAX_HISTORY_CHARS));
+ out.push_str("\n\n");
+ }
+
+ out.push_str("Retrieved project context:\n");
+ if input.references.is_empty() {
+ out.push_str("No matching wiki references were found.\n\n");
+ } else {
+ let mut rendered = String::new();
+ for (idx, reference) in input.references.iter().enumerate() {
+ rendered.push_str(&format!(
+ "{}. [{}] {} ({})\n",
+ idx + 1,
+ reference.kind,
+ reference.title,
+ reference.path
+ ));
+ if let Some(snippet) = reference.snippet.as_deref() {
+ rendered.push_str(&format!("Snippet: {}\n", collapse_whitespace(snippet)));
+ }
+ }
+ out.push_str(&trim_chars(&rendered, MAX_REFERENCE_CHARS));
+ out.push('\n');
+ }
+
+ out.push_str("Retrieval summary:\n");
+ out.push_str(&trim_chars(input.retrieval_summary, 8_000));
+ out.push_str("\n\nLatest user request:\n");
+ out.push_str(input.query.trim());
+ out
+}
+
+fn read_trimmed(path: impl AsRef<Path>, max_chars: usize) -> Option<String> {
+ let raw = fs::read_to_string(path).ok()?;
+ let trimmed = raw.trim();
+ if trimmed.is_empty() {
+ None
+ } else {
+ Some(trim_chars(trimmed, max_chars))
+ }
+}
+
+pub fn trim_chars(value: &str, max_chars: usize) -> String {
+ if value.chars().count() <= max_chars {
+ return value.to_string();
+ }
+ let mut out = value
+ .chars()
+ .take(max_chars.saturating_sub(3))
+ .collect::<String>();
+ out.push_str("...");
+ out
+}
+
+pub fn collapse_whitespace(value: &str) -> String {
+ value.split_whitespace().collect::<Vec<_>>().join(" ")
+}
+
+pub fn intent_label(intent: QueryIntent) -> &'static str {
+ match intent {
+ QueryIntent::NeedsInternalSearch => "internal_search",
+ QueryIntent::NeedsExternalSearch => "external_search",
+ QueryIntent::NeedsRawSourceSearch => "raw_source_search",
+ QueryIntent::NeedsGraph => "graph",
+ QueryIntent::NeedsWrite => "write",
+ QueryIntent::SimpleConversational => "conversation",
+ QueryIntent::Ambiguous => "ambiguous",
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::agent::router::route_query;
+ use crate::agent::types::{AgentMode, AgentToolOptions};
+
+ #[test]
+ fn context_keeps_stable_project_context_before_latest_request() {
+ let project = ProjectContext {
+ overview: Some("Project overview text".to_string()),
+ schema: Some("Schema text".to_string()),
+ };
+ let router = route_query(
+ "latest policy",
+ AgentMode::Standard,
+ &AgentToolOptions::default(),
+ );
+ let ctx = build_agent_context(AgentContextInput {
+ query: "latest policy",
+ project: &project,
+ router: &router,
+ history: &[],
+ skills: &[],
+ references: &[],
+ retrieval_summary: "None",
+ });
+
+ assert!(ctx.system.contains("Project overview text"));
+ assert!(ctx.system.contains("Schema text"));
+ assert!(ctx.user.ends_with("latest policy"));
+ }
+
+ #[test]
+ fn trim_chars_is_utf8_safe() {
+ assert_eq!(trim_chars("煤矿安全治理", 5), "煤矿...");
+ }
+}
diff --git a/src-tauri/src/agent/events.rs b/src-tauri/src/agent/events.rs
new file mode 100644
index 00000000..8c1dd6db
--- /dev/null
+++ b/src-tauri/src/agent/events.rs
@@ -0,0 +1,68 @@
+use serde::{Deserialize, Serialize};
+
+use super::types::AgentReference;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase", tag = "type")]
+pub enum AgentEvent {
+ AgentStart {
+ session_id: String,
+ },
+ TurnStart {
+ mode: String,
+ },
+ ToolStart {
+ tool: String,
+ input: Option<String>,
+ },
+ ToolEnd {
+ tool: String,
+ output: Option<String>,
+ },
+ ReferenceAdded {
+ reference: AgentReference,
+ },
+ MessageDelta {
+ text: String,
+ },
+ Error {
+ message: String,
+ },
+ Done {
+ session_id: String,
+ },
+}
+
+impl AgentEvent {
+ pub fn tool_start(tool: impl Into<String>, input: Option<String>) -> Self {
+ Self::ToolStart {
+ tool: tool.into(),
+ input,
+ }
+ }
+
+ pub fn tool_end(tool: impl Into<String>, output: Option<String>) -> Self {
+ Self::ToolEnd {
+ tool: tool.into(),
+ output,
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn agent_event_serializes_with_camelcase_tag() {
+ let value = serde_json::to_value(AgentEvent::ToolStart {
+ tool: "wiki.search".to_string(),
+ input: Some("query".to_string()),
+ })
+ .unwrap();
+
+ assert_eq!(value["type"], "toolStart");
+ assert_eq!(value["tool"], "wiki.search");
+ assert_eq!(value["input"], "query");
+ }
+}
diff --git a/src-tauri/src/agent/mod.rs b/src-tauri/src/agent/mod.rs
new file mode 100644
index 00000000..9be86b9e
--- /dev/null
+++ b/src-tauri/src/agent/mod.rs
@@ -0,0 +1,21 @@
+//! Backend Agent substrate shared by the desktop UI, local HTTP API, and MCP.
+//!
+//! Keep routing, retrieval, tool execution, context assembly, sessions, and
+//! cancellation in this Rust module. The React/TypeScript side may render UI
+//! state and bridge provider-specific transports, but it should not reimplement
+//! the Agent core; otherwise API/MCP/UI behavior will drift.
+
+pub mod cancel;
+pub mod context;
+pub mod events;
+pub mod permissions;
+pub mod provider;
+pub mod router;
+pub mod runtime;
+pub mod session;
+pub mod skills;
+pub mod tools;
+pub mod types;
+
+pub use runtime::AgentRuntime;
+pub use types::AgentChatRequest;
diff --git a/src-tauri/src/agent/permissions.rs b/src-tauri/src/agent/permissions.rs
new file mode 100644
index 00000000..2f44cc7e
--- /dev/null
+++ b/src-tauri/src/agent/permissions.rs
@@ -0,0 +1,61 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
+#[serde(rename_all = "snake_case")]
+pub enum AgentCapability {
+ ReadProject,
+ ReadSource,
+ SearchWiki,
+ SearchWeb,
+ SearchAnyTxt,
+ WriteWiki,
+ RunDeepResearch,
+ Network,
+ Process,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PermissionPolicy {
+ allowed: Vec<AgentCapability>,
+}
+
+impl PermissionPolicy {
+ pub fn api_default() -> Self {
+ Self {
+ allowed: vec![
+ AgentCapability::ReadProject,
+ AgentCapability::ReadSource,
+ AgentCapability::SearchWiki,
+ AgentCapability::SearchWeb,
+ AgentCapability::SearchAnyTxt,
+ AgentCapability::WriteWiki,
+ AgentCapability::Network,
+ ],
+ }
+ }
+
+ pub fn allows(&self, capability: AgentCapability) -> bool {
+ self.allowed.contains(&capability)
+ }
+
+ pub fn require(&self, capability: AgentCapability) -> Result<(), String> {
+ if self.allows(capability) {
+ Ok(())
+ } else {
+ Err(format!("Agent capability '{capability:?}' is not allowed"))
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn api_default_allows_read_network_and_sandboxed_wiki_writes() {
+ let policy = PermissionPolicy::api_default();
+ assert!(policy.allows(AgentCapability::SearchWiki));
+ assert!(policy.allows(AgentCapability::Network));
+ assert!(policy.allows(AgentCapability::WriteWiki));
+ }
+}
diff --git a/src-tauri/src/agent/provider.rs b/src-tauri/src/agent/provider.rs
new file mode 100644
index 00000000..58d9fd86
--- /dev/null
+++ b/src-tauri/src/agent/provider.rs
@@ -0,0 +1,1109 @@
+use std::future::Future;
+use std::pin::Pin;
+use std::time::Duration;
+
+use futures::StreamExt;
+use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
+use serde::Deserialize;
+use serde_json::{json, Value};
+
+use super::types::AgentImage;
+
+const REQUEST_TIMEOUT_SECS: u64 = 180;
+const DEFAULT_MAX_TOKENS: u32 = 2048;
+const ANTHROPIC_VERSION: &str = "2023-06-01";
+const AZURE_OPENAI_API_VERSION: &str = "2024-10-21";
+
+#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct LlmReasoningConfig {
+ #[serde(default)]
+ pub mode: Option<String>,
+ #[serde(default)]
+ pub budget_tokens: Option<u32>,
+}
+
+#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct LlmConfig {
+ pub provider: String,
+ #[serde(default)]
+ pub api_key: String,
+ #[serde(default)]
+ pub model: String,
+ #[serde(default)]
+ pub ollama_url: String,
+ #[serde(default)]
+ pub custom_endpoint: String,
+ #[serde(default)]
+ pub azure_api_version: Option<String>,
+ #[serde(default)]
+ pub api_mode: Option<String>,
+ #[serde(default)]
+ pub reasoning: Option<LlmReasoningConfig>,
+ // Mirrors the app's existing `maxContextSize` setting. It is treated as a
+ // character budget here for compatibility with the TypeScript budget model;
+ // do not reinterpret it as provider tokens without migrating callers.
+ #[serde(default)]
+ pub max_context_size: Option<usize>,
+}
+
+impl LlmConfig {
+ pub fn is_usable_for_backend_http(&self) -> bool {
+ let provider = self.provider.as_str();
+ let has_model = !self.model.trim().is_empty();
+ match provider {
+ "openai" | "anthropic" | "google" | "azure" | "minimax" => {
+ has_model && !self.api_key.trim().is_empty()
+ }
+ "ollama" => has_model && !self.ollama_url.trim().is_empty(),
+ "custom" => has_model && !self.custom_endpoint.trim().is_empty(),
+ // CLI transports need subprocess/session wiring and are handled in
+ // a later Agent transport layer, not by this HTTP provider.
+ "claude-code" | "codex-cli" => false,
+ _ => false,
+ }
+ }
+}
+
+#[derive(Debug, Clone)]
+pub struct LlmClient {
+ config: LlmConfig,
+ client: reqwest::Client,
+}
+
+pub trait AgentLlmProvider: Send + Sync {
+ fn provider_name(&self) -> &str;
+ fn model_name(&self) -> &str;
+ fn generate_text<'a>(
+ &'a self,
+ system: &'a str,
+ user: &'a str,
+ images: &'a [AgentImage],
+ ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'a>>;
+ fn generate_text_stream<'a>(
+ &'a self,
+ system: &'a str,
+ user: &'a str,
+ images: &'a [AgentImage],
+ on_delta: Box<dyn FnMut(&str) + Send + 'a>,
+ ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'a>>;
+}
+
+impl AgentLlmProvider for LlmClient {
+ fn provider_name(&self) -> &str {
+ &self.config.provider
+ }
+
+ fn model_name(&self) -> &str {
+ &self.config.model
+ }
+
+ fn generate_text<'a>(
+ &'a self,
+ system: &'a str,
+ user: &'a str,
+ images: &'a [AgentImage],
+ ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'a>> {
+ Box::pin(async move { LlmClient::generate_text(self, system, user, images).await })
+ }
+
+ fn generate_text_stream<'a>(
+ &'a self,
+ system: &'a str,
+ user: &'a str,
+ images: &'a [AgentImage],
+ mut on_delta: Box<dyn FnMut(&str) + Send + 'a>,
+ ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'a>> {
+ Box::pin(async move {
+ LlmClient::generate_text_stream(self, system, user, images, move |delta| {
+ on_delta(delta)
+ })
+ .await
+ })
+ }
+}
+
+impl LlmClient {
+ pub fn new(config: LlmConfig) -> Result<Self, String> {
+ let client = reqwest::Client::builder()
+ .timeout(Duration::from_secs(REQUEST_TIMEOUT_SECS))
+ .build()
+ .map_err(|err| format!("Failed to build LLM HTTP client: {err}"))?;
+ Ok(Self { config, client })
+ }
+
+ pub async fn generate_text(
+ &self,
+ system: &str,
+ user: &str,
+ images: &[AgentImage],
+ ) -> Result<String, String> {
+ match self.config.provider.as_str() {
+ "openai" => {
+ self.generate_openai_like(
+ "https://api.openai.com/v1/chat/completions",
+ system,
+ user,
+ images,
+ true,
+ )
+ .await
+ }
+ "azure" => {
+ let url = build_azure_url(&self.config)?;
+ self.generate_openai_like(&url, system, user, images, false)
+ .await
+ }
+ "ollama" => {
+ let url = build_ollama_url(&self.config.ollama_url);
+ self.generate_openai_like(&url, system, user, images, true)
+ .await
+ }
+ "custom" if self.config.api_mode.as_deref() == Some("anthropic_messages") => {
+ let url = build_anthropic_url(&self.config.custom_endpoint);
+ self.generate_anthropic_like(&url, system, user, images)
+ .await
+ }
+ "custom" => {
+ let url = build_custom_openai_url(&self.config);
+ self.generate_openai_like(&url, system, user, images, !is_azure_endpoint(&url))
+ .await
+ }
+ "anthropic" => {
+ self.generate_anthropic_like(
+ "https://api.anthropic.com/v1/messages",
+ system,
+ user,
+ images,
+ )
+ .await
+ }
+ "minimax" => {
+ if !images.is_empty() {
+ return Err("MiniMax official Anthropic-compatible endpoint does not support image input. Use a vision-capable provider for image chat.".to_string());
+ }
+ let base = if self.config.custom_endpoint.trim().is_empty() {
+ "https://api.minimax.io/anthropic"
+ } else {
+ self.config.custom_endpoint.trim()
+ };
+ let url = build_anthropic_url(base);
+ self.generate_anthropic_like(&url, system, user, images)
+ .await
+ }
+ "google" => self.generate_google(system, user, images).await,
+ other => Err(format!(
+ "Provider '{other}' is not supported by the backend HTTP Agent yet"
+ )),
+ }
+ }
+
+ pub async fn generate_text_stream<F>(
+ &self,
+ system: &str,
+ user: &str,
+ images: &[AgentImage],
+ on_delta: F,
+ ) -> Result<String, String>
+ where
+ F: FnMut(&str) + Send,
+ {
+ match self.config.provider.as_str() {
+ "openai" => {
+ self.stream_openai_like(
+ "https://api.openai.com/v1/chat/completions",
+ system,
+ user,
+ images,
+ true,
+ on_delta,
+ )
+ .await
+ }
+ "azure" => {
+ let url = build_azure_url(&self.config)?;
+ self.stream_openai_like(&url, system, user, images, false, on_delta)
+ .await
+ }
+ "ollama" => {
+ let url = build_ollama_url(&self.config.ollama_url);
+ self.stream_openai_like(&url, system, user, images, true, on_delta)
+ .await
+ }
+ "custom" if self.config.api_mode.as_deref() == Some("anthropic_messages") => {
+ let url = build_anthropic_url(&self.config.custom_endpoint);
+ self.stream_anthropic_like(&url, system, user, images, on_delta)
+ .await
+ }
+ "custom" => {
+ let url = build_custom_openai_url(&self.config);
+ self.stream_openai_like(
+ &url,
+ system,
+ user,
+ images,
+ !is_azure_endpoint(&url),
+ on_delta,
+ )
+ .await
+ }
+ "anthropic" => {
+ self.stream_anthropic_like(
+ "https://api.anthropic.com/v1/messages",
+ system,
+ user,
+ images,
+ on_delta,
+ )
+ .await
+ }
+ "minimax" => {
+ if !images.is_empty() {
+ return Err("MiniMax official Anthropic-compatible endpoint does not support image input. Use a vision-capable provider for image chat.".to_string());
+ }
+ let base = if self.config.custom_endpoint.trim().is_empty() {
+ "https://api.minimax.io/anthropic"
+ } else {
+ self.config.custom_endpoint.trim()
+ };
+ let url = build_anthropic_url(base);
+ self.stream_anthropic_like(&url, system, user, images, on_delta)
+ .await
+ }
+ "google" => self.stream_google(system, user, images, on_delta).await,
+ _ => self.generate_text(system, user, images).await,
+ }
+ }
+
+ fn openai_like_body(
+ &self,
+ system: &str,
+ user: &str,
+ images: &[AgentImage],
+ include_model: bool,
+ stream: bool,
+ ) -> Value {
+ let user_content = openai_user_content(user, images);
+ let mut body = json!({
+ "messages": [
+ { "role": "system", "content": system },
+ { "role": "user", "content": user_content }
+ ],
+ "stream": stream,
+ "max_tokens": DEFAULT_MAX_TOKENS
+ });
+ if include_model {
+ body["model"] = Value::String(self.config.model.clone());
+ }
+ apply_openai_reasoning(&mut body, self.config.reasoning.as_ref());
+ body
+ }
+
+ async fn generate_openai_like(
+ &self,
+ url: &str,
+ system: &str,
+ user: &str,
+ images: &[AgentImage],
+ include_model: bool,
+ ) -> Result<String, String> {
+ let body = self.openai_like_body(system, user, images, include_model, false);
+
+ let response = self
+ .client
+ .post(url)
+ .headers(openai_headers(&self.config, url)?)
+ .json(&body)
+ .send()
+ .await
+ .map_err(|err| format!("LLM request failed: {err}"))?;
+ let status = response.status();
+ let text = response
+ .text()
+ .await
+ .map_err(|err| format!("Failed to read LLM response: {err}"))?;
+ if !status.is_success() {
+ return Err(format!("LLM HTTP {status}: {}", trim_error_body(&text)));
+ }
+ let parsed: Value =
+ serde_json::from_str(&text).map_err(|err| format!("Invalid LLM JSON: {err}"))?;
+ let content = parsed
+ .get("choices")
+ .and_then(Value::as_array)
+ .and_then(|choices| choices.first())
+ .and_then(|choice| choice.get("message"))
+ .and_then(|message| message.get("content"))
+ .and_then(Value::as_str)
+ .unwrap_or("")
+ .trim()
+ .to_string();
+ if content.is_empty() {
+ return Err("LLM response did not contain assistant content".to_string());
+ }
+ Ok(content)
+ }
+
+ async fn stream_openai_like<F>(
+ &self,
+ url: &str,
+ system: &str,
+ user: &str,
+ images: &[AgentImage],
+ include_model: bool,
+ on_delta: F,
+ ) -> Result<String, String>
+ where
+ F: FnMut(&str) + Send,
+ {
+ let body = self.openai_like_body(system, user, images, include_model, true);
+ let response = self
+ .client
+ .post(url)
+ .headers(openai_headers(&self.config, url)?)
+ .json(&body)
+ .send()
+ .await
+ .map_err(|err| format!("LLM request failed: {err}"))?;
+ collect_sse_text(response, parse_openai_delta, on_delta).await
+ }
+
+ fn anthropic_like_body(
+ &self,
+ system: &str,
+ user: &str,
+ images: &[AgentImage],
+ stream: bool,
+ ) -> Value {
+ let mut body = json!({
+ "model": self.config.model,
+ "system": [{ "type": "text", "text": system, "cache_control": { "type": "ephemeral" } }],
+ "messages": [{ "role": "user", "content": anthropic_user_content(user, images) }],
+ "max_tokens": DEFAULT_MAX_TOKENS,
+ });
+ if stream {
+ body["stream"] = Value::Bool(true);
+ }
+ apply_anthropic_reasoning(&mut body, self.config.reasoning.as_ref());
+ body
+ }
+
+ async fn generate_anthropic_like(
+ &self,
+ url: &str,
+ system: &str,
+ user: &str,
+ images: &[AgentImage],
+ ) -> Result<String, String> {
+ let body = self.anthropic_like_body(system, user, images, false);
+
+ let response = self
+ .client
+ .post(url)
+ .headers(anthropic_headers(&self.config, url)?)
+ .json(&body)
+ .send()
+ .await
+ .map_err(|err| format!("LLM request failed: {err}"))?;
+ let status = response.status();
+ let text = response
+ .text()
+ .await
+ .map_err(|err| format!("Failed to read LLM response: {err}"))?;
+ if !status.is_success() {
+ return Err(format!("LLM HTTP {status}: {}", trim_error_body(&text)));
+ }
+ let parsed: Value =
+ serde_json::from_str(&text).map_err(|err| format!("Invalid LLM JSON: {err}"))?;
+ let content = parsed
+ .get("content")
+ .and_then(Value::as_array)
+ .map(|blocks| {
+ blocks
+ .iter()
+ .filter_map(|block| {
+ if block.get("type").and_then(Value::as_str) == Some("text") {
+ block.get("text").and_then(Value::as_str)
+ } else {
+ None
+ }
+ })
+ .collect::<Vec<_>>()
+ .join("")
+ })
+ .unwrap_or_default()
+ .trim()
+ .to_string();
+ if content.is_empty() {
+ return Err("LLM response did not contain assistant content".to_string());
+ }
+ Ok(content)
+ }
+
+ async fn stream_anthropic_like<F>(
+ &self,
+ url: &str,
+ system: &str,
+ user: &str,
+ images: &[AgentImage],
+ on_delta: F,
+ ) -> Result<String, String>
+ where
+ F: FnMut(&str) + Send,
+ {
+ let body = self.anthropic_like_body(system, user, images, true);
+ let response = self
+ .client
+ .post(url)
+ .headers(anthropic_headers(&self.config, url)?)
+ .json(&body)
+ .send()
+ .await
+ .map_err(|err| format!("LLM request failed: {err}"))?;
+ collect_sse_text(response, parse_anthropic_delta, on_delta).await
+ }
+
+ fn google_body(&self, system: &str, user: &str, images: &[AgentImage]) -> Value {
+ let mut parts = vec![json!({ "text": user })];
+ for image in images {
+ parts.push(json!({
+ "inlineData": {
+ "mimeType": image.media_type,
+ "data": image.data_base64
+ }
+ }));
+ }
+ let mut body = json!({
+ "systemInstruction": {
+ "parts": [{ "text": system }]
+ },
+ "contents": [{
+ "role": "user",
+ "parts": parts
+ }],
+ "generationConfig": {
+ "maxOutputTokens": DEFAULT_MAX_TOKENS
+ }
+ });
+ apply_google_reasoning(&mut body, self.config.reasoning.as_ref());
+ body
+ }
+
+ async fn generate_google(
+ &self,
+ system: &str,
+ user: &str,
+ images: &[AgentImage],
+ ) -> Result<String, String> {
+ let encoded_model = url_encode_path_segment(&self.config.model);
+ let url = format!(
+ "https://generativelanguage.googleapis.com/v1beta/models/{encoded_model}:generateContent"
+ );
+ let body = self.google_body(system, user, images);
+
+ let response = self
+ .client
+ .post(url)
+ .header("Content-Type", "application/json")
+ .header("x-goog-api-key", self.config.api_key.trim())
+ .json(&body)
+ .send()
+ .await
+ .map_err(|err| format!("LLM request failed: {err}"))?;
+ let status = response.status();
+ let text = response
+ .text()
+ .await
+ .map_err(|err| format!("Failed to read LLM response: {err}"))?;
+ if !status.is_success() {
+ return Err(format!("LLM HTTP {status}: {}", trim_error_body(&text)));
+ }
+ let parsed: Value =
+ serde_json::from_str(&text).map_err(|err| format!("Invalid LLM JSON: {err}"))?;
+ let content = parsed
+ .get("candidates")
+ .and_then(Value::as_array)
+ .and_then(|candidates| candidates.first())
+ .and_then(|candidate| candidate.get("content"))
+ .and_then(|content| content.get("parts"))
+ .and_then(Value::as_array)
+ .map(|parts| {
+ parts
+ .iter()
+ .filter_map(|part| part.get("text").and_then(Value::as_str))
+ .collect::<Vec<_>>()
+ .join("")
+ })
+ .unwrap_or_default()
+ .trim()
+ .to_string();
+ if content.is_empty() {
+ return Err("LLM response did not contain assistant content".to_string());
+ }
+ Ok(content)
+ }
+
+ async fn stream_google<F>(
+ &self,
+ system: &str,
+ user: &str,
+ images: &[AgentImage],
+ on_delta: F,
+ ) -> Result<String, String>
+ where
+ F: FnMut(&str) + Send,
+ {
+ let encoded_model = url_encode_path_segment(&self.config.model);
+ let url = format!(
+ "https://generativelanguage.googleapis.com/v1beta/models/{encoded_model}:streamGenerateContent?alt=sse"
+ );
+ let body = self.google_body(system, user, images);
+ let response = self
+ .client
+ .post(url)
+ .header("Content-Type", "application/json")
+ .header("x-goog-api-key", self.config.api_key.trim())
+ .json(&body)
+ .send()
+ .await
+ .map_err(|err| format!("LLM request failed: {err}"))?;
+ collect_sse_text(response, parse_google_delta, on_delta).await
+ }
+}
+
+fn openai_headers(config: &LlmConfig, url: &str) -> Result<HeaderMap, String> {
+ let mut headers = HeaderMap::new();
+ headers.insert("Content-Type", HeaderValue::from_static("application/json"));
+ let key = config.api_key.trim();
+ if !key.is_empty() {
+ if is_azure_endpoint(url) {
+ headers.insert(
+ "api-key",
+ HeaderValue::from_str(key)
+ .map_err(|err| format!("Invalid API key header: {err}"))?,
+ );
+ } else {
+ headers.insert(
+ "Authorization",
+ HeaderValue::from_str(&format!("Bearer {key}"))
+ .map_err(|err| format!("Invalid authorization header: {err}"))?,
+ );
+ }
+ }
+ Ok(headers)
+}
+
+fn anthropic_headers(config: &LlmConfig, url: &str) -> Result<HeaderMap, String> {
+ let mut headers = HeaderMap::new();
+ headers.insert("Content-Type", HeaderValue::from_static("application/json"));
+ headers.insert(
+ "anthropic-version",
+ HeaderValue::from_static(ANTHROPIC_VERSION),
+ );
+ let key = config.api_key.trim();
+ if !key.is_empty() {
+ let name = if requires_bearer_auth(url) {
+ "Authorization"
+ } else {
+ "x-api-key"
+ };
+ let value = if name == "Authorization" {
+ format!("Bearer {key}")
+ } else {
+ key.to_string()
+ };
+ headers.insert(
+ HeaderName::from_static(name),
+ HeaderValue::from_str(&value)
+ .map_err(|err| format!("Invalid API key header: {err}"))?,
+ );
+ }
+ Ok(headers)
+}
+
+fn openai_user_content(user: &str, images: &[AgentImage]) -> Value {
+ if images.is_empty() {
+ return Value::String(user.to_string());
+ }
+ let mut blocks = vec![json!({ "type": "text", "text": user })];
+ for image in images {
+ blocks.push(json!({
+ "type": "image_url",
+ "image_url": {
+ "url": format!("data:{};base64,{}", image.media_type, image.data_base64)
+ }
+ }));
+ }
+ Value::Array(blocks)
+}
+
+fn anthropic_user_content(user: &str, images: &[AgentImage]) -> Value {
+ let mut user_content = vec![json!({ "type": "text", "text": user })];
+ for image in images {
+ user_content.push(json!({
+ "type": "image",
+ "source": {
+ "type": "base64",
+ "media_type": image.media_type,
+ "data": image.data_base64
+ }
+ }));
+ }
+ Value::Array(user_content)
+}
+
+async fn collect_sse_text<F>(
+ response: reqwest::Response,
+ parse_delta: fn(&str) -> Option<String>,
+ mut on_delta: F,
+) -> Result<String, String>
+where
+ F: FnMut(&str) + Send,
+{
+ let status = response.status();
+ if !status.is_success() {
+ let text = response
+ .text()
+ .await
+ .map_err(|err| format!("Failed to read LLM response: {err}"))?;
+ return Err(format!("LLM HTTP {status}: {}", trim_error_body(&text)));
+ }
+
+ let mut full = String::new();
+ let mut buffer = Vec::<u8>::new();
+ let mut stream = response.bytes_stream();
+ while let Some(chunk) = stream.next().await {
+ let chunk = chunk.map_err(|err| format!("LLM stream failed: {err}"))?;
+ collect_sse_chunk_bytes(&mut buffer, &chunk, parse_delta, &mut on_delta, &mut full);
+ }
+ if !buffer.iter().all(|byte| byte.is_ascii_whitespace()) {
+ collect_sse_line_bytes(&buffer, parse_delta, &mut on_delta, &mut full);
+ }
+ if full.trim().is_empty() {
+ return Err("LLM response did not contain assistant content".to_string());
+ }
+ Ok(full.trim().to_string())
+}
+
+fn collect_sse_chunk_bytes<F>(
+ buffer: &mut Vec<u8>,
+ chunk: &[u8],
+ parse_delta: fn(&str) -> Option<String>,
+ on_delta: &mut F,
+ full: &mut String,
+) where
+ F: FnMut(&str) + Send,
+{
+ buffer.extend_from_slice(chunk);
+ while let Some(newline) = buffer.iter().position(|byte| *byte == b'\n') {
+ let mut line = buffer.drain(..=newline).collect::<Vec<_>>();
+ if line.last() == Some(&b'\n') {
+ line.pop();
+ }
+ if line.last() == Some(&b'\r') {
+ line.pop();
+ }
+ collect_sse_line_bytes(&line, parse_delta, on_delta, full);
+ }
+}
+
+fn collect_sse_line_bytes<F>(
+ line: &[u8],
+ parse_delta: fn(&str) -> Option<String>,
+ on_delta: &mut F,
+ full: &mut String,
+) where
+ F: FnMut(&str) + Send,
+{
+ let line = String::from_utf8_lossy(line);
+ collect_sse_line(line.trim(), parse_delta, on_delta, full);
+}
+
+fn collect_sse_line<F>(
+ line: &str,
+ parse_delta: fn(&str) -> Option<String>,
+ on_delta: &mut F,
+ full: &mut String,
+) where
+ F: FnMut(&str) + Send,
+{
+ let Some(data) = line.strip_prefix("data:") else {
+ return;
+ };
+ let data = data.trim();
+ if data == "[DONE]" || data.is_empty() {
+ return;
+ }
+ if let Some(delta) = parse_delta(data) {
+ if !delta.is_empty() {
+ on_delta(&delta);
+ full.push_str(&delta);
+ }
+ }
+}
+
+fn parse_openai_delta(data: &str) -> Option<String> {
+ let parsed: Value = serde_json::from_str(data).ok()?;
+ parsed
+ .get("choices")
+ .and_then(Value::as_array)
+ .and_then(|choices| choices.first())
+ .and_then(|choice| choice.get("delta").or_else(|| choice.get("message")))
+ .and_then(|message| message.get("content"))
+ .and_then(Value::as_str)
+ .map(str::to_string)
+}
+
+fn parse_anthropic_delta(data: &str) -> Option<String> {
+ let parsed: Value = serde_json::from_str(data).ok()?;
+ if parsed.get("type").and_then(Value::as_str) == Some("content_block_delta") {
+ return parsed
+ .get("delta")
+ .and_then(|delta| delta.get("text"))
+ .and_then(Value::as_str)
+ .map(str::to_string);
+ }
+ None
+}
+
+fn parse_google_delta(data: &str) -> Option<String> {
+ let parsed: Value = serde_json::from_str(data).ok()?;
+ parsed
+ .get("candidates")
+ .and_then(Value::as_array)
+ .and_then(|candidates| candidates.first())
+ .and_then(|candidate| candidate.get("content"))
+ .and_then(|content| content.get("parts"))
+ .and_then(Value::as_array)
+ .map(|parts| {
+ parts
+ .iter()
+ .filter_map(|part| part.get("text").and_then(Value::as_str))
+ .collect::<Vec<_>>()
+ .join("")
+ })
+ .filter(|text| !text.is_empty())
+}
+
+fn build_ollama_url(base: &str) -> String {
+ let mut base = base.trim().trim_end_matches('/').to_string();
+ if base.to_ascii_lowercase().ends_with("/v1/chat/completions") {
+ base.truncate(base.len() - "/v1/chat/completions".len());
+ } else if base.to_ascii_lowercase().ends_with("/v1") {
+ base.truncate(base.len() - "/v1".len());
+ }
+ format!("{base}/v1/chat/completions")
+}
+
+fn build_custom_openai_url(config: &LlmConfig) -> String {
+ let base = config.custom_endpoint.trim().trim_end_matches('/');
+ if is_azure_endpoint(base) {
+ return build_azure_url(config).unwrap_or_else(|_| base.to_string());
+ }
+ if base.to_ascii_lowercase().ends_with("/chat/completions") {
+ base.to_string()
+ } else {
+ format!("{base}/chat/completions")
+ }
+}
+
+fn build_azure_url(config: &LlmConfig) -> Result<String, String> {
+ let endpoint = config.custom_endpoint.trim().trim_end_matches('/');
+ if endpoint.is_empty() {
+ return Err("Azure endpoint is required".to_string());
+ }
+ let api_version = config
+ .azure_api_version
+ .as_deref()
+ .filter(|v| !v.trim().is_empty())
+ .unwrap_or(AZURE_OPENAI_API_VERSION);
+ if endpoint
+ .to_ascii_lowercase()
+ .contains("/openai/deployments/")
+ {
+ let sep = if endpoint.contains('?') { '&' } else { '?' };
+ return Ok(format!("{endpoint}{sep}api-version={api_version}"));
+ }
+ Ok(format!(
+ "{endpoint}/openai/deployments/{}/chat/completions?api-version={api_version}",
+ url_encode_path_segment(&config.model)
+ ))
+}
+
+fn build_anthropic_url(base: &str) -> String {
+ let base = base.trim().trim_end_matches('/');
+ if base.to_ascii_lowercase().ends_with("/v1/messages") {
+ base.to_string()
+ } else if base.to_ascii_lowercase().ends_with("/v1") {
+ format!("{base}/messages")
+ } else {
+ format!("{base}/v1/messages")
+ }
+}
+
+fn is_azure_endpoint(url: &str) -> bool {
+ let lower = url.to_ascii_lowercase();
+ lower.contains(".openai.azure.com") || lower.contains("/openai/deployments/")
+}
+
+fn requires_bearer_auth(url: &str) -> bool {
+ let lower = url.to_ascii_lowercase();
+ lower.contains("minimax.io") || lower.contains("minimaxi.com")
+}
+
+fn apply_openai_reasoning(body: &mut Value, reasoning: Option<&LlmReasoningConfig>) {
+ let Some(reasoning) = reasoning else {
+ return;
+ };
+ match reasoning.mode.as_deref() {
+ Some("off") => {}
+ Some("low" | "medium" | "high") => {
+ body["reasoning_effort"] = Value::String(reasoning.mode.clone().unwrap_or_default());
+ }
+ _ => {}
+ }
+}
+
+fn apply_anthropic_reasoning(body: &mut Value, reasoning: Option<&LlmReasoningConfig>) {
+ let Some(reasoning) = reasoning else {
+ return;
+ };
+ if reasoning.mode.as_deref() == Some("off") {
+ return;
+ }
+ let Some(budget) = reasoning_budget(reasoning) else {
+ return;
+ };
+ body["thinking"] = json!({ "type": "enabled", "budget_tokens": budget });
+ let min_tokens = budget.saturating_add(1024).max(DEFAULT_MAX_TOKENS);
+ body["max_tokens"] = Value::from(min_tokens);
+}
+
+fn apply_google_reasoning(body: &mut Value, reasoning: Option<&LlmReasoningConfig>) {
+ let Some(reasoning) = reasoning else {
+ return;
+ };
+ if reasoning.mode.as_deref() == Some("off") {
+ body["generationConfig"]["thinkingConfig"] = json!({ "thinkingBudget": 0 });
+ return;
+ }
+ if let Some(budget) = reasoning_budget(reasoning) {
+ body["generationConfig"]["thinkingConfig"] = json!({ "thinkingBudget": budget });
+ }
+}
+
+fn reasoning_budget(reasoning: &LlmReasoningConfig) -> Option<u32> {
+ match reasoning.mode.as_deref() {
+ Some("custom") => reasoning.budget_tokens,
+ Some("low") => Some(1024),
+ Some("medium") => Some(4096),
+ Some("high" | "max") => Some(8192),
+ _ => None,
+ }
+}
+
+fn trim_error_body(text: &str) -> String {
+ const MAX: usize = 800;
+ let trimmed = text.trim();
+ if trimmed.chars().count() <= MAX {
+ trimmed.to_string()
+ } else {
+ format!("{}...", trimmed.chars().take(MAX).collect::<String>())
+ }
+}
+
+fn url_encode_path_segment(value: &str) -> String {
+ value
+ .bytes()
+ .flat_map(|byte| match byte {
+ b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
+ vec![byte as char]
+ }
+ _ => format!("%{byte:02X}").chars().collect(),
+ })
+ .collect()
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn config(provider: &str) -> LlmConfig {
+ LlmConfig {
+ provider: provider.to_string(),
+ api_key: "key".to_string(),
+ model: "model/name".to_string(),
+ ollama_url: "http://localhost:11434/v1".to_string(),
+ custom_endpoint: "https://example.com/v1".to_string(),
+ azure_api_version: None,
+ api_mode: None,
+ reasoning: None,
+ max_context_size: None,
+ }
+ }
+
+ #[test]
+ fn ollama_url_normalizes_common_endpoint_shapes() {
+ assert_eq!(
+ build_ollama_url("http://localhost:11434"),
+ "http://localhost:11434/v1/chat/completions"
+ );
+ assert_eq!(
+ build_ollama_url("http://localhost:11434/v1"),
+ "http://localhost:11434/v1/chat/completions"
+ );
+ assert_eq!(
+ build_ollama_url("http://localhost:11434/v1/chat/completions"),
+ "http://localhost:11434/v1/chat/completions"
+ );
+ }
+
+ #[test]
+ fn anthropic_url_normalizes_messages_endpoint() {
+ assert_eq!(
+ build_anthropic_url("https://api.anthropic.com"),
+ "https://api.anthropic.com/v1/messages"
+ );
+ assert_eq!(
+ build_anthropic_url("https://api.anthropic.com/v1"),
+ "https://api.anthropic.com/v1/messages"
+ );
+ assert_eq!(
+ build_anthropic_url("https://api.anthropic.com/v1/messages"),
+ "https://api.anthropic.com/v1/messages"
+ );
+ }
+
+ #[test]
+ fn azure_url_uses_model_as_deployment_name() {
+ let mut cfg = config("azure");
+ cfg.custom_endpoint = "https://resource.openai.azure.com".to_string();
+ cfg.model = "my deployment".to_string();
+ assert_eq!(
+ build_azure_url(&cfg).unwrap(),
+ "https://resource.openai.azure.com/openai/deployments/my%20deployment/chat/completions?api-version=2024-10-21"
+ );
+ }
+
+ #[test]
+ fn usability_matches_existing_provider_requirements() {
+ assert!(config("openai").is_usable_for_backend_http());
+ assert!(config("anthropic").is_usable_for_backend_http());
+ assert!(config("custom").is_usable_for_backend_http());
+ assert!(config("ollama").is_usable_for_backend_http());
+ assert!(!config("claude-code").is_usable_for_backend_http());
+ let mut missing_key = config("openai");
+ missing_key.api_key.clear();
+ assert!(!missing_key.is_usable_for_backend_http());
+ }
+
+ #[test]
+ fn llm_config_parses_existing_app_state_shape() {
+ let cfg: LlmConfig = serde_json::from_value(json!({
+ "provider": "custom",
+ "apiKey": "key",
+ "model": "model",
+ "ollamaUrl": "",
+ "customEndpoint": "https://example.com/v1",
+ "apiMode": "anthropic_messages",
+ "reasoning": {
+ "mode": "custom",
+ "budgetTokens": 4096
+ }
+ }))
+ .unwrap();
+
+ assert_eq!(cfg.api_key, "key");
+ assert_eq!(cfg.api_mode.as_deref(), Some("anthropic_messages"));
+ assert_eq!(
+ cfg.reasoning.as_ref().and_then(|r| r.budget_tokens),
+ Some(4096)
+ );
+ }
+
+ #[test]
+ fn trim_error_body_is_utf8_safe() {
+ let long = "错误".repeat(600);
+ let trimmed = trim_error_body(&long);
+ assert!(trimmed.ends_with("..."));
+ assert!(trimmed.is_char_boundary(trimmed.len()));
+ }
+
+ #[test]
+ fn openai_reasoning_off_does_not_emit_null_field() {
+ let mut body = json!({});
+ apply_openai_reasoning(
+ &mut body,
+ Some(&LlmReasoningConfig {
+ mode: Some("off".to_string()),
+ budget_tokens: None,
+ }),
+ );
+ assert!(body.get("reasoning_effort").is_none());
+ }
+
+ #[test]
+ fn parses_provider_stream_deltas() {
+ assert_eq!(
+ parse_openai_delta(r#"{"choices":[{"delta":{"content":"hello"}}]}"#).as_deref(),
+ Some("hello")
+ );
+ assert_eq!(
+ parse_anthropic_delta(
+ r#"{"type":"content_block_delta","delta":{"type":"text_delta","text":"world"}}"#
+ )
+ .as_deref(),
+ Some("world")
+ );
+ assert_eq!(
+ parse_google_delta(r#"{"candidates":[{"content":{"parts":[{"text":"gemini"}]}}]}"#)
+ .as_deref(),
+ Some("gemini")
+ );
+ }
+
+ #[test]
+ fn collects_sse_line_without_trailing_newline() {
+ let mut full = String::new();
+ let mut deltas = Vec::new();
+ collect_sse_line(
+ r#"data: {"choices":[{"delta":{"content":"tail"}}]}"#,
+ parse_openai_delta,
+ &mut |delta| deltas.push(delta.to_string()),
+ &mut full,
+ );
+
+ assert_eq!(full, "tail");
+ assert_eq!(deltas, vec!["tail"]);
+ }
+
+ #[test]
+ fn sse_byte_buffer_preserves_multibyte_utf8_across_chunks() {
+ let line = r#"data: {"choices":[{"delta":{"content":"煤矿"}}]}
+"#;
+ let split = line.find("矿").unwrap() + 1;
+ let mut buffer = Vec::new();
+ let mut full = String::new();
+ let mut deltas = Vec::new();
+
+ collect_sse_chunk_bytes(
+ &mut buffer,
+ &line.as_bytes()[..split],
+ parse_openai_delta,
+ &mut |delta| deltas.push(delta.to_string()),
+ &mut full,
+ );
+ assert!(full.is_empty());
+
+ collect_sse_chunk_bytes(
+ &mut buffer,
+ &line.as_bytes()[split..],
+ parse_openai_delta,
+ &mut |delta| deltas.push(delta.to_string()),
+ &mut full,
+ );
+
+ assert_eq!(full, "煤矿");
+ assert_eq!(deltas, vec!["煤矿"]);
+ }
+}
diff --git a/src-tauri/src/agent/router.rs b/src-tauri/src/agent/router.rs
new file mode 100644
index 00000000..94fb1cbe
--- /dev/null
+++ b/src-tauri/src/agent/router.rs
@@ -0,0 +1,146 @@
+use serde::{Deserialize, Serialize};
+
+use super::types::{AgentMode, AgentToolOptions};
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum QueryIntent {
+ NeedsInternalSearch,
+ NeedsExternalSearch,
+ NeedsRawSourceSearch,
+ NeedsGraph,
+ NeedsWrite,
+ SimpleConversational,
+ Ambiguous,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct RouterDecision {
+ pub intent: QueryIntent,
+ pub should_search_wiki: bool,
+ pub should_hint_web: bool,
+ pub should_hint_anytxt: bool,
+ pub should_include_sources: bool,
+ pub rationale: String,
+}
+
+pub fn route_query(message: &str, mode: AgentMode, tools: &AgentToolOptions) -> RouterDecision {
+ let lower = message.to_lowercase();
+ let trimmed = message.trim();
+ let explicit_web = contains_any(
+ &lower,
+ &[
+ "web search",
+ "search the web",
+ "internet",
+ "online",
+ "latest",
+ "today",
+ "新闻",
+ "联网",
+ "网上",
+ "最新",
+ ],
+ );
+ let explicit_raw = contains_any(
+ &lower,
+ &[
+ "raw source",
+ "source file",
+ "原始资料",
+ "原始文件",
+ "源文件",
+ ],
+ );
+ let explicit_graph = contains_any(&lower, &["graph", "relationship", "知识图谱", "关系图"]);
+ let explicit_write = contains_any(
+ &lower,
+ &["write to wiki", "create page", "写入", "创建页面"],
+ );
+ let conversational = trimmed.len() < 32
+ && contains_any(
+ &lower,
+ &["hi", "hello", "thanks", "谢谢", "你好", "好的", "ok"],
+ );
+
+ let intent = if explicit_write {
+ QueryIntent::NeedsWrite
+ } else if explicit_graph {
+ QueryIntent::NeedsGraph
+ } else if explicit_raw {
+ QueryIntent::NeedsRawSourceSearch
+ } else if explicit_web {
+ QueryIntent::NeedsExternalSearch
+ } else if conversational {
+ QueryIntent::SimpleConversational
+ } else if trimmed.ends_with('?') || trimmed.ends_with('?') || trimmed.len() > 24 {
+ QueryIntent::NeedsInternalSearch
+ } else {
+ QueryIntent::Ambiguous
+ };
+
+ let should_search_wiki = tools.wiki
+ && !matches!(intent, QueryIntent::SimpleConversational)
+ && !matches!(mode, AgentMode::Fast);
+
+ RouterDecision {
+ intent,
+ should_search_wiki,
+ should_hint_web: tools.web,
+ should_hint_anytxt: tools.anytxt,
+ should_include_sources: explicit_raw || matches!(mode, AgentMode::Deep),
+ rationale: match intent {
+ QueryIntent::NeedsExternalSearch => {
+ "User appears to request current/external information.".to_string()
+ }
+ QueryIntent::SimpleConversational => {
+ "Short conversational turn; avoid unnecessary retrieval.".to_string()
+ }
+ QueryIntent::NeedsRawSourceSearch => {
+ "User explicitly referenced raw/source material.".to_string()
+ }
+ QueryIntent::NeedsGraph => "User asks about graph/relationships.".to_string(),
+ QueryIntent::NeedsWrite => "User asks to create or update wiki content.".to_string(),
+ QueryIntent::NeedsInternalSearch => {
+ "User question likely benefits from project retrieval.".to_string()
+ }
+ QueryIntent::Ambiguous => "Ambiguous request; keep local wiki available.".to_string(),
+ },
+ }
+}
+
+fn contains_any(value: &str, needles: &[&str]) -> bool {
+ needles.iter().any(|needle| value.contains(needle))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn router_detects_external_search_hint_without_forcing_wiki_off() {
+ let decision = route_query(
+ "Search the web for latest policy updates",
+ AgentMode::Standard,
+ &AgentToolOptions {
+ wiki: true,
+ web: true,
+ anytxt: false,
+ },
+ );
+ assert_eq!(decision.intent, QueryIntent::NeedsExternalSearch);
+ assert!(decision.should_search_wiki);
+ assert!(decision.should_hint_web);
+ }
+
+ #[test]
+ fn fast_mode_skips_pre_search() {
+ let decision = route_query(
+ "What does the project say about embeddings?",
+ AgentMode::Fast,
+ &AgentToolOptions::default(),
+ );
+ assert!(!decision.should_search_wiki);
+ }
+}
diff --git a/src-tauri/src/agent/runtime.rs b/src-tauri/src/agent/runtime.rs
new file mode 100644
index 00000000..97e7f776
--- /dev/null
+++ b/src-tauri/src/agent/runtime.rs
@@ -0,0 +1,1758 @@
+use std::collections::BTreeMap;
+use std::future::Future;
+use std::sync::Arc;
+
+use serde::Deserialize;
+use uuid::Uuid;
+
+use crate::commands::search::SearchEmbeddingConfig;
+
+use super::cancel::AgentCancellationToken;
+use super::context::{
+ build_agent_context, collapse_whitespace, intent_label, load_project_context, trim_chars,
+ AgentContextInput, BuiltAgentContext,
+};
+use super::events::AgentEvent;
+use super::permissions::{AgentCapability, PermissionPolicy};
+use super::provider::{AgentLlmProvider, LlmClient, LlmConfig};
+use super::router::route_query;
+use super::skills::load_project_skills;
+use super::tools::{self, AnyTxtConfig, ToolRegistry, WebSearchConfig};
+use super::types::{
+ AgentChatRequest, AgentChatResponse, AgentMode, AgentReference, AgentToolEvent, AgentUsage,
+};
+
+// These limits are intentionally enforced in the backend Agent rather than the
+// React UI. API and MCP callers bypass the UI, so safety and cost boundaries
+// must live here.
+const DEFAULT_CHAT_SEARCH_RESULTS: usize = 5;
+const MAX_CHAT_SEARCH_RESULTS: usize = 10;
+const MAX_IMAGES_PER_TURN: usize = 5;
+const MAX_IMAGE_BASE64_BYTES: usize = 7 * 1024 * 1024;
+
+pub type AgentEventSink = Arc<dyn Fn(AgentEvent) + Send + Sync>;
+
+#[derive(Debug, Clone)]
+pub struct AgentRuntime {
+ project_id: String,
+ project_path: String,
+ embedding_config: Option<SearchEmbeddingConfig>,
+ llm_config: Option<LlmConfig>,
+ web_search_config: Option<WebSearchConfig>,
+ anytxt_config: Option<AnyTxtConfig>,
+}
+
+#[derive(Debug, Clone, Default, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct ModelToolPlan {
+ #[serde(default)]
+ tool_calls: Vec<ModelToolCall>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct ModelToolCall {
+ tool: String,
+ #[serde(default)]
+ query: Option<String>,
+ #[serde(default)]
+ path: Option<String>,
+ #[serde(default)]
+ content: Option<String>,
+ // Overwriting existing wiki pages is destructive. The planner may set this
+ // only when the user explicitly asks to update/overwrite an existing page;
+ // the tool defaults to create-only when the field is absent.
+ #[serde(default)]
+ allow_overwrite: Option<bool>,
+}
+
+impl AgentRuntime {
+ pub fn new(
+ project_id: impl Into<String>,
+ project_path: impl Into<String>,
+ embedding_config: Option<SearchEmbeddingConfig>,
+ llm_config: Option<LlmConfig>,
+ web_search_config: Option<WebSearchConfig>,
+ anytxt_config: Option<AnyTxtConfig>,
+ ) -> Self {
+ Self {
+ project_id: project_id.into(),
+ project_path: project_path.into(),
+ embedding_config,
+ llm_config,
+ web_search_config,
+ anytxt_config,
+ }
+ }
+
+ #[allow(dead_code)]
+ pub async fn run_once(&self, request: AgentChatRequest) -> Result<AgentChatResponse, String> {
+ self.run_once_with_cancel(request, None).await
+ }
+
+ pub async fn run_once_with_cancel(
+ &self,
+ request: AgentChatRequest,
+ cancellation: Option<AgentCancellationToken>,
+ ) -> Result<AgentChatResponse, String> {
+ self.run_once_with_cancel_and_events(request, cancellation, None)
+ .await
+ }
+
+ pub async fn run_once_with_cancel_and_events(
+ &self,
+ request: AgentChatRequest,
+ cancellation: Option<AgentCancellationToken>,
+ event_sink: Option<AgentEventSink>,
+ ) -> Result<AgentChatResponse, String> {
+ let message = request.message.trim();
+ if message.is_empty() {
+ return Err("message is required".to_string());
+ }
+ validate_images(&request.images)?;
+ check_cancel(cancellation.as_ref())?;
+
+ let session_id = request
+ .session_id
+ .filter(|id| !id.trim().is_empty())
+ .unwrap_or_else(|| format!("api_{}", Uuid::new_v4()));
+ let mut tool_events = Vec::new();
+ let mut events = Vec::new();
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::AgentStart {
+ session_id: session_id.clone(),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::TurnStart {
+ mode: mode_label(request.mode).to_string(),
+ },
+ );
+ let mut references = Vec::new();
+ let permission_policy = PermissionPolicy::api_default();
+ let router = route_query(message, request.mode, &request.tools);
+ let skills = load_project_skills(&self.project_path, &request.skills);
+ check_cancel(cancellation.as_ref())?;
+ let model_plan = self
+ .plan_tools_with_model(message, request.mode, &request.tools, cancellation.as_ref())
+ .await
+ .unwrap_or_default();
+ if !model_plan.tool_calls.is_empty() {
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "agent.plan_tools".to_string(),
+ status: "completed".to_string(),
+ detail: Some(format!(
+ "{} planned tool call(s)",
+ model_plan.tool_calls.len()
+ )),
+ },
+ );
+ }
+ let planned_queries = planned_tool_queries(&model_plan, message);
+ let planned_has = |tool: &str| planned_queries.contains_key(tool);
+ if !request.skills.is_empty() {
+ permission_policy.require(AgentCapability::ReadProject)?;
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "skills.load".to_string(),
+ status: "completed".to_string(),
+ detail: Some(format!("{} skill(s) active", skills.len())),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end(
+ "skills.load",
+ Some(format!("{} skill(s) active", skills.len())),
+ ),
+ );
+ }
+
+ if request.tools.web {
+ permission_policy.require(AgentCapability::SearchWeb)?;
+ tool_emit_event(&mut tool_events, &mut events, &event_sink, AgentToolEvent {
+ tool: "web.search".to_string(),
+ status: "available".to_string(),
+ detail: Some("Web search is enabled for this turn. Router decides whether to execute it immediately.".to_string()),
+ });
+ }
+ if request.tools.anytxt {
+ permission_policy.require(AgentCapability::SearchAnyTxt)?;
+ tool_emit_event(&mut tool_events, &mut events, &event_sink, AgentToolEvent {
+ tool: "anytxt.search".to_string(),
+ status: "available".to_string(),
+ detail: Some("AnyTXT search is enabled for this turn. Router decides whether to execute it immediately.".to_string()),
+ });
+ }
+
+ let mut retrieval_parts = Vec::new();
+ let tool_registry = tools::BuiltinToolRegistry::default();
+ let should_search_wiki = router.should_search_wiki || planned_has("wiki.search");
+ let should_include_sources = router.should_include_sources || planned_has("source.search");
+ let should_search_graph = matches!(router.intent, super::router::QueryIntent::NeedsGraph)
+ || planned_has("graph.search");
+ let should_run_web = request.tools.web
+ && (matches!(
+ router.intent,
+ super::router::QueryIntent::NeedsExternalSearch
+ ) || planned_has("web.search")
+ || matches!(request.mode, AgentMode::Deep));
+ let should_run_anytxt = request.tools.anytxt
+ && (should_include_sources
+ || planned_has("anytxt.search")
+ || matches!(request.mode, AgentMode::Deep));
+ let deep_research = matches!(request.mode, AgentMode::Deep)
+ && (should_run_web || should_run_anytxt || should_include_sources);
+
+ if let Some(write_call) = model_plan
+ .tool_calls
+ .iter()
+ .find(|call| call.tool.trim() == "wiki.write_page")
+ {
+ check_cancel(cancellation.as_ref())?;
+ permission_policy.require(AgentCapability::WriteWiki)?;
+ let path = write_call
+ .path
+ .as_deref()
+ .map(str::trim)
+ .filter(|path| !path.is_empty())
+ .ok_or_else(|| "wiki.write_page requires path".to_string())?;
+ let content = write_call
+ .content
+ .as_deref()
+ .map(str::trim)
+ .filter(|content| !content.is_empty())
+ .ok_or_else(|| "wiki.write_page requires content".to_string())?;
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "wiki.write_page".to_string(),
+ status: "started".to_string(),
+ detail: Some(path.to_string()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_start("wiki.write_page", Some(path.to_string())),
+ );
+ let tool_context = self.tool_context();
+ match execute_tool_with_cancellation(
+ tool_registry.execute(
+ "wiki.write_page",
+ serde_json::json!({
+ "path": path,
+ "content": content,
+ "allowOverwrite": write_call.allow_overwrite.unwrap_or(false),
+ }),
+ tool_context,
+ ),
+ cancellation.as_ref(),
+ )
+ .await
+ .and_then(|value| {
+ serde_json::from_value::<AgentReference>(value)
+ .map_err(|err| format!("Invalid wiki.write_page result: {err}"))
+ }) {
+ Ok(reference) => {
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::ReferenceAdded {
+ reference: reference.clone(),
+ },
+ );
+ references.push(reference);
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "wiki.write_page".to_string(),
+ status: "completed".to_string(),
+ detail: Some(path.to_string()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end("wiki.write_page", Some(path.to_string())),
+ );
+ retrieval_parts.push(format!("wiki.write_page wrote {path}."));
+ }
+ Err(err) => {
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "wiki.write_page".to_string(),
+ status: "failed".to_string(),
+ detail: Some(err.clone()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end("wiki.write_page", Some(format!("failed: {err}"))),
+ );
+ }
+ }
+ }
+
+ if deep_research {
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "deep_research.run".to_string(),
+ status: "started".to_string(),
+ detail: Some(message.to_string()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_start("deep_research.run", Some(message.to_string())),
+ );
+ }
+
+ if should_search_wiki {
+ check_cancel(cancellation.as_ref())?;
+ permission_policy.require(AgentCapability::SearchWiki)?;
+ let wiki_query = planned_queries
+ .get("wiki.search")
+ .map(String::as_str)
+ .unwrap_or(message);
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "wiki.search".to_string(),
+ status: "started".to_string(),
+ detail: Some(wiki_query.to_string()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_start("wiki.search", Some(wiki_query.to_string())),
+ );
+ let top_k = request
+ .top_k
+ .unwrap_or(DEFAULT_CHAT_SEARCH_RESULTS)
+ .clamp(1, MAX_CHAT_SEARCH_RESULTS);
+ let wiki_search = execute_tool_with_cancellation(
+ tool_registry.execute(
+ "wiki.search",
+ serde_json::json!({
+ "query": wiki_query,
+ "topK": top_k,
+ "includeContent": request.include_content.unwrap_or(false)
+ }),
+ self.tool_context(),
+ ),
+ cancellation.as_ref(),
+ )
+ .await
+ .and_then(|value| {
+ serde_json::from_value::<tools::WikiSearchToolOutput>(value)
+ .map_err(|err| format!("Invalid wiki.search result: {err}"))
+ });
+ match wiki_search {
+ Ok(search) => {
+ check_cancel(cancellation.as_ref())?;
+ let search_refs = search.references;
+ for reference in &search_refs {
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::ReferenceAdded {
+ reference: reference.clone(),
+ },
+ );
+ }
+ let search_count = search_refs.len();
+ references.extend(search_refs);
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "wiki.search".to_string(),
+ status: "completed".to_string(),
+ detail: Some(format!(
+ "{} result(s), mode={}, tokenHits={}, vectorHits={}",
+ search_count, search.mode, search.token_hits, search.vector_hits
+ )),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end(
+ "wiki.search",
+ Some(format!("{search_count} result(s)")),
+ ),
+ );
+ retrieval_parts.push(build_retrieval_answer(message, &references));
+ }
+ Err(err) => {
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "wiki.search".to_string(),
+ status: "failed".to_string(),
+ detail: Some(err.clone()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end("wiki.search", Some(format!("failed: {err}"))),
+ );
+ }
+ }
+ if matches!(request.mode, AgentMode::Deep) && !references.is_empty() {
+ permission_policy.require(AgentCapability::ReadProject)?;
+ let excerpts = references
+ .iter()
+ .filter(|reference| reference.kind == "wiki")
+ .take(2)
+ .filter_map(|reference| {
+ tools::read_wiki_page(&self.project_path, &reference.path)
+ .ok()
+ .map(|content| {
+ format!(
+ "Excerpt from {}:\n{}",
+ reference.path,
+ collapse_whitespace(&content)
+ .chars()
+ .take(2_000)
+ .collect::<String>()
+ )
+ })
+ })
+ .collect::<Vec<_>>();
+ if !excerpts.is_empty() {
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "wiki.read_page".to_string(),
+ status: "completed".to_string(),
+ detail: Some(format!("{} excerpt(s)", excerpts.len())),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end(
+ "wiki.read_page",
+ Some(format!("{} excerpt(s)", excerpts.len())),
+ ),
+ );
+ retrieval_parts.push(excerpts.join("\n\n"));
+ }
+ }
+ } else if request.tools.wiki {
+ retrieval_parts.push(format!(
+ "Router intent={} did not require immediate wiki.search for this turn.",
+ intent_label(router.intent)
+ ));
+ }
+
+ if should_include_sources {
+ check_cancel(cancellation.as_ref())?;
+ permission_policy.require(AgentCapability::ReadSource)?;
+ let source_query = planned_queries
+ .get("source.search")
+ .map(String::as_str)
+ .unwrap_or(message);
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "source.search".to_string(),
+ status: "started".to_string(),
+ detail: Some(source_query.to_string()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_start("source.search", Some(source_query.to_string())),
+ );
+ match execute_tool_with_cancellation(
+ tool_registry.execute(
+ "source.search",
+ serde_json::json!({
+ "query": source_query,
+ "topK": request
+ .top_k
+ .unwrap_or(DEFAULT_CHAT_SEARCH_RESULTS)
+ .clamp(1, MAX_CHAT_SEARCH_RESULTS)
+ }),
+ self.tool_context(),
+ ),
+ cancellation.as_ref(),
+ )
+ .await
+ .and_then(|value| {
+ serde_json::from_value::<Vec<AgentReference>>(value)
+ .map_err(|err| format!("Invalid source.search result: {err}"))
+ }) {
+ Ok(source_refs) => {
+ for reference in &source_refs {
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::ReferenceAdded {
+ reference: reference.clone(),
+ },
+ );
+ }
+ let count = source_refs.len();
+ references.extend(source_refs);
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "source.search".to_string(),
+ status: "completed".to_string(),
+ detail: Some(format!("{count} result(s)")),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end("source.search", Some(format!("{count} result(s)"))),
+ );
+ }
+ Err(err) => {
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "source.search".to_string(),
+ status: "failed".to_string(),
+ detail: Some(err.clone()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end("source.search", Some(format!("failed: {err}"))),
+ );
+ }
+ }
+ }
+
+ if should_search_graph {
+ check_cancel(cancellation.as_ref())?;
+ permission_policy.require(AgentCapability::ReadProject)?;
+ let graph_query = planned_queries
+ .get("graph.search")
+ .map(String::as_str)
+ .unwrap_or(message);
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "graph.search".to_string(),
+ status: "started".to_string(),
+ detail: Some(graph_query.to_string()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_start("graph.search", Some(graph_query.to_string())),
+ );
+ match execute_tool_with_cancellation(
+ tool_registry.execute(
+ "graph.search",
+ serde_json::json!({
+ "query": graph_query,
+ "topK": request
+ .top_k
+ .unwrap_or(DEFAULT_CHAT_SEARCH_RESULTS)
+ .clamp(1, MAX_CHAT_SEARCH_RESULTS)
+ }),
+ self.tool_context(),
+ ),
+ cancellation.as_ref(),
+ )
+ .await
+ .and_then(|value| {
+ serde_json::from_value::<Vec<AgentReference>>(value)
+ .map_err(|err| format!("Invalid graph.search result: {err}"))
+ }) {
+ Ok(graph_refs) => {
+ for reference in &graph_refs {
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::ReferenceAdded {
+ reference: reference.clone(),
+ },
+ );
+ }
+ let count = graph_refs.len();
+ references.extend(graph_refs);
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "graph.search".to_string(),
+ status: "completed".to_string(),
+ detail: Some(format!("{count} result(s)")),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end("graph.search", Some(format!("{count} result(s)"))),
+ );
+ }
+ Err(err) => {
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "graph.search".to_string(),
+ status: "failed".to_string(),
+ detail: Some(err.clone()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end("graph.search", Some(format!("failed: {err}"))),
+ );
+ }
+ }
+ }
+
+ if should_run_web {
+ check_cancel(cancellation.as_ref())?;
+ permission_policy.require(AgentCapability::Network)?;
+ let web_query = planned_queries
+ .get("web.search")
+ .map(String::as_str)
+ .unwrap_or(message);
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "web.search".to_string(),
+ status: "started".to_string(),
+ detail: Some(web_query.to_string()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_start("web.search", Some(web_query.to_string())),
+ );
+ match execute_tool_with_cancellation(
+ tool_registry.execute(
+ "web.search",
+ serde_json::json!({
+ "query": web_query,
+ "topK": request
+ .top_k
+ .unwrap_or(DEFAULT_CHAT_SEARCH_RESULTS)
+ .clamp(1, MAX_CHAT_SEARCH_RESULTS)
+ }),
+ self.tool_context(),
+ ),
+ cancellation.as_ref(),
+ )
+ .await
+ .and_then(|value| {
+ serde_json::from_value::<Vec<AgentReference>>(value)
+ .map_err(|err| format!("Invalid web.search result: {err}"))
+ }) {
+ Ok(web_refs) => {
+ check_cancel(cancellation.as_ref())?;
+ for reference in &web_refs {
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::ReferenceAdded {
+ reference: reference.clone(),
+ },
+ );
+ }
+ let count = web_refs.len();
+ references.extend(web_refs);
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "web.search".to_string(),
+ status: "completed".to_string(),
+ detail: Some(format!("{count} result(s)")),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end("web.search", Some(format!("{count} result(s)"))),
+ );
+ }
+ Err(err) => {
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "web.search".to_string(),
+ status: "failed".to_string(),
+ detail: Some(err.clone()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end("web.search", Some(format!("failed: {err}"))),
+ );
+ }
+ }
+ }
+
+ if should_run_anytxt {
+ check_cancel(cancellation.as_ref())?;
+ permission_policy.require(AgentCapability::Network)?;
+ let anytxt_query = planned_queries
+ .get("anytxt.search")
+ .map(String::as_str)
+ .unwrap_or(message);
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "anytxt.search".to_string(),
+ status: "started".to_string(),
+ detail: Some(anytxt_query.to_string()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_start("anytxt.search", Some(anytxt_query.to_string())),
+ );
+ match execute_tool_with_cancellation(
+ tool_registry.execute(
+ "anytxt.search",
+ serde_json::json!({
+ "query": anytxt_query,
+ "topK": request
+ .top_k
+ .unwrap_or(DEFAULT_CHAT_SEARCH_RESULTS)
+ .clamp(1, MAX_CHAT_SEARCH_RESULTS)
+ }),
+ self.tool_context(),
+ ),
+ cancellation.as_ref(),
+ )
+ .await
+ .and_then(|value| {
+ serde_json::from_value::<Vec<AgentReference>>(value)
+ .map_err(|err| format!("Invalid anytxt.search result: {err}"))
+ }) {
+ Ok(anytxt_refs) => {
+ check_cancel(cancellation.as_ref())?;
+ for reference in &anytxt_refs {
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::ReferenceAdded {
+ reference: reference.clone(),
+ },
+ );
+ }
+ let count = anytxt_refs.len();
+ references.extend(anytxt_refs);
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "anytxt.search".to_string(),
+ status: "completed".to_string(),
+ detail: Some(format!("{count} result(s)")),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end("anytxt.search", Some(format!("{count} result(s)"))),
+ );
+ }
+ Err(err) => {
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "anytxt.search".to_string(),
+ status: "failed".to_string(),
+ detail: Some(err.clone()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end("anytxt.search", Some(format!("failed: {err}"))),
+ );
+ }
+ }
+ }
+
+ if deep_research {
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "deep_research.run".to_string(),
+ status: "completed".to_string(),
+ detail: Some(format!("{} reference(s)", references.len())),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::tool_end(
+ "deep_research.run",
+ Some(format!("{} reference(s)", references.len())),
+ ),
+ );
+ }
+
+ if retrieval_parts.is_empty() {
+ if !request.tools.wiki && !request.tools.web && !request.tools.anytxt {
+ retrieval_parts.push("No Agent tools were enabled for this request. Enable wiki, web, or AnyTXT tools to let the backend Agent retrieve supporting context.".to_string());
+ } else {
+ retrieval_parts.push(
+ "No Agent tools ran before generation. Available tools were exposed as model hints."
+ .to_string(),
+ );
+ }
+ }
+ let retrieval_summary = retrieval_parts.join("\n\n");
+ let project_context = load_project_context(&self.project_path);
+ let built_context = fit_context_to_model(
+ build_agent_context(AgentContextInput {
+ query: message,
+ project: &project_context,
+ router: &router,
+ history: &request.history,
+ skills: &skills,
+ references: &references,
+ retrieval_summary: &retrieval_summary,
+ }),
+ self.llm_config.as_ref(),
+ );
+
+ let answer = if let Some(config) = self
+ .llm_config
+ .as_ref()
+ .filter(|cfg| cfg.is_usable_for_backend_http())
+ {
+ check_cancel(cancellation.as_ref())?;
+ let client = LlmClient::new(config.clone())?;
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "llm.generate".to_string(),
+ status: "started".to_string(),
+ detail: Some(format!(
+ "{}:{}",
+ client.provider_name(),
+ client.model_name()
+ )),
+ },
+ );
+ let generation = if event_sink.is_some() {
+ generate_with_cancellation_stream(
+ &client,
+ &built_context.system,
+ &built_context.user,
+ &request.images,
+ cancellation.as_ref(),
+ |delta| {
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::MessageDelta {
+ text: delta.to_string(),
+ },
+ );
+ },
+ )
+ .await
+ } else {
+ generate_with_cancellation(
+ &client,
+ &built_context.system,
+ &built_context.user,
+ &request.images,
+ cancellation.as_ref(),
+ )
+ .await
+ };
+ match generation {
+ Ok(answer) => {
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "llm.generate".to_string(),
+ status: "completed".to_string(),
+ detail: None,
+ },
+ );
+ answer
+ }
+ Err(err) => {
+ tool_emit_event(
+ &mut tool_events,
+ &mut events,
+ &event_sink,
+ AgentToolEvent {
+ tool: "llm.generate".to_string(),
+ status: "failed".to_string(),
+ detail: Some(err.clone()),
+ },
+ );
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::Error {
+ message: err.clone(),
+ },
+ );
+ return Err(err);
+ }
+ }
+ } else {
+ retrieval_summary
+ };
+ emit_event(
+ &mut events,
+ &event_sink,
+ AgentEvent::Done {
+ session_id: session_id.clone(),
+ },
+ );
+ let usage = AgentUsage {
+ prompt_chars: built_context.system.len() + built_context.user.len(),
+ completion_chars: answer.len(),
+ reference_count: references.len(),
+ tool_event_count: tool_events.len(),
+ };
+
+ Ok(AgentChatResponse {
+ ok: true,
+ project_id: self.project_id.clone(),
+ session_id,
+ mode: request.mode,
+ message: answer,
+ references,
+ tool_events,
+ events,
+ usage: Some(usage),
+ })
+ }
+}
+
+impl AgentRuntime {
+ fn tool_context(&self) -> tools::ToolContext<'_> {
+ tools::ToolContext {
+ project_path: &self.project_path,
+ embedding_config: self.embedding_config.clone(),
+ web_search_config: self.web_search_config.clone(),
+ anytxt_config: self.anytxt_config.clone(),
+ }
+ }
+
+ async fn plan_tools_with_model(
+ &self,
+ message: &str,
+ mode: AgentMode,
+ tools: &super::types::AgentToolOptions,
+ cancellation: Option<&AgentCancellationToken>,
+ ) -> Result<ModelToolPlan, String> {
+ if !should_plan_tools_with_model(message, mode, tools) {
+ return Ok(ModelToolPlan::default());
+ }
+ let Some(config) = self
+ .llm_config
+ .as_ref()
+ .filter(|cfg| cfg.is_usable_for_backend_http())
+ else {
+ return Ok(ModelToolPlan::default());
+ };
+ check_cancel(cancellation)?;
+ let mut available = vec![
+ "wiki.search",
+ "source.search",
+ "graph.search",
+ "wiki.write_page",
+ ];
+ if tools.web {
+ available.push("web.search");
+ }
+ if tools.anytxt {
+ available.push("anytxt.search");
+ }
+ let system = "You are an agent tool planner. Return only compact JSON. Do not explain.";
+ let user = format!(
+ "User request:\n{message}\n\nAvailable tools: {}\n\nReturn JSON exactly like {{\"toolCalls\":[{{\"tool\":\"wiki.search\",\"query\":\"short query\"}}]}}. Use an empty array when no tool is needed. Prefer web.search only for current/external information. Prefer anytxt.search only for user files outside the wiki. Prefer wiki.search for project knowledge. Use wiki.write_page only when the user explicitly asks to create a wiki page; include path under wiki/ ending in .md and full Markdown content. Existing pages are create-only by default; include allowOverwrite:true only when the user explicitly asks to overwrite or update an existing wiki page.",
+ available.join(", ")
+ );
+ let client = LlmClient::new(config.clone())?;
+ let raw = generate_with_cancellation(&client, system, &user, &[], cancellation).await?;
+ parse_model_tool_plan(&raw)
+ }
+}
+
+fn should_plan_tools_with_model(
+ message: &str,
+ mode: AgentMode,
+ tools: &super::types::AgentToolOptions,
+) -> bool {
+ if matches!(mode, AgentMode::Fast) {
+ return false;
+ }
+ tools.web || tools.anytxt || looks_like_wiki_write_request(message)
+}
+
+fn looks_like_wiki_write_request(message: &str) -> bool {
+ let lower = message.to_lowercase();
+ let mentions_wiki = lower.contains("wiki")
+ || lower.contains("page")
+ || lower.contains("页面")
+ || lower.contains("词条")
+ || lower.contains("笔记");
+ let asks_write = lower.contains("create")
+ || lower.contains("write")
+ || lower.contains("update")
+ || lower.contains("save")
+ || lower.contains("生成")
+ || lower.contains("创建")
+ || lower.contains("新建")
+ || lower.contains("写入")
+ || lower.contains("保存")
+ || lower.contains("更新");
+ mentions_wiki && asks_write
+}
+
+fn planned_tool_queries(plan: &ModelToolPlan, fallback_query: &str) -> BTreeMap<String, String> {
+ let mut out = BTreeMap::new();
+ for call in &plan.tool_calls {
+ let tool = call.tool.trim();
+ if !matches!(
+ tool,
+ "wiki.search"
+ | "source.search"
+ | "graph.search"
+ | "web.search"
+ | "anytxt.search"
+ | "wiki.write_page"
+ ) {
+ continue;
+ }
+ let query = call
+ .query
+ .as_deref()
+ .map(str::trim)
+ .filter(|query| !query.is_empty())
+ .unwrap_or(fallback_query);
+ out.entry(tool.to_string())
+ .or_insert_with(|| query.to_string());
+ }
+ out
+}
+
+fn parse_model_tool_plan(raw: &str) -> Result<ModelToolPlan, String> {
+ let json_text = extract_json_object(raw).unwrap_or(raw).trim();
+ serde_json::from_str(json_text).map_err(|err| format!("Invalid Agent tool plan JSON: {err}"))
+}
+
+fn extract_json_object(raw: &str) -> Option<&str> {
+ let start = raw.find('{')?;
+ let end = raw.rfind('}')?;
+ if end <= start {
+ return None;
+ }
+ Some(&raw[start..=end])
+}
+
+fn check_cancel(cancellation: Option<&AgentCancellationToken>) -> Result<(), String> {
+ if let Some(token) = cancellation {
+ token.check()?;
+ }
+ Ok(())
+}
+
+fn fit_context_to_model(
+ mut context: BuiltAgentContext,
+ config: Option<&LlmConfig>,
+) -> BuiltAgentContext {
+ let Some(max_context_size) = config.and_then(|cfg| cfg.max_context_size) else {
+ return context;
+ };
+ let max_chars = max_context_size.clamp(8_000, 400_000);
+ let total_chars = context.system.chars().count() + context.user.chars().count();
+ if total_chars <= max_chars {
+ return context;
+ }
+ let user_budget = max_chars
+ .saturating_sub(context.system.chars().count())
+ .max(4_000);
+ context.user = trim_chars(&context.user, user_budget);
+ context
+}
+
+// Tool futures may include network I/O or blocking-pool filesystem scans.
+// Cancelling the turn should stop waiting for them immediately. A blocking task
+// already running in Tokio's blocking pool cannot be force-killed, so the
+// contract is "stop the Agent turn promptly", not "terminate the OS work".
+async fn execute_tool_with_cancellation<F>(
+ future: F,
+ cancellation: Option<&AgentCancellationToken>,
+) -> Result<serde_json::Value, String>
+where
+ F: Future<Output = Result<serde_json::Value, String>>,
+{
+ if let Some(token) = cancellation {
+ tokio::select! {
+ biased;
+ _ = token.cancelled() => Err("Agent turn cancelled".to_string()),
+ result = future => result,
+ }
+ } else {
+ future.await
+ }
+}
+
+fn validate_images(images: &[super::types::AgentImage]) -> Result<(), String> {
+ if images.len() > MAX_IMAGES_PER_TURN {
+ return Err(format!(
+ "At most {MAX_IMAGES_PER_TURN} images can be attached to one Agent turn"
+ ));
+ }
+ for image in images {
+ let media_type = image.media_type.trim();
+ if !matches!(
+ media_type,
+ "image/png" | "image/jpeg" | "image/webp" | "image/gif"
+ ) {
+ return Err(format!("Unsupported image media type: {media_type}"));
+ }
+ if image.data_base64.len() > MAX_IMAGE_BASE64_BYTES {
+ return Err("Attached image is too large".to_string());
+ }
+ if image.data_base64.trim().is_empty() {
+ return Err("Attached image is empty".to_string());
+ }
+ }
+ Ok(())
+}
+
+fn emit_event(
+ events: &mut Vec<AgentEvent>,
+ event_sink: &Option<AgentEventSink>,
+ event: AgentEvent,
+) {
+ if let Some(sink) = event_sink {
+ sink(event.clone());
+ }
+ events.push(event);
+}
+
+fn tool_emit_event(
+ tool_events: &mut Vec<AgentToolEvent>,
+ _events: &mut Vec<AgentEvent>,
+ _event_sink: &Option<AgentEventSink>,
+ tool_event: AgentToolEvent,
+) {
+ tool_events.push(tool_event);
+}
+
+async fn generate_with_cancellation<P: AgentLlmProvider>(
+ provider: &P,
+ system: &str,
+ user: &str,
+ images: &[super::types::AgentImage],
+ cancellation: Option<&AgentCancellationToken>,
+) -> Result<String, String> {
+ if let Some(token) = cancellation {
+ tokio::select! {
+ biased;
+ _ = token.cancelled() => Err("Agent turn cancelled".to_string()),
+ result = provider.generate_text(system, user, images) => result,
+ }
+ } else {
+ provider.generate_text(system, user, images).await
+ }
+}
+
+async fn generate_with_cancellation_stream<P, F>(
+ provider: &P,
+ system: &str,
+ user: &str,
+ images: &[super::types::AgentImage],
+ cancellation: Option<&AgentCancellationToken>,
+ on_delta: F,
+) -> Result<String, String>
+where
+ P: AgentLlmProvider,
+ F: FnMut(&str) + Send,
+{
+ if let Some(token) = cancellation {
+ tokio::select! {
+ biased;
+ _ = token.cancelled() => Err("Agent turn cancelled".to_string()),
+ result = provider.generate_text_stream(system, user, images, Box::new(on_delta)) => result,
+ }
+ } else {
+ provider
+ .generate_text_stream(system, user, images, Box::new(on_delta))
+ .await
+ }
+}
+
+fn build_retrieval_answer(query: &str, references: &[AgentReference]) -> String {
+ if references.is_empty() {
+ return format!(
+ "I searched the current LLM Wiki project for \"{query}\" but did not find matching wiki pages."
+ );
+ }
+
+ let mut out = format!(
+ "I searched the current LLM Wiki project for \"{query}\" and found {} relevant page(s):",
+ references.len()
+ );
+ for (idx, reference) in references.iter().take(MAX_CHAT_SEARCH_RESULTS).enumerate() {
+ out.push_str(&format!(
+ "\n{}. {} ({})",
+ idx + 1,
+ reference.title,
+ reference.path
+ ));
+ if let Some(snippet) = reference.snippet.as_deref() {
+ out.push_str(&format!("\n {}", collapse_whitespace(snippet)));
+ }
+ }
+ out
+}
+
+fn mode_label(mode: AgentMode) -> &'static str {
+ match mode {
+ AgentMode::Fast => "fast",
+ AgentMode::Standard => "standard",
+ AgentMode::Deep => "deep",
+ AgentMode::LocalFirst => "local_first",
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use std::fs;
+ use std::path::PathBuf;
+
+ use super::*;
+ use crate::agent::types::{AgentMode, AgentToolOptions};
+
+ fn temp_project(name: &str) -> PathBuf {
+ let root =
+ std::env::temp_dir().join(format!("llm-wiki-agent-test-{name}-{}", Uuid::new_v4()));
+ fs::create_dir_all(root.join("wiki").join("concepts")).unwrap();
+ root
+ }
+
+ #[tokio::test]
+ async fn run_once_searches_wiki_and_returns_references() {
+ let project = temp_project("search");
+ fs::write(
+ project.join("wiki").join("concepts").join("agent-runtime.md"),
+ "---\ntitle: Agent Runtime\n---\n# Agent Runtime\n\nRust backend agent substrate with tool calls.",
+ )
+ .unwrap();
+
+ let runtime = AgentRuntime::new(
+ "project-1",
+ project.to_string_lossy(),
+ None,
+ None,
+ None,
+ None,
+ );
+ let response = runtime
+ .run_once(AgentChatRequest {
+ message: "agent runtime".to_string(),
+ session_id: Some("s1".to_string()),
+ mode: AgentMode::Standard,
+ tools: AgentToolOptions {
+ wiki: true,
+ web: false,
+ anytxt: false,
+ },
+ top_k: Some(3),
+ include_content: Some(false),
+ history: Vec::new(),
+ skills: Vec::new(),
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+
+ assert!(response.ok);
+ assert_eq!(response.session_id, "s1");
+ assert_eq!(response.references.len(), 1);
+ assert_eq!(
+ response.references[0].path,
+ "wiki/concepts/agent-runtime.md"
+ );
+ assert!(response.message.contains("Agent Runtime"));
+ assert_eq!(response.tool_events[0].tool, "wiki.search");
+ }
+
+ #[tokio::test]
+ async fn run_once_rejects_empty_message() {
+ let project = temp_project("empty");
+ let runtime = AgentRuntime::new(
+ "project-1",
+ project.to_string_lossy(),
+ None,
+ None,
+ None,
+ None,
+ );
+ let err = runtime
+ .run_once(AgentChatRequest {
+ message: " ".to_string(),
+ session_id: None,
+ mode: AgentMode::Fast,
+ tools: AgentToolOptions::default(),
+ top_k: None,
+ include_content: None,
+ history: Vec::new(),
+ skills: Vec::new(),
+ ..Default::default()
+ })
+ .await
+ .unwrap_err();
+ assert_eq!(err, "message is required");
+ }
+
+ #[test]
+ fn fit_context_to_model_honors_configured_context_size() {
+ let context = BuiltAgentContext {
+ system: "system".repeat(100),
+ user: "user".repeat(10_000),
+ };
+ let config = LlmConfig {
+ provider: "custom".to_string(),
+ api_key: String::new(),
+ model: "local".to_string(),
+ ollama_url: String::new(),
+ custom_endpoint: "http://127.0.0.1:11434/v1".to_string(),
+ azure_api_version: None,
+ api_mode: None,
+ reasoning: None,
+ max_context_size: Some(8_000),
+ };
+ let fitted = fit_context_to_model(context, Some(&config));
+ assert!(fitted.system.contains("system"));
+ assert!(fitted.user.chars().count() <= 7_400);
+ assert!(fitted.user.ends_with("..."));
+ }
+
+ #[tokio::test]
+ async fn run_once_can_disable_wiki_tool() {
+ let project = temp_project("disabled");
+ let runtime = AgentRuntime::new(
+ "project-1",
+ project.to_string_lossy(),
+ None,
+ None,
+ None,
+ None,
+ );
+ let response = runtime
+ .run_once(AgentChatRequest {
+ message: "anything".to_string(),
+ session_id: None,
+ mode: AgentMode::LocalFirst,
+ tools: AgentToolOptions {
+ wiki: false,
+ web: false,
+ anytxt: false,
+ },
+ top_k: None,
+ include_content: None,
+ history: Vec::new(),
+ skills: Vec::new(),
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+
+ assert!(response.references.is_empty());
+ assert!(response.tool_events.is_empty());
+ assert!(response.message.contains("No Agent tools were enabled"));
+ }
+
+ #[tokio::test]
+ async fn run_once_in_fast_mode_exposes_tools_without_presearching() {
+ let project = temp_project("fast");
+ fs::write(
+ project.join("overview.md"),
+ "This project covers search routing.",
+ )
+ .unwrap();
+ fs::write(
+ project.join("wiki").join("concepts").join("routing.md"),
+ "# Routing\n\nThis should not be searched in fast mode.",
+ )
+ .unwrap();
+
+ let runtime = AgentRuntime::new(
+ "project-1",
+ project.to_string_lossy(),
+ None,
+ None,
+ None,
+ None,
+ );
+ let response = runtime
+ .run_once(AgentChatRequest {
+ message: "routing details?".to_string(),
+ session_id: None,
+ mode: AgentMode::Fast,
+ tools: AgentToolOptions {
+ wiki: true,
+ web: true,
+ anytxt: false,
+ },
+ top_k: Some(3),
+ include_content: Some(false),
+ history: Vec::new(),
+ skills: Vec::new(),
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+
+ assert!(response.references.is_empty());
+ assert!(response
+ .tool_events
+ .iter()
+ .any(|event| event.tool == "web.search" && event.status == "available"));
+ assert!(response.message.contains("Router intent"));
+ }
+
+ #[tokio::test]
+ async fn optional_tool_failure_does_not_abort_turn() {
+ let project = temp_project("web-fail");
+ let runtime = AgentRuntime::new(
+ "project-1",
+ project.to_string_lossy(),
+ None,
+ None,
+ None,
+ None,
+ );
+ let response = runtime
+ .run_once(AgentChatRequest {
+ message: "latest external update".to_string(),
+ session_id: None,
+ mode: AgentMode::Standard,
+ tools: AgentToolOptions {
+ wiki: false,
+ web: true,
+ anytxt: false,
+ },
+ top_k: Some(3),
+ include_content: Some(false),
+ history: Vec::new(),
+ skills: Vec::new(),
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+
+ assert!(response.ok);
+ assert!(response
+ .tool_events
+ .iter()
+ .any(|event| event.tool == "web.search" && event.status == "failed"));
+ assert!(!response
+ .events
+ .iter()
+ .any(|event| matches!(event, AgentEvent::Error { .. })));
+ }
+
+ #[tokio::test]
+ async fn run_once_can_include_raw_source_search_for_source_questions() {
+ let project = temp_project("source");
+ let source_dir = project.join("raw").join("sources");
+ fs::create_dir_all(&source_dir).unwrap();
+ fs::write(source_dir.join("coal.txt"), "煤矿安全治理 source details.").unwrap();
+
+ let runtime = AgentRuntime::new(
+ "project-1",
+ project.to_string_lossy(),
+ None,
+ None,
+ None,
+ None,
+ );
+ let response = runtime
+ .run_once(AgentChatRequest {
+ message: "原始资料 煤矿安全".to_string(),
+ session_id: None,
+ mode: AgentMode::Deep,
+ tools: AgentToolOptions::default(),
+ top_k: Some(3),
+ include_content: Some(false),
+ history: Vec::new(),
+ skills: Vec::new(),
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+
+ assert!(response
+ .references
+ .iter()
+ .any(|reference| reference.kind == "source"));
+ assert!(response
+ .tool_events
+ .iter()
+ .any(|event| event.tool == "source.search"));
+ }
+
+ #[tokio::test]
+ async fn deep_mode_reads_top_wiki_pages_after_search() {
+ let project = temp_project("deep-read");
+ fs::write(
+ project.join("wiki").join("concepts").join("deep-agent.md"),
+ "---\ntitle: Deep Agent\n---\n# Deep Agent\n\nDetailed evidence that should be read in deep mode.",
+ )
+ .unwrap();
+
+ let runtime = AgentRuntime::new(
+ "project-1",
+ project.to_string_lossy(),
+ None,
+ None,
+ None,
+ None,
+ );
+ let response = runtime
+ .run_once(AgentChatRequest {
+ message: "deep agent evidence".to_string(),
+ session_id: None,
+ mode: AgentMode::Deep,
+ tools: AgentToolOptions::default(),
+ top_k: Some(3),
+ include_content: Some(false),
+ history: Vec::new(),
+ skills: Vec::new(),
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+
+ assert!(response
+ .tool_events
+ .iter()
+ .any(|event| event.tool == "wiki.read_page" && event.status == "completed"));
+ assert!(response.message.contains("Detailed evidence"));
+ }
+
+ #[tokio::test]
+ async fn turn_start_event_uses_api_mode_label() {
+ let project = temp_project("mode-label");
+ let runtime = AgentRuntime::new(
+ "project-1",
+ project.to_string_lossy(),
+ None,
+ None,
+ None,
+ None,
+ );
+ let response = runtime
+ .run_once(AgentChatRequest {
+ message: "hello".to_string(),
+ session_id: None,
+ mode: AgentMode::LocalFirst,
+ tools: AgentToolOptions {
+ wiki: false,
+ web: false,
+ anytxt: false,
+ },
+ top_k: None,
+ include_content: None,
+ history: Vec::new(),
+ skills: Vec::new(),
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+
+ assert!(response
+ .events
+ .iter()
+ .any(|event| matches!(event, AgentEvent::TurnStart { mode } if mode == "local_first")));
+ }
+
+ #[tokio::test]
+ async fn graph_questions_run_graph_search_tool() {
+ let project = temp_project("graph");
+ fs::write(
+ project.join("wiki").join("concepts").join("graph.md"),
+ "---\ntitle: Graph Relations\n---\n# Graph Relations\n\n[[A]] links to [[B]].",
+ )
+ .unwrap();
+
+ let runtime = AgentRuntime::new(
+ "project-1",
+ project.to_string_lossy(),
+ None,
+ None,
+ None,
+ None,
+ );
+ let response = runtime
+ .run_once(AgentChatRequest {
+ message: "知识图谱 Graph Relations".to_string(),
+ session_id: None,
+ mode: AgentMode::Standard,
+ tools: AgentToolOptions::default(),
+ top_k: Some(3),
+ include_content: None,
+ history: Vec::new(),
+ skills: Vec::new(),
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+
+ assert!(response
+ .tool_events
+ .iter()
+ .any(|event| event.tool == "graph.search" && event.status == "completed"));
+ assert!(response
+ .references
+ .iter()
+ .any(|reference| reference.kind == "graph"));
+ }
+
+ #[test]
+ fn parses_model_tool_plan_from_wrapped_json() {
+ let plan = parse_model_tool_plan(
+ "```json\n{\"toolCalls\":[{\"tool\":\"web.search\",\"query\":\"llm wiki release\"}]}\n```",
+ )
+ .unwrap();
+ let queries = planned_tool_queries(&plan, "fallback");
+ assert_eq!(
+ queries.get("web.search").map(String::as_str),
+ Some("llm wiki release")
+ );
+ }
+
+ #[test]
+ fn ignores_unknown_model_tool_names() {
+ let plan = parse_model_tool_plan(
+ "{\"toolCalls\":[{\"tool\":\"shell.exec\",\"query\":\"rm -rf\"},{\"tool\":\"wiki.search\"}]}",
+ )
+ .unwrap();
+ let queries = planned_tool_queries(&plan, "safe query");
+ assert_eq!(queries.len(), 1);
+ assert_eq!(
+ queries.get("wiki.search").map(String::as_str),
+ Some("safe query")
+ );
+ }
+
+ #[test]
+ fn write_requests_enable_model_tool_planning_without_external_tools() {
+ let tools = AgentToolOptions {
+ wiki: true,
+ web: false,
+ anytxt: false,
+ };
+ assert!(should_plan_tools_with_model(
+ "请创建一个 wiki 页面总结今天的发现",
+ AgentMode::Standard,
+ &tools
+ ));
+ assert!(!should_plan_tools_with_model(
+ "普通问答不需要额外规划",
+ AgentMode::Standard,
+ &tools
+ ));
+ assert!(!should_plan_tools_with_model(
+ "请创建一个 wiki 页面",
+ AgentMode::Fast,
+ &tools
+ ));
+ }
+
+ #[test]
+ fn validates_agent_image_limits() {
+ let valid = super::super::types::AgentImage {
+ media_type: "image/png".to_string(),
+ data_base64: "abcd".to_string(),
+ };
+ assert!(validate_images(std::slice::from_ref(&valid)).is_ok());
+
+ let invalid = super::super::types::AgentImage {
+ media_type: "image/bmp".to_string(),
+ data_base64: "abcd".to_string(),
+ };
+ assert!(validate_images(&[invalid]).is_err());
+
+ let too_many = vec![valid; MAX_IMAGES_PER_TURN + 1];
+ assert!(validate_images(&too_many).is_err());
+ }
+}
diff --git a/src-tauri/src/agent/session.rs b/src-tauri/src/agent/session.rs
new file mode 100644
index 00000000..b5dc63b8
--- /dev/null
+++ b/src-tauri/src/agent/session.rs
@@ -0,0 +1,337 @@
+use std::collections::BTreeMap;
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use serde::{Deserialize, Serialize};
+
+const MAX_SESSION_MESSAGES: usize = 40;
+// Bound only the in-memory cache. Session files stay on disk so API/MCP callers
+// can resume old conversations without the desktop UI keeping every session hot.
+const MAX_CACHED_SESSIONS: usize = 128;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionMessage {
+ pub role: String,
+ pub content: String,
+ pub timestamp: u64,
+}
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSession {
+ #[serde(default)]
+ pub session_id: String,
+ #[serde(default)]
+ pub project_id: String,
+ pub messages: Vec<AgentSessionMessage>,
+ pub updated_at: u64,
+}
+
+#[derive(Debug, Default)]
+pub struct AgentSessionStore {
+ inner: Mutex<BTreeMap<String, AgentSession>>,
+}
+
+impl AgentSessionStore {
+ pub fn append_turn(
+ &self,
+ project_path: &str,
+ project_id: &str,
+ session_id: &str,
+ user: &str,
+ assistant: &str,
+ ) {
+ let now = now_ms();
+ let Ok(mut guard) = self.inner.lock() else {
+ return;
+ };
+ let cache_key = session_cache_key(project_path, session_id);
+ let session = guard
+ .entry(cache_key)
+ .or_insert_with(|| load_session(project_path, session_id).unwrap_or_default());
+ session.session_id = session_id.to_string();
+ session.project_id = project_id.to_string();
+ session.messages.push(AgentSessionMessage {
+ role: "user".to_string(),
+ content: user.to_string(),
+ timestamp: now,
+ });
+ session.messages.push(AgentSessionMessage {
+ role: "assistant".to_string(),
+ content: assistant.to_string(),
+ timestamp: now,
+ });
+ if session.messages.len() > MAX_SESSION_MESSAGES {
+ let drop_count = session.messages.len() - MAX_SESSION_MESSAGES;
+ session.messages.drain(0..drop_count);
+ }
+ session.updated_at = now;
+ let _ = save_session(project_path, session);
+ trim_session_cache(&mut guard);
+ }
+
+ pub fn recent_messages(
+ &self,
+ project_path: &str,
+ session_id: &str,
+ limit: usize,
+ ) -> Vec<AgentSessionMessage> {
+ let session = self
+ .inner
+ .lock()
+ .ok()
+ .and_then(|mut guard| {
+ let cache_key = session_cache_key(project_path, session_id);
+ if !guard.contains_key(&cache_key) {
+ if let Some(loaded) = load_session(project_path, session_id) {
+ guard.insert(cache_key.clone(), loaded);
+ trim_session_cache(&mut guard);
+ }
+ }
+ guard.get(&cache_key).cloned()
+ })
+ .or_else(|| load_session(project_path, session_id));
+ let Some(session) = session else {
+ return Vec::new();
+ };
+ let start = session.messages.len().saturating_sub(limit);
+ session.messages[start..].to_vec()
+ }
+
+ pub fn list_sessions(&self, project_path: &str) -> Vec<AgentSession> {
+ let dir = Path::new(project_path)
+ .join(".llm-wiki")
+ .join("agent-sessions");
+ let Ok(entries) = fs::read_dir(dir) else {
+ return Vec::new();
+ };
+ let mut sessions = entries
+ .filter_map(Result::ok)
+ .filter_map(|entry| {
+ if entry.path().extension().and_then(|s| s.to_str()) != Some("json") {
+ return None;
+ }
+ let raw = fs::read_to_string(entry.path()).ok()?;
+ serde_json::from_str::<AgentSession>(&raw).ok()
+ })
+ .collect::<Vec<_>>();
+ sessions.sort_by(|a, b| {
+ b.updated_at
+ .cmp(&a.updated_at)
+ .then_with(|| b.session_id.cmp(&a.session_id))
+ });
+ sessions
+ }
+}
+
+fn session_cache_key(project_path: &str, session_id: &str) -> String {
+ format!("{}::{session_id}", normalize_project_path(project_path))
+}
+
+fn normalize_project_path(path: &str) -> String {
+ path.replace('\\', "/").trim_end_matches('/').to_string()
+}
+
+fn trim_session_cache(cache: &mut BTreeMap<String, AgentSession>) {
+ if cache.len() <= MAX_CACHED_SESSIONS {
+ return;
+ }
+ let mut entries = cache
+ .iter()
+ .map(|(key, session)| (key.clone(), session.updated_at))
+ .collect::<Vec<_>>();
+ entries.sort_by(|a, b| a.1.cmp(&b.1).then_with(|| a.0.cmp(&b.0)));
+ let remove_count = cache.len().saturating_sub(MAX_CACHED_SESSIONS);
+ for (key, _) in entries.into_iter().take(remove_count) {
+ cache.remove(&key);
+ }
+}
+
+fn now_ms() -> u64 {
+ SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .map(|duration| duration.as_millis() as u64)
+ .unwrap_or(0)
+}
+
+fn load_session(project_path: &str, session_id: &str) -> Option<AgentSession> {
+ let path = session_file(project_path, session_id)?;
+ let raw = fs::read_to_string(path).ok()?;
+ serde_json::from_str(&raw).ok()
+}
+
+fn save_session(project_path: &str, session: &AgentSession) -> Result<(), String> {
+ let path = session_file(project_path, &session.session_id)
+ .ok_or_else(|| "Invalid Agent session id".to_string())?;
+ if let Some(parent) = path.parent() {
+ fs::create_dir_all(parent).map_err(|err| format!("Failed to create session dir: {err}"))?;
+ }
+ let raw = serde_json::to_string_pretty(session)
+ .map_err(|err| format!("Failed to serialize session: {err}"))?;
+ fs::write(path, raw).map_err(|err| format!("Failed to write session: {err}"))
+}
+
+fn session_file(project_path: &str, session_id: &str) -> Option<PathBuf> {
+ let id = sanitize_session_id(session_id)?;
+ Some(
+ Path::new(project_path)
+ .join(".llm-wiki")
+ .join("agent-sessions")
+ .join(format!("{id}.json")),
+ )
+}
+
+fn sanitize_session_id(session_id: &str) -> Option<String> {
+ let trimmed = session_id.trim();
+ if trimmed.is_empty()
+ || trimmed.contains('/')
+ || trimmed.contains('\\')
+ || trimmed.contains("..")
+ || trimmed.len() > 128
+ {
+ return None;
+ }
+ Some(
+ trimmed
+ .chars()
+ .map(|ch| {
+ if ch.is_ascii_alphanumeric() || matches!(ch, '-' | '_' | '.') {
+ ch
+ } else {
+ '_'
+ }
+ })
+ .collect(),
+ )
+}
+
+#[cfg(test)]
+mod tests {
+ use uuid::Uuid;
+
+ use super::*;
+
+ fn temp_project(name: &str) -> PathBuf {
+ let root =
+ std::env::temp_dir().join(format!("llm-wiki-agent-session-{name}-{}", Uuid::new_v4()));
+ fs::create_dir_all(&root).unwrap();
+ root
+ }
+
+ #[test]
+ fn append_turn_tracks_recent_messages() {
+ let project = temp_project("recent");
+ let store = AgentSessionStore::default();
+ store.append_turn(project.to_str().unwrap(), "p1", "s1", "hello", "hi");
+ store.append_turn(project.to_str().unwrap(), "p1", "s1", "question", "answer");
+
+ let messages = store.recent_messages(project.to_str().unwrap(), "s1", 3);
+ assert_eq!(messages.len(), 3);
+ assert_eq!(messages[0].content, "hi");
+ assert_eq!(messages[1].role, "user");
+ assert_eq!(messages[2].content, "answer");
+ let _ = fs::remove_dir_all(project);
+ }
+
+ #[test]
+ fn recent_messages_returns_empty_for_missing_session() {
+ let project = temp_project("missing");
+ let store = AgentSessionStore::default();
+ assert!(store
+ .recent_messages(project.to_str().unwrap(), "missing", 10)
+ .is_empty());
+ let _ = fs::remove_dir_all(project);
+ }
+
+ #[test]
+ fn append_turn_persists_session_to_project_state_dir() {
+ let project = temp_project("persist");
+ let store = AgentSessionStore::default();
+ store.append_turn(project.to_str().unwrap(), "p1", "s.persist", "hello", "hi");
+
+ let fresh = AgentSessionStore::default();
+ let messages = fresh.recent_messages(project.to_str().unwrap(), "s.persist", 10);
+ assert_eq!(messages.len(), 2);
+ assert_eq!(messages[0].content, "hello");
+ assert!(project
+ .join(".llm-wiki")
+ .join("agent-sessions")
+ .join("s.persist.json")
+ .exists());
+ let _ = fs::remove_dir_all(project);
+ }
+
+ #[test]
+ fn session_cache_is_bounded() {
+ let project = temp_project("bounded");
+ let store = AgentSessionStore::default();
+ for idx in 0..(MAX_CACHED_SESSIONS + 5) {
+ store.append_turn(
+ project.to_str().unwrap(),
+ "p1",
+ &format!("s{idx:03}"),
+ "hello",
+ "hi",
+ );
+ }
+ let guard = store.inner.lock().unwrap();
+ assert!(guard.len() <= MAX_CACHED_SESSIONS);
+ let _ = fs::remove_dir_all(project);
+ }
+
+ #[test]
+ fn same_session_id_is_isolated_by_project() {
+ let project_a = temp_project("isolate-a");
+ let project_b = temp_project("isolate-b");
+ let store = AgentSessionStore::default();
+ store.append_turn(
+ project_a.to_str().unwrap(),
+ "p1",
+ "same",
+ "hello a",
+ "answer a",
+ );
+ store.append_turn(
+ project_b.to_str().unwrap(),
+ "p2",
+ "same",
+ "hello b",
+ "answer b",
+ );
+
+ let a_messages = store.recent_messages(project_a.to_str().unwrap(), "same", 10);
+ let b_messages = store.recent_messages(project_b.to_str().unwrap(), "same", 10);
+
+ assert_eq!(a_messages.len(), 2);
+ assert_eq!(a_messages[0].content, "hello a");
+ assert_eq!(a_messages[1].content, "answer a");
+ assert_eq!(b_messages.len(), 2);
+ assert_eq!(b_messages[0].content, "hello b");
+ assert_eq!(b_messages[1].content, "answer b");
+ let _ = fs::remove_dir_all(project_a);
+ let _ = fs::remove_dir_all(project_b);
+ }
+
+ #[test]
+ fn session_ids_reject_path_traversal() {
+ assert!(session_file("/tmp/project", "../secret").is_none());
+ assert!(session_file("/tmp/project", "safe-id").is_some());
+ }
+
+ #[test]
+ fn list_sessions_returns_persisted_sessions_newest_first() {
+ let project = temp_project("list");
+ let store = AgentSessionStore::default();
+ store.append_turn(project.to_str().unwrap(), "p1", "s1", "one", "a");
+ store.append_turn(project.to_str().unwrap(), "p1", "s2", "two", "b");
+
+ let sessions = store.list_sessions(project.to_str().unwrap());
+ assert_eq!(sessions.len(), 2);
+ assert_eq!(sessions[0].session_id, "s2");
+ assert_eq!(sessions[1].session_id, "s1");
+ let _ = fs::remove_dir_all(project);
+ }
+}
diff --git a/src-tauri/src/agent/skills.rs b/src-tauri/src/agent/skills.rs
new file mode 100644
index 00000000..6fadc512
--- /dev/null
+++ b/src-tauri/src/agent/skills.rs
@@ -0,0 +1,143 @@
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+const MAX_SKILL_BYTES: usize = 24_000;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSkill {
+ pub name: String,
+ pub description: String,
+ pub instructions: String,
+}
+
+pub fn load_project_skills(project_path: &str, requested: &[String]) -> Vec<AgentSkill> {
+ if requested.is_empty() {
+ return Vec::new();
+ }
+ let root = Path::new(project_path).join(".llm-wiki").join("skills");
+ requested
+ .iter()
+ .filter_map(|name| load_one_skill(&root, name))
+ .collect()
+}
+
+fn load_one_skill(root: &Path, name: &str) -> Option<AgentSkill> {
+ let name = normalize_skill_name(name)?;
+ let candidates = [
+ root.join(format!("{name}.md")),
+ root.join(&name).join("SKILL.md"),
+ ];
+ candidates
+ .iter()
+ .find_map(|path| load_skill_file(path, &name).ok())
+}
+
+fn load_skill_file(path: &PathBuf, fallback_name: &str) -> Result<AgentSkill, String> {
+ let meta = fs::metadata(path).map_err(|err| format!("Skill not found: {err}"))?;
+ if !meta.is_file() || meta.len() as usize > MAX_SKILL_BYTES {
+ return Err("Skill file is not readable or is too large".to_string());
+ }
+ let raw = fs::read_to_string(path).map_err(|err| format!("Failed to read skill: {err}"))?;
+ let (frontmatter, instructions) = split_frontmatter(&raw);
+ let name = frontmatter
+ .as_deref()
+ .and_then(|fm| yaml_string_field(fm, "name"))
+ .unwrap_or_else(|| fallback_name.to_string());
+ let description = frontmatter
+ .as_deref()
+ .and_then(|fm| yaml_string_field(fm, "description"))
+ .unwrap_or_default();
+ Some(AgentSkill {
+ name,
+ description,
+ instructions: instructions.trim().to_string(),
+ })
+ .filter(|skill| !skill.instructions.is_empty())
+ .ok_or_else(|| "Skill instructions are empty".to_string())
+}
+
+fn normalize_skill_name(value: &str) -> Option<String> {
+ let trimmed = value.trim();
+ if trimmed.is_empty()
+ || trimmed.contains('/')
+ || trimmed.contains('\\')
+ || trimmed.contains("..")
+ {
+ return None;
+ }
+ Some(trimmed.to_string())
+}
+
+fn split_frontmatter(raw: &str) -> (Option<String>, String) {
+ let normalized = raw.strip_prefix('\u{feff}').unwrap_or(raw);
+ if !normalized.starts_with("---\n") {
+ return (None, normalized.to_string());
+ }
+ let rest = &normalized[4..];
+ if let Some(end) = rest.find("\n---") {
+ let fm = rest[..end].to_string();
+ let after = rest[end + "\n---".len()..]
+ .strip_prefix('\n')
+ .unwrap_or(&rest[end + "\n---".len()..])
+ .to_string();
+ (Some(fm), after)
+ } else {
+ (None, normalized.to_string())
+ }
+}
+
+fn yaml_string_field(frontmatter: &str, key: &str) -> Option<String> {
+ let prefix = format!("{key}:");
+ for line in frontmatter.lines() {
+ let trimmed = line.trim();
+ if !trimmed.starts_with(&prefix) {
+ continue;
+ }
+ let value = trimmed[prefix.len()..].trim();
+ let value = value
+ .strip_prefix('"')
+ .and_then(|v| v.strip_suffix('"'))
+ .or_else(|| value.strip_prefix('\'').and_then(|v| v.strip_suffix('\'')))
+ .unwrap_or(value);
+ if !value.is_empty() {
+ return Some(value.to_string());
+ }
+ }
+ None
+}
+
+#[cfg(test)]
+mod tests {
+ use std::fs;
+ use uuid::Uuid;
+
+ use super::*;
+
+ #[test]
+ fn load_project_skills_reads_frontmatter_skill() {
+ let root = std::env::temp_dir().join(format!("llm-wiki-skills-{}", Uuid::new_v4()));
+ let skills_dir = root.join(".llm-wiki").join("skills");
+ fs::create_dir_all(&skills_dir).unwrap();
+ fs::write(
+ skills_dir.join("reviewer.md"),
+ "---\nname: reviewer\ndescription: Review source quality\n---\nCheck claims carefully.",
+ )
+ .unwrap();
+
+ let skills = load_project_skills(root.to_str().unwrap(), &["reviewer".to_string()]);
+ assert_eq!(skills.len(), 1);
+ assert_eq!(skills[0].name, "reviewer");
+ assert_eq!(skills[0].description, "Review source quality");
+ assert_eq!(skills[0].instructions, "Check claims carefully.");
+ let _ = fs::remove_dir_all(root);
+ }
+
+ #[test]
+ fn load_project_skills_rejects_path_traversal_names() {
+ let skills = load_project_skills("/tmp/missing", &["../secret".to_string()]);
+ assert!(skills.is_empty());
+ }
+}
diff --git a/src-tauri/src/agent/tools.rs b/src-tauri/src/agent/tools.rs
new file mode 100644
index 00000000..2945f9a8
--- /dev/null
+++ b/src-tauri/src/agent/tools.rs
@@ -0,0 +1,1659 @@
+use std::collections::BTreeMap;
+use std::fs;
+use std::future::Future;
+use std::path::{Component, Path, PathBuf};
+use std::pin::Pin;
+
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use walkdir::WalkDir;
+
+use crate::commands::search::{self, SearchEmbeddingConfig};
+
+use super::types::AgentReference;
+
+// Tool I/O limits are backend security boundaries. Do not relax them only in
+// the UI: API and MCP callers can invoke the same tools without going through
+// React components.
+const MAX_READ_PAGE_BYTES: usize = 2 * 1024 * 1024;
+const MAX_WRITE_PAGE_BYTES: usize = 2 * 1024 * 1024;
+const MAX_SOURCE_SEARCH_FILES: usize = 10_000;
+const MAX_SOURCE_SNIPPET_CHARS: usize = 500;
+const MAX_GRAPH_SEARCH_FILES: usize = 10_000;
+const WEB_SEARCH_TIMEOUT_SECS: u64 = 30;
+const DEFAULT_ANYTXT_ENDPOINT: &str = "http://127.0.0.1:9920";
+const DEFAULT_ANYTXT_LIMIT: usize = 20;
+const ANYTXT_LAST_MODIFY_END: i64 = 2_147_483_647;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum ToolEffect {
+ Read,
+ Write,
+ Network,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct ToolSpec {
+ pub name: String,
+ pub description: String,
+ pub effects: Vec<ToolEffect>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub parameters: Option<serde_json::Value>,
+}
+
+#[allow(dead_code)]
+pub trait AgentTool: Send + Sync {
+ fn spec(&self) -> ToolSpec;
+ fn execute<'a>(
+ &'a self,
+ input: Value,
+ ) -> Pin<Box<dyn Future<Output = Result<Value, String>> + Send + 'a>>;
+}
+
+pub trait ToolRegistry {
+ fn specs(&self) -> Vec<ToolSpec>;
+ fn execute<'a>(
+ &'a self,
+ name: &'a str,
+ input: Value,
+ context: ToolContext<'a>,
+ ) -> Pin<Box<dyn Future<Output = Result<Value, String>> + Send + 'a>>;
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct BuiltinToolRegistry;
+
+#[derive(Clone)]
+pub struct ToolContext<'a> {
+ pub project_path: &'a str,
+ pub embedding_config: Option<SearchEmbeddingConfig>,
+ pub web_search_config: Option<WebSearchConfig>,
+ pub anytxt_config: Option<AnyTxtConfig>,
+}
+
+impl ToolRegistry for BuiltinToolRegistry {
+ fn specs(&self) -> Vec<ToolSpec> {
+ builtin_tool_specs()
+ }
+
+ fn execute<'a>(
+ &'a self,
+ name: &'a str,
+ input: Value,
+ context: ToolContext<'a>,
+ ) -> Pin<Box<dyn Future<Output = Result<Value, String>> + Send + 'a>> {
+ Box::pin(async move {
+ match name {
+ "wiki.write_page" => {
+ let path = input
+ .get("path")
+ .and_then(Value::as_str)
+ .ok_or_else(|| "wiki.write_page requires path".to_string())?;
+ let content = input
+ .get("content")
+ .and_then(Value::as_str)
+ .ok_or_else(|| "wiki.write_page requires content".to_string())?;
+ let allow_overwrite = input
+ .get("allowOverwrite")
+ .or_else(|| input.get("allow_overwrite"))
+ .and_then(Value::as_bool)
+ .unwrap_or(false);
+ serde_json::to_value(write_wiki_page_with_options(
+ context.project_path,
+ path,
+ content,
+ allow_overwrite,
+ )?)
+ .map_err(|err| format!("Failed to serialize wiki.write_page result: {err}"))
+ }
+ "wiki.search" => {
+ let query = tool_query(&input, "wiki.search")?;
+ let top_k = tool_top_k(&input);
+ let include_content = input
+ .get("includeContent")
+ .and_then(Value::as_bool)
+ .unwrap_or(false);
+ serde_json::to_value(
+ run_wiki_search(
+ context.project_path.to_string(),
+ query,
+ top_k,
+ include_content,
+ context.embedding_config,
+ )
+ .await?,
+ )
+ .map_err(|err| format!("Failed to serialize wiki.search result: {err}"))
+ }
+ "wiki.read_page" => {
+ let path = input
+ .get("path")
+ .and_then(Value::as_str)
+ .map(str::trim)
+ .filter(|path| !path.is_empty())
+ .ok_or_else(|| "wiki.read_page requires path".to_string())?;
+ serde_json::to_value(json!({
+ "path": path,
+ "content": read_wiki_page(context.project_path, path)?,
+ }))
+ .map_err(|err| format!("Failed to serialize wiki.read_page result: {err}"))
+ }
+ "source.search" => {
+ let query = tool_query(&input, "source.search")?.to_string();
+ let project_path = context.project_path.to_string();
+ let top_k = tool_top_k(&input);
+ // `search_sources` walks the filesystem synchronously.
+ // Keep it off Tokio worker threads so a large source tree
+ // cannot stall unrelated Agent/API work.
+ let references = tokio::task::spawn_blocking(move || {
+ search_sources(&project_path, &query, top_k)
+ })
+ .await
+ .map_err(|err| format!("source.search worker failed: {err}"))??;
+ serde_json::to_value(references)
+ .map_err(|err| format!("Failed to serialize source.search result: {err}"))
+ }
+ "graph.search" => {
+ let query = tool_query(&input, "graph.search")?.to_string();
+ let project_path = context.project_path.to_string();
+ let top_k = tool_top_k(&input);
+ // Graph search also performs synchronous markdown walks.
+ // Run it in the blocking pool for the same reason as
+ // `source.search`.
+ let references = tokio::task::spawn_blocking(move || {
+ search_graph(&project_path, &query, top_k)
+ })
+ .await
+ .map_err(|err| format!("graph.search worker failed: {err}"))??;
+ serde_json::to_value(references)
+ .map_err(|err| format!("Failed to serialize graph.search result: {err}"))
+ }
+ "web.search" => {
+ let query = tool_query(&input, "web.search")?;
+ serde_json::to_value(
+ run_web_search(query, context.web_search_config, tool_top_k(&input))
+ .await?,
+ )
+ .map_err(|err| format!("Failed to serialize web.search result: {err}"))
+ }
+ "anytxt.search" => {
+ let query = tool_query(&input, "anytxt.search")?;
+ serde_json::to_value(
+ run_anytxt_search(query, context.anytxt_config, tool_top_k(&input)).await?,
+ )
+ .map_err(|err| format!("Failed to serialize anytxt.search result: {err}"))
+ }
+ "deep_research.run" => {
+ let query = tool_query(&input, "deep_research.run")?;
+ serde_json::to_value(json!({
+ "query": query,
+ "status": "orchestrated_by_agent_runtime",
+ }))
+ .map_err(|err| format!("Failed to serialize deep_research.run result: {err}"))
+ }
+ other => Err(format!("Unknown Agent tool: {other}")),
+ }
+ })
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct WikiSearchToolOutput {
+ pub mode: String,
+ pub token_hits: usize,
+ pub vector_hits: usize,
+ pub references: Vec<AgentReference>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+#[serde(rename_all = "camelCase")]
+pub struct WebSearchConfig {
+ pub provider: String,
+ #[serde(default)]
+ pub api_key: String,
+ #[serde(default)]
+ pub sear_xng_url: Option<String>,
+ #[serde(default)]
+ pub sear_xng_categories: Option<Vec<String>>,
+ #[serde(default)]
+ pub serp_api_engine: Option<String>,
+ #[serde(default)]
+ pub provider_configs: Option<BTreeMap<String, WebSearchProviderOverride>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+#[serde(rename_all = "camelCase")]
+pub struct WebSearchProviderOverride {
+ #[serde(default)]
+ pub api_key: Option<String>,
+ #[serde(default)]
+ pub sear_xng_url: Option<String>,
+ #[serde(default)]
+ pub sear_xng_categories: Option<Vec<String>>,
+ #[serde(default)]
+ pub serp_api_engine: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+#[serde(rename_all = "camelCase")]
+pub struct AnyTxtConfig {
+ #[serde(default)]
+ pub enabled: Option<bool>,
+ #[serde(default)]
+ pub endpoint: Option<String>,
+ #[serde(default)]
+ pub filter_dir: Option<String>,
+ #[serde(default)]
+ pub filter_ext: Option<String>,
+ #[serde(default)]
+ pub limit: Option<usize>,
+}
+
+impl WebSearchConfig {
+ fn resolved(&self) -> Self {
+ let provider = self.provider.trim().to_ascii_lowercase();
+ let Some(override_cfg) = self
+ .provider_configs
+ .as_ref()
+ .and_then(|configs| configs.get(&provider))
+ else {
+ return self.clone();
+ };
+ Self {
+ provider: self.provider.clone(),
+ api_key: override_cfg
+ .api_key
+ .clone()
+ .unwrap_or_else(|| self.api_key.clone()),
+ sear_xng_url: override_cfg
+ .sear_xng_url
+ .clone()
+ .or_else(|| self.sear_xng_url.clone()),
+ sear_xng_categories: override_cfg
+ .sear_xng_categories
+ .clone()
+ .or_else(|| self.sear_xng_categories.clone()),
+ serp_api_engine: override_cfg
+ .serp_api_engine
+ .clone()
+ .or_else(|| self.serp_api_engine.clone()),
+ provider_configs: self.provider_configs.clone(),
+ }
+ }
+}
+
+pub fn builtin_tool_specs() -> Vec<ToolSpec> {
+ vec![
+ ToolSpec {
+ name: "wiki.search".to_string(),
+ description: "Search generated LLM Wiki pages using backend keyword/vector retrieval."
+ .to_string(),
+ effects: vec![ToolEffect::Read],
+ parameters: Some(serde_json::json!({
+ "type": "object",
+ "properties": {
+ "query": { "type": "string" },
+ "topK": { "type": "integer", "minimum": 1, "maximum": 10 }
+ },
+ "required": ["query"]
+ })),
+ },
+ ToolSpec {
+ name: "wiki.read_page".to_string(),
+ description: "Read a project wiki markdown page by project-relative path.".to_string(),
+ effects: vec![ToolEffect::Read],
+ parameters: Some(serde_json::json!({
+ "type": "object",
+ "properties": { "path": { "type": "string" } },
+ "required": ["path"]
+ })),
+ },
+ ToolSpec {
+ name: "source.search".to_string(),
+ description:
+ "Search raw source files stored under raw/sources for exact keyword snippets."
+ .to_string(),
+ effects: vec![ToolEffect::Read],
+ parameters: Some(serde_json::json!({
+ "type": "object",
+ "properties": {
+ "query": { "type": "string" },
+ "topK": { "type": "integer", "minimum": 1, "maximum": 10 }
+ },
+ "required": ["query"]
+ })),
+ },
+ ToolSpec {
+ name: "web.search".to_string(),
+ description: "Search external web sources when the user enables web search."
+ .to_string(),
+ effects: vec![ToolEffect::Network],
+ parameters: Some(serde_json::json!({
+ "type": "object",
+ "properties": {
+ "query": { "type": "string" },
+ "topK": { "type": "integer", "minimum": 1, "maximum": 10 }
+ },
+ "required": ["query"]
+ })),
+ },
+ ToolSpec {
+ name: "graph.search".to_string(),
+ description: "Search wiki graph nodes and relationship-heavy pages.".to_string(),
+ effects: vec![ToolEffect::Read],
+ parameters: Some(serde_json::json!({
+ "type": "object",
+ "properties": {
+ "query": { "type": "string" },
+ "topK": { "type": "integer", "minimum": 1, "maximum": 10 }
+ },
+ "required": ["query"]
+ })),
+ },
+ ToolSpec {
+ name: "anytxt.search".to_string(),
+ description: "Search files indexed by an AnyTXT JSON-RPC service.".to_string(),
+ effects: vec![ToolEffect::Network, ToolEffect::Read],
+ parameters: Some(serde_json::json!({
+ "type": "object",
+ "properties": {
+ "query": { "type": "string" },
+ "topK": { "type": "integer", "minimum": 1, "maximum": 10 }
+ },
+ "required": ["query"]
+ })),
+ },
+ ToolSpec {
+ name: "deep_research.run".to_string(),
+ description:
+ "Collect broader external/local evidence for deep research turns before synthesis."
+ .to_string(),
+ effects: vec![ToolEffect::Network, ToolEffect::Read],
+ parameters: Some(serde_json::json!({
+ "type": "object",
+ "properties": {
+ "query": { "type": "string" },
+ "sources": {
+ "type": "array",
+ "items": { "enum": ["web", "anytxt", "wiki", "source"] }
+ }
+ },
+ "required": ["query"]
+ })),
+ },
+ ToolSpec {
+ name: "wiki.write_page".to_string(),
+ description:
+ "Create a Markdown wiki page under wiki/ with project-bound path checks. Existing files require allowOverwrite=true."
+ .to_string(),
+ effects: vec![ToolEffect::Write],
+ parameters: Some(serde_json::json!({
+ "type": "object",
+ "properties": {
+ "path": {
+ "type": "string",
+ "description": "Project-relative path such as wiki/queries/new-page.md"
+ },
+ "content": { "type": "string" },
+ "allowOverwrite": {
+ "type": "boolean",
+ "description": "Defaults to false. Set true only when the user explicitly asks to overwrite an existing wiki page."
+ }
+ },
+ "required": ["path", "content"]
+ })),
+ },
+ ToolSpec {
+ name: "llm.generate".to_string(),
+ description: "Generate a final assistant answer from retrieved context.".to_string(),
+ effects: vec![ToolEffect::Network],
+ parameters: None,
+ },
+ ToolSpec {
+ name: "skills.load".to_string(),
+ description: "Load instruction-only project skills from .llm-wiki/skills.".to_string(),
+ effects: vec![ToolEffect::Read],
+ parameters: None,
+ },
+ ]
+}
+
+fn tool_query<'a>(input: &'a Value, tool: &str) -> Result<&'a str, String> {
+ input
+ .get("query")
+ .and_then(Value::as_str)
+ .map(str::trim)
+ .filter(|query| !query.is_empty())
+ .ok_or_else(|| format!("{tool} requires query"))
+}
+
+fn tool_top_k(input: &Value) -> usize {
+ input
+ .get("topK")
+ .or_else(|| input.get("top_k"))
+ .and_then(Value::as_u64)
+ .map(|value| value as usize)
+ .unwrap_or(5)
+ .clamp(1, 10)
+}
+
+pub fn write_wiki_page(
+ project_path: &str,
+ rel_path: &str,
+ content: &str,
+) -> Result<AgentReference, String> {
+ write_wiki_page_with_options(project_path, rel_path, content, false)
+}
+
+pub fn write_wiki_page_with_options(
+ project_path: &str,
+ rel_path: &str,
+ content: &str,
+ allow_overwrite: bool,
+) -> Result<AgentReference, String> {
+ if content.len() > MAX_WRITE_PAGE_BYTES {
+ return Err("wiki.write_page content is too large".to_string());
+ }
+ let rel = normalize_wiki_write_path(rel_path)?;
+ let path = safe_project_join(project_path, &rel)?;
+ if let Some(parent) = path.parent() {
+ // Check the deepest existing ancestor before creating directories. If a
+ // project already contains a symlink under `wiki/`, this prevents even
+ // empty intermediate directories from being created outside the project.
+ ensure_existing_ancestor_bound(project_path, parent)?;
+ fs::create_dir_all(parent)
+ .map_err(|err| format!("Failed to create wiki page directory: {err}"))?;
+ ensure_project_bound_path(project_path, parent)?;
+ }
+ // Create-only by default. Prompt injection in retrieved context must not be
+ // able to silently truncate an existing wiki page.
+ if path.exists() && !allow_overwrite {
+ return Err(
+ "wiki.write_page refuses to overwrite an existing page without allowOverwrite=true"
+ .to_string(),
+ );
+ }
+ fs::write(&path, content).map_err(|err| format!("Failed to write wiki page: {err}"))?;
+ Ok(AgentReference {
+ title: extract_markdown_title(content).unwrap_or_else(|| {
+ Path::new(&rel)
+ .file_stem()
+ .and_then(|s| s.to_str())
+ .unwrap_or("Wiki page")
+ .replace('-', " ")
+ }),
+ path: rel,
+ kind: "wiki".to_string(),
+ snippet: Some(trim_text(&collapse_markdown_preview(content), 500))
+ .filter(|value| !value.trim().is_empty()),
+ score: None,
+ })
+}
+
+pub async fn run_wiki_search(
+ project_path: String,
+ query: &str,
+ top_k: usize,
+ include_content: bool,
+ embedding_config: Option<SearchEmbeddingConfig>,
+) -> Result<WikiSearchToolOutput, String> {
+ let query_embedding = search::resolve_query_embedding(query, None, embedding_config).await?;
+ let search = search::search_project_inner(
+ project_path,
+ query.to_string(),
+ top_k,
+ include_content,
+ query_embedding,
+ )
+ .await?;
+ let references = search
+ .results
+ .iter()
+ .map(|result| AgentReference {
+ title: result.title.clone(),
+ path: result.path.clone(),
+ kind: "wiki".to_string(),
+ snippet: Some(result.snippet.clone()).filter(|s| !s.trim().is_empty()),
+ score: Some(result.score),
+ })
+ .collect();
+ Ok(WikiSearchToolOutput {
+ mode: search.mode,
+ token_hits: search.token_hits,
+ vector_hits: search.vector_hits,
+ references,
+ })
+}
+
+pub async fn run_web_search(
+ query: &str,
+ config: Option<WebSearchConfig>,
+ top_k: usize,
+) -> Result<Vec<AgentReference>, String> {
+ let query = query.trim();
+ if query.is_empty() {
+ return Ok(Vec::new());
+ }
+ let Some(config) = config else {
+ return Err(
+ "Web search is enabled for this turn but no search provider is configured.".to_string(),
+ );
+ };
+ let config = config.resolved();
+ let provider = config.provider.trim().to_ascii_lowercase();
+ if provider.is_empty() || provider == "none" {
+ return Err("Web search provider is not configured.".to_string());
+ }
+ let max_results = top_k.clamp(1, 10);
+ let client = reqwest::Client::builder()
+ .timeout(std::time::Duration::from_secs(WEB_SEARCH_TIMEOUT_SECS))
+ .build()
+ .map_err(|err| format!("Failed to build web search client: {err}"))?;
+ let raw = match provider.as_str() {
+ "firecrawl" => firecrawl_search(&client, query, max_results).await?,
+ "searxng" => searxng_search(&client, query, &config, max_results).await?,
+ "tavily" => tavily_search(&client, query, &config, max_results).await?,
+ "brave" => brave_search(&client, query, &config, max_results).await?,
+ "serpapi" => serpapi_search(&client, query, &config, max_results).await?,
+ other => {
+ return Err(format!(
+ "Web search provider '{other}' is not supported by the Rust Agent yet"
+ ))
+ }
+ };
+ Ok(raw
+ .into_iter()
+ .take(max_results)
+ .map(|item| AgentReference {
+ title: item.title,
+ path: item.url,
+ kind: "web".to_string(),
+ snippet: Some(item.snippet).filter(|s| !s.trim().is_empty()),
+ score: None,
+ })
+ .collect())
+}
+
+pub async fn run_anytxt_search(
+ query: &str,
+ config: Option<AnyTxtConfig>,
+ top_k: usize,
+) -> Result<Vec<AgentReference>, String> {
+ let query = query.trim();
+ if query.is_empty() {
+ return Ok(Vec::new());
+ }
+ let config = config.unwrap_or_default();
+ if config.enabled == Some(false) {
+ return Ok(Vec::new());
+ }
+ let endpoint = config
+ .endpoint
+ .as_deref()
+ .filter(|value| !value.trim().is_empty())
+ .unwrap_or(DEFAULT_ANYTXT_ENDPOINT)
+ .trim()
+ .trim_end_matches('/')
+ .to_string();
+ let limit = top_k
+ .clamp(1, 10)
+ .min(config.limit.unwrap_or(DEFAULT_ANYTXT_LIMIT).clamp(1, 100));
+ let pattern = anytxt_pattern_from_query(query);
+ let filter_dir = config.filter_dir.unwrap_or_default();
+ let filter_ext = config
+ .filter_ext
+ .filter(|value| !value.trim().is_empty())
+ .unwrap_or_else(|| "*".to_string());
+ let client = reqwest::Client::builder()
+ .timeout(std::time::Duration::from_secs(WEB_SEARCH_TIMEOUT_SECS))
+ .build()
+ .map_err(|err| format!("Failed to build AnyTXT client: {err}"))?;
+ let response = client
+ .post(&endpoint)
+ .header("Accept", "application/json")
+ .json(&json!({
+ "id": 1,
+ "jsonrpc": "2.0",
+ "method": "ATRpcServer.Searcher.V1.GetResult",
+ "params": {
+ "input": {
+ "pattern": pattern,
+ "filterDir": filter_dir,
+ "filterExt": filter_ext,
+ "lastModifyBegin": 0,
+ "lastModifyEnd": ANYTXT_LAST_MODIFY_END,
+ "limit": limit.to_string(),
+ "offset": 0,
+ "order": 0
+ }
+ }
+ }))
+ .send()
+ .await
+ .map_err(|err| {
+ format!("AnyTXT search failed. Check that ATGUI.exe or the AnyTXT service is running at {endpoint}: {err}")
+ })?;
+ let status = response.status();
+ let text = response
+ .text()
+ .await
+ .map_err(|err| format!("Failed to read AnyTXT response: {err}"))?;
+ if !status.is_success() {
+ return Err(format!("AnyTXT HTTP {status}: {}", trim_text(&text, 300)));
+ }
+ let value: Value = serde_json::from_str(&text)
+ .map_err(|_| format!("AnyTXT returned invalid JSON: {}", trim_text(&text, 300)))?;
+ if let Some(error) = value.get("error") {
+ return Err(format!(
+ "AnyTXT error: {}",
+ trim_text(&error.to_string(), 300)
+ ));
+ }
+ Ok(extract_anytxt_items(&value)
+ .into_iter()
+ .take(limit)
+ .map(|item| AgentReference {
+ title: item.title,
+ path: item.path,
+ kind: "anytxt".to_string(),
+ snippet: Some(item.snippet).filter(|s| !s.trim().is_empty()),
+ score: None,
+ })
+ .collect())
+}
+
+#[derive(Debug, Clone)]
+struct AnyTxtItem {
+ title: String,
+ path: String,
+ snippet: String,
+}
+
+fn extract_anytxt_items(value: &Value) -> Vec<AnyTxtItem> {
+ let candidates = value
+ .get("result")
+ .and_then(|result| {
+ result
+ .get("items")
+ .or_else(|| result.get("files"))
+ .or_else(|| result.get("result"))
+ .or_else(|| result.get("data"))
+ })
+ .and_then(Value::as_array)
+ .or_else(|| value.get("result").and_then(Value::as_array))
+ .cloned()
+ .unwrap_or_default();
+ candidates
+ .into_iter()
+ .filter_map(|item| {
+ let path = item
+ .get("path")
+ .or_else(|| item.get("file"))
+ .or_else(|| item.get("filename"))
+ .and_then(Value::as_str)
+ .unwrap_or("")
+ .to_string();
+ let title = item
+ .get("title")
+ .or_else(|| item.get("name"))
+ .and_then(Value::as_str)
+ .filter(|value| !value.trim().is_empty())
+ .map(ToOwned::to_owned)
+ .unwrap_or_else(|| {
+ Path::new(&path)
+ .file_name()
+ .and_then(|s| s.to_str())
+ .unwrap_or("AnyTXT result")
+ .to_string()
+ });
+ let snippet = item
+ .get("snippet")
+ .or_else(|| item.get("fragment"))
+ .or_else(|| item.get("text"))
+ .and_then(Value::as_str)
+ .unwrap_or("")
+ .to_string();
+ if path.is_empty() && snippet.is_empty() {
+ None
+ } else {
+ Some(AnyTxtItem {
+ title,
+ path,
+ snippet,
+ })
+ }
+ })
+ .collect()
+}
+
+fn anytxt_pattern_from_query(query: &str) -> String {
+ let terms = source_query_terms(&query.to_lowercase());
+ if terms.is_empty() {
+ return query.trim().to_string();
+ }
+ terms.into_iter().take(5).collect::<Vec<_>>().join(" ")
+}
+
+#[derive(Debug, Clone)]
+struct WebSearchItem {
+ title: String,
+ url: String,
+ snippet: String,
+}
+
+async fn firecrawl_search(
+ client: &reqwest::Client,
+ query: &str,
+ max_results: usize,
+) -> Result<Vec<WebSearchItem>, String> {
+ let response = client
+ .post("https://api.firecrawl.dev/v2/search")
+ .header("Accept", "application/json")
+ .json(&json!({ "query": query, "limit": max_results }))
+ .send()
+ .await
+ .map_err(|err| format!("Network error reaching Firecrawl Search: {err}"))?;
+ let status = response.status();
+ let text = response
+ .text()
+ .await
+ .map_err(|err| format!("Failed to read Firecrawl response: {err}"))?;
+ let parsed: Value = serde_json::from_str(&text).map_err(|_| {
+ format!(
+ "Firecrawl search returned invalid JSON: {}",
+ trim_text(&text, 300)
+ )
+ })?;
+ if !status.is_success() || parsed.get("success").and_then(Value::as_bool) == Some(false) {
+ let msg = parsed
+ .get("error")
+ .and_then(Value::as_str)
+ .map(friendly_firecrawl_error)
+ .unwrap_or_else(|| format!("Firecrawl search failed ({status})"));
+ return Err(msg);
+ }
+ let items = parsed
+ .get("data")
+ .and_then(Value::as_array)
+ .or_else(|| parsed.get("results").and_then(Value::as_array))
+ .cloned()
+ .unwrap_or_default();
+ Ok(items.into_iter().map(normalize_web_result).collect())
+}
+
+async fn searxng_search(
+ client: &reqwest::Client,
+ query: &str,
+ config: &WebSearchConfig,
+ max_results: usize,
+) -> Result<Vec<WebSearchItem>, String> {
+ let base = config
+ .sear_xng_url
+ .as_deref()
+ .filter(|v| !v.trim().is_empty())
+ .ok_or_else(|| "SearXNG URL is required for web.search".to_string())?;
+ let mut url = normalize_searxng_url(base)?;
+ let categories = config
+ .sear_xng_categories
+ .clone()
+ .unwrap_or_else(|| vec!["general".to_string()]);
+ url.push_str(&format!(
+ "?q={}&format=json&categories={}",
+ url_encode(query),
+ url_encode(&categories.join(","))
+ ));
+ let response = client
+ .get(&url)
+ .header("Accept", "application/json")
+ .send()
+ .await
+ .map_err(|err| format!("Network error reaching SearXNG: {err}"))?;
+ let status = response.status();
+ let text = response
+ .text()
+ .await
+ .map_err(|err| format!("Failed to read SearXNG response: {err}"))?;
+ if !status.is_success() {
+ return Err(format!(
+ "SearXNG search failed ({status}): {}",
+ trim_text(&text, 300)
+ ));
+ }
+ let parsed: Value = serde_json::from_str(&text)
+ .map_err(|_| format!("SearXNG returned invalid JSON: {}", trim_text(&text, 300)))?;
+ let items = parsed
+ .get("results")
+ .and_then(Value::as_array)
+ .cloned()
+ .unwrap_or_default();
+ Ok(items
+ .into_iter()
+ .take(max_results)
+ .map(normalize_web_result)
+ .collect())
+}
+
+async fn tavily_search(
+ client: &reqwest::Client,
+ query: &str,
+ config: &WebSearchConfig,
+ max_results: usize,
+) -> Result<Vec<WebSearchItem>, String> {
+ let key = required_api_key(config, "Tavily")?;
+ let response = client
+ .post("https://api.tavily.com/search")
+ .json(&json!({
+ "api_key": key,
+ "query": query,
+ "max_results": max_results,
+ "search_depth": "advanced",
+ "include_answer": false
+ }))
+ .send()
+ .await
+ .map_err(|err| format!("Network error reaching Tavily: {err}"))?;
+ parse_web_json_response(response, "Tavily", |value| {
+ value
+ .get("results")
+ .and_then(Value::as_array)
+ .cloned()
+ .unwrap_or_default()
+ .into_iter()
+ .map(normalize_web_result)
+ .collect()
+ })
+ .await
+}
+
+async fn brave_search(
+ client: &reqwest::Client,
+ query: &str,
+ config: &WebSearchConfig,
+ max_results: usize,
+) -> Result<Vec<WebSearchItem>, String> {
+ let key = required_api_key(config, "Brave")?;
+ let url = format!(
+ "https://api.search.brave.com/res/v1/web/search?q={}&count={}",
+ url_encode(query),
+ max_results.min(20)
+ );
+ let response = client
+ .get(url)
+ .header("Accept", "application/json")
+ .header("X-Subscription-Token", key)
+ .send()
+ .await
+ .map_err(|err| format!("Network error reaching Brave Search: {err}"))?;
+ parse_web_json_response(response, "Brave Search", |value| {
+ value
+ .get("web")
+ .and_then(|web| web.get("results"))
+ .and_then(Value::as_array)
+ .cloned()
+ .unwrap_or_default()
+ .into_iter()
+ .map(normalize_web_result)
+ .collect()
+ })
+ .await
+}
+
+async fn serpapi_search(
+ client: &reqwest::Client,
+ query: &str,
+ config: &WebSearchConfig,
+ max_results: usize,
+) -> Result<Vec<WebSearchItem>, String> {
+ let key = required_api_key(config, "SerpApi")?;
+ let engine = config.serp_api_engine.as_deref().unwrap_or("google");
+ let url = format!(
+ "https://serpapi.com/search?engine={}&q={}&api_key={}&num={}",
+ url_encode(engine),
+ url_encode(query),
+ url_encode(key),
+ max_results
+ );
+ let response = client
+ .get(url)
+ .header("Accept", "application/json")
+ .send()
+ .await
+ .map_err(|err| format!("Network error reaching SerpApi: {err}"))?;
+ parse_web_json_response(response, "SerpApi", |value| {
+ for key in [
+ "organic_results",
+ "news_results",
+ "images_results",
+ "video_results",
+ "videos_results",
+ "shopping_results",
+ ] {
+ if let Some(items) = value.get(key).and_then(Value::as_array) {
+ return items.iter().cloned().map(normalize_web_result).collect();
+ }
+ }
+ Vec::new()
+ })
+ .await
+}
+
+async fn parse_web_json_response(
+ response: reqwest::Response,
+ provider: &str,
+ parse: impl FnOnce(Value) -> Vec<WebSearchItem>,
+) -> Result<Vec<WebSearchItem>, String> {
+ let status = response.status();
+ let text = response
+ .text()
+ .await
+ .map_err(|err| format!("Failed to read {provider} response: {err}"))?;
+ if !status.is_success() {
+ return Err(format!(
+ "{provider} search failed ({status}): {}",
+ trim_text(&text, 300)
+ ));
+ }
+ let value: Value = serde_json::from_str(&text).map_err(|_| {
+ format!(
+ "{provider} returned invalid JSON: {}",
+ trim_text(&text, 300)
+ )
+ })?;
+ if let Some(error) = value.get("error").and_then(Value::as_str) {
+ return Err(format!("{provider} search failed: {error}"));
+ }
+ Ok(parse(value))
+}
+
+fn normalize_web_result(value: Value) -> WebSearchItem {
+ let title = value
+ .get("title")
+ .and_then(Value::as_str)
+ .unwrap_or("Untitled")
+ .to_string();
+ let url = value
+ .get("url")
+ .or_else(|| value.get("link"))
+ .or_else(|| value.get("source"))
+ .or_else(|| value.get("original"))
+ .and_then(Value::as_str)
+ .unwrap_or("")
+ .to_string();
+ let snippet = value
+ .get("snippet")
+ .or_else(|| value.get("content"))
+ .or_else(|| value.get("description"))
+ .or_else(|| value.get("summary"))
+ .or_else(|| value.get("markdown"))
+ .and_then(Value::as_str)
+ .unwrap_or("")
+ .to_string();
+ WebSearchItem {
+ title,
+ url,
+ snippet,
+ }
+}
+
+fn required_api_key<'a>(config: &'a WebSearchConfig, provider: &str) -> Result<&'a str, String> {
+ let key = config.api_key.trim();
+ if key.is_empty() {
+ Err(format!(
+ "{provider} web.search requires an API key in Settings."
+ ))
+ } else {
+ Ok(key)
+ }
+}
+
+fn normalize_searxng_url(value: &str) -> Result<String, String> {
+ let trimmed = value.trim().trim_end_matches('/');
+ if trimmed.is_empty() {
+ return Err("SearXNG URL is required".to_string());
+ }
+ let mut url = if trimmed.starts_with("http://") || trimmed.starts_with("https://") {
+ trimmed.to_string()
+ } else {
+ format!("https://{trimmed}")
+ };
+ if !url.ends_with("/search") {
+ url.push_str("/search");
+ }
+ Ok(url)
+}
+
+fn friendly_firecrawl_error(error: &str) -> String {
+ if error
+ .to_ascii_lowercase()
+ .contains("ip address looks suspicious")
+ {
+ "Firecrawl Search rejected this IP for key-free access. Add a Firecrawl API key when that backend supports authenticated search, or choose another Web Search provider.".to_string()
+ } else {
+ format!("Firecrawl search failed: {error}")
+ }
+}
+
+pub fn read_wiki_page(project_path: &str, rel_path: &str) -> Result<String, String> {
+ let rel = normalize_rel_path(rel_path);
+ if !is_public_read_rel(&rel) || !rel.to_ascii_lowercase().starts_with("wiki/") {
+ return Err("wiki.read_page path must stay under wiki/".to_string());
+ }
+ let path = safe_project_join(project_path, &rel)?;
+ let meta = fs::metadata(&path).map_err(|err| format!("Failed to read page metadata: {err}"))?;
+ if !meta.is_file() {
+ return Err("wiki.read_page path is not a file".to_string());
+ }
+ if meta.len() as usize > MAX_READ_PAGE_BYTES {
+ return Err("wiki.read_page file is too large".to_string());
+ }
+ fs::read_to_string(path).map_err(|err| format!("Failed to read wiki page: {err}"))
+}
+
+pub fn search_graph(
+ project_path: &str,
+ query: &str,
+ top_k: usize,
+) -> Result<Vec<AgentReference>, String> {
+ let query = query.trim().to_lowercase();
+ if query.is_empty() {
+ return Ok(Vec::new());
+ }
+ let wiki_root = Path::new(project_path).join("wiki");
+ if !wiki_root.exists() {
+ return Ok(Vec::new());
+ }
+ let mut refs = Vec::new();
+ let mut seen_files = 0usize;
+ for entry in WalkDir::new(&wiki_root).into_iter().filter_map(Result::ok) {
+ if !entry.file_type().is_file()
+ || entry.path().extension().and_then(|s| s.to_str()) != Some("md")
+ {
+ continue;
+ }
+ seen_files += 1;
+ if seen_files > MAX_GRAPH_SEARCH_FILES {
+ eprintln!(
+ "[Agent] graph.search stopped after {MAX_GRAPH_SEARCH_FILES} markdown files in {project_path}"
+ );
+ break;
+ }
+ let Ok(content) = fs::read_to_string(entry.path()) else {
+ continue;
+ };
+ let rel = relative_to_project(project_path, entry.path());
+ if is_hidden_rel(&rel) {
+ continue;
+ }
+ let title = search::extract_title(
+ &content,
+ entry
+ .path()
+ .file_stem()
+ .and_then(|s| s.to_str())
+ .unwrap_or(&rel),
+ );
+ let link_count = count_wikilinks(&content);
+ let haystack = format!("{} {} {}", title, rel, content).to_lowercase();
+ if !haystack.contains(&query) && link_count == 0 {
+ continue;
+ }
+ refs.push(AgentReference {
+ title,
+ path: rel,
+ kind: "graph".to_string(),
+ snippet: Some(format!("{link_count} wikilink(s)")),
+ score: Some(link_count as f64),
+ });
+ refs.sort_by(|a, b| {
+ b.score
+ .partial_cmp(&a.score)
+ .unwrap_or(std::cmp::Ordering::Equal)
+ .then_with(|| a.path.cmp(&b.path))
+ });
+ refs.truncate(top_k.clamp(1, 10));
+ }
+ Ok(refs)
+}
+
+pub fn search_sources(
+ project_path: &str,
+ query: &str,
+ top_k: usize,
+) -> Result<Vec<AgentReference>, String> {
+ let query = query.trim();
+ if query.is_empty() {
+ return Err("source.search query is required".to_string());
+ }
+ let root = Path::new(project_path).join("raw").join("sources");
+ if !root.exists() {
+ return Ok(Vec::new());
+ }
+ let lower_query = query.to_lowercase();
+ let query_terms = source_query_terms(&lower_query);
+ let mut refs = Vec::new();
+ let mut seen_files = 0usize;
+ for entry in WalkDir::new(&root).into_iter().filter_map(Result::ok) {
+ if !entry.file_type().is_file() {
+ continue;
+ }
+ seen_files += 1;
+ if seen_files > MAX_SOURCE_SEARCH_FILES {
+ eprintln!(
+ "[Agent] source.search stopped after {MAX_SOURCE_SEARCH_FILES} files in {project_path}"
+ );
+ break;
+ }
+ let Some(ext) = entry
+ .path()
+ .extension()
+ .and_then(|s| s.to_str())
+ .map(|s| s.to_ascii_lowercase())
+ else {
+ continue;
+ };
+ if !matches!(
+ ext.as_str(),
+ "md" | "markdown" | "txt" | "json" | "csv" | "tsv" | "yaml" | "yml" | "xml" | "html"
+ ) {
+ continue;
+ }
+ let Ok(content) = fs::read_to_string(entry.path()) else {
+ continue;
+ };
+ let lower = content.to_lowercase();
+ let matched = std::iter::once(lower_query.as_str())
+ .chain(query_terms.iter().map(String::as_str))
+ .find_map(|term| lower.find(term).map(|idx| (idx, term.len())));
+ let Some((byte_idx, _matched_len)) = matched else {
+ continue;
+ };
+ let rel = relative_to_project(project_path, entry.path());
+ if is_hidden_rel(&rel) {
+ continue;
+ }
+ refs.push(AgentReference {
+ title: entry
+ .path()
+ .file_name()
+ .and_then(|s| s.to_str())
+ .unwrap_or(&rel)
+ .to_string(),
+ path: rel,
+ kind: "source".to_string(),
+ snippet: Some(snippet_around_byte(
+ &content,
+ byte_idx,
+ MAX_SOURCE_SNIPPET_CHARS,
+ )),
+ score: None,
+ });
+ if refs.len() >= top_k.clamp(1, 10) {
+ break;
+ }
+ }
+ Ok(refs)
+}
+
+fn source_query_terms(query: &str) -> Vec<String> {
+ query
+ .split(|c: char| c.is_whitespace() || matches!(c, ',' | ',' | ';' | ';' | ':' | ':'))
+ .map(str::trim)
+ .filter(|term| term.chars().count() >= 2)
+ .filter(|term| {
+ !matches!(
+ *term,
+ "raw"
+ | "source"
+ | "sources"
+ | "file"
+ | "files"
+ | "原始资料"
+ | "原始文件"
+ | "源文件"
+ )
+ })
+ .map(ToString::to_string)
+ .collect()
+}
+
+fn count_wikilinks(content: &str) -> usize {
+ content.match_indices("[[").count()
+}
+
+fn safe_project_join(project_path: &str, rel: &str) -> Result<PathBuf, String> {
+ let root = Path::new(project_path);
+ let rel_path = Path::new(rel);
+ if rel_path.is_absolute()
+ || rel_path
+ .components()
+ .any(|component| matches!(component, Component::ParentDir | Component::Prefix(_)))
+ {
+ return Err("path must be project-relative".to_string());
+ }
+ let joined = root.join(rel_path);
+ if joined.exists() {
+ let root_canon = root
+ .canonicalize()
+ .map_err(|err| format!("Failed to resolve project path: {err}"))?;
+ let joined_canon = joined
+ .canonicalize()
+ .map_err(|err| format!("Failed to resolve requested path: {err}"))?;
+ if !joined_canon.starts_with(root_canon) {
+ return Err("path escapes project directory".to_string());
+ }
+ }
+ Ok(joined)
+}
+
+fn ensure_existing_ancestor_bound(project_path: &str, path: &Path) -> Result<(), String> {
+ let mut cursor = path;
+ while !cursor.exists() {
+ cursor = cursor
+ .parent()
+ .ok_or_else(|| "path must have an existing project ancestor".to_string())?;
+ }
+ ensure_project_bound_path(project_path, cursor)
+}
+
+fn ensure_project_bound_path(project_path: &str, path: &Path) -> Result<(), String> {
+ let root_canon = Path::new(project_path)
+ .canonicalize()
+ .map_err(|err| format!("Failed to resolve project path: {err}"))?;
+ let path_canon = path
+ .canonicalize()
+ .map_err(|err| format!("Failed to resolve requested path: {err}"))?;
+ if !path_canon.starts_with(root_canon) {
+ return Err("path escapes project directory".to_string());
+ }
+ Ok(())
+}
+
+fn is_public_read_rel(rel: &str) -> bool {
+ let lower = rel.to_ascii_lowercase();
+ if lower.split('/').any(|segment| segment.starts_with('.')) {
+ return false;
+ }
+ lower == "purpose.md"
+ || lower == "schema.md"
+ || lower.starts_with("wiki/")
+ || lower.starts_with("raw/sources/")
+}
+
+fn is_hidden_rel(rel: &str) -> bool {
+ normalize_rel_path(rel)
+ .split('/')
+ .any(|segment| segment.starts_with('.'))
+}
+
+fn normalize_rel_path(path: &str) -> String {
+ path.trim()
+ .replace('\\', "/")
+ .trim_start_matches('/')
+ .to_string()
+}
+
+fn normalize_wiki_write_path(path: &str) -> Result<String, String> {
+ let rel = normalize_rel_path(path);
+ let lower = rel.to_ascii_lowercase();
+ if !lower.starts_with("wiki/") || !lower.ends_with(".md") {
+ return Err("wiki.write_page path must be a Markdown file under wiki/".to_string());
+ }
+ if lower.split('/').any(|segment| segment.starts_with('.')) {
+ return Err("wiki.write_page cannot write hidden paths".to_string());
+ }
+ let rel_path = Path::new(&rel);
+ if rel_path.is_absolute()
+ || rel_path
+ .components()
+ .any(|component| matches!(component, Component::ParentDir | Component::Prefix(_)))
+ {
+ return Err("wiki.write_page path must stay inside the project".to_string());
+ }
+ Ok(rel)
+}
+
+fn extract_markdown_title(content: &str) -> Option<String> {
+ for line in content.lines().take(80) {
+ let trimmed = line.trim();
+ if let Some(title) = trimmed.strip_prefix("title:") {
+ let title = title.trim().trim_matches('"').trim_matches('\'');
+ if !title.is_empty() {
+ return Some(title.to_string());
+ }
+ }
+ if let Some(heading) = trimmed.strip_prefix("# ") {
+ let heading = heading.trim();
+ if !heading.is_empty() {
+ return Some(heading.to_string());
+ }
+ }
+ }
+ None
+}
+
+fn collapse_markdown_preview(content: &str) -> String {
+ content
+ .lines()
+ .filter(|line| {
+ let trimmed = line.trim();
+ !trimmed.is_empty() && trimmed != "---" && !trimmed.starts_with("title:")
+ })
+ .take(12)
+ .collect::<Vec<_>>()
+ .join(" ")
+}
+
+fn relative_to_project(project_path: &str, path: &Path) -> String {
+ path.strip_prefix(project_path)
+ .unwrap_or(path)
+ .to_string_lossy()
+ .replace('\\', "/")
+ .trim_start_matches('/')
+ .to_string()
+}
+
+fn snippet_around_byte(content: &str, byte_idx: usize, max_chars: usize) -> String {
+ let char_idx = content[..byte_idx.min(content.len())].chars().count();
+ let start = char_idx.saturating_sub(max_chars / 2);
+ let mut snippet = content
+ .chars()
+ .skip(start)
+ .take(max_chars)
+ .collect::<String>();
+ if start > 0 {
+ snippet.insert_str(0, "...");
+ }
+ if content.chars().count() > start + max_chars {
+ snippet.push_str("...");
+ }
+ snippet.split_whitespace().collect::<Vec<_>>().join(" ")
+}
+
+fn trim_text(value: &str, max_chars: usize) -> String {
+ if value.chars().count() <= max_chars {
+ value.to_string()
+ } else {
+ format!("{}...", value.chars().take(max_chars).collect::<String>())
+ }
+}
+
+fn url_encode(value: &str) -> String {
+ value
+ .bytes()
+ .flat_map(|byte| match byte {
+ b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
+ vec![byte as char]
+ }
+ b' ' => vec!['+'],
+ _ => format!("%{byte:02X}").chars().collect(),
+ })
+ .collect()
+}
+
+#[cfg(test)]
+mod tests {
+ use std::fs;
+
+ use uuid::Uuid;
+
+ use super::*;
+
+ #[test]
+ fn builtin_tool_specs_include_expected_tools() {
+ let names = builtin_tool_specs()
+ .into_iter()
+ .map(|tool| tool.name)
+ .collect::<Vec<_>>();
+ assert!(names.contains(&"wiki.search".to_string()));
+ assert!(names.contains(&"wiki.read_page".to_string()));
+ assert!(names.contains(&"source.search".to_string()));
+ assert!(names.contains(&"graph.search".to_string()));
+ assert!(names.contains(&"anytxt.search".to_string()));
+ assert!(names.contains(&"wiki.write_page".to_string()));
+ assert!(names.contains(&"llm.generate".to_string()));
+ assert!(names.contains(&"skills.load".to_string()));
+ }
+
+ #[test]
+ fn read_wiki_page_rejects_traversal() {
+ let err = read_wiki_page("/tmp/project", "../secret.md").unwrap_err();
+ assert!(err.contains("wiki.read_page"));
+ }
+
+ #[tokio::test]
+ async fn registry_executes_declared_read_page_and_deep_tools() {
+ let root = std::env::temp_dir().join(format!("llm-wiki-tool-registry-{}", Uuid::new_v4()));
+ fs::create_dir_all(root.join("wiki").join("concepts")).unwrap();
+ fs::write(root.join("wiki/concepts/a.md"), "# A\n\nBody").unwrap();
+
+ let registry = BuiltinToolRegistry;
+ let context = ToolContext {
+ project_path: root.to_str().unwrap(),
+ embedding_config: None,
+ web_search_config: None,
+ anytxt_config: None,
+ };
+ let read = registry
+ .execute(
+ "wiki.read_page",
+ json!({ "path": "wiki/concepts/a.md" }),
+ context.clone(),
+ )
+ .await
+ .unwrap();
+ assert_eq!(read["path"], "wiki/concepts/a.md");
+ assert!(read["content"].as_str().unwrap().contains("Body"));
+
+ let deep = registry
+ .execute("deep_research.run", json!({ "query": "topic" }), context)
+ .await
+ .unwrap();
+ assert_eq!(deep["status"], "orchestrated_by_agent_runtime");
+ let _ = fs::remove_dir_all(root);
+ }
+
+ #[test]
+ fn write_wiki_page_rejects_unsafe_paths_and_writes_markdown() {
+ let root = std::env::temp_dir().join(format!("llm-wiki-agent-write-{}", Uuid::new_v4()));
+ fs::create_dir_all(root.join("wiki")).unwrap();
+
+ assert!(write_wiki_page(root.to_str().unwrap(), "../secret.md", "# Secret").is_err());
+ assert!(write_wiki_page(root.to_str().unwrap(), "raw/sources/a.md", "# A").is_err());
+ assert!(write_wiki_page(root.to_str().unwrap(), "wiki/.hidden/a.md", "# A").is_err());
+ assert!(write_wiki_page(
+ root.to_str().unwrap(),
+ "wiki/queries/huge.md",
+ &"x".repeat(MAX_WRITE_PAGE_BYTES + 1)
+ )
+ .is_err());
+
+ let reference = write_wiki_page(
+ root.to_str().unwrap(),
+ "wiki/queries/new-page.md",
+ "---\ntitle: New Page\n---\n# New Page\n\nBody",
+ )
+ .unwrap();
+ assert_eq!(reference.title, "New Page");
+ assert_eq!(reference.path, "wiki/queries/new-page.md");
+ assert!(root.join("wiki/queries/new-page.md").exists());
+ let overwrite_err = write_wiki_page(
+ root.to_str().unwrap(),
+ "wiki/queries/new-page.md",
+ "# Replaced",
+ )
+ .unwrap_err();
+ assert!(overwrite_err.contains("refuses to overwrite"));
+ let overwritten = write_wiki_page_with_options(
+ root.to_str().unwrap(),
+ "wiki/queries/new-page.md",
+ "# Replaced",
+ true,
+ )
+ .unwrap();
+ assert_eq!(overwritten.title, "Replaced");
+ let _ = fs::remove_dir_all(root);
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn write_wiki_page_rejects_symlink_parent_escape_for_new_files() {
+ use std::os::unix::fs::symlink;
+
+ let root = std::env::temp_dir().join(format!("llm-wiki-agent-symlink-{}", Uuid::new_v4()));
+ let outside =
+ std::env::temp_dir().join(format!("llm-wiki-agent-outside-{}", Uuid::new_v4()));
+ fs::create_dir_all(root.join("wiki")).unwrap();
+ fs::create_dir_all(&outside).unwrap();
+ symlink(&outside, root.join("wiki").join("linked")).unwrap();
+
+ let err = write_wiki_page(
+ root.to_str().unwrap(),
+ "wiki/linked/newsub/escape.md",
+ "# Escape",
+ )
+ .unwrap_err();
+ assert!(err.contains("escapes project directory"));
+ assert!(!outside.join("newsub").exists());
+ let _ = fs::remove_dir_all(root);
+ let _ = fs::remove_dir_all(outside);
+ }
+
+ #[test]
+ fn search_sources_returns_source_references() {
+ let root = std::env::temp_dir().join(format!("llm-wiki-source-search-{}", Uuid::new_v4()));
+ let source_dir = root.join("raw").join("sources");
+ fs::create_dir_all(&source_dir).unwrap();
+ fs::write(source_dir.join("paper.txt"), "Coal mine safety case study.").unwrap();
+
+ let refs = search_sources(root.to_str().unwrap(), "safety", 5).unwrap();
+ assert_eq!(refs.len(), 1);
+ assert_eq!(refs[0].kind, "source");
+ assert!(refs[0].snippet.as_deref().unwrap().contains("safety"));
+ let _ = fs::remove_dir_all(root);
+ }
+
+ #[test]
+ fn source_and_graph_search_skip_hidden_paths() {
+ let root = std::env::temp_dir().join(format!("llm-wiki-hidden-search-{}", Uuid::new_v4()));
+ fs::create_dir_all(root.join("raw/sources/.cache")).unwrap();
+ fs::create_dir_all(root.join("wiki/.hidden")).unwrap();
+ fs::write(root.join("raw/sources/.cache/secret.txt"), "needle secret").unwrap();
+ fs::write(
+ root.join("wiki/.hidden/secret.md"),
+ "# Secret\n\nneedle [[A]]",
+ )
+ .unwrap();
+
+ assert!(search_sources(root.to_str().unwrap(), "needle", 5)
+ .unwrap()
+ .is_empty());
+ assert!(search_graph(root.to_str().unwrap(), "needle", 5)
+ .unwrap()
+ .is_empty());
+ let _ = fs::remove_dir_all(root);
+ }
+
+ #[test]
+ fn search_sources_uses_keyword_terms_from_natural_language() {
+ let root = std::env::temp_dir().join(format!("llm-wiki-source-search-{}", Uuid::new_v4()));
+ let source_dir = root.join("raw").join("sources");
+ fs::create_dir_all(&source_dir).unwrap();
+ fs::write(source_dir.join("煤矿.txt"), "煤矿安全治理 source details.").unwrap();
+
+ let refs = search_sources(root.to_str().unwrap(), "原始资料 煤矿安全", 5).unwrap();
+ assert_eq!(refs.len(), 1);
+ assert_eq!(refs[0].kind, "source");
+ let _ = fs::remove_dir_all(root);
+ }
+
+ #[test]
+ fn search_graph_returns_relationship_references() {
+ let root = std::env::temp_dir().join(format!("llm-wiki-graph-search-{}", Uuid::new_v4()));
+ let wiki_dir = root.join("wiki").join("concepts");
+ fs::create_dir_all(&wiki_dir).unwrap();
+ fs::write(
+ wiki_dir.join("agent.md"),
+ "---\ntitle: Agent Graph\n---\n# Agent Graph\n\nLinks to [[Tool Registry]] and [[Context Builder]].",
+ )
+ .unwrap();
+
+ let refs = search_graph(root.to_str().unwrap(), "agent", 5).unwrap();
+ assert_eq!(refs.len(), 1);
+ assert_eq!(refs[0].kind, "graph");
+ assert_eq!(refs[0].score, Some(2.0));
+ let _ = fs::remove_dir_all(root);
+ }
+
+ #[test]
+ fn searxng_url_normalizes_to_search_endpoint() {
+ assert_eq!(
+ normalize_searxng_url("search.example.com").unwrap(),
+ "https://search.example.com/search"
+ );
+ assert_eq!(
+ normalize_searxng_url("https://search.example.com/search").unwrap(),
+ "https://search.example.com/search"
+ );
+ }
+
+ #[test]
+ fn friendly_firecrawl_error_explains_key_free_ip_rejection() {
+ let msg = friendly_firecrawl_error("Unfortunately, your IP address looks suspicious");
+ assert!(msg.contains("rejected this IP"));
+ }
+
+ #[test]
+ fn url_encode_handles_unicode_terms() {
+ assert_eq!(url_encode("煤矿 safety"), "%E7%85%A4%E7%9F%BF+safety");
+ }
+
+ #[test]
+ fn web_search_config_resolves_active_provider_override() {
+ let mut configs = BTreeMap::new();
+ configs.insert(
+ "searxng".to_string(),
+ WebSearchProviderOverride {
+ sear_xng_url: Some("https://search.example.com".to_string()),
+ ..Default::default()
+ },
+ );
+ let cfg = WebSearchConfig {
+ provider: "searxng".to_string(),
+ provider_configs: Some(configs),
+ ..Default::default()
+ }
+ .resolved();
+
+ assert_eq!(
+ cfg.sear_xng_url.as_deref(),
+ Some("https://search.example.com")
+ );
+ }
+
+ #[test]
+ fn extract_anytxt_items_accepts_common_result_shapes() {
+ let value = json!({
+ "result": {
+ "items": [
+ { "path": "/docs/a.pdf", "title": "A", "snippet": "coal mine" }
+ ]
+ }
+ });
+ let items = extract_anytxt_items(&value);
+ assert_eq!(items.len(), 1);
+ assert_eq!(items[0].title, "A");
+ assert_eq!(items[0].path, "/docs/a.pdf");
+ assert_eq!(items[0].snippet, "coal mine");
+ }
+
+ #[test]
+ fn anytxt_pattern_keeps_multiple_useful_terms() {
+ assert_eq!(
+ anytxt_pattern_from_query("请搜索 原始资料 煤矿 安全 治理 的材料"),
+ "请搜索 煤矿 安全 治理 的材料"
+ );
+ }
+}
diff --git a/src-tauri/src/agent/types.rs b/src-tauri/src/agent/types.rs
new file mode 100644
index 00000000..b09c0285
--- /dev/null
+++ b/src-tauri/src/agent/types.rs
@@ -0,0 +1,193 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum AgentMode {
+ Fast,
+ Standard,
+ Deep,
+ LocalFirst,
+}
+
+impl Default for AgentMode {
+ fn default() -> Self {
+ Self::Standard
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentToolOptions {
+ #[serde(default = "default_true")]
+ pub wiki: bool,
+ #[serde(default)]
+ pub web: bool,
+ #[serde(default)]
+ pub anytxt: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentUsage {
+ pub prompt_chars: usize,
+ pub completion_chars: usize,
+ pub reference_count: usize,
+ pub tool_event_count: usize,
+}
+
+const fn default_true() -> bool {
+ true
+}
+
+impl Default for AgentToolOptions {
+ fn default() -> Self {
+ Self {
+ wiki: true,
+ web: false,
+ anytxt: false,
+ }
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentChatRequest {
+ pub message: String,
+ #[serde(default)]
+ pub session_id: Option<String>,
+ #[serde(default)]
+ pub run_id: Option<String>,
+ #[serde(default)]
+ pub mode: AgentMode,
+ #[serde(default)]
+ pub tools: AgentToolOptions,
+ #[serde(default)]
+ pub top_k: Option<usize>,
+ #[serde(default)]
+ pub include_content: Option<bool>,
+ #[serde(default)]
+ pub history: Vec<AgentConversationMessage>,
+ #[serde(default)]
+ pub skills: Vec<String>,
+ #[serde(default)]
+ pub images: Vec<AgentImage>,
+ #[serde(default)]
+ pub stream: Option<bool>,
+ #[serde(default = "default_true")]
+ pub persist_session: bool,
+}
+
+impl Default for AgentChatRequest {
+ fn default() -> Self {
+ Self {
+ message: String::new(),
+ session_id: None,
+ run_id: None,
+ mode: AgentMode::default(),
+ tools: AgentToolOptions::default(),
+ top_k: None,
+ include_content: None,
+ history: Vec::new(),
+ skills: Vec::new(),
+ images: Vec::new(),
+ stream: None,
+ persist_session: true,
+ }
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentImage {
+ pub media_type: String,
+ pub data_base64: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentReference {
+ pub title: String,
+ pub path: String,
+ pub kind: String,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub snippet: Option<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub score: Option<f64>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentToolEvent {
+ pub tool: String,
+ pub status: String,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub detail: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentChatResponse {
+ pub ok: bool,
+ pub project_id: String,
+ pub session_id: String,
+ pub mode: AgentMode,
+ pub message: String,
+ pub references: Vec<AgentReference>,
+ pub tool_events: Vec<AgentToolEvent>,
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
+ pub events: Vec<super::events::AgentEvent>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub usage: Option<AgentUsage>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentConversationMessage {
+ pub role: String,
+ pub content: String,
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn chat_request_accepts_camelcase_api_shape_with_defaults() {
+ let req: AgentChatRequest = serde_json::from_value(serde_json::json!({
+ "message": "hello",
+ "sessionId": "s1",
+ "topK": 7
+ }))
+ .unwrap();
+
+ assert_eq!(req.message, "hello");
+ assert_eq!(req.session_id.as_deref(), Some("s1"));
+ assert!(req.run_id.is_none());
+ assert_eq!(req.mode, AgentMode::Standard);
+ assert_eq!(req.top_k, Some(7));
+ assert!(req.tools.wiki);
+ assert!(!req.tools.web);
+ assert!(!req.tools.anytxt);
+ assert!(req.persist_session);
+ }
+
+ #[test]
+ fn chat_request_accepts_tool_overrides() {
+ let req: AgentChatRequest = serde_json::from_value(serde_json::json!({
+ "message": "hello",
+ "mode": "local_first",
+ "tools": {
+ "wiki": false,
+ "web": true,
+ "anytxt": true
+ }
+ }))
+ .unwrap();
+
+ assert_eq!(req.mode, AgentMode::LocalFirst);
+ assert!(!req.tools.wiki);
+ assert!(req.tools.web);
+ assert!(req.tools.anytxt);
+ assert!(req.images.is_empty());
+ }
+}
diff --git a/src-tauri/src/api_server.rs b/src-tauri/src/api_server.rs
index 8b257cc6..16e5236a 100644
--- a/src-tauri/src/api_server.rs
+++ b/src-tauri/src/api_server.rs
@@ -11,14 +11,16 @@ use serde::{Deserialize, Serialize};
use serde_json::{json, Map, Value};
use tauri::{AppHandle, Manager};
use tiny_http::{Header, Method, Response, Server, StatusCode};
+use uuid::Uuid;
use walkdir::WalkDir;
use crate::cors::{local_cors_headers, request_origin};
-use crate::{clip_server, commands, server_bind};
+use crate::{agent, clip_server, commands, server_bind};
const PORT: u16 = 19828;
const API_PREFIX: &str = "/api/v1";
const MAX_BODY_BYTES: usize = 1024 * 1024;
+const MAX_CHAT_BODY_BYTES: usize = 40 * 1024 * 1024;
const MAX_FILE_CONTENT_BYTES: u64 = 2 * 1024 * 1024;
const DEFAULT_MAX_FILES: usize = 2_000;
const HARD_MAX_FILES: usize = 10_000;
@@ -171,7 +173,7 @@ fn process_request(app: AppHandle, mut request: tiny_http::Request) {
})
.collect();
- let body = match read_body(&mut request) {
+ let body = match read_body(&mut request, body_limit_for_request(&method, &url)) {
Ok(body) => body,
Err(err) => {
respond_error(request, 400, &err, origin.as_deref());
@@ -230,6 +232,10 @@ fn handle_request(
"mcpEnabled": api_mcp_enabled(app),
"allowUnauthenticated": api_allow_unauthenticated(app),
"allowLanAccess": api_allow_lan_access(app),
+ "agent": {
+ "chat": true,
+ "streaming": false,
+ },
}));
}
if !path.starts_with(API_PREFIX) {
@@ -243,6 +249,9 @@ fn handle_request(
// retry instantly the way 401 would.
return err(503, "API server is disabled in Settings → API Server");
}
+ if is_agent_chat_request(&method, &path) && !is_token_authorized(app, query, headers) {
+ return err(401, "Unauthorized");
+ }
if !is_authorized(app, query, headers) {
return err(401, "Unauthorized");
}
@@ -277,9 +286,9 @@ fn handle_request(
(&Method::Post, ["projects", project_id, "sources", "rescan"]) => {
handle_rescan(app, project_id)
}
- (&Method::Post, ["projects", project_id, "chat"]) => {
- let _ = project_id;
- err(501, "Chat API is not implemented in the local Rust API server yet. The existing chat/RAG pipeline currently lives in the WebView; expose it after moving the shared chat pipeline behind a backend command.")
+ (&Method::Post, ["projects", project_id, "chat"]) => handle_chat(app, project_id, body),
+ (&Method::Post, ["projects", project_id, "chat", session_id, "cancel"]) => {
+ handle_cancel_chat(app, project_id, session_id)
}
_ => err(404, "Not found"),
}
@@ -310,13 +319,42 @@ fn allow_request() -> bool {
true
}
-fn read_body(request: &mut tiny_http::Request) -> Result<String, String> {
- let mut limited = request.as_reader().take(MAX_BODY_BYTES as u64 + 1);
+fn is_agent_chat_request(method: &Method, path: &str) -> bool {
+ let parts = path
+ .trim_start_matches(API_PREFIX)
+ .trim_start_matches('/')
+ .split('/')
+ .filter(|part| !part.is_empty())
+ .collect::<Vec<_>>();
+ method == &Method::Post
+ && matches!(
+ parts.as_slice(),
+ ["projects", _, "chat"] | ["projects", _, "chat", _, "cancel"]
+ )
+}
+
+fn body_limit_for_request(method: &Method, url: &str) -> usize {
+ let (path, _) = split_url(url);
+ let parts = path
+ .trim_start_matches(API_PREFIX)
+ .trim_start_matches('/')
+ .split('/')
+ .filter(|part| !part.is_empty())
+ .collect::<Vec<_>>();
+ if method == &Method::Post && matches!(parts.as_slice(), ["projects", _, "chat"]) {
+ MAX_CHAT_BODY_BYTES
+ } else {
+ MAX_BODY_BYTES
+ }
+}
+
+fn read_body(request: &mut tiny_http::Request, max_body_bytes: usize) -> Result<String, String> {
+ let mut limited = request.as_reader().take(max_body_bytes as u64 + 1);
let mut bytes = Vec::new();
limited
.read_to_end(&mut bytes)
.map_err(|e| format!("Failed to read body: {e}"))?;
- if bytes.len() > MAX_BODY_BYTES {
+ if bytes.len() > max_body_bytes {
return Err("Request body too large".to_string());
}
String::from_utf8(bytes).map_err(|_| "Request body must be UTF-8".to_string())
@@ -390,6 +428,10 @@ fn is_authorized(app: &AppHandle, query: &str, headers: &[(String, String)]) ->
if !api_auth_required(app) {
return true;
}
+ is_token_authorized(app, query, headers)
+}
+
+fn is_token_authorized(app: &AppHandle, query: &str, headers: &[(String, String)]) -> bool {
let Some(token) = api_token(app) else {
return false;
};
@@ -1632,12 +1674,153 @@ fn handle_search(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {
}
}
+fn handle_chat(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {
+ let project = match resolve_project(app, project_id) {
+ Ok(project) => project,
+ Err(e) => return err(404, e),
+ };
+ let mut req: agent::AgentChatRequest = match serde_json::from_str(body) {
+ Ok(req) => req,
+ Err(e) => return err(400, format!("Invalid JSON: {e}")),
+ };
+ if req
+ .session_id
+ .as_deref()
+ .map(str::trim)
+ .unwrap_or("")
+ .is_empty()
+ {
+ req.session_id = Some(format!("api_{}", Uuid::new_v4()));
+ }
+ if req
+ .run_id
+ .as_deref()
+ .map(str::trim)
+ .unwrap_or("")
+ .is_empty()
+ {
+ req.run_id = Some(format!("run_{}", Uuid::new_v4()));
+ }
+ let requested_session_id = req.session_id.clone();
+ if let Some(session_id) = requested_session_id.as_deref() {
+ if req.history.is_empty() {
+ req.history = app
+ .state::<agent::session::AgentSessionStore>()
+ .recent_messages(&project.path, session_id, 12)
+ .into_iter()
+ .map(|message| agent::types::AgentConversationMessage {
+ role: message.role,
+ content: message.content,
+ })
+ .collect();
+ }
+ }
+ let runtime_config = load_agent_runtime_config(app);
+ let runtime = agent::AgentRuntime::new(
+ project.id.clone(),
+ project.path.clone(),
+ runtime_config.embedding,
+ runtime_config.llm,
+ runtime_config.web_search,
+ runtime_config.anytxt,
+ );
+ let user_message_for_session = req.message.clone();
+ let persist_session = req.persist_session;
+ let session_id = req.session_id.clone().unwrap_or_default();
+ let run_id = req.run_id.clone().unwrap_or_default();
+ let cancellation = app
+ .state::<agent::cancel::AgentCancellationRegistry>()
+ .start(&project.id, &session_id, &run_id);
+ let result =
+ tauri::async_runtime::block_on(runtime.run_once_with_cancel(req, Some(cancellation)));
+ app.state::<agent::cancel::AgentCancellationRegistry>()
+ .finish(&project.id, &session_id, &run_id);
+ match result {
+ Ok(response) => {
+ if persist_session {
+ app.state::<agent::session::AgentSessionStore>()
+ .append_turn(
+ &project.path,
+ &project.id,
+ &response.session_id,
+ &user_message_for_session,
+ &response.message,
+ );
+ }
+ ok(json!({
+ "ok": true,
+ "projectId": response.project_id,
+ "sessionId": response.session_id,
+ "mode": response.mode,
+ "message": {
+ "role": "assistant",
+ "content": response.message,
+ },
+ "references": response.references,
+ "toolEvents": response.tool_events,
+ "events": response.events,
+ "usage": response.usage,
+ }))
+ }
+ Err(e) if e == "message is required" => err(400, e),
+ Err(e) if e == "Agent turn cancelled" => err(499, e),
+ Err(e) => err(502, e),
+ }
+}
+
+fn handle_cancel_chat(app: &AppHandle, project_id: &str, session_id: &str) -> ApiResponse {
+ let project = match resolve_project(app, project_id) {
+ Ok(project) => project,
+ Err(e) => return err(404, e),
+ };
+ ok(json!({
+ "ok": true,
+ "cancelled": app
+ .state::<agent::cancel::AgentCancellationRegistry>()
+ .cancel(&project.id, session_id, None),
+ "sessionId": session_id,
+ }))
+}
+
fn load_embedding_config(app: &AppHandle) -> Option<commands::search::SearchEmbeddingConfig> {
let parsed = load_app_state(app)?;
let value = parsed.get("embeddingConfig")?.clone();
serde_json::from_value::<commands::search::SearchEmbeddingConfig>(value).ok()
}
+#[derive(Debug, Clone, Default)]
+struct AgentRuntimeConfig {
+ embedding: Option<commands::search::SearchEmbeddingConfig>,
+ llm: Option<agent::provider::LlmConfig>,
+ web_search: Option<agent::tools::WebSearchConfig>,
+ anytxt: Option<agent::tools::AnyTxtConfig>,
+}
+
+fn load_agent_runtime_config(app: &AppHandle) -> AgentRuntimeConfig {
+ let Some(parsed) = load_app_state(app) else {
+ return AgentRuntimeConfig::default();
+ };
+ AgentRuntimeConfig {
+ embedding: parsed
+ .get("embeddingConfig")
+ .cloned()
+ .and_then(|value| serde_json::from_value(value).ok()),
+ llm: parsed
+ .get("llmConfig")
+ .cloned()
+ .and_then(|value| serde_json::from_value(value).ok()),
+ web_search: parsed
+ .get("searchApiConfig")
+ .cloned()
+ .and_then(|value| serde_json::from_value(value).ok()),
+ anytxt: parsed
+ .get("searchApiConfig")
+ .and_then(|value| value.get("anyTxt"))
+ .cloned()
+ .and_then(|value| serde_json::from_value(value).ok()),
+ }
+}
+
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct ApiGraphNode {
@@ -2429,6 +2612,38 @@ mod tests {
));
}
+ #[test]
+ fn chat_endpoint_allows_larger_multimodal_bodies() {
+ assert_eq!(
+ body_limit_for_request(&Method::Post, "/api/v1/projects/current/chat"),
+ MAX_CHAT_BODY_BYTES
+ );
+ assert_eq!(
+ body_limit_for_request(&Method::Post, "/api/v1/projects/current/search"),
+ MAX_BODY_BYTES
+ );
+ }
+
+ #[test]
+ fn chat_routes_are_recognized_as_agent_requests() {
+ assert!(is_agent_chat_request(
+ &Method::Post,
+ "/api/v1/projects/current/chat"
+ ));
+ assert!(is_agent_chat_request(
+ &Method::Post,
+ "/api/v1/projects/current/chat/session-1/cancel"
+ ));
+ assert!(!is_agent_chat_request(
+ &Method::Post,
+ "/api/v1/projects/current/search"
+ ));
+ assert!(!is_agent_chat_request(
+ &Method::Get,
+ "/api/v1/projects/current/chat"
+ ));
+ }
+
#[test]
fn api_config_shape_parses_enabled_and_unauthenticated_access() {
// Standalone pure-function check to mirror what `api_enabled`
diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index 04a5702d..8073ab20 100644
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -1,3 +1,4 @@
+mod agent;
mod api_server;
mod clip_server;
mod commands;
@@ -9,12 +10,32 @@ mod tray;
mod types;
use panic_guard::run_guarded;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
use std::sync::Mutex;
-use tauri::Manager;
+use tauri::{Emitter, Manager};
+use uuid::Uuid;
struct CloseBehaviorState(Mutex<String>);
struct TrayAvailabilityState(Mutex<bool>);
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct AgentProjectEntry {
+ id: String,
+ name: String,
+ path: String,
+ current: bool,
+}
+
+#[derive(Debug, Clone, Default)]
+struct AgentRuntimeConfig {
+ embedding: Option<commands::search::SearchEmbeddingConfig>,
+ llm: Option<agent::provider::LlmConfig>,
+ web_search: Option<agent::tools::WebSearchConfig>,
+ anytxt: Option<agent::tools::AnyTxtConfig>,
+}
+
#[tauri::command]
fn clip_server_status() -> String {
run_guarded("clip_server_status", || {
@@ -40,6 +61,225 @@ fn api_server_reload_config() -> String {
.unwrap_or_else(|e| format!("error: {e}"))
}
+#[tauri::command]
+async fn agent_start_turn(
+ app: tauri::AppHandle,
+ project_id: String,
+ mut request: agent::AgentChatRequest,
+) -> Result<agent::types::AgentChatResponse, String> {
+ let project = resolve_agent_project(&app, &project_id)?;
+ if request
+ .session_id
+ .as_deref()
+ .map(str::trim)
+ .unwrap_or("")
+ .is_empty()
+ {
+ request.session_id = Some(format!("ui_{}", Uuid::new_v4()));
+ }
+ let active_session_id = request.session_id.clone().unwrap_or_default();
+ if request
+ .run_id
+ .as_deref()
+ .map(str::trim)
+ .unwrap_or("")
+ .is_empty()
+ {
+ request.run_id = Some(format!("run_{}", Uuid::new_v4()));
+ }
+ let active_run_id = request.run_id.clone().unwrap_or_default();
+ if let Some(session_id) = request.session_id.clone() {
+ if request.history.is_empty() {
+ request.history = app
+ .state::<agent::session::AgentSessionStore>()
+ .recent_messages(&project.path, &session_id, 12)
+ .into_iter()
+ .map(|message| agent::types::AgentConversationMessage {
+ role: message.role,
+ content: message.content,
+ })
+ .collect();
+ }
+ }
+ let runtime_config = load_agent_runtime_config(&app);
+ let runtime = agent::AgentRuntime::new(
+ project.id.clone(),
+ project.path.clone(),
+ runtime_config.embedding,
+ runtime_config.llm,
+ runtime_config.web_search,
+ runtime_config.anytxt,
+ );
+ let user_message = request.message.clone();
+ let persist_session = request.persist_session;
+ let cancellation = app
+ .state::<agent::cancel::AgentCancellationRegistry>()
+ .start(&project.id, &active_session_id, &active_run_id);
+ let result = runtime
+ .run_once_with_cancel(request, Some(cancellation))
+ .await;
+ app.state::<agent::cancel::AgentCancellationRegistry>()
+ .finish(&project.id, &active_session_id, &active_run_id);
+ let response = result?;
+ if persist_session {
+ app.state::<agent::session::AgentSessionStore>()
+ .append_turn(
+ &project.path,
+ &project.id,
+ &response.session_id,
+ &user_message,
+ &response.message,
+ );
+ }
+ Ok(response)
+}
+
+#[tauri::command]
+fn agent_cancel_turn(
+ app: tauri::AppHandle,
+ project_id: String,
+ session_id: String,
+ run_id: Option<String>,
+) -> Result<bool, String> {
+ let project = resolve_agent_project(&app, &project_id)?;
+ Ok(app
+ .state::<agent::cancel::AgentCancellationRegistry>()
+ .cancel(&project.id, &session_id, run_id.as_deref()))
+}
+
+#[tauri::command]
+async fn agent_start_turn_stream(
+ app: tauri::AppHandle,
+ project_id: String,
+ mut request: agent::AgentChatRequest,
+) -> Result<String, String> {
+ let project = resolve_agent_project(&app, &project_id)?;
+ if request
+ .session_id
+ .as_deref()
+ .map(str::trim)
+ .unwrap_or("")
+ .is_empty()
+ {
+ request.session_id = Some(format!("ui_{}", Uuid::new_v4()));
+ }
+ let active_session_id = request.session_id.clone().unwrap_or_default();
+ if request
+ .run_id
+ .as_deref()
+ .map(str::trim)
+ .unwrap_or("")
+ .is_empty()
+ {
+ request.run_id = Some(format!("run_{}", Uuid::new_v4()));
+ }
+ let active_run_id = request.run_id.clone().unwrap_or_default();
+ if request.history.is_empty() {
+ request.history = app
+ .state::<agent::session::AgentSessionStore>()
+ .recent_messages(&project.path, &active_session_id, 12)
+ .into_iter()
+ .map(|message| agent::types::AgentConversationMessage {
+ role: message.role,
+ content: message.content,
+ })
+ .collect();
+ }
+ let runtime_config = load_agent_runtime_config(&app);
+ let runtime = agent::AgentRuntime::new(
+ project.id.clone(),
+ project.path.clone(),
+ runtime_config.embedding,
+ runtime_config.llm,
+ runtime_config.web_search,
+ runtime_config.anytxt,
+ );
+ let app_for_task = app.clone();
+ let project_for_task = project.clone();
+ let session_for_task = active_session_id.clone();
+ let run_for_task = active_run_id.clone();
+ let user_message = request.message.clone();
+ let persist_session = request.persist_session;
+ let cancellation = app
+ .state::<agent::cancel::AgentCancellationRegistry>()
+ .start(&project.id, &active_session_id, &active_run_id);
+ tauri::async_runtime::spawn(async move {
+ let emit_app = app_for_task.clone();
+ let emit_session = session_for_task.clone();
+ let emit_run = run_for_task.clone();
+ let sink: agent::runtime::AgentEventSink = std::sync::Arc::new(move |event| {
+ let _ = emit_app.emit(
+ "agent-event",
+ serde_json::json!({
+ "sessionId": emit_session.clone(),
+ "runId": emit_run.clone(),
+ "event": event,
+ }),
+ );
+ });
+ let result = runtime
+ .run_once_with_cancel_and_events(request, Some(cancellation), Some(sink))
+ .await;
+ app_for_task
+ .state::<agent::cancel::AgentCancellationRegistry>()
+ .finish(&project_for_task.id, &session_for_task, &run_for_task);
+ match result {
+ Ok(response) => {
+ if persist_session {
+ app_for_task
+ .state::<agent::session::AgentSessionStore>()
+ .append_turn(
+ &project_for_task.path,
+ &project_for_task.id,
+ &response.session_id,
+ &user_message,
+ &response.message,
+ );
+ }
+ }
+ Err(err) => {
+ let _ = app_for_task.emit(
+ "agent-event",
+ serde_json::json!({
+ "sessionId": session_for_task,
+ "runId": run_for_task,
+ "event": { "type": "error", "message": err },
+ }),
+ );
+ }
+ }
+ });
+ Ok(active_session_id)
+}
+
+#[tauri::command]
+fn agent_get_session(
+ app: tauri::AppHandle,
+ project_id: String,
+ session_id: String,
+ limit: Option<usize>,
+) -> Result<Vec<agent::session::AgentSessionMessage>, String> {
+ let project = resolve_agent_project(&app, &project_id)?;
+ Ok(app
+ .state::<agent::session::AgentSessionStore>()
+ .recent_messages(
+ &project.path,
+ &session_id,
+ limit.unwrap_or(40).clamp(1, 200),
+ ))
+}
+
+#[tauri::command]
+fn agent_list_sessions(
+ app: tauri::AppHandle,
+ project_id: String,
+) -> Result<Vec<agent::session::AgentSession>, String> {
+ let project = resolve_agent_project(&app, &project_id)?;
+ Ok(app
+ .state::<agent::session::AgentSessionStore>()
+ .list_sessions(&project.path))
+}
+
#[tauri::command]
fn mcp_server_entry_path(app: tauri::AppHandle) -> Result<String, String> {
run_guarded("mcp_server_entry_path", || {
@@ -83,6 +323,176 @@ fn mcp_server_entry_path(app: tauri::AppHandle) -> Result<String, String> {
})
}
+fn resolve_agent_project(
+ app: &tauri::AppHandle,
+ project_id: &str,
+) -> Result<AgentProjectEntry, String> {
+ let decoded = percent_decode(project_id);
+ let wants_current = decoded.eq_ignore_ascii_case("current");
+ load_agent_projects(app)
+ .into_iter()
+ .find(|project| {
+ project.id == decoded
+ || project_path_matches(&project.path, &decoded)
+ || (wants_current && project.current)
+ })
+ .ok_or_else(|| format!("Unknown project: {decoded}"))
+}
+
+fn load_agent_projects(app: &tauri::AppHandle) -> Vec<AgentProjectEntry> {
+ let current = normalize_path(&clip_server::current_project_path());
+ let mut projects = Vec::new();
+ if let Some(parsed) = load_agent_app_state(app) {
+ if let Some(registry) = parsed.get("projectRegistry").and_then(Value::as_object) {
+ for (id, value) in registry {
+ let path = value.get("path").and_then(Value::as_str).unwrap_or("");
+ if path.is_empty() {
+ continue;
+ }
+ let path = normalize_path(path);
+ let name = value
+ .get("name")
+ .and_then(Value::as_str)
+ .map(ToOwned::to_owned)
+ .unwrap_or_else(|| project_name_from_path(&path));
+ projects.push(AgentProjectEntry {
+ id: id.clone(),
+ name,
+ current: path == current,
+ path,
+ });
+ }
+ }
+ if let Some(recents) = parsed.get("recentProjects").and_then(Value::as_array) {
+ for value in recents {
+ let path = value.get("path").and_then(Value::as_str).unwrap_or("");
+ if path.is_empty() {
+ continue;
+ }
+ let path = normalize_path(path);
+ if projects.iter().any(|project| project.path == path) {
+ continue;
+ }
+ let name = value
+ .get("name")
+ .and_then(Value::as_str)
+ .map(ToOwned::to_owned)
+ .unwrap_or_else(|| project_name_from_path(&path));
+ projects.push(AgentProjectEntry {
+ id: read_project_id(&path).unwrap_or_else(|| path.clone()),
+ name,
+ current: path == current,
+ path,
+ });
+ }
+ }
+ }
+ if !current.is_empty() && !projects.iter().any(|project| project.path == current) {
+ projects.push(AgentProjectEntry {
+ id: read_project_id(&current).unwrap_or_else(|| current.clone()),
+ name: project_name_from_path(&current),
+ current: true,
+ path: current,
+ });
+ }
+ projects
+}
+
+fn load_agent_app_state(app: &tauri::AppHandle) -> Option<Value> {
+ let path = app.path().app_data_dir().ok()?.join("app-state.json");
+ let raw = std::fs::read_to_string(path).ok()?;
+ serde_json::from_str(&raw).ok()
+}
+
+fn load_agent_runtime_config(app: &tauri::AppHandle) -> AgentRuntimeConfig {
+ let Some(parsed) = load_agent_app_state(app) else {
+ return AgentRuntimeConfig::default();
+ };
+ AgentRuntimeConfig {
+ embedding: parsed
+ .get("embeddingConfig")
+ .cloned()
+ .and_then(|value| serde_json::from_value(value).ok()),
+ llm: parsed
+ .get("llmConfig")
+ .cloned()
+ .and_then(|value| serde_json::from_value(value).ok()),
+ web_search: parsed
+ .get("searchApiConfig")
+ .cloned()
+ .and_then(|value| serde_json::from_value(value).ok()),
+ anytxt: parsed
+ .get("searchApiConfig")
+ .and_then(|value| value.get("anyTxt"))
+ .cloned()
+ .and_then(|value| serde_json::from_value(value).ok()),
+ }
+}
+
+fn read_project_id(path: &str) -> Option<String> {
+ let raw = std::fs::read_to_string(
+ std::path::Path::new(path)
+ .join(".llm-wiki")
+ .join("project.json"),
+ )
+ .ok()?;
+ serde_json::from_str::<Value>(&raw)
+ .ok()?
+ .get("id")
+ .and_then(Value::as_str)
+ .map(ToOwned::to_owned)
+}
+
+fn project_name_from_path(path: &str) -> String {
+ std::path::Path::new(path)
+ .file_name()
+ .and_then(|s| s.to_str())
+ .filter(|name| !name.is_empty())
+ .unwrap_or("Project")
+ .to_string()
+}
+
+fn project_path_matches(stored_path: &str, candidate: &str) -> bool {
+ let stored = normalize_path(stored_path);
+ let candidate = normalize_path(candidate);
+ if cfg!(windows) {
+ stored.eq_ignore_ascii_case(&candidate)
+ } else {
+ stored == candidate
+ }
+}
+
+fn normalize_path(path: &str) -> String {
+ path.replace('\\', "/").trim_end_matches('/').to_string()
+}
+
+fn percent_decode(input: &str) -> String {
+ let bytes = input.as_bytes();
+ let mut out = Vec::with_capacity(bytes.len());
+ let mut i = 0;
+ while i < bytes.len() {
+ if bytes[i] == b'%' && i + 2 < bytes.len() {
+ if let (Some(hi), Some(lo)) = (hex_val(bytes[i + 1]), hex_val(bytes[i + 2])) {
+ out.push((hi << 4) | lo);
+ i += 3;
+ continue;
+ }
+ }
+ out.push(bytes[i]);
+ i += 1;
+ }
+ String::from_utf8(out).unwrap_or_else(|_| input.to_string())
+}
+
+fn hex_val(b: u8) -> Option<u8> {
+ match b {
+ b'0'..=b'9' => Some(b - b'0'),
+ b'a'..=b'f' => Some(b - b'a' + 10),
+ b'A'..=b'F' => Some(b - b'A' + 10),
+ _ => None,
+ }
+}
+
/// Apply a proxy configuration to the process env immediately, so the
/// next outbound HTTP request picks it up without needing the user to
/// restart the app. tauri-plugin-http builds a fresh
@@ -180,6 +590,8 @@ pub fn run() {
app.manage(commands::claude_cli::ClaudeCliState::default());
app.manage(commands::codex_cli::CodexCliState::default());
app.manage(commands::file_sync::FileSyncState::default());
+ app.manage(agent::session::AgentSessionStore::default());
+ app.manage(agent::cancel::AgentCancellationRegistry::default());
app.manage(CloseBehaviorState(Mutex::new("minimize".to_string())));
app.manage(TrayAvailabilityState(Mutex::new(false)));
// Start the API before optional desktop integrations so the
@@ -227,6 +639,11 @@ pub fn run() {
clip_server_status,
api_server_status,
api_server_reload_config,
+ agent_start_turn,
+ agent_start_turn_stream,
+ agent_cancel_turn,
+ agent_get_session,
+ agent_list_sessions,
mcp_server_entry_path,
commands::vectorstore::vector_upsert,
commands::vectorstore::vector_search,
diff --git a/src/components/chat/chat-input.tsx b/src/components/chat/chat-input.tsx
index 9b2995e3..4e999eb8 100644
--- a/src/components/chat/chat-input.tsx
+++ b/src/components/chat/chat-input.tsx
@@ -5,7 +5,7 @@ import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"
import { isImeComposing } from "@/lib/keyboard-utils"
import type { MessageImage } from "@/stores/chat-store"
-import type { ChatAgentMode } from "@/lib/chat-agent"
+import type { ChatAgentMode } from "@/lib/chat-agent-types"
import {
MAX_IMAGE_BYTES,
MAX_IMAGE_MB,
diff --git a/src/components/chat/chat-message.tsx b/src/components/chat/chat-message.tsx
index 718a99bb..ff006932 100644
--- a/src/components/chat/chat-message.tsx
+++ b/src/components/chat/chat-message.tsx
@@ -30,7 +30,7 @@ import { getHtmlLang, getTextDirection } from "@/lib/language-metadata"
import { MermaidDiagram, unwrapMermaidPre } from "@/components/mermaid-diagram"
import { inferWikiTypeFromPath } from "@/lib/wiki-page-types"
import { cleanAssistantContentForWikiSave, titleFromCleanAssistantContent } from "@/lib/chat-save-to-wiki"
-import type { ChatAgentEvent, ChatAgentEventStage, ChatAgentStep } from "@/lib/chat-agent"
+import type { ChatAgentEvent, ChatAgentEventStage, ChatAgentStep } from "@/lib/chat-agent-types"
import { filterRawSourceTree } from "@/lib/source-filter"
import { refreshProjectFileTree } from "@/lib/project-file-tree-refresh"
diff --git a/src/components/chat/chat-panel.tsx b/src/components/chat/chat-panel.tsx
index dc23b5e6..aab5cec1 100644
--- a/src/components/chat/chat-panel.tsx
+++ b/src/components/chat/chat-panel.tsx
@@ -1,5 +1,7 @@
import { useRef, useEffect, useCallback, useState } from "react"
import { useTranslation } from "react-i18next"
+import { invoke } from "@tauri-apps/api/core"
+import { listen } from "@tauri-apps/api/event"
import { BookOpen, Plus, Trash2, MessageSquare, X } from "lucide-react"
import { Button } from "@/components/ui/button"
import { ChatMessage, StreamingMessage, useSourceFiles, type ChatReferencePreview } from "./chat-message"
@@ -12,7 +14,8 @@ import { executeIngestWrites } from "@/lib/ingest"
import { deleteFile } from "@/commands/fs"
import { getFileName, normalizePath } from "@/lib/path-utils"
import { hasConfiguredAnyTxt } from "@/lib/anytxt-search"
-import { buildChatAgentMessages, type ChatAgentEvent } from "@/lib/chat-agent"
+import type { ChatAgentEvent } from "@/lib/chat-agent-types"
+import type { ChatMessage as LlmChatMessage, ContentBlock } from "@/lib/llm-client"
import { FilePreview } from "@/components/editor/file-preview"
import { WikiReader } from "@/components/editor/wiki-reader"
import { FrontmatterPanel } from "@/components/editor/frontmatter-panel"
@@ -20,6 +23,43 @@ import { parseFrontmatter } from "@/lib/frontmatter"
import { getFileCategory } from "@/lib/file-types"
import { refreshProjectFileTree } from "@/lib/project-file-tree-refresh"
+interface BackendAgentReference {
+ title: string
+ path: string
+ kind: string
+ snippet?: string
+ score?: number
+}
+
+interface BackendAgentToolEvent {
+ tool: string
+ status: string
+ detail?: string
+}
+
+interface BackendAgentEventPayload {
+ sessionId: string
+ runId?: string
+ event: {
+ type: string
+ text?: string
+ tool?: string
+ input?: string
+ output?: string
+ message?: string
+ reference?: BackendAgentReference
+ sessionId?: string
+ }
+}
+
+interface BackendAgentResponse {
+ sessionId: string
+ mode?: string
+ message: string | { role?: string; content?: string }
+ references?: BackendAgentReference[]
+ toolEvents?: BackendAgentToolEvent[]
+}
+
// Store the page mapping from the last query so SourceFilesBar can show which pages were cited
export let lastQueryPages: { title: string; path: string }[] = []
@@ -124,6 +164,111 @@ function ConversationSidebar() {
)
}
+function backendReferenceToMessageReference(ref: BackendAgentReference): MessageReference {
+ const isWiki = ref.kind === "wiki" || ref.path.startsWith("wiki/")
+ const isWeb = ref.kind === "web" || /^https?:\/\//i.test(ref.path)
+ const source =
+ ref.kind === "anytxt" ? "AnyTXT"
+ : ref.kind === "web" ? "Web"
+ : ref.kind === "source" ? "Source"
+ : ref.kind === "graph" ? "Graph"
+ : undefined
+ return {
+ title: ref.title,
+ path: ref.path,
+ kind: isWiki ? "wiki" : "external",
+ source,
+ url: isWeb ? ref.path : undefined,
+ snippet: ref.snippet,
+ }
+}
+
+function backendToolToAgentStep(event: BackendAgentToolEvent, index: number) {
+ if (event.tool === "agent.plan_tools") {
+ return {
+ id: `backend-${index}-${event.tool}-${event.status}`,
+ type: "routing" as const,
+ message: event.detail ?? event.tool,
+ status: event.status === "failed" ? "error" as const : "success" as const,
+ }
+ }
+ if (event.tool === "llm.generate") {
+ return {
+ id: `backend-${index}-${event.tool}-${event.status}`,
+ type: "final" as const,
+ message: event.detail ?? event.tool,
+ status: event.status === "failed" ? "error" as const
+ : event.status === "started" ? "running" as const
+ : "success" as const,
+ }
+ }
+ const tool = normalizeBackendToolName(event.tool)
+ return {
+ id: `backend-${index}-${event.tool}-${event.status}`,
+ type: event.status === "started" ? "tool_call" as const : "tool_result" as const,
+ tool,
+ message: event.detail ?? event.tool,
+ status: event.status === "failed" ? "error" as const
+ : event.status === "available" ? "skipped" as const
+ : event.status === "started" ? "running" as const
+ : "success" as const,
+ }
+}
+
+function normalizeBackendToolName(tool: string) {
+ const normalized = tool.split(".").join("_")
+ if (normalized === "wiki_search") return "wiki_search" as const
+ if (normalized === "wiki_read_page") return "project_file_read" as const
+ if (normalized === "source_search") return "project_file_read" as const
+ if (normalized === "graph_search") return "graph_search" as const
+ if (normalized === "web_search") return "web_search" as const
+ if (normalized === "anytxt_search") return "anytxt_search" as const
+ if (normalized === "deep_research_run") return "project_file_read" as const
+ return "unknown_tool" as const
+}
+
+function backendToolToAgentEvent(event: BackendAgentToolEvent): ChatAgentEvent {
+ if (event.tool === "agent.plan_tools") {
+ return {
+ stage: "routing",
+ message: event.detail ?? event.tool,
+ status: event.status === "failed" ? "error" : "success",
+ }
+ }
+ if (event.tool === "llm.generate") {
+ return {
+ stage: "writing",
+ message: event.detail ?? event.tool,
+ status: event.status === "failed" ? "error"
+ : event.status === "started" ? "running"
+ : "success",
+ }
+ }
+ const tool = normalizeBackendToolName(event.tool)
+ const stage =
+ tool === "web_search" ? "searching_web"
+ : tool === "anytxt_search" ? "searching_anytxt"
+ : tool === "graph_search" ? "searching_graph"
+ : tool === "project_file_read" ? "reading_context"
+ : tool === "wiki_search" ? "searching_wiki"
+ : event.status === "started" ? "tool_call"
+ : "tool_result"
+ return {
+ stage,
+ tool,
+ message: event.detail ?? event.tool,
+ status: event.status === "failed" ? "error"
+ : event.status === "started" ? "running"
+ : event.status === "available" ? "skipped"
+ : "success",
+ }
+}
+
+function backendResponseText(response: BackendAgentResponse): string {
+ if (typeof response.message === "string") return response.message
+ return response.message?.content ?? ""
+}
+
export function ChatPanel() {
const { t } = useTranslation()
useSourceFiles() // Keep source file cache warm
@@ -158,6 +303,8 @@ export function ChatPanel() {
const imageInputAvailable = supportsImageInput(llmConfig)
const abortRef = useRef<AbortController | null>(null)
+ const activeRunSessionIdRef = useRef<string | null>(null)
+ const activeRunIdRef = useRef<string | null>(null)
const runIdRef = useRef(0)
const scrollContainerRef = useRef<HTMLDivElement>(null)
const bottomRef = useRef<HTMLDivElement>(null)
@@ -203,34 +350,224 @@ export function ChatPanel() {
setAgentEvents([])
let finalized = false
const runId = ++runIdRef.current
+ const backendRunId = `ui-${Date.now()}-${runId}`
try {
const controller = new AbortController()
abortRef.current = controller
+ activeRunSessionIdRef.current = convId
+ activeRunIdRef.current = backendRunId
const isCurrentRun = () => runIdRef.current === runId && !controller.signal.aborted
+ const useBackendAgent =
+ llmConfig.provider !== "claude-code" &&
+ llmConfig.provider !== "codex-cli"
+
+ if (useBackendAgent) {
+ setAgentEvents([
+ {
+ stage: "routing",
+ status: "running",
+ message: t("chat.agent.routing"),
+ },
+ ])
+ const activeConvMessages = useChatStore.getState().getActiveMessages()
+ .filter((m) => m.role === "user" || m.role === "assistant")
+ .slice(0, -1)
+ .slice(-maxHistoryMessages)
+ .map((m) => ({ role: m.role, content: m.content }))
+ let accumulated = ""
+ const references: MessageReference[] = []
+ const backendEvents: BackendAgentToolEvent[] = []
+ const seenRefs = new Set<string>()
+ let streamFinished = false
+ let streamUnlisten: (() => void) | null = null
+ let resolveStream: (() => void) | null = null
+ let rejectStream: ((err: Error) => void) | null = null
+ const streamDone = new Promise<void>((resolve, reject) => {
+ resolveStream = resolve
+ rejectStream = reject
+ })
+ void streamDone.catch(() => {})
+ const timeout = window.setTimeout(() => {
+ if (!streamFinished) {
+ streamFinished = true
+ rejectStream?.(new Error("Agent stream timed out"))
+ }
+ }, 240_000)
+ streamUnlisten = await listen<BackendAgentEventPayload>("agent-event", (event) => {
+ const payload = event.payload
+ if (payload.sessionId !== convId || payload.runId !== backendRunId || !isCurrentRun()) return
+ const agentEvent = payload.event
+ if (agentEvent.type === "done") {
+ if (!streamFinished) {
+ streamFinished = true
+ window.clearTimeout(timeout)
+ resolveStream?.()
+ }
+ return
+ }
+ if (agentEvent.type === "messageDelta" && agentEvent.text) {
+ accumulated += agentEvent.text
+ appendStreamToken(agentEvent.text)
+ return
+ }
+ if (agentEvent.type === "referenceAdded" && agentEvent.reference) {
+ const ref = backendReferenceToMessageReference(agentEvent.reference)
+ const key = `${ref.kind ?? "wiki"}:${ref.url ?? ref.path}`.toLowerCase()
+ if (!seenRefs.has(key)) {
+ seenRefs.add(key)
+ references.push(ref)
+ }
+ return
+ }
+ if (agentEvent.type === "toolStart" && agentEvent.tool) {
+ const toolEvent: BackendAgentToolEvent = {
+ tool: agentEvent.tool,
+ status: "started",
+ detail: agentEvent.input,
+ }
+ backendEvents.push(toolEvent)
+ setAgentEvents((prev) => [...prev, backendToolToAgentEvent(toolEvent)].slice(-6))
+ return
+ }
+ if (agentEvent.type === "toolEnd" && agentEvent.tool) {
+ const failed = typeof agentEvent.output === "string" && agentEvent.output.startsWith("failed:")
+ const toolEvent: BackendAgentToolEvent = {
+ tool: agentEvent.tool,
+ status: failed ? "failed" : "completed",
+ detail: agentEvent.output,
+ }
+ backendEvents.push(toolEvent)
+ setAgentEvents((prev) => [...prev, backendToolToAgentEvent(toolEvent)].slice(-6))
+ return
+ }
+ if (agentEvent.type === "error" && agentEvent.message) {
+ const toolEvent: BackendAgentToolEvent = {
+ tool: "agent",
+ status: "failed",
+ detail: agentEvent.message,
+ }
+ backendEvents.push(toolEvent)
+ setAgentEvents((prev) => [...prev, backendToolToAgentEvent(toolEvent)].slice(-6))
+ if (!streamFinished) {
+ streamFinished = true
+ window.clearTimeout(timeout)
+ rejectStream?.(new Error(agentEvent.message))
+ }
+ }
+ })
+ try {
+ await invoke<string>("agent_start_turn_stream", {
+ projectId: project?.id ?? "current",
+ request: {
+ message: text,
+ sessionId: convId,
+ runId: backendRunId,
+ mode: sendOptions.agentMode,
+ stream: true,
+ tools: {
+ wiki: true,
+ web: sendOptions.useWebSearch,
+ anytxt: sendOptions.useAnyTxtSearch,
+ },
+ topK: sendOptions.agentMode === "deep" ? 8 : 5,
+ includeContent: sendOptions.agentMode === "deep",
+ history: activeConvMessages,
+ images: images.map((image) => ({
+ mediaType: image.mediaType,
+ dataBase64: image.dataBase64,
+ })),
+ },
+ })
+ await streamDone
+ } finally {
+ window.clearTimeout(timeout)
+ streamUnlisten?.()
+ }
+ if (!isCurrentRun()) return
+ lastQueryPages = references
+ .filter((ref) => ref.kind === "wiki")
+ .map((ref) => ({ title: ref.title, path: ref.path }))
+ const steps = backendEvents.map(backendToolToAgentStep)
+ finalized = true
+ finalizeStream(accumulated, references, steps)
+ setAgentEvents([])
+ abortRef.current = null
+ activeRunSessionIdRef.current = null
+ activeRunIdRef.current = null
+ return
+ }
+
const activeConvMessages = useChatStore.getState().getActiveMessages()
.filter((m) => m.role === "user" || m.role === "assistant")
.slice(-maxHistoryMessages)
- const historyMessages = chatMessagesToLLM(activeConvMessages)
- const retrievalHistory = collectRecentRetrievalHistory(activeConvMessages)
- const agentResult = await buildChatAgentMessages({
- project: project ? { name: project.name, path: project.path } : null,
- llmConfig,
- searchApiConfig,
- text,
- historyMessages,
- retrievalHistory,
- dataVersion: useWikiStore.getState().dataVersion,
- options: sendOptions,
- signal: controller.signal,
- onEvent: (event) => {
- if (!isCurrentRun()) return
- setAgentEvents((prev) => [...prev, event].slice(-6))
+ const priorMessages = activeConvMessages.slice(0, -1)
+ const backendResponse = await invoke<BackendAgentResponse>("agent_start_turn", {
+ projectId: project?.id ?? "current",
+ request: {
+ message: text,
+ sessionId: convId,
+ runId: backendRunId,
+ persistSession: false,
+ mode: sendOptions.agentMode,
+ tools: {
+ wiki: true,
+ web: sendOptions.useWebSearch,
+ anytxt: sendOptions.useAnyTxtSearch,
+ },
+ topK: sendOptions.agentMode === "deep" ? 8 : 5,
+ includeContent: sendOptions.agentMode === "deep",
+ history: chatMessagesToLLM(priorMessages).map((m) => ({
+ role: m.role,
+ content: typeof m.content === "string"
+ ? m.content
+ : m.content
+ .filter((block) => block.type === "text")
+ .map((block) => block.text)
+ .join("\n"),
+ })),
+ images: images.map((image) => ({
+ mediaType: image.mediaType,
+ dataBase64: image.dataBase64,
+ })),
},
})
if (!isCurrentRun()) return
- lastQueryPages = agentResult.queryPages
+
+ const backendReferences = (backendResponse.references ?? []).map(backendReferenceToMessageReference)
+ const backendSteps = (backendResponse.toolEvents ?? []).map(backendToolToAgentStep)
+ const backendEvents = (backendResponse.toolEvents ?? []).map(backendToolToAgentEvent)
+ setAgentEvents(backendEvents.slice(-6))
+ lastQueryPages = backendReferences
+ .filter((ref) => ref.kind === "wiki")
+ .map((ref) => ({ title: ref.title, path: ref.path }))
+
+ const contextText = [
+ "You have access to the current LLM Wiki project context below. Use it as retrieved evidence when it is relevant.",
+ "",
+ backendResponseText(backendResponse),
+ "",
+ `User request: ${text}`,
+ ].join("\n")
+ const userContent: string | ContentBlock[] = images.length > 0
+ ? [
+ { type: "text", text: contextText },
+ ...images.map((image) => ({
+ type: "image" as const,
+ mediaType: image.mediaType,
+ dataBase64: image.dataBase64,
+ })),
+ ]
+ : contextText
+ const finalMessages: LlmChatMessage[] = [
+ {
+ role: "system",
+ content: "Answer using the provided LLM Wiki context and references. If the context is insufficient, say what is missing instead of inventing details.",
+ },
+ ...chatMessagesToLLM(priorMessages),
+ { role: "user", content: userContent },
+ ]
let accumulated = ""
let thinkingOpen = false
@@ -257,7 +594,7 @@ export function ChatPanel() {
let streamError: Error | null = null
await streamChat(
llmConfig,
- agentResult.messages,
+ finalMessages,
{
onToken: (token) => {
if (!isCurrentRun()) return
@@ -298,9 +635,11 @@ export function ChatPanel() {
if (!isCurrentRun()) return
closeReasoning()
finalized = true
- finalizeStream(accumulated, agentResult.references, agentResult.steps)
+ finalizeStream(accumulated, backendReferences, backendSteps)
setAgentEvents([])
abortRef.current = null
+ activeRunSessionIdRef.current = null
+ activeRunIdRef.current = null
// save-worthy detection removed — user has direct "Save to Wiki" button on each message
} catch (err) {
if (!finalized) {
@@ -308,6 +647,8 @@ export function ChatPanel() {
setStreaming(false)
setAgentEvents([])
abortRef.current = null
+ activeRunSessionIdRef.current = null
+ activeRunIdRef.current = null
return
}
const message = err instanceof Error ? err.message : String(err)
@@ -315,18 +656,31 @@ export function ChatPanel() {
setAgentEvents([])
}
abortRef.current = null
+ activeRunSessionIdRef.current = null
+ activeRunIdRef.current = null
}
},
- [project, llmConfig, searchApiConfig, addMessage, setStreaming, appendStreamToken, finalizeStream, createConversation, maxHistoryMessages],
+ [project, llmConfig, searchApiConfig, addMessage, setStreaming, appendStreamToken, finalizeStream, createConversation, maxHistoryMessages, t],
)
const handleStop = useCallback(() => {
runIdRef.current += 1
+ const sessionId = activeRunSessionIdRef.current
+ const backendRunId = activeRunIdRef.current
+ if (sessionId) {
+ void invoke("agent_cancel_turn", {
+ projectId: project?.id ?? "current",
+ sessionId,
+ runId: backendRunId ?? undefined,
+ }).catch(() => {})
+ }
abortRef.current?.abort()
abortRef.current = null
+ activeRunSessionIdRef.current = null
+ activeRunIdRef.current = null
setStreaming(false)
setAgentEvents([])
- }, [setStreaming])
+ }, [project, setStreaming])
const handleRegenerate = useCallback(async () => {
if (isStreaming) return
@@ -596,19 +950,3 @@ function isAbortLikeError(err: unknown): boolean {
if (!(err instanceof Error)) return false
return err.name === "AbortError" || /abort|cancel/i.test(err.message)
}
-
-function collectRecentRetrievalHistory(messages: ReturnType<typeof useChatStore.getState>["messages"]): MessageReference[] {
- const refs: MessageReference[] = []
- const seen = new Set<string>()
- for (const msg of [...messages].reverse()) {
- if (msg.role !== "assistant" || !msg.references) continue
- for (const ref of msg.references) {
- const key = `${ref.kind ?? "wiki"}:${ref.url ?? ref.path}`.toLowerCase()
- if (seen.has(key)) continue
- seen.add(key)
- refs.push(ref)
- if (refs.length >= 10) return refs
- }
- }
- return refs
-}
diff --git a/src/components/layout/app-layout-visibility.test.ts b/src/components/layout/app-layout-visibility.test.ts
index 65654627..3045a847 100644
--- a/src/components/layout/app-layout-visibility.test.ts
+++ b/src/components/layout/app-layout-visibility.test.ts
@@ -2,9 +2,11 @@ import { describe, expect, it } from "vitest"
import { getAppLayoutVisibility } from "./app-layout-visibility"
describe("getAppLayoutVisibility", () => {
- it("keeps chat research panel hidden while using the standard project side panel", () => {
+ it("keeps chat standalone without project side panels", () => {
+ // Chat owns its conversation list and reference preview area. It must not
+ // also inherit the project knowledge/file panel used by workspace views.
expect(getAppLayoutVisibility("chat", true)).toEqual({
- showLeftPanel: true,
+ showLeftPanel: false,
hasRightPanel: false,
})
})
diff --git a/src/components/layout/app-layout-visibility.ts b/src/components/layout/app-layout-visibility.ts
index 97078b84..d3f3e39e 100644
--- a/src/components/layout/app-layout-visibility.ts
+++ b/src/components/layout/app-layout-visibility.ts
@@ -7,7 +7,7 @@ export function getAppLayoutVisibility(
): { showLeftPanel: boolean; hasRightPanel: boolean } {
const isStandalone = isStandaloneView(activeView)
return {
- showLeftPanel: activeView !== "settings",
+ showLeftPanel: !isStandalone,
hasRightPanel: !isStandalone && researchPanelOpen,
}
}
diff --git a/src/lib/chat-agent-types.ts b/src/lib/chat-agent-types.ts
new file mode 100644
index 00000000..1f5a59a3
--- /dev/null
+++ b/src/lib/chat-agent-types.ts
@@ -0,0 +1,51 @@
+/**
+ * UI-facing Agent metadata types.
+ *
+ * The Agent execution engine lives in Rust (`src-tauri/src/agent`). Keep this
+ * file intentionally limited to display/persistence shapes used by the React UI.
+ * Do not reintroduce routing, retrieval, tool execution, or prompt-building
+ * logic here; those belong in the Rust Agent runtime so API, MCP, and UI callers
+ * share one backend behavior.
+ */
+
+export type ChatAgentEventStage =
+ | "understanding"
+ | "routing"
+ | "tool_call"
+ | "tool_result"
+ | "searching_wiki"
+ | "searching_graph"
+ | "searching_web"
+ | "searching_anytxt"
+ | "reading_context"
+ | "writing"
+
+export interface ChatAgentEvent {
+ stage: ChatAgentEventStage
+ query?: string
+ tool?: ChatAgentToolName
+ message?: string
+ count?: number
+ status?: "running" | "success" | "error" | "skipped"
+}
+
+export type ChatAgentMode = "fast" | "standard" | "deep" | "local_first"
+
+export type ChatAgentToolName =
+ | "project_files"
+ | "project_file_read"
+ | "wiki_search"
+ | "graph_search"
+ | "web_search"
+ | "anytxt_search"
+ | "unknown_tool"
+
+export interface ChatAgentStep {
+ id: string
+ type: "understanding" | "routing" | "tool_call" | "tool_result" | "final"
+ tool?: ChatAgentToolName
+ query?: string
+ message?: string
+ count?: number
+ status?: "running" | "success" | "error" | "skipped"
+}
diff --git a/src/lib/chat-agent.test.ts b/src/lib/chat-agent.test.ts
deleted file mode 100644
index ed780a14..00000000
--- a/src/lib/chat-agent.test.ts
+++ /dev/null
@@ -1,714 +0,0 @@
-import { describe, expect, it, vi } from "vitest"
-import {
- buildChatAgentMessages,
- getChatAgentTools,
- parseDecision,
- parseUnderstanding,
- shouldBypassAgentPlanner,
- type ChatAgentDeps,
-} from "./chat-agent"
-import type { LlmConfig, SearchApiConfig } from "@/stores/wiki-store"
-import type { ChatMessage as LLMMessage } from "@/lib/llm-client"
-
-vi.mock("@/commands/fs", () => ({
- listDirectory: vi.fn(async (path: string) => {
- if (path.endsWith("/wiki")) {
- return [
- { name: "concepts", path: `${path}/concepts`, is_dir: true, children: [
- { name: "attention.md", path: `${path}/concepts/attention.md`, is_dir: false },
- { name: "transformer.md", path: `${path}/concepts/transformer.md`, is_dir: false },
- ] },
- { name: "index.md", path: `${path}/index.md`, is_dir: false },
- ]
- }
- if (path.endsWith("/raw/sources")) {
- return [
- { name: "paper.pdf", path: `${path}/paper.pdf`, is_dir: false },
- ]
- }
- return []
- }),
- readFile: vi.fn(async (path: string) => {
- if (path.endsWith("purpose.md")) {
- return "This wiki tracks transformer research."
- }
- if (path.endsWith("wiki/index.md")) {
- return "## Concepts\n- [[Attention]]\n- [[Transformer]]"
- }
- if (path.endsWith("wiki/overview.md")) {
- return "# Overview\n\nThis wiki covers transformer architecture, attention, and benchmark notes."
- }
- if (path.endsWith("attention.md")) {
- return "---\ntitle: Attention\ntype: concept\n---\n# Attention\n\nAttention lets models focus on relevant tokens."
- }
- if (path.endsWith("transformer.md")) {
- return "---\ntitle: Transformer\ntype: concept\n---\n# Transformer\n\nTransformers use attention layers."
- }
- if (path.endsWith("schema.md")) {
- return "# Schema"
- }
- return ""
- }),
-}))
-
-vi.mock("@/lib/graph-relevance", () => ({
- buildRetrievalGraph: vi.fn(async () => ({ nodes: new Map(), dataVersion: 1 })),
- getRelatedNodes: vi.fn(() => [
- {
- node: {
- id: "transformer",
- title: "Transformer",
- type: "concept",
- path: "/tmp/project/wiki/concepts/transformer.md",
- sources: [],
- outLinks: new Set(),
- inLinks: new Set(),
- },
- relevance: 3,
- },
- ]),
-}))
-
-const llmConfig: LlmConfig = {
- provider: "openai",
- apiKey: "test",
- model: "test-model",
- ollamaUrl: "",
- customEndpoint: "https://example.com/v1",
- maxContextSize: 128_000,
-}
-
-const searchApiConfig: SearchApiConfig = {
- provider: "none",
- apiKey: "",
-}
-
-describe("chat agent routing", () => {
- it("bypasses retrieval for greetings", () => {
- expect(shouldBypassAgentPlanner("你好")?.action).toBe("answer")
- })
-
- it("bypasses retrieval for short follow-up commands", () => {
- expect(shouldBypassAgentPlanner("继续")?.action).toBe("answer")
- expect(shouldBypassAgentPlanner("summarize the above")?.action).toBe("answer")
- })
-
- it("parses JSON decisions from model output", () => {
- expect(parseDecision('```json\n{"action":"graph_search","queries":["A B relationship"]}\n```', "fallback")).toEqual({
- action: "graph_search",
- queries: ["A B relationship"],
- answer: undefined,
- reason: undefined,
- })
- })
-
- it("falls back to wiki search when model routing output is malformed", () => {
- expect(parseDecision("not json", "attention")).toMatchObject({
- action: "wiki_search",
- queries: ["attention"],
- })
- })
-
- it("parses query understanding output", () => {
- expect(parseUnderstanding(
- '{"intent":"mixed","rewrittenQuery":"transformer benchmark","wikiQueries":["transformer"],"graphQueries":["attention transformer"],"externalQueries":["latest transformer benchmark"],"needsWiki":true,"needsGraph":true,"needsExternal":true,"isFollowUp":false,"reason":"needs local and current context"}',
- "fallback",
- { hasProject: true, webSearchEnabled: true, anyTxtSearchEnabled: false },
- )).toMatchObject({
- intent: "mixed",
- rewrittenQuery: "transformer benchmark",
- wikiQueries: ["transformer"],
- graphQueries: ["attention transformer"],
- externalQueries: ["latest transformer benchmark"],
- needsWiki: true,
- needsGraph: true,
- needsExternal: true,
- })
- })
-
- it("filters tool registry by available capabilities", () => {
- expect(getChatAgentTools({
- hasProject: false,
- webSearchEnabled: true,
- anyTxtSearchEnabled: false,
- mode: "standard",
- }).map((tool) => tool.name)).toEqual(["web_search"])
- expect(getChatAgentTools({
- hasProject: true,
- webSearchEnabled: false,
- anyTxtSearchEnabled: true,
- mode: "standard",
- }).map((tool) => tool.name)).toEqual([
- "project_files",
- "project_file_read",
- "wiki_search",
- "graph_search",
- "anytxt_search",
- ])
- expect(getChatAgentTools({
- hasProject: true,
- webSearchEnabled: true,
- anyTxtSearchEnabled: false,
- mode: "local_first",
- }).map((tool) => tool.name)).not.toContain("web_search")
- })
-
- it("does not call search tools for direct greetings", async () => {
- const deps: ChatAgentDeps = {
- searchWiki: vi.fn(),
- streamChat: vi.fn(),
- }
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig,
- text: "hello",
- historyMessages: [{ role: "user", content: "hello" }],
- dataVersion: 1,
- options: { useWebSearch: false, useAnyTxtSearch: false },
- deps,
- })
-
- expect(deps.searchWiki).not.toHaveBeenCalled()
- expect(deps.streamChat).not.toHaveBeenCalled()
- expect(result.references).toEqual([])
- expect(result.messages[0].content).toContain("Do not claim that you searched")
- })
-
- it("executes wiki search only after the planner chooses it", async () => {
- const searchWiki = vi.fn(async () => [
- {
- path: "/tmp/project/wiki/concepts/attention.md",
- title: "Attention",
- snippet: "Attention lets models focus.",
- titleMatch: true,
- score: 1,
- images: [],
- },
- ])
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- callbacks.onToken('{"action":"wiki_search","queries":["attention mechanism"],"reason":"needs local notes"}')
- callbacks.onDone()
- })
- const deps: ChatAgentDeps = { searchWiki, streamChat }
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig,
- text: "What do my notes say about attention?",
- historyMessages: [{ role: "user", content: "What do my notes say about attention?" }],
- dataVersion: 1,
- options: { useWebSearch: false, useAnyTxtSearch: false },
- deps,
- })
-
- expect(searchWiki).toHaveBeenCalledWith("/tmp/project", "attention mechanism")
- expect(result.references).toEqual([
- {
- title: "Attention",
- path: "/tmp/project/wiki/concepts/attention.md",
- kind: "wiki",
- },
- ])
- expect(String(result.messages[0].content)).toContain("## Retrieved Context")
- expect(String(result.messages[0].content)).toContain('<context id="1" source="wiki"')
- expect(String(result.messages[0].content)).toContain("Attention lets models focus on relevant tokens")
- expect(String(result.messages[0].content)).toContain("## Wiki Purpose")
- expect(String(result.messages[0].content)).toContain("This wiki tracks transformer research.")
- expect(String(result.messages[0].content)).toContain("## Wiki Overview")
- expect(String(result.messages[0].content)).toContain("This wiki covers transformer architecture")
- expect(String(result.messages[0].content)).toContain("## Wiki Index")
- expect(String(result.messages[result.messages.length - 1]?.content)).toContain("[REMINDER: Write prose in English")
- })
-
- it("emits detailed agent steps for tool calls and results", async () => {
- const searchWiki = vi.fn(async () => [
- {
- path: "/tmp/project/wiki/concepts/attention.md",
- title: "Attention",
- snippet: "Attention lets models focus.",
- titleMatch: true,
- score: 1,
- images: [],
- },
- ])
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- callbacks.onToken('{"action":"wiki_search","queries":["attention mechanism"],"reason":"needs local notes"}')
- callbacks.onDone()
- })
- const events: Array<{ stage: string; tool?: string; count?: number }> = []
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig,
- text: "What do my notes say about attention?",
- historyMessages: [{ role: "user", content: "What do my notes say about attention?" }],
- dataVersion: 1,
- options: { useWebSearch: false, useAnyTxtSearch: false },
- onEvent: (event) => events.push(event),
- deps: { searchWiki, streamChat },
- })
-
- expect(result.steps.map((step) => step.type)).toContain("understanding")
- expect(result.steps).toEqual(expect.arrayContaining([
- expect.objectContaining({ type: "tool_call", tool: "wiki_search", status: "running" }),
- expect.objectContaining({ type: "tool_result", tool: "wiki_search", status: "success", count: 1 }),
- ]))
- expect(events).toEqual(expect.arrayContaining([
- expect.objectContaining({ stage: "tool_call", tool: "wiki_search" }),
- expect.objectContaining({ stage: "tool_result", tool: "wiki_search", count: 1 }),
- ]))
- })
-
- it("disables reasoning for internal JSON controller calls", async () => {
- const streamChat = vi.fn(async (...args: unknown[]) => {
- const callbacks = args[2] as { onToken: (token: string) => void; onDone: () => void }
- callbacks.onToken('{"action":"wiki_search","queries":["attention mechanism"]}')
- callbacks.onDone()
- })
- const searchWiki = vi.fn(async () => [])
-
- await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig: { ...llmConfig, reasoning: { mode: "high" } },
- searchApiConfig,
- text: "What do my notes say about attention?",
- historyMessages: [{ role: "user", content: "What do my notes say about attention?" }],
- dataVersion: 1,
- options: { useWebSearch: false, useAnyTxtSearch: false },
- deps: { streamChat, searchWiki },
- })
-
- expect(streamChat).toHaveBeenCalled()
- for (const call of streamChat.mock.calls as unknown[][]) {
- expect(call[4]).toEqual(expect.objectContaining({ reasoning: { mode: "off" } }))
- }
- })
-
- it("can list project files through the project_files tool", async () => {
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- callbacks.onToken('{"action":"project_files","queries":["what files exist"]}')
- callbacks.onDone()
- })
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig,
- text: "What files are in this project?",
- historyMessages: [{ role: "user", content: "What files are in this project?" }],
- dataVersion: 1,
- options: { useWebSearch: false, useAnyTxtSearch: false, mode: "standard" },
- deps: { streamChat },
- })
-
- expect(result.steps).toEqual(expect.arrayContaining([
- expect.objectContaining({ type: "tool_call", tool: "project_files" }),
- expect.objectContaining({ type: "tool_result", tool: "project_files", count: 1 }),
- ]))
- expect(String(result.messages[0].content)).toContain("Project file listing")
- expect(String(result.messages[0].content)).toContain("wiki/concepts/attention.md")
- })
-
- it("can read a project text file by relative path", async () => {
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- callbacks.onToken('{"action":"project_file_read","queries":["wiki/concepts/attention.md"]}')
- callbacks.onDone()
- })
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig,
- text: "Read wiki/concepts/attention.md",
- historyMessages: [{ role: "user", content: "Read wiki/concepts/attention.md" }],
- dataVersion: 1,
- options: { useWebSearch: false, useAnyTxtSearch: false, mode: "standard" },
- deps: { streamChat },
- })
-
- expect(result.references).toEqual([
- {
- title: "attention.md",
- path: "/tmp/project/wiki/concepts/attention.md",
- kind: "wiki",
- },
- ])
- expect(String(result.messages[0].content)).toContain("Attention lets models focus")
- })
-
- it("materializes graph results without double-prefixing absolute node paths", async () => {
- const searchWiki = vi.fn(async () => [
- {
- path: "/tmp/project/wiki/concepts/attention.md",
- title: "Attention",
- snippet: "Attention relates to transformers.",
- titleMatch: true,
- score: 1,
- images: [],
- },
- ])
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- callbacks.onToken('{"action":"graph_search","queries":["attention transformer"]}')
- callbacks.onDone()
- })
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig,
- text: "How is attention connected to transformers?",
- historyMessages: [{ role: "user", content: "How is attention connected to transformers?" }],
- dataVersion: 1,
- options: { useWebSearch: false, useAnyTxtSearch: false },
- deps: { searchWiki, streamChat },
- })
-
- expect(result.references).toEqual([
- {
- title: "Transformer",
- path: "/tmp/project/wiki/concepts/transformer.md",
- kind: "wiki",
- },
- ])
- expect(String(result.messages[0].content)).toContain("Transformers use attention layers")
- expect(String(result.messages[0].content)).not.toContain("/tmp/project//tmp/project")
- })
-
- it("uses external search only when the planner selects it", async () => {
- const webSearch = vi.fn(async () => [
- {
- title: "External Paper",
- url: "https://example.com/paper",
- snippet: "A current external result.",
- source: "web",
- },
- ])
- const searchWiki = vi.fn()
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- callbacks.onToken('{"action":"external_search","queries":["latest transformer benchmark"]}')
- callbacks.onDone()
- })
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig: { provider: "firecrawl", apiKey: "" },
- text: "Find the latest transformer benchmark news.",
- historyMessages: [{ role: "user", content: "Find the latest transformer benchmark news." }],
- dataVersion: 1,
- options: { useWebSearch: true, useAnyTxtSearch: false },
- deps: { searchWiki, webSearch, streamChat },
- })
-
- expect(searchWiki).not.toHaveBeenCalled()
- expect(webSearch).toHaveBeenCalledWith("latest transformer benchmark", expect.any(Object), 5)
- expect(result.references).toEqual([
- {
- title: "External Paper",
- path: "https://example.com/paper",
- kind: "external",
- source: "web",
- url: "https://example.com/paper",
- snippet: "A current external result.",
- },
- ])
- expect(String(result.messages[0].content)).toContain("[E1]")
- expect(String(result.messages[0].content)).toContain('<context id="E1" source="web"')
- expect(String(result.messages[0].content)).toContain("External search is enabled for this conversation")
- expect(String(result.messages[0].content)).toContain("decide whether they are relevant")
- expect(String(result.messages[0].content)).toContain("If your answer uses any external search fact, include its [E#] citation")
- expect(String(result.messages[0].content)).toContain("Do not rely on the separate References panel")
- })
-
- it("overrides stale no-internet history when current external search results exist", async () => {
- const webSearch = vi.fn(async () => [
- {
- title: "Current Source",
- url: "https://example.com/current",
- snippet: "Fresh web result that answers the question.",
- source: "web",
- },
- ])
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- callbacks.onToken('{"action":"external_search","queries":["current source"]}')
- callbacks.onDone()
- })
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig: { provider: "firecrawl", apiKey: "" },
- text: "Please search the web and answer.",
- historyMessages: [
- { role: "user", content: "Can you search the web?" },
- { role: "assistant", content: "I cannot access the internet." },
- { role: "user", content: "Please search the web and answer." },
- ],
- dataVersion: 1,
- options: { useWebSearch: true, useAnyTxtSearch: false },
- deps: { webSearch, streamChat },
- })
-
- const system = String(result.messages[0].content)
- expect(system).toContain("Fresh web result that answers the question.")
- expect(system).toContain("If earlier conversation messages claimed external search was unavailable, ignore that stale claim")
- expect(system).toContain("Do not apologize for lacking web access")
- })
-
- it("can reuse recent external retrieval history without repeating web search", async () => {
- const webSearch = vi.fn()
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- callbacks.onToken('{"action":"finish","queries":[],"reason":"history is enough"}')
- callbacks.onDone()
- })
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig: { provider: "firecrawl", apiKey: "" },
- text: "What were the main points from the external source?",
- historyMessages: [{ role: "user", content: "What were the main points from the external source?" }],
- retrievalHistory: [
- {
- title: "External Paper",
- path: "https://example.com/paper",
- kind: "external",
- source: "web",
- url: "https://example.com/paper",
- snippet: "A prior external result.",
- },
- ],
- dataVersion: 1,
- options: { useWebSearch: true, useAnyTxtSearch: false },
- deps: { webSearch, streamChat },
- })
-
- expect(webSearch).not.toHaveBeenCalled()
- expect(result.references).toEqual([
- {
- title: "External Paper",
- path: "https://example.com/paper",
- kind: "external",
- source: "web",
- url: "https://example.com/paper",
- snippet: "A prior external result.",
- },
- ])
- expect(String(result.messages[0].content)).toContain("## Retrieved Context")
- expect(String(result.messages[0].content)).toContain('<context id="E1" source="web"')
- expect(String(result.messages[0].content)).toContain("A prior external result.")
- })
-
- it("lets follow-up understanding reach the planner so retrieval history can be reused", async () => {
- const webSearch = vi.fn()
- let call = 0
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- call += 1
- callbacks.onToken(call === 1
- ? '{"intent":"follow_up","rewrittenQuery":"main points","wikiQueries":[],"graphQueries":[],"externalQueries":[],"needsWiki":false,"needsGraph":false,"needsExternal":false,"isFollowUp":true}'
- : '{"action":"finish","queries":[],"reason":"history is enough"}')
- callbacks.onDone()
- })
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig: { provider: "firecrawl", apiKey: "" },
- text: "What were the main points?",
- historyMessages: [{ role: "user", content: "What were the main points?" }],
- retrievalHistory: [
- {
- title: "External Paper",
- path: "https://example.com/paper",
- kind: "external",
- source: "web",
- url: "https://example.com/paper",
- snippet: "A prior external result.",
- },
- ],
- dataVersion: 1,
- options: { useWebSearch: true, useAnyTxtSearch: false },
- deps: { webSearch, streamChat },
- })
-
- expect(streamChat).toHaveBeenCalledTimes(2)
- expect(webSearch).not.toHaveBeenCalled()
- expect(result.references).toHaveLength(1)
- expect(String(result.messages[0].content)).toContain("A prior external result.")
- })
-
- it("tells the planner when web search is enabled for the turn", async () => {
- const plannerUserPrompts: string[] = []
- const streamChat = vi.fn(async (_cfg, messages: LLMMessage[], callbacks) => {
- plannerUserPrompts.push(String(messages.find((msg) => msg.role === "user")?.content ?? ""))
- callbacks.onToken('{"action":"answer","queries":[]}')
- callbacks.onDone()
- })
-
- await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig: { provider: "firecrawl", apiKey: "" },
- text: "What's new in the latest release?",
- historyMessages: [{ role: "user", content: "What's new in the latest release?" }],
- dataVersion: 1,
- options: { useWebSearch: true, useAnyTxtSearch: false },
- deps: { streamChat },
- })
-
- expect(plannerUserPrompts[0]).toContain("User enabled Web Search for this turn: yes")
- expect(plannerUserPrompts[0]).toContain("User enabled AnyTXT Search for this turn: no")
- expect(plannerUserPrompts[0]).toContain("## Current Wiki Overview")
- expect(plannerUserPrompts[0]).toContain("This wiki covers transformer architecture")
- expect(plannerUserPrompts[1]).toContain("## Current Wiki Overview")
- })
-
- it("does not run tools when the planner chooses a direct answer", async () => {
- const searchWiki = vi.fn()
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- callbacks.onToken('{"action":"answer","queries":[],"answer":"This is a normal follow-up."}')
- callbacks.onDone()
- })
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig,
- text: "Can you rewrite that more clearly?",
- historyMessages: [{ role: "user", content: "Can you rewrite that more clearly?" }],
- dataVersion: 1,
- options: { useWebSearch: false, useAnyTxtSearch: false },
- deps: { searchWiki, streamChat },
- })
-
- expect(searchWiki).not.toHaveBeenCalled()
- expect(result.references).toEqual([])
- expect(String(result.messages[0].content)).toContain("Possible answer direction: This is a normal follow-up.")
- expect(String(result.messages[0].content)).not.toContain("Retrieved Context")
- })
-
- it("deduplicates repeated external retrieval items by url", async () => {
- const webSearch = vi.fn(async () => [
- {
- title: "Same Result A",
- url: "https://example.com/duplicate",
- snippet: "First copy.",
- source: "web",
- },
- {
- title: "Same Result B",
- url: "https://example.com/duplicate",
- snippet: "Second copy.",
- source: "web",
- },
- ])
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- callbacks.onToken('{"action":"external_search","queries":["duplicate result"]}')
- callbacks.onDone()
- })
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig: { provider: "firecrawl", apiKey: "" },
- text: "Search the web for duplicate result.",
- historyMessages: [{ role: "user", content: "Search the web for duplicate result." }],
- dataVersion: 1,
- options: { useWebSearch: true, useAnyTxtSearch: false },
- deps: { webSearch, streamChat },
- })
-
- expect(result.references).toHaveLength(1)
- expect(String(result.messages[0].content).match(/<context id="E\d+"/g)).toHaveLength(1)
- })
-
- it("keeps external search errors visible when no source returns results", async () => {
- const webSearch = vi.fn(async () => {
- throw new Error("Search provider unavailable")
- })
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- callbacks.onToken('{"action":"external_search","queries":["current outage"]}')
- callbacks.onDone()
- })
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig: { provider: "firecrawl", apiKey: "" },
- text: "Search for the current outage.",
- historyMessages: [{ role: "user", content: "Search for the current outage." }],
- dataVersion: 1,
- options: { useWebSearch: true, useAnyTxtSearch: false },
- deps: { webSearch, streamChat },
- })
-
- expect(result.references).toEqual([])
- expect(String(result.messages[0].content)).toContain("Retrieval status")
- expect(String(result.messages[0].content)).toContain("Search provider unavailable")
- expect(String(result.messages[0].content)).toContain("Do not apologize for lacking web access")
- })
-
- it("ranks query-overlapping wiki context ahead of weaker graph context", async () => {
- const searchWiki = vi.fn(async (projectPath: string, query: string) => {
- if (query === "attention") {
- return [
- {
- path: `${projectPath}/wiki/concepts/attention.md`,
- title: "Attention",
- snippet: "Attention lets models focus.",
- titleMatch: true,
- score: 1,
- images: [],
- },
- ]
- }
- return []
- })
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- callbacks.onToken('{"action":"multi_search","queries":["attention"]}')
- callbacks.onDone()
- })
-
- const result = await buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig,
- text: "Explain attention.",
- historyMessages: [{ role: "user", content: "Explain attention." }],
- dataVersion: 1,
- options: { useWebSearch: false, useAnyTxtSearch: false },
- deps: { searchWiki, streamChat },
- })
-
- const system = String(result.messages[0].content)
- expect(system.indexOf('title="Attention"')).toBeGreaterThan(-1)
- expect(system.indexOf('title="Transformer"')).toBeGreaterThan(system.indexOf('title="Attention"'))
- })
-
- it("stops the agent flow when the planner request is aborted", async () => {
- const controller = new AbortController()
- const searchWiki = vi.fn()
- const streamChat = vi.fn(async (_cfg, _messages, callbacks) => {
- controller.abort()
- callbacks.onDone()
- })
-
- await expect(buildChatAgentMessages({
- project: { name: "Demo", path: "/tmp/project" },
- llmConfig,
- searchApiConfig,
- text: "Search my wiki for attention.",
- historyMessages: [{ role: "user", content: "Search my wiki for attention." }],
- dataVersion: 1,
- options: { useWebSearch: false, useAnyTxtSearch: false },
- signal: controller.signal,
- deps: { searchWiki, streamChat },
- })).rejects.toMatchObject({ name: "AbortError" })
-
- expect(searchWiki).not.toHaveBeenCalled()
- })
-})
diff --git a/src/lib/chat-agent.ts b/src/lib/chat-agent.ts
deleted file mode 100644
index 0010a33b..00000000
--- a/src/lib/chat-agent.ts
+++ /dev/null
@@ -1,1800 +0,0 @@
-import { listDirectory, readFile } from "@/commands/fs"
-import { anyTxtSearchSmart } from "@/lib/anytxt-search"
-import { computeContextBudget } from "@/lib/context-budget"
-import { isGreeting } from "@/lib/greeting-detector"
-import { buildRetrievalGraph, getRelatedNodes } from "@/lib/graph-relevance"
-import { streamChat, type ChatMessage as LLMMessage } from "@/lib/llm-client"
-import { buildLanguageDirective, buildLanguageReminder } from "@/lib/output-language"
-import { getFileName, getRelativePath, normalizePath } from "@/lib/path-utils"
-import { searchWiki, type SearchResult } from "@/lib/search"
-import { resolveSearchConfig, webSearch, type WebSearchResult } from "@/lib/web-search"
-import type { LlmConfig, SearchApiConfig } from "@/stores/wiki-store"
-import type { MessageReference } from "@/stores/chat-store"
-import type { FileNode } from "@/types/wiki"
-import { filterRawSourceTree } from "@/lib/source-filter"
-
-export type ChatAgentAction =
- | "answer"
- | "project_files"
- | "project_file_read"
- | "wiki_search"
- | "graph_search"
- | "external_search"
- | "multi_search"
- | "finish"
-
-export interface ChatAgentDecision {
- action: ChatAgentAction
- queries: string[]
- answer?: string
- reason?: string
-}
-
-export type ChatAgentIntent =
- | "chitchat"
- | "follow_up"
- | "rewrite"
- | "kb_search"
- | "graph"
- | "external"
- | "mixed"
-
-export interface ChatQueryUnderstanding {
- intent: ChatAgentIntent
- rewrittenQuery: string
- wikiQueries: string[]
- graphQueries: string[]
- externalQueries: string[]
- needsWiki: boolean
- needsGraph: boolean
- needsExternal: boolean
- isFollowUp: boolean
- reason?: string
-}
-
-export interface ChatAgentProject {
- name: string
- path: string
-}
-
-export interface ChatAgentOptions {
- useWebSearch: boolean
- useAnyTxtSearch: boolean
- mode?: ChatAgentMode
-}
-
-export interface ChatAgentDeps {
- searchWiki?: typeof searchWiki
- webSearch?: typeof webSearch
- anyTxtSearchSmart?: typeof anyTxtSearchSmart
- streamChat?: typeof streamChat
-}
-
-export type ChatAgentEventStage =
- | "understanding"
- | "routing"
- | "tool_call"
- | "tool_result"
- | "searching_wiki"
- | "searching_graph"
- | "searching_web"
- | "searching_anytxt"
- | "reading_context"
- | "writing"
-
-export interface ChatAgentEvent {
- stage: ChatAgentEventStage
- query?: string
- tool?: ChatAgentToolName
- message?: string
- count?: number
- status?: "running" | "success" | "error" | "skipped"
-}
-
-export interface ChatAgentInput {
- project: ChatAgentProject | null
- llmConfig: LlmConfig
- searchApiConfig: SearchApiConfig
- text: string
- historyMessages: LLMMessage[]
- retrievalHistory?: MessageReference[]
- dataVersion: number
- options: ChatAgentOptions
- signal?: AbortSignal
- onEvent?: (event: ChatAgentEvent) => void
- deps?: ChatAgentDeps
-}
-
-export interface ChatAgentResult {
- messages: LLMMessage[]
- references: MessageReference[]
- queryPages: { title: string; path: string }[]
- plan: ChatAgentDecision[]
- steps: ChatAgentStep[]
-}
-
-interface ToolObservation {
- tool: "project_files" | "project_file_read" | "wiki_search" | "graph_search" | "external_search"
- query: string
- content: string
- references: MessageReference[]
- pages: { title: string; path: string }[]
- items: RetrievedItem[]
- errorCount?: number
-}
-
-export type ChatAgentMode = "fast" | "standard" | "deep" | "local_first"
-
-export type ChatAgentToolName =
- | "project_files"
- | "project_file_read"
- | "wiki_search"
- | "graph_search"
- | "web_search"
- | "anytxt_search"
-
-export interface ChatAgentToolDefinition {
- name: ChatAgentToolName
- action: Extract<ChatAgentAction, "project_files" | "project_file_read" | "wiki_search" | "graph_search" | "external_search">
- stage: Extract<ChatAgentEventStage, "searching_wiki" | "searching_graph" | "searching_web" | "searching_anytxt">
- label: string
- description: string
- requiresProject?: boolean
-}
-
-export interface ChatAgentStep {
- id: string
- type: "understanding" | "routing" | "tool_call" | "tool_result" | "final"
- tool?: ChatAgentToolName
- query?: string
- message?: string
- count?: number
- status?: "running" | "success" | "error" | "skipped"
-}
-
-type PageEntry = { title: string; path: string; content: string; priority: number }
-type ProjectPromptContext = { purpose: string; index: string; overview: string }
-type RetrievedItemKind = "wiki" | "graph" | "external" | "history"
-
-interface RetrievedItem {
- id: string
- kind: RetrievedItemKind
- source: string
- title: string
- path: string
- url?: string
- snippet: string
- content: string
- score: number
- query: string
- reference: MessageReference
- page?: { title: string; path: string }
-}
-
-interface RetrievedContext {
- contextText: string
- references: MessageReference[]
- pages: { title: string; path: string }[]
- itemCount: number
-}
-
-const MAX_AGENT_ROUNDS = 3
-const MAX_DEEP_AGENT_ROUNDS = 5
-const MAX_TOOL_CONTEXT_CHARS = 48_000
-
-const CHAT_AGENT_TOOL_REGISTRY: ChatAgentToolDefinition[] = [
- {
- name: "project_files",
- action: "project_files",
- stage: "searching_wiki",
- label: "Project Files",
- description: "List project and wiki files through the same project-bound file access used by the local API/MCP tools.",
- requiresProject: true,
- },
- {
- name: "project_file_read",
- action: "project_file_read",
- stage: "searching_wiki",
- label: "Project File Read",
- description: "Read a specific project text file by relative path when the user names a file or asks to inspect one.",
- requiresProject: true,
- },
- {
- name: "wiki_search",
- action: "wiki_search",
- stage: "searching_wiki",
- label: "Wiki Search",
- description: "Search local wiki pages and retrieve relevant page content.",
- requiresProject: true,
- },
- {
- name: "graph_search",
- action: "graph_search",
- stage: "searching_graph",
- label: "Graph Search",
- description: "Inspect relationships between wiki entities, concepts, and pages.",
- requiresProject: true,
- },
- {
- name: "web_search",
- action: "external_search",
- stage: "searching_web",
- label: "Web Search",
- description: "Search enabled web providers for current or external information.",
- },
- {
- name: "anytxt_search",
- action: "external_search",
- stage: "searching_anytxt",
- label: "AnyTXT Search",
- description: "Search external local files indexed by AnyTXT.",
- },
-]
-
-export function getChatAgentTools(args: {
- hasProject: boolean
- webSearchEnabled: boolean
- anyTxtSearchEnabled: boolean
- mode?: ChatAgentMode
-}): ChatAgentToolDefinition[] {
- return CHAT_AGENT_TOOL_REGISTRY.filter((tool) => {
- if (tool.requiresProject && !args.hasProject) return false
- if (tool.name === "web_search") return args.webSearchEnabled && args.mode !== "local_first"
- if (tool.name === "anytxt_search") return args.anyTxtSearchEnabled
- if (tool.name === "project_file_read") return args.mode !== "fast"
- return true
- })
-}
-
-export function shouldBypassAgentPlanner(text: string): ChatAgentDecision | null {
- const q = text.trim()
- const lower = q.toLowerCase()
- if (!q) return { action: "answer", queries: [], reason: "empty" }
-
- if (isGreeting(q)) {
- return { action: "answer", queries: [], reason: "greeting" }
- }
-
- if (/^(继续|接着说|展开|展开一下|详细说说|换个说法|重新说|总结一下|总结上面|翻译|翻译成英文|翻译成中文|这是什么意思|什么意思)[\s\S]{0,30}$/i.test(q)) {
- return { action: "answer", queries: [], reason: "short follow-up" }
- }
-
- if (
- /^(continue|go on|expand|summari[sz]e|translate|rewrite|rephrase|what do you mean)\b/i.test(lower) &&
- q.length < 120
- ) {
- return { action: "answer", queries: [], reason: "short follow-up" }
- }
-
- return null
-}
-
-export async function buildChatAgentMessages(input: ChatAgentInput): Promise<ChatAgentResult> {
- throwIfAborted(input.signal)
- const deps = {
- searchWiki,
- webSearch,
- anyTxtSearchSmart,
- streamChat,
- ...input.deps,
- }
- const projectPath = input.project ? normalizePath(input.project.path) : ""
- const searchConfig = resolveSearchConfig(input.searchApiConfig)
- const observations: ToolObservation[] = []
- const historicalObservations = await buildHistoricalObservations({
- projectPath,
- references: input.retrievalHistory ?? [],
- llmConfig: input.llmConfig,
- })
- const plan: ChatAgentDecision[] = []
- const steps: ChatAgentStep[] = []
- const executedToolKeys = new Set<string>()
- const enabledTools = getChatAgentTools({
- hasProject: Boolean(input.project),
- webSearchEnabled: input.options.useWebSearch,
- anyTxtSearchEnabled: input.options.useAnyTxtSearch,
- mode: input.options.mode ?? "standard",
- })
- const projectRoutingContext = input.project
- ? await readProjectRoutingContext(projectPath, input.text, input.llmConfig)
- : undefined
-
- const direct = shouldBypassAgentPlanner(input.text)
- if (direct) {
- plan.push(direct)
- steps.push({
- id: makeStepId(steps),
- type: "understanding",
- message: direct.reason ?? "Direct answer",
- status: "success",
- })
- } else {
- input.onEvent?.({ stage: "understanding", status: "running" })
- const understanding = await understandUserQuery({
- llmConfig: input.llmConfig,
- text: input.text,
- historyMessages: input.historyMessages,
- hasProject: Boolean(input.project),
- projectContext: projectRoutingContext,
- webSearchEnabled: input.options.useWebSearch,
- anyTxtSearchEnabled: input.options.useAnyTxtSearch,
- mode: input.options.mode ?? "standard",
- tools: enabledTools,
- signal: input.signal,
- streamChatImpl: deps.streamChat,
- })
- steps.push({
- id: makeStepId(steps),
- type: "understanding",
- query: understanding.rewrittenQuery,
- message: understanding.reason ?? understanding.intent,
- status: "success",
- })
- input.onEvent?.({
- stage: "understanding",
- query: understanding.rewrittenQuery,
- message: understanding.reason ?? understanding.intent,
- status: "success",
- })
-
- const understandingDecision = decisionFromUnderstanding(understanding, input.text)
- if (understandingDecision.action === "answer") {
- plan.push(understandingDecision)
- }
-
- const maxRounds = input.options.mode === "deep" ? MAX_DEEP_AGENT_ROUNDS : MAX_AGENT_ROUNDS
- for (let round = 0; round < maxRounds; round++) {
- if (plan[plan.length - 1]?.action === "answer") break
- throwIfAborted(input.signal)
- const observationsBefore = observations.length
- input.onEvent?.({ stage: "routing", status: "running" })
- const decision = await decideNextAction({
- llmConfig: input.llmConfig,
- text: input.text,
- understanding,
- tools: enabledTools,
- historyMessages: input.historyMessages,
- observations,
- historicalObservations,
- projectName: input.project?.name,
- hasProject: Boolean(input.project),
- projectContext: projectRoutingContext,
- webSearchEnabled: input.options.useWebSearch,
- anyTxtSearchEnabled: input.options.useAnyTxtSearch,
- mode: input.options.mode ?? "standard",
- signal: input.signal,
- streamChatImpl: deps.streamChat,
- })
- throwIfAborted(input.signal)
- plan.push(decision)
- steps.push({
- id: makeStepId(steps),
- type: "routing",
- query: decision.queries.join(" | "),
- message: decision.reason ?? decision.action,
- status: "success",
- })
- input.onEvent?.({
- stage: "routing",
- query: decision.queries.join(" | "),
- message: decision.reason ?? decision.action,
- status: "success",
- })
- if (decision.action === "answer" || decision.action === "finish") break
-
- const queries = normalizeDecisionQueries(decision, input.text)
- if (queries.length === 0) break
- const toolKey = `${decision.action}:${queries.map((query) => query.toLowerCase()).join("|")}`
- if (executedToolKeys.has(toolKey)) break
- executedToolKeys.add(toolKey)
-
- if ((decision.action === "project_files" || decision.action === "multi_search") && input.project) {
- throwIfAborted(input.signal)
- const tool = enabledTools.find((item) => item.name === "project_files")
- if (tool) {
- emitToolCall({ tool, queries, steps, onEvent: input.onEvent })
- const observation = await runProjectFilesTool({
- projectPath,
- queries,
- llmConfig: input.llmConfig,
- })
- observations.push(observation)
- emitToolResult({ tool, observation, steps, onEvent: input.onEvent })
- }
- }
-
- if ((decision.action === "project_file_read" || decision.action === "multi_search") && input.project) {
- throwIfAborted(input.signal)
- const tool = enabledTools.find((item) => item.name === "project_file_read")
- if (tool) {
- emitToolCall({ tool, queries, steps, onEvent: input.onEvent })
- const observation = await runProjectFileReadTool({
- projectPath,
- queries,
- llmConfig: input.llmConfig,
- })
- observations.push(observation)
- emitToolResult({ tool, observation, steps, onEvent: input.onEvent })
- }
- }
-
- if ((decision.action === "wiki_search" || decision.action === "multi_search") && input.project) {
- throwIfAborted(input.signal)
- const tool = enabledTools.find((item) => item.name === "wiki_search")
- if (tool) {
- emitToolCall({ tool, queries, steps, onEvent: input.onEvent })
- const observation = await runWikiSearchTool({
- projectPath,
- queries,
- llmConfig: input.llmConfig,
- searchWikiImpl: deps.searchWiki,
- })
- observations.push(observation)
- emitToolResult({ tool, observation, steps, onEvent: input.onEvent })
- }
- }
-
- if ((decision.action === "graph_search" || decision.action === "multi_search") && input.project) {
- throwIfAborted(input.signal)
- const tool = enabledTools.find((item) => item.name === "graph_search")
- if (tool) {
- emitToolCall({ tool, queries, steps, onEvent: input.onEvent })
- const observation = await runGraphSearchTool({
- projectPath,
- dataVersion: input.dataVersion,
- queries,
- llmConfig: input.llmConfig,
- searchWikiImpl: deps.searchWiki,
- })
- observations.push(observation)
- emitToolResult({ tool, observation, steps, onEvent: input.onEvent })
- }
- }
-
- if ((decision.action === "external_search" || decision.action === "multi_search") && input.options.useWebSearch) {
- throwIfAborted(input.signal)
- const tool = enabledTools.find((item) => item.name === "web_search")
- if (tool) {
- emitToolCall({ tool, queries, steps, onEvent: input.onEvent })
- const observation = await runExternalSearchTool({
- queries,
- searchConfig,
- webSearchImpl: deps.webSearch,
- source: "web",
- })
- observations.push(observation)
- emitToolResult({ tool, observation, steps, onEvent: input.onEvent })
- }
- }
-
- if ((decision.action === "external_search" || decision.action === "multi_search") && input.options.useAnyTxtSearch) {
- throwIfAborted(input.signal)
- const tool = enabledTools.find((item) => item.name === "anytxt_search")
- if (tool) {
- emitToolCall({ tool, queries, steps, onEvent: input.onEvent })
- const observation = await runExternalSearchTool({
- queries,
- searchConfig,
- llmConfig: input.llmConfig,
- projectPath,
- anyTxtSearchSmartImpl: deps.anyTxtSearchSmart,
- source: "anytxt",
- })
- observations.push(observation)
- emitToolResult({ tool, observation, steps, onEvent: input.onEvent })
- }
- }
-
- if (observations.length === observationsBefore) break
- }
- }
-
- throwIfAborted(input.signal)
- const lastDecision = plan[plan.length - 1]
- const observationsForAnswer = observations.length > 0
- ? observations
- : lastDecision?.action === "finish"
- ? historicalObservations
- : []
- if (observations.length > 0) input.onEvent?.({ stage: "reading_context" })
- const projectContext = input.project && observationsForAnswer.some((obs) =>
- obs.tool === "project_files"
- || obs.tool === "project_file_read"
- || obs.tool === "wiki_search"
- || obs.tool === "graph_search")
- ? await readProjectPromptContext(projectPath, input.text, input.llmConfig)
- : undefined
- const retrievedContext = buildRetrievedContext(observationsForAnswer, input.text, input.llmConfig)
- throwIfAborted(input.signal)
- input.onEvent?.({ stage: "writing" })
- steps.push({
- id: makeStepId(steps),
- type: "final",
- message: retrievedContext.itemCount > 0 ? "Answer with retrieved context" : "Direct answer",
- count: retrievedContext.references.length,
- status: "success",
- })
- return {
- messages: buildFinalMessages({
- project: input.project,
- text: input.text,
- historyMessages: input.historyMessages,
- observations: observationsForAnswer,
- retrievedContext,
- directAnswerHint: plan.find((item) => item.answer)?.answer,
- projectContext,
- }),
- references: retrievedContext.references,
- queryPages: retrievedContext.pages,
- plan,
- steps,
- }
-}
-
-async function decideNextAction(args: {
- llmConfig: LlmConfig
- text: string
- understanding: ChatQueryUnderstanding
- tools: ChatAgentToolDefinition[]
- historyMessages: LLMMessage[]
- observations: ToolObservation[]
- historicalObservations: ToolObservation[]
- projectName?: string
- hasProject: boolean
- projectContext?: ProjectPromptContext
- webSearchEnabled: boolean
- anyTxtSearchEnabled: boolean
- mode: ChatAgentMode
- signal?: AbortSignal
- streamChatImpl: typeof streamChat
-}): Promise<ChatAgentDecision> {
- const externalEnabled = args.webSearchEnabled || args.anyTxtSearchEnabled
- const toolDescriptions = args.tools.length > 0
- ? args.tools.map((tool) => `- ${tool.name}: ${tool.description}`).join("\n")
- : "- none"
- const system = [
- "You are a routing controller for a local knowledge assistant.",
- "Return JSON only. Do not answer in prose.",
- "",
- "Available actions:",
- "- answer: answer from conversation history or general reasoning without retrieval.",
- "- project_files: list project/wiki files when the user asks what exists, asks for project structure, or names files/pages imprecisely.",
- "- project_file_read: read a specific project text file when the user names a path or asks to inspect a known file.",
- "- wiki_search: search the local wiki when the user asks about project/wiki/docs/knowledge.",
- "- graph_search: inspect relationships between entities/concepts/pages.",
- "- external_search: search enabled external information sources.",
- "- multi_search: use more than one retrieval source.",
- "- finish: enough tool observations are available; final answer can be produced.",
- "",
- "Enabled tools:",
- toolDescriptions,
- "",
- "Return shape:",
- "{\"action\":\"answer|project_files|project_file_read|wiki_search|graph_search|external_search|multi_search|finish\",\"queries\":[\"short query or relative file path\"],\"answer\":\"optional direct draft\",\"reason\":\"short reason\"}",
- "",
- "Rules:",
- "- Do not retrieve for greetings, casual chat, translation/rewrite/summarize/follow-up requests about prior assistant messages.",
- "- Use wiki_search for questions about the local wiki, project materials, documents, notes, or remembered knowledge.",
- "- Use the project overview/purpose/index below to judge whether the local wiki is likely to contain the answer.",
- "- If the project overview says the current topic is in scope, prefer wiki_search or multi_search before relying only on external_search.",
- "- Use project_files before project_file_read when the user gives a fuzzy file/page name and you need to locate likely paths.",
- "- Use graph_search for relationships, dependencies, links, entities, concepts, clusters, or graph questions.",
- "- If the user enabled Web Search for this turn, treat that as a strong preference to use external_search or multi_search for current facts, web pages, public docs, product/API details, news, versions, pricing, or anything likely outside the local wiki.",
- "- If the user enabled AnyTXT Search for this turn, treat that as a strong preference to use external_search or multi_search when the answer may depend on external local files outside the wiki.",
- "- Do not repeat external_search for simple follow-ups, summaries, rewrites, translations, or questions that can be answered from already available observations/history, unless the user explicitly asks to search again or asks for newer information.",
- "- Never choose external_search if no external source is enabled.",
- "- In local_first mode, prefer project_files, project_file_read, wiki_search, or graph_search; use external_search only when the user explicitly asks for external information.",
- "- In fast mode, avoid multi-step file inspection; prefer answer or a single wiki_search when retrieval is clearly needed.",
- "- In deep mode, you may use multiple tools when the question requires broader evidence.",
- "- If tool observations are already enough, choose finish.",
- "- Keep queries concise and keyword-rich.",
- ].join("\n")
-
- const recentHistory = args.historyMessages.slice(-6).map((msg) => {
- const content = typeof msg.content === "string"
- ? msg.content
- : msg.content.map((block) => block.type === "text" ? block.text : "[image]").join("\n")
- return `${msg.role}: ${content.slice(0, 1200)}`
- }).join("\n\n")
-
- const observations = args.observations.map((obs, index) => [
- `Observation ${index + 1}: ${obs.tool}`,
- `Query: ${obs.query}`,
- obs.content.slice(0, 5000),
- ].join("\n")).join("\n\n---\n\n")
-
- const historyObservations = args.historicalObservations.map((obs, index) => [
- `Historical observation ${index + 1}: ${obs.tool}`,
- `Query: ${obs.query}`,
- obs.content.slice(0, 3000),
- ].join("\n")).join("\n\n---\n\n")
-
- const user = [
- `Project: ${args.projectName ?? "none"}`,
- `Local wiki available: ${args.hasProject ? "yes" : "no"}`,
- `External search enabled: ${externalEnabled ? "yes" : "no"}`,
- `Agent mode: ${args.mode}`,
- `User enabled Web Search for this turn: ${args.webSearchEnabled ? "yes" : "no"}`,
- `User enabled AnyTXT Search for this turn: ${args.anyTxtSearchEnabled ? "yes" : "no"}`,
- `Query understanding: ${JSON.stringify(args.understanding)}`,
- "",
- formatProjectContextForRouting(args.projectContext),
- "",
- recentHistory ? `Recent conversation:\n${recentHistory}` : "Recent conversation: none",
- "",
- observations ? `Tool observations:\n${observations}` : "Tool observations: none",
- "",
- historyObservations
- ? [
- "Recent retrieval history:",
- historyObservations,
- "Use this only when the current message is a follow-up to the earlier retrieved sources. If it already answers the current follow-up, choose finish instead of repeating the same search.",
- ].join("\n")
- : "Recent retrieval history: none",
- "",
- `Current user message:\n${args.text}`,
- ].join("\n")
-
- const raw = await collectChatText(args.llmConfig, [
- { role: "system", content: system },
- { role: "user", content: user },
- ], args.streamChatImpl, args.signal, { temperature: 0, max_tokens: 300 })
-
- return parseDecision(raw, args.text)
-}
-
-async function understandUserQuery(args: {
- llmConfig: LlmConfig
- text: string
- historyMessages: LLMMessage[]
- hasProject: boolean
- projectContext?: ProjectPromptContext
- webSearchEnabled: boolean
- anyTxtSearchEnabled: boolean
- mode: ChatAgentMode
- tools: ChatAgentToolDefinition[]
- signal?: AbortSignal
- streamChatImpl: typeof streamChat
-}): Promise<ChatQueryUnderstanding> {
- const toolDescriptions = args.tools.length > 0
- ? args.tools.map((tool) => `- ${tool.name}: ${tool.description}`).join("\n")
- : "- none"
- const system = [
- "You are the query understanding stage for a local knowledge assistant.",
- "Return JSON only. Do not answer the user.",
- "",
- "Classify the current message and produce search-ready queries.",
- "Return shape:",
- "{\"intent\":\"chitchat|follow_up|rewrite|kb_search|graph|external|mixed\",\"rewrittenQuery\":\"short normalized query\",\"wikiQueries\":[\"...\"],\"graphQueries\":[\"...\"],\"externalQueries\":[\"...\"],\"needsWiki\":true,\"needsGraph\":false,\"needsExternal\":false,\"isFollowUp\":false,\"reason\":\"short reason\"}",
- "",
- "Rules:",
- "- chitchat/follow_up/rewrite should not require retrieval unless the user explicitly asks to search.",
- "- Use kb_search for local wiki/project/document questions.",
- "- Use the project overview/purpose/index below to judge whether the local wiki is likely to contain the answer.",
- "- If the project overview says the current topic is in scope, set needsWiki=true. If current external facts are also useful, use mixed instead of external-only.",
- "- Use graph for relationship/entity/connection questions.",
- "- Use external for current facts, public docs, web pages, product/API details, versions, pricing, or local files outside the wiki when the matching external source is enabled.",
- "- Use mixed when local wiki plus external sources are both useful.",
- "- In local_first mode, set needsWiki=true for any topic plausibly covered by the project.",
- "- In fast mode, be conservative about extra tools.",
- "- In deep mode, prefer mixed when both local and external evidence could help.",
- "- Keep each query concise and keyword-rich.",
- "",
- "Enabled tools:",
- toolDescriptions,
- ].join("\n")
-
- const recentHistory = args.historyMessages.slice(-6).map((msg) => {
- const content = typeof msg.content === "string"
- ? msg.content
- : msg.content.map((block) => block.type === "text" ? block.text : "[image]").join("\n")
- return `${msg.role}: ${content.slice(0, 1000)}`
- }).join("\n\n")
-
- const user = [
- `Local wiki available: ${args.hasProject ? "yes" : "no"}`,
- `Web Search enabled: ${args.webSearchEnabled ? "yes" : "no"}`,
- `AnyTXT Search enabled: ${args.anyTxtSearchEnabled ? "yes" : "no"}`,
- `Agent mode: ${args.mode}`,
- `User enabled Web Search for this turn: ${args.webSearchEnabled ? "yes" : "no"}`,
- `User enabled AnyTXT Search for this turn: ${args.anyTxtSearchEnabled ? "yes" : "no"}`,
- "",
- formatProjectContextForRouting(args.projectContext),
- "",
- recentHistory ? `Recent conversation:\n${recentHistory}` : "Recent conversation: none",
- "",
- `Current user message:\n${args.text}`,
- ].join("\n")
-
- const raw = await collectChatText(args.llmConfig, [
- { role: "system", content: system },
- { role: "user", content: user },
- ], args.streamChatImpl, args.signal, { temperature: 0, max_tokens: 450 })
-
- return parseUnderstanding(raw, args.text, {
- hasProject: args.hasProject,
- webSearchEnabled: args.webSearchEnabled,
- anyTxtSearchEnabled: args.anyTxtSearchEnabled,
- })
-}
-
-export function parseUnderstanding(
- raw: string,
- fallbackQuery: string,
- availability: { hasProject: boolean; webSearchEnabled: boolean; anyTxtSearchEnabled: boolean },
-): ChatQueryUnderstanding {
- const fallback = fallbackUnderstanding(fallbackQuery, availability)
- const text = raw.trim()
- const start = text.indexOf("{")
- const end = text.lastIndexOf("}")
- const json = start >= 0 && end > start ? text.slice(start, end + 1) : text
- try {
- const parsed = JSON.parse(json) as Partial<ChatQueryUnderstanding & ChatAgentDecision>
- const intent = normalizeIntent(parsed.intent)
- const rewrittenQuery = typeof parsed.rewrittenQuery === "string" && parsed.rewrittenQuery.trim()
- ? parsed.rewrittenQuery.trim()
- : fallback.rewrittenQuery
- const wikiQueries = normalizeQueryList(parsed.wikiQueries, rewrittenQuery)
- const graphQueries = normalizeQueryList(parsed.graphQueries, rewrittenQuery)
- const externalQueries = normalizeQueryList(parsed.externalQueries, rewrittenQuery)
- return {
- intent,
- rewrittenQuery,
- wikiQueries,
- graphQueries,
- externalQueries,
- needsWiki: typeof parsed.needsWiki === "boolean" ? parsed.needsWiki : fallback.needsWiki,
- needsGraph: typeof parsed.needsGraph === "boolean" ? parsed.needsGraph : fallback.needsGraph,
- needsExternal: typeof parsed.needsExternal === "boolean" ? parsed.needsExternal : fallback.needsExternal,
- isFollowUp: typeof parsed.isFollowUp === "boolean" ? parsed.isFollowUp : intent === "follow_up",
- reason: typeof parsed.reason === "string" ? parsed.reason.trim() : fallback.reason,
- }
- } catch {
- return fallback
- }
-}
-
-function fallbackUnderstanding(
- query: string,
- availability: { hasProject: boolean; webSearchEnabled: boolean; anyTxtSearchEnabled: boolean },
-): ChatQueryUnderstanding {
- const lower = query.toLowerCase()
- const needsGraph = /(关系|关联|连接|图谱|依赖|relationship|related|graph|connection|linked)/i.test(query)
- const needsExternal = availability.webSearchEnabled && /(latest|current|today|news|price|version|docs|api|最新|现在|今天|新闻|价格|版本|官方文档)/i.test(lower)
- const needsWiki = availability.hasProject && (!needsExternal || availability.anyTxtSearchEnabled)
- const intent: ChatAgentIntent = needsGraph
- ? "graph"
- : needsExternal && needsWiki
- ? "mixed"
- : needsExternal
- ? "external"
- : needsWiki
- ? "kb_search"
- : "chitchat"
- return {
- intent,
- rewrittenQuery: query.trim(),
- wikiQueries: needsWiki ? [query.trim()] : [],
- graphQueries: needsGraph ? [query.trim()] : [],
- externalQueries: needsExternal || availability.anyTxtSearchEnabled ? [query.trim()] : [],
- needsWiki,
- needsGraph,
- needsExternal: needsExternal || availability.anyTxtSearchEnabled,
- isFollowUp: false,
- reason: "fallback understanding",
- }
-}
-
-function normalizeIntent(intent: unknown): ChatAgentIntent {
- switch (intent) {
- case "chitchat":
- case "follow_up":
- case "rewrite":
- case "kb_search":
- case "graph":
- case "external":
- case "mixed":
- return intent
- default:
- return "kb_search"
- }
-}
-
-function normalizeQueryList(value: unknown, fallback: string): string[] {
- if (!Array.isArray(value)) return fallback ? [fallback] : []
- const queries = value.map((item) => String(item).trim()).filter(Boolean)
- return (queries.length > 0 ? queries : fallback ? [fallback] : []).slice(0, 5)
-}
-
-function decisionFromUnderstanding(understanding: ChatQueryUnderstanding, fallback: string): ChatAgentDecision {
- if (understanding.intent === "chitchat" || understanding.intent === "rewrite") {
- return {
- action: "answer",
- queries: [],
- reason: understanding.reason ?? understanding.intent,
- }
- }
- if (understanding.intent === "follow_up") {
- return {
- action: "finish",
- queries: [],
- reason: understanding.reason ?? understanding.intent,
- }
- }
- if (understanding.needsWiki && understanding.needsGraph || understanding.needsWiki && understanding.needsExternal) {
- return { action: "multi_search", queries: preferredQueries(understanding, fallback), reason: understanding.reason }
- }
- if (understanding.needsGraph) {
- return { action: "graph_search", queries: nonEmptyQueries(understanding.graphQueries, fallback), reason: understanding.reason }
- }
- if (understanding.needsExternal) {
- return { action: "external_search", queries: nonEmptyQueries(understanding.externalQueries, fallback), reason: understanding.reason }
- }
- if (understanding.needsWiki) {
- return { action: "wiki_search", queries: nonEmptyQueries(understanding.wikiQueries, fallback), reason: understanding.reason }
- }
- return { action: "answer", queries: [], reason: understanding.reason }
-}
-
-function preferredQueries(understanding: ChatQueryUnderstanding, fallback: string): string[] {
- return nonEmptyQueries([
- ...understanding.wikiQueries,
- ...understanding.graphQueries,
- ...understanding.externalQueries,
- ], fallback)
-}
-
-function nonEmptyQueries(queries: string[], fallback: string): string[] {
- const normalized = queries.map((q) => q.trim()).filter(Boolean)
- return (normalized.length > 0 ? normalized : [fallback]).slice(0, 5)
-}
-
-export function parseDecision(raw: string, fallbackQuery: string): ChatAgentDecision {
- const text = raw.trim()
- const start = text.indexOf("{")
- const end = text.lastIndexOf("}")
- const json = start >= 0 && end > start ? text.slice(start, end + 1) : text
- try {
- const parsed = JSON.parse(json) as Partial<ChatAgentDecision>
- const action = normalizeAction(parsed.action)
- return {
- action,
- queries: Array.isArray(parsed.queries)
- ? parsed.queries.map((q) => String(q).trim()).filter(Boolean).slice(0, 5)
- : [fallbackQuery],
- answer: typeof parsed.answer === "string" ? parsed.answer.trim() : undefined,
- reason: typeof parsed.reason === "string" ? parsed.reason.trim() : undefined,
- }
- } catch {
- return { action: "wiki_search", queries: [fallbackQuery], reason: "router fallback" }
- }
-}
-
-function normalizeAction(action: unknown): ChatAgentAction {
- switch (action) {
- case "answer":
- case "project_files":
- case "project_file_read":
- case "wiki_search":
- case "graph_search":
- case "external_search":
- case "multi_search":
- case "finish":
- return action
- default:
- return "wiki_search"
- }
-}
-
-function normalizeDecisionQueries(decision: ChatAgentDecision, fallback: string): string[] {
- const queries = decision.queries.map((q) => q.trim()).filter(Boolean)
- return (queries.length > 0 ? queries : [fallback]).slice(0, 5)
-}
-
-async function runProjectFilesTool(args: {
- projectPath: string
- queries: string[]
- llmConfig: LlmConfig
-}): Promise<ToolObservation> {
- const maxEntries = args.llmConfig.maxContextSize > 180_000 ? 160 : 80
- const [wikiTree, rawTree] = await Promise.all([
- listDirectory(`${args.projectPath}/wiki`).catch(() => [] as FileNode[]),
- listDirectory(`${args.projectPath}/raw/sources`, true)
- .then(filterRawSourceTree)
- .catch(() => [] as FileNode[]),
- ])
- const wikiEntries = flattenFileTree(wikiTree, "wiki").slice(0, maxEntries)
- const rawEntries = flattenFileTree(rawTree, "raw/sources").slice(0, Math.floor(maxEntries / 2))
- const content = [
- "# Project file listing",
- `Query: ${args.queries.join(" | ")}`,
- "",
- "## Wiki files",
- wikiEntries.length > 0 ? wikiEntries.map((entry) => `- ${entry}`).join("\n") : "(none)",
- wikiEntries.length >= maxEntries ? "\n[...wiki listing truncated...]" : "",
- "",
- "## Source files",
- rawEntries.length > 0 ? rawEntries.map((entry) => `- ${entry}`).join("\n") : "(none)",
- rawEntries.length >= Math.floor(maxEntries / 2) ? "\n[...source listing truncated...]" : "",
- ].filter(Boolean).join("\n")
- const reference: MessageReference = {
- title: "Project file listing",
- path: `${args.projectPath}/wiki/index.md`,
- kind: "wiki",
- snippet: wikiEntries.slice(0, 10).join("\n"),
- }
- return {
- tool: "project_files",
- query: args.queries.join(" | "),
- content,
- references: [reference],
- pages: [],
- items: [{
- id: "project-files",
- kind: "wiki",
- source: "project_files",
- title: "Project file listing",
- path: `${args.projectPath}/wiki/index.md`,
- snippet: wikiEntries.slice(0, 10).join("\n"),
- content,
- score: 0.8,
- query: args.queries.join(" | "),
- reference,
- }],
- errorCount: 0,
- }
-}
-
-async function runProjectFileReadTool(args: {
- projectPath: string
- queries: string[]
- llmConfig: LlmConfig
-}): Promise<ToolObservation> {
- const { maxPageSize } = computeContextBudget(args.llmConfig.maxContextSize)
- const pages: PageEntry[] = []
- const errors: string[] = []
- for (const query of args.queries.slice(0, 5)) {
- const rel = normalizeProjectRelativePath(query)
- if (!rel || !isReadableProjectTextPath(rel)) {
- errors.push(`Skipped unsafe or unsupported path: ${query}`)
- continue
- }
- try {
- const raw = await readFile(`${args.projectPath}/${rel}`)
- const content = raw.length > maxPageSize
- ? `${raw.slice(0, maxPageSize)}\n\n[...truncated...]`
- : raw
- pages.push({
- title: getFileName(rel),
- path: rel,
- content,
- priority: pages.length,
- })
- } catch (err) {
- errors.push(`Failed to read ${rel}: ${err instanceof Error ? err.message : String(err)}`)
- }
- }
- return {
- tool: "project_file_read",
- query: args.queries.join(" | "),
- content: [
- formatWikiObservation("Project file contents", pages, []),
- errors.length > 0 ? `Errors:\n${errors.map((err) => `- ${err}`).join("\n")}` : "",
- ].filter(Boolean).join("\n\n"),
- references: pages.map((page) => ({ title: page.title, path: `${args.projectPath}/${page.path}`, kind: "wiki" as const })),
- pages: pages.map((page) => ({ title: page.title, path: `${args.projectPath}/${page.path}` })),
- items: pages.map((page) => pageToRetrievedItem({
- projectPath: args.projectPath,
- page,
- query: args.queries.join(" | "),
- kind: "wiki",
- source: "project_file_read",
- score: 0.95,
- })),
- errorCount: errors.length,
- }
-}
-
-async function readProjectRoutingContext(
- projectPath: string,
- query: string,
- llmConfig: LlmConfig,
-): Promise<ProjectPromptContext> {
- const { indexBudget } = computeContextBudget(llmConfig.maxContextSize)
- const [purpose, overview, rawIndex] = await Promise.all([
- readFile(`${projectPath}/purpose.md`).catch(() => ""),
- readFile(`${projectPath}/wiki/overview.md`).catch(() => ""),
- readFile(`${projectPath}/wiki/index.md`).catch(() => ""),
- ])
- return {
- purpose: trimForBudget(purpose, 2500),
- overview: trimForBudget(overview, Math.min(7000, Math.max(2500, Math.floor(indexBudget * 0.4)))),
- index: trimRelevantIndex(rawIndex, query, Math.min(5000, Math.max(1800, Math.floor(indexBudget * 0.35)))),
- }
-}
-
-function formatProjectContextForRouting(context?: ProjectPromptContext): string {
- if (!context || (!context.purpose.trim() && !context.overview.trim() && !context.index.trim())) {
- return "Project context: none"
- }
- return [
- "Project context for routing:",
- context.purpose.trim() ? `## Project Purpose\n${context.purpose.trim()}` : "",
- context.overview.trim() ? `## Current Wiki Overview\n${context.overview.trim()}` : "",
- context.index.trim() ? `## Wiki Index Signals\n${context.index.trim()}` : "",
- ].filter(Boolean).join("\n\n")
-}
-
-function trimRelevantIndex(rawIndex: string, query: string, maxChars: number): string {
- if (!rawIndex.trim()) return ""
- if (rawIndex.length <= maxChars) return rawIndex
- const tokens = tokenizeIndexQuery(query)
- const lines = rawIndex.split("\n")
- const keptLines: string[] = []
- let keptSize = 0
- for (const line of lines) {
- const isHeader = line.startsWith("#")
- const lower = line.toLowerCase()
- const isRelevant = tokens.length === 0 || tokens.some((token) => lower.includes(token))
- if (!isHeader && !isRelevant) continue
- if (keptSize + line.length + 1 > maxChars) continue
- keptLines.push(line)
- keptSize += line.length + 1
- }
- return keptLines.length > 0
- ? `${keptLines.join("\n")}\n\n[...index trimmed to routing-relevant entries...]`
- : rawIndex.slice(0, Math.max(0, maxChars - 40)).trimEnd() + "\n[...index truncated...]"
-}
-
-function flattenFileTree(nodes: FileNode[], prefix: string): string[] {
- const out: string[] = []
- const walk = (items: FileNode[], base: string) => {
- for (const node of items) {
- const rel = `${base}/${node.name}`.replace(/\/+/g, "/")
- if (node.is_dir) {
- if (node.children) walk(node.children, rel)
- } else {
- out.push(rel)
- }
- }
- }
- walk(nodes, prefix)
- return out.sort((a, b) => a.localeCompare(b))
-}
-
-function normalizeProjectRelativePath(input: string): string {
- const stripped = input
- .trim()
- .replace(/^["'`]+|["'`]+$/g, "")
- .replace(/^\.\//, "")
- const normalized = normalizePath(stripped)
- .replace(/^\/+/, "")
- .replace(/^.*?\/(wiki|raw\/sources)\//, "$1/")
- if (!normalized || normalized.includes("\0")) return ""
- if (normalized.split("/").some((part) => part === ".." || part.startsWith("."))) return ""
- return normalized
-}
-
-function isReadableProjectTextPath(rel: string): boolean {
- const lower = rel.toLowerCase()
- if (!lower.startsWith("wiki/") && !lower.startsWith("raw/sources/") && lower !== "purpose.md" && lower !== "schema.md") {
- return false
- }
- return /\.(md|mdx|txt|json|yaml|yml|csv|tsv|log)$/i.test(lower)
- || lower === "purpose.md"
- || lower === "schema.md"
-}
-
-function makeStepId(steps: ChatAgentStep[]): string {
- return `step-${steps.length + 1}`
-}
-
-function emitToolCall(args: {
- tool: ChatAgentToolDefinition
- queries: string[]
- steps: ChatAgentStep[]
- onEvent?: (event: ChatAgentEvent) => void
-}): void {
- const query = args.queries.join(" | ")
- args.steps.push({
- id: makeStepId(args.steps),
- type: "tool_call",
- tool: args.tool.name,
- query,
- message: args.tool.label,
- status: "running",
- })
- args.onEvent?.({
- stage: "tool_call",
- tool: args.tool.name,
- query,
- message: args.tool.label,
- status: "running",
- })
- args.onEvent?.({
- stage: args.tool.stage,
- tool: args.tool.name,
- query,
- message: args.tool.label,
- status: "running",
- })
-}
-
-function emitToolResult(args: {
- tool: ChatAgentToolDefinition
- observation: ToolObservation
- steps: ChatAgentStep[]
- onEvent?: (event: ChatAgentEvent) => void
-}): void {
- const count = args.observation.references.length
- const status = args.observation.errorCount && count === 0 ? "error" : "success"
- const message = count > 0
- ? `${args.tool.label}: ${count} result${count === 1 ? "" : "s"}`
- : args.observation.errorCount
- ? `${args.tool.label}: failed`
- : `${args.tool.label}: no results`
- args.steps.push({
- id: makeStepId(args.steps),
- type: "tool_result",
- tool: args.tool.name,
- query: args.observation.query,
- message,
- count,
- status,
- })
- args.onEvent?.({
- stage: "tool_result",
- tool: args.tool.name,
- query: args.observation.query,
- message,
- count,
- status,
- })
-}
-
-async function runWikiSearchTool(args: {
- projectPath: string
- queries: string[]
- llmConfig: LlmConfig
- searchWikiImpl: typeof searchWiki
-}): Promise<ToolObservation> {
- const { pageBudget, maxPageSize } = computeContextBudget(args.llmConfig.maxContextSize)
- const seen = new Set<string>()
- const results: SearchResult[] = []
- for (const query of args.queries.slice(0, 3)) {
- for (const result of await args.searchWikiImpl(args.projectPath, query)) {
- const key = normalizePath(result.path)
- if (seen.has(key)) continue
- seen.add(key)
- results.push(result)
- if (results.length >= 8) break
- }
- if (results.length >= 8) break
- }
-
- const pages = await materializePages(args.projectPath, results, Math.min(pageBudget, MAX_TOOL_CONTEXT_CHARS), maxPageSize)
- return {
- tool: "wiki_search",
- query: args.queries.join(" | "),
- content: formatWikiObservation("Wiki search results", pages, results),
- references: pages.map((page) => ({ title: page.title, path: `${args.projectPath}/${page.path}`, kind: "wiki" as const })),
- pages: pages.map((page) => ({ title: page.title, path: `${args.projectPath}/${page.path}` })),
- items: pages.map((page) => pageToRetrievedItem({
- projectPath: args.projectPath,
- page,
- query: args.queries.join(" | "),
- kind: "wiki",
- source: "wiki",
- score: searchScoreForPage(page, results),
- })),
- errorCount: 0,
- }
-}
-
-async function runGraphSearchTool(args: {
- projectPath: string
- dataVersion: number
- queries: string[]
- llmConfig: LlmConfig
- searchWikiImpl: typeof searchWiki
-}): Promise<ToolObservation> {
- const base = await args.searchWikiImpl(args.projectPath, args.queries[0] ?? "")
- const graph = await buildRetrievalGraph(args.projectPath, args.dataVersion)
- const candidates = new Map<string, { title: string; path: string; relevance: number }>()
- const hitPaths = new Set(base.slice(0, 6).map((item) => normalizePath(item.path)))
-
- for (const result of base.slice(0, 6)) {
- const fileName = getFileName(result.path)
- const nodeId = fileName.replace(/\.md$/, "")
- for (const { node, relevance } of getRelatedNodes(nodeId, graph, 5)) {
- if (relevance < 1.5) continue
- if (hitPaths.has(normalizePath(node.path))) continue
- const nodePath = normalizePath(node.path)
- const absoluteNodePath = nodePath.startsWith(`${args.projectPath}/`)
- ? nodePath
- : `${args.projectPath}/${nodePath.replace(/^\/+/, "")}`
- const current = candidates.get(nodePath)
- if (!current || relevance > current.relevance) {
- candidates.set(nodePath, { title: node.title, path: absoluteNodePath, relevance })
- }
- }
- }
-
- const relatedResults: SearchResult[] = [...candidates.values()]
- .sort((a, b) => b.relevance - a.relevance)
- .slice(0, 8)
- .map((item) => ({
- path: item.path,
- title: item.title,
- snippet: `Graph relevance ${item.relevance.toFixed(2)}`,
- titleMatch: false,
- score: item.relevance,
- images: [],
- }))
-
- const pages = await materializePages(args.projectPath, relatedResults, Math.min(computeContextBudget(args.llmConfig.maxContextSize).pageBudget, 24_000), 6000)
- return {
- tool: "graph_search",
- query: args.queries.join(" | "),
- content: formatWikiObservation("Graph-related pages", pages, relatedResults),
- references: pages.map((page) => ({ title: page.title, path: `${args.projectPath}/${page.path}`, kind: "wiki" as const })),
- pages: pages.map((page) => ({ title: page.title, path: `${args.projectPath}/${page.path}` })),
- items: pages.map((page) => pageToRetrievedItem({
- projectPath: args.projectPath,
- page,
- query: args.queries.join(" | "),
- kind: "graph",
- source: "graph",
- score: searchScoreForPage(page, relatedResults),
- })),
- errorCount: 0,
- }
-}
-
-async function runExternalSearchTool(args: {
- queries: string[]
- searchConfig: SearchApiConfig
- source: "web" | "anytxt"
- llmConfig?: LlmConfig
- projectPath?: string
- webSearchImpl?: typeof webSearch
- anyTxtSearchSmartImpl?: typeof anyTxtSearchSmart
-}): Promise<ToolObservation> {
- const results: WebSearchResult[] = []
- const seen = new Set<string>()
- const errors: string[] = []
- for (const query of args.queries.slice(0, 3)) {
- try {
- const batch = args.source === "web"
- ? await args.webSearchImpl?.(query, args.searchConfig, 5) ?? []
- : await args.anyTxtSearchSmartImpl?.(query, args.searchConfig.anyTxt, args.llmConfig, 5, args.projectPath) ?? []
- for (const result of batch) {
- const key = (result.url || `${result.source}:${result.title}:${result.snippet}`).toLowerCase()
- if (seen.has(key)) continue
- seen.add(key)
- results.push(result)
- if (results.length >= 8) break
- }
- } catch (err) {
- errors.push(err instanceof Error ? err.message : String(err))
- }
- if (results.length >= 8) break
- }
-
- return {
- tool: "external_search",
- query: args.queries.join(" | "),
- content: [
- formatExternalSearchContext(results),
- errors.length > 0 ? `Errors:\n${errors.map((err) => `- ${err}`).join("\n")}` : "",
- ].filter(Boolean).join("\n\n"),
- references: results.map((result) => ({
- title: result.title,
- path: result.url,
- kind: "external" as const,
- source: result.source,
- url: result.url,
- snippet: result.snippet,
- })),
- pages: [],
- items: results.map((result, index) => externalResultToRetrievedItem(result, args.queries.join(" | "), index)),
- errorCount: errors.length,
- }
-}
-
-async function buildHistoricalObservations(args: {
- projectPath: string
- references: MessageReference[]
- llmConfig: LlmConfig
-}): Promise<ToolObservation[]> {
- const refs = dedupeReferences(args.references).slice(0, 10)
- if (refs.length === 0) return []
-
- const wikiRefs = refs.filter((ref) => ref.kind !== "external" && ref.path)
- const externalRefs = refs.filter((ref) => ref.kind === "external")
- const observations: ToolObservation[] = []
-
- if (wikiRefs.length > 0 && args.projectPath) {
- const results: SearchResult[] = wikiRefs.slice(0, 5).map((ref, index) => ({
- path: normalizeReferencePath(args.projectPath, ref.path),
- title: ref.title,
- snippet: ref.snippet ?? "Previously cited local wiki page.",
- titleMatch: false,
- score: 1 / (index + 1),
- images: [],
- }))
- const pages = await materializePages(
- args.projectPath,
- results,
- Math.min(computeContextBudget(args.llmConfig.maxContextSize).pageBudget, 18_000),
- 5000,
- )
- if (pages.length > 0) {
- observations.push({
- tool: "wiki_search",
- query: "recent local references",
- content: formatWikiObservation("Recent local retrieval history", pages, results),
- references: pages.map((page) => ({
- title: page.title,
- path: `${args.projectPath}/${page.path}`,
- kind: "wiki" as const,
- })),
- pages: pages.map((page) => ({ title: page.title, path: `${args.projectPath}/${page.path}` })),
- items: pages.map((page) => pageToRetrievedItem({
- projectPath: args.projectPath,
- page,
- query: "recent local references",
- kind: "history",
- source: "history",
- score: 0.75,
- })),
- errorCount: 0,
- })
- }
- }
-
- if (externalRefs.length > 0) {
- const results: WebSearchResult[] = externalRefs.slice(0, 8).map((ref) => ({
- title: ref.title,
- url: ref.url ?? ref.path,
- snippet: ref.snippet ?? "",
- source: ref.source ?? "external",
- }))
- observations.push({
- tool: "external_search",
- query: "recent external references",
- content: [
- "# Recent external retrieval history",
- formatExternalSearchContext(results),
- ].filter(Boolean).join("\n\n"),
- references: externalRefs,
- pages: [],
- items: results.map((result, index) => externalResultToRetrievedItem(result, "recent external references", index, "history")),
- errorCount: 0,
- })
- }
-
- return observations
-}
-
-function normalizeReferencePath(projectPath: string, path: string): string {
- const normalized = normalizePath(path)
- if (normalized.startsWith(`${projectPath}/`)) return normalized
- return `${projectPath}/${normalized.replace(/^\/+/, "")}`
-}
-
-async function materializePages(
- projectPath: string,
- results: SearchResult[],
- pageBudget: number,
- maxPageSize: number,
-): Promise<PageEntry[]> {
- let usedChars = 0
- const pages: PageEntry[] = []
- for (const [index, result] of results.entries()) {
- if (usedChars >= pageBudget) break
- try {
- const raw = await readFile(result.path)
- const relativePath = getRelativePath(result.path, projectPath)
- const truncated = raw.length > maxPageSize
- ? raw.slice(0, maxPageSize) + "\n\n[...truncated...]"
- : raw
- if (usedChars + truncated.length > pageBudget) continue
- usedChars += truncated.length
- pages.push({
- title: result.title,
- path: relativePath,
- content: truncated,
- priority: index,
- })
- } catch {
- // Skip unreadable pages; search snippets remain in the observation.
- }
- }
- return pages
-}
-
-function buildFinalMessages(args: {
- project: ChatAgentProject | null
- text: string
- historyMessages: LLMMessage[]
- observations: ToolObservation[]
- retrievedContext: RetrievedContext
- directAnswerHint?: string
- projectContext?: ProjectPromptContext
-}): LLMMessage[] {
- const hasTools = args.retrievedContext.itemCount > 0
- const hasExternalObservations = args.observations.some((obs) => obs.tool === "external_search")
- const localRefs = args.retrievedContext.references
- .filter((ref) => ref.kind !== "external")
- const pageList = localRefs.map((ref, index) => `[${index + 1}] ${ref.title} (${ref.path})`).join("\n")
-
- const system = hasTools
- ? [
- "You are a knowledgeable wiki assistant. Answer using the retrieved context below and conversation history.",
- "If the observations are insufficient, say what is missing instead of inventing facts.",
- "Keep subject boundaries strict: do not apply a claim, limitation, evaluation, benchmark result, or recommendation about one entity/model/product/method to another subject just because they share keywords.",
- "If retrieved context discusses multiple subjects, attribute each claim to the exact subject named in that context block; when uncertain, state the uncertainty instead of generalizing.",
- "Use [[wikilink]] syntax for local wiki pages when relevant.",
- "When a sentence or bullet uses retrieved context, include an inline citation immediately after that claim.",
- "Cite local context blocks with [1], [2]. Cite external context blocks with [E1], [E2].",
- "Do not rely on the separate References panel as a substitute for inline citations in the answer body.",
- hasExternalObservations
- ? [
- "External search is enabled for this conversation, and you can use external search results when they are relevant.",
- "For this answer, external search context blocks are available below; decide whether they are relevant to the user's request and use them when they help.",
- "If your answer uses any external search fact, include its [E#] citation in the same sentence or bullet.",
- "Do not apologize for lacking web access, do not say you cannot browse, and do not say you can only access the local wiki when external context blocks are present.",
- "If earlier conversation messages claimed external search was unavailable, ignore that stale claim for this turn and reason from the current available context.",
- ].join(" ")
- : "",
- "At the VERY END of your response, add a hidden comment listing which local page numbers you used:",
- " <!-- cited: 1, 3 -->",
- "",
- args.project ? `Project: ${args.project.name}` : "",
- args.projectContext?.purpose ? `## Wiki Purpose\n${args.projectContext.purpose}` : "",
- args.projectContext?.overview ? `## Wiki Overview\n${args.projectContext.overview}` : "",
- args.projectContext?.index ? `## Wiki Index\n${args.projectContext.index}` : "",
- pageList ? `## Page List\n${pageList}` : "",
- "",
- args.retrievedContext.contextText,
- "",
- buildLanguageDirective(args.text),
- ].filter(Boolean).join("\n")
- : [
- args.project
- ? `You are a wiki assistant for the project "${args.project.name}".`
- : "You are a helpful assistant.",
- "Answer directly from the conversation. Do not claim that you searched the wiki or external sources.",
- args.directAnswerHint ? `Possible answer direction: ${args.directAnswerHint}` : "",
- buildLanguageReminder(args.text),
- ].filter(Boolean).join("\n")
-
- return addLanguageReminderToLastUser([
- { role: "system", content: system },
- ...args.historyMessages,
- ], args.text)
-}
-
-function buildRetrievedContext(observations: ToolObservation[], query: string, llmConfig: LlmConfig): RetrievedContext {
- const items = fuseRetrievedItems(observations.flatMap((obs) => obs.items), query)
- const { pageBudget } = computeContextBudget(llmConfig.maxContextSize)
- const budget = Math.max(8_000, Math.min(pageBudget, MAX_TOOL_CONTEXT_CHARS))
- const blocks: string[] = []
- const references: MessageReference[] = []
- const pages: { title: string; path: string }[] = []
- let used = 0
- let localIndex = 0
- let externalIndex = 0
-
- for (const item of items) {
- const isExternal = item.reference.kind === "external"
- const refId = isExternal ? `E${++externalIndex}` : `${++localIndex}`
- const maxItemChars = isExternal ? 1800 : 6500
- const content = trimForBudget(item.content || item.snippet, Math.min(maxItemChars, Math.max(800, budget - used)))
- if (!content.trim()) continue
- const block = [
- `<context id="${refId}" source="${escapeContextAttr(item.source)}" kind="${item.kind}" title="${escapeContextAttr(item.title)}" path="${escapeContextAttr(item.url ?? item.path)}">`,
- content,
- "</context>",
- ].join("\n")
- if (used + block.length > budget && blocks.length > 0) break
- used += block.length
- blocks.push(block)
- references.push(item.reference)
- if (item.page) pages.push(item.page)
- if (used >= budget) break
- }
-
- return {
- contextText: blocks.length > 0
- ? `## Retrieved Context\n${blocks.join("\n\n---\n\n")}`
- : buildEmptyRetrievalStatus(observations),
- references: dedupeReferences(references),
- pages,
- itemCount: blocks.length || observations.length,
- }
-}
-
-function buildEmptyRetrievalStatus(observations: ToolObservation[]): string {
- if (observations.length === 0) return ""
- return [
- "## Retrieved Context",
- observations.map((obs, index) => [
- `<context id="status-${index + 1}" source="${obs.tool}" kind="status" title="Retrieval status" path="">`,
- `Query: ${obs.query}`,
- obs.content || "(no results)",
- "</context>",
- ].join("\n")).join("\n\n---\n\n"),
- ].join("\n")
-}
-
-function fuseRetrievedItems(items: RetrievedItem[], query: string): RetrievedItem[] {
- const tokens = tokenizeIndexQuery(query)
- const merged = new Map<string, RetrievedItem>()
- for (const item of items) {
- const key = retrievedItemKey(item)
- const ranked = {
- ...item,
- score: rankRetrievedItem(item, tokens),
- }
- const existing = merged.get(key)
- if (!existing || ranked.score > existing.score || ranked.content.length > existing.content.length) {
- merged.set(key, ranked)
- }
- }
- return [...merged.values()].sort((a, b) => {
- if (b.score !== a.score) return b.score - a.score
- return a.title.localeCompare(b.title)
- })
-}
-
-function rankRetrievedItem(item: RetrievedItem, tokens: string[]): number {
- const sourceWeight = item.kind === "wiki"
- ? 1
- : item.kind === "graph"
- ? 0.88
- : item.kind === "external"
- ? 0.92
- : 0.78
- const text = `${item.title}\n${item.snippet}\n${item.path}`.toLowerCase()
- const overlap = tokens.reduce((score, token) => score + (text.includes(token) ? 0.12 : 0), 0)
- const boundedSourceScore = Math.max(0, Math.min(1, item.score))
- return sourceWeight + boundedSourceScore + overlap
-}
-
-function retrievedItemKey(item: RetrievedItem): string {
- const locator = item.url || item.path || item.id
- return `${item.reference.kind ?? "wiki"}:${locator}`.toLowerCase()
-}
-
-function pageToRetrievedItem(args: {
- projectPath: string
- page: PageEntry
- query: string
- kind: Extract<RetrievedItemKind, "wiki" | "graph" | "history">
- source: string
- score: number
-}): RetrievedItem {
- const absolutePath = `${args.projectPath}/${args.page.path}`
- return {
- id: absolutePath,
- kind: args.kind,
- source: args.source,
- title: args.page.title,
- path: absolutePath,
- snippet: args.page.content.slice(0, 400),
- content: args.page.content,
- score: args.score,
- query: args.query,
- reference: { title: args.page.title, path: absolutePath, kind: "wiki" },
- page: { title: args.page.title, path: absolutePath },
- }
-}
-
-function externalResultToRetrievedItem(
- result: WebSearchResult,
- query: string,
- index: number,
- kind: Extract<RetrievedItemKind, "external" | "history"> = "external",
-): RetrievedItem {
- return {
- id: result.url || `${result.source}:${result.title}:${index}`,
- kind,
- source: result.source,
- title: result.title,
- path: result.url,
- url: result.url,
- snippet: result.snippet,
- content: result.snippet,
- score: 1 / (index + 1),
- query,
- reference: {
- title: result.title,
- path: result.url,
- kind: "external",
- source: result.source,
- url: result.url,
- snippet: result.snippet,
- },
- }
-}
-
-function searchScoreForPage(page: PageEntry, results: SearchResult[]): number {
- const normalized = normalizePath(page.path)
- const found = results.find((result) => normalizePath(result.path).endsWith(normalized))
- return found?.score ?? 1 / (page.priority + 1)
-}
-
-function trimForBudget(content: string, maxChars: number): string {
- if (content.length <= maxChars) return content
- return `${content.slice(0, Math.max(0, maxChars - 20)).trimEnd()}\n[...truncated...]`
-}
-
-function escapeContextAttr(value: string): string {
- return value.replace(/[<>"&]/g, (char) => {
- switch (char) {
- case "<": return "&lt;"
- case ">": return "&gt;"
- case "\"": return "&quot;"
- case "&": return "&amp;"
- default: return char
- }
- })
-}
-
-async function readProjectPromptContext(
- projectPath: string,
- query: string,
- llmConfig: LlmConfig,
-): Promise<ProjectPromptContext> {
- const { indexBudget } = computeContextBudget(llmConfig.maxContextSize)
- const [rawIndex, purpose, overview] = await Promise.all([
- readFile(`${projectPath}/wiki/index.md`).catch(() => ""),
- readFile(`${projectPath}/purpose.md`).catch(() => ""),
- readFile(`${projectPath}/wiki/overview.md`).catch(() => ""),
- ])
- if (rawIndex.length <= indexBudget) return { purpose, index: rawIndex, overview }
-
- const tokens = tokenizeIndexQuery(query)
- const lines = rawIndex.split("\n")
- const keptLines: string[] = []
- let keptSize = 0
- for (const line of lines) {
- const isHeader = line.startsWith("##")
- const lower = line.toLowerCase()
- const isRelevant = tokens.some((token) => lower.includes(token))
- if (!isHeader && !isRelevant) continue
- if (keptSize + line.length + 1 > indexBudget) continue
- keptLines.push(line)
- keptSize += line.length + 1
- }
- const index = keptLines.length > 0
- ? `${keptLines.join("\n")}\n\n[...index trimmed to relevant entries...]`
- : ""
- return { purpose, index, overview }
-}
-
-function tokenizeIndexQuery(query: string): string[] {
- return query
- .toLowerCase()
- .split(/[\s,,。!?、;:""''()()\-_/\\·~~…]+/)
- .map((token) => token.trim())
- .filter((token) => token.length > 1)
- .slice(0, 20)
-}
-
-function addLanguageReminderToLastUser(messages: LLMMessage[], text: string): LLMMessage[] {
- const reminder = buildLanguageReminder(text)
- if (!reminder) return messages
- const lastIdx = [...messages].reverse().findIndex((msg) => msg.role === "user")
- if (lastIdx < 0) return messages
- const idx = messages.length - 1 - lastIdx
- const target = messages[idx]
- if (!target || target.role !== "user") return messages
- const prefix = `[${reminder}]\n\n`
- const content = typeof target.content === "string"
- ? `${prefix}${target.content}`
- : addTextPrefix(target.content, prefix)
- return [
- ...messages.slice(0, idx),
- { ...target, content },
- ...messages.slice(idx + 1),
- ]
-}
-
-function addTextPrefix(content: Exclude<LLMMessage["content"], string>, prefix: string): LLMMessage["content"] {
- const blocks = [...content]
- const firstTextIdx = blocks.findIndex((block) => block.type === "text")
- if (firstTextIdx >= 0) {
- const block = blocks[firstTextIdx]
- if (block.type === "text") blocks[firstTextIdx] = { type: "text", text: `${prefix}${block.text}` }
- return blocks
- }
- return [{ type: "text", text: prefix }, ...blocks]
-}
-
-function formatWikiObservation(title: string, pages: PageEntry[], snippets: SearchResult[]): string {
- const pageText = pages.length > 0
- ? pages.map((page, index) => [
- `### [${index + 1}] ${page.title}`,
- `Path: ${page.path}`,
- "",
- page.content,
- ].join("\n")).join("\n\n---\n\n")
- : ""
-
- const snippetText = snippets.length > 0
- ? snippets.slice(0, 8).map((result, index) => [
- `- ${index + 1}. ${result.title}`,
- ` Path: ${result.path}`,
- ` Snippet: ${result.snippet}`,
- ].join("\n")).join("\n")
- : ""
-
- return [
- `# ${title}`,
- pageText,
- snippetText ? `## Search snippets\n${snippetText}` : "",
- ].filter(Boolean).join("\n\n")
-}
-
-function formatExternalSearchContext(results: WebSearchResult[]): string {
- if (results.length === 0) return ""
- return results.map((result, index) => [
- `### [E${index + 1}] ${result.title}`,
- `Source: ${result.source}`,
- `URL: ${result.url}`,
- "",
- result.snippet,
- ].join("\n")).join("\n\n---\n\n")
-}
-
-function dedupeReferences(refs: MessageReference[]): MessageReference[] {
- const seen = new Set<string>()
- const out: MessageReference[] = []
- for (const ref of refs) {
- const key = `${ref.kind ?? "wiki"}:${ref.url ?? ref.path}`.toLowerCase()
- if (seen.has(key)) continue
- seen.add(key)
- out.push(ref)
- }
- return out
-}
-
-async function collectChatText(
- llmConfig: LlmConfig,
- messages: LLMMessage[],
- streamChatImpl: typeof streamChat,
- signal?: AbortSignal,
- overrides?: Parameters<typeof streamChat>[4],
-): Promise<string> {
- let out = ""
- let error: Error | null = null
- const requestOverrides: Parameters<typeof streamChat>[4] = {
- ...overrides,
- reasoning: overrides?.reasoning ?? { mode: "off" },
- }
- await streamChatImpl(
- llmConfig,
- messages,
- {
- onToken: (token) => { out += token },
- onReasoningToken: () => {},
- onDone: () => {},
- onError: (err) => { error = err },
- },
- signal,
- requestOverrides,
- )
- if (error) throw error
- throwIfAborted(signal)
- return out
-}
-
-function throwIfAborted(signal?: AbortSignal): void {
- if (!signal?.aborted) return
- const err = new Error("Chat request aborted")
- err.name = "AbortError"
- throw err
-}
diff --git a/src/lib/persist.ts b/src/lib/persist.ts
index b607f486..e86b2486 100644
--- a/src/lib/persist.ts
+++ b/src/lib/persist.ts
@@ -2,7 +2,7 @@ import { writeFile, readFile, createDirectory } from "@/commands/fs"
import { normalizeReviewItems, type ReviewItem } from "@/stores/review-store"
import type { LintItem } from "@/stores/lint-store"
import type { DisplayMessage, Conversation } from "@/stores/chat-store"
-import type { ChatAgentMode } from "@/lib/chat-agent"
+import type { ChatAgentMode } from "@/lib/chat-agent-types"
import { normalizePath } from "@/lib/path-utils"
async function ensureDir(projectPath: string): Promise<void> {
diff --git a/src/stores/chat-store.ts b/src/stores/chat-store.ts
index 05e406e0..d662cc96 100644
--- a/src/stores/chat-store.ts
+++ b/src/stores/chat-store.ts
@@ -1,7 +1,7 @@
import { create } from "zustand"
import type { ChatMessage, ContentBlock } from "@/lib/llm-client"
import i18n from "@/i18n"
-import type { ChatAgentMode, ChatAgentStep } from "@/lib/chat-agent"
+import type { ChatAgentMode, ChatAgentStep } from "@/lib/chat-agent-types"
/**
* An image attached to a user message. Field names mirror the