@abloatai/humans 0.61.0 → 0.62.0

package/src/react/AbloProvider.tsx

@@ -12,7 +12,7 @@ import {
 } from 'react';
 import type { Schema, SchemaRecord } from '@abloatai/transaction/schema/schema';
 import type { AbloClient as Ablo } from '../client.js';
-import type { Peer } from '@abloatai/transaction/types/streams';
+import type { PresenceSession } from '@abloatai/transaction/presence';
 import type { GroupScope } from '../local/sync/scopeGroups.js';
 import { resolveScopeGroups } from '../local/sync/scopeGroups.js';
 import { SyncContext, type SyncStoreContract } from './context.js';
@@ -20,6 +20,7 @@ import { AbloInternalContext, type AbloInternalContextValue } from './internalCo
 import { AbloValidationError } from '@abloatai/transaction/errors';
 import { useSyncStatus } from './useSyncStatus.js';
 import { DefaultFallback } from './DefaultFallback.js';
+import { presenceOfClient } from '../presence/index.js';
 
 /**
  * Ablo umbrella provider — owns the sync engine, multiplayer, and
@@ -380,12 +381,12 @@ function BootstrapGate({
 }
 
 
-const EMPTY_PRESENCE: readonly Peer[] = Object.freeze([]);
+const EMPTY_PRESENCE: readonly PresenceSession[] = Object.freeze([]);
 
 export type { GroupScope };
 
 /**
- * Read-only presence: the OTHER participants currently visible to this
+ * Read-only presence: the other sessions currently visible to this
  * connection, bridged to React. This is a pure reader of the engine's
  * already-flowing presence stream; it does not mutate connection groups.
  *
@@ -403,7 +404,7 @@ export type { GroupScope };
  * const alone = !peers.some((p) => p.participantKind === 'user');
  * ```
  */
-export function usePeers(scope?: GroupScope): readonly Peer[] {
+export function usePeers(scope?: GroupScope): readonly PresenceSession[] {
   const ctx = useContext(AbloInternalContext);
   const engine = ctx?.engine ?? null;
 
@@ -414,19 +415,23 @@ export function usePeers(scope?: GroupScope): readonly Peer[] {
   );
   const groups = useMemo(() => JSON.parse(scopeKey) as string[], [scopeKey]);
 
-  const [peers, setPeers] = useState<readonly Peer[]>(EMPTY_PRESENCE);
+  const [peers, setPeers] = useState<readonly PresenceSession[]>(EMPTY_PRESENCE);
 
   useEffect(() => {
     if (!engine) {
       setPeers(EMPTY_PRESENCE);
       return;
     }
-    const presence = engine.presence;
-    const compute = (): readonly Peer[] =>
+    const presence = presenceOfClient(engine);
+    const compute = (): readonly PresenceSession[] =>
       groups.length === 0
         ? presence.others
-        : presence.others.filter((p) =>
-            p.syncGroups.some((g) => groups.includes(g)),
+        : presence.others.filter((session) =>
+            session.activities.some(({ target }) =>
+              target.id !== undefined && groups.includes(
+                `${target.model.toLowerCase()}:${target.id}`,
+              ),
+            ),
           );
     // Plain useState + onChange — presence changes on connect/disconnect/activity
     // only (never on cursor traffic, a separate channel), so this fires

package/src/surface.ts

@@ -37,6 +37,7 @@ export const PUBLIC_MODEL_VERBS = [
   'list',
   'listAll',
   'local',
+  'presence',
   'create',
   'update',
   'delete',

package/dist/presenceStream.d.ts

@@ -1,69 +0,0 @@
-/**
- * Creates a {@link PresenceStream} over a live sync connection. Presence is the
- * lightweight, ephemeral "who's here and what are they doing" view: each
- * participant broadcasts a status and an activity, and sees everyone else's.
- * The stream is built directly on the sync WebSocket and adds no second
- * connection. It is the sibling of {@link createClaimStream}, which reuses the
- * same presence frames.
- *
- * There are two ways to construct it:
- *
- *   1. Direct — pass an already-open `transport`, for example an agent worker
- *      or a test.
- *   2. Deferred — construct without a transport and call `attach(transport)`
- *      once the connection is ready. The returned stream object is stable from
- *      construction, so callers can hold the reference and let attachment
- *      happen later.
- *
- * Wire frames:
- *   • Outbound `presence_update` — `{ status, activity? }`. The server stamps
- *       `userId`, `kind`, `timestamp`, and `isAgent`, then broadcasts to the
- *       other participants on the same sync groups.
- *   • Inbound — the same frame, with `kind` one of `enter`, `update`, or
- *       `leave`.
- */
-import type { WsTransport } from '@abloatai/transaction/transport/websocket';
-import type { PresenceStream } from '@abloatai/transaction/types/streams';
-import type { ParticipantKind } from '@abloatai/transaction/types/participant';
-/**
- * The wire capability the presence stream actually uses: subscribe to typed
- * inbound frames, check liveness, and send outbound frames. The duplex
- * `WsTransport` satisfies it — the same port shape the claim stream depends
- * on — so the stream can attach to whatever connection the host built,
- * without naming the engine's subclass.
- */
-export type PresenceTransport = Pick<WsTransport, 'subscribe' | 'isConnected' | 'send'>;
-export interface PresenceStreamConfig {
-    /** Identity used to filter our own echoed frames out of `others`. */
-    participantId: string;
-    /** Optional human label for the self entry. */
-    label?: string;
-    /** Sync groups the participant is broadcasting on. Used for the
-     *  initial `self` entry and for `othersIn(...)` filtering. */
-    syncGroups: readonly string[];
-    /** Marks `self` as an agent. Server is the source of truth for
-     *  peers' `isAgent`, but `self` is local — caller decides. */
-    isAgent?: boolean;
-}
-/** PresenceStream extended with engine-lifecycle hooks. */
-export interface AttachablePresenceStream extends PresenceStream {
-    /** Wire the stream to a now-ready transport. Calls before this are
-     *  buffered (self mutations only — no wire send). Idempotent. */
-    attach(transport: PresenceTransport): void;
-    /**
-     * Seeds the participant identity once the host resolves it. The stream can
-     * be built before identity is known — a hosted client learns who it is
-     * from its credential's scope during connect — and until then the
-     * construction-time values (possibly empty) would leave the `self` entry
-     * blank and let the participant's own echoed frames into `others`. Updates
-     * the `self` entry in place, so held references see the resolved identity.
-     */
-    setParticipant(participant: {
-        id: string;
-        kind?: ParticipantKind;
-        syncGroups?: readonly string[];
-    }): void;
-    /** Tear down listeners. Stream object stays usable as a no-op. */
-    dispose(): void;
-}
-export declare function createPresenceStream(config: PresenceStreamConfig, transport?: PresenceTransport | null): AttachablePresenceStream;

package/dist/presenceStream.js

@@ -1,200 +0,0 @@
-/**
- * Creates a {@link PresenceStream} over a live sync connection. Presence is the
- * lightweight, ephemeral "who's here and what are they doing" view: each
- * participant broadcasts a status and an activity, and sees everyone else's.
- * The stream is built directly on the sync WebSocket and adds no second
- * connection. It is the sibling of {@link createClaimStream}, which reuses the
- * same presence frames.
- *
- * There are two ways to construct it:
- *
- *   1. Direct — pass an already-open `transport`, for example an agent worker
- *      or a test.
- *   2. Deferred — construct without a transport and call `attach(transport)`
- *      once the connection is ready. The returned stream object is stable from
- *      construction, so callers can hold the reference and let attachment
- *      happen later.
- *
- * Wire frames:
- *   • Outbound `presence_update` — `{ status, activity? }`. The server stamps
- *       `userId`, `kind`, `timestamp`, and `isAgent`, then broadcasts to the
- *       other participants on the same sync groups.
- *   • Inbound — the same frame, with `kind` one of `enter`, `update`, or
- *       `leave`.
- */
-import { asyncIteratorFrom } from '@abloatai/transaction/utils/asyncIterator';
-import { participantKindFromWire } from '@abloatai/transaction/coordination/schema';
-import { isTargetTuple, subTarget, wireTarget } from '@abloatai/transaction/coordination';
-export function createPresenceStream(config, transport = null) {
-    const { label, syncGroups, isAgent = false } = config;
-    // Mutable: the host seeds the resolved identity via `setParticipant` once
-    // it is known; the own-echo filter always reads the current value.
-    let participantId = config.participantId;
-    // ── Self ─────────────────────────────────────────────────────────
-    const self = {
-        participantKind: isAgent ? 'agent' : 'user',
-        participantId,
-        label,
-        syncGroups: [...syncGroups],
-        activity: { entityType: 'Unknown', entityId: '', action: 'idle' },
-        lastActive: new Date().toISOString(),
-    };
-    // ── Others ───────────────────────────────────────────────────────
-    const othersById = new Map();
-    let othersSnapshot = Object.freeze([]);
-    const listeners = new Set();
-    const notifyListeners = () => {
-        othersSnapshot = Object.freeze(Array.from(othersById.values()));
-        for (const l of listeners) {
-            try {
-                l();
-            }
-            catch {
-                /* one bad listener doesn't break the others */
-            }
-        }
-    };
-    // ── Wire wiring ──────────────────────────────────────────────────
-    let attached = null;
-    const unsubs = [];
-    function attach(t) {
-        if (attached)
-            return; // idempotent
-        attached = t;
-        // Reconnect: clear roster (Hub sends fresh snapshot), re-announce
-        // own activity (peers don't auto-learn about us across reconnects).
-        unsubs.push(t.subscribe('connected', () => {
-            if (othersById.size > 0) {
-                othersById.clear();
-                othersSnapshot = Object.freeze([]);
-                notifyListeners();
-            }
-            if (self.activity.entityId)
-                sendUpdate(self.activity);
-        }));
-        // Inbound presence frames arrive in the wire vocabulary
-        // (userId / isAgent / timestamp); translate them into the shape this
-        // stream exposes (participantId / participantKind / lastActive).
-        unsubs.push(t.subscribe('presence_update', (event) => {
-            if (event.userId === participantId)
-                return; // own echo
-            if (!event.userId)
-                return;
-            switch (event.kind) {
-                case 'leave':
-                    if (othersById.delete(event.userId))
-                        notifyListeners();
-                    return;
-                // No `undefined` arm: every site that builds a presence frame stamps
-                // `kind`, and the schema now says so, so an unlabelled frame is not a
-                // shape the transport can hand us.
-                case 'enter':
-                case 'update': {
-                    const entry = {
-                        participantKind: participantKindFromWire(event.participantKind, event.isAgent),
-                        participantId: event.userId,
-                        syncGroups: event.syncGroups ?? [],
-                        activity: event.activity
-                            ? {
-                                ...wireTarget(event.activity),
-                                ...subTarget(event.activity),
-                                action: event.activity.action,
-                                ...(event.activity.detail !== undefined
-                                    ? { detail: event.activity.detail }
-                                    : {}),
-                            }
-                            : { entityType: 'Unknown', entityId: '', action: event.status },
-                        lastActive: event.timestamp
-                            ? new Date(event.timestamp).toISOString()
-                            : new Date().toISOString(),
-                    };
-                    othersById.set(event.userId, entry);
-                    notifyListeners();
-                    return;
-                }
-            }
-        }));
-        // If self was already mutated before attach, broadcast it now.
-        if (self.activity.entityId)
-            sendUpdate(self.activity);
-    }
-    if (transport)
-        attach(transport);
-    // ── Outbound ────────────────────────────────────────────────────
-    // Do not include `isAgent` in the payload. The server derives it
-    // authoritatively from the connection's identity, and letting a client
-    // self-declare it once caused human sessions to broadcast as agents to peers.
-    function sendUpdate(activity) {
-        if (!attached?.isConnected())
-            return; // no-op until connected
-        attached.send({
-            type: 'presence_update',
-            payload: { status: 'online', activity },
-        });
-    }
-    function doUpdate(activity) {
-        self.activity = activity;
-        self.lastActive = new Date().toISOString();
-        sendUpdate(activity);
-    }
-    function resolveTarget(target) {
-        if (isTargetTuple(target)) {
-            return { entityType: target[0], entityId: target[1], action: 'unknown' };
-        }
-        return {
-            ...wireTarget(target),
-            ...subTarget(target),
-            action: 'unknown',
-        };
-    }
-    const withVerb = (action) => (target, detail) => {
-        doUpdate({ ...resolveTarget(target), action, detail });
-    };
-    return {
-        self,
-        update: doUpdate,
-        editing: withVerb('editing'),
-        reading: withVerb('reading'),
-        viewing: withVerb('viewing'),
-        idle: () => {
-            doUpdate({ entityType: 'Unknown', entityId: '', action: 'idle' });
-        },
-        get others() {
-            return othersSnapshot;
-        },
-        othersIn: (syncGroup) => othersSnapshot.filter((e) => e.syncGroups.includes(syncGroup)),
-        onChange: (listener) => {
-            listeners.add(listener);
-            return () => {
-                listeners.delete(listener);
-            };
-        },
-        [Symbol.asyncIterator]() {
-            return asyncIteratorFrom((onChange) => {
-                listeners.add(onChange);
-                return () => {
-                    listeners.delete(onChange);
-                };
-            }, () => othersSnapshot);
-        },
-        attach,
-        setParticipant(participant) {
-            participantId = participant.id;
-            const writable = self;
-            writable.participantId = participant.id;
-            if (participant.kind)
-                writable.participantKind = participant.kind;
-            if (participant.syncGroups)
-                writable.syncGroups = [...participant.syncGroups];
-        },
-        dispose() {
-            for (const off of unsubs)
-                off();
-            unsubs.length = 0;
-            listeners.clear();
-            othersById.clear();
-            othersSnapshot = Object.freeze([]);
-            attached = null;
-        },
-    };
-}

package/src/presenceStream.ts

@@ -1,279 +0,0 @@
-/**
- * Creates a {@link PresenceStream} over a live sync connection. Presence is the
- * lightweight, ephemeral "who's here and what are they doing" view: each
- * participant broadcasts a status and an activity, and sees everyone else's.
- * The stream is built directly on the sync WebSocket and adds no second
- * connection. It is the sibling of {@link createClaimStream}, which reuses the
- * same presence frames.
- *
- * There are two ways to construct it:
- *
- *   1. Direct — pass an already-open `transport`, for example an agent worker
- *      or a test.
- *   2. Deferred — construct without a transport and call `attach(transport)`
- *      once the connection is ready. The returned stream object is stable from
- *      construction, so callers can hold the reference and let attachment
- *      happen later.
- *
- * Wire frames:
- *   • Outbound `presence_update` — `{ status, activity? }`. The server stamps
- *       `userId`, `kind`, `timestamp`, and `isAgent`, then broadcasts to the
- *       other participants on the same sync groups.
- *   • Inbound — the same frame, with `kind` one of `enter`, `update`, or
- *       `leave`.
- */
-
-import type { WsTransport } from '@abloatai/transaction/transport/websocket';
-import type { PresenceUpdate } from '@abloatai/transaction/transport/websocket';
-import type {
-  Activity,
-  Peer,
-  PresenceStream,
-  PresenceTarget,
-} from '@abloatai/transaction/types/streams';
-
-import { asyncIteratorFrom } from '@abloatai/transaction/utils/asyncIterator';
-import { participantKindFromWire } from '@abloatai/transaction/coordination/schema';
-import { isTargetTuple, subTarget, wireTarget } from '@abloatai/transaction/coordination';
-import type { ParticipantKind } from '@abloatai/transaction/types/participant';
-
-/**
- * The wire capability the presence stream actually uses: subscribe to typed
- * inbound frames, check liveness, and send outbound frames. The duplex
- * `WsTransport` satisfies it — the same port shape the claim stream depends
- * on — so the stream can attach to whatever connection the host built,
- * without naming the engine's subclass.
- */
-export type PresenceTransport = Pick<WsTransport, 'subscribe' | 'isConnected' | 'send'>;
-
-export interface PresenceStreamConfig {
-  /** Identity used to filter our own echoed frames out of `others`. */
-  participantId: string;
-  /** Optional human label for the self entry. */
-  label?: string;
-  /** Sync groups the participant is broadcasting on. Used for the
-   *  initial `self` entry and for `othersIn(...)` filtering. */
-  syncGroups: readonly string[];
-  /** Marks `self` as an agent. Server is the source of truth for
-   *  peers' `isAgent`, but `self` is local — caller decides. */
-  isAgent?: boolean;
-}
-
-/** PresenceStream extended with engine-lifecycle hooks. */
-export interface AttachablePresenceStream extends PresenceStream {
-  /** Wire the stream to a now-ready transport. Calls before this are
-   *  buffered (self mutations only — no wire send). Idempotent. */
-  attach(transport: PresenceTransport): void;
-  /**
-   * Seeds the participant identity once the host resolves it. The stream can
-   * be built before identity is known — a hosted client learns who it is
-   * from its credential's scope during connect — and until then the
-   * construction-time values (possibly empty) would leave the `self` entry
-   * blank and let the participant's own echoed frames into `others`. Updates
-   * the `self` entry in place, so held references see the resolved identity.
-   */
-  setParticipant(participant: {
-    id: string;
-    kind?: ParticipantKind;
-    syncGroups?: readonly string[];
-  }): void;
-  /** Tear down listeners. Stream object stays usable as a no-op. */
-  dispose(): void;
-}
-
-export function createPresenceStream(
-  config: PresenceStreamConfig,
-  transport: PresenceTransport | null = null,
-): AttachablePresenceStream {
-  const { label, syncGroups, isAgent = false } = config;
-  // Mutable: the host seeds the resolved identity via `setParticipant` once
-  // it is known; the own-echo filter always reads the current value.
-  let participantId = config.participantId;
-
-  // ── Self ─────────────────────────────────────────────────────────
-  const self: Peer = {
-    participantKind: isAgent ? 'agent' : 'user',
-    participantId,
-    label,
-    syncGroups: [...syncGroups],
-    activity: { entityType: 'Unknown', entityId: '', action: 'idle' },
-    lastActive: new Date().toISOString(),
-  };
-
-  // ── Others ───────────────────────────────────────────────────────
-  const othersById = new Map<string, Peer>();
-  let othersSnapshot: readonly Peer[] = Object.freeze([]);
-  const listeners = new Set<() => void>();
-
-  const notifyListeners = () => {
-    othersSnapshot = Object.freeze(Array.from(othersById.values()));
-    for (const l of listeners) {
-      try {
-        l();
-      } catch {
-        /* one bad listener doesn't break the others */
-      }
-    }
-  };
-
-  // ── Wire wiring ──────────────────────────────────────────────────
-  let attached: PresenceTransport | null = null;
-  const unsubs: (() => void)[] = [];
-
-  function attach(t: PresenceTransport): void {
-    if (attached) return; // idempotent
-    attached = t;
-
-    // Reconnect: clear roster (Hub sends fresh snapshot), re-announce
-    // own activity (peers don't auto-learn about us across reconnects).
-    unsubs.push(
-      t.subscribe('connected', () => {
-        if (othersById.size > 0) {
-          othersById.clear();
-          othersSnapshot = Object.freeze([]);
-          notifyListeners();
-        }
-        if (self.activity.entityId) sendUpdate(self.activity);
-      }),
-    );
-
-    // Inbound presence frames arrive in the wire vocabulary
-    // (userId / isAgent / timestamp); translate them into the shape this
-    // stream exposes (participantId / participantKind / lastActive).
-    unsubs.push(
-      t.subscribe('presence_update', (event: PresenceUpdate) => {
-        if (event.userId === participantId) return; // own echo
-        if (!event.userId) return;
-
-        switch (event.kind) {
-          case 'leave':
-            if (othersById.delete(event.userId)) notifyListeners();
-            return;
-          // No `undefined` arm: every site that builds a presence frame stamps
-          // `kind`, and the schema now says so, so an unlabelled frame is not a
-          // shape the transport can hand us.
-          case 'enter':
-          case 'update': {
-            const entry: Peer = {
-              participantKind: participantKindFromWire(
-                event.participantKind,
-                event.isAgent,
-              ),
-              participantId: event.userId,
-              syncGroups: event.syncGroups ?? [],
-              activity: event.activity
-                ? {
-                    ...wireTarget(event.activity),
-                    ...subTarget(event.activity),
-                    action: event.activity.action,
-                    ...(event.activity.detail !== undefined
-                      ? { detail: event.activity.detail }
-                      : {}),
-                  }
-                : { entityType: 'Unknown', entityId: '', action: event.status },
-              lastActive: event.timestamp
-                ? new Date(event.timestamp).toISOString()
-                : new Date().toISOString(),
-            };
-            othersById.set(event.userId, entry);
-            notifyListeners();
-            return;
-          }
-        }
-      }),
-    );
-
-    // If self was already mutated before attach, broadcast it now.
-    if (self.activity.entityId) sendUpdate(self.activity);
-  }
-
-  if (transport) attach(transport);
-
-  // ── Outbound ────────────────────────────────────────────────────
-  // Do not include `isAgent` in the payload. The server derives it
-  // authoritatively from the connection's identity, and letting a client
-  // self-declare it once caused human sessions to broadcast as agents to peers.
-  function sendUpdate(activity: Activity): void {
-    if (!attached?.isConnected()) return; // no-op until connected
-    attached.send({
-      type: 'presence_update',
-      payload: { status: 'online', activity },
-    });
-  }
-
-  function doUpdate(activity: Activity): void {
-    (self as { activity: Activity }).activity = activity;
-    (self as { lastActive: string }).lastActive = new Date().toISOString();
-    sendUpdate(activity);
-  }
-
-  function resolveTarget(target: PresenceTarget): Activity {
-    if (isTargetTuple(target)) {
-      return { entityType: target[0], entityId: target[1], action: 'unknown' };
-    }
-    return {
-      ...wireTarget(target),
-      ...subTarget(target),
-      action: 'unknown',
-    };
-  }
-
-  const withVerb =
-    (action: string) =>
-    (target: PresenceTarget, detail?: string): void => {
-      doUpdate({ ...resolveTarget(target), action, detail });
-    };
-
-  return {
-    self,
-    update: doUpdate,
-    editing: withVerb('editing'),
-    reading: withVerb('reading'),
-    viewing: withVerb('viewing'),
-    idle: () => {
-      doUpdate({ entityType: 'Unknown', entityId: '', action: 'idle' });
-    },
-    get others() {
-      return othersSnapshot;
-    },
-    othersIn: (syncGroup: string) =>
-      othersSnapshot.filter((e) => e.syncGroups.includes(syncGroup)),
-    onChange: (listener: () => void) => {
-      listeners.add(listener);
-      return () => {
-        listeners.delete(listener);
-      };
-    },
-    [Symbol.asyncIterator]() {
-      return asyncIteratorFrom<readonly Peer[]>(
-        (onChange) => {
-          listeners.add(onChange);
-          return () => {
-            listeners.delete(onChange);
-          };
-        },
-        () => othersSnapshot,
-      );
-    },
-    attach,
-    setParticipant(participant): void {
-      participantId = participant.id;
-      const writable = self as {
-        participantId: string;
-        participantKind: Peer['participantKind'];
-        syncGroups: readonly string[];
-      };
-      writable.participantId = participant.id;
-      if (participant.kind) writable.participantKind = participant.kind;
-      if (participant.syncGroups) writable.syncGroups = [...participant.syncGroups];
-    },
-    dispose(): void {
-      for (const off of unsubs) off();
-      unsubs.length = 0;
-      listeners.clear();
-      othersById.clear();
-      othersSnapshot = Object.freeze([]);
-      attached = null;
-    },
-  };
-}