@desplega.ai/agent-swarm 2.0.0 → 2.1.0

package/src/be/model-tier-resolution.ts

@@ -7,9 +7,12 @@
  *
  * Precedence (first hit wins):
  *   1. task `model`                         → modelSource "model"
- *   2. the claiming worker's MODEL_TIER_*   → "worker-env"  (agents.modelTierOverrides)
- *   3. swarm_config MODEL_TIER_<PROV>_<TIER> → "tier-config"
- *   4. DEFAULT_MODEL_TIER_MAP                → "tier-default"
+ *   2. task `profile`                       → "profile:task"
+ *   3. the claiming worker's MODEL_TIER_*   → "worker-env"  (agents.modelTierOverrides)
+ *   4. swarm_config MODEL_TIER_<PROV>_<TIER> → "tier-config"
+ *   5. DEFAULT_MODEL_TIER_MAP                → "tier-default"
+ *   6. the agent's default profile          → "profile:agent-default" (no model, no tier,
+ *      no repo-scoped MODEL_OVERRIDE on the task's repo)
  *
  * Any layer may hold a `latest:` alias. An alias that resolves to nothing
  * (empty catalog, everything filtered) falls through to the next layer.
@@ -45,8 +48,14 @@ import {
   type ProviderName,
   ProviderNameSchema,
   parseModelTier,
+  type ReasoningEffort,
 } from "../types";
 import { getDbClient } from "./db";
+import {
+  getAgentDefaultProfileName,
+  getModelProfileByName,
+  repoModelOverrideKeys,
+} from "./db/model-profiles";
 import {
   CLI_PINNED_HARNESSES,
   fallbackForUnsupportedModel,
@@ -74,7 +83,9 @@ export type ModelSource =
   | "tier-config"
   | "tier-default"
   | "fallback:cli-unsupported"
-  | "fallback:cli-unsupported:model";
+  | "fallback:cli-unsupported:model"
+  | "profile:task"
+  | "profile:agent-default";
 
 export interface TaskModelResolution {
   resolvedModel: string;
@@ -490,15 +501,21 @@ async function applyCliSupport(
   if (!fallback) return resolution;
   noticeCliUnsupported(harness, cliVersion, resolution.resolvedModel, fallback);
   // Keep the winning layer in the source: a fallback from the task's own `latest:` alias is
-  // still a task-level pin (a resume carries it), one from a tier layer is not.
-  const modelSource =
-    resolution.modelSource === "model"
+  // still a task-level pin (a resume carries it), one from a tier layer is not. A profile keeps
+  // its own source; `resolvedProfile` still names it and `resolvedModel` shows the swap.
+  const modelSource = resolution.modelSource.startsWith("profile:")
+    ? resolution.modelSource
+    : resolution.modelSource === "model"
       ? "fallback:cli-unsupported:model"
       : "fallback:cli-unsupported";
   return { ...resolution, resolvedModel: fallback, modelSource };
 }
 
 export type ClaimModelFields = Partial<TaskModelResolution> & {
+  /** The profile claim applied (`agent_tasks.resolvedProfile`). */
+  resolvedProfile?: string;
+  /** The profile's effort, when it has one and the task set none; the worker spawns with it. */
+  effort?: ReasoningEffort;
   /**
    * Set when the task's explicit model is rejected by this worker's CLI, or belongs to another
    * harness family (`[model-harness-mismatch]`); the worker fails the task without a spawn.
@@ -506,6 +523,55 @@ export type ClaimModelFields = Partial<TaskModelResolution> & {
   modelUnsupported?: string;
 };
 
+/**
+ * Resolve a model profile for a claim. Null when the profile does not apply:
+ * an agent default that is missing or on another harness falls through to the
+ * tier chain. For a task's own `profile` both are a hard stop.
+ */
+async function resolveClaimProfile(
+  name: string,
+  source: "profile:task" | "profile:agent-default",
+  harness: ProviderName | null,
+): Promise<
+  | { profile: { name: string; effort: ReasoningEffort | null }; resolution: TaskModelResolution }
+  | { modelUnsupported: string }
+  | null
+> {
+  const isTask = source === "profile:task";
+  const profile = await getModelProfileByName(name);
+  if (!profile) {
+    return isTask
+      ? { modelUnsupported: `[model-profile-missing] Model profile "${name}" no longer exists.` }
+      : null;
+  }
+  if (profile.harness !== harness) {
+    if (!isTask) return null;
+    return {
+      modelUnsupported: `[model-harness-mismatch] Model profile "${name}" runs on the ${profile.harness} harness, not on the ${harness ?? "unknown"} harness of this worker. Re-create the task with a ${harness ?? "matching"} profile.`,
+    };
+  }
+  let resolution: TaskModelResolution = {
+    resolvedModel: profile.model,
+    modelSource: source,
+    modelAlias: null,
+  };
+  if (isAlias(profile.model)) {
+    const resolved = await resolveLatestAlias(profile.model);
+    if (!resolved) {
+      if (!isTask) return null;
+      return {
+        modelUnsupported: `[model-profile-unresolved] Model profile "${name}" names ${profile.model}, which resolves to no usable model.`,
+      };
+    }
+    resolution = {
+      resolvedModel: resolved,
+      modelSource: source,
+      modelAlias: profile.model.trim().toLowerCase(),
+    };
+  }
+  return { profile: { name: profile.name, effort: profile.effort }, resolution };
+}
+
 /**
  * Resolve and record the model for a task the given agent is claiming. Runs
  * inside the claim transaction. Returns the fields to merge into the trigger.
@@ -513,10 +579,77 @@ export type ClaimModelFields = Partial<TaskModelResolution> & {
  * previous session reported into the column.
  */
 export async function recordClaimModelResolution(
-  task: { id: string; model?: string | null; modelTier?: string | null },
+  task: {
+    id: string;
+    model?: string | null;
+    modelTier?: string | null;
+    profile?: string | null;
+    effort?: string | null;
+    vcsRepo?: string | null;
+  },
   agent: { id: string; harnessProvider?: ProviderName | null; provider?: ProviderName | null },
+  /**
+   * Whether the claiming worker's config read includes secret repo rows
+   * (`readsRepoSecrets`). A secret repo override it never receives cannot
+   * beat its default profile. Defaults to true (an operator-key worker).
+   */
+  { includeRepoSecrets = true }: { includeRepoSecrets?: boolean } = {},
 ): Promise<ClaimModelFields> {
   const harnessProvider = agent.harnessProvider ?? agent.provider ?? null;
+
+  if (!task.model?.trim()) {
+    const taskProfile = task.profile?.trim();
+    const agentDefault =
+      taskProfile || parseModelTier(task.modelTier)
+        ? null
+        : await getAgentDefaultProfileName(agent.id);
+    // The agent default is agent-scoped config: a repo-scoped MODEL_OVERRIDE or
+    // REASONING_EFFORT_OVERRIDE on the task's repo still beats it on that axis
+    // (repo > agent), as it beats the agent's own override in the worker env.
+    // A task's own profile is the creator's pick and beats repo config.
+    const repoKeys = agentDefault
+      ? await repoModelOverrideKeys(task.vcsRepo, { includeSecrets: includeRepoSecrets })
+      : new Set<string>();
+    const defaultProfile = repoKeys.has("MODEL_OVERRIDE") ? null : agentDefault;
+    const picked = taskProfile
+      ? await resolveClaimProfile(taskProfile, "profile:task", harnessProvider)
+      : defaultProfile
+        ? await resolveClaimProfile(defaultProfile, "profile:agent-default", harnessProvider)
+        : null;
+    if (picked && "modelUnsupported" in picked)
+      return { modelUnsupported: picked.modelUnsupported };
+    if (picked) {
+      const checked = await applyCliSupport(
+        picked.resolution,
+        harnessProvider,
+        await getAgentHarnessCliVersion(agent.id),
+      );
+      // Profiles never fail fast on the CLI check (only a raw task pin does), so this is a resolution.
+      const resolution = "unsupported" in checked ? picked.resolution : checked;
+      await getDbClient().run(
+        "UPDATE agent_tasks SET resolvedModel = ?, modelSource = ?, modelAlias = ?, resolvedProfile = ? WHERE id = ?",
+        [
+          resolution.resolvedModel,
+          resolution.modelSource,
+          resolution.modelAlias,
+          picked.profile.name,
+          task.id,
+        ],
+      );
+      return {
+        resolvedModel: resolution.resolvedModel,
+        modelSource: resolution.modelSource,
+        ...(resolution.modelAlias ? { modelAlias: resolution.modelAlias } : {}),
+        resolvedProfile: picked.profile.name,
+        // A task's own effort stays the pin; the profile's fills only an unset one,
+        // and an agent default's yields to the repo's effort override.
+        ...(!task.effort && picked.profile.effort && !repoKeys.has("REASONING_EFFORT_OVERRIDE")
+          ? { effort: picked.profile.effort }
+          : {}),
+      };
+    }
+  }
+
   const resolved = await resolveTaskModel({
     model: task.model,
     modelTier: task.modelTier,
@@ -527,8 +660,9 @@ export async function recordClaimModelResolution(
     // A re-claimed row keeps the claim record of its previous run; drop it so
     // the trigger and the row do not replay that run's model.
     await getDbClient().run(
-      `UPDATE agent_tasks SET resolvedModel = NULL, modelSource = NULL, modelAlias = NULL
-         WHERE id = ? AND (resolvedModel IS NOT NULL OR modelSource IS NOT NULL OR modelAlias IS NOT NULL)`,
+      `UPDATE agent_tasks SET resolvedModel = NULL, modelSource = NULL, modelAlias = NULL, resolvedProfile = NULL
+         WHERE id = ? AND (resolvedModel IS NOT NULL OR modelSource IS NOT NULL OR modelAlias IS NOT NULL
+           OR resolvedProfile IS NOT NULL)`,
       [task.id],
     );
     return {};
@@ -544,7 +678,7 @@ export async function recordClaimModelResolution(
   }
   const resolution = checked;
   await getDbClient().run(
-    "UPDATE agent_tasks SET resolvedModel = ?, modelSource = ?, modelAlias = ? WHERE id = ?",
+    "UPDATE agent_tasks SET resolvedModel = ?, modelSource = ?, modelAlias = ?, resolvedProfile = NULL WHERE id = ?",
     [resolution.resolvedModel, resolution.modelSource, resolution.modelAlias, task.id],
   );
   return resolution.modelAlias

package/src/be/model-validation.ts

@@ -32,6 +32,7 @@ import {
 import { type TaskModelPinFields, taskModelPin } from "../tasks/model-pin";
 import { ampModelError, ampPinCatalogError, ampPinProviderError } from "../utils/amp-models";
 import { getAgentById, getAllAgents } from "./db";
+import { getModelProfileByName } from "./db/model-profiles";
 import { loadModelsCatalog } from "./model-catalog-store";
 import { resolveLatestAlias } from "./model-tier-resolution";
 
@@ -100,9 +101,15 @@ export async function harnessModelErrorFor(
  * stays sync and catalog-free; this runs next to it.
  */
 export async function poolTaskRunsOnHarness(
-  task: TaskModelPinFields | null | undefined,
+  task: (TaskModelPinFields & { profile?: string | null }) | null | undefined,
   harness: string | null | undefined,
 ): Promise<boolean> {
+  // A task's model profile runs on one harness only; other workers leave it in the pool.
+  const profileName = task?.profile?.trim();
+  if (profileName) {
+    const profile = await getModelProfileByName(profileName);
+    return !profile || !harness || profile.harness === harness;
+  }
   // Only the task's own pin restricts harnesses; a model a previous run
   // reported into `model` does not.
   const model = taskModelPin(task ?? {})?.trim();

package/src/be/scripts/typecheck.ts

@@ -232,6 +232,8 @@ export interface SwarmSdk {
   // --- config ---
   config_get(args?: { agentId?: string; repoId?: string; key?: string; includeSecrets?: boolean }): Promise<unknown>;
   config_list(args?: { scope?: "global" | "agent" | "repo"; scopeId?: string; key?: string; includeSecrets?: boolean }): Promise<unknown>;
+  // --- model profiles ---
+  modelProfile_list(args?: { harness?: string }): Promise<unknown>;
   // --- slack ---
   slack_read(args?: { inboxMessageId?: string; taskId?: string; channelId?: string; threadTs?: string; limit?: number; includeFiles?: boolean }): Promise<unknown>;
   slack_listChannels(args?: { types?: Array<"public" | "private" | "dm" | "mpim">; limit?: number }): Promise<unknown>;
@@ -439,6 +441,16 @@ export interface SwarmSdk {
   // --- human input ---
   request_humanInput(args: Record<string, unknown>): Promise<unknown>;
   approval_cancel(args: { requestId: string; reason?: string }): Promise<unknown>;
+
+  // --- decisions ---
+  systemOne_decide(args: {
+    provider?: "typesafe" | "openrouter" | "laya" | "openai" | "cloudflare";
+    model?: string;
+    state: string | string[] | Record<string, unknown>;
+    questions: Record<string, Record<string, unknown>>;
+    timeoutMs?: number;
+    maxRetries?: number;
+  }): Promise<unknown>;
 }
 
 export interface ScriptStdlib {

package/src/be/secret-registry.ts

@@ -77,8 +77,12 @@ export function encodedForms(value: string): string[] {
 /** Register a stored secret value, plus its encoded forms, with the scrubber. */
 export function registerStoredSecret(value: string | null | undefined, name: string): void {
   if (!value) return;
-  registerVolatileSecret(value, name);
-  for (const form of encodedForms(value)) registerVolatileSecret(form, name);
+  // Config values are hydrated verbatim but consumed trimmed.
+  for (const candidate of new Set([value, value.trim()])) {
+    if (!candidate) continue;
+    registerVolatileSecret(candidate, name);
+    for (const form of encodedForms(candidate)) registerVolatileSecret(form, name);
+  }
 }
 
 export interface SecretRegistryLoadResult {

package/src/be/seed-model-profiles.ts

@@ -0,0 +1,41 @@
+/**
+ * Boot seed for the shipped model profiles: one `<harness>-<tier>` profile per
+ * harness and tier, a 1:1 copy of `DEFAULT_MODEL_TIER_MAP` (runbooks/model-tiers.md
+ * § Model profiles). A global `MODEL_TIER_<HARNESS>_<TIER>` row, when one exists,
+ * overrides the seed's model at seeding time. Seeds use the harness default
+ * route, no effort and no fallbacks.
+ *
+ * Idempotent: an existing name is never overwritten, so an operator's edit to a
+ * seed survives every boot. Harnesses with no portable tier mapping (acp) get
+ * no seeds.
+ */
+import { DEFAULT_MODEL_TIER_MAP, MODEL_TIERS, ProviderNameSchema } from "../types";
+import { createModelProfile } from "./db/model-profiles";
+import { getDbClient } from "./db/runtime";
+import { tierConfigKey } from "./model-tier-keys";
+
+export async function seedModelProfiles(): Promise<number> {
+  let inserted = 0;
+  for (const harness of ProviderNameSchema.options) {
+    for (const tier of MODEL_TIERS) {
+      const fallback = DEFAULT_MODEL_TIER_MAP[harness]?.[tier];
+      if (!fallback) continue;
+      const configured = await getDbClient().get<{ value: string }>(
+        "SELECT value FROM swarm_config WHERE scope = 'global' AND scopeId IS NULL AND key = ? AND isSecret = 0",
+        [tierConfigKey(harness, tier)],
+      );
+      const created = await createModelProfile({
+        name: `${harness}-${tier}`,
+        harness,
+        model: configured?.value.trim() || fallback,
+        effort: null,
+        // Tier values are free-form today (a `latest:` alias, a gateway id); keep that.
+        allowCustomModel: true,
+        description: `The ${tier} tier on ${harness}, seeded from the tier map.`,
+        seededFrom: `tier:${tier}`,
+      });
+      if (created) inserted++;
+    }
+  }
+  return inserted;
+}