@cad0p/pi-subagents-tintinweb 0.14.2 → 0.22.0

package/src/settings.ts

@@ -5,7 +5,44 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import type { JoinMode, ResultPreviewMode, WidgetMode } from "./types.js";
+import { IMPLICIT_FALLBACK, NO_FALLBACK } from "./agent-types.js";
+import type { WidgetMode } from "./types.js";
+
+/**
+ * What the `fallbackSubagent` row shows and offers.
+ *
+ * The current value is always included in `values`. pi-tui's cycle handler
+ * computes `values.indexOf(currentValue)` and writes `values[0]` when that is
+ * -1, so a row whose current value is absent from its own list turns a single
+ * Enter into a silent rewrite to whatever happens to sort first — a custom
+ * agent, once the defaults are disabled. Including it makes Enter mean "cycle
+ * from what is shown", which is what every other row means.
+ *
+ * `unresolvable` reports an explicitly configured fallback that no longer names
+ * an enabled agent — deleted, disabled, or a default with `disableDefaultAgents`
+ * on. Dispatch refuses in that state, so the row must say so rather than
+ * presenting it as a working target. `general-purpose` is the exception in both
+ * directions: it resolves to the permissive hardcoded tier whether it is
+ * configured or unset, and dispatch accepts it either way, so an unset fallback
+ * is never unresolvable and neither is an explicit `general-purpose`.
+ */
+export function fallbackRow(
+  configured: string | undefined,
+  available: readonly string[],
+  noneValue: string,
+  resolvable: (name: string) => boolean,
+): { value: string; values: string[]; unresolvable: boolean } {
+  const value = configured ?? IMPLICIT_FALLBACK;
+  // `resolvable` is `isFallbackResolvable`, i.e. the resolver's own policy. The
+  // uniqueness rule needs the full registry (a disabled agent still claims its
+  // name), which `available` alone cannot express — so the caller supplies the
+  // verdict rather than this function re-deriving a half-truth.
+  // Only a *configured* value can be unresolvable: an unset fallback deliberately
+  // targets the permissive hardcoded tier even when that agent is unregistered or
+  // disabled, so calling it broken would report a refusal dispatch never performs.
+  const unresolvable = configured !== undefined && value.trim().toLowerCase() !== noneValue && !resolvable(value);
+  return { value, values: [...new Set([value, ...available, noneValue])], unresolvable };
+}
 
 export interface SubagentsSettings {
   maxConcurrent?: number;
@@ -16,7 +53,6 @@ export interface SubagentsSettings {
    */
   defaultMaxTurns?: number;
   graceTurns?: number;
-  defaultJoinMode?: JoinMode;
   /**
    * Master switch for the schedule subagent feature. Defaults to `true`.
    * When `false`: the `Agent` tool's `schedule` param + its guideline are
@@ -44,12 +80,20 @@ export interface SubagentsSettings {
    * against. Defaults to false: subagents may use any model.
    */
   scopeModels?: boolean;
-  /** Result preview rendering mode. Defaults to "markdown". */
-  resultPreviewMode?: ResultPreviewMode;
-  /** Always show expanded result preview, ignoring pi's expanded flag. Defaults to true. */
-  resultPreviewExpanded?: boolean;
   /** Max chars for failure preview before truncation. Defaults to 65536 (64 KiB). */
   failurePreviewMaxChars?: number;
+  /**
+   * When true, an unreadable or unparseable agent `.md` aborts extension load
+   * instead of being skipped with a warning — pi exits, naming the file.
+   *
+   * Startup only, by design. Mid-session reloads (one per `Agent` call) keep
+   * warning: a bad edit at 3pm should not kill the session on the next
+   * unrelated spawn, where the failure would look disconnected from its cause.
+   * For a checked-in `.pi/agents/`, failing at startup is the point — the
+   * alternative is running a *different* agent than the file names.
+   * Defaults to false.
+   */
+  strictAgentFiles?: boolean;
   /**
    * When true, the three built-in default agents (general-purpose, Explore, Plan)
    * are not registered at startup. User-defined agents from project/global custom
@@ -76,13 +120,9 @@ export interface SubagentsSettings {
   fleetView?: boolean;
   /**
    * Display mode for the persistent above-editor agent widget:
-   *   - `all`: show every agent (foreground + background).
-   *   - `background`: hide foreground agents — they already render inline as the
-   *     Agent tool result, so the widget would otherwise double-render them
-   *     (#118); everything else (background, queued, scheduled, RPC) stays.
+   *   - `all`: show every agent.
    *   - `off`: hide the widget entirely.
-   * Defaults to `background`. Pure-UI and applied live (toggling refreshes the
-   * widget).
+   * Defaults to `all`. Pure-UI and applied live (toggling refreshes the widget).
    */
   widgetMode?: WidgetMode;
   /**
@@ -92,10 +132,106 @@ export interface SubagentsSettings {
    * project (e.g. a repo that shouldn't leave run transcripts on disk for backup
    * or DLP tooling to ingest). A custom agent's `output_transcript` frontmatter
    * overrides this per agent. This governs only the transcript — it does NOT
-   * affect the persisted pi session (`persist_session`), worktree commits
-   * (`isolation: worktree`), or memory files.
+   * affect whether the run's pi session file is retained (`persist_session`),
+   * worktree commits (`isolation: worktree`), or memory files.
    */
   outputTranscript?: boolean;
+  /**
+   * Hard ceiling on nested subagent delegation, counted from the main session:
+   * main = 0, its subagents = 1, their children = 2. Defaults to `2`; `0` or `1`
+   * disables nesting project-wide. Read when a subagent session is built, so a
+   * change applies to agents started after it. A per-agent `max_subagent_depth`
+   * can only tighten this, never raise it.
+   */
+  maxSubagentDepth?: number;
+  /**
+   * Whether `isolation: "worktree"` may create a worktree at all. Defaults to
+   * `true`. Set `false` on a repo where worktrees are too slow or too large to
+   * be worth it: a requested worktree is then dropped and the agent runs in the
+   * main checkout.
+   *
+   * The drop is deliberately silent — there is no per-result note, because the
+   * setting exists for projects whose model asks for a worktree on every call,
+   * where a note would be noise on every result. What keeps the orchestrator
+   * from claiming a `pi-agent-*` branch anyway is that it is never told the
+   * capability exists: `isolationParam` (invocation-config.ts) drops the field
+   * from the tool schema, and `isolationGuideline` (index.ts) drops the
+   * matching prose from the full and compact descriptions — a custom one opts
+   * in via the `{{isolationGuideline}}` placeholder. Anything that
+   * reintroduces the prose has to reintroduce a note with it.
+   *
+   * Deliberately a downgrade rather than an error. The fail-loud rule covers
+   * worktrees that *cannot* be created; this is the user declining one, and
+   * throwing would reject exactly the calls that the `isolation: "off"` value
+   * exists to tolerate. Enforced below the tool boundary, so it also covers the
+   * scheduler and the unvalidated cross-extension RPC path.
+   */
+  worktreeIsolation?: boolean;
+  /**
+   * Agent type substituted when a caller-supplied `subagent_type` doesn't
+   * resolve to exactly one enabled agent (unknown, disabled, or ambiguous by
+   * case). Omitted keeps the historical `general-purpose` fallback; a type name
+   * routes those calls to that agent instead; `"none"` disables the fallback so
+   * dispatch fails closed with an error naming the available types.
+   *
+   * The boolean `false` is accepted as a spelling of `"none"`, because a boolean
+   * would otherwise be dropped as the wrong type and silently leave the
+   * PERMISSIVE default in place while the author believes strict dispatch is on
+   * — the wrong direction to fail for this setting. Every other value is an
+   * agent name, so a mistaken `"off"` fails loudly at dispatch rather than
+   * meaning one thing here and another in the resolver.
+   */
+  fallbackSubagent?: string;
+  /**
+   * Whether this extension's tool results carry a `usage` field, so subagent
+   * spend reaches the parent session's own accounting. Defaults to `true`.
+   *
+   * Subagents run in their own pi sessions, so without this the parent's footer,
+   * statusline and `/cost` show only what the main model spent — a session that
+   * delegated most of its work reads as nearly free. Pi folds
+   * `toolResult.usage` into `getSessionStats()`, so attaching it makes those
+   * surfaces count subagents too, under `/cost`'s "Tools/summaries" bucket.
+   *
+   * On by default because the alternative is a total that is quietly wrong about
+   * what the session cost; upstream defaults it off, this fork does not. The
+   * honest caveat stands: turning it on makes numbers move that a statusline may
+   * already have been tracking, which is why it remains a setting.
+   *
+   * Three properties of what gets reported:
+   *   - `cacheRead` IS included, because pi counts the parent's own messages
+   *     that way and the prefix really is re-billed on every call. The display
+   *     total (`getLifetimeTotal`) keeps excluding it — see `usage.ts`.
+   *   - Cost is pi's own per-message `usage.cost.total`; we price nothing, and
+   *     a model pi has no rates for contributes 0.
+   *   - The context-window percentage is untouched. Pi derives it from assistant
+   *     messages alone (`getContextUsage`), so a delegating session's context
+   *     does not appear to fill up faster.
+   */
+  reportUsage?: boolean;
+  /**
+   * Whether the subagent surfaces show an estimated dollar cost next to their
+   * token counts (widget, FleetView, conversation viewer, `get_subagent_result`,
+   * completion notifications). Defaults to `true`. Applied live.
+   *
+   * Rendered as `~$0.0042` — the tilde marks it as pi's reported estimate rather
+   * than a billed figure, and it is omitted entirely when the model has no
+   * pricing data, so a local model shows tokens and no dollars.
+   *
+   * Independent of `reportUsage`: this one is what a human reads, that one is
+   * what the parent session counts.
+   */
+  showCost?: boolean;
+  /**
+   * Whether the widget's running rows name the model driving each agent and the
+   * thinking level it is running at. Defaults to `false`.
+   *
+   * Off by default because the widget row already carries the description,
+   * turns, tool uses, tokens and elapsed time, and every character it gains is
+   * one the description loses on a narrow terminal. The conversation viewer and
+   * the `get_subagent_result` header show the pair either way — they have a line
+   * to themselves.
+   */
+  showModel?: boolean;
 }
 
 export type ToolDescriptionMode = "full" | "compact" | "custom";
@@ -105,26 +241,28 @@ export interface SettingsAppliers {
   setMaxConcurrent: (n: number) => void;
   setDefaultMaxTurns: (n: number) => void;
   setGraceTurns: (n: number) => void;
-  setDefaultJoinMode: (mode: JoinMode) => void;
   setSchedulingEnabled: (b: boolean) => void;
   setScopeModels: (enabled: boolean) => void;
-  setResultPreviewMode: (mode: ResultPreviewMode) => void;
-  setResultPreviewExpanded: (expanded: boolean) => void;
+  setStrictAgentFiles: (b: boolean) => void;
   setFailurePreviewMaxChars: (chars: number) => void;
   setDisableDefaultAgents: (b: boolean) => void;
   setToolDescriptionMode: (mode: ToolDescriptionMode) => void;
   setFleetView: (b: boolean) => void;
   setWidgetMode: (mode: WidgetMode) => void;
   setOutputTranscript: (b: boolean) => void;
+  setMaxSubagentDepth: (n: number) => void;
+  setWorktreeIsolation: (b: boolean) => void;
+  setFallbackSubagent: (v: string | undefined) => void;
+  setReportUsage: (b: boolean) => void;
+  setShowCost: (b: boolean) => void;
+  setShowModel: (b: boolean) => void;
 }
 
 /** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
 export type SettingsEmit = (event: string, payload: unknown) => void;
 
-const VALID_JOIN_MODES: ReadonlySet<string> = new Set<JoinMode>(["async", "group", "smart"]);
-const VALID_RESULT_PREVIEW_MODES: ReadonlySet<string> = new Set<ResultPreviewMode>(["plain", "markdown"]);
 const VALID_TOOL_DESCRIPTION_MODES: ReadonlySet<string> = new Set<ToolDescriptionMode>(["full", "compact", "custom"]);
-const VALID_WIDGET_MODES: ReadonlySet<string> = new Set<WidgetMode>(["all", "background", "off"]);
+const VALID_WIDGET_MODES: ReadonlySet<string> = new Set<WidgetMode>(["all", "off"]);
 
 
 // Sanity ceilings — prevent hand-edited configs from asking for values that
@@ -133,7 +271,16 @@ const VALID_WIDGET_MODES: ReadonlySet<string> = new Set<WidgetMode>(["all", "bac
 const MAX_CONCURRENT_CEILING = 1024;
 const MAX_TURNS_CEILING = 10_000;
 const GRACE_TURNS_CEILING = 1_000;
-export const RESULT_PREVIEW_MAX_CHARS_CEILING = 1_048_576;
+const SUBAGENT_DEPTH_CEILING = 16;
+export const FAILURE_PREVIEW_MAX_CHARS_CEILING = 1_048_576;
+
+/**
+ * Shipped default for `showCost`. Named because the report renderer keeps its
+ * own copy of the flag (see `result-report.ts`): a file that omits the key
+ * applies nothing, so both copies must start from the same value or the widget
+ * and the result report disagree about showing a cost.
+ */
+export const DEFAULT_SHOW_COST = true;
 
 /** Drop fields that don't match the expected shape. Silent — garbage becomes absent. */
 function sanitize(raw: unknown): SubagentsSettings {
@@ -161,8 +308,12 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.graceTurns = r.graceTurns as number;
   }
-  if (typeof r.defaultJoinMode === "string" && VALID_JOIN_MODES.has(r.defaultJoinMode)) {
-    out.defaultJoinMode = r.defaultJoinMode as JoinMode;
+  if (
+    Number.isInteger(r.maxSubagentDepth) &&
+    (r.maxSubagentDepth as number) >= 0 &&
+    (r.maxSubagentDepth as number) <= SUBAGENT_DEPTH_CEILING
+  ) {
+    out.maxSubagentDepth = r.maxSubagentDepth as number;
   }
   if (typeof r.schedulingEnabled === "boolean") {
     out.schedulingEnabled = r.schedulingEnabled;
@@ -170,16 +321,13 @@ function sanitize(raw: unknown): SubagentsSettings {
   if (typeof r.scopeModels === "boolean") {
     out.scopeModels = r.scopeModels;
   }
-  if (typeof r.resultPreviewMode === "string" && VALID_RESULT_PREVIEW_MODES.has(r.resultPreviewMode)) {
-    out.resultPreviewMode = r.resultPreviewMode as ResultPreviewMode;
-  }
-  if (typeof r.resultPreviewExpanded === "boolean") {
-    out.resultPreviewExpanded = r.resultPreviewExpanded;
+  if (typeof r.strictAgentFiles === "boolean") {
+    out.strictAgentFiles = r.strictAgentFiles;
   }
   if (
     Number.isInteger(r.failurePreviewMaxChars) &&
     (r.failurePreviewMaxChars as number) >= 1 &&
-    (r.failurePreviewMaxChars as number) <= RESULT_PREVIEW_MAX_CHARS_CEILING
+    (r.failurePreviewMaxChars as number) <= FAILURE_PREVIEW_MAX_CHARS_CEILING
   ) {
     out.failurePreviewMaxChars = r.failurePreviewMaxChars as number;
   }
@@ -198,6 +346,28 @@ function sanitize(raw: unknown): SubagentsSettings {
   if (typeof r.outputTranscript === "boolean") {
     out.outputTranscript = r.outputTranscript;
   }
+  if (typeof r.worktreeIsolation === "boolean") {
+    out.worktreeIsolation = r.worktreeIsolation;
+  }
+  if (typeof r.reportUsage === "boolean") {
+    out.reportUsage = r.reportUsage;
+  }
+  if (typeof r.showCost === "boolean") {
+    out.showCost = r.showCost;
+  }
+  if (typeof r.showModel === "boolean") {
+    out.showModel = r.showModel;
+  }
+  if (r.fallbackSubagent === false) {
+    // The only non-string spelling worth accepting: a boolean would otherwise be
+    // dropped, silently leaving the PERMISSIVE default in place. Every string is
+    // an agent name except the `none` sentinel, which the resolver recognizes —
+    // so a mistaken "off" fails loudly at dispatch instead of meaning something
+    // different here than it does there.
+    out.fallbackSubagent = NO_FALLBACK;
+  } else if (typeof r.fallbackSubagent === "string" && r.fallbackSubagent.trim()) {
+    out.fallbackSubagent = r.fallbackSubagent.trim();
+  }
   return out;
 }
 
@@ -251,17 +421,21 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   if (typeof s.maxConcurrent === "number") appliers.setMaxConcurrent(s.maxConcurrent);
   if (typeof s.defaultMaxTurns === "number") appliers.setDefaultMaxTurns(s.defaultMaxTurns);
   if (typeof s.graceTurns === "number") appliers.setGraceTurns(s.graceTurns);
-  if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode);
+  if (typeof s.maxSubagentDepth === "number") appliers.setMaxSubagentDepth(s.maxSubagentDepth);
   if (typeof s.schedulingEnabled === "boolean") appliers.setSchedulingEnabled(s.schedulingEnabled);
   if (typeof s.scopeModels === "boolean") appliers.setScopeModels(s.scopeModels);
-  if (s.resultPreviewMode) appliers.setResultPreviewMode(s.resultPreviewMode);
-  if (typeof s.resultPreviewExpanded === "boolean") appliers.setResultPreviewExpanded(s.resultPreviewExpanded);
+  if (typeof s.strictAgentFiles === "boolean") appliers.setStrictAgentFiles(s.strictAgentFiles);
   if (typeof s.failurePreviewMaxChars === "number") appliers.setFailurePreviewMaxChars(s.failurePreviewMaxChars);
   if (typeof s.disableDefaultAgents === "boolean") appliers.setDisableDefaultAgents(s.disableDefaultAgents);
   if (s.toolDescriptionMode) appliers.setToolDescriptionMode(s.toolDescriptionMode);
   if (typeof s.fleetView === "boolean") appliers.setFleetView(s.fleetView);
   if (s.widgetMode) appliers.setWidgetMode(s.widgetMode);
   if (typeof s.outputTranscript === "boolean") appliers.setOutputTranscript(s.outputTranscript);
+  if (typeof s.worktreeIsolation === "boolean") appliers.setWorktreeIsolation(s.worktreeIsolation);
+  if (typeof s.fallbackSubagent === "string") appliers.setFallbackSubagent(s.fallbackSubagent);
+  if (typeof s.reportUsage === "boolean") appliers.setReportUsage(s.reportUsage);
+  if (typeof s.showCost === "boolean") appliers.setShowCost(s.showCost);
+  if (typeof s.showModel === "boolean") appliers.setShowModel(s.showModel);
 }
 
 /**

package/src/status-note.ts

@@ -1,7 +1,14 @@
 /**
- * status-note.ts — Parenthetical status note appended to agent result text.
+ * status-note.ts — Honest framing for an agent result: the parenthetical status
+ * note for a non-normal outcome, and the salvaged partial output of a failure.
+ *
+ * Lives here rather than in an index.ts closure because both entry points need
+ * it — the top-level tools and the nested delegation tools, which cannot import
+ * the extension entry point.
  */
 
+import type { AgentRecord } from "./types.js";
+
 /**
  * Explicit parenthetical note for a non-normal terminal outcome, so the parent
  * agent can't mistake partial output for a completed result. Empty string for a
@@ -23,3 +30,13 @@ export function getStatusNote(status: string): string {
       return "";
   }
 }
+
+/**
+ * Salvaged partial output of a failed run, as a labeled suffix for the error
+ * surfaces (or "" if the run produced nothing). `record.result` is bounded to
+ * the run's own turns, so this is never a stale earlier answer (#144).
+ */
+export function partialOutputSuffix(record: AgentRecord): string {
+  const partial = record.result?.trim();
+  return partial ? `\n\nPartial output before the failure:\n${partial}` : "";
+}

package/src/text-safety.ts

@@ -0,0 +1,69 @@
+/**
+ * text-safety.ts — shared sanitizer for untrusted text that reaches the
+ * terminal or the model context (child output, tool arguments, settings).
+ */
+
+/**
+ * Strip terminal control sequences and invisible/forging characters, keeping
+ * tab, LF, and printable non-ASCII. Complete OSC and CSI sequences are consumed
+ * whole, including the 8-bit C1 form of CSI (U+009B with no `[`); a dangling
+ * introducer goes with its ESC/C1 byte, while an unterminated payload (an
+ * OSC/DCS sequence missing its terminator) may leave that payload as visible
+ * text. CR is dropped, so CRLF collapses to LF and a
+ * lone CR cannot overwrite the rendered line. A guard against terminal control
+ * and invisible text, not a content filter: markdown and XML-ish characters
+ * pass through untouched. The result is always well-formed UTF-16: an
+ * unpaired surrogate becomes U+FFFD, or the paired character when a removal
+ * above brings a high and a low surrogate together. Leaving one in place
+ * would let a padded or clamped row overflow — a terminal renders it as
+ * U+FFFD one column wide, while width helpers count it as zero columns.
+ *
+ * The invisible/format set includes the Unicode Tag block (U+E0001,
+ * U+E0020–U+E007F), which encodes invisible ASCII payloads, plus CGJ (U+034F),
+ * the Hangul fillers (U+115F/U+1160/U+3164/U+FFA0), the variation-selector
+ * supplement (U+E0100–U+E01EF), the zero-width/directional mark range
+ * (U+200B–U+200F, including ZWJ U+200D), the line/paragraph separators
+ * (U+2028/U+2029), the bidi embedding/override controls (U+202A–U+202E), the
+ * U+2060–U+2069 block (word joiner, invisible operators, bidi isolates), soft
+ * hyphen (U+00AD), ALM (U+061C), the Mongolian vowel separator (U+180E), and
+ * BOM/ZWNBSP (U+FEFF). Stripping those families is a deliberate over-strip for
+ * Trojan-Source/covert-channel defense even though they have legitimate roles —
+ * CGJ blocks Arabic/Indic ligatures, the VS supplement selects CJK ideographic
+ * glyph variants, the Hangul fillers appear in old-Hangul text, ZWJ joins emoji
+ * and Indic sequences, and the bidi controls/isolates steer RTL layout.
+ * U+FE0E/U+FE0F are deliberately kept: they carry emoji vs text presentation.
+ */
+export function stripControlChars(s: string): string {
+  return s
+    .replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g, "") // complete OSC: ESC ] … BEL | ST
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "") // complete CSI: ESC [ … final byte
+    .replace(/\u009b[0-?]*[ -/]*[@-~]/g, "") // complete C1 CSI: U+009B … final byte
+    .replace(/[\u001b\u009b][[\]()#;?]*/g, "") // dangling ESC/C1 plus its introducer
+    .replace(
+      /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g,
+      "\uFFFD",
+    ) // coerce unpaired surrogates
+    .replace(
+      /[\u{e0100}-\u{e01ef}\u034f\x00-\x08\x0b-\x0d\x0e-\x1f\x7f-\x9f\u00ad\u061c\u115f\u1160\u180e\u200b-\u200f\u2028-\u202e\u2060-\u2069\u3164\ufeff\uffa0\u{e0001}\u{e0020}-\u{e007f}]/gu,
+      "",
+    );
+}
+
+/**
+ * Collapse newlines/CRs/tabs to spaces and strip control/invisible characters,
+ * for untrusted text composed into a single terminal line (report headers and
+ * metadata, tool-call lines, widget rows). Use `stripControlChars` for body
+ * and display paths that preserve layout. A display sanitizer, not a type
+ * guard: non-string input renders as the empty string.
+ */
+export function toSingleLine(s: unknown): string {
+  if (typeof s !== "string") return "";
+  return stripControlChars(s.replace(/\r\n?|\n/g, " ").replace(/\t/g, " ")).trim();
+}
+
+/** Truncate to maxChars UTF-16 code units, never splitting a surrogate pair. */
+export function safeTruncate(s: string, maxChars: number): string {
+  if (s.length <= maxChars) return s;
+  const high = s.charCodeAt(maxChars - 1);
+  return high >= 0xD800 && high <= 0xDBFF ? s.slice(0, maxChars - 1) : s.slice(0, maxChars);
+}