agent-relay-server 0.19.3 → 0.20.0

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.17.0",
+    "version": "0.19.3",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",
@@ -10774,21 +10774,57 @@
           "System"
         ],
         "description": "Returns agent count, online count, and message statistics.",
+        "parameters": [
+          {
+            "name": "period",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
         "responses": {
           "200": {
             "description": "Success",
             "content": {
               "application/json": {}
             }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
           },
-          "404": {
-            "description": "Not found",
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
+    "/api/stats/analytics": {
+      "get": {
+        "operationId": "getAnalyticsRoute",
+        "summary": "Get Analytics",
+        "tags": [
+          "System"
+        ],
+        "parameters": [
+          {
+            "name": "period",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
             "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
+              "application/json": {}
             }
           }
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.19.3",
+  "version": "0.20.0",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -33,7 +33,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-sdk": "0.2.10"
+    "agent-relay-sdk": "0.2.11"
   },
   "scripts": {
     "prepack": "bun run build:dashboard:bundle >&2",

package/public/index.html

@@ -11944,6 +11944,7 @@ var useRelayStore = create$1()(persist((set, get) => ({
 	agents: [],
 	agentsById: {},
 	messages: [],
+	threadHistory: {},
 	pairs: [],
 	tasks: [],
 	orchestrators: [],
@@ -12028,6 +12029,7 @@ var useRelayStore = create$1()(persist((set, get) => ({
 	chatHasNewItems: false,
 	pendingForkImport: null,
 	analyticsPeriod: "24h",
+	analyticsData: null,
 	inboxReadCursors: {},
 	inboxArchivedThreads: {},
 	inboxDrafts: {},
@@ -12152,7 +12154,8 @@ var useRelayStore = create$1()(persist((set, get) => ({
 				context: true,
 				skills: true,
 				plugins: true,
-				statusLine: true
+				statusLine: true,
+				mcp: true
 			},
 			skills: [],
 			plugins: [],
@@ -12248,6 +12251,7 @@ var useRelayStore = create$1()(persist((set, get) => ({
 			s.fetchAgents()
 		]);
 		if (view === "files") await s.fetchOrchestrators();
+		if (view === "analytics") await s.fetchAnalytics();
 	},
 	startClock() {
 		useClock.getState().start();
@@ -12362,6 +12366,7 @@ var useRelayStore = create$1()(persist((set, get) => ({
 			if (view === "maintenance") work.push(s.fetchMaintenanceJobs());
 			if (view === "profiles") work.push(s.fetchAgentProfiles());
 			if (view === "workspaces") work.push(s.fetchWorkspaces());
+			if (view === "analytics") work.push(s.fetchAnalytics());
 			await Promise.all(work);
 		} finally {
 			set({ _refreshInFlight: false });
@@ -12372,6 +12377,15 @@ var useRelayStore = create$1()(persist((set, get) => ({
 			set({ stats: await api("GET", "/stats") });
 		} catch {}
 	},
+	async fetchAnalytics() {
+		try {
+			set({ analyticsData: await api("GET", "/stats/analytics?period=" + get().analyticsPeriod) });
+		} catch {}
+	},
+	setAnalyticsPeriod(period) {
+		set({ analyticsPeriod: period });
+		get().fetchAnalytics();
+	},
 	async fetchHealth() {
 		try {
 			set({ health: await api("GET", "/health") });
@@ -12630,6 +12644,16 @@ var useRelayStore = create$1()(persist((set, get) => ({
 			set({ messages: mergeFetchedMessages(get().messages, messages) });
 		} catch {}
 	},
+	async fetchThreadHistory(peer) {
+		if (!peer) return;
+		try {
+			const history = await api("GET", "/messages?for=" + encodeURIComponent(peer) + "&limit=500");
+			set({ threadHistory: {
+				...get().threadHistory,
+				[peer]: history
+			} });
+		} catch {}
+	},
 	async fetchChatHistoryImports() {
 		try {
 			set({ chatHistoryImports: await api("GET", "/chat/history-imports?limit=500") });
@@ -13240,6 +13264,7 @@ var useRelayStore = create$1()(persist((set, get) => ({
 	openInboxThread(peer, messages = []) {
 		set({ selectedInboxThread: peer });
 		if (messages.length) get().markInboxThreadRead(peer, messages);
+		get().fetchThreadHistory(peer);
 	},
 	async sendChatMessage(body, thread, attachments = []) {
 		if (!body.trim() && attachments.length === 0 || get().chatSending) return;
@@ -13995,7 +14020,8 @@ var useRelayStore = create$1()(persist((set, get) => ({
 				context: true,
 				skills: true,
 				plugins: true,
-				statusLine: true
+				statusLine: true,
+				mcp: true
 			},
 			skills: [],
 			plugins: [],
@@ -125295,6 +125321,7 @@ function useChatAgents() {
 	]);
 }
 var NO_STATUS_EVENTS = [];
+var NO_THREAD_HISTORY = [];
 function useAgentStatusEvents(agentId) {
 	return useRelayStore((s) => s.chatStatusEvents[agentId] ?? NO_STATUS_EVENTS);
 }
@@ -126768,6 +126795,7 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 	const doAgentAction = useRelayStore((s) => s.doAgentAction);
 	const forkFromAgent = useRelayStore((s) => s.forkFromAgent);
 	const chatHistoryImports = useRelayStore((s) => s.chatHistoryImports);
+	const peerHistory = useRelayStore((s) => s.threadHistory[s.selectedInboxThread] ?? NO_THREAD_HISTORY);
 	const openConfirm = useRelayStore((s) => s.openConfirm);
 	const showError = useRelayStore((s) => s.showError);
 	const orchestrators = useRelayStore((s) => s.orchestrators);
@@ -126805,6 +126833,18 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 	const filePreviewRequest = (0, import_react.useRef)(0);
 	const statusEvents = useAgentStatusEvents(selectedInboxThread);
 	const thread = (0, import_react.useMemo)(() => threads.find((t) => t.peer === selectedInboxThread) || null, [threads, selectedInboxThread]);
+	const threadMessages = (0, import_react.useMemo)(() => {
+		const live = thread?.messages ?? [];
+		if (peerHistory.length === 0) return live;
+		const byId = /* @__PURE__ */ new Map();
+		for (const m of peerHistory) if (inboxPeer(m) === selectedInboxThread && !isReactionEventMessage(m)) byId.set(m.id, m);
+		for (const m of live) byId.set(m.id, m);
+		return [...byId.values()].sort((a, b) => a.id - b.id);
+	}, [
+		thread?.messages,
+		peerHistory,
+		selectedInboxThread
+	]);
 	const agent = agentsById[selectedInboxThread] || null;
 	const agentSpawnRequestId = typeof agent?.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : "";
 	const importedHistory = (0, import_react.useMemo)(() => {
@@ -126824,7 +126864,7 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 	const draft = inboxDrafts[selectedInboxThread] || "";
 	const importedEntryCount = importedHistory.reduce((sum, history) => sum + history.entries.length, 0);
 	const pinnedScroll = usePinnedScroll(selectedInboxThread, [
-		thread?.messages.length,
+		threadMessages.length,
 		statusEvents.length,
 		importedEntryCount,
 		pendingApproval?.id,
@@ -126880,8 +126920,8 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 			if (filePreviewCloseTimer.current !== null) window.clearTimeout(filePreviewCloseTimer.current);
 		};
 	}, []);
-	const timeline = (0, import_react.useMemo)(() => buildTimeline(thread?.messages || [], statusEvents, agent?.createdAt, importedHistory), [
-		thread?.messages,
+	const timeline = (0, import_react.useMemo)(() => buildTimeline(threadMessages, statusEvents, agent?.createdAt, importedHistory), [
+		threadMessages,
 		statusEvents,
 		agent?.createdAt,
 		importedHistory
@@ -152495,13 +152535,14 @@ var PERIODS = [
 function periodMs(id) {
 	return PERIODS.find((p) => p.id === id)?.ms ?? 864e5;
 }
-function categorizeMessage(msg) {
-	if (msg.claimable) return "Work items";
-	if (msg.kind === "system" || msg.from === "system") return "System";
-	if (msg.kind === "pair") return "Pair";
-	if (msg.kind === "channel.event") return "Channel";
-	return "Messages";
-}
+var CATEGORY_ORDER = [
+	"Messages",
+	"Replies",
+	"Work items",
+	"System",
+	"Pair",
+	"Channel"
+];
 function StatCard({ label, value, icon: Icon, className = "" }) {
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Card, { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CardContent, {
 		className: "pt-4",
@@ -152522,11 +152563,11 @@ function StatCard({ label, value, icon: Icon, className = "" }) {
 }
 function PeriodSelector() {
 	const period = useRelayStore((s) => s.analyticsPeriod);
-	const set = useRelayStore((s) => s.set);
+	const setPeriod = useRelayStore((s) => s.setAnalyticsPeriod);
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", {
 		className: "flex items-center gap-1 bg-muted rounded-lg p-1",
 		children: PERIODS.map((p) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", {
-			onClick: () => set({ analyticsPeriod: p.id }),
+			onClick: () => setPeriod(p.id),
 			className: `px-3 py-1 rounded-md text-xs font-medium transition-colors ${period === p.id ? "bg-background text-foreground shadow-sm" : "text-muted-foreground hover:text-foreground"}`,
 			children: p.label
 		}, p.id))
@@ -152566,67 +152607,38 @@ function useChart(id, getOptions, deps) {
 }
 function AnalyticsView() {
 	const agents = useRelayStore((s) => s.agents);
-	const messages = useRelayStore((s) => s.messages);
-	useRelayStore((s) => s.stats);
+	const data = useRelayStore((s) => s.analyticsData);
 	const period = useRelayStore((s) => s.analyticsPeriod);
 	const theme = useRelayStore((s) => s.theme);
 	const onlineCount = useOnlineCount();
 	const busyCount = useBusyCount();
 	const isDark = THEMES.find((t) => t.id === theme)?.dark ?? true;
-	const cutoff = Date.now() - periodMs(period);
-	const filteredMessages = (0, import_react.useMemo)(() => {
-		return messages.filter((m) => {
-			const ts = toTimestamp(m.createdAt);
-			return ts && ts >= cutoff;
-		});
-	}, [messages, cutoff]);
 	const volumeData = (0, import_react.useMemo)(() => {
-		const ms = periodMs(period);
-		const bucketCount = period === "1h" ? 12 : period === "6h" ? 12 : period === "24h" ? 24 : period === "7d" ? 14 : period === "14d" ? 14 : 15;
-		const bucketMs = ms / bucketCount;
-		const now = Date.now();
-		const categories = [
-			"Messages",
-			"Replies",
-			"Work items",
-			"System",
-			"Pair",
-			"Channel"
-		];
-		const series = {};
-		for (const cat of categories) series[cat] = new Array(bucketCount).fill(0);
-		const labels = [];
-		for (let i = 0; i < bucketCount; i++) {
-			const t = /* @__PURE__ */ new Date(now - (bucketCount - 1 - i) * bucketMs);
-			if (ms <= 864e5) labels.push(t.toLocaleTimeString(void 0, {
-				hour: "2-digit",
-				minute: "2-digit"
-			}));
-			else labels.push(t.toLocaleDateString(void 0, {
-				month: "short",
-				day: "numeric"
-			}));
-		}
-		for (const msg of filteredMessages) {
-			const ts = toTimestamp(msg.createdAt);
-			if (!ts) continue;
-			const bucketIdx = Math.floor((ts - (now - ms)) / bucketMs);
-			if (bucketIdx < 0 || bucketIdx >= bucketCount) continue;
-			const bucket = series[categorizeMessage(msg)];
-			if (bucket) bucket[bucketIdx] = (bucket[bucketIdx] ?? 0) + 1;
-		}
+		if (!data) return {
+			labels: [],
+			series: []
+		};
+		const asTime = periodMs(period) <= 864e5;
 		return {
-			labels,
-			series: categories.flatMap((c) => {
-				const data = series[c];
-				if (!data || !data.some((v) => v > 0)) return [];
-				return [{
-					name: c,
-					data
-				}];
+			labels: data.buckets.map((b) => {
+				const t = new Date(b.start);
+				return asTime ? t.toLocaleTimeString(void 0, {
+					hour: "2-digit",
+					minute: "2-digit"
+				}) : t.toLocaleDateString(void 0, {
+					month: "short",
+					day: "numeric"
+				});
+			}),
+			series: CATEGORY_ORDER.flatMap((cat) => {
+				const series = data.buckets.map((b) => b.counts[cat] ?? 0);
+				return series.some((v) => v > 0) ? [{
+					name: cat,
+					data: series
+				}] : [];
 			})
 		};
-	}, [filteredMessages, period]);
+	}, [data, period]);
 	const utilizationData = (0, import_react.useMemo)(() => {
 		let idle = 0, busy = 0;
 		for (const a of agents) {
@@ -152641,14 +152653,7 @@ function AnalyticsView() {
 		};
 	}, [agents]);
 	const heatmapData = (0, import_react.useMemo)(() => {
-		const grid = Array.from({ length: 7 }, () => new Array(24).fill(0));
-		for (const msg of filteredMessages) {
-			const ts = toTimestamp(msg.createdAt);
-			if (!ts) continue;
-			const d = new Date(ts);
-			const row = grid[d.getDay()];
-			if (row) row[d.getHours()] = (row[d.getHours()] ?? 0) + 1;
-		}
+		const grid = data?.heatmap ?? Array.from({ length: 7 }, () => new Array(24).fill(0));
 		return [
 			"Sun",
 			"Mon",
@@ -152659,24 +152664,20 @@ function AnalyticsView() {
 			"Sat"
 		].map((name, dayIdx) => ({
 			name,
-			data: (grid[dayIdx] ?? []).map((v, hour) => ({
+			data: (grid[dayIdx] ?? new Array(24).fill(0)).map((v, hour) => ({
 				x: String(hour).padStart(2, "0"),
 				y: v
 			}))
 		}));
-	}, [filteredMessages]);
+	}, [data]);
 	const activityBreakdown = (0, import_react.useMemo)(() => {
-		const counts = {};
-		for (const msg of filteredMessages) {
-			const cat = categorizeMessage(msg);
-			counts[cat] = (counts[cat] ?? 0) + 1;
-		}
-		const entries = Object.entries(counts).filter(([, v]) => v > 0).sort((a, b) => b[1] - a[1]);
+		const counts = data?.categories;
+		const entries = counts ? Object.entries(counts).filter(([, v]) => v > 0).sort((a, b) => b[1] - a[1]) : [];
 		return {
 			labels: entries.map(([k]) => k),
 			values: entries.map(([, v]) => v)
 		};
-	}, [filteredMessages]);
+	}, [data]);
 	const chartColors = isDark ? {
 		text: "rgba(255,255,255,0.4)",
 		grid: "rgba(255,255,255,0.06)",
@@ -152815,8 +152816,9 @@ function AnalyticsView() {
 			}] }
 		} }
 	}), [heatmapData, isDark]);
-	const periodMessageCount = filteredMessages.length;
-	const reactionCount = filteredMessages.reduce((sum, m) => sum + (m.reactions?.length ?? 0), 0);
+	const periodMessageCount = data?.totalMessages ?? 0;
+	const reactionCount = data?.totalReactions ?? 0;
+	const hasHeatmapData = (data?.totalMessages ?? 0) > 0;
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
 		className: "space-y-6",
 		children: [
@@ -152882,7 +152884,7 @@ function AnalyticsView() {
 			/* @__PURE__ */ (0, import_jsx_runtime.jsxs)(Card, { children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(CardHeader, { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CardTitle, {
 				className: "text-sm",
 				children: "Busiest hours"
-			}) }), /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CardContent, { children: filteredMessages.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", {
+			}) }), /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CardContent, { children: !hasHeatmapData ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", {
 				className: "flex items-center justify-center h-[240px] text-muted-foreground text-sm",
 				children: "No data for heatmap"
 			}) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { id: "analytics-heatmap-chart" }) })] })
@@ -157595,7 +157597,8 @@ function AgentProfileModal() {
 				context: isHost,
 				skills: isHost,
 				plugins: isHost,
-				statusLine: isHost
+				statusLine: isHost,
+				mcp: isHost
 			},
 			mcp: {
 				...profile.mcp,
@@ -157695,14 +157698,15 @@ function AgentProfileModal() {
 									"context",
 									"skills",
 									"plugins",
-									"statusLine"
+									"statusLine",
+									"mcp"
 								].map((key) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
 									className: "flex items-center justify-between gap-2",
 									children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(Label, {
 										className: "capitalize",
-										children: key === "statusLine" ? "Status Line" : key
+										children: key === "statusLine" ? "Status Line" : key === "mcp" ? "MCP Tools" : key
 									}), /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Switch, {
-										checked: profile.relay[key],
+										checked: profile.relay[key] ?? true,
 										onCheckedChange: (v) => updateRelay({ [key]: v }),
 										disabled: readOnly
 									})]

package/runner/src/adapter.ts

@@ -40,6 +40,8 @@ export interface ProviderSessionEvent {
   origin?: "chat" | "terminal" | "provider";
   turnId?: string;
   label?: string;
+  status?: "running" | "completed" | "failed";
+  streaming?: boolean;
 }
 
 export interface ProviderConfig {

package/src/config-store.ts

@@ -204,6 +204,7 @@ function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Parti
       skills: input.relay?.skills ?? !isolated,
       plugins: input.relay?.plugins ?? !isolated,
       statusLine: input.relay?.statusLine ?? !isolated,
+      mcp: input.relay?.mcp ?? !isolated,
     },
     skills: input.skills ?? [],
     plugins: input.plugins ?? [],
@@ -274,6 +275,7 @@ function validateAgentProfile(key: string, value: unknown): AgentProfile {
       skills: relay.skills === undefined ? defaults.relay.skills : cleanBoolean(relay.skills, "relay.skills"),
       plugins: relay.plugins === undefined ? defaults.relay.plugins : cleanBoolean(relay.plugins, "relay.plugins"),
       statusLine: relay.statusLine === undefined ? defaults.relay.statusLine : cleanBoolean(relay.statusLine, "relay.statusLine"),
+      mcp: relay.mcp === undefined ? defaults.relay.mcp : cleanBoolean(relay.mcp, "relay.mcp"),
     },
     skills: cleanAgentProfileAssetArray(value.skills, "skills"),
     plugins: cleanAgentProfileAssetArray(value.plugins, "plugins"),

package/src/db.ts

@@ -4678,6 +4678,113 @@ export function getStats(): {
   return { version: VERSION, agents, online, messages, messagesLast24h, tasks, openTasks };
 }
 
+// Analytics aggregation periods. Bucket counts mirror the dashboard chart
+// granularity so the client renders pre-aggregated buckets directly. This is the
+// single source of truth — the dashboard no longer windows raw messages (which
+// capped it at the last ~100 rows ≈ 3h on a busy relay; the data was always
+// retained server-side per RETENTION_DAYS). See issue #212 for the Layer-2 rollup
+// that will let stats outlive the message-retention window.
+export const ANALYTICS_PERIODS = {
+  "1h": { ms: 3_600_000, buckets: 12 },
+  "6h": { ms: 21_600_000, buckets: 12 },
+  "24h": { ms: 86_400_000, buckets: 24 },
+  "7d": { ms: 604_800_000, buckets: 14 },
+  "14d": { ms: 1_209_600_000, buckets: 14 },
+  "30d": { ms: 2_592_000_000, buckets: 15 },
+} as const;
+
+export type AnalyticsPeriod = keyof typeof ANALYTICS_PERIODS;
+
+// Message → category, the ONE place this mapping lives (server-side SQL). Order is
+// significant: a claimable/system/pair/channel message is classified as such even
+// when it is also a reply; only an otherwise-plain reply counts as "Replies".
+export const ANALYTICS_CATEGORIES = ["Messages", "Replies", "Work items", "System", "Pair", "Channel"] as const;
+export type AnalyticsCategory = (typeof ANALYTICS_CATEGORIES)[number];
+const ANALYTICS_CATEGORY_SQL = `
+  CASE
+    WHEN claimable = 1 THEN 'Work items'
+    WHEN kind = 'system' OR from_agent = 'system' THEN 'System'
+    WHEN kind = 'pair' THEN 'Pair'
+    WHEN kind = 'channel.event' THEN 'Channel'
+    WHEN reply_to IS NOT NULL THEN 'Replies'
+    ELSE 'Messages'
+  END`;
+
+export interface AnalyticsData {
+  period: AnalyticsPeriod;
+  start: number;
+  now: number;
+  bucketMs: number;
+  bucketCount: number;
+  // Per-bucket category counts, oldest → newest, length === bucketCount.
+  buckets: Array<{ start: number; counts: Record<AnalyticsCategory, number> }>;
+  // Category totals over the whole period (powers the breakdown donut).
+  categories: Record<AnalyticsCategory, number>;
+  // Busiest-hours grid: heatmap[dayOfWeek 0=Sun][hour 0-23], in server-local time.
+  heatmap: number[][];
+  totalMessages: number;
+  totalReactions: number;
+}
+
+function emptyCategoryCounts(): Record<AnalyticsCategory, number> {
+  return { Messages: 0, Replies: 0, "Work items": 0, System: 0, Pair: 0, Channel: 0 };
+}
+
+export function getAnalytics(period: AnalyticsPeriod, now: number = Date.now()): AnalyticsData {
+  const { ms, buckets: bucketCount } = ANALYTICS_PERIODS[period] ?? ANALYTICS_PERIODS["24h"];
+  const start = now - ms;
+  const bucketMs = ms / bucketCount;
+
+  const buckets = Array.from({ length: bucketCount }, (_, i) => ({
+    start: start + i * bucketMs,
+    counts: emptyCategoryCounts(),
+  }));
+  const categories = emptyCategoryCounts();
+
+  // One pass: bucket index × category counts. CAST floors toward zero; created_at
+  // in (start, now] keeps the index in [0, bucketCount).
+  const volumeRows = db
+    .query(
+      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket, ${ANALYTICS_CATEGORY_SQL} AS category, COUNT(*) AS c
+       FROM messages WHERE created_at > ? AND created_at <= ? GROUP BY bucket, category`,
+    )
+    .all(start, bucketMs, start, now) as Array<{ bucket: number; category: AnalyticsCategory; c: number }>;
+  for (const row of volumeRows) {
+    const idx = Math.min(Math.max(row.bucket, 0), bucketCount - 1);
+    const bucket = buckets[idx];
+    if (bucket && row.category in bucket.counts) {
+      bucket.counts[row.category] += row.c;
+      categories[row.category] += row.c;
+    }
+  }
+  const totalMessages = Object.values(categories).reduce((sum, v) => sum + v, 0);
+
+  // Busiest-hours heatmap (day-of-week × hour), server-local time.
+  const heatmap: number[][] = Array.from({ length: 7 }, () => new Array(24).fill(0));
+  const heatRows = db
+    .query(
+      `SELECT CAST(strftime('%w', created_at / 1000, 'unixepoch', 'localtime') AS INTEGER) AS dow,
+              CAST(strftime('%H', created_at / 1000, 'unixepoch', 'localtime') AS INTEGER) AS hour, COUNT(*) AS c
+       FROM messages WHERE created_at > ? AND created_at <= ? GROUP BY dow, hour`,
+    )
+    .all(start, now) as Array<{ dow: number; hour: number; c: number }>;
+  for (const row of heatRows) {
+    const day = heatmap[row.dow];
+    if (day && row.hour >= 0 && row.hour < 24) day[row.hour] = row.c;
+  }
+
+  const totalReactions = (
+    db
+      .query(
+        `SELECT COUNT(*) AS c FROM message_reactions r
+         JOIN messages m ON m.id = r.message_id WHERE m.created_at > ? AND m.created_at <= ?`,
+      )
+      .get(start, now) as { c: number }
+  ).c;
+
+  return { period, start, now, bucketMs, bucketCount, buckets, categories, heatmap, totalMessages, totalReactions };
+}
+
 export function getHealth(now: number = Date.now()): HealthReport {
   const checks: HealthCheck[] = [];
 

package/src/routes.ts

@@ -27,6 +27,9 @@ import {
   markRead,
   deleteMessage,
   getStats,
+  getAnalytics,
+  ANALYTICS_PERIODS,
+  type AnalyticsPeriod,
   getHealth,
   getLatestMessageId,
   ingestIntegrationEvent,
@@ -6514,6 +6517,15 @@ const getEvents: Handler = (req) => {
 // --- Stats ---
 
 const getStatsRoute: Handler = () => json(getStats());
+
+const getAnalyticsRoute: Handler = (req) => {
+  const period = new URL(req.url).searchParams.get("period") ?? "24h";
+  if (!(period in ANALYTICS_PERIODS)) {
+    return error(`period must be one of ${Object.keys(ANALYTICS_PERIODS).join(", ")}`);
+  }
+  return json(getAnalytics(period as AnalyticsPeriod));
+};
+
 const getHealthRoute: Handler = () => json(getHealth());
 
 const getMaintenanceJobs: Handler = () => json(listMaintenanceJobs());
@@ -6819,6 +6831,7 @@ const routes: Route[] = [
 
   route("GET", "/api/events", getEvents),
   route("GET", "/api/stats", getStatsRoute),
+  route("GET", "/api/stats/analytics", getAnalyticsRoute),
   route("GET", "/api/health", getHealthRoute),
   route("GET", "/api/maintenance/jobs", getMaintenanceJobs),
   route("POST", "/api/maintenance/jobs/:id/run", postMaintenanceJobRun),

package/src/token-db.ts

@@ -57,7 +57,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Agent",
     description: "Coding-agent runtime access for messages, commands, tasks, and scoped memory reads.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use"],
     ttlSeconds: 24 * 60 * 60,
     builtIn: true,
     createdBy: "system",
@@ -67,7 +67,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Child Agent",
     description: "Delegated child-agent runtime access, constrained to its parent and spawn request.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use"],
     constraints: { canDelegate: false },
     ttlSeconds: 2 * 60 * 60,
     builtIn: true,
@@ -78,7 +78,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Interactive Agent",
     description: "User-launched provider runtime access constrained to its own agent and cwd for long interactive sessions.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use"],
     constraints: { terminalAttach: false, logsRead: false, canDelegate: false },
     ttlSeconds: 30 * 24 * 60 * 60,
     builtIn: true,