@signalridge/pi-subagents 1.2.0 → 1.3.0

package/src/settings.ts

@@ -9,7 +9,41 @@ import type { WorkflowTier } from "@signalridge/pi-subagents-protocol";
 import { NO_FALLBACK } from "./agent-types.js";
 import type { JoinMode, ThinkingLevel } from "./types.js";
 
-export type WorkflowThinking = ThinkingLevel | "inherit";
+/** A tier's thinking value: a level, or `inherit` to keep the parent's. */
+export type TierThinking = ThinkingLevel | "inherit";
+
+/** Historical name for {@link TierThinking}, kept for the workflow tier types. */
+export type WorkflowThinking = TierThinking;
+
+/**
+ * One user-named (model, thinking) pair for ordinary subagent spawns.
+ *
+ * Separate from {@link WorkflowTierProfile} because the key space differs: these
+ * names are whatever the user chose, while workflow tiers are the protocol's
+ * fixed small/medium/large. `description` is what the host agent reads in the
+ * tool description to decide between tiers, so it is prose about the job the
+ * tier is for, not about the model.
+ */
+export interface AgentTierProfile {
+  /** `inherit` keeps the parent model; other values are provider/model references. */
+  model: string;
+  /** `inherit` keeps the parent thinking level; other values are clamped natively. */
+  thinking: TierThinking;
+  /** Shown to the host agent. Defaults to the tier key when omitted. */
+  description?: string;
+}
+
+/** Tier policy for ordinary subagent spawns, resolved by `agent-tiers.ts`. */
+export interface AgentTiersSettings {
+  /** Applied when neither the caller nor the agent names a tier. */
+  defaultTier?: string;
+  /** A configured entry replaces the complete entry inherited from global settings. */
+  profiles?: Record<string, AgentTierProfile>;
+  /** Tombstones for malformed explicit profiles; not a user policy field. */
+  blockedProfiles?: string[];
+  /** Tombstone for a malformed defaultTier; not a user policy field. */
+  blockedDefaultTier?: boolean;
+}
 
 export interface WorkflowTierProfile {
   /** `inherit` keeps the parent model; other values are provider/model references. */
@@ -42,6 +76,12 @@ export const DEFAULT_WORKFLOW_TIER_PROFILES: Readonly<Record<WorkflowTier, Workf
 export interface SubagentsSettings {
   /** Semantic model-plus-thinking profiles used by workflow-owned spawns. */
   workflow?: WorkflowSettings;
+  /**
+   * User-named model tiers for ordinary subagent spawns. Independent of
+   * `workflow` above: the key space is arbitrary, and `pi-workflows` never reads
+   * these. See `agent-tiers.ts` for resolution and precedence.
+   */
+  agentTiers?: AgentTiersSettings;
   maxConcurrent?: number;
   /**
    * 0 = unlimited — the extension's single source of truth for that convention:
@@ -166,6 +206,8 @@ export interface SettingsAppliers {
   setFallbackSubagent: (v: string | undefined) => void;
   /** Optional because non-runtime settings tests and consumers need not apply workflow state. */
   setWorkflow?: (settings: WorkflowSettings) => void;
+  /** Optional for the same reason as `setWorkflow`. */
+  setAgentTiers?: (settings: AgentTiersSettings) => void;
 }
 
 /** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
@@ -184,6 +226,11 @@ const VALID_THINKING_LEVELS: ReadonlySet<string> = new Set([
 ]);
 const WORKFLOW_TIER_NAMES: readonly WorkflowTier[] = ["small", "medium", "large"];
 const MAX_MODEL_REFERENCE_LENGTH = 512;
+/** Mirrors MAX_AGENT_TIER_KEY_LENGTH in agent-tiers.ts; duplicated to keep settings dependency-free. */
+const MAX_AGENT_TIER_KEY_LENGTH = 64;
+/** Bounds a hand-edited config; far above any realistic number of tiers. */
+const MAX_AGENT_TIER_PROFILES = 64;
+const MAX_AGENT_TIER_DESCRIPTION_LENGTH = 512;
 
 // Sanity ceilings — prevent hand-edited configs from asking for values that
 // make no operational sense (e.g. 1e6 concurrent subagents). Permissive enough
@@ -250,6 +297,70 @@ function sanitizeWorkflow(raw: unknown): WorkflowSettings | undefined {
   return out.defaultTier !== undefined || out.tiers !== undefined || out.blockedTiers !== undefined || out.blockedDefaultTier !== undefined ? out : undefined;
 }
 
+function isAgentTierKey(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= MAX_AGENT_TIER_KEY_LENGTH &&
+    value.trim() === value &&
+    !/\s/u.test(value)
+  );
+}
+
+/**
+ * A profile is all-or-nothing, for the same reason a workflow profile is: half
+ * a profile with an implied `inherit` makes a typo look like a policy choice.
+ * `description` is the one optional field — it is prose for the tool
+ * description, and its absence has an obvious meaning (use the key).
+ */
+function sanitizeAgentTierProfile(raw: unknown): AgentTierProfile | undefined {
+  if (!isRecord(raw)) return undefined;
+  const keys = Object.keys(raw);
+  if (keys.some((key) => key !== "model" && key !== "thinking" && key !== "description")) return undefined;
+  if (!Object.hasOwn(raw, "model") || !Object.hasOwn(raw, "thinking")) return undefined;
+  if (!validWorkflowModelReference(raw.model) || !validThinkingLevel(raw.thinking)) return undefined;
+  if (
+    Object.hasOwn(raw, "description") &&
+    (typeof raw.description !== "string" ||
+      raw.description.trim().length === 0 ||
+      raw.description.length > MAX_AGENT_TIER_DESCRIPTION_LENGTH)
+  ) {
+    return undefined;
+  }
+  return {
+    model: raw.model.trim(),
+    thinking: raw.thinking,
+    ...(typeof raw.description === "string" ? { description: raw.description.trim() } : {}),
+  };
+}
+
+function sanitizeAgentTiers(raw: unknown): AgentTiersSettings | undefined {
+  if (!isRecord(raw)) return undefined;
+  const out: AgentTiersSettings = {};
+  if (isAgentTierKey(raw.defaultTier)) out.defaultTier = raw.defaultTier;
+  if (Object.hasOwn(raw, "defaultTier") && !isAgentTierKey(raw.defaultTier)) out.blockedDefaultTier = true;
+  if (raw.blockedDefaultTier === true) out.blockedDefaultTier = true;
+  if (Array.isArray(raw.blockedProfiles)) {
+    const blocked = [...new Set(raw.blockedProfiles.filter(isAgentTierKey))];
+    if (blocked.length > 0) out.blockedProfiles = blocked;
+  }
+  if (isRecord(raw.profiles)) {
+    const profiles: Record<string, AgentTierProfile> = {};
+    for (const key of Object.keys(raw.profiles).slice(0, MAX_AGENT_TIER_PROFILES)) {
+      if (!isAgentTierKey(key)) continue;
+      const profile = sanitizeAgentTierProfile(raw.profiles[key]);
+      if (profile) profiles[key] = profile;
+    }
+    if (Object.keys(profiles).length > 0) out.profiles = profiles;
+  }
+  return out.defaultTier !== undefined ||
+    out.profiles !== undefined ||
+    out.blockedProfiles !== undefined ||
+    out.blockedDefaultTier !== undefined
+    ? out
+    : undefined;
+}
+
 function isWorkflowTierValue(value: unknown): value is WorkflowTier {
   return value === "small" || value === "medium" || value === "large";
 }
@@ -323,6 +434,8 @@ function sanitize(raw: unknown): SubagentsSettings {
 
   const workflow = sanitizeWorkflow(r.workflow);
   if (workflow) out.workflow = workflow;
+  const agentTiers = sanitizeAgentTiers(r.agentTiers);
+  if (agentTiers) out.agentTiers = agentTiers;
   return out;
 }
 
@@ -351,9 +464,28 @@ interface WorkflowSource {
   blockedDefaultTier: boolean;
 }
 
+/**
+ * Presence of each agent-tier entry in one file, kept separate from the
+ * sanitized value so the merge can tell "the project did not mention this
+ * profile" from "the project mentioned it and it was malformed". Only the
+ * second may block the global entry, and neither may silently revive it.
+ */
+interface AgentTiersSource {
+  present: boolean;
+  object: boolean;
+  defaultTierPresent: boolean;
+  defaultTier?: string;
+  profilesPresent: boolean;
+  profilesObject: boolean;
+  profileEntries: Record<string, AgentTierProfile | undefined>;
+  blockedProfiles: string[];
+  blockedDefaultTier: boolean;
+}
+
 interface ReadSettings {
   settings: SubagentsSettings;
   workflow: WorkflowSource;
+  agentTiers: AgentTiersSource;
 }
 
 function emptyWorkflowSource(): WorkflowSource {
@@ -369,6 +501,116 @@ function emptyWorkflowSource(): WorkflowSource {
   };
 }
 
+function emptyAgentTiersSource(): AgentTiersSource {
+  return {
+    present: false,
+    object: false,
+    defaultTierPresent: false,
+    blockedDefaultTier: false,
+    profilesPresent: false,
+    profilesObject: false,
+    profileEntries: {},
+    blockedProfiles: [],
+  };
+}
+
+/** Preserve invalid agent-tier entry presence so project policy cannot resurrect a global entry. */
+function agentTiersSource(raw: unknown): AgentTiersSource {
+  if (!isRecord(raw) || !Object.hasOwn(raw, "agentTiers")) return emptyAgentTiersSource();
+  const value = raw.agentTiers;
+  if (!isRecord(value)) {
+    return { ...emptyAgentTiersSource(), present: true, object: false, blockedDefaultTier: true };
+  }
+
+  const source: AgentTiersSource = {
+    present: true,
+    object: true,
+    defaultTierPresent: Object.hasOwn(value, "defaultTier"),
+    blockedDefaultTier:
+      (Object.hasOwn(value, "defaultTier") && !isAgentTierKey(value.defaultTier)) || value.blockedDefaultTier === true,
+    ...(isAgentTierKey(value.defaultTier) ? { defaultTier: value.defaultTier } : {}),
+    profilesPresent: Object.hasOwn(value, "profiles"),
+    profilesObject: isRecord(value.profiles),
+    profileEntries: {},
+    blockedProfiles: Array.isArray(value.blockedProfiles) ? value.blockedProfiles.filter(isAgentTierKey) : [],
+  };
+
+  if (isRecord(value.profiles)) {
+    for (const key of Object.keys(value.profiles).slice(0, MAX_AGENT_TIER_PROFILES)) {
+      if (!isAgentTierKey(key)) continue;
+      const profile = sanitizeAgentTierProfile(value.profiles[key]);
+      source.profileEntries[key] = profile;
+      if (!profile) source.blockedProfiles.push(key);
+    }
+  }
+  source.blockedProfiles = [...new Set(source.blockedProfiles)];
+  return source;
+}
+
+/**
+ * Global supplies the catalogue, project edits it. A project profile replaces
+ * its global namesake whole — never field by field, which would let a project
+ * change a model while inheriting a thinking level nobody chose for that pair.
+ */
+function mergeAgentTierSources(
+  global: AgentTiersSource,
+  project: AgentTiersSource,
+): AgentTiersSettings | undefined {
+  if (!global.present && !project.present) return undefined;
+
+  const merged: AgentTiersSettings = {};
+  if (project.present && !project.object) {
+    // The project said "agentTiers" and gave something that is not an object.
+    // Inheriting the global catalogue here would run models the project was
+    // trying to change, so the whole policy is blocked instead.
+    merged.blockedDefaultTier = true;
+    const inherited = [
+      ...new Set([...Object.keys(global.profileEntries), ...global.blockedProfiles]),
+    ].sort((a, b) => a.localeCompare(b));
+    if (inherited.length > 0) merged.blockedProfiles = inherited;
+    return merged;
+  }
+
+  if (project.defaultTierPresent) {
+    if (project.defaultTier !== undefined) merged.defaultTier = project.defaultTier;
+    else merged.blockedDefaultTier = true;
+  } else {
+    if (global.defaultTier !== undefined) merged.defaultTier = global.defaultTier;
+    if (global.blockedDefaultTier || project.blockedDefaultTier) merged.blockedDefaultTier = true;
+  }
+
+  const blocked = new Set<string>([...global.blockedProfiles, ...project.blockedProfiles]);
+  const profiles: Record<string, AgentTierProfile> = {};
+  const keys = [...new Set([...Object.keys(global.profileEntries), ...Object.keys(project.profileEntries)])];
+  for (const key of keys) {
+    if (project.profilesPresent && !project.profilesObject) {
+      blocked.add(key);
+      continue;
+    }
+    if (Object.hasOwn(project.profileEntries, key)) {
+      const profile = project.profileEntries[key];
+      if (profile) {
+        profiles[key] = profile;
+        blocked.delete(key);
+      } else {
+        blocked.add(key);
+      }
+      continue;
+    }
+    const inherited = global.profileEntries[key];
+    if (inherited) profiles[key] = inherited;
+  }
+
+  if (Object.keys(profiles).length > 0) merged.profiles = profiles;
+  if (blocked.size > 0) merged.blockedProfiles = [...blocked].sort((a, b) => a.localeCompare(b));
+  return merged.defaultTier !== undefined ||
+    merged.profiles !== undefined ||
+    merged.blockedProfiles !== undefined ||
+    merged.blockedDefaultTier !== undefined
+    ? merged
+    : undefined;
+}
+
 /** Preserve invalid workflow entry presence so project policy cannot resurrect a global entry. */
 function workflowSource(raw: unknown): WorkflowSource {
   if (!isRecord(raw) || !Object.hasOwn(raw, "workflow")) return emptyWorkflowSource();
@@ -415,10 +657,12 @@ function workflowSource(raw: unknown): WorkflowSource {
 }
 
 function readSettingsFile(path: string): ReadSettings {
-  if (!existsSync(path)) return { settings: {}, workflow: emptyWorkflowSource() };
+  if (!existsSync(path)) {
+    return { settings: {}, workflow: emptyWorkflowSource(), agentTiers: emptyAgentTiersSource() };
+  }
   try {
     const raw: unknown = JSON.parse(readFileSync(path, "utf-8"));
-    return { settings: sanitize(raw), workflow: workflowSource(raw) };
+    return { settings: sanitize(raw), workflow: workflowSource(raw), agentTiers: agentTiersSource(raw) };
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
     console.warn(`[pi-subagents] Ignoring malformed settings at ${path}: ${reason}`);
@@ -431,6 +675,9 @@ function readSettingsFile(path: string): ReadSettings {
         blockedTiers: [...WORKFLOW_TIER_NAMES],
         blockedDefaultTier: true,
       },
+      // An unreadable file may have held the tier catalogue; block rather than
+      // fall through to whatever global happens to define.
+      agentTiers: { ...emptyAgentTiersSource(), present: true, object: false, blockedDefaultTier: true },
     };
   }
 }
@@ -444,13 +691,15 @@ function readSettingsFile(path: string): ReadSettings {
 export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
   const global = readSettingsFile(globalPath());
   const project = readSettingsFile(projectPath(cwd));
-  const { workflow: _globalWorkflow, ...globalSettings } = global.settings;
-  const { workflow: _projectWorkflow, ...projectSettings } = project.settings;
+  const { workflow: _globalWorkflow, agentTiers: _globalAgentTiers, ...globalSettings } = global.settings;
+  const { workflow: _projectWorkflow, agentTiers: _projectAgentTiers, ...projectSettings } = project.settings;
   const workflow = mergeWorkflowSources(global.workflow, project.workflow);
+  const agentTiers = mergeAgentTierSources(global.agentTiers, project.agentTiers);
   return {
     ...globalSettings,
     ...projectSettings,
     ...(workflow ? { workflow } : {}),
+    ...(agentTiers ? { agentTiers } : {}),
   };
 }
 
@@ -533,6 +782,9 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   if (typeof s.fleetView === "boolean") appliers.setFleetView(s.fleetView);
   if (typeof s.outputTranscript === "boolean") appliers.setOutputTranscript(s.outputTranscript);
   if (s.workflow) appliers.setWorkflow?.(s.workflow);
+  // Applied unconditionally so a session that had tiers and no longer does gets
+  // the empty catalogue rather than keeping the previous one.
+  appliers.setAgentTiers?.(s.agentTiers ?? {});
 }
 
 /**

package/src/types.ts

@@ -5,6 +5,7 @@
 import type { ThinkingLevel } from "@earendil-works/pi-ai";
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import type { WorkflowTier } from "@signalridge/pi-subagents-protocol";
+import type { AgentTierResolutionSnapshot } from "./agent-tiers.js";
 import type { LifetimeUsage } from "./usage.js";
 import type { WorkflowTierResolutionSnapshot } from "./workflow-tiers.js";
 import type { WorktreeCleanupResult, WorktreeInfo } from "./worktree.js";
@@ -50,6 +51,14 @@ export interface AgentConfig {
   excludeExtensions?: string[];
   /** true = inherit all, string[] = only listed, false = none */
   skills: true | string[] | false;
+  /**
+   * This agent's default model tier, from `tier:` in its frontmatter. A tier
+   * names a (model, thinking) pair in `agentTiers.profiles`; a tier passed at
+   * the call site overrides it. When set, it takes precedence over the legacy
+   * `model`/`thinking` fields below, which stay only for agents written before
+   * tiers existed.
+   */
+  agentTier?: string;
   model?: string;
   thinking?: ThinkingLevel;
   maxTurns?: number;
@@ -171,6 +180,15 @@ export interface AgentInvocation {
   tier?: WorkflowTier;
   /** Immutable model/thinking resolution captured by pi-subagents. */
   tierSnapshot?: WorkflowTierResolutionSnapshot;
+  /**
+   * User-named tier applied to an ordinary spawn. Deliberately a separate field
+   * from `tier` above: that one is the workflow protocol's small/medium/large
+   * union, and widening it to hold arbitrary names would take the protocol's
+   * exhaustiveness with it.
+   */
+  agentTier?: string;
+  /** Immutable model/thinking resolution for `agentTier`. */
+  agentTierSnapshot?: AgentTierResolutionSnapshot;
   maxTurns?: number;
   isolated?: boolean;
   inheritContext?: boolean;
@@ -188,6 +206,7 @@ export type AgentRecordSnapshot = Omit<Readonly<AgentRecord>, "session" | "abort
   readonly pendingSteers?: readonly string[];
   readonly invocation?: Readonly<AgentInvocation> & {
     readonly tierSnapshot?: Readonly<NonNullable<AgentInvocation["tierSnapshot"]>>;
+    readonly agentTierSnapshot?: Readonly<NonNullable<AgentInvocation["agentTierSnapshot"]>>;
   };
 };
 
@@ -234,6 +253,8 @@ export interface ScheduledSubagent {
   // spawn params (subset of Agent tool params; no inherit_context, no resume)
   subagent_type: SubagentType;
   prompt: string;
+  /** Model tier key, resolved at fire time against the then-current catalogue. */
+  tier?: string;
   model?: string;
   thinking?: ThinkingLevel;
   max_turns?: number;

package/src/ui/conversation-viewer.ts

@@ -177,11 +177,16 @@ export class ConversationViewer implements Component {
       const fitted = truncateToWidth(pad(content, innerW), innerW, "...", true);
       return ` ${fitted} `;
     };
-    const hrTop = row(th.bold("Agent conversation"));
-    const hrBot = row("");
+    // Two full-width rules, top and bottom, and none in between. The overlay
+    // floats over the transcript, so without them there is no telling where the
+    // agent's conversation ends and the parent's resumes. An inner rule would be
+    // a third horizontal line competing with the two that mark the boundary, and
+    // a four-sided box would cost two columns on every row for the same job.
+    const rule = () => th.fg("border", "─".repeat(Math.max(0, width)));
     const hrMid = row("");
 
-    lines.push(hrTop);
+    lines.push(rule());
+    lines.push(row(th.bold("Agent conversation")));
     const name = getDisplayName(this.record.type);
     const modeLabel = getPromptModeLabel(this.record.type);
     const modeTag = modeLabel ? th.fg("dim", `mode ${modeLabel}`) : undefined;
@@ -256,7 +261,7 @@ export class ConversationViewer implements Component {
       const footerGap = Math.max(1, innerW - visibleWidth(footerLeft) - visibleWidth(footerRight));
       lines.push(row(footerLeft + " ".repeat(footerGap) + footerRight));
     }
-    lines.push(hrBot);
+    lines.push(rule());
 
     return lines;
   }