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

package/src/skill-loader.ts

@@ -25,7 +25,7 @@ import type { Dirent } from "node:fs";
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { resolveAgentDir } from "./home-paths.js";
 import { isSymlink, isUnsafeName, safeReadFile } from "./memory.js";
 
 export interface PreloadedSkill {
@@ -33,21 +33,22 @@ export interface PreloadedSkill {
   content: string;
 }
 
-export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
-  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd) }));
+export function preloadSkills(skillNames: string[], cwd: string, homeDir = homedir()): PreloadedSkill[] {
+  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd, homeDir) }));
 }
 
-function loadSkillContent(name: string, cwd: string): string {
+function loadSkillContent(name: string, cwd: string, homeDir: string): string {
   if (isUnsafeName(name)) {
     return `(Skill "${name}" skipped: name contains path traversal characters)`;
   }
   // `trusted`: user-owned root, symlinks followed. Project roots stay strict.
+  const agentDir = resolveAgentDir(homeDir);
   const roots = [
     { path: join(cwd, ".pi", "skills"), trusted: false }, // project — Pi standard
     { path: join(cwd, ".agents", "skills"), trusted: false }, // project — Agent Skills spec
-    { path: join(getAgentDir(), "skills"), trusted: true }, // user — Pi standard
-    { path: join(homedir(), ".agents", "skills"), trusted: true }, // user — Agent Skills spec
-    { path: join(homedir(), ".pi", "skills"), trusted: true }, // legacy global, pre-Pi
+    { path: join(agentDir, "skills"), trusted: true }, // user — Pi standard
+    { path: join(homeDir, ".agents", "skills"), trusted: true }, // user — Agent Skills spec
+    { path: join(homeDir, ".pi", "skills"), trusted: true }, // legacy global, pre-Pi
   ];
   for (const root of roots) {
     const content = findInRoot(root.path, name, root.trusted);

package/src/stale-ctx.ts

@@ -0,0 +1,16 @@
+/**
+ * stale-ctx.ts -- recognising pi's "extension ctx is stale" failure.
+ *
+ * pi invalidates an extension runner on reload and on session replacement
+ * (/new, /fork, /resume). Anything that still reaches the old runner or its
+ * `pi` throws this message (#145).
+ */
+
+/** Matched on the stable prefix of core's message. */
+export const STALE_CTX_RE = /extension ctx is stale after session replacement or reload/i;
+
+/** Whether `error` (an `Error` or a message string) is the stale-ctx failure. */
+export function isStaleCtxError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+  return STALE_CTX_RE.test(message);
+}

package/src/types.ts

@@ -4,6 +4,9 @@
 
 import type { ThinkingLevel } from "@earendil-works/pi-ai";
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { ModelFallback } from "./model-resolver.js";
+import type { ModelSelection } from "./model-selection.js";
+import type { TierDisclosure } from "./model-tiers.js";
 import type { BudgetLease } from "./process-budget.js";
 import type { LifetimeUsage } from "./usage.js";
 
@@ -147,6 +150,9 @@ export interface AgentTombstone {
   description: string;
   /** Always set — a record with no session file is never tombstoned. */
   sessionFile: string;
+  /** The evicted run's tier and fallback, handed back when `@handle` reopens it. */
+  modelTier?: TierDisclosure;
+  modelFallback?: ModelFallback;
   completedAt: number;
 }
 
@@ -270,6 +276,24 @@ export interface AgentRecord {
   isBackground?: boolean;
   /** Resolved spawn params, captured for UI display. Fixed at spawn time. */
   invocation?: AgentInvocation;
+  /**
+   * Set when a configured model did not resolve and the agent runs on the parent
+   * model. The single source for every disclosure surface; a resume reuses it
+   * as is, never recomputes it from the resuming call's config.
+   */
+  modelFallback?: ModelFallback;
+  /**
+   * This record's selection, retained across live resumes and physical relabelling.
+   * An evicted-session reopen selects anew; current fallback disclosure always
+   * comes from that selection.
+   */
+  modelSelection?: ModelSelection;
+  /** Actual run's tier provenance, preserved through eviction and replay. */
+  modelTier?: TierDisclosure;
+  /** Prior evicted run's outcome, never the continuation's selection or disclosure. */
+  previousModelTier?: TierDisclosure;
+  /** Prior evicted run's fallback, retained separately from the continuation's current disclosure. */
+  previousModelFallback?: ModelFallback;
   /** Nesting depth: top-level subagent = 1. */
   depth?: number;
   /**
@@ -350,6 +374,9 @@ export interface NotificationDetails {
   durationMs: number;
   outputFile?: string;
   error?: string;
+  /** The `Note:` line when the agent ran on the parent model because its configured one did not resolve. */
+  modelNote?: string;
+  modelTier?: TierDisclosure;
   resultPreview: string;
   /** Additional agents in a group notification. */
   others?: NotificationDetails[];

package/src/ui/agent-row.ts

@@ -14,6 +14,7 @@ import { pathToFileURL } from "node:url";
 import { type Component, hyperlink, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { type Clock, realClock, type TimerHandle } from "../clock.js";
 import { formatClock } from "../model-call.js";
+import { modelSelectionNote } from "../model-selection.js";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeCost, getLifetimeTotal } from "../usage.js";
 import {
@@ -26,6 +27,7 @@ import {
   SPINNER,
   type Theme,
 } from "./agent-widget.js";
+import { fallbackFlag, withLeadingFlag } from "./fallback-flag.js";
 
 /** Lines of the result shown when expanded; the rest is one `get_subagent_result` away. */
 const EXPANDED_RESULT_LINES = 50;
@@ -89,6 +91,7 @@ export function agentRowSummary(
   live: AgentRowLive,
   theme: Theme,
   now: number = Date.now(),
+  width?: number,
 ): string {
   const record = details.agentId ? live.getRecord(details.agentId) : undefined;
   const activity = details.agentId ? live.getActivity(details.agentId) : undefined;
@@ -106,7 +109,10 @@ export function agentRowSummary(
   if (tokenText) parts.push(tokenText);
   if (cost) parts.push(cost);
   if (!finished && details.backgroundHint && elapsed >= 2000) parts.push("(ctrl+b to run in background)");
-  return `${icon} ${parts.map(p => fgPreservingNestedStyles(theme, "dim", p)).join(` ${theme.fg("dim", "·")} `)}`;
+  // Leading, ahead of the status text, which may carry a 300-char error.
+  const flag = fallbackFlag(theme, record?.modelFallback || record?.modelTier ? record : details);
+  const body = parts.map(p => fgPreservingNestedStyles(theme, "dim", p)).join(` ${theme.fg("dim", "·")} `);
+  return width === undefined ? `${icon} ${flag ? `${flag} ` : ""}${body}` : withLeadingFlag(`${icon} `, flag, body, width);
 }
 
 /**
@@ -116,7 +122,9 @@ export function agentRowSummary(
  */
 function tagsLine(details: AgentDetails, theme: Theme): string | undefined {
   const parts = [...(details.modelName ? [details.modelName] : []), ...(details.tags ?? [])];
-  return parts.length > 0 ? theme.fg("dim", `↳ ${parts.join(" · ")}`) : undefined;
+  const flag = fallbackFlag(theme, details);
+  if (parts.length === 0 && !flag) return undefined;
+  return `${theme.fg("dim", "↳")} ${flag ? `${flag} ` : ""}${theme.fg("dim", parts.join(" · "))}`;
 }
 
 /** The transcript as an OSC 8 hyperlink, so a click opens it. */
@@ -189,12 +197,14 @@ export class AgentResultView implements Component {
   ) {}
 
   render(width: number): string[] {
-    const lines = [truncateToWidth(agentRowSummary(this.details, this.live, this.theme, this.clock.now()), width)];
+    const lines = [agentRowSummary(this.details, this.live, this.theme, this.clock.now(), width)];
     if (!this.expanded) return lines;
 
     const record = this.details.agentId ? this.live.getRecord(this.details.agentId) : undefined;
     const tags = tagsLine(this.details, this.theme);
     if (tags) lines.push(truncateToWidth(tags, width));
+    const note = modelSelectionNote(record) || this.details.modelNote;
+    if (note) lines.push(...wrapTextWithAnsi(this.theme.fg("warning", note), width));
     const transcript = record?.outputFile ?? this.details.outputFile;
     if (transcript) lines.push(truncateToWidth(transcriptLink(transcript, this.theme), width));
 

package/src/ui/agent-widget.ts

@@ -11,8 +11,11 @@ import { type AgentManager, isTopLevelAgent } from "../agent-manager.js";
 import { getConfig } from "../agent-types.js";
 import { type Clock, realClock, type TimerHandle } from "../clock.js";
 import { describeModelCall, type ModelCallState } from "../model-call.js";
+import type { ModelFallback } from "../model-resolver.js";
+import type { TierDisclosure } from "../model-tiers.js";
 import type { AgentInvocation, SubagentType, WidgetMode } from "../types.js";
 import { getLifetimeCost, getLifetimeTotal, getSessionContextPercent, type LifetimeUsage, type SessionLike } from "../usage.js";
+import { fallbackFlag } from "./fallback-flag.js";
 
 // ---- Constants ----
 
@@ -83,6 +86,11 @@ export interface AgentDetails {
   backgroundHint?: boolean;
   /** Short label for the model the run used, e.g. "haiku 4.5". */
   modelName?: string;
+  /** Set when a configured model did not resolve and the run fell back to the parent model. */
+  modelNote?: string;
+  /** The structured form of {@link modelNote}, for the one-line label. */
+  modelFallback?: ModelFallback;
+  modelTier?: TierDisclosure;
   /** Notable config tags (e.g. ["thinking: high", "isolated"]). */
   tags?: string[];
   /** Current turn count. */
@@ -389,7 +397,7 @@ export class AgentWidget {
   }
 
   /** Render a finished agent line. */
-  private renderFinishedLine(a: { id: string; type: SubagentType; status: string; description: string; toolUses: number; startedAt: number; completedAt?: number; error?: string; lifetimeUsage?: LifetimeUsage }, theme: Theme): string {
+  private renderFinishedLine(a: { id: string; type: SubagentType; status: string; description: string; toolUses: number; startedAt: number; completedAt?: number; error?: string; lifetimeUsage?: LifetimeUsage; modelFallback?: ModelFallback; modelTier?: TierDisclosure }, theme: Theme): string {
     const modeLabel = getPromptModeLabel(a.type);
     const duration = formatMs((a.completedAt ?? this.clock.now()) - a.startedAt);
 
@@ -418,6 +426,7 @@ export class AgentWidget {
     const activity = this.agentActivity.get(a.id);
     if (activity) parts.push(formatTurns(activity.turnCount, activity.maxTurns));
     if (a.toolUses > 0) parts.push(`${a.toolUses} tool use${a.toolUses === 1 ? "" : "s"}`);
+    // Not gated by `showModel`: a substituted model is never a cosmetic detail.
     // From the record, not the activity tracker: that entry is deleted the
     // moment an agent finishes, and "what did it cost" is a question asked
     // about finished agents.
@@ -426,7 +435,8 @@ export class AgentWidget {
     parts.push(duration);
 
     const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
-    return `${icon} ${renderAgentName(a.type, theme, { fallbackColor: "dim" })}${modeTag}  ${theme.fg("dim", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
+    const flag = fallbackFlag(theme, a) ? `${fallbackFlag(theme, a)} ` : "";
+    return `${icon} ${flag}${renderAgentName(a.type, theme, { fallbackColor: "dim" })}${modeTag}  ${theme.fg("dim", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
   }
 
   /**
@@ -466,6 +476,7 @@ export class AgentWidget {
     for (const a of running) {
       const modeLabel = getPromptModeLabel(a.type);
       const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
+    const flag = fallbackFlag(theme, a) ? `${fallbackFlag(theme, a)} ` : "";
       const elapsed = formatMs(this.clock.now() - a.startedAt);
 
       const bg = this.agentActivity.get(a.id);
@@ -489,7 +500,7 @@ export class AgentWidget {
         const thinkingTag = tags.find(tag => tag.startsWith("thinking: "));
         if (thinkingTag) parts.push(thinkingTag);
       }
-      if (bg) parts.push(formatTurns(bg.turnCount, bg.maxTurns));
+        if (bg) parts.push(formatTurns(bg.turnCount, bg.maxTurns));
       if (toolUses > 0) parts.push(`${toolUses} tool use${toolUses === 1 ? "" : "s"}`);
       if (tokenText) parts.push(tokenText);
       if (costText) parts.push(costText);
@@ -499,7 +510,7 @@ export class AgentWidget {
       const activity = bg ? describeActivity(bg.activeTools, bg.responseText, bg.modelCall, this.clock.now()) : "thinking…";
 
       runningLines.push([
-        truncate(theme.fg("dim", "├─") + ` ${theme.fg("accent", frame)} ${renderAgentName(a.type, theme, { bold: true })}${modeTag}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${fgPreservingNestedStyles(theme, "dim", statsText)}`),
+        truncate(theme.fg("dim", "├─") + ` ${theme.fg("accent", frame)} ${flag}${renderAgentName(a.type, theme, { bold: true })}${modeTag}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${fgPreservingNestedStyles(theme, "dim", statsText)}`),
         truncate(theme.fg("dim", "│  ") + theme.fg("dim", `  ⎿  ${activity}`)),
       ]);
     }

package/src/ui/conversation-viewer.ts

@@ -14,6 +14,7 @@ import type { AgentRecord, ViewerMarkdownMode } from "../types.js";
 import { getLifetimeCost, getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import type { Theme } from "./agent-widget.js";
 import { type AgentActivity, buildInvocationTags, describeActivity, fgPreservingNestedStyles, formatCost, formatDuration, formatSessionTokens, getPromptModeLabel } from "./agent-widget.js";
+import { fallbackFlag } from "./fallback-flag.js";
 import { createViewerKeys, type ViewerKeybindings, type ViewerKeys } from "./viewer-keys.js";
 
 /** Base lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
@@ -727,9 +728,11 @@ export class ConversationViewer implements Component, Focusable {
     // models whose short names read alike.
     const { modelName, modelId, tags } = buildInvocationTags(this.record.invocation);
     const model = modelId ?? modelName;
-    const parts = model ? [model, ...tags] : tags;
-    if (parts.length === 0) return undefined;
-    return this.theme.fg("dim", `  ↳ ${parts.join(" · ")}`);
+    const flag = fallbackFlag(this.theme, this.record);
+    const parts = [...(model ? [model] : []), ...tags];
+    if (parts.length === 0 && !flag) return undefined;
+    // The flag leads the (possibly very long) canonical model id.
+    return `${this.theme.fg("dim", "  ↳")} ${flag ? `${flag} ` : ""}${this.theme.fg("dim", parts.join(" · "))}`;
   }
 
   private buildContentLines(width: number): string[] {

package/src/ui/fallback-flag.ts

@@ -0,0 +1,90 @@
+/**
+ * fallback-flag.ts -- the ONE compact indicator for "this agent ran on another
+ * model than configured", shared by every renderer that shows model info.
+ *
+ * Rows are `label + stats` clamped from the right, so anything appended after
+ * unbounded text (a description, an error, a canonical model id) is the first
+ * thing a narrow terminal cuts. The flag is therefore always rendered FIRST and
+ * the rest is truncated around it. Renderers must use these helpers rather than
+ * building their own marker; `test/fallback-flag-renderers.test.ts` walks every
+ * renderer and fails the ones that do not.
+ */
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { TierDisclosure } from "../model-tiers.js";
+
+/** Minimal theme surface, so this module has no dependency on the widgets that use it. */
+interface FlagTheme {
+  fg(color: string, text: string): string;
+}
+
+/** Anything that can carry the fallback: a record, details or notice details. */
+export interface FallbackCarrier {
+  modelFallback?: unknown;
+  modelNote?: string;
+  modelTier?: TierDisclosure;
+}
+
+/** Whether this tier's answer differs from the member/profile admitted for it. */
+function switchedWithinTier(tier: TierDisclosure): boolean {
+  if (tier.kind !== "routed" && tier.kind !== "static") return false;
+  const baseline = tier.kind === "routed" ? tier.admitted : tier.member;
+  return baseline !== undefined && tier.answered !== undefined && tier.answered !== baseline;
+}
+
+/** Whether `carrier` needs an actionable fallback warning, not merely tier identity. */
+export const hasFallback = (carrier: FallbackCarrier | undefined): boolean => {
+  if (carrier?.modelFallback !== undefined) return true;
+  const tier = carrier?.modelTier;
+  if (!tier) return carrier?.modelNote !== undefined;
+  return tier.kind === "unmapped" || tier.kind === "unavailable" || switchedWithinTier(tier);
+};
+
+/** Plain tier identity/outcome flag, or `[fallback]`; group counts retain the same identity. */
+export function fallbackFlagText(count = 1, carrier?: FallbackCarrier): string {
+  const tier = carrier?.modelTier;
+  const suffix = count > 1 ? ` x${count}` : "";
+  return tier ? `[@${tier.tier}${tier.kind !== "routed" && tier.kind !== "static" ? ` ${tier.kind}` : ""}${suffix}]`
+    : `[fallback${suffix}]`;
+}
+
+/** The themed tier identity or actionable fallback flag for `carrier`. */
+export function fallbackFlag(theme: FlagTheme, carrier: FallbackCarrier | undefined, count = 1): string {
+  if (carrier?.modelTier) return theme.fg(hasFallback(carrier) ? "warning" : "dim", fallbackFlagText(count, carrier));
+  return hasFallback(carrier) ? theme.fg("warning", fallbackFlagText(count, carrier)) : "";
+}
+
+/** What a flag degrades to when even it does not fit; plain so it cannot depend on a theme. */
+const MINIMAL_FLAGS = ["[fb]", "!"] as const;
+
+/**
+ * `prefix + flag + rest`, never wider than `width`, and the flag is never cut.
+ *
+ * Normal case: the prefix and the flag are reserved first and `rest` (a string,
+ * or a function of the width left for it) is truncated to what remains.
+ *
+ * Narrow case, when `prefix + flag + " "` exceeds `width`: the prefix and then
+ * the rest are dropped before the flag is. If the flag alone still does not
+ * fit, it degrades to a plain `[fb]`, then `!`. Only a zero width renders
+ * nothing.
+ */
+export function withLeadingFlag(
+  prefix: string,
+  flag: string,
+  rest: string | ((inner: number) => string),
+  width: number,
+): string {
+  const lead = flag ? `${prefix}${flag} ` : prefix;
+  if (!flag || visibleWidth(lead) <= width) {
+    const inner = Math.max(0, width - visibleWidth(lead));
+    const body = typeof rest === "function" ? rest(inner) : truncateToWidth(rest, inner);
+    return truncateToWidth(lead + body, width);
+  }
+  const flagWidth = visibleWidth(flag);
+  if (flagWidth <= width) {
+    const inner = width - flagWidth - 1;
+    if (inner < 1) return flag;
+    const body = typeof rest === "function" ? rest(inner) : truncateToWidth(rest, inner);
+    return truncateToWidth(`${flag} ${body}`, width);
+  }
+  return MINIMAL_FLAGS.find(m => visibleWidth(m) <= width) ?? "";
+}