primitive-functions 0.2.0-alpha.8 → 0.2.0

package/index.d.ts

@@ -32,8 +32,15 @@ export interface FunctionUser {
  * that the fire path does not set.
  */
 export type FunctionTrigger =
-  /** An HTTP invocation: the caller is `ctx.user`. */
-  | { kind: "http" }
+  /**
+   * An HTTP invocation: the caller is `ctx.user`.
+   *
+   * `runKey` is the key a `start` was coalesced by (#3562) — what you
+   * passed as `runKey` to make the run a singleton — and null when the
+   * start named none, or when the call was an `invoke`, which coalesces
+   * nothing.
+   */
+  | { kind: "http"; runKey: string | null }
   /** A verified webhook delivery to the function's own key. */
   | {
       kind: "webhook";
@@ -56,8 +63,6 @@ export type FunctionTrigger =
       /** Present, and true, only on the diagnostic fire: nothing was scheduled. */
       manual?: true;
     }
-  /** A write to a watched database type. */
-  | { kind: "database"; databaseId: string; databaseType: string }
   /**
    * A DSL workflow's `workflow.call` step reached this function (#3288).
    *
@@ -71,19 +76,25 @@ export type FunctionTrigger =
    * Another function started this one with `ctx.functions.start` (#3280).
    *
    * `functionKey` names the PARENT, and `runId` its run — null when the
-   * parent was a request invocation over HTTP, which writes no run row, or a
-   * database-change fire, which writes none either.
+   * parent was a request invocation over HTTP, which writes no run row.
+   * `runKey` is the key the parent's start named, or null (#3562).
    */
-  | { kind: "function"; functionKey: string; runId: string | null }
+  | {
+      kind: "function";
+      functionKey: string;
+      runId: string | null;
+      runKey: string | null;
+    }
   /**
    * An admin ran this function as the SYSTEM, from outside any trigger
    * (#3448) — `primitive functions invoke --as system`.
    *
    * `ctx.user` is null and the code runs with the app's system authority, as
    * it does for a cron or webhook fire. `userId` names the admin who asked:
-   * attribution, never the principal the code runs as.
+   * attribution, never the principal the code runs as. `runKey` is the key
+   * the admin's start named, or null (#3562).
    */
-  | { kind: "manual"; userId: string };
+  | { kind: "manual"; userId: string; runKey: string | null };
 
 /** The result shape of an operation that answers in response headers. */
 export interface HeaderResult {
@@ -103,7 +114,7 @@ export interface PrimitivePlatformError extends Error {
 
 /**
  * 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, gemini, groups, integrations, llm, locks, notifications, prompts, resourceMetadata, secrets, users.
+ * namespaces mirror the operation ids: 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`.
  *
@@ -358,6 +369,8 @@ export interface FunctionApi {
     /** `collections.listCollectionsForDocument` — GET /documents/{documentId}/collections. List collections a document belongs to (reverse lookup) */
     "listCollectionsForDocument"(args: {
       "documentId": string | number;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
     }): Promise<any>;
     /** `collections.listDocuments` — GET /collections/{collectionId}/documents. List documents in a collection */
     "listDocuments"(args: {
@@ -497,32 +510,50 @@ export interface FunctionApi {
       body: unknown;
     }): Promise<any>;
     "adminData": {
-      /** `databases.adminData.batch` — POST /databases/{databaseId}/admin-data/batch. DEPRECATED — direct database batch; use databases/{databaseId}/records/batch */
+      /**
+       * `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 */
+      /**
+       * `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 */
+      /**
+       * `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 */
+      /**
+       * `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 */
+      /**
+       * `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 */
+      /**
+       * `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;
@@ -553,7 +584,10 @@ export interface FunctionApi {
     "get"(args: {
       "databaseId": string | number;
     }): Promise<any>;
-    /** `databases.getMetadata` — GET /databases/{databaseId}/metadata. Get database metadata */
+    /**
+     * `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>;
@@ -710,13 +744,22 @@ export interface FunctionApi {
       "databaseId": string | number;
       body: unknown;
     }): Promise<any>;
-    /** `databases.updateMetadata` — PATCH /databases/{databaseId}/metadata. Update database metadata */
+    /**
+     * `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 */
+    "abortIngest"(args: {
+      "documentId": string | number;
+      "sessionId": string | number;
+      body: unknown;
+    }): Promise<any>;
     /** `documents.addTag` — POST /documents/{documentId}/tags. Add a tag to a document */
     "addTag"(args: {
       "documentId": string | number;
@@ -727,6 +770,7 @@ export interface FunctionApi {
       "delete"(args: {
         "scope": string | number;
         "aliasKey": string | number;
+        "userId"?: string | number | boolean;
       }): Promise<any>;
       /** `documents.aliases.listForDocument` — GET /documents/{documentId}/aliases. List aliases bound to a document */
       "listForDocument"(args: {
@@ -736,6 +780,7 @@ export interface FunctionApi {
       "resolve"(args: {
         "scope": string | number;
         "aliasKey": string | number;
+        "userId"?: string | number | boolean;
       }): Promise<any>;
       /** `documents.aliases.set` — PUT /document-aliases/{scope}/{aliasKey}. Bind a (scope, aliasKey) alias to a document */
       "set"(args: {
@@ -785,7 +830,10 @@ 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 */
+      /**
+       * `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>;
@@ -794,10 +842,21 @@ export interface FunctionApi {
     "clearLinkAccess"(args: {
       "documentId": string | number;
     }): Promise<any>;
+    /** `documents.commitIngest` — POST /documents/{documentId}/ingest/{sessionId}/commit. Commit a bulk-load session: freeze its manifest and apply it */
+    "commitIngest"(args: {
+      "documentId": string | number;
+      "sessionId": string | number;
+      body: unknown;
+    }): Promise<any>;
     /** `documents.create` — POST /documents. Create a new document */
     "create"(args: {
       body: unknown;
     }): Promise<any>;
+    /** `documents.createIngest` — POST /documents/{documentId}/ingest. Open a bulk-load session on a large document */
+    "createIngest"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
     /** `documents.createWithAlias` — POST /documents/create-with-alias. Create a document and bind it to an alias */
     "createWithAlias"(args: {
       body: unknown;
@@ -855,6 +914,11 @@ export interface FunctionApi {
     "getImportChainStatus"(args: {
       "documentId": string | number;
     }): Promise<any>;
+    /** `documents.getIngest` — GET /documents/{documentId}/ingest/{sessionId}. One bulk-load session's status */
+    "getIngest"(args: {
+      "documentId": string | number;
+      "sessionId": string | number;
+    }): Promise<any>;
     /** `documents.getLinkAccess` — GET /documents/{documentId}/link-access. Get the document's "anyone with the link" access level */
     "getLinkAccess"(args: {
       "documentId": string | number;
@@ -913,6 +977,12 @@ export interface FunctionApi {
     "listGroupPermissions"(args: {
       "documentId": string | number;
     }): Promise<any>;
+    /** `documents.listIngests` — GET /documents/{documentId}/ingest. List a large document's bulk-load sessions, newest first */
+    "listIngests"(args: {
+      "documentId": string | number;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+    }): Promise<any>;
     /** `documents.listPendingInvitations` — GET /documents/{documentId}/pending-invitations. List a document's pending (deferred) invitations */
     "listPendingInvitations"(args: {
       "documentId": string | number;
@@ -932,17 +1002,20 @@ export interface FunctionApi {
       "aggregate"(args: {
         "documentId": string | number;
         "model": string | number;
+        "documentFormat"?: string | number | boolean;
         body: unknown;
       }): Promise<any>;
       /** `documents.records.bulk` — POST /documents/{documentId}/records/bulk. Apply an atomic multi-model record blob to a document (create/patch/delete) */
       "bulk"(args: {
         "documentId": string | number;
+        "documentFormat"?: string | number | boolean;
         body: unknown;
       }): Promise<any>;
       /** `documents.records.count` — GET /documents/{documentId}/records/{model}/count. Count records in a document model */
       "count"(args: {
         "documentId": string | number;
         "model": string | number;
+        "documentFormat"?: string | number | boolean;
         "filter"?: Record<string, unknown> | string;
       }): Promise<any>;
       /** `documents.records.delete` — DELETE /documents/{documentId}/records/{model}/{recordId}. Delete a record from a document model */
@@ -950,18 +1023,21 @@ export interface FunctionApi {
         "documentId": string | number;
         "model": string | number;
         "recordId": string | number;
+        "documentFormat"?: 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: {
         "documentId": string | number;
         "model": string | number;
         "recordId": string | number;
+        "documentFormat"?: string | number | boolean;
         body: unknown;
       }): Promise<any>;
       /** `documents.records.query` — GET /documents/{documentId}/records/{model}. Query records in a document model */
       "query"(args: {
         "documentId": string | number;
         "model": string | number;
+        "documentFormat"?: string | number | boolean;
         "limit"?: string | number | boolean;
         "cursor"?: string | number | boolean;
         "filter"?: Record<string, unknown> | string;
@@ -970,6 +1046,7 @@ export interface FunctionApi {
       "save"(args: {
         "documentId": string | number;
         "model": string | number;
+        "documentFormat"?: string | number | boolean;
         body: unknown;
       }): Promise<any>;
     };
@@ -993,6 +1070,11 @@ export interface FunctionApi {
       "documentId": string | number;
       body: unknown;
     }): Promise<any>;
+    /** `documents.requestSnapshot` — POST /documents/{documentId}/snapshots. Snapshot a large document now: seal the open epoch and build a base */
+    "requestSnapshot"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
     /** `documents.revokeGroupPermission` — DELETE /documents/{documentId}/group-permissions/{groupType}/{groupId}. Revoke a group permission on a document */
     "revokeGroupPermission"(args: {
       "documentId": string | number;
@@ -1019,9 +1101,16 @@ export interface FunctionApi {
       "documentId": string | number;
       body: unknown;
     }): Promise<any>;
-    /** `documents.validateAccess` — POST /documents/{documentId}/validate-access. Resolve the caller's effective access level for a document */
+    /** `documents.uploadIngestChunk` — POST /documents/{documentId}/ingest/{sessionId}/chunks. Upload one chunk of a bulk-load session's artifact */
+    "uploadIngestChunk"(args: {
+      "documentId": string | number;
+      "sessionId": string | number;
+      body: FormData | ArrayBuffer | Uint8Array | string;
+    }): Promise<any>;
+    /** `documents.validateAccess` — POST /documents/{documentId}/validate-access. Resolve effective access to a document, for the caller or a named user */
     "validateAccess"(args: {
       "documentId": string | number;
+      body?: unknown;
     }): Promise<any>;
   };
   "email": {
@@ -1048,29 +1137,12 @@ export interface FunctionApi {
       "cursor"?: string | number | boolean;
       "runId"?: string | number | boolean;
     }): Promise<any>;
-    /** `functions.start` — POST /functions/{functionKey}/start. Start a task function from inside another server function */
+    /** `functions.start` — POST /functions/{functionKey}/start. Start a server function as a task run */
     "start"(args: {
       "functionKey": string | number;
       body?: unknown;
     }): Promise<any>;
   };
-  "gemini": {
-    /** `gemini.countTokens` — POST /gemini/count-tokens. Count tokens for a Gemini request */
-    "countTokens"(args: {
-      body: unknown;
-    }): Promise<any>;
-    /** `gemini.generate` — POST /gemini/generate. Generate content with Gemini */
-    "generate"(args: {
-      body: unknown;
-    }): Promise<any>;
-    /** `gemini.generateRaw` — POST /gemini/generate-raw. Generate content with Gemini (raw passthrough) */
-    "generateRaw"(args: {
-      "model"?: string | number | boolean;
-      body: unknown;
-    }): Promise<any>;
-    /** `gemini.models` — GET /gemini/models. List available Gemini models */
-    "models"(args?: Record<string, never>): Promise<any>;
-  };
   "groups": {
     /** `groups.addMember` — POST /groups/{groupType}/{groupId}/members. Add a member to a group */
     "addMember"(args: {
@@ -1160,14 +1232,6 @@ export interface FunctionApi {
       "integrationKey": string | number;
     }): Promise<any>;
   };
-  "llm": {
-    /** `llm.chat` — POST /llm/chat. Run an LLM chat completion */
-    "chat"(args: {
-      body: unknown;
-    }): Promise<any>;
-    /** `llm.models` — GET /llm/models. List available LLM models */
-    "models"(args?: Record<string, never>): Promise<any>;
-  };
   "locks": {
     /** `locks.list` — GET /locks. List all currently-held named locks in the app */
     "list"(args?: Record<string, never>): Promise<any>;
@@ -1278,6 +1342,10 @@ export interface FunctionApi {
     "getProfiles"(args: {
       body: unknown;
     }): Promise<any>;
+    /** `users.getRootDocument` — GET /users/{userId}/root-document. Get an app user's root document id */
+    "getRootDocument"(args: {
+      "userId": string | number;
+    }): Promise<any>;
     /** `users.list` — GET /users. List app users */
     "list"(args?: {
       "email"?: string | number | boolean;
@@ -1290,7 +1358,10 @@ export interface FunctionApi {
     "lookup"(args?: {
       "email"?: string | number | boolean;
     }): Promise<any>;
-    /** `users.remove` — DELETE /users/{userId}. Remove a user from the app */
+    /**
+     * `users.remove` — DELETE /users/{userId}. DEPRECATED — remove a user from the app; use the admin API's PUT apps/:appId/users/:userId/disable (`primitive users disable`)
+     * @deprecated Use the admin API's PUT apps/:appId/users/:userId/disable (`primitive users disable`)
+     */
     "remove"(args: {
       "userId": string | number;
     }): Promise<any>;
@@ -1339,8 +1410,8 @@ export type DatabaseModels<K extends string> = K extends keyof DatabaseSchemas
  * The app's functions, key by key — EMPTY here and filled by the declaration
  * `primitive config push` writes into the config tree's `functions/`
  * directory (`primitive-function-types.d.ts`): each key's declared input and
- * output types (from its `inputSchema` and `outputSchema`) and its mode. It
- * is what types `defineFunction("<key>", handler)`.
+ * output types, from its `inputSchema` and `outputSchema`. It is what types
+ * `defineFunction("<key>", handler)`.
  */
 export interface FunctionSchemas {}
 
@@ -1368,20 +1439,6 @@ export type FunctionOutput<K extends string> = K extends keyof FunctionSchemas
     : any
   : any;
 
-/**
- * A declared function's mode, fixed at generation time.
- *
- * `"any"` — the default when the authored file names no mode (#3454) — takes
- * EITHER runner and the caller picks at call time; `"request"` and `"task"`
- * lock it to one. An UNDECLARED key is the whole union, because nothing has
- * said which of the three it is.
- */
-export type FunctionMode<K extends string> = K extends keyof FunctionSchemas
-  ? FunctionSchemas[K] extends { mode: infer M }
-    ? M
-    : "request" | "task" | "any"
-  : "request" | "task" | "any";
-
 /**
  * The model names one database type addresses — its own, or any name at all
  * for a type that declares no schema (the DO is schemaless, so a grant on such
@@ -1545,12 +1602,40 @@ export interface DocumentQueryOptions {
   filter?: Record<string, unknown> | string;
   limit?: number;
   cursor?: string;
+  /**
+   * The document format you expect (#3764). When it disagrees with the format
+   * the platform resolved, the call is refused with a 409
+   * DOCUMENT_FORMAT_MISMATCH rather than answered out of the wrong tables.
+   * Usually stated once on the handle, as ctx.doc(id, { documentFormat: 2 }),
+   * rather than per read.
+   */
+  documentFormat?: 1 | 2;
 }
 
 /**
  * One document model, bound to its document and its model name — a thin
  * binding over `ctx.api.documents.records.*` with the route's own shapes.
  */
+/**
+ * One op of a document `batch` — the `documents.records.bulk` blob's shape,
+ * typed to this handle's model (#3455).
+ *
+ * `model` is NOT a member: the handle already names it and assigns it last, so
+ * a multi-model blob stays on the raw `ctx.api.documents.records.bulk`
+ * operation rather than becoming a second way to say the same thing.
+ */
+export type DocumentBatchOp<TRow> =
+  | { action: "create" | "patch"; id: string; data: Partial<TRow>; precondition?: Record<string, unknown> }
+  | { action: "delete"; id: string; precondition?: Record<string, unknown> };
+
+/** What `documents.records.bulk` answers: the blob's aggregate effect. */
+export interface DocumentBulkResult {
+  applied: number;
+  added: Array<{ model: string; id: string }>;
+  updated: Array<{ model: string; id: string }>;
+  deleted: number;
+}
+
 export interface DocumentModelHandle<TRow> {
   query(options?: DocumentQueryOptions): Promise<{ items: TRow[]; hasMore: boolean; nextCursor?: string }>;
   count(options?: { filter?: Record<string, unknown> | string }): Promise<{ count: number }>;
@@ -1558,6 +1643,15 @@ export interface DocumentModelHandle<TRow> {
   save(body: { id: string; data: Partial<TRow>; options?: Record<string, unknown> }): Promise<{ record: TRow }>;
   patch(recordId: string, body: { data: Partial<TRow>; options?: Record<string, unknown> }): Promise<{ record: TRow }>;
   delete(recordId: string): Promise<{ deleted: boolean }>;
+  /**
+   * Apply an ordered blob of this model's ops in ONE transaction — all of it
+   * commits or none of it does, and connected clients see one update.
+   *
+   * One model's ops, by construction: every op's `model` is this handle's.
+   * A blob that spans models is the raw `ctx.api.documents.records.bulk`
+   * operation's job.
+   */
+  batch(ops: Array<DocumentBatchOp<TRow>>): Promise<DocumentBulkResult>;
 }
 
 /** A document, addressed once; its models are typed from `DocumentSchemas`. */
@@ -1600,6 +1694,13 @@ export interface IntegrationCallResult {
 
 /** What a prompt run is given — the member execute route's own body. */
 export interface PromptRunArgs {
+  /**
+   * The prompt's variables. A `kind = "decisions"` prompt takes
+   * `{ state, criteria? }`: `state` is the value its questions are asked
+   * about, and `criteria.<question>` supplies this run's options for each
+   * choice question declared `criteriaSource = "dynamic"` — a table of option
+   * key = description (a string or a JSON object), at least two entries (#3813).
+   */
   variables?: Record<string, unknown>;
   /** Run against a different model for this call only. */
   modelOverride?: string;
@@ -1617,10 +1718,45 @@ export interface PromptRunArgs {
  */
 export interface PromptSchemas {}
 
-/** The keys `ctx.prompts.run` accepts — every declared one, or `string` before a push. */
+/**
+ * The keys whose declaration is an AGENT (`kind = "agent"`, #3798): entries
+ * carrying `{ agent: … }` instead of an output. An agent runs turn by turn in
+ * a session and never single-shot, so these are the keys `PromptKeys` leaves
+ * out.
+ */
+export type AgentKeys = {
+  [K in keyof PromptSchemas]: PromptSchemas[K] extends { agent: unknown } ? K : never;
+}[keyof PromptSchemas] &
+  string;
+
+/**
+ * The keys `ctx.prompts.run` accepts — every declared one that is not an
+ * agent, or `string` before a push.
+ */
 export type PromptKeys = [keyof PromptSchemas] extends [never]
   ? string
-  : keyof PromptSchemas & string;
+  : Exclude<keyof PromptSchemas & string, AgentKeys>;
+
+/** One agent's session variables, typed from its `inputSchema` (#3798). */
+export type AgentVariables<K extends AgentKeys> = PromptSchemas[K] extends {
+  agent: { variables: infer V };
+}
+  ? V
+  : never;
+
+/** 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 };
+}
+  ? T
+  : never;
+
+/** One agent's event kinds, by name: each one's payload (#3798). */
+export type AgentEvents<K extends AgentKeys> = PromptSchemas[K] extends {
+  agent: { events: infer E };
+}
+  ? E
+  : never;
 
 /** One prompt's declared output type, or `unknown` where none is declared. */
 export type PromptOutput<K extends string> = K extends keyof PromptSchemas
@@ -1638,6 +1774,29 @@ export type PromptOutputErrorCode =
   | "PROMPT_OUTPUT_NOT_JSON"
   | "PROMPT_OUTPUT_SCHEMA_VIOLATION";
 
+/**
+ * Every code the envelope's `errorCode` can carry — #3663, #3813.
+ *
+ * `PROMPT_UPSTREAM_TIMEOUT` is the one that is NOT about the prompt's own
+ * answer: the provider ran out of time, so there was no answer to refuse. It
+ * is the only provider failure that sets `errorCode` at all, which is what
+ * leaves "the model returned the wrong shape" distinguishable from "the model
+ * failed" while still letting a caller retry the one failure worth retrying.
+ *
+ * `PROMPT_CRITERIA_INVALID` is the run that never reached a provider: a
+ * decisions run's `variables.criteria` was refused before the call, so
+ * nothing was billed (#3813).
+ *
+ * `PROMPT_STRICT_OUTPUT_SCHEMA_MISSING` never reached one either: the config
+ * sets `strictOutput = true` and the prompt has no usable `outputSchema` to
+ * send as the strict `json_schema` (#3801).
+ */
+export type PromptRunErrorCode =
+  | PromptOutputErrorCode
+  | "PROMPT_UPSTREAM_TIMEOUT"
+  | "PROMPT_CRITERIA_INVALID"
+  | "PROMPT_STRICT_OUTPUT_SCHEMA_MISSING";
+
 /** A prompt that declares an output shape, when the answer matched it. */
 export interface PromptRunSuccess<TParsed> {
   success: true;
@@ -1651,19 +1810,31 @@ export interface PromptRunSuccess<TParsed> {
 }
 
 /**
- * The failure arm, whichever failed. `errorCode` is set for a SHAPE failure
- * and absent for a provider one; `output` carries the text either way, which
- * is where the model's own value lives — a validation `error` names paths and
- * schema constraints only.
+ * The failure arm, whichever failed. `errorCode` is set for a SHAPE failure,
+ * for a refused run (`PROMPT_CRITERIA_INVALID`, #3813), and for a provider
+ * one only when the upstream TIMED OUT (#3663); `output` carries the text
+ * either way, which is where the model's own value lives — a validation
+ * `error` names paths and schema constraints only.
  */
 export interface PromptRunFailure {
   success: false;
   output: string;
   error: string | null;
-  errorCode?: PromptOutputErrorCode | null;
+  errorCode?: PromptRunErrorCode | null;
   parsed?: undefined;
   metrics?: Record<string, unknown>;
   configId: string;
+  /**
+   * The upstream provider's HTTP status, when the call reached a provider and
+   * it answered — #3663. This is what a retry decision is made on: a 504 or a
+   * 503 is worth another attempt, a 400 on a refused payload is not.
+   *
+   * It does not depend on which provider the config named: Gemini and
+   * OpenRouter report it identically. It is absent when no provider answer was
+   * observed — an unset key, an oversized payload, a completion that came back
+   * empty — so a number here is always the provider's own.
+   */
+  upstreamStatus?: number;
 }
 
 /** The envelope for a key whose declaration says nothing about its output. */
@@ -1676,9 +1847,11 @@ export interface PromptRunOpenResult {
    */
   parsed?: unknown;
   error?: string | null;
-  errorCode?: PromptOutputErrorCode | null;
+  errorCode?: PromptRunErrorCode | null;
   metrics?: Record<string, unknown>;
   configId: string;
+  /** The upstream provider's HTTP status on a provider failure — #3663. */
+  upstreamStatus?: number;
 }
 
 /**
@@ -1785,9 +1958,45 @@ export interface FunctionStartResult {
 }
 
 export interface FunctionContext {
-  /** The HTTP caller, or null for a webhook, cron or database-change fire. */
+  /** The HTTP caller, or null for a webhook or cron fire. */
   user: FunctionUser | null;
   trigger: FunctionTrigger;
+  /**
+   * Which RUNTIME is hosting this code — #3482.
+   *
+   * Beside `trigger`, which says which DOOR fired, and they are different
+   * questions: an HTTP call is whichever runtime the caller chose
+   * (`invoke` or `start`), a cron fire is always a task and a webhook
+   * delivery is always a request.
+   *
+   * To REFUSE a runtime rather than branch on it, call
+   * `assertRuntime("task")` — at module scope to refuse it outright, or in
+   * the handler to refuse one call.
+   */
+  runtime: "request" | "task";
+  /**
+   * The RUN this invocation belongs to, or null — #3562.
+   *
+   * Set under the task runtime (every slice of the run, the first and every
+   * resume) and for a webhook-fired request run, which writes a row. Null for
+   * an HTTP `invoke`, which writes no run row at all.
+   *
+   * It is the deterministic OWNER a task run presents to re-take its own
+   * lease: `ctx.api.locks.tryAcquire({ body: { key, ttlMs, owner: ctx.runId } })`
+   * succeeds for the run that already holds the key, with a fresh handle.
+   */
+  runId: string | null;
+  /**
+   * The SLICE of the run this code is running in, or null — #3562.
+   *
+   * The same identifier `primitive functions runs` and the run-status
+   * route's `slice.sliceId` report. A task run is a sequence of slices: it
+   * changes when the run hibernates and wakes, which is how a handler can tell
+   * a resume from a first pass.
+   *
+   * Null under the request runtime: a request invocation is not a slice.
+   */
+  sliceId: string | null;
   api: FunctionApi;
   /**
    * A typed handle over one database. The second argument is the database TYPE
@@ -1804,7 +2013,7 @@ export interface FunctionContext {
    * confers nothing: every call is a `documents.records.*` operation on the
    * same authority.
    */
-  doc(documentId: string): DocumentHandle;
+  doc(documentId: string, options?: { documentFormat?: 1 | 2 }): DocumentHandle;
   /**
    * Outbound HTTP, through a granted integration and nowhere else (#3183).
    *
@@ -1937,6 +2146,29 @@ export interface FunctionContext {
   };
 }
 
+/** How the wait between one step's retries grows. */
+export type StepBackoff = "constant" | "linear" | "exponential";
+
+/**
+ * The retry and timeout policy for ONE `step.do` — Cloudflare Workflows' own
+ * step config.
+ *
+ * Under the TASK runner the platform forwards this object to Workflows
+ * untouched, so these are its fields and its spellings: a duration is either a
+ * number of milliseconds or a string Workflows parses (`"10 seconds"`,
+ * `"5 minutes"`). Under the REQUEST runner `step.do` accepts a config and
+ * ignores it — the body runs inline, and there is nothing to retry into.
+ *
+ * `stepPolicy.<family>` IS a `StepConfig`, so the platform's own defaults
+ * hand straight to `step.do` (#3657). The shape is closed on purpose: a key
+ * outside it — `retry` for `retries`, `timeoutMs` for `timeout` — is a
+ * refusal at `config push` rather than an option the engine silently drops.
+ */
+export interface StepConfig {
+  retries?: { limit: number; delay: string | number; backoff?: StepBackoff };
+  timeout?: string | number;
+}
+
 /**
  * The step handle. `step` is the third argument under BOTH runners, so the
  * same body runs either way — which is what `mode = "any"` is for (#3454).
@@ -1949,7 +2181,7 @@ export interface FunctionContext {
  * clock: `do` executes the body inline (there is no engine to memoize into,
  * and nothing is replayed); `sleep` and `sleepUntil` REALLY wait when the
  * remaining request budget covers the duration, and otherwise fail the
- * invocation with `errorCode: "FUNCTION_STEP_NEEDS_TASK"` saying to start the
+ * invocation with `errorCode: "FUNCTION_RUNTIME_REFUSED"` saying to start the
  * function as a task; `waitForEvent` fails the same way, because nothing can
  * deliver an event to an invocation that has to return now. The thrown error's
  * `name` is `STEP_NOT_AVAILABLE` in every case, so a body that catches it
@@ -1959,7 +2191,7 @@ export interface FunctionStep {
   do<T>(name: string, body: () => T | Promise<T>): Promise<T>;
   do<T>(
     name: string,
-    config: Record<string, unknown>,
+    config: StepConfig,
     body: () => T | Promise<T>
   ): Promise<T>;
   sleep(name: string, duration: number | string): Promise<void>;
@@ -1972,6 +2204,48 @@ export interface FunctionStep {
 
 export declare const SDK_STUB_VERSION: string;
 
+/**
+ * Thrown by `assertRuntime` when this function is running under the other
+ * runtime — #3482.
+ *
+ * The platform settles it as `status: "failed"` with
+ * `errorCode: "FUNCTION_RUNTIME_REFUSED"`, on a request invocation's
+ * envelope and on a task run's row and record alike.
+ */
+export declare class FunctionRuntimeError extends Error {
+  name: "FUNCTION_RUNTIME_REFUSED";
+  /** The runtime this invocation is actually running under. */
+  runtime: "request" | "task";
+  /** The runtime the function asked for. */
+  required: "request" | "task";
+}
+
+/**
+ * Refuse the runtime this function was not written for — #3482.
+ *
+ * A function is a function and the caller picks the runtime at each call, so
+ * nothing in config says which one a function may run under. This is the lock,
+ * and it lives in the one place that can always be right about the code:
+ *
+ * ```ts
+ * import { assertRuntime } from "primitive-functions";
+ *
+ * // At module scope: this function is never runnable inside a request.
+ * assertRuntime("task");
+ *
+ * export default async function (input, ctx, step) {
+ *   await step.sleep("cool-off", "1 hour");
+ *   return { ok: true };
+ * }
+ * ```
+ *
+ * Returns when the runtimes match; otherwise throws
+ * {@link FunctionRuntimeError}, which the platform settles as
+ * `status: "failed"` with `errorCode: "FUNCTION_RUNTIME_REFUSED"` and a
+ * message naming both runtimes and the verb that takes the one required.
+ */
+export declare function assertRuntime(required: "request" | "task"): void;
+
 /**
  * The handler a function exports, typed for one declared key.
  *
@@ -2181,9 +2455,9 @@ export declare const PMAP_DEFAULT_CONCURRENCY: number;
  */
 export declare function ulid(): string;
 
-/** One family's durable `step.do` configuration. */
-export interface StepPolicy {
-  retries: { limit: number; delay: string; backoff: string };
+/** One family's durable `step.do` configuration — a `StepConfig` with every field decided. */
+export interface StepPolicy extends StepConfig {
+  retries: { limit: number; delay: string; backoff: StepBackoff };
   timeout: string;
 }
 
@@ -2204,6 +2478,12 @@ export declare const stepPolicy: {
   database: StepPolicy;
 };
 
+// Every member the three runtime copies put on their own default export — the
+// platform's `sdk-core.ts`, the published stub and the CLI's collect stub —
+// and nothing else. A helper the module hands a default import but does not
+// declare here is one an author cannot call without the compiler refusing it
+// (#3482 CR3482-002); `tests/api/spec/function-profile.test.ts` holds the four
+// lists equal and compiles a default import against them.
 declare const _default: {
   SDK_STUB_VERSION: string;
   defineFunction: typeof defineFunction;
@@ -2211,5 +2491,7 @@ declare const _default: {
   defineMutation: typeof defineMutation;
   pMap: typeof pMap;
   ulid: typeof ulid;
+  assertRuntime: typeof assertRuntime;
+  FunctionRuntimeError: typeof FunctionRuntimeError;
 };
 export default _default;

package/index.js

@@ -82,6 +82,34 @@ export const stepPolicy = {
   database: null,
 };
 
+/**
+ * The runtime refusal's error class — #3482.
+ *
+ * Carried rather than thrown from: a function narrows a `catch` with
+ * `instanceof FunctionRuntimeError`, and a class that threw on construction
+ * would break a build that only type-checks. The platform copy is the one that
+ * is ever really thrown.
+ */
+export class FunctionRuntimeError extends Error {
+  constructor(message, runtime, required) {
+    super(message);
+    this.name = "FUNCTION_RUNTIME_REFUSED";
+    this.runtime = runtime;
+    this.required = required;
+  }
+}
+
+/**
+ * Refuse the runtime this function was not written for — #3482.
+ *
+ * The platform copy compares the required runtime against the one the isolate
+ * declared. This one refuses, loudly, like every other function here: an
+ * assertion answered outside a sandbox would be answering about nothing.
+ */
+export function assertRuntime() {
+  throw new Error(NOT_PROVIDED);
+}
+
 export default {
   SDK_STUB_VERSION,
   defineFunction,
@@ -89,4 +117,6 @@ export default {
   defineMutation,
   pMap,
   ulid,
+  assertRuntime,
+  FunctionRuntimeError,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primitive-functions",
-  "version": "0.2.0-alpha.8",
+  "version": "0.2.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",