@soat/cli 0.22.1 → 0.23.0

package/dist/index.mjs

@@ -13,7 +13,7 @@ import { load } from "js-yaml";
 import * as os from "node:os";
 
 //#region package.json
-var version = "0.22.1";
+var version = "0.23.0";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
@@ -745,19 +745,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_bindings",
-      "description": "Tools to attach, one binding object per tool — the canonical attachment field. Cannot be combined with the deprecated `tool_ids`/`tools` shorthands (400). See [Tool Bindings](/docs/modules/agents#tool-bindings).",
-      "required": false,
-      "type": "array",
-      "in": "body"
-    }, {
-      "name": "tool_ids",
-      "description": "Deprecated shorthand — each entry becomes a bare `{ \"tool_id\": … }` binding. Use `tool_bindings` instead.",
-      "required": false,
-      "type": "array",
-      "in": "body"
-    }, {
-      "name": "tools",
-      "description": "Deprecated shorthand — each entry becomes a bare `{ \"tool\": … }` binding (an ephemeral definition: no separate Tool resource is created, any `project_id` on an entry is ignored, entries never appear in `GET /tools`, cannot be targeted by `active_tool_ids`/`step_rules`, and cannot be of type `pipeline`). Use `tool_bindings` instead.",
+      "description": "Tools to attach, one binding object per tool — the only attachment field. An entry is either a reference (`{ \"tool_id\": … }`) or an inline definition (`{ \"tool\": … }`). See [Tool Bindings](/docs/modules/agents#tool-bindings).",
       "required": false,
       "type": "array",
       "in": "body"
@@ -909,19 +897,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_bindings",
-      "description": "Tools attached to the agent — the canonical attachment field. Replaces the whole binding list; set to `null` to clear. Cannot be combined with the deprecated `tool_ids`/`tools` shorthands (400). See [Tool Bindings](/docs/modules/agents#tool-bindings).",
-      "required": false,
-      "type": "array",
-      "in": "body"
-    }, {
-      "name": "tool_ids",
-      "description": "Deprecated shorthand — replaces only the reference (`tool_id`) bindings, rewriting them bare. Use `tool_bindings` instead.",
-      "required": false,
-      "type": "array",
-      "in": "body"
-    }, {
-      "name": "tools",
-      "description": "Deprecated shorthand — replaces only the inline (`tool`) bindings (ephemeral definitions: no separate Tool resource is created, any `project_id` on an entry is ignored, entries never appear in `GET /tools`, cannot be targeted by `active_tool_ids`/`step_rules`, and cannot be of type `pipeline`). Set to `null` to clear the inline bindings. Use `tool_bindings` instead.",
+      "description": "Tools attached to the agent — the only attachment field. Replaces the whole binding list; set to `null` to clear. See [Tool Bindings](/docs/modules/agents#tool-bindings).",
       "required": false,
       "type": "array",
       "in": "body"
@@ -1057,19 +1033,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_bindings",
-      "description": "Tools attached to the agent — the canonical attachment field. Replaces the whole binding list; set to `null` to clear. Cannot be combined with the deprecated `tool_ids`/`tools` shorthands (400). See [Tool Bindings](/docs/modules/agents#tool-bindings).",
-      "required": false,
-      "type": "array",
-      "in": "body"
-    }, {
-      "name": "tool_ids",
-      "description": "Deprecated shorthand — replaces only the reference (`tool_id`) bindings, rewriting them bare. Use `tool_bindings` instead.",
-      "required": false,
-      "type": "array",
-      "in": "body"
-    }, {
-      "name": "tools",
-      "description": "Deprecated shorthand — replaces only the inline (`tool`) bindings (ephemeral definitions: no separate Tool resource is created, any `project_id` on an entry is ignored, entries never appear in `GET /tools`, cannot be targeted by `active_tool_ids`/`step_rules`, and cannot be of type `pipeline`). Set to `null` to clear the inline bindings. Use `tool_bindings` instead.",
+      "description": "Tools attached to the agent — the only attachment field. Replaces the whole binding list; set to `null` to clear. See [Tool Bindings](/docs/modules/agents#tool-bindings).",
       "required": false,
       "type": "array",
       "in": "body"
@@ -2126,7 +2090,7 @@ var routes = {
       "type": "string",
       "in": "body"
     }, {
-      "name": "system_message",
+      "name": "instructions",
       "description": "Optional system message applied to all completions on this chat",
       "required": false,
       "type": "string",
@@ -2171,57 +2135,35 @@ var routes = {
       "in": "path"
     }]
   },
-  "create-chat-completion-for-chat": {
+  "create-chat-completion": {
     serviceClass: "Chats",
-    operationId: "createChatCompletionForChat",
-    description: "Runs a completion using the AI provider and settings stored in the chat. Pass `stream: true` for SSE streaming. A system message in `messages` overrides the chat's stored system message for this call only. Messages may use `documentId` instead of `content`.",
+    operationId: "createChatCompletion",
+    description: "OpenAI Chat Completions-compatible endpoint. Mirrors OpenAI's `POST /v1/chat/completions` path so an OpenAI SDK can target it by base URL alone. Names exactly one target. With `ai_provider_id` the completion is stateless: the provider's secret is decrypted and the appropriate Vercel AI SDK provider is called, with no server-side model fallback. With `chat_id` the stored chat supplies the provider (or the project's `default_model_route_id`), model and instructions. System content travels only in `instructions` — a `role: \"system\"` entry in `messages` is refused with `400 SYSTEM_MESSAGE_NOT_ALLOWED`. With `chat_id`, a request `instructions` replaces the chat's stored one for this call only; the stored value applies when the request carries none, and the two are never merged. Messages may use `document_id` instead of `content` with either target. Chats hold no message history — send the full `messages` array every time.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/chats",
     httpMethod: "post",
-    pathParams: ["chat_id"],
+    pathParams: [],
     queryParams: [],
     flags: [{
-      "name": "chat_id",
-      "description": "",
-      "required": true,
+      "name": "ai_provider_id",
+      "description": "Public ID of the AI provider to run the completion against. Mutually exclusive with `chat_id`; exactly one of the two is required.\n",
+      "required": false,
       "type": "string",
-      "in": "path"
-    }, {
-      "name": "messages",
-      "description": "",
-      "required": true,
-      "type": "array",
       "in": "body"
     }, {
-      "name": "model",
-      "description": "Override the chat's default model for this call",
+      "name": "chat_id",
+      "description": "Public ID of a stored chat supplying the provider, model and instructions. Mutually exclusive with `ai_provider_id`; exactly one of the two is required.\n",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "stream",
-      "description": "When `true` the response is an SSE stream.",
+      "name": "model",
+      "description": "Model identifier. Overrides the provider's `default_model`, or the chat's `model`, when specified.\n",
       "required": false,
-      "type": "boolean",
-      "in": "body"
-    }]
-  },
-  "create-chat-completion": {
-    serviceClass: "Chats",
-    operationId: "createChatCompletion",
-    description: "OpenAI Chat Completions-compatible endpoint. Mirrors OpenAI's `POST /v1/chat/completions` path so an OpenAI SDK can target it by base URL alone. Resolves the AI provider from `ai_provider_id`, decrypts its secret, and calls the appropriate Vercel AI SDK provider. `ai_provider_id` is required — there is no server-side model fallback.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/chats",
-    httpMethod: "post",
-    pathParams: [],
-    queryParams: [],
-    flags: [{
-      "name": "ai_provider_id",
-      "description": "Public ID of the AI provider to use.",
-      "required": true,
       "type": "string",
       "in": "body"
     }, {
-      "name": "model",
-      "description": "Model identifier. Overrides the provider's `default_model` when specified.\n",
+      "name": "instructions",
+      "description": "System instructions for this call. Sent to the provider as its `instructions` argument rather than as a message, which is the only place the AI SDK accepts system content (`allowSystemInMessages` defaults to false). This field is the only channel — a `role: \"system\"` entry in `messages` is refused with `400 SYSTEM_MESSAGE_NOT_ALLOWED`. With `chat_id`, this replaces the chat's stored `instructions` for this call only; the stored value applies when the request carries none, and the two are never merged.\n",
       "required": false,
       "type": "string",
       "in": "body"
@@ -3129,6 +3071,40 @@ var routes = {
       "in": "body"
     }]
   },
+  "create-dataset-item-from-generation": {
+    serviceClass: "Evaluations",
+    operationId: "createDatasetItemFromGeneration",
+    description: "Promotes a real, completed generation into a test case: its input messages become the item's `input`, and its own answer becomes `expected_output` unless you supply one. Use it to build an evaluation set out of production traffic rather than hand-authoring fixtures. The item is a **copy**, not a view. It keeps working after the source generation's content is purged, and `source_generation_id` goes null if that generation is deleted — a purge can never quietly stop a suite from being runnable. Requires both `evaluations:CreateDataset` and `generations:GetGeneration`: the call copies content out of a generation, so a principal that may not read that generation may not curate it either. Only a **completed** generation can be promoted (`409 GENERATION_NOT_COMPLETED`), and only while its content is still available: an agent or project running with `trace_content_mode: none` never stored the input, and a purged or expired generation no longer has it (`409 GENERATION_CONTENT_UNAVAILABLE`). Generations that predate input recording answer the same way.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
+    httpMethod: "post",
+    pathParams: ["dataset_id"],
+    queryParams: [],
+    flags: [{
+      "name": "dataset_id",
+      "description": "Dataset ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "generation_id",
+      "description": "The completed generation to promote. Must belong to the same project as the dataset.",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "expected_output",
+      "description": "Reference answer. Omit to use the generation's own answer; pass `null` to store the item with no reference answer.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "metadata",
+      "description": "Free-form tags, opaque to the platform",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
+  },
   "update-dataset-item": {
     serviceClass: "Evaluations",
     operationId: "updateDatasetItem",
@@ -4110,7 +4086,7 @@ var routes = {
   "delete-formation": {
     serviceClass: "Formations",
     operationId: "deleteFormation",
-    description: "Deletes the formation stack and all its managed resources in reverse dependency order.",
+    description: "Deletes the formation stack and all its managed resources in reverse dependency order. A resource the platform refuses to delete on its own — most often an agent that has generation or trace history — fails the teardown with `409 FORMATION_DELETE_FAILED`, naming every blocking resource in `error.meta.failures`. Resolve the blockers (for an agent, `DELETE /api/v1/agents/{agent_id}?force=true` also removes its generations and traces, and `deletion_policy: retain` exempts it from teardown entirely) and delete the formation again. A refusal the platform can foresee is found by a pre-flight, before the first delete: nothing is removed, and the formation stays `active` and intact for the retry. An unforeseeable error surfaces mid-teardown instead, where resources deleted before the blocker stay deleted and the formation is left in `delete_failed`. The error message states which happened.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/formations",
     httpMethod: "delete",
     pathParams: ["formation_id"],
@@ -5564,7 +5540,7 @@ var routes = {
   "start-orchestration-run": {
     serviceClass: "Orchestrations",
     operationId: "startOrchestrationRun",
-    description: "Creates a new run for the orchestration named by orchestration_id. By default the run executes durably in the background: the response returns immediately with status \"queued\" (a worker then claims it and moves it to \"running\") and progress is observed via get-orchestration-run or run lifecycle webhook events (orchestration_runs.started/awaiting_input/succeeded/failed). Delay and poll waits park the run as \"sleeping\" and are woken by a background scheduler, surviving restarts. Pass wait=true to block until the run reaches a terminal or awaiting_input state (the legacy synchronous behaviour).",
+    description: "Creates a new run for the orchestration named by orchestration_id. By default the run executes durably in the background: the response returns immediately with status \"queued\" (a worker then claims it and moves it to \"running\") and progress is observed via get-orchestration-run or run lifecycle webhook events (orchestration_runs.started/awaiting_input/succeeded/failed). Delay and poll waits park the run as \"sleeping\" and are woken by a background scheduler, surviving restarts. Pass wait=true to block until the run reaches a terminal or awaiting_input state.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/orchestrations",
     httpMethod: "post",
     pathParams: [],
@@ -7444,11 +7420,11 @@ var routes = {
   "list-usage-meters": {
     serviceClass: "Usage",
     operationId: "listUsageMeters",
-    description: "Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent, generation, trace, actor, or session. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.",
+    description: "Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent, generation, trace, actor, session, or `source`. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/usage",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["agent_id", "generation_id", "trace_id", "actor_id", "session_id", "trigger_id", "action_id", "meter_type", "limit", "offset"],
+    queryParams: ["agent_id", "generation_id", "trace_id", "actor_id", "session_id", "trigger_id", "action_id", "meter_type", "source", "limit", "offset"],
     flags: [{
       "name": "agent_id",
       "description": "Filter by agent public ID",
@@ -7497,6 +7473,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "source",
+      "description": "Filter by what the spend was incurred for. `eval` is an eval run's item generations and `eval_judge` an `llm_judge` scorer's own completion, so verification spend is `source` in (`eval`, `eval_judge`). Ordinary agent traffic carries no source and is matched by neither.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
     }, {
       "name": "limit",
       "description": "",
@@ -7527,7 +7509,7 @@ var routes = {
       "in": "query"
     }, {
       "name": "group_by",
-      "description": "Dimension to bucket by. `day` buckets on the event's UTC calendar day; the others bucket on the matching column.\n",
+      "description": "Dimension to bucket by. `day` buckets on the event's UTC calendar day; the others bucket on the matching column. `source` buckets by what the spend was incurred for (`eval`, `eval_judge`), which is how verification spend is priced apart from the traffic serving real users; unlabelled traffic collapses into the single `null` bucket.\n",
       "required": true,
       "type": "string",
       "in": "query"
@@ -8314,7 +8296,12 @@ var routes = {
 };
 
 //#endregion
-//#region src/index.ts
+//#region src/naming.ts
+/**
+* Flag-name spellings. The CLI accepts kebab-case (the documented convention),
+* snake_case (the wire spelling, so a body field can be typed exactly as the
+* spec names it), and camelCase alike; matching happens on the canonical form.
+*/
 /**
 * Normalize kebab-case, snake_case, or camelCase to camelCase for param matching.
 * e.g. agent-id → agentId, actor_id → actorId, agentId → agentId
@@ -8338,6 +8325,73 @@ var kebabToSnake = s => {
 var toKebab = s => {
   return s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/_/g, "-").toLowerCase();
 };
+
+//#endregion
+//#region src/validateFlags.ts
+/** Accepted on any command: Commander globals plus the generic id alias. */
+var ALWAYS_ALLOWED = /* @__PURE__ */new Set(["profile", "id"]);
+/**
+* Every flag name this command accepts, canonicalized. Wrapper-added flags are
+* absent on purpose — a wrapper deletes the flags it consumed before this runs,
+* so anything left over really is unrecognized.
+*/
+var knownFlagsFor = route => {
+  return new Set([...route.flags.map(f => {
+    return f.name;
+  }), ...route.pathParams, ...route.queryParams].map(toCanonical));
+};
+/**
+* Offer the closest known flag, so a typo is one line away from its fix rather
+* than a trip to `--help`. Prefix matching in either direction covers the real
+* cases (`limitt`/`limit`, `agent`/`agent_id`) without a full edit-distance pass.
+*/
+var suggestionFor = args => {
+  const target = toCanonical(args.flag).toLowerCase();
+  const near = [...args.known].find(known => {
+    const candidate = known.toLowerCase();
+    return candidate.startsWith(target) || target.startsWith(candidate);
+  });
+  return near ? ` Did you mean --${toKebab(near)}?` : "";
+};
+/**
+* Reject an unrecognized flag **only where the server cannot catch it** — a flag
+* the CLI would otherwise append to the query string.
+*
+* An undeclared query param never reaches a check: the server ignores what it
+* does not know, so `list-agents --limitt 1` returned every row instead of one.
+* The filter failed **open**, with exit 0 and no warning, and the caller acted on
+* a superset it never asked for. The name does not survive the request, so only
+* the client can catch it.
+*
+* An unrecognized flag on a **write** is deliberately still forwarded. The server
+* already answers `400 VALIDATION_FAILED` naming the field (`strictFields`), and
+* that check is the authority on what a body may contain — rejecting locally
+* would front-run it, hide the real error, and make an older CLI refuse a field a
+* newer server accepts. It would also make the behavior untestable through the
+* CLI: `tests/smoke-tests.sh` asserts precisely that the server rejects
+* `update-agent --reasoning` with a 400, which a client-side refusal turns into a
+* usage error the assertion cannot read.
+*
+* Returns the error lines to print; empty when every flag is recognized.
+*/
+var findUnknownFlags = args => {
+  if (args.route.httpMethod !== "get") return [];
+  const known = knownFlagsFor(args.route);
+  const unknown = args.flagKeys.filter(flagKey => {
+    if (ALWAYS_ALLOWED.has(flagKey)) return false;
+    return !known.has(toCanonical(flagKey));
+  });
+  if (unknown.length === 0) return [];
+  return [...unknown.map(flag => {
+    return `Unknown flag --${flag} for '${args.commandName}'.${suggestionFor({
+      flag,
+      known
+    })}`;
+  }), `Run "soat ${args.commandName} --help" to see the flags this command accepts.`];
+};
+
+//#endregion
+//#region src/index.ts
 /**
 * Renders a command's payload for stdout.
 *
@@ -8536,6 +8590,15 @@ program.argument("[command]", "API command in kebab-case (e.g. list-actors)").ar
   const flagTypeByCanonical = new Map(route.flags.map(f => {
     return [toCanonical(f.name), f.type];
   }));
+  const unknownFlagErrors = findUnknownFlags({
+    commandName,
+    route,
+    flagKeys: Object.keys(flags)
+  });
+  if (unknownFlagErrors.length > 0) {
+    for (const line of unknownFlagErrors) console.error(line);
+    process.exit(1);
+  }
   const pathArgs = {};
   const queryArgs = {};
   const bodyArgs = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/cli",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "type": "module",
   "dependencies": {
     "@inquirer/input": "^5.1.2",
@@ -8,7 +8,7 @@
     "@ttoss/logger": "^0.8.19",
     "commander": "^15.0.0",
     "js-yaml": "^5.2.1",
-    "@soat/sdk": "0.22.1"
+    "@soat/sdk": "0.23.0"
   },
   "devDependencies": {
     "@ttoss/config": "^1.37.17",