primitive-functions 0.2.0 → 0.3.0-alpha.0

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,12 @@ export interface PrimitivePlatformError extends Error {
  * stays refused: same-run composition is an import.
  */
 export interface FunctionApi {
+  "agentSessions": {
+    /** `agentSessions.create` — POST /agent-sessions. Create an agent session (ctx.agents.createSession) */
+    "create"(args: {
+      body: unknown;
+    }): Promise<any>;
+  };
   "analytics": {
     /** `analytics.cohortRetention` — GET /analytics/cohort-retention. Cohort retention metrics */
     "cohortRetention"(args?: {
@@ -509,56 +521,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;
@@ -830,13 +792,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 +1202,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 +1699,39 @@ 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;
+}
+
+/** 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;
+}
+
 /** 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 +1945,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 +2113,25 @@ 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.
+   */
+  agents: {
+    createSession<K extends SessionAgentKeys>(
+      options: AgentSessionCreateOptions<K>
+    ): Promise<AgentSessionCreateResult>;
+  };
   /**
    * The value of one app secret, under a `secret:<NAME>` grant (#3183).
    *
@@ -2144,6 +2197,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.0",
+  "version": "0.3.0-alpha.0",
   "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",