@toloka-platform/sdk 0.11.2 → 0.11.3

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

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

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-2e9290a8e04d18db2dd275be6fc273d15459a67f6b1f98d27aebf1c6bdfd7fa1  toloka.js
+a038b95e14fe030c3d9b59182799dc89f8c76fd501fe42036831ea3d1daa27c5  toloka.js

package/docs/authoring.md

@@ -225,7 +225,7 @@ A quorum node **requires** an `onboarding` block: the Training course is part of
 
 ### match
 
-Predicate routing. Conditions are evaluated in declaration order.
+Predicate routing. Conditions are evaluated in declaration order. A condition's `logic` defaults to `'and'`, so every predicate must match; set `logic: 'or'` when any one predicate should match. `match()` writes the default into the graph, as the platform stores it, so `toloka plan` does not report the condition as changed after an apply.
 
 ```ts
 import { match } from "@toloka-platform/sdk";
@@ -284,7 +284,9 @@ export default definePipeline({
 });
 ```
 
-`dataset` names the source dataset. `plan` creates it if it is absent and records the resolved id in `toloka.json`.
+`dataset` names the source dataset. `apply` creates it if it is absent, binds it to the pipeline, and records the resolved id in `toloka.json`.
+
+Leave `dataset` out for a pipeline that has no dataset yet, such as one created from a template in the platform UI. `plan` and `apply` then edit its graph without binding a dataset, and `toloka import` writes such a pipeline the same way. The pipeline cannot run until it has a dataset: add `dataset` to its source later, or bind one in the platform UI and import again. Apply never removes a bound dataset, so it refuses to apply a source that drops `dataset` from a pipeline that has one.
 
 Each `pipelines/<name>/pipeline.ts` is one pipeline. A project can hold several; each names its own dataset, and a dataset can be shared.
 
@@ -296,7 +298,7 @@ Constructors mint deterministic ids from the node name, so authored source needs
 
 `toloka import` emits explicit `{ id }` options for nodes and fields that already exist on the platform. **Preserve them.** They are how reconciliation recognizes the same resource instead of replacing it.
 
-Never hand-write `fp_…`, `ds.…`, `pl.…`, or `pp.…` values into settings, and never author a `layout` block: layout is not authored, existing layout is preserved, and the server supplies defaults.
+Never hand-write `fp_…`, `ds.…`, `pl.…`, or `pp.…` values into settings, and never author a `layout` block: layout is not authored, existing nodes keep their canvas position, and the server places new nodes one column after their rightmost input and moves End to the right when they reach it.
 
 ## Validate
 
@@ -305,7 +307,7 @@ toloka check
 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.
+`definePipeline` and the typed ports add local declaration and connection invariants. `toloka check` also reports, as warnings, the platform rules that would reject a node connected to the root: node names, unique quality elements, quality-criterion thresholds, the minimum task and Human QA review times, a positive price per task, a media upload component on a human `data_collection` node, and the limits of an enabled exam. `toloka apply` refuses to write a new or changed pipeline that breaks them, before any platform write; an unchanged pipeline, such as a draft saved in the platform UI, does not block apply of the others. `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 also runs the local entity checks described under [generation](#generation) and makes no network call.
 

package/docs/cli.md

@@ -178,6 +178,16 @@ toloka audience specialization list [--json]
 
 Lists every expert specialization (platform qualification) with `ID`, `NAME`, and `EXPERTS` columns, sorted by name. Copy `ID` into `qualificationId` and `NAME` into `value` of `audience.specializations.values[]`; never invent a `qualificationId`. `EXPERTS` is the number of ID-verified experts currently eligible for tasks who hold the specialization; it can be `0` while the id is still valid. Pass `--json` for the full array. Empty output is `No specializations available.`
 
+## generation-model
+
+Inspect the global, read-only catalog of models a synthetic `generation` node can use.
+
+```sh
+toloka generation-model list [--json]
+```
+
+Prints one row per model and reasoning effort with `ID`, `NAME`, `REASONING EFFORT`, `TYPICAL`, `MIN`, and `MAX` columns, then the default and recommended models. Copy `ID` into `generationModelId`. A `-` in `REASONING EFFORT` means the model does not support `reasoningEffort`; leave it unset there. `MIN` and `MAX` bound the `maxCostPerAttempt` apply accepts; a budget below `TYPICAL` is accepted with a warning because generation can stop before the result is complete. `--json` adds each model's description. Empty output is `No generation models available.`
+
 ## login
 
 Signs in through the browser, or stores an API key, after verifying access.
@@ -250,27 +260,33 @@ Generates TypeScript source from a live project.
 toloka import [projectId] [-f]
 ```
 
-When `projectId` is omitted, the selected project is imported. If `pipelines/` already exists, the command exits with `Folder already exists: <path>. Pass --force to replace it.` Pass `-f` or `--force` to replace that directory. On success it prints `Imported project <projectId> with N pipelines and M datasets into <root>.`
+When `projectId` is omitted, the selected project is imported. If `pipelines/` already exists, the command exits with `Folder already exists: <path>. Pass --force to replace it.` Pass `-f` or `--force` to replace that directory. On success it prints `Imported project <projectId> with N pipelines and M datasets into <root>.` A pipeline without a dataset is written without `dataset` in its `definePipeline`.
+
+The generated nodes keep every stored check case, including cases of the retired `ui` and `llmqa` types. A check type with no cases is left out, and a node whose check types are all empty gets no `checks` at all. `plan` and `apply` treat a check type that source leaves out as unmanaged: they neither report nor remove the cases the platform has for it, so set a type to an empty array to remove its cases.
+
+A field whose JSON Schema is stored on the platform as invalid JSON or as an unsupported schema, for example after an unfinished edit in the UI, is imported as `field("name", invalidJsonSchema({ field, reason, text }))` with the stored text. Loading the source then fails with `Field "<name>" has an unreadable JSON Schema on the platform.` until you replace the call with a valid JSON Schema object; the next `apply` writes that schema and repairs the field.
 
 ## plan
 
 Shows what `apply` would change.
 
 ```sh
-toloka plan
+toloka plan [--json]
 ```
 
-On success it prints `No changes.` when the platform matches source, otherwise `Plan: N changes` followed by one line per change. The plan also lists missing project secrets and dataset field schema conflicts so you can resolve them before applying.
+On success it prints `No changes.` when the platform matches source, otherwise `Plan: N changes` followed by one line per change. The plan also lists missing project secrets and dataset field schema conflicts so you can resolve them before applying. `--json` prints `{ "changes": [...], "missingSecrets": [...] }` instead, where each change has `kind`, `action`, `label`, and, when they apply, `pipeline`, `dataset`, and `id`.
 
 ## validate
 
 Runs platform spec validation for each bound pipeline and reports the latest matching check jobs. Does not write the graph.
 
 ```sh
-toloka validate
+toloka validate [--wait]
 ```
 
-On success it prints one line per pipeline: `valid`, `invalid` with issue details, or `skipped` when the pipeline is not on the platform yet. Exits `1` when any submitted graph is invalid.
+It prints one line per pipeline with its status, then its issues: `valid`; `invalid`; `checks-pending` when only check state is open, such as a stored test case or a lint that has not run on this graph; `checks-running` when `--wait` gave up on running checks; or `skipped` when the pipeline or its dataset is not on the platform yet. A `note:` line explains what to do next when `--wait` could not finish. Exits `1` when any submitted graph is invalid or its checks were still running at the `--wait` deadline.
+
+The platform lints a pipeline a few seconds after every apply. While a lint or a check is running, or a lint is about to start after an apply, validate lists it as `running running_node_check`; a lint that has not run on this graph and is no longer expected to start is `pending not_ran_node_check`, and the user runs it from the node's Checks tab. `--wait` validates again every 5 seconds until nothing is running, for up to 5 minutes, then prints the final report; a pipeline whose source differs from the applied graph is not waited on, because its lints start only after `toloka apply`. Right after an apply, plain `toloka validate` can print `valid` and exit `0` while lints are still running, so run `toloka validate --wait` before treating an applied pipeline as valid.
 
 ## check
 
@@ -280,7 +296,7 @@ Runs the complete local gate without platform credentials.
 toloka check [pipeline] [--node <name-or-id>] [--json] [--watch]
 ```
 
-The command loads authored source, runs the project's TypeScript compiler, typechecks every Task UI against declarations bundled with the installed SDK, runs Vitest, and compares passing typed test evidence with every code node, human-work node, and pipeline. Statuses distinguish `missing`, `failed`, `partial`, and `infrastructure_error`. Exit code `0` means all required checks passed, `1` means source, types, tests, or required coverage failed, and `2` means a required checker could not run.
+The command loads authored source, runs the project's TypeScript compiler, typechecks every Task UI against declarations bundled with the installed SDK, runs Vitest, and compares passing typed test evidence with every code node, human-work node, and pipeline. Statuses distinguish `missing`, `failed`, `partial`, `warning`, and `infrastructure_error`. `partial` marks a Task UI whose upload or recording fields the headless browser could not exercise; it is reported but does not fail the gate. `warning` marks a `platform-rules` result: nodes connected to the root that break a rule the platform enforces on write. It does not fail the gate, but `toloka apply` refuses to write that pipeline until it is fixed. Exit code `0` means all required checks passed, `1` means source, types, tests, or required coverage failed, and `2` means a required checker could not run.
 
 Use `test.code`, `test.ui`, and `test.pipeline` from `@toloka-platform/sdk/testing` to produce required evidence. Plain Vitest tests still run and can fail the command, but do not satisfy graph coverage. A focused check accepts a pipeline plus `--node`; `--watch` serializes reruns after relevant file changes.
 
@@ -288,7 +304,7 @@ With `--watch`, the command prints one complete report after each serialized run
 
 ## apply
 
-Runs the complete Local Check Gate, then makes the platform match source.
+Runs the complete local gate, then makes the platform match source. It takes no options and never asks for confirmation.
 
 ```sh
 toloka apply
@@ -426,7 +442,7 @@ Inspect the Task UI components the launcher renders. The command opens the launc
 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.
+Without names it prints one line per public component (`name: description When to use: …`). 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
 
@@ -464,7 +480,7 @@ An unknown command exits 1 before anything else runs, even when `--help` is pres
 
 ## 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.
+Treat the TypeScript source as authoritative. The canonical sequence is: run the complete local gate, validate against the platform, plan, apply, validate again once the platform lints finish, then plan again to confirm convergence.
 
 ```sh
 # 1. Run source, type, and typed test checks
@@ -479,11 +495,14 @@ toloka plan
 # 4. Apply only when the plan matches the intent
 toloka apply
 
-# 5. Confirm the platform matches source
+# 5. Wait for the platform lints that start after apply
+toloka validate --wait
+
+# 6. Confirm the platform matches source
 toloka plan  # expect: No changes.
 ```
 
-`toloka apply` reruns the complete local gate before resolving credentials. `toloka validate` posts each authored graph to `POST /pipelines/:pipelineId/graph/validate`; it reports platform spec validation and the latest matching Remote Node Check jobs without writing the graph. Resolve every unexpected plan change, missing secret, and immutable-field conflict before applying.
+`toloka apply` reruns the complete local gate before resolving credentials. `toloka validate` posts each authored graph to `POST /pipelines/:pipelineId/graph/validate`; it reports platform spec validation and the latest matching check runs without writing the graph. Resolve every unexpected plan change, missing secret, and immutable-field conflict before applying.
 
 ## Further reading
 

package/docs/limitations.md

@@ -19,7 +19,7 @@ The standalone CLI supports macOS and glibc Linux on ARM64 and x64. Native Windo
 | Training course content, when Training is enabled | platform validation  | nothing                |
 | labeler UI validation receipt                     | platform validation  | nothing                |
 
-The typed client can list, start, and poll Remote Node Checks. `toloka check` does not start them: it validates the authored source and its local tests. A `not_ran_node_check` result from `toloka validate` describes remote state rather than missing local evidence. Its severity is check-specific: lint checks report a blocking error, while other checks can report a warning.
+The typed client can list, start, and poll Remote Node Checks. `toloka check` does not start them: it validates the authored source and its local tests. A `not_ran_node_check` or `running_node_check` warning from `toloka validate` describes remote state rather than missing local evidence.
 
 Python code nodes have executable behavior checks but no useful static Python typecheck yet. Their generated `Inputs` and `Outputs` aliases are currently `dict[str, Any]`; adding Pyright or mypy before those aliases become field-derived `TypedDict` contracts would provide little protection.
 
@@ -27,7 +27,7 @@ The standalone CLI's runtime does not provide project test dependencies. Executa
 
 ## Layout is not authored
 
-Node canvas positions are not part of authored source. Existing layout is preserved across applies and the server supplies defaults for new nodes. You cannot lay out a graph from code.
+Node canvas positions are not part of authored source. Existing nodes keep their canvas position across applies. The server places a new node one column to the right of its rightmost input, below any node already in that spot, and moves End to the right when new nodes reach it. You cannot lay out a graph from code.
 
 ## One checkout targets one project
 

package/docs/testing.md

@@ -17,7 +17,7 @@ bun add -d vitest playwright
 bunx playwright install chromium
 ```
 
-Executable code-node tests also require `python3` on the test machine, including any third-party Python packages imported by the authored program. Browser-backed Task UI tests use the separately downloaded Playwright Chromium binary and require network access to the hosted launcher. Training-only CLI workflows require none of these project test tools or a separate JavaScript runtime. See [testing examples](./testing-examples.md) for parameterization, validation failures, hardware coverage, and cleanup patterns.
+Executable code-node tests also require `python3` on the test machine. The platform runs code nodes on Python 3.12 with the standard library only, so a program that imports a package installed only on the test machine passes locally and fails on the platform. Browser-backed Task UI tests use the separately downloaded Playwright Chromium binary and require network access to the hosted launcher. Training-only CLI workflows require none of these project test tools or a separate JavaScript runtime. See [testing examples](./testing-examples.md) for parameterization, validation failures, hardware coverage, and cleanup patterns.
 
 ## Test a code node
 
@@ -110,6 +110,8 @@ Valid JavaScript: `items.map((item) => item.value)`
 
 Invalid runtime JavaScript: `items.map((item: unknown) => item.value)`
 
+Only `data` is in scope in `preprocess` and `postprocess`. `CONST` exists only in `ui.code`, so `toloka check` reports `Cannot find name 'CONST'` when either function reads it: write the value inline in the function, or read it from `ui.code` instead.
+
 `preprocess` can run again after form state changes. Use it to shape input data; if it prefills a bound field, return that key only while it is absent so later edits are not overwritten. A `Field`-bound top-level key already enters the submission. `postprocess` must return only new top-level keys: bind a component to a draft key when postprocess must derive a different entity key.
 
 The fixture loads the hosted TBX launcher in a fresh local Chromium context, so tests require network access but do not use Azure Playwright or Potato application services. The context has no platform cookies or credentials. Use synthetic or redacted fixtures because the hosted launcher executes with access to the supplied test data.
@@ -120,4 +122,4 @@ File pickers, video upload/recording, and other hardware-backed fields cannot be
 
 ## Final gate
 
-`toloka check` loads every authored pipeline, runs the project TypeScript compiler, typechecks every Task UI against declarations bundled with the installed SDK, runs Vitest, and requires passing `test.code`, `test.ui`, and `test.pipeline` evidence. `missing`, `failed`, `partial`, and `infrastructure_error` are distinct blocking outcomes. `toloka apply` reruns this complete gate before resolving credentials or writing platform state. Platform validation remains separate: a `not_ran_node_check` describes Remote Node Check state rather than missing local evidence, but lint checks report it as a blocking remote error while other checks can report it as a warning.
+`toloka check` loads every authored pipeline, runs the project TypeScript compiler, typechecks every Task UI against declarations bundled with the installed SDK, runs Vitest, and requires passing `test.code`, `test.ui`, and `test.pipeline` evidence. `missing`, `failed`, and `infrastructure_error` are distinct blocking outcomes. `partial` is reported for a Task UI with hardware-backed fields and does not block: verify those fields on a real device before launching a run. `toloka apply` reruns this complete gate before resolving credentials or writing platform state. Platform validation remains separate: a `not_ran_node_check` warning describes Remote Node Check state rather than missing local evidence.

package/examples/README.md

@@ -0,0 +1,11 @@
+# Examples
+
+Complete pipeline projects to borrow structure from. Each directory has a README and a `pipeline.browser.integration.spec.ts` with its typed tests. Borrow the patterns, not the task-specific choices: design the graph, entities, criteria, and Task UI for the task at hand.
+
+| example                        | read it for                                                                                                                                                     |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `product-moderation`           | **start here for a show-an-item, collect-a-judgment task**: one human `generation` node that shows an image and text and collects a label, a subcategory, and a rationale; label lists shared by fields and UI; variants for synthetic generation and several experts |
+| `face-image-collection`        | a human image-annotation node followed by a code node; a structured array output                                                                                |
+| `video-pair-rating`            | side-by-side rating with a `quorum`, deterministic code cascades over rater arrays, `match` routing with `default` branches, and human adjudication             |
+| `egocentric-video-collection`  | data collection with a recording field, a category label driven by one constant list, LLM QA with one criterion per concern, Training with quizzes, stored checks |
+| `app-crowdtesting`             | data collection with an upload field plus structured metadata answers, a step-by-step screen with long text in `ui.constants`, contributor diversity via the per-expert cap |

package/examples/app-crowdtesting/README.md

@@ -0,0 +1,41 @@
+# App crowdtesting
+
+A crowdtesting data-collection pipeline: each tester installs a pre-release Android build on their own phone, screen-records a full session through the app's key flows, uploads the recording, and reports their device model and Android version. An LLM reviews every submission against quality criteria before it is accepted.
+
+The task content is built around a fictional app, Acme Fitness. To adopt it, replace the app everywhere it appears: the install link, node description and public name, entity descriptions, every quality criterion, the instruction, the Task UI constants, and the Training steps and quiz.
+
+## Shape
+
+```
+root.started (item_id)
+  └─> app_flow_test   generation  a tester installs, records, uploads, and describes the device
+      └─> root.completed (app_test_video, device_model, os_version)
+```
+
+Two nodes: one root and one `data_collection` `generation`. Each dataset row is one recording slot; `item_id` carries no task content, so the number of rows is the number of recordings.
+
+## What to read first
+
+| file                                   | why                                                                       |
+| -------------------------------------- | ------------------------------------------------------------------------- |
+| `nodes/app-flow-test/node.ts`          | the whole task: entities, criteria, instruction, Task UI, and Training    |
+| `fields.ts`                            | a scalar video field fed from a single upload, plus two free-text answers |
+| `pipeline.browser.integration.spec.ts` | how to drive an upload component in a headless UI scenario                |
+
+## Patterns this example demonstrates
+
+**One upload is one entity.** `Field.VideoUpload` always produces an array, but a tester submits one recording. The output field is a scalar URI, the entity is static, and its `jsonPath` selects `$.app_test_video[0].sasLink`, matching the component's `linkType={'sasLink'}` (the contract's recommended link type; `downloadLink` may be inaccessible to end users). Duration bounds are set on both the entity and the component, and they agree.
+
+**Structured metadata next to the upload.** Device model and OS version are separate `SHORT_ANSWER` outputs related to the recording, each with a `required` rule and its own `max` length rule, and each with a criterion that rejects placeholders.
+
+**A step-by-step screen.** The Task UI stacks install, record, and upload as three cards in the order the tester works. Long markdown and the install link live in `ui.constants` and are read as `CONST.*`, so `ui.code` needs no nested template literals and the install link is declared once for both the instruction and the screen.
+
+**LLM QA judges what is visible.** Criteria count attempted flow runs and required screens by on-screen text, never by which control was tapped, and a captured crash counts as a completed run rather than a failure.
+
+**Training that matches the task.** Three steps, ending in a quiz on the rules that most often fail a recording: when to start recording, how many runs each flow needs, and what to do when the app crashes.
+
+**Contributor diversity.** An unverified English-speaking crowd with a per-expert cap of 1, so every recording comes from a different person and device.
+
+## Check locally
+
+Upload and recording controls are hardware-backed, and headless Chromium cannot pick, capture, or upload a file. The UI scenario renders with `allowPartialCoverage: true`, sets the upload value from the component's documented example output, and asserts that coverage is incomplete. It verifies browser validation and the output mapping, not the upload itself, so `toloka check` reports this node as `partial`.

package/examples/app-crowdtesting/fields.ts

@@ -0,0 +1,6 @@
+import { field } from "@toloka-platform/sdk";
+
+export const itemId = field("item_id", { type: "number" });
+export const appTestVideo = field("app_test_video", { type: "string", format: "uri" });
+export const deviceModel = field("device_model", { type: "string" });
+export const osVersion = field("os_version", { type: "string" });