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

package/src/modules/ai_assistant/api/ai/chat/route.ts

@@ -8,7 +8,11 @@ import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacS
 import { llmProviderRegistry } from '@open-mercato/shared/lib/ai/llm-provider-registry'
 import { loadAgentRegistry } from '../../../lib/agent-registry'
 import { checkAgentPolicy, type AgentPolicyDenyCode } from '../../../lib/agent-policy'
-import { runAiAgentText } from '../../../lib/agent-runtime'
+import {
+  runAiAgentText,
+  resolveLoopBudgetPreset,
+  type AiAgentLoopBudgetPreset,
+} from '../../../lib/agent-runtime'
 import { AgentPolicyError } from '../../../lib/agent-tools'
 import { readBaseurlAllowlist, isBaseurlAllowlisted } from '../../../lib/baseurl-allowlist'
 import {
@@ -52,10 +56,13 @@ const chatRequestSchema = z.object({
   debug: z.boolean().optional(),
   pageContext: pageContextSchema.optional(),
   /**
-   * Optional stable conversation id forwarded from `<AiChat>`. Bridged into
-   * the Step 5.6 `prepareMutation` idempotency hash so repeated turns within
-   * the same chat collapse onto the same pending action. Additive; omitted
-   * bodies continue to work as before.
+   * Stable per-conversation id (Phase 6.2). Wins over `conversationId` when
+   * both are provided. The server echoes the resolved id on the SSE
+   * `loop-finish` event so clients can persist it for the next turn.
+   */
+  sessionId: z.string().uuid().optional(),
+  /**
+   * @deprecated Use `sessionId` instead.
    */
   conversationId: z.string().min(1).max(128).optional(),
 })
@@ -69,7 +76,7 @@ const agentQuerySchema = z.object({
   /**
    * Per-request provider override. Must match a registered + configured
    * provider id. Validated against `llmProviderRegistry` at dispatch time.
-   * Rejected when the agent has `allowRuntimeModelOverride: false`.
+   * Rejected when the agent has `allowRuntimeOverride: false`.
    *
    * Phase 4a of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
    */
@@ -89,6 +96,18 @@ const agentQuerySchema = z.object({
    * Phase 4a of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
    */
   baseUrl: z.string().optional(),
+  /**
+   * Named loop-budget preset. Maps to a fixed `loop.budget` triple:
+   *   tight   → maxSteps: 3,  maxWallClockMs: 10_000,  maxTokens:  50_000
+   *   default → no override (agent default applies)
+   *   loose   → maxSteps: 20, maxWallClockMs: 120_000, maxTokens: 500_000
+   *
+   * Rejected when the agent has `allowRuntimeOverride: false` or
+   * `loop.allowRuntimeOverride: false`.
+   *
+   * Phase 4 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  loopBudget: z.enum(['tight', 'default', 'loose']).optional(),
 })
 
 export const openApi: OpenApiRouteDoc = {
@@ -107,7 +126,7 @@ export const openApi: OpenApiRouteDoc = {
         'override the resolved provider/model/base-URL for this turn (Phase 4a). ' +
         'Provider must be registered and configured; baseUrl must match ' +
         '`AI_RUNTIME_BASEURL_ALLOWLIST` when set. Both are suppressed when the ' +
-        'agent declares `allowRuntimeModelOverride: false`.',
+        'agent declares `allowRuntimeOverride: false`.',
       query: agentQuerySchema,
       requestBody: {
         contentType: 'application/json',
@@ -122,7 +141,7 @@ export const openApi: OpenApiRouteDoc = {
           status: 400,
           description:
             'Invalid query param, malformed payload, or message count above the cap. ' +
-            'Typed codes: `runtime_override_disabled` (agent has allowRuntimeModelOverride:false), ' +
+            'Typed codes: `runtime_override_disabled` (agent has allowRuntimeOverride:false), ' +
             '`provider_unknown` (provider id not registered), ' +
             '`provider_not_configured` (provider registered but no API key in env), ' +
             '`baseurl_not_allowlisted` (baseUrl not in AI_RUNTIME_BASEURL_ALLOWLIST).',
@@ -182,6 +201,7 @@ export async function POST(req: NextRequest): Promise<Response> {
     provider: requestUrl.searchParams.get('provider') ?? undefined,
     model: requestUrl.searchParams.get('model') ?? undefined,
     baseUrl: requestUrl.searchParams.get('baseUrl') ?? undefined,
+    loopBudget: requestUrl.searchParams.get('loopBudget') ?? undefined,
   })
   if (!queryResult.success) {
     return jsonError(400, 'Invalid or missing "agent" query parameter.', 'validation_error', {
@@ -192,6 +212,7 @@ export async function POST(req: NextRequest): Promise<Response> {
   const rawProvider = queryResult.data.provider
   const rawModel = queryResult.data.model
   const rawBaseUrl = queryResult.data.baseUrl
+  const rawLoopBudget = queryResult.data.loopBudget as AiAgentLoopBudgetPreset | undefined
 
   let parsedBody: unknown
   try {
@@ -241,16 +262,23 @@ export async function POST(req: NextRequest): Promise<Response> {
     const hasRuntimeOverride =
       (rawProvider && rawProvider.trim().length > 0) ||
       (rawModel && rawModel.trim().length > 0) ||
-      (rawBaseUrl && rawBaseUrl.trim().length > 0)
+      (rawBaseUrl && rawBaseUrl.trim().length > 0) ||
+      (rawLoopBudget !== undefined && rawLoopBudget !== 'default')
 
-    if (hasRuntimeOverride) {
-      if (agentDef.allowRuntimeModelOverride === false) {
-        return jsonError(
-          400,
-          `Agent "${agentId}" has runtime model override disabled (allowRuntimeModelOverride: false).`,
-          'runtime_override_disabled',
-        )
-      }
+    // `allowRuntimeOverride` is the canonical flag (renamed from
+    // `allowRuntimeModelOverride` in Phase 4 of this spec). Both are checked
+    // here to cover agents declared before the rename lands; the deprecated
+    // alias has lower priority.
+    const runtimeOverrideAllowed =
+      agentDef.allowRuntimeOverride !== false &&
+      agentDef.allowRuntimeModelOverride !== false
+
+    if (hasRuntimeOverride && !runtimeOverrideAllowed) {
+      return jsonError(
+        400,
+        `Agent "${agentId}" has runtime override disabled (allowRuntimeOverride: false).`,
+        'runtime_override_disabled',
+      )
     }
 
     let tenantAllowlistSnapshot: TenantAllowlistSnapshot | null = null
@@ -374,7 +402,7 @@ export async function POST(req: NextRequest): Promise<Response> {
         )
       }
     }
-    // --- end Phase 4a validation ---
+    // --- end Phase 4a + Phase 4 validation ---
 
     const requestOverride =
       hasRuntimeOverride
@@ -385,12 +413,19 @@ export async function POST(req: NextRequest): Promise<Response> {
           }
         : undefined
 
+    // Resolve the loopBudget preset to a loop config override (Phase 4).
+    const loopFromPreset =
+      rawLoopBudget !== undefined && rawLoopBudget !== 'default'
+        ? resolveLoopBudgetPreset(rawLoopBudget)
+        : undefined
+
     return await runAiAgentText({
       agentId,
       messages: bodyResult.data.messages as unknown as UIMessage[],
       attachmentIds: bodyResult.data.attachmentIds,
       pageContext: bodyResult.data.pageContext,
       debug: bodyResult.data.debug,
+      sessionId: bodyResult.data.sessionId ?? null,
       conversationId: bodyResult.data.conversationId ?? null,
       authContext: {
         tenantId: auth.tenantId ?? null,
@@ -401,6 +436,8 @@ export async function POST(req: NextRequest): Promise<Response> {
       },
       container,
       requestOverride,
+      loop: loopFromPreset,
+      emitLoopTrace: true,
     })
   } catch (error) {
     if (error instanceof AgentPolicyError) {

package/src/modules/ai_assistant/api/settings/route.ts

@@ -16,7 +16,7 @@ import { AiAgentRuntimeOverrideRepository, AiAgentRuntimeOverrideValidationError
 import { AiTenantModelAllowlistRepository } from '../../data/repositories/AiTenantModelAllowlistRepository'
 import { isBaseurlAllowlisted, readBaseurlAllowlist } from '../../lib/baseurl-allowlist'
 import { loadAgentRegistry, listAgents } from '../../lib/agent-registry'
-import { createModelFactory } from '../../lib/model-factory'
+import { createModelFactory, resolveAllowRuntimeOverride } from '../../lib/model-factory'
 import {
   agentOverrideModelAllowlistEnvVarName,
   agentOverrideProviderAllowlistEnvVarName,
@@ -181,6 +181,7 @@ export async function GET(req: NextRequest) {
     let agentResolutions: Array<{
       agentId: string
       moduleId: string
+      allowRuntimeOverride: boolean
       allowRuntimeModelOverride: boolean
       codeDefaultProviderId: string | null
       codeDefaultModelId: string | null
@@ -273,7 +274,7 @@ export async function GET(req: NextRequest) {
             agentDefaultModel: agent.defaultModel,
             agentDefaultProvider: agent.defaultProvider,
             agentDefaultBaseUrl: agent.defaultBaseUrl,
-            allowRuntimeModelOverride: agent.allowRuntimeModelOverride,
+            allowRuntimeOverride: resolveAllowRuntimeOverride(agent),
             tenantOverride: agentTenantOverride,
             tenantAllowlist: tenantAllowlistSnapshot,
           })
@@ -311,7 +312,8 @@ export async function GET(req: NextRequest) {
           return {
             agentId: agent.id,
             moduleId: agent.moduleId,
-            allowRuntimeModelOverride: agent.allowRuntimeModelOverride !== false,
+            allowRuntimeOverride: resolveAllowRuntimeOverride(agent),
+            allowRuntimeModelOverride: resolveAllowRuntimeOverride(agent),
             codeDefaultProviderId: agent.defaultProvider ?? null,
             codeDefaultModelId: agent.defaultModel ?? null,
             override: agentOverrideRow

package/src/modules/ai_assistant/api/usage/daily/__tests__/route.test.ts

@@ -0,0 +1,159 @@
+const authMock = jest.fn()
+const loadAclMock = jest.fn()
+const createRequestContainerMock = jest.fn()
+const listDailyRollupMock = jest.fn()
+
+jest.mock('@open-mercato/shared/lib/auth/server', () => ({
+  getAuthFromRequest: (...args: unknown[]) => authMock(...args),
+}))
+
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: (...args: unknown[]) => createRequestContainerMock(...args),
+}))
+
+jest.mock('../../../../data/repositories/AiTokenUsageRepository', () => ({
+  AiTokenUsageRepository: jest.fn().mockImplementation(() => ({
+    listDailyRollup: listDailyRollupMock,
+  })),
+}))
+
+import { GET } from '../route'
+
+function buildRequest(params: Record<string, string> = {}) {
+  const url = new URL('http://localhost/api/ai_assistant/usage/daily')
+  for (const [k, v] of Object.entries(params)) {
+    url.searchParams.set(k, v)
+  }
+  return new Request(url.toString(), { method: 'GET' })
+}
+
+function makeRow(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'row-1',
+    tenantId: 'tenant-1',
+    organizationId: null,
+    day: '2026-05-01',
+    agentId: 'catalog.assistant',
+    modelId: 'claude-haiku-4-5',
+    providerId: 'anthropic',
+    inputTokens: '1000',
+    outputTokens: '500',
+    cachedInputTokens: '0',
+    reasoningTokens: '0',
+    stepCount: '5',
+    turnCount: '3',
+    sessionCount: '2',
+    createdAt: new Date('2026-05-01T12:00:00Z'),
+    updatedAt: new Date('2026-05-01T12:00:00Z'),
+    ...overrides,
+  }
+}
+
+describe('GET /api/ai_assistant/usage/daily', () => {
+  let consoleErrorSpy: jest.SpyInstance
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    authMock.mockResolvedValue({ sub: 'user-1', tenantId: 'tenant-1', orgId: null })
+    loadAclMock.mockResolvedValue({ features: ['ai_assistant.settings.manage'], isSuperAdmin: false })
+    createRequestContainerMock.mockResolvedValue({
+      resolve: (name: string) => {
+        if (name === 'rbacService') return { loadAcl: loadAclMock, hasAllFeatures: (req: string[], have: string[]) => req.every((r) => have.includes(r)) }
+        if (name === 'em') return {}
+        throw new Error(`Unknown token: ${name}`)
+      },
+    })
+    listDailyRollupMock.mockResolvedValue([])
+  })
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore()
+  })
+
+  it('returns 401 when unauthenticated', async () => {
+    authMock.mockResolvedValue(null)
+    const res = await GET(buildRequest({ from: '2026-05-01', to: '2026-05-31' }) as Parameters<typeof GET>[0])
+    expect(res.status).toBe(401)
+  })
+
+  it('returns 403 when the caller lacks ai_assistant.settings.manage', async () => {
+    loadAclMock.mockResolvedValue({ features: ['ai_assistant.view'], isSuperAdmin: false })
+    const res = await GET(buildRequest({ from: '2026-05-01', to: '2026-05-31' }) as Parameters<typeof GET>[0])
+    expect(res.status).toBe(403)
+  })
+
+  it('returns 400 when from is missing', async () => {
+    const res = await GET(buildRequest({ to: '2026-05-31' }) as Parameters<typeof GET>[0])
+    expect(res.status).toBe(400)
+    const body = await res.json()
+    expect(body.code).toBe('validation_error')
+  })
+
+  it('returns 400 when from has an invalid date format', async () => {
+    const res = await GET(buildRequest({ from: 'not-a-date', to: '2026-05-31' }) as Parameters<typeof GET>[0])
+    expect(res.status).toBe(400)
+  })
+
+  it('returns 200 with empty rows when no data', async () => {
+    const res = await GET(buildRequest({ from: '2026-05-01', to: '2026-05-31' }) as Parameters<typeof GET>[0])
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.rows).toEqual([])
+    expect(body.total).toBe(0)
+  })
+
+  it('returns 200 with serialized rows', async () => {
+    listDailyRollupMock.mockResolvedValue([makeRow()])
+    const res = await GET(buildRequest({ from: '2026-05-01', to: '2026-05-31' }) as Parameters<typeof GET>[0])
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.rows).toHaveLength(1)
+    expect(body.rows[0].agentId).toBe('catalog.assistant')
+    expect(body.total).toBe(1)
+  })
+
+  it('serializes bigint counters and string timestamps returned by the database driver', async () => {
+    listDailyRollupMock.mockResolvedValue([
+      makeRow({
+        inputTokens: 1000n,
+        outputTokens: 500n,
+        cachedInputTokens: 10n,
+        reasoningTokens: 20n,
+        stepCount: 5n,
+        turnCount: 3n,
+        sessionCount: 2n,
+        createdAt: '2026-05-01T12:00:00.000Z',
+        updatedAt: '2026-05-01T12:30:00.000Z',
+      }),
+    ])
+
+    const res = await GET(buildRequest({ from: '2026-05-01', to: '2026-05-31' }) as Parameters<typeof GET>[0])
+
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.rows[0]).toMatchObject({
+      inputTokens: '1000',
+      outputTokens: '500',
+      cachedInputTokens: '10',
+      reasoningTokens: '20',
+      stepCount: '5',
+      turnCount: '3',
+      sessionCount: '2',
+      createdAt: '2026-05-01T12:00:00.000Z',
+      updatedAt: '2026-05-01T12:30:00.000Z',
+    })
+  })
+
+  it('passes agentId filter to the repository', async () => {
+    const res = await GET(buildRequest({ from: '2026-05-01', to: '2026-05-31', agentId: 'catalog.assistant' }) as Parameters<typeof GET>[0])
+    expect(res.status).toBe(200)
+    expect(listDailyRollupMock).toHaveBeenCalledWith('tenant-1', '2026-05-01', '2026-05-31', { agentId: 'catalog.assistant', modelId: undefined })
+  })
+
+  it('allows superadmin to bypass feature check', async () => {
+    loadAclMock.mockResolvedValue({ features: [], isSuperAdmin: true })
+    const res = await GET(buildRequest({ from: '2026-05-01', to: '2026-05-31' }) as Parameters<typeof GET>[0])
+    expect(res.status).toBe(200)
+  })
+})

package/src/modules/ai_assistant/api/usage/daily/route.ts

@@ -0,0 +1,126 @@
+import { NextResponse, type NextRequest } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
+import { AiTokenUsageRepository } from '../../../data/repositories/AiTokenUsageRepository'
+import { hasRequiredFeatures } from '../../../lib/auth'
+import { toDateString, toIntegerString, toIsoString } from '../../../lib/usage-serialization'
+
+const REQUIRED_FEATURE = 'ai_assistant.settings.manage'
+
+const querySchema = z.object({
+  from: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'from must be a date in YYYY-MM-DD format'),
+  to: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'to must be a date in YYYY-MM-DD format'),
+  agentId: z.string().min(1).max(256).optional(),
+  modelId: z.string().min(1).max(256).optional(),
+})
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'AI Assistant',
+  summary: 'Token usage daily rollup',
+  methods: {
+    GET: {
+      operationId: 'aiAssistantUsageDaily',
+      summary: 'Fetch daily token-usage rollup rows for a date window.',
+      description:
+        'Returns aggregated token-usage data from `ai_token_usage_daily` for the given ' +
+        'date window. Tenant-scoped. Optionally filtered by `agentId` and/or `modelId`. ' +
+        'Requires `ai_assistant.settings.manage`.',
+      query: querySchema,
+      responses: [
+        {
+          status: 200,
+          description: 'Array of daily rollup rows.',
+          mediaType: 'application/json',
+        },
+      ],
+      errors: [
+        { status: 400, description: 'Invalid query parameters.' },
+        { status: 401, description: 'Unauthenticated caller.' },
+        { status: 403, description: 'Caller lacks `ai_assistant.settings.manage`.' },
+        { status: 500, description: 'Internal failure.' },
+      ],
+    },
+  },
+}
+
+export const metadata = {
+  path: '/ai_assistant/usage/daily',
+  GET: { requireAuth: true, requireFeatures: [REQUIRED_FEATURE] },
+}
+
+function jsonError(status: number, message: string, code: string, extra?: Record<string, unknown>): NextResponse {
+  return NextResponse.json({ error: message, code, ...(extra ?? {}) }, { status })
+}
+
+export async function GET(req: NextRequest): Promise<Response> {
+  const auth = await getAuthFromRequest(req)
+  if (!auth) {
+    return jsonError(401, 'Unauthorized', 'unauthenticated')
+  }
+
+  const { searchParams } = new URL(req.url)
+  const rawQuery = {
+    from: searchParams.get('from') ?? undefined,
+    to: searchParams.get('to') ?? undefined,
+    agentId: searchParams.get('agentId') ?? undefined,
+    modelId: searchParams.get('modelId') ?? undefined,
+  }
+
+  const queryResult = querySchema.safeParse(rawQuery)
+  if (!queryResult.success) {
+    return jsonError(400, 'Invalid query parameters.', 'validation_error', {
+      issues: queryResult.error.issues,
+    })
+  }
+
+  const { from, to, agentId, modelId } = queryResult.data
+
+  try {
+    const container = await createRequestContainer()
+    const rbacService = container.resolve<RbacService>('rbacService')
+    const acl = await rbacService.loadAcl(auth.sub, {
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+    })
+
+    if (!hasRequiredFeatures([REQUIRED_FEATURE], acl.features, acl.isSuperAdmin, rbacService)) {
+      return jsonError(403, `Caller lacks required feature "${REQUIRED_FEATURE}".`, 'forbidden')
+    }
+
+    if (!auth.tenantId) {
+      return NextResponse.json({ rows: [], total: 0 })
+    }
+
+    const em = container.resolve<EntityManager>('em')
+    const repo = new AiTokenUsageRepository(em)
+    const rows = await repo.listDailyRollup(auth.tenantId, from, to, { agentId, modelId })
+
+    const serialized = rows.map((row) => ({
+      id: row.id,
+      tenantId: row.tenantId,
+      organizationId: row.organizationId ?? null,
+      day: toDateString(row.day),
+      agentId: row.agentId,
+      modelId: row.modelId,
+      providerId: row.providerId,
+      inputTokens: toIntegerString(row.inputTokens),
+      outputTokens: toIntegerString(row.outputTokens),
+      cachedInputTokens: toIntegerString(row.cachedInputTokens),
+      reasoningTokens: toIntegerString(row.reasoningTokens),
+      stepCount: toIntegerString(row.stepCount),
+      turnCount: toIntegerString(row.turnCount),
+      sessionCount: toIntegerString(row.sessionCount),
+      createdAt: toIsoString(row.createdAt),
+      updatedAt: toIsoString(row.updatedAt),
+    }))
+
+    return NextResponse.json({ rows: serialized, total: serialized.length })
+  } catch (error) {
+    console.error('[AI Usage Daily] GET error:', error)
+    return jsonError(500, 'Failed to fetch daily usage data.', 'internal_error')
+  }
+}

package/src/modules/ai_assistant/api/usage/sessions/[sessionId]/__tests__/route.test.ts

@@ -0,0 +1,143 @@
+const authMock = jest.fn()
+const loadAclMock = jest.fn()
+const createRequestContainerMock = jest.fn()
+const listEventsForSessionMock = jest.fn()
+
+jest.mock('@open-mercato/shared/lib/auth/server', () => ({
+  getAuthFromRequest: (...args: unknown[]) => authMock(...args),
+}))
+
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: (...args: unknown[]) => createRequestContainerMock(...args),
+}))
+
+jest.mock('../../../../../data/repositories/AiTokenUsageRepository', () => ({
+  AiTokenUsageRepository: jest.fn().mockImplementation(() => ({
+    listEventsForSession: listEventsForSessionMock,
+  })),
+}))
+
+import { GET } from '../route'
+
+const SESSION_ID = '11111111-1111-4111-8111-111111111111'
+
+function buildRequest() {
+  return new Request(`http://localhost/api/ai_assistant/usage/sessions/${SESSION_ID}`, { method: 'GET' })
+}
+
+function buildContext(sessionId: string) {
+  return { params: Promise.resolve({ sessionId }) }
+}
+
+function makeEvent(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'evt-1',
+    tenantId: 'tenant-1',
+    organizationId: null,
+    userId: 'user-1',
+    agentId: 'catalog.assistant',
+    moduleId: 'catalog',
+    sessionId: SESSION_ID,
+    turnId: '22222222-2222-4222-8222-222222222222',
+    stepIndex: 0,
+    providerId: 'anthropic',
+    modelId: 'claude-haiku-4-5',
+    inputTokens: 100,
+    outputTokens: 50,
+    cachedInputTokens: null,
+    reasoningTokens: null,
+    finishReason: 'stop',
+    loopAbortReason: null,
+    createdAt: new Date('2026-05-01T12:00:00Z'),
+    updatedAt: new Date('2026-05-01T12:00:00Z'),
+    ...overrides,
+  }
+}
+
+describe('GET /api/ai_assistant/usage/sessions/[sessionId]', () => {
+  let consoleErrorSpy: jest.SpyInstance
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    authMock.mockResolvedValue({ sub: 'user-1', tenantId: 'tenant-1', orgId: null })
+    loadAclMock.mockResolvedValue({ features: ['ai_assistant.settings.manage'], isSuperAdmin: false })
+    createRequestContainerMock.mockResolvedValue({
+      resolve: (name: string) => {
+        if (name === 'rbacService') return { loadAcl: loadAclMock, hasAllFeatures: (req: string[], have: string[]) => req.every((r) => have.includes(r)) }
+        if (name === 'em') return {}
+        throw new Error(`Unknown token: ${name}`)
+      },
+    })
+    listEventsForSessionMock.mockResolvedValue([])
+  })
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore()
+  })
+
+  it('returns 401 when unauthenticated', async () => {
+    authMock.mockResolvedValue(null)
+    const res = await GET(buildRequest() as Parameters<typeof GET>[0], buildContext(SESSION_ID))
+    expect(res.status).toBe(401)
+  })
+
+  it('returns 403 when caller lacks ai_assistant.settings.manage', async () => {
+    loadAclMock.mockResolvedValue({ features: ['ai_assistant.view'], isSuperAdmin: false })
+    const res = await GET(buildRequest() as Parameters<typeof GET>[0], buildContext(SESSION_ID))
+    expect(res.status).toBe(403)
+  })
+
+  it('returns 400 for an invalid (non-UUID) session id', async () => {
+    const res = await GET(buildRequest() as Parameters<typeof GET>[0], buildContext('not-a-uuid'))
+    expect(res.status).toBe(400)
+    const body = await res.json()
+    expect(body.code).toBe('validation_error')
+  })
+
+  it('returns 404 when no events exist for the session', async () => {
+    listEventsForSessionMock.mockResolvedValue([])
+    const res = await GET(buildRequest() as Parameters<typeof GET>[0], buildContext(SESSION_ID))
+    expect(res.status).toBe(404)
+    const body = await res.json()
+    expect(body.code).toBe('session_not_found')
+  })
+
+  it('returns 200 with serialized events when events exist', async () => {
+    listEventsForSessionMock.mockResolvedValue([
+      makeEvent({
+        stepIndex: 0n,
+        inputTokens: 100n,
+        outputTokens: 50n,
+        cachedInputTokens: 5n,
+        reasoningTokens: 7n,
+        createdAt: '2026-05-01T12:00:00.000Z',
+        updatedAt: '2026-05-01T12:30:00.000Z',
+      }),
+    ])
+    const res = await GET(buildRequest() as Parameters<typeof GET>[0], buildContext(SESSION_ID))
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.events).toHaveLength(1)
+    expect(body.events[0].agentId).toBe('catalog.assistant')
+    expect(body.events[0].finishReason).toBe('stop')
+    expect(body.events[0]).toMatchObject({
+      stepIndex: 0,
+      inputTokens: 100,
+      outputTokens: 50,
+      cachedInputTokens: 5,
+      reasoningTokens: 7,
+      createdAt: '2026-05-01T12:00:00.000Z',
+      updatedAt: '2026-05-01T12:30:00.000Z',
+    })
+    expect(body.total).toBe(1)
+    expect(body.sessionId).toBe(SESSION_ID)
+  })
+
+  it('allows superadmin to bypass feature check', async () => {
+    listEventsForSessionMock.mockResolvedValue([makeEvent()])
+    loadAclMock.mockResolvedValue({ features: [], isSuperAdmin: true })
+    const res = await GET(buildRequest() as Parameters<typeof GET>[0], buildContext(SESSION_ID))
+    expect(res.status).toBe(200)
+  })
+})