@open-mercato/ai-assistant 0.6.1-develop.3291.1.6fad645fd0 → 0.6.1

package/src/modules/ai_assistant/data/entities.ts

@@ -264,6 +264,13 @@ export class AiAgentRuntimeOverride {
     | 'allowedOverrideModelsByProvider'
     | 'updatedByUserId'
     | 'deletedAt'
+    | 'loopDisabled'
+    | 'loopMaxSteps'
+    | 'loopMaxToolCalls'
+    | 'loopMaxWallClockMs'
+    | 'loopMaxTokens'
+    | 'loopStopWhenJson'
+    | 'loopActiveToolsJson'
 
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string
@@ -303,6 +310,236 @@ export class AiAgentRuntimeOverride {
 
   @Property({ name: 'deleted_at', type: Date, nullable: true })
   deletedAt?: Date | null
+
+  /**
+   * Kill switch — when `true`, runtime forces `stopWhen: stepCountIs(1)` and
+   * ignores all other loop config. Phase 3 of spec
+   * `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  @Property({ name: 'loop_disabled', type: 'boolean', nullable: true })
+  loopDisabled?: boolean | null
+
+  /**
+   * Override `loop.maxSteps`. Phase 3 of spec
+   * `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  @Property({ name: 'loop_max_steps', type: 'int', nullable: true })
+  loopMaxSteps?: number | null
+
+  /**
+   * Override `loop.budget.maxToolCalls`. Phase 3 of spec
+   * `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  @Property({ name: 'loop_max_tool_calls', type: 'int', nullable: true })
+  loopMaxToolCalls?: number | null
+
+  /**
+   * Override `loop.budget.maxWallClockMs`. Phase 3 of spec
+   * `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  @Property({ name: 'loop_max_wall_clock_ms', type: 'int', nullable: true })
+  loopMaxWallClockMs?: number | null
+
+  /**
+   * Override `loop.budget.maxTokens`. Phase 3 of spec
+   * `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  @Property({ name: 'loop_max_tokens', type: 'int', nullable: true })
+  loopMaxTokens?: number | null
+
+  /**
+   * Override `loop.stopWhen`. JSON-safe variants only (`stepCount`,
+   * `hasToolCall`); validator rejects `kind: 'custom'`. Phase 3 of spec
+   * `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  @Property({ name: 'loop_stop_when_json', type: 'jsonb', nullable: true })
+  loopStopWhenJson?: unknown | null
+
+  /**
+   * Override `loop.activeTools` (must be subset of `agent.allowedTools`).
+   * Phase 3 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  @Property({ name: 'loop_active_tools_json', type: 'jsonb', nullable: true })
+  loopActiveToolsJson?: unknown | null
+}
+
+/**
+ * Append-only event log for token usage per step (chat) or per turn (object).
+ *
+ * One row is created by `recordTokenUsage` (Phase 6.3) for every completed
+ * AI SDK step. Indexed for the three read patterns: daily rollup, per-agent
+ * report, and session drill-down.
+ *
+ * Retention: rows older than `AI_TOKEN_USAGE_EVENTS_RETENTION_DAYS` (default
+ * 90) are swept by the `ai-token-usage-prune` worker (Phase 6.4).
+ *
+ * Phase 6.0 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+ */
+@Entity({ tableName: 'ai_token_usage_events' })
+@Index({
+  name: 'ai_token_usage_events_tenant_created_idx',
+  properties: ['tenantId', 'createdAt'],
+})
+@Index({
+  name: 'ai_token_usage_events_tenant_agent_created_idx',
+  properties: ['tenantId', 'agentId', 'createdAt'],
+})
+@Index({
+  name: 'ai_token_usage_events_tenant_model_created_idx',
+  properties: ['tenantId', 'modelId', 'createdAt'],
+})
+@Index({
+  name: 'ai_token_usage_events_tenant_session_turn_step_idx',
+  properties: ['tenantId', 'sessionId', 'turnId', 'stepIndex'],
+})
+export class AiTokenUsageEvent {
+  [OptionalProps]?:
+    | 'createdAt'
+    | 'updatedAt'
+    | 'organizationId'
+    | 'cachedInputTokens'
+    | 'reasoningTokens'
+    | 'finishReason'
+    | 'loopAbortReason'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'organization_id', type: 'uuid', nullable: true })
+  organizationId?: string | null
+
+  @Property({ name: 'user_id', type: 'uuid' })
+  userId!: string
+
+  @Property({ name: 'agent_id', type: 'text' })
+  agentId!: string
+
+  @Property({ name: 'module_id', type: 'text' })
+  moduleId!: string
+
+  @Property({ name: 'session_id', type: 'uuid' })
+  sessionId!: string
+
+  @Property({ name: 'turn_id', type: 'uuid' })
+  turnId!: string
+
+  @Property({ name: 'step_index', type: 'int' })
+  stepIndex!: number
+
+  @Property({ name: 'provider_id', type: 'text' })
+  providerId!: string
+
+  @Property({ name: 'model_id', type: 'text' })
+  modelId!: string
+
+  @Property({ name: 'input_tokens', type: 'int' })
+  inputTokens!: number
+
+  @Property({ name: 'output_tokens', type: 'int' })
+  outputTokens!: number
+
+  @Property({ name: 'cached_input_tokens', type: 'int', nullable: true })
+  cachedInputTokens?: number | null
+
+  @Property({ name: 'reasoning_tokens', type: 'int', nullable: true })
+  reasoningTokens?: number | null
+
+  @Property({ name: 'finish_reason', type: 'text', nullable: true })
+  finishReason?: string | null
+
+  @Property({ name: 'loop_abort_reason', type: 'text', nullable: true })
+  loopAbortReason?: string | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}
+
+/**
+ * Materialized daily rollup of token usage per `(tenant, day, agent, model)`.
+ *
+ * Updated incrementally by UPSERT on every `recordTokenUsage` call so the
+ * rollup is always current even when the prune worker is behind. A daily
+ * reconciliation worker (Phase 6.4) recomputes `session_count` from the events
+ * table to correct any drift caused by event delivery delays or outages.
+ *
+ * `session_count` is maintained via a per-row LATERAL exists check at write
+ * time (first event in a `(tenant, day, agent, model, session)` window
+ * increments the counter). This counter may drift if events arrive out of
+ * order; the daily worker corrects it.
+ *
+ * Phase 6.1 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+ */
+@Entity({ tableName: 'ai_token_usage_daily' })
+@Index({
+  name: 'ai_token_usage_daily_tenant_day_agent_model_org_uq',
+  expression:
+    'create unique index "ai_token_usage_daily_tenant_day_agent_model_org_uq" on "ai_token_usage_daily" ("tenant_id", "day", "agent_id", "model_id", "organization_id") where "organization_id" is not null',
+})
+@Index({
+  name: 'ai_token_usage_daily_tenant_day_agent_model_null_org_uq',
+  expression:
+    'create unique index "ai_token_usage_daily_tenant_day_agent_model_null_org_uq" on "ai_token_usage_daily" ("tenant_id", "day", "agent_id", "model_id") where "organization_id" is null',
+})
+@Index({
+  name: 'ai_token_usage_daily_tenant_day_idx',
+  properties: ['tenantId', 'day'],
+})
+export class AiTokenUsageDaily {
+  [OptionalProps]?: 'createdAt' | 'updatedAt' | 'organizationId'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'organization_id', type: 'uuid', nullable: true })
+  organizationId?: string | null
+
+  @Property({ name: 'day', type: 'string', columnType: 'date' })
+  day!: string
+
+  @Property({ name: 'agent_id', type: 'text' })
+  agentId!: string
+
+  @Property({ name: 'model_id', type: 'text' })
+  modelId!: string
+
+  @Property({ name: 'provider_id', type: 'text' })
+  providerId!: string
+
+  @Property({ name: 'input_tokens', type: 'string', columnType: 'bigint' })
+  inputTokens!: string
+
+  @Property({ name: 'output_tokens', type: 'string', columnType: 'bigint' })
+  outputTokens!: string
+
+  @Property({ name: 'cached_input_tokens', type: 'string', columnType: 'bigint' })
+  cachedInputTokens!: string
+
+  @Property({ name: 'reasoning_tokens', type: 'string', columnType: 'bigint' })
+  reasoningTokens!: string
+
+  @Property({ name: 'step_count', type: 'string', columnType: 'bigint' })
+  stepCount!: string
+
+  @Property({ name: 'turn_count', type: 'string', columnType: 'bigint' })
+  turnCount!: string
+
+  @Property({ name: 'session_count', type: 'string', columnType: 'bigint' })
+  sessionCount!: string
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
 }
 
 /**

package/src/modules/ai_assistant/data/repositories/AiAgentRuntimeOverrideRepository.ts

@@ -2,6 +2,7 @@ import type { EntityManager, FilterQuery } from '@mikro-orm/postgresql'
 import { llmProviderRegistry } from '@open-mercato/shared/lib/ai/llm-provider-registry'
 import { canonicalProviderId } from '../../lib/model-allowlist'
 import { AiAgentRuntimeOverride } from '../entities'
+import type { AiAgentLoopStopCondition } from '../../lib/ai-agent-definition'
 
 export interface AiAgentRuntimeOverrideContext {
   tenantId: string
@@ -9,7 +10,24 @@ export interface AiAgentRuntimeOverrideContext {
   userId?: string | null
 }
 
-export interface AiAgentRuntimeOverrideInput {
+export interface AiAgentRuntimeOverrideLoopInput {
+  /** Kill switch — when true, runtime forces stepCountIs(1). */
+  loopDisabled?: boolean | null
+  /** Override loop.maxSteps. */
+  loopMaxSteps?: number | null
+  /** Override loop.budget.maxToolCalls. */
+  loopMaxToolCalls?: number | null
+  /** Override loop.budget.maxWallClockMs. */
+  loopMaxWallClockMs?: number | null
+  /** Override loop.budget.maxTokens. */
+  loopMaxTokens?: number | null
+  /** Override loop.stopWhen — JSON-safe variants only (stepCount, hasToolCall). */
+  loopStopWhenJson?: AiAgentLoopStopCondition[] | null
+  /** Override loop.activeTools — must be a subset of agent.allowedTools. */
+  loopActiveToolsJson?: string[] | null
+}
+
+export interface AiAgentRuntimeOverrideInput extends AiAgentRuntimeOverrideLoopInput {
   /** null means tenant-wide default (no agent pinning). */
   agentId?: string | null
   providerId?: string | null
@@ -17,6 +35,12 @@ export interface AiAgentRuntimeOverrideInput {
   baseURL?: string | null
   allowedOverrideProviders?: string[] | null
   allowedOverrideModelsByProvider?: Record<string, string[]>
+  /**
+   * Optional: the agent's declared allowedTools. When provided, loopActiveToolsJson
+   * is validated to be a subset. When omitted, allowlist validation is skipped
+   * (write-time defense only; the runtime re-validates at read time).
+   */
+  agentAllowedTools?: string[]
 }
 
 /**
@@ -90,6 +114,89 @@ export class AiAgentRuntimeOverrideRepository {
     return row ?? null
   }
 
+  /**
+   * Validates and normalizes the loop override fields from an input object.
+   * Throws `AiAgentRuntimeOverrideValidationError` with code
+   * `invalid_loop_override` for any validation failure.
+   *
+   * Validation rules (Phase 3 — R5 mitigation):
+   * - `loopStopWhenJson`: all items must have kind `stepCount` or `hasToolCall`.
+   *   Items with kind `custom` are rejected — they cannot be stored as JSON.
+   * - `loopActiveToolsJson`: when `agentAllowedTools` is provided, every entry
+   *   must be in that allowlist.
+   */
+  private validateLoopInput(input: AiAgentRuntimeOverrideInput): void {
+    if (input.loopStopWhenJson != null) {
+      if (!Array.isArray(input.loopStopWhenJson)) {
+        throw new AiAgentRuntimeOverrideValidationError(
+          'loopStopWhenJson must be an array of stop condition objects.',
+          'invalid_loop_override',
+        )
+      }
+      for (const item of input.loopStopWhenJson) {
+        if (!item || typeof item !== 'object' || !('kind' in item)) {
+          throw new AiAgentRuntimeOverrideValidationError(
+            'loopStopWhenJson items must have a "kind" field.',
+            'invalid_loop_override',
+          )
+        }
+        const kind = (item as AiAgentLoopStopCondition).kind
+        if (kind === 'custom') {
+          throw new AiAgentRuntimeOverrideValidationError(
+            'loopStopWhenJson does not support kind "custom" — only "stepCount" and "hasToolCall" are JSON-safe and storable.',
+            'invalid_loop_override',
+          )
+        }
+        if (kind !== 'stepCount' && kind !== 'hasToolCall') {
+          throw new AiAgentRuntimeOverrideValidationError(
+            `loopStopWhenJson contains unknown kind "${String(kind)}". Allowed: "stepCount", "hasToolCall".`,
+            'invalid_loop_override',
+          )
+        }
+        if (kind === 'stepCount' && typeof (item as { count?: unknown }).count !== 'number') {
+          throw new AiAgentRuntimeOverrideValidationError(
+            'loopStopWhenJson stepCount item must have a numeric "count" field.',
+            'invalid_loop_override',
+          )
+        }
+        if (kind === 'hasToolCall' && typeof (item as { toolName?: unknown }).toolName !== 'string') {
+          throw new AiAgentRuntimeOverrideValidationError(
+            'loopStopWhenJson hasToolCall item must have a string "toolName" field.',
+            'invalid_loop_override',
+          )
+        }
+      }
+    }
+
+    if (input.loopActiveToolsJson != null) {
+      if (!Array.isArray(input.loopActiveToolsJson)) {
+        throw new AiAgentRuntimeOverrideValidationError(
+          'loopActiveToolsJson must be an array of tool name strings.',
+          'invalid_loop_override',
+        )
+      }
+      for (const name of input.loopActiveToolsJson) {
+        if (typeof name !== 'string' || name.length === 0) {
+          throw new AiAgentRuntimeOverrideValidationError(
+            'loopActiveToolsJson entries must be non-empty strings.',
+            'invalid_loop_override',
+          )
+        }
+      }
+      if (input.agentAllowedTools && input.agentAllowedTools.length > 0) {
+        const outsideAllowlist = input.loopActiveToolsJson.filter(
+          (name) => !input.agentAllowedTools!.includes(name),
+        )
+        if (outsideAllowlist.length > 0) {
+          throw new AiAgentRuntimeOverrideValidationError(
+            `loopActiveToolsJson contains tools outside the agent's allowedTools: ${outsideAllowlist.join(', ')}.`,
+            'invalid_loop_override',
+          )
+        }
+      }
+    }
+  }
+
   /**
    * Inserts or updates the runtime override for the given context.
    *
@@ -97,6 +204,11 @@ export class AiAgentRuntimeOverrideRepository {
    * cannot save a typo (Phase 1.4 contract re-applied per spec §Data Models).
    * An unknown provider id throws a typed error.
    *
+   * Also validates loop override fields (R5 mitigation — Phase 3):
+   * - `loopStopWhenJson` items must use only JSON-safe kinds.
+   * - `loopActiveToolsJson` items must be a subset of `agentAllowedTools`
+   *   when that is provided.
+   *
    * The R6 base-URL allowlist check is intentionally NOT performed here —
    * that enforcement lives at the HTTP layer (PUT settings route). The
    * repository trusts that callers have already validated the value.
@@ -121,6 +233,8 @@ export class AiAgentRuntimeOverrideRepository {
       }
     }
 
+    this.validateLoopInput(input)
+
     const orgFilter = ctx.organizationId ?? null
     const agentIdFilter = input.agentId ?? null
     const hasProviderId = Object.prototype.hasOwnProperty.call(input, 'providerId')
@@ -149,6 +263,13 @@ export class AiAgentRuntimeOverrideRepository {
         }
         existing.updatedByUserId = ctx.userId ?? null
         existing.updatedAt = new Date()
+        if ('loopDisabled' in input) existing.loopDisabled = input.loopDisabled ?? null
+        if ('loopMaxSteps' in input) existing.loopMaxSteps = input.loopMaxSteps ?? null
+        if ('loopMaxToolCalls' in input) existing.loopMaxToolCalls = input.loopMaxToolCalls ?? null
+        if ('loopMaxWallClockMs' in input) existing.loopMaxWallClockMs = input.loopMaxWallClockMs ?? null
+        if ('loopMaxTokens' in input) existing.loopMaxTokens = input.loopMaxTokens ?? null
+        if ('loopStopWhenJson' in input) existing.loopStopWhenJson = input.loopStopWhenJson ?? null
+        if ('loopActiveToolsJson' in input) existing.loopActiveToolsJson = input.loopActiveToolsJson ?? null
         await tx.persist(existing).flush()
         return existing
       }
@@ -167,6 +288,13 @@ export class AiAgentRuntimeOverrideRepository {
           ? (input.allowedOverrideModelsByProvider ?? {})
           : {},
         updatedByUserId: ctx.userId ?? null,
+        loopDisabled: input.loopDisabled ?? null,
+        loopMaxSteps: input.loopMaxSteps ?? null,
+        loopMaxToolCalls: input.loopMaxToolCalls ?? null,
+        loopMaxWallClockMs: input.loopMaxWallClockMs ?? null,
+        loopMaxTokens: input.loopMaxTokens ?? null,
+        loopStopWhenJson: input.loopStopWhenJson ?? null,
+        loopActiveToolsJson: input.loopActiveToolsJson ?? null,
       } as unknown as AiAgentRuntimeOverride)
       await tx.persist(row).flush()
       return row
@@ -215,12 +343,16 @@ export class AiAgentRuntimeOverrideRepository {
 }
 
 /**
- * Thrown by `upsertDefault` when an unknown provider id is submitted.
+ * Thrown by `upsertDefault` when validation fails (unknown provider id,
+ * invalid loop override JSON).
  */
 export class AiAgentRuntimeOverrideValidationError extends Error {
-  constructor(message: string) {
+  readonly code: string
+
+  constructor(message: string, code = 'invalid_override') {
     super(message)
     this.name = 'AiAgentRuntimeOverrideValidationError'
+    this.code = code
   }
 }
 

package/src/modules/ai_assistant/data/repositories/AiTokenUsageRepository.ts

@@ -0,0 +1,213 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { AiTokenUsageEvent, AiTokenUsageDaily } from '../entities'
+
+export interface CreateTokenUsageEventInput {
+  tenantId: string
+  organizationId?: string | null
+  userId: string
+  agentId: string
+  moduleId: string
+  sessionId: string
+  turnId: string
+  stepIndex: number
+  providerId: string
+  modelId: string
+  inputTokens: number
+  outputTokens: number
+  cachedInputTokens?: number | null
+  reasoningTokens?: number | null
+  finishReason?: string | null
+  loopAbortReason?: string | null
+}
+
+export interface UpsertTokenUsageDailyInput {
+  tenantId: string
+  organizationId?: string | null
+  day: string
+  agentId: string
+  modelId: string
+  providerId: string
+  sessionId: string
+  inputTokens: number
+  outputTokens: number
+  cachedInputTokens: number
+  reasoningTokens: number
+}
+
+/**
+ * Repository for the Phase 6 token-usage event log and daily rollup tables.
+ *
+ * `upsertDaily` uses raw SQL to perform the CONFLICT-based incremental update
+ * because MikroORM does not expose `INSERT ... ON CONFLICT DO UPDATE` for
+ * arbitrary expressions. The LATERAL session-count check guards against
+ * double-counting a session within the same `(tenant, day, agent, model)` tuple.
+ *
+ * All writes are fail-open — callers MUST wrap invocations in try/catch and
+ * log at `warn` rather than rethrowing (R12: recorder must never break a turn).
+ *
+ * Phase 6.1 + 6.3 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+ */
+export class AiTokenUsageRepository {
+  constructor(private readonly em: EntityManager) {}
+
+  async createEvent(input: CreateTokenUsageEventInput): Promise<AiTokenUsageEvent> {
+    const event = this.em.create(AiTokenUsageEvent, {
+      tenantId: input.tenantId,
+      organizationId: input.organizationId ?? null,
+      userId: input.userId,
+      agentId: input.agentId,
+      moduleId: input.moduleId,
+      sessionId: input.sessionId,
+      turnId: input.turnId,
+      stepIndex: input.stepIndex,
+      providerId: input.providerId,
+      modelId: input.modelId,
+      inputTokens: input.inputTokens,
+      outputTokens: input.outputTokens,
+      cachedInputTokens: input.cachedInputTokens ?? null,
+      reasoningTokens: input.reasoningTokens ?? null,
+      finishReason: input.finishReason ?? null,
+      loopAbortReason: input.loopAbortReason ?? null,
+    })
+    this.em.persist(event)
+    await this.em.flush()
+    return event
+  }
+
+  /**
+   * Upserts the daily rollup row, incrementing counters atomically via
+   * `INSERT ... ON CONFLICT DO UPDATE`. The `session_count` column is
+   * incremented only when this is the first event observed for the
+   * `(tenant_id, session_id, day, agent_id, model_id)` tuple — a LATERAL
+   * NOT EXISTS check prevents double-counting.
+   *
+   * The query handles the two partial unique indexes (org IS NOT NULL vs
+   * IS NULL) by encoding `organization_id` in the EXCLUDED row and relying
+   * on the appropriate partial index the planner selects.
+   */
+  async upsertDaily(input: UpsertTokenUsageDailyInput): Promise<void> {
+    const connection = this.em.getConnection()
+    const now = new Date()
+    const orgValue = input.organizationId ?? null
+
+    // Determine if this is the first event for this session in the window
+    // (used to guard the session_count increment).
+    const sessionCheckSql = `
+      select exists (
+        select 1 from ai_token_usage_events
+        where tenant_id = ?
+          and session_id = ?::uuid
+          and agent_id = ?
+          and model_id = ?
+          and date_trunc('day', created_at) = ?::date
+          ${orgValue !== null ? 'and organization_id = ?' : 'and organization_id is null'}
+      ) as already_seen
+    `
+    const sessionCheckParams: unknown[] = [
+      input.tenantId,
+      input.sessionId,
+      input.agentId,
+      input.modelId,
+      input.day,
+    ]
+    if (orgValue !== null) sessionCheckParams.push(orgValue)
+
+    const sessionRows = await connection.execute(sessionCheckSql, sessionCheckParams, 'all')
+    const alreadySeen =
+      Array.isArray(sessionRows) &&
+      sessionRows.length > 0 &&
+      (sessionRows[0] as Record<string, unknown>).already_seen === true
+
+    const sessionDelta = alreadySeen ? 0 : 1
+
+    if (orgValue !== null) {
+      await connection.execute(
+        `
+        insert into ai_token_usage_daily (
+          id, tenant_id, organization_id, day, agent_id, model_id, provider_id,
+          input_tokens, output_tokens, cached_input_tokens, reasoning_tokens,
+          step_count, turn_count, session_count, created_at, updated_at
+        ) values (
+          gen_random_uuid(), ?, ?, ?::date, ?, ?, ?,
+          ?, ?, ?, ?,
+          1, 1, ?, ?, ?
+        )
+        on conflict (tenant_id, day, agent_id, model_id, organization_id)
+        where organization_id is not null
+        do update set
+          input_tokens         = ai_token_usage_daily.input_tokens + excluded.input_tokens,
+          output_tokens        = ai_token_usage_daily.output_tokens + excluded.output_tokens,
+          cached_input_tokens  = ai_token_usage_daily.cached_input_tokens + excluded.cached_input_tokens,
+          reasoning_tokens     = ai_token_usage_daily.reasoning_tokens + excluded.reasoning_tokens,
+          step_count           = ai_token_usage_daily.step_count + 1,
+          turn_count           = ai_token_usage_daily.turn_count + 1,
+          session_count        = ai_token_usage_daily.session_count + excluded.session_count,
+          updated_at           = excluded.updated_at
+        `,
+        [
+          input.tenantId, orgValue, input.day, input.agentId, input.modelId, input.providerId,
+          input.inputTokens, input.outputTokens, input.cachedInputTokens, input.reasoningTokens,
+          sessionDelta, now, now,
+        ],
+        'run',
+      )
+    } else {
+      await connection.execute(
+        `
+        insert into ai_token_usage_daily (
+          id, tenant_id, organization_id, day, agent_id, model_id, provider_id,
+          input_tokens, output_tokens, cached_input_tokens, reasoning_tokens,
+          step_count, turn_count, session_count, created_at, updated_at
+        ) values (
+          gen_random_uuid(), ?, null, ?::date, ?, ?, ?,
+          ?, ?, ?, ?,
+          1, 1, ?, ?, ?
+        )
+        on conflict (tenant_id, day, agent_id, model_id)
+        where organization_id is null
+        do update set
+          input_tokens         = ai_token_usage_daily.input_tokens + excluded.input_tokens,
+          output_tokens        = ai_token_usage_daily.output_tokens + excluded.output_tokens,
+          cached_input_tokens  = ai_token_usage_daily.cached_input_tokens + excluded.cached_input_tokens,
+          reasoning_tokens     = ai_token_usage_daily.reasoning_tokens + excluded.reasoning_tokens,
+          step_count           = ai_token_usage_daily.step_count + 1,
+          turn_count           = ai_token_usage_daily.turn_count + 1,
+          session_count        = ai_token_usage_daily.session_count + excluded.session_count,
+          updated_at           = excluded.updated_at
+        `,
+        [
+          input.tenantId, input.day, input.agentId, input.modelId, input.providerId,
+          input.inputTokens, input.outputTokens, input.cachedInputTokens, input.reasoningTokens,
+          sessionDelta, now, now,
+        ],
+        'run',
+      )
+    }
+  }
+
+  async listEventsForSession(
+    tenantId: string,
+    sessionId: string,
+    limit = 200,
+  ): Promise<AiTokenUsageEvent[]> {
+    return this.em.find(
+      AiTokenUsageEvent,
+      { tenantId, sessionId },
+      { orderBy: { createdAt: 'ASC', stepIndex: 'ASC' }, limit },
+    )
+  }
+
+  async listDailyRollup(
+    tenantId: string,
+    from: string,
+    to: string,
+    filters: { agentId?: string; modelId?: string } = {},
+  ): Promise<AiTokenUsageDaily[]> {
+    const where: Record<string, unknown> = { tenantId, day: { $gte: from, $lte: to } }
+    if (filters.agentId) where.agentId = filters.agentId
+    if (filters.modelId) where.modelId = filters.modelId
+    return this.em.find(AiTokenUsageDaily, where, {
+      orderBy: { day: 'ASC', agentId: 'ASC', modelId: 'ASC' },
+    })
+  }
+}