@toloka-platform/sdk 0.11.1 → 0.11.2

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

@@ -1 +1 @@
-6a0f8dbdd98f49a9c663bb3051960c4f168961bc4ebd8b428ae75fd5f07ba994  toloka.js.jsc
+1024b0621937fe114806d81e918925d05e4e71ef8c2f6aa209eabbe9aa102e02  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-20b4b75534617c8aed19bf129f8b78fe18d43a5a91221f1aa4bf2fbc0f792175  toloka.js
+2e9290a8e04d18db2dd275be6fc273d15459a67f6b1f98d27aebf1c6bdfd7fa1  toloka.js

package/docs/authoring.md

@@ -99,6 +99,14 @@ Choose entity cardinality from the task, not from the component's JavaScript val
 
 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`.
 
+Entity types and labels are checked locally, for both generation and quorum nodes, before anything is sent to the platform:
+
+- `entityType` on every input and output entity must be one of the platform's core entity types. The list ships with the SDK in `src/core-entity-types.json`, generated from the server schema: `JUDGEMENT`, `EXPLANATION`, `PROMPT`, `USER_PROMPT`, `RESPONSE`, `RESPONSE_EVALUATION`, `RUBRIC`, `RUBRICS_GROUP`, `DIALOG`, `DIALOG_STEP`, `DIALOG_EVALUATION`, `SHORT_ANSWER`, `FEEDBACK`, `CONTEXT`, `IMAGE`, `ANNOTATION`, `SINGLE_LABEL`, `MULTI_LABEL`, `VIDEO`, `DOCUMENT`, `GOLDEN_SET`, `LOGS`, `SOLUTION`, `CODE`, `METADATA`, `AUDIO`, `AGENT_TRAJECTORY`, `MCP_SERVER`, `CONTAINER`, `CUSTOM`.
+- An output entity of type `SINGLE_LABEL` or `MULTI_LABEL` needs `allowedLabels` with at least two entries.
+- Every label `value` must be snake_case (`first_video`, not `firstVideo` or `First Video`).
+
+A violation is thrown as `PipelineGraphValidationError`, with one issue per offending path, as soon as the pipeline source is loaded — so `toloka check`, `toloka plan`, `toloka apply` and `toloka validate` all fail on it locally before any platform request.
+
 The following task is legitimately dynamic because the labeler can draw one independent box for every visible face:
 
 ```ts
@@ -299,7 +307,7 @@ toloka validate
 
 `definePipeline` and the typed ports add local declaration and connection invariants. `toloka validate` posts each bound pipeline to `POST /pipelines/:pipelineId/graph/validate` and reports platform spec errors, warnings, and the latest matching check jobs. It does not write the graph.
 
-A pipeline that is not on the platform yet is skipped until `toloka apply` creates it. The published JSON contract is still available as `validate(graph)` for importer and fixture tests; that helper makes no network call.
+A pipeline that is not on the platform yet is skipped until `toloka apply` creates it. The published JSON contract is still available as `validate(graph)` for importer and fixture tests; that helper also runs the local entity checks described under [generation](#generation) and makes no network call.
 
 A successful validate is necessary, not sufficient for launch. Gates outside the graph contract — an underpriced audience, a Training course that is enabled but unbuilt, a task UI that was never validated — can still block deployment. See [limitations](./limitations.md).
 

package/docs/cli.md

@@ -56,14 +56,15 @@ If both installations exist, put the desired directory first on `PATH`, run `has
 
 ## Configuration
 
-Credentials and the platform base URL resolve from the same precedence order, highest first.
+Credentials and the platform base URL resolve independently. Credentials use this precedence, highest first.
 
 | Precedence  | Credential source                                |
 | ----------- | ------------------------------------------------ |
 | 1 (highest) | `--api-key` flag                                 |
-| 2           | `TOLOKA_API_KEY` environment variable            |
-| 3           | API key stored by `toloka login --api-key-stdin` |
-| 4 (lowest)  | browser session stored by `toloka login`         |
+| 2           | `TOLOKA_SCOPED_TOKEN` environment variable       |
+| 3           | `TOLOKA_API_KEY` environment variable            |
+| 4           | API key stored by `toloka login --api-key-stdin` |
+| 5 (lowest)  | browser session stored by `toloka login`         |
 
 | Precedence  | Base URL source                         |
 | ----------- | --------------------------------------- |
@@ -81,6 +82,8 @@ Credentials and the platform base URL resolve from the same precedence order, hi
 
 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 aliases remain supported for compatibility; rename them to silence the warning and use the current names in new automation.
 
+`TOLOKA_SCOPED_TOKEN` always sends its value in `X-Scoped-Token`, so it supports both issued `pst_…` tokens and secret placeholders such as `dtn_secret_…`. The `--api-key` and `TOLOKA_API_KEY` slots continue to recognize the `pst_` prefix for backward compatibility. Use the explicit scoped-token variable for new agent and CI configuration.
+
 `toloka login` verifies access against the platform before saving anything. A browser login is saved as a session file under `$TOLOKA_CLI_CREDENTIALS_DIR`, which defaults to `~/.toloka/cli/credentials/<auth-host>/<realm>/<client>.json`. When `TOLOKA_CREDENTIALS_FILE` points at an explicit credentials file, sessions go to a `browser-sessions` directory next to it instead, so that profile stays isolated. The platform choice, a stored API key, and local project aliases live in `$XDG_CONFIG_HOME/toloka/credentials.json`, which defaults to `~/.config/toloka/credentials.json`. Both are written with file mode `0600` in directories with mode `0700`. The legacy `~/.toloka/credentials.json` is still read when the new path has no file. `toloka logout` ends the browser session and deletes both files; it does not revoke an API key.
 
 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).
@@ -190,7 +193,7 @@ By default the command asks whether to sign in through the browser or with an AP
 
 Browser login is available for `https://platform.toloka.ai` and the `*.platform.toloka-test.ai` environments. Without a terminal the command opens the chooser page directly and fails fast when no browser can be opened; automation uses an API key instead.
 
-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. Choosing it asks for the key with masked input; `--api-key-stdin` reads it from standard input instead, 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. Platforms without a known login service go straight to the API key prompt. The command verifies the key and prints `Authenticated against <base-url> with an API key`, then the number of projects visible, where the key is stored, and a reminder that the key does not expire until you delete it in the Business Console.
+The API key choice does not expire: the key works until it is deleted in the Business Console, which suits scripts and CI. Choosing it asks for the key with masked input; `--api-key-stdin` reads it from standard input instead, 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. For an already-issued project-scoped token, set `TOLOKA_SCOPED_TOKEN` for the command instead of storing it with `login`. Platforms without a known login service go straight to the API key prompt. The command verifies the key and prints `Authenticated against <base-url> with an API key`, then the number of projects visible, where the key is stored, and a reminder that the key does not expire until you delete it in the Business Console.
 
 ## logout
 
@@ -210,7 +213,7 @@ Shows which platform and login the CLI would use. Alias: `whoami`.
 toloka auth-status [--show-token]
 ```
 
-On success it prints the platform URL with its source, then either the masked API key or a `Login:` line for the browser session and a `Session:` line with the current refresh window, then the selected project, `Reachable: N project(s) visible.`, `Account:` with the email the platform reports, `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. `--show-token` prints the full API key or the browser session's live access token instead of the mask; pass it only when you need the raw value on this terminal. It exits `1` when no login is in effect, when the browser session has expired, when the platform rejects the login (`Rejected: …`, followed by the advice to run `toloka login`), when the platform does not answer (`Not reachable: …`; the login was not evaluated), or when the platform fails (`Platform error: …`).
+On success it prints the platform URL with its source, then either the masked API key, the masked scoped token with `from TOLOKA_SCOPED_TOKEN`, or a `Login:` line for the browser session and a `Session:` line with the current refresh window. It then prints the selected project, `Reachable: N project(s) visible.`, `Account:` with the email the platform reports, `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. `--show-token` prints the full active credential instead of the mask; pass it only when you need the raw value on this terminal. It exits `1` when no login is in effect, when the browser session has expired, when the platform rejects the credential, or when the platform cannot be reached.
 
 ## config
 
@@ -415,6 +418,16 @@ In a terminal the command asks `Send this report to Toloka? [y/N]`; outside a te
 
 One `sdk_cli_issue_report_submitted` event carries `report_id`, the complete `report_text`, its UTF-8 `report_length_bytes`, `authored_by`, and `platform`, plus the standard pseudonymous CLI telemetry context. The command never reads or sends an API key. It flushes PostHog before printing `Submitted issue report: <id>`; a delivery failure exits non-zero and prints no success ID. When CLI telemetry is disabled, issue reporting is unavailable rather than bypassing that preference.
 
+## ui
+
+Inspect the Task UI components the launcher renders. The command opens the launcher in a headless Chromium (Playwright from the project's `node_modules`), so it needs the same local setup as `toloka check` and no credentials.
+
+```sh
+toloka ui components [names...] [--json]
+```
+
+Without names it prints one line per public component (`name: description`). With names it prints each component's description, when to use it, capabilities, limitations, best practices, the `propsType` contract, the value shape, and the documented JSX example with its output. An unknown name fails with `Unknown Task UI components: <name>`. `--json` prints the same contracts keyed by component name. The output always reflects the currently deployed launcher, so run it instead of guessing component names or props from memory.
+
 ## skill
 
 Discover bundled agent skills and install them into the project. The Skill Catalog ships inside the SDK package, so these actions are local and deterministic: they need no credentials, make no network requests, and change with the package version only.

package/docs/getting-started.md

@@ -37,7 +37,7 @@ The session renews itself for up to 14 days; after that, run `toloka login` agai
 toloka whoami
 ```
 
-CI does not need `login`. Set `TOLOKA_API_KEY` and the stored login is ignored; an agent without a terminal can pipe a key to `toloka login --api-key-stdin`. See the precedence table in the [CLI reference](./cli.md).
+CI does not need `login`. Set `TOLOKA_API_KEY` for a long-lived API key or `TOLOKA_SCOPED_TOKEN` for an issued project-scoped token, and the stored login is ignored; an agent without a terminal can pipe a long-lived key to `toloka login --api-key-stdin`. See the precedence table in the [CLI reference](./cli.md).
 
 ## Start with an agent
 

package/docs/testing.md

@@ -83,7 +83,7 @@ Use an ordinary TypeScript loop to register several `test.code` or `test.ui` sce
 
 The low-level `ui` fixture remains available inside ordinary Vitest tests for component discovery and exploratory work, but plain tests do not satisfy required node coverage. Use typed wrappers for committed gate evidence. Importing `@toloka-platform/sdk/testing` from a plain Bun script executes Vitest fixture setup and fails.
 
-- `ui.componentDocumentation(names?)` returns the current launcher's supported component contracts. Call it before choosing component names or props.
+- `ui.componentDocumentation(names?)` returns the current launcher's supported component contracts. `ui` is a fixture argument of `test` (`test("…", async ({ ui }) => …)`), not an export. Outside a test, `toloka ui components [names...]` prints the same contracts.
 - `ui.render(pipeline, node, options)` creates a fresh browser context and returns a Task UI session for exactly that authored node. `test.ui` supplies the equivalent bound `render(options?)` helper.
 
 The returned Task UI session supports:

package/docs/troubleshooting.md

@@ -96,7 +96,7 @@ toloka pipeline results <runId> --failed
 Not logged in. Run toloka login once to sign in through your browser on this machine:
 ```
 
-Run `toloka login`. Where a browser is not available, pipe an API key to `toloka login --api-key-stdin` or set `TOLOKA_API_KEY`. `toloka whoami` reports which platform and which login source is in effect, and exits non-zero when the platform is unreachable.
+Run `toloka login`. Where a browser is not available, pipe a long-lived API key to `toloka login --api-key-stdin` or set `TOLOKA_API_KEY`; set `TOLOKA_SCOPED_TOKEN` when using an issued project-scoped token. `toloka whoami` reports which platform and which credential source is in effect, and exits non-zero when the platform is unreachable.
 
 ## The browser login expired
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toloka-platform/sdk",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "private": false,
   "description": "Build, inspect, and operate Toloka pipeline projects as TypeScript source. The public API may change between minor versions before 1.0.",
   "license": "Apache-2.0",
@@ -77,6 +77,6 @@
     "bun": ">=1.4.0"
   },
   "tolokaBuild": {
-    "commit": "62d9c4558758f7409b65de7c849c8a2e8d15ba9a"
+    "commit": "33545324d935ee7d0e9da6f845c03b25ae49759f"
   }
 }

package/skills/catalog.json

@@ -11,8 +11,8 @@
         "testing",
         "checks"
       ],
-      "version": "0.11.1",
-      "digest": "79283e8ca89ddafa3d6206be108db32046f6941fb52d4b622aec72c20b791de7",
+      "version": "0.11.2",
+      "digest": "f97f94dd6eff745884e07d9f19cc414fdc2fe5d9b7992e062e7beb0058dcce59",
       "files": [
         "SKILL.md",
         "references/node-semantics.md",
@@ -29,7 +29,7 @@
         "bug",
         "report"
       ],
-      "version": "0.11.1",
+      "version": "0.11.2",
       "digest": "70f0bd2c80b32f87896aeb27c363b8a2d37f40e22424f57fe1aad142e125ad67",
       "files": [
         "SKILL.md",
@@ -46,7 +46,7 @@
         "getting-started",
         "agent"
       ],
-      "version": "0.11.1",
+      "version": "0.11.2",
       "digest": "ccf148c682de4e452bb031db95d3933257899006b1766f0fdbc3d15265a63bb9",
       "files": [
         "SKILL.md"
@@ -63,7 +63,7 @@
         "sft",
         "models"
       ],
-      "version": "0.11.1",
+      "version": "0.11.2",
       "digest": "279c69977eef170dada20b664ee0c30858681e84a2cabb2fdff18b8bb1bdc055",
       "files": [
         "SKILL.md"
@@ -80,7 +80,7 @@
         "prompt",
         "models"
       ],
-      "version": "0.11.1",
+      "version": "0.11.2",
       "digest": "b9f314eb6b39754bc8d2ae79aca3dc680fced5f14948c975d1e084a83c2e0a8c",
       "files": [
         "SKILL.md"

package/skills/toloka-build/SKILL.md

@@ -80,6 +80,7 @@ Distinguish server requirements from optional design choices. The following cons
 - **Training is part of the node, not extra.** A quorum node requires `onboarding`, and while it is enabled the platform wants at least three steps and at least one quiz block. Preserve an explicit `enabled: false` that a user or `toloka import` put there; never switch Training on to satisfy your own sense of completeness.
 - **Optional settings should serve the task.** Exams, non-default QA, audience reuse, and smart search can be useful when the requirements call for them. Omit blocks that add no value rather than copying placeholders; an empty disabled block is still authored state. Preserve imported choices unless changing them is part of the task, and explain additions that affect cost or expert eligibility.
 - **Run scope belongs to the platform.** `itemFilter` and `itemLimit` on the root node are set from the platform, and apply preserves whatever is live unless source declares its own value. Do not add an item limit to source to "restore" one you saw in the UI.
+- **Entities use a closed vocabulary, and label entities need choices.** `entityType` must be one of the platform core types listed in [node semantics](references/node-semantics.md): `CONTEXT` for any non-media input the expert reads (text, numbers, objects), `IMAGE`/`VIDEO`/`AUDIO`/`DOCUMENT` for media inputs, `SINGLE_LABEL` or `MULTI_LABEL` for fixed choices, `SHORT_ANSWER` or `RESPONSE` for produced text, `EXPLANATION` only for reasoning about another value. Never invent `TEXT`, `LABEL`, or another name. Every `SINGLE_LABEL`/`MULTI_LABEL` output needs `allowedLabels` with at least two `{ label, value }` entries whose `value` is snake_case. The SDK checks these when it loads the source, so `toloka check` (and `toloka plan`, `toloka apply`, `toloka validate`) fails locally with `PipelineGraphValidationError` before any platform request; read the reference before writing a node instead of discovering them from a failed check.
 
 ## Know the validation boundary
 
@@ -89,7 +90,7 @@ Distinguish server requirements from optional design choices. The following cons
 
 `toloka validate` posts each bound graph to the platform. Treat source/spec errors as blocking and warnings as informational. A `not_ran_node_check` concerns a separate Remote Node Check and does not replace a passing Local Check Gate, but its remote-validation severity still matters: lint checks report it as a blocking error while other checks can report it as a warning. A pipeline not yet on the platform is skipped until `toloka apply` creates it. When a reviewed plan adds a dataset field already bound by an existing live pipeline, pre-apply validation can report that exact field as missing; apply only the reviewed additive plan, then require post-apply validation to clear source/spec errors. Never rewrite valid source for a missing Remote Node Check.
 
-Before choosing Task UI components, call `ui.componentDocumentation()` from a local `@toloka-platform/sdk/testing` scenario. A component's usable contract is the returned `propsType` plus its returned `valueType` and `example`; shared `Field` props such as `path`, `label`, `hint`, and `validation` can be confirmed from any current `Field.*` example, but do not invent any other prop. For structured or array-valued Fields, derive the dataset field schema from `valueType`, then feed the documented example value through `setValue`, `getValue`, and `submit` in the UI scenario so upstream contract drift fails locally. Never translate undocumented property names or replace missing values with defaults. Every identifier in `ui.code` must be a returned component or documented `actions` API, and JSX must have one root element. Register each required UI scenario with `test.ui(pipeline, node, name, callback)` and submit through its bound `render` helper. Run `toloka check <pipeline> --node <name-or-id>` after every Task UI edit; require passing UI types, empty browser validation errors, valid postprocessed entity output, and visual inspection where relevant. Never weaken authored validation merely to make a test pass.
+Before choosing Task UI components, list them from the launcher with `toloka ui components` (one line per component) and read the contract of the ones you intend to use with `toloka ui components <name> [name...]`; never guess component names or props from memory. If this SDK version has no `ui` command, the same data comes from the `ui` fixture of the `test` exported by `@toloka-platform/sdk/testing` (`ui` is a fixture argument, not an export): write a throwaway `probe.spec.ts` with `test("components", async ({ ui }) => { console.log(JSON.stringify(await ui.componentDocumentation(["View.Image"]), null, 2)); });`, run `bunx vitest run probe.spec.ts`, and delete the file before `toloka check`. A component's usable contract is the returned `propsType` plus its returned `valueType` and `example`; shared `Field` props such as `path`, `label`, `hint`, and `validation` can be confirmed from any current `Field.*` example, but do not invent any other prop. For structured or array-valued Fields, derive the dataset field schema from `valueType`, then feed the documented example value through `setValue`, `getValue`, and `submit` in the UI scenario so upstream contract drift fails locally. Never translate undocumented property names or replace missing values with defaults. Every identifier in `ui.code` must be a returned component or documented `actions` API, and JSX must have one root element. Register each required UI scenario with `test.ui(pipeline, node, name, callback)` and submit through its bound `render` helper. Run `toloka check <pipeline> --node <name-or-id>` after every Task UI edit; require passing UI types, empty browser validation errors, valid postprocessed entity output, and visual inspection where relevant. Never weaken authored validation merely to make a test pass.
 
 `ui.code` accepts TSX, including TypeScript annotations. `preprocess` and `postprocess` are JavaScript function bodies; do not put TypeScript-only syntax in either transform.
 
@@ -104,8 +105,9 @@ Register code behavior with `test.code(pipeline, node, name, callback)` and exec
 
 `toloka login` signs the user in through the browser, or stores an API key when they choose that, and
 keeps the login with owner-only permissions, so no later command needs `--api-key`. Precedence is flag,
-then environment variable (`TOLOKA_API_KEY`, `TOLOKA_BASE_URL`), then the stored API key, then the
-browser session. `toloka auth-status` reports what is in effect and where it came from; `toloka logout`
+then environment variable (`TOLOKA_SCOPED_TOKEN`, then `TOLOKA_API_KEY`; `TOLOKA_BASE_URL`), then the
+stored API key, then the browser session. `TOLOKA_SCOPED_TOKEN` is a project-scoped token minted for the
+user by the platform (for example inside an agent sandbox); it never grants more than that user has. `toloka auth-status` reports what is in effect and where it came from; `toloka logout`
 ends the browser session and removes the stored files. If credentials are missing, run `toloka login --browser`
 yourself: it opens the sign-in page in the user's browser and waits, so ask the user to pick their
 provider and finish signing in there. Never request a key in chat.

package/skills/toloka-build/references/node-semantics.md

@@ -142,11 +142,11 @@ An authored entity references a declared `field`. Choose its cardinality from th
 - One logical result from one labeler is static. A caption, verdict, rating, recording, or upload remains one entity even when its value is an object or a component holds it in an array. Omit `dynamic` and `maxEntities`, and use a `jsonPath` without `[*]`.
 - Multiple independent results from one labeler are dynamic. Examples include one box per visible face and one defect record per discovered defect. Set `dynamic: true`, use exactly one `[*]` in `jsonPath`, and set `maxEntities` to the tightest upper bound justified by the task. Never use 50 as an unexamined default.
 - Do not choose `dynamic` from a TypeScript or JSON container shape. Ask whether the task expects one logical result or a repeated collection; the answer owns the entity model.
-- Use `allowedLabels: [{ label, value }]` for fixed choices. Use `SINGLE_LABEL` for exactly one stored value and `MULTI_LABEL` for multiple values.
+- Use `allowedLabels: [{ label, value }]` for fixed choices. Use `SINGLE_LABEL` for exactly one stored value and `MULTI_LABEL` for multiple values. Every `SINGLE_LABEL`/`MULTI_LABEL` output needs at least two entries, and each `value` must be snake_case.
 - Set media duration bounds only when the expert produces the media through an upload or recording output. Input media used for annotation does not require duration bounds.
 - Give every output entity at least one relation to the input it uses: `{ field, rel_type: 'context' | 'references' | 'depends_on' | 'evaluates' }`, or a conditional relation supported by the public type.
 
-`entityType` is a closed platform vocabulary even where a generated TypeScript shape is currently broad. Use `CONTEXT` for any non-media input the expert reads, including text, numbers, and objects. Use `SHORT_ANSWER` for short produced text, `RESPONSE` for long produced text, and `EXPLANATION` only for reasoning about another value. Use `SINGLE_LABEL` or `MULTI_LABEL` for fixed choices and the matching media or annotation type for those values. Never invent `TEXT` or another natural-language type name; consult the documented vocabulary when these categories do not fit.
+`entityType` is a closed platform vocabulary even where a generated TypeScript shape is currently broad. Use `CONTEXT` for any non-media input the expert reads, including text, numbers, and objects. Use `SHORT_ANSWER` for short produced text, `RESPONSE` for long produced text, and `EXPLANATION` only for reasoning about another value. Use `SINGLE_LABEL` or `MULTI_LABEL` for fixed choices and the matching media or annotation type for those values. Never invent `TEXT` or another natural-language type name; consult the documented vocabulary when these categories do not fit. The full vocabulary, generated from the server schema into the SDK's `core-entity-types.json`, is `JUDGEMENT`, `EXPLANATION`, `PROMPT`, `USER_PROMPT`, `RESPONSE`, `RESPONSE_EVALUATION`, `RUBRIC`, `RUBRICS_GROUP`, `DIALOG`, `DIALOG_STEP`, `DIALOG_EVALUATION`, `SHORT_ANSWER`, `FEEDBACK`, `CONTEXT`, `IMAGE`, `ANNOTATION`, `SINGLE_LABEL`, `MULTI_LABEL`, `VIDEO`, `DOCUMENT`, `GOLDEN_SET`, `LOGS`, `SOLUTION`, `CODE`, `METADATA`, `AUDIO`, `AGENT_TRAJECTORY`, `MCP_SERVER`, `CONTAINER`, `CUSTOM`. The SDK validates `entityType` and the `allowedLabels` rules when it loads the source, so `toloka check` fails locally with `PipelineGraphValidationError` before anything is sent to the platform.
 
 Entities enforce format, not meaning. Put types, ranges, cardinality, requiredness, and labels in the field schema and entity. Put accuracy, correctness, completeness, and clarity in quality criteria.
 

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

@@ -73,8 +73,10 @@ The API key choice does not expire: the key works until it is deleted in the Bus
 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.
+credential precedence is flag, then `TOLOKA_SCOPED_TOKEN`, then `TOLOKA_API_KEY`, then the stored API key,
+then the browser session; CI can use an environment variable without running login. A scoped token is
+minted by the platform for one user and one project (agent sandboxes receive it in `TOLOKA_SCOPED_TOKEN`);
+it cannot issue further tokens and expires on its own. The base URL defaults to the platform.
 
 ```sh
 toloka auth-status     # or toloka whoami
@@ -100,8 +102,8 @@ A scoped token downloads project files in two steps: a request to `ProjectFile.u
 
 ## Configure the CLI
 
-Provide the API key and base URL on networked workflows through `TOLOKA_API_KEY` and
-`TOLOKA_BASE_URL`, or with `--api-key` and `--base-url`. A base URL with a path (a gateway such as
+Provide the credential and base URL on networked workflows through `TOLOKA_SCOPED_TOKEN` or
+`TOLOKA_API_KEY` and `TOLOKA_BASE_URL`, or with `--api-key` and `--base-url`. A base URL with a path (a gateway such as
 `https://gateway.example/ss/pp.1`) keeps that path on every request, with or without a trailing
 slash; use the given URL unchanged. The registry-mutating commands
 `toloka project add`, `toloka project switch`, `toloka project remove`, and `toloka project create`
@@ -273,7 +275,7 @@ Apply preserves existing live layout and the root's live item filter. Do not add
 
 Register every code-node behavior with `test.code(pipeline, node, name, callback)`. Its callback receives a bound `run(inputs, options?)` helper with the same Python execution contract as `runCodeNode`; the test counts only after the bound executor runs, an assertion executes, and the callback passes.
 
-Before choosing component names or props, call `ui.componentDocumentation()` in a local `@toloka-platform/sdk/testing` scenario. A component's contract is its returned `propsType`, `valueType`, and `example`. For structured or array-valued Fields, derive the dataset field schema from `valueType`, then feed the documented example value through `setValue`, `getValue`, and `submit`; never translate undocumented property names or replace missing values with defaults. Register required human-work behavior with `test.ui(pipeline, node, name, callback)`. Its callback receives bound `render(options?)`; the test counts only after a successful `submit`, at least one assertion, and a passing callback.
+Before choosing component names or props, run `toloka ui components` to list the launcher's components and `toloka ui components <name> [name...]` for their contracts (on an SDK without the `ui` command, use the `ui` fixture argument of `test` from `@toloka-platform/sdk/testing` in a throwaway spec and delete it afterwards). A component's contract is its returned `propsType`, `valueType`, and `example`. For structured or array-valued Fields, derive the dataset field schema from `valueType`, then feed the documented example value through `setValue`, `getValue`, and `submit`; never translate undocumented property names or replace missing values with defaults. Register required human-work behavior with `test.ui(pipeline, node, name, callback)`. Its callback receives bound `render(options?)`; the test counts only after a successful `submit`, at least one assertion, and a passing callback.
 
 Register representative connected flows with `test.pipeline(pipeline, name, callback)`. Choose fixtures from available data that exercise the task, redacting sensitive values while preserving field names, nesting, optionality, and media/value shapes. Use synthetic cases for privacy or boundaries absent from the sample. Use the callback's bound `runCode` and `renderUi` helpers, merge only declared node outputs, and assert the final `root.completed` fields. Cover meaningful match branches, optional routes, and failures as well as the happy path.
 

package/src/cli/auth.ts

@@ -451,27 +451,47 @@ export type AuthStatusOptions = {
 export type AuthStatusResult = { readonly authenticated: boolean; readonly output: string };
 
 type ResolvedValue = { readonly value: string; readonly source: string };
+type ResolvedCredential = ResolvedValue & {
+  readonly type: "apiKey" | "scopedToken";
+  readonly environmentVariable?: "TOLOKA_SCOPED_TOKEN" | "TOLOKA_API_KEY";
+};
 
-const firstDefined = (
-  candidates: ReadonlyArray<ResolvedValue | undefined>,
-): ResolvedValue | undefined => candidates.find((candidate) => candidate !== undefined);
+const firstDefined = <T>(candidates: ReadonlyArray<T | undefined>): T | undefined =>
+  candidates.find((candidate) => candidate !== undefined);
 
-const resolveStatusApiKey = (
+const resolveStatusCredential = (
   options: AuthStatusOptions,
   environment: CliEnvironment,
   found: FoundCredentials | undefined,
   storedPath: string,
-): ResolvedValue | undefined =>
-  firstDefined([
+): ResolvedCredential | undefined =>
+  firstDefined<ResolvedCredential>([
     options.flagApiKey === undefined
       ? undefined
-      : { value: options.flagApiKey, source: "from --api-key" },
+      : { type: "apiKey", value: options.flagApiKey, source: "from --api-key" },
+    environment.TOLOKA_SCOPED_TOKEN === undefined
+      ? undefined
+      : {
+          type: "scopedToken",
+          value: environment.TOLOKA_SCOPED_TOKEN,
+          source: "from TOLOKA_SCOPED_TOKEN",
+          environmentVariable: "TOLOKA_SCOPED_TOKEN",
+        },
     environment.TOLOKA_API_KEY === undefined
       ? undefined
-      : { value: environment.TOLOKA_API_KEY, source: "from TOLOKA_API_KEY" },
+      : {
+          type: "apiKey",
+          value: environment.TOLOKA_API_KEY,
+          source: "from TOLOKA_API_KEY",
+          environmentVariable: "TOLOKA_API_KEY",
+        },
     found?.credentials.apiKey === undefined
       ? undefined
-      : { value: found.credentials.apiKey, source: `stored in ${storedPath}` },
+      : {
+          type: "apiKey",
+          value: found.credentials.apiKey,
+          source: `stored in ${storedPath}`,
+        },
   ]);
 
 const resolvePlatform = (
@@ -576,17 +596,23 @@ export async function authStatus(options: AuthStatusOptions = {}): Promise<AuthS
   const now = (options.now ?? unixSeconds)();
   const credentialLookup =
     options.credentialLookup ??
-    (await findCommandCredentials(environment, options.flagApiKey ?? environment.TOLOKA_API_KEY));
+    (await findCommandCredentials(
+      environment,
+      options.flagApiKey ??
+        environment.TOLOKA_SCOPED_TOKEN ??
+        environment.TOLOKA_API_KEY,
+    ));
   const { found, warning } = credentialLookup;
   const storedPath = found?.path ?? credentialsPath(environment);
-  const apiKey = resolveStatusApiKey(options, environment, found, storedPath);
+  const credential = resolveStatusCredential(options, environment, found, storedPath);
   const platform = resolvePlatform(options, environment, found);
-  const browser = apiKey === undefined ? await findBrowserLogin(platform.value, environment) : undefined;
+  const browser =
+    credential === undefined ? await findBrowserLogin(platform.value, environment) : undefined;
   const projectLine = formatProjectContextLine(options.project, found?.credentials);
 
   const lines: string[] = warning === undefined ? [] : [warning, ""];
 
-  if (apiKey === undefined && browser === undefined) {
+  if (credential === undefined && browser === undefined) {
     lines.push(
       "Not logged in.",
       "",
@@ -600,11 +626,15 @@ export async function authStatus(options: AuthStatusOptions = {}): Promise<AuthS
   const { value: baseUrl, source: urlSource } = platform;
   lines.push(`Platform: ${baseUrl} (${urlSource})`);
   let clientConfig: ClientConfig;
-  if (apiKey !== undefined) {
+  if (credential !== undefined) {
+    const label = credential.type === "scopedToken" ? "Scoped token:" : "API key: ";
     lines.push(
-      `API key:  ${options.showToken === true ? apiKey.value : maskApiKey(apiKey.value)} (${apiKey.source})`,
+      `${label} ${options.showToken === true ? credential.value : maskApiKey(credential.value)} (${credential.source})`,
     );
-    clientConfig = { baseUrl, apiKey: apiKey.value };
+    clientConfig =
+      credential.type === "scopedToken"
+        ? { baseUrl, scopedToken: credential.value }
+        : { baseUrl, apiKey: credential.value };
   } else {
     assertCli(browser, "No login is in effect.", { hint: { description: "Run toloka login." } });
     const status = await browserStatus(browser, baseUrl, environment, options, now);
@@ -617,8 +647,11 @@ export async function authStatus(options: AuthStatusOptions = {}): Promise<AuthS
   }
   lines.push(projectLine);
 
-  if (environment.TOLOKA_API_KEY !== undefined && found?.credentials.apiKey !== undefined) {
-    lines.push("", `TOLOKA_API_KEY is set, so the key stored in ${found.path} is ignored.`);
+  if (found?.credentials.apiKey !== undefined && credential?.environmentVariable !== undefined) {
+    lines.push(
+      "",
+      `${credential.environmentVariable} is set, so the key stored in ${found.path} is ignored.`,
+    );
   }
   if (found?.legacy === true) {
     lines.push(

package/src/cli/check.ts

@@ -25,7 +25,7 @@ import {
 } from "../testing/test-evidence";
 import { cliRelaunchCommand } from "./cli-entry";
 import { bunSubprocessEnvironment } from "./native-runtime";
-import { API_KEY_ENVIRONMENT_NAMES } from "./environment";
+import { CREDENTIAL_ENVIRONMENT_NAMES } from "./environment";
 import { loadProjectSource, type ProjectSource } from "./source";
 import { assertCli, REPORT_HINT, TolokaCliError } from "./cli-error";
 import type { TolokaCliErrorOptions } from "./cli-error";
@@ -276,13 +276,13 @@ const loadSourceWithoutPlatformCredentials = async (
   environment: NodeJS.ProcessEnv,
 ): Promise<ProjectSource> => {
   const targets = [process.env, environment];
-  const saved = targets.map((current) => API_KEY_ENVIRONMENT_NAMES.map((name) => current[name]));
-  for (const current of targets) for (const name of API_KEY_ENVIRONMENT_NAMES) delete current[name];
+  const saved = targets.map((current) => CREDENTIAL_ENVIRONMENT_NAMES.map((name) => current[name]));
+  for (const current of targets) for (const name of CREDENTIAL_ENVIRONMENT_NAMES) delete current[name];
   try {
     return await loadProjectSource(sourceRoot);
   } finally {
     targets.forEach((current, target) => {
-      API_KEY_ENVIRONMENT_NAMES.forEach((name, index) => {
+      CREDENTIAL_ENVIRONMENT_NAMES.forEach((name, index) => {
         const value = saved[target]?.[index];
         if (value === undefined) delete current[name];
         else current[name] = value;
@@ -693,7 +693,7 @@ export async function checkProject(
   try {
     const selectedPipeline = selected.pipelines.length === 1 ? selected.pipelines[0] : undefined;
     const checkEnvironment = { ...(options.environment ?? process.env) };
-    for (const name of API_KEY_ENVIRONMENT_NAMES) delete checkEnvironment[name];
+    for (const name of CREDENTIAL_ENVIRONMENT_NAMES) delete checkEnvironment[name];
     const environment = {
       ...checkEnvironment,
       [TEST_EVIDENCE_DIR_ENV]: evidenceDirectory,

package/src/cli/commands/auth.ts

@@ -59,13 +59,15 @@ export const registerAuthCommands = (program: Command, host: CommandHost): void
   program
     .command("auth-status")
     .alias("whoami")
-    .description("show which platform and login the CLI would use")
-    .option("--show-token", "print the API key or access token instead of masking it", false)
+    .description("show which platform and credential the CLI would use")
+    .option("--show-token", "print the API key, scoped token, or access token instead of masking it", false)
     .action(async (options: { showToken: boolean }) => {
       const flags = globals();
       const credentialLookup = await findCommandCredentials(
         context.environment,
-        flags.apiKey ?? context.environment.TOLOKA_API_KEY,
+        flags.apiKey ??
+          context.environment.TOLOKA_SCOPED_TOKEN ??
+          context.environment.TOLOKA_API_KEY,
       );
       const stored = credentialLookup.found?.credentials;
       const sourceRoot = await resolveSourceRoot(flags, context.io);

package/src/cli/commands/project.ts

@@ -15,6 +15,7 @@ import { readTolokaState } from "../../state";
 import { assertCli } from "../cli-error";
 import { formatTable } from "../table";
 import type { CreateScopedTokenBodyAnyOfPreset, ScopedTokenSummary } from "../../../openapi/gen/models";
+import { SCOPED_TOKEN_PREFIX } from "../../transport";
 
 const TOKEN_PRESETS: readonly CreateScopedTokenBodyAnyOfPreset[] = [
   "read",
@@ -157,8 +158,12 @@ export const registerProjectCommands = (program: Command, host: CommandHost): vo
         expiresIn?: number;
         projects?: string;
       }) => {
-        const { client, projectId } = await resolveContext(globals(), context);
+        const { client, credential, projectId } = await resolveContext(globals(), context);
         assertProjectSelected(projectId);
+        const usesScopedToken =
+          credential.type === "scopedToken" ||
+          (credential.type === "apiKey" && credential.apiKey.startsWith(SCOPED_TOKEN_PREFIX));
+        assertCli(!usesScopedToken, "A scoped token cannot issue tokens.", { hint: { disabled: true } });
         const scope =
           options.permissions === undefined
             ? { preset: options.preset }
@@ -174,7 +179,7 @@ export const registerProjectCommands = (program: Command, host: CommandHost): vo
             : { projectIds: options.projects.split(",").map((projectId) => projectId.trim()) }),
         });
         context.io.stdout(token);
-        context.io.stderr(`Token expires at ${expiresAt}. Use it as TOLOKA_API_KEY or --api-key.`);
+        context.io.stderr(`Token expires at ${expiresAt}. Use it as TOLOKA_SCOPED_TOKEN.`);
       },
     );
   project

package/src/cli/commands/ui.ts

@@ -0,0 +1,23 @@
+import type { Command } from "commander";
+import { describeTaskUiComponents } from "../../testing/task-ui-browser";
+import { resolveSourceRoot, type CommandHost } from "../context";
+import { uiComponentsCommand } from "../ui";
+
+export const registerUiCommands = (program: Command, host: CommandHost): void => {
+  const { context, globals } = host;
+  const ui = program.command("ui").description("inspect the Task UI components the launcher renders");
+  ui.command("components")
+    .argument("[names...]", "component names such as Field.RadioGroup; omit to list every component")
+    .option("--json", "print the component contracts as JSON", false)
+    .description("list Task UI components, or print the props, value shape, and example of the named ones")
+    .action(async (names: string[], options: { json: boolean }) => {
+      const sourceRoot = await resolveSourceRoot(globals(), context.io);
+      await uiComponentsCommand({
+        sourceRoot,
+        names,
+        json: options.json,
+        io: context.io,
+        describe: context.taskUiComponents ?? describeTaskUiComponents,
+      });
+    });
+};

package/src/cli/config.ts

@@ -12,12 +12,14 @@ export type TolokaCliFlags = {
 
 export type TolokaEnvironment = Readonly<Record<string, string | undefined>> & {
   readonly TOLOKA_API_KEY?: string;
+  readonly TOLOKA_SCOPED_TOKEN?: string;
   readonly TOLOKA_BASE_URL?: string;
   readonly TOLOKA_PROJECT_ID?: string;
 };
 
 export type CliCredential =
   | { readonly type: "apiKey"; readonly apiKey: string }
+  | { readonly type: "scopedToken"; readonly scopedToken: string }
   | { readonly type: "browser"; readonly provider: BrowserLoginProvider };
 
 export type ResolvedTolokaConfig = {
@@ -60,15 +62,22 @@ export const MISSING_CREDENTIALS_MESSAGE = [
   "",
   "  toloka login",
   "",
-  "Automation can pass --api-key, set TOLOKA_API_KEY, or pipe a key to toloka login --api-key-stdin.",
+  "Automation can pass --api-key, set TOLOKA_SCOPED_TOKEN or TOLOKA_API_KEY, or pipe a key to toloka login --api-key-stdin.",
   "Run toloka auth-status to see what is in effect.",
 ].join("\n");
 
-export const resolveApiKey = (
+export const resolveConfiguredCredential = (
   flags: TolokaCliFlags,
   environment: TolokaEnvironment,
   stored?: StoredCredentials,
-): string | undefined => flags.apiKey ?? environment.TOLOKA_API_KEY ?? stored?.apiKey;
+): Exclude<CliCredential, { readonly type: "browser" }> | undefined => {
+  if (flags.apiKey !== undefined) return { type: "apiKey", apiKey: flags.apiKey };
+  if (environment.TOLOKA_SCOPED_TOKEN !== undefined) {
+    return { type: "scopedToken", scopedToken: environment.TOLOKA_SCOPED_TOKEN };
+  }
+  const apiKey = environment.TOLOKA_API_KEY ?? stored?.apiKey;
+  return apiKey === undefined ? undefined : { type: "apiKey", apiKey };
+};
 
 export const resolveBaseUrl = (
   flags: TolokaCliFlags,
@@ -88,7 +97,7 @@ export function resolveTolokaConfig(
   stored?: StoredCredentials,
   browserLogin?: BrowserLoginProvider,
 ): ResolvedTolokaConfig {
-  const apiKey = resolveApiKey(flags, environment, stored);
+  const configuredCredential = resolveConfiguredCredential(flags, environment, stored);
   const baseUrl = resolveBaseUrl(flags, environment, stored);
   const project = resolveProjectContext({
     flags,
@@ -98,11 +107,8 @@ export function resolveTolokaConfig(
     effectiveBaseUrl: baseUrl,
   });
   const credential: CliCredential | undefined =
-    apiKey !== undefined
-      ? { type: "apiKey", apiKey }
-      : browserLogin !== undefined
-        ? { type: "browser", provider: browserLogin }
-        : undefined;
+    configuredCredential ??
+    (browserLogin === undefined ? undefined : { type: "browser", provider: browserLogin });
   assertCli(credential, MISSING_CREDENTIALS_MESSAGE, { hint: { disabled: true } });
   return { baseUrl, credential, ...(project === undefined ? {} : { projectId: project.id }) };
 }