@toloka-platform/sdk 0.11.1 → 0.11.3

package/src/cli/auth.ts

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

package/src/cli/check.ts

@@ -23,14 +23,21 @@ import {
   type TestEvidence,
   type TestEvidenceKind,
 } from "../testing/test-evidence";
+import { platformRuleIssues } from "../validate";
 import { cliRelaunchCommand } from "./cli-entry";
 import { bunSubprocessEnvironment } from "./native-runtime";
-import { API_KEY_ENVIRONMENT_NAMES } from "./environment";
+import { CREDENTIAL_ENVIRONMENT_NAMES } from "./environment";
 import { loadProjectSource, type ProjectSource } from "./source";
 import { assertCli, REPORT_HINT, TolokaCliError } from "./cli-error";
 import type { TolokaCliErrorOptions } from "./cli-error";
 
-export type CheckStatus = "passed" | "failed" | "missing" | "partial" | "infrastructure_error";
+export type CheckStatus =
+  | "passed"
+  | "failed"
+  | "missing"
+  | "partial"
+  | "warning"
+  | "infrastructure_error";
 export type CheckKind =
   | "source"
   | "project-types"
@@ -38,6 +45,7 @@ export type CheckKind =
   | "code-test"
   | "ui-test"
   | "pipeline-flow"
+  | "platform-rules"
   | "test-runner";
 
 export type CheckDiagnostic = {
@@ -276,13 +284,13 @@ const loadSourceWithoutPlatformCredentials = async (
   environment: NodeJS.ProcessEnv,
 ): Promise<ProjectSource> => {
   const targets = [process.env, environment];
-  const saved = targets.map((current) => API_KEY_ENVIRONMENT_NAMES.map((name) => current[name]));
-  for (const current of targets) for (const name of API_KEY_ENVIRONMENT_NAMES) delete current[name];
+  const saved = targets.map((current) => CREDENTIAL_ENVIRONMENT_NAMES.map((name) => current[name]));
+  for (const current of targets) for (const name of CREDENTIAL_ENVIRONMENT_NAMES) delete current[name];
   try {
     return await loadProjectSource(sourceRoot);
   } finally {
     targets.forEach((current, target) => {
-      API_KEY_ENVIRONMENT_NAMES.forEach((name, index) => {
+      CREDENTIAL_ENVIRONMENT_NAMES.forEach((name, index) => {
         const value = saved[target]?.[index];
         if (value === undefined) delete current[name];
         else current[name] = value;
@@ -504,6 +512,39 @@ const uiTypeResults = async (
   return results;
 };
 
+const platformRuleResults = (
+  source: ProjectSource,
+  selected: readonly CheckInventoryPipeline[],
+): CheckResult[] => {
+  const selectedDirectories = new Set(selected.map((pipeline) => pipeline.sourceDirectory));
+  return source.pipelines
+    .filter((pipeline) => selectedDirectories.has(pipeline.sourceDirectory))
+    .map((pipeline) => {
+      const issues = platformRuleIssues(pipeline.definition.graph);
+      return {
+        scope: "pipeline",
+        kind: "platform-rules",
+        status: issues.length === 0 ? "passed" : "warning",
+        sourceDirectory: pipeline.sourceDirectory,
+        pipelineFingerprint: pipelineFingerprint(pipeline.definition),
+        ...boundedDiagnostics(
+          issues.length === 0
+            ? []
+            : [
+                ...issues.map((issue) => ({
+                  message: `node ${issue.node}: ${issue.reason}`,
+                  severity: "warning" as const,
+                })),
+                {
+                  message: "toloka apply refuses to write this pipeline until these are fixed.",
+                  severity: "warning" as const,
+                },
+              ],
+        ),
+      };
+    });
+};
+
 const evidenceStatus = (
   evidence: readonly TestEvidence[],
 ): Pick<CheckResult, "status" | "diagnostics" | "truncatedDiagnosticCount"> => {
@@ -536,9 +577,9 @@ const evidenceStatus = (
       status: "partial",
       diagnostics: [
         {
-          message: `Hardware-backed fields not fully covered: ${[
+          message: `Hardware-backed fields not covered by a real device: ${[
             ...new Set(passing.flatMap((entry) => entry.untestedHardwareFields ?? [])),
-          ].join(", ")}`,
+          ].join(", ")}. This does not block apply; try the task on a real device before launching a run.`,
         },
       ],
     };
@@ -559,6 +600,38 @@ const evidenceFor = (
       (nodeId === undefined || entry.nodeId === nodeId),
   );
 
+const typedTestUsage: Record<TestEvidenceKind, { call: string; counts: string }> = {
+  code: { call: "test.code(pipeline, node, name, callback)", counts: "runs the node" },
+  ui: { call: "test.ui(pipeline, node, name, callback)", counts: "submits the rendered task" },
+  pipeline: { call: "test.pipeline(pipeline, name, callback)", counts: "runs the connected nodes" },
+};
+
+const coverageStatus = (
+  evidence: readonly TestEvidence[],
+  inventory: readonly CheckInventoryPipeline[],
+  pipeline: CheckInventoryPipeline,
+  kind: TestEvidenceKind,
+  nodeId?: string,
+): Pick<CheckResult, "status" | "diagnostics" | "truncatedDiagnosticCount"> => {
+  const status = evidenceStatus(evidenceFor(evidence, pipeline, kind, nodeId));
+  if (status.status !== "missing") return status;
+  const target = nodeId === undefined ? "this pipeline" : "this node";
+  const { call, counts } = typedTestUsage[kind];
+  const knownFingerprints = new Set(inventory.map((candidate) => candidate.pipelineFingerprint));
+  const strayTests = evidence.filter(
+    (entry) =>
+      entry.kind === kind &&
+      entry.status === "passed" &&
+      entry.nodeId === nodeId &&
+      !knownFingerprints.has(entry.pipelineFingerprint),
+  );
+  const message =
+    strayTests.length > 0
+      ? `Passing ${kind} tests for ${target} (${strayTests.length}) ran against a different pipeline definition than the one ${pipeline.sourceDirectory}/pipeline.ts exports and do not count. Pass that exported pipeline to the test instead of building one inside the test.`
+      : `No passing ${kind} test covers ${target}. Add ${call} with the pipeline ${pipeline.sourceDirectory}/pipeline.ts exports; it counts once it ${counts}, makes an assertion, and passes.`;
+  return { status: "missing", diagnostics: [{ message }] };
+};
+
 const coverageResults = (
   inventory: readonly CheckInventoryPipeline[],
   evidence: readonly TestEvidence[],
@@ -576,7 +649,7 @@ const coverageResults = (
         sourceDirectory: pipeline.sourceDirectory,
         pipelineFingerprint: pipeline.pipelineFingerprint,
         nodeId: node.id,
-        ...evidenceStatus(evidenceFor(evidence, pipeline, evidenceKind, node.id)),
+        ...coverageStatus(evidence, inventory, pipeline, evidenceKind, node.id),
       });
     }
     if (nodeSelector === undefined) {
@@ -585,7 +658,7 @@ const coverageResults = (
         kind: "pipeline-flow",
         sourceDirectory: pipeline.sourceDirectory,
         pipelineFingerprint: pipeline.pipelineFingerprint,
-        ...evidenceStatus(evidenceFor(evidence, pipeline, "pipeline")),
+        ...coverageStatus(evidence, inventory, pipeline, "pipeline"),
       });
     }
     return result;
@@ -596,6 +669,7 @@ const statusLabel: Record<CheckStatus, string> = {
   failed: "FAIL",
   missing: "MISSING",
   partial: "PARTIAL",
+  warning: "WARN",
   infrastructure_error: "ERROR",
 };
 
@@ -629,13 +703,7 @@ export const formatCheckResults = (results: readonly CheckResult[]): string =>
 
 const exitCodeForResults = (results: readonly CheckResult[]): 0 | 1 | 2 => {
   if (results.some((result) => result.status === "infrastructure_error")) return 2;
-  if (
-    results.some(
-      (result) =>
-        result.status === "failed" || result.status === "missing" || result.status === "partial",
-    )
-  )
-    return 1;
+  if (results.some((result) => result.status === "failed" || result.status === "missing")) return 1;
   return 0;
 };
 
@@ -693,7 +761,7 @@ export async function checkProject(
   try {
     const selectedPipeline = selected.pipelines.length === 1 ? selected.pipelines[0] : undefined;
     const checkEnvironment = { ...(options.environment ?? process.env) };
-    for (const name of API_KEY_ENVIRONMENT_NAMES) delete checkEnvironment[name];
+    for (const name of CREDENTIAL_ENVIRONMENT_NAMES) delete checkEnvironment[name];
     const environment = {
       ...checkEnvironment,
       [TEST_EVIDENCE_DIR_ENV]: evidenceDirectory,
@@ -723,6 +791,7 @@ export async function checkProject(
       ...uiResults,
       projectToolResult("test-runner", vitestRun),
       ...coverageResults(selected.pipelines, evidence, selected.nodeId),
+      ...(selected.nodeId === undefined ? platformRuleResults(source, selected.pipelines) : []),
     ]);
     const exitCode = exitCodeForResults(results);
     return {
@@ -787,6 +856,7 @@ const isCheckKind = (value: unknown): value is CheckKind =>
   value === "code-test" ||
   value === "ui-test" ||
   value === "pipeline-flow" ||
+  value === "platform-rules" ||
   value === "test-runner";
 
 const isCheckStatus = (value: unknown): value is CheckStatus =>
@@ -794,6 +864,7 @@ const isCheckStatus = (value: unknown): value is CheckStatus =>
   value === "failed" ||
   value === "missing" ||
   value === "partial" ||
+  value === "warning" ||
   value === "infrastructure_error";
 
 const parseFreshCheckDiagnostic = (value: unknown): CheckDiagnostic => {

package/src/cli/commands/auth.ts

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

package/src/cli/commands/generation-model.ts

@@ -0,0 +1,18 @@
+import type { Command } from "commander";
+import { resolveContext, type CommandHost } from "../context";
+import { listGenerationModels } from "../generation-models";
+
+export const registerGenerationModelCommands = (program: Command, host: CommandHost): void => {
+  const { context, globals } = host;
+
+  program
+    .command("generation-model")
+    .description("inspect the models synthetic generation nodes can use")
+    .command("list")
+    .option("--json", "print JSON", false)
+    .description("list generation models with reasoning efforts and maxCostPerAttempt bounds")
+    .action(async (options: { json: boolean }) => {
+      const { client } = await resolveContext(globals(), context);
+      await listGenerationModels(client, { json: options.json }, context.io);
+    });
+};

package/src/cli/commands/pipeline.ts

@@ -38,7 +38,7 @@ export const registerPipelineCommands = (program: Command, host: CommandHost): v
     .argument("[name]", pipelineNameHelp)
     .option("--wait", "wait for the run to reach a terminal state", false)
     .option("--timeout <ms>", "how long to wait", positiveInteger)
-    .description("start a run on a deployed pipeline")
+    .description("start a run on an applied pipeline")
     .action(async (name: string | undefined, options: { wait: boolean; timeout?: number }) => {
       const { client, state, projectId } = await resolveContext(globals(), context);
       assertProjectSelected(projectId);

package/src/cli/commands/project.ts

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

package/src/cli/commands/source.ts

@@ -14,6 +14,9 @@ import { applyProject, importProject, planProject, validateProject } from "../pr
 import { assertProjectSelected, resolveProjectContext } from "../project-context";
 import { readTolokaState } from "../../state";
 import { assertCli, REPORT_HINT } from "../cli-error";
+import { writeOutput } from "../table";
+
+const VALIDATE_WAIT = { timeoutMs: 5 * 60_000, pollIntervalMs: 5_000 };
 
 const runChecksInterruptibly = async (
   options: CheckProjectOptions,
@@ -88,24 +91,32 @@ export const registerSourceCommands = (program: Command, host: CommandHost): voi
 
   program
     .command("plan")
+    .option("--json", "print the planned changes and missing secrets as JSON", false)
     .description("show what apply would change")
-    .action(async () => {
+    .action(async (options: { json: boolean }) => {
       const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
       const result = await planProject(client, {
         sourceRoot,
         ...(projectId === undefined ? {} : { projectId }),
       });
-      context.io.stdout(result.output);
+      writeOutput(
+        context.io,
+        options.json,
+        { changes: result.changes, missingSecrets: result.missingSecrets },
+        result.output,
+      );
     });
 
   program
     .command("validate")
+    .option("--wait", "wait up to 5 minutes for running lints and checks to finish", false)
     .description("run platform spec validation and report matching checks")
-    .action(async () => {
+    .action(async (options: { wait: boolean }) => {
       const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
       const result = await validateProject(client, {
         sourceRoot,
         ...(projectId === undefined ? {} : { projectId }),
+        ...(options.wait ? { wait: VALIDATE_WAIT } : {}),
       });
       context.io.stdout(result.output);
       if (!result.valid) exitCode.value = 1;

package/src/cli/commands/ui.ts

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

package/src/cli/config.ts

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

package/src/cli/context.ts

@@ -10,8 +10,14 @@ import type { CliAnalytics } from "./analytics";
 import type { BrowserLoginFlow } from "./browser-login";
 import { createBrowserSessionAuth, findBrowserLogin } from "./browser-session";
 import type { checkProject } from "./check";
-import { PRODUCTION_BASE_URL, resolveApiKey, resolveBaseUrl, resolveTolokaConfig } from "./config";
-import type { ResolvedTolokaConfig, TolokaEnvironment } from "./config";
+import type { DescribeTaskUiComponents } from "../testing/task-ui-browser";
+import {
+  PRODUCTION_BASE_URL,
+  resolveBaseUrl,
+  resolveConfiguredCredential,
+  resolveTolokaConfig,
+} from "./config";
+import type { CliCredential, ResolvedTolokaConfig, TolokaEnvironment } from "./config";
 import { findCommandCredentials } from "./credentials";
 import type { StoredCredentials } from "./credentials";
 import { resolveProjectContext } from "./project-context";
@@ -36,6 +42,7 @@ export type ProgramContext = {
   readonly browserLogin?: BrowserLoginFlow;
   readonly runChecks?: typeof checkProject;
   readonly analytics?: CliAnalytics;
+  readonly taskUiComponents?: DescribeTaskUiComponents;
 };
 
 export type GlobalOptions = {
@@ -54,6 +61,7 @@ export type Resolved = {
   readonly sourceRoot: string;
   readonly client: PotatoClient;
   readonly baseUrl: string;
+  readonly credential: CliCredential;
   readonly state: TolokaState | undefined;
   readonly stored: StoredCredentials | undefined;
   readonly projectId?: string;
@@ -61,10 +69,11 @@ export type Resolved = {
 
 export const CREDENTIAL_PRECEDENCE = [
   "Credentials resolve in this order, highest first:",
-  "  1. --api-key / --base-url",
-  "  2. TOLOKA_API_KEY / TOLOKA_BASE_URL",
-  "  3. the API key stored by toloka login --api-key-stdin",
-  "  4. the browser login stored by toloka login",
+  "  1. --api-key",
+  "  2. TOLOKA_SCOPED_TOKEN",
+  "  3. TOLOKA_API_KEY",
+  "  4. the API key stored by toloka login --api-key-stdin",
+  "  5. the browser login stored by toloka login",
   `The platform defaults to ${PRODUCTION_BASE_URL}.`,
 ].join("\n");
 
@@ -205,7 +214,9 @@ export const resolveInitRoot = (globals: GlobalOptions): string =>
 export const readCommandCredentials = async (globals: GlobalOptions, context: ProgramContext) => {
   const { found, warning } = await findCommandCredentials(
     context.environment,
-    globals.apiKey ?? context.environment.TOLOKA_API_KEY,
+    globals.apiKey ??
+      context.environment.TOLOKA_SCOPED_TOKEN ??
+      context.environment.TOLOKA_API_KEY,
   );
   if (warning !== undefined) context.io.stderr(warning);
   return found?.credentials;
@@ -229,7 +240,7 @@ export const resolveClient = async (
 ): Promise<{ readonly config: ResolvedTolokaConfig; readonly client: PotatoClient }> => {
   const { environment } = context;
   const browserLogin =
-    resolveApiKey(globals, environment, stored) === undefined
+    resolveConfiguredCredential(globals, environment, stored) === undefined
       ? (await findBrowserLogin(resolveBaseUrl(globals, environment, stored), environment))?.provider
       : undefined;
   const config = resolveTolokaConfig(globals, state, environment, stored, browserLogin);
@@ -239,10 +250,16 @@ export const resolveClient = async (
     createClient(
       credential.type === "apiKey"
         ? { baseUrl, apiKey: credential.apiKey }
-        : {
-            baseUrl,
-            accessToken: createBrowserSessionAuth({ provider: credential.provider, baseUrl, environment }),
-          },
+        : credential.type === "scopedToken"
+          ? { baseUrl, scopedToken: credential.scopedToken }
+          : {
+              baseUrl,
+              accessToken: createBrowserSessionAuth({
+                provider: credential.provider,
+                baseUrl,
+                environment,
+              }),
+            },
     );
   return { config, client };
 };
@@ -261,6 +278,7 @@ export const resolveContext = async (
     sourceRoot,
     client,
     baseUrl: config.baseUrl,
+    credential: config.credential,
     state,
     stored,
     ...(config.projectId === undefined ? {} : { projectId: config.projectId }),

package/src/cli/credentials.ts

@@ -192,12 +192,12 @@ export async function findStoredCredentials(
 
 export async function findCommandCredentials(
   environment: CliEnvironment,
-  overrideApiKey: string | undefined,
+  overrideCredential: string | undefined,
 ): Promise<CommandCredentialLookup> {
   try {
     return { found: await findStoredCredentials(environment) };
   } catch (error) {
-    if (!(error instanceof CredentialsError) || overrideApiKey === undefined) throw error;
+    if (!(error instanceof CredentialsError) || overrideCredential === undefined) throw error;
     return { found: undefined, warning: error.message };
   }
 }

package/src/cli/environment.ts

@@ -6,7 +6,11 @@ const LEGACY_ENVIRONMENT_NAMES: Readonly<Record<string, string>> = {
   POTATO_PROJECT_ID: "TOLOKA_PROJECT_ID",
 };
 
-export const API_KEY_ENVIRONMENT_NAMES = ["TOLOKA_API_KEY", "POTATO_API_KEY"];
+export const CREDENTIAL_ENVIRONMENT_NAMES = [
+  "TOLOKA_SCOPED_TOKEN",
+  "TOLOKA_API_KEY",
+  "POTATO_API_KEY",
+];
 
 export type NormalizedEnvironment = {
   readonly environment: TolokaEnvironment;