@soat/sdk 0.22.1 → 0.24.0

package/dist/index.cjs

@@ -1018,6 +1018,8 @@ var AiProviders = class {
 	* Asks the provider which models it can run, using this provider record's own credentials and configuration, and returns provider-native model ids — the same strings `default_model` and an agent's `model` carry.
 	* Which models are reachable is a property of the credential, not of the provider type: a Vertex provider sees only the publisher models its Google Cloud project and location serve, and a Bedrock provider only the foundation models enabled in its region. Reading the list is how a caller avoids pinning a model that fails at generation time.
 	* Not every provider type can answer. `azure` lists deployments an operator named rather than models, and `ollama` lists whatever was pulled onto that host, so both return `400 MODEL_LISTING_UNSUPPORTED`.
+	* Listing resolves credentials the same way generation does, so a record that can generate can list. The API-key types (`openai`, `groq`, `xai`, `gateway`, `custom`, `anthropic`, `google`) use the record's linked secret and cannot list without one. `bedrock` and `vertex` use the linked secret when there is one — IAM keys or a Bedrock API key, a Google service-account key — and otherwise fall back to the server environment (the AWS default credential chain, Google Application Default Credentials), so a record with no `secret_id` can still list.
+	* A Vertex record needs no `config.project` when its secret is a service-account key, since the key file names its own project. A Vertex record in express mode (API key) cannot list at all: express mode is a global, project-less endpoint and the publisher-model catalogue is per-project, so it returns `400 MODEL_LISTING_UNSUPPORTED`.
 	*
 	*/
 	static listAiProviderModels(options) {
@@ -1059,7 +1061,7 @@ var ApiKeys = class {
 	/**
 	* List API keys
 	*
-	* Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - API key: returns only API keys scoped to the key's project.
+	* Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-scoped credential (API key or OAuth token): returns only API keys scoped to that project.
 	*
 	*/
 	static listApiKeys(options) {
@@ -1075,7 +1077,7 @@ var ApiKeys = class {
 	/**
 	* Create an API key
 	*
-	* Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped).
+	* Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped). - When the request is authenticated with a **project-scoped credential**, the new key is confined to that same project: omitting `project_id` defaults to it, naming a different project returns `403 API_KEY_PROJECT_SCOPE`, and `project_id: null` (an unscoped key) is likewise refused. Minting an unscoped key requires an unscoped credential.
 	*
 	*/
 	static createApiKey(options) {
@@ -1091,7 +1093,7 @@ var ApiKeys = class {
 	/**
 	* Delete an API key
 	*
-	* Deletes an API key. Only the owner or an admin can delete it.
+	* Deletes an API key. Only the owner or an admin can delete it, and a project-scoped credential can only delete keys in its own project.
 	*/
 	static deleteApiKey(options) {
 		return (options.client ?? client).delete({
@@ -1102,7 +1104,7 @@ var ApiKeys = class {
 	/**
 	* Get an API key
 	*
-	* Returns details of an API key. Only the owner or an admin can access it.
+	* Returns details of an API key. Only the owner or an admin can access it, and a project-scoped credential can only reach keys in its own project.
 	*/
 	static getApiKey(options) {
 		return (options.client ?? client).get({
@@ -1113,7 +1115,7 @@ var ApiKeys = class {
 	/**
 	* Update an API key
 	*
-	* Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it.
+	* Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it. A project-scoped credential can only update keys in its own project, and cannot move a key to another project or unscope it.
 	*/
 	static updateApiKey(options) {
 		return (options.client ?? client).put({
@@ -1276,25 +1278,15 @@ var Chats = class {
 		});
 	}
 	/**
-	* Create a chat completion for a stored chat
+	* Create a chat completion
 	*
-	* Runs a completion using the AI provider and settings stored in the chat. Pass `stream: true` for SSE streaming. A system message in `messages` overrides the chat's stored system message for this call only. Messages may use `documentId` instead of `content`.
+	* OpenAI Chat Completions-compatible endpoint. Mirrors OpenAI's `POST /v1/chat/completions` path so an OpenAI SDK can target it by base URL alone.
 	*
-	*/
-	static createChatCompletionForChat(options) {
-		return (options.client ?? client).post({
-			url: "/api/v1/chats/{chat_id}/completions",
-			...options,
-			headers: {
-				"Content-Type": "application/json",
-				...options.headers
-			}
-		});
-	}
-	/**
-	* Create a chat completion (stateless)
+	* Names exactly one target. With `ai_provider_id` the completion is stateless: the provider's secret is decrypted and the appropriate Vercel AI SDK provider is called, with no server-side model fallback. With `chat_id` the stored chat supplies the provider (or the project's `default_model_route_id`), model and instructions.
+	*
+	* System content travels only in `instructions` — a `role: "system"` entry in `messages` is refused with `400 SYSTEM_MESSAGE_NOT_ALLOWED`. With `chat_id`, a request `instructions` replaces the chat's stored one for this call only; the stored value applies when the request carries none, and the two are never merged.
 	*
-	* OpenAI Chat Completions-compatible endpoint. Mirrors OpenAI's `POST /v1/chat/completions` path so an OpenAI SDK can target it by base URL alone. Resolves the AI provider from `ai_provider_id`, decrypts its secret, and calls the appropriate Vercel AI SDK provider. `ai_provider_id` is required — there is no server-side model fallback.
+	* Messages may use `document_id` instead of `content` with either target. Chats hold no message history — send the full `messages` array every time.
 	*
 	*/
 	static createChatCompletion(options) {
@@ -1782,6 +1774,27 @@ var Evaluations = class {
 		});
 	}
 	/**
+	* Curate a dataset item from a generation
+	*
+	* Promotes a real, completed generation into a test case: its input messages become the item's `input`, and its own answer becomes `expected_output` unless you supply one. Use it to build an evaluation set out of production traffic rather than hand-authoring fixtures.
+	*
+	* The item is a **copy**, not a view. It keeps working after the source generation's content is purged, and `source_generation_id` goes null if that generation is deleted — a purge can never quietly stop a suite from being runnable.
+	*
+	* Requires both `evaluations:CreateDataset` and `generations:GetGeneration`: the call copies content out of a generation, so a principal that may not read that generation may not curate it either.
+	*
+	* Only a **completed** generation can be promoted (`409 GENERATION_NOT_COMPLETED`), and only while its content is still available: an agent or project running with `trace_content_mode: none` never stored the input, and a purged or expired generation no longer has it (`409 GENERATION_CONTENT_UNAVAILABLE`). Generations that predate input recording answer the same way.
+	*/
+	static createDatasetItemFromGeneration(options) {
+		return (options.client ?? client).post({
+			url: "/api/v1/datasets/{dataset_id}/items/from-generation",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
 	* Delete a dataset item
 	*
 	* Deletes a test case. Results of runs that already scored it stay readable; their `dataset_item_id` becomes null.
@@ -2232,6 +2245,8 @@ var Formations = class {
 	*
 	* Validates the template, creates the formation record, then provisions all declared resources in dependency order.
 	*
+	* A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `201` and `status: "failed"`, and `error` explains why (the resources created before the failure are rolled back). Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `soat` CLI exits non-zero on that body so `create-formation && …` does not lie.
+	*
 	*/
 	static createFormation(options) {
 		return (options.client ?? client).post({
@@ -2248,6 +2263,10 @@ var Formations = class {
 	*
 	* Deletes the formation stack and all its managed resources in reverse dependency order.
 	*
+	* A resource the platform refuses to delete on its own — most often an agent that has generation or trace history — fails the teardown with `409 FORMATION_DELETE_FAILED`, naming every blocking resource in `error.meta.failures`. Resolve the blockers (for an agent, `DELETE /api/v1/agents/{agent_id}?force=true` also removes its generations and traces, and `deletion_policy: retain` exempts it from teardown entirely) and delete the formation again.
+	*
+	* A refusal the platform can foresee is found by a pre-flight, before the first delete: nothing is removed, and the formation stays `active` and intact for the retry. An unforeseeable error surfaces mid-teardown instead, where resources deleted before the blocker stay deleted and the formation is left in `delete_failed`. The error message states which happened.
+	*
 	*/
 	static deleteFormation(options) {
 		return (options.client ?? client).delete({
@@ -2271,6 +2290,8 @@ var Formations = class {
 	*
 	* Applies a new template to the formation. Resources are created, updated, or deleted to reconcile the current state with the desired state.
 	*
+	* A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `200` and `status: "failed"`, and `error` explains why. Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `soat` CLI exits non-zero on that body so `update-formation && …` does not lie.
+	*
 	*/
 	static updateFormation(options) {
 		return (options.client ?? client).put({
@@ -2354,6 +2375,22 @@ var Generations = class {
 			...options
 		});
 	}
+	/**
+	* Get a generation's transcript
+	*
+	* Returns one generation's turn read back as an ordered sequence of steps: what it was asked, each model step with its tool calls and results, and how it ended.
+	*
+	* The transcript is assembled at read time from the generation record and the trace's steps object; nothing is stored, so it cannot outlive the content it projects. Requires `traces:GetTrace` in addition to `generations:GetGeneration`, because the response merges content from both resources.
+	*
+	* A generation whose content is unavailable — never written under zero-retention, or cleared by a purge — returns `200` with the skeleton rather than an error: `input` and `output` are null, `steps` is empty, and the `content_redacted_*` fields say which happened. `content_redacted_by_principal_id` is `zero_retention` when the content was never stored, and the purging principal's ID when it was erased later. A generation that is still running returns the same shape with an empty `steps`; `status` disambiguates the two.
+	*
+	*/
+	static getGenerationTranscript(options) {
+		return (options.client ?? client).get({
+			url: "/api/v1/generations/{generation_id}/transcript",
+			...options
+		});
+	}
 };
 var Guardrails = class {
 	/**
@@ -2909,7 +2946,7 @@ var Orchestrations = class {
 	/**
 	* Start an orchestration run
 	*
-	* Creates a new run for the orchestration named by orchestration_id. By default the run executes durably in the background: the response returns immediately with status "queued" (a worker then claims it and moves it to "running") and progress is observed via get-orchestration-run or run lifecycle webhook events (orchestration_runs.started/awaiting_input/succeeded/failed). Delay and poll waits park the run as "sleeping" and are woken by a background scheduler, surviving restarts. Pass wait=true to block until the run reaches a terminal or awaiting_input state (the legacy synchronous behaviour).
+	* Creates a new run for the orchestration named by orchestration_id. By default the run executes durably in the background: the response returns immediately with status "queued" (a worker then claims it and moves it to "running") and progress is observed via get-orchestration-run or run lifecycle webhook events (orchestration_runs.started/awaiting_input/succeeded/failed). Delay and poll waits park the run as "sleeping" and are woken by a background scheduler, surviving restarts. Pass wait=true to block until the run reaches a terminal or awaiting_input state.
 	*/
 	static startOrchestrationRun(options) {
 		return (options.client ?? client).post({
@@ -3380,6 +3417,38 @@ var Sessions = class {
 		});
 	}
 	/**
+	* Fork a session
+	*
+	* Branches a new session from a point in this session's history: same context, different continuation.
+	*
+	* The fork gets its own conversation whose messages **reference the same documents** as the parent rather than copying them, so there is one stored copy of the content and a retention purge erases it from both. Recorded tool results ride along on those messages and are **replayed** as model input on the fork's next turn — forking never re-invokes a tool, so exploring a "what if" cannot send an email or charge a card a second time. The consequence to accept is that a forked turn sees the tool data as it was, not as it is now.
+	*
+	* The fork is created **inert**: `auto_generate` is false and no generation is triggered. Drive it with the normal message and generate endpoints. The fork has no actor — attach one only if the branch is meant to be driven by the same end user, since `single_session_per_actor` agents allow one open session per actor.
+	*
+	*/
+	static forkSession(options) {
+		return (options.client ?? client).post({
+			url: "/api/v1/sessions/{session_id}/fork",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* List a session's forks
+	*
+	* Returns the sessions forked directly from this one. One level of lineage: a fork of a fork is listed under its own parent.
+	*
+	*/
+	static listSessionForks(options) {
+		return (options.client ?? client).get({
+			url: "/api/v1/sessions/{session_id}/forks",
+			...options
+		});
+	}
+	/**
 	* Get session tags
 	*
 	* Returns the session's tags object.
@@ -3775,7 +3844,7 @@ var Usage = class {
 	/**
 	* List usage meters
 	*
-	* Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent, generation, trace, actor, or session. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.
+	* Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent, generation, trace, actor, session, or `source`. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.
 	*
 	*/
 	static listUsageMeters(options) {
@@ -4070,6 +4139,22 @@ var Webhooks = class {
 		});
 	}
 	/**
+	* Redeliver a webhook delivery
+	*
+	* Queues the stored payload of an existing delivery to be sent again.
+	*
+	* A new delivery record is created rather than the original being reset,
+	* so the original attempt stays in the history. The send happens in the
+	* background: poll the returned delivery to observe its outcome.
+	*
+	*/
+	static redeliverWebhookDelivery(options) {
+		return (options.client ?? client).post({
+			url: "/api/v1/webhook-deliveries/{delivery_id}/redeliver",
+			...options
+		});
+	}
+	/**
 	* Get webhook secret
 	*
 	* Retrieves the signing secret for the specified webhook