primitive-functions 0.2.1 → 0.3.0-alpha.1

package/index.d.ts

@@ -110,11 +110,17 @@ export interface HeaderResult {
 export interface PrimitivePlatformError extends Error {
   status: number;
   errorCode: string | null;
+  /**
+   * 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`.
+   */
+  details: unknown;
 }
 
 /**
  * The typed HTTP profile, generated from the platform's OpenAPI document. Its
- * namespaces mirror the operation ids: analytics, blobBuckets, channels, collections, configVars, connections, databaseTypeConfigs, databases, documents, email, functions, groups, integrations, locks, notifications, prompts, resourceMetadata, secrets, users.
+ * namespaces mirror the operation ids: agentSessions, analytics, blobBuckets, channels, collections, configVars, connections, databaseTypeConfigs, databases, documents, email, functions, groups, integrations, locks, notifications, prompts, resourceMetadata, secrets, users.
  * Methods take one options object carrying the operation's path parameters,
  * query parameters, request headers (under their wire names) and `body`.
  *
@@ -131,6 +137,43 @@ export interface PrimitivePlatformError extends Error {
  * stays refused: same-run composition is an import.
  */
 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 */
     "cohortRetention"(args?: {
@@ -509,56 +552,6 @@ export interface FunctionApi {
       "databaseId": string | number;
       body: unknown;
     }): Promise<any>;
-    "adminData": {
-      /**
-       * `databases.adminData.batch` — POST /databases/{databaseId}/admin-data/batch. DEPRECATED — direct database batch; use databases/{databaseId}/records/batch
-       * @deprecated Use databases/{databaseId}/records/batch
-       */
-      "batch"(args: {
-        "databaseId": string | number;
-        body: unknown;
-      }): Promise<any>;
-      /**
-       * `databases.adminData.count` — POST /databases/{databaseId}/admin-data/count. DEPRECATED — direct database count; use databases/{databaseId}/records/count
-       * @deprecated Use databases/{databaseId}/records/count
-       */
-      "count"(args: {
-        "databaseId": string | number;
-        body: unknown;
-      }): Promise<any>;
-      /**
-       * `databases.adminData.delete` — POST /databases/{databaseId}/admin-data/delete. DEPRECATED — direct database delete; use databases/{databaseId}/records/delete
-       * @deprecated Use databases/{databaseId}/records/delete
-       */
-      "delete"(args: {
-        "databaseId": string | number;
-        body: unknown;
-      }): Promise<any>;
-      /**
-       * `databases.adminData.patch` — POST /databases/{databaseId}/admin-data/patch. DEPRECATED — direct database patch; use databases/{databaseId}/records/patch
-       * @deprecated Use databases/{databaseId}/records/patch
-       */
-      "patch"(args: {
-        "databaseId": string | number;
-        body: unknown;
-      }): Promise<any>;
-      /**
-       * `databases.adminData.query` — POST /databases/{databaseId}/admin-data/query. DEPRECATED — direct database query; use databases/{databaseId}/records/query
-       * @deprecated Use databases/{databaseId}/records/query
-       */
-      "query"(args: {
-        "databaseId": string | number;
-        body: unknown;
-      }): Promise<any>;
-      /**
-       * `databases.adminData.save` — POST /databases/{databaseId}/admin-data/save. DEPRECATED — direct database save; use databases/{databaseId}/records/save
-       * @deprecated Use databases/{databaseId}/records/save
-       */
-      "save"(args: {
-        "databaseId": string | number;
-        body: unknown;
-      }): Promise<any>;
-    };
     /** `databases.create` — POST /databases. Create a database */
     "create"(args: {
       body: unknown;
@@ -584,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;
@@ -744,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 */
@@ -830,13 +808,6 @@ export interface FunctionApi {
         "X-Blob-Sha256": string | number;
         body: ArrayBuffer | Uint8Array | string;
       }): Promise<any>;
-      /**
-       * `documents.blobs.uploadWithoutId` — PUT /documents/{documentId}/blobs. Deprecated: upload a document blob without a client-specified id
-       * @deprecated Deprecated in the app API spec; see its description.
-       */
-      "uploadWithoutId"(args: {
-        "documentId": string | number;
-      }): Promise<any>;
     };
     /** `documents.clearLinkAccess` — DELETE /documents/{documentId}/link-access. Turn off the document's link access */
     "clearLinkAccess"(args: {
@@ -1247,7 +1218,7 @@ export interface FunctionApi {
     "status"(args: {
       body: unknown;
     }): Promise<any>;
-    /** `locks.tryAcquire` — POST /locks/acquire. Attempt to acquire a named lock (single non-blocking attempt) */
+    /** `locks.tryAcquire` — POST /locks/acquire. Attempt to acquire a named lock (one attempt, or with waitMs a bounded server-side wait) */
     "tryAcquire"(args: {
       body: unknown;
     }): Promise<any>;
@@ -1744,6 +1715,102 @@ export type AgentVariables<K extends AgentKeys> = PromptSchemas[K] extends {
   ? V
   : never;
 
+/**
+ * The keys `ctx.agents.createSession` accepts — #3803: every declared agent,
+ * or `string` before the tree has pushed any prompt (the `PromptKeys`
+ * rule).
+ */
+export type SessionAgentKeys = [keyof PromptSchemas] extends [never]
+  ? string
+  : AgentKeys;
+
+/**
+ * What `ctx.agents.createSession` takes — #3803. Typed by the agent's key:
+ * `variables` is that agent's `inputSchema` (any object before a push),
+ * and the platform validates it again against the schema as pushed.
+ */
+export interface AgentSessionCreateOptions<K extends SessionAgentKeys> {
+  /** The key of an agent prompt (`kind = "agent"`). */
+  agent: K;
+  /** The session's variables; at most 16 KiB of JSON. */
+  variables?: K extends AgentKeys ? AgentVariables<K> : Record<string, unknown>;
+  /** Free text the app groups sessions by, 1 to 256 characters. */
+  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. */
+export interface AgentSessionCreateResult {
+  /** The session: what the app keeps and uses for everything but opening. */
+  sessionId: string;
+  /** The session's conversation document, opened with the document client. */
+  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 };
@@ -1957,6 +2024,52 @@ export interface FunctionStartResult {
   existing?: boolean;
 }
 
+/** A held named lock, as `ctx.locks.acquire` hands it back — #3930. */
+export interface LockHandle {
+  key: string;
+  handleId: string;
+  leaseExpiresAt: string;
+}
+
+/** How long to hold, and how long to wait — #3930. */
+export interface LockAcquireOptions {
+  /** The lease, in milliseconds (at most 24 h). Renew or release before it lapses. */
+  ttlMs: number;
+  /**
+   * How long to wait for the key, in milliseconds, at most one hour. Under the
+   * request runtime it must also fit the invocation's remaining budget.
+   */
+  timeoutMs: number;
+  /**
+   * Who this hold belongs to. Defaults to `ctx.runId` when the invocation
+   * has a run, so a resumed slice re-takes its own hold with a fresh handle
+   * rather than waiting on it.
+   */
+  owner?: string;
+}
+
+/**
+ * The answer to a blocking acquire — #3930. Never a throw for "not acquired":
+ * a refusal carries the last contention seen, and `rateLimited` says the
+ * last attempt was refused by the acquire rate limit rather than by a holder.
+ */
+export type LockAcquireResult =
+  | { acquired: true; handle: LockHandle }
+  | {
+      acquired: false;
+      timedOut: true;
+      rateLimited: boolean;
+      heldBy: string | null;
+      holderKind: string | null;
+      owner: string | null;
+      leaseExpiresAt: string | null;
+    };
+
+/** The answer to `ctx.locks.release`. */
+export type LockReleaseResult =
+  | { released: true }
+  | { released: false; reason: "not_holder" | "not_held" };
+
 export interface FunctionContext {
   /** The HTTP caller, or null for a webhook or cron fire. */
   user: FunctionUser | null;
@@ -2079,6 +2192,35 @@ export interface FunctionContext {
       args?: PromptRunArgs
     ): 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`.
+   *
+   * 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.
+   */
+  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).
    *
@@ -2144,6 +2286,47 @@ export interface FunctionContext {
     ): Promise<ChannelGrantResult>;
     publish(channel: string, payload: unknown): Promise<SendResult>;
   };
+  /**
+   * Named locks that WAIT — #3930. `ctx.api.locks.tryAcquire` is one attempt;
+   * these wait for the key, up to `timeoutMs` (at most one hour).
+   *
+   * The owner defaults to `ctx.runId`, so a run never waits on its own hold:
+   * a resumed slice, or a second call on a key the run already holds, re-takes
+   * it at once with a fresh handle.
+   *
+   * Under the TASK runtime the wait is durable: each attempt is a step that
+   * asks the platform to wait server-side for up to 30 s, so a wait costs one
+   * platform call and one acquire slot per half-minute, no CPU, and the
+   * slice's budget is refreshed at every attempt. It is not a suspension — the
+   * engine does not hibernate a wait shorter than five minutes. Under the
+   * REQUEST runtime the whole wait must fit the invocation's remaining budget,
+   * or the call fails `FUNCTION_RUNTIME_REFUSED` before any attempt (a
+   * webhook delivery has 5 s): hand longer waits to a task with
+   * `ctx.functions.start`.
+   */
+  locks: {
+    /**
+     * Wait for `key`. Answers `acquired: true` with the handle, or
+     * `acquired: false, timedOut: true` with the last contention seen.
+     */
+    acquire(key: string, options: LockAcquireOptions): Promise<LockAcquireResult>;
+    /** Release a handle `acquire` handed back. */
+    release(handle: LockHandle): Promise<LockReleaseResult>;
+    /**
+     * Acquire, run `fn`, and release in `finally` — on a return and on a
+     * throw. Answers `fn`'s value; `fn`'s own error propagates after the
+     * release. Throws an error named `LOCK_TIMEOUT` (`code` the same, the
+     * contention in `details`) without running `fn` when the key is not
+     * acquired within `timeoutMs`. A nested `withLock` on the same key in
+     * one run re-enters, and its release frees the outer hold: use distinct
+     * keys, or one wrapper.
+     */
+    withLock<T>(
+      key: string,
+      options: LockAcquireOptions,
+      fn: (handle: LockHandle) => Promise<T>
+    ): Promise<T>;
+  };
 }
 
 /** How the wait between one step's retries grows. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primitive-functions",
-  "version": "0.2.1",
+  "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",