@toloka-platform/sdk 0.2.0-preview.3 → 0.2.0

package/src/cli/commands/training.ts

@@ -1,17 +1,20 @@
-import { assert } from "es-toolkit";
 import type { Command } from "commander";
 import {
-  nonNegativeInteger,
   positiveInteger,
   resolveContext,
+  trainingBatchSize,
   trainingDraftOptions,
+  trainingEpochs,
+  trainingGistTokens,
+  trainingLearningRate,
+  trainingLoraRank,
+  trainingMaxSequenceLength,
   trainingMethod,
-  trainingRegime,
   type CommandHost,
   type RawTrainingDraftOptions,
 } from "../context";
 import { parseBaseModelId } from "../models";
-import { MISSING_PROJECT_ID_MESSAGE } from "../project-context";
+import { assertProjectSelected } from "../project-context";
 import {
   cancelTrainingRun,
   createTraining,
@@ -37,7 +40,7 @@ export const registerTrainingCommands = (program: Command, host: CommandHost): v
     .description("list active Trainings owned by the selected project")
     .action(async (options: { json: boolean }) => {
       const { client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       await listTrainings(client, { projectId, json: options.json }, context.io);
     });
   training
@@ -47,7 +50,7 @@ export const registerTrainingCommands = (program: Command, host: CommandHost): v
     .description("show one Training draft")
     .action(async (nameOrId: string, options: { json: boolean }) => {
       const { client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       await getTraining(client, { projectId, nameOrId, json: options.json }, context.io);
     });
   training
@@ -60,15 +63,30 @@ export const registerTrainingCommands = (program: Command, host: CommandHost): v
     .option("--validation-dataset <id>", "optional validation Dataset ID")
     .option("--train-filter <field=value>", "training Dataset field equality filter")
     .option("--validation-filter <field=value>", "validation Dataset field equality filter")
-    .option("--regime <regime>", "Python training regime", trainingRegime)
-    .option("--epochs <count>", "training epochs", nonNegativeInteger)
-    .option("--eval-steps <count>", "SFT eval steps", positiveInteger)
+    .option("--lora-rank <rank>", "SFT LoRA adapter rank: 8, 16, or 32 (default 16)", trainingLoraRank)
+    .option("--gist-tokens <count>", "gisting soft tokens: 8, 32, or 64 (default 32)", trainingGistTokens)
+    .option("--epochs <count>", "training epochs, 1 through 5 (default 3)", trainingEpochs)
+    .option(
+      "--learning-rate <rate>",
+      "optimizer learning rate (default 0.00015 for SFT, 0.03 for gisting)",
+      trainingLearningRate,
+    )
+    .option(
+      "--batch-size <count>",
+      "sequences per optimizer step: 8, 16, 32, or 64 (default 8)",
+      trainingBatchSize,
+    )
+    .option(
+      "--max-sequence-length <tokens>",
+      "token budget per example, 64 through 16384 (default 12288 for SFT, 3072 for gisting)",
+      trainingMaxSequenceLength,
+    )
     .option("--prompt-file <path>", "gisting prompt text file")
     .option("--json", "print JSON", false)
     .description("create a normalized Training draft")
     .action(async (name: string, options: RawTrainingDraftOptions & { json: boolean }) => {
       const { client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       await createTraining(
         client,
         {
@@ -92,15 +110,30 @@ export const registerTrainingCommands = (program: Command, host: CommandHost): v
       "--validation-filter <field=value>",
       "replacement validation Dataset field equality filter",
     )
-    .option("--regime <regime>", "Python training regime", trainingRegime)
-    .option("--epochs <count>", "training epochs", nonNegativeInteger)
-    .option("--eval-steps <count>", "SFT eval steps", positiveInteger)
+    .option("--lora-rank <rank>", "SFT LoRA adapter rank: 8, 16, or 32 (default 16)", trainingLoraRank)
+    .option("--gist-tokens <count>", "gisting soft tokens: 8, 32, or 64 (default 32)", trainingGistTokens)
+    .option("--epochs <count>", "training epochs, 1 through 5 (default 3)", trainingEpochs)
+    .option(
+      "--learning-rate <rate>",
+      "optimizer learning rate (default 0.00015 for SFT, 0.03 for gisting)",
+      trainingLearningRate,
+    )
+    .option(
+      "--batch-size <count>",
+      "sequences per optimizer step: 8, 16, 32, or 64 (default 8)",
+      trainingBatchSize,
+    )
+    .option(
+      "--max-sequence-length <tokens>",
+      "token budget per example, 64 through 16384 (default 12288 for SFT, 3072 for gisting)",
+      trainingMaxSequenceLength,
+    )
     .option("--prompt-file <path>", "replacement gisting prompt text file")
     .option("--json", "print JSON", false)
     .description("replace the complete Training draft")
     .action(async (nameOrId: string, options: RawTrainingDraftOptions & { json: boolean }) => {
       const { client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       await updateTraining(
         client,
         {
@@ -120,7 +153,7 @@ export const registerTrainingCommands = (program: Command, host: CommandHost): v
     .description("validate Training inputs and calculate the maximum charge")
     .action(async (nameOrId: string, options: { idempotencyKey?: string; json: boolean }) => {
       const { client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       await estimateTrainingCost(
         client,
         { projectId, nameOrId, idempotencyKey: options.idempotencyKey, json: options.json },
@@ -146,7 +179,7 @@ export const registerTrainingCommands = (program: Command, host: CommandHost): v
         },
       ) => {
         const { client, projectId } = await resolveContext(globals(), context);
-        assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+        assertProjectSelected(projectId);
         await createTrainingRun(client, { projectId, nameOrId, ...options }, context.io);
       },
     );
@@ -157,7 +190,7 @@ export const registerTrainingCommands = (program: Command, host: CommandHost): v
     .description("list Training Run history")
     .action(async (nameOrId: string, options: { json: boolean }) => {
       const { client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       await listTrainingRuns(client, { projectId, nameOrId, json: options.json }, context.io);
     });
   training

package/src/cli/config.ts

@@ -1,7 +1,7 @@
-import { assert } from "es-toolkit";
 import type { TolokaState } from "../state";
 import type { StoredCredentials } from "./credentials";
 import { resolveProjectContext } from "./project-context";
+import { assertCli } from "./cli-error";
 
 export type TolokaCliFlags = {
   readonly apiKey?: string;
@@ -76,6 +76,6 @@ export function resolveTolokaConfig(
     stored,
     effectiveBaseUrl: baseUrl,
   });
-  assert(apiKey, missingApiKeyMessage);
+  assertCli(apiKey, missingApiKeyMessage, { hint: { disabled: true } });
   return { apiKey, baseUrl, ...(project === undefined ? {} : { projectId: project.id }) };
 }

package/src/cli/context.ts

@@ -30,7 +30,6 @@ export type ProgramContext = {
   readonly injectedClient?: PotatoClient;
   readonly runChecks?: typeof checkProject;
   readonly analytics?: CliAnalytics;
-  readonly internalUser?: boolean;
 };
 
 export type GlobalOptions = {
@@ -89,11 +88,52 @@ export const trainingMethod = (raw: string): "sft" | "gisting" => {
   return raw;
 };
 
-export const trainingRegime = (raw: string): "low" | "medium" | "high" => {
-  if (raw !== "low" && raw !== "medium" && raw !== "high") {
-    throw new InvalidArgumentError('Expected regime "low", "medium", or "high".');
+export const trainingLoraRank = (raw: string): 8 | 16 | 32 => {
+  const value = Number(raw);
+  if (value !== 8 && value !== 16 && value !== 32) {
+    throw new InvalidArgumentError("Expected a LoRA rank of 8, 16, or 32.");
   }
-  return raw;
+  return value;
+};
+
+export const trainingGistTokens = (raw: string): 8 | 32 | 64 => {
+  const value = Number(raw);
+  if (value !== 8 && value !== 32 && value !== 64) {
+    throw new InvalidArgumentError("Expected 8, 32, or 64 gist tokens.");
+  }
+  return value;
+};
+
+export const trainingEpochs = (raw: string): number => {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1 || value > 5) {
+    throw new InvalidArgumentError("Expected epochs from 1 through 5.");
+  }
+  return value;
+};
+
+export const trainingLearningRate = (raw: string): number => {
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new InvalidArgumentError("Expected a positive learning rate, for example 0.00015.");
+  }
+  return value;
+};
+
+export const trainingBatchSize = (raw: string): 8 | 16 | 32 | 64 => {
+  const value = Number(raw);
+  if (value !== 8 && value !== 16 && value !== 32 && value !== 64) {
+    throw new InvalidArgumentError("Expected a batch size of 8, 16, 32, or 64.");
+  }
+  return value;
+};
+
+export const trainingMaxSequenceLength = (raw: string): number => {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 64 || value > 16384) {
+    throw new InvalidArgumentError("Expected a maximum sequence length from 64 through 16384 tokens.");
+  }
+  return value;
 };
 
 export type RawTrainingDraftOptions = {
@@ -104,9 +144,12 @@ export type RawTrainingDraftOptions = {
   validationDataset?: string;
   trainFilter?: string;
   validationFilter?: string;
-  regime?: TrainingDraftOptions["regime"];
+  loraRank?: TrainingDraftOptions["loraRank"];
+  gistTokens?: TrainingDraftOptions["gistTokens"];
   epochs?: number;
-  evalSteps?: number;
+  learningRate?: number;
+  batchSize?: TrainingDraftOptions["batchSize"];
+  maxSequenceLength?: number;
   promptFile?: string;
 };
 
@@ -118,9 +161,12 @@ export const trainingDraftOptions = (options: RawTrainingDraftOptions): Training
   validationDatasetId: options.validationDataset,
   trainingFilter: options.trainFilter,
   validationFilter: options.validationFilter,
-  regime: options.regime,
+  loraRank: options.loraRank,
+  gistTokens: options.gistTokens,
   epochs: options.epochs,
-  evalSteps: options.evalSteps,
+  learningRate: options.learningRate,
+  batchSize: options.batchSize,
+  maxSequenceLength: options.maxSequenceLength,
   promptFilePath: options.promptFile,
 });
 
@@ -163,14 +209,6 @@ export const identifyClientUser = async (
   } catch {}
 };
 
-export const resolveInternalUser = async (client: PotatoClient): Promise<boolean | undefined> => {
-  try {
-    return (await client.me()).internal;
-  } catch {
-    return undefined;
-  }
-};
-
 export const resolveContext = async (
   globals: GlobalOptions,
   context: ProgramContext,

package/src/cli/credentials.ts

@@ -1,7 +1,8 @@
-import { assert } from "es-toolkit";
 import { chmod, lstat, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { assertCli, TolokaCliError } from "./cli-error";
+import type { TolokaCliErrorOptions } from "./cli-error";
 
 export type StoredProjectAlias = {
   readonly id: string;
@@ -28,8 +29,8 @@ export type CommandCredentialLookup = {
   readonly warning?: string;
 };
 
-export class CredentialsError extends Error {
-  constructor(message: string, options?: { readonly cause?: unknown }) {
+export class CredentialsError extends TolokaCliError {
+  constructor(message: string, options: TolokaCliErrorOptions) {
     super(message, options);
     this.name = "CredentialsError";
   }
@@ -168,6 +169,7 @@ export async function findStoredCredentials(
     if (primary === "invalid") {
       throw new CredentialsError(
         `Invalid credentials file at ${path}. Run toloka logout, then toloka login.`,
+        { hint: { disabled: true } },
       );
     }
     return { credentials: primary.credentials, path, legacy: false };
@@ -181,6 +183,7 @@ export async function findStoredCredentials(
   if (legacy === "invalid") {
     throw new CredentialsError(
       `Invalid credentials file at ${legacyPath}. Run toloka logout, then toloka login.`,
+      { hint: { disabled: true } },
     );
   }
   return { credentials: legacy.credentials, path: legacyPath, legacy: true };
@@ -211,6 +214,7 @@ export async function requireStoredCredentials(
   if (found !== undefined) return found;
   throw new CredentialsError(
     `No stored credentials found at ${credentialsPath(environment)}. Run toloka login.`,
+    { hint: { disabled: true } },
   );
 }
 
@@ -228,7 +232,11 @@ const serializedCredentials = (credentials: StoredCredentials): StoredCredential
 const assertNotSymbolicLink = async (path: string): Promise<void> => {
   try {
     const entry = await lstat(path);
-    assert(!entry.isSymbolicLink(), `Refusing to write through symbolic link ${path}.`);
+    assertCli(
+      !entry.isSymbolicLink(),
+      `Refusing to write through symbolic link ${path}.`,
+      { hint: { description: "Replace the symbolic link with a regular file or directory, then retry." } },
+    );
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
     throw error;

package/src/cli/data.ts

@@ -1,4 +1,3 @@
-import { assert } from "es-toolkit";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname } from "node:path";
 import type { Dataset, InferredField, PotatoClient, UploadId } from "../client";
@@ -7,18 +6,20 @@ import { generateFieldDeclarationsSource } from "../importer";
 import { readTolokaState } from "../state";
 import type { WaitForOptions } from "../wait-for";
 import { desiredDatasets } from "./project";
-import { MISSING_PROJECT_ID_MESSAGE } from "./project-context";
+import { assertProjectSelected } from "./project-context";
 import { loadProjectSource } from "./source";
 import type { ProjectSource } from "./source";
+import { assertCli, REPORT_HINT, RETRY_OR_REPORT_HINT, TolokaCliError } from "./cli-error";
+import type { TolokaCliErrorOptions } from "./cli-error";
 
 const RAW_UPLOAD_FIELD_NAME = "uploaded";
 const DATASET_ID_PATTERN =
   /^ds\.[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
 const FINALIZE_UPLOAD_ATTEMPTS = 3;
 
-class DatasetUploadError extends Error {
-  constructor(message: string, cause: unknown) {
-    super(message, { cause });
+class DatasetUploadError extends TolokaCliError {
+  constructor(message: string, options: TolokaCliErrorOptions) {
+    super(message, options);
     this.name = "DatasetUploadError";
   }
 }
@@ -171,7 +172,7 @@ const resolveLiveDataset = async (
 ): Promise<DatasetRef> => {
   const state = await readTolokaState(options.sourceRoot);
   const projectId = options.projectId ?? state?.projectId;
-  assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+  assertProjectSelected(projectId);
   const token = options.datasetName;
   const live = await collectLiveDatasets(client, projectId);
   const nameIsUnique = (name: string) =>
@@ -186,13 +187,14 @@ const resolveLiveDataset = async (
   }
 
   const byName = live.filter((dataset) => dataset.name === token);
-  assert(
+  assertCli(
     byName.length <= 1,
     `Project ${projectId} has multiple datasets named "${token}": ${byName.map(formatDatasetChoice).join(", ")}.`,
+    { hint: { description: "Pass the dataset id (ds.…) instead of the name." } },
   );
   if (byName.length === 1) {
     const [dataset] = byName;
-    assert(dataset, `Dataset "${token}" has no resolved ID.`);
+    assertCli(dataset, `Dataset "${token}" has no resolved ID.`, { hint: REPORT_HINT });
     return { datasetId: dataset.id, name: dataset.name, nameIsUnique: true };
   }
 
@@ -204,16 +206,18 @@ const resolveLiveDataset = async (
     }
   }
 
-  assert(
+  assertCli(
     createWhenMissing && datasetId === undefined,
     live.length === 0
-      ? `Dataset "${token}" does not exist in project ${projectId}. Run toloka apply first.`
+      ? `Dataset "${token}" does not exist in project ${projectId}. Run toloka dataset create ${JSON.stringify(token)} first, or toloka apply for a dataset a pipeline declares.`
       : `Dataset "${token}" does not exist in project ${projectId}. This project has: ${live.map(formatDatasetChoice).join(", ")}.`,
+    { hint: { disabled: true } },
   );
 
-  assert(
+  assertCli(
     (await declaredDatasetFields(options)).length > 0,
-    `Dataset "${token}" does not exist in project ${projectId} and no pipeline in source declares it. Bind a pipeline to it in source so its columns are known, or upload to an existing dataset.`,
+    `Dataset "${token}" does not exist in project ${projectId} and no pipeline in source declares it. Run toloka dataset create ${JSON.stringify(token)} to create it empty, bind a pipeline to it in source so its columns are known, or upload to an existing dataset.`,
+    { hint: { disabled: true } },
   );
   const created = await client.datasets.create({ projectId, name: token });
   return { datasetId: created.id, name: created.name, nameIsUnique: true };
@@ -226,7 +230,11 @@ const resolveDatasetUploadFormat = (filename: string): DatasetUploadFormat => {
   if (normalizedFilename.endsWith(".jsonl")) return "jsonl";
   if (normalizedFilename.endsWith(".csv")) return "csv";
 
-  assert(false, `${filename} must have a .json, .jsonl, or .csv extension`);
+  assertCli(
+    false,
+    `${filename} must have a .json, .jsonl, or .csv extension`,
+    { hint: { description: "Rename the file with the extension that matches its format." } },
+  );
 };
 
 const readDatasetUpload = async (filePath: string) => {
@@ -243,9 +251,17 @@ const readDatasetUpload = async (filePath: string) => {
       try {
         value = JSON.parse(line);
       } catch {
-        assert(false, `${filename}:${lineNumber} is not valid JSON`);
+        assertCli(
+          false,
+          `${filename}:${lineNumber} is not valid JSON`,
+          { hint: { description: "Fix the JSON on that line; every line of a JSONL file must be one complete object." } },
+        );
       }
-      assert(isJsonObject(value), `${filename}:${lineNumber} must contain a JSON object`);
+      assertCli(
+        isJsonObject(value),
+        `${filename}:${lineNumber} must contain a JSON object`,
+        { hint: { description: "Wrap the value in an object with named fields, one object per line." } },
+      );
     }
   }
 
@@ -265,16 +281,22 @@ const cancelStartedUpload = async (
     await client.datasets.cancelUpload({ uploadId });
   } catch (cancelError) {
     const cancelReason = cancelError instanceof Error ? cancelError.message : String(cancelError);
-    throw new AggregateError(
-      [error, cancelError],
+    throw new DatasetUploadError(
       `Dataset upload ${uploadId} failed and could not be canceled. Upload error: ${reason}. Cancellation error: ${cancelReason}.`,
+      {
+        cause: new AggregateError([error, cancelError]),
+        hint: {
+          description:
+            "Check toloka dataset list before re-running toloka dataset upload; an upload that never finalized is cleaned up automatically.",
+        },
+      },
     );
   }
 
-  throw new DatasetUploadError(
-    `Dataset upload ${uploadId} failed and was canceled: ${reason}`,
-    error,
-  );
+  throw new DatasetUploadError(`Dataset upload ${uploadId} failed and was canceled: ${reason}`, {
+    cause: error,
+    hint: { description: "Fix the upload error above, then re-run toloka dataset upload." },
+  });
 };
 
 const transferAndFinalizeUpload = async ({
@@ -310,10 +332,9 @@ const transferAndFinalizeUpload = async ({
     return cancelStartedUpload(
       client,
       started.job.id,
-      new DatasetUploadError(
-        `Dataset upload failed with HTTP ${uploadResponse.status}.`,
-        undefined,
-      ),
+      new DatasetUploadError(`Dataset upload failed with HTTP ${uploadResponse.status}.`, {
+        hint: RETRY_OR_REPORT_HINT,
+      }),
     );
   }
 
@@ -334,7 +355,7 @@ const transferAndFinalizeUpload = async ({
           started.job.id,
           new DatasetUploadError(
             `Storage remained unavailable after ${FINALIZE_UPLOAD_ATTEMPTS} finalization attempts.`,
-            error,
+            { cause: error, hint: RETRY_OR_REPORT_HINT },
           ),
         );
       }
@@ -346,6 +367,28 @@ const transferAndFinalizeUpload = async ({
   }
 };
 
+export type CreateDatasetResult = {
+  readonly datasetId: string;
+  readonly output: string;
+};
+
+export async function createDataset(
+  client: Pick<PotatoClient, "datasets">,
+  options: { readonly projectId: string; readonly name: string },
+): Promise<CreateDatasetResult> {
+  const name = options.name.trim();
+  assertCli(
+    name.length > 0,
+    "Dataset name cannot be empty.",
+    { hint: { description: "Pass a non-empty dataset name." } },
+  );
+  const created = await client.datasets.create({ projectId: options.projectId, name });
+  return {
+    datasetId: created.id,
+    output: `Created dataset ${created.name} (${created.id}). Upload rows with toloka dataset upload ${created.id} <file>.`,
+  };
+}
+
 export async function uploadDataset(
   client: PotatoClient,
   options: UploadDatasetOptions,
@@ -388,9 +431,10 @@ export async function uploadDataset(
     completed.error?.startsWith("Schema incompatible with existing upload") === true
       ? `\nRun toloka dataset fields ${JSON.stringify(fieldsHint)} to inspect the inferred schema stored from the first successful upload.`
       : "";
-  assert(
+  assertCli(
     completed.status === "succeeded",
     `${completed.error ?? `Dataset upload ${completed.id} failed.`}${compatibilityHint}`,
+    { hint: { disabled: true } },
   );
 
   const uploadedOutput = `Uploaded ${completed.result.itemsIngested} rows to dataset ${resolved.name}.`;
@@ -455,20 +499,32 @@ const downloadExportRows = async (options: {
   readonly fetch: typeof globalThis.fetch;
 }): Promise<Record<string, unknown>[]> => {
   const download = await options.fetch(options.downloadUrl);
-  assert(download.ok, `Dataset export download failed with HTTP ${download.status}.`);
+  assertCli(
+    download.ok,
+    `Dataset export download failed with HTTP ${download.status}.`,
+    { hint: RETRY_OR_REPORT_HINT },
+  );
   const text = await download.text();
   let parsed: unknown;
   try {
     parsed = JSON.parse(text);
   } catch (error) {
-    throw new Error(`Dataset export ${options.exportId} is not valid JSON.`, { cause: error });
+    throw new TolokaCliError(`Dataset export ${options.exportId} is not valid JSON.`, {
+      cause: error,
+      hint: REPORT_HINT,
+    });
   }
-  assert(Array.isArray(parsed), `Dataset export ${options.exportId} is not a JSON array.`);
+  assertCli(
+    Array.isArray(parsed),
+    `Dataset export ${options.exportId} is not a JSON array.`,
+    { hint: REPORT_HINT },
+  );
   const rows: Record<string, unknown>[] = [];
   for (const [index, element] of parsed.entries()) {
-    assert(
+    assertCli(
       isJsonObject(element),
       `Dataset export ${options.exportId} row ${index} is not a JSON object.`,
+      { hint: REPORT_HINT },
     );
     rows.push(element);
   }
@@ -485,7 +541,11 @@ export async function loadDataset(
     if (field.internal || field.name === RAW_UPLOAD_FIELD_NAME) continue;
     fieldNames.push(field.name);
   }
-  assert(fieldNames.length > 0, `Dataset ${resolved.name} has no fields to export.`);
+  assertCli(
+    fieldNames.length > 0,
+    `Dataset ${resolved.name} has no fields to export.`,
+    { hint: { description: "Upload rows first with toloka dataset upload <name> <file>." } },
+  );
 
   const started = await client.datasets.startExport({
     datasetId: resolved.datasetId,
@@ -498,16 +558,18 @@ export async function loadDataset(
       options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs },
     );
   } catch (error) {
-    assert(
+    assertCli(
       !(error instanceof PotatoApiError && error.code === "wait_timeout"),
       `Stopped waiting for dataset export ${started.id}; raise --timeout to wait longer.`,
+      { hint: { disabled: true } },
     );
     throw error;
   }
 
-  assert(
+  assertCli(
     completed.result.downloadUrl,
     `Dataset export ${completed.id} succeeded without a download URL.`,
+    { hint: REPORT_HINT },
   );
 
   const rows = await downloadExportRows({

package/src/cli/delivery-orders.ts

@@ -1,3 +1,6 @@
+import { PotatoApiError } from "../errors";
+import { TolokaCliError } from "./cli-error";
+
 export type DeliveryOrderRecord = {
   readonly id: string;
   readonly name: string;
@@ -15,7 +18,21 @@ export type DeliveryOrderListApi = {
 export async function listDeliveryOrders(options: {
   readonly client: DeliveryOrderListApi;
 }): Promise<{ readonly output: string }> {
-  const orders = await options.client.deliveryOrders.list();
+  let orders: readonly DeliveryOrderRecord[];
+  try {
+    orders = await options.client.deliveryOrders.list();
+  } catch (error) {
+    if (error instanceof PotatoApiError && error.status === 403) {
+      throw new TolokaCliError("Delivery orders are available to internal teams only.", {
+        cause: error,
+        hint: {
+          description:
+            "Run toloka whoami; when it prints Internal: false, create the project without --delivery-order-id.",
+        },
+      });
+    }
+    throw error;
+  }
   if (orders.length === 0) {
     return { output: "No delivery orders visible." };
   }

package/src/cli/file-system.ts

@@ -1,6 +1,6 @@
-import { assert } from "es-toolkit";
 import { lstat } from "node:fs/promises";
 import { join } from "node:path";
+import { assertCli } from "./cli-error";
 
 export const hasErrorCode = (error: unknown, ...codes: readonly string[]) =>
   error instanceof Error &&
@@ -29,6 +29,10 @@ export const assertSafeDestination = async (
     currentPath = join(currentPath, segment);
     const entry = await entryStats(currentPath);
     if (entry === undefined) return;
-    assert(!entry.isSymbolicLink(), `Refusing to ${action} through symbolic link ${currentPath}.`);
+    assertCli(
+      !entry.isSymbolicLink(),
+      `Refusing to ${action} through symbolic link ${currentPath}.`,
+      { hint: { description: "Replace the symbolic link with a regular directory, or point the command at the real path." } },
+    );
   }
 };