primitive-functions 0.3.0-alpha.2 → 0.3.0-alpha.4

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>;
@@ -672,12 +693,6 @@ 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 */
@@ -838,7 +853,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 +863,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 +1116,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 +1174,10 @@ 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;
+    }): 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 +1337,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 +1361,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 +1388,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 +1461,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;
@@ -1704,7 +1726,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 +1906,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 +1935,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 +1998,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 +2022,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 +2408,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 +2475,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 +2504,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.2",
+  "version": "0.3.0-alpha.4",
   "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",