primitive-functions 0.3.0-alpha.0 → 0.3.0-alpha.1

package/index.d.ts

@@ -138,10 +138,41 @@ export interface PrimitivePlatformError extends Error {
  */
 export interface FunctionApi {
   "agentSessions": {
+    /** `agentSessions.addMember` — POST /agent-sessions/{sessionId}/members. Add a member to an agent session, or change their role */
+    "addMember"(args: {
+      "sessionId": string | number;
+      body: unknown;
+    }): Promise<any>;
     /** `agentSessions.create` — POST /agent-sessions. Create an agent session (ctx.agents.createSession) */
     "create"(args: {
       body: unknown;
     }): Promise<any>;
+    /** `agentSessions.delete` — DELETE /agent-sessions/{sessionId}. Delete an agent session */
+    "delete"(args: {
+      "sessionId": string | number;
+    }): Promise<any>;
+    /** `agentSessions.get` — GET /agent-sessions/{sessionId}. Get an agent session */
+    "get"(args: {
+      "sessionId": string | number;
+    }): Promise<any>;
+    /** `agentSessions.list` — GET /agent-sessions. List one user's agent sessions */
+    "list"(args?: {
+      "userId"?: string | number | boolean;
+      "agent"?: string | number | boolean;
+      "scope"?: string | number | boolean;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+    }): Promise<any>;
+    /** `agentSessions.removeMember` — DELETE /agent-sessions/{sessionId}/members/{userId}. Remove a member from an agent session */
+    "removeMember"(args: {
+      "sessionId": string | number;
+      "userId": string | number;
+    }): Promise<any>;
+    /** `agentSessions.rename` — PATCH /agent-sessions/{sessionId}. Rename an agent session */
+    "rename"(args: {
+      "sessionId": string | number;
+      body: unknown;
+    }): Promise<any>;
   };
   "analytics": {
     /** `analytics.cohortRetention` — GET /analytics/cohort-retention. Cohort retention metrics */
@@ -546,13 +577,6 @@ export interface FunctionApi {
     "get"(args: {
       "databaseId": string | number;
     }): Promise<any>;
-    /**
-     * `databases.getMetadata` — GET /databases/{databaseId}/metadata. DEPRECATED — get database metadata; use resource metadata categories (resources/database/:databaseId/metadata/:category)
-     * @deprecated Use resource metadata categories (resources/database/:databaseId/metadata/:category)
-     */
-    "getMetadata"(args: {
-      "databaseId": string | number;
-    }): Promise<any>;
     /** `databases.grantGroupPermission` — POST /databases/{databaseId}/group-permissions. Grant a group permission on a database */
     "grantGroupPermission"(args: {
       "databaseId": string | number;
@@ -706,14 +730,6 @@ export interface FunctionApi {
       "databaseId": string | number;
       body: unknown;
     }): Promise<any>;
-    /**
-     * `databases.updateMetadata` — PATCH /databases/{databaseId}/metadata. DEPRECATED — update database metadata; use resource metadata categories (resources/database/:databaseId/metadata/:category)
-     * @deprecated Use resource metadata categories (resources/database/:databaseId/metadata/:category)
-     */
-    "updateMetadata"(args: {
-      "databaseId": string | number;
-      body: unknown;
-    }): Promise<any>;
   };
   "documents": {
     /** `documents.abortIngest` — POST /documents/{documentId}/ingest/{sessionId}/abort. Abort a bulk-load session before its swap */
@@ -1722,6 +1738,17 @@ export interface AgentSessionCreateOptions<K extends SessionAgentKeys> {
   scope?: string;
   /** 1 to 255 characters; defaults to the agent's display name. */
   title?: string;
+  /**
+   * Initial participants, who send messages and hold a `read-write` grant
+   * on the session's document — #3805. Existing users of this app, not the
+   * caller; with `viewers`, at most 50.
+   */
+  participants?: string[];
+  /**
+   * Initial viewers, who read the session and hold a `reader` grant — #3805.
+   * Existing users of this app, not the caller, in neither list twice.
+   */
+  viewers?: string[];
 }
 
 /** What `ctx.agents.createSession` answers — #3803. */
@@ -1732,6 +1759,58 @@ export interface AgentSessionCreateResult {
   documentId: string;
 }
 
+/** What `ctx.agents.getSession` answers — #3805. Never the document's rows. */
+export interface AgentSessionInfo {
+  sessionId: string;
+  agentKey: string;
+  /** Open this with the document client to read the conversation. */
+  documentId: string;
+  ownerUserId: string;
+  /** ISO-8601. */
+  createdAt: string;
+  title: string | null;
+  scope: string | null;
+  /** ISO-8601; null when the session's listing row is missing. */
+  lastActivityAt: string | null;
+  /** The members, in the order they were added. */
+  members: { viewers: string[]; participants: string[] };
+  /** The invoking user's standing on the session. */
+  role: "owner" | "participant" | "viewer" | "admin";
+}
+
+/** One session in `ctx.agents.listSessions` — #3805. */
+export interface AgentSessionListItem {
+  sessionId: string;
+  agentKey: string;
+  scope: string | null;
+  documentId: string;
+  ownerUserId: string;
+  role: "owner" | "participant" | "viewer";
+  title: string | null;
+  /** ISO-8601. */
+  lastActivityAt: string;
+  createdAt: string | null;
+}
+
+/** What `ctx.agents.listSessions` takes — #3805. There is no user: it is always the invoking user. */
+export interface AgentSessionListOptions {
+  /** 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;
+}
+
+/** A page of `ctx.agents.listSessions` — #3805. */
+export interface AgentSessionListPage {
+  items: AgentSessionListItem[];
+  hasMore: boolean;
+  nextCursor?: string;
+}
+
 /** One agent's client tools, by name: each one's `input` and `output` (#3798). */
 export type AgentClientTools<K extends AgentKeys> = PromptSchemas[K] extends {
   agent: { clientTools: infer T };
@@ -2125,12 +2204,22 @@ export interface FunctionContext {
    * `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.
+   * 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.
    */
   agents: {
     createSession<K extends SessionAgentKeys>(
       options: AgentSessionCreateOptions<K>
     ): Promise<AgentSessionCreateResult>;
+    getSession(sessionId: string): Promise<AgentSessionInfo>;
+    listSessions(options?: AgentSessionListOptions): Promise<AgentSessionListPage>;
   };
   /**
    * 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.0",
+  "version": "0.3.0-alpha.1",
   "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",