feat(runtime): trace per-request provider usage and cache attribution

apps/desktop/src/main/__tests__/artifact-visibility.test.ts

@@ -25,6 +25,7 @@ describe('generated artifact visibility', () => {
       'synthesis_cache_block',
       'history_compact_block',
       'history_compact_source',
+      'provider_request_capture',
       'user_upload',
     ];
 

apps/desktop/src/main/session-stream.ts

@@ -11,6 +11,7 @@ import {
   buildLlmHistorySummarizer,
   buildMcpTools,
   buildProviderOptions,
+  createProviderRequestCaptureRecorder,
   getAIModel,
   loadHistoryCompactBlocksFromArtifacts,
   loadSynthesisCacheBlocksFromArtifacts,
@@ -38,6 +39,7 @@ import {
   createAttachmentByteReader,
   createTelemetryRepo,
   openRuntimeEventPersistence,
+  persistProviderRequestCaptureArtifact,
 } from '@maka/storage';
 import { WEB_SEARCH_TOOL_NAME } from './web-search/agent-tool.js';
 import {
@@ -252,6 +254,25 @@ export function createAiSdkBackendFactory(deps: AiSdkBackendFactoryDeps): Backen
         },
       }),
       recordRunTrace: ctx.recordRunTrace,
+      ...(ctx.recordProviderRequestCapture
+        ? {
+            recordProviderRequestCapture: createProviderRequestCaptureRecorder({
+              persistArtifact: async (capture) => {
+                const artifact = await persistProviderRequestCaptureArtifact(artifactStore, {
+                  sessionId: ctx.sessionId,
+                  turnId: capture.turnId,
+                  captureId: capture.captureId,
+                  step: capture.step,
+                  serializedRequest: capture.serializedRequest,
+                  now: Date.now(),
+                });
+                return { artifactId: artifact.id };
+              },
+              recordLedger: ctx.recordProviderRequestCapture,
+            }),
+            recordProviderRequestAttempt: ctx.recordProviderRequestAttempt,
+          }
+        : {}),
       recordHistoryCompactCheckpoint: ctx.recordHistoryCompactCheckpoint,
       loadTurnRuntimeEvents: ctx.loadTurnRuntimeEvents,
       recordActiveFullCompactBlock: ctx.recordActiveFullCompactBlock,

apps/desktop/src/renderer/artifact-visibility.ts

@@ -6,6 +6,7 @@ const USER_VISIBLE_ARTIFACT_SOURCES = {
   synthesis_cache_block: false,
   history_compact_block: false,
   history_compact_source: false,
+  provider_request_capture: false,
   user_upload: false,
   export: true,
   snapshot: true,

packages/cli/src/runtime-bootstrap.ts

@@ -19,6 +19,7 @@ import {
   buildRuntimeEventModelReplayPlan,
   buildChildAgentTools,
   createBuiltinSandboxManager,
+  createProviderRequestCaptureRecorder,
   createFilesystemWorkerLaunchSpecProvider,
   createLocalContinuationSafetyInspector,
   FilesystemWorkerClient,
@@ -63,6 +64,7 @@ import {
   createSettingsStore,
   createShellRunStore,
   type ForeignSessionStore,
+  persistProviderRequestCaptureArtifact,
 } from '@maka/storage';
 import type { ToolPermissionRule } from '@maka/core/permission';
 import { fetchProviderModels } from '@maka/runtime';
@@ -631,6 +633,25 @@ export async function createMakaCliRuntimeContext(
       turnTailPrompt: ({ cwd }) =>
         buildCliTurnTailPrompt({ cwd, sessionId: ctx.sessionId, automationManager, goalManager }),
       shellRunContextSummary: ctx.shellRunContextSummary,
+      ...(ctx.recordProviderRequestCapture
+        ? {
+            recordProviderRequestCapture: createProviderRequestCaptureRecorder({
+              persistArtifact: async (capture) => {
+                const artifact = await persistProviderRequestCaptureArtifact(artifactStore, {
+                  sessionId: ctx.sessionId,
+                  turnId: capture.turnId,
+                  captureId: capture.captureId,
+                  step: capture.step,
+                  serializedRequest: capture.serializedRequest,
+                  now: Date.now(),
+                });
+                return { artifactId: artifact.id };
+              },
+              recordLedger: ctx.recordProviderRequestCapture,
+            }),
+            recordProviderRequestAttempt: ctx.recordProviderRequestAttempt,
+          }
+        : {}),
       newId: randomUUID,
       now: Date.now,
       ...(input.maxSteps !== undefined ? { maxSteps: input.maxSteps } : {}),

packages/core/src/__tests__/agent-run-provider-request.test.ts

@@ -0,0 +1,19 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { decodeAgentRunEvent } from '../agent-run.js';
+
+test('AgentRun accepts provider request capture and attempt trace rows', () => {
+  for (const type of ['provider_request_captured', 'provider_request_attempt_recorded']) {
+    const decoded = decodeAgentRunEvent({
+      type,
+      id: `${type}-1`,
+      runId: 'run-1',
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      ts: 1,
+      data: { traceId: 'provider-trace-1' },
+    });
+    assert.equal(decoded.type, type);
+  }
+});

packages/core/src/__tests__/runtime-event.test.ts

@@ -1,4 +1,5 @@
 import { describe, test } from 'node:test';
+import assert from 'node:assert/strict';
 import { expect } from '../test-helpers.js';
 import {
   RUNTIME_EVENT_AUTHORS,
@@ -7,6 +8,7 @@ import {
   RUNTIME_EVENT_STATUSES,
   TERMINAL_RUNTIME_EVENT_STATUSES,
   createRuntimeEventId,
+  decodeRuntimeEvent,
   isRuntimeEventAuthor,
   isRuntimeEventRole,
   isRuntimeEventStatus,
@@ -312,6 +314,17 @@ describe('createRuntimeEventId', () => {
 });
 
 describe('RuntimeEvent shape compile-time contract', () => {
+  test('accepts a provider-request trace reference and rejects a non-string reference', () => {
+    const event = baseEvent({ refs: { providerRequestTraceId: 'provider-trace-1' } });
+    expect(decodeRuntimeEvent(event).refs?.providerRequestTraceId).toBe('provider-trace-1');
+    assert.throws(() =>
+      decodeRuntimeEvent({
+        ...event,
+        refs: { providerRequestTraceId: 123 },
+      }),
+    );
+  });
+
   test('a full user event satisfies the type', () => {
     const event: RuntimeEvent = {
       id: 'evt-u1',

packages/core/src/agent-run.ts

@@ -98,6 +98,8 @@ export const AGENT_RUN_EVENT_TYPES = [
   'sandbox_escalation_failed',
   'sandbox_denial_detected',
   'usage_recorded',
+  'provider_request_captured',
+  'provider_request_attempt_recorded',
   'history_compact_checkpoint_recorded',
   'active_full_compact_block_recorded',
   'semantic_compact_block_recorded',

packages/core/src/artifacts.ts

@@ -6,6 +6,7 @@ export type ArtifactSource =
   | 'synthesis_cache_block'
   | 'history_compact_block'
   | 'history_compact_source'
+  | 'provider_request_capture'
   | 'user_upload'
   | 'export'
   | 'snapshot'

packages/core/src/events.ts

@@ -518,6 +518,8 @@ export interface TokenUsageEvent extends BaseEvent {
   requestShapeChangeReason?: PrefixChangeReason;
   promptSegments?: PromptSegmentEstimate[];
   contextBudget?: ContextBudgetDiagnostic;
+  /** Links this aggregate to per-physical-request AgentRun trace rows. */
+  providerRequestTraceId?: string;
 }
 
 /**

packages/core/src/runtime-event.ts

@@ -298,6 +298,8 @@ export interface RuntimeEventRefs {
   traceEventId?: string;
   toolCallId?: string;
   providerEventId?: string;
+  /** Trace-group id linking aggregate usage to physical provider attempts. */
+  providerRequestTraceId?: string;
   artifactId?: string;
   /** Runtime-owned durable identity for one tool side-effect boundary. */
   operationId?: string;
@@ -453,6 +455,7 @@ const RUNTIME_REFS_SHAPE = defineObjectShape<RuntimeEventRefs>()(
     'traceEventId',
     'toolCallId',
     'providerEventId',
+    'providerRequestTraceId',
     'artifactId',
     'operationId',
     'stepId',
@@ -594,6 +597,7 @@ function isRuntimeEventRefs(value: unknown): value is RuntimeEventRefs {
       value.traceEventId,
       value.toolCallId,
       value.providerEventId,
+      value.providerRequestTraceId,
       value.artifactId,
       value.operationId,
       value.stepId,

packages/core/src/session.ts

@@ -329,6 +329,7 @@ export interface TokenUsageMessage {
   requestShapeChangeReason?: PrefixChangeReason;
   promptSegments?: PromptSegmentEstimate[];
   contextBudget?: ContextBudgetDiagnostic;
+  providerRequestTraceId?: string;
 }
 
 export interface TurnStateMessage {
@@ -424,6 +425,7 @@ const TOKEN_USAGE_MESSAGE_SHAPE = defineObjectShape<TokenUsageMessage>()(
     'requestShapeChangeReason',
     'promptSegments',
     'contextBudget',
+    'providerRequestTraceId',
   ],
 );
 const TURN_STATE_MESSAGE_SHAPE = defineObjectShape<TurnStateMessage>()(
@@ -540,7 +542,8 @@ function decodeStoredMessage(
       if (
         hasExactShape(message, TOKEN_USAGE_MESSAGE_SHAPE) &&
         hasMessageEnvelope(message, true) &&
-        isTokenUsageFields(message)
+        isTokenUsageFields(message) &&
+        isOptionalString(message.providerRequestTraceId)
       )
         return message as unknown as TokenUsageMessage;
       break;