@arbidocs/sdk 0.5.80 → 0.5.82

package/README.md

@@ -137,6 +137,18 @@ workspace cannot be opened, nothing is sent and the call rejects with
 `ArbiWorkspaceUnavailableError`. `workspaceConflictOf(error)` reads either 409.
 `assistant.submit` and `assistant.retrieve` take `workspaceId` the same way.
 
+### Which workspace other calls act in
+
+Facts (`facts.create`, `createBatch`, `list`, `search`), conversations
+(`conversations.list`, `search`, `createWork`, `plan`), `assistant.listSkills`,
+`files.list` and `files.upload` act in the current workspace, or in the `workspaceId`
+option they are given, which is opened for this session first without becoming current.
+Either way the request names the workspace (`workspace_ext_id`), so a switch while it is
+sent cannot move it. A note, a task or a conversation changed by id is changed in its own
+workspace, which the server derives from it. A refusal for the workspace (409
+`workspace_key_required`, or `workspace_mismatch` for a sub-task whose parent is in
+another workspace) is an `ArbiApiError` with that `code`, saying nothing was saved.
+
 ## Session recovery
 
 Browsers persist the signing key encrypted in IndexedDB. Without IndexedDB, each SDK client keeps its own key in memory; it is not shared with other instances or saved to disk. Recover a session without a password:

package/dist/{browser-CP0e4GnL.d.cts → browser-4oIgAqs1.d.cts}

@@ -2922,8 +2922,11 @@ type AssistantMode = components['schemas']['AssistantMode'];
 type ConversationSearchRequest = components['schemas']['ConversationSearchRequest'];
 type ConversationSearchResponse = components['schemas']['ConversationSearchResponse'];
 
-/** The caller's conversations. A conversation with a `status` is also a task (work item). */
-declare function listConversations(arbi: ArbiClient): Promise<{
+/**
+ * The caller's conversations in `workspaceExtId` (absent: the session's open workspace). A
+ * conversation with a `status` is also a task (work item).
+ */
+declare function listConversations(arbi: ArbiClient, workspaceExtId?: string | null): Promise<{
     label_ext_ids?: string[] | undefined;
     external_id: string;
     title: string | null;
@@ -3067,15 +3070,14 @@ declare function listConversations(arbi: ArbiClient): Promise<{
     is_owner: boolean;
 }[]>;
 /**
- * Import a conversation export into the active workspace.
+ * Import a conversation export into `workspaceExtId` (absent: the session's open workspace).
  *
  * Accepts a ChatGPT data export (`conversations.json`), an OpenClaw session log, or a
  * Claude Code transcript (`.jsonl`); `source='auto'` lets the server detect the format.
  * Uses raw multipart fetch (the typed client can't express file uploads), mirroring
- * `files.uploadFile`. The active workspace + cipher are resolved server-side from the
- * session, so no extra header is needed.
+ * `files.uploadFile`.
  */
-declare function importConversations(auth: AuthHeaders, fileData: Blob, fileName: string, source?: string): Promise<ConversationImportResponse>;
+declare function importConversations(auth: AuthHeaders, fileData: Blob, fileName: string, source?: string, workspaceExtId?: string | null): Promise<ConversationImportResponse>;
 declare function getConversationThreads(arbi: ArbiClient, conversationId: string): Promise<{
     conversation_ext_id: string;
     threads: {
@@ -3284,8 +3286,11 @@ declare function getConversationThreads(arbi: ArbiClient, conversationId: string
 declare function deleteConversation(arbi: ArbiClient, conversationId: string): Promise<{
     detail: string;
 }>;
-/** Keyword + semantic search over the open workspace's past conversation messages, grouped. */
-declare function searchConversations(arbi: ArbiClient, body: ConversationSearchRequest): Promise<ConversationSearchResponse>;
+/**
+ * Keyword + semantic search over the past conversation messages of `workspaceExtId` (absent: the
+ * session's open workspace), grouped.
+ */
+declare function searchConversations(arbi: ArbiClient, body: ConversationSearchRequest, workspaceExtId?: string | null): Promise<ConversationSearchResponse>;
 declare function getMessage(arbi: ArbiClient, messageId: string): Promise<{
     role: "user" | "assistant" | "system";
     content: string;
@@ -3969,9 +3974,8 @@ type SkillSummary = components['schemas']['SkillSummaryResponse'];
  * never the SKILL.md body. To read the body, fetch the document via
  * ``getParsedContent(authHeaders, doc_ext_id, 'content')``.
  *
- * Scoped to the workspace the caller has open (the backend uses the
- * session's ``active_workspace``); cross-workspace listing isn't
- * supported because each workspace has its own encryption key.
+ * Without a deployment marketplace the skills are a workspace's: ``workspaceExtId``
+ * (its key must be on the session), else the session's open workspace.
  *
  * @param includeHidden  When ``true``, returns skills with
  *   ``user-invocable: false`` in their frontmatter. Off by default —
@@ -3980,6 +3984,8 @@ type SkillSummary = components['schemas']['SkillSummaryResponse'];
  */
 declare function listSkills(arbi: ArbiClient, options?: {
     includeHidden?: boolean;
+    /** The workspace whose skills back the list without a marketplace; absent: the open one. */
+    workspaceExtId?: string | null;
 }): Promise<SkillSummary[]>;
 /**
  * Whether a skill is the caller's own and shared with everyone (``global``), so saving it again
@@ -5207,6 +5213,8 @@ interface ListFilesOptions {
     limit?: number;
     order?: string;
     after?: string | null;
+    /** The workspace listed (its key must be on the session); absent: the session's open one. */
+    workspaceExtId?: string | null;
 }
 declare function listFiles(arbi: ArbiClient, options?: ListFilesOptions): Promise<{
     object: string;
@@ -5242,10 +5250,10 @@ declare function deleteFile(arbi: ArbiClient, fileId: string): Promise<{
     deleted: boolean;
 }>;
 /**
- * Upload a file via the OpenAI-compatible Files API.
- * Uses raw fetch for multipart upload.
+ * Upload a file via the OpenAI-compatible Files API into `workspaceExtId` (absent: the session's
+ * open workspace). Uses raw fetch for multipart upload.
  */
-declare function uploadFile(auth: AuthHeaders, fileData: Blob, fileName: string, purpose?: string): Promise<FileObject>;
+declare function uploadFile(auth: AuthHeaders, fileData: Blob, fileName: string, purpose?: string, workspaceExtId?: string | null): Promise<FileObject>;
 /**
  * Get file content (binary). Returns the raw Response for the caller to handle.
  */
@@ -7404,8 +7412,11 @@ type AuthMode = components['schemas']['src__models__work__AuthMode'];
  * and rename.
  */
 declare function updateConversation(arbi: ArbiClient, conversationId: string, body: UpdateConversationRequest): Promise<ConversationResponse>;
-/** Create a work item. With a `prompt` / `skill_ref` the agent starts at once; otherwise a to-do. */
-declare function createWork(arbi: ArbiClient, body: CreateWorkRequest): Promise<ConversationResponse>;
+/**
+ * Create a work item in `workspaceExtId` (absent: the session's open workspace). With a `prompt` /
+ * `skill_ref` the agent starts at once; otherwise a to-do. A parent must be in the same workspace.
+ */
+declare function createWork(arbi: ArbiClient, body: CreateWorkRequest, workspaceExtId?: string | null): Promise<ConversationResponse>;
 /** Run a work item now (or retry). Not while a run is live. */
 declare function runConversation(arbi: ArbiClient, conversationId: string): Promise<ConversationResponse>;
 /** What an unattended run waits on (agent email + session public key); 404 when nothing waits. */
@@ -7440,8 +7451,11 @@ declare function getConversationUsage(arbi: ArbiClient, conversationId: string):
 declare function notifyConversation(arbi: ArbiClient, conversationId: string, userIds: string[]): Promise<string[]>;
 /** The task's history, oldest first: created, run started, handed off, sent back, done and so on. */
 declare function getActivity(arbi: ArbiClient, conversationId: string): Promise<ActivityResponse[]>;
-/** Draft an editable plan (goal and acceptance checklist) from a plain objective. */
-declare function planWork(arbi: ArbiClient, body: PlanWorkRequest): Promise<TaskPlan>;
+/**
+ * Draft an editable plan (goal and acceptance checklist) from a plain objective, for a task in
+ * `workspaceExtId` (absent: the session's open workspace).
+ */
+declare function planWork(arbi: ArbiClient, body: PlanWorkRequest, workspaceExtId?: string | null): Promise<TaskPlan>;
 /** A stepped run as it stands: its conversation, each step's phase, and what it waits for now. */
 interface RunProgress {
     conversation: ConversationResponse;
@@ -7568,8 +7582,9 @@ declare namespace workflows {
 /**
  * Workspace facts — per-workspace encrypted statements with citations.
  * The firm's practice profile / house style / precedent knowhow lives here (`/setup`
- * records it as ordinary facts) and is read by grounded agents. All endpoints
- * require an OPEN workspace.
+ * records it as ordinary facts) and is read by grounded agents. Create, list and search name
+ * their workspace (`workspaceExtId`; its key must be on the session); edit, delete and remind act
+ * in the fact's own workspace, which the server derives from the fact.
  * Backend: `/v1/facts` (src/api/v1/routers/facts.py).
  */
 
@@ -7594,16 +7609,17 @@ interface ListFactsOptions {
     limit?: number;
     /** Notes to skip, for paging with `limit`. */
     offset?: number;
+    /** The workspace listed (its key must be on the session); absent: the session's open one. */
+    workspaceExtId?: string | null;
 }
-/** Create a note. `content` is required; `shared` makes it workspace-wide. */
-declare function createFact(arbi: ArbiClient, body: CreateFactRequest): Promise<FactResponse>;
+/** Create a note in `workspaceExtId` (absent: the open one). `shared` makes it workspace-wide. */
+declare function createFact(arbi: ArbiClient, body: CreateFactRequest, workspaceExtId?: string | null): Promise<FactResponse>;
 /**
  * Create several notes in one all-or-nothing request (max 200). Prefer this to a loop of
  * {@link createFact} for an import: tags are resolved once and the notes are indexed in batches.
  * Results come back in request order.
  */
-declare function createFactsBatch(arbi: ArbiClient, body: CreateFactsRequest): Promise<FactResponse[]>;
-/** List the open workspace's notes (newest first). */
+declare function createFactsBatch(arbi: ArbiClient, body: CreateFactsRequest, workspaceExtId?: string | null): Promise<FactResponse[]>;
 /**
  * List notes. Passing a date range — or `datedOnly` — turns this into the
  * TIMELINE: only dated notes, ordered by when they happened rather than when
@@ -7616,8 +7632,8 @@ declare function createFactsBatch(arbi: ArbiClient, body: CreateFactsRequest): P
  * Narrow with `tagExtIds` / `docExtId` and page with `limit` / `offset`.
  */
 declare function listFacts(arbi: ArbiClient, options?: ListFactsOptions): Promise<FactResponse[]>;
-/** Semantic/keyword/hybrid search across the workspace's notes. */
-declare function searchFacts(arbi: ArbiClient, body: FactSearchRequest): Promise<FactSearchResponse>;
+/** Semantic/keyword/hybrid search across the notes of `workspaceExtId` (absent: the open one). */
+declare function searchFacts(arbi: ArbiClient, body: FactSearchRequest, workspaceExtId?: string | null): Promise<FactSearchResponse>;
 declare function updateFact(arbi: ArbiClient, factId: string, body: UpdateFactRequest): Promise<FactResponse>;
 declare function deleteFact(arbi: ArbiClient, factId: string): Promise<void>;
 /**
@@ -11247,7 +11263,10 @@ declare class Arbi {
         getThumbnails: (docIds: string[]) => Promise<Record<string, string | null>>;
     };
     readonly conversations: {
-        list: () => Promise<{
+        /** The current workspace's conversations, or `options.workspaceId`'s (opened, not switched to). */
+        list: (options?: {
+            workspaceId?: string;
+        }) => Promise<{
             label_ext_ids?: string[] | undefined;
             external_id: string;
             title: string | null;
@@ -11598,8 +11617,13 @@ declare class Arbi {
         delete: (conversationId: string) => Promise<{
             detail: string;
         }>;
-        /** Search the open workspace's past conversation messages (keyword + semantic), grouped. */
-        search: (body: ConversationSearchRequest) => Promise<{
+        /**
+         * Search the past conversation messages (keyword + semantic, grouped) of the current
+         * workspace, or `options.workspaceId` (opened for this session, not switched to).
+         */
+        search: (body: ConversationSearchRequest, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             query: string;
             search_mode: string;
             results: components["schemas"]["ConversationSearchGroup"][];
@@ -11655,8 +11679,14 @@ declare class Arbi {
             owner_ext_id?: string | null;
             is_owner: boolean;
         }>;
-        /** Create a work item: a plain to-do, or (with a prompt / skill) agent work that starts now. */
-        createWork: (body: CreateWorkRequest) => Promise<{
+        /**
+         * Create a work item: a plain to-do, or (with a prompt / skill) agent work that starts now. It
+         * is made in the current workspace, or `options.workspaceId` (opened, not switched to), which
+         * the request names: a switch while it is sent cannot move it.
+         */
+        createWork: (body: CreateWorkRequest, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             label_ext_ids?: string[];
             external_id: string;
             title: string | null;
@@ -11983,8 +12013,10 @@ declare class Arbi {
         }>;
         /** Notify people about a conversation (each gets a notification); resolves with who was. */
         notify: (conversationId: string, userIds: string[]) => Promise<string[]>;
-        /** Draft an editable plan from an objective. */
-        plan: (body: PlanWorkRequest) => Promise<{
+        /** Draft an editable plan from an objective, in the current workspace or `options.workspaceId`. */
+        plan: (body: PlanWorkRequest, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             goal: string;
             criteria: components["schemas"]["TaskPlanCriterion"][];
             max_passes: number;
@@ -12679,9 +12711,14 @@ declare class Arbi {
             } | null;
             conversation_ext_id?: string | null;
         }>;
-        /** The skills the caller can run (own + shared marketplace), metadata only. */
+        /**
+         * The skills the caller can run (own + shared marketplace), metadata only. Without a
+         * marketplace they are the current workspace's, or `options.workspaceId`'s (opened, not
+         * switched to).
+         */
         listSkills: (options?: {
             includeHidden?: boolean;
+            workspaceId?: string;
         }) => Promise<{
             name: string;
             slug: string;
@@ -15270,7 +15307,10 @@ declare class Arbi {
         }>;
     };
     readonly files: {
-        list: (options?: ListFilesOptions) => Promise<{
+        /** The current workspace's files, or `options.workspaceId`'s (opened, not switched to). */
+        list: (options?: Omit<ListFilesOptions, "workspaceExtId"> & {
+            workspaceId?: string;
+        }) => Promise<{
             object: string;
             data: {
                 id: string;
@@ -15303,7 +15343,10 @@ declare class Arbi {
             object: string;
             deleted: boolean;
         }>;
-        upload: (fileData: Blob, fileName: string, purpose?: string) => Promise<{
+        /** Upload a file into the current workspace, or `options.workspaceId` (opened, not switched to). */
+        upload: (fileData: Blob, fileName: string, purpose?: string, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             id: string;
             object: string;
             bytes: number;
@@ -16239,8 +16282,15 @@ declare class Arbi {
         }>;
         export: (databaseId: string, format: "csv" | "xlsx") => Promise<Blob>;
     };
+    /**
+     * Notes. Create, list and search act in the current workspace, or `workspaceId` (opened for this
+     * session, not switched to), which the request names; update, delete and remind act in the
+     * note's own workspace, which the server derives from it.
+     */
     readonly facts: {
-        create: (body: CreateFactRequest) => Promise<{
+        create: (body: CreateFactRequest, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             text: string;
             citations?: components["schemas"]["CitationSources"] | null;
             external_id: string;
@@ -16257,7 +16307,9 @@ declare class Arbi {
             updated_at: string;
         }>;
         /** Create up to 200 notes in one all-or-nothing request. */
-        createBatch: (body: CreateFactsRequest) => Promise<{
+        createBatch: (body: CreateFactsRequest, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             text: string;
             citations?: components["schemas"]["CitationSources"] | null;
             external_id: string;
@@ -16276,7 +16328,9 @@ declare class Arbi {
         /** Pass `from`/`to`/`datedOnly` for the timeline view — dated notes only,
          *  ordered by when they happened. `tagExtIds` / `docExtId` narrow the list;
          *  `limit` / `offset` page it. */
-        list: (options?: ListFactsOptions) => Promise<{
+        list: (options?: Omit<ListFactsOptions, "workspaceExtId"> & {
+            workspaceId?: string;
+        }) => Promise<{
             text: string;
             citations?: components["schemas"]["CitationSources"] | null;
             external_id: string;
@@ -16292,7 +16346,9 @@ declare class Arbi {
             created_at: string;
             updated_at: string;
         }[]>;
-        search: (body: FactSearchRequest) => Promise<{
+        search: (body: FactSearchRequest, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             facts: components["schemas"]["FactSearchHit"][];
         }>;
         update: (factId: string, body: UpdateFactRequest) => Promise<{

package/dist/{browser-xgwYmWyv.d.ts → browser-CL-6Y6E1.d.ts}

@@ -2922,8 +2922,11 @@ type AssistantMode = components['schemas']['AssistantMode'];
 type ConversationSearchRequest = components['schemas']['ConversationSearchRequest'];
 type ConversationSearchResponse = components['schemas']['ConversationSearchResponse'];
 
-/** The caller's conversations. A conversation with a `status` is also a task (work item). */
-declare function listConversations(arbi: ArbiClient): Promise<{
+/**
+ * The caller's conversations in `workspaceExtId` (absent: the session's open workspace). A
+ * conversation with a `status` is also a task (work item).
+ */
+declare function listConversations(arbi: ArbiClient, workspaceExtId?: string | null): Promise<{
     label_ext_ids?: string[] | undefined;
     external_id: string;
     title: string | null;
@@ -3067,15 +3070,14 @@ declare function listConversations(arbi: ArbiClient): Promise<{
     is_owner: boolean;
 }[]>;
 /**
- * Import a conversation export into the active workspace.
+ * Import a conversation export into `workspaceExtId` (absent: the session's open workspace).
  *
  * Accepts a ChatGPT data export (`conversations.json`), an OpenClaw session log, or a
  * Claude Code transcript (`.jsonl`); `source='auto'` lets the server detect the format.
  * Uses raw multipart fetch (the typed client can't express file uploads), mirroring
- * `files.uploadFile`. The active workspace + cipher are resolved server-side from the
- * session, so no extra header is needed.
+ * `files.uploadFile`.
  */
-declare function importConversations(auth: AuthHeaders, fileData: Blob, fileName: string, source?: string): Promise<ConversationImportResponse>;
+declare function importConversations(auth: AuthHeaders, fileData: Blob, fileName: string, source?: string, workspaceExtId?: string | null): Promise<ConversationImportResponse>;
 declare function getConversationThreads(arbi: ArbiClient, conversationId: string): Promise<{
     conversation_ext_id: string;
     threads: {
@@ -3284,8 +3286,11 @@ declare function getConversationThreads(arbi: ArbiClient, conversationId: string
 declare function deleteConversation(arbi: ArbiClient, conversationId: string): Promise<{
     detail: string;
 }>;
-/** Keyword + semantic search over the open workspace's past conversation messages, grouped. */
-declare function searchConversations(arbi: ArbiClient, body: ConversationSearchRequest): Promise<ConversationSearchResponse>;
+/**
+ * Keyword + semantic search over the past conversation messages of `workspaceExtId` (absent: the
+ * session's open workspace), grouped.
+ */
+declare function searchConversations(arbi: ArbiClient, body: ConversationSearchRequest, workspaceExtId?: string | null): Promise<ConversationSearchResponse>;
 declare function getMessage(arbi: ArbiClient, messageId: string): Promise<{
     role: "user" | "assistant" | "system";
     content: string;
@@ -3969,9 +3974,8 @@ type SkillSummary = components['schemas']['SkillSummaryResponse'];
  * never the SKILL.md body. To read the body, fetch the document via
  * ``getParsedContent(authHeaders, doc_ext_id, 'content')``.
  *
- * Scoped to the workspace the caller has open (the backend uses the
- * session's ``active_workspace``); cross-workspace listing isn't
- * supported because each workspace has its own encryption key.
+ * Without a deployment marketplace the skills are a workspace's: ``workspaceExtId``
+ * (its key must be on the session), else the session's open workspace.
  *
  * @param includeHidden  When ``true``, returns skills with
  *   ``user-invocable: false`` in their frontmatter. Off by default —
@@ -3980,6 +3984,8 @@ type SkillSummary = components['schemas']['SkillSummaryResponse'];
  */
 declare function listSkills(arbi: ArbiClient, options?: {
     includeHidden?: boolean;
+    /** The workspace whose skills back the list without a marketplace; absent: the open one. */
+    workspaceExtId?: string | null;
 }): Promise<SkillSummary[]>;
 /**
  * Whether a skill is the caller's own and shared with everyone (``global``), so saving it again
@@ -5207,6 +5213,8 @@ interface ListFilesOptions {
     limit?: number;
     order?: string;
     after?: string | null;
+    /** The workspace listed (its key must be on the session); absent: the session's open one. */
+    workspaceExtId?: string | null;
 }
 declare function listFiles(arbi: ArbiClient, options?: ListFilesOptions): Promise<{
     object: string;
@@ -5242,10 +5250,10 @@ declare function deleteFile(arbi: ArbiClient, fileId: string): Promise<{
     deleted: boolean;
 }>;
 /**
- * Upload a file via the OpenAI-compatible Files API.
- * Uses raw fetch for multipart upload.
+ * Upload a file via the OpenAI-compatible Files API into `workspaceExtId` (absent: the session's
+ * open workspace). Uses raw fetch for multipart upload.
  */
-declare function uploadFile(auth: AuthHeaders, fileData: Blob, fileName: string, purpose?: string): Promise<FileObject>;
+declare function uploadFile(auth: AuthHeaders, fileData: Blob, fileName: string, purpose?: string, workspaceExtId?: string | null): Promise<FileObject>;
 /**
  * Get file content (binary). Returns the raw Response for the caller to handle.
  */
@@ -7404,8 +7412,11 @@ type AuthMode = components['schemas']['src__models__work__AuthMode'];
  * and rename.
  */
 declare function updateConversation(arbi: ArbiClient, conversationId: string, body: UpdateConversationRequest): Promise<ConversationResponse>;
-/** Create a work item. With a `prompt` / `skill_ref` the agent starts at once; otherwise a to-do. */
-declare function createWork(arbi: ArbiClient, body: CreateWorkRequest): Promise<ConversationResponse>;
+/**
+ * Create a work item in `workspaceExtId` (absent: the session's open workspace). With a `prompt` /
+ * `skill_ref` the agent starts at once; otherwise a to-do. A parent must be in the same workspace.
+ */
+declare function createWork(arbi: ArbiClient, body: CreateWorkRequest, workspaceExtId?: string | null): Promise<ConversationResponse>;
 /** Run a work item now (or retry). Not while a run is live. */
 declare function runConversation(arbi: ArbiClient, conversationId: string): Promise<ConversationResponse>;
 /** What an unattended run waits on (agent email + session public key); 404 when nothing waits. */
@@ -7440,8 +7451,11 @@ declare function getConversationUsage(arbi: ArbiClient, conversationId: string):
 declare function notifyConversation(arbi: ArbiClient, conversationId: string, userIds: string[]): Promise<string[]>;
 /** The task's history, oldest first: created, run started, handed off, sent back, done and so on. */
 declare function getActivity(arbi: ArbiClient, conversationId: string): Promise<ActivityResponse[]>;
-/** Draft an editable plan (goal and acceptance checklist) from a plain objective. */
-declare function planWork(arbi: ArbiClient, body: PlanWorkRequest): Promise<TaskPlan>;
+/**
+ * Draft an editable plan (goal and acceptance checklist) from a plain objective, for a task in
+ * `workspaceExtId` (absent: the session's open workspace).
+ */
+declare function planWork(arbi: ArbiClient, body: PlanWorkRequest, workspaceExtId?: string | null): Promise<TaskPlan>;
 /** A stepped run as it stands: its conversation, each step's phase, and what it waits for now. */
 interface RunProgress {
     conversation: ConversationResponse;
@@ -7568,8 +7582,9 @@ declare namespace workflows {
 /**
  * Workspace facts — per-workspace encrypted statements with citations.
  * The firm's practice profile / house style / precedent knowhow lives here (`/setup`
- * records it as ordinary facts) and is read by grounded agents. All endpoints
- * require an OPEN workspace.
+ * records it as ordinary facts) and is read by grounded agents. Create, list and search name
+ * their workspace (`workspaceExtId`; its key must be on the session); edit, delete and remind act
+ * in the fact's own workspace, which the server derives from the fact.
  * Backend: `/v1/facts` (src/api/v1/routers/facts.py).
  */
 
@@ -7594,16 +7609,17 @@ interface ListFactsOptions {
     limit?: number;
     /** Notes to skip, for paging with `limit`. */
     offset?: number;
+    /** The workspace listed (its key must be on the session); absent: the session's open one. */
+    workspaceExtId?: string | null;
 }
-/** Create a note. `content` is required; `shared` makes it workspace-wide. */
-declare function createFact(arbi: ArbiClient, body: CreateFactRequest): Promise<FactResponse>;
+/** Create a note in `workspaceExtId` (absent: the open one). `shared` makes it workspace-wide. */
+declare function createFact(arbi: ArbiClient, body: CreateFactRequest, workspaceExtId?: string | null): Promise<FactResponse>;
 /**
  * Create several notes in one all-or-nothing request (max 200). Prefer this to a loop of
  * {@link createFact} for an import: tags are resolved once and the notes are indexed in batches.
  * Results come back in request order.
  */
-declare function createFactsBatch(arbi: ArbiClient, body: CreateFactsRequest): Promise<FactResponse[]>;
-/** List the open workspace's notes (newest first). */
+declare function createFactsBatch(arbi: ArbiClient, body: CreateFactsRequest, workspaceExtId?: string | null): Promise<FactResponse[]>;
 /**
  * List notes. Passing a date range — or `datedOnly` — turns this into the
  * TIMELINE: only dated notes, ordered by when they happened rather than when
@@ -7616,8 +7632,8 @@ declare function createFactsBatch(arbi: ArbiClient, body: CreateFactsRequest): P
  * Narrow with `tagExtIds` / `docExtId` and page with `limit` / `offset`.
  */
 declare function listFacts(arbi: ArbiClient, options?: ListFactsOptions): Promise<FactResponse[]>;
-/** Semantic/keyword/hybrid search across the workspace's notes. */
-declare function searchFacts(arbi: ArbiClient, body: FactSearchRequest): Promise<FactSearchResponse>;
+/** Semantic/keyword/hybrid search across the notes of `workspaceExtId` (absent: the open one). */
+declare function searchFacts(arbi: ArbiClient, body: FactSearchRequest, workspaceExtId?: string | null): Promise<FactSearchResponse>;
 declare function updateFact(arbi: ArbiClient, factId: string, body: UpdateFactRequest): Promise<FactResponse>;
 declare function deleteFact(arbi: ArbiClient, factId: string): Promise<void>;
 /**
@@ -11247,7 +11263,10 @@ declare class Arbi {
         getThumbnails: (docIds: string[]) => Promise<Record<string, string | null>>;
     };
     readonly conversations: {
-        list: () => Promise<{
+        /** The current workspace's conversations, or `options.workspaceId`'s (opened, not switched to). */
+        list: (options?: {
+            workspaceId?: string;
+        }) => Promise<{
             label_ext_ids?: string[] | undefined;
             external_id: string;
             title: string | null;
@@ -11598,8 +11617,13 @@ declare class Arbi {
         delete: (conversationId: string) => Promise<{
             detail: string;
         }>;
-        /** Search the open workspace's past conversation messages (keyword + semantic), grouped. */
-        search: (body: ConversationSearchRequest) => Promise<{
+        /**
+         * Search the past conversation messages (keyword + semantic, grouped) of the current
+         * workspace, or `options.workspaceId` (opened for this session, not switched to).
+         */
+        search: (body: ConversationSearchRequest, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             query: string;
             search_mode: string;
             results: components["schemas"]["ConversationSearchGroup"][];
@@ -11655,8 +11679,14 @@ declare class Arbi {
             owner_ext_id?: string | null;
             is_owner: boolean;
         }>;
-        /** Create a work item: a plain to-do, or (with a prompt / skill) agent work that starts now. */
-        createWork: (body: CreateWorkRequest) => Promise<{
+        /**
+         * Create a work item: a plain to-do, or (with a prompt / skill) agent work that starts now. It
+         * is made in the current workspace, or `options.workspaceId` (opened, not switched to), which
+         * the request names: a switch while it is sent cannot move it.
+         */
+        createWork: (body: CreateWorkRequest, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             label_ext_ids?: string[];
             external_id: string;
             title: string | null;
@@ -11983,8 +12013,10 @@ declare class Arbi {
         }>;
         /** Notify people about a conversation (each gets a notification); resolves with who was. */
         notify: (conversationId: string, userIds: string[]) => Promise<string[]>;
-        /** Draft an editable plan from an objective. */
-        plan: (body: PlanWorkRequest) => Promise<{
+        /** Draft an editable plan from an objective, in the current workspace or `options.workspaceId`. */
+        plan: (body: PlanWorkRequest, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             goal: string;
             criteria: components["schemas"]["TaskPlanCriterion"][];
             max_passes: number;
@@ -12679,9 +12711,14 @@ declare class Arbi {
             } | null;
             conversation_ext_id?: string | null;
         }>;
-        /** The skills the caller can run (own + shared marketplace), metadata only. */
+        /**
+         * The skills the caller can run (own + shared marketplace), metadata only. Without a
+         * marketplace they are the current workspace's, or `options.workspaceId`'s (opened, not
+         * switched to).
+         */
         listSkills: (options?: {
             includeHidden?: boolean;
+            workspaceId?: string;
         }) => Promise<{
             name: string;
             slug: string;
@@ -15270,7 +15307,10 @@ declare class Arbi {
         }>;
     };
     readonly files: {
-        list: (options?: ListFilesOptions) => Promise<{
+        /** The current workspace's files, or `options.workspaceId`'s (opened, not switched to). */
+        list: (options?: Omit<ListFilesOptions, "workspaceExtId"> & {
+            workspaceId?: string;
+        }) => Promise<{
             object: string;
             data: {
                 id: string;
@@ -15303,7 +15343,10 @@ declare class Arbi {
             object: string;
             deleted: boolean;
         }>;
-        upload: (fileData: Blob, fileName: string, purpose?: string) => Promise<{
+        /** Upload a file into the current workspace, or `options.workspaceId` (opened, not switched to). */
+        upload: (fileData: Blob, fileName: string, purpose?: string, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             id: string;
             object: string;
             bytes: number;
@@ -16239,8 +16282,15 @@ declare class Arbi {
         }>;
         export: (databaseId: string, format: "csv" | "xlsx") => Promise<Blob>;
     };
+    /**
+     * Notes. Create, list and search act in the current workspace, or `workspaceId` (opened for this
+     * session, not switched to), which the request names; update, delete and remind act in the
+     * note's own workspace, which the server derives from it.
+     */
     readonly facts: {
-        create: (body: CreateFactRequest) => Promise<{
+        create: (body: CreateFactRequest, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             text: string;
             citations?: components["schemas"]["CitationSources"] | null;
             external_id: string;
@@ -16257,7 +16307,9 @@ declare class Arbi {
             updated_at: string;
         }>;
         /** Create up to 200 notes in one all-or-nothing request. */
-        createBatch: (body: CreateFactsRequest) => Promise<{
+        createBatch: (body: CreateFactsRequest, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             text: string;
             citations?: components["schemas"]["CitationSources"] | null;
             external_id: string;
@@ -16276,7 +16328,9 @@ declare class Arbi {
         /** Pass `from`/`to`/`datedOnly` for the timeline view — dated notes only,
          *  ordered by when they happened. `tagExtIds` / `docExtId` narrow the list;
          *  `limit` / `offset` page it. */
-        list: (options?: ListFactsOptions) => Promise<{
+        list: (options?: Omit<ListFactsOptions, "workspaceExtId"> & {
+            workspaceId?: string;
+        }) => Promise<{
             text: string;
             citations?: components["schemas"]["CitationSources"] | null;
             external_id: string;
@@ -16292,7 +16346,9 @@ declare class Arbi {
             created_at: string;
             updated_at: string;
         }[]>;
-        search: (body: FactSearchRequest) => Promise<{
+        search: (body: FactSearchRequest, options?: {
+            workspaceId?: string;
+        }) => Promise<{
             facts: components["schemas"]["FactSearchHit"][];
         }>;
         update: (factId: string, body: UpdateFactRequest) => Promise<{