Add attention inbox and AI usage observability

packages/api-contracts/src/attention.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { RedditAccountOwnerSchema } from './session.js';
+
+export const AttentionKindSchema = z.enum([
+  'human-required',
+  'boundary',
+  'failed-delivery',
+  'account-login-required',
+  'runtime-failed',
+  'invitation-cooldown',
+]);
+
+export const AttentionItemSchema = z.strictObject({
+  id: z.string(),
+  kind: AttentionKindSchema,
+  severity: z.enum(['warning', 'critical']),
+  title: z.string(),
+  detail: z.string(),
+  occurredAt: z.number(),
+  owner: RedditAccountOwnerSchema.optional(),
+  conversationId: z.string().optional(),
+  username: z.string().optional(),
+});
+
+export const AttentionResponseSchema = z.strictObject({
+  generatedAt: z.number(),
+  items: z.array(AttentionItemSchema),
+});
+
+export type AttentionItem = z.infer<typeof AttentionItemSchema>;
+export type AttentionResponse = z.infer<typeof AttentionResponseSchema>;

packages/api-contracts/src/index.ts

@@ -1,4 +1,5 @@
 export * from './activity.js';
+export * from './attention.js';
 export * from './chats.js';
 export * from './common.js';
 export * from './config.js';

packages/api-contracts/src/stats.ts

@@ -74,5 +74,24 @@ export const FunnelResponseSchema = z.strictObject({
   images: z.number(),
 });
 
+const AiUsageFields = {
+  requests: z.number().int().nonnegative(),
+  successes: z.number().int().nonnegative(),
+  refusals: z.number().int().nonnegative(),
+  errors: z.number().int().nonnegative(),
+  promptTokens: z.number().int().nonnegative(),
+  completionTokens: z.number().int().nonnegative(),
+  totalTokens: z.number().int().nonnegative(),
+  costUsd: z.number().nonnegative(),
+  averageLatencyMs: z.number().nonnegative(),
+};
+
+export const AiUsageSummaryResponseSchema = z.strictObject({
+  days: z.number().int().positive(),
+  ...AiUsageFields,
+  models: z.array(z.strictObject({ model: z.string(), ...AiUsageFields })),
+});
+
 export type StatsResponse = z.infer<typeof StatsResponseSchema>;
 export type TimersResponse = z.infer<typeof TimersResponseSchema>;
+export type AiUsageSummaryResponse = z.infer<typeof AiUsageSummaryResponseSchema>;