@toloka-platform/sdk 0.1.0-preview.4 → 0.1.0-preview.6

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

@@ -1 +1 @@
-dfdcb0c64d04df834c08b292facaf8edb31aba8a00876f29d6240cd08c9bf378  toloka.js.jsc
+2e4e22afc766a0a267262fe07718505b43f1cdf364e402a990279e224ad92923  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-0e0efdf2d8a9bfacfacd3801a8cd89ceaa80534f262dbf4c9617fc7c22ef822c  toloka.js
+842c3cdfb47d5a899375c288cefa8ba550c22301dbd47d99d224a8b34acd01a2  toloka.js

package/docs/cli-v2.md

@@ -80,6 +80,7 @@ toloka project list                          # remote projects this key can see
 toloka project add cat-labeling pp.019f…     # register + select
 toloka project switch cat-labeling
 toloka project current                       # alias of the project line in whoami
+toloka project url                           # print the selected project's UI URL
 toloka project remove cat-labeling           # local unbind only
 ```
 
@@ -95,6 +96,8 @@ toloka project create cat-labeling --team-id <teamId>
 
 `project create` writes the machine alias, sets `current`, and if cwd has no `toloka.json`, writes one.
 
+UI links follow the resource-first shape `toloka <resource> url`. `project url` is available now; future pipeline, dataset, and other entity links belong under their existing resource groups. Every `url` command prints exactly one URL with no label to stdout. Opening a browser, if added, must be an explicit `--web` option rather than the default.
+
 ### init
 
 `init` sets up **this directory** for an agent. A selected platform project is optional.
@@ -118,6 +121,7 @@ Resource commands never search the disk for a pipeline first. They load the proj
 
 | Command                       | Scope                         | Pipeline required? |
 | ----------------------------- | ----------------------------- | ------------------ |
+| `project url`                 | project UI URL                | no                 |
 | `plan` / `apply` / `validate` | whole project                 | no                 |
 | `secret set`                  | project                       | no                 |
 | `dataset list`                | project                       | no                 |

package/docs/cli.md

@@ -33,7 +33,7 @@ Credentials and the platform base URL resolve from the same precedence order, hi
 
 `toloka login` verifies the key against the platform before saving anything. It writes `$XDG_CONFIG_HOME/toloka/credentials.json`, which defaults to `~/.config/toloka/credentials.json`, with file mode `0600` and a parent directory with mode `0700`. The file may also store local project aliases. The legacy `~/.toloka/credentials.json` is still read when the new path has no file. `toloka logout` deletes the stored file but does not revoke the key.
 
-Anonymous 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. Event payloads contain only an allowlisted command classifier, duration, exit code, outcome or error code, SDK and Bun versions, actor, and channel. Raw arguments, flag values, environment variables, API keys, secret names, base URLs and hosts, local paths, project ids, error messages, stack traces, and source context are not sent. GeoIP enrichment is disabled. Distinct id starts as a random UUID stored next to the credentials file. After a successful authenticated command, the CLI calls `GET /me` and aliases that UUID onto the platform user id without setting person properties. Set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to turn this off. CI is off unless you set `TOLOKA_TELEMETRY=1`.
+Ordinary usage events (`sdk_cli_command_completed` / `sdk_cli_command_failed`) go to Toloka's PostHog project so we can see which commands run and which error classes they hit. Their payloads contain only an allowlisted command classifier, duration, exit code, outcome or error code, SDK and Bun versions, actor, and channel. Raw arguments, flag values, environment variables, API keys, secret names, base URLs and hosts, local paths, project ids, error messages, stack traces, and source context are not sent. GeoIP enrichment is disabled. Distinct id starts as a random UUID stored next to the credentials file. After a successful authenticated command, the CLI calls `GET /me` and aliases that UUID onto the platform user id without setting person properties. Set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable capture. CI environments are disabled unless `TOLOKA_TELEMETRY=1`. The explicitly approved full-text `report` event is documented in [report](#report).
 
 The root program accepts these flags before any command:
 
@@ -44,7 +44,21 @@ The root program accepts these flags before any command:
 | `--base-url <url>`          | Platform base URL for this command only                          |
 | `--project-id <id>`         | Target project; overrides env, checkout, and the registry        |
 
-Commands resolve the project root by walking up from the working directory until they find a `toloka.json` file. The CLI reports that directory on stderr when it differs from the working directory. Passing `--source-root` disables discovery. With no marker found, the working directory is used. `init` does not walk up: it binds the working directory or `--source-root` only. The authentication commands `login`, `logout`, and `auth-status` do not need a project root.
+Commands resolve the project root by walking up from the working directory until they find a `toloka.json` file. The CLI reports that directory on stderr when it differs from the working directory. Passing `--source-root` disables discovery. With no marker found, the working directory is used. `init` and `report` do not walk up: they use the working directory or `--source-root` only. The authentication commands `login`, `logout`, and `auth-status` do not need a project root.
+
+## Resources and Base Actions
+
+The CLI is resource-first: `toloka <resource> <action>`. A Base Action has one meaning wherever a resource implements it. A resource exposes only the Base Actions that have real behavior; there are no placeholder actions.
+
+| Base Action | Meaning                                                                                   |
+| ----------- | ----------------------------------------------------------------------------------------- |
+| `list`      | Read a bounded, paginated collection of one Resource type.                                |
+| `get`       | Read exactly one Resource selected by a stable identifier.                                |
+| `create`    | Create exactly one Resource and return its stable identifier and representation.          |
+| `delete`    | Remove exactly one Resource selected by a stable identifier and return no representation. |
+| `url`       | Read exactly one browser-ready URL with no surrounding prose.                             |
+
+Resources may also expose specialized actions beyond the Base Actions, such as `pipeline cost`, `skill search`, and `skill install`.
 
 ## project
 
@@ -55,12 +69,15 @@ toloka project list
 toloka project add [alias] [projectId]
 toloka project switch <alias>
 toloka project current
+toloka project url
 toloka project remove <alias>
 toloka project create [alias] [--name <name>] [--team-id <id>]
 ```
 
 `add`, `switch`, `remove`, and `create` write the machine registry in the credentials file. They refuse `--api-key` / `--base-url` / `POTATO_*` when those would select a different key or platform than the stored file. `create` reuses the only visible team when every listed project shares one; otherwise pass `--team-id`.
 
+`url` fetches the selected project to resolve its team and prints only its platform UI URL to stdout, making the output safe to capture in scripts and agent workflows.
+
 ## login
 
 Stores an API key for this machine after verifying it.
@@ -93,15 +110,17 @@ On success it prints the platform URL with its source, the API key masked unless
 
 ## init
 
-Initializes the current project directory and installs agent entry points.
+Initializes the current project directory and installs the Agent Bootstrap entry points.
 
 ```sh
 toloka init
 ```
 
-`init` does not require a selected platform project. It always writes `.claude/skills/toloka-build/SKILL.md`, `.cursor/rules/toloka-build.mdc` when Cursor configuration exists, and an SDK-owned block in `AGENTS.md`. When a project is already selected through `--project-id`, `TOLOKA_PROJECT_ID` / `POTATO_PROJECT_ID`, `toloka.json`, or the machine registry, it also writes `toloka.json` when missing. It does not walk up to a parent checkout.
+`init` does not require a selected platform project. It always maintains one `<toloka>` … `</toloka>` Agent Bootstrap block in `AGENTS.md` and writes minimal pointers to it: `.claude/skills/toloka-bootstrap/SKILL.md` when `.claude/` exists (or when no agent configuration exists at all) and `.cursor/rules/toloka-bootstrap.mdc` with `alwaysApply: true` when `.cursor/rules/` exists. The bootstrap tells an agent to run `toloka --help`, search the bundled Skill Catalog with `toloka skill search`, install a matching skill with `toloka skill install`, and read `.agents/skills/<skill-id>/SKILL.md`; it does not embed the build workflow. Bytes outside the block are preserved, and re-running `init` refreshes the block and both pointers in place without adding duplicates. When a project is already selected through `--project-id`, `TOLOKA_PROJECT_ID` / `POTATO_PROJECT_ID`, `toloka.json`, or the machine registry, it also writes `toloka.json` when missing. It does not walk up to a parent checkout.
 
-On success it prints `Initialized agent entry points for @toloka-platform/sdk <version> in <root>:` followed by the file list, or `Agent entry points are up to date` when nothing changed. It warns on stderr when the SDK is not listed in the project dependencies. Every other `toloka` command compares the recorded skill digest with the installed SDK and warns on stderr when the generated files are stale; that warning never blocks the command.
+`init` removes only Toloka-generated legacy entry points that still carry the `<!-- toloka:sdk-version … -->` marker: the full `toloka-build` and `toloka-pipeline-as-code` Claude skills and Cursor rules, plus the `<!-- toloka:begin -->` … `<!-- toloka:end -->` block in `AGENTS.md`, which is replaced by the `<toloka>` block in place. Files without that marker, other skills and rules, and installed skills under `.agents/skills/` are left untouched. An `AGENTS.md` whose current or legacy block is unterminated, reversed, or duplicated is refused with the file's full path before anything, including `toloka.json`, is written.
+
+On success it prints `Initialized agent entry points for @toloka-platform/sdk <version> in <root>:` followed by the file list and one `removed <path>` line per legacy entry point, or `Agent entry points are up to date` when nothing changed. It warns on stderr when the SDK is not listed in the project dependencies. Every other project command warns on stderr when a generated legacy entry point is still present or the recorded bootstrap version differs from the installed SDK; that warning never blocks the command. `support` commands skip the check because they never read the checkout.
 
 ## import
 
@@ -183,6 +202,31 @@ toloka pipeline results <runId> [--limit <n>] [--failed]
 
 `pipeline status` reports the latest run of that pipeline. `pipeline runs` lists recent runs (default 10). `pipeline cost` forecasts what a run would bill. `pipeline cancel` and `pipeline results` take a run id.
 
+## base-model
+
+Inspect the global, read-only Base Model Catalog.
+
+```sh
+toloka base-model list [--json]
+toloka base-model get <id> [--json]
+```
+
+Human-readable output is the default. `base-model list` prints aligned ID, name, provider, and upstream-model columns; `base-model get` prints labeled fields including the pinned revision. Pass `--json` for machine-readable output.
+
+## model
+
+Manage Model metadata in the selected project.
+
+```sh
+toloka model list [--json]
+toloka model get <name-or-id> [--json]
+toloka model versions <name-or-id> [--json]
+toloka model create <name> --base <base-model-id> [--description <text>] [--json]
+toloka model archive <name-or-id> [--json]
+```
+
+`model create` creates project-owned Model metadata linked to one catalog Base Model; it does not create a Model Version. Human-readable output is the default for every command in this group. Pass `--json` for machine-readable objects or arrays. Weight upload, validation, download, and Model Version creation are deferred.
+
 ## dataset
 
 Catalog and row commands for datasets in the selected project. Name or id is accepted; duplicate names must be addressed by id.
@@ -200,7 +244,39 @@ toloka dataset upload <name> <file>
 
 `dataset load` starts a platform export, waits for it (default 60s; pass `--timeout`), downloads the JSON array, and writes JSONL to `--out`. `--limit` slices after download; it still waits for the full export. On timeout the message names the export id. Failed downloads and invalid payloads leave `--out` untouched.
 
-`dataset upload` appends JSONL rows. Field schemas are immutable after the first upload: you can add columns, never alter or remove one. See [datasets](./datasets.md).
+`dataset upload` accepts `.json` arrays, `.jsonl` files with one object per line, and `.csv` files with a header row. The CLI infers the format from the extension and uploads the original bytes without conversion. If the blob transfer or finalization fails, the CLI cancels the started upload before returning the error, so another upload can start immediately and may reuse the same filename. Field schemas are immutable after the first successful upload: you can add columns, never alter or remove one. See [datasets](./datasets.md).
+
+## report
+
+Preview and submit one Markdown issue report through the CLI's existing PostHog telemetry client. The command is project-independent: it does not read `toloka.json`, walk up to find a project root, require credentials, or call the Toloka API.
+
+```sh
+toloka report <markdownPath> [--authored-by human|agent] [--confirm]
+```
+
+The report path must name a non-empty regular UTF-8 file no larger than 256 KiB. The CLI refuses symbolic-link files and paths that traverse a symbolic-link directory under the selected source root. It prints the complete report, declared authorship, and platform origin before submission. Control and bidirectional formatting characters are escaped in the preview but preserved in the submitted report text.
+
+In a terminal the command asks `Send this report to Toloka? [y/N]`; outside a terminal it refuses unless `--confirm` is passed. `--authored-by` defaults to `human`. Add `--confirm` only after reviewing the exact preview.
+
+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.
+
+## 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.
+
+```sh
+toloka skill list [--json]
+toloka skill search <query> [--json]
+toloka skill install <skillId> [--force]
+```
+
+`list` prints every skill in the catalog with its installation status: `not-installed` when `.agents/skills/<skillId>` is absent, `current` when the installed files match the catalog digest, and `stale` when they differ. Each skill line (`id`, status, name) is followed by one indented description line. `--json` prints the Skill Descriptors (`id`, `name`, `description`, `tags`, `version`, `digest`, `files`) plus `status` and never includes file contents.
+
+`search` matches `<query>` case-insensitively against each skill's id, name, description, and tags and prints the matches in the same format. When nothing matches it says so (or prints `[]` with `--json`), exits 0, and installs nothing.
+
+`install` copies the complete skill — its `SKILL.md` entry point and every reference — from the package into `.agents/skills/<skillId>/` under the project root and prints the destination. Every path is confined to that directory and the command refuses to write through symbolic links. An existing `.agents/skills/<skillId>` is refused unless `--force` is passed. With `--force` the new copy is written to a temporary sibling directory and verified against the catalog digest, the existing directory is renamed to a backup, the verified copy is moved into place, and the backup is removed; a failed swap restores the backup, so the directory never holds a mixed version. A malformed catalog, an unsafe path, or a digest mismatch fails before any existing file changes.
+
+After an SDK upgrade `list` reports installed skills whose catalog digest changed as `stale` until they are refreshed with `install --force`. Local edits to an installed skill also make it `stale`; `list` and `search` never modify local files.
 
 ## Exit codes
 

package/docs/datasets.md

@@ -109,17 +109,16 @@ toloka dataset upload face-images data/face_images.jsonl
 
 The command takes two positional arguments and has no flags:
 
-| Argument | Description                          |
-| -------- | ------------------------------------ |
-| `<name>` | Dataset name or id                   |
-| `<file>` | JSONL file, one JSON object per line |
+| Argument | Description                                |
+| -------- | ------------------------------------------ |
+| `<name>` | Dataset name or id                         |
+| `<file>` | `.json`, `.jsonl`, or `.csv` file to append |
 
-Each line is a JSON object with keys matching column names:
+The CLI infers the format from the filename extension and uploads the original bytes without conversion:
 
-```json
-{"image_url": "https://example.com/cat-1.jpg"}
-{"image_url": "https://example.com/cat-2.jpg"}
-```
+- `.json` contains an array of row objects.
+- `.jsonl` contains one row object per non-empty line and is validated locally before upload.
+- `.csv` uses its header row for field names; every value is ingested as a string.
 
 Upload is additive: it appends items and never rewrites existing ones. If the dataset does not exist yet and a pipeline in source declares it, `dataset upload` creates the dataset with the declared columns automatically. If no pipeline declares the dataset, upload stops and asks you to bind a pipeline to it in source so its columns are known, or to upload to an existing dataset. Duplicate live names must be addressed by id.
 

package/docs/getting-started.md

@@ -44,7 +44,7 @@ CI does not need `login`. Set `POTATO_API_KEY` and the stored file is ignored. S
 
 ## Start with an agent
 
-Initialize the current directory and install the bundled agent skills. No platform project needs to be selected yet.
+Initialize the current directory and install the Agent Bootstrap. No platform project needs to be selected yet.
 
 ```sh
 toloka init
@@ -54,7 +54,7 @@ Open your coding agent in this directory and describe the project you want, for
 
 > Create a Toloka project that collects captions for images. Show me the plan before applying it.
 
-The skill guides the agent through creating and selecting the platform project, authoring the TypeScript source, validating it, showing the plan, and applying the approved changes. `toloka.json` is created when the project is selected.
+The bootstrap directs the agent to `toloka --help` and to search and install the matching bundled skill; the `toloka-build` skill then guides the agent through creating and selecting the platform project, authoring the TypeScript source, validating it, showing the plan, and applying the approved changes. `toloka.json` is created when the project is selected.
 
 ## Manual project setup
 

package/docs/limitations.md

@@ -2,7 +2,7 @@
 
 What this Preview SDK does not do yet, stated plainly so you can decide what to depend on.
 
-`@toloka-platform/sdk` is `0.1.0-preview.4`. This is a Preview: the authoring API, the CLI surface, and the generated source layout can change without a major version bump. Pin an exact version. Do not depend on this in production yet.
+`@toloka-platform/sdk` is `0.1.0-preview.6`. This is a Preview: the authoring API, the CLI surface, and the generated source layout can change without a major version bump. Pin an exact version. Do not depend on this in production yet.
 
 ## The SDK does not certify deployability
 
@@ -39,13 +39,10 @@ A `code` node carries its Python as an inline string in `code.code`. There is no
 
 These are reproduced platform-side issues that affect the SDK path. They are not SDK bugs and cannot be fixed from this package.
 
-| defect                                                                                  | effect on you                                                                                           | workaround                                                        |
-| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| Re-uploading a filename already used in a dataset returns a bodyless `500`              | running the same `toloka dataset upload` twice fails                                                    | use a distinct filename per upload                                |
-| A failed upload leaves a pending upload row, and a pending upload counts as in progress | later uploads to that dataset return `409 Another upload is already in progress`, with no public cancel | load into a new dataset; ask for the pending upload to be cleared |
-| Finalizing a file upload can return a bodyless `500`                                    | `toloka dataset upload` cannot complete on an affected environment                                      | declare columns in source and load rows through a client call     |
-| Rows added through the items endpoint skip column inference                             | `toloka dataset fields` reports no columns for a dataset that holds rows                                | declare columns in source rather than inferring them              |
-| Starting a run intermittently returns a bodyless `500`                                  | `toloka pipeline run` fails with nothing to act on                                                      | check `toloka pipeline runs <name>` for a created run, then retry |
+| defect                                                      | effect on you                                                            | workaround                                                        |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------- |
+| Rows added through the items endpoint skip column inference | `toloka dataset fields` reports no columns for a dataset that holds rows | declare columns in source rather than inferring them              |
+| Starting a run intermittently returns a bodyless `500`      | `toloka pipeline run` fails with nothing to act on                       | check `toloka pipeline runs <name>` for a created run, then retry |
 
 ## Not attempted yet
 

package/docs/troubleshooting.md

@@ -51,17 +51,6 @@ A resource exists on the platform but not in your source tree. `apply` reports i
 
 Another writer changed the graph after your source was read. Do not retry blindly: `plan` again to re-read live state, review the new diff, carry any intentional remote change into source, then `apply`.
 
-## Second upload of the same filename fails
-
-Uploading a file whose basename already exists in that dataset fails with a bodyless `500`. `toloka dataset upload` sends the file's basename, so running the same documented command twice reproduces it:
-
-```sh
-toloka dataset upload cat-images ./data/rows.jsonl   # first time: fine
-toloka dataset upload cat-images ./data/rows.jsonl   # second time: 500
-```
-
-Until the platform returns a proper conflict, use a distinct filename per upload — for example `rows-2026-08-13.jsonl`. This is a platform defect, tracked; the SDK cannot detect it in advance.
-
 ## Another upload is already in progress
 
 ```