@arbidocs/sdk 0.3.16 → 0.3.18

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-DFRwcoc1.d.cts → browser-DUQ3Eyvd.d.cts}

@@ -92,6 +92,8 @@ interface CliCredentials {
     workspaceId?: string;
     /** ISO timestamp when the token was cached */
     tokenTimestamp?: string;
+    /** Auth0 SSO token — needed for session recovery of SSO users */
+    ssoToken?: string;
 }
 interface ChatSession {
     /** Last assistant message ID — used as previous_response_id for follow-ups */
@@ -114,6 +116,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;
 }
 
 /**
@@ -169,6 +175,17 @@ declare function createAuthenticatedClient(config: CliConfig, creds: CliCredenti
  * use createAuthenticatedClient() instead.
  */
 declare function performPasswordLogin(config: CliConfig, email: string, password: string, store: ConfigStore): Promise<AuthContext>;
+/**
+ * SSO device-flow login (RFC 8628).
+ *
+ * Fetches SSO config from the deployment, initiates the device authorization
+ * flow with Auth0, waits for the user to authorize in a browser, then logs
+ * in to the ARBI deployment using the Auth0 JWT.
+ */
+declare function performSsoDeviceFlowLogin(config: CliConfig, email: string, password: string, store: ConfigStore, callbacks?: {
+    onUserCode?: (userCode: string, verificationUri: string) => void;
+    onPoll?: (elapsedMs: number) => void;
+}): Promise<AuthContext>;
 /**
  * Decrypt wrapped workspace key and set it as the active workspace header.
  */
@@ -219,7 +236,7 @@ type UserInputRequestEvent = components['schemas']['UserInputRequestEvent'];
 type ArtifactEvent = components['schemas']['ArtifactEvent'];
 type UserMessageEvent = components['schemas']['UserMessageEvent'];
 type MessageQueuedEvent = components['schemas']['MessageQueuedEvent'];
-type MessageMetadataPayload = components['schemas']['MessageMetadataPayload'];
+type MessageMetadataPayload$1 = components['schemas']['MessageMetadataPayload'];
 type ResponseUsage = components['schemas']['ResponseUsage'];
 type OutputTokensDetails = components['schemas']['OutputTokensDetails'];
 type TokenBudgetContext = components['schemas']['TokenBudgetContext'];
@@ -276,7 +293,7 @@ interface SSEStreamCallbacks {
     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;
@@ -294,7 +311,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. */
@@ -310,6 +327,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)`.
@@ -426,6 +452,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.
  *
@@ -909,7 +995,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 */
@@ -3233,4 +3319,4 @@ declare namespace responses {
   export { type responses_SubmitBackgroundQueryOptions as SubmitBackgroundQueryOptions, responses_extractResponseText as extractResponseText, responses_getResponse as getResponse, responses_submitBackgroundQuery as submitBackgroundQuery };
 }
 
-export { connectWebSocket as $, type AuthHeaders as A, type ResponseUsage as B, type ConfigStore as C, type DocumentWaiter as D, type SSEStreamCallbacks as E, type FormattedWsMessage as F, type SSEStreamResult as G, type SSEStreamStartData as H, type UserInfo as I, type UserInputRequestEvent as J, type UserMessageEvent as K, LIFECYCLE_LABELS as L, type MessageLevel as M, type WsConnection as N, type OutputTokensDetails as O, agentconfig as P, type QueryOptions as Q, type ReconnectOptions as R, type SSEEvent as S, TOOL_LABELS as T, type UploadBatchResult as U, assistant as V, type WorkspaceContext as W, authenticatedFetch as X, buildRetrievalChunkTool as Y, buildRetrievalFullContextTool as Z, buildRetrievalTocTool as _, type CliConfig as a, connectWithReconnect as a0, consumeSSEStream as a1, contacts as a2, conversations as a3, createAuthenticatedClient as a4, createDocumentWaiter as a5, dm as a6, doctags as a7, documents as a8, files as a9, formatAgentStepLabel as aa, formatFileSize as ab, formatUserName as ac, formatWorkspaceChoices as ad, formatWsMessage as ae, generateEncryptedWorkspaceKey as af, getErrorCode as ag, getErrorMessage as ah, health as ai, parseSSEEvents as aj, performPasswordLogin as ak, requireData as al, requireOk as am, resolveAuth as an, resolveWorkspace as ao, responses as ap, selectWorkspace as aq, selectWorkspaceById as ar, settings as as, streamSSE as at, tags as au, workspaces as av, 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 MessageQueuedEvent as q, type ReconnectableWsConnection as r, type ResponseCompletedEvent as s, type ResponseContentPartAddedEvent as t, type ResponseCreatedEvent as u, type ResponseFailedEvent as v, type ResponseOutputItemAddedEvent as w, type ResponseOutputItemDoneEvent as x, type ResponseOutputTextDeltaEvent as y, type ResponseOutputTextDoneEvent 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, stripCitationMarkdown as aA, summarizeCitations as aB, tags as aC, workspaces as aD, 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, performSsoDeviceFlowLogin as ap, requireData as aq, requireOk as ar, resolveAuth as as, resolveCitations as at, resolveWorkspace as au, responses as av, selectWorkspace as aw, selectWorkspaceById as ax, settings as ay, streamSSE 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-DFRwcoc1.d.ts → browser-DUQ3Eyvd.d.ts}

@@ -92,6 +92,8 @@ interface CliCredentials {
     workspaceId?: string;
     /** ISO timestamp when the token was cached */
     tokenTimestamp?: string;
+    /** Auth0 SSO token — needed for session recovery of SSO users */
+    ssoToken?: string;
 }
 interface ChatSession {
     /** Last assistant message ID — used as previous_response_id for follow-ups */
@@ -114,6 +116,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;
 }
 
 /**
@@ -169,6 +175,17 @@ declare function createAuthenticatedClient(config: CliConfig, creds: CliCredenti
  * use createAuthenticatedClient() instead.
  */
 declare function performPasswordLogin(config: CliConfig, email: string, password: string, store: ConfigStore): Promise<AuthContext>;
+/**
+ * SSO device-flow login (RFC 8628).
+ *
+ * Fetches SSO config from the deployment, initiates the device authorization
+ * flow with Auth0, waits for the user to authorize in a browser, then logs
+ * in to the ARBI deployment using the Auth0 JWT.
+ */
+declare function performSsoDeviceFlowLogin(config: CliConfig, email: string, password: string, store: ConfigStore, callbacks?: {
+    onUserCode?: (userCode: string, verificationUri: string) => void;
+    onPoll?: (elapsedMs: number) => void;
+}): Promise<AuthContext>;
 /**
  * Decrypt wrapped workspace key and set it as the active workspace header.
  */
@@ -219,7 +236,7 @@ type UserInputRequestEvent = components['schemas']['UserInputRequestEvent'];
 type ArtifactEvent = components['schemas']['ArtifactEvent'];
 type UserMessageEvent = components['schemas']['UserMessageEvent'];
 type MessageQueuedEvent = components['schemas']['MessageQueuedEvent'];
-type MessageMetadataPayload = components['schemas']['MessageMetadataPayload'];
+type MessageMetadataPayload$1 = components['schemas']['MessageMetadataPayload'];
 type ResponseUsage = components['schemas']['ResponseUsage'];
 type OutputTokensDetails = components['schemas']['OutputTokensDetails'];
 type TokenBudgetContext = components['schemas']['TokenBudgetContext'];
@@ -276,7 +293,7 @@ interface SSEStreamCallbacks {
     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;
@@ -294,7 +311,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. */
@@ -310,6 +327,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)`.
@@ -426,6 +452,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.
  *
@@ -909,7 +995,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 */
@@ -3233,4 +3319,4 @@ declare namespace responses {
   export { type responses_SubmitBackgroundQueryOptions as SubmitBackgroundQueryOptions, responses_extractResponseText as extractResponseText, responses_getResponse as getResponse, responses_submitBackgroundQuery as submitBackgroundQuery };
 }
 
-export { connectWebSocket as $, type AuthHeaders as A, type ResponseUsage as B, type ConfigStore as C, type DocumentWaiter as D, type SSEStreamCallbacks as E, type FormattedWsMessage as F, type SSEStreamResult as G, type SSEStreamStartData as H, type UserInfo as I, type UserInputRequestEvent as J, type UserMessageEvent as K, LIFECYCLE_LABELS as L, type MessageLevel as M, type WsConnection as N, type OutputTokensDetails as O, agentconfig as P, type QueryOptions as Q, type ReconnectOptions as R, type SSEEvent as S, TOOL_LABELS as T, type UploadBatchResult as U, assistant as V, type WorkspaceContext as W, authenticatedFetch as X, buildRetrievalChunkTool as Y, buildRetrievalFullContextTool as Z, buildRetrievalTocTool as _, type CliConfig as a, connectWithReconnect as a0, consumeSSEStream as a1, contacts as a2, conversations as a3, createAuthenticatedClient as a4, createDocumentWaiter as a5, dm as a6, doctags as a7, documents as a8, files as a9, formatAgentStepLabel as aa, formatFileSize as ab, formatUserName as ac, formatWorkspaceChoices as ad, formatWsMessage as ae, generateEncryptedWorkspaceKey as af, getErrorCode as ag, getErrorMessage as ah, health as ai, parseSSEEvents as aj, performPasswordLogin as ak, requireData as al, requireOk as am, resolveAuth as an, resolveWorkspace as ao, responses as ap, selectWorkspace as aq, selectWorkspaceById as ar, settings as as, streamSSE as at, tags as au, workspaces as av, 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 MessageQueuedEvent as q, type ReconnectableWsConnection as r, type ResponseCompletedEvent as s, type ResponseContentPartAddedEvent as t, type ResponseCreatedEvent as u, type ResponseFailedEvent as v, type ResponseOutputItemAddedEvent as w, type ResponseOutputItemDoneEvent as x, type ResponseOutputTextDeltaEvent as y, type ResponseOutputTextDoneEvent 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, stripCitationMarkdown as aA, summarizeCitations as aB, tags as aC, workspaces as aD, 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, performSsoDeviceFlowLogin as ap, requireData as aq, requireOk as ar, resolveAuth as as, resolveCitations as at, resolveWorkspace as au, responses as av, selectWorkspace as aw, selectWorkspaceById as ax, settings as ay, streamSSE 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

@@ -98,6 +98,8 @@ async function authenticatedFetch(options) {
   }
   return res;
 }
+
+// src/auth.ts
 function formatWorkspaceChoices(wsList) {
   return wsList.map((ws) => {
     const totalDocs = ws.shared_document_count + ws.private_document_count;
@@ -118,7 +120,8 @@ async function createAuthenticatedClient(config, creds, store) {
   const signingPrivateKey = client.base64ToBytes(creds.signingPrivateKeyBase64);
   const loginResult = await arbi.auth.loginWithKey({
     email: creds.email,
-    signingPrivateKey
+    signingPrivateKey,
+    ssoToken: creds.ssoToken
   });
   store.saveCredentials({
     ...creds,
@@ -582,6 +585,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, {
@@ -1279,6 +1342,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. */
@@ -1579,6 +1655,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;
@@ -1595,12 +1672,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