pi-pstack-adapter 0.3.0 → 0.5.0

package/src/activation.ts

@@ -2,23 +2,26 @@ import { homedir } from "node:os";
 import { posix, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { GeneratedSkill } from "./types.ts";
-
-/** The pi-subagents tool a delegation skill calls. */
-export const DELEGATION_TOOL = "subagent";
-/** The pi-subagents loader that exposes a registered but inactive `subagent` tool. */
-export const DELEGATION_LOADER = "subagents_enable";
+import {
+  DEFAULT_DELEGATION,
+  type DelegationHost,
+  type ToolPresence,
+  callableTool,
+  delegationHost,
+  resolveDelegation,
+} from "./delegation.ts";
+import type { DelegationProvider, GeneratedSkill } from "./types.ts";
 
 /** The slice of Pi's tool registry that activation reads and writes. */
 export interface ToolLoadout {
-  getAllTools(): readonly { readonly name: string }[];
+  getAllTools(): readonly ToolPresence[];
   getActiveTools(): string[];
   setActiveTools(toolNames: string[]): void;
 }
 
 export type ActivationResult =
-  | { readonly kind: "already-active" }
-  | { readonly kind: "activated" }
+  | { readonly kind: "already-active"; readonly backend: DelegationProvider }
+  | { readonly kind: "activated"; readonly backend: DelegationProvider }
   | { readonly kind: "unavailable" };
 
 export function needsDelegation(skill: GeneratedSkill): boolean {
@@ -54,37 +57,51 @@ export function skillFromReadPath(
 }
 
 /**
- * Adds `subagent` to the active tools, the same selection `subagents_enable` makes, so a
- * delegation skill never depends on the model remembering to call the loader first.
- * Pi applies the new loadout on the next model request.
+ * Adds the delegation backend that capability detection resolves to the active tools, with its
+ * companion tools, so a delegation skill never depends on the model loading it first. For
+ * pi-subagents that is the selection `subagents_enable` makes; T3's `delegate_task` may be
+ * deferred behind `tool_search`. Pi applies the new loadout on the next model request.
  */
-export function activateDelegation(loadout: ToolLoadout): ActivationResult {
-  if (!loadout.getAllTools().some((tool) => tool.name === DELEGATION_TOOL)) return { kind: "unavailable" };
+export function activateDelegation(
+  loadout: ToolLoadout,
+  preferred: DelegationProvider = DEFAULT_DELEGATION,
+  host: DelegationHost = delegationHost(),
+): ActivationResult {
+  const registered = loadout.getAllTools();
+  const resolution = resolveDelegation(registered, preferred, host);
+  if (resolution.kind === "unavailable") return { kind: "unavailable" };
+  const { backend, companions } = resolution;
+  const wanted = [backend.tool, ...companions];
   const active = loadout.getActiveTools();
-  if (active.includes(DELEGATION_TOOL)) return { kind: "already-active" };
-  loadout.setActiveTools([...active, DELEGATION_TOOL]);
-  return { kind: "activated" };
+  const missing = wanted.filter((name) => !active.includes(name));
+  if (missing.length === 0) return { kind: "already-active", backend: backend.id };
+  loadout.setActiveTools([...active, ...missing]);
+  return { kind: "activated", backend: backend.id };
 }
 
 export interface ActivationSources {
   /** Generated skills, or none while the adapter has no upstream checkout. */
   readonly skills: () => readonly GeneratedSkill[];
   readonly modeActive: () => boolean;
+  /** The configured backend preference, read at activation time. */
+  readonly preferred: () => DelegationProvider;
+  /** Defaults to the running process's T3 Code bridge, if any. */
+  readonly host?: DelegationHost;
 }
 
 type ActivationHost = Pick<ExtensionAPI, "on" | "getAllTools" | "getActiveTools" | "setActiveTools">;
 
 /**
- * A delegation skill must not depend on the model remembering to call `subagents_enable`,
- * so a slash command, a model-initiated SKILL.md read, and Poteto Mode each activate
- * `subagent` in code.
+ * A delegation skill must not depend on the model remembering to load its delegation tool,
+ * so a slash command, a model-initiated SKILL.md read, and Poteto Mode each activate it in code.
  */
 export function registerDelegationActivation(pi: ActivationHost, sources: ActivationSources): void {
+  const activate = () => activateDelegation(pi, sources.preferred(), sources.host ?? delegationHost());
   // `input` runs before Pi copies the tool list for the prompt, so the first model request
-  // already carries `subagent`. It also covers messages queued while the agent is streaming.
+  // already carries the tool. It also covers messages queued while the agent is streaming.
   pi.on("input", async (event) => {
     const skill = skillFromPrompt(event.text, sources.skills());
-    if (sources.modeActive() || (skill && needsDelegation(skill))) activateDelegation(pi);
+    if (sources.modeActive() || (skill && needsDelegation(skill))) activate();
   });
 
   pi.on("tool_call", async (event, ctx) => {
@@ -92,12 +109,12 @@ export function registerDelegationActivation(pi: ActivationHost, sources: Activa
     const path = (event.input as { path?: unknown }).path;
     if (typeof path !== "string") return;
     const skill = skillFromReadPath(path, ctx.cwd, sources.skills());
-    if (skill && needsDelegation(skill)) activateDelegation(pi);
+    if (skill && needsDelegation(skill)) activate();
   });
 
   // Backstop for prompts that reach the agent without an `input` event.
   pi.on("before_agent_start", async () => {
-    if (sources.modeActive()) activateDelegation(pi);
+    if (sources.modeActive()) activate();
   });
 }
 

package/src/agents.ts

@@ -1,4 +1,6 @@
-import type { Diagnostic, GeneratedAgent } from "./types.ts";
+import { join } from "node:path";
+import { T3_DELEGATE_TOOL } from "./delegation.ts";
+import type { DelegationProvider, Diagnostic, GeneratedAgent } from "./types.ts";
 
 export const RUNTIME_AGENT_REGISTER_EVENT = "pi-subagents:runtime-agent-register:v1";
 
@@ -19,6 +21,9 @@ export interface EventBus {
 
 export interface AgentRegistrationResult {
   readonly registrations: readonly RuntimeRegistration[];
+  /** Agents no installed extension accepted as named agents. */
+  readonly unregistered: readonly GeneratedAgent[];
+  /** Registrations a provider refused. */
   readonly diagnostics: readonly Diagnostic[];
 }
 
@@ -32,6 +37,7 @@ export function registerAgents(
   namespace: string,
 ): AgentRegistrationResult {
   const registrations: RuntimeRegistration[] = [];
+  const unregistered: GeneratedAgent[] = [];
   const diagnostics: Diagnostic[] = [];
 
   for (const agent of agents) {
@@ -45,12 +51,7 @@ export function registerAgents(
     };
     bus.emit(RUNTIME_AGENT_REGISTER_EVENT, request);
     if (!request.result) {
-      diagnostics.push({
-        level: "warning",
-        resource: `agent:${agent.upstreamName}`,
-        message: `No installed delegation provider accepted \`${agent.generatedName}\`, so pstack workflows cannot delegate to it.`,
-        action: `Install a provider that owns ${RUNTIME_AGENT_REGISTER_EVENT}, for example \`pi install npm:pi-subagents\`.`,
-      });
+      unregistered.push(agent);
       continue;
     }
     if (!request.result.ok) {
@@ -65,5 +66,32 @@ export function registerAgents(
     registrations.push(request.result.registration);
   }
 
-  return { registrations, diagnostics };
+  return { registrations, unregistered, diagnostics };
+}
+
+/**
+ * T3 Code children have no named agents and load an agent from its prompt file, so a missing
+ * pi-subagents registration only blocks delegation when T3 is not the resolved backend.
+ */
+export function unregisteredAgentDiagnostics(
+  unregistered: readonly GeneratedAgent[],
+  backend: DelegationProvider | undefined,
+  promptsDir: string,
+): Diagnostic[] {
+  return unregistered.map((agent) => {
+    const promptPath = join(promptsDir, `${agent.generatedName}.md`);
+    if (backend === "t3") {
+      return {
+        level: "info",
+        resource: `agent:${agent.upstreamName}`,
+        message: `\`${agent.generatedName}\` is not a named agent here. T3 Code children run it by reading ${promptPath} as their system prompt.`,
+      };
+    }
+    return {
+      level: "warning",
+      resource: `agent:${agent.upstreamName}`,
+      message: `No installed delegation provider accepted \`${agent.generatedName}\` as a named agent, so pstack workflows cannot delegate to it through \`subagent\`.`,
+      action: `Install a provider that owns ${RUNTIME_AGENT_REGISTER_EVENT}, for example \`pi install npm:pi-subagents\`, or run Pi inside T3 Code, whose \`${T3_DELEGATE_TOOL}\` loads the agent from ${promptPath}.`,
+    };
+  });
 }

package/src/capabilities.ts

@@ -1,9 +1,18 @@
-import type { CapabilityId, CapabilityStatus } from "./types.ts";
+import {
+  DEFAULT_DELEGATION,
+  type DelegationHost,
+  callableTool,
+  delegationHost,
+  parameterNames,
+  resolveDelegation,
+} from "./delegation.ts";
+import type { CapabilityId, CapabilityStatus, DelegationProvider } from "./types.ts";
 
 export interface ToolDescriptor {
   readonly name: string;
+  readonly exposure?: string;
   readonly parameters?: unknown;
-  readonly sourceInfo?: { readonly source?: string };
+  readonly sourceInfo?: { readonly source?: string; readonly path?: string };
 }
 
 interface CapabilityProbe {
@@ -14,13 +23,10 @@ interface CapabilityProbe {
   readonly recommendation: string;
 }
 
+const DELEGATION_RECOMMENDATION =
+  "Run Pi inside T3 Code, whose `delegate_task` tool starts child agents, or install a delegation provider with named background agents and model selection, for example `pi install npm:pi-subagents`.";
+
 const PROBES: readonly CapabilityProbe[] = [
-  {
-    id: "delegation",
-    toolName: "subagent",
-    requiredParameters: ["agent", "task", "async", "model"],
-    recommendation: "Install a delegation provider that exposes named background agents with model selection, for example `pi install npm:pi-subagents`.",
-  },
   {
     id: "structured-question",
     toolName: "ask_user",
@@ -29,31 +35,50 @@ const PROBES: readonly CapabilityProbe[] = [
   },
 ];
 
-export function detectCapabilities(tools: readonly ToolDescriptor[]): CapabilityStatus[] {
-  return PROBES.map((probe) => {
-    const tool = tools.find((candidate) => candidate.name === probe.toolName);
-    if (!tool) {
-      return { id: probe.id, available: false, recommendation: probe.recommendation };
-    }
-    const properties = parameterNames(tool.parameters);
-    const missing = probe.requiredParameters.filter((name) => !properties.has(name));
-    if (missing.length > 0) {
-      return {
-        id: probe.id,
-        available: false,
-        provider: tool.sourceInfo?.source,
-        recommendation: `The \`${probe.toolName}\` tool is present but does not accept ${missing.join(", ")}. ${probe.recommendation}`,
-      };
-    }
-    return { id: probe.id, available: true, provider: tool.sourceInfo?.source, recommendation: probe.recommendation };
-  });
+export function detectCapabilities(
+  tools: readonly ToolDescriptor[],
+  preferred: DelegationProvider = DEFAULT_DELEGATION,
+  host: DelegationHost = delegationHost(),
+): CapabilityStatus[] {
+  return [detectDelegation(tools, preferred, host), ...PROBES.map((probe) => detectTool(tools, probe))];
 }
 
-function parameterNames(parameters: unknown): Set<string> {
-  if (typeof parameters !== "object" || parameters === null) return new Set();
-  const properties = (parameters as { properties?: unknown }).properties;
-  if (typeof properties !== "object" || properties === null) return new Set();
-  return new Set(Object.keys(properties as Record<string, unknown>));
+/** The first usable backend in preference order satisfies `delegation`. */
+function detectDelegation(
+  tools: readonly ToolDescriptor[],
+  preferred: DelegationProvider,
+  host: DelegationHost,
+): CapabilityStatus {
+  const resolution = resolveDelegation(tools, preferred, host);
+  if (resolution.kind === "unavailable") {
+    return { id: "delegation", available: false, recommendation: [...resolution.problems, DELEGATION_RECOMMENDATION].join(" ") };
+  }
+  return {
+    id: "delegation",
+    available: true,
+    provider: resolution.backend.id === "t3" ? resolution.backend.label : resolution.tool.sourceInfo?.source ?? resolution.backend.label,
+    backend: resolution.backend.id,
+    tools: [resolution.backend.tool, ...resolution.companions],
+    recommendation: DELEGATION_RECOMMENDATION,
+  };
+}
+
+function detectTool(tools: readonly ToolDescriptor[], probe: CapabilityProbe): CapabilityStatus {
+  const tool = callableTool(tools, probe.toolName);
+  if (!tool) {
+    return { id: probe.id, available: false, recommendation: probe.recommendation };
+  }
+  const properties = parameterNames(tool.parameters);
+  const missing = probe.requiredParameters.filter((name) => !properties.has(name));
+  if (missing.length > 0) {
+    return {
+      id: probe.id,
+      available: false,
+      provider: tool.sourceInfo?.source,
+      recommendation: `The \`${probe.toolName}\` tool is present but does not accept ${missing.join(", ")}. ${probe.recommendation}`,
+    };
+  }
+  return { id: probe.id, available: true, provider: tool.sourceInfo?.source, recommendation: probe.recommendation };
 }
 
 export interface PrerequisiteReport {

package/src/certified.ts

@@ -5,9 +5,9 @@
 export const CERTIFIED = {
   repo: "https://github.com/cursor/plugins",
   ref: "main",
-  commit: "e43c7ee26e0038c6c1fa8380dd34ce86ff94cb2a",
+  commit: "dbf49813a39c1a5389c5e28cb8e4c1c2379e2454",
   pluginPath: "pstack",
-  pstackVersion: "0.15.9",
-  skillCount: 50,
+  pstackVersion: "0.15.23",
+  skillCount: 53,
   agentCount: 2,
 } as const;

package/src/config.ts

@@ -1,9 +1,11 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, resolve } from "node:path";
 import { CERTIFIED } from "./certified.ts";
+import { safeEcho } from "./echo.ts";
 import { DEFAULT_NAMESPACE, validateNamespace } from "./namespace.ts";
 import { expandHome } from "./paths.ts";
-import type { SourceSelection, Trust } from "./types.ts";
+import { DEFAULT_DELEGATION, DELEGATION_PROVIDERS, isDelegationProvider } from "./delegation.ts";
+import type { DelegationProvider, SourceSelection, Trust } from "./types.ts";
 
 export interface AdapterConfig {
   readonly namespace: string;
@@ -17,6 +19,8 @@ export interface AdapterConfig {
   readonly allowBootstrap: boolean;
   readonly cacheDir?: string;
   readonly models: Readonly<Record<string, string>>;
+  /** The delegation backend tried first. The other one is the fallback. */
+  readonly delegation: DelegationProvider;
   readonly sources: readonly string[];
 }
 
@@ -30,6 +34,7 @@ export interface ConfigFile {
   allowBootstrap?: boolean;
   cacheDir?: string;
   models?: Record<string, string>;
+  delegation?: string;
 }
 
 export interface ConfigLayer {
@@ -49,6 +54,7 @@ const ENV = {
   allowBootstrap: "PISTACK_ALLOW_BOOTSTRAP",
   cacheDir: "PISTACK_CACHE_DIR",
   models: "PISTACK_MODELS",
+  delegation: "PISTACK_DELEGATION",
 } as const;
 
 export function readConfigFile(path: string): ConfigLayer | undefined {
@@ -61,8 +67,9 @@ export function readConfigFile(path: string): ConfigLayer | undefined {
   let parsed: unknown;
   try {
     parsed = JSON.parse(raw);
-  } catch (error) {
-    throw new Error(`${path} is not valid JSON: ${(error as Error).message}`);
+  } catch {
+    // The parser's message quotes raw file text, which can reach the agent. Say only where to look.
+    throw new Error(`${path} is not valid JSON. Fix the syntax in that file and restart Pi.`);
   }
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     throw new Error(`${path} must contain a JSON object.`);
@@ -82,7 +89,139 @@ export function updateConfigFile(path: string, patch: ConfigFile): ConfigFile {
   return next;
 }
 
-/** `role=provider/model,role2=provider/model2` */
+/** Thinking levels Pi accepts as a `:level` suffix on a model id. */
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+export function isThinkingLevel(value: string): value is ThinkingLevel {
+  return (THINKING_LEVELS as readonly string[]).includes(value);
+}
+
+export interface ModelSpec {
+  readonly model: string;
+  readonly thinking?: ThinkingLevel;
+}
+
+/**
+ * Splits `provider/model[:thinking]`. Only a known level is a suffix, so a model id that
+ * itself contains a colon, such as `ollama/qwen:7b`, stays whole. Pi parses ids the same way.
+ */
+export function splitModelSpec(spec: string): ModelSpec {
+  const separator = spec.lastIndexOf(":");
+  if (separator > 0) {
+    const suffix = spec.slice(separator + 1).toLowerCase();
+    if (isThinkingLevel(suffix)) return { model: spec.slice(0, separator), thinking: suffix };
+  }
+  return { model: spec };
+}
+
+export function joinModelSpec(spec: ModelSpec): string {
+  return spec.thinking === undefined ? spec.model : `${spec.model}:${spec.thinking}`;
+}
+
+export interface AvailableModel {
+  readonly id: string;
+  readonly reasoning?: boolean;
+}
+
+export type ModelAssignment =
+  | { readonly kind: "inherit" }
+  | { readonly kind: "assign"; readonly spec: ModelSpec }
+  | { readonly kind: "rejected"; readonly message: string };
+
+/** Validates a `set_model` request. `available` holds `provider/id` entries from the registry. */
+export function planModelAssignment(
+  model: string,
+  thinking: string | undefined,
+  available: readonly AvailableModel[],
+): ModelAssignment {
+  if (model.trim().toLowerCase() === "inherit") {
+    if (thinking?.trim()) {
+      return {
+        kind: "rejected",
+        message:
+          "A role that inherits the parent session has no thinking level of its own. Pass a `provider/model` with `thinking`, or drop `thinking`.",
+      };
+    }
+    return { kind: "inherit" };
+  }
+  const whole = model.trim();
+  // A registry id that itself ends in a level word, such as `x/model:low`, wins over a split.
+  const exact = available.some((candidate) => candidate.id === whole);
+  const spec = exact ? { model: whole } : splitModelSpec(whole);
+  const requested = thinking?.trim().toLowerCase() || undefined;
+  if (requested !== undefined && !isThinkingLevel(requested)) {
+    return {
+      kind: "rejected",
+      message: `Unknown thinking level \`${safeEcho(thinking).replaceAll('"', "")}\`. Use one of ${THINKING_LEVELS.map((level) => `\`${level}\``).join(", ")}.`,
+    };
+  }
+  if (requested !== undefined && spec.thinking !== undefined && spec.thinking !== requested) {
+    return {
+      kind: "rejected",
+      message: `\`model\` names thinking \`${spec.thinking}\` but \`thinking\` says \`${requested}\`. Pass one of them.`,
+    };
+  }
+  const level = requested !== undefined && isThinkingLevel(requested) ? requested : spec.thinking;
+  if (!isValidModelSpec(spec.model)) return { kind: "rejected", message: invalidModelMessage(spec.model) };
+  if (exact && requested === undefined && splitModelSpec(whole).thinking !== undefined) {
+    // Stored whole, `x/model:low` would read back as model `x/model` at thinking `low`.
+    return {
+      kind: "rejected",
+      message: `Model \`${whole}\` ends in a thinking-level word, so a plain assignment would be misread. Pass \`thinking\` explicitly, for example \`high\`.`,
+    };
+  }
+  const known = available.find((candidate) => candidate.id === spec.model);
+  if (!known) {
+    return {
+      kind: "rejected",
+      message: `No model \`${spec.model}\` is available in this Pi installation. Call this tool with action "models" for real ids, or pass "inherit".`,
+    };
+  }
+  if (level !== undefined && level !== "off" && known.reasoning === false) {
+    return {
+      kind: "rejected",
+      message: `Model \`${spec.model}\` does not support thinking. Drop \`thinking\`, or pick a reasoning model.`,
+    };
+  }
+  const assigned: ModelSpec = { model: spec.model, thinking: level };
+  if (!isValidModelSpec(joinModelSpec(assigned))) return { kind: "rejected", message: invalidModelMessage(joinModelSpec(assigned)) };
+  return { kind: "assign", spec: assigned };
+}
+
+/** Role names reach generated markdown and status tables, so they stay plain kebab-case. */
+const ROLE_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+/**
+ * A model spec is also rendered into markdown the agent reads, so it is printable ASCII with the
+ * markup characters removed. An allow-list of ASCII keeps invisible text (tag characters, zero-width
+ * and bidi controls) out; catalogue ids such as OpenRouter's `~anthropic/...` aliases are ASCII.
+ * A trailing colon is never a valid id or level.
+ */
+const PRINTABLE_ASCII = /^[\x21-\x7e]+$/;
+const MARKUP_CHARACTERS = /[`|<>[\]()\\*]/;
+
+const MAX_MODEL_SPEC_LENGTH = 128;
+
+export function isValidModelSpec(model: string): boolean {
+  const plain = (value: string) => PRINTABLE_ASCII.test(value) && !MARKUP_CHARACTERS.test(value) && !value.endsWith(":");
+  if (model.length > MAX_MODEL_SPEC_LENGTH || !plain(model)) return false;
+  // `x/model::high` splits to `x/model:`, which is no model id.
+  return plain(splitModelSpec(model).model);
+}
+
+export function isValidRole(role: string): boolean {
+  return ROLE_PATTERN.test(role);
+}
+
+export function invalidRoleMessage(role: string): string {
+  return `Invalid role name ${safeEcho(role)}. Use lowercase letters, digits, and hyphens, starting with a letter, for example "bug-fix".`;
+}
+
+function invalidModelMessage(model: unknown): string {
+  return `Invalid model value ${typeof model === "string" ? `(${model.length} characters)` : safeEcho(model)}. Use provider/model or provider/model:thinking with no spaces or markup characters, at most 128 characters.`;
+}
+
+/** `role=provider/model[:thinking],role2=provider/model2` */
 export function parseModelRoles(value: string): Record<string, string> {
   const roles: Record<string, string> = {};
   for (const pair of value.split(",")) {
@@ -90,9 +229,15 @@ export function parseModelRoles(value: string): Record<string, string> {
     if (trimmed === "") continue;
     const separator = trimmed.indexOf("=");
     if (separator <= 0) {
-      throw new Error(`Invalid model role assignment ${JSON.stringify(trimmed)}. Use role=provider/model.`);
+      throw new Error(`Invalid model role assignment ${safeEcho(trimmed)}. Use role=provider/model or role=provider/model:thinking.`);
     }
-    roles[trimmed.slice(0, separator).trim()] = trimmed.slice(separator + 1).trim();
+    const role = trimmed.slice(0, separator).trim();
+    const model = trimmed.slice(separator + 1).trim();
+    if (!isValidRole(role)) throw new Error(invalidRoleMessage(role));
+    // An empty value is an unset variable that expanded to nothing, not a model.
+    if (model === "") continue;
+    if (!isValidModelSpec(model)) throw new Error(invalidModelMessage(model));
+    roles[role] = model;
   }
   return roles;
 }
@@ -106,7 +251,14 @@ export function environmentLayer(env: NodeJS.ProcessEnv): ConfigLayer {
   if (env[ENV.pluginPath]) values.pluginPath = env[ENV.pluginPath];
   if (env[ENV.cacheDir]) values.cacheDir = env[ENV.cacheDir];
   if (env[ENV.allowBootstrap]) values.allowBootstrap = !NEGATIVE.has((env[ENV.allowBootstrap] as string).trim().toLowerCase());
-  if (env[ENV.models]) values.models = parseModelRoles(env[ENV.models] as string);
+  if (env[ENV.models]) {
+    try {
+      values.models = parseModelRoles(env[ENV.models] as string);
+    } catch (error) {
+      throw new Error(`${ENV.models}: ${(error as Error).message}`);
+    }
+  }
+  if (env[ENV.delegation]) values.delegation = (env[ENV.delegation] as string).trim().toLowerCase();
   return { label: "environment", values };
 }
 
@@ -128,7 +280,7 @@ export function mergeConfig(layers: readonly ConfigLayer[]): AdapterConfig {
         merged.ref = undefined;
       }
       if (key === "models") {
-        merged.models = { ...merged.models, ...(value as Record<string, string>) };
+        merged.models = { ...merged.models, ...validatedModels(value, layer.label) };
       } else {
         (merged as Record<string, unknown>)[key] = value;
       }
@@ -151,10 +303,30 @@ export function mergeConfig(layers: readonly ConfigLayer[]): AdapterConfig {
     allowBootstrap: merged.allowBootstrap ?? false,
     cacheDir: merged.cacheDir,
     models: merged.models ?? {},
+    delegation: validateDelegation(merged.delegation, layers),
     sources,
   };
 }
 
+/** A bad `models` entry fails with the layer that holds it, so status can still be reached after a fix. */
+function validatedModels(value: unknown, label: string): Record<string, string> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${label} sets \`models\` to something other than an object of role to provider/model.`);
+  }
+  const models: Record<string, string> = {};
+  for (const [role, model] of Object.entries(value)) {
+    if (!isValidRole(role)) {
+      throw new Error(`${label}: ${invalidRoleMessage(role)} Edit that key in \`models\` in the named file, then restart Pi.`);
+    }
+    if (model === "") continue;
+    if (typeof model !== "string" || !isValidModelSpec(model)) {
+      throw new Error(`${label}: role ${safeEcho(role)}. ${invalidModelMessage(model)}`);
+    }
+    Object.defineProperty(models, role, { value: model, enumerable: true, writable: true, configurable: true });
+  }
+  return models;
+}
+
 /**
  * The certified commit is the default, not a floor. Naming a ref or a repository without a
  * commit means the user asked for that ref, so the pin must get out of the way and trust
@@ -167,6 +339,15 @@ function resolvePin(merged: ConfigFile): string | undefined {
   return CERTIFIED.commit;
 }
 
+function validateDelegation(value: string | undefined, layers: readonly ConfigLayer[]): DelegationProvider {
+  if (value === undefined) return DEFAULT_DELEGATION;
+  if (isDelegationProvider(value)) return value;
+  const owner = [...layers].reverse().find((layer) => layer.values.delegation === value);
+  throw new Error(
+    `${owner?.label ?? "config"} sets \`delegation\` to ${safeEcho(value)}. Use one of ${DELEGATION_PROVIDERS.map((id) => `"${id}"`).join(", ")}, or remove it to prefer "${DEFAULT_DELEGATION}".`,
+  );
+}
+
 function resolveLayerPath(value: string, layers: readonly ConfigLayer[]): string {
   const expanded = expandHome(value);
   if (isAbsolute(expanded)) return expanded;