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
fix(agent): record OpenAI token usage on spans and in metering (#7542)
Wolf Mermelstein73690f54adf5
diff --git a/apps/web/src/lib/core/agent-session/AgentSession.test.ts b/apps/web/src/lib/core/agent-session/AgentSession.test.tsindex fdde1bac15..53a035ce3d 100644--- a/apps/web/src/lib/core/agent-session/AgentSession.test.ts+++ b/apps/web/src/lib/core/agent-session/AgentSession.test.ts@@ -995,7 +995,7 @@ describe('AgentSession', () => {});describe('prompt telemetry', () => {- it('posts a prompt inside its span and ends it at the first agent output', async () => {+ it('posts a prompt inside its span and ends it at the first painted agent text', async () => {let postedUnder: RecordedSpan | undefined;harness.control.mockImplementation(async (_id: string, request: { actionId: string }) => {@@ -1047,6 +1047,31 @@ describe('AgentSession', () => {] satisfies FoldedStreamEvent[]);AgentSession.ingest({ agentSessionId: SESSION, entries: [row(2)] });await settle();+ expect(span.ends).toBe(0);+ expect(span.attributes['agent.prompt.first_output_part']).toBe('thought');++ fold.pushSession.mockResolvedValueOnce([+ {+ kind: 'update',+ message: {+ agentSessionId: SESSION,+ turn: 1,+ author: { kind: 'agent' },+ requestId: null,+ parts: [+ { kind: 'thought', text: 'thinking' },+ { kind: 'text', text: 'Hello' },+ ],+ stop: null,+ pending: false,+ },+ },+ ] satisfies FoldedStreamEvent[]);+ AgentSession.ingest({ agentSessionId: SESSION, entries: [row(3)] });+ await settle();+ await new Promise((resolve) =>+ requestAnimationFrame(() => requestAnimationFrame(resolve))+ );expect(span.ends).toBe(1);expect(span.attributes).toMatchObject({@@ -1055,11 +1080,15 @@ describe('AgentSession', () => {'agent.prompt.action_id': actionId,'agent.prompt.turn': 1,'agent.prompt.first_output_part': 'thought',- 'agent.prompt.outcome': 'output',+ 'agent.prompt.first_text_via': 'socket',+ 'agent.prompt.outcome': 'text',});+ expect(span.attributes['agent.prompt.first_text_paint_at_ms']).toEqual(+ expect.any(Number)+ );live.release();expect(span.ends).toBe(1);- expect(span.attributes['agent.prompt.outcome']).toBe('output');+ expect(span.attributes['agent.prompt.outcome']).toBe('text');});it('traces no action but a prompt', async () => {diff --git a/apps/web/src/lib/core/agent-session/AgentSession.ts b/apps/web/src/lib/core/agent-session/AgentSession.tsindex 34a31fafec..87de9e6156 100644--- a/apps/web/src/lib/core/agent-session/AgentSession.ts+++ b/apps/web/src/lib/core/agent-session/AgentSession.ts@@ -50,7 +50,7 @@ import type {import { subscribeGraphqlSoupReconnected } from '@service-storage/graphql-soup';import { v7 as uuidv7 } from 'uuid';import { SessionLoadTrace, traceAcquire } from './load-telemetry';-import { PromptTrace } from './prompt-telemetry';+import { frameDelivery, PromptTrace } from './prompt-telemetry';import { publishSessionTurn } from './session-turn';export type AgentSessionListener = (events: FoldedStreamEvent[]) => void;@@ -678,6 +678,16 @@ export class AgentSession {}private apply(inputs: FoldInput[]): Promise<void> {+ // Taken now, not after the chain: waiting for earlier pushes is part of+ // what a prompt's fold stage costs.+ const pushed = inputs.flatMap((input) =>+ input.kind === 'confirmed' ? [input.row] : []+ );+ const snapshot = inputs.find((input) => input.kind === 'snapshot');+ const delivery =+ pushed.length > 0+ ? frameDelivery('socket', pushed)+ : snapshot && frameDelivery('snapshot', snapshot.rows);const run = this.chain.then(async () => {if (this.closed) return;const events = await pushSession(this.id, inputs);@@ -686,7 +696,7 @@ export class AgentSession {if (metadata) this.setTurn(metadata.metadata.turn);for (const listener of this.listeners) listener(events);for (const prompt of this.prompts) {- prompt.observe(events);+ prompt.observe(events, delivery);if (prompt.ended) this.prompts.delete(prompt);}});diff --git a/apps/web/src/lib/core/agent-session/prompt-telemetry.test.ts b/apps/web/src/lib/core/agent-session/prompt-telemetry.test.tsindex 3afbcd8fbe..f4ff840555 100644--- a/apps/web/src/lib/core/agent-session/prompt-telemetry.test.ts+++ b/apps/web/src/lib/core/agent-session/prompt-telemetry.test.ts@@ -1,6 +1,7 @@/*** The `agent.prompt` span read off literal fold events: the confirmed user- * message fixes the turn, the first agent message in it ends the span.+ * message fixes the turn, and the turn's first agent text, once painted,+ * ends the span.*/import type { FoldedStreamEvent } from '@service-agent-fold/generated/types';@@ -46,7 +47,7 @@ vi.mock('@macro-inc/observability', () => ({},}));-import { PromptTrace } from './prompt-telemetry';+import { frameDelivery, PromptTrace } from './prompt-telemetry';const SESSION = '01a0abed-279f-724c-9f49-60dbedc79b6e';const ACTION = '01a0abed-3000-7000-8000-000000000001';@@ -57,10 +58,16 @@ beforeEach(() => {afterEach(() => {vi.useRealTimers();+ vi.unstubAllGlobals();+ vi.restoreAllMocks();});describe('PromptTrace', () => {- it('records the prompt from acceptance through confirmation to the first agent output', () => {+ it('records the prompt from acceptance through confirmation to the first painted text', () => {+ vi.useFakeTimers();+ vi.stubGlobal('requestAnimationFrame', (callback: () => void) =>+ setTimeout(callback, 16)+ );const trace = new PromptTrace(SESSION, { newSession: false });trace.expect(ACTION);trace.accepted(ACTION, false);@@ -111,6 +118,8 @@ describe('PromptTrace', () => {];trace.observe(output);trace.observe(output);+ expect(trace.ended).toBe(false);+ vi.advanceTimersByTime(32);expect(telemetry.spans).toHaveLength(1);const [span] = telemetry.spans;@@ -122,10 +131,16 @@ describe('PromptTrace', () => {'agent.prompt.action_id': ACTION,'agent.prompt.turn': 1,'agent.prompt.first_output_part': 'text',- 'agent.prompt.outcome': 'output',+ 'agent.prompt.outcome': 'text',});expect(span.attributes).not.toHaveProperty('agent.prompt.queued');- for (const stage of ['accepted', 'confirmed', 'first_output']) {+ for (const stage of [+ 'accepted',+ 'confirmed',+ 'first_output',+ 'first_text',+ 'first_text_paint',+ ]) {expect(span.attributes[`agent.prompt.${stage}_at_ms`]).toEqual(expect.any(Number));@@ -137,10 +152,110 @@ describe('PromptTrace', () => {'agent.prompt.accepted','agent.prompt.confirmed','agent.prompt.first_output',+ 'agent.prompt.first_text',+ 'agent.prompt.first_text_paint',]);expect(trace.ended).toBe(true);});+ it('ends with no_text when the turn stops after only reasoning', () => {+ const trace = new PromptTrace(SESSION, { newSession: false });+ trace.expect(ACTION);++ trace.observe([+ {+ kind: 'new',+ message: {+ agentSessionId: SESSION,+ turn: 0,+ author: { kind: 'user', userId: null },+ requestId: ACTION,+ parts: [{ kind: 'text', text: 'hi' }],+ stop: null,+ pending: false,+ },+ },+ {+ kind: 'new',+ message: {+ agentSessionId: SESSION,+ turn: 0,+ author: { kind: 'agent' },+ requestId: null,+ parts: [{ kind: 'thought', text: 'nothing to say' }],+ stop: { kind: 'end_turn' },+ pending: false,+ },+ },+ ]);++ const [span] = telemetry.spans;+ expect(span.ends).toBe(1);+ expect(span.attributes).toMatchObject({+ 'agent.prompt.first_output_part': 'thought',+ 'agent.prompt.stop': 'end_turn',+ 'agent.prompt.outcome': 'no_text',+ });+ });++ it('splits the first text into its delivery from the server and its fold', () => {+ vi.useFakeTimers();+ vi.setSystemTime(Date.parse('2026-10-05T12:00:00.250Z'));+ vi.spyOn(document, 'visibilityState', 'get').mockReturnValue('hidden');+ const trace = new PromptTrace(SESSION, { newSession: false });+ trace.expect(ACTION);+ const delivery = frameDelivery('socket', [+ { createdAt: '2026-10-05T12:00:00.100Z' },+ { createdAt: '2026-10-05T12:00:00.200Z' },+ ]);+ expect(delivery?.lagMs).toBe(50);+ expect(frameDelivery('snapshot', [])).toBeUndefined();++ trace.observe(+ [+ {+ kind: 'new',+ message: {+ agentSessionId: SESSION,+ turn: 0,+ author: { kind: 'user', userId: null },+ requestId: ACTION,+ parts: [{ kind: 'text', text: 'hi' }],+ stop: null,+ pending: false,+ },+ },+ {+ kind: 'new',+ message: {+ agentSessionId: SESSION,+ turn: 0,+ author: { kind: 'agent' },+ requestId: null,+ parts: [{ kind: 'text', text: 'Hello' }],+ stop: null,+ pending: false,+ },+ },+ ],+ delivery+ );++ // A hidden tab never paints, so the span ends at the first text.+ const [span] = telemetry.spans;+ expect(span.ends).toBe(1);+ expect(span.attributes).toMatchObject({+ 'agent.prompt.first_text_via': 'socket',+ 'agent.prompt.first_text_delivery_ms': 50,+ 'agent.prompt.first_text_fold_ms': 0,+ 'agent.prompt.hidden': true,+ 'agent.prompt.outcome': 'text',+ });+ expect(span.attributes).not.toHaveProperty(+ 'agent.prompt.first_text_paint_at_ms'+ );+ });+it('ends with no_output when the turn stops before the agent says anything', () => {const trace = new PromptTrace(SESSION, { newSession: true });trace.expect(ACTION);diff --git a/apps/web/src/lib/core/agent-session/prompt-telemetry.ts b/apps/web/src/lib/core/agent-session/prompt-telemetry.tsindex f66dce840e..6f9ff13206 100644--- a/apps/web/src/lib/core/agent-session/prompt-telemetry.ts+++ b/apps/web/src/lib/core/agent-session/prompt-telemetry.ts@@ -1,6 +1,6 @@/*** Telemetry for sending a prompt: from the moment a person sends it to the- * first agent output on screen, as one span.+ * agent's first text on screen, as one span.** Without it the flow is several unrelated traces (the create, the load, a* config control, the prompt control, the server's turn) and the waits in the@@ -22,8 +22,10 @@ import { match } from 'ts-pattern';/** How a sent prompt ended, as far as this span is concerned. */export type PromptOutcome =- /** The agent produced its first output for the prompt's turn. */- | 'output'+ /** The agent's first text for the prompt's turn was painted. */+ | 'text'+ /** The turn ended after reasoning or tool calls, without any text. */+ | 'no_text'/** The turn ended before the agent produced anything. */| 'no_output'/** The prompt was never accepted: the create, a setting, or the POST failed. */@@ -46,7 +48,38 @@ export type PromptStage =/** The log confirmed the prompt: its row came back over the socket. */| 'confirmed'/** The first agent message in the prompt's turn was folded. */- | 'first_output';+ | 'first_output'+ /** The turn's first agent text was folded. */+ | 'first_text'+ /** The frame after the first text was folded: what a person saw. */+ | 'first_text_paint';++/**+ * When a batch of stored frames reached this browser, and how long after the+ * server stored the newest of them. The lag compares the server's clock with+ * this one, so it carries their skew: read it as a distribution.+ */+export type FrameDelivery = {+ /**+ * How the batch came: pushed over the realtime socket, or read back by a+ * snapshot refetch after the socket missed it.+ */+ via: 'socket' | 'snapshot';+ /** `performance.now()` when the batch arrived, before it was folded. */+ receivedAt: number;+ /** Milliseconds from the server storing the batch's newest frame. */+ lagMs: number;+};++/** The delivery of a batch of stored rows, if it carries any. */+export function frameDelivery(+ via: FrameDelivery['via'],+ rows: { createdAt: string }[]+): FrameDelivery | undefined {+ const storedAt = Math.max(...rows.map((row) => Date.parse(row.createdAt)));+ if (!Number.isFinite(storedAt)) return undefined;+ return { via, receivedAt: performance.now(), lagMs: Date.now() - storedAt };+}/*** How long a prompt may wait for output before it is reported as stalled.@@ -64,6 +97,8 @@ export class PromptTrace {readonly #actionIds = new Set<string>();/** The prompt's turn, once the log confirmed it. */#turn: number | undefined;+ #output = false;+ #text = false;#ended = false;#stallTimer: ReturnType<typeof setTimeout> | undefined;@@ -124,13 +159,16 @@ export class PromptTrace {this.stage('accepted');}- /** Read fold events for the prompt's confirmation and its turn's first output. */- observe(events: FoldedStreamEvent[]): void {+ /**+ * Read fold events for the prompt's confirmation and its turn's first+ * output and text. `delivery` is how the frames they came from arrived.+ */+ observe(events: FoldedStreamEvent[], delivery?: FrameDelivery): void {if (this.#ended) return;try {for (const event of events) {for (const message of messagesOf(event)) {- this.#observeMessage(message);+ this.#observeMessage(message, delivery);if (this.#ended) return;}}@@ -158,7 +196,7 @@ export class PromptTrace {}}- #observeMessage(message: FoldedMessage): void {+ #observeMessage(message: FoldedMessage, delivery?: FrameDelivery): void {if (this.#turn === undefined &&message.author.kind === 'user' &&@@ -170,17 +208,46 @@ export class PromptTrace {this.stage('confirmed', { turn: message.turn });}if (this.#turn === undefined || message.turn !== this.#turn) return;- if (message.author.kind === 'agent') {+ if (message.author.kind === 'agent') this.#observeAgent(message, delivery);+ if (message.stop && !this.#text) {+ this.#set('agent.prompt.stop', message.stop.kind);+ this.end(this.#output ? 'no_text' : 'no_output');+ }+ }++ #observeAgent(message: FoldedMessage, delivery?: FrameDelivery): void {+ if (!this.#output) {+ this.#output = true;this.stage('first_output', {first_output_part: message.parts[0]?.kind ?? 'none',});- this.end('output');- return;}- if (message.stop) {- this.#set('agent.prompt.stop', message.stop.kind);- this.end('no_output');+ const text = message.parts.some(+ (part) => part.kind === 'text' && part.text.trim() !== ''+ );+ if (this.#text || !text) return;+ this.#text = true;+ this.stage(+ 'first_text',+ delivery && {+ first_text_via: delivery.via,+ first_text_delivery_ms: delivery.lagMs,+ first_text_fold_ms: Math.round(performance.now() - delivery.receivedAt),+ }+ );+ // A hidden tab never paints, and never runs animation frames either.+ if (documentHidden()) {+ this.#set('agent.prompt.hidden', true);+ this.end('text');+ return;}+ // Two frames: the first runs before the paint the text lands in.+ requestAnimationFrame(() =>+ requestAnimationFrame(() => {+ this.stage('first_text_paint');+ this.end('text');+ })+ );}#set(name: string, value: string | number | boolean): void {@@ -193,6 +260,14 @@ export class PromptTrace {}}+function documentHidden(): boolean {+ return (+ typeof document === 'undefined' ||+ typeof requestAnimationFrame === 'undefined' ||+ document.visibilityState === 'hidden'+ );+}+function messagesOf(event: FoldedStreamEvent): FoldedMessage[] {return match(event).with({ kind: 'new' }, { kind: 'update' }, (changed) => [changed.message])diff --git a/crates/agent/src/agent_loop.rs b/crates/agent/src/agent_loop.rsindex bb0c3e7335..62afff981a 100644--- a/crates/agent/src/agent_loop.rs+++ b/crates/agent/src/agent_loop.rs@@ -274,6 +274,7 @@ impl AgentLoop {}let adapter = DynToolSetAdapter::loaded(tool.name,+ tool.description,tool.schema,toolset.clone(),context.clone(),diff --git a/crates/agent/src/model/metering_http.rs b/crates/agent/src/model/metering_http.rsindex 186e331c4b..e45bd35724 100644--- a/crates/agent/src/model/metering_http.rs+++ b/crates/agent/src/model/metering_http.rs@@ -577,6 +577,9 @@ fn normalize(protocol: WireProtocol, usage: &Value) -> Option<TrustedTokenUsage>let cached = usage.get(input_details).map_or(Some(0), |v| optional_count(v, "cached_tokens"))?;+ let cache_written = usage+ .get(input_details)+ .map_or(Some(0), |v| optional_count(v, "cache_write_tokens"))?;let reasoning = usage.get(output_details).map_or(Some(0), |v| optional_count(v, "reasoning_tokens"))?;@@ -584,9 +587,10 @@ fn normalize(protocol: WireProtocol, usage: &Value) -> Option<TrustedTokenUsage>for details in [input_details, output_details] {if let Some(object) = usage.get(details).and_then(Value::as_object)&& object.iter().any(|(key, value)| {- key != "cached_tokens"- && key != "reasoning_tokens"- && value.as_u64() != Some(0)+ !matches!(+ key.as_str(),+ "cached_tokens" | "cache_write_tokens" | "reasoning_tokens"+ ) && value.as_u64() != Some(0)}){return None;@@ -596,7 +600,7 @@ fn normalize(protocol: WireProtocol, usage: &Value) -> Option<TrustedTokenUsage>count(usage, input)?,count(usage, output)?,cached,- 0,+ cache_written,reasoning,).ok()diff --git a/crates/agent/src/model/metering_http/test.rs b/crates/agent/src/model/metering_http/test.rsindex 52a905d384..268f1574f6 100644--- a/crates/agent/src/model/metering_http/test.rs+++ b/crates/agent/src/model/metering_http/test.rs@@ -281,6 +281,18 @@ fn provider_semantics_are_disjoint() {}}+/// gpt-6-astra reports prompt-cache writes on a cache miss, inside `input_tokens`.+#[test]+fn openai_cache_writes_are_a_billed_dimension() {+ assert_eq!(+ normalize(+ WireProtocol::Responses,+ &json!({"input_tokens":9015,"input_tokens_details":{"cache_write_tokens":9012,"cached_tokens":0},"output_tokens":5,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":9020}),+ ),+ Some(TrustedTokenUsage::from_disjoint(3, 5, 0, 9012, 0))+ );+}+#[test]fn absent_inconsistent_and_unsupported_counters_are_not_zero() {assert_eq!(diff --git a/crates/agent/src/model/router.rs b/crates/agent/src/model/router.rsindex d68561ecd0..5e14b31dcb 100644--- a/crates/agent/src/model/router.rs+++ b/crates/agent/src/model/router.rs@@ -691,6 +691,11 @@ wherewhile let Some(item) = rig_stream.next().await {liveness.observed();+ if let Ok(MultiTurnStreamItem::StreamAssistantItem(content)) = &item+ && let Some(kind) = chunk_kind(content)+ {+ telemetry.record_chunk(kind);+ }match item {Ok(MultiTurnStreamItem::StreamAssistantItem(StreamedAssistantContent::ReasoningDelta { reasoning, .. },@@ -785,6 +790,19 @@ whereBox::pin(stream)}+/// What a streamed item carries, for the model call's first-chunk timing.+/// `None` for the final response and items rig does not model.+fn chunk_kind<R>(content: &StreamedAssistantContent<R>) -> Option<&'static str> {+ match content {+ StreamedAssistantContent::Text(_) => Some("text"),+ StreamedAssistantContent::Reasoning(_)+ | StreamedAssistantContent::ReasoningDelta { .. } => Some("reasoning"),+ StreamedAssistantContent::ToolCall { .. }+ | StreamedAssistantContent::ToolCallDelta { .. } => Some("tool_call"),+ StreamedAssistantContent::Final(_) | StreamedAssistantContent::Unknown(_) => None,+ }+}+/// Test-only type erasure so [`ProviderAgent`] can hold an arbitrary/// [`Agent<M>`] (e.g. a scripted fake model) without adding a model type parameter./// Mirrors the production arms: it just drives [`drive_stream`].diff --git a/crates/agent/src/telemetry.rs b/crates/agent/src/telemetry.rsindex d79042fcc3..4c9fe9a502 100644--- a/crates/agent/src/telemetry.rs+++ b/crates/agent/src/telemetry.rs@@ -27,6 +27,7 @@mod test;use std::sync::{Arc, Mutex, OnceLock};+use std::time::Instant;use genai_telemetry::messages::{self, MediaSource};use genai_telemetry::{@@ -64,6 +65,9 @@ struct Inner {/// [`TracedModel`] on request, consumed by [`ChatSpanHook`] on response./// Holding the handle keeps the span open, so it is always taken out again.chat_span: Mutex<Option<tracing::Span>>,+ /// When the parked model call was requested, until its first chunk is+ /// recorded.+ chat_requested_at: Mutex<Option<Instant>>,}impl GenAiContext {@@ -80,6 +84,7 @@ impl GenAiContext {enabled,model: OnceLock::new(),chat_span: Mutex::new(None),+ chat_requested_at: Mutex::new(None),}))}@@ -158,11 +163,51 @@ impl GenAiContext {}*self.0.chat_span.lock().expect("chat span slot poisoned") = Some(span);+ *self+ .0+ .chat_requested_at+ .lock()+ .expect("chat request time poisoned") = Some(Instant::now());+ }++ /// The model call in flight streamed a chunk of `kind`. The first one per+ /// call records how long after the request it came.+ pub(crate) fn record_chunk(&self, kind: &'static str) {+ let Some(requested_at) = self+ .0+ .chat_requested_at+ .lock()+ .expect("chat request time poisoned")+ .take()+ else {+ return;+ };+ if let Some(span) = self+ .0+ .chat_span+ .lock()+ .expect("chat span slot poisoned")+ .as_ref()+ {+ span.set_i64(+ attr::MACRO_CHAT_TIME_TO_FIRST_CHUNK_MS,+ i64::try_from(requested_at.elapsed().as_millis()).unwrap_or(i64::MAX),+ );+ span.set_str(attr::MACRO_CHAT_FIRST_CHUNK_KIND, kind);+ }}/// Record the response side of the model call whose request was recorded/// last, then release the parked span so it can close.fn record_response(&self, content: &OneOrMany<AssistantContent>) {+ // A call whose output arrived whole streamed nothing earlier: the+ // response is its first chunk.+ self.record_chunk(match content.first() {+ AssistantContent::Text(_) => "text",+ AssistantContent::ToolCall(_) => "tool_call",+ AssistantContent::Reasoning(_) => "reasoning",+ AssistantContent::Image(_) => "image",+ });let Some(span) = self.0.chat_spandiff --git a/crates/agent/src/test/agent_loop/test_telemetry.rs b/crates/agent/src/test/agent_loop/test_telemetry.rsindex fe2ec68529..99447d2253 100644--- a/crates/agent/src/test/agent_loop/test_telemetry.rs+++ b/crates/agent/src/test/agent_loop/test_telemetry.rs@@ -639,3 +639,51 @@ async fn the_run_span_records_how_the_provider_stream_behaved() {"the silence at the end is recorded");}++/// Each model call's `chat` span records how soon its first chunk came and+/// what it was: the provider's latency, apart from the generation the call's+/// duration also includes.+#[tokio::test]+async fn each_model_call_records_its_first_chunk() {+ let (exporter, provider, _guard) = otel_test_pipeline();+ let model = MockCompletionModel::from_stream_turns([+ vec![+ MockStreamEvent::tool_call("call-1", "echo_tool", json!({ "value": "a" })),+ MockStreamEvent::final_response_with_default_usage(),+ ],+ vec![+ MockStreamEvent::text("done"),+ MockStreamEvent::final_response_with_default_usage(),+ ],+ ]);+ let toolset = util::single_tool_set::<EchoTool, ()>();+ let mut session = util::session(toolset, Arc::new(()), model).await;++ let result = util::drive(&mut session, "call echo").await;+ assert_eq!(result.content(), "done");+ drop(session);++ let spans = finished(&exporter, &provider);+ let chats = spans_with_operation(&spans, attr::operation::CHAT);+ assert_eq!(+ chats.len(),+ 2,+ "two model calls, got:\n{}",+ describe(&spans)+ );+ assert_eq!(+ string_attribute(chats[0], attr::MACRO_CHAT_FIRST_CHUNK_KIND).as_deref(),+ Some("tool_call")+ );+ assert_eq!(+ string_attribute(chats[1], attr::MACRO_CHAT_FIRST_CHUNK_KIND).as_deref(),+ Some("text")+ );+ for chat in &chats {+ assert!(+ int_attribute(chat, attr::MACRO_CHAT_TIME_TO_FIRST_CHUNK_MS).is_some_and(|ms| ms >= 0),+ "{}",+ describe(&spans)+ );+ }+}diff --git a/crates/agent/src/test/test_tool_adapter.rs b/crates/agent/src/test/test_tool_adapter.rsindex be6fab8859..f12310a11c 100644--- a/crates/agent/src/test/test_tool_adapter.rs+++ b/crates/agent/src/test/test_tool_adapter.rs@@ -63,3 +63,38 @@ fn non_object_schemas_are_unchanged() {normalize_request_schema(&mut schema);assert_eq!(schema, original);}++#[test]+fn the_schema_description_moves_to_the_tool() {+ let mut schema = serde_json::json!({+ "type": "object",+ "title": "ListLabels",+ "description": "List the user's Gmail labels.",+ "properties": {}+ });+ let description = take_description("ListLabels", String::new(), &mut schema);+ assert_eq!(description, "List the user's Gmail labels.");+ assert_eq!(+ schema,+ serde_json::json!({ "type": "object", "title": "ListLabels", "properties": {} })+ );+}++#[test]+fn a_declared_description_wins_over_the_schema() {+ let mut schema = serde_json::json!({ "type": "object", "description": "From the schema." });+ let description = take_description("Fetch", "Declared.".to_owned(), &mut schema);+ assert_eq!(description, "Declared.");+ assert_eq!(schema, serde_json::json!({ "type": "object" }));+}++/// OpenAI echoes an omitted description back as `null`, which rig cannot+/// parse, so the tool name stands in.+#[test]+fn a_tool_without_any_description_is_described_by_its_name() {+ let mut schema = serde_json::json!({ "type": "object", "properties": {} });+ assert_eq!(+ take_description("mcp__Linear__list_issues", " ".to_owned(), &mut schema),+ "mcp__Linear__list_issues"+ );+}diff --git a/crates/agent/src/tool_adapter.rs b/crates/agent/src/tool_adapter.rsindex e4133a5b75..66481264f8 100644--- a/crates/agent/src/tool_adapter.rs+++ b/crates/agent/src/tool_adapter.rs@@ -50,6 +50,29 @@ pub fn normalize_request_schema(schema: &mut serde_json::Value) {}}+/// The provider-facing description of a tool, lifted out of its schema.+///+/// Providers take the description on the tool definition, so the schema's root+/// `description` moves there rather than being sent twice. It is never empty:+/// rig omits an empty description, OpenAI echoes the tool back with+/// `"description": null`, and rig then fails to parse `response.completed`,+/// dropping the call's token usage from its span.+pub(crate) fn take_description(+ name: &str,+ description: String,+ schema: &mut serde_json::Value,+) -> String {+ let in_schema = schema+ .as_object_mut()+ .and_then(|map| map.remove("description"))+ .and_then(|value| value.as_str().map(str::to_owned));+ [Some(description), in_schema]+ .into_iter()+ .flatten()+ .find(|description| !description.trim().is_empty())+ .unwrap_or_else(|| name.to_owned())+}+type Deserializer<Context> = Arc<dyn Fn(&serde_json::Value,@@ -84,9 +107,10 @@ impl ToolsetToolAdapter {.tools.into_iter().map(|(name, tool_object)| {- let description = tool_object.description.clone();let mut input_schema = serde_json::Value::Object(tool_object.input_schema.clone());normalize_request_schema(&mut input_schema);+ let description =+ take_description(&name, tool_object.description.clone(), &mut input_schema);let deserializer: Deserializer<Context> = Arc::new(move |json: &serde_json::Value| -> Result<Box<dyn ToolSetCallable<Context> + Send + Sync>,@@ -175,17 +199,24 @@ impl DynToolSetAdapter {let schemas = toolset.request_schemas().unwrap_or_default();schemas.into_iter()- .map(|RequestSchema { name, schema }| {- let schema_json = serde_json::to_value(&schema)- .unwrap_or(serde_json::Value::Object(serde_json::Map::new()));- Self::build(- name,- schema_json,- toolset.clone(),- context.clone(),- request_context.clone(),- )- })+ .map(+ |RequestSchema {+ name,+ description,+ schema,+ }| {+ let schema_json = serde_json::to_value(&schema)+ .unwrap_or(serde_json::Value::Object(serde_json::Map::new()));+ Self::build(+ name,+ description,+ schema_json,+ toolset.clone(),+ context.clone(),+ request_context.clone(),+ )+ },+ ).collect()}@@ -197,6 +228,7 @@ impl DynToolSetAdapter {/// [`Self::from_toolset`].pub fn loaded<Context>(name: String,+ description: String,schema: schemars::Schema,toolset: Arc<dyn AiToolSet<Context> + Send + Sync>,context: Arc<Context>,@@ -207,11 +239,19 @@ impl DynToolSetAdapter {{let schema_json = serde_json::to_value(&schema).unwrap_or(serde_json::Value::Object(serde_json::Map::new()));- Self::build(name, schema_json, toolset, context, request_context)+ Self::build(+ name,+ description,+ schema_json,+ toolset,+ context,+ request_context,+ )}fn build<Context>(name: String,+ description: String,mut schema: serde_json::Value,toolset: Arc<dyn AiToolSet<Context> + Send + Sync>,context: Arc<Context>,@@ -221,10 +261,11 @@ impl DynToolSetAdapter {Context: Clone + Send + Sync + 'static,{normalize_request_schema(&mut schema);+ let description = take_description(&name, description, &mut schema);let tool_name = name.clone();DynamicTool::new(name,- String::new(),+ description,schema,move |_tool_ctx, args: serde_json::Value| {let toolset = toolset.clone();diff --git a/crates/agent_session/README.md b/crates/agent_session/README.mdindex fd6f80783d..8e939a3150 100644--- a/crates/agent_session/README.md+++ b/crates/agent_session/README.md@@ -76,6 +76,33 @@ prompt spans also split `agent.turn.lock_wait_ms`, `agent.turn.admission_wait_msand `agent.turn.first_text_ms`; their legacy `ttft_ms` can include reasoning ora tool call, but excludes usage and tool-result events.+### From the send click to the first painted text++The web app's `agent.prompt` span (service `web-app`) covers one prompt end to+end. Every harness request made inside it carries its `traceparent`, so the+harness's request, `redis.process`, `invoke_agent` and `chat_streaming` spans+join the same trace. Its `*_at_ms` attributes are milliseconds from the send:++| Stage | Attribute | Where |+| --- | --- | --- |+| New session created, loaded, configured | `agent.prompt.created_at_ms`, `loaded_at_ms`, `configured_at_ms` | browser |+| Control POST answered, including dispatch to the runtime | `agent.prompt.accepted_at_ms` | browser |+| `session/prompt` → first model chunk, per call | `macro.genai.chat.time_to_first_chunk_ms` on `chat_streaming` | harness |+| `session/prompt` → first text at the session actor | `macro.genai.turn.time_to_first_text_ms` on `invoke_agent` | harness |+| First agent output of any kind folded | `agent.prompt.first_output_at_ms` | browser |+| First-text frame stored → received (gateway fan-out) | `agent.prompt.first_text_delivery_ms`, with `agent.prompt.first_text_via` (`socket`, or `snapshot` when a refetch caught what the socket missed) | browser |+| Received → folded | `agent.prompt.first_text_fold_ms` | browser |+| First text folded | `agent.prompt.first_text_at_ms` | browser |+| First text painted | `agent.prompt.first_text_paint_at_ms` | browser |++`agent.prompt.outcome` says how the span ended: `text`, `no_text` (reasoning+or tool calls only), `no_output`, `failed`, `released`, or `stalled` (five+minutes). A hidden tab never paints, so it ends at the first text with+`agent.prompt.hidden`. The delivery stage compares the server's clock with the+browser's, so read it as a distribution. A turn that calls tools before+answering spends that time between the first model chunk and the first text:+`macro.genai.chat.first_chunk_kind` says what each call streamed first.+To investigate a slow first session in Datadog, correlate by `agent.session.id`,report sample counts andp50/p95 for initialization and first text by harness/model. Include the fractiondiff --git a/crates/ai_toolset/src/toolset/traits.rs b/crates/ai_toolset/src/toolset/traits.rsindex 345538a121..f13d3269a0 100644--- a/crates/ai_toolset/src/toolset/traits.rs+++ b/crates/ai_toolset/src/toolset/traits.rs@@ -105,6 +105,7 @@ where.values().map(|tool| RequestSchema {name: tool.name.clone(),+ description: tool.description.clone(),schema: tool.input_schema.clone().into(),}).collect::<Vec<_>>();diff --git a/crates/ai_toolset/src/toolset/types.rs b/crates/ai_toolset/src/toolset/types.rsindex bb0be177d7..14581b51c0 100644--- a/crates/ai_toolset/src/toolset/types.rs+++ b/crates/ai_toolset/src/toolset/types.rs@@ -61,6 +61,8 @@ pub type AsyncToolCollection<ToolSetContext> = ToolCollection<AsyncToolObject<Topub struct RequestSchema {/// The name of the tool.pub name: String,+ /// What the tool does, sent as the provider tool definition's description.+ pub description: String,/// The JSON schema for the tool's input parameters.pub schema: Schema,}diff --git a/crates/genai_telemetry/src/attr.rs b/crates/genai_telemetry/src/attr.rsindex f72afee441..9853f4c18d 100644--- a/crates/genai_telemetry/src/attr.rs+++ b/crates/genai_telemetry/src/attr.rs@@ -85,6 +85,13 @@ pub const MACRO_TIME_TO_FIRST_TEXT_MS: &str = "macro.genai.turn.time_to_first_tepub const MACRO_TIME_TO_FIRST_REASONING_MS: &str = "macro.genai.turn.time_to_first_reasoning_ms";/// Milliseconds from sending `session/prompt` to the first tool call.pub const MACRO_TIME_TO_FIRST_TOOL_CALL_MS: &str = "macro.genai.turn.time_to_first_tool_call_ms";+/// Macro-specific: milliseconds from a model call's request to the first chunk+/// it streamed back (text, reasoning or a tool call), on its `chat` span. The+/// call's duration includes generation; this is the provider's latency alone.+pub const MACRO_CHAT_TIME_TO_FIRST_CHUNK_MS: &str = "macro.genai.chat.time_to_first_chunk_ms";+/// Macro-specific: what a model call streamed first: `text`, `reasoning` or+/// `tool_call`.+pub const MACRO_CHAT_FIRST_CHUNK_KIND: &str = "macro.genai.chat.first_chunk_kind";/// Macro-specific: the coarse ACP tool kind (`execute`, `edit`, `read`, …).pub const MACRO_TOOL_KIND: &str = "macro.genai.tool.kind";diff --git a/crates/import/src/domain/service/test/admission.rs b/crates/import/src/domain/service/test/admission.rsindex e4e81a4d45..bb7fa1cf08 100644--- a/crates/import/src/domain/service/test/admission.rs+++ b/crates/import/src/domain/service/test/admission.rs@@ -521,6 +521,7 @@ impl<Context: Send> ToolSet<Context> for Tools {fn request_schemas(&self) -> Option<Vec<ai_toolset::RequestSchema>> {Some(vec![ai_toolset::RequestSchema {name: self.name.into(),+ description: String::new(),schema: schemars::schema_for!(serde_json::Value),}])}diff --git a/crates/import/src/outbound/mcp_slack_source/test.rs b/crates/import/src/outbound/mcp_slack_source/test.rsindex 36066b7ab0..62ca48d451 100644--- a/crates/import/src/outbound/mcp_slack_source/test.rs+++ b/crates/import/src/outbound/mcp_slack_source/test.rs@@ -45,6 +45,7 @@ impl ToolSet<()> for Tools {.iter().map(|(name, schema)| RequestSchema {name: name.clone(),+ description: String::new(),schema: serde_json::from_value(schema.clone()).unwrap(),}).collect(),diff --git a/crates/mcp_client/src/domain/service/toolset.rs b/crates/mcp_client/src/domain/service/toolset.rsindex d70647e9b5..81d9d310f9 100644--- a/crates/mcp_client/src/domain/service/toolset.rs+++ b/crates/mcp_client/src/domain/service/toolset.rs@@ -384,6 +384,12 @@ impl<Context: Send + Sync + 'static> ToolSet<Context> for McpToolSet {.iter().map(|(mangled, entry)| RequestSchema {name: mangled.as_str().to_string(),+ description: entry+ .tool+ .description+ .as_deref()+ .unwrap_or_default()+ .to_string(),schema: Schema::from((*entry.tool.input_schema).clone()),}).collect();diff --git a/crates/mcp_toolset/src/toolset.rs b/crates/mcp_toolset/src/toolset.rsindex 922b774db5..25369e89cc 100644--- a/crates/mcp_toolset/src/toolset.rs+++ b/crates/mcp_toolset/src/toolset.rs@@ -254,6 +254,12 @@ impl<Context: Send + Sync + 'static> ToolSet<Context> for RemoteMcpToolSet {.iter().map(|(mangled, entry)| RequestSchema {name: mangled.as_str().to_string(),+ description: entry+ .tool+ .description+ .as_deref()+ .unwrap_or_default()+ .to_string(),schema: Schema::from((*entry.tool.input_schema).clone()),}).collect();