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

package/skills/toloka-gisting/SKILL.md

@@ -5,72 +5,162 @@ description: Create, estimate, start, monitor, and verify a project-owned prompt
 
 # Compress a prompt with gisting
 
-Use this skill for prompt gisting. For the full first-time agent sequence, read `https://platform.toloka.ai/agents/gisting.md`.
+## Mission
 
-## Rules
+Help the user learn a compact representation of their static prompt from representative example conversations while preserving the exact prompt and their model, data, quality, latency, and budget constraints. Match the work to the requested outcome: inspect an existing Training or run, prepare a draft, calculate an estimate, start an approved run, monitor it, or retrieve its output. Do not create resources or start a run merely because they appear later in this reference.
+
+For first-time setup details, read `https://platform.toloka.ai/agents/gisting.md`.
+
+## Domain model
+
+- **Prompt gisting** learns soft prompt tokens that stand in for a static instruction prompt. Training examples should contain the dynamic inputs and desired assistant responses; do not repeat the static prompt in every user message.
+- A **Training** is an editable project-owned draft. A **Training Run** is one immutable, billable execution of a frozen draft, prompt, and Dataset selections.
+- A run can start from a catalog **Base Model** or an exact existing **Model Version**. An explicit Model Version is the source; do not also select a Base Model.
+- A completed run publishes a durable Model Version. It does not prove deployment or inference readiness.
+- Training and validation are data roles, not file-layout rules. Separate Datasets and disjoint top-level filters are both valid. Without a validation selection, the provider reserves 10% of the training rows as a holdout.
+
+## Working posture
+
+- Inspect the user's request and current CLI, project, Training, Dataset, prompt, and run state before changing anything. The process below is a dependency map: skip satisfied or irrelevant work and stop when the requested outcome is complete.
+- Honor explicit choices first. If a requested project, source, Dataset, prompt, or configuration is incompatible, explain the evidence and tradeoff before proposing a substitute.
+- Make routine reversible choices and briefly explain them. Ask a focused question only for material ambiguity, missing authorization or inputs, conflicting constraints, or destructive or out-of-scope changes.
+- If the goal is weight adaptation from labeled conversations or data labeling rather than prompt compression, explain the distinction and route to `toloka-fine-tuning` or `toloka-build`; never silently change the method.
+
+## Safety
 
 - Never ask for an API key in chat; the user enters it through `toloka login`.
-- Never invent project, Dataset, Base Model, Training, Model, Model Version, price, prompt, or run IDs.
-- Use authorized project Datasets containing representative examples. Keep production data out of source control.
-- The prompt file must be non-empty UTF-8 text no larger than 256 KiB.
-- Prefer a separate validation Dataset. Without one, the provider holds out 10% of training rows.
-- Do not start a Training Run before the user approves the ready estimate's `maximumCharge`.
-- Use `--model-version` only for an existing Model Version source.
-- Keep polling bounded and report terminal state only when the CLI shows it.
-
-## Workflow
-
-1. Verify `bun --version`, `toloka --version`, `toloka whoami`, and `toloka project current`.
-2. Inspect the exact training Dataset ID supplied by the user:
-   ```sh
-   toloka dataset fields <training-dataset-id>
-   ```
-3. Ask the user for an absolute prompt-file path and validate that it is non-empty UTF-8 text within the size limit.
-4. Verify the supplied Base Model ID or existing Model Version source:
-   ```sh
-   toloka base-model get <base-model-id>
-   ```
-5. Ask the user to choose the source, training Dataset, optional validation Dataset, prompt file, and Training name.
-6. Create the normalized gisting Training:
-   ```sh
-   toloka training create "<training-name>" \
-     --method gisting \
-     --prompt-file <absolute-prompt-path> \
-     --base-model <base-model-id> \
-     --dataset <training-dataset-id> \
-     --validation-dataset <validation-dataset-id> \
-     --json
-   ```
-   Omit `--validation-dataset` when the user chooses provider holdout. Use `--model-version <model-version-id>` instead of `--base-model` for an existing Model Version source.
-7. Verify the draft:
-   ```sh
-   toloka training get <training-id> --json
-   ```
-8. Calculate a ready estimate to an absolute path:
-   ```sh
-   toloka training cost <training-id> --json > <absolute-estimate-file>
-   ```
-   Report rows, tokens, maximum GPU seconds, `maximumCharge`, currency, and fingerprint. Fix every blocked issue and recalculate after changing inputs.
-9. Ask the user to approve the exact `maximumCharge`. After approval, start one run:
-   ```sh
-   toloka training run <training-id> \
-     --estimate-file <absolute-estimate-file> \
-     --version-name <unique-version-name> \
-     --json
-   ```
-   Both flags are optional. Without `--estimate-file`, `training run` calculates a fresh ready estimate itself; without `--version-name`, the Model Version takes the Training name. Passing the approved estimate prevents a fresh quote from replacing the reviewed one.
-10. Monitor with bounded commands:
-    ```sh
-    toloka training status <training-run-id> --json
-    toloka training logs <training-run-id>
-    toloka training metrics <training-run-id> --json
-    ```
-    Resume only after the user confirms a billing block is resolved. Cancel only on explicit request.
-11. When completed, verify the output Model and Model Version, then download if requested:
-    ```sh
-    toloka training get <training-id> --json
-    toloka model get <model-id> --json
-    toloka model version download <model-version-id> --out <absolute-output-directory>
-    ```
-
-A completed Training Run produces a durable Model Version. It does not prove deployment or inference readiness.
+- Never invent project, Dataset, Base Model, Training, Model, Model Version, prompt, price, or run IDs. Read identity and source metadata from the CLI.
+- Use only authorized project Datasets containing representative examples. Keep credentials and production data out of source control and agent messages.
+- The prompt file must be non-empty UTF-8 text no larger than 256 KiB. Preserve user-provided prompt text exactly unless they ask to edit it; when the prompt is supplied in chat, materialize that exact text instead of inventing missing intent.
+- Preserve train/validation separation and avoid duplicate or near-duplicate examples across roles.
+- Never start a Training Run before the user approves the ready estimate's exact `maximumCharge`.
+- Keep polling bounded. Report terminal state only when the CLI shows it, and report timeouts as still running.
+
+## Process
+
+### 1. Establish only the context the goal needs
+
+When runtime, authentication, or binding is unknown, inspect it:
+
+```sh
+bun --version
+toloka --version
+toloka whoami
+toloka project current
+```
+
+Reuse an authenticated, compatible workspace. For an inspection request, inspect existing resources rather than creating a project, Dataset, Training, prompt file, or run.
+
+Use the project the user explicitly requested. Otherwise keep the current binding when it is consistent with the task. If no suitable project is bound and the requested work needs one, inspect `toloka project list --limit 20`, then create a task-named project or register the exact existing project the user identified. Do not silently select an unrelated project or rebind an existing checkout; use an explicit `--project-id` or a separate source root when working against another project without changing the binding.
+
+### 2. Inspect and assign data roles
+
+```sh
+toloka dataset list
+toloka dataset fields <dataset-name-or-id>
+```
+
+Use the user's authorized data and existing role assignments. If local JSONL files must be uploaded, organize Datasets by training and validation role, not automatically by file. `dataset upload` appends, so compatible files for one role can share a Dataset:
+
+```sh
+toloka dataset create <role-dataset-name>
+toloka dataset upload <role-dataset-name> <absolute-jsonl-path>
+toloka dataset fields <role-dataset-name>
+```
+
+CLI uploads to an otherwise undeclared Dataset store each row whole. A nested `split` value in that uploaded object is not a top-level Dataset field and cannot be used by `--train-filter` or `--validation-filter`. In that case, use separate role Datasets or omit validation flags and use the provider's 10% holdout. Existing Datasets with a real top-level split field can use disjoint filters. Never use overlapping selections or mix a supplied validation set back into training.
+
+Check that the examples demonstrate the desired behavior under the prompt: dynamic input in user messages, target output in the final assistant message, representative edge cases, and no prompt or answer leakage across validation.
+
+### 3. Preserve the prompt and choose the source
+
+Confirm the prompt path contains non-empty UTF-8 text within 256 KiB. Use the supplied file as-is. If the user supplied prompt text in the request instead, write that exact text to a UTF-8 file. Ask only when the required prompt or its intended boundaries are genuinely missing; do not author a replacement prompt from assumptions.
+
+Explicit source choices take precedence. An existing Model Version bypasses Base Model selection.
+
+Gisting supports only `qwen3-4b` and `qwen3-8b` because it publishes full model weights. This restriction also applies to the underlying Base Model of an existing Model Version. Unsupported tiers are rejected when creating or updating a Training draft; explain the constraint rather than silently substituting a model.
+
+```sh
+toloka base-model list --json
+toloka base-model get <base-model-id> --json
+toloka model list --json
+toloka model get <model-id> --json
+toloka model versions <model-id> --json
+```
+
+For a Base Model, compare available evidence about prompt and language fit, prior quality, data volume, desired compression fidelity, training budget, and serving latency or deployment constraints. Model size alone is not a quality decision; a smaller model is a useful cost and latency baseline when the task permits it, not a mandatory default. Verify the selected catalog ID, upstream model, and pinned revision with `base-model get`, and consult upstream documentation or user-provided evidence for capabilities the catalog does not expose.
+
+For a Model Version, verify the exact ID and revision under its project-owned Model, and record the owning Model's Base Model and the Version's runtime base from JSON. If those identities conflict, report the conflict rather than guessing or substituting. Use `--model-version` only for that existing version. The ready cost estimate is the concrete final check that the source type, underlying Base Model, method, prompt, and data are supported together.
+
+### 4. Reuse or create the draft
+
+Inspect before creating another Training:
+
+```sh
+toloka training list --json
+toloka training get <training-id> --json
+```
+
+When a new draft is needed, use a descriptive name and create normalized gisting configuration:
+
+```sh
+toloka training create "<training-name>" \
+  --method gisting \
+  --prompt-file <absolute-prompt-path> \
+  --base-model <base-model-id> \
+  --dataset <training-dataset-id> \
+  --validation-dataset <validation-dataset-id> \
+  --json
+```
+
+Omit `--validation-dataset` when no separate validation selection exists so the provider uses its 10% holdout. For disjoint selections in a Dataset with top-level fields, add `--train-filter <field>=<value>` and `--validation-filter <field>=<value>`. For an existing Model Version source, replace `--base-model` with `--model-version <model-version-id>`.
+
+Preserve requested hyperparameters. The current CLI uses `--gist-tokens 8|32|64` (default 32), `--epochs 1..5` (default 3), `--learning-rate` within 0.001–0.3 (default 0.03), `--batch-size 8|16|32|64` (default 8), and `--max-sequence-length 64..16384` (default 3072), rather than `regime`. Use defaults when suitable; 8 gist tokens favor compression for simple prompts, while 64 may help when 32 loses holdout accuracy. Choose sequence length from actual examples within the supported limit. `--lora-rank` is rejected for gisting. `training update <name-or-id>` takes the same flags except `--method`; omitted flags retain current values.
+
+Verify the saved method, exact source, prompt file, selections, filters, and configuration with `toloka training get <training-id> --json`.
+
+### 5. Validate and estimate
+
+```sh
+toloka training cost <training-id> --json > <absolute-estimate-file>
+```
+
+A blocked estimate exits 1, leaves the redirected file empty, and prints `Training cannot run with these inputs:` followed by one `- <message>` line per issue on stderr. Report every issue, correct the cause, and calculate a new estimate.
+
+For a duration issue, use the reported rows, tokens, epochs, GPU count, and wall time to compare supported options. Gisting publishes full model weights, so only `qwen3-4b` and `qwen3-8b` are supported; switching to the larger 8-GPU tiers is not a valid workaround. Reducing rows can weaken coverage and reducing epochs can weaken compression quality. Do not silently change the requested model, discard data, or alter epochs merely to make the estimate pass. Explain the tradeoff, obtain direction when material, update the draft, re-estimate, and obtain approval for the new quote.
+
+For a ready estimate, report the source, prompt, and selections, training and validation row counts, token totals, maximum GPU seconds, `maximumCharge`, currency, and fingerprint. If the user asked only for an estimate, stop here.
+
+### 6. Run only after explicit cost approval
+
+Ask the user to approve the exact ready `maximumCharge`. After approval, start only the requested run and pass the approved file so a new unseen quote cannot replace it:
+
+```sh
+toloka training run <training-id> \
+  --estimate-file <absolute-estimate-file> \
+  --version-name <unique-version-name> \
+  --json
+```
+
+Both flags are optional at the CLI level. Without `--estimate-file`, `training run` calculates a fresh ready estimate; do not use that path when the user approved a saved quote. Without `--version-name`, the Model Version takes the Training name.
+
+Monitor only as far as the user requested, with bounded commands:
+
+```sh
+toloka training status <training-run-id> --json
+toloka training logs <training-run-id>
+toloka training metrics <training-run-id> --json
+```
+
+Resume only after the user confirms a billing block is resolved. Cancel only on explicit request.
+
+For a completed run, verify the observed output and download only when requested:
+
+```sh
+toloka training get <training-id> --json
+toloka model get <model-id> --json
+toloka model versions <model-id> --json
+toloka model version download <model-version-id> --out <absolute-output-directory>
+```
+
+The downloaded folder contains full model weights (`config.json` and `model-*.safetensors`) and tokenizer files, including supported text sidecars such as `merges.txt` and `chat_template.jinja`. Keep the files together. The learned prompt is represented by `<|gist_…|>` tokens that prefix requests in place of the original prompt. Verify serving separately with a compatible runtime; a successful download alone does not establish inference readiness.

package/src/cli/analytics.ts

@@ -1,14 +1,15 @@
-import { assert } from "es-toolkit";
 import { randomUUID } from "node:crypto";
 import { chmod, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { PostHog } from "posthog-node";
-import { PipelineGraphValidationError, PotatoApiError } from "../errors";
+import { PipelineGraphValidationError } from "../errors";
 import type { TolokaEnvironment } from "./config";
 import type { CliEnvironment } from "./credentials";
 import { credentialsPath, preparePrivateFilePath } from "./credentials";
 import { isFalseyFlag, isTruthyFlag } from "./boolean-flag";
 import { SDK_VERSION } from "./sdk-version";
+import { assertCli, TolokaCliError } from "./cli-error";
+import { findPotatoApiError } from "./format-error";
 
 export const POSTHOG_PROJECT_KEY = "phc_kqHt0f53B5MVqURyzWpW1aNlbOmYt1YbUYza0JPcg19";
 export const POSTHOG_HOST = "https://eu.posthog.com";
@@ -77,7 +78,9 @@ export function telemetryEnabled(environment: CliEnvironment): boolean {
   return true;
 }
 
-const COMMAND_GROUPS: Readonly<Record<string, Readonly<Record<string, true>>>> = {
+type CommandGroup = Readonly<Record<string, true | Readonly<Record<string, true>>>>;
+
+const COMMAND_GROUPS: Readonly<Record<string, CommandGroup>> = {
   project: { list: true, add: true, switch: true, current: true, remove: true, create: true },
   pipeline: {
     list: true,
@@ -88,8 +91,31 @@ const COMMAND_GROUPS: Readonly<Record<string, Readonly<Record<string, true>>>> =
     cancel: true,
     results: true,
   },
-  dataset: { list: true, fields: true, load: true, upload: true },
+  dataset: { list: true, create: true, fields: true, load: true, upload: true },
   "delivery-order": { list: true },
+  training: {
+    list: true,
+    get: true,
+    create: true,
+    update: true,
+    cost: true,
+    run: true,
+    runs: true,
+    status: true,
+    resume: true,
+    cancel: true,
+    metrics: true,
+    logs: true,
+  },
+  "base-model": { list: true, get: true },
+  model: {
+    list: true,
+    get: true,
+    versions: true,
+    create: true,
+    archive: true,
+    version: { download: true },
+  },
   secret: { set: true },
   skill: { list: true, search: true, install: true },
   config: { get: true, set: true },
@@ -121,9 +147,13 @@ const nameFromTokens = (tokens: readonly string[]): string => {
   if (subcommands === undefined) return ROOT_COMMANDS[command] === true ? command : "unknown";
 
   const subcommand = tokens[1];
-  return subcommand !== undefined && subcommands[subcommand] === true
-    ? `${command} ${subcommand}`
-    : command;
+  const nested = subcommand === undefined ? undefined : subcommands[subcommand];
+  if (nested === undefined) return command;
+  if (nested === true) return `${command} ${subcommand}`;
+  const leaf = tokens[2];
+  return leaf !== undefined && nested[leaf] === true
+    ? `${command} ${subcommand} ${leaf}`
+    : `${command} ${subcommand}`;
 };
 
 export function commandNameFromArgv(argv: readonly string[]): string {
@@ -142,19 +172,6 @@ export function commandNameFromArgv(argv: readonly string[]): string {
   return nameFromTokens(tokens);
 }
 
-const findPotatoApiError = (error: unknown): PotatoApiError | undefined => {
-  if (error instanceof PotatoApiError) return error;
-
-  if (error instanceof AggregateError) {
-    for (const nested of error.errors) {
-      const apiError = findPotatoApiError(nested);
-      if (apiError !== undefined) return apiError;
-    }
-  }
-
-  return error instanceof Error ? findPotatoApiError(error.cause) : undefined;
-};
-
 export function classifyCliError(error: unknown): { readonly error_code: string } {
   if (error === undefined) return { error_code: "command_failed" };
   const apiError = findPotatoApiError(error);
@@ -197,7 +214,11 @@ const noopAnalytics = (): CliAnalytics => ({
   identifyCurrentUser() {},
   captureCommand() {},
   async submitIssueReport() {
-    assert(false, "Issue reporting is disabled. Re-run with TOLOKA_TELEMETRY=1.");
+    assertCli(
+      false,
+      "Issue reporting is disabled. Re-run with TOLOKA_TELEMETRY=1.",
+      { hint: { disabled: true } },
+    );
   },
   async shutdown() {},
 });
@@ -270,7 +291,9 @@ export function createCliAnalytics(options: {
             const errorProperties = cliErrorProperties(event.error);
 
             if (event.error !== undefined) {
-              const exception = new Error(`CLI command failed: ${classified.error_code}`);
+              const exception = new TolokaCliError(`CLI command failed: ${classified.error_code}`, {
+                hint: { disabled: true },
+              });
               exception.name = "PotatoCliError";
               client.captureException(exception, distinctId, {
                 ...shared,
@@ -316,7 +339,11 @@ export function createCliAnalytics(options: {
     },
     submitIssueReport(report) {
       const submission = queue.then(async () => {
-        assert(client && distinctId, "PostHog issue reporting could not be initialized.");
+        assertCli(
+          client && distinctId,
+          "PostHog issue reporting could not be initialized.",
+          { hint: { description: "Set TOLOKA_TELEMETRY=1 and check that this machine can reach PostHog, then retry." } },
+        );
         deliveryErrors.length = 0;
         client.capture({
           distinctId,

package/src/cli/auth.ts

@@ -1,4 +1,3 @@
-import { assert } from "es-toolkit";
 import { createClient } from "../client";
 import { PotatoApiError } from "../errors";
 import { PRODUCTION_BASE_URL, consoleUrlFor, resolveInternalBaseUrl } from "./config";
@@ -19,6 +18,7 @@ import type {
 } from "./credentials";
 import type { ProjectContext } from "./project-context";
 import { formatProjectContextLine } from "./project-context";
+import { assertCli, TolokaCliError } from "./cli-error";
 
 type ProbeFailureKind = "rejected" | "unreachable" | "platform";
 
@@ -89,7 +89,14 @@ export type AuthProbe = {
       readonly pagination: { readonly total: number };
     }>;
   };
-  readonly me?: () => Promise<{ readonly internal: boolean }>;
+  readonly me?: () => Promise<{
+    readonly internal: boolean;
+    readonly teams?: ReadonlyArray<{
+      readonly id: string;
+      readonly writable: boolean;
+      readonly internal?: boolean;
+    }>;
+  }>;
 };
 
 export type LoginOptions = {
@@ -119,14 +126,19 @@ export async function login(options: LoginOptions = {}): Promise<LoginResult> {
 
   let apiKey = options.apiKey ?? environment.TOLOKA_API_KEY;
   if (apiKey === undefined) {
-    assert(
+    assertCli(
       options.prompt,
       "Missing API key. Without a terminal, pipe the key to toloka login --api-key-stdin, pass --api-key, or set TOLOKA_API_KEY.",
+      { hint: { disabled: true } },
     );
     write(`\n${apiKeyInstructions(baseUrl)}\n`);
     apiKey = (await options.prompt("API key: ", { mask: true })).trim();
   }
-  assert(apiKey.length > 0, "No API key entered.");
+  assertCli(
+    apiKey.length > 0,
+    "No API key entered.",
+    { hint: { description: "Re-run toloka login and paste the key at the prompt, or pass --api-key." } },
+  );
   const credentials: StoredCredentials = { baseUrl, apiKey };
   const probe: AuthProbe = options.probe?.(credentials) ?? createClient(credentials);
 
@@ -136,13 +148,13 @@ export async function login(options: LoginOptions = {}): Promise<LoginResult> {
     reachable = `Authenticated against ${baseUrl}: ${page.pagination.total} project(s) visible.`;
   } catch (error) {
     const failure = classifyProbeFailure(error);
-    throw new Error(
+    throw new TolokaCliError(
       [
         `Could not authenticate against ${baseUrl}: ${failure.reason}`,
         "",
         `Nothing was saved. ${LOGIN_FAILURE_ADVICE[failure.kind](baseUrl)}`,
       ].join("\n"),
-      { cause: error },
+      { cause: error, hint: { disabled: true } },
     );
   }
 
@@ -249,13 +261,21 @@ const resolvePlatform = (
   );
 };
 
-const internalStatusLine = async (probe: AuthProbe): Promise<string | undefined> => {
-  if (probe.me === undefined) return undefined;
+const accountLines = async (probe: AuthProbe): Promise<readonly string[]> => {
+  if (probe.me === undefined) return [];
   try {
     const me = await probe.me();
-    return `Internal: ${me.internal}`;
+    if (me.teams === undefined) return [`Internal: ${me.internal}`];
+    const teams = me.teams.map((team) => {
+      const qualifiers = [...(team.internal ? ["internal"] : []), ...(team.writable ? [] : ["read-only"])];
+      return qualifiers.length === 0 ? team.id : `${team.id} (${qualifiers.join(", ")})`;
+    });
+    return [
+      `Internal: ${me.internal}`,
+      `Teams:    ${teams.length === 0 ? "(none)" : teams.join(", ")}`,
+    ];
   } catch {
-    return undefined;
+    return [];
   }
 };
 
@@ -306,8 +326,7 @@ export async function authStatus(options: AuthStatusOptions = {}): Promise<AuthS
   try {
     const page = await probe.projects.listPage({ limit: 1 });
     lines.push("", `Reachable: ${page.pagination.total} project(s) visible.`);
-    const internalLine = await internalStatusLine(probe);
-    if (internalLine !== undefined) lines.push(internalLine);
+    lines.push(...(await accountLines(probe)));
     return { authenticated: true, output: lines.join("\n") };
   } catch (error) {
     const failure = classifyProbeFailure(error);

package/src/cli/auto-update.ts

@@ -17,6 +17,8 @@ import { commandNameFromArgv } from "./analytics";
 import { readCliSettings } from "./settings";
 import { CHECK_RESULT_FILE_ENV } from "./check";
 import { isFalseyFlag, isTruthyFlag } from "./boolean-flag";
+import { TolokaCliError } from "./cli-error";
+import { formatCliError } from "./format-error";
 
 export const AUTO_UPDATE_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export const AUTO_UPDATE_QUARANTINE_MS = 24 * 60 * 60 * 1000;
@@ -199,9 +201,9 @@ const collectOutput = async (stream: NodeJS.ReadableStream | null): Promise<stri
   return Buffer.concat(chunks).toString("utf8");
 };
 
-class RegistryError extends Error {
+class RegistryError extends TolokaCliError {
   constructor(message: string) {
-    super(message);
+    super(message, { hint: { disabled: true } });
     this.name = "RegistryError";
   }
 }
@@ -239,10 +241,16 @@ const defaultInstall: AutoUpdateInstall = async ({
   const exitCode = close[0];
   if (exitCode === 0) return;
   const detail = [stderr.trim(), stdout.trim()].filter((part) => part.length > 0).join("\n");
-  throw new Error(
+  throw new TolokaCliError(
     detail.length > 0
       ? `bun add --global failed: ${detail}`
       : `bun add --global exited ${String(exitCode)}`,
+    {
+      hint: {
+        description:
+          "Run the bun add --global command yourself, or turn the check off with toloka config set auto-update false.",
+      },
+    },
   );
 };
 
@@ -340,9 +348,7 @@ export async function maybeAutoUpdate(options: {
       environment,
     });
   } catch (error) {
-    io.stderr(
-      `Auto-update to ${candidate.version} failed: ${error instanceof Error ? error.message : String(error)}.`,
-    );
+    io.stderr(`Auto-update to ${candidate.version} failed: ${formatCliError(error)}`);
     return continueResult();
   }