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 streaming chat API

nash_su4fee1b093eac
diff --git a/README.md b/README.md
index 63353544..cf261e1f 100644
--- a/README.md
+++ b/README.md
@@ -444,7 +444,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
+- `POST /api/v1/projects/{id}/chat` — backend Agent chat endpoint for wiki/source/web/AnyTXT retrieval. JSON requests remain non-streaming by default; send `"stream": true` or `Accept: text/event-stream` for SSE events (`meta`, incremental `agent`, then `done`, `cancelled`, or `error`). The terminal `done` frame contains the complete aggregate response, so clients should not render both message deltas and the final message as separate answers. `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/src-tauri/src/api_server.rs b/src-tauri/src/api_server.rs
index 933cd176..121ae964 100644
--- a/src-tauri/src/api_server.rs
+++ b/src-tauri/src/api_server.rs
@@ -1,12 +1,14 @@
use std::collections::{BTreeMap, BTreeSet, VecDeque};
use std::fs;
-use std::io::Read;
+use std::io::{Cursor, Read};
use std::path::{Component, Path, PathBuf};
use std::sync::atomic::{AtomicU8, AtomicUsize, Ordering};
+use std::sync::mpsc::{self, Receiver, SyncSender};
use std::sync::{Mutex, OnceLock};
use std::thread;
use std::time::{Duration, Instant};
+use futures::FutureExt;
use serde::{Deserialize, Serialize};
use serde_json::{json, Map, Value};
use tauri::{AppHandle, Manager};
@@ -33,10 +35,14 @@ const APP_STATE_CACHE_TTL: Duration = Duration::from_secs(5);
const RATE_LIMIT_WINDOW: Duration = Duration::from_secs(1);
const RATE_LIMIT_MAX_REQUESTS: usize = 120;
const MAX_IN_FLIGHT_REQUESTS: usize = 64;
+const MAX_IN_FLIGHT_CHAT_STREAMS: usize = 8;
+const SSE_QUEUE_CAPACITY: usize = 64;
+const SSE_HEARTBEAT_INTERVAL: Duration = Duration::from_secs(10);
/// API status: 0=starting, 1=running, 2=port_conflict, 3=error
static API_STATUS: AtomicU8 = AtomicU8::new(0);
static IN_FLIGHT_REQUESTS: AtomicUsize = AtomicUsize::new(0);
+static IN_FLIGHT_CHAT_STREAMS: AtomicUsize = AtomicUsize::new(0);
static APP_STATE_CACHE: OnceLock<Mutex<Option<CachedAppState>>> = OnceLock::new();
static RATE_LIMIT: OnceLock<Mutex<VecDeque<Instant>>> = OnceLock::new();
@@ -135,6 +141,32 @@ impl Drop for RequestSlot {
}
}
+struct ChatStreamSlot;
+
+impl Drop for ChatStreamSlot {
+ fn drop(&mut self) {
+ IN_FLIGHT_CHAT_STREAMS.fetch_sub(1, Ordering::Relaxed);
+ }
+}
+
+fn try_acquire_chat_stream_slot() -> Option<ChatStreamSlot> {
+ let mut current = IN_FLIGHT_CHAT_STREAMS.load(Ordering::Relaxed);
+ loop {
+ if current >= MAX_IN_FLIGHT_CHAT_STREAMS {
+ return None;
+ }
+ match IN_FLIGHT_CHAT_STREAMS.compare_exchange_weak(
+ current,
+ current + 1,
+ Ordering::Relaxed,
+ Ordering::Relaxed,
+ ) {
+ Ok(_) => return Some(ChatStreamSlot),
+ Err(next) => current = next,
+ }
+ }
+}
+
fn try_acquire_request_slot() -> Option<RequestSlot> {
let mut current = IN_FLIGHT_REQUESTS.load(Ordering::Relaxed);
loop {
@@ -181,6 +213,47 @@ fn process_request(app: AppHandle, mut request: tiny_http::Request) {
}
};
+ let (path, query) = split_url(&url);
+ if wants_streaming_chat(&method, &path, &body, &headers) {
+ if !api_enabled(&app) {
+ respond_error(
+ request,
+ 503,
+ "API server is disabled in Settings → API Server",
+ origin.as_deref(),
+ );
+ return;
+ }
+ // Agent chat remains token-protected even when read-oriented API
+ // endpoints are configured for unauthenticated local access.
+ if !is_token_authorized(&app, query, &headers) {
+ respond_error(request, 401, "Unauthorized", origin.as_deref());
+ return;
+ }
+ let Some(project_id) = chat_project_id(&method, &path) else {
+ respond_error(request, 404, "Not found", origin.as_deref());
+ return;
+ };
+ let Some(stream_slot) = try_acquire_chat_stream_slot() else {
+ respond_error(
+ request,
+ 503,
+ "Too many concurrent Agent chat streams",
+ origin.as_deref(),
+ );
+ return;
+ };
+ respond_chat_sse(
+ request,
+ app,
+ project_id,
+ &body,
+ origin.as_deref(),
+ stream_slot,
+ );
+ return;
+ }
+
let response = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
handle_request(&app, &method, &url, &body, &headers)
}))
@@ -234,7 +307,8 @@ fn handle_request(
"allowLanAccess": api_allow_lan_access(app),
"agent": {
"chat": true,
- "streaming": false,
+ "streaming": true,
+ "streamProtocol": "sse",
},
}));
}
@@ -259,12 +333,9 @@ fn handle_request(
return err(405, "Method not allowed");
}
- let parts: Vec<&str> = path
- .trim_start_matches(API_PREFIX)
- .trim_start_matches('/')
- .split('/')
- .filter(|part| !part.is_empty())
- .collect();
+ let Some(parts) = api_path_parts(&path) else {
+ return err(404, "Not found");
+ };
match (method, parts.as_slice()) {
(&Method::Get, ["projects"]) => handle_projects(app),
@@ -320,12 +391,9 @@ fn allow_request() -> bool {
}
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<_>>();
+ let Some(parts) = api_path_parts(path) else {
+ return false;
+ };
method == &Method::Post
&& matches!(
parts.as_slice(),
@@ -333,15 +401,65 @@ fn is_agent_chat_request(method: &Method, path: &str) -> bool {
)
}
+fn chat_project_id<'a>(method: &Method, path: &'a str) -> Option<&'a str> {
+ if method != &Method::Post {
+ return None;
+ }
+ let parts = api_path_parts(path)?;
+ match parts.as_slice() {
+ ["projects", project_id, "chat"] => Some(*project_id),
+ _ => None,
+ }
+}
+
+fn api_path_parts(path: &str) -> Option<Vec<&str>> {
+ let remainder = path.strip_prefix(API_PREFIX)?;
+ if !remainder.is_empty() && !remainder.starts_with('/') {
+ return None;
+ }
+ Some(
+ remainder
+ .trim_start_matches('/')
+ .split('/')
+ .filter(|part| !part.is_empty())
+ .collect(),
+ )
+}
+
+fn wants_streaming_chat(
+ method: &Method,
+ path: &str,
+ body: &str,
+ headers: &[(String, String)],
+) -> bool {
+ if chat_project_id(method, path).is_none() {
+ return false;
+ }
+ let accepts_sse = headers.iter().any(|(key, value)| {
+ key == "accept"
+ && value
+ .split(',')
+ .filter_map(|part| part.trim().split(';').next())
+ .any(|media_type| media_type.trim().eq_ignore_ascii_case("text/event-stream"))
+ });
+ match serde_json::from_str::<Value>(body)
+ .ok()
+ .and_then(|value| value.get("stream").and_then(Value::as_bool))
+ {
+ Some(stream) => stream,
+ None => accepts_sse,
+ }
+}
+
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"]) {
+ let parts = api_path_parts(&path);
+ if method == &Method::Post
+ && parts
+ .as_deref()
+ .map(|parts| matches!(parts, ["projects", _, "chat"]))
+ .unwrap_or(false)
+ {
MAX_CHAT_BODY_BYTES
} else {
MAX_BODY_BYTES
@@ -1669,15 +1787,28 @@ 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}")),
- };
+struct PreparedChat {
+ project: ProjectEntry,
+ request: agent::AgentChatRequest,
+ runtime: agent::AgentRuntime,
+ user_message: String,
+ persist_session: bool,
+ session_id: String,
+ run_id: String,
+ cancellation: Option<agent::cancel::AgentCancellationToken>,
+}
+
+fn prepare_chat(
+ app: &AppHandle,
+ project_id: &str,
+ body: &str,
+) -> Result<PreparedChat, ApiResponse> {
+ let project = resolve_project(app, project_id).map_err(|e| err(404, e))?;
+ let mut req: agent::AgentChatRequest =
+ serde_json::from_str(body).map_err(|e| err(400, format!("Invalid JSON: {e}")))?;
+ if req.message.trim().is_empty() {
+ return Err(err(400, "message is required"));
+ }
if req
.session_id
.as_deref()
@@ -1726,39 +1857,70 @@ fn handle_chat(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {
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)));
+ Ok(PreparedChat {
+ project,
+ request: req,
+ runtime,
+ user_message: user_message_for_session,
+ persist_session,
+ session_id,
+ run_id,
+ cancellation: Some(cancellation),
+ })
+}
+
+fn persist_chat_response(
+ app: &AppHandle,
+ prepared: &PreparedChat,
+ response: &agent::types::AgentChatResponse,
+) {
+ if prepared.persist_session {
+ app.state::<agent::session::AgentSessionStore>()
+ .append_turn(
+ &prepared.project.path,
+ &prepared.project.id,
+ &response.session_id,
+ &prepared.user_message,
+ &response.message,
+ );
+ }
+}
+
+fn external_chat_response(mut response: agent::types::AgentChatResponse) -> Value {
+ for event in &mut response.events {
+ event.redact_for_external_api();
+ }
+ 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,
+ })
+}
+
+fn handle_chat(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {
+ let mut prepared = match prepare_chat(app, project_id, body) {
+ Ok(prepared) => prepared,
+ Err(response) => return response,
+ };
+ let result = tauri::async_runtime::block_on(prepared.runtime.run_once_with_cancel(
+ std::mem::take(&mut prepared.request),
+ prepared.cancellation.take(),
+ ));
app.state::<agent::cancel::AgentCancellationRegistry>()
- .finish(&project.id, &session_id, &run_id);
+ .finish(&prepared.project.id, &prepared.session_id, &prepared.run_id);
match result {
- Ok(mut response) => {
- if persist_session {
- app.state::<agent::session::AgentSessionStore>()
- .append_turn(
- &project.path,
- &project.id,
- &response.session_id,
- &user_message_for_session,
- &response.message,
- );
- }
- for event in &mut response.events {
- event.redact_for_external_api();
- }
- 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,
- }))
+ Ok(response) => {
+ persist_chat_response(app, &prepared, &response);
+ ok(external_chat_response(response))
}
Err(e) if e == "message is required" => err(400, e),
Err(e) if e == "Agent turn cancelled" => err(499, e),
@@ -1766,6 +1928,213 @@ fn handle_chat(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {
}
}
+struct SseReader {
+ receiver: Receiver<Vec<u8>>,
+ current: Cursor<Vec<u8>>,
+}
+
+impl SseReader {
+ fn new(receiver: Receiver<Vec<u8>>) -> Self {
+ Self {
+ receiver,
+ current: Cursor::new(Vec::new()),
+ }
+ }
+}
+
+impl Read for SseReader {
+ fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
+ if buffer.is_empty() {
+ return Ok(0);
+ }
+ loop {
+ let read = self.current.read(buffer)?;
+ if read > 0 {
+ return Ok(read);
+ }
+ match self.receiver.recv() {
+ Ok(chunk) => self.current = Cursor::new(chunk),
+ Err(_) => return Ok(0),
+ }
+ }
+ }
+}
+
+fn sse_frame(event: &str, data: &Value) -> Vec<u8> {
+ format!("event: {event}\ndata: {}\n\n", data).into_bytes()
+}
+
+enum SseSendResult {
+ Sent,
+ Full,
+ Disconnected,
+}
+
+fn try_send_sse(sender: &SyncSender<Vec<u8>>, frame: Vec<u8>) -> SseSendResult {
+ match sender.try_send(frame) {
+ Ok(()) => SseSendResult::Sent,
+ Err(mpsc::TrySendError::Full(_)) => SseSendResult::Full,
+ Err(mpsc::TrySendError::Disconnected(_)) => SseSendResult::Disconnected,
+ }
+}
+
+fn send_terminal_sse(sender: SyncSender<Vec<u8>>, frame: Vec<u8>) {
+ // A terminal frame must not be dropped when the bounded queue is briefly
+ // full, but blocking a Tokio worker would stall unrelated app work. Use a
+ // short-lived writer thread; send unblocks when the socket drains or the
+ // request reader is dropped after a disconnect.
+ thread::spawn(move || {
+ let _ = sender.send(frame);
+ });
+}
+
+fn respond_chat_sse(
+ request: tiny_http::Request,
+ app: AppHandle,
+ project_id: &str,
+ body: &str,
+ origin: Option<&str>,
+ _stream_slot: ChatStreamSlot,
+) {
+ let prepared = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+ prepare_chat(&app, project_id, body)
+ }));
+ let mut prepared = match prepared {
+ Ok(Ok(prepared)) => prepared,
+ Ok(Err(response)) => {
+ respond_json(request, response.status, response.body, origin);
+ return;
+ }
+ Err(_) => {
+ respond_error(request, 500, "Internal API server error", origin);
+ return;
+ }
+ };
+ let (sender, receiver) = mpsc::sync_channel::<Vec<u8>>(SSE_QUEUE_CAPACITY);
+ let _ = try_send_sse(
+ &sender,
+ sse_frame(
+ "meta",
+ &json!({
+ "projectId": prepared.project.id,
+ "sessionId": prepared.session_id,
+ "runId": prepared.run_id,
+ }),
+ ),
+ );
+
+ let (heartbeat_stop, heartbeat_done) = mpsc::channel::<()>();
+ let heartbeat_sender = sender.clone();
+ let heartbeat_registry = app
+ .state::<agent::cancel::AgentCancellationRegistry>()
+ .inner()
+ .clone();
+ let heartbeat_project = prepared.project.id.clone();
+ let heartbeat_session = prepared.session_id.clone();
+ let heartbeat_run = prepared.run_id.clone();
+ thread::spawn(move || loop {
+ match heartbeat_done.recv_timeout(SSE_HEARTBEAT_INTERVAL) {
+ Ok(_) | Err(mpsc::RecvTimeoutError::Disconnected) => break,
+ Err(mpsc::RecvTimeoutError::Timeout) => {
+ match try_send_sse(&heartbeat_sender, b": keepalive\n\n".to_vec()) {
+ SseSendResult::Disconnected => {
+ heartbeat_registry.cancel(
+ &heartbeat_project,
+ &heartbeat_session,
+ Some(&heartbeat_run),
+ );
+ break;
+ }
+ SseSendResult::Sent | SseSendResult::Full => {}
+ }
+ }
+ }
+ });
+
+ let task_app = app.clone();
+ tauri::async_runtime::spawn(async move {
+ let event_sender = sender.clone();
+ let registry = task_app
+ .state::<agent::cancel::AgentCancellationRegistry>()
+ .inner()
+ .clone();
+ let cancel_project = prepared.project.id.clone();
+ let cancel_session = prepared.session_id.clone();
+ let cancel_run = prepared.run_id.clone();
+ let sink: agent::runtime::AgentEventSink = std::sync::Arc::new(move |mut event| {
+ event.redact_for_external_api();
+ let payload = serde_json::to_value(event)
+ .unwrap_or_else(|err| json!({ "type": "error", "message": err.to_string() }));
+ match try_send_sse(&event_sender, sse_frame("agent", &payload)) {
+ SseSendResult::Disconnected => {
+ registry.cancel(&cancel_project, &cancel_session, Some(&cancel_run));
+ }
+ // Intermediate events may be dropped for a temporarily slow
+ // client. The terminal `done` frame still carries the complete
+ // aggregate response, so correctness is preserved.
+ SseSendResult::Sent | SseSendResult::Full => {}
+ }
+ });
+ let result =
+ std::panic::AssertUnwindSafe(prepared.runtime.run_once_with_cancel_and_events(
+ std::mem::take(&mut prepared.request),
+ prepared.cancellation.take(),
+ Some(sink),
+ ))
+ .catch_unwind()
+ .await;
+ task_app
+ .state::<agent::cancel::AgentCancellationRegistry>()
+ .finish(&prepared.project.id, &prepared.session_id, &prepared.run_id);
+ match result {
+ Ok(Ok(response)) => {
+ persist_chat_response(&task_app, &prepared, &response);
+ send_terminal_sse(
+ sender.clone(),
+ sse_frame("done", &external_chat_response(response)),
+ );
+ }
+ Ok(Err(message)) => {
+ let event = if message == "Agent turn cancelled" {
+ "cancelled"
+ } else {
+ "error"
+ };
+ send_terminal_sse(
+ sender.clone(),
+ sse_frame(event, &json!({ "ok": false, "error": message })),
+ );
+ }
+ Err(_) => {
+ send_terminal_sse(
+ sender.clone(),
+ sse_frame(
+ "error",
+ &json!({ "ok": false, "error": "Agent chat task panicked" }),
+ ),
+ );
+ }
+ }
+ let _ = heartbeat_stop.send(());
+ });
+
+ let mut response = Response::new(
+ StatusCode(200),
+ vec![
+ Header::from_bytes("Content-Type", "text/event-stream; charset=utf-8").unwrap(),
+ Header::from_bytes("Cache-Control", "no-cache, no-transform").unwrap(),
+ Header::from_bytes("X-Accel-Buffering", "no").unwrap(),
+ ],
+ SseReader::new(receiver),
+ None,
+ None,
+ );
+ for header in cors_headers(origin) {
+ response.add_header(header);
+ }
+ let _ = request.respond(response);
+}
+
fn handle_cancel_chat(app: &AppHandle, project_id: &str, session_id: &str) -> ApiResponse {
let project = match resolve_project(app, project_id) {
Ok(project) => project,
@@ -2725,6 +3094,119 @@ mod tests {
));
}
+ #[test]
+ fn chat_streaming_is_enabled_by_body_or_accept_header() {
+ let path = "/api/v1/projects/current/chat";
+ assert!(wants_streaming_chat(
+ &Method::Post,
+ path,
+ r#"{"message":"hello","stream":true}"#,
+ &[],
+ ));
+ assert!(wants_streaming_chat(
+ &Method::Post,
+ path,
+ r#"{"message":"hello"}"#,
+ &[(
+ "accept".to_string(),
+ "application/json, text/event-stream; q=0.9".to_string(),
+ )],
+ ));
+ assert!(!wants_streaming_chat(
+ &Method::Post,
+ path,
+ r#"{"message":"hello","stream":false}"#,
+ &[],
+ ));
+ assert!(!wants_streaming_chat(
+ &Method::Post,
+ path,
+ r#"{"message":"hello","stream":false}"#,
+ &[("accept".to_string(), "text/event-stream".to_string())],
+ ));
+ assert!(!wants_streaming_chat(
+ &Method::Post,
+ "/api/v1/projects/current/search",
+ r#"{"stream":true}"#,
+ &[],
+ ));
+ assert!(!wants_streaming_chat(
+ &Method::Post,
+ "/api/v1/projects/current/chat/s1/cancel",
+ r#"{"stream":true}"#,
+ &[],
+ ));
+ assert!(!wants_streaming_chat(
+ &Method::Post,
+ "/projects/current/chat",
+ r#"{"stream":true}"#,
+ &[],
+ ));
+ assert!(!wants_streaming_chat(
+ &Method::Post,
+ "/api/v1/api/v1/projects/current/chat",
+ r#"{"stream":true}"#,
+ &[],
+ ));
+ }
+
+ #[test]
+ fn sse_reader_preserves_event_frames_until_sender_closes() {
+ let (sender, receiver) = mpsc::sync_channel(4);
+ sender
+ .send(sse_frame("meta", &json!({ "sessionId": "s1" })))
+ .unwrap();
+ sender
+ .send(sse_frame(
+ "agent",
+ &json!({ "type": "messageDelta", "text": "Hi" }),
+ ))
+ .unwrap();
+ drop(sender);
+
+ let mut body = String::new();
+ let mut reader = SseReader::new(receiver);
+ assert_eq!(reader.read(&mut []).unwrap(), 0);
+ reader.read_to_string(&mut body).unwrap();
+ assert!(body.contains("event: meta\n"));
+ assert!(body.contains(r#"data: {"sessionId":"s1"}"#));
+ assert!(body.contains("event: agent\n"));
+ assert!(body.contains(r#""type":"messageDelta""#));
+ }
+
+ #[test]
+ fn sse_queue_rejects_backpressure_without_blocking_runtime_threads() {
+ let (sender, _receiver) = mpsc::sync_channel(1);
+ assert!(matches!(
+ try_send_sse(&sender, b"first".to_vec()),
+ SseSendResult::Sent
+ ));
+ assert!(matches!(
+ try_send_sse(&sender, b"second".to_vec()),
+ SseSendResult::Full
+ ));
+ }
+
+ #[test]
+ fn sse_queue_reports_disconnected_clients() {
+ let (sender, receiver) = mpsc::sync_channel(1);
+ drop(receiver);
+ assert!(matches!(
+ try_send_sse(&sender, b"event".to_vec()),
+ SseSendResult::Disconnected
+ ));
+ }
+
+ #[test]
+ fn terminal_sse_waits_for_queue_capacity() {
+ let (sender, receiver) = mpsc::sync_channel(1);
+ sender.send(b"agent".to_vec()).unwrap();
+ send_terminal_sse(sender, b"done".to_vec());
+
+ assert_eq!(receiver.recv().unwrap(), b"agent");
+ assert_eq!(receiver.recv().unwrap(), b"done");
+ }
+
#[test]
fn api_config_shape_parses_enabled_and_unauthenticated_access() {
// Standalone pure-function check to mirror what `api_enabled`
diff --git a/src/components/settings/sections/api-server-section.tsx b/src/components/settings/sections/api-server-section.tsx
index be8d2ebb..113ca975 100644
--- a/src/components/settings/sections/api-server-section.tsx
+++ b/src/components/settings/sections/api-server-section.tsx
@@ -54,12 +54,13 @@ export const API_ENDPOINTS: Array<{ method: "GET" | "POST" | "PATCH"; path: stri
{ method: "GET", path: "/api/v1/projects/{id}/graph", noteKey: "endpointGraphNote" },
{ method: "POST", path: "/api/v1/projects/{id}/sources/rescan", noteKey: "endpointRescanNote" },
{ method: "POST", path: "/api/v1/projects/{id}/chat", noteKey: "endpointChatNote" },
+ { method: "POST", path: "/api/v1/projects/{id}/chat/{sessionId}/cancel", noteKey: "endpointChatCancelNote" },
]
export function ApiServerSection({ draft, setDraft }: Props) {
const { t } = useTranslation()
const [showToken, setShowToken] = useState(false)
- const [copiedField, setCopiedField] = useState<"token" | "curl" | "mcp" | null>(null)
+ const [copiedField, setCopiedField] = useState<"token" | "curl" | "chat" | "mcp" | null>(null)
const [serverStatus, setServerStatus] = useState<string>("...")
const [health, setHealth] = useState<ApiHealth | null>(null)
const [mcpEntryPath, setMcpEntryPath] = useState<string | null>(null)
@@ -123,14 +124,30 @@ export function ApiServerSection({ draft, setDraft }: Props) {
// header is the recommended auth (never put the token in URL
// query — it leaks into logs / shell history / Referer).
const tokenForExample = draft.apiToken || "<your-token>"
- return `curl -H 'Authorization: Bearer ${tokenForExample}' ${API_SERVER_BASE_URL}/api/v1/projects`
+ return `curl -H "Authorization: Bearer ${tokenForExample}" ${API_SERVER_BASE_URL}/api/v1/projects`
}, [draft.apiAllowUnauthenticated, draft.apiToken])
+ const sampleChatCurl = useMemo(() => {
+ const tokenForExample = health?.tokenSource === "env"
+ ? "$LLM_WIKI_API_TOKEN"
+ : draft.apiToken || "<your-token>"
+ return `curl -N -X POST \\
+ -H "Authorization: Bearer ${tokenForExample}" \\
+ -H 'Content-Type: application/json' \\
+ -H 'Accept: text/event-stream' \\
+ ${API_SERVER_BASE_URL}/api/v1/projects/current/chat \\
+ -d '{"message":"Summarize this knowledge base.","stream":true}'`
+ }, [draft.apiToken, health?.tokenSource])
+
const sampleMcpConfig = useMemo(() => {
if (!mcpEntryPath) return ""
- const env = draft.apiAllowUnauthenticated
- ? {}
- : { LLM_WIKI_API_TOKEN: draft.apiToken || "<your-token>" }
+ const env = health?.tokenSource === "env"
+ ? { LLM_WIKI_API_TOKEN: "<same value as the LLM Wiki process environment>" }
+ : draft.apiToken
+ ? { LLM_WIKI_API_TOKEN: draft.apiToken }
+ : draft.apiAllowUnauthenticated
+ ? {}
+ : { LLM_WIKI_API_TOKEN: "<your-token>" }
return JSON.stringify(
{
mcpServers: {
@@ -144,7 +161,7 @@ export function ApiServerSection({ draft, setDraft }: Props) {
null,
2,
)
- }, [draft.apiAllowUnauthenticated, draft.apiToken, mcpEntryPath])
+ }, [draft.apiAllowUnauthenticated, draft.apiToken, health?.tokenSource, mcpEntryPath])
const hasUnsavedApiConfig =
persistedApiConfig.enabled !== draft.apiEnabled ||
@@ -163,6 +180,16 @@ export function ApiServerSection({ draft, setDraft }: Props) {
}
}, [sampleCurl])
+ const handleCopyChatCurl = useCallback(async () => {
+ try {
+ await navigator.clipboard.writeText(sampleChatCurl)
+ setCopiedField("chat")
+ setTimeout(() => setCopiedField(null), 1500)
+ } catch (err) {
+ console.error("[api-settings] copy streaming chat curl failed:", err)
+ }
+ }, [sampleChatCurl])
+
const handleCopyMcpConfig = useCallback(async () => {
if (!mcpEntryPath) return
try {
@@ -334,7 +361,7 @@ export function ApiServerSection({ draft, setDraft }: Props) {
</Button>
<span className="text-[11px] text-muted-foreground">
{t("settings.sections.apiServer.openHealthHint", {
- defaultValue: "Opens in your system browser. /health is the only unauthenticated endpoint.",
+ defaultValue: "/health never requires authentication. Other endpoints follow the access mode below, except Agent chat, which always requires a token.",
})}
</span>
</div>
@@ -349,7 +376,7 @@ export function ApiServerSection({ draft, setDraft }: Props) {
<p className="mt-1 text-xs leading-relaxed text-muted-foreground">
{t("settings.sections.apiServer.tokenHint", {
defaultValue:
- "Required unless unauthenticated access is enabled. Send as `Authorization: Bearer <token>` or `X-LLM-Wiki-Token: <token>`. The environment variable LLM_WIKI_API_TOKEN overrides this field if set.",
+ "Send as `Authorization: Bearer <token>` or `X-LLM-Wiki-Token: <token>`. Read-oriented endpoints may omit it when unauthenticated access is enabled, but Agent chat and cancellation always require it. The environment variable LLM_WIKI_API_TOKEN overrides this field if set.",
})}
</p>
</div>
@@ -414,14 +441,14 @@ export function ApiServerSection({ draft, setDraft }: Props) {
{tokenStrength === "missing" && (
<span className="text-xs text-amber-700 dark:text-amber-400">
{t("settings.sections.apiServer.tokenMissing", {
- defaultValue: "No token — every endpoint will return 401",
+ defaultValue: "No token — Agent chat is unavailable and protected endpoints return 401",
})}
</span>
)}
- {tokenStrength === "unused" && (
+ {tokenStrength === "unused" && health?.tokenSource !== "env" && (
<span className="text-xs text-amber-700 dark:text-amber-400">
{t("settings.sections.apiServer.tokenUnused", {
- defaultValue: "Token is not used while unauthenticated access is enabled",
+ defaultValue: "Read endpoints are open, but Agent chat still uses this token",
})}
</span>
)}
@@ -497,6 +524,53 @@ export function ApiServerSection({ draft, setDraft }: Props) {
</div>
{/* ── Endpoint catalog ──────────────────────────────────────── */}
+ <div className="space-y-3 rounded-lg border border-border/60 bg-muted/20 p-4">
+ <div className="flex items-start justify-between gap-3">
+ <div>
+ <h3 className="text-sm font-semibold">
+ {t("settings.sections.apiServer.chatTitle", { defaultValue: "Agent chat and streaming" })}
+ </h3>
+ <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
+ {t("settings.sections.apiServer.chatHint", {
+ defaultValue:
+ "POST a message to /chat. The default response is one JSON document. Set stream: true or send Accept: text/event-stream to receive SSE frames while the Agent works.",
+ })}
+ </p>
+ </div>
+ <Button type="button" variant="outline" size="sm" onClick={handleCopyChatCurl} disabled={hasUnsavedApiConfig} className="shrink-0 gap-1.5">
+ <Copy className="h-3.5 w-3.5" />
+ {copiedField === "chat"
+ ? t("settings.sections.apiServer.copied", { defaultValue: "Copied" })
+ : t("settings.sections.apiServer.copy", { defaultValue: "Copy" })}
+ </Button>
+ </div>
+ <div className="grid gap-2 text-xs sm:grid-cols-2">
+ <div className="rounded-md border border-border/60 bg-background/40 px-3 py-2">
+ <div className="font-medium">{t("settings.sections.apiServer.chatJsonTitle", { defaultValue: "JSON mode" })}</div>
+ <p className="mt-1 leading-relaxed text-muted-foreground">
+ {t("settings.sections.apiServer.chatJsonHint", { defaultValue: "Omit stream or set it to false. The request returns after the complete Agent turn." })}
+ </p>
+ </div>
+ <div className="rounded-md border border-border/60 bg-background/40 px-3 py-2">
+ <div className="font-medium">{t("settings.sections.apiServer.chatSseTitle", { defaultValue: "SSE mode" })}</div>
+ <p className="mt-1 leading-relaxed text-muted-foreground">
+ {t("settings.sections.apiServer.chatSseHint", { defaultValue: "Frames: meta, incremental agent events, then done, cancelled, or error. done contains the complete aggregate response." })}
+ </p>
+ </div>
+ </div>
+ <div className="flex items-start gap-2 text-xs leading-relaxed text-amber-700 dark:text-amber-400">
+ <ShieldAlert className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+ <span>
+ {t("settings.sections.apiServer.chatTokenRequired", { defaultValue: "Agent chat and its cancellation endpoint always require a token, even when read endpoints allow unauthenticated access." })}
+ </span>
+ </div>
+ <pre className="overflow-x-auto whitespace-pre-wrap break-all rounded-md bg-background/60 px-3 py-2 text-[11px] font-mono leading-relaxed">
+ {hasUnsavedApiConfig
+ ? t("settings.sections.apiServer.saveFirstExample", { defaultValue: "Save settings first, then copy an example request." })
+ : sampleChatCurl}
+ </pre>
+ </div>
+
<div className="space-y-2 rounded-lg border border-border/60 bg-muted/20 p-4">
<h3 className="text-sm font-semibold">
{t("settings.sections.apiServer.endpoints", { defaultValue: "Endpoints" })}
diff --git a/src/i18n/en.json b/src/i18n/en.json
index ad3fd6a3..e484b6e0 100644
--- a/src/i18n/en.json
+++ b/src/i18n/en.json
@@ -776,7 +776,7 @@
"statusUnknown": "Unknown",
"baseUrl": "Base URL",
"openHealth": "Open /health",
- "openHealthHint": "Opens in your system browser. /health is the only unauthenticated endpoint.",
+ "openHealthHint": "/health never requires authentication. Other endpoints follow the access mode below, except Agent chat, which always requires a token.",
"allowUnauthenticated": "Allow access without a token",
"allowUnauthenticatedHint": "Use only for trusted local agents. Any process or browser page on this machine can call the API while this is enabled.",
"allowLanAccess": "Allow API and Clip server access from the local network",
@@ -787,15 +787,15 @@
"mcpUsageHint": "Build once with `npm run mcp:build`, then configure your MCP client to run the server below. Use LLM_WIKI_API_TOKEN unless unauthenticated access is enabled.",
"mcpPathUnavailable": "MCP server entry was not found. Run `npm run mcp:build` from the LLM Wiki repository, then reopen Settings.",
"token": "Access token",
- "tokenHint": "Required unless unauthenticated access is enabled. Send as `Authorization: Bearer <token>` or `X-LLM-Wiki-Token: <token>`. The environment variable LLM_WIKI_API_TOKEN overrides this field if set.",
+ "tokenHint": "Send as `Authorization: Bearer <token>` or `X-LLM-Wiki-Token: <token>`. Read endpoints may omit it when unauthenticated access is enabled, but Agent chat and cancellation always require it. The environment variable LLM_WIKI_API_TOKEN overrides this field if set.",
"tokenPlaceholder": "Paste an existing token or click Generate",
"generate": "Generate new token",
"show": "Show",
"hide": "Hide",
"copy": "Copy",
"copied": "Copied",
- "tokenMissing": "No token — every endpoint will return 401",
- "tokenUnused": "Token is not used while unauthenticated access is enabled",
+ "tokenMissing": "No token — Agent chat is unavailable and protected endpoints return 401",
+ "tokenUnused": "Read endpoints are open, but Agent chat still uses this token",
"envTokenActive": "LLM_WIKI_API_TOKEN is active and overrides this field",
"tokenWeak": "Token is short — consider Generate for 256-bit entropy",
"saveFirst": "Save settings to apply API/MCP changes",
@@ -803,6 +803,13 @@
"tokenWarning": "Keep this token secret. Anyone with the token on this machine can read your project files via localhost.",
"tokenQueryWarning": "Prefer the Authorization header — passing ?token=… via URL leaks the value into shell history, logs, and Referer headers.",
"sample": "Example request",
+ "chatTitle": "Agent chat and streaming",
+ "chatHint": "POST a message to /chat. The default response is one JSON document. Set stream: true or send Accept: text/event-stream to receive SSE frames while the Agent works.",
+ "chatJsonTitle": "JSON mode",
+ "chatJsonHint": "Omit stream or set it to false. The request returns after the complete Agent turn.",
+ "chatSseTitle": "SSE mode",
+ "chatSseHint": "Frames: meta, incremental agent events, then done, cancelled, or error. done contains the complete aggregate response.",
+ "chatTokenRequired": "Agent chat and its cancellation endpoint always require a token, even when read endpoints allow unauthenticated access.",
"endpoints": "Endpoints",
"endpointsHint": "Replace {id} with a project UUID, a project filesystem path, or the literal 'current'.",
"endpointHealthNote": "Liveness probe. No auth.",
@@ -815,7 +822,8 @@
"endpointSearchNote": "JSON body: { query, topK?, includeContent?, queryEmbedding? }. Uses shared keyword + vector retrieval when embeddings are configured.",
"endpointGraphNote": "?q=…&nodeType=…&limit=N — wikilinks graph derived from wiki/*.md.",
"endpointRescanNote": "Triggers a backend rescan using your Source Watch config.",
- "endpointChatNote": "Not implemented yet (returns 501)."
+ "endpointChatNote": "Agent chat. Returns JSON by default; use stream: true or Accept: text/event-stream for SSE. A token is always required.",
+ "endpointChatCancelNote": "Cancels the active Agent turn for a session. A token is always required."
},
"output": {
"title": "Output Preferences",
diff --git a/src/i18n/it.json b/src/i18n/it.json
index d4355f3c..c50679b1 100644
--- a/src/i18n/it.json
+++ b/src/i18n/it.json
@@ -776,7 +776,7 @@
"statusUnknown": "Sconosciuto",
"baseUrl": "URL di base",
"openHealth": "Apri /health",
- "openHealthHint": "Si apre nel browser di sistema. /health è l'unico endpoint senza autenticazione.",
+ "openHealthHint": "/health non richiede mai autenticazione. Gli altri endpoint seguono la modalità di accesso seguente, tranne la chat Agent che richiede sempre un token.",
"allowUnauthenticated": "Consenti l'accesso senza token",
"allowUnauthenticatedHint": "Usalo solo con agent locali fidati. Con questa opzione attiva, qualsiasi processo o pagina del browser su questa macchina può chiamare l'API.",
"allowLanAccess": "Consenti l'accesso ad API e server Clip dalla rete locale",
@@ -787,15 +787,15 @@
"mcpUsageHint": "Compila una volta con `npm run mcp:build`, poi configura il tuo client MCP per avviare il server qui sotto. Usa LLM_WIKI_API_TOKEN a meno che non sia attivo l'accesso senza autenticazione.",
"mcpPathUnavailable": "Entry point del server MCP non trovato. Esegui `npm run mcp:build` dal repository di LLM Wiki, poi riapri le Impostazioni.",
"token": "Token di accesso",
- "tokenHint": "Obbligatorio se non è attivo l'accesso senza autenticazione. Invialo come `Authorization: Bearer <token>` oppure `X-LLM-Wiki-Token: <token>`. Se impostata, la variabile d'ambiente LLM_WIKI_API_TOKEN ha la precedenza su questo campo.",
+ "tokenHint": "Invialo come `Authorization: Bearer <token>` oppure `X-LLM-Wiki-Token: <token>`. Gli endpoint di lettura possono ometterlo quando l'accesso senza autenticazione è attivo, ma chat Agent e annullamento lo richiedono sempre. LLM_WIKI_API_TOKEN ha la precedenza.",
"tokenPlaceholder": "Incolla un token esistente o clicca su Genera",
"generate": "Genera un nuovo token",
"show": "Mostra",
"hide": "Nascondi",
"copy": "Copia",
"copied": "Copiato",
- "tokenMissing": "Nessun token — ogni endpoint restituirà 401",
- "tokenUnused": "Il token non viene usato mentre è attivo l'accesso senza autenticazione",
+ "tokenMissing": "Nessun token — la chat Agent non è disponibile e gli endpoint protetti restituiscono 401",
+ "tokenUnused": "Gli endpoint di lettura sono aperti, ma la chat Agent usa ancora questo token",
"envTokenActive": "LLM_WIKI_API_TOKEN è attiva e ha la precedenza su questo campo",
"tokenWeak": "Token corto — valuta Genera per avere 256 bit di entropia",
"saveFirst": "Salva le impostazioni per applicare le modifiche ad API/MCP",
@@ -803,6 +803,13 @@
"tokenWarning": "Tieni segreto questo token. Chiunque lo possieda su questa macchina può leggere i file del tuo progetto tramite localhost.",
"tokenQueryWarning": "Meglio usare l'header Authorization: passare ?token=… nell'URL espone il valore nella cronologia della shell, nei log e negli header Referer.",
"sample": "Richiesta di esempio",
+ "chatTitle": "Chat Agent e streaming",
+ "chatHint": "Invia un messaggio POST a /chat. Per impostazione predefinita viene restituito un documento JSON completo. Imposta stream: true o Accept: text/event-stream per ricevere eventi SSE durante l'esecuzione.",
+ "chatJsonTitle": "Modalità JSON",
+ "chatJsonHint": "Ometti stream o impostalo su false. La risposta arriva al termine del turno Agent completo.",
+ "chatSseTitle": "Modalità SSE",
+ "chatSseHint": "Eventi: meta, eventi agent incrementali, quindi done, cancelled o error. done contiene la risposta aggregata completa.",
+ "chatTokenRequired": "Chat Agent e annullamento richiedono sempre un token, anche quando gli endpoint di lettura consentono accesso senza autenticazione.",
"endpoints": "Endpoint",
"endpointsHint": "Sostituisci {id} con l'UUID di un progetto, con il percorso del progetto sul filesystem o con la parola 'current'.",
"endpointHealthNote": "Sonda di liveness. Nessuna autenticazione.",
@@ -815,7 +822,8 @@
"endpointSearchNote": "Corpo JSON: { query, topK?, includeContent?, queryEmbedding? }. Usa il recupero condiviso per parole chiave e vettori quando gli embedding sono configurati.",
"endpointGraphNote": "?q=…&nodeType=…&limit=N — grafo dei wikilink derivato da wiki/*.md.",
"endpointRescanNote": "Avvia una nuova scansione lato backend con la tua configurazione di Monitoraggio fonti.",
- "endpointChatNote": "Non ancora implementato (restituisce 501)."
+ "endpointChatNote": "Chat Agent. Restituisce JSON per impostazione predefinita; usa stream: true o Accept: text/event-stream per SSE. Richiede sempre un token.",
+ "endpointChatCancelNote": "Annulla il turno Agent attivo per una sessione. Richiede sempre un token."
},
"output": {
"title": "Preferenze di output",
diff --git a/src/i18n/ru.json b/src/i18n/ru.json
index a7c5c964..c7cdad3c 100644
--- a/src/i18n/ru.json
+++ b/src/i18n/ru.json
@@ -776,7 +776,7 @@
"statusUnknown": "Неизвестно",
"baseUrl": "Базовый URL",
"openHealth": "Открыть /health",
- "openHealthHint": "Открывается в системном браузере. /health — единственный эндпоинт без аутентификации.",
+ "openHealthHint": "/health никогда не требует аутентификации. Остальные эндпоинты следуют режиму ниже, кроме чата Agent, которому всегда нужен токен.",
"allowUnauthenticated": "Разрешить доступ без токена",
"allowUnauthenticatedHint": "Используйте только для доверенных локальных агентов. Пока включено, любой процесс или страница браузера на этом компьютере может обращаться к API.",
"allowLanAccess": "Разрешить доступ к API и серверу Clip из локальной сети",
@@ -787,15 +787,15 @@
"mcpUsageHint": "Соберите один раз с помощью `npm run mcp:build`, затем настройте MCP-клиент на запуск сервера ниже. Используйте LLM_WIKI_API_TOKEN, если не включён доступ без аутентификации.",
"mcpPathUnavailable": "Точка входа MCP-сервера не найдена. Выполните `npm run mcp:build` из репозитория LLM Wiki, затем откройте Настройки заново.",
"token": "Токен доступа",
- "tokenHint": "Обязателен, если не включён доступ без аутентификации. Отправляйте как `Authorization: Bearer <token>` или `X-LLM-Wiki-Token: <token>`. Переменная окружения LLM_WIKI_API_TOKEN переопределяет это поле, если задана.",
+ "tokenHint": "Отправляйте как `Authorization: Bearer <token>` или `X-LLM-Wiki-Token: <token>`. Эндпоинты чтения могут обходиться без него в открытом режиме, но чат Agent и отмена всегда требуют токен. LLM_WIKI_API_TOKEN имеет приоритет.",
"tokenPlaceholder": "Вставьте существующий токен или нажмите «Сгенерировать»",
"generate": "Сгенерировать новый токен",
"show": "Показать",
"hide": "Скрыть",
"copy": "Копировать",
"copied": "Скопировано",
- "tokenMissing": "Нет токена — каждый эндпоинт вернёт 401",
- "tokenUnused": "Токен не используется, пока включён доступ без аутентификации",
+ "tokenMissing": "Нет токена — чат Agent недоступен, а защищённые эндпоинты вернут 401",
+ "tokenUnused": "Эндпоинты чтения открыты, но чат Agent всё ещё использует этот токен",
"envTokenActive": "LLM_WIKI_API_TOKEN активна и переопределяет это поле",
"tokenWeak": "Токен короткий — нажмите «Сгенерировать» для энтропии в 256 бит",
"saveFirst": "Сохраните настройки, чтобы применить изменения API/MCP",
@@ -803,6 +803,13 @@
"tokenWarning": "Храните этот токен в секрете. Любой, у кого есть токен на этом компьютере, сможет читать файлы вашего проекта через localhost.",
"tokenQueryWarning": "Предпочитайте заголовок Authorization — передача ?token=… в URL раскрывает значение в истории оболочки, логах и Referer-заголовках.",
"sample": "Пример запроса",
+ "chatTitle": "Чат Agent и потоковый вывод",
+ "chatHint": "Отправьте POST-сообщение на /chat. По умолчанию возвращается один JSON после завершения. Задайте stream: true или Accept: text/event-stream для SSE.",
+ "chatJsonTitle": "Режим JSON",
+ "chatJsonHint": "Не передавайте stream или задайте false. Ответ придёт после полного хода Agent.",
+ "chatSseTitle": "Режим SSE",
+ "chatSseHint": "События: meta, потоковые agent, затем done, cancelled или error. done содержит полный итоговый ответ.",
+ "chatTokenRequired": "Чат Agent и его отмена всегда требуют токен, даже если эндпоинты чтения открыты.",
"endpoints": "Эндпоинты",
"endpointsHint": "Замените {id} на UUID проекта, путь к файловой системе проекта или литерал 'current'.",
"endpointHealthNote": "Проверка активности. Без авторизации.",
@@ -815,7 +822,8 @@
"endpointSearchNote": "JSON-тело: { query, topK?, includeContent?, queryEmbedding? }. Использует общий поиск по ключевым словам и векторам, если настроены эмбеддинги.",
"endpointGraphNote": "?q=…&nodeType=…&limit=N — граф вики-ссылок, построенный из wiki/*.md.",
"endpointRescanNote": "Запускает пересканирование бэкенда с использованием вашей конфигурации «Мониторинг источников».",
- "endpointChatNote": "Пока не реализовано (возвращает 501)."
+ "endpointChatNote": "Чат Agent. По умолчанию возвращает JSON; для SSE используйте stream: true или Accept: text/event-stream. Всегда требуется токен.",
+ "endpointChatCancelNote": "Отменяет активный ход Agent для сессии. Всегда требуется токен."
},
"output": {
"title": "Настройки вывода",
diff --git a/src/i18n/zh.json b/src/i18n/zh.json
index ee4127fe..f228403f 100644
--- a/src/i18n/zh.json
+++ b/src/i18n/zh.json
@@ -776,7 +776,7 @@
"statusUnknown": "未知",
"baseUrl": "服务地址",
"openHealth": "打开 /health",
- "openHealthHint": "在系统浏览器中打开。/health 是唯一不需要 token 的接口。",
+ "openHealthHint": "/health 始终无需鉴权。其他接口遵循下方的访问模式,但 Agent 对话始终需要 token。",
"allowUnauthenticated": "允许无 token 访问",
"allowUnauthenticatedHint": "仅用于可信的本地智能体。启用后,这台机器上的任何进程或浏览器页面都可以调用 API。",
"allowLanAccess": "允许 API 和 Clip server 局域网访问",
@@ -787,15 +787,15 @@
"mcpUsageHint": "先执行一次 `npm run mcp:build`,然后让 MCP 客户端运行下面的服务配置。除非启用了无认证访问,否则需要设置 LLM_WIKI_API_TOKEN。",
"mcpPathUnavailable": "没有找到 MCP 服务入口。请在 LLM Wiki 仓库中先执行 `npm run mcp:build`,然后重新打开设置。",
"token": "访问令牌",
- "tokenHint": "除非启用了无认证访问,否则必须配置。通过 `Authorization: Bearer <token>` 或 `X-LLM-Wiki-Token: <token>` 发送。设置了环境变量 LLM_WIKI_API_TOKEN 时优先生效。",
+ "tokenHint": "通过 `Authorization: Bearer <token>` 或 `X-LLM-Wiki-Token: <token>` 发送。启用无认证访问后,读取类接口可以省略 token,但 Agent 对话和取消接口始终需要 token。环境变量 LLM_WIKI_API_TOKEN 优先生效。",
"tokenPlaceholder": "粘贴已有 token,或点击生成",
"generate": "生成新 token",
"show": "显示",
"hide": "隐藏",
"copy": "复制",
"copied": "已复制",
- "tokenMissing": "未配置 token —— 所有接口都会返回 401",
- "tokenUnused": "启用无认证访问时,token 不会参与鉴权",
+ "tokenMissing": "未配置 token —— Agent 对话不可用,受保护的接口会返回 401",
+ "tokenUnused": "读取类接口已开放,但 Agent 对话仍使用此 token",
"envTokenActive": "LLM_WIKI_API_TOKEN 正在生效,并会覆盖此处填写的 token",
"tokenWeak": "token 长度偏短 —— 建议使用「生成新 token」获得 256 位熵",
"saveFirst": "保存设置后 API/MCP 改动才会生效",
@@ -803,6 +803,13 @@
"tokenWarning": "请妥善保管。任何能访问这台机器 localhost 的进程拿到 token 后,都能通过 API 读取你的项目内容。",
"tokenQueryWarning": "推荐使用 Authorization header —— 将 token 放在 ?token=… 查询参数里会泄露到 shell 历史、日志和 Referer。",
"sample": "示例请求",
+ "chatTitle": "Agent 对话与流式输出",
+ "chatHint": "向 /chat POST 消息。默认在 Agent 完成后返回一个 JSON 文档;设置 stream: true 或发送 Accept: text/event-stream 可在执行过程中接收 SSE 事件。",
+ "chatJsonTitle": "JSON 模式",
+ "chatJsonHint": "省略 stream 或设为 false。请求会在完整 Agent 回合结束后返回。",
+ "chatSseTitle": "SSE 模式",
+ "chatSseHint": "事件顺序为 meta、增量 agent 事件,最后是 done、cancelled 或 error。done 包含完整汇总结果。",
+ "chatTokenRequired": "Agent 对话及其取消接口始终需要 token,即使读取类接口允许无认证访问。",
"endpoints": "接口列表",
"endpointsHint": "把 {id} 替换为项目 UUID、项目文件系统路径,或字面量 'current'。",
"endpointHealthNote": "存活探针。无需鉴权。",
@@ -815,7 +822,8 @@
"endpointSearchNote": "JSON body:{ query, topK?, includeContent?, queryEmbedding? }。配置嵌入后使用统一的关键词 + 向量检索。",
"endpointGraphNote": "?q=…&nodeType=…&limit=N —— 基于 wiki/*.md 的双链图谱。",
"endpointRescanNote": "使用你的资料文件夹监控配置触发后端重新扫描。",
- "endpointChatNote": "尚未实现(返回 501)。"
+ "endpointChatNote": "Agent 对话。默认返回 JSON;使用 stream: true 或 Accept: text/event-stream 可启用 SSE 流式输出。此接口始终需要 Token。",
+ "endpointChatCancelNote": "取消指定会话当前正在执行的 Agent 回合。此接口始终需要 Token。"
},
"output": {
"title": "输出偏好",
diff --git a/src/lib/api-server.real-llm.test.ts b/src/lib/api-server.real-llm.test.ts
index 203d6429..b4a76efa 100644
--- a/src/lib/api-server.real-llm.test.ts
+++ b/src/lib/api-server.real-llm.test.ts
@@ -40,6 +40,20 @@ interface ApiEnvelope {
[key: string]: unknown
}
+interface ApiChatEnvelope extends ApiEnvelope {
+ sessionId?: string
+ message?: {
+ role?: string
+ content?: string
+ }
+ usage?: {
+ promptChars?: number
+ completionChars?: number
+ referenceCount?: number
+ toolEventCount?: number
+ }
+}
+
interface ApiHealth extends ApiEnvelope {
status?: string
enabled?: boolean
@@ -48,6 +62,11 @@ interface ApiHealth extends ApiEnvelope {
allowUnauthenticated?: boolean
allowLanAccess?: boolean
tokenSource?: "env" | "store" | "none"
+ agent?: {
+ chat?: boolean
+ streaming?: boolean
+ streamProtocol?: string
+ }
}
interface ApiProject {
@@ -339,6 +358,11 @@ describe.skipIf(!ENABLED)("local API v1 against real project", () => {
expect(typeof h.authConfigured).toBe("boolean")
expect(typeof h.allowUnauthenticated).toBe("boolean")
expect(["env", "store", "none"]).toContain(h.tokenSource)
+ expect(h.agent).toMatchObject({
+ chat: true,
+ streaming: true,
+ streamProtocol: "sse",
+ })
},
TEST_TIMEOUT_MS,
)
@@ -425,6 +449,18 @@ describe.skipIf(!ENABLED)("local API v1 against real project", () => {
expect(resp.body.ok).toBe(true)
expect(Array.isArray(resp.body.projects)).toBe(true)
expect(resp.body.currentProject == null || resp.body.currentProject.current).toBe(true)
+
+ const chat = await api<ApiEnvelope>(
+ "/api/v1/projects/current/chat",
+ {
+ method: "POST",
+ body: JSON.stringify({ message: "This request must be rejected before calling an LLM.", stream: true }),
+ },
+ { auth: "none" },
+ )
+ expect(chat.status).toBe(401)
+ expect(chat.body.ok).toBe(false)
+ expect(chat.body.error).toContain("Unauthorized")
},
TEST_TIMEOUT_MS,
)
@@ -598,16 +634,70 @@ describe.skipIf(!ENABLED)("local API v1 against real project", () => {
)
it(
- "reports chat as not implemented in API v1",
+ "runs backend Agent chat through API v1",
async (ctx) => {
ensureServer(ctx)
await requireUsableApi()
- const chatResp = await api<ApiEnvelope>(`/api/v1/projects/${PROJECT_ID}/chat`, {
+ if (!API_TOKEN) {
+ console.warn("Skipping Agent chat API assertion because this endpoint always requires a token.")
+ ctx.skip()
+ }
+ const chatResp = await api<ApiChatEnvelope>(`/api/v1/projects/${PROJECT_ID}/chat`, {
method: "POST",
body: JSON.stringify({ message: "hello" }),
})
- expect(chatResp.status).toBe(501)
- expect(chatResp.body.ok).toBe(false)
+ expect(chatResp.status).toBe(200)
+ expect(chatResp.body.ok).toBe(true)
+ expect(chatResp.body.sessionId).toEqual(expect.any(String))
+ expect(chatResp.body.sessionId?.length).toBeGreaterThan(0)
+ expect(chatResp.body.message?.role).toBe("assistant")
+ expect(chatResp.body.message?.content?.trim().length).toBeGreaterThan(0)
+ expect(chatResp.body.usage).toMatchObject({
+ promptChars: expect.any(Number),
+ completionChars: expect.any(Number),
+ referenceCount: expect.any(Number),
+ toolEventCount: expect.any(Number),
+ })
+ expect(chatResp.body.usage?.completionChars).toBeGreaterThan(0)
+ },
+ TEST_TIMEOUT_MS,
+ )
+
+ it(
+ "streams backend Agent chat through SSE",
+ async (ctx) => {
+ ensureServer(ctx)
+ await requireUsableApi()
+ if (!API_TOKEN) {
+ console.warn("Skipping streaming Agent chat assertion because this endpoint always requires a token.")
+ ctx.skip()
+ }
+ const response = await fetch(endpoint(`/api/v1/projects/${PROJECT_ID}/chat`), {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${API_TOKEN}`,
+ "Content-Type": "application/json",
+ Accept: "text/event-stream",
+ },
+ body: JSON.stringify({ message: "Reply with one short sentence.", stream: true }),
+ })
+ expect(response.status).toBe(200)
+ expect(response.headers.get("content-type")).toContain("text/event-stream")
+ const body = await response.text()
+ const metaIndex = body.indexOf("event: meta\n")
+ const agentIndex = body.indexOf("event: agent\n")
+ const doneIndex = body.indexOf("event: done\n")
+ expect(metaIndex).toBeGreaterThanOrEqual(0)
+ expect(agentIndex).toBeGreaterThan(metaIndex)
+ expect(doneIndex).toBeGreaterThan(agentIndex)
+ const doneData = body
+ .split("\n\n")
+ .find((frame) => frame.startsWith("event: done\n"))
+ ?.split("\ndata: ")[1]
+ expect(doneData).toBeTruthy()
+ const done = JSON.parse(doneData ?? "{}") as ApiChatEnvelope
+ expect(done.ok).toBe(true)
+ expect(done.message?.content?.trim().length).toBeGreaterThan(0)
},
TEST_TIMEOUT_MS,
)