@toloka-platform/sdk 0.11.3 → 0.11.4

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

@@ -1 +1 @@
-6f99f48f6bd7c933cd5d2f6b2382d9c4149e6cfb4a39a32364d49994a16f436e  toloka.js.jsc
+a7b5f9f339e9293bf388a7a57c15cfa4297942cdb7243e8b53d116661ddf5f0d  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-a038b95e14fe030c3d9b59182799dc89f8c76fd501fe42036831ea3d1daa27c5  toloka.js
+3c36c2751f8365c8ed466bd389723fa1d836d2ec5e61850450e4a725648ec0f8  toloka.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toloka-platform/sdk",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "private": false,
   "description": "Build, inspect, and operate Toloka pipeline projects as TypeScript source. The public API may change between minor versions before 1.0.",
   "license": "Apache-2.0",
@@ -77,6 +77,6 @@
     "bun": ">=1.4.0"
   },
   "tolokaBuild": {
-    "commit": "113d50a57cb089999d1f93567c5c51afff932e67"
+    "commit": "7f1f084ec6f6d02475f766f468ad60a31ff123c8"
   }
 }

package/skills/catalog.json

@@ -11,8 +11,8 @@
         "testing",
         "checks"
       ],
-      "version": "0.11.3",
-      "digest": "f56be02fd1deb2f4d4221718f0b774ae8a32ae088926ac9103c4a1049191f515",
+      "version": "0.11.4",
+      "digest": "2a3f1b1cfa72c726b6255e3e93158c52d6a96108575327dd73479c2536c63167",
       "files": [
         "SKILL.md",
         "references/human-work.md",
@@ -33,7 +33,7 @@
         "bug",
         "report"
       ],
-      "version": "0.11.3",
+      "version": "0.11.4",
       "digest": "70f0bd2c80b32f87896aeb27c363b8a2d37f40e22424f57fe1aad142e125ad67",
       "files": [
         "SKILL.md",
@@ -50,7 +50,7 @@
         "getting-started",
         "agent"
       ],
-      "version": "0.11.3",
+      "version": "0.11.4",
       "digest": "2278adeb46a792356579395fcf73c42322cb23bcd0c61e20856ccabdad6762d1",
       "files": [
         "SKILL.md"
@@ -67,7 +67,7 @@
         "sft",
         "models"
       ],
-      "version": "0.11.3",
+      "version": "0.11.4",
       "digest": "b7ae3d76a6f1cba8d26a0dec30f540ef5a0298a9234580f418831c38cdc45bbb",
       "files": [
         "SKILL.md"
@@ -84,7 +84,7 @@
         "prompt",
         "models"
       ],
-      "version": "0.11.3",
+      "version": "0.11.4",
       "digest": "25388767c582e064f9ba366b04ed3a9883e7e5926301efb2b352f06cd2fa1bab",
       "files": [
         "SKILL.md"

package/skills/toloka-build/SKILL.md

@@ -105,7 +105,7 @@ Choose representative fixtures from available data, redacting sensitive values w
 
 ## Recover from expected failures
 
-When plan, apply, or validate fails, follow [Recover safely](references/workflow-and-cli.md#recover-safely). It covers a dataset field schema conflict, an unreadable field schema, a missing secret, a 409 stale graph version, node drift after apply, and a server 400 after a partial apply. Never retry blindly, and never work around reconciliation with raw API calls.
+When plan, apply, or validate fails, follow [Recover safely](references/workflow-and-cli.md#recover-safely). It covers a dataset field schema conflict, an unreadable field schema, a missing secret, a 409 stale graph version, node drift after apply, a server 400 after a partial apply, and a lost platform connection. Never retry blindly, and never work around reconciliation with raw API calls.
 
 ## Run an applied pipeline
 

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

@@ -107,13 +107,15 @@ The upload file path resolves from the command process's working directory, not
 
 The CLI infers the input format from its extension and uploads the original bytes without conversion: `.json` is an array of row objects, `.jsonl` has one object per non-empty line, and `.csv` uses its header row as field names with every value ingested as a string. JSONL is validated locally before upload. If transfer or finalization fails, the CLI cancels the started upload before returning the error, so another upload can start immediately and may reuse the same filename. The dataset does not have to exist yet: when a pipeline in source binds it, upload creates it and declares that pipeline's columns, so rows land in real columns rather than in the raw `uploaded` blob. When the dataset does not exist and no pipeline in source declares it, upload refuses, because it would have no column names to map onto; an existing dataset accepts the upload either way. An id-shaped argument is never created; upload fails when that dataset id does not exist in the project. Upload appends items; applying source never deletes them.
 
+After the upload the CLI prints the field types it inferred from the rows. They describe the rows, not the dataset's columns: inference omits enum, length, range, and format constraints, while the columns keep the schemas declared in source. Never edit `field()` declarations to match that list; `toloka plan` is what compares source with the live columns.
+
 If a later upload fails with a schema-incompatibility error, inspect the inferred schema from the first successful upload:
 
 ```sh
 toloka dataset fields <dataset>
 ```
 
-That prints `field()` declarations for the top-level inferred columns. Use the output to recover stored names and base types, but do not copy it wholesale over stricter source schemas: inference can omit enum, length, range, and format constraints. It does not write source or mutate the dataset.
+That prints the same inferred types as `field()` declarations for the top-level columns. Use them to recover stored names and base types, never to replace stricter source schemas. The command does not write source or mutate the dataset.
 
 Keep item files outside the source tree or gitignored. Never embed sample or production rows in `pipeline.ts` to make reconciliation create them.
 
@@ -178,3 +180,7 @@ Object settings preserve omitted live keys, but list-valued settings such as con
 ### Server 400 after a clean validate
 
 A new pipeline is skipped by `toloka validate` until it exists remotely, and apply can create its dataset and fields before pipeline import returns a 400. Fix the reported path or reason, then run plan again. If only the pipeline addition remains, continue from that diff; do not recreate or rename resources already created. If the rejection means a newly created field schema is wrong, that field is already immutable: follow the field schema conflict rule, prefer the option that preserves names the request fixes, and report the orphaned field instead of deleting it. Check connection endpoints, duplicate or unknown imported IDs, field references, and accidentally authored layout. Never bypass reconciliation with a raw API call.
+
+### Platform connection lost
+
+Inside a platform agent sandbox the CLI reaches the platform through the sandbox's connection and retries, for about 90 seconds, every request that connection reports as never sent. `Hint: The sandbox lost its connection to the platform … the request was not sent` therefore means nothing changed on the platform: retry the same command in a minute. Any other `5xx` may have reached the platform, so before repeating a command that changes state (`apply`, `dataset upload`, `pipeline run`), check whether it already took effect with the matching list or status command.

package/src/cli/data.ts

@@ -132,7 +132,7 @@ const summarizeJsonSchema = (schema: unknown): string => {
 const formatInferredFields = (fields: ReadonlyArray<InferredField>): string => {
   if (fields.length === 0) return "No inferred fields are available yet.";
   return [
-    "Inferred fields:",
+    "Types inferred from the uploaded rows (not the column schemas, which keep the constraints declared in source):",
     ...fields
       .toSorted((left, right) => left.jsonPath.localeCompare(right.jsonPath))
       .map(
@@ -459,6 +459,9 @@ export async function uploadDataset(
   };
 }
 
+const INFERRED_DECLARATIONS_NOTE =
+  "// Inferred from the uploaded rows: enum, length, range and format constraints are not inferred, so these are not the dataset's column schemas.";
+
 export async function generateDatasetFieldDeclarations(
   client: PotatoClient,
   options: GenerateDatasetFieldDeclarationsOptions,
@@ -476,7 +479,7 @@ export async function generateDatasetFieldDeclarations(
     output:
       topLevelFields.length === 0
         ? `Dataset ${resolved.name} has no inferred fields yet.`
-        : declarations,
+        : `${INFERRED_DECLARATIONS_NOTE}\n${declarations}`,
   };
 }
 

package/src/cli/format-error.ts

@@ -24,6 +24,9 @@ const apiErrorHint = (error: PotatoApiError): string | undefined => {
   if (error.status === 429) {
     return "Hint: The platform is rate limiting this key; wait a moment and retry.";
   }
+  if (error.status === 503 && error.body === "Tunnel unavailable; the request was not sent") {
+    return "Hint: The sandbox lost its connection to the platform (usually a platform restart) and it was not restored within 90 seconds; the request was not sent. Retry in a minute.";
+  }
   if (error.status !== undefined && error.status >= 500) {
     return "Hint: The platform failed to handle the request. Retry; if it keeps failing, write a report as the toloka-report-issue skill describes and send it with toloka report <report.md>.";
   }

package/src/transport.ts

@@ -1,4 +1,4 @@
-import { assert } from "es-toolkit";
+import { assert, delay } from "es-toolkit";
 import { PotatoApiError } from "./errors";
 
 const BASE_URL_HEADER = "x-potato-sdk-base-url";
@@ -14,9 +14,16 @@ export type ClientCredential =
     }
   | { readonly scopedToken: string; readonly accessToken?: undefined; readonly apiKey?: undefined };
 
+const RELAY_HEADER = "x-potato-relay";
+const TUNNEL_UNAVAILABLE = "tunnel-unavailable";
+export const TUNNEL_RETRY_DELAYS_MS: readonly number[] = [
+  1_000, 2_000, 4_000, 8_000, 15_000, 15_000, 15_000, 15_000, 15_000,
+];
+
 type TransportRequestInit = RequestInit & {
   readonly fetch?: typeof globalThis.fetch;
   readonly authorization?: () => Promise<string>;
+  readonly tunnelRetryDelaysMs?: readonly number[];
 };
 
 export const createRequestOptions = (
@@ -79,6 +86,7 @@ export async function potatoFetch(url: string, options: TransportRequestInit): P
   const {
     fetch: fetchImplementation = globalThis.fetch,
     authorization,
+    tunnelRetryDelaysMs = TUNNEL_RETRY_DELAYS_MS,
     ...requestOptions
   } = options;
   const headers = new Headers(requestOptions.headers);
@@ -87,10 +95,20 @@ export async function potatoFetch(url: string, options: TransportRequestInit): P
   headers.delete(BASE_URL_HEADER);
   if (authorization !== undefined) headers.set("Authorization", await authorization());
 
-  const response = await fetchImplementation(
-    resolveRequestUrl(url, baseUrl),
-    prepareRequestInit(requestOptions, headers),
-  );
+  const send = () =>
+    fetchImplementation(resolveRequestUrl(url, baseUrl), prepareRequestInit(requestOptions, headers));
+
+  let response = await send();
+  const replayableBody = !(typeof ReadableStream !== "undefined" && requestOptions.body instanceof ReadableStream);
+
+  for (const delayMs of replayableBody ? tunnelRetryDelaysMs : []) {
+    if (response.status !== 503 || response.headers.get(RELAY_HEADER) !== TUNNEL_UNAVAILABLE) break;
+
+    await response.body?.cancel();
+    await delay(delayMs, { signal: requestOptions.signal ?? undefined });
+    response = await send();
+  }
+
   const text = await response.text();
 
   if (!response.ok) {