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.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index d68561ecd0..5e14b31dcb 100644
--- a/crates/agent/src/model/router.rs
+++ b/crates/agent/src/model/router.rs
@@ -691,6 +691,11 @@ where
while 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 @@ where
Box::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.rs
index 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_span
diff --git a/crates/agent/src/test/agent_loop/test_telemetry.rs b/crates/agent/src/test/agent_loop/test_telemetry.rs
index 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.rs
index 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.rs
index 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.md
index 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_ms
and `agent.turn.first_text_ms`; their legacy `ttft_ms` can include reasoning or
a 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 and
p50/p95 for initialization and first text by harness/model. Include the fraction
diff --git a/crates/ai_toolset/src/toolset/traits.rs b/crates/ai_toolset/src/toolset/traits.rs
index 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.rs
index 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<To
pub 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.rs
index 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_te
pub 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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();