@bermudi/pi-delegate 0.1.7 → 0.1.9

package/settings.ts

@@ -1,12 +1,18 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { VALID_THINKING } from "./constants.ts";
+
+export interface AgentOverride {
+  model?: string;
+  thinking?: ThinkingLevel;
+  tools?: string[];
+}
 
 export interface DelegateSettings {
-  agentOverrides?: Record<
-    string,
-    { model?: string; thinking?: string; tools?: string[]; skills?: string[] }
-  >;
+  agentOverrides?: Record<string, AgentOverride>;
+  agentOverridesByParentModel?: Record<string, Record<string, AgentOverride>>;
 }
 
 /** Read and validate a JSON settings object, returning null on I/O or parse errors. */
@@ -16,29 +22,192 @@ export function readDelegateSettingsFile(
   try {
     const raw = fs.readFileSync(filePath, "utf-8");
     const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      console.warn(
+        `[delegate] ignoring malformed settings file ${filePath}: expected a JSON object.`,
+      );
       return null;
+    }
     return parsed as Record<string, unknown>;
-  } catch {
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return null;
+    }
+    console.warn(
+      `[delegate] could not read settings file ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
+    );
     return null;
   }
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeOverride(
+  raw: unknown,
+  source: string,
+  agentName: string,
+): AgentOverride | null {
+  if (!isRecord(raw)) {
+    console.warn(
+      `[delegate] ignoring malformed settings override for agent '${agentName}' in ${source}: expected an object.`,
+    );
+    return null;
+  }
+
+  const result: AgentOverride = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (key === "model") {
+      if (typeof value !== "string" || value.trim().length === 0) {
+        console.warn(
+          `[delegate] ignoring malformed settings override for agent '${agentName}' in ${source}: model must be a nonempty string.`,
+        );
+        return null;
+      }
+      result.model = value.trim();
+    } else if (key === "thinking") {
+      if (typeof value !== "string" || !VALID_THINKING.has(value)) {
+        console.warn(
+          `[delegate] ignoring malformed settings override for agent '${agentName}' in ${source}: thinking must be a supported level.`,
+        );
+        return null;
+      }
+      result.thinking = value as ThinkingLevel;
+    } else if (key === "tools") {
+      if (
+        !Array.isArray(value) ||
+        value.some((tool) => typeof tool !== "string")
+      ) {
+        console.warn(
+          `[delegate] ignoring malformed settings override for agent '${agentName}' in ${source}: tools must be a string array.`,
+        );
+        return null;
+      }
+      result.tools = [...value];
+    } else if (key === "skills") {
+      console.warn(
+        `[delegate] ignoring unsupported skills override for agent '${agentName}' in ${source}: per-agent skill filtering is not supported.`,
+      );
+      return null;
+    } else {
+      console.warn(
+        `[delegate] ignoring malformed settings override for agent '${agentName}' in ${source}: unknown field '${key}'.`,
+      );
+      return null;
+    }
+  }
+  return result;
+}
+
+function normalizeOverrides(
+  raw: unknown,
+  source: string,
+): Record<string, AgentOverride> {
+  if (!isRecord(raw)) {
+    console.warn(
+      `[delegate] ignoring malformed agentOverrides in ${source}: expected an object.`,
+    );
+    return {};
+  }
+
+  const result: Record<string, AgentOverride> = {};
+  const seenNames = new Map<string, string>();
+  for (const [agentName, value] of Object.entries(raw)) {
+    const normalizedAgentName = agentName.trim();
+    if (normalizedAgentName.length === 0) {
+      console.warn(
+        `[delegate] ignoring malformed settings override in ${source}: agent name must be nonempty.`,
+      );
+      continue;
+    }
+    const previousName = seenNames.get(normalizedAgentName);
+    if (previousName !== undefined) {
+      console.warn(
+        `[delegate] ignoring duplicate settings override in ${source}: agent keys '${previousName}' and '${agentName}' both normalize to '${normalizedAgentName}'.`,
+      );
+      continue;
+    }
+    seenNames.set(normalizedAgentName, agentName);
+    const override = normalizeOverride(value, source, normalizedAgentName);
+    if (override) result[normalizedAgentName] = override;
+  }
+  return result;
+}
+
+function normalizeOverridesByParentModel(
+  raw: unknown,
+  source: string,
+): Record<string, Record<string, AgentOverride>> {
+  if (!isRecord(raw)) {
+    console.warn(
+      `[delegate] ignoring malformed agentOverridesByParentModel in ${source}: expected an object.`,
+    );
+    return {};
+  }
+
+  const result: Record<string, Record<string, AgentOverride>> = {};
+  const seenModels = new Map<string, string>();
+  for (const [parentModel, overrides] of Object.entries(raw)) {
+    const normalizedParentModel = parentModel.trim();
+    if (normalizedParentModel.length === 0) {
+      console.warn(
+        `[delegate] ignoring malformed parent-model override in ${source}: model key must be nonempty.`,
+      );
+      continue;
+    }
+    const previousModel = seenModels.get(normalizedParentModel);
+    if (previousModel !== undefined) {
+      console.warn(
+        `[delegate] ignoring duplicate parent-model override in ${source}: model keys '${previousModel}' and '${parentModel}' both normalize to '${normalizedParentModel}'.`,
+      );
+      continue;
+    }
+    seenModels.set(normalizedParentModel, parentModel);
+    result[normalizedParentModel] = normalizeOverrides(
+      overrides,
+      `${source} (parent model '${normalizedParentModel}')`,
+    );
+  }
+  return result;
+}
+
 function getDelegateSettings(filePath: string): DelegateSettings | null {
   const settings = readDelegateSettingsFile(filePath);
   if (
     !settings?.delegate ||
     typeof settings.delegate !== "object" ||
     Array.isArray(settings.delegate)
-  )
+  ) {
+    if (settings?.delegate !== undefined) {
+      console.warn(
+        `[delegate] ignoring malformed delegate settings in ${filePath}: expected an object.`,
+      );
+    }
     return null;
-  return settings.delegate as DelegateSettings;
+  }
+  const raw = settings.delegate as Record<string, unknown>;
+  const result: DelegateSettings = {};
+  if (raw.agentOverrides !== undefined) {
+    result.agentOverrides = normalizeOverrides(raw.agentOverrides, filePath);
+  }
+  if (raw.agentOverridesByParentModel !== undefined) {
+    result.agentOverridesByParentModel = normalizeOverridesByParentModel(
+      raw.agentOverridesByParentModel,
+      filePath,
+    );
+  }
+  return result;
 }
 
 const delegateSettingsCache = new Map<string, DelegateSettings | null>();
 
 /** Load merged delegate settings: project overrides user.
- * Result is cached per cwd for the lifetime of the delegate call. */
+ * Result is cached per cwd until the next delegate dispatch clears it. */
 export function loadDelegateSettings(cwd: string): DelegateSettings | null {
   const key = path.resolve(cwd);
   const cached = delegateSettingsCache.get(key);
@@ -68,11 +237,64 @@ export function loadDelegateSettings(cwd: string): DelegateSettings | null {
     return null;
   }
   const result: DelegateSettings = {
-    agentOverrides: {
-      ...(user?.agentOverrides ?? {}),
-      ...(project?.agentOverrides ?? {}),
-    },
+    ...(user?.agentOverrides || project?.agentOverrides
+      ? {
+          agentOverrides: mergeOverrides(
+            user?.agentOverrides,
+            project?.agentOverrides,
+          ),
+        }
+      : {}),
+    ...(user?.agentOverridesByParentModel ||
+    project?.agentOverridesByParentModel
+      ? {
+          agentOverridesByParentModel: mergeParentModelOverrides(
+            user?.agentOverridesByParentModel,
+            project?.agentOverridesByParentModel,
+          ),
+        }
+      : {}),
   };
   delegateSettingsCache.set(key, result);
   return result;
 }
+
+function mergeOverride(
+  base: AgentOverride | undefined,
+  override: AgentOverride | undefined,
+): AgentOverride {
+  return { ...(base ?? {}), ...(override ?? {}) };
+}
+
+function mergeOverrides(
+  user: Record<string, AgentOverride> | undefined,
+  project: Record<string, AgentOverride> | undefined,
+): Record<string, AgentOverride> {
+  const result: Record<string, AgentOverride> = {};
+  for (const name of new Set([
+    ...Object.keys(user ?? {}),
+    ...Object.keys(project ?? {}),
+  ])) {
+    result[name] = mergeOverride(user?.[name], project?.[name]);
+  }
+  return result;
+}
+
+function mergeParentModelOverrides(
+  user: Record<string, Record<string, AgentOverride>> | undefined,
+  project: Record<string, Record<string, AgentOverride>> | undefined,
+): Record<string, Record<string, AgentOverride>> {
+  const result: Record<string, Record<string, AgentOverride>> = {};
+  for (const model of new Set([
+    ...Object.keys(user ?? {}),
+    ...Object.keys(project ?? {}),
+  ])) {
+    result[model] = mergeOverrides(user?.[model], project?.[model]);
+  }
+  return result;
+}
+
+/** Clear settings read from earlier delegate calls so edits are visible. */
+export function clearDelegateSettingsCache(): void {
+  delegateSettingsCache.clear();
+}

package/task-resolution.ts

@@ -1,6 +1,7 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import {
+  BUILTIN_AGENT_NAMES,
   DEFAULT_AGENT_NAME,
   DEFAULT_TOOLS,
   VALID_THINKING,
@@ -8,7 +9,7 @@ import {
 import { TOOL_FACTORIES, resolveToolGroups } from "./tools.ts";
 import { configFor } from "./pool.ts";
 import { isSessionBusy } from "./tickets.ts";
-import { buildSubagentSystemPrompt } from "./agents.ts";
+import { BUILTIN_AGENT_CONFIGS, buildSubagentSystemPrompt } from "./agents.ts";
 import { buildParentTranscript } from "./parent-context.ts";
 import { findAvailableAlternative, resolveModelRequest } from "./model.ts";
 import { resolveModelSpec } from "./config.ts";
@@ -91,6 +92,52 @@ export function validateTasks(
   agents: Map<string, AgentConfig>,
   parentModelId: string | undefined,
 ): DelegateToolResult | null {
+  const unknown: string[] = [];
+  for (const task of tasks) {
+    if (
+      task.agent &&
+      !(BUILTIN_AGENT_NAMES as readonly string[]).includes(task.agent) &&
+      !agents.has(task.agent)
+    ) {
+      unknown.push(task.agent);
+    }
+  }
+  if (unknown.length) {
+    const names = [...new Set([...BUILTIN_AGENT_NAMES, ...agents.keys()])];
+    return noticeResult(
+      `Unknown agent(s): ${unknown.join(", ")}. Available: ${names.join(", ") || "(none)"}. Call delegate with an empty tasks array for help.`,
+      tasks,
+      parentModelId,
+    );
+  }
+
+  // Scratch sessions are deliberately one-shot. This check uses the
+  // effective workspace, so reviewer gets the same protection even when the
+  // caller omits workspace. Explicit scratch is never silently promoted to
+  // shared.
+  for (const [index, task] of tasks.entries()) {
+    const agent = task.agent
+      ? (agents.get(task.agent) ?? BUILTIN_AGENT_CONFIGS[task.agent])
+      : undefined;
+    const workspace = task.workspace ?? agent?.workspace ?? "shared";
+    const sessionAction = task.sessionAction ?? task.action;
+    if (
+      workspace === "scratch" &&
+      (task.sessionId || task.resumeFrom || sessionAction !== undefined)
+    ) {
+      const defaultText =
+        task.workspace === undefined && agent?.workspace === "scratch"
+          ? "defaults to workspace `scratch`"
+          : "uses workspace `scratch`";
+      const persistentAgent = task.agent ?? "agent";
+      return noticeResult(
+        `${formatTaskRef(index, task.id)}: Agent \`${persistentAgent}\` ${defaultText}, which is one-shot and cannot use \`sessionId\`, \`resumeFrom\`, or session actions. Set \`workspace: "shared"\` to use a persistent ${persistentAgent}.`,
+        tasks,
+        parentModelId,
+      );
+    }
+  }
+
   // Disallow same sessionId across multiple parallel tasks (one agent can't serve two prompts concurrently).
   const sessionIds = tasks.map((t) => t.sessionId).filter(Boolean) as string[];
   const duplicateSessions = sessionIds.filter(
@@ -136,21 +183,6 @@ export function validateTasks(
     return noticeResult(duplicateIds.join(" "), tasks, parentModelId);
   }
 
-  const unknown: string[] = [];
-  for (const t of tasks) {
-    if (t.agent && t.agent !== DEFAULT_AGENT_NAME && !agents.has(t.agent)) {
-      unknown.push(t.agent);
-    }
-  }
-  if (unknown.length) {
-    const names = [DEFAULT_AGENT_NAME, ...agents.keys()];
-    return noticeResult(
-      `Unknown agent(s): ${unknown.join(", ")}. Available: ${names.join(", ") || "(none)"}. Call delegate with an empty tasks array for help.`,
-      tasks,
-      parentModelId,
-    );
-  }
-
   return null;
 }
 
@@ -187,11 +219,21 @@ export function resolveTasks(
 
   return tasks.map((t, i) => {
     const isDefaultAgent = t.agent === DEFAULT_AGENT_NAME;
-    const agent = t.agent && !isDefaultAgent ? agents.get(t.agent) : undefined;
+    const agent = t.agent
+      ? (agents.get(t.agent) ?? BUILTIN_AGENT_CONFIGS[t.agent])
+      : undefined;
+    const isBuiltinAgent = agent?.builtin === true;
     const cwd = resolveCwd(t.cwd ?? ctx.cwd, ctx.cwd);
 
     // Load settings-based overrides for this agent
     const settings = loadDelegateSettings(cwd);
+    const parentModelKey = ctx.model
+      ? `${ctx.model.provider}/${ctx.model.id}`
+      : undefined;
+    const parentModelOverride =
+      t.agent && !isDefaultAgent && parentModelKey
+        ? settings?.agentOverridesByParentModel?.[parentModelKey]?.[t.agent]
+        : undefined;
     const agentOverride =
       t.agent && !isDefaultAgent && settings?.agentOverrides?.[t.agent]
         ? settings.agentOverrides[t.agent]
@@ -208,7 +250,8 @@ export function resolveTasks(
     );
     let tools: string[] = [];
     const warnings: string[] = [];
-    if (t.workspace === "scratch") {
+    const workspace = t.workspace ?? agent?.workspace ?? "shared";
+    if (workspace === "scratch") {
       warnings.push(
         "Scratch workspace: relative file changes run in a disposable CoW copy and are discarded.",
       );
@@ -233,9 +276,11 @@ export function resolveTasks(
     if (t.sessionAction !== "close" && t.sessionAction !== "list") {
       tools = resolveToolGroups(
         t.tools ??
+          parentModelOverride?.tools ??
           agentOverride?.tools ??
-          agent?.tools ??
           (isDefaultAgent ? parentNativeTools : undefined) ??
+          (isBuiltinAgent ? agent?.tools : undefined) ??
+          agent?.tools ??
           (isPoolHit ? pooledConfig?.tools : undefined) ??
           DEFAULT_TOOLS,
       );
@@ -318,20 +363,32 @@ export function resolveTasks(
     let thinking: ThinkingLevel = "off";
 
     if (t.sessionAction !== "close" && t.sessionAction !== "list") {
+      const agentType = t.agent ?? "inline";
+      // The built-in `default` profile bypasses delegate/settings model
+      // overrides for backwards compatibility. The other built-ins accept
+      // task and settings.json model overrides, but deliberately ignore the
+      // legacy delegate.json agent model map so they inherit the parent unless
+      // an explicit modern override wins.
+      const modelSpec = isDefaultAgent
+        ? t.model
+        : isBuiltinAgent
+          ? (t.model ?? parentModelOverride?.model ?? agentOverride?.model)
+          : resolveModelSpec({
+              taskModel:
+                t.model ?? parentModelOverride?.model ?? agentOverride?.model,
+              agentType,
+              frontmatterModel: agent?.model,
+            });
+
       // A pool hit always runs its frozen model, but an explicitly requested
       // task/profile model still has to be resolved so checkout can reject a
       // contradictory request rather than silently discarding it. Naming the
       // built-in `default` profile is also explicit: it requests the live
       // parent model, so reuse fails clearly if the pool was frozen differently.
       if (pooledConfig) {
-        const requestedModelSpec =
-          t.model ??
-          (t.agent && !isDefaultAgent
-            ? (agentOverride?.model ?? agent?.model)
-            : undefined);
-        if (requestedModelSpec) {
+        if (modelSpec) {
           const requested = resolveModelRequest(
-            requestedModelSpec,
+            modelSpec,
             ctx.modelRegistry,
             ctx.model,
           );
@@ -339,7 +396,7 @@ export function resolveTasks(
           modelSuffix = requested.strippedSuffix;
           if (!requestedModel) {
             throw new Error(
-              `${formatTaskRef(i, t.id)}: requested model '${requestedModelSpec}' is not available. Check provider config or remove the model field to continue the pooled session.`,
+              `${formatTaskRef(i, t.id)}: requested model '${modelSpec}' is not available. Check provider config or remove the model field to continue the pooled session.`,
             );
           }
         } else if (isDefaultAgent) {
@@ -347,17 +404,6 @@ export function resolveTasks(
         }
         model = pooledConfig.model;
       } else {
-        // The built-in `default` profile bypasses delegate.json and settings:
-        // absent a task override, it means this exact live parent Model object.
-        // Other tasks retain the normal task > config > frontmatter chain.
-        const agentType = t.agent ?? "inline";
-        const modelSpec = isDefaultAgent
-          ? t.model
-          : resolveModelSpec({
-              taskModel: t.model ?? agentOverride?.model,
-              agentType,
-              frontmatterModel: agent?.model,
-            });
         const resolvedRequest = modelSpec
           ? resolveModelRequest(modelSpec, ctx.modelRegistry, ctx.model)
           : undefined;
@@ -376,7 +422,7 @@ export function resolveTasks(
           );
         }
 
-        model = isDefaultAgent
+        model = isBuiltinAgent
           ? (resolvedModel ?? ctx.model)
           : (resolvedModel ??
             findAvailableAlternative(ctx.model, ctx.modelRegistry) ??
@@ -398,15 +444,28 @@ export function resolveTasks(
       // changed, rather than silently reusing a stale frozen value. The final
       // pooled fallback is reachable only when parentDefaults.thinking is
       // undefined (headless parent without a thinking level).
-      const thinkingRaw =
-        t.thinking ??
-        agentOverride?.thinking ??
-        agent?.thinking ??
-        (isPoolHit && !isDefaultAgent ? pooledConfig?.thinking : undefined) ??
-        modelSuffix ??
-        (isDefaultAgent ? parentDefaults.thinking : undefined) ??
-        (isPoolHit ? pooledConfig?.thinking : undefined) ??
-        "off";
+      const thinkingRaw = isBuiltinAgent
+        ? isDefaultAgent
+          ? (t.thinking ??
+            parentModelOverride?.thinking ??
+            agentOverride?.thinking ??
+            modelSuffix ??
+            parentDefaults.thinking ??
+            (isPoolHit ? pooledConfig?.thinking : undefined) ??
+            "off")
+          : (t.thinking ??
+            parentModelOverride?.thinking ??
+            agentOverride?.thinking ??
+            (isPoolHit ? pooledConfig?.thinking : undefined) ??
+            modelSuffix ??
+            parentDefaults.thinking ??
+            "off")
+        : (t.thinking ??
+          agentOverride?.thinking ??
+          agent?.thinking ??
+          (isPoolHit ? pooledConfig?.thinking : undefined) ??
+          modelSuffix ??
+          "off");
       thinking = VALID_THINKING.has(thinkingRaw)
         ? (thinkingRaw as ThinkingLevel)
         : "off";
@@ -423,7 +482,7 @@ export function resolveTasks(
       ...t,
       id: t.id,
       cwd,
-      workspace: t.workspace ?? "shared",
+      workspace,
       systemPrompt,
       model: model!,
       tools,
@@ -433,9 +492,7 @@ export function resolveTasks(
       prompt: prompt ?? "",
       // Keep the built-in selector visible in progress/results. Omitted-agent
       // inline tasks retain the established `ad-hoc` label and config namespace.
-      agentName: isDefaultAgent
-        ? DEFAULT_AGENT_NAME
-        : (agent?.name ?? "ad-hoc"),
+      agentName: agent?.name ?? "ad-hoc",
       warnings,
       reuseIntent: {
         model: requestedModel,

package/types.ts

@@ -18,9 +18,15 @@ export interface AgentConfig {
   name: string;
   description: string;
   model?: string;
-  thinking: ThinkingLevel;
+  /** Markdown agents default invalid/omitted values to "off". Built-ins omit
+   *  this field so they can inherit the parent's thinking level. */
+  thinking?: ThinkingLevel;
   tools: string[];
   systemPrompt: string;
+  /** Built-in profiles are immutable and cannot be shadowed by Markdown. */
+  builtin?: boolean;
+  /** Default workspace for a built-in profile. Custom agents use shared. */
+  workspace?: WorkspaceMode;
   /** Origin of the profile. `claude` denotes imported .claude/agents files. */
   scope?: "project" | "global" | "claude";
 }