@toloka-platform/sdk 0.2.0-preview.2 → 0.2.0-preview.4

package/dist/cli/toloka.js.jsc.sha256

@@ -1 +1 @@
-4bc560d638ddf49386ccbb12f7eeaaa0922fd26ab13c69065cbb8540c27cbe50  toloka.js.jsc
+ee914e999937f98c40a657d10640ea64acda93b2e50f4a9306e25453c8897248  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-e7e688bae427a1230ea0cbcacf81224527dc592f0e9087d584462d5ab3ec2059  toloka.js
+fabf11ce7545f788c03870778c18deda006d89c95c839ae8c1592f4eaa287366  toloka.js

package/docs/authoring.md

@@ -86,6 +86,21 @@ Register authored code behavior with `test.code(pipeline, node, name, callback)`
 
 One human-work task type. The node owns the entire expert journey: instruction, UI, entity schemas, quality criteria, quality assurance, audience, pricing, Training, and Exam.
 
+Choose entity cardinality from the task, not from the component's JavaScript value shape. If one labeler produces one logical result, keep the entity static: omit `dynamic` and `maxEntities`, and use a path without `[*]`.
+
+```ts
+{
+  field: caption,
+  entityType: "SHORT_ANSWER",
+  jsonPath: "$.caption",
+  description: "The one caption written for this image.",
+}
+```
+
+Use `dynamic: true` only when one labeler produces multiple independent entities. Set `maxEntities` to a task-grounded upper bound rather than a generic default. A component may expose an array while still producing one logical entity; for a single upload or recording, keep a scalar field and static entity and select the completed first value with a path such as `$.video_file[0].downloadLink`.
+
+The following task is legitimately dynamic because the labeler can draw one independent box for every visible face:
+
 ```ts
 import { generation } from "@toloka-platform/sdk";
 
@@ -209,7 +224,7 @@ export const routeDisputed = match("route_disputed", {
   about: { name: "route_disputed" },
   conditions: [
     {
-      name: "is disputed",
+      name: "is_disputed",
       predicates: [{ field: verdict, jsonPath: "$", operator: "text_eq", value: "disputed" }],
     },
   ],
@@ -217,6 +232,8 @@ export const routeDisputed = match("route_disputed", {
 });
 ```
 
+Each condition name must be unique within the Match node and contain 2–32 characters. Start with a lowercase letter, use only lowercase letters, digits, and underscores, and end with a letter or digit. `match()` rejects invalid or duplicate names locally before any platform request.
+
 ## Connect ports
 
 `connect(from, to)` is the only way to create an edge. Ports are typed, so a wrong direction is a compile error.

package/docs/cli-v2.md

@@ -9,7 +9,7 @@ The platform object is a **project** (`pp.…`, today's pipeline project). Windm
 Today the checkout is a pipeline tree that happens to mention a project.
 
 - A directory is a project root if it has `toloka.json` **or** a `pipelines/` folder. No pipelines, no root.
-- `init` writes agent skills before a project exists. It writes `toloka.json` only from an explicit `--project-id`, `TOLOKA_PROJECT_ID` / `POTATO_PROJECT_ID`, or an existing checkout; it never binds a new checkout from the machine registry.
+- `init` writes agent skills before a project exists. It writes `toloka.json` only from an explicit `--project-id`, `TOLOKA_PROJECT_ID`, or an existing checkout; it never binds a new checkout from the machine registry.
 - A checkout attaches when `project create` or `import` writes `toloka.json`, or when `init` receives explicit project identity.
 - `run`, `status`, `runs`, and `cost` pick a pipeline from `toloka.json`. Zero pipelines is an error. Several pipelines opens a picker. The command names pretend there is "the" pipeline.
 - `status` means "latest run of some pipeline", not "this project".
@@ -61,7 +61,7 @@ A checkout can later grow other folders (`datasets/`, `files/`, whatever we auth
 Highest wins:
 
 1. `--project-id`
-2. `TOLOKA_PROJECT_ID` (keep accepting `POTATO_PROJECT_ID` until we rename the rest of the env surface)
+2. `TOLOKA_PROJECT_ID` (the legacy `POTATO_*` names are still read for one preview cycle with a deprecation warning)
 3. `toloka.json` in the discovered checkout (walk up from cwd, or `--source-root`)
 4. `current` in the machine registry
 5. Fail: `No project selected. Run toloka project create for a new project, toloka project add for an existing project, or cd into a checkout.`
@@ -86,13 +86,14 @@ toloka project remove cat-labeling           # local unbind only
 
 `project add` with no arguments prompts for alias and id, like `wmill workspace add`. The new alias becomes `current`.
 
-Create a live project and bind it in one step:
+Create a live project and bind it in one step. The delivery order follows the owning team, not the account (`toloka whoami` marks internal teams `(internal)` on its `Teams:` line): a project in an internal team must carry an active id from `toloka delivery-order list`, and a project in an external team must not carry one, even when the account is internal:
 
 ```sh
 toloka project create cat-labeling --team-id <teamId>
+toloka project create cat-labeling --team-id <teamId> --delivery-order-id <orderId>
 ```
 
-`POST /projects` requires `teamId`. There is no public team-list endpoint today, so `--team-id` is required unless every visible project shares one team, in which case we reuse that id. If teams differ, refuse and ask.
+`POST /projects` requires `teamId`. `GET /me` lists the caller's teams with their write access, so `--team-id` is optional when the account has exactly one writable team; with several, the CLI refuses and names them.
 
 `project create` writes the machine alias, sets `current`, and if cwd has no `toloka.json`, writes one.
 
@@ -125,6 +126,7 @@ Resource commands never search the disk for a pipeline first. They load the proj
 | `plan` / `apply` / `validate` | whole project                 | no                 |
 | `secret set`                  | project                       | no                 |
 | `dataset list`                | project                       | no                 |
+| `dataset create <name>`       | project                       | no                 |
 | `dataset fields <name>`       | named dataset in this project | no                 |
 | `dataset load <name>`         | named dataset in this project | no                 |
 | `dataset upload <name>`       | named dataset in this project | no                 |

package/docs/cli.md

@@ -4,7 +4,7 @@ The `toloka` CLI reads TypeScript source as the desired state, compares it with
 
 This CLI is Beta software. Commands, flags, and output can change before general availability.
 
-`toloka` requires Bun 1.4.0. The published package ships matching CLI bytecode; the launcher falls back to TypeScript source in a development checkout when the bytecode is absent.
+`toloka` requires Bun 1.4.0 or newer. The published package ships CLI bytecode built with Bun 1.4.0; another Bun version runs the same bundled JavaScript without that cache and starts slower. The launcher falls back to TypeScript source in a development checkout when the bytecode is absent.
 
 ## Configuration
 
@@ -13,28 +13,30 @@ Credentials and the platform base URL resolve from the same precedence order, hi
 | Precedence  | API key source                             |
 | ----------- | ------------------------------------------ |
 | 1 (highest) | `--api-key` flag                           |
-| 2           | `POTATO_API_KEY` environment variable      |
+| 2           | `TOLOKA_API_KEY` environment variable      |
 | 3 (lowest)  | credentials file written by `toloka login` |
 
 | Precedence  | Base URL source                         |
 | ----------- | --------------------------------------- |
 | 1 (highest) | `--base-url` flag                       |
-| 2           | `POTATO_BASE_URL` environment variable  |
+| 2           | `TOLOKA_BASE_URL` environment variable  |
 | 3           | base URL stored in the credentials file |
 | 4 (default) | `https://platform.toloka.ai`            |
 
 | Precedence  | Project id source                             |
 | ----------- | --------------------------------------------- |
 | 1 (highest) | `--project-id` flag                           |
-| 2           | `TOLOKA_PROJECT_ID`, then `POTATO_PROJECT_ID` |
+| 2           | `TOLOKA_PROJECT_ID` |
 | 3           | `projectId` in `toloka.json`                  |
 | 4 (lowest)  | `current` alias in the credentials file       |
 
+Earlier releases named these variables `POTATO_API_KEY`, `POTATO_BASE_URL`, and `POTATO_PROJECT_ID`. The CLI still reads each legacy name when its `TOLOKA_*` counterpart is unset, prefers the `TOLOKA_*` value when both are set, and prints `POTATO_API_KEY is deprecated and will stop being read; set TOLOKA_API_KEY instead.` (and the same line for the other two) on stderr once per command. The legacy names stop being read in the first stable `0.2.0` release; rename them now to silence the warning.
+
 `toloka login` verifies the key against the platform before saving anything. It writes `$XDG_CONFIG_HOME/toloka/credentials.json`, which defaults to `~/.config/toloka/credentials.json`, with file mode `0600` and a parent directory with mode `0700`. The file may also store local project aliases. The legacy `~/.toloka/credentials.json` is still read when the new path has no file. `toloka logout` deletes the stored file but does not revoke the key.
 
 Machine settings live next to that credentials file in `settings.json` and default `auto-update` to `true`. A globally installed `toloka` checks `https://registry.npmjs.org/` at most once per day and, when a newer `@toloka-platform/sdk` version has been published for at least 24 hours, installs it with `bun add --global` and re-runs the original command. The check is pinned to that registry; a checkout `.env` cannot retarget it. `config`, `version`, and `help` never trigger a check. Project-local installs, CI, and `TOLOKA_SKIP_AUTO_UPDATE=1` also skip it. `TOLOKA_AUTO_UPDATE=0` turns it off for one command; `TOLOKA_AUTO_UPDATE=1` turns it on even when the setting is false.
 
-Ordinary usage events (`sdk_cli_command_completed` / `sdk_cli_command_failed`) go to Toloka's PostHog project so we can see which commands run and which error classes they hit. Their payloads contain only an allowlisted command classifier, duration, exit code, outcome or error code, SDK and Bun versions, actor, and channel. Raw arguments, flag values, environment variables, API keys, secret names, base URLs and hosts, local paths, project ids, error messages, stack traces, and source context are not sent. GeoIP enrichment is disabled. Distinct id starts as a random UUID stored next to the credentials file. After a successful authenticated command, the CLI calls `GET /me` and aliases that UUID onto the platform user id without setting person properties. Set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable capture. CI environments are disabled unless `TOLOKA_TELEMETRY=1`. The explicitly approved full-text `report` event is documented in [report](#report).
+Ordinary usage events (`sdk_cli_command_completed` / `sdk_cli_command_failed`) go to Toloka's PostHog project so we can see which commands run and which error classes they hit. Every failed command with an exception also emits a sanitized PostHog Error Tracking `$exception`; usage errors such as unknown commands or invalid flags do not. Command events contain only an allowlisted command classifier, duration, exit code, outcome or error code, optional HTTP status and server request ID, SDK and Bun versions, actor, and channel. Error Tracking receives the same bounded metadata plus a synthetic exception; raw arguments, flag values, environment variables, API keys, secret names, base URLs and hosts, local paths, project ids, error messages, stack traces, response bodies, and source context are not sent. GeoIP enrichment is disabled. Distinct id starts as a random UUID stored next to the credentials file. After a successful authenticated command, the CLI calls `GET /me` and aliases that UUID onto the platform user id without setting person properties. Set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable capture. CI environments are disabled unless `TOLOKA_TELEMETRY=1`. The explicitly approved full-text `report` event is documented in [report](#report).
 
 The root program accepts these flags before any command:
 
@@ -47,6 +49,10 @@ The root program accepts these flags before any command:
 
 Commands resolve the project root by walking up from the working directory until they find a `toloka.json` file. The CLI reports that directory on stderr when it differs from the working directory. Passing `--source-root` disables discovery. With no marker found, the working directory is used. `init` and `report` do not walk up: they use the working directory or `--source-root` only. The authentication commands `login`, `logout`, and `auth-status` do not need a project root.
 
+## Errors and hints
+
+A failing command prints its message to stderr and exits `1`. Most messages are followed by a `Hint: …` line with the next command to run; messages that already spell out the remedy carry no hint. Platform failures print `Potato API request failed with status <code> (request id: <id>)`, the response body, and a status-based hint: `401`/`403` point at `toloka whoami` and `toloka login`, `404` at the selected project and the matching list command, `429` asks you to wait, and `5xx` asks you to retry and then send a report with `toloka report <report.md>`.
+
 ## Resources and Base Actions
 
 The CLI is resource-first: `toloka <resource> <action>`. A Base Action has one meaning wherever a resource implements it. A resource exposes only the Base Actions that have real behavior; there are no placeholder actions.
@@ -80,11 +86,11 @@ toloka project switch <alias>
 toloka project current
 toloka project url
 toloka project remove <alias>
-toloka project create [alias] [--name <name>] [--team-id <id>]
+toloka project create [alias] [--name <name>] [--team-id <id>] [--delivery-order-id <id>]
 toloka project untrack <pipeline|dataset> <name> [--confirm]
 ```
 
-`add`, `switch`, `remove`, and `create` write the machine registry in the credentials file. They refuse `--api-key` / `--base-url` / `POTATO_*` when those would select a different key or platform than the stored file. `project list` prints project id, name, and team id. `create` reuses the only visible team when every listed project shares one; otherwise pass `--team-id`.
+`add`, `switch`, `remove`, and `create` write the machine registry in the credentials file. They refuse `--api-key` / `--base-url` / `TOLOKA_*` when those would select a different key or platform than the stored file. `project list` prints project id, name, and team id. `create` uses the account's only writable team (`GET /me` lists the teams; `whoami` prints them) and asks for `--team-id` when there are several. A project owned by an internal team also needs `--delivery-order-id`; `toloka delivery-order list` shows the orders and answers with an explanation for accounts without internal teams.
 
 `project untrack` removes one pipeline or dataset binding from `toloka.json` without deleting the live resource. It previews the name and id in a terminal; outside a terminal, pass `--confirm` after reviewing the state file.
 
@@ -92,16 +98,29 @@ toloka project untrack <pipeline|dataset> <name> [--confirm]
 
 `url` fetches the selected project to resolve its team and prints only its platform UI URL to stdout, making the output safe to capture in scripts and agent workflows.
 
+## delivery-order
+
+Lists the Sunday delivery orders this key can attach on `project create`. The command is always registered; the platform answers `403` for accounts without an internal team, which the CLI reports as `Delivery orders are available to internal teams only.`
+
+```sh
+toloka delivery-order list
+```
+
+Prints `ID`, `NAME`, `STATUS`, and `CLIENT` columns. Empty output is `No delivery orders visible.`
+
 ## login
 
 Stores an API key for this machine after verifying it.
 
 ```sh
 toloka login
+toloka login --api-key-stdin < key.txt
 ```
 
 The command explains how to generate an API key, prompts for it with masked input, and verifies it against the platform before saving. On success it prints `Authenticated against <base-url>: N project(s) visible.` and `Saved credentials to <path>.`
 
+Without a terminal there is no prompt. `--api-key-stdin` reads the key from standard input, so it never appears in shell history or the process list; `--api-key <key>` and `TOLOKA_API_KEY` also work but expose the key to both.
+
 ## logout
 
 Removes stored credentials from this machine.
@@ -120,7 +139,7 @@ Shows which platform and key the CLI would use. Alias: `whoami`.
 toloka auth-status [--show-token]
 ```
 
-On success it prints the platform URL with its source, the API key masked unless `--show-token` is passed, the selected project, and `Reachable: N project(s) visible.` The project line is printed even when no key is in effect or the platform is not reachable. It exits `1` when no key is in effect or the platform is not reachable.
+On success it prints the platform URL with its source, the API key masked unless `--show-token` is passed, the selected project, `Reachable: N project(s) visible.`, `Internal: true` or `Internal: false` for the account, and a `Teams:` line that marks each team `(internal)` and `(read-only)` where that applies. The project line is printed even when the probe fails. It exits `1` when no key is in effect, when the platform rejects the key (`Rejected: …`, followed by the advice to run `toloka login`), when the platform does not answer (`Not reachable: …`; the key was not evaluated), or when the platform fails (`Platform error: …`).
 
 ## config
 
@@ -143,7 +162,7 @@ Initializes the current project directory and installs the Agent Bootstrap entry
 toloka init
 ```
 
-`init` does not require a selected platform project. It always maintains one `<toloka>` … `</toloka>` Agent Bootstrap block in `AGENTS.md` and writes minimal pointers to it: `.claude/skills/toloka-bootstrap/SKILL.md` when `.claude/` exists (or when no agent configuration exists at all) and `.cursor/rules/toloka-bootstrap.mdc` with `alwaysApply: true` when `.cursor/rules/` exists. The bootstrap tells an agent to run `toloka --help`, search the bundled Skill Catalog with `toloka skill search`, install a matching skill with `toloka skill install`, and read `.agents/skills/<skill-id>/SKILL.md`; it does not embed the build workflow. Bytes outside the block are preserved, and re-running `init` refreshes the block and both pointers in place without adding duplicates. When a project is already selected through `--project-id`, `TOLOKA_PROJECT_ID` / `POTATO_PROJECT_ID`, `toloka.json`, or the machine registry, it also writes `toloka.json` when missing. It does not walk up to a parent checkout.
+`init` does not require a selected platform project. It always maintains one `<toloka>` … `</toloka>` Agent Bootstrap block in `AGENTS.md` and writes minimal pointers to it: `.claude/skills/toloka-bootstrap/SKILL.md` when `.claude/` exists (or when no agent configuration exists at all) and `.cursor/rules/toloka-bootstrap.mdc` with `alwaysApply: true` when `.cursor/rules/` exists. The bootstrap tells an agent to run `toloka --help`, search the bundled Skill Catalog with `toloka skill search`, install a matching skill with `toloka skill install`, and read `.agents/skills/<skill-id>/SKILL.md`; it does not embed the build workflow. Bytes outside the block are preserved, and re-running `init` refreshes the block and both pointers in place without adding duplicates. When a project is already selected through `--project-id`, `TOLOKA_PROJECT_ID`, `toloka.json`, or the machine registry, it also writes `toloka.json` when missing. It does not walk up to a parent checkout.
 
 `init` removes only Toloka-generated legacy entry points that still carry the `<!-- toloka:sdk-version … -->` marker: the full `toloka-build` and `toloka-pipeline-as-code` Claude skills and Cursor rules, plus the `<!-- toloka:begin -->` … `<!-- toloka:end -->` block in `AGENTS.md`, which is replaced by the `<toloka>` block in place. Files without that marker, other skills and rules, and installed skills under `.agents/skills/` are left untouched. An `AGENTS.md` whose current or legacy block is unterminated, reversed, or duplicated is refused with the file's full path before anything, including `toloka.json`, is written.
 
@@ -252,7 +271,7 @@ toloka base-model list [--json]
 toloka base-model get <id> [--json]
 ```
 
-Human-readable output is the default. `base-model list` prints aligned ID, name, provider, and upstream-model columns; `base-model get` prints labeled fields including the pinned revision. Pass `--json` for machine-readable output.
+Human-readable output is the default. `base-model list` prints aligned ID, name, provider, upstream-model, revision (first 12 characters) and upstream-snapshot URL columns; `base-model get` prints labeled fields including the full pinned revision and the `https://huggingface.co/<model>/tree/<revision>` snapshot URL. Pass `--json` for machine-readable output.
 
 ## model
 
@@ -268,12 +287,34 @@ toloka model archive <name-or-id> [--json]
 
 `model create` creates project-owned Model metadata linked to one catalog Base Model; it does not create a Model Version. Human-readable output is the default for every command in this group. Pass `--json` for machine-readable objects or arrays. Weight upload, validation, download, and Model Version creation are deferred.
 
+## training
+
+Create a reusable Training draft, price it, and run it.
+
+```sh
+toloka training list [--json]
+toloka training get <name-or-id> [--json]
+toloka training create <name> [--method sft|gisting] (--base-model <id> | --model-version <id>) --dataset <id> [--train-filter field=value] [--validation-dataset <id> [--validation-filter field=value]] [--prompt-file <path>] [--lora-rank 8|16|32 | --gist-tokens 8|32|64] [--epochs 1..5] [--learning-rate <rate>] [--batch-size 8|16|32|64] [--max-sequence-length <tokens>] [--json]
+toloka training update <name-or-id> [--base-model <id> | --model-version <id>] [--dataset <id>] [--train-filter field=value] [--validation-dataset <id> [--validation-filter field=value]] [--prompt-file <path>] [--lora-rank 8|16|32 | --gist-tokens 8|32|64] [--epochs 1..5] [--learning-rate <rate>] [--batch-size 8|16|32|64] [--max-sequence-length <tokens>] [--json]
+toloka training cost <name-or-id> [--idempotency-key <key>] [--json]
+toloka training run <name-or-id> [--estimate-file <path>] [--version-name <name>] [--idempotency-key <key>] [--json]
+toloka training runs <name-or-id> [--json]
+toloka training status <training-run-id> [--json]
+toloka training resume <training-run-id> [--json]
+toloka training cancel <training-run-id> [--json]
+toloka training logs <training-run-id>
+toloka training metrics <training-run-id> [--key <metric>] [--resolution <n>] [--json]
+```
+
+Hyperparameters are optional flags on `training create` and `training update`: `--epochs 1..5` (default 3), `--learning-rate` (SFT 0.00001–0.001, default 0.00015; gisting 0.001–0.3, default 0.03), `--batch-size 8|16|32|64` (default 8; sequences per optimizer step across all GPUs) and `--max-sequence-length 64..16384` (default 12288 for SFT, 3072 for gisting) apply to both methods; `--lora-rank 8|16|32` (default 16) is SFT-only and `--gist-tokens 8|32|64` (default 32) is gisting-only — passing one to the other method fails before any request. `--regime` and `--eval-steps` no longer exist. `training update` has no `--method` flag: the method stays as created, and every flag you omit keeps its current value. `training cost` is blocked when the longest example exceeds `--max-sequence-length` or when the training selection leaves fewer rows than `--batch-size` after the 10% holdout. `training get` prints the resolved recipe, so omitted flags are visible as their defaults.
+
 ## dataset
 
 Catalog and row commands for datasets in the selected project. Name or id is accepted; duplicate names must be addressed by id.
 
 ```sh
 toloka dataset list
+toloka dataset create <name>
 toloka dataset fields <name>
 toloka dataset load <name> --out <file> [--limit <n>] [--timeout <ms>]
 toloka dataset upload <name> <file>
@@ -281,6 +322,8 @@ toloka dataset upload <name> <file>
 
 `dataset list` prints live `name` and id. It does not page items.
 
+`dataset create` makes an empty dataset in the selected project; the first `dataset upload` infers its columns from the rows.
+
 `dataset fields` prints inferred `field()` TypeScript, or `Dataset <name> has no inferred fields yet.`
 
 `dataset load` starts a platform export, waits for it (default 60s; pass `--timeout`), downloads the JSON array, and writes JSONL to `--out`. `--limit` slices after download; it still waits for the full export. On timeout the message names the export id. Failed downloads and invalid payloads leave `--out` untouched.
@@ -313,12 +356,14 @@ toloka skill install <skillId> [--force]
 
 `list` prints every skill in the catalog with its installation status: `not-installed` when `.agents/skills/<skillId>` is absent, `current` when the installed files match the catalog digest, and `stale` when they differ. Each skill line (`id`, status, name) is followed by one indented description line. `--json` prints the Skill Descriptors (`id`, `name`, `description`, `tags`, `version`, `digest`, `files`) plus `status` and never includes file contents.
 
-`search` matches `<query>` case-insensitively against each skill's id, name, description, and tags and prints the matches in the same format. When nothing matches it says so (or prints `[]` with `--json`), exits 0, and installs nothing.
+`search` matches `<query>` case-insensitively against each skill's id, name, description, and tags and prints the matches in the same format. When nothing matches it prints `No skills match "<query>" in the catalog bundled with @toloka-platform/sdk <version>. …` (or `[]` with `--json`), exits 0, and installs nothing.
 
 `install` copies the complete skill — its `SKILL.md` entry point and every reference — from the package into `.agents/skills/<skillId>/` under the project root and prints the destination. Every path is confined to that directory and the command refuses to write through symbolic links. An existing `.agents/skills/<skillId>` is refused unless `--force` is passed. With `--force` the new copy is written to a temporary sibling directory and verified against the catalog digest, the existing directory is renamed to a backup, the verified copy is moved into place, and the backup is removed; a failed swap restores the backup, so the directory never holds a mixed version. A malformed catalog, an unsafe path, or a digest mismatch fails before any existing file changes.
 
 After an SDK upgrade `list` reports installed skills whose catalog digest changed as `stale` until they are refreshed with `install --force`. Local edits to an installed skill also make it `stale`; `list` and `search` never modify local files.
 
+The catalog is bound to the installed package version, so a skill that a newer release ships is simply absent from an older CLI. `install` then exits 1 with `Skill "<skillId>" is not in the catalog bundled with @toloka-platform/sdk <version>. Run toloka skill list to see the available skills; a newer release may ship it (bun add --global @toloka-platform/sdk@<channel>).` and creates nothing. `<channel>` is the channel of the installed version (`preview` for a `-preview.N` version, otherwise `latest`); reinstall from it and retry.
+
 ## Exit codes
 
 `toloka pipeline run --wait` maps the run outcome to the process exit code.
@@ -331,6 +376,8 @@ After an SDK upgrade `list` reports installed skills whose catalog digest change
 
 Every other failure exits non-zero with a message on stderr: missing project identity, a rejected login, an unauthenticated `auth-status`, or a failed `secret set`.
 
+An unknown command exits 1 before anything else runs, even when `--help` is present: `toloka training --help` on a build without `training` prints `error: unknown command 'training'` followed by `toloka <version> does not have it. Run toloka --help to list its commands; a runbook that uses it may need a newer release.` on stderr, and does not print the root help. Only a command the installed version defines exits 0 with `--help`.
+
 ## The reconcile loop
 
 Treat the TypeScript source as authoritative. The canonical sequence is: run the complete local gate, validate against the platform, plan, apply, then plan again to confirm convergence.

package/docs/getting-started.md

@@ -11,7 +11,7 @@ curl -fsSL https://platform.toloka.ai/cli/install.sh | sh
 bun add @toloka-platform/sdk@latest
 ```
 
-The installer requires Bun 1.4.0, installs `@toloka-platform/sdk` globally, and exposes `toloka` through Bun's global binary directory. The published CLI includes matching precompiled bytecode. The project install makes SDK imports resolvable.
+The installer requires Bun 1.4.0 or newer, installs `@toloka-platform/sdk` globally, and exposes `toloka` through Bun's global binary directory. The published CLI includes bytecode built with Bun 1.4.0; another Bun version runs the same bundled JavaScript without that cache and starts slower. The project install makes SDK imports resolvable.
 
 ## Sign in
 
@@ -33,11 +33,11 @@ Check what the CLI will use at any time:
 toloka whoami
 ```
 
-CI does not need `login`. Set `POTATO_API_KEY` and the stored file is ignored. See the precedence table in the [CLI reference](./cli.md).
+CI does not need `login`. Set `TOLOKA_API_KEY` and the stored file is ignored. See the precedence table in the [CLI reference](./cli.md).
 
 ## Start with an agent
 
-For a guided first run, start a fresh coding-agent session and ask it to follow `https://platform.toloka.ai/agents/data-labeling.md`. The guide takes the agent through installation, credentials, project selection, local tests, plan approval, apply, cost review, and a bounded sample run.
+For a guided first run, start a fresh coding-agent session and ask it to follow the [Toloka agent bootstrap](https://platform.toloka.ai/agents/SKILL.md). It routes to the data-labeling, fine-tuning, or gisting runbook and the matching packaged skill.
 
 Initialize the current directory and install the Agent Bootstrap. No platform project needs to be selected yet.
 

package/docs/limitations.md

@@ -2,7 +2,7 @@
 
 What this Beta SDK does not do yet, stated plainly so you can decide what to depend on.
 
-`@toloka-platform/sdk` is `0.2.0-preview.2`. This is a Beta: the authoring API, the CLI surface, and the generated source layout can change before general availability. Pin an exact version. Do not depend on this in production yet.
+`@toloka-platform/sdk` is `0.2.0-preview.3`. This is a Beta: the authoring API, the CLI surface, and the generated source layout can change before general availability. Pin an exact version. Do not depend on this in production yet.
 
 ## Local checks do not certify deployability
 

package/docs/testing.md

@@ -94,7 +94,7 @@ For a structured or array-valued Field, derive the dataset field schema from the
 
 ## Runtime rules
 
-`ui.code` must parse as one JSX root. Every identifier must be a component returned by `componentDocumentation()` or a documented `actions` API. `toloka check` applies full TypeScript semantic checking with declarations bundled in the SDK; the real launcher then renders the same JSX in browser scenarios. Treat a component's `propsType` and `example` together as its contract.
+`ui.code` must parse as one TSX root. Every identifier must be a component returned by `componentDocumentation()` or a documented `actions` API. `toloka check` applies full TypeScript semantic checking with declarations bundled in the SDK; the real launcher then renders the same TSX in browser scenarios. Treat a component's `propsType` and `example` together as its contract.
 
 `preprocess` and `postprocess` are JavaScript function bodies, not TypeScript:
 

package/docs/troubleshooting.md

@@ -92,7 +92,7 @@ toloka pipeline results <runId> --failed
 Missing API key. Run toloka login once to store credentials for this machine.
 ```
 
-Run `toloka login`, or set `POTATO_API_KEY` in an environment where interactive login is not possible. `toloka whoami` reports which platform and which key source is in effect, and exits non-zero when the platform is unreachable.
+Run `toloka login`. Where interactive login is not possible, pipe the key to `toloka login --api-key-stdin` or set `TOLOKA_API_KEY`. `toloka whoami` reports which platform and which key source is in effect, and exits non-zero when the platform is unreachable.
 
 ## Authentication fails with a key you just generated
 

package/examples/face-image-collection/README.md

@@ -11,8 +11,8 @@ toloka init
 Then configure the API and import an existing project:
 
 ```sh
-export POTATO_API_KEY=api-key
-export POTATO_BASE_URL=https://potato.example.com
+export TOLOKA_API_KEY=api-key
+export TOLOKA_BASE_URL=https://potato.example.com
 toloka import pp.0190abcd-abcd-7abc-8abc-abcdefabcdef
 # Imported project pp.0190abcd-abcd-7abc-8abc-abcdefabcdef with 1 pipeline and 1 dataset into ...
 ```

package/openapi/gen/api.ts

@@ -30,12 +30,14 @@ import type {
   ExportPipeline200,
   GetDatasetInferredFields200,
   GetTrainingRunLogsParams,
+  GetTrainingRunMetricHistoryParams,
   ImportPipelineBody,
   ListBaseModels200,
   ListDatasetFields200,
   ListDatasetFieldsParams,
   ListDatasetItems200,
   ListDatasetItemsParams,
+  ListDeliveryOrders200,
   ListModelVersions200,
   ListModelVersionsParams,
   ListPipelineChecks200,
@@ -93,6 +95,8 @@ import type {
   TrainingRun,
   TrainingRunId,
   TrainingRunLogs,
+  TrainingRunMetricHistory,
+  TrainingRunMetrics,
   UpdatePipelineBody,
   UpdateProjectBody,
   UpdateTrainingMetadataBody,
@@ -587,6 +591,59 @@ export const getTrainingRunLogs = async (trainingRunId: TrainingRunId,
 
 
 
+export const getGetTrainingRunMetricsUrl = (trainingRunId: TrainingRunId,) => {
+
+
+  
+
+  return `/api/v2-beta/training-runs/${trainingRunId}/metrics`
+}
+
+export const getTrainingRunMetrics = async (trainingRunId: TrainingRunId, options?: RequestInit): Promise<TrainingRunMetrics> => {
+  
+  return potatoFetch<TrainingRunMetrics>(getGetTrainingRunMetricsUrl(trainingRunId),
+  {      
+    ...options,
+    method: 'GET'
+    
+    
+  }
+);}
+
+
+
+export const getGetTrainingRunMetricHistoryUrl = (trainingRunId: TrainingRunId,
+    metricKey: string,
+    params?: GetTrainingRunMetricHistoryParams,) => {
+  const normalizedParams = new URLSearchParams();
+
+  Object.entries(params || {}).forEach(([key, value]) => {
+    
+    if (value !== undefined) {
+      normalizedParams.append(key, value === null ? 'null' : value.toString())
+    }
+  });
+
+  const stringifiedParams = normalizedParams.toString();
+
+  return stringifiedParams.length > 0 ? `/api/v2-beta/training-runs/${trainingRunId}/metrics/${metricKey}?${stringifiedParams}` : `/api/v2-beta/training-runs/${trainingRunId}/metrics/${metricKey}`
+}
+
+export const getTrainingRunMetricHistory = async (trainingRunId: TrainingRunId,
+    metricKey: string,
+    params?: GetTrainingRunMetricHistoryParams, options?: RequestInit): Promise<TrainingRunMetricHistory> => {
+  
+  return potatoFetch<TrainingRunMetricHistory>(getGetTrainingRunMetricHistoryUrl(trainingRunId,metricKey,params),
+  {      
+    ...options,
+    method: 'GET'
+    
+    
+  }
+);}
+
+
+
 export const getResumeTrainingRunUrl = (trainingRunId: TrainingRunId,) => {
 
 
@@ -650,6 +707,27 @@ export const getCurrentUser = async ( options?: RequestInit): Promise<CurrentUse
 
 
 
+export const getListDeliveryOrdersUrl = () => {
+
+
+  
+
+  return `/api/v2-beta/delivery-orders`
+}
+
+export const listDeliveryOrders = async ( options?: RequestInit): Promise<ListDeliveryOrders200> => {
+  
+  return potatoFetch<ListDeliveryOrders200>(getListDeliveryOrdersUrl(),
+  {      
+    ...options,
+    method: 'GET'
+    
+    
+  }
+);}
+
+
+
 export const getListProjectsUrl = (params?: ListProjectsParams,) => {
   const normalizedParams = new URLSearchParams();
 

package/openapi/gen/models/baseModel.ts

@@ -6,4 +6,5 @@ export interface BaseModel {
   provider: string;
   upstreamModel: string;
   upstreamRevision: string;
+  upstreamUrl: string;
 }

package/openapi/gen/models/checkReport.ts

@@ -3,5 +3,6 @@ import type { CheckReportAnyOfSix } from './checkReportAnyOfSix';
 import type { CheckReportAnyOfOnezero } from './checkReportAnyOfOnezero';
 import type { CheckReportAnyOfTwoone } from './checkReportAnyOfTwoone';
 import type { CheckReportAnyOfTwofive } from './checkReportAnyOfTwofive';
+import type { CheckReportAnyOfTwoseven } from './checkReportAnyOfTwoseven';
 
-export type CheckReport = CheckReportAnyOf | CheckReportAnyOfSix | CheckReportAnyOfOnezero | CheckReportAnyOfTwoone | CheckReportAnyOfTwofive;
+export type CheckReport = CheckReportAnyOf | CheckReportAnyOfSix | CheckReportAnyOfOnezero | CheckReportAnyOfTwoone | CheckReportAnyOfTwofive | CheckReportAnyOfTwoseven;

package/openapi/gen/models/checkReportAnyOfTwoseven.ts

@@ -0,0 +1,5 @@
+import type { CheckReportAnyOfTwosevenResultsItem } from './checkReportAnyOfTwosevenResultsItem';
+
+export type CheckReportAnyOfTwoseven = {
+  results: CheckReportAnyOfTwosevenResultsItem[];
+};

package/openapi/gen/models/checkReportAnyOfTwosevenResultsItem.ts

@@ -0,0 +1,6 @@
+import type { CheckReportAnyOfTwosevenResultsItemVerdict } from './checkReportAnyOfTwosevenResultsItemVerdict';
+
+export type CheckReportAnyOfTwosevenResultsItem = {
+  criterionId: string;
+  verdict: CheckReportAnyOfTwosevenResultsItemVerdict;
+};

package/openapi/gen/models/checkReportAnyOfTwosevenResultsItemVerdict.ts

@@ -0,0 +1,2 @@
+
+export type CheckReportAnyOfTwosevenResultsItemVerdict = 'pass' | 'fail' | 'unable_to_process' | 'incorrect_data' | 'jsonpath_error' | 'error' | 'skipped';

package/openapi/gen/models/currentUser.ts

@@ -1,6 +1,9 @@
 import type { CurrentUserEmail } from './currentUserEmail';
+import type { CurrentUserTeamsItem } from './currentUserTeamsItem';
 
 export interface CurrentUser {
   id: string;
   email: CurrentUserEmail;
+  internal: boolean;
+  teams: CurrentUserTeamsItem[];
 }

package/openapi/gen/models/currentUserTeamsItem.ts

@@ -0,0 +1,6 @@
+
+export type CurrentUserTeamsItem = {
+  id: string;
+  writable: boolean;
+  internal: boolean;
+};

package/openapi/gen/models/deliveryOrder.ts

@@ -0,0 +1,9 @@
+import type { DeliveryOrderClientName } from './deliveryOrderClientName';
+
+export interface DeliveryOrder {
+  id: string;
+  name: string;
+  mondayId: string;
+  status: string;
+  clientName: DeliveryOrderClientName;
+}

package/openapi/gen/models/deliveryOrderClientName.ts

@@ -0,0 +1,2 @@
+
+export type DeliveryOrderClientName = string | null;

package/openapi/gen/models/getTrainingRunMetricHistoryParams.ts

@@ -0,0 +1,4 @@
+
+export type GetTrainingRunMetricHistoryParams = {
+resolution?: number;
+};

package/openapi/gen/models/gistingTrainingConfiguration.ts

@@ -1,6 +1,7 @@
 import type { TrainingModelSource } from './trainingModelSource';
 import type { TrainingDatasetSelection } from './trainingDatasetSelection';
-import type { GistingTrainingConfigurationRegime } from './gistingTrainingConfigurationRegime';
+import type { GistingTrainingConfigurationGistTokens } from './gistingTrainingConfigurationGistTokens';
+import type { GistingTrainingConfigurationBatchSize } from './gistingTrainingConfigurationBatchSize';
 
 export interface GistingTrainingConfiguration {
   method: 'gisting';
@@ -8,6 +9,9 @@ export interface GistingTrainingConfiguration {
   training: TrainingDatasetSelection;
   validation?: TrainingDatasetSelection;
   promptFileId: string;
-  regime: GistingTrainingConfigurationRegime;
+  gistTokens: GistingTrainingConfigurationGistTokens;
   epochs: number;
+  learningRate: number;
+  batchSize: GistingTrainingConfigurationBatchSize;
+  maxSequenceLength: number;
 }

package/openapi/gen/models/gistingTrainingConfigurationBatchSize.ts

@@ -0,0 +1,2 @@
+
+export type GistingTrainingConfigurationBatchSize = 8 | 16 | 32 | 64;

package/openapi/gen/models/gistingTrainingConfigurationGistTokens.ts

@@ -0,0 +1,2 @@
+
+export type GistingTrainingConfigurationGistTokens = 8 | 32 | 64;

package/openapi/gen/models/gistingTrainingConfigurationInput.ts

@@ -1,6 +1,7 @@
 import type { TrainingModelSource } from './trainingModelSource';
 import type { TrainingDatasetSelectionInput } from './trainingDatasetSelectionInput';
-import type { GistingTrainingConfigurationInputRegime } from './gistingTrainingConfigurationInputRegime';
+import type { GistingTrainingConfigurationInputGistTokens } from './gistingTrainingConfigurationInputGistTokens';
+import type { GistingTrainingConfigurationInputBatchSize } from './gistingTrainingConfigurationInputBatchSize';
 
 export interface GistingTrainingConfigurationInput {
   method: 'gisting';
@@ -8,6 +9,9 @@ export interface GistingTrainingConfigurationInput {
   training: TrainingDatasetSelectionInput;
   validation?: TrainingDatasetSelectionInput;
   promptFileId: string;
-  regime?: GistingTrainingConfigurationInputRegime;
+  gistTokens?: GistingTrainingConfigurationInputGistTokens;
   epochs?: number;
+  learningRate?: number;
+  batchSize?: GistingTrainingConfigurationInputBatchSize;
+  maxSequenceLength?: number;
 }

package/openapi/gen/models/gistingTrainingConfigurationInputBatchSize.ts

@@ -0,0 +1,2 @@
+
+export type GistingTrainingConfigurationInputBatchSize = 8 | 16 | 32 | 64;

package/openapi/gen/models/gistingTrainingConfigurationInputGistTokens.ts

@@ -0,0 +1,2 @@
+
+export type GistingTrainingConfigurationInputGistTokens = 8 | 32 | 64;