Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
feat(agents): route skills and SDK entities through one batched Jev path (#9875)
Wolf Mermelstein6fe2c83eb50d
diff --git a/Cargo.lock b/Cargo.lockindex 3bdfc9c913..8b6c151b28 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -11390,6 +11390,7 @@ dependencies = ["ai_billing","ai_usage","async-trait",+ "futures","macro_env_var","macro_user_id","reqwest 0.13.4",diff --git a/crates/agent_code_mode/AGENTS.md b/crates/agent_code_mode/AGENTS.mdindex da6947d405..4afb733e3e 100644--- a/crates/agent_code_mode/AGENTS.md+++ b/crates/agent_code_mode/AGENTS.md@@ -56,8 +56,9 @@ stacks. Process isolation belongs tothe native tool gate, so both tools are in `covered_by_code_sdk`.- `src/domain/documentation.rs`: the build-time SDK catalog (per entity a`@routing` description, an `@agent` guide and an index; a reference per- symbol). Jev ranks entities on their descriptions (32 per call, at most 8- calls) for the per-turn prompt (≥ 0.5, top four, 48 KiB) or a+ symbol). Jev ranks entities on their descriptions, in parallel calls of 32+ (`cognition::domain::decide_in_batches`; a late or failed call loses only+ its own entities), for the per-turn prompt (≥ 0.5, top four, 48 KiB) or a`DescribeCodeTools` `task` (every relevant entity, 32 KiB); `ReadCodeDocs`reads symbol references (32 KiB). `Guidance::Selected` (owners with`auto-skills`) loads each entity's guide with its index; otherwise prompts@@ -76,7 +77,7 @@ session presentation. Never replay an uncertain submitted action.## Tool contracts-- `ContentSearch`, `NameSearch`, `ListEntities` and `ReadChat` are covered by the SDK's `search` entity (`macro.search`, `macro.workspace`, `macro.chats`), which carries the search guide; keep their filters in step.+- `ContentSearch`, `NameSearch`, `ListEntities` and `ReadChat` are covered by the SDK's `search`, `workspace` and `chats` entities (`macro.search`, `macro.workspace`, `macro.chats`); the `search` entity carries the search guide. Keep their filters in step.Reviews write `review.decided` and `review.settled` through the injectedtransaction-aware notification writer in the same revision-checked transaction.@@ -100,7 +101,6 @@ longer delivery state.database configuration and `SQLX_OFFLINE` unset.- The review toolset test builds every review tool through shared provider schemavalidation.-- Keep generated discovery topics within the classifier's 32-question limit.- The SDK catalog and operation labels come from `crates/code_mode_assets`,generated from the public SDK at build time; change the SDK or`packages/code-mode-sdk`, never a generated file.diff --git a/crates/agent_code_mode/src/domain/documentation.rs b/crates/agent_code_mode/src/domain/documentation.rsindex 2ba7ada61d..1fab79cd01 100644--- a/crates/agent_code_mode/src/domain/documentation.rs+++ b/crates/agent_code_mode/src/domain/documentation.rs@@ -1,5 +1,5 @@//! Bounded SDK documentation selection through the shared cognition service.-use cognition::domain::{Cognition, DecisionRequest};+use cognition::domain::{Answer, BatchedOutcome, Cognition, decide_in_batches};use macro_user_id::user_id::MacroUserIdStr;use schemars::JsonSchema;use serde::{Deserialize, Serialize};@@ -143,9 +143,9 @@ pub enum SelectionStatus {Unconfigured,/// The caller cancelled before Jev answered.Cancelled,- /// Jev returned an error.+ /// Every Jev call failed.ProviderError,- /// Jev did not answer before the deadline.+ /// No Jev call answered before the deadline.Timeout,}@@ -161,14 +161,27 @@ impl SelectionStatus {}}-/// Questions Jev answers in one call.-const QUESTIONS_PER_CALL: usize = 32;-/// Parallel Jev calls per selection; entities past `MAX_CALLS * 32` are not-/// asked about and stay reachable through `DescribeCodeTools`.-const MAX_CALLS: usize = 8;+/// The entities Jev considers relevant, most relevant first.+struct Ranking<'a> {+ entities: Vec<&'a SdkDocumentation>,+ status: SelectionStatus,+ /// Parallel Jev calls made, 32 entities per call.+ batches: usize,+}++impl Ranking<'_> {+ fn nothing(status: SelectionStatus) -> Self {+ Self {+ entities: Vec::new(),+ status,+ batches: 0,+ }+ }+}-/// Ask Jev which entities help with `text`, at most 32 questions per call and-/// [`MAX_CALLS`] calls in parallel; most relevant first.+/// Ask Jev which entities help with `text`, every entity in parallel calls of+/// 32. Entities whose call fails or misses the deadline are not ranked; the+/// rest still are.async fn rank_entities<'a>(user: &MacroUserIdStr<'static>,text: &str,@@ -176,75 +189,59 @@ async fn rank_entities<'a>(cognition: Option<&Arc<dyn Cognition>>,deadline: Duration,cancel: &CancellationToken,-) -> (Vec<&'a SdkDocumentation>, SelectionStatus) {+) -> Ranking<'a> {let Some(cognition) = cognition else {- return (Vec::new(), SelectionStatus::Unconfigured);+ return Ranking::nothing(SelectionStatus::Unconfigured);};let input = serde_json::json!({"userRequest": text.chars().take(8000).collect::<String>()});- let calls = docs- .chunks(QUESTIONS_PER_CALL)- .take(MAX_CALLS)- .map(|chunk| {- cognition.decide(- user,- DecisionRequest {- input: input.clone(),- questions: chunk- .iter()- .map(|doc| {- (- doc.name.clone(),- format!(- "Would the SDK entity {} help with this request? {}",- doc.name, doc.description- ),- )- })- .collect(),- },+ let questions: Vec<String> = docs+ .iter()+ .map(|doc| {+ format!(+ "Would the SDK entity {} help with this request? {}",+ doc.name, doc.description)- });- let answers = tokio::select! {+ })+ .collect();+ let decision = tokio::select! {biased;- _ = cancel.cancelled() => return (Vec::new(), SelectionStatus::Cancelled),- result = tokio::time::timeout(deadline, futures::future::join_all(calls)) => match result {- Ok(answers) => answers,- Err(_) => return (Vec::new(), SelectionStatus::Timeout),- },+ _ = cancel.cancelled() => return Ranking::nothing(SelectionStatus::Cancelled),+ decision = decide_in_batches(&input, &questions, deadline, |request| cognition.decide(user, request)) => decision,};- let mut probabilities = std::collections::BTreeMap::new();- let mut answered = false;- for answer in answers {- match answer {- Ok(answer) => {- answered = true;- probabilities.extend(answer.probabilities);- }- Err(error) => tracing::warn!(error = %error, "Jev could not rank SDK entities"),- }- }- if !answered {- return (Vec::new(), SelectionStatus::ProviderError);++ let status = match decision.outcome() {+ BatchedOutcome::Answered => SelectionStatus::Selected,+ BatchedOutcome::TimedOut => SelectionStatus::Timeout,+ BatchedOutcome::Failed => SelectionStatus::ProviderError,+ };+ if status != SelectionStatus::Selected {+ return Ranking {+ batches: decision.batches,+ ..Ranking::nothing(status)+ };}+let mut ranked: Vec<_> = docs.iter()- .filter_map(|doc| {- let score = probabilities.get(&doc.name).copied()?;- (score.is_finite() && score >= 0.5).then_some((score, doc))+ .zip(decision.answers)+ .filter_map(|(doc, answer)| match answer {+ Answer::Probability(score) if score.is_finite() && score >= 0.5 => Some((score, doc)),+ Answer::Probability(_) | Answer::Failed | Answer::TimedOut => None,}).collect();ranked.sort_by(|a, b| b.0.total_cmp(&a.0).then(a.1.name.cmp(&b.1.name)));- (- ranked.into_iter().map(|(_, doc)| doc).collect(),- SelectionStatus::Selected,- )+ Ranking {+ entities: ranked.into_iter().map(|(_, doc)| doc).collect(),+ status: SelectionStatus::Selected,+ batches: decision.batches,+ }}/// Load the entities a request needs, ranked by Jev, at most four: their/// indexes, and with [`Guidance::Selected`] their guidance too. Failures retain/// the compact catalog. The byte cap bounds prompt growth; it is not an exact/// tokenizer count.-#[tracing::instrument(skip_all, fields(guidance = ?guidance, selected = tracing::field::Empty, bytes = tracing::field::Empty, selection_status = tracing::field::Empty, selected_entities = tracing::field::Empty))]+#[tracing::instrument(skip_all, fields(guidance = ?guidance, batches = tracing::field::Empty, selected = tracing::field::Empty, bytes = tracing::field::Empty, selection_status = tracing::field::Empty, selected_entities = tracing::field::Empty))]pub async fn select_documentation(user: &MacroUserIdStr<'static>,prompt: &str,@@ -260,7 +257,7 @@ pub async fn select_documentation(output.push_str(&format!("{}: {}\n", doc.name, doc.description));}let started = tokio::time::Instant::now();- let (ranked, status) = rank_entities(+ let ranking = rank_entities(user,prompt,docs,@@ -270,7 +267,7 @@ pub async fn select_documentation().await;let mut selected_entities = Vec::new();- for doc in ranked.into_iter().take(4) {+ for doc in ranking.entities.into_iter().take(4) {let Some(index) = doc.index.as_ref() else {continue;};@@ -288,10 +285,11 @@ pub async fn select_documentation(}}let span = tracing::Span::current();+ span.record("batches", ranking.batches);span.record("selected", selected_entities.len());span.record("selected_entities", selected_entities.join(","));span.record("bytes", output.len());- span.record("selection_status", status.as_str());+ span.record("selection_status", ranking.status.as_str());tracing::debug!(elapsed_ms = started.elapsed().as_millis() as u64,selected = selected_entities.len(),@@ -320,7 +318,7 @@ pub struct TaskDocumentation {/// Select entity indexes for a task the agent describes, for clients that/// never show the server the user's request.-#[tracing::instrument(name = "code_mode.task_documentation", skip_all, fields(selected = tracing::field::Empty, omitted = tracing::field::Empty, bytes = tracing::field::Empty, selection_status = tracing::field::Empty, selected_entities = tracing::field::Empty))]+#[tracing::instrument(name = "code_mode.task_documentation", skip_all, fields(batches = tracing::field::Empty, selected = tracing::field::Empty, omitted = tracing::field::Empty, bytes = tracing::field::Empty, selection_status = tracing::field::Empty, selected_entities = tracing::field::Empty))]pub async fn documentation_for_task(user: &MacroUserIdStr<'static>,task: &str,@@ -329,12 +327,11 @@ pub async fn documentation_for_task() -> TaskDocumentation {let docs = sdk_documentation();// The agent is waiting on this call, unlike the per-turn prompt path.- let (ranked, status) =- rank_entities(user, task, docs, cognition, Duration::from_secs(5), cancel).await;+ let ranking = rank_entities(user, task, docs, cognition, Duration::from_secs(5), cancel).await;let mut bytes = 0;let mut entities = Vec::new();let mut omitted = Vec::new();- for doc in ranked {+ for doc in ranking.entities {let size =doc.index.as_ref().map_or(0, String::len) + doc.guide.as_ref().map_or(0, String::len);if bytes + size <= DOCUMENTATION_BYTES {@@ -345,10 +342,11 @@ pub async fn documentation_for_task(}}let span = tracing::Span::current();+ span.record("batches", ranking.batches);span.record("selected", entities.len());span.record("omitted", omitted.len());span.record("bytes", bytes);- span.record("selection_status", status.as_str());+ span.record("selection_status", ranking.status.as_str());span.record("selected_entities",entities@@ -358,7 +356,7 @@ pub async fn documentation_for_task(.join(","),);TaskDocumentation {- status,+ status: ranking.status,entities,omitted,}diff --git a/crates/agent_code_mode/src/domain/documentation/eval.rs b/crates/agent_code_mode/src/domain/documentation/eval.rsindex f5033f2368..b3cdd29e69 100644--- a/crates/agent_code_mode/src/domain/documentation/eval.rs+++ b/crates/agent_code_mode/src/domain/documentation/eval.rs@@ -8,7 +8,9 @@use super::*;use async_trait::async_trait;-use cognition::domain::{DecisionResponse, GenerateObjectRequest, GenerateObjectResponse};+use cognition::domain::{+ DecisionRequest, DecisionResponse, GenerateObjectRequest, GenerateObjectResponse,+};use jev::domain::{JevProvider as _, YesNoQuestion};use rootcause::Report;@@ -25,11 +27,11 @@ const PROMPTS: &[(&str, &[&str])] = &[),("Catch me up on what changed in my workspace today",- &["search"],+ &["workspace"],),("What did I ask Macro in my AI chat about the offsite?",- &["search"],+ &["chats"],),("Every Monday at 9, send me a summary of my open tasks",@@ -80,14 +82,25 @@ const PROMPTS: &[(&str, &[&str])] = &[),("Thanks, that's perfect!", &[]),("What's 15% of 2,340?", &[]),+ ("Pin the roadmap doc to my home view", &["pins"]),+ ("Add the Q3 plan to my favorites", &["favorites"]),+ (+ "What title and preview image does https://example.com/launch show?",+ &["unfurls"],+ ),];const RUNS: usize = 3;/// What a turn loads: entities at 0.5 or higher, at most four.const LOADED: usize = 4;-/// The real Jev behind the cognition port.-struct RealJev(jev::outbound::SystemOneJev);+/// The real Jev behind the cognition port, counting its calls and the input+/// tokens they bill.+struct RealJev {+ jev: jev::outbound::SystemOneJev,+ calls: std::sync::atomic::AtomicU64,+ input_tokens: std::sync::atomic::AtomicU64,+}#[async_trait]impl Cognition for RealJev {@@ -115,10 +128,16 @@ impl Cognition for RealJev {}).unzip();let evaluation = self- .0+ .jev.evaluate(&request.input, &questions).await.map_err(|error| rootcause::report!("{error}"))?;+ self.calls+ .fetch_add(1, std::sync::atomic::Ordering::Relaxed);+ self.input_tokens.fetch_add(+ evaluation.input_tokens,+ std::sync::atomic::Ordering::Relaxed,+ );Ok(DecisionResponse {probabilities: keys.into_iter()@@ -133,17 +152,20 @@ impl Cognition for RealJev {#[ignore = "calls TypeSafe's Jev; needs TYPESAFE_API_KEY"]async fn entity_route_evaluation() {let key = jev::outbound::TypesafeApiKey::new().expect("TYPESAFE_API_KEY is set");- let cognition: Arc<dyn Cognition> = Arc::new(RealJev(- jev::outbound::SystemOneJev::typesafe(key.value().expect("TYPESAFE_API_KEY is set"))+ let jev = Arc::new(RealJev {+ jev: jev::outbound::SystemOneJev::typesafe(key.value().expect("TYPESAFE_API_KEY is set")).expect("a valid TypeSafe key"),- ));+ calls: std::sync::atomic::AtomicU64::new(0),+ input_tokens: std::sync::atomic::AtomicU64::new(0),+ });+ let cognition: Arc<dyn Cognition> = jev.clone();let owner = MacroUserIdStr::parse_from_str("macro|[email protected]").expect("a user id");let docs = sdk_documentation();let (mut recalled, mut expected_total, mut exact, mut spurious, mut loaded_total) =(0, 0, 0, 0, 0);for (prompt, expected) in PROMPTS {for run in 0..RUNS {- let (ranked, status) = rank_entities(+ let ranking = rank_entities(&owner,prompt,docs,@@ -152,8 +174,9 @@ async fn entity_route_evaluation() {&CancellationToken::new(),).await;- assert_eq!(status, SelectionStatus::Selected, "{prompt}");- let loaded: Vec<&str> = ranked+ assert_eq!(ranking.status, SelectionStatus::Selected, "{prompt}");+ let loaded: Vec<&str> = ranking+ .entities.iter().take(LOADED).map(|doc| doc.name.as_str())@@ -187,4 +210,11 @@ async fn entity_route_evaluation() {"recall {recalled}/{expected_total}, exact set {exact}/{runs}, loads on prompts needing none {spurious}/{none_runs}, mean entities loaded {:.2}",loaded_total as f64 / runs as f64);+ let calls = jev.calls.load(std::sync::atomic::Ordering::Relaxed);+ let input_tokens = jev.input_tokens.load(std::sync::atomic::Ordering::Relaxed);+ println!(+ "Jev calls {calls} ({:.2} per routing), input tokens {input_tokens} ({:.0} per routing)",+ calls as f64 / runs as f64,+ input_tokens as f64 / runs as f64+ );}diff --git a/crates/agent_code_mode/src/domain/documentation/test.rs b/crates/agent_code_mode/src/domain/documentation/test.rsindex 9a40360df1..9f50d28b6d 100644--- a/crates/agent_code_mode/src/domain/documentation/test.rs+++ b/crates/agent_code_mode/src/domain/documentation/test.rs@@ -1,6 +1,8 @@use super::*;use async_trait::async_trait;-use cognition::domain::{DecisionResponse, GenerateObjectRequest, GenerateObjectResponse};+use cognition::domain::{+ DecisionRequest, DecisionResponse, GenerateObjectRequest, GenerateObjectResponse,+};use rootcause::Report;use std::sync::Mutex;@@ -26,16 +28,12 @@ impl Cognition for Classifier {) -> Result<DecisionResponse, Report> {let probabilities = request.questions- .keys()- .map(|name| {- (- name.clone(),- if self.relevant.is_empty() || self.relevant.contains(&name.as_str()) {- 0.9- } else {- 0.1- },- )+ .iter()+ .map(|(key, question)| {+ // "Would the SDK entity <name> help with this request? …"+ let name = question.split_whitespace().nth(4).unwrap();+ let relevant = self.relevant.is_empty() || self.relevant.contains(&name);+ (key.clone(), if relevant { 0.9 } else { 0.1 })}).collect();self.requests.lock().unwrap().push(request);@@ -74,13 +72,10 @@ async fn one_bounded_request_expands_only_selected_entities() {assert!(result.contains("email:"));assert!(result.len() <= 48 * 1024);let requests = classifier.requests.lock().unwrap();- assert_eq!(requests.len(), 1);- assert!(requests[0].questions.len() <= 32);- assert_eq!(- requests[0].input["userRequest"].as_str().unwrap().len(),- 8000- );- requests[0].validate().unwrap();+ for request in requests.iter() {+ assert_eq!(request.input["userRequest"].as_str().unwrap().len(), 8000);+ request.validate().unwrap();+ }}#[tokio::test]@@ -341,34 +336,27 @@ fn every_entity_routes_on_a_use_when_sentence() {}#[tokio::test]-async fn candidates_split_into_calls_of_at_most_32_questions_and_at_most_eight_calls() {+async fn entities_past_the_first_32_route_in_another_parallel_call() {+ let catalog = sdk_documentation();+ assert!(catalog.len() > 32);+ let in_second_call = catalog[32].name.as_str();let classifier = Arc::new(Classifier {requests: Mutex::new(vec![]),delay: Duration::ZERO,fail: false,- relevant: &["entity-69"],+ relevant: Vec::leak(vec![in_second_call]),});let service: Arc<dyn Cognition> = classifier.clone();- let docs: Vec<SdkDocumentation> = (0..300)- .map(|index| SdkDocumentation {- name: format!("entity-{index}"),- description: "Use when testing; not otherwise.".into(),- guide: None,- index: None,- })- .collect();- let (ranked, status) = rank_entities(++ let result = select_documentation(&user(),"request",- &docs[..70],Some(&service),- Duration::from_secs(1),+ Guidance::Inline,&CancellationToken::new(),).await;- assert_eq!(status, SelectionStatus::Selected);- assert_eq!(ranked.len(), 1);- assert_eq!(ranked[0].name, "entity-69");+let sizes: Vec<usize> = classifier.requests.lock()@@ -376,19 +364,8 @@ async fn candidates_split_into_calls_of_at_most_32_questions_and_at_most_eight_c.iter().map(|request| request.questions.len()).collect();- assert_eq!(sizes, [32, 32, 6]);- classifier.requests.lock().unwrap().clear();- rank_entities(- &user(),- "request",- &docs,- Some(&service),- Duration::from_secs(1),- &CancellationToken::new(),- )- .await;- let requests = classifier.requests.lock().unwrap();- let asked: usize = requests.iter().map(|request| request.questions.len()).sum();- assert_eq!(requests.len(), 8);- assert_eq!(asked, 256);+ assert_eq!(sizes.len(), catalog.len().div_ceil(32));+ assert!(sizes.iter().all(|size| *size <= 32));+ assert_eq!(sizes.iter().sum::<usize>(), catalog.len());+ assert!(result.contains(catalog[32].index.as_deref().unwrap()));}diff --git a/crates/cognition/AGENTS.md b/crates/cognition/AGENTS.mdindex 90ad54e234..a65b131aa9 100644--- a/crates/cognition/AGENTS.md+++ b/crates/cognition/AGENTS.md@@ -8,7 +8,9 @@ HTTP endpoints directly; this crate does not register tools into a runtime.## Start here-- `src/domain.rs`: authenticated-user port, model identifier and request bounds.+- `src/domain.rs`: authenticated-user port, model identifier and request bounds;+ re-exports Jev's `decide_in_batches` for callers asking more than 32+ questions.- `src/outbound.rs`: pooled HTTP adapter to the cognition service.- `src/inbound/toolset.rs`: optional `GenerateObject` and `Decide` adapters.diff --git a/crates/cognition/Cargo.toml b/crates/cognition/Cargo.tomlindex 9c12c86508..734a73bb8d 100644--- a/crates/cognition/Cargo.toml+++ b/crates/cognition/Cargo.toml@@ -7,7 +7,7 @@ publish = false[dependencies]ai_toolset = { path = "../ai_toolset" }async-trait = { workspace = true }-jev = { path = "../jev" }+jev = { path = "../jev", features = ["batches"] }macro_authorization = { path = "../macro_authorization", default-features = false, features = ["axum"] }macro_tower_layers = { path = "../macro_tower_layers" }macro_user_id = { path = "../macro_user_id" }diff --git a/crates/cognition/src/domain.rs b/crates/cognition/src/domain.rsindex b035c16da4..1b01c53794 100644--- a/crates/cognition/src/domain.rs+++ b/crates/cognition/src/domain.rs@@ -1,7 +1,8 @@//! Tool-free generation and classification for an authenticated user.use async_trait::async_trait;-pub use jev::domain::{DecisionRequest, DecisionResponse};+pub use jev::domain::batches::{Answer, BatchedDecision, BatchedOutcome, decide_in_batches};+pub use jev::domain::{DecisionRequest, DecisionResponse, MAX_QUESTIONS};use macro_user_id::user_id::MacroUserIdStr;use rootcause::Report;use schemars::JsonSchema;diff --git a/crates/jev/AGENTS.md b/crates/jev/AGENTS.mdindex e187f9b7b8..d3d0cdf81c 100644--- a/crates/jev/AGENTS.md+++ b/crates/jev/AGENTS.md@@ -16,6 +16,11 @@ composer's Auto mode.- `src/domain/decisions.rs`: named decision admission, capacity, deadline andcancellation-safe metering (`decisions` feature).- `src/domain/ports.rs`: `JevProvider` / `YesNoClassifier` port traits.+- `src/domain/batches.rs` (`batches` feature): `decide_in_batches`, the one+ way to ask more than 32 questions: parallel requests of at most 32 under one+ deadline, answers typed and in question order, a late or failed request+ losing only its own questions. Skill and SDK entity routing use it through+ `cognition`; never chunk questions in a caller.- `src/outbound/system_one.rs`: `SystemOneJev`, the HTTP adapter for TypeSafeand Cloudflare Workers AI (feature `outbound`).diff --git a/crates/jev/Cargo.toml b/crates/jev/Cargo.tomlindex 15a2f4969e..a819009e50 100644--- a/crates/jev/Cargo.toml+++ b/crates/jev/Cargo.toml@@ -6,6 +6,7 @@ version = "0.1.0"[features]default = []+batches = ["dep:futures", "dep:tokio"]decisions = ["dep:ai_billing", "dep:async-trait", "dep:macro_user_id", "dep:tokio"]outbound = ["dep:macro_env_var", "dep:reqwest", "dep:tokio"]@@ -13,6 +14,7 @@ outbound = ["dep:macro_env_var", "dep:reqwest", "dep:tokio"]ai_billing = { path = "../ai_billing", optional = true }ai_usage = { path = "../ai_usage" }async-trait = { workspace = true, optional = true }+futures = { workspace = true, optional = true }macro_env_var = { path = "../macro_env_var", optional = true }macro_user_id = { path = "../macro_user_id", optional = true }reqwest = { workspace = true, optional = true }diff --git a/crates/jev/src/domain.rs b/crates/jev/src/domain.rsindex 8dbd00672c..e3c36fb0cd 100644--- a/crates/jev/src/domain.rs+++ b/crates/jev/src/domain.rs@@ -1,6 +1,8 @@//! Jev domain: question and probability value objects, the provider port, and//! the metered classification use case. No transport or infrastructure lives here.+#[cfg(feature = "batches")]+pub mod batches;#[cfg(feature = "decisions")]pub mod decisions;pub mod models;diff --git a/crates/jev/src/domain/batches.rs b/crates/jev/src/domain/batches.rsnew file mode 100644index 0000000000..1056a6982f--- /dev/null+++ b/crates/jev/src/domain/batches.rs@@ -0,0 +1,141 @@+//! Asking more questions than one decision takes: split into requests of at+//! most [`MAX_QUESTIONS`], run concurrently under one deadline, and answered in+//! the order asked.++use std::fmt::Display;+use std::future::Future;+use std::time::Duration;++use futures::StreamExt as _;+use futures::stream::FuturesUnordered;++use super::models::{DecisionRequest, DecisionResponse, MAX_QUESTIONS};++#[cfg(test)]+mod test;++/// One question's answer.+#[derive(Debug, Clone, Copy, PartialEq)]+pub enum Answer {+ /// The probability of yes.+ Probability(f32),+ /// The call that asked it failed or left it out.+ Failed,+ /// The call that asked it had not answered by the deadline.+ TimedOut,+}++/// How a batched decision went overall.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum BatchedOutcome {+ /// At least one call answered; unanswered questions say why.+ Answered,+ /// No call answered, and at least one was still running at the deadline.+ TimedOut,+ /// Every call failed.+ Failed,+}++/// The answers to [`decide_in_batches`], one per question, in the order asked.+#[derive(Debug, Clone, PartialEq)]+pub struct BatchedDecision {+ /// One answer per question, in the order asked.+ pub answers: Vec<Answer>,+ /// Calls made: one per [`MAX_QUESTIONS`] questions, rounded up.+ pub batches: usize,+}++impl BatchedDecision {+ /// Whether any call answered, and if none did, why.+ pub fn outcome(&self) -> BatchedOutcome {+ let answered = self+ .answers+ .iter()+ .any(|answer| matches!(answer, Answer::Probability(_)));+ let timed_out = self.answers.contains(&Answer::TimedOut);++ if answered || self.answers.is_empty() {+ BatchedOutcome::Answered+ } else if timed_out {+ BatchedOutcome::TimedOut+ } else {+ BatchedOutcome::Failed+ }+ }+}++/// Ask `questions` about `input` through `decide`, at most [`MAX_QUESTIONS`]+/// per call, all calls at once. Answers that arrive within `deadline` are+/// kept; a call that fails or is late loses only its own questions.+#[tracing::instrument(+ name = "jev.decide_in_batches",+ skip_all,+ fields(+ questions = questions.len(),+ batches = tracing::field::Empty,+ failed = tracing::field::Empty,+ timed_out = tracing::field::Empty,+ )+)]+pub async fn decide_in_batches<Decide, Decision, Error>(+ input: &serde_json::Value,+ questions: &[String],+ deadline: Duration,+ decide: Decide,+) -> BatchedDecision+where+ Decide: Fn(DecisionRequest) -> Decision,+ Decision: Future<Output = Result<DecisionResponse, Error>>,+ Error: Display,+{+ let until = tokio::time::Instant::now() + deadline;+ let mut pending: FuturesUnordered<_> = questions+ .chunks(MAX_QUESTIONS)+ .enumerate()+ .map(|(batch, chunk)| {+ let first = batch * MAX_QUESTIONS;+ let request = DecisionRequest {+ input: input.clone(),+ questions: chunk+ .iter()+ .enumerate()+ .map(|(offset, question)| ((first + offset).to_string(), question.clone()))+ .collect(),+ };+ let decision = decide(request);+ async move { (first..first + chunk.len(), decision.await) }+ })+ .collect();+ let mut decision = BatchedDecision {+ answers: vec![Answer::TimedOut; questions.len()],+ batches: pending.len(),+ };+ let mut failed = 0;++ while let Ok(Some((asked, result))) = tokio::time::timeout_at(until, pending.next()).await {+ let response = match result {+ Ok(response) => response,+ Err(error) => {+ failed += 1;+ tracing::warn!(error = %error, "a batch of decisions failed");+ DecisionResponse {+ probabilities: Default::default(),+ }+ }+ };+ for index in asked {+ decision.answers[index] = response+ .probabilities+ .get(&index.to_string())+ .map_or(Answer::Failed, |probability| {+ Answer::Probability(*probability)+ });+ }+ }++ let span = tracing::Span::current();+ span.record("batches", decision.batches);+ span.record("failed", failed);+ span.record("timed_out", pending.len());+ decision+}diff --git a/crates/jev/src/domain/batches/test.rs b/crates/jev/src/domain/batches/test.rsnew file mode 100644index 0000000000..c5502dc312--- /dev/null+++ b/crates/jev/src/domain/batches/test.rs@@ -0,0 +1,95 @@+use std::collections::BTreeMap;+use std::sync::Mutex;+use std::time::Duration;++use serde_json::json;++use super::*;++#[tokio::test(start_paused = true)]+async fn seventy_questions_answer_in_order_across_three_calls_and_a_late_or_failed_call_loses_only_its_own()+ {+ let sizes = Mutex::new(Vec::new());+ let questions: Vec<String> = (0..70).map(|index| format!("Question {index}?")).collect();++ let decision = decide_in_batches(+ &json!({ "request": "anything" }),+ &questions,+ Duration::from_secs(1),+ |request: DecisionRequest| {+ request.validate().unwrap();+ sizes.lock().unwrap().push(request.questions.len());+ async move {+ // Questions 32 to 63 never answer; 64 to 69 fail.+ if request+ .questions+ .values()+ .any(|question| question == "Question 40?")+ {+ std::future::pending::<()>().await;+ }+ if request+ .questions+ .values()+ .any(|question| question == "Question 69?")+ {+ return Err("unavailable");+ }+ let probabilities: BTreeMap<String, f32> = request+ .questions+ .into_iter()+ .map(|(key, question)| {+ let index: f32 = question+ .trim_start_matches("Question ")+ .trim_end_matches('?')+ .parse()+ .unwrap();+ (key, index / 100.0)+ })+ .collect();+ Ok(DecisionResponse { probabilities })+ }+ },+ )+ .await;++ assert_eq!(*sizes.lock().unwrap(), [32, 32, 6]);+ assert_eq!(decision.batches, 3);+ assert_eq!(decision.outcome(), BatchedOutcome::Answered);+ assert_eq!(decision.answers.len(), 70);+ assert_eq!(decision.answers[0], Answer::Probability(0.0));+ assert_eq!(decision.answers[10], Answer::Probability(0.1));+ assert_eq!(decision.answers[31], Answer::Probability(0.31));+ assert_eq!(decision.answers[32], Answer::TimedOut);+ assert_eq!(decision.answers[63], Answer::TimedOut);+ assert_eq!(decision.answers[64], Answer::Failed);+ assert_eq!(decision.answers[69], Answer::Failed);+}++#[tokio::test(start_paused = true)]+async fn no_answering_call_reports_why() {+ let questions = vec!["Is it relevant?".to_owned()];++ let late = decide_in_batches(+ &json!({}),+ &questions,+ Duration::from_secs(1),+ |_: DecisionRequest| async {+ std::future::pending::<()>().await;+ Ok::<_, &str>(DecisionResponse {+ probabilities: BTreeMap::new(),+ })+ },+ )+ .await;+ assert_eq!(late.outcome(), BatchedOutcome::TimedOut);++ let failed = decide_in_batches(+ &json!({}),+ &questions,+ Duration::from_secs(1),+ |_: DecisionRequest| async { Err::<DecisionResponse, _>("unavailable") },+ )+ .await;+ assert_eq!(failed.outcome(), BatchedOutcome::Failed);+}diff --git a/crates/skills/src/domain/selection.rs b/crates/skills/src/domain/selection.rsindex a0b9ba4778..aba1a6c8c5 100644--- a/crates/skills/src/domain/selection.rs+++ b/crates/skills/src/domain/selection.rs@@ -3,9 +3,9 @@//!//! The user's most recently updated skills are the candidates. Jev answers one//! yes/no question per candidate, built from its "Use when …" description, at-//! most 32 per call, so candidates are split into parallel calls, at most-//! [`MAX_CALLS`]. A skill redirects the agent, so only a confident match-//! loads.+//! most 32 per call, so candidates are split into parallel calls+//! ([`decide_in_batches`]), at most [`MAX_CALLS`]. A skill redirects the+//! agent, so only a confident match loads.#[cfg(test)]mod test;@@ -13,7 +13,7 @@ mod test;use std::sync::Arc;use std::time::Duration;-use cognition::domain::{Cognition, DecisionRequest};+use cognition::domain::{Answer, BatchedOutcome, Cognition, MAX_QUESTIONS, decide_in_batches};use futures::future::join_all;use macro_user_id::user_id::MacroUserIdStr;use tokio_util::sync::CancellationToken;@@ -22,12 +22,11 @@ use uuid::Uuid;use crate::domain::model::{SkillError, SkillSummary};use crate::domain::ports::SkillService;-/// Questions Jev answers in one call.-const QUESTIONS_PER_CALL: usize = 32;/// Parallel Jev calls per turn; candidates past `MAX_CALLS * 32` are not/// routed, and stay reachable through `ReadSkill`.pub const MAX_CALLS: usize = 8;-/// How long the turn waits for Jev.+/// How long the turn waits for Jev; calls that miss it lose only their own+/// candidates.const DECISION_DEADLINE: Duration = Duration::from_secs(1);/// How long the turn waits for the chosen skills' instructions.const READ_DEADLINE: Duration = Duration::from_secs(1);@@ -81,7 +80,7 @@ pub enum SelectionStatus {Cancelled,/// Listing skills or every Jev call failed.ProviderError,- /// Jev did not answer before the deadline.+ /// No Jev call answered before the deadline.Timeout,}@@ -217,19 +216,16 @@ async fn select<Svc: SkillService>(if candidates.is_empty() {return SkillSelection::nothing(0, SelectionStatus::NoCandidates);}- let scored = tokio::select! {+ let scores = tokio::select! {biased;_ = cancel.cancelled() => {return SkillSelection::nothing(candidates.len(), SelectionStatus::Cancelled);}- scored = tokio::time::timeout(DECISION_DEADLINE, score(cognition.as_ref(), user, request, &candidates)) => scored,+ scores = score(cognition.as_ref(), user, request, &candidates) => scores,};- let scores = match scored {- Ok(Some(scores)) => scores,- Ok(None) => {- return SkillSelection::nothing(candidates.len(), SelectionStatus::ProviderError);- }- Err(_) => return SkillSelection::nothing(candidates.len(), SelectionStatus::Timeout),+ let scores = match scores {+ Ok(scores) => scores,+ Err(status) => return SkillSelection::nothing(candidates.len(), status),};let top_score = scores.iter().map(|(_, score)| *score).reduce(f32::max);let (chosen, suggested) = choose(scores);@@ -261,49 +257,42 @@ fn candidates(.filter(|skill| !already_loaded.contains(&skill.document_id)).filter(|skill| !request.latest.contains(&skill.document_id.to_string())).collect();- candidates.truncate(MAX_CALLS * QUESTIONS_PER_CALL);+ candidates.truncate(MAX_CALLS * MAX_QUESTIONS);candidates}-/// Every candidate's score, or `None` when no call succeeded.+/// Every candidate's score from the calls that answered by the deadline, or+/// why none did.async fn score(cognition: &dyn Cognition,user: &MacroUserIdStr<'static>,request: SkillRequest<'_>,candidates: &[SkillSummary],-) -> Option<Vec<(SkillSummary, f32)>> {+) -> Result<Vec<(SkillSummary, f32)>, SelectionStatus> {let mut input = serde_json::json!({ "request": clip(request.latest, MAX_REQUEST_CHARS) });if let Some(previous) = request.previous {input["previousRequest"] = clip(previous, MAX_REQUEST_CHARS).into();}- let calls = candidates.chunks(QUESTIONS_PER_CALL).map(|chunk| {- let request = DecisionRequest {- input: input.clone(),- questions: chunk- .iter()- .map(|skill| (skill.document_id.to_string(), question(skill)))- .collect(),- };+ let questions: Vec<String> = candidates.iter().map(question).collect();+ let decision = decide_in_batches(&input, &questions, DECISION_DEADLINE, |request| {cognition.decide(user, request)- });- let answers = join_all(calls).await;- let mut scores = Vec::new();- let mut answered = false;- for answer in answers {- match answer {- Ok(answer) => {- answered = true;- scores.extend(answer.probabilities.into_iter().filter_map(|(key, score)| {- let skill = candidates- .iter()- .find(|skill| skill.document_id.to_string() == key)?;- score.is_finite().then(|| (skill.clone(), score))- }));- }- Err(error) => tracing::warn!(error = %error, "Jev could not route skills"),- }+ })+ .await;++ match decision.outcome() {+ BatchedOutcome::Answered => {}+ BatchedOutcome::TimedOut => return Err(SelectionStatus::Timeout),+ BatchedOutcome::Failed => return Err(SelectionStatus::ProviderError),}- answered.then_some(scores)++ Ok(candidates+ .iter()+ .zip(decision.answers)+ .filter_map(|(skill, answer)| match answer {+ Answer::Probability(score) if score.is_finite() => Some((skill.clone(), score)),+ Answer::Probability(_) | Answer::Failed | Answer::TimedOut => None,+ })+ .collect())}fn question(skill: &SkillSummary) -> String {diff --git a/crates/skills/src/domain/selection/test.rs b/crates/skills/src/domain/selection/test.rsindex 5f53b96a4c..a670957024 100644--- a/crates/skills/src/domain/selection/test.rs+++ b/crates/skills/src/domain/selection/test.rs@@ -2,12 +2,21 @@ use std::collections::BTreeMap;use std::sync::Mutex;use async_trait::async_trait;-use cognition::domain::{DecisionResponse, GenerateObjectRequest, GenerateObjectResponse};+use cognition::domain::{+ DecisionRequest, DecisionResponse, GenerateObjectRequest, GenerateObjectResponse,+};use rootcause::Report;use super::*;use crate::domain::model::{SkillContent, SkillMatchType};+/// The numbered skill a question asks about (`Skills::numbered` names them+/// "Skill <id>").+fn asked_about(question: &str) -> Option<Uuid> {+ let id = question.split("\"Skill ").nth(1)?.split('"').next()?;+ Some(Uuid::from_u128(id.parse().ok()?))+}+/// Answers each question with the score its skill was given, 0.1 otherwise.struct Jev {scores: BTreeMap<Uuid, f32>,@@ -34,7 +43,13 @@ impl Jev {.lock().unwrap().iter()- .map(|request| request.questions.keys().cloned().collect())+ .map(|request| {+ request+ .questions+ .values()+ .map(|question| asked_about(question).unwrap().to_string())+ .collect()+ }).collect()}}@@ -56,10 +71,12 @@ impl Cognition for Jev {) -> Result<DecisionResponse, Report> {let probabilities = request.questions- .keys()- .map(|key| {- let id: Uuid = key.parse().unwrap();- (key.clone(), self.scores.get(&id).copied().unwrap_or(0.1))+ .iter()+ .map(|(key, question)| {+ let score = asked_about(question)+ .and_then(|id| self.scores.get(&id).copied())+ .unwrap_or(0.1);+ (key.clone(), score)}).collect();self.calls.lock().unwrap().push(request);@@ -365,14 +382,14 @@ async fn the_classifier_sees_the_request_and_each_description() {request.input,serde_json::json!({"request": "now do it for Q3", "previousRequest": "summarise Q2 revenue"}));+ let questions: Vec<&String> = request.questions.values().collect();assert_eq!(- request.questions[&Uuid::from_u128(1).to_string()],- "Would the skill \"Release notes\" help with this request? Use when drafting release notes; not changelogs"- );- // A skill made before descriptions existed routes on its name.- assert_eq!(- request.questions[&Uuid::from_u128(2).to_string()],- "Would the skill \"Old skill\" help with this request?"+ questions,+ [+ "Would the skill \"Release notes\" help with this request? Use when drafting release notes; not changelogs",+ // A skill made before descriptions existed routes on its name.+ "Would the skill \"Old skill\" help with this request?",+ ]);}diff --git a/docs/architecture/agent-sdk-guidance.md b/docs/architecture/agent-sdk-guidance.mdindex 326d934442..cd27bc7fc6 100644--- a/docs/architecture/agent-sdk-guidance.md+++ b/docs/architecture/agent-sdk-guidance.md@@ -30,7 +30,7 @@ code-mode agent turn ────┤ prompt = cross-cutting rules + inline_guidprompt = cross-cutting rules (routed_prompt) │turn = select_documentation(Selected): │Jev over every entity's @routing sentence, │- 32 per call, ≤8 calls, 1 s, ≥0.5, top 4 → │+ parallel calls of 32, 1 s, ≥0.5, top 4 → │index + @agent guide per entity │direct-tool hosts (chat, channel bot): prompt + inline guides that do not need the SDKdatabase-only host: base prompt + the databases guide@@ -39,7 +39,9 @@ public MCP: shared rules + databases, CRM and document-content guides;```The selection runs in the turn's pre-turn join, alongside the memory fetch.-Its span records the selected entities, bytes and status.+Its span records the Jev calls (`batches`), selected entities, bytes and+status. A call that fails or misses the deadline loses only its own entities;+the turn keeps what the other calls ranked.## Where to change thingsdiff --git a/docs/architecture/agent-skills.md b/docs/architecture/agent-skills.mdindex aa967e9118..1d55222574 100644--- a/docs/architecture/agent-skills.md+++ b/docs/architecture/agent-skills.md@@ -30,7 +30,8 @@ turn ─┬─ memory, SDK docs, auto model ...list ≤256 of the user's skills (soup, access-checked), newest first,with descriptions; skip ones this session loaded or the request @mentionsceil(n/32) parallel Jev calls (≤8): "Would skill X help? <description>"- 1 s deadline; any failure loads nothing and the turn runs as usual+ 1 s deadline; a late or failed call loses only its own skills, and+ when none answers nothing loads and the turn runs as usualload ≥0.8 (≥0.95 without a description), at most 2, most relevant firstread bodies through ReadSkill's access check, 1 s▼diff --git a/packages/code-mode-sdk/AGENTS.md b/packages/code-mode-sdk/AGENTS.mdindex af8be3b822..50997af2a6 100644--- a/packages/code-mode-sdk/AGENTS.md+++ b/packages/code-mode-sdk/AGENTS.md@@ -12,12 +12,9 @@ HTML worker belong to `packages/sdk-docs`.the directory it is given; `crates/code_mode_assets` runs it at build time.- `scripts/typedoc.ts`: index each entity and split linked Markdown intoper-symbol references (classes, methods, types).-- `scripts/catalog.ts`: the entity directories agents discover; agent and- harness docs share a topic, as do native channels, external chats and- WhatsApp, and cross-type search, workspace browsing and AI chats- (`search`, whose guide is the `search` topic), and the web and URL previews- (`web`). Keep the catalog at 32- entities or fewer: Jev ranks them in one 32-question call.+- `scripts/catalog.ts`: the entity directories agents discover, one entity+ each. Never fold an area into another to save room: Jev routes the catalog+ in parallel 32-question calls, so its size is not capped.- Each entity's description is its one `@routing` sentence ("Use when …; not…") and its `guide` every `@agent` block, both from the SDK's TSDoc andcollected by `packages/sdk-docs/src/render.ts`. Generation fails for andiff --git a/packages/code-mode-sdk/scripts/catalog.ts b/packages/code-mode-sdk/scripts/catalog.tsindex be6527b4f3..123009018a 100644--- a/packages/code-mode-sdk/scripts/catalog.ts+++ b/packages/code-mode-sdk/scripts/catalog.ts@@ -5,6 +5,7 @@export const entityDirectories: readonly string[] = ['agent-sessions','agents',+ 'harnesses','api-keys','entity-mentions','github-pull-requests',@@ -12,13 +13,19 @@ export const entityDirectories: readonly string[] = ['meetings','routines','search',+ 'workspace',+ 'chats',+ 'unfurls','web','ai',+ 'images','bots','calendar','calls','channels','connected-apps',+ 'external-chat',+ 'whatsapp','crm','databases','documents',@@ -27,11 +34,13 @@ export const entityDirectories: readonly string[] = ['foreign','forms','notifications',+ 'pins','projects','properties','referrals','tasks','teams','users',+ 'me','webhooks',];diff --git a/packages/code-mode-sdk/scripts/typedoc.ts b/packages/code-mode-sdk/scripts/typedoc.tsindex 4349940b4b..fb24a088cf 100644--- a/packages/code-mode-sdk/scripts/typedoc.ts+++ b/packages/code-mode-sdk/scripts/typedoc.ts@@ -86,26 +86,7 @@ export function packageEntityDocs(: directory.replace(/-([a-z])/g, (_, letter: string) =>letter.toUpperCase()),- // Agent and host setup share one discovery topic, as do AI calls and- // image generation, searching, browsing and AI chats, the web and URL- // previews, and favorites and pins, keeping the classifier request- // within its 32-question contract as the public API grows.- prefixes: (directory === 'agents'- ? ['agents', 'harnesses']- : directory === 'channels'- ? ['channels', 'external-chat', 'whatsapp']- : directory === 'ai'- ? ['ai', 'images']- : directory === 'users'- ? ['users', 'me']- : directory === 'search'- ? ['search', 'workspace', 'chats']- : directory === 'web'- ? ['web', 'unfurls']- : directory === 'favorites'- ? ['favorites', 'pins']- : [directory]- ).map((value) => `src/entities/${value}/`),+ prefixes: [`src/entities/${directory}/`],})),{ name: 'core', prefixes: core },];diff --git a/packages/code-mode-sdk/src/documentation.test.ts b/packages/code-mode-sdk/src/documentation.test.tsindex 25705c2558..15f8198634 100644--- a/packages/code-mode-sdk/src/documentation.test.ts+++ b/packages/code-mode-sdk/src/documentation.test.ts@@ -250,23 +250,31 @@ describe('TypeDoc documentation packaging', () => {expect(docs.symbols.Macro).toContain('`workspace`');expect(docs.symbols.Macro).toContain('`chats`');expect(entity('routines')).toContain('`RoutineOptions`');- expect(entity('agents')).toContain('### HarnessNamespace');+ expect(entity('harnesses')).toContain('### HarnessNamespace');+ expect(entity('agents')).not.toContain('HarnessNamespace');expect(entity('apiKeys')).toContain('### UserApiKey');expect(entity('entityMentions')).toContain('EntityMentionNamespace');expect(entity('githubPullRequests')).toContain('PullRequestChangeset');expect(entity('core')).toContain('`SharePermissionOptions`');- // Searching, browsing the workspace and reading AI chats share one entity.expect(entity('search')).toContain('### SearchNamespace (`macro.search`)');expect(entity('search')).toContain('`SearchNamespace.all`');- expect(entity('search')).toContain(+ expect(entity('workspace')).toContain('### WorkspaceNamespace (`macro.workspace`)');- expect(entity('search')).toContain('### ChatNamespace (`macro.chats`)');- expect(entity('search')).toContain('`Chat.history`');+ expect(entity('chats')).toContain('### ChatNamespace (`macro.chats`)');+ expect(entity('chats')).toContain('`Chat.history`');expect(entity('core')).not.toContain('SearchNamespace');expect(docs.symbols.SearchOptions).toContain('agentSessions');expect(docs.symbols.WorkspaceType).toContain('agent_session');- expect(docs.entities.length).toBeLessThanOrEqual(32);+ // Jev routes the catalog 32 entities per call, so every SDK directory is+ // its own entity, asked about with its own routing sentence.+ expect(docs.entities.length).toBeGreaterThan(32);+ expect(entity('unfurls')).toContain('### UnfurlNamespace');+ expect(entity('web')).not.toContain('UnfurlNamespace');+ expect(entity('pins')).toContain('### PinsNamespace');+ expect(entity('favorites')).not.toContain('PinsNamespace');+ expect(entity('images')).toContain('### ImagesNamespace');+ expect(entity('me')).toContain('### MeNamespace');for (const doc of docs.entities)expect(Buffer.byteLength(doc.index)).toBeLessThan(16 * 1024);for (const reference of Object.values(docs.symbols)) {@@ -276,12 +284,13 @@ describe('TypeDoc documentation packaging', () => {});});-it('external chats and WhatsApp share the channels discovery topic without pairing methods', async () => {+it('external chats and WhatsApp are their own entities without pairing methods', async () => {const docs = JSON.parse(await readFile(artifact, 'utf8')) as SdkDocs;- const channels = docs.entities.find((entry) => entry.name === 'channels');- expect(channels?.index).toContain('ExternalChatsNamespace');- expect(channels?.index).toContain('ExternalChat');- expect(channels?.index).toContain('WhatsAppNamespace');- expect(channels?.index).toContain('.chats`');- expect(channels?.index).not.toContain('whatsappConnect');+ const index = (name: string) =>+ docs.entities.find((entry) => entry.name === name)?.index;+ expect(index('externalChat')).toContain('ExternalChatsNamespace');+ expect(index('whatsapp')).toContain('WhatsAppNamespace');+ expect(index('whatsapp')).toContain('.chats`');+ expect(index('whatsapp')).not.toContain('whatsappConnect');+ expect(index('channels')).not.toContain('WhatsAppNamespace');});diff --git a/packages/sdk/src/entities/ai/namespace.ts b/packages/sdk/src/entities/ai/namespace.tsindex 048555088d..93c016d4a7 100644--- a/packages/sdk/src/entities/ai/namespace.ts+++ b/packages/sdk/src/entities/ai/namespace.ts@@ -19,7 +19,7 @@ export type {/*** Shared cognition endpoints, charged to the authenticated acting user.*- * @routing Use when generating structured objects or images, or classifying supplied content with Jev; not answering the user yourself.+ * @routing Use when generating structured objects or classifying supplied content with Jev; not generating images (`macro.images`) or answering the user yourself.*/export class AiNamespace {/** Read AI usage over a time range, optionally restricting it to users. */diff --git a/packages/sdk/src/entities/channels/namespace.ts b/packages/sdk/src/entities/channels/namespace.tsindex 8efc4ec56d..6fec049c53 100644--- a/packages/sdk/src/entities/channels/namespace.ts+++ b/packages/sdk/src/entities/channels/namespace.ts@@ -15,7 +15,7 @@ import { ChannelLabelsNamespace } from './labels';const CHANNEL_PAGE_SIZE = 100;/**- * @routing Use when reading or sending channel and direct messages, posting a poll, reacting, managing members, or WhatsApp and external chats; not email.+ * @routing Use when reading or sending channel and direct messages, posting a poll, reacting or managing members; not email, or WhatsApp and other external chats (`macro.externalChats`).** @agent* ## Pollsdiff --git a/packages/sdk/src/entities/chats/namespace.ts b/packages/sdk/src/entities/chats/namespace.tsindex 752a1d883c..eff812e71a 100644--- a/packages/sdk/src/entities/chats/namespace.ts+++ b/packages/sdk/src/entities/chats/namespace.ts@@ -10,6 +10,8 @@ import { Chat } from './chat';* `macro.workspace.list({includeTypes: ['ai_chat']})`, then read it with* `chat.history()`. Agent work and coding sessions are agent sessions, not* chats.+ *+ * @routing Use when reading or continuing one of the user's AI chats with Macro's assistant; not agent sessions or channels.*/export class ChatNamespace {constructor(private readonly client: MacroClient) {}diff --git a/packages/sdk/src/entities/external-chat/namespace.ts b/packages/sdk/src/entities/external-chat/namespace.tsindex 2032a28a1d..1ba9701382 100644--- a/packages/sdk/src/entities/external-chat/namespace.ts+++ b/packages/sdk/src/entities/external-chat/namespace.ts@@ -6,6 +6,8 @@ import { ExternalChat } from './chat';* Chats from external messaging providers (WhatsApp today) that someone added* to Macro: read, share and send in them. Find and add a provider's chats* through its own namespace, such as `macro.whatsapp.chats()`.+ *+ * @routing Use when reading, sharing or sending in an external chat, such as a WhatsApp chat, already added to Macro; not Macro channels, or finding chats to add (`macro.whatsapp`).*/export class ExternalChatsNamespace {/** Bind external chat operations to this authenticated client. */diff --git a/packages/sdk/src/entities/favorites/namespace.ts b/packages/sdk/src/entities/favorites/namespace.tsindex 19b2e39315..60bb2910a4 100644--- a/packages/sdk/src/entities/favorites/namespace.ts+++ b/packages/sdk/src/entities/favorites/namespace.ts@@ -24,7 +24,7 @@ export type FavoritesFilter = {/*** The user's favorites: a manually ordered collection of entity references.*- * @routing Use when adding or removing the user's favorites or pinned home-view slots (`macro.pins`); not tags or properties.+ * @routing Use when adding or removing the user's favorites; not pins (`macro.pins`).*/export class FavoritesNamespace {constructor(private readonly client: MacroClient) {}diff --git a/packages/sdk/src/entities/harnesses/namespace.ts b/packages/sdk/src/entities/harnesses/namespace.tsindex 85e5e002ce..4c078ea21d 100644--- a/packages/sdk/src/entities/harnesses/namespace.ts+++ b/packages/sdk/src/entities/harnesses/namespace.ts@@ -6,7 +6,11 @@ import { Agent } from '../agents/agent';import { Harness } from './harness';import { DevicePairing, HarnessPairing } from './pairing';-/** Hosts and device pairing. Self operations require host credentials. */+/**+ * Hosts and device pairing. Self operations require host credentials.+ *+ * @routing Use when listing, pairing or removing the machines (hosts) that run the user's agents; not changing an agent persona's setup (`macro.agents`).+ */export class HarnessNamespace {constructor(private readonly client: MacroClient) {}diff --git a/packages/sdk/src/entities/images/namespace.ts b/packages/sdk/src/entities/images/namespace.tsindex c7481b4feb..e4d91eadf4 100644--- a/packages/sdk/src/entities/images/namespace.ts+++ b/packages/sdk/src/entities/images/namespace.ts@@ -30,7 +30,11 @@ export interface GenerateImageOptions {referenceImages?: (Document | StaticImage)[];}-/** Image generation, charged to the acting user's AI allowance. */+/**+ * Image generation, charged to the acting user's AI allowance.+ *+ * @routing Use when generating an image; not structured output or classification (`macro.ai`).+ */export class ImagesNamespace {constructor(private readonly client: MacroClient) {}diff --git a/packages/sdk/src/entities/me/namespace.ts b/packages/sdk/src/entities/me/namespace.tsindex 9768fa9c39..7bbbf3ec0d 100644--- a/packages/sdk/src/entities/me/namespace.ts+++ b/packages/sdk/src/entities/me/namespace.ts@@ -18,7 +18,11 @@ export interface UpdateMeOptions {profilePicture?: StaticImage;}-/** The authenticated user's own profile. */+/**+ * The authenticated user's own profile.+ *+ * @routing Use when changing the user's own name or profile picture; not looking up other people (`macro.users`).+ */export class MeNamespace {constructor(private readonly client: MacroClient) {}diff --git a/packages/sdk/src/entities/pins/namespace.ts b/packages/sdk/src/entities/pins/namespace.tsindex f3341beaf7..b6c9d758a4 100644--- a/packages/sdk/src/entities/pins/namespace.ts+++ b/packages/sdk/src/entities/pins/namespace.ts@@ -10,6 +10,8 @@ export type { PinnedItem, ReorderPinRequest };/*** The user's pins: items pinned to fixed slots in the home view.+ *+ * @routing Use when pinning or unpinning items; not favorites (`macro.favorites`).*/export class PinsNamespace {constructor(private readonly client: MacroClient) {}diff --git a/packages/sdk/src/entities/search/namespace.ts b/packages/sdk/src/entities/search/namespace.tsindex 5b6172b842..c561208063 100644--- a/packages/sdk/src/entities/search/namespace.ts+++ b/packages/sdk/src/entities/search/namespace.ts@@ -68,7 +68,7 @@ const searchTypes: readonly SearchType[] = [* handles, with the same filters as the per-type searches and more: exact* matching, tags, one inbox and agent session transcripts.*- * @routing Use when finding, looking up or listing the user's own Macro content, across types or in one, browsing recent or filtered workspace items, or reading an AI chat; not the web, and not one item already in context.+ * @routing Use when finding or looking up the user's own Macro content by keyword, across types or in one; not browsing recent items (`macro.workspace`), the web, or one item already in context.** @agent* Search is keyword search, not semantic: pass 1-3 words that would literally appear in the item, not the user's description. Whitespace-separated terms are ANDed; for documents and email each word is a prefix and terms may match different passages, while for other kinds the query is one adjacent phrase prefix, so long phrases match nothing. Quote a multi-word phrase; use matchType 'exact' for a whole word, identifier or email address. Search a person and a topic separately. To find someone's email, search their quoted address, not their name.diff --git a/packages/sdk/src/entities/unfurls/namespace.ts b/packages/sdk/src/entities/unfurls/namespace.tsindex 24f558ad35..5938c31cbe 100644--- a/packages/sdk/src/entities/unfurls/namespace.ts+++ b/packages/sdk/src/entities/unfurls/namespace.ts@@ -2,7 +2,9 @@ import { unwrap } from '../../utils';import type { MacroClient } from '../../utils/client';/**- * URL metadata lookup. Discovered with `macro.web`.+ * URL metadata lookup.+ *+ * @routing Use when reading a URL's preview metadata; not fetching or searching the web.*/export class UnfurlNamespace {constructor(private readonly client: MacroClient) {}diff --git a/packages/sdk/src/entities/users/namespace.ts b/packages/sdk/src/entities/users/namespace.tsindex f55bce6ff4..93e0bc33ed 100644--- a/packages/sdk/src/entities/users/namespace.ts+++ b/packages/sdk/src/entities/users/namespace.ts@@ -3,7 +3,7 @@ import type { MacroClient } from '../../utils/client';import { User } from './user';/**- * @routing Use when looking up people or their profiles, or changing the user's own name or picture; not team membership.+ * @routing Use when looking up people or their profiles; not team membership, or changing the user's own profile (`macro.me`).*/export class UserNamespace {constructor(private readonly client: MacroClient) {}diff --git a/packages/sdk/src/entities/web/namespace.ts b/packages/sdk/src/entities/web/namespace.tsindex 0940b1d399..60b0c5885f 100644--- a/packages/sdk/src/entities/web/namespace.ts+++ b/packages/sdk/src/entities/web/namespace.ts@@ -34,7 +34,7 @@ export interface WebFetchOptions {* Search the public web and read web pages, charged to the acting user's AI* allowance.*- * @routing Use when finding or reading information on the public internet, or reading a URL's preview metadata (`macro.unfurls`); not searching the user's Macro workspace (`macro.search`).+ * @routing Use when finding or reading information on the public internet; not searching the user's Macro workspace (`macro.search`) or reading a URL's preview card (`macro.unfurls`).** @agent Search returns snippets, which often answer the question on their* own; fetch a result's URL only when you need the whole page. Cite the URL ofdiff --git a/packages/sdk/src/entities/whatsapp/namespace.ts b/packages/sdk/src/entities/whatsapp/namespace.tsindex 8430905265..ec7ffe50e9 100644--- a/packages/sdk/src/entities/whatsapp/namespace.ts+++ b/packages/sdk/src/entities/whatsapp/namespace.ts@@ -7,6 +7,8 @@ import { WhatsAppChat } from './chat';* The current user's WhatsApp account, paired through the Macro app, and its* chat list. Added chats are external chats: read and send in them through* `macro.externalChats`.+ *+ * @routing Use when checking the user's paired WhatsApp account or listing its chats to add to Macro; not reading or sending in an added chat (`macro.externalChats`).*/export class WhatsAppNamespace {/** Bind existing-account operations to this authenticated client. */diff --git a/packages/sdk/src/entities/workspace/namespace.ts b/packages/sdk/src/entities/workspace/namespace.tsindex f71f9b0acc..a12b8729fc 100644--- a/packages/sdk/src/entities/workspace/namespace.ts+++ b/packages/sdk/src/entities/workspace/namespace.ts@@ -79,6 +79,8 @@ import type {* (owner principal), `src` and `vis`. Filters remain server-validated.* CRM, initiatives and database rows have their own namespaces and are not* included in this browsing surface.+ *+ * @routing Use when browsing the user's recent or filtered workspace items, such as what changed today; not keyword search (`macro.search`).*/export class WorkspaceNamespace {constructor(private readonly client: MacroClient) {}