@soat/cli 0.17.4 → 0.18.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.17.4";
+var version = "0.18.0";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
@@ -670,8 +670,14 @@ var routes = {
       "in": "body"
     }, {
       "name": "ai_provider_id",
-      "description": "Public ID of the AI provider",
-      "required": true,
+      "description": "Public ID of the AI provider to pin. Mutually exclusive with `model_route_id`.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "model_route_id",
+      "description": "Public ID of a model route in the same project. The agent's completion model is then resolved through the route's ordered targets with failover. Mutually exclusive with `ai_provider_id` and `model`.",
+      "required": false,
       "type": "string",
       "in": "body"
     }, {
@@ -820,6 +826,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "body"
+    }, {
+      "name": "model_route_id",
+      "description": "Model route in the same project. Mutually exclusive with `ai_provider_id` and `model`; set to null to clear.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }, {
       "name": "name",
       "description": "",
@@ -950,6 +962,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "body"
+    }, {
+      "name": "model_route_id",
+      "description": "Model route in the same project. Mutually exclusive with `ai_provider_id` and `model`; set to null to clear.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }, {
       "name": "name",
       "description": "",
@@ -1349,7 +1367,7 @@ var routes = {
   "delete-ai-provider": {
     serviceClass: "AIProviders",
     operationId: "deleteAiProvider",
-    description: "Deletes an AI provider configuration. Live references — chats, agents, and discussions that use this provider — always block deletion with `409 AI_PROVIDER_HAS_DEPENDENTS`; `force` does not override them, so delete or repoint those resources first. Soft dependents — price overrides, usage/generation records, and discussion participants — also block with `409` unless `force=true`, which deletes the provider's price overrides and unlinks (nulls) its usage and participant history, preserving those rows. The `409` body's `error.meta` reports the counts, a sample of offending IDs, and a `forcible` flag that is `true` when a `force=true` retry would succeed.",
+    description: "Deletes an AI provider configuration. Live references — chats, agents, discussions, and model routes whose targets name this provider — always block deletion with `409 AI_PROVIDER_HAS_DEPENDENTS`; `force` does not override them, so delete or repoint those resources first. Soft dependents — price overrides, usage/generation records, and discussion participants — also block with `409` unless `force=true`, which deletes the provider's price overrides and unlinks (nulls) its usage and participant history, preserving those rows. The `409` body's `error.meta` reports the counts, a sample of offending IDs, and a `forcible` flag that is `true` when a `force=true` retry would succeed.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/ai-providers",
     httpMethod: "delete",
     pathParams: ["ai_provider_id"],
@@ -1362,7 +1380,7 @@ var routes = {
       "in": "path"
     }, {
       "name": "force",
-      "description": "When `true`, delete the provider's price overrides and unlink its usage/participant history so a provider with only soft dependents can be removed. Has no effect on live references (chats, agents, discussions), which always block deletion.\n",
+      "description": "When `true`, delete the provider's price overrides and unlink its usage/participant history so a provider with only soft dependents can be removed. Has no effect on live references (chats, agents, discussions, model routes), which always block deletion.\n",
       "required": false,
       "type": "boolean",
       "in": "query"
@@ -1838,8 +1856,8 @@ var routes = {
     queryParams: [],
     flags: [{
       "name": "ai_provider_id",
-      "description": "Public ID of the AI provider",
-      "required": true,
+      "description": "Public ID of the AI provider to pin. Optional: omit it to inherit the project's `default_model_route_id`, which gives the chat provider failover. Omitting it returns `400` when the project has no default, and cannot be combined with `model` — each route target names its own.",
+      "required": false,
       "type": "string",
       "in": "body"
     }, {
@@ -2336,8 +2354,8 @@ var routes = {
       "in": "body"
     }, {
       "name": "ai_provider_id",
-      "description": "Default AI provider participants and synthesis fall back to.",
-      "required": true,
+      "description": "Default AI provider participants and synthesis fall back to. Optional: omit it to inherit the project's `default_model_route_id`, which gives every turn provider failover. Omitting it returns `400` when the project has no default.",
+      "required": false,
       "type": "string",
       "in": "body"
     }, {
@@ -2432,7 +2450,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "ai_provider_id",
-      "description": "",
+      "description": "Repins the default AI provider. An explicit `null` unpins the discussion onto the project's `default_model_route_id`, and returns `400` when the project has no default.",
       "required": false,
       "type": "string",
       "in": "body"
@@ -4450,6 +4468,158 @@ var routes = {
       "in": "path"
     }]
   },
+  "list-model-routes": {
+    serviceClass: "ModelRoutes",
+    operationId: "listModelRoutes",
+    description: "Returns the model routes defined in a project",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/model-routes",
+    httpMethod: "get",
+    pathParams: [],
+    queryParams: ["project_id", "limit", "offset"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (required if not using project key auth)",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "limit",
+      "description": "Maximum number of results to return",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "Number of results to skip",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
+  },
+  "create-model-route": {
+    serviceClass: "ModelRoutes",
+    operationId: "createModelRoute",
+    description: "Creates a project-scoped model route: a named, ordered list of provider+model targets tried in array order. Every target must reference an AI provider in the same project (400 otherwise), and the total attempt budget — the sum of `1 + max_retries` over all targets — may not exceed 10 (400 naming the computed total). A duplicate `name` in the project is rejected with 409.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/model-routes",
+    httpMethod: "post",
+    pathParams: [],
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (required if not using project key auth)",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "name",
+      "description": "Human-readable name, unique per project",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "targets",
+      "description": "Ordered failover targets. Position is priority: target 0 is tried first, and a retryable failure falls through to the next target.",
+      "required": true,
+      "type": "array",
+      "in": "body"
+    }, {
+      "name": "retry_on",
+      "description": "Which failure classes are failover-eligible. A failure whose class is not listed (and every deterministic failure — 400-class, auth, content policy) fails the generation immediately instead of spending another target's budget.",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }, {
+      "name": "failure_threshold",
+      "description": "Consecutive retryable failures after which a target is skipped for `cooldown_seconds`. Breaker state is in-process per node and keyed by (provider, model), so it is shared by every route pointing at the same backend.",
+      "required": false,
+      "type": "integer",
+      "in": "body"
+    }, {
+      "name": "cooldown_seconds",
+      "description": "How long a tripped target is skipped before being probed again",
+      "required": false,
+      "type": "integer",
+      "in": "body"
+    }]
+  },
+  "get-model-route": {
+    serviceClass: "ModelRoutes",
+    operationId: "getModelRoute",
+    description: "Returns a specific model route",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/model-routes",
+    httpMethod: "get",
+    pathParams: ["route_id"],
+    queryParams: [],
+    flags: [{
+      "name": "route_id",
+      "description": "Model route ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
+  "update-model-route": {
+    serviceClass: "ModelRoutes",
+    operationId: "updateModelRoute",
+    description: "Updates a model route's name, targets, retry classes, or breaker configuration. Omitted fields are left unchanged.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/model-routes",
+    httpMethod: "put",
+    pathParams: ["route_id"],
+    queryParams: [],
+    flags: [{
+      "name": "route_id",
+      "description": "Model route ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "name",
+      "description": "New name (unique per project)",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "targets",
+      "description": "Replacement target list (ordered)",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }, {
+      "name": "retry_on",
+      "description": "",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }, {
+      "name": "failure_threshold",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "body"
+    }, {
+      "name": "cooldown_seconds",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "body"
+    }]
+  },
+  "delete-model-route": {
+    serviceClass: "ModelRoutes",
+    operationId: "deleteModelRoute",
+    description: "Deletes a model route. Returns 409 when an agent still references it — a routed agent has no pinned provider to fall back on, so the reference must be repointed or the agent deleted first.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/model-routes",
+    httpMethod: "delete",
+    pathParams: ["route_id"],
+    queryParams: [],
+    flags: [{
+      "name": "route_id",
+      "description": "Model route ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
   "list-orchestrations": {
     serviceClass: "Orchestrations",
     operationId: "listOrchestrations",
@@ -4963,7 +5133,7 @@ var routes = {
   "update-project": {
     serviceClass: "Projects",
     operationId: "updateProject",
-    description: "Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), and/or its read-auditing opt-in (`audit_reads_enabled`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.",
+    description: "Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its inherited model route (`default_model_route_id`), and/or its read-auditing opt-in (`audit_reads_enabled`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/projects",
     httpMethod: "patch",
     pathParams: ["project_id"],
@@ -4992,6 +5162,12 @@ var routes = {
       "required": false,
       "type": "integer",
       "in": "body"
+    }, {
+      "name": "default_model_route_id",
+      "description": "Model route inherited by consumers in this project that bind neither `model_route_id` nor `ai_provider_id`. The route must belong to this project (`400` otherwise). `null` clears the default, which is refused with `409` while any consumer inherits it — repointing it to another route is always allowed and immediately changes which targets those consumers use.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }, {
       "name": "audit_reads_enabled",
       "description": "Opt the project into read auditing. When true, `GET` requests that name this project are recorded in the audit log alongside mutations. Defaults to `false`.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/cli",
-  "version": "0.17.4",
+  "version": "0.18.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.17.4"
+    "@soat/sdk": "0.18.0"
   },
   "devDependencies": {
     "@ttoss/config": "^1.37.17",