World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
Let document tools continue reading past their response budget (#1235)
Daniel4c3dd1bf083f
diff --git a/crates/utopia-server/src/api/chat.rs b/crates/utopia-server/src/api/chat.rsindex 8e12a955..ccd6a0a1 100644--- a/crates/utopia-server/src/api/chat.rs+++ b/crates/utopia-server/src/api/chat.rs@@ -365,8 +365,9 @@ pub(super) fn base_tools() -> serde_json::Value {"type": "function","function": {"name": "get_document",- "description": "Read the full text of ONE knowledge base document, all sections \- in order, by the document_id shown in search_chunks results. Use it whenever \+ "description": "Read ONE knowledge base document, all sections in order, up to \+ 24,000 body characters per call, by the document_id shown in search_chunks \+ results. If truncated, call again with the offset in the notice to continue. Use it whenever \a search hit looks like the right document but the excerpt does not contain \the answer — action items, decisions and lists usually sit past the excerpt \or in a section that did not match the query.",@@ -377,6 +378,11 @@ pub(super) fn base_tools() -> serde_json::Value {"type": "string","format": "uuid","description": "Document id (uuid) from a search_chunks result line."+ },+ "offset": {+ "type": "integer",+ "minimum": 0,+ "description": "Optional zero-based Unicode character position (default 0) across trimmed section bodies in order, excluding headers and separators. Use the next offset from a truncation notice; at or past the end returns no remaining text."}},"required": ["document_id"]@@ -599,7 +605,7 @@ pub(super) fn base_tools() -> serde_json::Value {}const SYSTEM_PROMPT: &str = "You are the assistant of Utopia, a temporal knowledge platform. \- You have tools: search_chunks (document search) and get_document (the full text of one \+ You have tools: search_chunks (document search) and get_document (paged text of one \document found by search), find_entities, entity_facts, neighbors, timeline, \paths_between and changes (a bi-temporal knowledge graph), and search_docs (Utopia's \own manual, the Charter).\n\@@ -610,7 +616,9 @@ const SYSTEM_PROMPT: &str = "You are the assistant of Utopia, a temporal knowledreason to skip the tools. Never say the base lacks something you have not searched for.\n\search_chunks returns short excerpts of the best-matching sections only. When a hit is \clearly the right document but the excerpt does not carry the answer, read the whole \- document with get_document before saying the knowledge base does not have it.\n\+ document with get_document before saying the knowledge base does not have it. If a \+ document read is truncated, continue with the offset in its notice; a partial read is \+ not the full document and cannot establish that the document lacks the answer.\n\The graph has TWO independent time axes:\n\- World time — when something was true. entity_facts(`at` = as of that date).\n\- Record time — when we came to believe it, and when we revised it. entity_facts and search_chunks take `as_of` = the base as it stood at that moment, before later corrections, retractions and merges; changes lists what moved in a window.\n\diff --git a/crates/utopia-server/src/api/mcp_tests.rs b/crates/utopia-server/src/api/mcp_tests.rsindex 110ec325..6f86a0fb 100644--- a/crates/utopia-server/src/api/mcp_tests.rs+++ b/crates/utopia-server/src/api/mcp_tests.rs@@ -1911,6 +1911,205 @@ async fn failed_reads_do_not_become_successful_empty_results() -> anyhow::Resultf.clean().await}+#[tokio::test]+async fn document_reads_continue_past_the_budget_in_chat_and_mcp() -> anyhow::Result<()> {+ let Some(f) = Fixture::new().await? else {+ return Ok(());+ };+ let ctx = ToolCtx {+ state: &f.state,+ kb_id: f.kb,+ workspace_id: f.ws,+ mounted_sources: &[],+ can_write: false,+ actor: None,+ via_token: None,+ question: None,+ };+ let schema = super::super::chat::tools_schema(false, &[]);+ let listed = f+ .request(f.kb, "tools/list", json!({}))+ .await+ .map_err(|e| e.0)?+ .0;+ let document_tool = listed["result"]["tools"]+ .as_array()+ .unwrap()+ .iter()+ .find(|tool| tool["name"] == "get_document")+ .unwrap();+ assert_eq!(+ document_tool["inputSchema"]["properties"]["offset"]["type"],+ "integer"+ );+ assert_eq!(+ document_tool["inputSchema"]["properties"]["offset"]["minimum"],+ 0+ );+ assert_eq!(+ document_tool["inputSchema"]["required"],+ json!(["document_id"])+ );++ // One oversized table row, then a page boundary inside the next chunk.+ for (first_body, second_body) in [+ (+ format!("| Case | {} | CHECKSUM-TAIL |", "界🦀".repeat(16_000)),+ "LAST-SECTION",+ ),+ ("界".repeat(23_999), "🦀CHECKSUM-TAIL"),+ ] {+ sqlx::query(+ "UPDATE chunks SET text=CASE WHEN seq=0 THEN $2 ELSE $3 END WHERE document_id=$1",+ )+ .bind(f.document)+ .bind(format!(" \n{first_body}\n "))+ .bind(format!(" \n{second_body}\n "))+ .execute(&f.state.pool)+ .await?;+ let first_len = first_body.chars().count();+ for over_mcp in [false, true] {+ let mut sink = ToolSink::default();+ let mut args = json!({"document_id":f.document});+ for page in 0..2 {+ let read = if over_mcp {+ f.call("get_document", args.clone()).await?+ } else {+ let checked =+ super::super::chat::check_call(&schema, "get_document", &args.to_string())+ .map_err(|(message, _)| anyhow::anyhow!(message))?;+ tool_result(tools::dispatch(&ctx, &mut sink, "get_document", &checked).await)+ };+ assert_eq!(read["isError"], false, "{read}");+ let text = read["content"][0]["text"].as_str().unwrap();+ if page == 0 {+ assert!(!text.contains("CHECKSUM-TAIL"), "{text}");+ assert!(text.contains(&format!(+ "{} chars omitted",+ first_len + second_body.chars().count() - 24_000+ )));+ let next_offset: usize = text+ .rsplit_once("offset: ")+ .unwrap()+ .1+ .split_whitespace()+ .next()+ .unwrap()+ .parse()?;+ assert_eq!(next_offset, 24_000);+ args["offset"] = json!(next_offset);+ } else {+ assert!(text.contains("CHECKSUM-TAIL"), "{text}");+ assert!(!text.contains("truncated"), "{text}");+ if first_len > 24_000 {+ let tail: String = first_body.chars().skip(24_000).collect();+ assert!(text.contains(&format!("section 1:\n{tail}")));+ assert!(text.contains(second_body));+ } else {+ assert!(!text.contains("section 1:"));+ assert!(text.contains("section 2:\nCHECKSUM-TAIL"));+ }+ }+ }+ if !over_mcp {+ assert_eq!(sink.sources.len(), 2);+ assert_eq!(sink.source_ids[0], f.chunk.to_string());+ }+ }+ }+ f.clean().await+}++#[tokio::test]+async fn document_offsets_preserve_defaults_and_report_invalid_or_finished_reads(+) -> anyhow::Result<()> {+ let Some(f) = Fixture::new().await? else {+ return Ok(());+ };+ let default = f+ .call("get_document", json!({"document_id":f.document}))+ .await?;+ let zero = f+ .call("get_document", json!({"document_id":f.document,"offset":0}))+ .await?;+ assert_eq!(default, zero);+ for offset in [+ json!(-1),+ json!(1.5),+ json!("24000"),+ json!(true),+ Value::Null,+ json!([]),+ json!({}),+ ] {+ let read = f+ .call(+ "get_document",+ json!({"document_id":f.document,"offset":offset}),+ )+ .await?;+ assert_eq!(read["isError"], true, "{read}");+ assert!(read["content"][0]["text"]+ .as_str()+ .unwrap()+ .contains("non-negative integer"));+ }+ let step = step_of(+ &f,+ &[],+ "get_document",+ json!({"document_id":f.document,"offset":-1}),+ )+ .await;+ assert_eq!(step["status"], "invalid");+ assert_eq!(step["param"], "offset");+ let total: i64 = sqlx::query_scalar(+ "SELECT sum(char_length(trim(text)))::bigint FROM chunks WHERE document_id=$1",+ )+ .bind(f.document)+ .fetch_one(&f.state.pool)+ .await?;+ let total = u64::try_from(total)?;+ for offset in [total, total + 1, usize::MAX as u64] {+ let read = f+ .call(+ "get_document",+ json!({"document_id":f.document,"offset":offset}),+ )+ .await?;+ assert_eq!(read["isError"], false, "{read}");+ assert!(read["content"][0]["text"]+ .as_str()+ .unwrap()+ .ends_with(&format!("(no text remaining at offset {offset})")));+ }+ let boundary = f+ .call(+ "get_document",+ json!({"document_id":f.document,"offset":959}),+ )+ .await?;+ let text = boundary["content"][0]["text"].as_str().unwrap();+ assert!(!text.contains("section 1:"));+ assert!(text.contains("section 2:\nAlice works for Acme."));+ // An empty trailing chunk must not turn an exhausted read into an empty citation.+ sqlx::query("UPDATE chunks SET text=' \n ' WHERE document_id=$1 AND seq=1")+ .bind(f.document)+ .execute(&f.state.pool)+ .await?;+ let finished = f+ .call(+ "get_document",+ json!({"document_id":f.document,"offset":959}),+ )+ .await?;+ assert!(finished["content"][0]["text"]+ .as_str()+ .unwrap()+ .ends_with("(no text remaining at offset 959)"));+ f.clean().await+}+#[tokio::test]async fn document_reads_preserve_text_empty_and_unavailable_results() -> anyhow::Result<()> {let Some(f) = Fixture::new().await? else {@@ -1951,13 +2150,17 @@ async fn document_reads_preserve_text_empty_and_unavailable_results() -> anyhow:// Missing, foreign and deleted IDs remain indistinguishable; a read failure// must not change that boundary or turn a genuinely empty document into an error.for id in [Uuid::now_v7(), foreign, f.document] {- let result = f.call("get_document", json!({"document_id":id})).await?;- assert_eq!(result["isError"], false);- assert_eq!(- result["content"][0]["text"],- "No document with that id in this knowledge base."- );- assert!(result.get("structuredContent").is_none());+ for offset in [0, 24_000] {+ let result = f+ .call("get_document", json!({"document_id":id,"offset":offset}))+ .await?;+ assert_eq!(result["isError"], false);+ assert_eq!(+ result["content"][0]["text"],+ "No document with that id in this knowledge base."+ );+ assert!(result.get("structuredContent").is_none());+ }}f.clean().await}diff --git a/crates/utopia-server/src/api/tools.rs b/crates/utopia-server/src/api/tools.rsindex 0c28606f..149f68d0 100644--- a/crates/utopia-server/src/api/tools.rs+++ b/crates/utopia-server/src/api/tools.rs@@ -17,9 +17,7 @@ use crate::state::AppState;const SEARCH_TOP_K: usize = 6;const TOOL_CHUNK_CHARS: usize = 800;-/// `get_document` 一次最多回多少字。检索那边的 800 字是为了让六条命中都装得下,-/// 这边只有一篇文档,而问的人已经知道要读哪一篇——截在答案前面才是这个工具-/// 要消灭的毛病+/// `get_document` 每页的正文预算;超出的部分用字符 offset 续读,不把上下文塞满。const DOCUMENT_CHARS: usize = 24_000;/// 一次 changes 最多回多少条。刚灌完的库里 asserted 是成百上千条,全发出去/// 只会把上下文填满而不增加信息——有信息量的是 corrected/rejected,那类事件@@ -391,6 +389,22 @@ pub async fn get_document(else {return refuse(Step::new("document", "?", "invalid id").invalid("document_id"));};+ let offset = match args.get("offset") {+ None => 0,+ Some(value) => {+ let Some(offset) = value.as_u64().and_then(|n| usize::try_from(n).ok()) else {+ return ToolResult::new(+ "get_document needs `offset` to be a non-negative integer character position."+ .into(),+ Step::new("document", "?", "invalid offset")+ .invalid("offset")+ .json(),+ )+ .error();+ };+ offset+ }+ };// 本库之外的 id 一律当作不存在——分不出「没有」和「不给你看」才是对的let doc = match utopia_store::documents::find_in_kb(&ctx.state.pool, ctx.kb_id, id).await {Ok(Some(doc)) => doc,@@ -420,25 +434,34 @@ pub async fn get_document(};let mut lines = Vec::new();+ let mut skip = offset;let mut used = 0usize;let mut omitted = 0usize;for c in &chunks {let body = c.text.trim();let len = body.chars().count();+ // offset 只数按顺序拼接的正文,不数标题、引证和分块之间的排版。+ if offset > 0 && skip >= len {+ skip -= len;+ continue;+ }+ let remaining = len - skip;let room = DOCUMENT_CHARS.saturating_sub(used);// 装不下的分块整块不发,也不引——发一个引证编号出去而正文不在,// 界面上落成一条指不到东西的引证if room == 0 {- omitted += len;+ omitted += remaining;continue;}- let body: String = if len > room {- omitted += len - room;- body.chars().take(room).collect()+ let read = remaining.min(room);+ let body: String = if skip > 0 || remaining > room {+ body.chars().skip(skip).take(read).collect()} else {body.to_string()};- used += body.chars().count();+ skip = 0;+ omitted += remaining - read;+ used += read;let n = cite(sink, c.id.to_string(), |n| source_json(n, c));lines.push(format!("[{n}] \"{}\" section {}:\n{body}",@@ -447,7 +470,10 @@ pub async fn get_document());}if omitted > 0 {- lines.push(format!("… truncated, {omitted} chars omitted"));+ lines.push(format!(+ "… truncated, {omitted} chars omitted; call get_document with document_id: {id}, offset: {} to continue",+ offset + used+ ));}let when = doc@@ -459,7 +485,9 @@ pub async fn get_document(doc.filename,chunks.len());- let text = if lines.is_empty() {+ let text = if lines.is_empty() && offset > 0 {+ format!("{header}\n(no text remaining at offset {offset})")+ } else if lines.is_empty() {format!("{header}\n(no text)")} else {format!("{header}\n\n{}", lines.join("\n\n"))diff --git a/web/src/docs/mcp.md b/web/src/docs/mcp.mdindex f6156291..1417802d 100644--- a/web/src/docs/mcp.md+++ b/web/src/docs/mcp.md@@ -38,7 +38,7 @@ Three methods are served:| Tool | What it answers ||---|---|| `search_chunks` | Full-text + semantic search over the base's documents. Returns the six best-matching passages, each cut at 800 characters and carrying its `document_id`. Pass `as_of` to search the base as it stood at that moment — earlier versions, documents deleted since; full-text recall stays current, so hits are right but may be incomplete |-| `get_document` | The full text of one document, all sections in order, by `document_id`. Use it when a search hit is the right document but the excerpt does not carry the answer. Capped at 24,000 characters, and says so when it cuts |+| `get_document` | Read one document by `document_id`, all sections in order, up to 24,000 body characters per call. When truncated, call again with the optional `offset` given in the notice to continue || `find_entities` | Entities by (partial) name: id, type, and a disambiguator when several share a name || `entity_facts` | One entity's facts with validity ranges. Pass `at` (a date) to see the world as of that day; this is the tool for "who was X in 2024". Pass `as_of` (a date or an RFC3339 moment) to see the facts **as the base held them then**, before later corrections, retractions and merges — "what did we have on record before the memo arrived". The two combine: `at` for the date asked about, `as_of` for when || `neighbors` | The entities linked to one entity, one hop, grouped by predicate; narrow with `predicate` or `object_type`. Takes a name as well as an id |@@ -183,6 +183,8 @@ curl -s -X POST https://your-utopia/api/v1/kbs/$KB/mcp \"params":{"name":"get_document","arguments":{"document_id":"<id from the hit>"}}}'```+If the document is truncated, repeat `get_document` with the same `document_id` and the `offset` from the notice (for example, `"offset":24000` after the first full page). The offset is a zero-based Unicode character position across trimmed section bodies in order; headers and separators do not count. Omitting it starts at 0. At or past the end, the tool reports no remaining text.+A document id from another base, or a made-up one, comes back as "No document with that id in this knowledge base" — the tool cannot tell you what it is not allowed to see.## Point a client at it