@gravity-rail/sdk 0.47.0 → 0.50.0

package/README.md

@@ -35,9 +35,10 @@ const client = new GravityRailClient(
   'https://api.gravityrail.com'
 );
 
-const workspaces = await client.getWorkspaces();
-if (workspaces.length === 0) throw new Error('No workspace available');
-const workspaceId = workspaces[0].id;
+const workspaces = await client.getWorkspaces({ page: 1, pageSize: 20, search: 'clinic' });
+// Read workspaces.items; request the next page explicitly when needed.
+if (workspaces.items.length === 0) throw new Error('No workspace on this page; search or request another page');
+const workspaceId = workspaces.items[0].uuid;
 const workflows = await client.getWorkflows(workspaceId);
 const chats = await client.getChats(workspaceId);
 ```
@@ -96,17 +97,29 @@ Select the required scopes and expiry using the [granular scope system](#scopes-
 
 ### OAuth2 with PKCE
 
-For browser-based applications:
+For browser-based applications on your own origin, complete the PKCE flow and pass the access token it returns as the client's credential — it is sent as `Authorization: Bearer`:
 
 ```typescript
-const client = new GravityRailClient(undefined, 'https://api.gravityrail.com');
+const client = new GravityRailClient(accessToken, 'https://api.gravityrail.com');
 
 // Handle step-up authentication when the API requires it
 client.setEnhancedAuthHandler(async (authInfo) => {
-  // Redirect to login or show auth modal
+  // Redirect to login or show auth modal; resolve with the new token
 });
 ```
 
+### Same-origin session
+
+A client built **without** a credential is a same-origin session client: it sends no `Authorization` header and fetches with `credentials: 'same-origin'`, so the browser presents the httpOnly session cookie of the origin the page is on, and only to that origin. It never reads a cookie to build a credential. This is how Gravity Rail's own web app calls the API (it serves `/api/v2` on its own origin); point `baseUrl` at the page's origin:
+
+```typescript
+const client = new GravityRailClient(undefined, window.location.origin);
+```
+
+A cross-origin `baseUrl` with no credential makes unauthenticated calls.
+
+When an organization requires SSO, a 401 carrying `WWW-Authenticate: Bearer realm="org"` calls your `setOrgAuthHandler` handler once. A bearer client's handler must hand back the org session with `client.setOrgSession(session, orgUuid)` (sent as `X-Org-Session`); a same-origin session client is retried once after the handler resolves, carrying the httpOnly org-session cookie the sign-in left.
+
 ## Core Concepts
 
 Every Gravity Rail workspace is a self-contained environment with isolated data, workflows, and configuration. The SDK organizes its 500+ methods by domain:
@@ -352,7 +365,9 @@ const operators = await client.getLiveOperators(workspaceId);
 
 ### Sites & Portals
 
-Site record write methods may return a successful value-free receipt: `fieldValues` is empty and `memberId` / `memberName` / `externalId` are null unless Reading Records, level-2 sign-in verification, and the row read policy all allow values. This includes partial updates, resubmissions and upserts. The write still succeeds; use a permitted record read to load stored values.
+Site settings accept `allowedScopes: ['records:read', 'records:write', 'records:admin']` for Manage Records. This opt-in exposes only record scopes the signed-in Member’s current role already allows, within the Site workspace. It permits existing record administration, including other Members’ records, admin-only fields, and deletion. The default is `[]`; read/write opt-ins remain independent. Unrelated administrative scopes stay suppressed.
+
+Site record write methods may return a successful value-free receipt: `fieldValues` is empty and `memberId` / `memberName` / `externalId` are null unless Reading Records and the row read policy both allow values. This includes partial updates, resubmissions and upserts. The write still succeeds; use a permitted record read to load stored values.
 
 ```typescript
 // Build customer-facing portals with AI chat built in
@@ -374,13 +389,42 @@ await client.crawlSite(workspaceId, site.id, { url: 'https://docs.example.com' }
 
 ### Workspace Management
 
+Workspace and organization directories return `{ items, page, pageSize, total, totalPages }`. Read
+`items` instead of treating the response as an array. Pass `page`, `pageSize` (at
+most 100), and `search` to request a page. This applies to `getWorkspaces`,
+`getDeviceAdmissibleWorkspaces`, `getPublicWorkspaces`, `getMyOrganizations`, and
+`getOrganizationWorkspaceSummaries`.
+Organization member details no longer embed workspace lists; request organization
+workspace summary pages instead.
+`getMyOrganizations` also accepts `organizationSlug` for exact host resolution
+and `organizationUuids` (at most 100 UUIDs) for a bounded membership lookup. These
+filters only narrow the current account's memberships.
+Account and device workspace totals count eligible global membership candidates;
+workspace admission can make a page sparse or empty. Use pagination metadata to
+reach later candidates.
+
+`getOrgWorkspaceUsage(orgUuid, { page, pageSize, search })` returns a bounded
+`workspaces` list with `page`, `pageSize`, `total`, and `totalPages` metadata.
+Organization usage totals remain global and can be null when measurement coverage
+is incomplete. Do not sum the visible cards to calculate an organization total.
+
 ```typescript
 // Workspaces this credential can reach
-const workspaces = await client.getWorkspaces();
+const workspaces = await client.getWorkspaces({ page: 1, pageSize: 20, search: 'clinic' });
+// Read workspaces.items; request the next page explicitly when needed.
 
 // Companion-device picker (Lantern): compact rows for only the
 // workspaces a paired device could enter — no device credential needed
-const deviceWorkspaces = await client.getDeviceAdmissibleWorkspaces();
+const deviceWorkspaces = await client.getDeviceAdmissibleWorkspaces({
+  page: 1, pageSize: 20, search: 'clinic',
+});
+// Read deviceWorkspaces.items; a sparse page can still have later candidates.
+
+// Public workspace directory
+const publicWorkspaces = await client.getPublicWorkspaces({
+  page: 1, pageSize: 20, search: 'clinic',
+});
+// Read publicWorkspaces.items and use total/page/pageSize for pagination.
 
 // Export/import full workspace configuration
 const config = await client.exportWorkspace(workspaceId);
@@ -395,6 +439,70 @@ const clientWs = await client.createClientWorkspace(workspaceId, {
 await client.provisionClientWorkspace(workspaceId, clientWs.id);
 ```
 
+## Export Workflow revisions
+
+Workspace JSON and ZIP exports default to active snapshots. Request
+`revisionMode: 'all'` to include historical revisions and drafts. The version `2.0` archive carries isolated
+`workflowRevisions` graphs and requires a revision-aware server for import. Import
+it as new Workflows to preserve active and draft roles; an existing Workflow match
+is refused before writes. Legacy version `1.0` imports keep their existing behavior.
+
+```typescript
+const archive = await client.exportWorkspace(workspaceUuid, undefined, undefined, undefined, {
+  revisionMode: 'all',
+});
+const selected = await client.exportWorkspace(workspaceUuid, workflowId, undefined, undefined, {
+  revisionId: 87,
+});
+const active = await client.exportWorkspace(workspaceUuid, undefined, undefined, undefined, {
+  revisionMode: 'active',
+});
+```
+
+The same options apply to `exportWorkspaceZip`. A selected revision requires a
+Workflow ID and cannot be combined with active mode. Selected and active snapshots
+import into an editable draft and do not change an existing active revision.
+
+The public workspace export API supports only the `channels` exclusion in every
+revision mode. All-revision archives preserve that exclusion. Other public
+exclusion values are rejected.
+
+The SDK throws when a legacy server returns an active-only snapshot for an
+all-revision or selected export.
+JSON validation checks selection metadata and internal Workflow/revision identities.
+ZIP validation checks provenance headers generated from the actual exported data,
+before reading the archive. It adds no archive size limit or permission requirement.
+Deploy a server with ZIP provenance headers before releasing this client update;
+servers with revision-aware JSON alone still fail the ZIP guard. Explicit
+`revisionMode: 'active'` exports remain compatible with legacy servers.
+
+ZIP provenance uses `X-Gravityrail-Export-Version` (`2.0` for all revisions,
+`1.0` for active and selected snapshots) and `X-Gravityrail-Export-Selection`
+(`active`, `all`, or `selected`). A selected ZIP also includes nonempty
+`X-Gravityrail-Export-Revision-Uuid` and `X-Gravityrail-Export-Workflow-Uuid`.
+These values come from the exported artifact. Explicit active exports do not
+require these headers.
+
+Shared dependency definitions are current exported Forms, files, and integrations,
+not historical snapshots of those resources.
+
+## Chat history (`@gravity-rail/sdk/agui`)
+
+`mergeChatHistoryWindow(existing, fetched)` merges an authoritative chronological
+history window into an existing transcript. If the first fetched ID appears in
+the existing transcript, the helper retains only the earlier prefix and replaces
+the covered tail. It removes prefix entries whose IDs also appear in the fetched
+window; it does not remove repeated IDs within the retained prefix. If the first
+ID is unknown, or the fetched window is empty, the result is the fetched window alone.
+Message text does not identify a message. Fetch the needed history pages before
+calling this helper; it does not fetch or filter messages.
+
+```ts
+import { mergeChatHistoryWindow } from '@gravity-rail/sdk/agui';
+
+const messages = mergeChatHistoryWindow(existingMessages, fetchedMessages);
+```
+
 ## Helpers (`@gravity-rail/sdk/helpers`)
 
 Small compound operations built on the client methods, for the common

package/dist/agui.cjs

@@ -24,7 +24,8 @@ __export(agui_exports, {
   getAguiTextMessageContent: () => getAguiTextMessageContent,
   getAguiTextMessageId: () => getAguiTextMessageId,
   getAguiTextMessageMemberId: () => getAguiTextMessageMemberId,
-  getAguiTextMessageRole: () => getAguiTextMessageRole
+  getAguiTextMessageRole: () => getAguiTextMessageRole,
+  mergeChatHistoryWindow: () => mergeChatHistoryWindow
 });
 module.exports = __toCommonJS(agui_exports);
 
@@ -79,12 +80,26 @@ function applyAguiTextMessageEvent(messages, event) {
   }
   return false;
 }
+
+// src/agui/chat-history.ts
+function mergeChatHistoryWindow(existingMessages, fetchedMessages) {
+  const joinsAt = fetchedMessages.length > 0 ? existingMessages.findIndex((msg) => msg.id === fetchedMessages[0].id) : -1;
+  if (joinsAt > 0) {
+    const inPage = new Set(fetchedMessages.map((msg) => msg.id));
+    return [
+      ...existingMessages.slice(0, joinsAt).filter((msg) => !inPage.has(msg.id)),
+      ...fetchedMessages
+    ];
+  }
+  return fetchedMessages;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   applyAguiTextMessageEvent,
   getAguiTextMessageContent,
   getAguiTextMessageId,
   getAguiTextMessageMemberId,
-  getAguiTextMessageRole
+  getAguiTextMessageRole,
+  mergeChatHistoryWindow
 });
 //# sourceMappingURL=agui.cjs.map

package/dist/agui.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/agui/index.ts","../src/agui/text-messages.ts"],"sourcesContent":["export {\n   applyAguiTextMessageEvent,\n   getAguiTextMessageContent,\n   getAguiTextMessageId,\n   getAguiTextMessageMemberId,\n   getAguiTextMessageRole,\n   type TranscriptMessage,\n} from './text-messages';\n","import type { ChannelEvent } from '../realtime/types';\n\nexport interface TranscriptMessage {\n   id: string;\n   role: string;\n   content: string;\n   /** Authoring member id when TEXT_MESSAGE_START carried it (Gravity extension). */\n   memberId?: number;\n}\n\nexport function getAguiTextMessageId(event: ChannelEvent): string | null {\n   const raw = event.messageId ?? event.message_id;\n   return typeof raw === 'string' && raw.length > 0 ? raw : null;\n}\n\nexport function getAguiTextMessageContent(event: ChannelEvent): string | null {\n   const raw = event.content ?? event.text ?? event.delta;\n   return typeof raw === 'string' ? raw : null;\n}\n\nexport function getAguiTextMessageRole(event: ChannelEvent, fallback = 'assistant'): string {\n   const raw = event.role;\n   return typeof raw === 'string' && raw.length > 0 ? raw : fallback;\n}\n\n/** Gravity extension: authoring member on TEXT_MESSAGE_START (camel or snake). */\nexport function getAguiTextMessageMemberId(event: ChannelEvent): number | undefined {\n   const raw = event.memberId ?? event.member_id;\n   return typeof raw === 'number' && Number.isFinite(raw) ? raw : undefined;\n}\n\nexport function applyAguiTextMessageEvent(\n   messages: Map<string, TranscriptMessage>,\n   event: ChannelEvent\n): boolean {\n   const type = event.type;\n   if (typeof type !== 'string') return false;\n\n   if (type === 'TEXT_MESSAGE_START') {\n      const messageId = getAguiTextMessageId(event);\n      if (!messageId) return false;\n      const role = getAguiTextMessageRole(event);\n      const memberId = getAguiTextMessageMemberId(event);\n      messages.set(messageId, {\n         id: messageId,\n         role,\n         content: '',\n         ...(memberId !== undefined ? { memberId } : {}),\n      });\n      return true;\n   }\n\n   if (type === 'TEXT_MESSAGE_CONTENT') {\n      const messageId = getAguiTextMessageId(event);\n      const content = getAguiTextMessageContent(event);\n      if (!messageId || content === null) return false;\n\n      // CONTENT does not carry memberId per protocol — only START does.\n      // Synthesize a bare message if START was missed; leave memberId unset.\n      const existing =\n         messages.get(messageId) ??\n         ({\n            id: messageId,\n            role: getAguiTextMessageRole(event),\n            content: '',\n         } satisfies TranscriptMessage);\n\n      existing.content = content;\n      messages.set(messageId, existing);\n      return true;\n   }\n\n   if (type === 'TEXT_MESSAGE_END') {\n      return Boolean(getAguiTextMessageId(event));\n   }\n\n   return false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACUO,SAAS,qBAAqB,OAAoC;AACtE,QAAM,MAAM,MAAM,aAAa,MAAM;AACrC,SAAO,OAAO,QAAQ,YAAY,IAAI,SAAS,IAAI,MAAM;AAC5D;AAEO,SAAS,0BAA0B,OAAoC;AAC3E,QAAM,MAAM,MAAM,WAAW,MAAM,QAAQ,MAAM;AACjD,SAAO,OAAO,QAAQ,WAAW,MAAM;AAC1C;AAEO,SAAS,uBAAuB,OAAqB,WAAW,aAAqB;AACzF,QAAM,MAAM,MAAM;AAClB,SAAO,OAAO,QAAQ,YAAY,IAAI,SAAS,IAAI,MAAM;AAC5D;AAGO,SAAS,2BAA2B,OAAyC;AACjF,QAAM,MAAM,MAAM,YAAY,MAAM;AACpC,SAAO,OAAO,QAAQ,YAAY,OAAO,SAAS,GAAG,IAAI,MAAM;AAClE;AAEO,SAAS,0BACb,UACA,OACQ;AACR,QAAM,OAAO,MAAM;AACnB,MAAI,OAAO,SAAS,SAAU,QAAO;AAErC,MAAI,SAAS,sBAAsB;AAChC,UAAM,YAAY,qBAAqB,KAAK;AAC5C,QAAI,CAAC,UAAW,QAAO;AACvB,UAAM,OAAO,uBAAuB,KAAK;AACzC,UAAM,WAAW,2BAA2B,KAAK;AACjD,aAAS,IAAI,WAAW;AAAA,MACrB,IAAI;AAAA,MACJ;AAAA,MACA,SAAS;AAAA,MACT,GAAI,aAAa,SAAY,EAAE,SAAS,IAAI,CAAC;AAAA,IAChD,CAAC;AACD,WAAO;AAAA,EACV;AAEA,MAAI,SAAS,wBAAwB;AAClC,UAAM,YAAY,qBAAqB,KAAK;AAC5C,UAAM,UAAU,0BAA0B,KAAK;AAC/C,QAAI,CAAC,aAAa,YAAY,KAAM,QAAO;AAI3C,UAAM,WACH,SAAS,IAAI,SAAS,KACrB;AAAA,MACE,IAAI;AAAA,MACJ,MAAM,uBAAuB,KAAK;AAAA,MAClC,SAAS;AAAA,IACZ;AAEH,aAAS,UAAU;AACnB,aAAS,IAAI,WAAW,QAAQ;AAChC,WAAO;AAAA,EACV;AAEA,MAAI,SAAS,oBAAoB;AAC9B,WAAO,QAAQ,qBAAqB,KAAK,CAAC;AAAA,EAC7C;AAEA,SAAO;AACV;","names":[]}
+{"version":3,"sources":["../src/agui/index.ts","../src/agui/text-messages.ts","../src/agui/chat-history.ts"],"sourcesContent":["export {\n   applyAguiTextMessageEvent,\n   getAguiTextMessageContent,\n   getAguiTextMessageId,\n   getAguiTextMessageMemberId,\n   getAguiTextMessageRole,\n   type TranscriptMessage,\n} from './text-messages';\nexport { mergeChatHistoryWindow } from './chat-history';\n","import type { ChannelEvent } from '../realtime/types';\n\nexport interface TranscriptMessage {\n   id: string;\n   role: string;\n   content: string;\n   /** Authoring member id when TEXT_MESSAGE_START carried it (Gravity extension). */\n   memberId?: number;\n}\n\nexport function getAguiTextMessageId(event: ChannelEvent): string | null {\n   const raw = event.messageId ?? event.message_id;\n   return typeof raw === 'string' && raw.length > 0 ? raw : null;\n}\n\nexport function getAguiTextMessageContent(event: ChannelEvent): string | null {\n   const raw = event.content ?? event.text ?? event.delta;\n   return typeof raw === 'string' ? raw : null;\n}\n\nexport function getAguiTextMessageRole(event: ChannelEvent, fallback = 'assistant'): string {\n   const raw = event.role;\n   return typeof raw === 'string' && raw.length > 0 ? raw : fallback;\n}\n\n/** Gravity extension: authoring member on TEXT_MESSAGE_START (camel or snake). */\nexport function getAguiTextMessageMemberId(event: ChannelEvent): number | undefined {\n   const raw = event.memberId ?? event.member_id;\n   return typeof raw === 'number' && Number.isFinite(raw) ? raw : undefined;\n}\n\nexport function applyAguiTextMessageEvent(\n   messages: Map<string, TranscriptMessage>,\n   event: ChannelEvent\n): boolean {\n   const type = event.type;\n   if (typeof type !== 'string') return false;\n\n   if (type === 'TEXT_MESSAGE_START') {\n      const messageId = getAguiTextMessageId(event);\n      if (!messageId) return false;\n      const role = getAguiTextMessageRole(event);\n      const memberId = getAguiTextMessageMemberId(event);\n      messages.set(messageId, {\n         id: messageId,\n         role,\n         content: '',\n         ...(memberId !== undefined ? { memberId } : {}),\n      });\n      return true;\n   }\n\n   if (type === 'TEXT_MESSAGE_CONTENT') {\n      const messageId = getAguiTextMessageId(event);\n      const content = getAguiTextMessageContent(event);\n      if (!messageId || content === null) return false;\n\n      // CONTENT does not carry memberId per protocol — only START does.\n      // Synthesize a bare message if START was missed; leave memberId unset.\n      const existing =\n         messages.get(messageId) ??\n         ({\n            id: messageId,\n            role: getAguiTextMessageRole(event),\n            content: '',\n         } satisfies TranscriptMessage);\n\n      existing.content = content;\n      messages.set(messageId, existing);\n      return true;\n   }\n\n   if (type === 'TEXT_MESSAGE_END') {\n      return Boolean(getAguiTextMessageId(event));\n   }\n\n   return false;\n}\n","/** Keep loaded messages before a fetched window; the fetched tail is authoritative.\n * With no shared first message, the windows do not join and the fetched page stands alone.\n * Extracted from the main app's useChatMessages cache merge.\n */\nexport function mergeChatHistoryWindow<T extends { id: string }>(\n   existingMessages: T[],\n   fetchedMessages: T[]\n): T[] {\n   const joinsAt =\n      fetchedMessages.length > 0\n         ? existingMessages.findIndex((msg) => msg.id === fetchedMessages[0].id)\n         : -1;\n   if (joinsAt > 0) {\n      const inPage = new Set(fetchedMessages.map((msg) => msg.id));\n      return [\n         ...existingMessages.slice(0, joinsAt).filter((msg) => !inPage.has(msg.id)),\n         ...fetchedMessages,\n      ];\n   }\n   return fetchedMessages;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACUO,SAAS,qBAAqB,OAAoC;AACtE,QAAM,MAAM,MAAM,aAAa,MAAM;AACrC,SAAO,OAAO,QAAQ,YAAY,IAAI,SAAS,IAAI,MAAM;AAC5D;AAEO,SAAS,0BAA0B,OAAoC;AAC3E,QAAM,MAAM,MAAM,WAAW,MAAM,QAAQ,MAAM;AACjD,SAAO,OAAO,QAAQ,WAAW,MAAM;AAC1C;AAEO,SAAS,uBAAuB,OAAqB,WAAW,aAAqB;AACzF,QAAM,MAAM,MAAM;AAClB,SAAO,OAAO,QAAQ,YAAY,IAAI,SAAS,IAAI,MAAM;AAC5D;AAGO,SAAS,2BAA2B,OAAyC;AACjF,QAAM,MAAM,MAAM,YAAY,MAAM;AACpC,SAAO,OAAO,QAAQ,YAAY,OAAO,SAAS,GAAG,IAAI,MAAM;AAClE;AAEO,SAAS,0BACb,UACA,OACQ;AACR,QAAM,OAAO,MAAM;AACnB,MAAI,OAAO,SAAS,SAAU,QAAO;AAErC,MAAI,SAAS,sBAAsB;AAChC,UAAM,YAAY,qBAAqB,KAAK;AAC5C,QAAI,CAAC,UAAW,QAAO;AACvB,UAAM,OAAO,uBAAuB,KAAK;AACzC,UAAM,WAAW,2BAA2B,KAAK;AACjD,aAAS,IAAI,WAAW;AAAA,MACrB,IAAI;AAAA,MACJ;AAAA,MACA,SAAS;AAAA,MACT,GAAI,aAAa,SAAY,EAAE,SAAS,IAAI,CAAC;AAAA,IAChD,CAAC;AACD,WAAO;AAAA,EACV;AAEA,MAAI,SAAS,wBAAwB;AAClC,UAAM,YAAY,qBAAqB,KAAK;AAC5C,UAAM,UAAU,0BAA0B,KAAK;AAC/C,QAAI,CAAC,aAAa,YAAY,KAAM,QAAO;AAI3C,UAAM,WACH,SAAS,IAAI,SAAS,KACrB;AAAA,MACE,IAAI;AAAA,MACJ,MAAM,uBAAuB,KAAK;AAAA,MAClC,SAAS;AAAA,IACZ;AAEH,aAAS,UAAU;AACnB,aAAS,IAAI,WAAW,QAAQ;AAChC,WAAO;AAAA,EACV;AAEA,MAAI,SAAS,oBAAoB;AAC9B,WAAO,QAAQ,qBAAqB,KAAK,CAAC;AAAA,EAC7C;AAEA,SAAO;AACV;;;ACzEO,SAAS,uBACb,kBACA,iBACI;AACJ,QAAM,UACH,gBAAgB,SAAS,IACpB,iBAAiB,UAAU,CAAC,QAAQ,IAAI,OAAO,gBAAgB,CAAC,EAAE,EAAE,IACpE;AACR,MAAI,UAAU,GAAG;AACd,UAAM,SAAS,IAAI,IAAI,gBAAgB,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;AAC3D,WAAO;AAAA,MACJ,GAAG,iBAAiB,MAAM,GAAG,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;AAAA,MACzE,GAAG;AAAA,IACN;AAAA,EACH;AACA,SAAO;AACV;","names":[]}

package/dist/agui.d.cts

@@ -14,4 +14,12 @@ declare function getAguiTextMessageRole(event: ChannelEvent, fallback?: string):
 declare function getAguiTextMessageMemberId(event: ChannelEvent): number | undefined;
 declare function applyAguiTextMessageEvent(messages: Map<string, TranscriptMessage>, event: ChannelEvent): boolean;
 
-export { type TranscriptMessage, applyAguiTextMessageEvent, getAguiTextMessageContent, getAguiTextMessageId, getAguiTextMessageMemberId, getAguiTextMessageRole };
+/** Keep loaded messages before a fetched window; the fetched tail is authoritative.
+ * With no shared first message, the windows do not join and the fetched page stands alone.
+ * Extracted from the main app's useChatMessages cache merge.
+ */
+declare function mergeChatHistoryWindow<T extends {
+    id: string;
+}>(existingMessages: T[], fetchedMessages: T[]): T[];
+
+export { type TranscriptMessage, applyAguiTextMessageEvent, getAguiTextMessageContent, getAguiTextMessageId, getAguiTextMessageMemberId, getAguiTextMessageRole, mergeChatHistoryWindow };

package/dist/agui.d.ts

@@ -14,4 +14,12 @@ declare function getAguiTextMessageRole(event: ChannelEvent, fallback?: string):
 declare function getAguiTextMessageMemberId(event: ChannelEvent): number | undefined;
 declare function applyAguiTextMessageEvent(messages: Map<string, TranscriptMessage>, event: ChannelEvent): boolean;
 
-export { type TranscriptMessage, applyAguiTextMessageEvent, getAguiTextMessageContent, getAguiTextMessageId, getAguiTextMessageMemberId, getAguiTextMessageRole };
+/** Keep loaded messages before a fetched window; the fetched tail is authoritative.
+ * With no shared first message, the windows do not join and the fetched page stands alone.
+ * Extracted from the main app's useChatMessages cache merge.
+ */
+declare function mergeChatHistoryWindow<T extends {
+    id: string;
+}>(existingMessages: T[], fetchedMessages: T[]): T[];
+
+export { type TranscriptMessage, applyAguiTextMessageEvent, getAguiTextMessageContent, getAguiTextMessageId, getAguiTextMessageMemberId, getAguiTextMessageRole, mergeChatHistoryWindow };

package/dist/agui.js

@@ -49,11 +49,25 @@ function applyAguiTextMessageEvent(messages, event) {
   }
   return false;
 }
+
+// src/agui/chat-history.ts
+function mergeChatHistoryWindow(existingMessages, fetchedMessages) {
+  const joinsAt = fetchedMessages.length > 0 ? existingMessages.findIndex((msg) => msg.id === fetchedMessages[0].id) : -1;
+  if (joinsAt > 0) {
+    const inPage = new Set(fetchedMessages.map((msg) => msg.id));
+    return [
+      ...existingMessages.slice(0, joinsAt).filter((msg) => !inPage.has(msg.id)),
+      ...fetchedMessages
+    ];
+  }
+  return fetchedMessages;
+}
 export {
   applyAguiTextMessageEvent,
   getAguiTextMessageContent,
   getAguiTextMessageId,
   getAguiTextMessageMemberId,
-  getAguiTextMessageRole
+  getAguiTextMessageRole,
+  mergeChatHistoryWindow
 };
 //# sourceMappingURL=agui.js.map

package/dist/agui.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/agui/text-messages.ts"],"sourcesContent":["import type { ChannelEvent } from '../realtime/types';\n\nexport interface TranscriptMessage {\n   id: string;\n   role: string;\n   content: string;\n   /** Authoring member id when TEXT_MESSAGE_START carried it (Gravity extension). */\n   memberId?: number;\n}\n\nexport function getAguiTextMessageId(event: ChannelEvent): string | null {\n   const raw = event.messageId ?? event.message_id;\n   return typeof raw === 'string' && raw.length > 0 ? raw : null;\n}\n\nexport function getAguiTextMessageContent(event: ChannelEvent): string | null {\n   const raw = event.content ?? event.text ?? event.delta;\n   return typeof raw === 'string' ? raw : null;\n}\n\nexport function getAguiTextMessageRole(event: ChannelEvent, fallback = 'assistant'): string {\n   const raw = event.role;\n   return typeof raw === 'string' && raw.length > 0 ? raw : fallback;\n}\n\n/** Gravity extension: authoring member on TEXT_MESSAGE_START (camel or snake). */\nexport function getAguiTextMessageMemberId(event: ChannelEvent): number | undefined {\n   const raw = event.memberId ?? event.member_id;\n   return typeof raw === 'number' && Number.isFinite(raw) ? raw : undefined;\n}\n\nexport function applyAguiTextMessageEvent(\n   messages: Map<string, TranscriptMessage>,\n   event: ChannelEvent\n): boolean {\n   const type = event.type;\n   if (typeof type !== 'string') return false;\n\n   if (type === 'TEXT_MESSAGE_START') {\n      const messageId = getAguiTextMessageId(event);\n      if (!messageId) return false;\n      const role = getAguiTextMessageRole(event);\n      const memberId = getAguiTextMessageMemberId(event);\n      messages.set(messageId, {\n         id: messageId,\n         role,\n         content: '',\n         ...(memberId !== undefined ? { memberId } : {}),\n      });\n      return true;\n   }\n\n   if (type === 'TEXT_MESSAGE_CONTENT') {\n      const messageId = getAguiTextMessageId(event);\n      const content = getAguiTextMessageContent(event);\n      if (!messageId || content === null) return false;\n\n      // CONTENT does not carry memberId per protocol — only START does.\n      // Synthesize a bare message if START was missed; leave memberId unset.\n      const existing =\n         messages.get(messageId) ??\n         ({\n            id: messageId,\n            role: getAguiTextMessageRole(event),\n            content: '',\n         } satisfies TranscriptMessage);\n\n      existing.content = content;\n      messages.set(messageId, existing);\n      return true;\n   }\n\n   if (type === 'TEXT_MESSAGE_END') {\n      return Boolean(getAguiTextMessageId(event));\n   }\n\n   return false;\n}\n"],"mappings":";AAUO,SAAS,qBAAqB,OAAoC;AACtE,QAAM,MAAM,MAAM,aAAa,MAAM;AACrC,SAAO,OAAO,QAAQ,YAAY,IAAI,SAAS,IAAI,MAAM;AAC5D;AAEO,SAAS,0BAA0B,OAAoC;AAC3E,QAAM,MAAM,MAAM,WAAW,MAAM,QAAQ,MAAM;AACjD,SAAO,OAAO,QAAQ,WAAW,MAAM;AAC1C;AAEO,SAAS,uBAAuB,OAAqB,WAAW,aAAqB;AACzF,QAAM,MAAM,MAAM;AAClB,SAAO,OAAO,QAAQ,YAAY,IAAI,SAAS,IAAI,MAAM;AAC5D;AAGO,SAAS,2BAA2B,OAAyC;AACjF,QAAM,MAAM,MAAM,YAAY,MAAM;AACpC,SAAO,OAAO,QAAQ,YAAY,OAAO,SAAS,GAAG,IAAI,MAAM;AAClE;AAEO,SAAS,0BACb,UACA,OACQ;AACR,QAAM,OAAO,MAAM;AACnB,MAAI,OAAO,SAAS,SAAU,QAAO;AAErC,MAAI,SAAS,sBAAsB;AAChC,UAAM,YAAY,qBAAqB,KAAK;AAC5C,QAAI,CAAC,UAAW,QAAO;AACvB,UAAM,OAAO,uBAAuB,KAAK;AACzC,UAAM,WAAW,2BAA2B,KAAK;AACjD,aAAS,IAAI,WAAW;AAAA,MACrB,IAAI;AAAA,MACJ;AAAA,MACA,SAAS;AAAA,MACT,GAAI,aAAa,SAAY,EAAE,SAAS,IAAI,CAAC;AAAA,IAChD,CAAC;AACD,WAAO;AAAA,EACV;AAEA,MAAI,SAAS,wBAAwB;AAClC,UAAM,YAAY,qBAAqB,KAAK;AAC5C,UAAM,UAAU,0BAA0B,KAAK;AAC/C,QAAI,CAAC,aAAa,YAAY,KAAM,QAAO;AAI3C,UAAM,WACH,SAAS,IAAI,SAAS,KACrB;AAAA,MACE,IAAI;AAAA,MACJ,MAAM,uBAAuB,KAAK;AAAA,MAClC,SAAS;AAAA,IACZ;AAEH,aAAS,UAAU;AACnB,aAAS,IAAI,WAAW,QAAQ;AAChC,WAAO;AAAA,EACV;AAEA,MAAI,SAAS,oBAAoB;AAC9B,WAAO,QAAQ,qBAAqB,KAAK,CAAC;AAAA,EAC7C;AAEA,SAAO;AACV;","names":[]}
+{"version":3,"sources":["../src/agui/text-messages.ts","../src/agui/chat-history.ts"],"sourcesContent":["import type { ChannelEvent } from '../realtime/types';\n\nexport interface TranscriptMessage {\n   id: string;\n   role: string;\n   content: string;\n   /** Authoring member id when TEXT_MESSAGE_START carried it (Gravity extension). */\n   memberId?: number;\n}\n\nexport function getAguiTextMessageId(event: ChannelEvent): string | null {\n   const raw = event.messageId ?? event.message_id;\n   return typeof raw === 'string' && raw.length > 0 ? raw : null;\n}\n\nexport function getAguiTextMessageContent(event: ChannelEvent): string | null {\n   const raw = event.content ?? event.text ?? event.delta;\n   return typeof raw === 'string' ? raw : null;\n}\n\nexport function getAguiTextMessageRole(event: ChannelEvent, fallback = 'assistant'): string {\n   const raw = event.role;\n   return typeof raw === 'string' && raw.length > 0 ? raw : fallback;\n}\n\n/** Gravity extension: authoring member on TEXT_MESSAGE_START (camel or snake). */\nexport function getAguiTextMessageMemberId(event: ChannelEvent): number | undefined {\n   const raw = event.memberId ?? event.member_id;\n   return typeof raw === 'number' && Number.isFinite(raw) ? raw : undefined;\n}\n\nexport function applyAguiTextMessageEvent(\n   messages: Map<string, TranscriptMessage>,\n   event: ChannelEvent\n): boolean {\n   const type = event.type;\n   if (typeof type !== 'string') return false;\n\n   if (type === 'TEXT_MESSAGE_START') {\n      const messageId = getAguiTextMessageId(event);\n      if (!messageId) return false;\n      const role = getAguiTextMessageRole(event);\n      const memberId = getAguiTextMessageMemberId(event);\n      messages.set(messageId, {\n         id: messageId,\n         role,\n         content: '',\n         ...(memberId !== undefined ? { memberId } : {}),\n      });\n      return true;\n   }\n\n   if (type === 'TEXT_MESSAGE_CONTENT') {\n      const messageId = getAguiTextMessageId(event);\n      const content = getAguiTextMessageContent(event);\n      if (!messageId || content === null) return false;\n\n      // CONTENT does not carry memberId per protocol — only START does.\n      // Synthesize a bare message if START was missed; leave memberId unset.\n      const existing =\n         messages.get(messageId) ??\n         ({\n            id: messageId,\n            role: getAguiTextMessageRole(event),\n            content: '',\n         } satisfies TranscriptMessage);\n\n      existing.content = content;\n      messages.set(messageId, existing);\n      return true;\n   }\n\n   if (type === 'TEXT_MESSAGE_END') {\n      return Boolean(getAguiTextMessageId(event));\n   }\n\n   return false;\n}\n","/** Keep loaded messages before a fetched window; the fetched tail is authoritative.\n * With no shared first message, the windows do not join and the fetched page stands alone.\n * Extracted from the main app's useChatMessages cache merge.\n */\nexport function mergeChatHistoryWindow<T extends { id: string }>(\n   existingMessages: T[],\n   fetchedMessages: T[]\n): T[] {\n   const joinsAt =\n      fetchedMessages.length > 0\n         ? existingMessages.findIndex((msg) => msg.id === fetchedMessages[0].id)\n         : -1;\n   if (joinsAt > 0) {\n      const inPage = new Set(fetchedMessages.map((msg) => msg.id));\n      return [\n         ...existingMessages.slice(0, joinsAt).filter((msg) => !inPage.has(msg.id)),\n         ...fetchedMessages,\n      ];\n   }\n   return fetchedMessages;\n}\n"],"mappings":";AAUO,SAAS,qBAAqB,OAAoC;AACtE,QAAM,MAAM,MAAM,aAAa,MAAM;AACrC,SAAO,OAAO,QAAQ,YAAY,IAAI,SAAS,IAAI,MAAM;AAC5D;AAEO,SAAS,0BAA0B,OAAoC;AAC3E,QAAM,MAAM,MAAM,WAAW,MAAM,QAAQ,MAAM;AACjD,SAAO,OAAO,QAAQ,WAAW,MAAM;AAC1C;AAEO,SAAS,uBAAuB,OAAqB,WAAW,aAAqB;AACzF,QAAM,MAAM,MAAM;AAClB,SAAO,OAAO,QAAQ,YAAY,IAAI,SAAS,IAAI,MAAM;AAC5D;AAGO,SAAS,2BAA2B,OAAyC;AACjF,QAAM,MAAM,MAAM,YAAY,MAAM;AACpC,SAAO,OAAO,QAAQ,YAAY,OAAO,SAAS,GAAG,IAAI,MAAM;AAClE;AAEO,SAAS,0BACb,UACA,OACQ;AACR,QAAM,OAAO,MAAM;AACnB,MAAI,OAAO,SAAS,SAAU,QAAO;AAErC,MAAI,SAAS,sBAAsB;AAChC,UAAM,YAAY,qBAAqB,KAAK;AAC5C,QAAI,CAAC,UAAW,QAAO;AACvB,UAAM,OAAO,uBAAuB,KAAK;AACzC,UAAM,WAAW,2BAA2B,KAAK;AACjD,aAAS,IAAI,WAAW;AAAA,MACrB,IAAI;AAAA,MACJ;AAAA,MACA,SAAS;AAAA,MACT,GAAI,aAAa,SAAY,EAAE,SAAS,IAAI,CAAC;AAAA,IAChD,CAAC;AACD,WAAO;AAAA,EACV;AAEA,MAAI,SAAS,wBAAwB;AAClC,UAAM,YAAY,qBAAqB,KAAK;AAC5C,UAAM,UAAU,0BAA0B,KAAK;AAC/C,QAAI,CAAC,aAAa,YAAY,KAAM,QAAO;AAI3C,UAAM,WACH,SAAS,IAAI,SAAS,KACrB;AAAA,MACE,IAAI;AAAA,MACJ,MAAM,uBAAuB,KAAK;AAAA,MAClC,SAAS;AAAA,IACZ;AAEH,aAAS,UAAU;AACnB,aAAS,IAAI,WAAW,QAAQ;AAChC,WAAO;AAAA,EACV;AAEA,MAAI,SAAS,oBAAoB;AAC9B,WAAO,QAAQ,qBAAqB,KAAK,CAAC;AAAA,EAC7C;AAEA,SAAO;AACV;;;ACzEO,SAAS,uBACb,kBACA,iBACI;AACJ,QAAM,UACH,gBAAgB,SAAS,IACpB,iBAAiB,UAAU,CAAC,QAAQ,IAAI,OAAO,gBAAgB,CAAC,EAAE,EAAE,IACpE;AACR,MAAI,UAAU,GAAG;AACd,UAAM,SAAS,IAAI,IAAI,gBAAgB,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;AAC3D,WAAO;AAAA,MACJ,GAAG,iBAAiB,MAAM,GAAG,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;AAAA,MACzE,GAAG;AAAA,IACN;AAAA,EACH;AACA,SAAO;AACV;","names":[]}