agent-relay-server 0.80.0 → 0.82.0

package/src/agent-authz.ts

@@ -0,0 +1,169 @@
+// Agent authorization (#388 users wave 3, #392). THE single home for "which human may see and
+// drive which agent". Two dimensions compose here:
+//
+//   1. ROLE → action  — admin/operator/viewer map onto the EXISTING scope sets (no parallel
+//      authz): an action is allowed iff the role's scopes satisfy the scope that gates it, via
+//      the same `hasScope` used by `requiredComponentScopeFor`. viewer observes, operator
+//      drives, admin manages.
+//   2. VISIBILITY + ownership — private (owner/admin only), shared (all users), team (team
+//      members/admin) decide whether the agent is in view at all.
+//
+// Fail-closed: an unknown role, or a viewer that satisfies neither ownership nor visibility, is
+// denied. Fail-open back-compat: while only the seeded single user exists, every gate passes so
+// the legacy single-operator flow is byte-for-byte unchanged (the gate only bites once a second
+// user is added — `multiUser`).
+import { hasScope, type UserRole } from "agent-relay-sdk";
+import { isMultiUserWorld, resolveAgentOwnership, type AgentOwnership, type AgentVisibility } from "./db/agent-ownership.ts";
+import { getUser } from "./db/users.ts";
+
+/** What a human is trying to do to an agent. Maps 1:1 onto a gating scope (see ACTION_SCOPE). */
+export type AgentAction = "view" | "drive" | "manage";
+
+/** The resolved human behind a request: their relational id, role, and (optional) team set. */
+export interface AgentViewer {
+  userId: string;
+  role: UserRole;
+  /** Teams the user belongs to — consulted only for `team`-visibility agents. */
+  teamIds?: string[];
+}
+
+/**
+ * Scope sets per role, expressed in the SAME vocabulary as `requiredComponentScopeFor`, so the
+ * user-authz gate reuses the existing scope model instead of inventing a parallel one. `admin`
+ * holds `system:admin` (full reach via `hasScope`); operator can drive; viewer is read-only.
+ * Unknown roles map to the empty set → every `hasScope` check is false → fail-closed.
+ */
+const ROLE_SCOPES: Record<UserRole, readonly string[]> = {
+  admin: ["system:admin"],
+  operator: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "command:spawn", "task:read", "task:write", "teams:read", "stats:read"],
+  viewer: ["agent:read", "message:read", "command:read", "task:read", "teams:read", "stats:read"],
+};
+
+/** The scope each agent action is gated by — drive/manage reuse the same scopes the routes do. */
+const ACTION_SCOPE: Record<AgentAction, string> = {
+  view: "agent:read",
+  drive: "agent:write",
+  manage: "system:admin",
+};
+
+/** The scope set a role carries. Unknown role → empty set (fail-closed). */
+export function scopesForRole(role: UserRole | string | undefined): readonly string[] {
+  return ROLE_SCOPES[role as UserRole] ?? [];
+}
+
+/** Does this role's scope set satisfy `scope`? Reuses the SDK `hasScope` (handles `*`/`:*`). */
+export function roleHasScope(role: UserRole | string | undefined, scope: string): boolean {
+  return hasScope(scopesForRole(role), scope);
+}
+
+/** Can this role perform `action` at all (role dimension only — ignores ownership)? */
+export function roleAllowsAction(role: UserRole | string | undefined, action: AgentAction): boolean {
+  return roleHasScope(role, ACTION_SCOPE[action]);
+}
+
+export interface AuthorizeOptions {
+  /** True once more than one user exists — the gate only enforces in a multi-user world.
+   * Single-user (or zero) → every check passes (legacy fail-open back-compat). */
+  multiUser: boolean;
+}
+
+/**
+ * Can `viewer` see an agent with this `ownership`? Visibility/ownership dimension only.
+ * - single-user world → always (fail-open).
+ * - admin → always (admin sees everything it manages).
+ * - private → owner only.
+ * - shared → any user.
+ * - team   → the owning team's members (and admin, handled above).
+ * Unknown/garbage visibility falls through to deny (fail-closed).
+ */
+function viewerCanSeeOwnership(viewer: AgentViewer, ownership: AgentOwnership, opts: AuthorizeOptions): boolean {
+  if (!opts.multiUser) return true;
+  if (viewer.role === "admin") return true;
+  if (viewer.userId === ownership.ownerUserId) return true;
+  const visibility: AgentVisibility = ownership.visibility;
+  if (visibility === "shared") return true;
+  if (visibility === "team") return Boolean(ownership.teamId && viewer.teamIds?.includes(ownership.teamId));
+  // "private" and any unrecognized value → deny.
+  return false;
+}
+
+/**
+ * THE authorization decision: may `viewer` perform `action` on the agent owned per `ownership`?
+ * Both dimensions must pass — the role must permit the action AND the agent must be visible to
+ * the viewer. Fail-open while single-user; fail-closed otherwise.
+ */
+export function authorizeAgentAction(
+  viewer: AgentViewer,
+  ownership: AgentOwnership,
+  action: AgentAction,
+  opts: AuthorizeOptions,
+): boolean {
+  if (!opts.multiUser) return true;
+  if (!roleAllowsAction(viewer.role, action)) return false;
+  return viewerCanSeeOwnership(viewer, ownership, opts);
+}
+
+/** Convenience: can the viewer observe (list/chat-read) this agent? */
+export function canViewerSeeAgent(viewer: AgentViewer, ownership: AgentOwnership, opts: AuthorizeOptions): boolean {
+  return authorizeAgentAction(viewer, ownership, "view", opts);
+}
+
+/** Convenience: can the viewer drive (prompt/interrupt/approve) this agent? */
+export function canViewerDriveAgent(viewer: AgentViewer, ownership: AgentOwnership, opts: AuthorizeOptions): boolean {
+  return authorizeAgentAction(viewer, ownership, "drive", opts);
+}
+
+/**
+ * Filter a list of (agent, ownership) pairs down to what `viewer` may observe. The list-gating
+ * primitive behind "a private agent is invisible to other users".
+ */
+export function filterVisibleAgents<T>(
+  items: ReadonlyArray<{ item: T; ownership: AgentOwnership }>,
+  viewer: AgentViewer,
+  opts: AuthorizeOptions,
+): T[] {
+  return items.filter(({ ownership }) => canViewerSeeAgent(viewer, ownership, opts)).map(({ item }) => item);
+}
+
+// ── DB-wired entry points ────────────────────────────────────────────────────────────────────
+// The above is pure (no DB) so the role/visibility matrix is testable in isolation. These tie it
+// to persistence — resolving the viewer's role from `users`, the agent's ownership row, and the
+// live multi-user switch — and are what the transport/route layer (the request→user wiring lands
+// with the sessions sub-issue) calls.
+
+/** Resolve the live authz options (the single-vs-multi-user switch) from the DB. */
+export function currentAuthorizeOptions(): AuthorizeOptions {
+  return { multiUser: isMultiUserWorld() };
+}
+
+/** Build a viewer from a user id by reading their role off the `users` row. Undefined for an
+ * unknown user (the caller must then fail closed — an unresolvable principal drives nothing). */
+export function resolveViewer(userId: string | undefined, teamIds?: string[]): AgentViewer | undefined {
+  if (!userId) return undefined;
+  const user = getUser(userId);
+  if (!user) return undefined;
+  return { userId: user.id, role: user.role, teamIds };
+}
+
+/**
+ * Wired decision: may the user behind `userId` perform `action` on `agentId`? Resolves the
+ * viewer, the agent's ownership, and the multi-user switch from the DB, then defers to the pure
+ * `authorizeAgentAction`. An unknown user is denied UNLESS the relay is still single-user (legacy
+ * fail-open), matching every other gate here.
+ */
+export function authorizeAgentForUser(userId: string | undefined, agentId: string, action: AgentAction): boolean {
+  const opts = currentAuthorizeOptions();
+  if (!opts.multiUser) return true;
+  const viewer = resolveViewer(userId);
+  if (!viewer) return false;
+  return authorizeAgentAction(viewer, resolveAgentOwnership(agentId), action, opts);
+}
+
+/** Wired list-gate: the subset of `agentIds` the user may observe (drives agent-list visibility). */
+export function visibleAgentIdsForUser(userId: string | undefined, agentIds: readonly string[]): string[] {
+  const opts = currentAuthorizeOptions();
+  if (!opts.multiUser) return [...agentIds];
+  const viewer = resolveViewer(userId);
+  if (!viewer) return [];
+  return agentIds.filter((agentId) => canViewerSeeAgent(viewer, resolveAgentOwnership(agentId), opts));
+}

package/src/agent-ref.ts

@@ -13,6 +13,7 @@
 
 import { STALE_TTL_MS } from "./config";
 import type { AgentCard, Message, TokenConstraints } from "./types";
+import { isReservedAgentId } from "agent-relay-sdk";
 import { targetMatchesAgentIdentity } from "agent-relay-sdk/agent-target";
 
 interface ResolveOptions {
@@ -191,10 +192,9 @@ type SendPlan =
 
 const FANOUT_PREFIXES = ["tag:", "cap:", "capability:", "label:", "team:"];
 const PASSTHROUGH_PREFIXES = ["policy:", "orchestrator:", "pool:"];
-const RESERVED_TARGETS = new Set(["user", "system"]);
 
 function isPseudoAgent(agent: AgentCard): boolean {
-  return agent.id !== "user" && agent.id !== "system" && agent.kind !== "channel" && (agent.meta?.kind as unknown) !== "channel";
+  return !isReservedAgentId(agent.id) && agent.kind !== "channel" && (agent.meta?.kind as unknown) !== "channel";
 }
 
 function describeAgent(agent: AgentCard): string {
@@ -236,7 +236,11 @@ export function planSend(to: string, agents: AgentCard[], opts: ResolveOptions =
       .filter((a) => isAgentOnline(a, now)).map((a) => a.id);
     return { kind: "fanout", to: target, receipt: fanoutReceipt(recipients) };
   }
-  if (RESERVED_TARGETS.has(target) || PASSTHROUGH_PREFIXES.some((p) => target.startsWith(p))) {
+  // Reserved-human (`user`, the whole `user:` namespace) + `system` pass straight through to the
+  // canonical sink — they must NEVER direct-resolve to a registered agent, or a provider squatting
+  // a human address would intercept human-addressed mail (#393). Same predicate the registration
+  // gate and the SDK use, so the namespace can't drift between "what's reserved" and "what routes".
+  if (isReservedAgentId(target) || PASSTHROUGH_PREFIXES.some((p) => target.startsWith(p))) {
     return { kind: "passthrough", to: target, receipt: { delivered: true, expectReply: true, recipients: [target] } };
   }
 

package/src/dashboard-presence.ts

@@ -0,0 +1,91 @@
+// Lightweight dashboard presence for #390: "who is viewing / typing in this agent's chat".
+// Ephemeral, in-memory, TTL-pruned — never persisted. A dashboard announces its presence on
+// an agent thread via a heartbeat; we key each viewer by agentId + clientId so the same
+// browser counts once across tabs, and expire it when the heartbeat stops. This is the
+// human-side complement to the agent-liveness presence in dashboard/lib/display.ts.
+import { canonicalHumanAgentId, isHumanAgentId, LEGACY_HUMAN_AGENT_ID } from "agent-relay-sdk";
+
+/** A heartbeat older than this is considered gone (the client re-announces well within it). */
+export const PRESENCE_TTL_MS = 20_000;
+
+export interface PresenceViewer {
+  /** Canonical human address (`user` / `user:<id>`) of the viewer. */
+  userId: string;
+  /** Stable per-browser id, so multiple tabs of one browser collapse to one viewer. */
+  clientId: string;
+  /** Whether the viewer's composer currently has draft text aimed at this agent. */
+  typing: boolean;
+  /** Epoch ms of the latest heartbeat. */
+  lastSeen: number;
+}
+
+interface PresenceRecord extends PresenceViewer {
+  agentId: string;
+}
+
+// Keyed by agentId + clientId so one browser viewing one agent is a single row.
+const presence = new Map<string, PresenceRecord>();
+
+function key(agentId: string, clientId: string): string {
+  return `${agentId}\t${clientId}`;
+}
+
+function prune(now: number): void {
+  for (const [k, rec] of presence) {
+    if (now - rec.lastSeen > PRESENCE_TTL_MS) presence.delete(k);
+  }
+}
+
+/** Normalize a raw header userId to a canonical human address, defaulting to the legacy sink. */
+function normalizeUserId(raw: string | undefined): string {
+  if (raw && isHumanAgentId(raw)) return canonicalHumanAgentId(raw);
+  return LEGACY_HUMAN_AGENT_ID;
+}
+
+interface AnnounceInput {
+  agentId: string;
+  clientId: string;
+  userId?: string;
+  typing?: boolean;
+  /** Explicit "I navigated away" — removes the viewer without waiting for TTL. */
+  leaving?: boolean;
+  now?: number;
+}
+
+/**
+ * Record (or clear) a dashboard's presence on an agent thread and return the current live
+ * viewers for that agent. Pure given `now`, so it is deterministic to test.
+ */
+export function announcePresence(input: AnnounceInput): PresenceViewer[] {
+  const now = input.now ?? Date.now();
+  prune(now);
+  const k = key(input.agentId, input.clientId);
+  if (input.leaving) {
+    presence.delete(k);
+  } else {
+    presence.set(k, {
+      agentId: input.agentId,
+      clientId: input.clientId,
+      userId: normalizeUserId(input.userId),
+      typing: input.typing === true,
+      lastSeen: now,
+    });
+  }
+  return viewersForAgent(input.agentId, now);
+}
+
+/** Live viewers for an agent, newest heartbeat first. Prunes stale records as a side effect. */
+export function viewersForAgent(agentId: string, now = Date.now()): PresenceViewer[] {
+  prune(now);
+  const out: PresenceViewer[] = [];
+  for (const rec of presence.values()) {
+    if (rec.agentId !== agentId) continue;
+    out.push({ userId: rec.userId, clientId: rec.clientId, typing: rec.typing, lastSeen: rec.lastSeen });
+  }
+  return out.sort((a, b) => b.lastSeen - a.lastSeen);
+}
+
+/** Test-only reset so suites don't leak presence across cases. */
+export function _clearPresence(): void {
+  presence.clear();
+}

package/src/db/agent-ownership.ts

@@ -0,0 +1,168 @@
+// Agent ownership & visibility (#388 users wave 3, #392). The per-agent half of the
+// user-authorization model: who created an agent (`owner_user_id` → users.id) and who else
+// may see it (`visibility`). This module owns persistence ONLY — the role/visibility decision
+// logic lives in `src/agent-authz.ts` (the single authz home that reuses the scope path).
+//
+// Back-compat invariant (#392): pre-existing agents are seeded as owned by the admin
+// `user:default` with `visibility='shared'` on migration, so NOTHING becomes invisible when a
+// second user is added. An agent with no row resolves to the same default (see
+// `resolveAgentOwnership`) — unowned is treated as the admin's shared agent, never an orphan.
+import { DEFAULT_USER_ID } from "agent-relay-sdk";
+import { ValidationError, getDb } from "./connection.ts";
+
+/**
+ * Who may see an agent:
+ * - `private`     — owner (and any admin) only.
+ * - `shared`      — every user, gated by their role (viewer observes, operator drives).
+ * - `team`        — members of the owning `team_id` (and any admin).
+ */
+export type AgentVisibility = "private" | "shared" | "team";
+
+export const AGENT_VISIBILITIES: readonly AgentVisibility[] = ["private", "shared", "team"];
+
+export interface AgentOwnership {
+  agentId: string;
+  ownerUserId: string;
+  visibility: AgentVisibility;
+  teamId: string | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface SetAgentOwnershipInput {
+  agentId: string;
+  ownerUserId: string;
+  visibility?: AgentVisibility;
+  teamId?: string | null;
+}
+
+interface AgentOwnershipRow {
+  agent_id: string;
+  owner_user_id: string;
+  visibility: string;
+  team_id: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+/**
+ * Single DDL home for the `agent_ownership` table (#392). Called from applyMigrations so both
+ * fresh and upgraded DBs gain it (CREATE TABLE IF NOT EXISTS), mirroring `ensureUsersSchema`.
+ * The owner FK points at the keystone `users` table; ON DELETE CASCADE drops the row when the
+ * agent is removed so ownership never outlives its agent.
+ */
+export function ensureAgentOwnershipSchema(): void {
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS agent_ownership (
+      agent_id TEXT PRIMARY KEY REFERENCES agents(id) ON DELETE CASCADE,
+      owner_user_id TEXT NOT NULL REFERENCES users(id),
+      visibility TEXT NOT NULL DEFAULT 'shared',
+      team_id TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_agent_ownership_owner ON agent_ownership(owner_user_id)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_agent_ownership_team ON agent_ownership(team_id)");
+}
+
+function normalizeVisibility(value: string): AgentVisibility {
+  return (AGENT_VISIBILITIES as readonly string[]).includes(value) ? (value as AgentVisibility) : "shared";
+}
+
+function rowToOwnership(row: AgentOwnershipRow): AgentOwnership {
+  return {
+    agentId: row.agent_id,
+    ownerUserId: row.owner_user_id,
+    visibility: normalizeVisibility(row.visibility),
+    teamId: row.team_id,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+export function getAgentOwnership(agentId: string): AgentOwnership | undefined {
+  const row = getDb().query("SELECT * FROM agent_ownership WHERE agent_id = ?").get(agentId) as AgentOwnershipRow | null;
+  return row ? rowToOwnership(row) : undefined;
+}
+
+/**
+ * The ownership of an agent for authorization. A stored row wins; an unowned agent falls back to
+ * the back-compat default — owned by the admin `user:default`, `shared` — so a not-yet-attributed
+ * agent stays visible/drivable exactly as it was pre-#392 instead of vanishing (fail-open for the
+ * legacy world; the multi-user gate in `agent-authz.ts` is what tightens this once it matters).
+ */
+export function resolveAgentOwnership(agentId: string): AgentOwnership {
+  const stored = getAgentOwnership(agentId);
+  if (stored) return stored;
+  const now = Date.now();
+  return { agentId, ownerUserId: DEFAULT_USER_ID, visibility: "shared", teamId: null, createdAt: now, updatedAt: now };
+}
+
+export function listAgentOwnership(): AgentOwnership[] {
+  const rows = getDb().query("SELECT * FROM agent_ownership ORDER BY created_at").all() as AgentOwnershipRow[];
+  return rows.map(rowToOwnership);
+}
+
+/** Upsert an agent's owner/visibility/team. Idempotent on `agent_id`; preserves `created_at`. */
+export function setAgentOwnership(input: SetAgentOwnershipInput): AgentOwnership {
+  if (!input.agentId) throw new ValidationError("agentId is required");
+  if (!input.ownerUserId) throw new ValidationError("ownerUserId is required");
+  const visibility = input.visibility ?? "shared";
+  if (!(AGENT_VISIBILITIES as readonly string[]).includes(visibility)) {
+    throw new ValidationError(`invalid visibility: ${visibility}`);
+  }
+  const now = Date.now();
+  getDb()
+    .query(
+      `INSERT INTO agent_ownership (agent_id, owner_user_id, visibility, team_id, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(agent_id) DO UPDATE SET
+         owner_user_id = excluded.owner_user_id,
+         visibility = excluded.visibility,
+         team_id = excluded.team_id,
+         updated_at = excluded.updated_at`,
+    )
+    .run(input.agentId, input.ownerUserId, visibility, input.teamId ?? null, now, now);
+  const saved = getAgentOwnership(input.agentId);
+  if (!saved) throw new ValidationError(`failed to set ownership for agent ${input.agentId}`);
+  return saved;
+}
+
+export function deleteAgentOwnership(agentId: string): void {
+  getDb().query("DELETE FROM agent_ownership WHERE agent_id = ?").run(agentId);
+}
+
+/**
+ * True once more than one user exists — the switch that turns the authz gate ON. While only the
+ * seeded `user:default` exists, the relay is in its legacy single-operator world and every gate
+ * fail-opens (`agent-authz.ts`). Counted live so adding/removing a user flips enforcement with no
+ * extra state to keep in sync.
+ */
+export function isMultiUserWorld(): boolean {
+  const row = getDb().query("SELECT count(*) AS n FROM users").get() as { n: number } | null;
+  return (row?.n ?? 0) > 1;
+}
+
+/**
+ * One-shot migration backfill (#392 back-compat): every existing real agent that lacks an
+ * ownership row is assigned to the admin `user:default`, `visibility='shared'`. Idempotent
+ * (INSERT … WHERE NOT EXISTS), so it runs safely on every boot. Built-in sinks (`user`,
+ * `system`, and any `user:<id>` human address) are skipped — they are not driveable workers and
+ * must not be owned. This is what guarantees "nothing becomes invisible on upgrade".
+ */
+export function seedDefaultAgentOwnership(): void {
+  const now = Date.now();
+  getDb()
+    .query(
+      `INSERT INTO agent_ownership (agent_id, owner_user_id, visibility, team_id, created_at, updated_at)
+       SELECT a.id, ?, 'shared', NULL, ?, ?
+       FROM agents a
+       WHERE a.id NOT IN (SELECT agent_id FROM agent_ownership)
+         AND a.id != 'user'
+         AND a.id != 'system'
+         AND a.id NOT LIKE 'user:%'
+         AND coalesce(json_extract(a.meta, '$.builtin'), 0) != 1`,
+    )
+    .run(DEFAULT_USER_ID, now, now);
+}

package/src/db/index.ts

@@ -16,6 +16,8 @@ export * from "./messages.ts";
 export * from "./delivery.ts";
 export * from "./message-reads.ts";
 export * from "./inbox.ts";
+export * from "./users.ts";
+export * from "./agent-ownership.ts";
 export * from "./activity.ts";
 export * from "./stats.ts";
 export * from "./orchestrators.ts";

package/src/db/migrations.ts

@@ -15,6 +15,8 @@ import {
 import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
 import { matchAgents } from "../agent-ref";
 import { getDb } from "./connection.ts";
+import { ensureUsersSchema, seedDefaultUser } from "./users.ts";
+import { ensureAgentOwnershipSchema, seedDefaultAgentOwnership } from "./agent-ownership.ts";
 import { ensureContinuationArchiveSearchSchema } from "./continuation-archives.ts";
 import { normalizeReactionEmoji } from "./mappers.ts";
 import { normalizeProviderQuotaAccountKeys } from "./provider-quotas.ts";
@@ -791,6 +793,17 @@ export function applyMigrations(): void {
     )
   `);
 
+  // First-class human users (#388 keystone #393): ensure the table (single DDL home in users.ts)
+  // and seed the admin-level default user mapped to the existing single human. P0 + idempotent —
+  // bare 'user' == user:default resolve to users.id='default' via the SDK resolver; no bytes move.
+  ensureUsersSchema();
+  seedDefaultUser();
+
+  // Agent ownership/visibility table (#392). FK-references both agents and users, so it ensures
+  // AFTER both exist. The backfill (seedDefaultAgentOwnership) runs below, once the built-in
+  // agents are in, so they can be excluded from ownership.
+  ensureAgentOwnershipSchema();
+
   // Built-in agents — registered unconditionally so sends from these ids
   // pass the sendMessage validation. The reaper exempts these by checking
   // meta.builtin (or by id for "user").
@@ -803,6 +816,10 @@ export function applyMigrations(): void {
   builtinStmt.run("user", "User", "user", '["human"]', now, now);
   builtinStmt.run("system", "System", "system", '["system"]', now, now);
 
+  // Back-compat backfill (#392): attribute every pre-existing real agent to the admin
+  // user:default as `shared`, so adding a second user never makes today's agents vanish.
+  seedDefaultAgentOwnership();
+
   // One-shot migration: backfill message_reads from legacy read_by JSON
   // if that column still carries data. Safe to run repeatedly (INSERT OR IGNORE).
   if (colNames.includes("read_by")) {

package/src/db/schema.ts

@@ -462,6 +462,22 @@ export function initDb(path: string = "agent-relay.db"): Database {
     );
     CREATE INDEX IF NOT EXISTS idx_config_history_key ON config_history(namespace, key, version);
 
+    -- Per-user settings (#391, epic #388). The user dimension the global \`config\` table lacks:
+    -- the same \`(namespace, key)\` descriptor address resolves to a per-user value, keyed by the
+    -- resolved \`users.id\` (#393). \`config\` semantics are untouched — \`tier:"user"\` descriptors
+    -- route here; everything else stays in \`config\`. ON DELETE CASCADE so removing a user drops
+    -- their prefs with them.
+    CREATE TABLE IF NOT EXISTS user_settings (
+      user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+      namespace TEXT NOT NULL,
+      key TEXT NOT NULL,
+      value TEXT NOT NULL,
+      version INTEGER NOT NULL DEFAULT 1,
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_by TEXT,
+      PRIMARY KEY (user_id, namespace, key)
+    );
+
     CREATE TABLE IF NOT EXISTS managed_agent_state (
       policy_name TEXT PRIMARY KEY,
       status TEXT NOT NULL,

package/src/db/teams.ts

@@ -131,11 +131,20 @@ export function getTeamRoster(teamId: string): AgentCard[] {
   return rows.map(rowToAgent);
 }
 
-export function countLiveTeamMembers(teamId: string, cutoff: number): number {
+export interface TeamMemberStats {
+  total: number;
+  live: number;
+}
+
+export function getTeamMemberStats(teamId: string, cutoff: number): TeamMemberStats {
   const row = getDb().query(
-    "SELECT count(*) AS n FROM agents WHERE team_id = ? AND status NOT IN ('offline') AND last_seen > ?",
-  ).get(teamId, cutoff) as { n: number };
-  return row.n;
+    "SELECT count(*) AS total, count(CASE WHEN status != 'offline' AND last_seen > ? THEN 1 END) AS live FROM agents WHERE team_id = ?",
+  ).get(cutoff, teamId) as { total: number; live: number };
+  return { total: row.total, live: row.live };
+}
+
+export function countLiveTeamMembers(teamId: string, cutoff: number): number {
+  return getTeamMemberStats(teamId, cutoff).live;
 }
 
 export function getTeamBusyState(teamId: string, cutoff: number): TeamBusyState {