@desplega.ai/agent-swarm 1.158.0 → 1.159.0

package/src/tools/model-catalog/index.ts

@@ -0,0 +1,137 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById } from "@/be/db";
+import { upsertModelCatalogOverlay } from "@/be/model-catalog-store";
+import { requestModelCatalogRefresh } from "@/be/pricing-refresh";
+import { can } from "@/rbac";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
+
+async function denyUnlessCatalogWriter(agentId: string): Promise<string | null> {
+  const agent = await getAgentById(agentId);
+  const decision = can({
+    principal: { kind: "agent", agentId, isLead: agent?.isLead ?? false },
+    verb: "models.catalog.write",
+    resource: { kind: "none" },
+    source: "mcp",
+  });
+  return decision.allow ? null : "Writing the model catalog requires the lead agent.";
+}
+
+export const registerModelCatalogRefreshTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "model-catalog-refresh",
+    {
+      title: "Refresh Model Catalog",
+      description:
+        "Refresh the swarm model catalog (and pricing rows) from models.dev, like `pi update --models`. Without force, skips the network when the last check is under 4h old. A forced refresh is accepted once per minute; a second one inside that window returns `skipped-cooldown` with `retryAfterMs`. Lead agent only. Returns the status, model count, and newly added provider/modelId keys.",
+      annotations: { idempotentHint: true, openWorldHint: true },
+      inputSchema: z.object({
+        force: z
+          .boolean()
+          .optional()
+          .describe(
+            "Fetch even if the last check is under 4h old (default false). Rate limited to one per minute.",
+          ),
+      }),
+      outputSchema: swarmToolOutputSchema({
+        status: z.string().optional(),
+        models: z.number().optional(),
+        added: z.array(z.string()).optional(),
+        checkedAt: z.number().nullable().optional(),
+        retryAfterMs: z.number().optional(),
+      }),
+    },
+    async ({ force }, requestInfo) => {
+      if (!requestInfo.agentId) {
+        return toolErr('Agent ID not found. Set the "X-Agent-ID" header.');
+      }
+      const denied = await denyUnlessCatalogWriter(requestInfo.agentId);
+      if (denied) return toolErr(denied);
+
+      const result = await requestModelCatalogRefresh({ force });
+      const data = {
+        status: result.status,
+        models: result.models,
+        added: result.added,
+        checkedAt: result.checkedAt,
+        retryAfterMs: result.retryAfterMs,
+      };
+      if (result.status === "error") {
+        return toolErr(`Model catalog refresh failed: ${result.error ?? "unknown error"}`, {
+          data,
+        });
+      }
+      const addedText = result.added.length > 0 ? ` Added: ${result.added.join(", ")}.` : "";
+      return toolOk(
+        `Model catalog ${result.status}: ${result.models} model(s), ${result.added.length} new.`,
+        {
+          details: `status=${result.status}; models=${result.models}; added=${result.added.length}.${addedText}`,
+          data,
+        },
+      );
+    },
+  );
+};
+
+export const registerModelCatalogOverlayUpsertTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "model-catalog-overlay-upsert",
+    {
+      title: "Upsert Model Catalog Overlay",
+      description:
+        "Add or update hand-verified facts for one model (e.g. a launch models.dev has not listed yet). Overlay fields win over models.dev; overlay prices fill pricing-table gaps so cost recompute prices the model. The row auto-expires once models.dev matches every fact you set.",
+      annotations: { idempotentHint: true },
+      inputSchema: z.object({
+        provider: z
+          .string()
+          .min(1)
+          .describe(
+            "models.dev provider id: anthropic, openai, openrouter, amazon-bedrock, opencode.",
+          ),
+        modelId: z
+          .string()
+          .min(1)
+          .describe("Model id as models.dev keys it (e.g. claude-opus-5-5)."),
+        name: z.string().optional().describe("Display name."),
+        releaseDate: z.string().optional().describe("Release date, YYYY-MM-DD."),
+        contextWindow: z.number().int().positive().optional().describe("Context window, tokens."),
+        maxOutput: z.number().int().positive().optional().describe("Max output tokens."),
+        reasoningOptions: z
+          .array(z.object({ type: z.string(), values: z.array(z.string()).optional() }))
+          .optional()
+          .describe("Reasoning options, models.dev shape: [{type, values?}]."),
+        pricing: z
+          .object({
+            input: z.number().nonnegative().optional(),
+            output: z.number().nonnegative().optional(),
+            cache_read: z.number().nonnegative().optional(),
+            cache_write: z.number().nonnegative().optional(),
+          })
+          .optional()
+          .describe("USD per million tokens."),
+        reason: z.string().min(1).describe("Why this overlay exists (source of the facts)."),
+        verifiedBy: z.string().optional().describe("Who verified the facts (URL, person, agent)."),
+      }),
+      outputSchema: swarmToolOutputSchema({
+        overlay: z.looseObject({}).optional(),
+      }),
+    },
+    async (input, requestInfo) => {
+      if (!requestInfo.agentId) {
+        return toolErr('Agent ID not found. Set the "X-Agent-ID" header.');
+      }
+      const denied = await denyUnlessCatalogWriter(requestInfo.agentId);
+      if (denied) return toolErr(denied);
+      try {
+        const overlay = await upsertModelCatalogOverlay(input);
+        return toolOk(`Overlay for ${input.provider}/${input.modelId} saved.`, {
+          details: `Overlay for ${input.provider}/${input.modelId} saved (reason: ${input.reason}). It expires when models.dev matches every fact set.`,
+          data: { overlay },
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return toolErr(`Failed to save overlay: ${message}`);
+      }
+    },
+  );
+};

package/src/tools/schedules/create-schedule.ts

@@ -11,6 +11,7 @@ import {
   getWorkflow,
   isExtensionAgent,
 } from "@/be/db";
+import { explicitModelErrorForAgent } from "@/be/model-validation";
 import { getScript } from "@/be/scripts/db";
 import { calculateNextRun } from "@/scheduler";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
@@ -109,6 +110,12 @@ export const createScheduleInputSchema = z.object({
   modelTier: ModelTierSchema.optional().describe(
     "Portable model tier for tasks created by this schedule: 'smol', 'regular', 'smart', or 'ultra'. Resolved by each assignee's harness/provider at run time.",
   ),
+  allowCustomModel: z
+    .boolean()
+    .optional()
+    .describe(
+      "Accept a `model` the model catalog does not list. Without it an unknown model id is rejected. Only for ids the catalog cannot know yet.",
+    ),
 });
 
 const scheduleDataShape = {
@@ -177,6 +184,7 @@ export const registerCreateScheduleTool = (server: McpServer) => {
         enabled,
         model,
         modelTier,
+        allowCustomModel,
       },
       requestInfo,
       _meta,
@@ -263,8 +271,15 @@ export const registerCreateScheduleTool = (server: McpServer) => {
         }
       }
 
+      const normalizedModel = splitLegacyModelAlias({ model, modelTier });
+      const modelError = await explicitModelErrorForAgent({
+        model: normalizedModel.model,
+        allowCustomModel,
+        agentId: targetAgentId,
+      });
+      if (modelError) return toolErr(modelError);
+
       try {
-        const normalizedModel = splitLegacyModelAlias({ model, modelTier });
         // Calculate initial nextRunAt
         let nextRunAt: string | undefined;
         if (enabled === false) {

package/src/tools/schedules/patch-schedule.ts

@@ -12,6 +12,7 @@ import {
   isExtensionAgent,
   updateScheduledTask,
 } from "@/be/db";
+import { explicitModelErrorForAgent } from "@/be/model-validation";
 import { mergeScheduleTiming, validateRecurringTiming } from "@/be/schedules/validate";
 import { getScript } from "@/be/scripts/db";
 import { calculateNextRun } from "@/scheduler";
@@ -73,6 +74,12 @@ export const patchScheduleInputSchema = z.object({
   modelTier: ModelTierSchema.nullable()
     .optional()
     .describe("Portable model tier for tasks created by this schedule. Set to null to clear."),
+  allowCustomModel: z
+    .boolean()
+    .optional()
+    .describe(
+      "Accept a `model` the model catalog does not list. Without it an unknown model id is rejected. Only for ids the catalog cannot know yet.",
+    ),
 });
 
 const scheduleDataShape = {
@@ -140,6 +147,7 @@ export const registerPatchScheduleTool = (server: McpServer) => {
         enabled,
         model,
         modelTier,
+        allowCustomModel,
       },
       requestInfo,
       _meta,
@@ -249,6 +257,15 @@ export const registerPatchScheduleTool = (server: McpServer) => {
         if (enabled !== undefined) updateData.enabled = enabled;
         if (model !== undefined || modelTier !== undefined) {
           const normalizedModel = splitLegacyModelAlias({ model, modelTier });
+          // A model the schedule already stores is not re-judged, so an unrelated edit still saves.
+          if (normalizedModel.model !== schedule.model) {
+            const modelError = await explicitModelErrorForAgent({
+              model: normalizedModel.model,
+              allowCustomModel,
+              agentId: targetAgentId ?? schedule.targetAgentId,
+            });
+            if (modelError) return toolErr(modelError);
+          }
           if (model !== undefined) updateData.model = normalizedModel.model ?? null;
           if (modelTier !== undefined || normalizedModel.modelTier) {
             updateData.modelTier = normalizedModel.modelTier ?? null;

package/src/tools/schedules/update-schedule.ts

@@ -12,6 +12,7 @@ import {
   isExtensionAgent,
   updateScheduledTask,
 } from "@/be/db";
+import { explicitModelErrorForAgent } from "@/be/model-validation";
 import { mergeScheduleTiming, validateRecurringTiming } from "@/be/schedules/validate";
 import { getScript } from "@/be/scripts/db";
 import { calculateNextRun } from "@/scheduler";
@@ -73,6 +74,12 @@ export const updateScheduleInputSchema = z.object({
   modelTier: ModelTierSchema.nullable()
     .optional()
     .describe("Portable model tier for tasks created by this schedule. Set to null to clear."),
+  allowCustomModel: z
+    .boolean()
+    .optional()
+    .describe(
+      "Accept a `model` the model catalog does not list. Without it an unknown model id is rejected. Only for ids the catalog cannot know yet.",
+    ),
 });
 
 const scheduleDataShape = {
@@ -139,6 +146,7 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
         enabled,
         model,
         modelTier,
+        allowCustomModel,
       },
       requestInfo,
       _meta,
@@ -248,6 +256,15 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
         if (enabled !== undefined) updateData.enabled = enabled;
         if (model !== undefined || modelTier !== undefined) {
           const normalizedModel = splitLegacyModelAlias({ model, modelTier });
+          // A model the schedule already stores is not re-judged, so an unrelated edit still saves.
+          if (normalizedModel.model !== schedule.model) {
+            const modelError = await explicitModelErrorForAgent({
+              model: normalizedModel.model,
+              allowCustomModel,
+              agentId: targetAgentId ?? schedule.targetAgentId,
+            });
+            if (modelError) return toolErr(modelError);
+          }
           if (model !== undefined) updateData.model = normalizedModel.model ?? null;
           if (modelTier !== undefined || normalizedModel.modelTier) {
             updateData.modelTier = normalizedModel.modelTier ?? null;

package/src/tools/send-task.ts

@@ -17,6 +17,7 @@ import {
   isExtensionAgent,
 } from "@/be/db";
 import { repointTrackerSyncBySwarmId } from "@/be/db-queries/tracker";
+import { explicitModelErrorForAgent } from "@/be/model-validation";
 import { applyPreTaskCreate } from "@/extensions/apply-task-create";
 import { checkSlackRoutingCoherence } from "@/tasks/slack-routing";
 import { findDuplicateTask } from "@/tools/task-dedup";
@@ -136,6 +137,12 @@ export const sendTaskInputSchema = z
     modelTier: ModelTierSchema.optional().describe(
       "Portable model tier for this task: 'smol', 'regular', 'smart', or 'ultra'. Resolved at claim/run time using the assignee's harness/provider. Legacy model shortnames map as haiku→smol, sonnet→regular, opus→smart, fable→ultra.",
     ),
+    allowCustomModel: z
+      .boolean()
+      .optional()
+      .describe(
+        "Accept a `model` the model catalog does not list. Without it an unknown model id is rejected. Only for ids the catalog cannot know yet (a fresh launch, a private deployment).",
+      ),
     effort: ReasoningEffortSchema.optional().describe(
       "Reasoning effort for this task: 'off', 'low', 'medium', 'high', 'xhigh', or 'max'. If omitted, the assignee's REASONING_EFFORT_OVERRIDE/default applies.",
     ),
@@ -268,6 +275,7 @@ export async function sendTaskHandler(
     vcsRepo,
     model,
     modelTier,
+    allowCustomModel,
     effort,
     allowDuplicate,
     slackChannelId,
@@ -313,6 +321,12 @@ export async function sendTaskHandler(
 
   const effectiveVcsRepo = vcsRepo;
   const normalizedModel = splitLegacyModelAlias({ model, modelTier });
+  const modelError = await explicitModelErrorForAgent({
+    model: normalizedModel.model,
+    allowCustomModel,
+    agentId,
+  });
+  if (modelError) return toolErr(modelError, { data: { yourAgentId: creatorAgentId } });
 
   // Auto-default parentTaskId to caller's current task for tree tracking
   const effectiveParentTaskId = parentTaskId ?? sourceTaskId;

package/src/tools/task-action.ts

@@ -27,6 +27,7 @@ import {
   releaseTask,
   updateTaskClaudeSessionId,
 } from "@/be/db";
+import { explicitModelErrorForAgent } from "@/be/model-validation";
 import { touchRuntimeInstance } from "@/be/multi-runtime";
 import { applyPreTaskCreate } from "@/extensions/apply-task-create";
 import { assertOwnsTask, ownerCtx, type ToolCtx } from "@/tools/task-tool-ctx";
@@ -98,6 +99,12 @@ export const taskActionInputSchema = z.object({
   modelTier: ModelTierSchema.optional().describe(
     "Portable model tier for the created task: 'smol', 'regular', 'smart', or 'ultra'. Resolved when a worker claims/runs the task. Only used with 'create' action.",
   ),
+  allowCustomModel: z
+    .boolean()
+    .optional()
+    .describe(
+      "Accept a `model` the model catalog does not list. Without it an unknown model id is rejected. Only used with 'create' action.",
+    ),
   effort: ReasoningEffortSchema.optional().describe(
     "Reasoning effort for the created task: 'off', 'low', 'medium', 'high', 'xhigh', or 'max'. Only used with 'create' action.",
   ),
@@ -275,6 +282,11 @@ export async function taskActionHandler(
         agentId,
       );
     }
+    const modelError = await explicitModelErrorForAgent({
+      model: normalizedModel.model,
+      allowCustomModel: input.allowCustomModel,
+    });
+    if (modelError) return taskActionResult({ success: false, message: modelError }, agentId);
     try {
       assetKey = key
         ? await authorizeAssetKeyWrite(key, await resolveTaskAuditUserId(ctx.sourceTaskId, agentId))

package/src/tools/tool-config.ts

@@ -78,12 +78,14 @@ export const DEFERRED_TOOLS = new Set([
   "list-services",
   "update-service-status",
 
-  // Config (5)
+  // Config (7)
   "set-config",
   "list-config",
   "delete-config",
   "credential-bindings",
   "script-connections",
+  "model-catalog-refresh",
+  "model-catalog-overlay-upsert",
 
   // Repos (1)
   "update-repo",

package/src/tools/workflows/create-workflow.ts

@@ -19,6 +19,7 @@ import {
 } from "@/types";
 import { getExecutorRegistry } from "@/workflows";
 import { validateDefinition } from "@/workflows/definition";
+import { withSaveWarnings, workflowSaveWarnings } from "@/workflows/readiness";
 
 export const registerCreateWorkflowTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -102,6 +103,7 @@ export const registerCreateWorkflowTool = (server: McpServer) => {
       outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
         workflow: z.unknown().optional(),
+        warnings: z.array(z.string()).optional(),
       }),
     },
     async (
@@ -152,11 +154,16 @@ export const registerCreateWorkflowTool = (server: McpServer) => {
           "mcp",
         );
         const longScriptTimeoutHint = findLongScriptTimeoutHint(definition.nodes);
-        return toolOk(`Created workflow "${workflow.name}".`, {
-          details: `Created workflow "${workflow.name}" (${workflow.id}).`,
+        const warnings = await workflowSaveWarnings(workflow.definition, getExecutorRegistry());
+        return toolOk(withSaveWarnings(`Created workflow "${workflow.name}".`, warnings), {
+          details: withSaveWarnings(
+            `Created workflow "${workflow.name}" (${workflow.id}).`,
+            warnings,
+          ),
           data: {
             yourAgentId: requestInfo.agentId,
             workflow,
+            ...(warnings.length > 0 ? { warnings } : {}),
             ...(longScriptTimeoutHint ? { longScriptTimeoutHint } : {}),
           },
         });

package/src/tools/workflows/patch-workflow-node.ts

@@ -11,6 +11,7 @@ import {
 import { WorkflowNodePatchSchema } from "@/types";
 import { getExecutorRegistry } from "@/workflows";
 import { patchWorkflowDefinition } from "@/workflows/patch-definition";
+import { withSaveWarnings, workflowSaveWarnings } from "@/workflows/readiness";
 
 export const registerPatchWorkflowNodeTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -30,6 +31,7 @@ export const registerPatchWorkflowNodeTool = (server: McpServer) => {
       outputSchema: swarmToolOutputSchema({
         workflow: z.unknown().optional(),
         versionCreated: z.number().optional(),
+        warnings: z.array(z.string()).optional(),
       }),
     },
     async ({ id, nodeId, ...nodeFields }, requestInfo) => {
@@ -59,14 +61,22 @@ export const registerPatchWorkflowNodeTool = (server: McpServer) => {
           { id: nodeId, type: patchedNode?.type, config: nodeFields.config },
         ]);
 
-        return toolOk(`Patched node "${nodeId}" in workflow "${workflow.name}".`, {
-          details: `Patched node "${nodeId}" in workflow "${workflow.name}" (${id}). Version ${version} snapshot created.`,
-          data: {
-            workflow,
-            versionCreated: version ?? undefined,
-            ...(longScriptTimeoutHint ? { longScriptTimeoutHint } : {}),
+        const warnings = await workflowSaveWarnings(result.definition, getExecutorRegistry());
+        return toolOk(
+          withSaveWarnings(`Patched node "${nodeId}" in workflow "${workflow.name}".`, warnings),
+          {
+            details: withSaveWarnings(
+              `Patched node "${nodeId}" in workflow "${workflow.name}" (${id}). Version ${version} snapshot created.`,
+              warnings,
+            ),
+            data: {
+              workflow,
+              versionCreated: version ?? undefined,
+              ...(warnings.length > 0 ? { warnings } : {}),
+              ...(longScriptTimeoutHint ? { longScriptTimeoutHint } : {}),
+            },
           },
-        });
+        );
       } catch (err) {
         return toolErr(String(err));
       }

package/src/tools/workflows/patch-workflow.ts

@@ -14,6 +14,7 @@ import type { WorkflowPatch } from "@/types";
 import { AssetKeySchema, WorkflowNodePatchSchema } from "@/types";
 import { getExecutorRegistry } from "@/workflows";
 import { patchWorkflowDefinition } from "@/workflows/patch-definition";
+import { withSaveWarnings, workflowSaveWarnings } from "@/workflows/readiness";
 
 export const registerPatchWorkflowTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -78,6 +79,7 @@ export const registerPatchWorkflowTool = (server: McpServer) => {
         nodesCreated: z.number().optional(),
         nodesUpdated: z.number().optional(),
         nodesDeleted: z.number().optional(),
+        warnings: z.array(z.string()).optional(),
       }),
     },
     async ({ id, key, update, delete: del, create, onNodeFailure, triggerSchema }, requestInfo) => {
@@ -133,14 +135,19 @@ export const registerPatchWorkflowTool = (server: McpServer) => {
         );
         const longScriptTimeoutHint = findLongScriptTimeoutHint(authoredFinalNodes);
 
-        return toolOk(`Patched workflow "${workflow.name}".`, {
-          details: `Patched workflow "${workflow.name}" (${id}). Version ${version} snapshot created.`,
+        const warnings = await workflowSaveWarnings(result.definition, getExecutorRegistry());
+        return toolOk(withSaveWarnings(`Patched workflow "${workflow.name}".`, warnings), {
+          details: withSaveWarnings(
+            `Patched workflow "${workflow.name}" (${id}). Version ${version} snapshot created.`,
+            warnings,
+          ),
           data: {
             workflow,
             versionCreated: version ?? undefined,
             nodesCreated: create?.length ?? 0,
             nodesUpdated: update?.length ?? 0,
             nodesDeleted: del?.length ?? 0,
+            ...(warnings.length > 0 ? { warnings } : {}),
             ...(longScriptTimeoutHint ? { longScriptTimeoutHint } : {}),
           },
         });

package/src/tools/workflows/update-workflow.ts

@@ -19,6 +19,7 @@ import {
 } from "@/types";
 import { getExecutorRegistry } from "@/workflows";
 import { definitionNodeIds, validateDefinition } from "@/workflows/definition";
+import { withSaveWarnings, workflowSaveWarnings } from "@/workflows/readiness";
 import { snapshotAndUpdateWorkflow } from "@/workflows/version";
 
 export const registerUpdateWorkflowTool = (server: McpServer) => {
@@ -84,6 +85,7 @@ export const registerUpdateWorkflowTool = (server: McpServer) => {
       outputSchema: swarmToolOutputSchema({
         workflow: z.unknown().optional(),
         versionCreated: z.number().optional(),
+        warnings: z.array(z.string()).optional(),
       }),
     },
     async (
@@ -152,11 +154,16 @@ export const registerUpdateWorkflowTool = (server: McpServer) => {
         const longScriptTimeoutHint = definition
           ? findLongScriptTimeoutHint(definition.nodes)
           : undefined;
-        return toolOk(`Updated workflow "${workflow.name}".`, {
-          details: `Updated workflow "${workflow.name}" (${id}). Version ${version.version} snapshot created.`,
+        const warnings = await workflowSaveWarnings(workflow.definition, getExecutorRegistry());
+        return toolOk(withSaveWarnings(`Updated workflow "${workflow.name}".`, warnings), {
+          details: withSaveWarnings(
+            `Updated workflow "${workflow.name}" (${id}). Version ${version.version} snapshot created.`,
+            warnings,
+          ),
           data: {
             workflow,
             versionCreated: version.version,
+            ...(warnings.length > 0 ? { warnings } : {}),
             ...(longScriptTimeoutHint ? { longScriptTimeoutHint } : {}),
           },
         });

package/src/types.ts

@@ -231,6 +231,25 @@ export function resolveModelTier(opts: {
   return DEFAULT_MODEL_TIER_MAP[opts.harnessProvider]?.[tier];
 }
 
+export type ModelTierOverrides = Partial<Record<string, Partial<Record<ModelTier, string>>>>;
+
+/**
+ * The worker's own MODEL_TIER_<TIER> / MODEL_TIER_MAP overrides, keyed by its
+ * harness provider, in the shape the worker sends on register and poll so the
+ * server can apply them at claim time. Values only (model ids), never secrets.
+ */
+export function parseWorkerModelTierOverrides(
+  env: Record<string, string | undefined>,
+  harnessProvider: ProviderName,
+): ModelTierOverrides {
+  const tiers: Partial<Record<ModelTier, string>> = { ...parseTierMapJson(env.MODEL_TIER_MAP) };
+  for (const tier of MODEL_TIERS) {
+    const direct = env[`MODEL_TIER_${tier.toUpperCase()}`]?.trim();
+    if (direct) tiers[tier] = direct;
+  }
+  return Object.keys(tiers).length > 0 ? { [harnessProvider]: tiers } : {};
+}
+
 export function resolveTaskModelSelection(opts: {
   model?: string | null;
   modelTier?: string | null;
@@ -612,6 +631,12 @@ export const AgentTaskSchema = z
     model: z.string().optional(),
     modelTier: ModelTierSchema.optional(),
     effort: ReasoningEffortSchema.optional(),
+    // Claim-time model resolution (server-side, see runbooks/model-tiers.md).
+    // resolvedModel is what the worker runs; modelSource says which layer won;
+    // modelAlias is the `latest:` alias the value came from, when any.
+    resolvedModel: z.string().optional(),
+    modelSource: z.string().optional(),
+    modelAlias: z.string().optional(),
 
     // Schedule linking (optional — set when task was created by a schedule).
     // z.string(): also reachable verbatim from the create-task query param.
@@ -1996,7 +2021,7 @@ export const WorkflowNodeSchema = z
     type: z
       .string()
       .describe(
-        "Executor type: 'agent-task', 'script', 'swarm-script', 'raw-llm', 'validate', 'property-match'",
+        "Executor type: 'agent-task', 'script', 'swarm-script', 'raw-llm', 'system-one-decision', 'validate', 'property-match'",
       ),
     label: z.string().optional().describe("Human-readable label for UI display"),
     config: z
@@ -2005,6 +2030,7 @@ export const WorkflowNodeSchema = z
         "Executor-specific config. For agent-task: { template, outputSchema?, agentId?, routingReason?, routingNote?, tags?, priority?, dir?, vcsRepo?, model? }; configured agentId defaults routingReason to human_pinned. " +
           "For script: { runtime, script, args?, timeout? }. " +
           "For swarm-script: { scriptName, scope?, pinHash?, args?, fsMode?, timeoutMs? (1000-300000) }. " +
+          "For system-one-decision (typed decisions, Jev by default): { provider? ('typesafe' default | 'openrouter' | 'laya'; a literal, never a {{token}}), state, questions: { <id>: { type: 'noul'|'choice'|'score', instructions, criteria? } }, returns: { <id>: { type } }, model? (provider-specific; unset = the provider's default, and laya has none so it sends no model and picks its own checkpoint), timeoutMs?, maxRetries? (0-3), humanReview? { band: { min, max } (0-1, inclusive), approvers: { users?, roles?, policy }, title?, timeout?, notifications? } }; each provider needs its own global secret (TYPESAFE_API_KEY, OPENROUTER_API_KEY, or LAYA_API_KEY; laya also needs the global config LAYA_URL), and a save warns and a run fails before any node executes when one is missing; system-one-decision nodes must not set retry or validation.retry. With humanReview, an answer whose confidence is inside the band waits for a person (human-in-the-loop approval), and next must map ports { approved, rejected?, timeout? }. " +
           "Agent-task templates and ordinary config values support {{interpolation}} from the node's inputs context, including trigger and declared upstream aliases. " +
           "SECURITY: executable source for script/swarm-script nodes does not interpolate trigger.* or upstream node outputs; only input/workflow/swarm/run values are allowed in inline script source, and named swarm-script source is not workflow-interpolated. " +
           "Pass dynamic values through config.args instead (inline script receives them as argv; swarm-script receives its args object). " +
@@ -2412,6 +2438,9 @@ export type AgentTaskSummary = Pick<
   | "scheduleId"
   | "model"
   | "modelTier"
+  | "resolvedModel"
+  | "modelSource"
+  | "modelAlias"
   | "effort"
   | "provider"
   | "requestedByUserId"