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

package/index.d.ts

@@ -94,7 +94,64 @@ export type FunctionTrigger =
    * attribution, never the principal the code runs as. `runKey` is the key
    * the admin's start named, or null (#3562).
    */
-  | { kind: "manual"; userId: string; runKey: string | null };
+  | { kind: "manual"; userId: string; runKey: string | null }
+  /**
+   * An agent turn called this function as one of its tools.
+   *
+   * `ctx.user` is the turn's initiator, whose `access` gate the call
+   * passed, and `ctx.tool` carries the session's ids, members and
+   * variables. `callId` is the same on every attempt of the call, so use
+   * it as an idempotency key. `toolName` is the declared tool name, which
+   * may differ from the function's key.
+   */
+  | {
+      kind: "tool";
+      sessionId: string;
+      turnId: string;
+      callId: string;
+      toolName: string;
+    }
+  /** An agent turn asked this function for its turn context. */
+  | { kind: "context"; sessionId: string; turnId: string }
+  /** An agent turn asked this function for the history to send the model. */
+  | { kind: "history"; sessionId: string; turnId: string };
+
+/**
+ * The agent session a tool call belongs to — `ctx.tool`, set only when
+ * `ctx.trigger.kind === "tool"`.
+ *
+ * Variables and members describe the session; they grant nothing. Check what
+ * `ctx.user` (the turn's initiator) may do before acting for them.
+ */
+export interface FunctionToolContext {
+  readonly sessionId: string;
+  /** The session's document, which holds its messages. */
+  readonly documentId: string;
+  readonly turnId: string;
+  /** The call's id, the same on every attempt: an idempotency key. */
+  readonly callId: string;
+  /** The tool's declared name. */
+  readonly toolName: string;
+  /** The session's owner. */
+  readonly ownerUserId: string;
+  /** The session's members by role, besides the owner. */
+  readonly members: {
+    readonly viewerUserIds: string[];
+    readonly participantUserIds: string[];
+  };
+  /** The session's variables, set when it was created. */
+  readonly variables: Record<string, unknown>;
+  /**
+   * Attach an app-only artifact to this call's row, replacing any earlier
+   * one. The model never sees it; your app reads it from the call's row —
+   * `artifact`, or, for one over 64 KiB of JSON or past the agent's
+   * `maxRowBytes`, the blob on the session's document named by
+   * `artifactBlobId`. At most 4 MiB of JSON: a larger value rejects with
+   * `AGENT_ARTIFACT_TOO_LARGE`, and a call that already has its result with
+   * `AGENT_CALL_NOT_RUNNING`.
+   */
+  attachArtifact(value: unknown): Promise<void>;
+}
 
 /** The result shape of an operation that answers in response headers. */
 export interface HeaderResult {
@@ -143,6 +200,23 @@ export interface FunctionApi {
       "sessionId": string | number;
       body: unknown;
     }): Promise<any>;
+    /** `agentSessions.answer` — POST /agent-sessions/{sessionId}/calls/{callId}/answer. Answer a paused agent turn's call */
+    "answer"(args: {
+      "sessionId": string | number;
+      "callId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `agentSessions.attachArtifact` — POST /agent-sessions/{sessionId}/calls/{callId}/artifact. Attach an artifact to a running agent tool call (ctx.tool.attachArtifact) */
+    "attachArtifact"(args: {
+      "sessionId": string | number;
+      "callId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `agentSessions.cancel` — POST /agent-sessions/{sessionId}/cancel. Cancel an agent session's active turn */
+    "cancel"(args: {
+      "sessionId": string | number;
+      body: unknown;
+    }): Promise<any>;
     /** `agentSessions.create` — POST /agent-sessions. Create an agent session (ctx.agents.createSession) */
     "create"(args: {
       body: unknown;
@@ -163,6 +237,11 @@ export interface FunctionApi {
       "limit"?: string | number | boolean;
       "cursor"?: string | number | boolean;
     }): Promise<any>;
+    /** `agentSessions.recordEvent` — POST /agent-sessions/{sessionId}/events. Record an event in an agent session (ctx.agents.recordEvent) */
+    "recordEvent"(args: {
+      "sessionId": string | number;
+      body: unknown;
+    }): Promise<any>;
     /** `agentSessions.removeMember` — DELETE /agent-sessions/{sessionId}/members/{userId}. Remove a member from an agent session */
     "removeMember"(args: {
       "sessionId": string | number;
@@ -173,6 +252,11 @@ export interface FunctionApi {
       "sessionId": string | number;
       body: unknown;
     }): Promise<any>;
+    /** `agentSessions.send` — POST /agent-sessions/{sessionId}/messages. Send a message to an agent session */
+    "send"(args: {
+      "sessionId": string | number;
+      body: unknown;
+    }): Promise<any>;
   };
   "analytics": {
     /** `analytics.cohortRetention` — GET /analytics/cohort-retention. Cohort retention metrics */
@@ -421,6 +505,12 @@ export interface FunctionApi {
       "limit"?: string | number | boolean;
       "cursor"?: string | number | boolean;
     }): Promise<any>;
+    /** `collections.listForUser` — GET /users/{userId}/collections. List the collections an app user is a direct member of */
+    "listForUser"(args: {
+      "userId": string | number;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+    }): Promise<any>;
     /** `collections.listPendingInvitations` — GET /collections/{collectionId}/pending-invitations. List a collection's pending invitations */
     "listPendingInvitations"(args: {
       "collectionId": string | number;
@@ -954,10 +1044,26 @@ export interface FunctionApi {
       "limit"?: string | number | boolean;
       "cursor"?: string | number | boolean;
     }): Promise<any>;
+    /** `documents.listOwnedByUser` — GET /users/{userId}/owned-documents. List the documents an app user owns */
+    "listOwnedByUser"(args: {
+      "userId": string | number;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+      "tag"?: string | number | boolean;
+      "includeRoot"?: string | number | boolean;
+      "forward"?: string | number | boolean;
+    }): Promise<any>;
     /** `documents.listPendingInvitations` — GET /documents/{documentId}/pending-invitations. List a document's pending (deferred) invitations */
     "listPendingInvitations"(args: {
       "documentId": string | number;
     }): Promise<any>;
+    /** `documents.listSharedWithUser` — GET /users/{userId}/shared-documents. List the documents directly shared with an app user */
+    "listSharedWithUser"(args: {
+      "userId": string | number;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+      "tag"?: string | number | boolean;
+    }): Promise<any>;
     /** `documents.listSnapshots` — GET /documents/{documentId}/snapshots. List a large document's snapshot builds, newest first */
     "listSnapshots"(args: {
       "documentId": string | number;
@@ -976,7 +1082,7 @@ export interface FunctionApi {
         "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) */
+      /** `documents.records.bulk` — POST /documents/{documentId}/records/bulk. Apply an atomic multi-model record blob to a document (create/patch/delete/upsert) */
       "bulk"(args: {
         "documentId": string | number;
         "documentFormat"?: string | number | boolean;
@@ -1101,6 +1207,19 @@ export interface FunctionApi {
       "functionKey": string | number;
       body?: unknown;
     }): Promise<any>;
+    /** `functions.listRunSteps` — GET /functions/runs/{runId}/steps. List a function run's steps, oldest first */
+    "listRunSteps"(args: {
+      "runId": string | number;
+    }): Promise<any>;
+    /** `functions.listRuns` — GET /functions/runs. List the caller's own function runs */
+    "listRuns"(args?: {
+      "functionKey"?: string | number | boolean;
+      "contextDocId"?: string | number | boolean;
+      "status"?: string | number | boolean;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+      "forward"?: string | number | boolean;
+    }): Promise<any>;
     /** `functions.logs` — GET /functions/{functionKey}/logs. List a server function's invocation logs, newest first */
     "logs"(args: {
       "functionKey": string | number;
@@ -1341,6 +1460,11 @@ export interface FunctionApi {
       "userId": string | number;
       body: unknown;
     }): Promise<any>;
+    /** `users.setProfile` — PATCH /users/{userId}/profile. Set a user's display name and avatar */
+    "setProfile"(args: {
+      "userId": string | number;
+      body: unknown;
+    }): Promise<any>;
     /** `users.setRole` — PUT /users/{userId}/role. Set a user's app role */
     "setRole"(args: {
       "userId": string | number;
@@ -1594,17 +1718,28 @@ export interface DocumentQueryOptions {
  * `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.
+ *
+ * `upsert` addresses the record by a unique constraint the model declares:
+ * `data` carries every field of `constraint`, the record holding that key
+ * gets `data` merged into it, and when none does one is created (at `id`
+ * when given, else at a new id) with the model's defaults.
  */
 export type DocumentBatchOp<TRow> =
   | { action: "create" | "patch"; id: string; data: Partial<TRow>; precondition?: Record<string, unknown> }
-  | { action: "delete"; id: string; precondition?: Record<string, unknown> };
+  | { action: "delete"; id: string; precondition?: Record<string, unknown> }
+  | { action: "upsert"; constraint: string; id?: string; data: Partial<TRow>; precondition?: Record<string, unknown> };
 
-/** What `documents.records.bulk` answers: the blob's aggregate effect. */
+/**
+ * What `documents.records.bulk` answers: the blob's aggregate effect.
+ * `upserted` has one entry per `upsert` op, in input order: the op's
+ * `index`, the record's `id`, and whether the op `created` it.
+ */
 export interface DocumentBulkResult {
   applied: number;
   added: Array<{ model: string; id: string }>;
   updated: Array<{ model: string; id: string }>;
   deleted: number;
+  upserted: Array<{ index: number; model: string; id: string; created: boolean }>;
 }
 
 export interface DocumentModelHandle<TRow> {
@@ -1776,6 +1911,44 @@ export interface AgentSessionInfo {
   members: { viewers: string[]; participants: string[] };
   /** The invoking user's standing on the session. */
   role: "owner" | "participant" | "viewer" | "admin";
+  /**
+   * The session's status, decided from the session object (never the
+   * session row): the active turn's phase, else how the last turn ended.
+   */
+  status: AgentSessionStatus;
+  /** The active turn, or null when none runs. */
+  turn: AgentSessionTurnSummary | null;
+}
+
+/** A session's status: `idle` between turns, the active turn's phase, or how the last turn ended. */
+export type AgentSessionStatus =
+  | "idle"
+  | "thinking"
+  | "running_tool"
+  | "awaiting_answer"
+  | "failed"
+  | "expired"
+  | "cancelled";
+
+/** The active turn of a session, as `ctx.agents.getSession` answers it. */
+export interface AgentSessionTurnSummary {
+  turnId: string;
+  /** The member whose messages started the turn. */
+  initiatorUserId: string;
+  /** ISO-8601; null until the turn has started. */
+  startedAt: string | null;
+  /** `model` while a model call runs, `tools` while server tools run, `paused` while a call waits on a person. */
+  phase: "model" | "tools" | "paused" | "draining";
+  /** Model rounds begun. */
+  rounds: number;
+  /** ISO-8601; until when the turn's runner holds it. */
+  leaseUntil: string | null;
+  /** Who may answer the turn's calls, as pinned at the turn's start. */
+  answeredBy: string | null;
+  /** The calls waiting on a person and until when, or null. */
+  pause: { callIds: string[]; since: string; expiresAt: string } | null;
+  /** A transition being made, or null. */
+  pending: { kind: "answer" | "end" } | null;
 }
 
 /** One session in `ctx.agents.listSessions` — #3805. */
@@ -1811,6 +1984,26 @@ export interface AgentSessionListPage {
   nextCursor?: string;
 }
 
+/** What `ctx.agents.recordEvent` takes — #3807. */
+export interface AgentSessionEvent {
+  /** An event kind the session's agent declares. */
+  kind: string;
+  /** The payload, validated against the kind's schema; at most 64 KiB of JSON. */
+  data: unknown;
+  /** Your own id for the event, 1 to 128 characters: a repeat with the same content records nothing. */
+  eventId?: string;
+  /** A call of this session (`call_<ULID>`) the event is about. */
+  refersTo?: string;
+}
+
+/** What `ctx.agents.recordEvent` answers — #3807. */
+export interface AgentSessionEventResult {
+  messageId: string;
+  seq: number;
+  /** Set when the `eventId` was already recorded with this content: the first event's ids. */
+  duplicate?: boolean;
+}
+
 /** 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 };
@@ -1833,22 +2026,32 @@ export type PromptOutput<K extends string> = K extends keyof PromptSchemas
   : unknown;
 
 /**
- * Why a prompt's own answer was refused — #3330. Never set on a PROVIDER
- * failure, which is what makes "the model returned the wrong shape"
- * distinguishable from "the model failed".
+ * Why a prompt's own answer was refused or incomplete — #3330, #4146. Never
+ * set on a PROVIDER failure, which is what makes "the model returned the wrong
+ * shape" distinguishable from "the model failed".
+ *
+ * `PROMPT_OUTPUT_TRUNCATED` is the answer cut off at the output token limit
+ * (`truncated` is `true` beside it): a declared-JSON answer that stopped
+ * before it was finished, whatever its shape, or a completion that spent the
+ * whole limit and came back empty. Raise the config's `maxTokens` rather
+ * than rewording the prompt.
  */
 export type PromptOutputErrorCode =
   | "PROMPT_OUTPUT_NOT_JSON"
-  | "PROMPT_OUTPUT_SCHEMA_VIOLATION";
+  | "PROMPT_OUTPUT_SCHEMA_VIOLATION"
+  | "PROMPT_OUTPUT_TRUNCATED";
 
 /**
  * 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_UPSTREAM_TIMEOUT` and `PROMPT_UPSTREAM_REJECTED` are NOT about the
+ * prompt's own answer: the provider ran out of time, or refused the request as
+ * invalid (`upstreamStatus` 400 — a setting the model does not support, such
+ * as a reasoning level, with the provider's message in `error`), so there was
+ * no answer to refuse. They are the only provider failures that set
+ * `errorCode`, which is what leaves "the model returned the wrong shape"
+ * distinguishable from "the model failed" while still letting a caller retry
+ * a timeout and fix the config for a refusal.
  *
  * `PROMPT_CRITERIA_INVALID` is the run that never reached a provider: a
  * decisions run's `variables.criteria` was refused before the call, so
@@ -1861,6 +2064,7 @@ export type PromptOutputErrorCode =
 export type PromptRunErrorCode =
   | PromptOutputErrorCode
   | "PROMPT_UPSTREAM_TIMEOUT"
+  | "PROMPT_UPSTREAM_REJECTED"
   | "PROMPT_CRITERIA_INVALID"
   | "PROMPT_STRICT_OUTPUT_SCHEMA_MISSING";
 
@@ -1874,6 +2078,12 @@ export interface PromptRunSuccess<TParsed> {
   errorCode?: null;
   metrics?: Record<string, unknown>;
   configId: string;
+  /**
+   * `true` when the provider stopped at the output token limit
+   * (`maxTokens`) before the answer was finished; absent otherwise. On
+   * Gemini, reasoning tokens count against the same limit.
+   */
+  truncated?: true;
 }
 
 /**
@@ -1902,6 +2112,12 @@ export interface PromptRunFailure {
    * empty — so a number here is always the provider's own.
    */
   upstreamStatus?: number;
+  /**
+   * `true` when the provider stopped at the output token limit
+   * (`maxTokens`) before the answer was finished; absent otherwise. On
+   * Gemini, reasoning tokens count against the same limit.
+   */
+  truncated?: true;
 }
 
 /** The envelope for a key whose declaration says nothing about its output. */
@@ -1919,6 +2135,12 @@ export interface PromptRunOpenResult {
   configId: string;
   /** The upstream provider's HTTP status on a provider failure — #3663. */
   upstreamStatus?: number;
+  /**
+   * `true` when the provider stopped at the output token limit
+   * (`maxTokens`) before the answer was finished; absent otherwise. On
+   * Gemini, reasoning tokens count against the same limit.
+   */
+  truncated?: true;
 }
 
 /**
@@ -2074,6 +2296,12 @@ export interface FunctionContext {
   /** The HTTP caller, or null for a webhook or cron fire. */
   user: FunctionUser | null;
   trigger: FunctionTrigger;
+  /**
+   * The agent session this tool call belongs to, when an agent turn called
+   * the function as a tool (`ctx.trigger.kind === "tool"`); otherwise
+   * absent.
+   */
+  tool?: FunctionToolContext;
   /**
    * Which RUNTIME is hosting this code — #3482.
    *
@@ -2213,6 +2441,13 @@ export interface FunctionContext {
    * `AGENT_SESSION_NOT_FOUND`. Both have the same origin rule as
    * `createSession`. Renaming, deleting and changing members are the
    * owner's, from a client.
+   *
+   * `recordEvent` (#3807) records an event in one of the invoking user's
+   * sessions, as that member: they must be its owner or a participant, and
+   * the origin rule is `createSession`'s. The kind must be one the agent
+   * declares (`AGENT_EVENT_KIND_UNKNOWN`) and the data must match its schema
+   * (`AGENT_EVENT_INVALID`). An event never starts a turn; the model reads
+   * it in a later turn.
    */
   agents: {
     createSession<K extends SessionAgentKeys>(
@@ -2220,6 +2455,7 @@ export interface FunctionContext {
     ): Promise<AgentSessionCreateResult>;
     getSession(sessionId: string): Promise<AgentSessionInfo>;
     listSessions(options?: AgentSessionListOptions): Promise<AgentSessionListPage>;
+    recordEvent(sessionId: string, event: AgentSessionEvent): Promise<AgentSessionEventResult>;
   };
   /**
    * 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.1",
+  "version": "0.3.0-alpha.3",
   "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",