@toloka-platform/sdk 0.2.0 → 0.3.0

package/src/cli/cli-entry.ts

@@ -1,8 +1,20 @@
 import { existsSync, realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { assertCli } from "./cli-error";
+import { isNativeCli } from "./native-runtime";
 
 const CLI_ENTRY = join("bin", "toloka.js");
+export type CliRelaunchCommand = {
+  readonly executable: string;
+  readonly args: readonly string[];
+  readonly environment: NodeJS.ProcessEnv;
+};
+
+export type CliRelaunchOptions = {
+  readonly native?: boolean;
+  readonly executable?: string;
+  readonly runtimeEntry?: string;
+};
 
 const runtimePath = (entry: string): string => {
   try {
@@ -40,3 +52,22 @@ export const resolveCliEntry = (runtimeEntry: string | undefined = process.argv[
   );
   return workingDirectoryEntry;
 };
+
+export const cliRelaunchCommand = (
+  argv: readonly string[],
+  environment: NodeJS.ProcessEnv,
+  options: CliRelaunchOptions = {},
+): CliRelaunchCommand => {
+  const executable = options.executable ?? process.execPath;
+  if (!(options.native ?? isNativeCli())) {
+    return {
+      executable:
+        options.executable ?? (Reflect.get(process.versions, "bun") ? process.execPath : "bun"),
+      args: [resolveCliEntry(options.runtimeEntry), ...argv],
+      environment,
+    };
+  }
+  const reexecEnvironment = { ...environment };
+  delete reexecEnvironment.BUN_BE_BUN;
+  return { executable, args: [...argv], environment: reexecEnvironment };
+};

package/src/cli/commands/audience.ts

@@ -0,0 +1,22 @@
+import type { Command } from "commander";
+import { listSpecializations } from "../audience";
+import { resolveContext, type CommandHost } from "../context";
+
+export const registerAudienceCommands = (program: Command, host: CommandHost): void => {
+  const { context, globals } = host;
+
+  const audience = program
+    .command("audience")
+    .description("inspect the expert audience catalog used by node audience filters");
+  const specialization = audience
+    .command("specialization")
+    .description("expert specializations (platform qualifications)");
+  specialization
+    .command("list")
+    .option("--json", "print JSON", false)
+    .description("list specializations with their id, name, and expert count")
+    .action(async (options: { json: boolean }) => {
+      const { client } = await resolveContext(globals(), context);
+      await listSpecializations(client, { json: options.json }, context.io);
+    });
+};

package/src/cli/commands/auth.ts

@@ -1,56 +1,66 @@
 import type { Command } from "commander";
-import { createClient } from "../../client";
 import { authStatus, login, logout } from "../auth";
 import {
   identifyClientUser,
+  resolveClient,
   resolveSelectedProject,
   resolveSourceRoot,
   type CommandHost,
 } from "../context";
 import { findCommandCredentials, readStoredCredentials } from "../credentials";
-import { resolveTolokaConfig } from "../config";
 import { readTolokaState } from "../../state";
 
+type LoginCommandOptions = {
+  readonly apiKeyStdin: boolean;
+  readonly browser?: boolean;
+};
+
 export const registerAuthCommands = (program: Command, host: CommandHost): void => {
   const { context, exitCode, globals } = host;
 
   program
     .command("login")
-    .description("store an API key for this machine after verifying it")
-    .option("--api-key-stdin", "read the API key from standard input instead of prompting", false)
-    .action(async (options: { apiKeyStdin: boolean }) => {
+    .description("sign in through your browser, or store an API key, after verifying access")
+    .option("--browser", "sign in through your browser without asking; pick the provider on the page it opens")
+    .option("--no-browser", "the same, but print the sign-in link instead of opening a browser")
+    .option("--api-key-stdin", "store an API key read from standard input instead", false)
+    .action(async (options: LoginCommandOptions) => {
       const apiKey = options.apiKeyStdin ? (await context.io.readStdin()).trim() : globals().apiKey;
       const injectedClient = context.injectedClient;
       const result = await login({
         ...(apiKey === undefined ? {} : { apiKey }),
+        ...(options.browser === undefined ? {} : { browser: options.browser }),
         ...(globals().baseUrl === undefined ? {} : { baseUrl: globals().baseUrl }),
         ...(context.io.prompt === undefined ? {} : { prompt: context.io.prompt }),
+        ...(context.io.choose === undefined ? {} : { choose: context.io.choose }),
         ...(injectedClient === undefined ? {} : { probe: () => injectedClient }),
+        ...(context.browserLogin === undefined ? {} : { browserLogin: context.browserLogin }),
+        ...(context.io.style === undefined ? {} : { style: context.io.style }),
         write: context.io.stdout,
         environment: context.environment,
       });
       context.io.stdout(result.output);
       try {
         const stored = await readStoredCredentials(context.environment);
-        if (stored === undefined) return;
-        const client = context.injectedClient ?? createClient(stored);
+        const { client } = await resolveClient(globals(), context, undefined, stored);
         await identifyClientUser(client, context.analytics);
       } catch {}
     });
 
   program
     .command("logout")
-    .description("remove stored credentials from this machine")
+    .description("remove stored credentials from this machine and end the browser login")
     .action(async () => {
-      const result = await logout(context.environment);
+      const baseUrl = globals().baseUrl;
+      const result = await logout(context.environment, baseUrl === undefined ? {} : { baseUrl });
       context.io.stdout(result.output);
     });
 
   program
     .command("auth-status")
     .alias("whoami")
-    .description("show which platform and key the CLI would use")
-    .option("--show-token", "print the API key instead of masking it", false)
+    .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)
     .action(async (options: { showToken: boolean }) => {
       const flags = globals();
       const credentialLookup = await findCommandCredentials(
@@ -79,10 +89,7 @@ export const registerAuthCommands = (program: Command, host: CommandHost): void
         return;
       }
       try {
-        const config = resolveTolokaConfig(flags, state, context.environment, stored);
-        const client =
-          context.injectedClient ??
-          createClient({ apiKey: config.apiKey, baseUrl: config.baseUrl });
+        const { client } = await resolveClient(flags, context, state, stored);
         await identifyClientUser(client, context.analytics);
       } catch {}
     });

package/src/cli/commands/project.ts

@@ -1,7 +1,7 @@
 import type { Command } from "commander";
-import { createClient } from "../../client";
 import {
   identifyClientUser,
+  resolveClient,
   positiveInteger,
   readCommandCredentials,
   resolveContext,
@@ -42,7 +42,7 @@ export const registerProjectCommands = (program: Command, host: CommandHost): vo
     .action(async (alias?: string, projectId?: string) => {
       const flags = globals();
       const found = await requireStoredCredentials(context.environment);
-      const client = context.injectedClient ?? createClient(found.credentials);
+      const { client } = await resolveClient(flags, context, undefined, found.credentials);
       await addProject({
         environment: context.environment,
         flags,
@@ -147,7 +147,7 @@ export const registerProjectCommands = (program: Command, host: CommandHost): vo
     ) => {
       const flags = globals();
       const found = await requireStoredCredentials(context.environment);
-      const client = context.injectedClient ?? createClient(found.credentials);
+      const { client } = await resolveClient(flags, context, undefined, found.credentials);
       const sourceRoot = await resolveSourceRoot(flags, context.io);
       await createProject({
         environment: context.environment,

package/src/cli/commands/training.ts

@@ -64,7 +64,11 @@ export const registerTrainingCommands = (program: Command, host: CommandHost): v
     .option("--train-filter <field=value>", "training Dataset field equality filter")
     .option("--validation-filter <field=value>", "validation Dataset field equality filter")
     .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(
+      "--gist-tokens <count>",
+      'gisting soft tokens: 8, 32, or 64, or a fraction of the prompt "1/4", "1/8", "1/16", "1/32" (default 32)',
+      trainingGistTokens,
+    )
     .option("--epochs <count>", "training epochs, 1 through 5 (default 3)", trainingEpochs)
     .option(
       "--learning-rate <rate>",
@@ -111,7 +115,11 @@ export const registerTrainingCommands = (program: Command, host: CommandHost): v
       "replacement validation Dataset field equality filter",
     )
     .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(
+      "--gist-tokens <count>",
+      'gisting soft tokens: 8, 32, or 64, or a fraction of the prompt "1/4", "1/8", "1/16", "1/32" (default 32)',
+      trainingGistTokens,
+    )
     .option("--epochs <count>", "training epochs, 1 through 5 (default 3)", trainingEpochs)
     .option(
       "--learning-rate <rate>",

package/src/cli/config.ts

@@ -1,5 +1,6 @@
 import type { TolokaState } from "../state";
 import type { StoredCredentials } from "./credentials";
+import type { BrowserLoginProvider } from "./keycloak";
 import { resolveProjectContext } from "./project-context";
 import { assertCli } from "./cli-error";
 
@@ -15,9 +16,13 @@ export type TolokaEnvironment = Readonly<Record<string, string | undefined>> & {
   readonly TOLOKA_PROJECT_ID?: string;
 };
 
+export type CliCredential =
+  | { readonly type: "apiKey"; readonly apiKey: string }
+  | { readonly type: "browser"; readonly provider: BrowserLoginProvider };
+
 export type ResolvedTolokaConfig = {
-  readonly apiKey: string;
   readonly baseUrl: string;
+  readonly credential: CliCredential;
   readonly projectId?: string;
 };
 
@@ -34,6 +39,9 @@ export const resolveInternalBaseUrl = (environment: TolokaEnvironment): string |
 const PRODUCTION_CONSOLE_URL = "https://console.toloka.ai";
 const INTERNAL_CONSOLE_URL = "https://prestable.console.toloka-test.ai";
 
+export const registrationUrlFor = (baseUrl: string): string =>
+  new URL("/auth?redirectPath=%2Fregistration", baseUrl).href;
+
 export const consoleUrlFor = (baseUrl: string): string | undefined => {
   let host: string;
   try {
@@ -47,28 +55,41 @@ export const consoleUrlFor = (baseUrl: string): string | undefined => {
   return undefined;
 };
 
-const missingApiKeyMessage = [
-  "Missing API key. Run toloka login once to store credentials for this machine:",
+export const MISSING_CREDENTIALS_MESSAGE = [
+  "Not logged in. Run toloka login once to sign in through your browser on this machine:",
   "",
   "  toloka login",
   "",
-  "It explains how to generate an API key and where it is saved. To override per command,",
-  "pass --api-key or set TOLOKA_API_KEY. Run toloka auth-status to see what is in effect.",
+  "Automation can pass --api-key, set 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 = (
+  flags: TolokaCliFlags,
+  environment: TolokaEnvironment,
+  stored?: StoredCredentials,
+): string | undefined => flags.apiKey ?? environment.TOLOKA_API_KEY ?? stored?.apiKey;
+
+export const resolveBaseUrl = (
+  flags: TolokaCliFlags,
+  environment: TolokaEnvironment,
+  stored?: StoredCredentials,
+): string =>
+  flags.baseUrl ??
+  environment.TOLOKA_BASE_URL ??
+  resolveInternalBaseUrl(environment) ??
+  stored?.baseUrl ??
+  PRODUCTION_BASE_URL;
+
 export function resolveTolokaConfig(
   flags: TolokaCliFlags,
   state: TolokaState | undefined,
   environment: TolokaEnvironment,
   stored?: StoredCredentials,
+  browserLogin?: BrowserLoginProvider,
 ): ResolvedTolokaConfig {
-  const apiKey = flags.apiKey ?? environment.TOLOKA_API_KEY ?? stored?.apiKey;
-  const baseUrl =
-    flags.baseUrl ??
-    environment.TOLOKA_BASE_URL ??
-    resolveInternalBaseUrl(environment) ??
-    stored?.baseUrl ??
-    PRODUCTION_BASE_URL;
+  const apiKey = resolveApiKey(flags, environment, stored);
+  const baseUrl = resolveBaseUrl(flags, environment, stored);
   const project = resolveProjectContext({
     flags,
     state,
@@ -76,6 +97,12 @@ export function resolveTolokaConfig(
     stored,
     effectiveBaseUrl: baseUrl,
   });
-  assertCli(apiKey, missingApiKeyMessage, { hint: { disabled: true } });
-  return { apiKey, baseUrl, ...(project === undefined ? {} : { projectId: project.id }) };
+  const credential: CliCredential | undefined =
+    apiKey !== undefined
+      ? { type: "apiKey", apiKey }
+      : browserLogin !== undefined
+        ? { type: "browser", provider: browserLogin }
+        : undefined;
+  assertCli(credential, MISSING_CREDENTIALS_MESSAGE, { hint: { disabled: true } });
+  return { baseUrl, credential, ...(project === undefined ? {} : { projectId: project.id }) };
 }

package/src/cli/context.ts

@@ -1,14 +1,17 @@
 import { InvalidArgumentError, type Command } from "commander";
+import type { Style } from "./style";
 import { resolve } from "node:path";
 import { createClient } from "../client";
 import type { PotatoClient } from "../client";
 import { readTolokaState } from "../state";
 import type { TolokaState } from "../state";
-import type { AuthPrompt } from "./auth";
+import type { AuthChoose, AuthPrompt } from "./auth";
 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, resolveTolokaConfig } from "./config";
-import type { TolokaEnvironment } from "./config";
+import { PRODUCTION_BASE_URL, resolveApiKey, resolveBaseUrl, resolveTolokaConfig } from "./config";
+import type { ResolvedTolokaConfig, TolokaEnvironment } from "./config";
 import { findCommandCredentials } from "./credentials";
 import type { StoredCredentials } from "./credentials";
 import { resolveProjectContext } from "./project-context";
@@ -21,13 +24,16 @@ export type CliIo = {
   readonly stderr: (text: string) => void;
   readonly readStdin: () => Promise<string>;
   readonly prompt?: AuthPrompt;
+  readonly choose?: AuthChoose;
   readonly select?: (choices: readonly { name: string; value: string }[]) => Promise<string>;
+  readonly style?: Style;
 };
 
 export type ProgramContext = {
   readonly environment: TolokaEnvironment;
   readonly io: CliIo;
   readonly injectedClient?: PotatoClient;
+  readonly browserLogin?: BrowserLoginFlow;
   readonly runChecks?: typeof checkProject;
   readonly analytics?: CliAnalytics;
 };
@@ -57,7 +63,8 @@ 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 file written by toloka login",
+  "  3. the API key stored by toloka login --api-key-stdin",
+  "  4. the browser login stored by toloka login",
   `The platform defaults to ${PRODUCTION_BASE_URL}.`,
 ].join("\n");
 
@@ -96,10 +103,15 @@ export const trainingLoraRank = (raw: string): 8 | 16 | 32 => {
   return value;
 };
 
-export const trainingGistTokens = (raw: string): 8 | 32 | 64 => {
+export const trainingGistTokens = (raw: string): 8 | 32 | 64 | "1/4" | "1/8" | "1/16" | "1/32" => {
+  if (raw === "1/4" || raw === "1/8" || raw === "1/16" || raw === "1/32") {
+    return raw;
+  }
   const value = Number(raw);
   if (value !== 8 && value !== 32 && value !== 64) {
-    throw new InvalidArgumentError("Expected 8, 32, or 64 gist tokens.");
+    throw new InvalidArgumentError(
+      'Expected 8, 32, or 64 gist tokens, or a fraction of the prompt: "1/4", "1/8", "1/16", or "1/32".',
+    );
   }
   return value;
 };
@@ -209,6 +221,32 @@ export const identifyClientUser = async (
   } catch {}
 };
 
+export const resolveClient = async (
+  globals: GlobalOptions,
+  context: ProgramContext,
+  state: TolokaState | undefined,
+  stored: StoredCredentials | undefined,
+): Promise<{ readonly config: ResolvedTolokaConfig; readonly client: PotatoClient }> => {
+  const { environment } = context;
+  const browserLogin =
+    resolveApiKey(globals, environment, stored) === undefined
+      ? (await findBrowserLogin(resolveBaseUrl(globals, environment, stored), environment))?.provider
+      : undefined;
+  const config = resolveTolokaConfig(globals, state, environment, stored, browserLogin);
+  const { baseUrl, credential } = config;
+  const client =
+    context.injectedClient ??
+    createClient(
+      credential.type === "apiKey"
+        ? { baseUrl, apiKey: credential.apiKey }
+        : {
+            baseUrl,
+            accessToken: createBrowserSessionAuth({ provider: credential.provider, baseUrl, environment }),
+          },
+    );
+  return { config, client };
+};
+
 export const resolveContext = async (
   globals: GlobalOptions,
   context: ProgramContext,
@@ -216,9 +254,7 @@ export const resolveContext = async (
   const sourceRoot = await resolveSourceRoot(globals, context.io);
   const state = await readTolokaState(sourceRoot);
   const stored = await readCommandCredentials(globals, context);
-  const config = resolveTolokaConfig(globals, state, context.environment, stored);
-  const client =
-    context.injectedClient ?? createClient({ apiKey: config.apiKey, baseUrl: config.baseUrl });
+  const { config, client } = await resolveClient(globals, context, state, stored);
   await identifyClientUser(client, context.analytics);
 
   return {

package/src/cli/credentials.ts

@@ -11,7 +11,7 @@ export type StoredProjectAlias = {
 
 export type StoredCredentials = {
   readonly baseUrl: string;
-  readonly apiKey: string;
+  readonly apiKey?: string;
   readonly current?: string;
   readonly projects?: Readonly<Record<string, StoredProjectAlias>>;
 };
@@ -132,15 +132,16 @@ const asCredentials = (payload: unknown): StoredCredentials | undefined => {
   const baseUrl = readField(payload, "baseUrl");
   const apiKey = readField(payload, "apiKey");
   if (typeof baseUrl !== "string" || baseUrl.length === 0) return undefined;
-  if (typeof apiKey !== "string" || apiKey.length === 0) return undefined;
+  if (apiKey !== undefined && (typeof apiKey !== "string" || apiKey.length === 0)) return undefined;
+  const identity = apiKey === undefined ? { baseUrl } : { baseUrl, apiKey };
 
   const currentField = readField(payload, "current");
   const projectsField = readField(payload, "projects");
-  if (currentField === undefined && projectsField === undefined) return { baseUrl, apiKey };
+  if (currentField === undefined && projectsField === undefined) return identity;
 
   const registry = asProjectRegistry(projectsField, currentField);
   if (registry === undefined) return undefined;
-  return { baseUrl, apiKey, ...registry };
+  return { ...identity, ...registry };
 };
 
 export async function inspectCredentialsFile(path: string): Promise<InspectedCredentialsFile> {
@@ -223,7 +224,7 @@ const serializedCredentials = (credentials: StoredCredentials): StoredCredential
   const hasProjects = projects !== undefined && Object.keys(projects).length > 0;
   return {
     baseUrl: credentials.baseUrl,
-    apiKey: credentials.apiKey,
+    ...(credentials.apiKey === undefined ? {} : { apiKey: credentials.apiKey }),
     ...(credentials.current === undefined ? {} : { current: credentials.current }),
     ...(hasProjects ? { projects } : {}),
   };
@@ -274,18 +275,17 @@ const fileExists = async (path: string): Promise<boolean> => {
   }
 };
 
+export const storedCredentialsPaths = (environment: CliEnvironment = process.env): string[] => [
+  credentialsPath(environment),
+  ...(environment.TOLOKA_CREDENTIALS_FILE === undefined ? [legacyCredentialsPath(environment)] : []),
+];
+
 export async function clearStoredCredentials(
   environment: CliEnvironment = process.env,
 ): Promise<string[]> {
   const removed: string[] = [];
-  const paths = [
-    credentialsPath(environment),
-    ...(environment.TOLOKA_CREDENTIALS_FILE === undefined
-      ? [legacyCredentialsPath(environment)]
-      : []),
-  ];
-
-  for (const path of paths) {
+
+  for (const path of storedCredentialsPaths(environment)) {
     if (!(await fileExists(path))) continue;
     await rm(path, { force: true });
     removed.push(path);

package/src/cli/init.ts

@@ -223,7 +223,12 @@ const bindCheckout = async (
   assertCli(
     existing === undefined || existing.projectId === projectId,
     `This directory is already bound to ${existing?.projectId}.`,
-    { hint: { description: "Run toloka init without --project-id to keep the current binding, or remove toloka.json to bind another project." } },
+    {
+      hint: {
+        description:
+          "Run toloka init without --project-id to keep the current binding, or remove toloka.json to bind another project.",
+      },
+    },
   );
   if (existing !== undefined) return undefined;
   await writeTolokaState(targetRoot, { projectId, pipelines: {}, datasets: {} });
@@ -275,7 +280,7 @@ export async function initProject(
   ];
   const warning = dependencyReady
     ? undefined
-    : `Warning: ${SDK_PACKAGE_NAME} is not listed in dependencies or devDependencies in ${join(targetRoot, "package.json")}. Run \`bun add --dev ${SDK_PACKAGE_NAME}\` before using \`toloka\`, then re-run \`toloka init\`.`;
+    : `Warning: ${SDK_PACKAGE_NAME} is not listed in dependencies or devDependencies in ${join(targetRoot, "package.json")}. Install it with npm or Bun before authoring pipelines, then re-run \`toloka init\`. Training commands do not require it.`;
   return {
     targetDirectory: targetRoot,
     files,