@vellumai/assistant 0.10.0-dev.202606201736.e485b5f → 0.10.0-dev.202606201937.7a5da97

package/openapi.yaml

@@ -27120,6 +27120,10 @@ paths:
                           type: number
                         eventCount:
                           type: number
+                        turnCount:
+                          anyOf:
+                            - type: number
+                            - type: "null"
                       required:
                         - group
                         - groupId
@@ -27129,6 +27133,7 @@ paths:
                         - totalCacheReadTokens
                         - totalEstimatedCostUsd
                         - eventCount
+                        - turnCount
                       additionalProperties: false
                     description: Grouped usage entries
                 required:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.0-dev.202606201736.e485b5f",
+  "version": "0.10.0-dev.202606201937.7a5da97",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/llm-usage-store.test.ts

@@ -1306,6 +1306,41 @@ describe("getUsageGroupBreakdown", () => {
     expect(groups[0].totalOutputTokens).toBe(125);
     expect(groups[0].totalEstimatedCostUsd).toBeCloseTo(0.05);
     expect(groups[0].eventCount).toBe(2);
+    // No user messages were inserted, so the conversation has zero turns.
+    expect(groups[0].turnCount).toBe(0);
+  });
+
+  test("counts conversation turns from eligible user messages when grouping by conversation", () => {
+    const db = getDb();
+    const conversationId = "conv-turns-1";
+    const now = Date.now();
+    db.run(
+      `INSERT INTO conversations (id, title, created_at, updated_at) VALUES ('${conversationId}', 'Turn counting', ${now}, ${now})`,
+    );
+    // Two user turns; the second turn has two LLM calls, but the count comes
+    // from the user messages (2), not the number of LLM calls (3).
+    db.run(
+      `INSERT INTO messages (id, conversation_id, role, content, created_at) VALUES ('u1', '${conversationId}', 'user', 'first', 500)`,
+    );
+    db.run(
+      `INSERT INTO messages (id, conversation_id, role, content, created_at) VALUES ('u2', '${conversationId}', 'user', 'second', 2000)`,
+    );
+    // Tool-result user messages are not real turns and must be excluded.
+    db.run(
+      `INSERT INTO messages (id, conversation_id, role, content, created_at) VALUES ('tr1', '${conversationId}', 'user', '[{"type":"tool_result","tool_use_id":"x","content":""}]', 2100)`,
+    );
+    insertEventAt(1000, { conversationId, inputTokens: 100 });
+    insertEventAt(2500, { conversationId, inputTokens: 100 });
+    insertEventAt(2600, { conversationId, inputTokens: 100 });
+
+    const groups = getUsageGroupBreakdown(
+      { from: 0, to: 5000 },
+      "conversation",
+    );
+    expect(groups).toHaveLength(1);
+    expect(groups[0].groupId).toBe(conversationId);
+    expect(groups[0].eventCount).toBe(3);
+    expect(groups[0].turnCount).toBe(2);
   });
 
   test("returns groupId null for the Other bucket when grouping by conversation and events have no conversation id", () => {
@@ -1329,6 +1364,8 @@ describe("getUsageGroupBreakdown", () => {
     expect(groups[0].groupId).toBeNull();
     expect(groups[0].totalInputTokens).toBe(300);
     expect(groups[0].eventCount).toBe(2);
+    // The Other bucket has no parent conversation, so turns are undefined.
+    expect(groups[0].turnCount).toBeNull();
   });
 
   test("returns groupId null for every row when grouping by a non-conversation dimension", () => {
@@ -1348,6 +1385,8 @@ describe("getUsageGroupBreakdown", () => {
     expect(groups.length).toBeGreaterThan(0);
     for (const row of groups) {
       expect(row.groupId).toBeNull();
+      // Turns are only computed for the conversation grouping.
+      expect(row.turnCount).toBeNull();
     }
   });
 });

package/src/memory/llm-usage-store.ts

@@ -363,6 +363,14 @@ export interface UsageGroupBreakdown {
   totalCacheReadTokens: number;
   totalEstimatedCostUsd: number;
   eventCount: number;
+  /**
+   * Number of turns in the conversation — the count of eligible user messages
+   * (tool-result turns excluded). Only populated when `groupBy ===
+   * "conversation"` (and `null` for that mode's "Other" bucket, which has no
+   * parent conversation). `null` for every other grouping, where a turn count
+   * has no well-defined meaning.
+   */
+  turnCount: number | null;
 }
 
 // -- raw row shapes returned by SQLite aggregation queries --
@@ -388,6 +396,8 @@ interface GroupRow {
   total_cache_read_tokens: number;
   total_estimated_cost_usd: number | null;
   event_count: number;
+  /** Only selected by the conversation grouping query; absent otherwise. */
+  turn_count?: number | null;
 }
 
 type UsageQueryParam = ScheduleAttributionSqlParam;
@@ -645,6 +655,9 @@ function mapGroupRow(
     totalCacheReadTokens: row.total_cache_read_tokens,
     totalEstimatedCostUsd: row.total_estimated_cost_usd ?? 0,
     eventCount: row.event_count,
+    // Turns are only meaningful per conversation; other dimensions select no
+    // turn_count column, so this collapses to null.
+    turnCount: groupBy === "conversation" ? (row.turn_count ?? null) : null,
   };
 }
 
@@ -678,7 +691,24 @@ export function getUsageGroupBreakdown(
         COALESCE(SUM(e.cache_creation_input_tokens), 0)  AS total_cache_creation_tokens,
         COALESCE(SUM(e.cache_read_input_tokens), 0)      AS total_cache_read_tokens,
         COALESCE(SUM(e.estimated_cost_usd), 0)           AS total_estimated_cost_usd,
-        COALESCE(SUM(COALESCE(e.llm_call_count, 1)), 0)  AS event_count
+        COALESCE(SUM(COALESCE(e.llm_call_count, 1)), 0)  AS event_count,
+        -- Number of turns in the conversation: the count of eligible user
+        -- messages (tool-result turns excluded, mirroring the turnIndex
+        -- definition). Evaluated once per conversation group via the
+        -- idx_messages_conversation_id index rather than once per usage event,
+        -- so it stays cheap as call volume grows. NULL for the "Other" (no
+        -- conversation) bucket. Note: derived from surviving messages, so a
+        -- turn removed via Undo (deleteLastExchange) stops being counted even
+        -- though its billed usage still shows up in Cost/Tokens.
+        CASE WHEN e.conversation_id IS NULL THEN NULL
+             ELSE (
+               SELECT COUNT(*) FROM messages AS m2
+               WHERE m2.conversation_id = e.conversation_id
+                 AND m2.role = 'user'
+                 AND m2.content NOT LIKE '%"type":"tool\\_result"%' ESCAPE '\\'
+                 AND m2.content NOT LIKE '%"type":"web\\_search\\_tool\\_result"%' ESCAPE '\\'
+             )
+        END                                              AS turn_count
       FROM llm_usage_events e
       LEFT JOIN conversations c ON e.conversation_id = c.id
       WHERE ${where.sql}

package/src/runtime/routes/usage-routes.ts

@@ -65,6 +65,9 @@ const usageGroupBreakdownSchema = z.object({
   totalCacheReadTokens: z.number(),
   totalEstimatedCostUsd: z.number(),
   eventCount: z.number(),
+  // Distinct conversation turns; populated only for the conversation grouping,
+  // null otherwise (and for the conversation "Other" bucket).
+  turnCount: z.number().nullable(),
 });
 
 const usageSeriesGroupValueSchema = z.object({