primitive-functions 0.2.0-alpha.10 → 0.2.0-alpha.12

package/index.d.ts

@@ -510,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;
@@ -566,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>;
@@ -723,7 +744,10 @@ 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;
@@ -804,7 +828,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>;
@@ -973,17 +1000,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 */
@@ -991,18 +1021,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;
@@ -1011,6 +1044,7 @@ export interface FunctionApi {
       "save"(args: {
         "documentId": string | number;
         "model": string | number;
+        "documentFormat"?: string | number | boolean;
         body: unknown;
       }): Promise<any>;
     };
@@ -1071,9 +1105,10 @@ export interface FunctionApi {
       "sessionId": string | number;
       body: FormData | ArrayBuffer | Uint8Array | string;
     }): Promise<any>;
-    /** `documents.validateAccess` — POST /documents/{documentId}/validate-access. Resolve the caller's effective access level for a document */
+    /** `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": {
@@ -1107,20 +1142,32 @@ export interface FunctionApi {
     }): Promise<any>;
   };
   "gemini": {
-    /** `gemini.countTokens` — POST /gemini/count-tokens. Count tokens for a Gemini request */
+    /**
+     * `gemini.countTokens` — POST /gemini/count-tokens. Count tokens for a Gemini request
+     * @deprecated These direct proxy routes will be removed in the next major release of the platform server. Run a managed prompt from a server function instead: `ctx.prompts.run` (see the Server Functions guide).
+     */
     "countTokens"(args: {
       body: unknown;
     }): Promise<any>;
-    /** `gemini.generate` — POST /gemini/generate. Generate content with Gemini */
+    /**
+     * `gemini.generate` — POST /gemini/generate. Generate content with Gemini
+     * @deprecated These direct proxy routes will be removed in the next major release of the platform server. Run a managed prompt from a server function instead: `ctx.prompts.run` (see the Server Functions guide).
+     */
     "generate"(args: {
       body: unknown;
     }): Promise<any>;
-    /** `gemini.generateRaw` — POST /gemini/generate-raw. Generate content with Gemini (raw passthrough) */
+    /**
+     * `gemini.generateRaw` — POST /gemini/generate-raw. Generate content with Gemini (raw passthrough)
+     * @deprecated These direct proxy routes will be removed in the next major release of the platform server. Run a managed prompt from a server function instead: `ctx.prompts.run` (see the Server Functions guide).
+     */
     "generateRaw"(args: {
       "model"?: string | number | boolean;
       body: unknown;
     }): Promise<any>;
-    /** `gemini.models` — GET /gemini/models. List available Gemini models */
+    /**
+     * `gemini.models` — GET /gemini/models. List available Gemini models
+     * @deprecated These direct proxy routes will be removed in the next major release of the platform server. Run a managed prompt from a server function instead: `ctx.prompts.run` (see the Server Functions guide).
+     */
     "models"(args?: Record<string, never>): Promise<any>;
   };
   "groups": {
@@ -1213,11 +1260,17 @@ export interface FunctionApi {
     }): Promise<any>;
   };
   "llm": {
-    /** `llm.chat` — POST /llm/chat. Run an LLM chat completion */
+    /**
+     * `llm.chat` — POST /llm/chat. Run an LLM chat completion
+     * @deprecated These direct proxy routes will be removed in the next major release of the platform server. Run a managed prompt from a server function instead: `ctx.prompts.run` (see the Server Functions guide).
+     */
     "chat"(args: {
       body: unknown;
     }): Promise<any>;
-    /** `llm.models` — GET /llm/models. List available LLM models */
+    /**
+     * `llm.models` — GET /llm/models. List available LLM models
+     * @deprecated These direct proxy routes will be removed in the next major release of the platform server. Run a managed prompt from a server function instead: `ctx.prompts.run` (see the Server Functions guide).
+     */
     "models"(args?: Record<string, never>): Promise<any>;
   };
   "locks": {
@@ -1342,7 +1395,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>;
@@ -1583,6 +1639,14 @@ 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;
 }
 
 /**
@@ -1667,6 +1731,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;
@@ -1684,10 +1755,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
@@ -1705,6 +1811,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;
@@ -1718,19 +1847,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. */
@@ -1743,9 +1884,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;
 }
 
 /**
@@ -1907,7 +2050,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).
    *
@@ -2040,6 +2183,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).
@@ -2062,7 +2228,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>;
@@ -2326,9 +2492,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;
 }
 

package/package.json

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