js-bao-wss-client 3.4.1 → 3.5.0-alpha.1

package/README.md

@@ -889,7 +889,7 @@ Additional flags:
 ### Pagination and tags
 
 - Paging params: `limit`, `cursor`, `forward`, `returnPage`. Default sort is by `grantedAt` (document permission grant time) descending; pass `forward: true` for ascending.
-- `returnPage: true` returns `{ items, cursor }` (backward-compatible array when omitted). With `refreshFromServer: true`, a background page walker fetches the remaining pages and updates the cache/`documentMetadataChanged` events; set `refreshFromServer: false` if you only want the first page. Note: cursors come from server responses; local-only/local-first paths do not fabricate cursors or enforce `limit` sizing—use `returnPage: true` when you need a cursor even if data is cached. To synchronously walk all pages yourself, loop on `{ returnPage: true, limit, cursor }` until `cursor` is null. To hydrate the full cache in one call, use `client.syncMetadata({ scope: "all", pageSize, includeRoot })` and then list with `refreshFromServer: false`.
+- `returnPage: true` returns `{ items, hasMore, nextCursor }` (backward-compatible array when omitted). With `refreshFromServer: true`, a background page walker fetches the remaining pages and updates the cache/`documentMetadataChanged` events; set `refreshFromServer: false` if you only want the first page. Note: cursors come from server responses; local-only/local-first paths do not fabricate cursors or enforce `limit` sizing—use `returnPage: true` when you need a cursor even if data is cached. To synchronously walk all pages yourself, loop on `{ returnPage: true, limit, cursor }`, passing each page's `nextCursor` back as `cursor`, until `nextCursor` is absent. To hydrate the full cache in one call, use `client.syncMetadata({ scope: "all", pageSize, includeRoot })` and then list with `refreshFromServer: false`.
 - Server page size defaults to 100 when `limit` is omitted; you can request smaller/larger pages within server limits.
 - Tag filtering: `tag: string` performs an exact-match filter server-side. Responses include `tags: string[]` and `grantedAt`; both are cached locally and usable offline (e.g., list + `tag` will be filtered from cache when offline/local-only). Root is also considered for tag queries—if you tag the root, it can appear in tag-filtered results even when the default list filters root out. When `refreshFromServer` is true with a tag, the client still fetches the full dataset in the background to keep the cache complete, then filters locally for the tag.
 - Tag CRUD: server endpoints exist (`POST /documents/:id/tags { tag }`, `DELETE /documents/:id/tags/:tag`) and document create accepts optional tags; the high-level client currently exposes tagging via HTTP helpers or `client.makeRequest`.
@@ -1410,8 +1410,8 @@ const page1 = await client.document(documentId).blobs().list({ limit: 10 });
 page1.items.forEach((b) => {
   console.log(b.blobId, b.filename, b.size);
 });
-if (page1.cursor) {
-  const page2 = await blobs.list({ cursor: page1.cursor });
+if (page1.nextCursor) {
+  const page2 = await blobs.list({ cursor: page1.nextCursor });
 }
 ```
 
@@ -1941,6 +1941,13 @@ const group = await client.groups.create({
   description: "All engineers",
 });
 
+// Create a group and stamp resource metadata on it in the same call
+const readingGroup = await client.groups.create({
+  groupType: "class-reading-group",
+  name: "Reading group",
+  initialMetadata: { classLink: { classId: "class-A" } },
+});
+
 // List groups
 const groups = await client.groups.list();
 const teams = await client.groups.list({ type: "team" });

package/dist/JsBaoClient.d.ts

@@ -33,6 +33,7 @@ import { GroupTypeConfigsAPI } from "./api/groupTypeConfigsApi";
 import { CollectionTypeConfigsAPI } from "./api/collectionTypeConfigsApi";
 import { DatabaseTypeConfigsAPI } from "./api/databaseTypeConfigsApi";
 import { CollectionsAPI } from "./api/collectionsApi";
+import { AgentsAPI } from "./api/agentSessionsApi";
 import { InvitationsAPI } from "./api/invitationsApi";
 import { NotificationsAPI } from "./api/notificationsApi";
 export { JsBaoError, isJsBaoError, LockTimeoutError, JsBaoApiError, isJsBaoApiError, JsBaoNetworkError, isJsBaoNetworkError, } from "./errors";
@@ -43,7 +44,7 @@ export type { DocumentInfo, DocumentPermissionEntry, DocumentAccessResult, Docum
 export type { UserProfile, SharedDocument, SharedDocumentListResult, SharedDocumentsOptions, OwnedDocumentsOptions, } from "./api/meApi";
 export type { SessionInfo } from "./api/sessionApi";
 export type { BasicUserInfo, BatchUserProfile } from "./api/usersApi";
-export type { DatabaseInfo, DatabasePermissionEntry, DatabaseGroupPermissionEntry, GrantDatabaseGroupPermissionParams, DatabaseOwnershipTransferResult, DatabaseOperationInfo, AddManagerParams, GrantPermissionParams, CsvImportOptions, CsvImportProgress, CsvImportResult, CelContextResult, ExecuteOperationOptions, DatabaseChangeEvent, DatabaseChangePayload, DatabaseSubscribeOptions, ListDatabasesOptions, DatabaseListPage, OperationType, OperationFilter, QueryDefinition, MutationOperation, MutationDefinition, CountDefinition, AggregateOperation, AggregateDefinition, PipelineStep, PipelineDefinition, ApplyToQuerySource, ApplyToQueryAction, ApplyToQueryDefinition, OperationDefinition, CreateOperationParams, UpdateOperationParams, } from "./api/databasesApi";
+export type { DatabaseInfo, DatabasePermissionEntry, DatabaseGroupPermissionEntry, GrantDatabaseGroupPermissionParams, DatabaseOwnershipTransferResult, DatabaseOperationInfo, AddManagerParams, CsvImportOptions, CsvImportProgress, CsvImportResult, ExecuteOperationOptions, DatabaseChangeEvent, DatabaseChangePayload, DatabaseSubscribeOptions, ListDatabasesOptions, DatabaseListPage, OperationType, OperationFilter, QueryDefinition, MutationOperation, MutationDefinition, CountDefinition, AggregateOperation, AggregateDefinition, PipelineStep, PipelineDefinition, ApplyToQuerySource, ApplyToQueryAction, ApplyToQueryDefinition, OperationDefinition, CreateOperationParams, UpdateOperationParams, } from "./api/databasesApi";
 export type { GroupInfo, GroupMemberInfo, GroupMembershipInfo, GroupDocumentInfo, GroupDatabaseInfo, ListUserMembershipsOptions, DirectGroupAdd, DeferredGroupAdd, GroupAddMemberResult, } from "./api/groupsApi";
 export type { CollectionInfo, CollectionDocumentInfo, CollectionGroupPermissionInfo, CollectionMemberInfo, CollectionAccessInfo, DocumentCollectionInfo, AddCollectionMemberParams, DirectCollectionAdd, DeferredCollectionAdd, CollectionAddMemberResult, PendingCollectionInvitationEntry, } from "./api/collectionsApi";
 export type { RuleSetInfo, RuleSetSchema, RuleSetTestResult, RuleSetDebugResult, TraceEntry, TriggerDefInfo, ModelRulesInfo, PathDeclaration, RuleLoads, RuleExpression, CategoryRules, } from "./api/ruleSetsApi";
@@ -60,19 +61,21 @@ export type { DocumentBlobContext, BlobUploadSourceOptions, BlobUploadResult, Bl
 export type { DocumentsAPI, DocumentContext, DocumentAliasesAPI, DocumentIngestsAPI, DocumentSnapshotsAPI, } from "./api/documentsApi";
 export type { DatabasesAPI } from "./api/databasesApi";
 export type { CollectionsAPI } from "./api/collectionsApi";
+export type { AgentsAPI, AgentSessionsAPI } from "./api/agentSessionsApi";
+export type { AgentSessionMemberRole, AgentSessionMembers, AgentSessionInfo, AgentSessionListItem, ListAgentSessionsOptions, AgentSessionRenameResult, AgentSessionDeleteResult, AgentSessionMembersResult, } from "./api/agentSessionsApi";
 export type { MeAPI } from "./api/meApi";
 export type { SessionAPI } from "./api/sessionApi";
 export type { UsersAPI } from "./api/usersApi";
 export type { GroupsAPI } from "./api/groupsApi";
 export type { RuleSetsAPI } from "./api/ruleSetsApi";
 export type { NotificationsAPI, NotificationInfo, NotificationListOptions, NotificationListResult, NotificationSendResult, SendNotificationParams, PushDeviceInfo, RegisterPushDeviceParams, } from "./api/notificationsApi";
-export type { BlobBucketsAPI, BlobBucketInfo, BlobBucketTtlTier, BlobBucketPreset, BlobBucketAccessPolicy, CreateBlobBucketParams, UpdateBlobBucketParams, BlobInfo, BlobUploadParams, BucketBlobUploadResult, BucketBlobListResult, BlobListOptions, BlobSignedUrlResult, BatchBlobDeleteResult, } from "./api/blobBucketsApi";
+export type { BlobBucketsAPI, BlobBucketInfo, BlobBucketTtlTier, BlobBucketPreset, CreateBlobBucketParams, UpdateBlobBucketParams, BlobInfo, BlobUploadParams, BucketBlobUploadResult, BucketBlobListResult, BlobListOptions, BlobSignedUrlResult, BatchBlobDeleteResult, } from "./api/blobBucketsApi";
 export type { GroupTypeConfigsAPI } from "./api/groupTypeConfigsApi";
 export type { CollectionTypeConfigsAPI } from "./api/collectionTypeConfigsApi";
 export type { DatabaseTypeConfigsAPI } from "./api/databaseTypeConfigsApi";
 export type { CronTriggersAPI } from "./api/cronTriggersApi";
 export type { CronTriggerInfo, CreateCronTriggerParams, UpdateCronTriggerParams, CronTriggerListResult, ObjectStatus, } from "./api/cronTriggersApi";
-export type { CreateDocumentOptions, CreateOfflineOptions, CreateWithAliasOptions, GetOrCreateWithAliasOptions, DeleteDocumentOptions, DocumentAccessRequest, DocumentAccessRequestResponse, DocumentListOptions, DocumentListPage, EvictAllDocumentsOptions, EvictDocumentOptions, GrantGroupPermissionParams, ResolveAliasParams, SetAliasParams, UpdateDocumentData, DocumentIngestSession, DocumentIngestCounterBucket, DocumentIngestStageCounters, DocumentIngestChunkUpload, DocumentIngestChunkUploadResult, DocumentIngestPage, DocumentSnapshotBuild, DocumentSnapshotPage, DocumentSnapshotRequest, } from "./api/documentsApi";
+export type { CreateDocumentOptions, CreateWithAliasOptions, GetOrCreateWithAliasOptions, DeleteDocumentOptions, DocumentAccessRequest, DocumentAccessRequestResponse, DocumentListOptions, DocumentListPage, EvictAllDocumentsOptions, EvictDocumentOptions, GrantGroupPermissionParams, ResolveAliasParams, SetAliasParams, UpdateDocumentData, DocumentIngestSession, DocumentIngestCounterBucket, DocumentIngestStageCounters, DocumentIngestChunkUpload, DocumentIngestChunkUploadResult, DocumentIngestPage, DocumentSnapshotBuild, DocumentSnapshotPage, DocumentSnapshotRequest, } from "./api/documentsApi";
 export type { CreateDatabaseParams, UpdateDatabaseParams } from "./api/databasesApi";
 export type { CreateCollectionParams, UpdateCollectionParams, GrantCollectionGroupPermissionParams, ListCollectionsOptions, } from "./api/collectionsApi";
 export type { ListResult } from "./api/listResult";
@@ -91,7 +94,7 @@ export type { DocumentDebugSnapshot, DocumentPermission, LocalDocumentEntry, Loc
 export type { LogLevel } from "./internal/logger";
 export type { RequestOptions } from "./internal/httpClient";
 export type { LocksAPI } from "./api/locksApi";
-export type { FunctionsAPI, FunctionInvokeOptions, FunctionInvokeResult, FunctionInvokeStatus, FunctionInvokeLimits, FunctionStartOptions, FunctionStartResult, FunctionRunRef, FunctionWaitForResult, FunctionRun, FunctionRunError, FunctionRunErrorCode, FunctionRunSettled, FunctionRunSlice, FunctionRunStatus, FunctionRunStatusValue, FunctionRunTerminalStatus, FunctionWaitOptions, } from "./api/functionsApi";
+export type { FunctionsAPI, FunctionInvokeOptions, FunctionInvokeResult, FunctionInvokeStatus, FunctionInvokeLimits, FunctionStartOptions, FunctionStartResult, FunctionRunRef, FunctionRun, FunctionRunError, FunctionRunErrorCode, FunctionRunSettled, FunctionRunSlice, FunctionRunStatus, FunctionRunStatusValue, FunctionRunTerminalStatus, FunctionWaitOptions, } from "./api/functionsApi";
 export type { LockHandle, LockContention, AcquireResponse, AcquireOptions, BlockingAcquireOptions, ReleaseResult, RenewResult, LockStatus, LockListEntry, LockListResult, } from "./api/locksApi";
 export type { ResourceMetadataAPI } from "./api/resourceMetadataApi";
 export type { ResourceMetadataReadResult, ResourceMetadataWriteResult, ResourceMetadataBatchRequestItem, ResourceMetadataBatchParams, ResourceMetadataBatchCategoryResult, ResourceMetadataBatchResourceResult, ResourceMetadataBatchResult, ResourceMetadataListEntry, ResourceMetadataListResult, ResourceMetadataDeleteResult, ResourceMetadataResolveParams, ResourceMetadataResolveResult, } from "./api/resourceMetadataApi";
@@ -1388,8 +1391,6 @@ export interface ListWorkflowRunsResult {
     nextCursor?: string;
     /** True when a next page exists. */
     hasMore?: boolean;
-    /** @deprecated Alias of `nextCursor` kept for one deprecation window. */
-    cursor?: string;
     /**
      * How many runs the server examined to produce this page.
      *
@@ -2519,6 +2520,10 @@ export declare class JsBaoClient extends Observable<any> {
     /** Sub-API for managing document collections.
      * @group Sub-APIs */
     collections: CollectionsAPI;
+    /** Sub-API for agents: `agents.sessions` lists, reads, renames and deletes
+     * agent sessions and manages their members.
+     * @group Sub-APIs */
+    agents: AgentsAPI;
     /** Sub-API for managing rule sets.
      * @group Sub-APIs */
     ruleSets: RuleSetsAPI;
@@ -3037,14 +3042,6 @@ export declare class JsBaoClient extends Observable<any> {
      * @param documentId - The document to check for local persistence
      * @group Offline & Sync */
     hasIndexedDbPersistence(documentId: string): Promise<boolean>;
-    /** Update the local snapshot flag for a document.
-     * @param documentId - The document to update the snapshot flag for
-     * @param hasSnapshot - Whether the document has a local IndexedDB snapshot
-     * @deprecated No longer called internally — `hasIndexedDbSnapshot` is now
-     *   ignored in favour of checking live ydoc content via `ydocHasData()`.
-     *   Retained for external callers; will be removed in a future major version.
-     * @group Offline & Sync */
-    updateLocalSnapshotFlag(documentId: string, hasSnapshot: boolean): Promise<void>;
     private sendAwarenessState;
     /** Remove awareness states for specific clients.
      * @param documentId - The document to remove awareness from
@@ -4487,8 +4484,6 @@ export declare class JsBaoClient extends Observable<any> {
      * @param timeoutMs - Maximum time to wait before rejecting (ms, default 30000)
      * @group Offline & Sync */
     waitForInitialSync(documentId: string, timeoutMs?: number): Promise<void>;
-    /** @deprecated Use {@link waitForInitialSync} instead. */
-    waitForSync(documentId: string, timeoutMs?: number): Promise<void>;
     /**
      * Wait until the server confirms it has all of this client's writes.
      * Polls {@link checkStateVector} until `includesWrites` is true.

package/dist/JsBaoClient.js

@@ -46,6 +46,7 @@ import { GroupTypeConfigsAPI } from "./api/groupTypeConfigsApi";
 import { CollectionTypeConfigsAPI } from "./api/collectionTypeConfigsApi";
 import { DatabaseTypeConfigsAPI } from "./api/databaseTypeConfigsApi";
 import { CollectionsAPI } from "./api/collectionsApi";
+import { AgentsAPI } from "./api/agentSessionsApi";
 import { InvitationsAPI } from "./api/invitationsApi";
 import { NotificationsAPI } from "./api/notificationsApi";
 export { JsBaoError, isJsBaoError, LockTimeoutError, JsBaoApiError, isJsBaoApiError, JsBaoNetworkError, isJsBaoNetworkError, } from "./errors";
@@ -1190,6 +1191,7 @@ export class JsBaoClient extends Observable {
         this.databases = new DatabasesAPI(this);
         this.groups = new GroupsAPI(this);
         this.collections = new CollectionsAPI(this);
+        this.agents = new AgentsAPI(this);
         this.ruleSets = new RuleSetsAPI(this);
         this.blobBuckets = new BlobBucketsAPI(this);
         this.groupTypeConfigs = new GroupTypeConfigsAPI(this);
@@ -1755,14 +1757,12 @@ export class JsBaoClient extends Observable {
                     const path = `/${endpoint}${qs.length ? `?${qs.join("&")}` : ""}`;
                     const response = await this.makeRequest("GET", path);
                     if (Array.isArray(response)) {
-                        return { items: response, cursor: null };
+                        return { items: response, nextCursor: null };
                     }
                     const page = response;
-                    // #1316: prefer `nextCursor`; fall back to the deprecated `cursor`
-                    // alias for older servers.
                     return {
                         items: page.items || [],
-                        cursor: page.nextCursor ?? page.cursor ?? null,
+                        nextCursor: page.nextCursor ?? null,
                     };
                 };
                 const allItems = [];
@@ -1782,7 +1782,7 @@ export class JsBaoClient extends Observable {
                                 allIds.add(id);
                             allItems.push(item);
                         }
-                        cursor = page.cursor || null;
+                        cursor = page.nextCursor || null;
                     } while (cursor);
                 }
                 items = allItems;
@@ -2077,13 +2077,13 @@ export class JsBaoClient extends Observable {
                 // response says nothing about where the scope ends.
                 if (Array.isArray(response))
                     return null;
-                const items = response?.items ?? response?.documents;
+                const items = response?.items;
                 // A body that never mentioned `items` is not a page of this scope, and
                 // an empty list read as the whole scope evicts everything.
                 if (!Array.isArray(items))
                     return null;
                 collected.push(...items);
-                const next = response?.nextCursor ?? response?.cursor ?? null;
+                const next = response?.nextCursor ?? null;
                 if (!next) {
                     // No continuation token. If the page nevertheless says more rows
                     // remain, the walk cannot ask for them and so never reached the end
@@ -3733,16 +3733,13 @@ export class JsBaoClient extends Observable {
         const path = `/workflows/runs${params.length ? `?${params.join("&")}` : ""}`;
         const response = await this.makeRequest("GET", path);
         const page = response;
-        // #1316: prefer `nextCursor`; fall back to the deprecated `cursor` alias
-        // for older servers.
-        const nextCursor = page?.nextCursor ?? page?.cursor ?? undefined;
+        const nextCursor = page?.nextCursor ?? undefined;
         const result = {
             items: page?.items ?? [],
             hasMore: typeof page?.hasMore === "boolean" ? page.hasMore : !!nextCursor,
         };
         if (nextCursor != null) {
             result.nextCursor = nextCursor;
-            result.cursor = nextCursor;
         }
         // #2237: filtered listings report how far the server's walk got. Only
         // surfaced when the server actually sent a number — `undefined` means
@@ -4701,52 +4698,6 @@ export class JsBaoClient extends Observable {
         }
         return false;
     }
-    /** Update the local snapshot flag for a document.
-     * @param documentId - The document to update the snapshot flag for
-     * @param hasSnapshot - Whether the document has a local IndexedDB snapshot
-     * @deprecated No longer called internally — `hasIndexedDbSnapshot` is now
-     *   ignored in favour of checking live ydoc content via `ydocHasData()`.
-     *   Retained for external callers; will be removed in a future major version.
-     * @group Offline & Sync */
-    async updateLocalSnapshotFlag(documentId, hasSnapshot) {
-        const metaIndex = this.docManager.metadataIndex;
-        const existing = metaIndex.get(documentId);
-        const currentFlag = existing?.hasIndexedDbSnapshot === true;
-        if (hasSnapshot === currentFlag)
-            return;
-        const next = (existing || { documentId });
-        const changedFields = ["hasIndexedDbSnapshot"];
-        if (hasSnapshot) {
-            next.hasIndexedDbSnapshot = true;
-            if (typeof next.localBytes !== "number" || next.localBytes <= 0) {
-                next.localBytes = 1;
-                changedFields.push("localBytes");
-            }
-        }
-        else {
-            delete next.hasIndexedDbSnapshot;
-            if (typeof next.localBytes === "number" && next.localBytes > 0) {
-                next.localBytes = 0;
-                changedFields.push("localBytes");
-            }
-        }
-        metaIndex.set(documentId, next);
-        try {
-            await this._putMetadataToIdb(next);
-        }
-        catch (_) { }
-        try {
-            this.emit("documentMetadataChanged", [
-                {
-                    documentId,
-                    metadata: next,
-                    changedFields,
-                    source: "local",
-                },
-            ]);
-        }
-        catch (_) { }
-    }
     // Send awareness state to server
     sendAwarenessState(documentId) {
         if (!this.ws || !this.wsconnected)
@@ -11606,10 +11557,6 @@ export class JsBaoClient extends Observable {
             this.on("sync", onSync);
         });
     }
-    /** @deprecated Use {@link waitForInitialSync} instead. */
-    waitForSync(documentId, timeoutMs = 30000) {
-        return this.waitForInitialSync(documentId, timeoutMs);
-    }
     /**
      * Wait until the server confirms it has all of this client's writes.
      * Polls {@link checkStateVector} until `includesWrites` is true.

package/dist/agents/sessionModels.generated.d.ts

@@ -18,24 +18,31 @@ export { encodeJsonColumn, decodeJsonColumn } from "./sessionModelRuntime";
 export type { PrimitiveQueueEntry } from "./sessionModelRuntime";
 /** The schema version a session row carries in `schemaVersion`. */
 export declare const AGENT_SESSION_SCHEMA_VERSION = 1;
+/** Values this client recognizes for `PrimitiveSessionStatus`. */
 export declare const PRIMITIVE_SESSION_STATUSES: readonly ["idle", "thinking", "running_tool", "awaiting_answer", "failed", "expired", "cancelled"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitiveSessionStatus = (typeof PRIMITIVE_SESSION_STATUSES)[number] | "unknown";
+/** Values this client recognizes for `PrimitivePartKind`. */
 export declare const PRIMITIVE_PART_KINDS: readonly ["text", "reasoning", "tool_call", "file", "event"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitivePartKind = (typeof PRIMITIVE_PART_KINDS)[number] | "unknown";
+/** Values this client recognizes for `PrimitiveTextState`. */
 export declare const PRIMITIVE_TEXT_STATES: readonly ["streaming", "done"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitiveTextState = (typeof PRIMITIVE_TEXT_STATES)[number] | "unknown";
+/** Values this client recognizes for `PrimitiveToolCallState`. */
 export declare const PRIMITIVE_TOOL_CALL_STATES: readonly ["input-streaming", "input-available", "approval-requested", "approval-responded", "output-available", "output-error", "output-denied"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitiveToolCallState = (typeof PRIMITIVE_TOOL_CALL_STATES)[number] | "unknown";
+/** Values this client recognizes for `PrimitiveAuthorKind`. */
 export declare const PRIMITIVE_AUTHOR_KINDS: readonly ["user", "agent", "app"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitiveAuthorKind = (typeof PRIMITIVE_AUTHOR_KINDS)[number] | "unknown";
+/** Values this client recognizes for `PrimitiveStepKind`. */
 export declare const PRIMITIVE_STEP_KINDS: readonly ["model_call", "tool_call"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitiveStepKind = (typeof PRIMITIVE_STEP_KINDS)[number] | "unknown";
+/** Values this client recognizes for `PrimitiveStepStatus`. */
 export declare const PRIMITIVE_STEP_STATUSES: readonly ["running", "completed", "failed"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitiveStepStatus = (typeof PRIMITIVE_STEP_STATUSES)[number] | "unknown";
@@ -182,18 +189,21 @@ interface PrimitivePartRecordBase {
     modifiedAt?: string;
     row?: PrimitivePartRow;
 }
+/** A decoded `PrimitivePart` record with `kind: "text"`. */
 export interface PrimitiveTextPartRecord extends PrimitivePartRecordBase {
     kind: "text";
     state?: PrimitiveTextState;
     text?: string;
     providerMetadata?: Record<string, unknown>;
 }
+/** A decoded `PrimitivePart` record with `kind: "reasoning"`. */
 export interface PrimitiveReasoningPartRecord extends PrimitivePartRecordBase {
     kind: "reasoning";
     state?: PrimitiveTextState;
     text?: string;
     providerMetadata?: Record<string, unknown>;
 }
+/** A decoded `PrimitivePart` record with `kind: "tool_call"`. */
 export interface PrimitiveToolCallPartRecord extends PrimitivePartRecordBase {
     kind: "tool_call";
     state?: PrimitiveToolCallState;
@@ -213,6 +223,7 @@ export interface PrimitiveToolCallPartRecord extends PrimitivePartRecordBase {
     artifactBlobId?: string;
     providerMetadata?: Record<string, unknown>;
 }
+/** A decoded `PrimitivePart` record with `kind: "file"`. */
 export interface PrimitiveFilePartRecord extends PrimitivePartRecordBase {
     kind: "file";
     mediaType?: string;
@@ -220,6 +231,7 @@ export interface PrimitiveFilePartRecord extends PrimitivePartRecordBase {
     blobId?: string;
     sizeBytes?: number;
 }
+/** A decoded `PrimitivePart` record with `kind: "event"`. */
 export interface PrimitiveEventPartRecord extends PrimitivePartRecordBase {
     kind: "event";
     eventKind?: string;
@@ -233,6 +245,7 @@ export interface PrimitiveUnknownPartRecord extends PrimitivePartRecordBase {
     rawKind: string;
     row: PrimitivePartRow;
 }
+/** A decoded `PrimitivePart` record, including unrecognized kinds. */
 export type PrimitivePartRecord = PrimitiveTextPartRecord | PrimitiveReasoningPartRecord | PrimitiveToolCallPartRecord | PrimitiveFilePartRecord | PrimitiveEventPartRecord | PrimitiveUnknownPartRecord;
 /** The attributes of a `PrimitivePart` model instance. */
 export interface PrimitivePartAttrs {

package/dist/agents/sessionModels.generated.js

@@ -20,6 +20,7 @@ import { decodeModelRow, encodeModelRecord, registerSessionModels, sessionRowInv
 export { encodeJsonColumn, decodeJsonColumn } from "./sessionModelRuntime";
 /** The schema version a session row carries in `schemaVersion`. */
 export const AGENT_SESSION_SCHEMA_VERSION = 1;
+/** Values this client recognizes for `PrimitiveSessionStatus`. */
 export const PRIMITIVE_SESSION_STATUSES = [
     "idle",
     "thinking",
@@ -29,6 +30,7 @@ export const PRIMITIVE_SESSION_STATUSES = [
     "expired",
     "cancelled",
 ];
+/** Values this client recognizes for `PrimitivePartKind`. */
 export const PRIMITIVE_PART_KINDS = [
     "text",
     "reasoning",
@@ -36,7 +38,9 @@ export const PRIMITIVE_PART_KINDS = [
     "file",
     "event",
 ];
+/** Values this client recognizes for `PrimitiveTextState`. */
 export const PRIMITIVE_TEXT_STATES = ["streaming", "done"];
+/** Values this client recognizes for `PrimitiveToolCallState`. */
 export const PRIMITIVE_TOOL_CALL_STATES = [
     "input-streaming",
     "input-available",
@@ -46,8 +50,11 @@ export const PRIMITIVE_TOOL_CALL_STATES = [
     "output-error",
     "output-denied",
 ];
+/** Values this client recognizes for `PrimitiveAuthorKind`. */
 export const PRIMITIVE_AUTHOR_KINDS = ["user", "agent", "app"];
+/** Values this client recognizes for `PrimitiveStepKind`. */
 export const PRIMITIVE_STEP_KINDS = ["model_call", "tool_call"];
+/** Values this client recognizes for `PrimitiveStepStatus`. */
 export const PRIMITIVE_STEP_STATUSES = [
     "running",
     "completed",

package/dist/api/agentSessionsApi.d.ts

@@ -0,0 +1,152 @@
+import type { JsBaoClient } from "../JsBaoClient";
+import type { ListResult } from "./listResult";
+/**
+ * A member's role in an agent session. A `viewer` reads the session and
+ * holds a `reader` grant on its document; a `participant` also sends
+ * messages and holds a `read-write` grant.
+ */
+export type AgentSessionMemberRole = "viewer" | "participant";
+/** A session's members, each list in the order they were added. */
+export interface AgentSessionMembers {
+    viewers: string[];
+    participants: string[];
+}
+/**
+ * One agent session, as `client.agents.sessions.get()` answers it: who it
+ * belongs to, which agent it runs, its members, and the document that holds
+ * its conversation. The conversation itself is read by opening `documentId`
+ * with the document client, never through this call.
+ */
+export interface AgentSessionInfo {
+    sessionId: string;
+    /** The agent prompt the session is bound to. */
+    agentKey: string;
+    /** The session's conversation document. */
+    documentId: string;
+    ownerUserId: string;
+    /** ISO-8601. */
+    createdAt: string;
+    title: string | null;
+    scope: string | null;
+    /** ISO-8601; null when the session's listing entry is missing. */
+    lastActivityAt: string | null;
+    members: AgentSessionMembers;
+    /**
+     * The caller's standing: their role in the session, or `admin` when they
+     * reached it as an app owner or admin without being in it.
+     */
+    role: "owner" | "participant" | "viewer" | "admin";
+}
+/**
+ * One entry of `client.agents.sessions.list()`: what an app shows in a
+ * session list without opening any document.
+ */
+export interface AgentSessionListItem {
+    sessionId: string;
+    agentKey: string;
+    scope: string | null;
+    documentId: string;
+    ownerUserId: string;
+    /** The listed user's role in the session. */
+    role: "owner" | "participant" | "viewer";
+    title: string | null;
+    /** ISO-8601. */
+    lastActivityAt: string;
+    createdAt: string | null;
+}
+/** Filters and paging for `client.agents.sessions.list()`. */
+export interface ListAgentSessionsOptions {
+    /**
+     * Whose sessions to list. Omit it for your own; naming another user
+     * requires being an app owner or admin.
+     */
+    userId?: string;
+    /** Only this agent's sessions. */
+    agent?: string;
+    /** Only sessions created with exactly this scope. */
+    scope?: string;
+    /** Page size, at most 100 (default 50). */
+    limit?: number;
+    /** The `nextCursor` of the previous page. */
+    cursor?: string;
+}
+/** What `client.agents.sessions.rename()` answers. */
+export interface AgentSessionRenameResult {
+    sessionId: string;
+    title: string;
+}
+/** What `client.agents.sessions.delete()` answers. */
+export interface AgentSessionDeleteResult {
+    deleted: boolean;
+    sessionId: string;
+    documentId: string;
+}
+/** What the member calls answer: the members after the change. */
+export interface AgentSessionMembersResult {
+    members: AgentSessionMembers;
+}
+/**
+ * Agent sessions, available as `client.agents.sessions`.
+ *
+ * A session is created by a server function (`ctx.agents.createSession`);
+ * from a client you list the sessions you own or belong to, read one, and —
+ * as its owner — rename it, delete it and manage its members. App owners and
+ * admins may also list any user's sessions and get or delete any session.
+ * A refusal rejects with the client's ordinary request error carrying the
+ * server's `code` (for example `AGENT_SESSION_OWNER_ONLY` or
+ * `AGENT_SESSION_NOT_FOUND`).
+ */
+export declare class AgentSessionsAPI {
+    private client;
+    /** @internal */
+    constructor(client: JsBaoClient);
+    /**
+     * List one user's sessions — your own by default — newest first. Pages may
+     * be shorter than `limit` when `scope` filters entries out; follow
+     * `nextCursor` while `hasMore` is true.
+     * @param options - Whose sessions, filters and paging
+     */
+    list(options?: ListAgentSessionsOptions): Promise<ListResult<AgentSessionListItem>>;
+    /**
+     * Get one session. Members, the owner, app owners and admins may; anyone
+     * else is answered `AGENT_SESSION_NOT_FOUND`.
+     * @param sessionId - The session
+     */
+    get(sessionId: string): Promise<AgentSessionInfo>;
+    /**
+     * Rename a session (owner only). The title changes on the session, in every
+     * member's list, and on the document.
+     * @param sessionId - The session
+     * @param title - 1 to 255 characters
+     */
+    rename(sessionId: string, title: string): Promise<AgentSessionRenameResult>;
+    /**
+     * Delete a session and its document (the owner, an app owner or an admin).
+     * Deleting a session that is already deleted succeeds again.
+     * @param sessionId - The session
+     */
+    delete(sessionId: string): Promise<AgentSessionDeleteResult>;
+    /**
+     * Add a member, or change an existing member's role (owner only). The user
+     * must be an existing user of this app; a session holds at most 50 members.
+     * @param sessionId - The session
+     * @param userId - The user to add
+     * @param role - `viewer` or `participant`
+     */
+    addMember(sessionId: string, userId: string, role: AgentSessionMemberRole): Promise<AgentSessionMembersResult>;
+    /**
+     * Remove a member (owner only): their grant on the document is revoked and
+     * the session leaves their list. Removing someone who is not a member
+     * succeeds with the members unchanged.
+     * @param sessionId - The session
+     * @param userId - The member to remove
+     */
+    removeMember(sessionId: string, userId: string): Promise<AgentSessionMembersResult>;
+}
+/** Agents, available as `client.agents`. */
+export declare class AgentsAPI {
+    /** Agent sessions: list, get, rename, delete and members. */
+    readonly sessions: AgentSessionsAPI;
+    /** @internal */
+    constructor(client: JsBaoClient);
+}

package/dist/api/agentSessionsApi.js

@@ -0,0 +1,91 @@
+import { normalizeListEnvelope } from "../internal/listEnvelope.js";
+/**
+ * Agent sessions, available as `client.agents.sessions`.
+ *
+ * A session is created by a server function (`ctx.agents.createSession`);
+ * from a client you list the sessions you own or belong to, read one, and —
+ * as its owner — rename it, delete it and manage its members. App owners and
+ * admins may also list any user's sessions and get or delete any session.
+ * A refusal rejects with the client's ordinary request error carrying the
+ * server's `code` (for example `AGENT_SESSION_OWNER_ONLY` or
+ * `AGENT_SESSION_NOT_FOUND`).
+ */
+export class AgentSessionsAPI {
+    /** @internal */
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List one user's sessions — your own by default — newest first. Pages may
+     * be shorter than `limit` when `scope` filters entries out; follow
+     * `nextCursor` while `hasMore` is true.
+     * @param options - Whose sessions, filters and paging
+     */
+    async list(options) {
+        const params = new URLSearchParams();
+        if (options?.userId !== undefined)
+            params.set("userId", options.userId);
+        if (options?.agent !== undefined)
+            params.set("agent", options.agent);
+        if (options?.scope !== undefined)
+            params.set("scope", options.scope);
+        if (options?.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options?.cursor)
+            params.set("cursor", options.cursor);
+        const qs = params.toString();
+        return normalizeListEnvelope(await this.client.makeRequest("GET", `/agent-sessions${qs ? `?${qs}` : ""}`));
+    }
+    /**
+     * Get one session. Members, the owner, app owners and admins may; anyone
+     * else is answered `AGENT_SESSION_NOT_FOUND`.
+     * @param sessionId - The session
+     */
+    async get(sessionId) {
+        return this.client.makeRequest("GET", `/agent-sessions/${encodeURIComponent(sessionId)}`);
+    }
+    /**
+     * Rename a session (owner only). The title changes on the session, in every
+     * member's list, and on the document.
+     * @param sessionId - The session
+     * @param title - 1 to 255 characters
+     */
+    async rename(sessionId, title) {
+        return this.client.makeRequest("PATCH", `/agent-sessions/${encodeURIComponent(sessionId)}`, { title });
+    }
+    /**
+     * Delete a session and its document (the owner, an app owner or an admin).
+     * Deleting a session that is already deleted succeeds again.
+     * @param sessionId - The session
+     */
+    async delete(sessionId) {
+        return this.client.makeRequest("DELETE", `/agent-sessions/${encodeURIComponent(sessionId)}`);
+    }
+    /**
+     * Add a member, or change an existing member's role (owner only). The user
+     * must be an existing user of this app; a session holds at most 50 members.
+     * @param sessionId - The session
+     * @param userId - The user to add
+     * @param role - `viewer` or `participant`
+     */
+    async addMember(sessionId, userId, role) {
+        return this.client.makeRequest("POST", `/agent-sessions/${encodeURIComponent(sessionId)}/members`, { userId, role });
+    }
+    /**
+     * Remove a member (owner only): their grant on the document is revoked and
+     * the session leaves their list. Removing someone who is not a member
+     * succeeds with the members unchanged.
+     * @param sessionId - The session
+     * @param userId - The member to remove
+     */
+    async removeMember(sessionId, userId) {
+        return this.client.makeRequest("DELETE", `/agent-sessions/${encodeURIComponent(sessionId)}/members/${encodeURIComponent(userId)}`);
+    }
+}
+/** Agents, available as `client.agents`. */
+export class AgentsAPI {
+    /** @internal */
+    constructor(client) {
+        this.sessions = new AgentSessionsAPI(client);
+    }
+}