primitive-functions 0.3.0-alpha.3 → 0.3.0-alpha.5

package/index.d.ts

@@ -8,6 +8,20 @@
  * against (#3180). The published package's RUNTIME is a stub that throws from
  * every export on purpose: the platform substitutes its own copy at invoke
  * time, and reaching the stub means it did not.
+ *
+ * WHICH USER A CALL IS ABOUT. Every `ctx.api` and `ctx.agents` call that is
+ * about one user says which user in `userId`. Omitted, it means the invoking
+ * user (`ctx.user`); in a run with no caller (cron, a webhook, the system
+ * door, a nested start under one of them) it must be named, or the call
+ * rejects with `FUNCTION_SUBJECT_REQUIRED`. Naming a user other than the
+ * invoking user — whether `userId` is optional or required on the call — is
+ * allowed only in a run with no caller or one an app owner or admin invoked,
+ * with the role read at the call; an ordinary member's run, and every run an
+ * agent drives (a tool, context or history run and anything it starts),
+ * rejects with `SUBJECT_USER_FORBIDDEN`. A named user who is not a member of
+ * the app rejects with `SUBJECT_USER_NOT_FOUND`. Calls that hand something
+ * to a user (`notifications.send`, `users.setProfile`, a channel grant)
+ * and app-wide reads are outside this rule.
  */
 
 /**
@@ -170,7 +184,7 @@ export interface PrimitivePlatformError extends Error {
   /**
    * The route's structured `details`, or null when its refusal carries none
    * (#3803). `AGENT_SESSION_VARIABLES_INVALID` lists `errors` as
-   * `{ path, message }`; `AGENT_SESSION_ORIGIN_REFUSED` names `origin`.
+   * `{ path, message }`.
    */
   details: unknown;
 }
@@ -228,18 +242,24 @@ export interface FunctionApi {
     /** `agentSessions.get` — GET /agent-sessions/{sessionId}. Get an agent session */
     "get"(args: {
       "sessionId": string | number;
+      "userId"?: string | number;
     }): Promise<any>;
     /** `agentSessions.list` — GET /agent-sessions. List one user's agent sessions */
     "list"(args?: {
-      "userId"?: string | number | boolean;
+      "userId"?: string | number;
       "agent"?: string | number | boolean;
       "scope"?: string | number | boolean;
       "limit"?: string | number | boolean;
       "cursor"?: string | number | boolean;
     }): Promise<any>;
+    /** `agentSessions.markRead` — POST /agent-sessions/{sessionId}/read. Mark an agent session read */
+    "markRead"(args: {
+      "sessionId": string | number;
+    }): Promise<any>;
     /** `agentSessions.recordEvent` — POST /agent-sessions/{sessionId}/events. Record an event in an agent session (ctx.agents.recordEvent) */
     "recordEvent"(args: {
       "sessionId": string | number;
+      "userId"?: string | number;
       body: unknown;
     }): Promise<any>;
     /** `agentSessions.removeMember` — DELETE /agent-sessions/{sessionId}/members/{userId}. Remove a member from an agent session */
@@ -490,6 +510,7 @@ export interface FunctionApi {
     }): Promise<any>;
     /** `collections.list` — GET /collections. List collections */
     "list"(args?: {
+      "userId"?: string | number;
       "limit"?: string | number | boolean;
       "cursor"?: string | number | boolean;
     }): Promise<any>;
@@ -556,30 +577,14 @@ export interface FunctionApi {
       "dryRun"?: string | number | boolean;
       body: unknown;
     }): Promise<any>;
-    /** `databaseTypeConfigs.createOperation` — POST /databases/types/{databaseType}/operations. Create an operation for a database type */
-    "createOperation"(args: {
-      "databaseType": string | number;
-      "dryRun"?: string | number | boolean;
-      body: unknown;
-    }): Promise<any>;
     /** `databaseTypeConfigs.delete` — DELETE /databases/types/{databaseType}. Delete a database type */
     "delete"(args: {
       "databaseType": string | number;
     }): Promise<any>;
-    /** `databaseTypeConfigs.deleteOperation` — DELETE /databases/types/{databaseType}/operations/{name}. Delete an operation for a database type */
-    "deleteOperation"(args: {
-      "databaseType": string | number;
-      "name": string | number;
-    }): Promise<any>;
     /** `databaseTypeConfigs.get` — GET /databases/types/{databaseType}. Get a database type */
     "get"(args: {
       "databaseType": string | number;
     }): Promise<any>;
-    /** `databaseTypeConfigs.getOperation` — GET /databases/types/{databaseType}/operations/{name}. Get an operation for a database type */
-    "getOperation"(args: {
-      "databaseType": string | number;
-      "name": string | number;
-    }): Promise<any>;
     /** `databaseTypeConfigs.getReindexStatus` — GET /databases/types/{databaseType}/reindex-status. Status of the index back-provision fan-out for a type */
     "getReindexStatus"(args: {
       "databaseType": string | number;
@@ -587,54 +592,16 @@ export interface FunctionApi {
     }): Promise<any>;
     /** `databaseTypeConfigs.list` — GET /databases/types. List database types */
     "list"(args?: Record<string, never>): Promise<any>;
-    /** `databaseTypeConfigs.listOperations` — GET /databases/types/{databaseType}/operations. List operations for a database type */
-    "listOperations"(args: {
-      "databaseType": string | number;
-    }): Promise<any>;
     /** `databaseTypeConfigs.scaffoldSchema` — POST /databases/types/{databaseType}/schema:scaffold. Scaffold a starter schema for a database type */
     "scaffoldSchema"(args: {
       "databaseType": string | number;
     }): Promise<any>;
-    "subscriptions": {
-      /** `databaseTypeConfigs.subscriptions.create` — POST /databases/types/{databaseType}/subscriptions. Create a subscription for a database type */
-      "create"(args: {
-        "databaseType": string | number;
-        body: unknown;
-      }): Promise<any>;
-      /** `databaseTypeConfigs.subscriptions.delete` — DELETE /databases/types/{databaseType}/subscriptions/{subscriptionKey}. Delete a database type subscription */
-      "delete"(args: {
-        "databaseType": string | number;
-        "subscriptionKey": string | number;
-      }): Promise<any>;
-      /** `databaseTypeConfigs.subscriptions.get` — GET /databases/types/{databaseType}/subscriptions/{subscriptionKey}. Get a database type subscription */
-      "get"(args: {
-        "databaseType": string | number;
-        "subscriptionKey": string | number;
-      }): Promise<any>;
-      /** `databaseTypeConfigs.subscriptions.list` — GET /databases/types/{databaseType}/subscriptions. List subscriptions for a database type */
-      "list"(args: {
-        "databaseType": string | number;
-      }): Promise<any>;
-      /** `databaseTypeConfigs.subscriptions.update` — PUT /databases/types/{databaseType}/subscriptions/{subscriptionKey}. Update a database type subscription */
-      "update"(args: {
-        "databaseType": string | number;
-        "subscriptionKey": string | number;
-        body: unknown;
-      }): Promise<any>;
-    };
     /** `databaseTypeConfigs.update` — PATCH /databases/types/{databaseType}. Update a database type */
     "update"(args: {
       "databaseType": string | number;
       "dryRun"?: string | number | boolean;
       body: unknown;
     }): Promise<any>;
-    /** `databaseTypeConfigs.updateOperation` — PATCH /databases/types/{databaseType}/operations/{name}. Update an operation for a database type */
-    "updateOperation"(args: {
-      "databaseType": string | number;
-      "name": string | number;
-      "dryRun"?: string | number | boolean;
-      body: unknown;
-    }): Promise<any>;
   };
   "databases": {
     /** `databases.addManager` — PUT /databases/{databaseId}/permissions. Set a user's database permission */
@@ -650,19 +617,6 @@ export interface FunctionApi {
     "delete"(args: {
       "databaseId": string | number;
     }): Promise<any>;
-    /** `databases.executeBatch` — POST /databases/{databaseId}/operations/{name}/batch. Execute a database operation in batch */
-    "executeBatch"(args: {
-      "databaseId": string | number;
-      "name": string | number;
-      body: unknown;
-    }): Promise<any>;
-    /** `databases.executeOperation` — POST /databases/{databaseId}/operations/{name}/execute. Execute a database operation */
-    "executeOperation"(args: {
-      "databaseId": string | number;
-      "name": string | number;
-      "dryRun"?: string | number | boolean;
-      body?: unknown;
-    }): Promise<any>;
     /** `databases.get` — GET /databases/{databaseId}. Get a database by id */
     "get"(args: {
       "databaseId": string | number;
@@ -672,118 +626,108 @@ export interface FunctionApi {
       "databaseId": string | number;
       body: unknown;
     }): Promise<any>;
-    /** `databases.importBulk` — POST /databases/{databaseId}/operations/{name}/import-bulk. Bulk-import records via a database operation */
-    "importBulk"(args: {
-      "databaseId": string | number;
-      "name": string | number;
-      body: unknown;
-    }): Promise<any>;
     /** `databases.list` — GET /databases. List databases */
     "list"(args?: Record<string, never>): Promise<any>;
     /** `databases.listGroupPermissions` — GET /databases/{databaseId}/group-permissions. List a database's group permissions */
     "listGroupPermissions"(args: {
       "databaseId": string | number;
     }): Promise<any>;
-    /** `databases.listOperations` — GET /databases/{databaseId}/operations. List operations runnable on a database */
-    "listOperations"(args: {
-      "databaseId": string | number;
-    }): Promise<any>;
     /** `databases.listPermissions` — GET /databases/{databaseId}/permissions. List a database's user permissions */
     "listPermissions"(args: {
       "databaseId": string | number;
     }): Promise<any>;
     "records": {
-      /** `databases.records.addToSet` — POST /databases/{databaseId}/records/stringset/add. Database records: stringset/add (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.addToSet` — POST /databases/{databaseId}/records/stringset/add. Database records: stringset/add (app admin or owner) */
       "addToSet"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<any>;
-      /** `databases.records.aggregate` — POST /databases/{databaseId}/records/aggregate. Database records: aggregate (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.aggregate` — POST /databases/{databaseId}/records/aggregate. Database records: aggregate (app admin or owner) */
       "aggregate"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<any>;
-      /** `databases.records.batch` — POST /databases/{databaseId}/records/batch. Database records: batch (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.batch` — POST /databases/{databaseId}/records/batch. Database records: batch (app admin or owner) */
       "batch"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<any>;
-      /** `databases.records.count` — POST /databases/{databaseId}/records/count. Database records: count (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.count` — POST /databases/{databaseId}/records/count. Database records: count (app admin or owner) */
       "count"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<any>;
-      /** `databases.records.delete` — POST /databases/{databaseId}/records/delete. Database records: delete (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.delete` — POST /databases/{databaseId}/records/delete. Database records: delete (app admin or owner) */
       "delete"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<any>;
-      /** `databases.records.describe` — GET /databases/{databaseId}/records/describe. Database records: describe (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.describe` — GET /databases/{databaseId}/records/describe. Database records: describe (app admin or owner) */
       "describe"(args: {
         "databaseId": string | number;
         "modelName"?: string | number | boolean;
       }): Promise<any>;
-      /** `databases.records.dropIndex` — POST /databases/{databaseId}/records/index/drop. Database records: index/drop (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.dropIndex` — POST /databases/{databaseId}/records/index/drop. Database records: index/drop (app admin or owner) */
       "dropIndex"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<any>;
-      /** `databases.records.dropUniqueConstraint` — POST /databases/{databaseId}/records/unique-constraint/drop. Database records: unique-constraint/drop (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.dropUniqueConstraint` — POST /databases/{databaseId}/records/unique-constraint/drop. Database records: unique-constraint/drop (app admin or owner) */
       "dropUniqueConstraint"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<any>;
-      /** `databases.records.increment` — POST /databases/{databaseId}/records/increment. Database records: increment (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.increment` — POST /databases/{databaseId}/records/increment. Database records: increment (app admin or owner) */
       "increment"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<any>;
-      /** `databases.records.listIndexes` — GET /databases/{databaseId}/records/indexes. Database records: indexes (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.listIndexes` — GET /databases/{databaseId}/records/indexes. Database records: indexes (app admin or owner) */
       "listIndexes"(args: {
         "databaseId": string | number;
         "modelName"?: string | number | boolean;
       }): Promise<any>;
-      /** `databases.records.listUniqueConstraints` — GET /databases/{databaseId}/records/unique-constraints. Database records: unique-constraints (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.listUniqueConstraints` — GET /databases/{databaseId}/records/unique-constraints. Database records: unique-constraints (app admin or owner) */
       "listUniqueConstraints"(args: {
         "databaseId": string | number;
         "modelName"?: string | number | boolean;
       }): Promise<any>;
-      /** `databases.records.models` — GET /databases/{databaseId}/records/models. Database records: models (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.models` — GET /databases/{databaseId}/records/models. Database records: models (app admin or owner) */
       "models"(args: {
         "databaseId": string | number;
         "modelName"?: string | number | boolean;
       }): Promise<any>;
-      /** `databases.records.patch` — POST /databases/{databaseId}/records/patch. Database records: patch (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.patch` — POST /databases/{databaseId}/records/patch. Database records: patch (app admin or owner) */
       "patch"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<any>;
-      /** `databases.records.query` — POST /databases/{databaseId}/records/query. Database records: query (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.query` — POST /databases/{databaseId}/records/query. Database records: query (app admin or owner) */
       "query"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<{ items: any[]; hasMore: boolean; nextCursor?: string; prevCursor?: string }>;
-      /** `databases.records.registerIndex` — POST /databases/{databaseId}/records/index/register. Database records: index/register (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.registerIndex` — POST /databases/{databaseId}/records/index/register. Database records: index/register (app admin or owner) */
       "registerIndex"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<any>;
-      /** `databases.records.registerUniqueConstraint` — POST /databases/{databaseId}/records/unique-constraint/register. Database records: unique-constraint/register (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.registerUniqueConstraint` — POST /databases/{databaseId}/records/unique-constraint/register. Database records: unique-constraint/register (app admin or owner) */
       "registerUniqueConstraint"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<any>;
-      /** `databases.records.removeFromSet` — POST /databases/{databaseId}/records/stringset/remove. Database records: stringset/remove (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.removeFromSet` — POST /databases/{databaseId}/records/stringset/remove. Database records: stringset/remove (app admin or owner) */
       "removeFromSet"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<any>;
-      /** `databases.records.save` — POST /databases/{databaseId}/records/save. Database records: save (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.save` — POST /databases/{databaseId}/records/save. Database records: save (app admin or owner) */
       "save"(args: {
         "databaseId": string | number;
         body: unknown;
       }): Promise<any>;
-      /** `databases.records.syncIndexes` — POST /databases/{databaseId}/records/indexes/sync. Database records: indexes/sync (requires manager-or-higher on the database, or an app-admin/owner role) */
+      /** `databases.records.syncIndexes` — POST /databases/{databaseId}/records/indexes/sync. Database records: indexes/sync (app admin or owner) */
       "syncIndexes"(args: {
         "databaseId": string | number;
         body: unknown;
@@ -804,12 +748,6 @@ export interface FunctionApi {
       "databaseId": string | number;
       "userId": string | number;
     }): Promise<any>;
-    /** `databases.runOperation` — POST /databases/{databaseId}/operations/{name}/run. Run a database operation under a server function's grants */
-    "runOperation"(args: {
-      "databaseId": string | number;
-      "name": string | number;
-      body?: unknown;
-    }): Promise<any>;
     /** `databases.transferOwnership` — POST /databases/{databaseId}/permissions/transfer. Transfer database ownership */
     "transferOwnership"(args: {
       "databaseId": string | number;
@@ -838,7 +776,7 @@ export interface FunctionApi {
       "delete"(args: {
         "scope": string | number;
         "aliasKey": string | number;
-        "userId"?: string | number | boolean;
+        "userId"?: string | number;
       }): Promise<any>;
       /** `documents.aliases.listForDocument` — GET /documents/{documentId}/aliases. List aliases bound to a document */
       "listForDocument"(args: {
@@ -848,7 +786,7 @@ export interface FunctionApi {
       "resolve"(args: {
         "scope": string | number;
         "aliasKey": string | number;
-        "userId"?: string | number | boolean;
+        "userId"?: string | number;
       }): Promise<any>;
       /** `documents.aliases.set` — PUT /document-aliases/{scope}/{aliasKey}. Bind a (scope, aliasKey) alias to a document */
       "set"(args: {
@@ -1101,6 +1039,7 @@ export interface FunctionApi {
         "model": string | number;
         "recordId": string | number;
         "documentFormat"?: string | number | boolean;
+        "requestId"?: string | number | boolean;
       }): Promise<any>;
       /** `documents.records.patch` — PATCH /documents/{documentId}/records/{model}/{recordId}. Merge fields into an existing record in a document model */
       "patch"(args: {
@@ -1158,6 +1097,13 @@ export interface FunctionApi {
       "groupType": string | number;
       "groupId": string | number;
     }): Promise<any>;
+    /** `documents.room` — GET /documents/{documentId}/room. Inspect a record-log document's room */
+    "room"(args: {
+      "documentId": string | number;
+      "refused"?: string | number | boolean;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+    }): Promise<any>;
     /** `documents.setLinkAccess` — PUT /documents/{documentId}/link-access. Set the document's "anyone with the link" access level */
     "setLinkAccess"(args: {
       "documentId": string | number;
@@ -1317,10 +1263,6 @@ export interface FunctionApi {
     }): Promise<any>;
     /** `integrations.list` — GET /integrations. List integrations configured for the app */
     "list"(args?: Record<string, never>): Promise<any>;
-    /** `integrations.proxy` — POST /integrations/{integrationKey}/proxy. Proxy a request through a configured integration */
-    "proxy"(args: {
-      "integrationKey": string | number;
-    }): Promise<any>;
   };
   "locks": {
     /** `locks.list` — GET /locks. List all currently-held named locks in the app */
@@ -1345,19 +1287,26 @@ export interface FunctionApi {
   "notifications": {
     /** `notifications.list` — GET /notifications. List the caller's in-app notification inbox (newest first) */
     "list"(args?: {
+      "userId"?: string | number;
       "limit"?: string | number | boolean;
       "cursor"?: string | number | boolean;
     }): Promise<any>;
     /** `notifications.listDevices` — GET /me/push-tokens. List the caller's registered push devices */
-    "listDevices"(args?: Record<string, never>): Promise<any>;
+    "listDevices"(args?: {
+      "userId"?: string | number;
+    }): Promise<any>;
     /** `notifications.markAllRead` — POST /notifications/read-all. Mark all of the caller's notifications as read */
-    "markAllRead"(args?: Record<string, never>): Promise<any>;
+    "markAllRead"(args?: {
+      "userId"?: string | number;
+    }): Promise<any>;
     /** `notifications.markRead` — PATCH /notifications/{notificationId}/read. Mark one of the caller's notifications as read */
     "markRead"(args: {
       "notificationId": string | number;
+      "userId"?: string | number;
     }): Promise<any>;
     /** `notifications.registerDevice` — POST /me/push-tokens. Register (upsert) the caller's device push token */
     "registerDevice"(args: {
+      "userId"?: string | number;
       body: unknown;
     }): Promise<any>;
     /** `notifications.send` — POST /notifications/send. Send a notification to an app user (durable in-app inbox row + live WS frame) */
@@ -1365,17 +1314,16 @@ export interface FunctionApi {
       body: unknown;
     }): Promise<any>;
     /** `notifications.unreadCount` — GET /notifications/unread-count. Count the caller's unread notifications */
-    "unreadCount"(args?: Record<string, never>): Promise<any>;
+    "unreadCount"(args?: {
+      "userId"?: string | number;
+    }): Promise<any>;
     /** `notifications.unregisterDevice` — DELETE /me/push-tokens/{token}. Unregister one of the caller's device push tokens */
     "unregisterDevice"(args: {
       "token": string | number;
+      "userId"?: string | number;
     }): Promise<any>;
   };
   "prompts": {
-    /** `prompts.execute` — POST /prompts/{promptKey}/execute. Execute a saved prompt */
-    "execute"(args: {
-      "promptKey": string | number;
-    }): Promise<any>;
     /** `prompts.run` — POST /prompts/{promptKey}/run. Run a prompt under a server function's grants */
     "run"(args: {
       "promptKey": string | number;
@@ -1439,7 +1387,7 @@ export interface FunctionApi {
     /** `users.list` — GET /users. List app users */
     "list"(args?: {
       "email"?: string | number | boolean;
-      "userId"?: string | number | boolean;
+      "userId"?: string | number;
       "name"?: string | number | boolean;
       "limit"?: string | number | boolean;
       "cursor"?: string | number | boolean;
@@ -1665,8 +1613,6 @@ export interface DatabaseHandle<TModels> {
     operations: Array<Record<string, unknown>>;
     atomic?: boolean;
   }): Promise<any>;
-  /** Run one of the database type's prepared operations under this function's grants. */
-  runOperation(name: string, params?: Record<string, unknown>): Promise<any>;
 }
 
 /**
@@ -1704,7 +1650,7 @@ export interface DocumentQueryOptions {
    * Usually stated once on the handle, as ctx.doc(id, { documentFormat: 2 }),
    * rather than per read.
    */
-  documentFormat?: 1 | 2;
+  documentFormat?: 1 | 2 | 3;
 }
 
 /**
@@ -1884,6 +1830,12 @@ export interface AgentSessionCreateOptions<K extends SessionAgentKeys> {
    * Existing users of this app, not the caller, in neither list twice.
    */
   viewers?: string[];
+  /**
+   * The member who owns the session; omitted, the invoking user. A run with
+   * no caller must name one; naming another member follows the header's
+   * subject rule. Initial members may not name the owner.
+   */
+  userId?: string;
 }
 
 /** What `ctx.agents.createSession` answers — #3803. */
@@ -1907,9 +1859,16 @@ export interface AgentSessionInfo {
   scope: string | null;
   /** ISO-8601; null when the session's listing row is missing. */
   lastActivityAt: string | null;
+  /**
+   * Whether the invoking user has activity in the session they have not
+   * marked read (their client marks it); false for an admin with no role.
+   */
+  hasUnread: boolean;
+  /** When the invoking user last marked the session read (ISO-8601), or null. */
+  lastReadAt: string | null;
   /** The members, in the order they were added. */
   members: { viewers: string[]; participants: string[] };
-  /** The invoking user's standing on the session. */
+  /** The standing on the session of the member the call acted as. */
   role: "owner" | "participant" | "viewer" | "admin";
   /**
    * The session's status, decided from the session object (never the
@@ -1963,10 +1922,20 @@ export interface AgentSessionListItem {
   /** ISO-8601. */
   lastActivityAt: string;
   createdAt: string | null;
+  /** Whether the user has activity in the session they have not marked read. */
+  hasUnread: boolean;
+  /** When the user last marked the session read (ISO-8601), or null. */
+  lastReadAt: string | null;
 }
 
-/** What `ctx.agents.listSessions` takes — #3805. There is no user: it is always the invoking user. */
+/** What `ctx.agents.listSessions` takes — #3805. */
 export interface AgentSessionListOptions {
+  /**
+   * Whose sessions; omitted, the invoking user's. A run with no caller must
+   * name one, and naming another follows the header's subject rule. A user
+   * with no sessions here, member or not, answers an empty page.
+   */
+  userId?: string;
   /** Only this agent's sessions. */
   agent?: string;
   /** Only sessions created with exactly this scope. */
@@ -1977,6 +1946,15 @@ export interface AgentSessionListOptions {
   cursor?: string;
 }
 
+/**
+ * Which member `ctx.agents.getSession` and `recordEvent` act as. Omitted,
+ * the invoking user; a run with no caller must name one, and naming another
+ * follows the header's subject rule.
+ */
+export interface AgentSessionSubjectOptions {
+  userId?: string;
+}
+
 /** A page of `ctx.agents.listSessions` — #3805. */
 export interface AgentSessionListPage {
   items: AgentSessionListItem[];
@@ -2354,7 +2332,7 @@ export interface FunctionContext {
    * confers nothing: every call is a `documents.records.*` operation on the
    * same authority.
    */
-  doc(documentId: string, options?: { documentFormat?: 1 | 2 }): DocumentHandle;
+  doc(documentId: string, options?: { documentFormat?: 1 | 2 | 3 }): DocumentHandle;
   /**
    * Outbound HTTP, through a granted integration and nowhere else (#3183).
    *
@@ -2421,30 +2399,27 @@ export interface FunctionContext {
     ): Promise<PromptRunResult<K>>;
   };
   /**
-   * Agent sessions (#3803, project `agents`).
-   *
-   * `createSession` creates a session owned by this invocation's caller and
-   * answers `{ sessionId, documentId }`. It is allowed only in a run fired
-   * over HTTP (`invoke`, or a `start` task) by a signed-in user; from a
-   * manual run, a nested start, a workflow step, cron or a webhook it
-   * rejects with `AGENT_SESSION_ORIGIN_REFUSED`, `details.origin` naming
-   * it. Variables failing the agent's `inputSchema` reject with
-   * `AGENT_SESSION_VARIABLES_INVALID` and `details.errors`.
+   * Agent sessions (#3803, project `agents`), on the header's subject rule:
+   * each call acts for `userId`, else the invoking user, and from any kind of
+   * run — a run with no caller must name the member.
    *
-   * Once a tree has pushed, a key that is not an agent, and variables the
-   * agent's schema refuses, are compile errors. `participants` and
-   * `viewers` name initial members (#3805).
+   * `createSession` creates a session that member owns and answers
+   * `{ sessionId, documentId }`. Variables failing the agent's
+   * `inputSchema` reject with `AGENT_SESSION_VARIABLES_INVALID` and
+   * `details.errors`. Once a tree has pushed, a key that is not an agent,
+   * and variables the agent's schema refuses, are compile errors.
+   * `participants` and `viewers` name initial members (#3805).
    *
-   * `getSession` and `listSessions` (#3805) read the INVOKING user's
-   * sessions — the ones they own or are a member of — and nobody else's,
-   * whoever invoked the function; a session the user is not in answers
-   * `AGENT_SESSION_NOT_FOUND`. Both have the same origin rule as
-   * `createSession`. Renaming, deleting and changing members are the
-   * owner's, from a client.
+   * `getSession` and `listSessions` (#3805) read the member's sessions —
+   * the ones they own or are a member of — as that member, with no admin arm
+   * whoever invoked the function: a session they are not in answers
+   * `AGENT_SESSION_NOT_FOUND`, and function code never sees a session's
+   * `object`, `turnContexts` or `lastTurn`. Renaming, deleting and
+   * changing members are the owner's, from a client.
    *
-   * `recordEvent` (#3807) records an event in one of the invoking user's
-   * sessions, as that member: they must be its owner or a participant, and
-   * the origin rule is `createSession`'s. The kind must be one the agent
+   * `recordEvent` (#3807) records an event as the member, who must be the
+   * session's owner or a participant (`AGENT_SESSION_PARTICIPANT_ONLY` for a
+   * viewer); the row is authored `app`. The kind must be one the agent
    * declares (`AGENT_EVENT_KIND_UNKNOWN`) and the data must match its schema
    * (`AGENT_EVENT_INVALID`). An event never starts a turn; the model reads
    * it in a later turn.
@@ -2453,9 +2428,16 @@ export interface FunctionContext {
     createSession<K extends SessionAgentKeys>(
       options: AgentSessionCreateOptions<K>
     ): Promise<AgentSessionCreateResult>;
-    getSession(sessionId: string): Promise<AgentSessionInfo>;
+    getSession(
+      sessionId: string,
+      options?: AgentSessionSubjectOptions
+    ): Promise<AgentSessionInfo>;
     listSessions(options?: AgentSessionListOptions): Promise<AgentSessionListPage>;
-    recordEvent(sessionId: string, event: AgentSessionEvent): Promise<AgentSessionEventResult>;
+    recordEvent(
+      sessionId: string,
+      event: AgentSessionEvent,
+      options?: AgentSessionSubjectOptions
+    ): Promise<AgentSessionEventResult>;
   };
   /**
    * The value of one app secret, under a `secret:<NAME>` grant (#3183).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primitive-functions",
-  "version": "0.3.0-alpha.3",
+  "version": "0.3.0-alpha.5",
   "description": "The module a Primitive server function imports. Supplied by the platform at invoke time; reserved here so the name is ours before the runtime lands.",
   "license": "UNLICENSED",
   "author": "Primitive LLC",