feat(service-ai): optional per-turn daily chat quota on the agent chat route (ADR-0040 §5) (#1760)

os-zhuang · claude · web-flow · commit 57abe7aeecf7 · 2026-06-12T08:27:42.000+05:00
Mechanism only, default OFF — no behavior change unless a deployment sets
AI_DAILY_USER_MESSAGES=&lt;N&gt;:

- AgentChatQuota hook on buildAgentRoutes: checked before each user turn,
  consumed exactly once when admitted (per turn, not per tool call).
- Refusal is honest at the moment of impact (perception rule): streaming
  clients receive the copy as a normal assistant message (no client change,
  no raw transport error); JSON clients get 429 + code 'ai_quota_exhausted'
  + resetAt.
- DailyMessageQuota: N user turns / user / environment / UTC day, backed by
  the new ai_usage_daily platform object via IDataEngine. Counter semantics
  (lost update under-counts one turn) — entitlement gate, not billing.
  Fail-open on store errors: a broken counter never takes chat down.
- Plan-tier policies (free vs pro) later implement AgentChatQuota and plug
  into the same gate; route and counter unchanged.

10 new tests (quota policy + route gate, both modes, env scoping, fail-open).

Co-authored-by: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/packages/services/service-ai/src/__tests__/agent-chat-quota.test.ts b/packages/services/service-ai/src/__tests__/agent-chat-quota.test.ts
@@ -0,0 +1,197 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi } from 'vitest';
+import type { IDataEngine, Logger } from '@objectstack/spec/contracts';
+import { DailyMessageQuota, type AgentChatQuota } from '../quota/agent-chat-quota.js';
+import { buildAgentRoutes } from '../routes/agent-routes.js';
+import { AIService } from '../ai-service.js';
+import { MemoryLLMAdapter } from '../adapters/memory-adapter.js';
+import { InMemoryConversationService } from '../conversation/in-memory-conversation-service.js';
+import type { AgentRuntime } from '../agent-runtime.js';
+
+const silentLogger: Logger = {
+  debug: vi.fn(),
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  fatal: vi.fn(),
+};
+
+const FIXED_NOW = () => new Date('2026-06-12T10:00:00.000Z');
+
+function mockDataEngine(rows: Record<string, { messages: number }> = {}): IDataEngine & {
+  inserted: unknown[];
+  updated: unknown[];
+} {
+  const inserted: unknown[] = [];
+  const updated: unknown[] = [];
+  return {
+    inserted,
+    updated,
+    findOne: vi.fn(async (_obj: string, q?: { where?: { id?: string } }) => {
+      const id = q?.where?.id;
+      return id && rows[id] ? { id, ...rows[id] } : null;
+    }),
+    insert: vi.fn(async (_obj: string, data: unknown) => {
+      inserted.push(data);
+      return data;
+    }),
+    update: vi.fn(async (_obj: string, data: unknown, opts: unknown) => {
+      updated.push({ data, opts });
+      return data;
+    }),
+    find: vi.fn(async () => []),
+    delete: vi.fn(async () => ({})),
+    count: vi.fn(async () => 0),
+    aggregate: vi.fn(async () => []),
+  } as unknown as IDataEngine & { inserted: unknown[]; updated: unknown[] };
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// DailyMessageQuota
+// ═══════════════════════════════════════════════════════════════════
+
+describe('DailyMessageQuota', () => {
+  const subject = { userId: 'u1', environmentId: 'env1' };
+  const todayId = '2026-06-12:env1:u1';
+
+  it('allows under the limit and reports remaining + resetAt', async () => {
+    const quota = new DailyMessageQuota(mockDataEngine({ [todayId]: { messages: 3 } }), 30, FIXED_NOW);
+    const d = await quota.check(subject);
+    expect(d.allowed).toBe(true);
+    expect(d.remaining).toBe(26); // 30 - 3 - this turn
+    expect(d.resetAt).toBe('2026-06-13T00:00:00.000Z');
+  });
+
+  it('refuses at the limit with honest copy (why + when + way out)', async () => {
+    const quota = new DailyMessageQuota(mockDataEngine({ [todayId]: { messages: 30 } }), 30, FIXED_NOW);
+    const d = await quota.check(subject);
+    expect(d.allowed).toBe(false);
+    expect(d.resetAt).toBe('2026-06-13T00:00:00.000Z');
+    expect(d.message).toContain('30');
+    expect(d.message).toContain('恢复');
+    expect(d.message).toContain('upgrade');
+  });
+
+  it('consume inserts the first turn of the day, then increments', async () => {
+    const engine = mockDataEngine();
+    const quota = new DailyMessageQuota(engine, 30, FIXED_NOW);
+    await quota.consume(subject);
+    expect(engine.inserted).toEqual([
+      { id: todayId, day: '2026-06-12', user_id: 'u1', environment_id: 'env1', messages: 1 },
+    ]);
+
+    const engine2 = mockDataEngine({ [todayId]: { messages: 5 } });
+    const quota2 = new DailyMessageQuota(engine2, 30, FIXED_NOW);
+    await quota2.consume(subject);
+    expect(engine2.updated).toEqual([{ data: { messages: 6 }, opts: { where: { id: todayId } } }]);
+  });
+
+  it('fails OPEN when the counter store errors — never blocks chat', async () => {
+    const engine = mockDataEngine();
+    (engine.findOne as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('db down'));
+    const quota = new DailyMessageQuota(engine, 1, FIXED_NOW);
+    await expect(quota.check(subject)).resolves.toMatchObject({ allowed: true });
+    await expect(quota.consume(subject)).resolves.toBeUndefined();
+  });
+
+  it('scopes the counter per environment and per user', async () => {
+    const engine = mockDataEngine({ ['2026-06-12:envA:u1']: { messages: 99 } });
+    const quota = new DailyMessageQuota(engine, 10, FIXED_NOW);
+    // Same user, different environment → independent counter.
+    expect((await quota.check({ userId: 'u1', environmentId: 'envB' })).allowed).toBe(true);
+    // Different user, same environment → independent counter.
+    expect((await quota.check({ userId: 'u2', environmentId: 'envA' })).allowed).toBe(true);
+    // The exhausted pair stays refused.
+    expect((await quota.check({ userId: 'u1', environmentId: 'envA' })).allowed).toBe(false);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════
+// Agent chat route × quota gate
+// ═══════════════════════════════════════════════════════════════════
+
+function mockAgentRuntime(): AgentRuntime {
+  return {
+    loadAgent: vi.fn(async () => ({
+      name: 'data_chat',
+      label: 'Assistant',
+      active: true,
+    })),
+    resolveActiveSkills: vi.fn(async () => []),
+    buildSystemMessages: vi.fn(() => [{ role: 'system', content: 'sys' }]),
+    buildRequestOptions: vi.fn(() => ({})),
+    listAgents: vi.fn(async () => []),
+  } as unknown as AgentRuntime;
+}
+
+function chatRoute(quota?: AgentChatQuota) {
+  const aiService = new AIService({
+    adapter: new MemoryLLMAdapter(),
+    conversationService: new InMemoryConversationService(),
+  });
+  const routes = buildAgentRoutes(aiService, mockAgentRuntime(), silentLogger, { quota });
+  const route = routes.find((r) => r.path.endsWith('/chat'));
+  if (!route) throw new Error('chat route not found');
+  return route;
+}
+
+const chatReq = (over: Record<string, unknown> = {}) => ({
+  params: { agentName: 'data_chat' },
+  body: { messages: [{ role: 'user', content: 'hi' }], stream: false, ...over },
+  user: { userId: 'u1' },
+});
+
+describe('agent chat route quota gate', () => {
+  it('passes through and consumes exactly once when allowed', async () => {
+    const quota: AgentChatQuota = {
+      check: vi.fn(async () => ({ allowed: true })),
+      consume: vi.fn(async () => {}),
+    };
+    const res = await chatRoute(quota).handler(chatReq() as never);
+    expect(res.status).toBe(200);
+    expect(quota.check).toHaveBeenCalledTimes(1);
+    expect(quota.consume).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns 429 + stable code on JSON mode when exhausted (nothing consumed)', async () => {
+    const quota: AgentChatQuota = {
+      check: vi.fn(async () => ({ allowed: false, message: '额度已用完', resetAt: '2026-06-13T00:00:00.000Z' })),
+      consume: vi.fn(async () => {}),
+    };
+    const res = await chatRoute(quota).handler(chatReq() as never);
+    expect(res.status).toBe(429);
+    expect(res.body).toMatchObject({ code: 'ai_quota_exhausted', error: '额度已用完', resetAt: '2026-06-13T00:00:00.000Z' });
+    expect(quota.consume).not.toHaveBeenCalled();
+  });
+
+  it('streams the refusal as a normal assistant message in stream mode', async () => {
+    const quota: AgentChatQuota = {
+      check: vi.fn(async () => ({ allowed: false, message: '今日额度已用完,明日恢复' })),
+      consume: vi.fn(async () => {}),
+    };
+    const res = await chatRoute(quota).handler(chatReq({ stream: true }) as never);
+    expect(res.status).toBe(200);
+    expect(res.stream).toBe(true);
+    let text = '';
+    for await (const chunk of res.events as AsyncIterable<string>) text += chunk;
+    expect(text).toContain('今日额度已用完');
+    expect(text).toContain('"type":"finish"');
+    expect(quota.consume).not.toHaveBeenCalled();
+  });
+
+  it('no quota wired → unchanged behavior', async () => {
+    const res = await chatRoute(undefined).handler(chatReq() as never);
+    expect(res.status).toBe(200);
+  });
+
+  it('forwards the environmentId from chat context to the quota subject', async () => {
+    const quota: AgentChatQuota = {
+      check: vi.fn(async () => ({ allowed: true })),
+      consume: vi.fn(async () => {}),
+    };
+    await chatRoute(quota).handler(chatReq({ context: { environmentId: 'env42' } }) as never);
+    expect(quota.check).toHaveBeenCalledWith({ userId: 'u1', environmentId: 'env42' });
+    expect(quota.consume).toHaveBeenCalledWith({ userId: 'u1', environmentId: 'env42' });
+  });
+});
diff --git a/packages/services/service-ai/src/objects/ai-usage-daily.object.ts b/packages/services/service-ai/src/objects/ai-usage-daily.object.ts
@@ -0,0 +1,59 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * ai_usage_daily — per-user, per-day AI chat usage counters
+ *
+ * One row per (UTC day, environment, user). The agent chat route increments
+ * `messages` once per user turn; {@link DailyMessageQuota} reads it to decide
+ * whether a daily message limit has been reached.
+ *
+ * This is a quota counter, not billing-grade metering: increments are
+ * last-write-wins and a lost update under concurrency only ever under-counts
+ * by a message — acceptable for an abuse/entitlement gate, not for invoicing.
+ *
+ * @namespace ai
+ */
+export const AiUsageDailyObject = ObjectSchema.create({
+  name: 'ai_usage_daily',
+  label: 'AI Daily Usage',
+  pluralLabel: 'AI Daily Usage',
+  icon: 'gauge',
+  isSystem: true,
+  description: 'Per-user daily AI chat usage counters (quota enforcement)',
+
+  fields: {
+    id: Field.text({
+      label: 'Usage ID',
+      required: true,
+      readonly: true,
+      description: 'Deterministic key: <day>:<environment|->:<user>',
+    }),
+
+    day: Field.text({
+      label: 'Day (UTC)',
+      required: true,
+      maxLength: 10,
+      description: 'UTC calendar day, YYYY-MM-DD',
+    }),
+
+    user_id: Field.text({
+      label: 'User ID',
+      required: true,
+      maxLength: 255,
+    }),
+
+    environment_id: Field.text({
+      label: 'Environment ID',
+      required: false,
+      maxLength: 255,
+    }),
+
+    messages: Field.number({
+      label: 'Messages',
+      required: true,
+      description: 'User chat turns consumed this day',
+    }),
+  },
+});
diff --git a/packages/services/service-ai/src/objects/index.ts b/packages/services/service-ai/src/objects/index.ts
@@ -12,3 +12,4 @@ export { AiTraceObject } from './ai-trace.object.js';
 export { AiPendingActionObject } from './ai-pending-action.object.js';
 export { AiEvalCaseObject } from './ai-eval-case.object.js';
 export { AiEvalRunObject } from './ai-eval-run.object.js';
+export { AiUsageDailyObject } from './ai-usage-daily.object.js';
diff --git a/packages/services/service-ai/src/plugin.ts b/packages/services/service-ai/src/plugin.ts
@@ -14,7 +14,8 @@ import { buildToolRoutes } from './routes/tool-routes.js';
 import { buildPendingActionRoutes } from './routes/pending-action-routes.js';
 import { buildEvalRoutes } from './routes/eval-routes.js';
 import { ObjectQLConversationService } from './conversation/objectql-conversation-service.js';
-import { AiConversationObject, AiMessageObject, AiPendingActionObject, AiTraceObject, AiEvalCaseObject, AiEvalRunObject } from './objects/index.js';
+import { AiConversationObject, AiMessageObject, AiPendingActionObject, AiTraceObject, AiEvalCaseObject, AiEvalRunObject, AiUsageDailyObject } from './objects/index.js';
+import { DailyMessageQuota, type AgentChatQuota } from './quota/agent-chat-quota.js';
 import { AiTraceView, AiMessageView, AiPendingActionView, AiEvalCaseView, AiEvalRunView } from './views/index.js';
 import { EvalRunner } from './eval/index.js';
 import { registerDataTools } from './tools/data-tools.js';
@@ -593,7 +594,7 @@ export class AIServicePlugin implements Plugin {
       type: 'plugin',
       scope: 'system',
       namespace: 'ai',
-      objects: [AiConversationObject, AiMessageObject, AiTraceObject, AiPendingActionObject, AiEvalCaseObject, AiEvalRunObject],
+      objects: [AiConversationObject, AiMessageObject, AiTraceObject, AiPendingActionObject, AiEvalCaseObject, AiEvalRunObject, AiUsageDailyObject],
       views: [AiTraceView, AiMessageView, AiPendingActionView, AiEvalCaseView, AiEvalRunView],
     });
 
@@ -857,7 +858,26 @@ export class AIServicePlugin implements Plugin {
     if (metadataService) {
       const skillRegistry = new SkillRegistry(metadataService);
       const agentRuntime = new AgentRuntime(metadataService, skillRegistry);
-      const agentRoutes = buildAgentRoutes(this.service, agentRuntime, ctx.logger);
+
+      // ── Optional per-turn chat quota (ADR-0040 §5, perception rule) ──
+      // Mechanism only: the deployment opts in by setting
+      // AI_DAILY_USER_MESSAGES=<N>. Unset/invalid → no quota, unchanged
+      // behavior. Plan-tier policies (free vs pro) wire a richer
+      // AgentChatQuota here later; the gate and counter do not change.
+      let chatQuota: AgentChatQuota | undefined;
+      const quotaRaw = process.env.AI_DAILY_USER_MESSAGES;
+      const quotaLimit = quotaRaw ? Number.parseInt(quotaRaw, 10) : NaN;
+      if (Number.isFinite(quotaLimit) && quotaLimit > 0) {
+        const quotaDataEngine = ctx.getService<IDataEngine>('data');
+        if (quotaDataEngine && typeof quotaDataEngine.findOne === 'function') {
+          chatQuota = new DailyMessageQuota(quotaDataEngine, quotaLimit);
+          ctx.logger.info(`[AI] Daily chat quota enabled (${quotaLimit} user turns/user/day)`);
+        } else {
+          ctx.logger.warn('[AI] AI_DAILY_USER_MESSAGES set but IDataEngine unavailable — quota disabled');
+        }
+      }
+
+      const agentRoutes = buildAgentRoutes(this.service, agentRuntime, ctx.logger, { quota: chatQuota });
       routes.push(...agentRoutes);
       ctx.logger.info(`[AI] Agent routes registered (${agentRoutes.length} routes)`);
 
diff --git a/packages/services/service-ai/src/quota/agent-chat-quota.ts b/packages/services/service-ai/src/quota/agent-chat-quota.ts
diff --git a/packages/services/service-ai/src/routes/agent-routes.ts b/packages/services/service-ai/src/routes/agent-routes.ts
