@toloka-platform/sdk 0.1.0-preview.9 → 0.1.0

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

@@ -1 +1 @@
-92bbe68b3e86c7e0a8d7d66dfc8277f682402c5513db4a58844ba6173975afd1  toloka.js.jsc
+b3ff8750d4254e81d4dccbba6db162057e702b7b823d76d6adc2e6b122212251  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-16b1b42414dbde194d20e05efb359538bae80906bba75e1af3e0b8638a82ec43  toloka.js
+122b2c1f1afe960176a8f8f5557f847da14ed454809f44d8ed4a5212be6ace2a  toloka.js

package/docs/authoring.md

@@ -37,19 +37,24 @@ The name is a bare identifier. When a field is a pipeline **input**, its name mu
 
 ## Node constructors
 
-Five constructors cover the whole palette. Each takes a name, a settings object, and optional `{ id }`.
+Four work-node constructors take a name, settings, and optional `{ id }`: `code`, `generation`, `quorum`, and `match`. `root` is the single pipeline boundary and takes only settings plus optional `{ id }`.
 
 ### root
 
 Defines the pipeline's input and output contract. `started` is what each item carries in from the dataset; `completed` is what gets written back.
 
 ```ts
-import { root } from "@toloka-platform/sdk";
+import { optional, root } from "@toloka-platform/sdk";
 
-export const collection = root({ started: [imageUrl], completed: [annotations] });
+export const collection = root({
+  started: [imageUrl],
+  completed: [optional(annotations)],
+});
 ```
 
-Pass `{ field, optional: true }` instead of a bare field to make a binding optional.
+Pass a bare field for a required binding. Use `optional(field)` for new optional bindings. The explicit `{ field, optional }` form remains supported and may appear in imported source.
+
+`root()` deliberately has no name argument: a pipeline has exactly one boundary, and its default wire id is `root`.
 
 ### code
 

package/docs/cli-v2.md

@@ -1,6 +1,6 @@
 # CLI v2: project as the root
 
-How `toloka` should work in the next version. Preview is unreleased, so this is a clean cutover, not a compatibility layer.
+How `toloka` should work in the next version. Beta remains a clean cutover rather than a compatibility layer.
 
 The platform object is a **project** (`pp.…`, today's pipeline project). Windmill calls the same role a workspace. PostHog calls it a project. We keep **project** so the CLI matches the API and the console.
 
@@ -212,7 +212,7 @@ Do not add those groups until the resource exists. The rule is already fixed: th
 | `toloka runs` / `cost` / `cancel` / `results` | `toloka pipeline …`                                                |
 | root = `toloka.json` or `pipelines/`          | root = `toloka.json` only                                          |
 
-No shims. Preview callers update.
+No shims. Beta callers update.
 
 ## Out of scope
 

package/docs/cli.md

@@ -2,7 +2,7 @@
 
 The `toloka` CLI reads TypeScript source as the desired state, compares it with the live platform state, and reconciles the two.
 
-This CLI is Preview software. Commands, flags, and output can change without a major version bump.
+This CLI is Beta software. Commands, flags, and output can change before general availability.
 
 `toloka` requires Bun 1.4.0. The published package ships matching CLI bytecode; the launcher falls back to TypeScript source in a development checkout when the bytecode is absent.
 
@@ -61,6 +61,14 @@ The CLI is resource-first: `toloka <resource> <action>`. A Base Action has one m
 
 Resources may also expose specialized actions beyond the Base Actions, such as `pipeline cost`, `skill search`, and `skill install`.
 
+## version
+
+Print the SDK/CLI version. `toloka version --json` also prints build provenance: the build commit when the bytecode bundle recorded one, the install channel (`global-registry`, `linked`, or `project-local`), and the local package path for linked installs. `toloka -v` and `toloka --version` remain semver-only for scripts.
+
+```sh
+toloka version [--json]
+```
+
 ## project
 
 Register and select the platform project later commands use.
@@ -73,9 +81,12 @@ toloka project current
 toloka project url
 toloka project remove <alias>
 toloka project create [alias] [--name <name>] [--team-id <id>]
+toloka project untrack <pipeline|dataset> <name> [--confirm]
 ```
 
-`add`, `switch`, `remove`, and `create` write the machine registry in the credentials file. They refuse `--api-key` / `--base-url` / `POTATO_*` when those would select a different key or platform than the stored file. `create` reuses the only visible team when every listed project shares one; otherwise pass `--team-id`.
+`add`, `switch`, `remove`, and `create` write the machine registry in the credentials file. They refuse `--api-key` / `--base-url` / `POTATO_*` when those would select a different key or platform than the stored file. `project list` prints project id, name, and team id. `create` reuses the only visible team when every listed project shares one; otherwise pass `--team-id`.
+
+`project untrack` removes one pipeline or dataset binding from `toloka.json` without deleting the live resource. It previews the name and id in a terminal; outside a terminal, pass `--confirm` after reviewing the state file.
 
 `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.
 

package/docs/getting-started.md

@@ -4,11 +4,11 @@ Install the SDK, sign in, and get a pipeline project reconciling from source in
 
 ## Install
 
-Install the bytecode-cached CLI globally and declare the Preview SDK in the project:
+Install the bytecode-cached CLI globally and declare the Beta SDK in the project:
 
 ```sh
 curl -fsSL https://platform.toloka.ai/cli/install.sh | sh
-bun add @toloka-platform/sdk@preview
+bun add @toloka-platform/sdk@latest
 ```
 
 The installer requires Bun 1.4.0, installs `@toloka-platform/sdk` globally, and exposes `toloka` through Bun's global binary directory. The published CLI includes matching precompiled bytecode. The project install makes SDK imports resolvable.
@@ -140,4 +140,4 @@ Exit code `0` means the run reached a successful terminal state, `1` a failed on
 - [Nodes](./nodes.md) — which node to reach for, and the pricing floors you must clear
 - [CLI](./cli.md) — every command and flag
 - [Troubleshooting](./troubleshooting.md) — the failures you will hit
-- [Limitations](./limitations.md) — Preview status and what this SDK does not do yet
+- [Limitations](./limitations.md) — Beta status and what this SDK does not do yet

package/docs/limitations.md

@@ -1,8 +1,8 @@
 # Limitations
 
-What this Preview SDK does not do yet, stated plainly so you can decide what to depend on.
+What this Beta SDK does not do yet, stated plainly so you can decide what to depend on.
 
-`@toloka-platform/sdk` is `0.1.0-preview.9`. 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`. This is a Beta: the authoring API, the CLI surface, and the generated source layout can change before general availability. Pin an exact version. Do not depend on this in production yet.
 
 ## Local checks do not certify deployability
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@toloka-platform/sdk",
-  "version": "0.1.0-preview.9",
+  "version": "0.1.0",
   "private": false,
-  "description": "Preview. Build, inspect, and operate Toloka pipeline projects as TypeScript source. The public API may change.",
+  "description": "Beta. Build, inspect, and operate Toloka pipeline projects as TypeScript source. The public API may change.",
   "license": "Apache-2.0",
   "bin": {
     "toloka": "bin/toloka.js"
@@ -28,7 +28,7 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "tag": "preview"
+    "tag": "latest"
   },
   "scripts": {
     "build": "bun ./scripts/build-cli.ts ./dist/cli",

package/skills/catalog.json

@@ -13,8 +13,8 @@
         "testing",
         "checks"
       ],
-      "version": "0.1.0-preview.9",
-      "digest": "87dca7b1cc0cf3d61f54ab27703ea4b60622355ec07e289ce1242bb3c2233482",
+      "version": "0.1.0",
+      "digest": "bcdb60e89bc4b8e345c1793c7a7d5275e8b196e171bd09adba242ed89f117a50",
       "files": ["SKILL.md", "references/node-semantics.md", "references/workflow-and-cli.md"]
     },
     {
@@ -22,8 +22,8 @@
       "name": "Report a Toloka problem",
       "description": "Report a problem with the Toloka platform, CLI, or SDK as a redacted Markdown issue report sent through the toloka CLI only after explicit approval. Use when the user hits unexpected behavior, an error, or a bug and wants Toloka engineers to investigate.",
       "tags": ["support", "issue", "bug", "report"],
-      "version": "0.1.0-preview.9",
-      "digest": "6fb8ccf80b346de0745bb7d9192e4e3998cb8f06c8b30f7eb6dcc5b326f4646d",
+      "version": "0.1.0",
+      "digest": "969aedef68e56243395e0a9115d90041c7c1e27f759762b07e62a7d521a8a251",
       "files": ["SKILL.md", "references/report-template.md"]
     }
   ]

package/skills/toloka-build/SKILL.md

@@ -5,7 +5,7 @@ description: Onboard users and build, test, inspect, or change Toloka platform p
 
 # Build Toloka pipelines as code
 
-This SDK is Preview software. The authoring API, the CLI, and generated source can change. Do not invent helpers or flags that are not in the installed package.
+This SDK is Beta software. The authoring API, the CLI, and generated source can change before general availability. Do not invent helpers or flags that are not in the installed package.
 
 Use this skill when the user wants to get started or to create, inspect, test, or change a Toloka pipeline project as code. Work in the project source tree; do not translate the request into direct platform API calls.
 

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

@@ -43,13 +43,13 @@ connect(annotate.output, collection.completed);
 
 ### Pick and configure it
 
-Create exactly one `root` node. Use `started` for dataset fields the pipeline reads and `completed` for fields it writes back to the same dataset. A completed field is not a separate output destination: the platform creates or uses that dataset column per item.
+Create exactly one `root` node with `root(settings)`. It has no name argument because it represents the pipeline boundary, not a named unit of work. Use `started` for dataset fields the pipeline reads and `completed` for fields it writes back to the same dataset. A completed field is not a separate output destination: the platform creates or uses that dataset column per item.
 
 The public authoring shape is `RootAuthoringSettings`:
 
 - `started`: fields exposed through the `started` output port.
 - `completed`: fields accepted through the `completed` input port and written to the dataset.
-- Each entry can be a `Field` or `{ field, optional }`; a bare `Field` is required.
+- Each entry can be a required `Field`, `optional(field)`, or an explicit `{ field, optional }` binding. Prefer `optional(field)` for new optional bindings and preserve the explicit object form in imported source.
 - `itemLimit` exists in both `RootNodeSettings` and `RootAuthoringSettings`. Do not invent a limit; author one only when the user explicitly requests a bounded test or batch. Apply preserves a live `itemLimit` unless source declares its own.
 
 The dataset name belongs in `definePipeline({ dataset: 'name', ... })`, not in the root settings. `toloka apply` resolves or creates the named dataset and supplies its ID.

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

@@ -83,7 +83,7 @@ All commands accept `--source-root <directory>`. Prefer running from the source
 The real command surface is:
 
 ```text
-toloka version
+toloka version [--json]
 toloka -v
 toloka --version
 toloka login
@@ -99,6 +99,7 @@ toloka project current
 toloka project url
 toloka project remove <alias>
 toloka project create [alias] [--name <name>] [--team-id <id>]
+toloka project untrack <pipeline|dataset> <name> [--confirm]
 toloka init
 toloka import [projectId]
 toloka check [pipeline] [--node <name-or-id>] [--json] [--watch]

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

@@ -26,7 +26,7 @@ The CLI exits 1 with `Potato API request failed with status 500`. The same comma
 
 ## Environment
 
-- toloka CLI 0.1.0-preview.9 (`toloka --version`), Bun 1.4.0, macOS 15
+- toloka CLI 0.1.0 (`toloka --version`), Bun 1.4.0, macOS 15
 - Platform: https://platform.toloka.ai
 
 ## Redactions

package/src/authoring/index.ts

@@ -56,6 +56,8 @@ type FieldReference = {
   readonly optional: boolean;
 };
 
+export type OptionalFieldBinding = { readonly field: Field; readonly optional: true };
+
 type RootFieldReference = Field | { readonly field: Field; readonly optional?: boolean };
 
 type FieldRelation<Relation> = Relation extends { id: string }
@@ -445,10 +447,18 @@ export function field<const Name extends string>(
   };
 }
 
+export function optional(referencedField: Field): OptionalFieldBinding {
+  return { field: referencedField, optional: true };
+}
+
 function createRoot(
   settings: RootAuthoringSettings,
   options: AuthoringIdOptions = {},
 ): AuthoredRootNode {
+  assert(
+    typeof settings === "object" && settings !== null && !Array.isArray(settings),
+    "root() defines the single pipeline boundary; call root({ started, completed }) without a name",
+  );
   const id = options.id ?? "root";
   const { started, completed, ...settingsWithoutFieldProxies } = settings;
   return {

package/src/cli/auto-update.ts

@@ -123,11 +123,7 @@ export const asNpmPackageView = (payload: unknown): NpmPackageView | undefined =
 };
 
 export const latestPublishedVersion = (view: NpmPackageView): string | undefined => {
-  const tags = view["dist-tags"];
-  if (tags === undefined) return undefined;
-  const preview = tags.preview;
-  if (typeof preview === "string" && preview.length > 0) return preview;
-  const latest = tags.latest;
+  const latest = view["dist-tags"]?.latest;
   return typeof latest === "string" && latest.length > 0 ? latest : undefined;
 };
 

package/src/cli/check.ts

@@ -114,6 +114,18 @@ export type CheckProjectResult = {
   readonly source?: ProjectSource;
   readonly output: string;
 };
+
+export type FreshCheckFailurePhase = "spawn" | "execute" | "read_result" | "parse_result";
+
+export class FreshCheckProcessError extends Error {
+  readonly phase: FreshCheckFailurePhase;
+
+  constructor(phase: FreshCheckFailurePhase, message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "FreshCheckProcessError";
+    this.phase = phase;
+  }
+}
 const MAX_DIAGNOSTIC_CHARS = 5_000;
 const MAX_TOOL_OUTPUT_BYTES = 64 * 1024;
 export const CHECK_RESULT_FILE_ENV = "TOLOKA_INTERNAL_CHECK_RESULT_FILE";
@@ -865,44 +877,93 @@ const parseFreshCheckResult = (value: unknown, json: boolean): CheckProjectResul
     output: json ? JSON.stringify({ exitCode, results }) : formatCheckResults(results),
   };
 };
+
+const checkProcessOutput = (run: ToolRunResult): string =>
+  [run.stderr, run.stdout].filter(Boolean).join("\n");
+
+export const readFreshCheckResult = async (
+  run: ToolRunResult,
+  readResult: () => Promise<string>,
+  json = false,
+): Promise<CheckProjectResult> => {
+  let raw: string;
+  try {
+    raw = await readResult();
+  } catch (error) {
+    if (run.exitCode !== 0) {
+      const output = checkProcessOutput(run);
+      throw new FreshCheckProcessError(
+        "execute",
+        output.length === 0
+          ? `Local check process exited ${run.exitCode} before producing results`
+          : `Local check process failed before producing results:\n${output}`,
+        { cause: error },
+      );
+    }
+    throw new FreshCheckProcessError(
+      "read_result",
+      "Local check process completed without producing a result file",
+      { cause: error },
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new FreshCheckProcessError("parse_result", "Local check process returned invalid JSON", {
+      cause: error,
+    });
+  }
+
+  try {
+    return parseFreshCheckResult(parsed, json);
+  } catch (error) {
+    throw new FreshCheckProcessError(
+      "parse_result",
+      `Local check process returned an invalid result: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+};
 export const runFreshCheck = async (options: CheckProjectOptions): Promise<CheckProjectResult> => {
   const entry = resolveCliEntry();
   const resultDirectory = await mkdtemp(join(tmpdir(), "toloka-check-watch-result-"));
   const resultPath = join(resultDirectory, "result.json");
-  let run: ToolRunResult | undefined;
   try {
-    run = await runModule(
-      options.sourceRoot,
-      entry,
-      [
-        "--source-root",
+    let run: ToolRunResult;
+    try {
+      run = await runModule(
         options.sourceRoot,
-        "check",
-        ...(options.pipeline === undefined ? [] : [options.pipeline]),
-        ...(options.node === undefined ? [] : ["--node", options.node]),
-        "--json",
-      ],
-      {
-        ...(process.env.PATH === undefined ? {} : { PATH: process.env.PATH }),
-        ...(options.environment ?? process.env),
-        [CHECK_RESULT_FILE_ENV]: resultPath,
-      },
-      options.signal,
-      "bun",
-    );
-    return parseFreshCheckResult(
-      JSON.parse(await readFile(resultPath, "utf8")),
+        entry,
+        [
+          "--source-root",
+          options.sourceRoot,
+          "check",
+          ...(options.pipeline === undefined ? [] : [options.pipeline]),
+          ...(options.node === undefined ? [] : ["--node", options.node]),
+          "--json",
+        ],
+        {
+          ...(process.env.PATH === undefined ? {} : { PATH: process.env.PATH }),
+          ...(options.environment ?? process.env),
+          [CHECK_RESULT_FILE_ENV]: resultPath,
+        },
+        options.signal,
+        "bun",
+      );
+    } catch (error) {
+      throw new FreshCheckProcessError(
+        "spawn",
+        `Unable to start the local check process: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
+      );
+    }
+    return await readFreshCheckResult(
+      run,
+      async () => readFile(resultPath, "utf8"),
       options.json === true,
     );
-  } catch (error) {
-    const detail = [
-      run?.stderr,
-      run?.stdout,
-      error instanceof Error ? error.message : String(error),
-    ]
-      .filter(Boolean)
-      .join("\n");
-    throw new Error(`Fresh check process returned unreadable output: ${detail}`, { cause: error });
   } finally {
     await rm(resultDirectory, { recursive: true, force: true });
   }

package/src/cli/cost.ts

@@ -80,7 +80,13 @@ const collectNodeRows = (
 };
 
 const collectTotalRows = (total: PipelineCostEstimate["total"]): TableRow[] => {
-  const totals: TableRow[] = [["Total", total.expected, total.worstCase]];
+  const totals: TableRow[] =
+    total.expected === total.worstCase
+      ? [["Run cost", total.expected, ""]]
+      : [
+          ["Expected run cost", total.expected, ""],
+          ["Maximum run cost", "", total.worstCase],
+        ];
   if (total.bestCase != null) {
     totals.push(["Best case", total.bestCase, ""]);
   }

package/src/cli/program.ts

@@ -64,6 +64,7 @@ import {
   removeProject,
   resolveProjectContext,
   switchProject,
+  untrackProjectResource,
 } from "./project-context";
 import { estimatePipelineCost } from "./cost";
 import { submitIssueReport } from "./report";
@@ -81,6 +82,7 @@ import {
 
 import type { RunOutcome } from "./runs";
 import { skillInstallCommand, skillListCommand, skillSearchCommand } from "./skill";
+import { cliVersionInfo } from "./version";
 import { findSourceRoot } from "./source";
 
 export type CliIo = {
@@ -242,7 +244,7 @@ export function createProgram(context: ProgramContext): CreatedProgram {
 
   program
     .description(
-      "Preview. Build and operate Toloka pipeline projects from TypeScript source. The public API may change.",
+      "Beta. Build and operate Toloka pipeline projects from TypeScript source. The public API may change before general availability.",
     )
     .version(SDK_VERSION, "-v, --version", "output the current version")
     .option(
@@ -282,10 +284,14 @@ export function createProgram(context: ProgramContext): CreatedProgram {
     warnedAboutStaleSkills = true;
     context.io.stderr(warning);
   });
+
   program
     .command("version")
+    .option("--json", "print version and build provenance as JSON", false)
     .description("print the current CLI version")
-    .action(() => context.io.stdout(SDK_VERSION));
+    .action((options: { json: boolean }) =>
+      context.io.stdout(options.json ? JSON.stringify(cliVersionInfo()) : SDK_VERSION),
+    );
 
   const config = program.command("config").description("read and write machine CLI settings");
   config
@@ -472,6 +478,26 @@ export function createProgram(context: ProgramContext): CreatedProgram {
         io: context.io,
       });
     });
+  project
+    .command("untrack")
+    .argument("<type>", "pipeline or dataset")
+    .argument("<name>", "tracked resource name")
+    .option("--confirm", "confirm untracking in a non-interactive environment", false)
+    .description("remove a pipeline or dataset from local tracking without deleting it")
+    .action(async (type: string, name: string, options: { confirm: boolean }) => {
+      assert(
+        type === "pipeline" || type === "dataset",
+        "Resource type must be pipeline or dataset.",
+      );
+      const sourceRoot = await resolveSourceRoot(globals(), context.io);
+      await untrackProjectResource({
+        sourceRoot,
+        type,
+        name,
+        confirm: options.confirm,
+        io: context.io,
+      });
+    });
   project
     .command("create")
     .argument("[alias]", "local name for the new project")

package/src/cli/project-context.ts

@@ -1,5 +1,5 @@
 import { assert } from "es-toolkit";
-import { readTolokaState, writeTolokaState } from "../state";
+import { readTolokaState, TOLOKA_STATE_FILENAME, writeTolokaState } from "../state";
 import type { TolokaState } from "../state";
 import type { AuthPrompt } from "./auth";
 import type { TolokaCliFlags, TolokaEnvironment } from "./config";
@@ -238,7 +238,7 @@ export async function listRemoteProjects(options: {
       options.context?.id === project.id && options.context.alias !== undefined
         ? `\t${options.context.alias}`
         : "";
-    return `${mark}\t${project.id}\t${project.name}${alias}`;
+    return `${mark}\t${project.id}\t${project.name}\t${project.teamId}${alias}`;
   });
   if (page.pagination.hasMore) {
     lines.push(
@@ -250,6 +250,51 @@ export async function listRemoteProjects(options: {
   return { output };
 }
 
+export type TrackedResourceKind = "pipeline" | "dataset";
+
+export async function untrackProjectResource(options: {
+  readonly sourceRoot: string;
+  readonly type: TrackedResourceKind;
+  readonly name: string;
+  readonly confirm: boolean;
+  readonly io: ProjectIo;
+}): Promise<{ readonly output: string }> {
+  const state = await readTolokaState(options.sourceRoot);
+  assert(state, `No ${TOLOKA_STATE_FILENAME} found in ${options.sourceRoot}.`);
+  const bindings = options.type === "pipeline" ? state.pipelines : state.datasets;
+  const binding = bindings[options.name];
+  assert(
+    binding,
+    `${options.type === "pipeline" ? "Pipeline" : "Dataset"} ${options.name} is not tracked.`,
+  );
+  const id = "pipelineId" in binding ? binding.pipelineId : binding.datasetId;
+  const label = `${options.type} ${options.name} (${id})`;
+
+  if (!options.confirm) {
+    assert(
+      options.io.prompt,
+      `Refusing to untrack ${label} without confirmation. Pass --confirm after reviewing ${TOLOKA_STATE_FILENAME}.`,
+    );
+    const answer = (
+      await options.io.prompt(`Untrack ${label}? The live resource will not be deleted. [y/N] `)
+    )
+      .trim()
+      .toLowerCase();
+    assert(answer === "y" || answer === "yes", "Untrack canceled.");
+  }
+
+  const remaining = Object.fromEntries(
+    Object.entries(bindings).filter(([candidate]) => candidate !== options.name),
+  );
+  await writeTolokaState(options.sourceRoot, {
+    ...state,
+    ...(options.type === "pipeline" ? { pipelines: remaining } : { datasets: remaining }),
+  });
+  const output = `Untracked ${label}. The live ${options.type} was not deleted.`;
+  options.io.stdout(output);
+  return { output };
+}
+
 export async function addProject(options: {
   readonly environment: CliEnvironment;
   readonly flags?: TolokaCliFlags;