@toloka-platform/sdk 0.11.2 → 0.11.4

package/src/cli/check.ts

@@ -23,6 +23,7 @@ import {
   type TestEvidence,
   type TestEvidenceKind,
 } from "../testing/test-evidence";
+import { platformRuleIssues } from "../validate";
 import { cliRelaunchCommand } from "./cli-entry";
 import { bunSubprocessEnvironment } from "./native-runtime";
 import { CREDENTIAL_ENVIRONMENT_NAMES } from "./environment";
@@ -30,7 +31,13 @@ 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 = {
@@ -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;
 };
 
@@ -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/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/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/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/cli/generation-models.ts

@@ -0,0 +1,46 @@
+import type { PotatoClient } from "../client";
+import { formatTable, type TableIo, writeOutput } from "./table";
+
+type GenerationModelApi = Pick<PotatoClient, "generationModels">;
+
+const dollars = (amount: number): string => `$${amount.toFixed(2)}`;
+
+export const listGenerationModels = async (
+  client: GenerationModelApi,
+  input: { json: boolean },
+  io: TableIo,
+): Promise<void> => {
+  const catalog = await client.generationModels.list();
+  const recommended = catalog.generationModels
+    .filter((model) => model.recommended)
+    .map((model) => model.id);
+  writeOutput(
+    io,
+    input.json,
+    catalog,
+    catalog.generationModels.length === 0
+      ? "No generation models available."
+      : [
+          formatTable([
+            ["ID", "NAME", "REASONING EFFORT", "TYPICAL", "MIN", "MAX"],
+            ...catalog.generationModels.flatMap((model) =>
+              model.budgets.map((budget) => [
+                model.id,
+                model.displayName,
+                budget.reasoningEffort === undefined
+                  ? "-"
+                  : budget.reasoningEffort === model.defaultReasoningEffort
+                    ? `${budget.reasoningEffort} (default)`
+                    : budget.reasoningEffort,
+                dollars(budget.typical),
+                dollars(budget.min),
+                dollars(budget.maxEstimate),
+              ]),
+            ),
+          ]),
+          "",
+          `Default model: ${catalog.defaultGenerationModelId}`,
+          ...(recommended.length === 0 ? [] : [`Recommended: ${recommended.join(", ")}`]),
+        ].join("\n"),
+  );
+};

package/src/cli/program.ts

@@ -11,6 +11,7 @@ import { registerAudienceCommands } from "./commands/audience";
 import { registerAuthCommands } from "./commands/auth";
 import { registerConfigCommands } from "./commands/config";
 import { registerDatasetCommands } from "./commands/dataset";
+import { registerGenerationModelCommands } from "./commands/generation-model";
 import { registerDeliveryOrderCommands } from "./commands/delivery-order";
 import { registerModelCommands } from "./commands/models";
 import { registerPipelineCommands } from "./commands/pipeline";
@@ -96,6 +97,7 @@ export function createProgram(context: ProgramContext): CreatedProgram {
   registerProjectCommands(program, host);
   registerDeliveryOrderCommands(program, host);
   registerAudienceCommands(program, host);
+  registerGenerationModelCommands(program, host);
   registerSourceCommands(program, host);
   registerSecretCommands(program, host);
   registerModelCommands(program, host);