Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(agents): route skills and SDK entities through one batched Jev path (#9875)

Wolf Mermelstein6fe2c83eb50d
diff --git a/Cargo.lock b/Cargo.lock
index 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.md
index 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 to
the 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 injected
transaction-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 schema
validation.
-- 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.rs
index 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.rs
index 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.rs
index 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.md
index 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.toml
index 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.rs
index 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.md
index 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 and
cancellation-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 TypeSafe
and Cloudflare Workers AI (feature `outbound`).
diff --git a/crates/jev/Cargo.toml b/crates/jev/Cargo.toml
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.md
index 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_guid
prompt = 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 SDK
database-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 things
diff --git a/docs/architecture/agent-skills.md b/docs/architecture/agent-skills.md
index 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 @mentions
ceil(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 usual
load ≥0.8 (≥0.95 without a description), at most 2, most relevant first
read bodies through ReadSkill's access check, 1 s
▼
diff --git a/packages/code-mode-sdk/AGENTS.md b/packages/code-mode-sdk/AGENTS.md
index 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 into
per-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 and
collected by `packages/sdk-docs/src/render.ts`. Generation fails for an
diff --git a/packages/code-mode-sdk/scripts/catalog.ts b/packages/code-mode-sdk/scripts/catalog.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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
* ## Polls
diff --git a/packages/sdk/src/entities/chats/namespace.ts b/packages/sdk/src/entities/chats/namespace.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 of
diff --git a/packages/sdk/src/entities/whatsapp/namespace.ts b/packages/sdk/src/entities/whatsapp/namespace.ts
index 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.ts
index 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) {}