agent-relay-server 0.57.2 → 0.59.0

package/src/db/stats.ts

@@ -135,20 +135,35 @@ export const ANALYTICS_PERIODS = {
 
 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];
-export const ANALYTICS_CATEGORY_SQL = `
+// ─── Analytics taxonomy ─────────────────────────────────────────────────────
+// The relay carries three distinct streams of activity, and analytics keeps them
+// SEPARATE rather than collapsing into one "messages" count (which is ~94%
+// session-mirror noise on a busy relay — see the work layer below):
+//   1. Conversation — real inter-agent / human messaging (chat, replies, channel, pair, work items)
+//   2. Work — session-mirror cognition: tool calls, reasoning, narration, responses
+//   3. Fleet — agent registrations/spawns + per-agent activity (NOT online/offline:
+//      agents start, work, and shut down constantly — point-in-time status is noise here)
+
+// Conversation categories. Order is significant: a claimable/channel/pair message
+// is classified as such even when it is also a reply; only an otherwise-plain reply
+// counts as "Replies". Session/control/system rows are EXCLUDED (they're streams 2/mechanical).
+export const CONVERSATION_CATEGORIES = ["Chat", "Replies", "Channel", "Pair", "Work items"] as const;
+export type ConversationCategory = (typeof CONVERSATION_CATEGORIES)[number];
+const CONVERSATION_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 kind = 'pair' THEN 'Pair'
     WHEN reply_to IS NOT NULL THEN 'Replies'
-    ELSE 'Messages'
+    ELSE 'Chat'
   END`;
+// Only real messaging — excludes the session-mirror lane and mechanical/system rows.
+const CONVERSATION_FILTER = `kind NOT IN ('session','control','system') AND from_agent != 'system'`;
+
+// Session-mirror event sub-types we surface as the "agent work" composition. (prompt
+// is counted in the user-interaction stream; notice is mechanical chatter.)
+export const WORK_TYPES = ["tool", "reasoning", "narration", "response"] as const;
+export type WorkType = (typeof WORK_TYPES)[number];
 
 export interface AnalyticsData {
   period: AnalyticsPeriod;
@@ -156,52 +171,196 @@ export interface AnalyticsData {
   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.
+  // 1. Conversation — real messaging volume, per-bucket (oldest→newest) + totals.
+  conversation: {
+    buckets: Array<{ start: number; counts: Record<ConversationCategory, number> }>;
+    totals: Record<ConversationCategory, number>;
+    total: number;
+  };
+  // 2. Work — session-mirror cognition: per-bucket type counts, totals, tool leaderboard, turn count.
+  work: {
+    buckets: Array<{ start: number; counts: Record<WorkType, number> }>;
+    totals: Record<WorkType, number>;
+    topTools: Array<{ name: string; count: number }>;
+    turns: number;
+    toolCalls: number;
+  };
+  // 3. User interaction — human prompts, reply rate, and agent reply latency (median is
+  // the headline; avg is tail-inflated by agents that were away mid-conversation).
+  user: {
+    prompts: number;
+    replied: number;
+    replyRate: number; // 0..1
+    latencyMs: { median: number; avg: number; p90: number } | null;
+    buckets: Array<{ start: number; prompts: number }>;
+  };
+  // 4. Fleet — activity-based, never online/offline. Registrations (spawns) over time,
+  // how many were agent-spawned, distinct active agents, and a per-agent leaderboard.
+  fleet: {
+    activeAgents: number;
+    registrations: number;
+    spawnedByAgent: number;
+    buckets: Array<{ start: number; registrations: number }>;
+    leaderboard: Array<{ id: string; label: string | null; turns: number; toolCalls: number; messages: number }>;
+  };
+  // Busiest-hours grid: heatmap[dayOfWeek 0=Sun][hour 0-23], server-local time, all activity.
   heatmap: number[][];
-  totalMessages: number;
   totalReactions: number;
 }
 
-export function emptyCategoryCounts(): Record<AnalyticsCategory, number> {
-  return { Messages: 0, Replies: 0, "Work items": 0, System: 0, Pair: 0, Channel: 0 };
+function emptyConversationCounts(): Record<ConversationCategory, number> {
+  return { Chat: 0, Replies: 0, Channel: 0, Pair: 0, "Work items": 0 };
+}
+function emptyWorkCounts(): Record<WorkType, number> {
+  return { tool: 0, reasoning: 0, narration: 0, response: 0 };
+}
+
+// Percentile over an unsorted list of numbers (linear interpolation-free nearest-rank).
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+  return sorted[idx] ?? 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 db = getDb();
+  // created_at in (start, now] keeps the floored bucket index in [0, bucketCount).
+  const clampIdx = (bucket: number) => Math.min(Math.max(bucket, 0), bucketCount - 1);
+  const bucketStarts = Array.from({ length: bucketCount }, (_, i) => start + i * bucketMs);
 
-  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 = getDb()
+  // ── 1. Conversation: real messaging volume ──
+  const conversationBuckets = bucketStarts.map((s) => ({ start: s, counts: emptyConversationCounts() }));
+  const conversationTotals = emptyConversationCounts();
+  const convRows = 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`,
+      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket, ${CONVERSATION_CATEGORY_SQL} AS category, COUNT(*) AS c
+       FROM messages WHERE created_at > ? AND created_at <= ? AND ${CONVERSATION_FILTER} 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];
+    .all(start, bucketMs, start, now) as Array<{ bucket: number; category: ConversationCategory; c: number }>;
+  for (const row of convRows) {
+    const bucket = conversationBuckets[clampIdx(row.bucket)];
     if (bucket && row.category in bucket.counts) {
       bucket.counts[row.category] += row.c;
-      categories[row.category] += row.c;
+      conversationTotals[row.category] += row.c;
+    }
+  }
+  const conversationTotal = Object.values(conversationTotals).reduce((sum, v) => sum + v, 0);
+
+  // ── 2. Work: session-mirror cognition ──
+  const workBuckets = bucketStarts.map((s) => ({ start: s, counts: emptyWorkCounts() }));
+  const workTotals = emptyWorkCounts();
+  const workRows = db
+    .query(
+      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket,
+              json_extract(payload, '$.session.type') AS wtype, COUNT(*) AS c
+       FROM messages WHERE created_at > ? AND created_at <= ? AND kind = 'session'
+         AND json_extract(payload, '$.session.type') IN ('tool','reasoning','narration','response')
+       GROUP BY bucket, wtype`,
+    )
+    .all(start, bucketMs, start, now) as Array<{ bucket: number; wtype: WorkType; c: number }>;
+  for (const row of workRows) {
+    const bucket = workBuckets[clampIdx(row.bucket)];
+    if (bucket && row.wtype in bucket.counts) {
+      bucket.counts[row.wtype] += row.c;
+      workTotals[row.wtype] += row.c;
     }
   }
-  const totalMessages = Object.values(categories).reduce((sum, v) => sum + v, 0);
+  const topTools = db
+    .query(
+      `SELECT json_extract(payload, '$.session.label') AS name, COUNT(*) AS count
+       FROM messages WHERE created_at > ? AND created_at <= ? AND kind = 'session'
+         AND json_extract(payload, '$.session.type') = 'tool'
+         AND json_extract(payload, '$.session.label') IS NOT NULL
+       GROUP BY name ORDER BY count DESC LIMIT 12`,
+    )
+    .all(start, now) as Array<{ name: string; count: number }>;
+  const turns = (
+    db
+      .query(
+        `SELECT COUNT(DISTINCT json_extract(payload, '$.session.turnId')) AS c
+         FROM messages WHERE created_at > ? AND created_at <= ? AND kind = 'session'
+           AND json_extract(payload, '$.session.turnId') IS NOT NULL`,
+      )
+      .get(start, now) as { c: number }
+  ).c;
+
+  // ── 3. User interaction: human prompts + agent reply latency ──
+  const userBuckets = bucketStarts.map((s) => ({ start: s, prompts: 0 }));
+  const promptRows = db
+    .query(
+      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket, COUNT(*) AS c
+       FROM messages WHERE created_at > ? AND created_at <= ? AND from_agent = 'user' GROUP BY bucket`,
+    )
+    .all(start, bucketMs, start, now) as Array<{ bucket: number; c: number }>;
+  let prompts = 0;
+  for (const row of promptRows) {
+    const bucket = userBuckets[clampIdx(row.bucket)];
+    if (bucket) bucket.prompts += row.c;
+    prompts += row.c;
+  }
+  // Latency = first threaded reply from a non-user agent, in (start, now] by the prompt's time.
+  const latencyRows = db
+    .query(
+      `SELECT (r.created_at - u.created_at) AS delta
+       FROM messages u JOIN messages r ON r.reply_to = u.id
+       WHERE u.from_agent = 'user' AND r.from_agent != 'user'
+         AND u.created_at > ? AND u.created_at <= ? AND r.created_at >= u.created_at`,
+    )
+    .all(start, now) as Array<{ delta: number }>;
+  const deltas = latencyRows.map((r) => r.delta).sort((a, b) => a - b);
+  const replied = deltas.length;
+  const latencyMs =
+    replied > 0
+      ? {
+          median: percentile(deltas, 50),
+          avg: Math.round(deltas.reduce((sum, d) => sum + d, 0) / replied),
+          p90: percentile(deltas, 90),
+        }
+      : null;
+
+  // ── 4. Fleet: registrations (spawns) over time + per-agent leaderboard ──
+  const fleetBuckets = bucketStarts.map((s) => ({ start: s, registrations: 0 }));
+  const regRows = db
+    .query(
+      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket, COUNT(*) AS c,
+              SUM(CASE WHEN spawned_by IS NOT NULL THEN 1 ELSE 0 END) AS spawned
+       FROM agents WHERE created_at > ? AND created_at <= ? GROUP BY bucket`,
+    )
+    .all(start, bucketMs, start, now) as Array<{ bucket: number; c: number; spawned: number }>;
+  let registrations = 0;
+  let spawnedByAgent = 0;
+  for (const row of regRows) {
+    const bucket = fleetBuckets[clampIdx(row.bucket)];
+    if (bucket) bucket.registrations += row.c;
+    registrations += row.c;
+    spawnedByAgent += row.spawned ?? 0;
+  }
+  const activeAgents = (
+    db
+      .query(
+        `SELECT COUNT(DISTINCT from_agent) AS c FROM messages
+         WHERE created_at > ? AND created_at <= ? AND from_agent NOT IN ('system','user')`,
+      )
+      .get(start, now) as { c: number }
+  ).c;
+  const leaderboard = db
+    .query(
+      `SELECT m.from_agent AS id, a.label AS label,
+              COUNT(DISTINCT CASE WHEN m.kind = 'session' THEN json_extract(m.payload, '$.session.turnId') END) AS turns,
+              SUM(CASE WHEN m.kind = 'session' AND json_extract(m.payload, '$.session.type') = 'tool' THEN 1 ELSE 0 END) AS toolCalls,
+              SUM(CASE WHEN m.kind != 'session' THEN 1 ELSE 0 END) AS messages
+       FROM messages m LEFT JOIN agents a ON a.id = m.from_agent
+       WHERE m.created_at > ? AND m.created_at <= ? AND m.from_agent NOT IN ('system','user')
+       GROUP BY m.from_agent ORDER BY (toolCalls + messages) DESC LIMIT 10`,
+    )
+    .all(start, now) as Array<{ id: string; label: string | null; turns: number; toolCalls: number; messages: number }>;
 
-  // Busiest-hours heatmap (day-of-week × hour), server-local time.
+  // ── Busiest-hours heatmap (all activity, day-of-week × hour, server-local time) ──
   const heatmap: number[][] = Array.from({ length: 7 }, () => new Array(24).fill(0));
-  const heatRows = getDb()
+  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
@@ -214,7 +373,7 @@ export function getAnalytics(period: AnalyticsPeriod, now: number = Date.now()):
   }
 
   const totalReactions = (
-    getDb()
+    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 <= ?`,
@@ -222,7 +381,19 @@ export function getAnalytics(period: AnalyticsPeriod, now: number = Date.now()):
       .get(start, now) as { c: number }
   ).c;
 
-  return { period, start, now, bucketMs, bucketCount, buckets, categories, heatmap, totalMessages, totalReactions };
+  return {
+    period,
+    start,
+    now,
+    bucketMs,
+    bucketCount,
+    conversation: { buckets: conversationBuckets, totals: conversationTotals, total: conversationTotal },
+    work: { buckets: workBuckets, totals: workTotals, topTools, turns, toolCalls: workTotals.tool },
+    user: { prompts, replied, replyRate: prompts > 0 ? replied / prompts : 0, latencyMs, buckets: userBuckets },
+    fleet: { activeAgents, registrations, spawnedByAgent, buckets: fleetBuckets, leaderboard },
+    heatmap,
+    totalReactions,
+  };
 }
 
 export function getHealth(now: number = Date.now()): HealthReport {

package/src/db/teams.ts

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { getAgent, setAgentTeam } from "./agents.ts";
 import { getDb, ValidationError } from "./connection.ts";
 import { rowToAgent } from "./mappers.ts";
+import { unpromotedBlackboardEntries, type UnpromotedBlackboardSummary } from "./project-entries.ts";
 import type { AgentCard, Team } from "../types";
 
 interface TeamRow {
@@ -273,10 +274,20 @@ export function getTeamOutcomeAggregates(input: { recentLimit?: number } = {}):
   };
 }
 
-export function dissolveTeam(teamId: string, input: TeamDissolveInput = {}): Team {
+export interface TeamDissolveResult {
+  team: Team;
+  /** Active blackboard findings not yet lifted into a project — surfaced (not auto-promoted)
+   * so the operator/agent can decide what graduates to durable project knowledge (#404). */
+  unpromotedBlackboard: UnpromotedBlackboardSummary;
+}
+
+export function dissolveTeam(teamId: string, input: TeamDissolveInput = {}): TeamDissolveResult {
   const existing = getTeam(teamId);
   if (!existing) throw new ValidationError(`team ${teamId} not found`);
   const members = getTeamRoster(teamId);
+  // Capture unpromoted findings BEFORE the row flips to dissolved — the blackboard rows
+  // survive dissolve, but reading the summary here keeps the surface atomic with the event.
+  const unpromotedBlackboard = unpromotedBlackboardEntries(teamId);
   const now = Date.now();
   getDb().query(`
     UPDATE teams
@@ -299,5 +310,5 @@ export function dissolveTeam(teamId: string, input: TeamDissolveInput = {}): Tea
     now,
     teamId,
   );
-  return getTeam(teamId)!;
+  return { team: getTeam(teamId)!, unpromotedBlackboard };
 }

package/src/maintenance.ts

@@ -39,7 +39,7 @@ import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./
 import { requestWorkspaceMerge } from "./workspace-merge";
 import { reconcileLandedWorkspace } from "./branch-landed";
 import { isAwaitingReviewerApproval } from "./reviewer-pipeline";
-import { preparePrCompletionScan } from "./workspace-pr-completion";
+import { preparePrCompletionScan, reconcileLandedPr } from "./workspace-pr-completion";
 import { notifyAgentOffline } from "./agent-lifecycle-events";
 import { workspaceActiveClaim } from "./workspace-claim";
 import { reapOrphanedWorktrees } from "./workspace-orphans";
@@ -655,6 +655,7 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   );
   const flagged: string[] = [], cleared: string[] = [], merged: string[] = [], notifiedStewards: string[] = [];
   const reviewerArmed: string[] = [], reviewerChangesRequested: string[] = [], relayPrMerged: string[] = [], relayPrWaiting: string[] = [];
+  const prRecycled: string[] = [];
 
   for (const ws of candidates) {
     const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
@@ -687,6 +688,12 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
     // branch-landed.ts (#304).
     const landed = p.landed === true || p.prMerged === true;
     if (landed && LANDED_RECONCILE_STATUSES.has(ws.status)) {
+      // A PR-land merges asynchronously on the remote, outside the relay's land path. For a
+      // LIVE owner that means recycle (land-and-continue, #423); for a gone owner, finalize
+      // terminal `merged` (#304). `reconcileLandedPr` owns that split — see workspace-pr-completion.
+      const outcome = reconcileLandedPr(ws, p);
+      if (outcome.kind === "recycle") { emitCommand(outcome.command); prRecycled.push(ws.id); continue; }
+      if (outcome.kind === "wait") { relayPrWaiting.push(`${ws.id}:${outcome.reason}`); continue; }
       reconcileLandedWorkspace(ws, p);
       merged.push(ws.id);
       continue;
@@ -752,7 +759,7 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
     }
   }
 
-  return { scanned: candidates.length, flagged, cleared, merged, notifiedStewards, reviewerArmed, reviewerChangesRequested, relayPrMerged, relayPrWaiting };
+  return { scanned: candidates.length, flagged, cleared, merged, prRecycled, notifiedStewards, reviewerArmed, reviewerChangesRequested, relayPrMerged, relayPrWaiting };
 }
 
 // Deterministic auto-land (Layer 0, #167/#207/#242): land conflict-free ready