@toloka-platform/sdk 0.2.0 → 0.3.0

package/skills/toloka-build/references/workflow-and-cli.md

@@ -28,47 +28,69 @@ Treat the three layers differently:
 
 For a first-time guided session, consult `https://platform.toloka.ai/agents/data-labeling.md` for orientation. Adapt the journey to the user's goal and already-complete setup while preserving dependencies, cost approval, and identity/source protection; use this reference for command details.
 
-Install the SDK before invoking project commands:
+Bun is the recommended runtime and package manager for pipeline authoring. In an existing source root, install its declared dependencies:
 
 ```sh
-bun add --dev @toloka-platform/sdk@latest
+bun i
+```
+
+For a new pipeline project, add the SDK, TypeScript, and Vitest:
+
+```sh
+bun add -d @toloka-platform/sdk@latest typescript vitest
+```
+
+These are project authoring and test dependencies, not prerequisites for running the standalone CLI or a Training-only workflow. Task UI scenarios additionally require Playwright and Chromium:
+
+```sh
+bun add -d playwright
+bunx playwright install chromium
 ```
 
 Select or create the intended platform project before `toloka init` when the checkout should be bound immediately; follow the adoption or scratch recipe below. Running `init` without explicit or checkout-local project identity installs only the agent entry points and never adopts the machine registry's current project.
 
-`toloka init` checks that `@toloka-platform/sdk` is declared in `dependencies` or `devDependencies`, then maintains one `<toloka>` Agent Bootstrap block in `AGENTS.md` and writes minimal pointers to it: a Claude skill at `.claude/skills/toloka-bootstrap/SKILL.md` when `.claude/` exists (or when no agent configuration exists at all) and an always-applied Cursor rule at `.cursor/rules/toloka-bootstrap.mdc` when `.cursor/rules/` exists. It writes `toloka.json` only from an explicit project flag/environment value or an existing checkout binding.
+`toloka init` warns when `@toloka-platform/sdk` is not declared in `dependencies` or `devDependencies`, then maintains one `<toloka>` Agent Bootstrap block in `AGENTS.md` and writes minimal pointers to it: a Claude skill at `.claude/skills/toloka-bootstrap/SKILL.md` when `.claude/` exists (or when no agent configuration exists at all) and an always-applied Cursor rule at `.cursor/rules/toloka-bootstrap.mdc` when `.cursor/rules/` exists. The dependency warning applies to pipeline authoring; Training commands do not require the SDK dependency. `init` writes `toloka.json` only from an explicit project flag/environment value or an existing checkout binding.
 
-The bootstrap is small: it tells an agent to run `toloka --help`, search the bundled Skill Catalog with `toloka skill search <query>`, install the match with `toloka skill install <skill-id>`, and read `.agents/skills/<skill-id>/SKILL.md`. This skill is that installed copy. Commands warn on stderr when a generated legacy entry point is still present or the recorded bootstrap version differs from the installed SDK. Help, `init`, `report`, `project url`, `config`, and version invocations skip this checkout-dependent warning. The warning never blocks a command; re-run `toloka init` to refresh the bootstrap and its pointers.
+The bootstrap is small: it tells an agent to run `toloka --help`, search the bundled Skill Catalog with `toloka skill search <query>`, install the match with `toloka skill install <skill-id>`, and read `.agents/skills/<skill-id>/SKILL.md`. This skill is that installed copy. Commands warn on stderr when a generated legacy entry point is still present or the recorded bootstrap version differs from the running CLI's bundled version, independently of any project SDK dependency. Help, `init`, `report`, `project url`, `config`, and version invocations skip this checkout-dependent warning. The warning never blocks a command; after updating the standalone CLI, re-run `toloka init` to refresh the bootstrap and its pointers.
 
-## Store credentials once
+## Sign in once
 
 ```sh
 toloka login
 ```
 
-It explains where to generate an API key — `console.toloka.ai` → Company → API Keys → Generate API Key
-— reads the key without echoing it, verifies it by listing one project, and only then saves the
-credentials file with mode `0600`. Nothing is written when the key does not authenticate.
-
-Most later commands read that file, so `--api-key` becomes optional. For networked commands that do
-not mutate the machine project registry, key precedence is flag, then `TOLOKA_API_KEY`, then the
-stored file; CI can use an environment variable without running login. Non-interactive callers can
-skip the login prompt by piping the key to `toloka login --api-key-stdin`; `toloka login --api-key <key>`
-also works but leaves the key in shell history. The base URL defaults to the platform.
+It asks whether to sign in through the browser or with an API key. The browser choice opens a page in
+the browser where the user continues with Google or Microsoft (testing environments also offer email
+and password and the testing users), hands them to the Toloka login page, waits for the sign-in to finish, verifies access by
+listing one project, and only then saves the browser session under `~/.toloka/cli/credentials/` with
+mode `0600`. Nothing is written when the platform does not accept the account. The session renews
+itself for up to 14 days; after that `toloka login` is needed again. Run `toloka login --browser` yourself
+by default: it skips the question, opens the sign-in page in the user's browser, and waits for them to
+finish; without a terminal it fails fast when no browser can be opened. `toloka login --no-browser` prints
+the link instead of opening a browser.
+
+The API key choice does not expire: the key works until it is deleted in the Business Console, which
+suits scripts, CI, and coding agents. Type it at the masked prompt, or pipe it to `toloka login --api-key-stdin`.
+`toloka login --api-key <key>` also works but leaves the key in shell history. Most later commands read the stored login, so
+`--api-key` becomes optional. For networked commands that do not mutate the machine project registry,
+credential precedence is flag, then `TOLOKA_API_KEY`, then the stored API key, then the browser
+session; CI can use an environment variable without running login. The base URL defaults to the platform.
 
 ```sh
 toloka auth-status     # or toloka whoami
 toloka logout
 ```
 
-`auth-status` reports which platform and key are in effect and where each came from, masks the key
-unless you pass `--show-token`, and exits non-zero on failure — use it to check a setup rather than
-guessing. Its last lines say which failure it was: `Rejected:` means the platform refused the key
-(run `toloka login` with a working one); `Not reachable:` means the platform did not answer, so the
-key was not evaluated (fix network access, do not ask for a new key); `Platform error:` means the
-platform failed (retry later). `logout` deletes the stored file; it does not revoke the key.
+`auth-status` reports which platform and login are in effect and where each came from and exits
+non-zero on failure — use it to check a setup rather than guessing. It masks the credential; `--show-token`
+prints the full API key or the browser session's live access token, so pass it only when a command
+genuinely needs the raw value and never paste the output into chat. Its last lines say which failure it was: `Rejected:` means the platform refused the login
+(run `toloka login` again); `Not reachable:` means the platform did not answer, so the login was not
+evaluated (fix network access, do not ask for a new login); `Platform error:` means the platform
+failed (retry later). `logout` ends every stored browser session and deletes the stored files; it does not
+revoke an API key.
 
-A globally installed `toloka` auto-updates by default. It checks npm at most once per day and installs a newer `@toloka-platform/sdk` only after that version has been published for at least 24 hours, then re-runs the original command. `config`, `version`, and `help` never trigger a check. Project-local installs and CI skip it. Turn it off with `toloka config set auto-update false`.
+Standalone and Bun-global `toloka` installations check the public npm registry at most once per day and install eligible releases at least 24 hours old before rerunning the command. Project-local installs, CI, and `config`, `version`, and `help` skip the check. Turn it off with `toloka config set auto-update false`. For manual standalone updates, rerun `curl -fsSL https://platform.toloka.ai/cli/install.sh | sh -s -- --native`; Bun-global updates should use `--bun` instead. Preserve the mode and put any original `TOLOKA_CLI_INSTALL_DIR`, `TOLOKA_CLI_CHANNEL`, `TOLOKA_CLI_PACKAGE`, and `TOLOKA_CLI_REGISTRY` overrides on the `sh` side of the pipe again. A package version pin does not disable automatic updates, which always use the public npm registry.
 
 ## Configure the CLI
 
@@ -90,7 +112,7 @@ The real command surface is:
 toloka version [--json]
 toloka -v
 toloka --version
-toloka login
+toloka login [--browser] [--no-browser] [--api-key-stdin]
 toloka logout
 toloka auth-status
 toloka config
@@ -105,6 +127,7 @@ toloka project remove <alias>
 toloka project create [alias] [--name <name>] [--team-id <id>] [--delivery-order-id <id>]
 toloka project untrack <pipeline|dataset> <name> [--confirm]
 toloka delivery-order list
+toloka audience specialization list [--json]
 toloka init
 toloka import [projectId]
 toloka check [pipeline] [--node <name-or-id>] [--json] [--watch]
@@ -134,8 +157,8 @@ toloka model create <name> --base <base-model-id> [--description <text>] [--json
 toloka model archive <name-or-id> [--json]
 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 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|1/4|1/8|1/16|1/32] [--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|1/4|1/8|1/16|1/32] [--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]
@@ -156,6 +179,8 @@ Resolve the intended platform project before `import`, `plan`, or `apply`; use a
 
 `toloka project url` prints only the selected project's platform UI URL. Use it when the user needs a working link to inspect the live project.
 
+`toloka audience specialization list` prints the global specialization catalog: `ID`, `NAME`, and `EXPERTS` columns sorted by name (`--json` for the array). Run it before setting `audience.specializations` on a node, pick entries by name, and copy `ID` into `qualificationId` and `NAME` into `value`; never invent a `qualificationId`. `EXPERTS` counts ID-verified experts currently eligible for tasks; a `0` means the id is valid but nobody currently qualifies, so prefer another specialization or widen the audience.
+
 `toloka pipeline cost [name] [--item-limit <n>]` forecasts what a run of a live, validated pipeline would bill. It does not start a run or change the graph. If any billed node is marked `skipped`, the displayed total is incomplete and must not be presented as the pipeline price. Compute and label a labor floor for each skipped billed node as `items × pricePerTask × annotations per item`, using `1` for generation and `overlap` for quorum. Also report `maxEntities`, quality-criteria count, and only exclusions applicable to the authored QA and workflow. Apply accepting a rate does not prove its final billed value.
 
 ## Manage model checkpoints
@@ -166,7 +191,7 @@ The global Base Model Catalog is read-only and uses `toloka base-model`. `base-m
 
 `toloka training create` requires one source (`--base-model` or `--model-version`) and a training Dataset. A `--model-version` source must be a LoRA adapter Model Version (one produced by fine-tuning) and works for both methods — SFT continues the adapter, gisting merges it and trains gist tokens over it; a full-weights version is rejected with "Training from a Model Version requires a LoRA adapter source". The first Training Run creates a new output Model named after the Training; a source Model Version is only the training parent, never the output binding.
 
-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.
+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` (default 32) is gisting-only — passing one to the other method fails before any request. `--gist-tokens` takes an absolute count `8|32|64` or a fraction of the prompt being compressed (`1/4`, `1/8`, `1/16`, `1/32`), which the run resolves to `ceil(prompt tokens / N)` clamped to 8..256. `--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.
 
 Use `training cost` to validate inputs and show the maximum charge before `training run`. A blocked estimate exits 1 and lists the issues on stderr instead of printing the estimate; fix them and recalculate. `training run` accepts that ready estimate JSON through `--estimate-file`; without it, the command calculates a fresh ready estimate itself before creating the run. `--version-name` defaults to the Training name; pass it when a Model Version with that name already exists. Use `training status`, `training logs`, `training metrics`, `training resume`, and `training cancel` with the returned Training Run ID. `training metrics` lists each metric's latest value while the run is still training; `--key` prints one metric's point history instead.
 

package/skills/toloka-fine-tuning/SKILL.md

@@ -39,10 +39,9 @@ For first-time setup details, read `https://platform.toloka.ai/agents/fine-tunin
 
 ### 1. Establish only the context the goal needs
 
-When runtime, authentication, or binding is unknown, inspect it:
+When the CLI, authentication, or binding is unknown, inspect it. The runtime-inclusive standalone CLI is sufficient for Training-only work; no separate Bun or Node.js installation, SDK, TypeScript, or test packages are needed:
 
 ```sh
-bun --version
 toloka --version
 toloka whoami
 toloka project current
@@ -145,6 +144,8 @@ toloka training metrics <training-run-id> --json
 
 Resume only after the user confirms a billing block is resolved. Cancel only on explicit request.
 
+A run can train longer than the estimate predicted. It stays `running`, the charge stays capped at the approved `maximumCharge`, and the Model Version publishes when training finishes; treat a slow run as still running, not as failed, and do not start a duplicate run for it. A run that ends `failed` with error code `provider_failed` or `provider_timeout` is a platform-side failure: it is charged nothing and the whole hold returns to the team balance, while its reported GPU seconds stay visible; a run the user cancels during training is charged for the GPU seconds used.
+
 For a completed run, verify the observed output and download only when requested:
 
 ```sh

package/skills/toloka-get-started/SKILL.md

@@ -19,10 +19,11 @@ The workflow sequence preserves important dependencies and gates, but it is not
 
 ## Prepare missing prerequisites
 
-Check the runtime or CLI only when its state is not already known:
+Check the CLI only when its state is not already known. The installer prefers stable Bun 1.4.0 or newer matching the host architecture; otherwise it installs a standalone executable with its runtime included. Use `sh -s -- --native` or `sh -s -- --bun` on the installer pipe to force a mode. For custom packages or directories, choose the matching mode explicitly. Training-only workflows need no project SDK or test dependencies. For pipeline authoring, Bun is recommended: run `bun i` in an existing project and use `bun add -d` for missing packages.
+
+The shell installer supports macOS and Linux on ARM64/x64. The native path requires glibc on Linux, plus `curl`, `tar`, `mktemp`, and either `shasum` or `sha256sum`; compatible Bun can be used on musl. Native Windows packages are not available.
 
 ```sh
-bun --version
 toloka --version
 toloka dataset --help
 ```
@@ -39,7 +40,7 @@ Never request an API key in chat. Inspect the active identity with:
 toloka whoami
 ```
 
-If the reachable account is evidently the intended identity from the request, project, team, or established checkout, continue and report it. Ask a focused question when the identity conflicts with that context or more than one material choice remains. For a missing or rejected key, ask the user to run `toloka login`, then verify `toloka whoami` again. `Rejected:` means the key was refused; `Not reachable:` means the platform did not answer and the key was not evaluated, so fix network access rather than requesting another key; `Platform error:` means the platform failed, so retry later.
+If the reachable account is evidently the intended identity from the request, project, team, or established checkout, continue and report it. Ask a focused question when the identity conflicts with that context or more than one material choice remains. For a missing, expired, or rejected login, run `toloka login --browser` yourself: it opens the sign-in page in the user's browser and waits, so ask the user to finish signing in there, then verify `toloka whoami` again. `Rejected:` means the login was refused; `Not reachable:` means the platform did not answer and the login was not evaluated, so fix network access rather than requesting another sign-in; `Platform error:` means the platform failed, so retry later.
 
 Pipeline work needs a source root. Reuse a suitable initialized root when one exists. In a new root, or when the Agent Bootstrap or installed skills genuinely need initialization or refresh, use:
 

package/skills/toloka-gisting/SKILL.md

@@ -40,10 +40,9 @@ For first-time setup details, read `https://platform.toloka.ai/agents/gisting.md
 
 ### 1. Establish only the context the goal needs
 
-When runtime, authentication, or binding is unknown, inspect it:
+When the CLI, authentication, or binding is unknown, inspect it. The runtime-inclusive standalone CLI is sufficient for Training-only work; no separate Bun or Node.js installation, SDK, TypeScript, or test packages are needed:
 
 ```sh
-bun --version
 toloka --version
 toloka whoami
 toloka project current
@@ -115,7 +114,7 @@ toloka training create "<training-name>" \
 
 Omit `--validation-dataset` when no separate validation selection exists so the provider uses its 10% holdout. For disjoint selections in a Dataset with top-level fields, add `--train-filter <field>=<value>` and `--validation-filter <field>=<value>`.
 
-Preserve requested hyperparameters. The current CLI uses `--gist-tokens 8|32|64` (default 32), `--epochs 1..5` (default 3), `--learning-rate` within 0.001–0.3 (default 0.03), `--batch-size 8|16|32|64` (default 8), and `--max-sequence-length 64..16384` (default 3072), rather than `regime`. Use defaults when suitable; 8 gist tokens favor compression for simple prompts, while 64 may help when 32 loses holdout accuracy. Choose sequence length from actual examples within the supported limit. `--lora-rank` is rejected for gisting. `training update <name-or-id>` takes the same flags except `--method`; omitted flags retain current values.
+Preserve requested hyperparameters. The current CLI uses `--gist-tokens` (default 32), `--epochs 1..5` (default 3), `--learning-rate` within 0.001–0.3 (default 0.03), `--batch-size 8|16|32|64` (default 8), and `--max-sequence-length 64..16384` (default 3072), rather than `regime`. Use defaults when suitable. `--gist-tokens` takes an absolute count `8|32|64` or a fraction of the prompt being compressed — `1/4`, `1/8`, `1/16`, `1/32`. An absolute count fixes the soft-prompt size: 8 favors compression for simple prompts, while 64 may help when 32 loses holdout accuracy. A fraction fixes the compression ratio instead — the run resolves it to `ceil(prompt tokens / N)` and clamps it to 8..256 — so prefer one for a long prompt or a prompt whose length changes between drafts, starting at `1/32`. `training get` reports the fraction you set, not the count it resolved to. Choose sequence length from actual examples within the supported limit. `--lora-rank` is rejected for gisting. `training update <name-or-id>` takes the same flags except `--method`; omitted flags retain current values.
 
 Verify the saved method, exact source, prompt file, selections, filters, and configuration with `toloka training get <training-id> --json`.
 
@@ -154,6 +153,8 @@ toloka training metrics <training-run-id> --json
 
 Resume only after the user confirms a billing block is resolved. Cancel only on explicit request.
 
+A run can train longer than the estimate predicted. It stays `running`, the charge stays capped at the approved `maximumCharge`, and the Model Version publishes when training finishes; treat a slow run as still running, not as failed, and do not start a duplicate run for it. A run that ends `failed` with error code `provider_failed` or `provider_timeout` is a platform-side failure: it is charged nothing and the whole hold returns to the team balance, while its reported GPU seconds stay visible; a run the user cancels during training is charged for the GPU seconds used.
+
 For a completed run, verify the observed output and download only when requested:
 
 ```sh

package/skills/toloka-report-issue/references/report-template.md

@@ -26,7 +26,7 @@ The CLI exits 1 with `Potato API request failed with status 500`. The same comma
 
 ## Environment
 
-- toloka CLI 0.2.0 (`toloka --version`), Bun 1.4.0, macOS 15
+- Toloka CLI: native 0.2.0, build a1b2c3d4e5f6 (`toloka version --json`); macOS 15
 - Platform: https://platform.toloka.ai
 
 ## Redactions

package/src/checks/task-ui-typecheck.ts

@@ -10,7 +10,10 @@ import {
   createVirtualTypeScriptEnvironment,
 } from "./typescript-vfs.js";
 
-const tsLibDirectory = path.dirname(ts.getDefaultLibFilePath({ target: ts.ScriptTarget.Latest }));
+const tsLibDirectory =
+  Reflect.get(globalThis, "Bun")?.isStandaloneExecutable === true
+    ? path.join(path.dirname(process.argv[1]!), "typescript-lib")
+    : path.dirname(ts.getDefaultLibFilePath({ target: ts.ScriptTarget.Latest }));
 
 const BLOCK_MARKERS = {
   data: "DATA_INJECTION",

package/src/cli/analytics.ts

@@ -93,6 +93,7 @@ const COMMAND_GROUPS: Readonly<Record<string, CommandGroup>> = {
   },
   dataset: { list: true, create: true, fields: true, load: true, upload: true },
   "delivery-order": { list: true },
+  audience: { specialization: { list: true } },
   training: {
     list: true,
     get: true,

package/src/cli/audience.ts

@@ -0,0 +1,31 @@
+import type { PotatoClient } from "../client";
+import type { Specialization } from "../../openapi/gen/models";
+import { formatTable, type TableIo, writeOutput } from "./table";
+
+type AudienceApi = Pick<PotatoClient, "audience">;
+
+export const listSpecializations = async (
+  client: AudienceApi,
+  input: { json: boolean },
+  io: TableIo,
+): Promise<void> => {
+  const specializations: Specialization[] = [];
+  for await (const specialization of client.audience.specializations.listAll()) {
+    specializations.push(specialization);
+  }
+  writeOutput(
+    io,
+    input.json,
+    specializations,
+    specializations.length === 0
+      ? "No specializations available."
+      : formatTable([
+          ["ID", "NAME", "EXPERTS"],
+          ...specializations.map((specialization) => [
+            specialization.id,
+            specialization.name,
+            String(specialization.expertsCount),
+          ]),
+        ]),
+  );
+};