@agent-native/core 0.85.7 → 0.86.1

package/corpus/core/src/collab/agent-presence.ts

@@ -5,52 +5,82 @@
  * collaborator — it "enters" a document, its edits are visible with
  * durable presence, and it "leaves" when done. Actions call these
  * instead of hand-rolling HTTP awareness calls.
+ *
+ * Presence lingers after the agent finishes editing (default 6s) so viewers
+ * get a moment to see who just changed what — the same way a human
+ * collaborator's cursor doesn't vanish the instant they stop typing. Recent
+ * edits are attributed in the awareness state (`recentEdits`, `lastEditAt`)
+ * so clients can render fading highlights over the edited regions.
+ *
+ * On serverless hosts the linger timer may never fire after the response is
+ * sent; the 30s awareness expiry then removes the entry, so presence degrades
+ * to "up to 30s" instead of leaking.
  */
 
 import { AGENT_CLIENT_ID, DEFAULT_AGENT_IDENTITY } from "./agent-identity.js";
-import { getDocAwareness, type AwarenessEntry } from "./awareness.js";
+import { deleteAwarenessRow, upsertAwarenessRow } from "./awareness-store.js";
+import {
+  emitAwarenessChange,
+  getDocAwareness,
+  type AwarenessEntry,
+} from "./awareness.js";
+import { appendRecentEdit, type RecentEdit } from "./recent-edits.js";
 import { searchAndReplace } from "./ydoc-manager.js";
 
 const HEARTBEAT_INTERVAL = 10_000; // 10 seconds
 
+/** How long agent presence lingers after leave/last edit before clearing. */
+export const AGENT_PRESENCE_LINGER_MS = 6_000;
+
 // docId → heartbeat interval handle
 const _heartbeats = new Map<string, NodeJS.Timeout>();
 // docId → reference count (how many concurrent operations are using this doc)
 const _refCounts = new Map<string, number>();
+// docId → pending linger-removal timer
+const _lingerTimers = new Map<string, NodeJS.Timeout>();
 
-/**
- * Mark the agent as present on a document.
- *
- * Sets an awareness entry for the agent and starts a heartbeat that
- * keeps it alive. If the agent is already present on this doc, just
- * refreshes `lastSeen` without creating a second interval.
- */
-export function agentEnterDocument(
-  docId: string,
-  metadata?: Record<string, unknown>,
-): void {
-  const map = getDocAwareness(docId);
+function cancelLinger(docId: string): void {
+  const timer = _lingerTimers.get(docId);
+  if (timer) {
+    clearTimeout(timer);
+    _lingerTimers.delete(docId);
+  }
+}
 
-  const state = JSON.stringify({
-    user: {
-      name: DEFAULT_AGENT_IDENTITY.name,
-      email: DEFAULT_AGENT_IDENTITY.email,
-      color: DEFAULT_AGENT_IDENTITY.color,
-    },
-    ...metadata,
-  });
+function removeAgentPresence(docId: string): void {
+  cancelLinger(docId);
+  const map = getDocAwareness(docId);
+  map.delete(AGENT_CLIENT_ID);
+  emitAwarenessChange(docId, currentAwarenessStates(map));
+  // Cross-instance removal (serverless) — best-effort, never blocks.
+  void deleteAwarenessRow(docId, AGENT_CLIENT_ID);
 
-  const entry: AwarenessEntry = {
-    clientId: AGENT_CLIENT_ID,
-    state,
-    lastSeen: Date.now(),
-  };
-  map.set(AGENT_CLIENT_ID, entry);
+  const interval = _heartbeats.get(docId);
+  if (interval) {
+    clearInterval(interval);
+    _heartbeats.delete(docId);
+  }
+}
 
-  // Increment reference count
-  _refCounts.set(docId, (_refCounts.get(docId) ?? 0) + 1);
+function scheduleLingerRemoval(docId: string, lingerMs: number): void {
+  cancelLinger(docId);
+  if (lingerMs <= 0) {
+    removeAgentPresence(docId);
+    return;
+  }
+  const timer = setTimeout(() => {
+    _lingerTimers.delete(docId);
+    // A new operation may have re-entered while we waited.
+    if ((_refCounts.get(docId) ?? 0) > 0) return;
+    removeAgentPresence(docId);
+  }, lingerMs);
+  if (typeof timer === "object" && "unref" in timer) {
+    timer.unref();
+  }
+  _lingerTimers.set(docId, timer);
+}
 
-  // Don't create another interval if one already exists
+function ensureHeartbeat(docId: string): void {
   if (_heartbeats.has(docId)) return;
 
   const interval = setInterval(() => {
@@ -58,6 +88,14 @@ export function agentEnterDocument(
     const existing = m.get(AGENT_CLIENT_ID);
     if (existing) {
       existing.lastSeen = Date.now();
+      // Keep the SQL mirror fresh too, or remote-instance pollers would see
+      // the agent expire mid-operation (store throttles unchanged writes).
+      void upsertAwarenessRow(
+        docId,
+        AGENT_CLIENT_ID,
+        existing.state,
+        existing.lastSeen,
+      );
     }
   }, HEARTBEAT_INTERVAL);
 
@@ -69,12 +107,89 @@ export function agentEnterDocument(
   _heartbeats.set(docId, interval);
 }
 
+function currentAwarenessStates(map: Map<number, AwarenessEntry>) {
+  return Array.from(map, ([clientId, entry]) => ({
+    clientId,
+    state: entry.state,
+  }));
+}
+
+function readAgentState(docId: string): Record<string, unknown> {
+  const existing = getDocAwareness(docId).get(AGENT_CLIENT_ID);
+  if (existing) {
+    try {
+      return JSON.parse(existing.state) as Record<string, unknown>;
+    } catch {
+      // Invalid state — fall through to defaults
+    }
+  }
+  return {
+    user: {
+      name: DEFAULT_AGENT_IDENTITY.name,
+      email: DEFAULT_AGENT_IDENTITY.email,
+      color: DEFAULT_AGENT_IDENTITY.color,
+    },
+  };
+}
+
+function writeAgentState(docId: string, state: Record<string, unknown>): void {
+  const entry: AwarenessEntry = {
+    clientId: AGENT_CLIENT_ID,
+    state: JSON.stringify(state),
+    lastSeen: Date.now(),
+  };
+  const map = getDocAwareness(docId);
+  map.set(AGENT_CLIENT_ID, entry);
+  emitAwarenessChange(docId, currentAwarenessStates(map));
+  // Mirror to SQL so pollers on other instances see the agent — an action
+  // often runs in a different serverless invocation than the poll route.
+  void upsertAwarenessRow(docId, AGENT_CLIENT_ID, entry.state, entry.lastSeen);
+}
+
 /**
- * Remove the agent's presence from a document.
+ * Mark the agent as present on a document.
  *
- * Clears the awareness entry and stops the heartbeat.
+ * Sets an awareness entry for the agent and starts a heartbeat that
+ * keeps it alive. If the agent is already present on this doc (including
+ * lingering after a previous edit), refreshes state without creating a
+ * second interval.
  */
-export function agentLeaveDocument(docId: string): void {
+export function agentEnterDocument(
+  docId: string,
+  metadata?: Record<string, unknown>,
+): void {
+  cancelLinger(docId);
+
+  const state = { ...readAgentState(docId), ...metadata };
+  writeAgentState(docId, state);
+
+  // Increment reference count
+  _refCounts.set(docId, (_refCounts.get(docId) ?? 0) + 1);
+
+  ensureHeartbeat(docId);
+}
+
+export interface AgentLeaveOptions {
+  /**
+   * How long presence lingers before the awareness entry clears.
+   * Defaults to {@link AGENT_PRESENCE_LINGER_MS}. Pass 0 to clear
+   * immediately (e.g. when an operation failed before editing anything).
+   */
+  lingerMs?: number;
+}
+
+/**
+ * Release the agent's presence on a document.
+ *
+ * Decrements the reference count; when it reaches zero the awareness entry
+ * lingers for `lingerMs` (default 6s) and is then removed. Viewers see the
+ * agent avatar/highlights for a beat after the edit completes instead of an
+ * instant disappearance.
+ */
+export function agentLeaveDocument(
+  docId: string,
+  options?: AgentLeaveOptions,
+): void {
   const count = (_refCounts.get(docId) ?? 1) - 1;
   if (count > 0) {
     _refCounts.set(docId, count);
@@ -82,14 +197,7 @@ export function agentLeaveDocument(docId: string): void {
   }
   _refCounts.delete(docId);
 
-  const map = getDocAwareness(docId);
-  map.delete(AGENT_CLIENT_ID);
-
-  const interval = _heartbeats.get(docId);
-  if (interval) {
-    clearInterval(interval);
-    _heartbeats.delete(docId);
-  }
+  scheduleLingerRemoval(docId, options?.lingerMs ?? AGENT_PRESENCE_LINGER_MS);
 }
 
 /**
@@ -100,31 +208,52 @@ export function agentUpdateSelection(
   docId: string,
   selection: Record<string, unknown>,
 ): void {
-  const map = getDocAwareness(docId);
-  const existing = map.get(AGENT_CLIENT_ID);
+  const state = { ...readAgentState(docId), ...selection };
+  writeAgentState(docId, state);
+}
 
-  let parsed: Record<string, unknown> = {
-    user: {
-      name: DEFAULT_AGENT_IDENTITY.name,
-      email: DEFAULT_AGENT_IDENTITY.email,
-      color: DEFAULT_AGENT_IDENTITY.color,
-    },
-  };
+export interface AgentTouchOptions {
+  /** Region descriptor + label recorded in the agent's recentEdits ring. */
+  edit?: Omit<RecentEdit, "at"> & { at?: number };
+  /** Extra awareness fields to merge (e.g. `selection`). */
+  metadata?: Record<string, unknown>;
+  /** Linger before auto-clearing when no enter/leave pair is active. */
+  lingerMs?: number;
+}
 
-  if (existing) {
-    try {
-      parsed = JSON.parse(existing.state) as Record<string, unknown>;
-    } catch {
-      // Invalid state — use defaults
-    }
+/**
+ * Record an agent edit on a document without requiring an explicit
+ * enter/leave pair. Used by the collab write paths so ANY agent edit
+ * produces visible presence + lingering attribution automatically.
+ *
+ * - Upserts the agent awareness entry (identity preserved/merged).
+ * - Appends to the `recentEdits` ring and bumps `lastEditAt`.
+ * - When no explicit operation is in flight (refcount 0), (re)schedules a
+ *   linger removal so presence fades out on its own.
+ */
+export function agentTouchDocument(
+  docId: string,
+  options?: AgentTouchOptions,
+): void {
+  cancelLinger(docId);
+
+  const state = { ...readAgentState(docId), ...(options?.metadata ?? {}) };
+  const now = Date.now();
+  if (options?.edit) {
+    const { at, ...rest } = options.edit;
+    state.recentEdits = appendRecentEdit(
+      state.recentEdits as RecentEdit[] | undefined,
+      { ...rest, at: at ?? now },
+    );
   }
+  state.lastEditAt = now;
+  writeAgentState(docId, state);
 
-  const state = JSON.stringify({ ...parsed, ...selection });
-  map.set(AGENT_CLIENT_ID, {
-    clientId: AGENT_CLIENT_ID,
-    state,
-    lastSeen: Date.now(),
-  });
+  ensureHeartbeat(docId);
+
+  if ((_refCounts.get(docId) ?? 0) === 0) {
+    scheduleLingerRemoval(docId, options?.lingerMs ?? AGENT_PRESENCE_LINGER_MS);
+  }
 }
 
 /**

package/corpus/core/src/collab/awareness.ts

@@ -15,7 +15,13 @@ import { EventEmitter } from "node:events";
 import { defineEventHandler, setResponseStatus, getRouterParam } from "h3";
 import type { H3Event } from "h3";
 
+import { getSession } from "../server/auth.js";
 import { readBody } from "../server/h3-helpers.js";
+import {
+  deleteAwarenessRow,
+  loadAwarenessRows,
+  upsertAwarenessRow,
+} from "./awareness-store.js";
 
 const AWARENESS_TIMEOUT = 30_000; // 30 seconds
 
@@ -42,28 +48,58 @@ export interface AwarenessChangeEvent {
   owner?: string;
   /** Org ID for org-scoped delivery. */
   orgId?: string;
+  /** Shareable resource type this awareness event belongs to, when known. */
+  resourceType?: string;
+  /** Shareable resource id this awareness event belongs to, when known. */
+  resourceId?: string;
+}
+
+export interface AwarenessScope {
+  owner?: string;
+  orgId?: string;
+  resourceType?: string;
+  resourceId?: string;
 }
 
 const _awarenessEmitter = new EventEmitter();
 _awarenessEmitter.setMaxListeners(0);
 
+const _awarenessScopes = new Map<string, AwarenessScope>();
+
 export function getAwarenessEmitter(): EventEmitter {
   return _awarenessEmitter;
 }
 
+export function rememberAwarenessScope(
+  docId: string,
+  scope: AwarenessScope | undefined,
+): void {
+  if (!scope) return;
+  const next = { ...(_awarenessScopes.get(docId) ?? {}), ...scope };
+  if (!next.owner && !next.orgId && !next.resourceType && !next.resourceId) {
+    return;
+  }
+  _awarenessScopes.set(docId, next);
+}
+
 export function emitAwarenessChange(
   docId: string,
   states: Array<{ clientId: number; state: string }>,
-  owner?: string,
-  orgId?: string,
+  scope?: AwarenessScope,
 ): void {
+  rememberAwarenessScope(docId, scope);
+  const resolvedScope = _awarenessScopes.get(docId) ?? {};
   const event: AwarenessChangeEvent = {
     source: "awareness",
     type: "awareness-change",
     docId,
     states,
-    ...(owner && { owner }),
-    ...(orgId && { orgId }),
+    ...(resolvedScope.owner && { owner: resolvedScope.owner }),
+    ...(resolvedScope.orgId && { orgId: resolvedScope.orgId }),
+    ...(resolvedScope.resourceType && {
+      resourceType: resolvedScope.resourceType,
+    }),
+    ...(resolvedScope.resourceId && { resourceId: resolvedScope.resourceId }),
   };
   _awarenessEmitter.emit(AWARENESS_CHANGE_EVENT, event);
 }
@@ -97,6 +133,25 @@ function pruneIfEmpty(docId: string, map: Map<number, AwarenessEntry>): void {
   }
 }
 
+/**
+ * Merge SQL-mirrored awareness rows (written by other server instances —
+ * or by an agent action running in its own serverless invocation) into the
+ * in-memory map, newest lastSeen wins. Degrades to memory-only when the DB
+ * is unavailable.
+ */
+async function mergeStoredAwareness(
+  docId: string,
+  map: Map<number, AwarenessEntry>,
+): Promise<void> {
+  const rows = await loadAwarenessRows(docId);
+  for (const row of rows) {
+    const existing = map.get(row.clientId);
+    if (!existing || row.lastSeen > existing.lastSeen) {
+      map.set(row.clientId, row);
+    }
+  }
+}
+
 /**
  * POST /_agent-native/collab/:docId/awareness
  *
@@ -111,6 +166,10 @@ export const postAwareness = defineEventHandler(async (event: H3Event) => {
     setResponseStatus(event, 400);
     return { error: "docId required" };
   }
+  const session = await getSession(event).catch(() => null);
+  const contextScope = (
+    event.context as { _collabAwarenessScope?: AwarenessScope } | undefined
+  )?._collabAwarenessScope;
 
   const body = await readBody(event);
   const { clientId, state } = body as {
@@ -129,11 +188,21 @@ export const postAwareness = defineEventHandler(async (event: H3Event) => {
 
   if (state === null) {
     map.delete(clientId);
+    // Best-effort cross-instance removal (never blocks the response).
+    void deleteAwarenessRow(docId, clientId);
   } else {
     // Store this client's state
-    map.set(clientId, { clientId, state, lastSeen: Date.now() });
+    const entry = { clientId, state, lastSeen: Date.now() };
+    map.set(clientId, entry);
+    // Mirror to SQL so other instances (and serverless action invocations)
+    // see this participant. Throttled internally; never throws.
+    void upsertAwarenessRow(docId, clientId, state, entry.lastSeen);
   }
 
+  // Pull in participants known to other instances (multi-instance serverless)
+  // before building the response, so every poller sees the full set.
+  await mergeStoredAwareness(docId, map);
+
   // Clean expired entries, then prune the outer-map entry if it becomes empty.
   // Without pruning, a deployment with many transient docIds (e.g. one per
   // session) would grow _awarenessMap without bound.
@@ -154,7 +223,14 @@ export const postAwareness = defineEventHandler(async (event: H3Event) => {
 
   // Fast-path: push the updated state set to SSE-connected peers so they
   // don't have to wait for the next poll cycle for cursor/selection updates.
-  emitAwarenessChange(docId, allStates);
+  emitAwarenessChange(
+    docId,
+    allStates,
+    contextScope ?? {
+      ...(session?.email ? { owner: session.email } : {}),
+      ...(session?.orgId ? { orgId: session.orgId } : {}),
+    },
+  );
 
   return { states: otherStates };
 });
@@ -172,6 +248,7 @@ export const getActiveUsers = defineEventHandler(async (event: H3Event) => {
   }
 
   const map = getDocAwareness(docId);
+  await mergeStoredAwareness(docId, map);
   cleanExpired(map);
   pruneIfEmpty(docId, map);