@nredd/pi-subagents 0.22.0-nredd.7 → 0.22.0-nredd.9

package/src/schedule.ts

@@ -15,15 +15,14 @@
  *     `subagent-notification` path. No new delivery code.
  */
 
-import type { Model } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Cron } from "croner";
 import { nanoid } from "nanoid";
 import type { AgentManager } from "./agent-manager.js";
 import { normalizeMaxTurns } from "./agent-runner.js";
-import { resolveSpawnType } from "./agent-types.js";
+import { getAgentConfig, resolveSpawnType } from "./agent-types.js";
 import { type Clock, realClock, type TimerHandle } from "./clock.js";
-import { resolveModel } from "./model-resolver.js";
+import { admitModelSelection, type ModelSelection, selectModel } from "./model-selection.js";
 import { checkAdmission, describeBlock, mayPark, modelRef, PARKED_RESUME_DELAY_MS, QUOTA_RESTART_GRACE_MS } from "./quota-admission.js";
 import type { ScheduleStore } from "./schedule-store.js";
 import type { IsolationMode, ScheduledSubagent, SubagentType, ThinkingLevel } from "./types.js";
@@ -52,8 +51,17 @@ export interface NewJobInput {
   quotaParked?: boolean;
 }
 
+/** What `start()` binds, captured by a fire so a later session switch cannot leak into it. */
+interface BoundSession {
+  store: ScheduleStore;
+  pi: ExtensionAPI;
+  ctx: ExtensionContext;
+  manager: AgentManager;
+}
+
 /** Optional in-process scheduling dependencies; omitted clock uses native time. */
 export interface SubagentSchedulerOptions {
+  homeDir?: string;
   clock?: Clock;
 }
 
@@ -61,17 +69,22 @@ export class SubagentScheduler {
   private readonly clock: Clock;
   private jobs = new Map<string, Cron>();
   private intervals = new Map<string, TimerHandle>();
+  private scheduled = new Map<string, object>();
+  private admissions = new Map<string, Set<AbortController>>();
+  /** Newest pending admission per job that wrote "running", with the status it replaced. */
+  private pendingRuns = new Map<string, { token: AbortController; prior: ScheduledSubagent["lastStatus"] }>();
   private store: ScheduleStore | undefined;
   private pi: ExtensionAPI | undefined;
   private ctx: ExtensionContext | undefined;
   private manager: AgentManager | undefined;
 
-  constructor(options: SubagentSchedulerOptions = {}) {
+  constructor(private readonly options: SubagentSchedulerOptions = {}) {
     this.clock = options.clock ?? realClock;
   }
 
   /** Start the scheduler: bind to a session's store and arm enabled jobs. */
   start(pi: ExtensionAPI, ctx: ExtensionContext, manager: AgentManager, store: ScheduleStore): void {
+    this.stop();
     this.pi = pi;
     this.ctx = ctx;
     this.manager = manager;
@@ -88,6 +101,10 @@ export class SubagentScheduler {
     this.jobs.clear();
     for (const t of this.intervals.values()) t.cancel();
     this.intervals.clear();
+    for (const admissions of this.admissions.values()) for (const admission of admissions) admission.abort();
+    this.admissions.clear();
+    this.pendingRuns.clear();
+    this.scheduled.clear();
     this.store = undefined;
     this.pi = undefined;
     this.ctx = undefined;
@@ -138,7 +155,7 @@ export class SubagentScheduler {
     }
     const job = this.buildJob(input);
     store.add(job);
-    if (job.enabled) this.scheduleJob(job);
+    this.scheduleJob(job); // buildJob always creates an enabled job
     this.emit({ type: "added", job });
     return job;
   }
@@ -183,8 +200,8 @@ export class SubagentScheduler {
   // ── Scheduling primitives ────────────────────────────────────────────
 
   private scheduleJob(job: ScheduledSubagent): void {
-    const store = this.store;
-    if (!store) return;
+    const store = this.requireStore();
+    this.scheduled.set(job.id, {});
     try {
       if (job.scheduleType === "interval" && job.intervalMs) {
         const t = this.clock.setInterval(() => this.executeJob(job.id), job.intervalMs);
@@ -206,6 +223,7 @@ export class SubagentScheduler {
           this.intervals.set(job.id, t);
         } else {
           // Past timestamp — disable, mark error, never fire
+          this.scheduled.delete(job.id);
           store.update(job.id, { enabled: false, lastStatus: "error" });
           this.emit({ type: "error", jobId: job.id, error: `Scheduled time ${job.schedule} is in the past` });
         }
@@ -214,11 +232,16 @@ export class SubagentScheduler {
         this.jobs.set(job.id, cron);
       }
     } catch (err) {
+      // Nothing armed, so no token: a stale entry would admit a fire for a job with no timer.
+      this.scheduled.delete(job.id);
       this.emit({ type: "error", jobId: job.id, error: err instanceof Error ? err.message : String(err) });
     }
   }
 
   private unscheduleJob(id: string): void {
+    this.scheduled.delete(id);
+    for (const admission of this.admissions.get(id) ?? []) admission.abort();
+    this.admissions.delete(id);
     const cron = this.jobs.get(id);
     if (cron) {
       cron.stop();
@@ -241,28 +264,60 @@ export class SubagentScheduler {
     const pi = this.pi;
     const ctx = this.ctx;
     const manager = this.manager;
-    if (!store || !pi || !ctx || !manager) return;
+    const scheduled = this.scheduled.get(id);
+    if (!store || !pi || !ctx || !manager || !scheduled) return;
     const job = store.get(id);
     if (!job?.enabled) return;
 
+    // A fire that overlaps a pending admission inherits its prior status.
+    const previous = this.pendingRuns.get(id);
+    const prior = previous ? previous.prior : job.lastStatus;
+    this.pendingRuns.delete(id);
     store.update(id, { lastStatus: "running" });
 
-    // Resolve model at fire time — registry contents may have changed since the
-    // job was created (auth added/removed). Fall back silently to spawn-default
-    // if resolution fails; the spawn path handles undefined model gracefully.
-    let resolvedModel: Model<any> | undefined;
-    if (job.model) {
-      const r = resolveModel(job.model, ctx.modelRegistry);
-      if (typeof r !== "string") resolvedModel = r;
+    // Resolve the original request at fire time, using the same type and model
+    // policy as a manual dispatch. Never drop a failed explicit override.
+    const dispatch = resolveSpawnType(job.subagent_type);
+    const config = dispatch.ok ? getAgentConfig(dispatch.type) : undefined;
+    const selection = dispatch.ok ? selectModel({
+      homeDir: this.options.homeDir,
+      agentType: dispatch.type, definitionModel: config?.model, agentLabel: config?.displayName,
+      paramModel: job.model, parentModel: ctx.model, registry: ctx.modelRegistry, cwd: ctx.cwd,
+    }) : dispatch.message;
+    if (typeof selection === "string") {
+      store.update(id, { lastRun: new Date(this.clock.now()).toISOString(), lastStatus: "error" });
+      this.emit({ type: "error", jobId: id, error: selection });
+      return;
     }
 
+    if (selection.scopeWarning) ctx.ui.notify(selection.scopeWarning, "warning");
+
     // A quota-parked job re-asks the router before starting: the window it
     // waited for may have refilled while another is still exhausted.
-    const admissionModel = resolvedModel ?? ctx.model;
-    if (job.quotaParked && admissionModel) {
-      void checkAdmission(pi.events, modelRef(admissionModel)).then(block => {
+    const admissionModel = selection.model;
+    if ((job.quotaParked || selection.tierBinding) && admissionModel) {
+      const controller = new AbortController();
+      const admissions = this.admissions.get(id) ?? new Set<AbortController>();
+      admissions.add(controller);
+      this.admissions.set(id, admissions);
+      this.pendingRuns.set(id, { token: controller, prior });
+      // Cancelled before spawn: undo this admission's "running", never a newer one's.
+      controller.signal.addEventListener("abort", () => {
+        if (this.pendingRuns.get(id)?.token !== controller) return;
+        this.pendingRuns.delete(id);
+        if (store.get(id)?.lastStatus === "running") store.update(id, { lastStatus: prior });
+      }, { once: true });
+      const admission = selection.tierBinding
+        ? admitModelSelection(selection, ctx.modelRegistry, pi.events, this.clock, controller.signal)
+        : checkAdmission(pi.events, modelRef(admissionModel), undefined, this.clock, controller.signal);
+      const settle = (): void => {
+        if (this.pendingRuns.get(id)?.token === controller) this.pendingRuns.delete(id);
+      };
+      void admission.then(block => {
+        if (this.store !== store || this.ctx !== ctx || this.scheduled.get(id) !== scheduled) return;
+        settle();
         if (!block) {
-          this.spawnJob(id, resolvedModel);
+          this.spawnJob({ store, pi, ctx, manager }, id, selection);
         } else if (mayPark(block) && block.resetAt > this.clock.now()) {
           this.repark(id, block.resetAt);
         } else {
@@ -272,29 +327,36 @@ export class SubagentScheduler {
           this.store?.update(id, { lastRun: new Date(this.clock.now()).toISOString(), lastStatus: "error" });
           this.emit({ type: "error", jobId: id, error: `${describeBlock(block)} The agent was not started.` });
         }
+      }).catch(error => {
+        if (this.store !== store || this.scheduled.get(id) !== scheduled) return;
+        settle();
+        store.update(id, { lastStatus: "error" });
+        this.emit({ type: "error", jobId: id, error: error instanceof Error ? error.message : String(error) });
+      }).finally(() => {
+        admissions.delete(controller);
+        if (admissions.size === 0 && this.admissions.get(id) === admissions) this.admissions.delete(id);
       });
       return;
     }
-    this.spawnJob(id, resolvedModel);
+    this.spawnJob({ store, pi, ctx, manager }, id, selection);
   }
 
-  /** Re-arm a quota-parked one-shot at a later reset instead of starting it. */
+  /**
+   * Re-arm a quota-parked one-shot at a later reset instead of starting it.
+   * A job removed while admission was pending stays removed: `updateJob` is a
+   * no-op for an unknown id.
+   */
   private repark(id: string, resetAt: number): void {
-    if (!this.store?.get(id)) return;
     this.updateJob(id, {
       enabled: true,
       schedule: new Date(resetAt + QUOTA_RESTART_GRACE_MS).toISOString(),
       lastStatus: undefined,
+      quotaParked: true,
     });
   }
 
   /** Spawn a fired job (bypassing the concurrency queue) and persist its outcome. */
-  private spawnJob(id: string, resolvedModel: Model<any> | undefined): void {
-    const store = this.store;
-    const pi = this.pi;
-    const ctx = this.ctx;
-    const manager = this.manager;
-    if (!store || !pi || !ctx || !manager) return;
+  private spawnJob({ store, pi, ctx, manager }: BoundSession, id: string, selection: ModelSelection): void {
     const job = store.get(id);
     if (!job) return;
 
@@ -312,7 +374,8 @@ export class SubagentScheduler {
         description: job.description,
         isBackground: true,
         bypassQueue: true,
-        model: resolvedModel,
+        model: selection.model,
+        modelSelection: selection,
         maxTurns: job.max_turns,
         isolated: job.isolated,
         thinkingLevel: job.thinking,
@@ -429,7 +492,8 @@ export class SubagentScheduler {
       new Cron(expr, () => {});
       return { valid: true };
     } catch (e) {
-      return { valid: false, error: e instanceof Error ? e.message : "Invalid cron expression" };
+      // Croner only throws Error subclasses (TypeError, RangeError).
+      return { valid: false, error: (e as Error).message };
     }
   }
 

package/src/settings.ts

@@ -4,9 +4,12 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { NO_FALLBACK } from "./agent-types.js";
 import { readEnterpriseLocalManifest } from "./enterprise-local.js";
+import { errorMessage } from "./error-message.js";
+import { resolveAgentDir } from "./home-paths.js";
+import { type ModelResolution, parseTierBinding, setModelTiers } from "./model-tiers.js";
+import { NOTIFICATION_RESULT_CHARS_CEILING } from "./notification-result.js";
 import { type BudgetPolicy, DEFAULT_BUDGET_POLICY } from "./process-budget.js";
 import type { AgentMentionMode, JoinMode, ViewerMarkdownMode, WidgetMode } from "./types.js";
 
@@ -65,6 +68,15 @@ export interface SubagentsSettings {
    */
   defaultMaxTurns?: number;
   graceTurns?: number;
+  /**
+   * Result characters a background completion notice carries per agent,
+   * defaulting to `16000`. Past it the notice keeps the head and tail and
+   * names the transcript and `get_subagent_result`; agents that finish
+   * together share four times this. A result delivered whole counts as read.
+   * `0` restores the 500-character preview (300 per `group` member). See
+   * `notification-result.ts`.
+   */
+  notificationResultChars?: number;
   defaultJoinMode?: JoinMode;
   /**
    * Whether a top-level `Agent` spawn that doesn't say runs detached.
@@ -268,6 +280,10 @@ export interface SubagentsSettings {
   fallbackSubagent?: string;
   /** Trusted-global logical name -> ordered canonical provider/model candidates. */
   modelAliases?: Record<string, string[]>;
+  /** Trusted global/enterprise exact model bindings; never read from a project. */
+  modelTiers?: Record<string, string[]>;
+  /** Missing/unavailable tier policy. Both default to inherit with disclosure. */
+  modelResolution?: ModelResolution;
   /**
    * Trusted-global map of agent `type` (or `"*"` for every type) -> model, in
    * any form `Agent({ model })` accepts. Precedence, highest first: the Agent
@@ -386,6 +402,7 @@ export interface SettingsAppliers {
   setBudgetPolicy: (policy: BudgetPolicy) => void;
   setDefaultMaxTurns: (n: number) => void;
   setGraceTurns: (n: number) => void;
+  setNotificationResultChars: (n: number) => void;
   setDefaultJoinMode: (mode: JoinMode) => void;
   setBackgroundByDefault: (b: boolean) => void;
   setSchedulingEnabled: (b: boolean) => void;
@@ -497,6 +514,13 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.graceTurns = r.graceTurns as number;
   }
+  if (
+    Number.isInteger(r.notificationResultChars) &&
+    (r.notificationResultChars as number) >= 0 &&
+    (r.notificationResultChars as number) <= NOTIFICATION_RESULT_CHARS_CEILING
+  ) {
+    out.notificationResultChars = r.notificationResultChars as number;
+  }
   if (
     Number.isInteger(r.maxSubagentDepth) &&
     (r.maxSubagentDepth as number) >= 0 &&
@@ -576,6 +600,24 @@ function sanitize(raw: unknown): SubagentsSettings {
   } else if (typeof r.fallbackSubagent === "string" && r.fallbackSubagent.trim()) {
     out.fallbackSubagent = r.fallbackSubagent.trim();
   }
+  if (r.modelTiers !== undefined) {
+    out.modelTiers = {};
+    if (r.modelTiers && typeof r.modelTiers === "object" && !Array.isArray(r.modelTiers)) {
+      for (const [tier, members] of Object.entries(r.modelTiers)) {
+        const binding = parseTierBinding(tier, members);
+        if (binding) out.modelTiers[tier] = binding.kind === "routed" ? [binding.profile] : binding.members;
+        else console.warn(`[pi-subagents] Ignoring invalid modelTiers entry "${tier}".`);
+      }
+    } else console.warn("[pi-subagents] Ignoring modelTiers: expected an object of tier -> model list.");
+  }
+  if (r.modelResolution && typeof r.modelResolution === "object" && !Array.isArray(r.modelResolution)) {
+    out.modelResolution = {};
+    for (const key of ["onUnmapped", "onUnavailable"] as const) {
+      const mode = (r.modelResolution as Record<string, unknown>)[key];
+      if (mode === "error" || mode === "inherit") out.modelResolution[key] = mode;
+      else if (mode !== undefined) console.warn(`[pi-subagents] Ignoring invalid modelResolution.${key}.`);
+    }
+  }
   if (r.modelAliases !== undefined) {
     const aliases = sanitizeModelAliases(r.modelAliases);
     if (aliases) out.modelAliases = aliases;
@@ -630,8 +672,8 @@ function sanitizeModelAliases(raw: unknown): Record<string, string[]> | undefine
   return aliases;
 }
 
-function globalPath(): string {
-  return join(getAgentDir(), "subagents.json");
+function globalPath(homeDir?: string): string {
+  return join(resolveAgentDir(homeDir), "subagents.json");
 }
 
 function projectPath(cwd: string): string {
@@ -648,23 +690,28 @@ function readSettingsFile(path: string): SubagentsSettings {
   try {
     return sanitize(JSON.parse(readFileSync(path, "utf-8")));
   } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
+    const reason = errorMessage(err);
     console.warn(`[pi-subagents] Ignoring malformed settings at ${path}: ${reason}`);
     return {};
   }
 }
 
 /** Load merged settings: global provides defaults, project overrides. */
-export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
+export function loadSettings(cwd: string = process.cwd(), homeDir?: string): SubagentsSettings {
   // Aliases pick the provider a subagent runs on, so they are machine
   // configuration: a cloned repo's project file must not redirect them.
   const {
     modelAliases: projectModelAliases,
+    modelTiers: projectModelTiers,
+    modelResolution: projectModelResolution,
     agentModels: projectAgentModels,
     maxActiveSubagents: projectMaxActive,
     nestedSubagentReserve: projectReserve,
     ...project
   } = readSettingsFile(projectPath(cwd));
+  if (projectModelTiers !== undefined || projectModelResolution !== undefined) {
+    console.warn("[pi-subagents] Ignoring modelTiers/modelResolution in project .pi/subagents.json: model policy is read from trusted global configuration only.");
+  }
   if (projectModelAliases !== undefined) {
     console.warn("[pi-subagents] Ignoring modelAliases in project .pi/subagents.json: aliases are read from trusted global configuration only.");
   }
@@ -676,14 +723,14 @@ export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
   if (projectMaxActive !== undefined || projectReserve !== undefined) {
     console.warn("[pi-subagents] Ignoring maxActiveSubagents/nestedSubagentReserve in project .pi/subagents.json: the process-wide budget is read from global configuration only.");
   }
-  return { ...trustedSettings(), ...project };
+  return { ...trustedSettings(homeDir), ...project };
 }
 
 /** Global settings with the enterprise manifest over them: the layer a project file cannot touch. */
-function trustedSettings(): SubagentsSettings {
-  const enterprise = readEnterpriseLocalManifest()?.subagents;
+function trustedSettings(homeDir?: string): SubagentsSettings {
+  const enterprise = readEnterpriseLocalManifest(homeDir)?.subagents;
   const enterpriseSettings = enterprise === undefined ? {} : sanitize(enterprise);
-  return { ...readSettingsFile(globalPath()), ...enterpriseSettings };
+  return { ...readSettingsFile(globalPath(homeDir)), ...enterpriseSettings };
 }
 
 /**
@@ -692,8 +739,8 @@ function trustedSettings(): SubagentsSettings {
  * how deep its own sessions nest, but not what the process-wide reserve
  * covers. A missing key means its default, so removing the cap turns it off.
  */
-export function loadBudgetPolicy(): BudgetPolicy {
-  const trusted = trustedSettings();
+export function loadBudgetPolicy(homeDir?: string): BudgetPolicy {
+  const trusted = trustedSettings(homeDir);
   return {
     maxActive: trusted.maxActiveSubagents ?? DEFAULT_BUDGET_POLICY.maxActive,
     nestedReserve: trusted.nestedSubagentReserve ?? DEFAULT_BUDGET_POLICY.nestedReserve,
@@ -725,9 +772,11 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   }
   if (typeof s.defaultMaxTurns === "number") appliers.setDefaultMaxTurns(s.defaultMaxTurns);
   if (typeof s.graceTurns === "number") appliers.setGraceTurns(s.graceTurns);
+  if (typeof s.notificationResultChars === "number") appliers.setNotificationResultChars(s.notificationResultChars);
   if (typeof s.maxSubagentDepth === "number") appliers.setMaxSubagentDepth(s.maxSubagentDepth);
   if (typeof s.fallbackSubagent === "string") appliers.setFallbackSubagent(s.fallbackSubagent);
   // Module state: reset when a session omits it, or the previous activation's aliases leak.
+  setModelTiers(s.modelTiers, s.modelResolution);
   appliers.setModelAliases(s.modelAliases);
   appliers.setAgentModels(s.agentModels);
   if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode);
@@ -775,10 +824,11 @@ export function applyAndEmitLoaded(
   appliers: SettingsAppliers,
   emit: SettingsEmit,
   cwd: string = process.cwd(),
+  homeDir?: string,
 ): SubagentsSettings {
-  const settings = loadSettings(cwd);
+  const settings = loadSettings(cwd, homeDir);
   applySettings(settings, appliers);
-  appliers.setBudgetPolicy(loadBudgetPolicy());
+  appliers.setBudgetPolicy(loadBudgetPolicy(homeDir));
   emit("subagents:settings_loaded", { settings });
   return settings;
 }