@arbidocs/sdk 0.3.15 → 0.3.17

package/README.md

@@ -1,130 +1,107 @@
 # @arbidocs/sdk
 
-High-level TypeScript SDK for the ARBI platform. Wraps authentication, workspace encryption, and all API operations into a single `Arbi` class.
+TypeScript SDK for the ARBI platform. Handles authentication, workspace encryption, and streaming AI queries.
 
-## Install
+## Quickstart
 
 ```bash
 npm install @arbidocs/sdk
 ```
 
-For Node.js, also install the IndexedDB polyfill:
-
-```bash
-npm install fake-indexeddb
-```
-
-## Quick Start
-
 ```typescript
-import 'fake-indexeddb/auto' // Node.js only
-import { Arbi } from '@arbidocs/sdk'
+import { Arbi } from '@arbidocs/sdk/browser'
 
-const arbi = new Arbi({ url: 'https://arbi.mycompany.com' })
+const arbi = new Arbi({ url: 'https://www.arbidocs.com' })
 
-// Login
+// Login and select a workspace
 await arbi.login('user@example.com', 'password')
-
-// Pick a workspace
 const workspaces = await arbi.workspaces.list()
 await arbi.selectWorkspace(workspaces[0].external_id)
 
-// Use it
+// Ask a streaming question about your documents
 const docs = await arbi.documents.list()
-const tags = await arbi.tags.list()
-const conversations = await arbi.conversations.list()
-```
-
-## Streaming AI Queries
-
-```typescript
-const result = await arbi.assistant.query('What does section 3 say?', {
+await arbi.assistant.query('Summarize this document', {
   docIds: [docs[0].external_id],
   onToken: (token) => process.stdout.write(token),
-  onStreamStart: ({ assistant_message_ext_id }) => {
-    console.log('Stream started:', assistant_message_ext_id)
-  },
-  onComplete: () => console.log('\nDone'),
 })
 ```
 
-## Session Recovery
-
-After login, the SDK automatically persists your signing key (encrypted) in IndexedDB. You can also recover a session using the raw private key:
+For Node.js, install `fake-indexeddb` and import it first:
 
 ```typescript
-// Save the key after first login (e.g. the recovery key download)
-const signingKeyBase64 = '...'
-
-// Later, recover without password:
-await arbi.loginWithKey('user@example.com', signingKeyBase64)
+import 'fake-indexeddb/auto'
+import { Arbi } from '@arbidocs/sdk'
 ```
 
-## API Reference
-
-### Constructor
+## Lifecycle
 
 ```typescript
-const arbi = new Arbi({
-  url: 'https://arbi.mycompany.com',     // Required: backend URL
-  deploymentDomain: 'arbi.mycompany.com', // Optional: defaults to URL hostname
-  credentials: 'omit',                    // Optional: 'omit' | 'include' | 'same-origin'
-})
-```
+const arbi = new Arbi({ url: 'https://www.arbidocs.com' })
 
-### Lifecycle
+await arbi.login(email, password)            // or arbi.loginWithKey(email, keyBase64)
+await arbi.selectWorkspace(workspaceId)
+// ... use the SDK ...
+await arbi.logout()
+```
 
-| Method | Description |
-|--------|-------------|
-| `login(email, password)` | Authenticate with email and password |
-| `loginWithKey(email, signingKeyBase64)` | Authenticate with a stored signing key |
-| `selectWorkspace(workspaceId)` | Select a workspace (decrypts workspace key) |
-| `logout()` | Log out and securely clear key material |
+| Property | Description |
+|----------|-------------|
+| `arbi.isLoggedIn` | Whether the user is authenticated |
+| `arbi.hasWorkspace` | Whether a workspace is selected |
 
-### Properties
+## Operations
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `isLoggedIn` | `boolean` | Whether the user is authenticated |
-| `hasWorkspace` | `boolean` | Whether a workspace is selected |
+| Namespace | Key methods |
+|-----------|-------------|
+| `arbi.workspaces` | `list()`, `create()`, `update()`, `delete()`, `listUsers()`, `addUsers()`, `removeUsers()` |
+| `arbi.documents` | `list()`, `get()`, `uploadFile()`, `uploadUrl()`, `update()`, `delete()`, `download()` |
+| `arbi.conversations` | `list()`, `getThreads()`, `updateTitle()`, `share()`, `delete()` |
+| `arbi.assistant` | `query(question, options)`, `retrieve(query, docIds)`, `respond(messageId, answer)` |
+| `arbi.tags` | `list()`, `create()`, `update()`, `delete()` |
+| `arbi.doctags` | `assign()`, `remove()`, `generate()` |
+| `arbi.contacts` | `list()`, `add()`, `remove()` |
+| `arbi.health` | `check()`, `models()`, `mcpTools()` |
 
-### Operations
+## Streaming AI queries
 
-All operations are namespaced and require a workspace to be selected (except `workspaces` and `health`).
+```typescript
+const result = await arbi.assistant.query('What does section 3 say?', {
+  docIds: [docId],
+  previousResponseId: lastMessageId,   // for multi-turn conversations
+  onToken: (token) => { /* append to UI */ },
+  onStreamStart: ({ assistant_message_ext_id }) => { /* save for follow-ups */ },
+  onAgentStep: (step) => { /* agent tool usage */ },
+  onError: (message) => { /* handle error */ },
+  onComplete: () => { /* done */ },
+})
 
-| Namespace | Methods |
-|-----------|---------|
-| `arbi.workspaces` | `list()`, `create()`, `update()`, `delete()`, `listUsers()`, `addUsers()`, `removeUsers()`, `setUserRole()` |
-| `arbi.documents` | `list()`, `get()`, `upload()`, `update()`, `delete()` |
-| `arbi.conversations` | `list()`, `getThreads()`, `updateTitle()`, `share()`, `delete()` |
-| `arbi.assistant` | `query(question, options)`, `retrieve(messageExtId)` |
-| `arbi.tags` | `list()`, `create()`, `update()`, `delete()` |
-| `arbi.doctags` | `assign()`, `remove()` |
-| `arbi.contacts` | `list()`, `search()` |
-| `arbi.health` | `check()` |
+// result.text — full accumulated response
+// result.assistantMessageExtId — use as previousResponseId for follow-ups
+```
 
-### Browser Entry Point
+## Session recovery
 
-For browser environments (no Node.js APIs like `fs`), import from the browser entry:
+The SDK persists the signing key (encrypted) in IndexedDB. Recover a session without a password:
 
 ```typescript
-import { Arbi } from '@arbidocs/sdk/browser'
+await arbi.loginWithKey('user@example.com', signingKeyBase64)
 ```
 
+The SDK also auto-recovers on 401 responses using the stored key.
+
 ## Security
 
-- **Zero-knowledge auth**: Passwords never leave the client. Ed25519 keys are derived locally via Argon2id.
-- **E2E workspace encryption**: Each workspace has a symmetric key, wrapped with your public key.
-- **Encrypted key storage**: Private keys in IndexedDB are encrypted with a non-extractable Web Crypto AES-GCM key.
-- **Key zeroing on logout**: Signing and session keys are scrubbed from memory on logout.
+- **Zero-knowledge auth** — passwords never leave the client
+- **E2E workspace encryption** — symmetric keys wrapped with your public key
+- **Encrypted key storage** — private keys in IndexedDB encrypted with non-extractable AES-GCM
+- **Key zeroing on logout** — signing and session keys scrubbed from memory
 
-## Examples
+## React
 
-- **[Node.js Hello World](../../examples/node-hello-world/)** — Login, list docs, ask a streaming question (~40 lines)
-- **[React Chat App](../../examples/react-chat/)** — Login form, workspace selector, document picker, streaming chat
+For React apps, use `@arbidocs/react` instead — it wraps this SDK with hooks and a context provider. See the [@arbidocs/react README](../arbi-react/README.md).
 
 ## Requirements
 
 - **Browser**: Any modern browser with Web Crypto API
-- **Node.js**: v18+ (needs `fetch`, `FormData`, `Blob` globals). Install `fake-indexeddb`.
+- **Node.js**: v18+ (install `fake-indexeddb`)
 - **TypeScript**: 5.0+ (optional)

package/dist/{browser-DnGux0ct.d.cts → browser-BtAHbiq_.d.cts}

@@ -114,6 +114,10 @@ interface ConfigStore {
     saveChatSession(session: ChatSession): void;
     updateChatSession(updates: Partial<ChatSession>): void;
     clearChatSession(): void;
+    /** Persist last response metadata for citation browsing (optional). */
+    saveLastMetadata?(metadata: unknown): void;
+    /** Load last response metadata for citation browsing (optional). */
+    loadLastMetadata?(): unknown | null;
 }
 
 /**
@@ -218,7 +222,8 @@ type AgentStepEvent = components['schemas']['AgentStepEvent'];
 type UserInputRequestEvent = components['schemas']['UserInputRequestEvent'];
 type ArtifactEvent = components['schemas']['ArtifactEvent'];
 type UserMessageEvent = components['schemas']['UserMessageEvent'];
-type MessageMetadataPayload = components['schemas']['MessageMetadataPayload'];
+type MessageQueuedEvent = components['schemas']['MessageQueuedEvent'];
+type MessageMetadataPayload$1 = components['schemas']['MessageMetadataPayload'];
 type ResponseUsage = components['schemas']['ResponseUsage'];
 type OutputTokensDetails = components['schemas']['OutputTokensDetails'];
 type TokenBudgetContext = components['schemas']['TokenBudgetContext'];
@@ -273,8 +278,9 @@ interface SSEStreamCallbacks {
     onContentPartAdded?: (data: ResponseContentPartAddedEvent) => void;
     onAgentStep?: (data: AgentStepEvent) => void;
     onError?: (message: string) => void;
+    onMessageQueued?: (data: MessageQueuedEvent) => void;
     onUserMessage?: (data: UserMessageEvent) => void;
-    onMetadata?: (data: MessageMetadataPayload) => void;
+    onMetadata?: (data: MessageMetadataPayload$1) => void;
     onUserInputRequest?: (data: UserInputRequestEvent) => void;
     onArtifact?: (data: ArtifactEvent) => void;
     onElapsedTime?: (t: number) => void;
@@ -292,7 +298,7 @@ interface SSEStreamResult {
     toolCallCount: number;
     errors: string[];
     userMessage: UserMessageEvent | null;
-    metadata: MessageMetadataPayload | null;
+    metadata: MessageMetadataPayload$1 | null;
     artifacts: ArtifactEvent[];
     usage: ResponseUsage | null;
     /** Token budget context snapshot from response.completed. */
@@ -308,6 +314,15 @@ interface SSEStreamResult {
  * both the streaming callbacks and the final result.
  */
 declare function streamSSE(response: Response, callbacks?: SSEStreamCallbacks): Promise<SSEStreamResult>;
+/**
+ * Format a human-readable summary line from a completed SSE stream result.
+ *
+ * Returns a string like:
+ *   "3 steps (2 tool calls) · 1,234 tokens · 500/8,000 context · 2.5s"
+ *
+ * Returns empty string if there's nothing to report.
+ */
+declare function formatStreamSummary(result: SSEStreamResult, elapsedTime?: number | null): string;
 /**
  * Consume an entire SSE stream without streaming callbacks.
  * Convenience alias for `streamSSE(response)`.
@@ -424,6 +439,66 @@ type UserInfo = {
  */
 declare function formatUserName(user: UserInfo | null | undefined): string;
 
+/**
+ * Citation resolution utilities — shared by CLI and TUI.
+ *
+ * Parses citation data from SSE metadata (`MessageMetadataPayload`) and
+ * resolves chunk references into displayable citation summaries and passages.
+ *
+ * Citation data flow:
+ *   1. `tools.model_citations.tool_responses` maps citation number → CitationData
+ *      (contains chunk_ids, statement, offsets)
+ *   2. `tools.retrieval_chunk.tool_responses` and `tools.retrieval_full_context.tool_responses`
+ *      map document file name → Chunk[] (contains content and metadata)
+ *   3. This module joins those two data sets to produce resolved citations.
+ */
+
+type MessageMetadataPayload = components['schemas']['MessageMetadataPayload'];
+type CitationData$2 = components['schemas']['CitationData'];
+type Chunk$1 = components['schemas']['Chunk'];
+/** A fully resolved citation with its source chunks. */
+interface ResolvedCitation {
+    /** Citation number as a string (e.g. "1", "2") */
+    citationNum: string;
+    /** Raw citation data from model_citations */
+    citationData: CitationData$2;
+    /** Resolved chunks matching the citation's chunk_ids */
+    chunks: Chunk$1[];
+}
+/** A compact citation summary for display in lists. */
+interface CitationSummary {
+    citationNum: string;
+    statement: string;
+    docTitle: string;
+    pageNumber: number | null;
+    chunkCount: number;
+}
+/**
+ * Resolve all citations from SSE metadata into full citation objects.
+ *
+ * Reads `tools.model_citations.tool_responses` for citation→chunk_id mappings,
+ * then builds a chunk lookup from `retrieval_chunk` and `retrieval_full_context`
+ * tool responses to resolve each chunk_id to its full Chunk object.
+ *
+ * Returns citations sorted by citation number (ascending).
+ */
+declare function resolveCitations(metadata: MessageMetadataPayload | null): ResolvedCitation[];
+/**
+ * Produce compact summaries for display in citation lists.
+ * Uses the first chunk of each citation for doc title and page number.
+ */
+declare function summarizeCitations(resolved: ResolvedCitation[]): CitationSummary[];
+/**
+ * Count the number of citations in metadata.
+ * Returns 0 if metadata is null or has no citations.
+ */
+declare function countCitations(metadata: MessageMetadataPayload | null): number;
+/**
+ * Convert citation markdown to plain text with superscript-style numbers.
+ * Replaces `[text](#cite-N)` with `text[N]`.
+ */
+declare function stripCitationMarkdown(text: string): string;
+
 /**
  * Document operations — browser-safe functions.
  *
@@ -907,7 +982,7 @@ interface QueryOptions {
     /** Called when a user message event is received */
     onUserMessage?: (data: UserMessageEvent) => void;
     /** Called when message metadata is received */
-    onMetadata?: (data: MessageMetadataPayload) => void;
+    onMetadata?: (data: MessageMetadataPayload$1) => void;
     /** Called when the agent requests user input */
     onUserInputRequest?: (data: UserInputRequestEvent) => void;
     /** Called when an artifact event is received */
@@ -3231,4 +3306,4 @@ declare namespace responses {
   export { type responses_SubmitBackgroundQueryOptions as SubmitBackgroundQueryOptions, responses_extractResponseText as extractResponseText, responses_getResponse as getResponse, responses_submitBackgroundQuery as submitBackgroundQuery };
 }
 
-export { connectWithReconnect as $, type AuthHeaders as A, type SSEStreamCallbacks as B, type ConfigStore as C, type DocumentWaiter as D, type SSEStreamResult as E, type FormattedWsMessage as F, type SSEStreamStartData as G, type UserInfo as H, type UserInputRequestEvent as I, type UserMessageEvent as J, type WsConnection as K, LIFECYCLE_LABELS as L, type MessageLevel as M, agentconfig as N, type OutputTokensDetails as O, assistant as P, type QueryOptions as Q, type ReconnectOptions as R, type SSEEvent as S, TOOL_LABELS as T, type UploadBatchResult as U, authenticatedFetch as V, type WorkspaceContext as W, buildRetrievalChunkTool as X, buildRetrievalFullContextTool as Y, buildRetrievalTocTool as Z, connectWebSocket as _, type CliConfig as a, consumeSSEStream as a0, contacts as a1, conversations as a2, createAuthenticatedClient as a3, createDocumentWaiter as a4, dm as a5, doctags as a6, documents as a7, files as a8, formatAgentStepLabel as a9, formatFileSize as aa, formatUserName as ab, formatWorkspaceChoices as ac, formatWsMessage as ad, generateEncryptedWorkspaceKey as ae, getErrorCode as af, getErrorMessage as ag, health as ah, parseSSEEvents as ai, performPasswordLogin as aj, requireData as ak, requireOk as al, resolveAuth as am, resolveWorkspace as an, responses as ao, selectWorkspace as ap, selectWorkspaceById as aq, settings as ar, streamSSE as as, tags as at, workspaces as au, type CliCredentials as b, type ChatSession as c, type UploadOptions as d, type UploadResult as e, type AgentStepEvent as f, Arbi as g, ArbiApiError as h, ArbiError as i, type ArbiOptions as j, type ArtifactEvent as k, type AuthContext as l, type AuthenticatedClient as m, type ConnectOptions as n, type DocumentWaiterOptions as o, type MessageMetadataPayload as p, type ReconnectableWsConnection as q, type ResponseCompletedEvent as r, type ResponseContentPartAddedEvent as s, type ResponseCreatedEvent as t, type ResponseFailedEvent as u, type ResponseOutputItemAddedEvent as v, type ResponseOutputItemDoneEvent as w, type ResponseOutputTextDeltaEvent as x, type ResponseOutputTextDoneEvent as y, type ResponseUsage as z };
+export { buildRetrievalFullContextTool as $, type AuthHeaders as A, type ResponseOutputTextDeltaEvent as B, type ConfigStore as C, type DocumentWaiter as D, type ResponseOutputTextDoneEvent as E, type FormattedWsMessage as F, type ResponseUsage as G, type SSEStreamCallbacks as H, type SSEStreamResult as I, type SSEStreamStartData as J, type UserInfo as K, LIFECYCLE_LABELS as L, type MessageLevel as M, type UserInputRequestEvent as N, type OutputTokensDetails as O, type UserMessageEvent as P, type QueryOptions as Q, type ReconnectOptions as R, type SSEEvent as S, TOOL_LABELS as T, type UploadBatchResult as U, type WsConnection as V, type WorkspaceContext as W, agentconfig as X, assistant as Y, authenticatedFetch as Z, buildRetrievalChunkTool as _, type CliConfig as a, buildRetrievalTocTool as a0, connectWebSocket as a1, connectWithReconnect as a2, consumeSSEStream as a3, contacts as a4, conversations as a5, countCitations as a6, createAuthenticatedClient as a7, createDocumentWaiter as a8, dm as a9, summarizeCitations as aA, tags as aB, workspaces as aC, doctags as aa, documents as ab, files as ac, formatAgentStepLabel as ad, formatFileSize as ae, formatStreamSummary as af, formatUserName as ag, formatWorkspaceChoices as ah, formatWsMessage as ai, generateEncryptedWorkspaceKey as aj, getErrorCode as ak, getErrorMessage as al, health as am, parseSSEEvents as an, performPasswordLogin as ao, requireData as ap, requireOk as aq, resolveAuth as ar, resolveCitations as as, resolveWorkspace as at, responses as au, selectWorkspace as av, selectWorkspaceById as aw, settings as ax, streamSSE as ay, stripCitationMarkdown as az, type CliCredentials as b, type ChatSession as c, type UploadOptions as d, type UploadResult as e, type AgentStepEvent as f, Arbi as g, ArbiApiError as h, ArbiError as i, type ArbiOptions as j, type ArtifactEvent as k, type AuthContext as l, type AuthenticatedClient as m, type CitationSummary as n, type ConnectOptions as o, type DocumentWaiterOptions as p, type MessageMetadataPayload$1 as q, type MessageQueuedEvent as r, type ReconnectableWsConnection as s, type ResolvedCitation as t, type ResponseCompletedEvent as u, type ResponseContentPartAddedEvent as v, type ResponseCreatedEvent as w, type ResponseFailedEvent as x, type ResponseOutputItemAddedEvent as y, type ResponseOutputItemDoneEvent as z };

package/dist/{browser-DnGux0ct.d.ts → browser-BtAHbiq_.d.ts}

@@ -114,6 +114,10 @@ interface ConfigStore {
     saveChatSession(session: ChatSession): void;
     updateChatSession(updates: Partial<ChatSession>): void;
     clearChatSession(): void;
+    /** Persist last response metadata for citation browsing (optional). */
+    saveLastMetadata?(metadata: unknown): void;
+    /** Load last response metadata for citation browsing (optional). */
+    loadLastMetadata?(): unknown | null;
 }
 
 /**
@@ -218,7 +222,8 @@ type AgentStepEvent = components['schemas']['AgentStepEvent'];
 type UserInputRequestEvent = components['schemas']['UserInputRequestEvent'];
 type ArtifactEvent = components['schemas']['ArtifactEvent'];
 type UserMessageEvent = components['schemas']['UserMessageEvent'];
-type MessageMetadataPayload = components['schemas']['MessageMetadataPayload'];
+type MessageQueuedEvent = components['schemas']['MessageQueuedEvent'];
+type MessageMetadataPayload$1 = components['schemas']['MessageMetadataPayload'];
 type ResponseUsage = components['schemas']['ResponseUsage'];
 type OutputTokensDetails = components['schemas']['OutputTokensDetails'];
 type TokenBudgetContext = components['schemas']['TokenBudgetContext'];
@@ -273,8 +278,9 @@ interface SSEStreamCallbacks {
     onContentPartAdded?: (data: ResponseContentPartAddedEvent) => void;
     onAgentStep?: (data: AgentStepEvent) => void;
     onError?: (message: string) => void;
+    onMessageQueued?: (data: MessageQueuedEvent) => void;
     onUserMessage?: (data: UserMessageEvent) => void;
-    onMetadata?: (data: MessageMetadataPayload) => void;
+    onMetadata?: (data: MessageMetadataPayload$1) => void;
     onUserInputRequest?: (data: UserInputRequestEvent) => void;
     onArtifact?: (data: ArtifactEvent) => void;
     onElapsedTime?: (t: number) => void;
@@ -292,7 +298,7 @@ interface SSEStreamResult {
     toolCallCount: number;
     errors: string[];
     userMessage: UserMessageEvent | null;
-    metadata: MessageMetadataPayload | null;
+    metadata: MessageMetadataPayload$1 | null;
     artifacts: ArtifactEvent[];
     usage: ResponseUsage | null;
     /** Token budget context snapshot from response.completed. */
@@ -308,6 +314,15 @@ interface SSEStreamResult {
  * both the streaming callbacks and the final result.
  */
 declare function streamSSE(response: Response, callbacks?: SSEStreamCallbacks): Promise<SSEStreamResult>;
+/**
+ * Format a human-readable summary line from a completed SSE stream result.
+ *
+ * Returns a string like:
+ *   "3 steps (2 tool calls) · 1,234 tokens · 500/8,000 context · 2.5s"
+ *
+ * Returns empty string if there's nothing to report.
+ */
+declare function formatStreamSummary(result: SSEStreamResult, elapsedTime?: number | null): string;
 /**
  * Consume an entire SSE stream without streaming callbacks.
  * Convenience alias for `streamSSE(response)`.
@@ -424,6 +439,66 @@ type UserInfo = {
  */
 declare function formatUserName(user: UserInfo | null | undefined): string;
 
+/**
+ * Citation resolution utilities — shared by CLI and TUI.
+ *
+ * Parses citation data from SSE metadata (`MessageMetadataPayload`) and
+ * resolves chunk references into displayable citation summaries and passages.
+ *
+ * Citation data flow:
+ *   1. `tools.model_citations.tool_responses` maps citation number → CitationData
+ *      (contains chunk_ids, statement, offsets)
+ *   2. `tools.retrieval_chunk.tool_responses` and `tools.retrieval_full_context.tool_responses`
+ *      map document file name → Chunk[] (contains content and metadata)
+ *   3. This module joins those two data sets to produce resolved citations.
+ */
+
+type MessageMetadataPayload = components['schemas']['MessageMetadataPayload'];
+type CitationData$2 = components['schemas']['CitationData'];
+type Chunk$1 = components['schemas']['Chunk'];
+/** A fully resolved citation with its source chunks. */
+interface ResolvedCitation {
+    /** Citation number as a string (e.g. "1", "2") */
+    citationNum: string;
+    /** Raw citation data from model_citations */
+    citationData: CitationData$2;
+    /** Resolved chunks matching the citation's chunk_ids */
+    chunks: Chunk$1[];
+}
+/** A compact citation summary for display in lists. */
+interface CitationSummary {
+    citationNum: string;
+    statement: string;
+    docTitle: string;
+    pageNumber: number | null;
+    chunkCount: number;
+}
+/**
+ * Resolve all citations from SSE metadata into full citation objects.
+ *
+ * Reads `tools.model_citations.tool_responses` for citation→chunk_id mappings,
+ * then builds a chunk lookup from `retrieval_chunk` and `retrieval_full_context`
+ * tool responses to resolve each chunk_id to its full Chunk object.
+ *
+ * Returns citations sorted by citation number (ascending).
+ */
+declare function resolveCitations(metadata: MessageMetadataPayload | null): ResolvedCitation[];
+/**
+ * Produce compact summaries for display in citation lists.
+ * Uses the first chunk of each citation for doc title and page number.
+ */
+declare function summarizeCitations(resolved: ResolvedCitation[]): CitationSummary[];
+/**
+ * Count the number of citations in metadata.
+ * Returns 0 if metadata is null or has no citations.
+ */
+declare function countCitations(metadata: MessageMetadataPayload | null): number;
+/**
+ * Convert citation markdown to plain text with superscript-style numbers.
+ * Replaces `[text](#cite-N)` with `text[N]`.
+ */
+declare function stripCitationMarkdown(text: string): string;
+
 /**
  * Document operations — browser-safe functions.
  *
@@ -907,7 +982,7 @@ interface QueryOptions {
     /** Called when a user message event is received */
     onUserMessage?: (data: UserMessageEvent) => void;
     /** Called when message metadata is received */
-    onMetadata?: (data: MessageMetadataPayload) => void;
+    onMetadata?: (data: MessageMetadataPayload$1) => void;
     /** Called when the agent requests user input */
     onUserInputRequest?: (data: UserInputRequestEvent) => void;
     /** Called when an artifact event is received */
@@ -3231,4 +3306,4 @@ declare namespace responses {
   export { type responses_SubmitBackgroundQueryOptions as SubmitBackgroundQueryOptions, responses_extractResponseText as extractResponseText, responses_getResponse as getResponse, responses_submitBackgroundQuery as submitBackgroundQuery };
 }
 
-export { connectWithReconnect as $, type AuthHeaders as A, type SSEStreamCallbacks as B, type ConfigStore as C, type DocumentWaiter as D, type SSEStreamResult as E, type FormattedWsMessage as F, type SSEStreamStartData as G, type UserInfo as H, type UserInputRequestEvent as I, type UserMessageEvent as J, type WsConnection as K, LIFECYCLE_LABELS as L, type MessageLevel as M, agentconfig as N, type OutputTokensDetails as O, assistant as P, type QueryOptions as Q, type ReconnectOptions as R, type SSEEvent as S, TOOL_LABELS as T, type UploadBatchResult as U, authenticatedFetch as V, type WorkspaceContext as W, buildRetrievalChunkTool as X, buildRetrievalFullContextTool as Y, buildRetrievalTocTool as Z, connectWebSocket as _, type CliConfig as a, consumeSSEStream as a0, contacts as a1, conversations as a2, createAuthenticatedClient as a3, createDocumentWaiter as a4, dm as a5, doctags as a6, documents as a7, files as a8, formatAgentStepLabel as a9, formatFileSize as aa, formatUserName as ab, formatWorkspaceChoices as ac, formatWsMessage as ad, generateEncryptedWorkspaceKey as ae, getErrorCode as af, getErrorMessage as ag, health as ah, parseSSEEvents as ai, performPasswordLogin as aj, requireData as ak, requireOk as al, resolveAuth as am, resolveWorkspace as an, responses as ao, selectWorkspace as ap, selectWorkspaceById as aq, settings as ar, streamSSE as as, tags as at, workspaces as au, type CliCredentials as b, type ChatSession as c, type UploadOptions as d, type UploadResult as e, type AgentStepEvent as f, Arbi as g, ArbiApiError as h, ArbiError as i, type ArbiOptions as j, type ArtifactEvent as k, type AuthContext as l, type AuthenticatedClient as m, type ConnectOptions as n, type DocumentWaiterOptions as o, type MessageMetadataPayload as p, type ReconnectableWsConnection as q, type ResponseCompletedEvent as r, type ResponseContentPartAddedEvent as s, type ResponseCreatedEvent as t, type ResponseFailedEvent as u, type ResponseOutputItemAddedEvent as v, type ResponseOutputItemDoneEvent as w, type ResponseOutputTextDeltaEvent as x, type ResponseOutputTextDoneEvent as y, type ResponseUsage as z };
+export { buildRetrievalFullContextTool as $, type AuthHeaders as A, type ResponseOutputTextDeltaEvent as B, type ConfigStore as C, type DocumentWaiter as D, type ResponseOutputTextDoneEvent as E, type FormattedWsMessage as F, type ResponseUsage as G, type SSEStreamCallbacks as H, type SSEStreamResult as I, type SSEStreamStartData as J, type UserInfo as K, LIFECYCLE_LABELS as L, type MessageLevel as M, type UserInputRequestEvent as N, type OutputTokensDetails as O, type UserMessageEvent as P, type QueryOptions as Q, type ReconnectOptions as R, type SSEEvent as S, TOOL_LABELS as T, type UploadBatchResult as U, type WsConnection as V, type WorkspaceContext as W, agentconfig as X, assistant as Y, authenticatedFetch as Z, buildRetrievalChunkTool as _, type CliConfig as a, buildRetrievalTocTool as a0, connectWebSocket as a1, connectWithReconnect as a2, consumeSSEStream as a3, contacts as a4, conversations as a5, countCitations as a6, createAuthenticatedClient as a7, createDocumentWaiter as a8, dm as a9, summarizeCitations as aA, tags as aB, workspaces as aC, doctags as aa, documents as ab, files as ac, formatAgentStepLabel as ad, formatFileSize as ae, formatStreamSummary as af, formatUserName as ag, formatWorkspaceChoices as ah, formatWsMessage as ai, generateEncryptedWorkspaceKey as aj, getErrorCode as ak, getErrorMessage as al, health as am, parseSSEEvents as an, performPasswordLogin as ao, requireData as ap, requireOk as aq, resolveAuth as ar, resolveCitations as as, resolveWorkspace as at, responses as au, selectWorkspace as av, selectWorkspaceById as aw, settings as ax, streamSSE as ay, stripCitationMarkdown as az, type CliCredentials as b, type ChatSession as c, type UploadOptions as d, type UploadResult as e, type AgentStepEvent as f, Arbi as g, ArbiApiError as h, ArbiError as i, type ArbiOptions as j, type ArtifactEvent as k, type AuthContext as l, type AuthenticatedClient as m, type CitationSummary as n, type ConnectOptions as o, type DocumentWaiterOptions as p, type MessageMetadataPayload$1 as q, type MessageQueuedEvent as r, type ReconnectableWsConnection as s, type ResolvedCitation as t, type ResponseCompletedEvent as u, type ResponseContentPartAddedEvent as v, type ResponseCreatedEvent as w, type ResponseFailedEvent as x, type ResponseOutputItemAddedEvent as y, type ResponseOutputItemDoneEvent as z };

package/dist/browser.cjs

@@ -389,6 +389,14 @@ async function streamSSE(response, callbacks = {}) {
       callbacks.onError?.(message);
     },
     // ARBI-specific events (dot-prefixed from server)
+    "arbi.message_queued": (raw) => {
+      const data = JSON.parse(raw);
+      if (data.user_message) {
+        userMessage = data.user_message;
+        callbacks.onUserMessage?.(data.user_message);
+      }
+      callbacks.onMessageQueued?.(data);
+    },
     "arbi.agent_step": (raw) => {
       const data = JSON.parse(raw);
       const label = formatAgentStepLabel(data);
@@ -574,6 +582,66 @@ function formatUserName(user) {
   return [user.given_name, user.family_name].filter(Boolean).join(" ");
 }
 
+// src/citations.ts
+function resolveCitations(metadata) {
+  if (!metadata?.tools) return [];
+  const tools = metadata.tools;
+  const modelCitations = tools.model_citations;
+  const citationMap = modelCitations?.tool_responses;
+  if (!citationMap || Object.keys(citationMap).length === 0) return [];
+  const chunkLookup = buildChunkLookup(tools);
+  const resolved = [];
+  for (const [citationNum, citationData] of Object.entries(citationMap)) {
+    const chunks = [];
+    for (const chunkId of citationData.chunk_ids ?? []) {
+      const chunk = chunkLookup.get(chunkId);
+      if (chunk) chunks.push(chunk);
+    }
+    resolved.push({ citationNum, citationData, chunks });
+  }
+  resolved.sort((a, b) => Number(a.citationNum) - Number(b.citationNum));
+  return resolved;
+}
+function summarizeCitations(resolved) {
+  return resolved.map((r) => {
+    const firstChunk = r.chunks[0];
+    return {
+      citationNum: r.citationNum,
+      statement: r.citationData.statement ?? "",
+      docTitle: firstChunk?.metadata?.doc_title ?? "Unknown document",
+      pageNumber: firstChunk?.metadata?.page_number ?? null,
+      chunkCount: r.chunks.length
+    };
+  });
+}
+function countCitations(metadata) {
+  if (!metadata?.tools) return 0;
+  const tools = metadata.tools;
+  const modelCitations = tools.model_citations;
+  const responses = modelCitations?.tool_responses;
+  return responses ? Object.keys(responses).length : 0;
+}
+function stripCitationMarkdown(text) {
+  return text.replace(/\[([^\]]+)\]\(#cite-(\d+)\)/g, "$1[$2]");
+}
+function buildChunkLookup(tools) {
+  const lookup = /* @__PURE__ */ new Map();
+  for (const toolName of ["retrieval_chunk", "retrieval_full_context"]) {
+    const tool = tools[toolName];
+    if (!tool?.tool_responses) continue;
+    for (const chunks of Object.values(tool.tool_responses)) {
+      if (!Array.isArray(chunks)) continue;
+      for (const chunk of chunks) {
+        const id = chunk.metadata?.chunk_ext_id;
+        if (id && !lookup.has(id)) {
+          lookup.set(id, chunk);
+        }
+      }
+    }
+  }
+  return lookup;
+}
+
 // src/operations/documents.ts
 var documents_exports = {};
 __export(documents_exports, {
@@ -1271,6 +1339,19 @@ var Arbi = class {
       lr.serverSessionKey,
       signingPrivateKeyBase64
     );
+    const workspaceKeyHeader = client.session.getWorkspaceKeyHeader();
+    if (workspaceKeyHeader) {
+      const { data: openResult, error: openError } = await client.fetch.POST(
+        "/v1/workspace/{workspace_ext_id}/open",
+        {
+          params: { path: { workspace_ext_id: ws.external_id } },
+          body: { workspace_key: workspaceKeyHeader }
+        }
+      );
+      if (!openError && openResult?.access_token) {
+        client.session.setAccessToken(openResult.access_token);
+      }
+    }
     this.currentWorkspaceId = ws.external_id;
   }
   /** Log out and clear internal state. */
@@ -1571,6 +1652,7 @@ exports.connectWithReconnect = connectWithReconnect;
 exports.consumeSSEStream = consumeSSEStream;
 exports.contacts = contacts_exports;
 exports.conversations = conversations_exports;
+exports.countCitations = countCitations;
 exports.createAuthenticatedClient = createAuthenticatedClient;
 exports.dm = dm_exports;
 exports.doctags = doctags_exports;
@@ -1587,12 +1669,15 @@ exports.performPasswordLogin = performPasswordLogin;
 exports.requireData = requireData;
 exports.requireOk = requireOk;
 exports.resolveAuth = resolveAuth;
+exports.resolveCitations = resolveCitations;
 exports.resolveWorkspace = resolveWorkspace;
 exports.responses = responses_exports;
 exports.selectWorkspace = selectWorkspace;
 exports.selectWorkspaceById = selectWorkspaceById;
 exports.settings = settings_exports;
 exports.streamSSE = streamSSE;
+exports.stripCitationMarkdown = stripCitationMarkdown;
+exports.summarizeCitations = summarizeCitations;
 exports.tags = tags_exports;
 exports.workspaces = workspaces_exports;
 //# sourceMappingURL=browser.cjs.map