@opencxh/domain 1.151.0 → 1.153.0

package/dist/platform/ai-tools.d.ts

@@ -72,14 +72,20 @@ export interface ToolSource {
     /** A second line: a snippet, a date, an author. */
     detail?: string;
     /**
-     * Shell-absolute in-product route, including the `/apps/<app>` prefix — the
-     * source may well belong to a different app than the one showing it.
+     * Where to open this source. Two forms, told apart by their first character:
      *
-     * Follow it with the **kernel** router (`sdk` from `@opencxh/app-sdk`), not an
-     * app's own: `createApp().router.navigate` prefixes the calling app's id, which
-     * would turn `/apps/kb/…` into `/apps/ai/apps/kb/…`.
+     * - **`/…`** — a shell-absolute in-product route, including the `/apps/<app>`
+     *   prefix, since the source may well belong to a different app than the one
+     *   showing it. Follow it with the **kernel** router (`sdk` from
+     *   `@opencxh/app-sdk`), not an app's own: `createApp().router.navigate`
+     *   prefixes the calling app's id, which would turn `/apps/kb/…` into
+     *   `/apps/ai/apps/kb/…`.
+     * - **`http(s)://…`** — somewhere outside the platform, opened in a new tab.
+     *   A Shopify order lives in Shopify's admin and nowhere here; pretending
+     *   otherwise would mean either a dead in-product link or dropping the only
+     *   address the thing has.
      *
-     * Absent when the thing has no page of its own — a memory item, for instance —
+     * Absent when the thing has no page at all — a memory item, for instance —
      * which is a reason to show it without a link, not a reason to hide it.
      */
     url?: string;

package/dist/platform/presence.d.ts

@@ -9,7 +9,8 @@
 export declare const PRESENCE_ONLINE_WINDOW_MS = 90000;
 /**
  * Effective presence status. `offline` is derived from connectivity (stale
- * `lastSeenAt`) and always wins; the rest are set by the user or a provider.
+ * `lastSeenAt`) and wins over anything you set — except the statuses in
+ * {@link PRESENCE_SURVIVES_OFFLINE}; the rest are set by the user or a provider.
  */
 export type PresenceStatus = "available" | "away" | "busy" | "dnd" | "out_of_office" | "offline";
 /** Statuses a user (or provider) can set — `offline` is derived, not settable. */
@@ -43,3 +44,56 @@ export interface PresenceStatusInput {
     /** Unix ms after which the status auto-clears (falls back to derived). */
     expiresAt?: number;
 }
+/**
+ * A user's stored availability, as the server persists it. Connectivity is not
+ * in here — that stays derived from `lastSeenAt` on an installation.
+ */
+export interface StoredPresenceStatus {
+    status?: string;
+    message?: string;
+    /** Unix ms after which the status no longer applies. */
+    expiresAt?: number;
+    /** `"manual"` or a providerId (e.g. `"microsoft"`). */
+    source?: string;
+}
+/**
+ * Statuses that mean "I am not at my desk" rather than "I am here, in this
+ * state". Those two behave differently when connectivity goes stale: `busy`
+ * describes right now, so a closed laptop makes it meaningless and `offline` is
+ * the more honest answer. `out_of_office` is a statement about a period, and it
+ * is at its most useful precisely when the person is *not* reachable — so it
+ * outlives the connection instead of being overwritten by it.
+ */
+export declare const PRESENCE_SURVIVES_OFFLINE: readonly PresenceStatus[];
+/**
+ * The one place that turns "when was this user last seen" plus "what did they
+ * set" into an effective presence. Every read (the tenant list, your own row)
+ * and every broadcast goes through it, so the dot never depends on which route
+ * answered.
+ *
+ * `online` is connectivity and nothing else — call routing leans on it. The
+ * status layers on top: an expired one falls back, and a stale connection turns
+ * the rest into `offline` unless it survives (see
+ * {@link PRESENCE_SURVIVES_OFFLINE}). The message travels with the status it
+ * belongs to, so it disappears together with it.
+ */
+export declare function derivePresence(lastSeenAt: number, stored: StoredPresenceStatus | undefined, now: number): {
+    online: boolean;
+    status: PresenceStatus;
+    message?: string;
+};
+/** The shape a client holds per user; the stored status is already folded in. */
+export interface AgeablePresence {
+    lastSeenAt: number;
+    online: boolean;
+    status: PresenceStatus;
+}
+/**
+ * Age a client-held entry: peers who go silent expire without a round-trip.
+ *
+ * Clients only have the *effective* status, not the stored row, so this is the
+ * connectivity half of {@link derivePresence} — same rule about what survives.
+ * Returns the entry unchanged when nothing moved, so a re-render only happens
+ * on a real transition.
+ */
+export declare function agePresenceEntry<T extends AgeablePresence>(entry: T, now: number): T;

package/dist/platform/presence.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencxh/domain",
-  "version": "1.151.0",
+  "version": "1.153.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",