@athenaintel/react 0.21.2 → 0.22.0

package/dist/collab/presence-react.d.ts

@@ -0,0 +1,47 @@
+/**
+ * React bindings for the workspace presence feed.
+ *
+ * `useWorkspacePresence(workspaceId)` opens (and owns) a
+ * `connectWorkspacePresence` handle, resolving auth from the surrounding
+ * `AthenaProvider` (per-viewer bearer when present, API key otherwise), and
+ * re-renders on status/roster changes via `useSyncExternalStore`. Each person
+ * carries a `state` on the intent ladder, recomputed against a clock that
+ * ticks every `tickMs` so `active` decays to `idle` and `away` between
+ * awareness events.
+ *
+ * `useWorkspacePresenceResolver(workspaceId)` returns the batch id→title
+ * resolver bound to the same auth. It is deliberately thin: callers own
+ * caching (TanStack Query is the expected home for it).
+ */
+import { type WorkspacePresenceStatus } from './presence-client';
+import { type WorkspacePresenceResolveRequest, type WorkspacePresenceResolveResponse } from './presence-mint';
+import { type PresenceAgent, type PresenceHuman, type PresenceState } from './presence-slots';
+/** Default cadence for re-deriving each person's intent state. */
+export declare const PRESENCE_DEFAULT_TICK_MS = 10000;
+export interface PresenceHumanWithState extends PresenceHuman {
+    /** Where the person sits on the intent ladder as of the last tick. */
+    state: PresenceState;
+}
+export interface UseWorkspacePresenceOptions {
+    /** `false` closes the feed without unmounting the caller. Default `true`. */
+    enabled?: boolean;
+    /** How often `state` is re-derived from `lastIntentAt`. Default 10 s. */
+    tickMs?: number;
+}
+export interface UseWorkspacePresenceResult {
+    /** `'closed'` while disabled or without a workspace; `'connecting'` until the first mint resolves. */
+    status: WorkspacePresenceStatus;
+    error: Error | null;
+    accessType: 'r' | 'rw' | null;
+    humans: PresenceHumanWithState[];
+    agents: PresenceAgent[];
+    /** Force an early token refresh; resolves immediately when no feed is open. */
+    refreshNow: () => Promise<void>;
+}
+export declare function useWorkspacePresence(workspaceId: string | null, options?: UseWorkspacePresenceOptions): UseWorkspacePresenceResult;
+export type WorkspacePresenceResolver = (request: WorkspacePresenceResolveRequest, signal?: AbortSignal) => Promise<WorkspacePresenceResolveResponse>;
+/**
+ * A stable resolver bound to the provider's auth and the given workspace.
+ * Rejects when called without a workspace; no caching — callers own that.
+ */
+export declare function useWorkspacePresenceResolver(workspaceId: string | null): WorkspacePresenceResolver;

package/dist/collab/presence-react.js

@@ -0,0 +1,114 @@
+import { useState, useRef, useEffect, useMemo, useSyncExternalStore, useCallback } from "react";
+import { useAthenaConfig } from "../provider/AthenaContext.js";
+import { connectWorkspacePresence } from "./presence-client.js";
+import { resolveWorkspacePresence } from "./presence-mint.js";
+import { derivePresenceState } from "./presence-slots.js";
+const PRESENCE_DEFAULT_TICK_MS = 1e4;
+const EMPTY_SNAPSHOT = "init||0";
+const NO_HUMANS = [];
+const NO_AGENTS = [];
+function useWorkspacePresence(workspaceId, options) {
+  const config = useAthenaConfig();
+  const enabled = (options == null ? void 0 : options.enabled) !== false && workspaceId !== null;
+  const tickMs = (options == null ? void 0 : options.tickMs) ?? PRESENCE_DEFAULT_TICK_MS;
+  const [entry, setEntry] = useState(null);
+  const handleRef = useRef(null);
+  useEffect(() => {
+    if (!enabled || workspaceId === null) {
+      setEntry(null);
+      return;
+    }
+    const next = connectWorkspacePresence({
+      workspaceId,
+      auth: {
+        backendUrl: config.backendUrl,
+        apiKey: config.apiKey,
+        token: config.token
+      }
+    });
+    handleRef.current = next;
+    setEntry({ workspaceId, handle: next });
+    return () => {
+      handleRef.current = null;
+      next.destroy();
+    };
+  }, [enabled, workspaceId, config.backendUrl, config.apiKey, config.token]);
+  const handle = enabled && entry !== null && entry.workspaceId === workspaceId ? entry.handle : null;
+  const subscribe = useMemo(() => {
+    return (onStoreChange) => {
+      if (!handle) return () => {
+      };
+      return handle.onChange(onStoreChange);
+    };
+  }, [handle]);
+  useSyncExternalStore(
+    subscribe,
+    () => {
+      if (!handle) return EMPTY_SNAPSHOT;
+      return `${handle.status}|${handle.accessType ?? ""}|${handle.version}`;
+    },
+    () => EMPTY_SNAPSHOT
+  );
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    if (!enabled) return;
+    setNow(Date.now());
+    const timer = setInterval(() => {
+      setNow(Date.now());
+    }, tickMs);
+    return () => {
+      clearInterval(timer);
+    };
+  }, [enabled, tickMs]);
+  const rosterHumans = (handle == null ? void 0 : handle.humans) ?? NO_HUMANS;
+  const humans = useMemo(
+    () => rosterHumans.map((human) => ({
+      ...human,
+      state: derivePresenceState({
+        lastIntentAt: human.lastIntentAt,
+        hidden: human.hidden,
+        manualAway: human.manualAway,
+        now
+      })
+    })),
+    [rosterHumans, now]
+  );
+  const refreshNow = useCallback(() => {
+    var _a;
+    return ((_a = handleRef.current) == null ? void 0 : _a.refreshNow()) ?? Promise.resolve();
+  }, []);
+  return {
+    status: handle ? handle.status : enabled ? "connecting" : "closed",
+    error: (handle == null ? void 0 : handle.error) ?? null,
+    accessType: (handle == null ? void 0 : handle.accessType) ?? null,
+    humans,
+    agents: (handle == null ? void 0 : handle.agents) ?? NO_AGENTS,
+    refreshNow
+  };
+}
+function useWorkspacePresenceResolver(workspaceId) {
+  const config = useAthenaConfig();
+  const { backendUrl, apiKey, token } = config;
+  return useCallback(
+    (request, signal) => {
+      if (workspaceId === null) {
+        return Promise.reject(
+          new Error("[AthenaSDK] useWorkspacePresenceResolver: no workspace selected")
+        );
+      }
+      return resolveWorkspacePresence({
+        auth: { backendUrl, apiKey, token },
+        workspaceId,
+        request,
+        signal
+      });
+    },
+    [workspaceId, backendUrl, apiKey, token]
+  );
+}
+export {
+  PRESENCE_DEFAULT_TICK_MS,
+  useWorkspacePresence,
+  useWorkspacePresenceResolver
+};
+//# sourceMappingURL=presence-react.js.map

package/dist/collab/presence-react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence-react.js","sources":["../../src/collab/presence-react.ts"],"sourcesContent":["/**\n * React bindings for the workspace presence feed.\n *\n * `useWorkspacePresence(workspaceId)` opens (and owns) a\n * `connectWorkspacePresence` handle, resolving auth from the surrounding\n * `AthenaProvider` (per-viewer bearer when present, API key otherwise), and\n * re-renders on status/roster changes via `useSyncExternalStore`. Each person\n * carries a `state` on the intent ladder, recomputed against a clock that\n * ticks every `tickMs` so `active` decays to `idle` and `away` between\n * awareness events.\n *\n * `useWorkspacePresenceResolver(workspaceId)` returns the batch id→title\n * resolver bound to the same auth. It is deliberately thin: callers own\n * caching (TanStack Query is the expected home for it).\n */\n\nimport { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';\nimport { useAthenaConfig } from '../provider/AthenaContext';\nimport {\n  type WorkspacePresenceHandle,\n  type WorkspacePresenceStatus,\n  connectWorkspacePresence,\n} from './presence-client';\nimport {\n  type WorkspacePresenceResolveRequest,\n  type WorkspacePresenceResolveResponse,\n  resolveWorkspacePresence,\n} from './presence-mint';\nimport {\n  type PresenceAgent,\n  type PresenceHuman,\n  type PresenceState,\n  derivePresenceState,\n} from './presence-slots';\n\n/** Default cadence for re-deriving each person's intent state. */\nexport const PRESENCE_DEFAULT_TICK_MS = 10_000;\n\nexport interface PresenceHumanWithState extends PresenceHuman {\n  /** Where the person sits on the intent ladder as of the last tick. */\n  state: PresenceState;\n}\n\nexport interface UseWorkspacePresenceOptions {\n  /** `false` closes the feed without unmounting the caller. Default `true`. */\n  enabled?: boolean;\n  /** How often `state` is re-derived from `lastIntentAt`. Default 10 s. */\n  tickMs?: number;\n}\n\nexport interface UseWorkspacePresenceResult {\n  /** `'closed'` while disabled or without a workspace; `'connecting'` until the first mint resolves. */\n  status: WorkspacePresenceStatus;\n  error: Error | null;\n  accessType: 'r' | 'rw' | null;\n  humans: PresenceHumanWithState[];\n  agents: PresenceAgent[];\n  /** Force an early token refresh; resolves immediately when no feed is open. */\n  refreshNow: () => Promise<void>;\n}\n\nconst EMPTY_SNAPSHOT = 'init||0';\nconst NO_HUMANS: PresenceHuman[] = [];\nconst NO_AGENTS: PresenceAgent[] = [];\n\nexport function useWorkspacePresence(\n  workspaceId: string | null,\n  options?: UseWorkspacePresenceOptions\n): UseWorkspacePresenceResult {\n  const config = useAthenaConfig();\n  const enabled = options?.enabled !== false && workspaceId !== null;\n  const tickMs = options?.tickMs ?? PRESENCE_DEFAULT_TICK_MS;\n  const [entry, setEntry] = useState<{\n    workspaceId: string;\n    handle: WorkspacePresenceHandle;\n  } | null>(null);\n  const handleRef = useRef<WorkspacePresenceHandle | null>(null);\n\n  useEffect(() => {\n    if (!enabled || workspaceId === null) {\n      setEntry(null);\n      return;\n    }\n    const next = connectWorkspacePresence({\n      workspaceId,\n      auth: {\n        backendUrl: config.backendUrl,\n        apiKey: config.apiKey,\n        token: config.token,\n      },\n    });\n    handleRef.current = next;\n    setEntry({ workspaceId, handle: next });\n    return () => {\n      handleRef.current = null;\n      next.destroy();\n    };\n    // Recreate when the target or credentials change; the handle re-mints on\n    // its own schedule otherwise.\n  }, [enabled, workspaceId, config.backendUrl, config.apiKey, config.token]);\n\n  // React renders with the new arguments before the effect above runs, so a\n  // handle opened for a previous workspace, or before the feed was disabled,\n  // still sits in state for that one render. Expose it only while it is the\n  // handle this render asked for; otherwise the closed / connecting empty\n  // result wins, and a disabled feed never leaks a roster.\n  const handle =\n    enabled && entry !== null && entry.workspaceId === workspaceId ? entry.handle : null;\n\n  const subscribe = useMemo(() => {\n    return (onStoreChange: () => void) => {\n      if (!handle) return () => {};\n      return handle.onChange(onStoreChange);\n    };\n  }, [handle]);\n\n  const snapshot = useSyncExternalStore(\n    subscribe,\n    () => {\n      if (!handle) return EMPTY_SNAPSHOT;\n      return `${handle.status}|${handle.accessType ?? ''}|${handle.version}`;\n    },\n    () => EMPTY_SNAPSHOT\n  );\n  void snapshot;\n\n  // The ladder decays with wall-clock time, not with awareness events; a\n  // person who stops typing must drift to idle even when nothing arrives.\n  const [now, setNow] = useState(() => Date.now());\n  useEffect(() => {\n    if (!enabled) return;\n    setNow(Date.now());\n    const timer = setInterval(() => {\n      setNow(Date.now());\n    }, tickMs);\n    return () => {\n      clearInterval(timer);\n    };\n  }, [enabled, tickMs]);\n\n  const rosterHumans = handle?.humans ?? NO_HUMANS;\n  const humans = useMemo(\n    () =>\n      rosterHumans.map((human) => ({\n        ...human,\n        state: derivePresenceState({\n          lastIntentAt: human.lastIntentAt,\n          hidden: human.hidden,\n          manualAway: human.manualAway,\n          now,\n        }),\n      })),\n    [rosterHumans, now]\n  );\n\n  const refreshNow = useCallback(() => handleRef.current?.refreshNow() ?? Promise.resolve(), []);\n\n  return {\n    status: handle ? handle.status : enabled ? 'connecting' : 'closed',\n    error: handle?.error ?? null,\n    accessType: handle?.accessType ?? null,\n    humans,\n    agents: handle?.agents ?? NO_AGENTS,\n    refreshNow,\n  };\n}\n\nexport type WorkspacePresenceResolver = (\n  request: WorkspacePresenceResolveRequest,\n  signal?: AbortSignal\n) => Promise<WorkspacePresenceResolveResponse>;\n\n/**\n * A stable resolver bound to the provider's auth and the given workspace.\n * Rejects when called without a workspace; no caching — callers own that.\n */\nexport function useWorkspacePresenceResolver(\n  workspaceId: string | null\n): WorkspacePresenceResolver {\n  const config = useAthenaConfig();\n  const { backendUrl, apiKey, token } = config;\n  return useCallback<WorkspacePresenceResolver>(\n    (request, signal) => {\n      if (workspaceId === null) {\n        return Promise.reject(\n          new Error('[AthenaSDK] useWorkspacePresenceResolver: no workspace selected')\n        );\n      }\n      return resolveWorkspacePresence({\n        auth: { backendUrl, apiKey, token },\n        workspaceId,\n        request,\n        signal,\n      });\n    },\n    [workspaceId, backendUrl, apiKey, token]\n  );\n}\n"],"names":[],"mappings":"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"}

package/dist/collab/presence-slots.cjs

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const PRESENCE_CONTEXT_TYPE = {
+  ASSET: "asset",
+  SESSION: "session",
+  /** Server-written only: "somewhere in that project", never which document. */
+  PROJECT: "project"
+};
+const MAX_PRESENCE_CONTEXTS_PER_SLOT = 64;
+const MAX_PRESENCE_STRING_CHARS = 512;
+const PRESENCE_ACTIVE_WINDOW_MS = 6e4;
+const PRESENCE_IDLE_WINDOW_MS = 3e5;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cleanString(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  return trimmed.slice(0, MAX_PRESENCE_STRING_CHARS);
+}
+function cleanEpochMs(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return null;
+  return value;
+}
+function cleanContextType(value) {
+  if (value === PRESENCE_CONTEXT_TYPE.ASSET || value === PRESENCE_CONTEXT_TYPE.SESSION || value === PRESENCE_CONTEXT_TYPE.PROJECT) {
+    return value;
+  }
+  return null;
+}
+function cleanStringList(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const item of value) {
+    const cleaned = cleanString(item);
+    if (cleaned === null || out.includes(cleaned)) continue;
+    out.push(cleaned);
+    if (out.length >= MAX_PRESENCE_CONTEXTS_PER_SLOT) break;
+  }
+  return out;
+}
+function parseContext(raw) {
+  if (!isRecord(raw)) return null;
+  const type = cleanContextType(raw.type);
+  const guid = cleanString(raw.guid);
+  if (type === null || guid === null) return null;
+  return {
+    type,
+    guid,
+    locationLabel: cleanString(raw.locationLabel),
+    projects: cleanStringList(raw.projects),
+    coarse: raw.coarse === true,
+    lastAnchorChangeAt: cleanEpochMs(raw.lastAnchorChangeAt)
+  };
+}
+function parseContexts(raw) {
+  if (!Array.isArray(raw)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const contexts = [];
+  for (const item of raw) {
+    const parsed = parseContext(item);
+    if (parsed === null) continue;
+    const key = `${parsed.type}:${parsed.guid}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    contexts.push(parsed);
+    if (contexts.length >= MAX_PRESENCE_CONTEXTS_PER_SLOT) break;
+  }
+  return contexts;
+}
+function parseAgentInitiator(raw) {
+  if (!isRecord(raw)) return null;
+  const initiator = {
+    userId: cleanString(raw.userId),
+    email: cleanString(raw.email),
+    name: cleanString(raw.name)
+  };
+  if (initiator.userId === null && initiator.email === null && initiator.name === null) {
+    return null;
+  }
+  return initiator;
+}
+function parseSlot(raw) {
+  if (!isRecord(raw)) return null;
+  const user = raw.user;
+  if (!isRecord(user)) return null;
+  const email = cleanString(user.email);
+  const userId = cleanString(user.userId) ?? email;
+  if (userId === null) return null;
+  return {
+    kind: user.kind === "agent" ? "agent" : "human",
+    userId,
+    authUserId: cleanString(user.authUserId),
+    name: cleanString(user.name) ?? userId,
+    email,
+    color: cleanString(user.color),
+    avatarUrl: cleanString(user.avatarUrl),
+    agentInitiator: parseAgentInitiator(user.agentInitiator),
+    contexts: parseContexts(raw.activeContexts),
+    hidden: raw.hidden === true,
+    lastIntentAt: cleanEpochMs(raw.lastIntentAt),
+    manualAway: raw.status === "away"
+  };
+}
+function mergeContexts(existing, incoming) {
+  const index = /* @__PURE__ */ new Map();
+  existing.forEach((context, position) => {
+    index.set(`${context.type}:${context.guid}`, position);
+  });
+  for (const context of incoming) {
+    const key = `${context.type}:${context.guid}`;
+    const position = index.get(key);
+    if (position === void 0) {
+      existing.push(context);
+      index.set(key, existing.length - 1);
+      continue;
+    }
+    const prior = existing[position];
+    if (prior && (context.lastAnchorChangeAt ?? 0) > (prior.lastAnchorChangeAt ?? 0)) {
+      existing[position] = context;
+    }
+  }
+}
+function maxIntent(a, b) {
+  if (a === null) return b;
+  if (b === null) return a;
+  return Math.max(a, b);
+}
+function toPresenceContext(context) {
+  return {
+    type: context.type,
+    guid: context.guid,
+    locationLabel: context.locationLabel,
+    projects: context.projects,
+    coarse: context.coarse
+  };
+}
+function byName(a, b) {
+  const names = a.name.localeCompare(b.name);
+  return names !== 0 ? names : a.key.localeCompare(b.key);
+}
+function mergePresenceStates(states) {
+  const humans = /* @__PURE__ */ new Map();
+  const agents = /* @__PURE__ */ new Map();
+  for (const raw of states.values()) {
+    const slot = parseSlot(raw);
+    if (slot === null) continue;
+    if (slot.kind === "agent") {
+      const existing2 = agents.get(slot.userId);
+      if (existing2) {
+        existing2.lastIntentAt = maxIntent(existing2.lastIntentAt, slot.lastIntentAt);
+        existing2.agentInitiator = existing2.agentInitiator ?? slot.agentInitiator;
+        mergeContexts(existing2.contexts, slot.contexts);
+        continue;
+      }
+      agents.set(slot.userId, {
+        key: slot.userId,
+        userId: slot.userId,
+        name: slot.name,
+        agentInitiator: slot.agentInitiator,
+        contexts: [...slot.contexts],
+        lastIntentAt: slot.lastIntentAt
+      });
+      continue;
+    }
+    const key = slot.authUserId ?? slot.userId;
+    const existing = humans.get(key);
+    if (existing) {
+      existing.connections += 1;
+      existing.lastIntentAt = maxIntent(existing.lastIntentAt, slot.lastIntentAt);
+      existing.hidden = existing.hidden && slot.hidden;
+      existing.manualAway = existing.manualAway || slot.manualAway;
+      existing.email = existing.email ?? slot.email;
+      existing.avatarUrl = existing.avatarUrl ?? slot.avatarUrl;
+      existing.color = existing.color ?? slot.color;
+      mergeContexts(existing.contexts, slot.contexts);
+      continue;
+    }
+    humans.set(key, {
+      key,
+      authUserId: slot.authUserId,
+      userId: slot.userId,
+      name: slot.name,
+      email: slot.email,
+      avatarUrl: slot.avatarUrl,
+      color: slot.color,
+      contexts: [...slot.contexts],
+      lastIntentAt: slot.lastIntentAt,
+      hidden: slot.hidden,
+      manualAway: slot.manualAway,
+      connections: 1
+    });
+  }
+  return {
+    humans: [...humans.values()].map((human) => ({ ...human, contexts: human.contexts.map(toPresenceContext) })).sort(byName),
+    agents: [...agents.values()].map((agent) => ({ ...agent, contexts: agent.contexts.map(toPresenceContext) })).sort(byName)
+  };
+}
+function derivePresenceState({
+  lastIntentAt,
+  hidden,
+  manualAway,
+  now
+}) {
+  if (manualAway) return "away";
+  if (lastIntentAt === null) return "idle";
+  const elapsed = Math.max(0, now - lastIntentAt);
+  if (elapsed <= PRESENCE_ACTIVE_WINDOW_MS) return hidden ? "idle" : "active";
+  if (elapsed <= PRESENCE_IDLE_WINDOW_MS) return "idle";
+  return "away";
+}
+exports.MAX_PRESENCE_CONTEXTS_PER_SLOT = MAX_PRESENCE_CONTEXTS_PER_SLOT;
+exports.MAX_PRESENCE_STRING_CHARS = MAX_PRESENCE_STRING_CHARS;
+exports.PRESENCE_ACTIVE_WINDOW_MS = PRESENCE_ACTIVE_WINDOW_MS;
+exports.PRESENCE_CONTEXT_TYPE = PRESENCE_CONTEXT_TYPE;
+exports.PRESENCE_IDLE_WINDOW_MS = PRESENCE_IDLE_WINDOW_MS;
+exports.derivePresenceState = derivePresenceState;
+exports.mergePresenceStates = mergePresenceStates;
+//# sourceMappingURL=presence-slots.cjs.map

package/dist/collab/presence-slots.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence-slots.cjs","sources":["../../src/collab/presence-slots.ts"],"sourcesContent":["/**\n * Pure decoding of workspace awareness slots into typed presence entries.\n *\n * Every connected Olympus tab (and every agent run, published by the backend)\n * holds one slot in the workspace awareness room. Keryx narrows what each\n * recipient receives (a document the viewer may not open collapses into a\n * coarse `project` context, agents with nothing visible are dropped), so the\n * slots seen here are already scoped to the token holder. This module treats\n * every field as untrusted anyway: a slot is JSON a browser published, and a\n * malformed one must be dropped rather than crash the feed or merge every\n * anonymous tab into one phantom person.\n *\n * The shape mirrors Olympus's `WorkspaceAwarenessSlot`\n * (`olympus/src/store/workspaceAwarenessStore.ts`) and the bounds mirror\n * Agora's observer (`agora/agora/services/presence/awareness_slots.py`).\n * No React, no network — the merge and the intent ladder are testable directly.\n */\n\nexport const PRESENCE_CONTEXT_TYPE = {\n  ASSET: 'asset',\n  SESSION: 'session',\n  /** Server-written only: \"somewhere in that project\", never which document. */\n  PROJECT: 'project',\n} as const;\n\nexport type PresenceContextType =\n  (typeof PRESENCE_CONTEXT_TYPE)[keyof typeof PRESENCE_CONTEXT_TYPE];\n\n/** Contexts kept per slot; anything past this is publisher junk. */\nexport const MAX_PRESENCE_CONTEXTS_PER_SLOT = 64;\n/** Characters kept per string field. */\nexport const MAX_PRESENCE_STRING_CHARS = 512;\n\n/**\n * Intent ladder thresholds, mirroring `agora/agora/services/presence/types.py`\n * and `olympus/src/sections/presence-monitor/presence-state.ts`. Readers\n * recompute the state from `lastIntentAt` on every tick so it decays smoothly\n * instead of stepping when a snapshot lands.\n */\nexport const PRESENCE_ACTIVE_WINDOW_MS = 60_000;\nexport const PRESENCE_IDLE_WINDOW_MS = 300_000;\n\nexport type PresenceState = 'active' | 'idle' | 'away';\n\nexport interface PresenceContext {\n  type: PresenceContextType;\n  /** Asset id, session thread id, or project asset id depending on `type`. */\n  guid: string;\n  /** Human-readable location inside the asset (\"Slide 4\", \"Sheet1!B14\"), when the tab reported one. */\n  locationLabel: string | null;\n  /** Server-written: projects containing this document that the viewer may also open. */\n  projects: string[];\n  /** Server-written on `project` contexts: the viewer may not open the underlying document. */\n  coarse: boolean;\n}\n\nexport interface PresenceHuman {\n  /** Identity the person's tabs merge by: the server-attested id when present, else the self-reported one. */\n  key: string;\n  /** Agora user id stamped by Keryx from the publishing socket's token; null on unstamped slots. */\n  authUserId: string | null;\n  /** Self-reported user identifier (the email, for Olympus tabs). */\n  userId: string;\n  name: string;\n  email: string | null;\n  avatarUrl: string | null;\n  color: string | null;\n  /** Union of open contexts across the person's tabs, deduped by type + guid. */\n  contexts: PresenceContext[];\n  /** Most recent self-reported input across the person's tabs (epoch ms, publisher clock); null when none reported. */\n  lastIntentAt: number | null;\n  /** True only when every one of the person's tabs reports itself backgrounded. */\n  hidden: boolean;\n  /** True when any tab carries the manual \"away\" status set in Settings. */\n  manualAway: boolean;\n  /** Number of awareness slots (tabs) merged into this entry. */\n  connections: number;\n}\n\nexport interface PresenceAgent {\n  /** The agent slot's own id (`agent:<run>`); runs never collapse by publisher. */\n  key: string;\n  userId: string;\n  name: string;\n  /** The person the run works for; what a reader shows as \"Athena for …\". */\n  agentInitiator: { userId: string | null; email: string | null; name: string | null } | null;\n  contexts: PresenceContext[];\n  lastIntentAt: number | null;\n}\n\nexport interface PresenceRoster {\n  humans: PresenceHuman[];\n  agents: PresenceAgent[];\n}\n\ninterface ParsedContext extends PresenceContext {\n  /** Publisher-reported ms of the last anchor change; breaks ties when tabs share a context. */\n  lastAnchorChangeAt: number | null;\n}\n\ninterface ParsedSlot {\n  kind: 'human' | 'agent';\n  userId: string;\n  authUserId: string | null;\n  name: string;\n  email: string | null;\n  color: string | null;\n  avatarUrl: string | null;\n  agentInitiator: PresenceAgent['agentInitiator'];\n  contexts: ParsedContext[];\n  hidden: boolean;\n  lastIntentAt: number | null;\n  manualAway: boolean;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/** Accept a non-empty string, trimmed and truncated. Anything else becomes null. */\nfunction cleanString(value: unknown): string | null {\n  if (typeof value !== 'string') return null;\n  const trimmed = value.trim();\n  if (!trimmed) return null;\n  return trimmed.slice(0, MAX_PRESENCE_STRING_CHARS);\n}\n\n/** Accept a plausible epoch-milliseconds number, else null. */\nfunction cleanEpochMs(value: unknown): number | null {\n  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return null;\n  return value;\n}\n\nfunction cleanContextType(value: unknown): PresenceContextType | null {\n  if (\n    value === PRESENCE_CONTEXT_TYPE.ASSET ||\n    value === PRESENCE_CONTEXT_TYPE.SESSION ||\n    value === PRESENCE_CONTEXT_TYPE.PROJECT\n  ) {\n    return value;\n  }\n  return null;\n}\n\nfunction cleanStringList(value: unknown): string[] {\n  if (!Array.isArray(value)) return [];\n  const out: string[] = [];\n  for (const item of value) {\n    const cleaned = cleanString(item);\n    if (cleaned === null || out.includes(cleaned)) continue;\n    out.push(cleaned);\n    if (out.length >= MAX_PRESENCE_CONTEXTS_PER_SLOT) break;\n  }\n  return out;\n}\n\nfunction parseContext(raw: unknown): ParsedContext | null {\n  if (!isRecord(raw)) return null;\n  const type = cleanContextType(raw.type);\n  const guid = cleanString(raw.guid);\n  if (type === null || guid === null) return null;\n  return {\n    type,\n    guid,\n    locationLabel: cleanString(raw.locationLabel),\n    projects: cleanStringList(raw.projects),\n    coarse: raw.coarse === true,\n    lastAnchorChangeAt: cleanEpochMs(raw.lastAnchorChangeAt),\n  };\n}\n\nfunction parseContexts(raw: unknown): ParsedContext[] {\n  if (!Array.isArray(raw)) return [];\n  const seen = new Set<string>();\n  const contexts: ParsedContext[] = [];\n  for (const item of raw) {\n    const parsed = parseContext(item);\n    if (parsed === null) continue;\n    const key = `${parsed.type}:${parsed.guid}`;\n    if (seen.has(key)) continue;\n    seen.add(key);\n    contexts.push(parsed);\n    if (contexts.length >= MAX_PRESENCE_CONTEXTS_PER_SLOT) break;\n  }\n  return contexts;\n}\n\nfunction parseAgentInitiator(raw: unknown): PresenceAgent['agentInitiator'] {\n  if (!isRecord(raw)) return null;\n  const initiator = {\n    userId: cleanString(raw.userId),\n    email: cleanString(raw.email),\n    name: cleanString(raw.name),\n  };\n  if (initiator.userId === null && initiator.email === null && initiator.name === null) {\n    return null;\n  }\n  return initiator;\n}\n\n/**\n * Validate one slot. Returns null for anything that cannot be attributed to a\n * stable identity: a slot with neither `userId` nor `email` would otherwise\n * merge every anonymous tab in the workspace into one phantom participant.\n * A missing or unrecognised `kind` reads as human — an older client is far\n * likelier than an agent, and mislabelling a person would hide them.\n */\nfunction parseSlot(raw: unknown): ParsedSlot | null {\n  if (!isRecord(raw)) return null;\n  const user = raw.user;\n  if (!isRecord(user)) return null;\n  const email = cleanString(user.email);\n  const userId = cleanString(user.userId) ?? email;\n  if (userId === null) return null;\n  return {\n    kind: user.kind === 'agent' ? 'agent' : 'human',\n    userId,\n    authUserId: cleanString(user.authUserId),\n    name: cleanString(user.name) ?? userId,\n    email,\n    color: cleanString(user.color),\n    avatarUrl: cleanString(user.avatarUrl),\n    agentInitiator: parseAgentInitiator(user.agentInitiator),\n    contexts: parseContexts(raw.activeContexts),\n    hidden: raw.hidden === true,\n    lastIntentAt: cleanEpochMs(raw.lastIntentAt),\n    manualAway: raw.status === 'away',\n  };\n}\n\n/**\n * Fold one slot's contexts into an already-seen participant's list, keeping\n * the entry with the most recent anchor activity for a duplicate (type, guid).\n */\nfunction mergeContexts(existing: ParsedContext[], incoming: readonly ParsedContext[]): void {\n  const index = new Map<string, number>();\n  existing.forEach((context, position) => {\n    index.set(`${context.type}:${context.guid}`, position);\n  });\n  for (const context of incoming) {\n    const key = `${context.type}:${context.guid}`;\n    const position = index.get(key);\n    if (position === undefined) {\n      existing.push(context);\n      index.set(key, existing.length - 1);\n      continue;\n    }\n    const prior = existing[position];\n    if (prior && (context.lastAnchorChangeAt ?? 0) > (prior.lastAnchorChangeAt ?? 0)) {\n      existing[position] = context;\n    }\n  }\n}\n\nfunction maxIntent(a: number | null, b: number | null): number | null {\n  if (a === null) return b;\n  if (b === null) return a;\n  return Math.max(a, b);\n}\n\nfunction toPresenceContext(context: ParsedContext): PresenceContext {\n  return {\n    type: context.type,\n    guid: context.guid,\n    locationLabel: context.locationLabel,\n    projects: context.projects,\n    coarse: context.coarse,\n  };\n}\n\ninterface HumanAccumulator extends Omit<PresenceHuman, 'contexts'> {\n  contexts: ParsedContext[];\n}\n\ninterface AgentAccumulator extends Omit<PresenceAgent, 'contexts'> {\n  contexts: ParsedContext[];\n}\n\nfunction byName<T extends { name: string; key: string }>(a: T, b: T): number {\n  const names = a.name.localeCompare(b.name);\n  return names !== 0 ? names : a.key.localeCompare(b.key);\n}\n\n/**\n * Merge the awareness room's slots into one entry per person and one per\n * agent run.\n *\n * Humans merge by the server-attested `authUserId` when Keryx stamped one\n * (a tab that merely *claims* a colleague's `userId` gets its own row, with its\n * real identity on it) and by the self-reported `userId` only for unstamped\n * slots — the same rule as Agora's observer and Olympus's store. A person is\n * as active as their most active tab, backgrounded only when every tab is,\n * and away whenever any tab carries the manual flag. Agents keep their own\n * slot id: every run is published by the same service identity, so merging\n * by publisher would collapse concurrent runs into one.\n */\nexport function mergePresenceStates(states: ReadonlyMap<number, unknown>): PresenceRoster {\n  const humans = new Map<string, HumanAccumulator>();\n  const agents = new Map<string, AgentAccumulator>();\n\n  for (const raw of states.values()) {\n    const slot = parseSlot(raw);\n    if (slot === null) continue;\n\n    if (slot.kind === 'agent') {\n      const existing = agents.get(slot.userId);\n      if (existing) {\n        existing.lastIntentAt = maxIntent(existing.lastIntentAt, slot.lastIntentAt);\n        existing.agentInitiator = existing.agentInitiator ?? slot.agentInitiator;\n        mergeContexts(existing.contexts, slot.contexts);\n        continue;\n      }\n      agents.set(slot.userId, {\n        key: slot.userId,\n        userId: slot.userId,\n        name: slot.name,\n        agentInitiator: slot.agentInitiator,\n        contexts: [...slot.contexts],\n        lastIntentAt: slot.lastIntentAt,\n      });\n      continue;\n    }\n\n    const key = slot.authUserId ?? slot.userId;\n    const existing = humans.get(key);\n    if (existing) {\n      existing.connections += 1;\n      existing.lastIntentAt = maxIntent(existing.lastIntentAt, slot.lastIntentAt);\n      existing.hidden = existing.hidden && slot.hidden;\n      existing.manualAway = existing.manualAway || slot.manualAway;\n      // A person with tabs in two surfaces publishes identity from both;\n      // prefer whichever slot actually carried the optional fields.\n      existing.email = existing.email ?? slot.email;\n      existing.avatarUrl = existing.avatarUrl ?? slot.avatarUrl;\n      existing.color = existing.color ?? slot.color;\n      mergeContexts(existing.contexts, slot.contexts);\n      continue;\n    }\n    humans.set(key, {\n      key,\n      authUserId: slot.authUserId,\n      userId: slot.userId,\n      name: slot.name,\n      email: slot.email,\n      avatarUrl: slot.avatarUrl,\n      color: slot.color,\n      contexts: [...slot.contexts],\n      lastIntentAt: slot.lastIntentAt,\n      hidden: slot.hidden,\n      manualAway: slot.manualAway,\n      connections: 1,\n    });\n  }\n\n  return {\n    humans: [...humans.values()]\n      .map((human) => ({ ...human, contexts: human.contexts.map(toPresenceContext) }))\n      .sort(byName),\n    agents: [...agents.values()]\n      .map((agent) => ({ ...agent, contexts: agent.contexts.map(toPresenceContext) }))\n      .sort(byName),\n  };\n}\n\n/**\n * Where a person sits on the intent ladder right now.\n *\n * The manual \"away\" status overrides the ladder. A person who never reported\n * an input is `idle` rather than `away` — absence of evidence is not evidence\n * of leaving. Every tab backgrounded (`hidden`) caps the result below\n * `active`: whatever they did a moment ago, they are demonstrably not looking\n * at Athena now; it does not force `away`, because alt-tabbing to check\n * something is not leaving. A `lastIntentAt` ahead of `now` (a publisher whose\n * clock runs fast) counts as \"just acted\" rather than a negative elapsed.\n */\nexport function derivePresenceState({\n  lastIntentAt,\n  hidden,\n  manualAway,\n  now,\n}: {\n  lastIntentAt: number | null;\n  hidden: boolean;\n  manualAway: boolean;\n  now: number;\n}): PresenceState {\n  if (manualAway) return 'away';\n  if (lastIntentAt === null) return 'idle';\n  const elapsed = Math.max(0, now - lastIntentAt);\n  if (elapsed <= PRESENCE_ACTIVE_WINDOW_MS) return hidden ? 'idle' : 'active';\n  if (elapsed <= PRESENCE_IDLE_WINDOW_MS) return 'idle';\n  return 'away';\n}\n"],"names":["existing"],"mappings":"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"}

package/dist/collab/presence-slots.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Pure decoding of workspace awareness slots into typed presence entries.
+ *
+ * Every connected Olympus tab (and every agent run, published by the backend)
+ * holds one slot in the workspace awareness room. Keryx narrows what each
+ * recipient receives (a document the viewer may not open collapses into a
+ * coarse `project` context, agents with nothing visible are dropped), so the
+ * slots seen here are already scoped to the token holder. This module treats
+ * every field as untrusted anyway: a slot is JSON a browser published, and a
+ * malformed one must be dropped rather than crash the feed or merge every
+ * anonymous tab into one phantom person.
+ *
+ * The shape mirrors Olympus's `WorkspaceAwarenessSlot`
+ * (`olympus/src/store/workspaceAwarenessStore.ts`) and the bounds mirror
+ * Agora's observer (`agora/agora/services/presence/awareness_slots.py`).
+ * No React, no network — the merge and the intent ladder are testable directly.
+ */
+export declare const PRESENCE_CONTEXT_TYPE: {
+    readonly ASSET: 'asset';
+    readonly SESSION: 'session';
+    /** Server-written only: "somewhere in that project", never which document. */
+    readonly PROJECT: 'project';
+};
+export type PresenceContextType = (typeof PRESENCE_CONTEXT_TYPE)[keyof typeof PRESENCE_CONTEXT_TYPE];
+/** Contexts kept per slot; anything past this is publisher junk. */
+export declare const MAX_PRESENCE_CONTEXTS_PER_SLOT = 64;
+/** Characters kept per string field. */
+export declare const MAX_PRESENCE_STRING_CHARS = 512;
+/**
+ * Intent ladder thresholds, mirroring `agora/agora/services/presence/types.py`
+ * and `olympus/src/sections/presence-monitor/presence-state.ts`. Readers
+ * recompute the state from `lastIntentAt` on every tick so it decays smoothly
+ * instead of stepping when a snapshot lands.
+ */
+export declare const PRESENCE_ACTIVE_WINDOW_MS = 60000;
+export declare const PRESENCE_IDLE_WINDOW_MS = 300000;
+export type PresenceState = 'active' | 'idle' | 'away';
+export interface PresenceContext {
+    type: PresenceContextType;
+    /** Asset id, session thread id, or project asset id depending on `type`. */
+    guid: string;
+    /** Human-readable location inside the asset ("Slide 4", "Sheet1!B14"), when the tab reported one. */
+    locationLabel: string | null;
+    /** Server-written: projects containing this document that the viewer may also open. */
+    projects: string[];
+    /** Server-written on `project` contexts: the viewer may not open the underlying document. */
+    coarse: boolean;
+}
+export interface PresenceHuman {
+    /** Identity the person's tabs merge by: the server-attested id when present, else the self-reported one. */
+    key: string;
+    /** Agora user id stamped by Keryx from the publishing socket's token; null on unstamped slots. */
+    authUserId: string | null;
+    /** Self-reported user identifier (the email, for Olympus tabs). */
+    userId: string;
+    name: string;
+    email: string | null;
+    avatarUrl: string | null;
+    color: string | null;
+    /** Union of open contexts across the person's tabs, deduped by type + guid. */
+    contexts: PresenceContext[];
+    /** Most recent self-reported input across the person's tabs (epoch ms, publisher clock); null when none reported. */
+    lastIntentAt: number | null;
+    /** True only when every one of the person's tabs reports itself backgrounded. */
+    hidden: boolean;
+    /** True when any tab carries the manual "away" status set in Settings. */
+    manualAway: boolean;
+    /** Number of awareness slots (tabs) merged into this entry. */
+    connections: number;
+}
+export interface PresenceAgent {
+    /** The agent slot's own id (`agent:<run>`); runs never collapse by publisher. */
+    key: string;
+    userId: string;
+    name: string;
+    /** The person the run works for; what a reader shows as "Athena for …". */
+    agentInitiator: {
+        userId: string | null;
+        email: string | null;
+        name: string | null;
+    } | null;
+    contexts: PresenceContext[];
+    lastIntentAt: number | null;
+}
+export interface PresenceRoster {
+    humans: PresenceHuman[];
+    agents: PresenceAgent[];
+}
+/**
+ * Merge the awareness room's slots into one entry per person and one per
+ * agent run.
+ *
+ * Humans merge by the server-attested `authUserId` when Keryx stamped one
+ * (a tab that merely *claims* a colleague's `userId` gets its own row, with its
+ * real identity on it) and by the self-reported `userId` only for unstamped
+ * slots — the same rule as Agora's observer and Olympus's store. A person is
+ * as active as their most active tab, backgrounded only when every tab is,
+ * and away whenever any tab carries the manual flag. Agents keep their own
+ * slot id: every run is published by the same service identity, so merging
+ * by publisher would collapse concurrent runs into one.
+ */
+export declare function mergePresenceStates(states: ReadonlyMap<number, unknown>): PresenceRoster;
+/**
+ * Where a person sits on the intent ladder right now.
+ *
+ * The manual "away" status overrides the ladder. A person who never reported
+ * an input is `idle` rather than `away` — absence of evidence is not evidence
+ * of leaving. Every tab backgrounded (`hidden`) caps the result below
+ * `active`: whatever they did a moment ago, they are demonstrably not looking
+ * at Athena now; it does not force `away`, because alt-tabbing to check
+ * something is not leaving. A `lastIntentAt` ahead of `now` (a publisher whose
+ * clock runs fast) counts as "just acted" rather than a negative elapsed.
+ */
+export declare function derivePresenceState({ lastIntentAt, hidden, manualAway, now, }: {
+    lastIntentAt: number | null;
+    hidden: boolean;
+    manualAway: boolean;
+    now: number;
+}): PresenceState;