@cad0p/pi-subagents-tintinweb 0.14.2 → 0.22.0

package/src/agent-types.ts

@@ -5,7 +5,18 @@
  * User agents override defaults with the same name. Disabled agents are kept but excluded from spawning.
  */
 
-import { createCodingTools, createReadOnlyTools } from "@earendil-works/pi-coding-agent";
+import {
+  createBashToolDefinition,
+  createCodingTools,
+  createEditToolDefinition,
+  createFindToolDefinition,
+  createGrepToolDefinition,
+  createLsToolDefinition,
+  createPowerShellToolDefinition,
+  createReadOnlyTools,
+  createReadToolDefinition,
+  createWriteToolDefinition,
+} from "@earendil-works/pi-coding-agent";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import type { AgentConfig } from "./types.js";
 
@@ -21,6 +32,40 @@ export const BUILTIN_TOOL_NAMES: string[] = [
   ...new Set([...createCodingTools("."), ...createReadOnlyTools(".")].map((t) => t.name)),
 ];
 
+/**
+ * One-line `<tools>` snippets for the built-in tools, keyed by name.
+ *
+ * An append-mode child inherits the parent's `<tools>` block, which lists only
+ * the tools the parent has *active* — pi's default set is read/bash/edit/write —
+ * while an agent's `tools:` defaults to every built-in, grep/find/ls included.
+ * Retargeting the block from the inherited text alone would therefore advertise
+ * fewer tools than the child can call. These come from pi's own definitions, so
+ * the wording cannot drift from what pi prints in a main session.
+ */
+let builtinToolSnippets: Record<string, string> | undefined;
+
+/** Snippets for pi's built-in tools, built on first use (see above). */
+export function getBuiltinToolSnippets(): Record<string, string> {
+  // Built by calling pi's own factories rather than importing a snippet table, so
+  // the wording cannot drift. Called with the process cwd: a snippet is static text
+  // and nothing here executes the tool.
+  builtinToolSnippets ??= Object.fromEntries(
+    [
+      createReadToolDefinition("."),
+      createBashToolDefinition("."),
+      createEditToolDefinition("."),
+      createWriteToolDefinition("."),
+      createGrepToolDefinition("."),
+      createFindToolDefinition("."),
+      createLsToolDefinition("."),
+      createPowerShellToolDefinition("."),
+    ].flatMap((definition) =>
+      definition.promptSnippet ? [[definition.name, definition.promptSnippet] as const] : [],
+    ),
+  );
+  return builtinToolSnippets;
+}
+
 /** Unified runtime registry of all agents (defaults + user-defined). */
 const agents = new Map<string, AgentConfig>();
 
@@ -33,6 +78,47 @@ export function isDefaultsDisabled(): boolean { return disableDefaults; }
 /** Set whether default agents are disabled. */
 export function setDefaultsDisabled(b: boolean): void { disableDefaults = b; }
 
+/** `fallbackSubagent` value that disables the fallback entirely (strict dispatch). */
+export const NO_FALLBACK = "none";
+
+/**
+ * The agent type an unset `fallbackSubagent` targets. Naming it explicitly is
+ * equivalent to leaving the setting unset — see `resolveSpawnTypeIn`.
+ */
+export const IMPLICIT_FALLBACK = "general-purpose";
+
+/**
+ * Agent type substituted when a caller-supplied `subagent_type` doesn't resolve
+ * to exactly one enabled agent. `undefined` keeps the historical behavior
+ * (general-purpose); `NO_FALLBACK` makes dispatch fail closed. Set from
+ * `subagents.json` (`fallbackSubagent`).
+ *
+ * Module state rather than an index.ts closure because every caller-supplied
+ * spawn path needs it — the Agent tool, the scheduler, and cross-extension RPC.
+ */
+let fallbackSubagent: string | undefined;
+
+/** Get the configured fallback agent type. undefined = general-purpose. */
+export function getFallbackSubagent(): string | undefined { return fallbackSubagent; }
+
+/** Set the configured fallback agent type. undefined = general-purpose. */
+export function setFallbackSubagent(v: string | undefined): void { fallbackSubagent = v; }
+
+/**
+ * Build a registry map: DEFAULT_AGENTS first (unless disabled via settings),
+ * then user agents overlaid on top (same name overrides the default).
+ * Pure — callers that must not disturb the process-wide registry (nested
+ * delegation resolving agents from its own config root) build their own map.
+ */
+export function buildAgentRegistry(userAgents: Map<string, AgentConfig>): Map<string, AgentConfig> {
+  const registry = new Map<string, AgentConfig>();
+  if (!disableDefaults) {
+    for (const [name, config] of DEFAULT_AGENTS) registry.set(name, config);
+  }
+  for (const [name, config] of userAgents) registry.set(name, config);
+  return registry;
+}
+
 /**
  * Register agents into the unified registry.
  * Starts with DEFAULT_AGENTS, then overlays user agents (overrides defaults with same name).
@@ -40,30 +126,51 @@ export function setDefaultsDisabled(b: boolean): void { disableDefaults = b; }
  */
 export function registerAgents(userAgents: Map<string, AgentConfig>): void {
   agents.clear();
-
-  // Start with defaults (unless disabled via settings)
-  if (!disableDefaults) {
-    for (const [name, config] of DEFAULT_AGENTS) {
-      agents.set(name, config);
-    }
-  }
-
-  // Overlay user agents (overrides defaults with same name)
-  for (const [name, config] of userAgents) {
+  for (const [name, config] of buildAgentRegistry(userAgents)) {
     agents.set(name, config);
   }
 }
 
-/** Case-insensitive key resolution. */
-function resolveKey(name: string): string | undefined {
-  if (agents.has(name)) return name;
+/** Case-insensitive key resolution within a registry. */
+function resolveKeyIn(registry: Map<string, AgentConfig>, name: string): string | undefined {
+  if (registry.has(name)) return name;
   const lower = name.toLowerCase();
-  for (const key of agents.keys()) {
+  for (const key of registry.keys()) {
     if (key.toLowerCase() === lower) return key;
   }
   return undefined;
 }
 
+/** Case-insensitive key resolution. */
+function resolveKey(name: string): string | undefined {
+  return resolveKeyIn(agents, name);
+}
+
+/** Resolve a type name case-insensitively in a registry. Returns the canonical key or undefined. */
+export function resolveTypeIn(registry: Map<string, AgentConfig>, name: string): string | undefined {
+  return resolveKeyIn(registry, name);
+}
+
+/** Get the agent config for a type (case-insensitive) from a registry. */
+export function getAgentConfigIn(registry: Map<string, AgentConfig>, name: string): AgentConfig | undefined {
+  const key = resolveKeyIn(registry, name);
+  return key ? registry.get(key) : undefined;
+}
+
+/** Check if a type is valid and enabled (case-insensitive) in a registry. */
+export function isValidTypeIn(registry: Map<string, AgentConfig>, type: string): boolean {
+  const key = resolveKeyIn(registry, type);
+  if (!key) return false;
+  return registry.get(key)?.enabled !== false;
+}
+
+/** Get all enabled type names in a registry (for spawning and tool descriptions). */
+export function getAvailableTypesIn(registry: Map<string, AgentConfig>): string[] {
+  return [...registry.entries()]
+    .filter(([_, config]) => config.enabled !== false)
+    .map(([name]) => name);
+}
+
 /** Resolve a type name case-insensitively. Returns the canonical key or undefined. */
 export function resolveType(name: string): string | undefined {
   return resolveKey(name);
@@ -71,15 +178,12 @@ export function resolveType(name: string): string | undefined {
 
 /** Get the agent config for a type (case-insensitive). */
 export function getAgentConfig(name: string): AgentConfig | undefined {
-  const key = resolveKey(name);
-  return key ? agents.get(key) : undefined;
+  return getAgentConfigIn(agents, name);
 }
 
 /** Get all enabled type names (for spawning and tool descriptions). */
 export function getAvailableTypes(): string[] {
-  return [...agents.entries()]
-    .filter(([_, config]) => config.enabled !== false)
-    .map(([name]) => name);
+  return getAvailableTypesIn(agents);
 }
 
 /** Get all type names including disabled (for UI listing). */
@@ -103,9 +207,146 @@ export function getUserAgentNames(): string[] {
 
 /** Check if a type is valid and enabled (case-insensitive). */
 export function isValidType(type: string): boolean {
-  const key = resolveKey(type);
-  if (!key) return false;
-  return agents.get(key)?.enabled !== false;
+  return isValidTypeIn(agents, type);
+}
+
+/**
+ * Case-insensitive resolution that refuses to guess. An exact match always wins;
+ * otherwise the name must match exactly one key. Two agents differing only in
+ * case are reachable (`loadCustomAgents` keys by filename across three
+ * directories), and picking whichever came first would silently dispatch a
+ * different agent, model and tool policy than the caller meant.
+ */
+function resolveUnambiguousKeyIn(registry: Map<string, AgentConfig>, name: string): string | undefined {
+  if (registry.has(name)) return name;
+  const lower = name.toLowerCase();
+  const matches = [...registry.keys()].filter(key => key.toLowerCase() === lower);
+  return matches.length === 1 ? matches[0] : undefined;
+}
+
+/** Whether any key in the registry matches `name` case-insensitively. */
+function isNameClaimed(registry: Map<string, AgentConfig>, name: string): boolean {
+  const lower = name.toLowerCase();
+  return [...registry.keys()].some((key) => key.toLowerCase() === lower);
+}
+
+/**
+ * The canonical key for a caller-supplied name that identifies exactly one
+ * ENABLED agent, or undefined. Strict by construction: no fallback, no guessing
+ * between case-variants.
+ */
+export function resolveEnabledTypeIn(
+  registry: Map<string, AgentConfig>,
+  requested: unknown,
+): string | undefined {
+  const raw = typeof requested === "string" ? requested.trim() : "";
+  if (!raw) return undefined;
+  const key = resolveUnambiguousKeyIn(registry, raw);
+  return key !== undefined && registry.get(key)?.enabled !== false ? key : undefined;
+}
+
+/** Outcome of resolving a caller-supplied `subagent_type` into a spawnable type. */
+export type SpawnTypeResolution =
+  /** Spawn this type. `fellBackFrom` is set when it isn't what the caller asked for. */
+  | { ok: true; type: string; fellBackFrom?: string }
+  /** Refuse the spawn and return this message to the caller. */
+  | { ok: false; message: string };
+
+/**
+ * Resolve a caller-supplied agent type against a registry, applying the
+ * `fallbackSubagent` policy. The single decision point for every caller-supplied
+ * spawn — the Agent tool, the scheduler and cross-extension RPC — so a type that
+ * fails here never reaches `runAgent`, where `getConfig` would silently
+ * substitute general-purpose.
+ *
+ * Unknown, disabled, and case-ambiguous names are all treated the same way:
+ * the caller named something that doesn't identify exactly one enabled agent.
+ *
+ * Pure over `registry` — callers that need fresh agent files reload before
+ * calling (the Agent tool already does, per spawn). Reloading here would mean
+ * importing custom-agents.ts, which imports this module.
+ */
+export function resolveSpawnTypeIn(
+  registry: Map<string, AgentConfig>,
+  requested: unknown,
+): SpawnTypeResolution {
+  const raw = typeof requested === "string" ? requested.trim() : "";
+  const available = () => getAvailableTypesIn(registry).join(", ") || "(none)";
+
+  const key = resolveEnabledTypeIn(registry, raw);
+  if (key !== undefined) return { ok: true, type: key };
+
+  // A missing type follows the same policy as a wrong one rather than always
+  // erroring: before this setting existed an empty type fell back like any
+  // other unresolvable name, and only opting in should change that.
+  const reason = raw ? `Unknown or disabled agent type: "${raw}".` : "No agent type given.";
+
+  // Trimmed like `requested`: a padded value set programmatically would
+  // otherwise be reported as a missing agent.
+  const configured = typeof fallbackSubagent === "string" ? fallbackSubagent.trim() : undefined;
+
+  if (configured !== undefined && configured.toLowerCase() === NO_FALLBACK) {
+    return { ok: false, message: `${reason} Available: ${available()}.` };
+  }
+
+  if (configured !== undefined) {
+    const fallbackKey = resolveUnambiguousKeyIn(registry, configured);
+    if (fallbackKey === undefined || registry.get(fallbackKey)?.enabled === false) {
+      // Naming the implicit default is not a misconfiguration when nothing in the
+      // registry claims the name at all: an unset fallback already targets it, and
+      // the permissive hardcoded tier is what that resolves to even when the
+      // default agents are disabled — the case the settings row's own default
+      // cycles through. A registered-but-disabled general-purpose, or a
+      // case-ambiguous name, stays an error like any other: someone wrote that on
+      // purpose, and quietly running the all-tools tier is what `fallbackSubagent`
+      // exists to prevent. `none` is how strict dispatch is expressed.
+      if (configured.toLowerCase() === IMPLICIT_FALLBACK && !isNameClaimed(registry, configured)) {
+        return { ok: true, type: IMPLICIT_FALLBACK, fellBackFrom: raw };
+      }
+      // An explicitly configured fallback that is itself unusable is a
+      // misconfiguration, not a second chance to guess — say so rather than
+      // quietly dropping to general-purpose.
+      return {
+        ok: false,
+        message:
+          `${reason} The configured fallbackSubagent "${configured}" is itself ` +
+          `unknown or disabled. Available: ${available()}.`,
+      };
+    }
+    return { ok: true, type: fallbackKey, fellBackFrom: raw };
+  }
+
+  // Unset: historical behavior, deliberately unchanged. The fallback stays the
+  // default, so the pre-existing hole it leaves — an unregistered
+  // general-purpose resolving to `getConfig`'s all-tools hardcoded tier — is
+  // what `fallbackSubagent: none` is for, not something to close under everyone
+  // silently.
+  return { ok: true, type: IMPLICIT_FALLBACK, fellBackFrom: raw };
+}
+
+/** Resolve a caller-supplied agent type against the process-wide registry. */
+export function resolveSpawnType(requested: unknown): SpawnTypeResolution {
+  return resolveSpawnTypeIn(agents, requested);
+}
+
+/**
+ * Whether a configured `fallbackSubagent` names something dispatch would accept.
+ *
+ * Mirrors `resolveSpawnTypeIn`'s policy exactly, including the ambiguity over ALL
+ * registry keys (not just the enabled ones) and the implicit default's unregistered
+ * case. The settings row uses this so it cannot tell the user a value is fine while
+ * dispatch refuses it, or the reverse.
+ */
+export function isFallbackResolvableIn(registry: Map<string, AgentConfig>, configured: string): boolean {
+  const name = configured.trim();
+  const key = resolveUnambiguousKeyIn(registry, name);
+  if (key !== undefined) return registry.get(key)?.enabled !== false;
+  return name.toLowerCase() === IMPLICIT_FALLBACK && !isNameClaimed(registry, name);
+}
+
+/** Whether a configured fallback resolves, against the process-wide registry. */
+export function isFallbackResolvable(configured: string): boolean {
+  return isFallbackResolvableIn(agents, configured);
 }
 
 /** Tool names required for memory management. */
@@ -187,3 +428,8 @@ export function getConfig(type: string): {
   };
 }
 
+// Seed the defaults at module load so consumers that run before the extension's
+// init (direct store use, tools) see the same registry production uses;
+// registerAgents() re-seeds on every explicit call.
+registerAgents(new Map());
+

package/src/checkpoint.ts

@@ -0,0 +1,49 @@
+/**
+ * checkpoint.ts — the subagent-facing `checkpoint` write path, shared by the
+ * top-level extension registration (every subagent session) and the nested
+ * delegation tool set, so the two cannot drift on format or failure handling.
+ */
+
+import { appendFileSync } from "node:fs";
+import type { AgentRecord } from "./types.js";
+
+/** Derive the `.checkpoints.md` path from `outputFile`. Mirrors the
+ *  `record.outputFile` gate (undefined when suppressed). Appends the suffix
+ *  unconditionally — a `replace(/\.output$/, ...)` would silently return the
+ *  transcript path unchanged if `outputFile` ever lacked the suffix. */
+export function checkpointsFilePath(outputFile: string | undefined): string | undefined {
+  if (!outputFile) return undefined;
+  return `${outputFile}.checkpoints.md`;
+}
+
+/**
+ * Record a checkpoint on `record` and append it to the `.checkpoints.md`
+ * history. Returns the tool text for the calling subagent.
+ *
+ * Best-effort: a write failure (disk full, missing parent dir) returns a soft
+ * warning instead of crashing the call. `checkpointsFileOk` is latching-true —
+ * see AgentRecord.checkpointsFileOk for the suppression contract.
+ */
+export function saveCheckpoint(record: AgentRecord, summary: string): string {
+  const turn = record.turnCount ?? 0;
+  const maxTurns = record.effectiveMaxTurns;
+  const elapsedSeconds = Math.round((Date.now() - record.startedAt) / 1000);
+  record.lastCheckpoint = { turn, summary };
+
+  const maxTurnsLabel = maxTurns != null ? `/${maxTurns}` : "";
+  const path = checkpointsFilePath(record.outputFile);
+  if (path) {
+    try {
+      appendFileSync(
+        path,
+        `## Turn ${turn}${maxTurnsLabel} — ${elapsedSeconds}s elapsed\n${summary}\n\n`,
+        "utf-8",
+      );
+      record.checkpointsFileOk = true;
+    } catch (err) {
+      return `Checkpoint saved in memory, but file write failed: ${err instanceof Error ? err.message : String(err)}.`;
+    }
+  }
+
+  return `Checkpoint saved (turn ${turn}${maxTurnsLabel}, ${elapsedSeconds}s).`;
+}

package/src/child-context.ts

@@ -0,0 +1,30 @@
+/**
+ * child-context.ts — marks the async context in which a subagent's session is
+ * loaded and constructed.
+ *
+ * The extension factory runs during `loader.reload()`, so a child session that
+ * loads pi-subagents re-activates it in this process. That activation must not
+ * register the parent-facing tools (`Agent`, `get_subagent_result`,
+ * `steer_subagent`): its manager is empty, so an `Agent` there could only spawn
+ * into a manager nobody reads — and an opted-in child receives the nested
+ * `Agent` as an SDK custom tool, where a second definition of the same name
+ * would leave the survivor to pi's registration precedence.
+ *
+ * Async-context-local so concurrent top-level extension work is unaffected, and
+ * so a harness that activates the extension directly (no child context) still
+ * gets the parent tools.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const childSessionContext = new AsyncLocalStorage<boolean>();
+
+/** True while the current async context is building a subagent session. */
+export function inChildSessionContext(): boolean {
+  return childSessionContext.getStore() === true;
+}
+
+/** Run `fn` (resource loading / session construction) as a subagent session. */
+export function runInChildSessionContext<T>(fn: () => Promise<T>): Promise<T> {
+  return childSessionContext.run(true, fn);
+}

package/src/cross-extension-rpc.ts

@@ -1,8 +1,8 @@
 /**
  * Cross-extension RPC handlers for the subagents extension.
  *
- * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
- * using per-request scoped reply channels.
+ * Exposes ping, spawn, stop, consume and steer RPCs over the pi.events event
+ * bus, using per-request scoped reply channels.
  *
  * Reply envelope follows pi-mono convention:
  *   success → { success: true, data?: T }
@@ -10,6 +10,7 @@
  */
 
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
+import type { AgentRecord } from "./types.js";
 
 /** Minimal event bus interface needed by the RPC handlers. */
 export interface EventBus {
@@ -25,10 +26,27 @@ export type RpcReply<T = void> =
 /** RPC protocol version — bumped when the envelope or method contracts change. */
 export const PROTOCOL_VERSION = 2;
 
-/** Minimal AgentManager interface needed by the spawn/stop RPCs. */
+/** Minimal AgentManager interface needed by the spawn/stop/consume/steer RPCs. */
 export interface SpawnCapable {
   spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: any): string;
   abort(id: string): boolean;
+  /**
+   * The record behind an id, for the ownership check stop, consume and steer
+   * share. Narrowed to the one field that check reads, so the RPC layer keeps
+   * its deliberately shallow view of the manager.
+   */
+  getRecord(id: string): Pick<AgentRecord, "parentAgentId"> | undefined;
+  /**
+   * Mark a settled agent's result as read by the caller, suppressing the
+   * completion notification — what `get_subagent_result` does when it returns
+   * one. False when there is no such agent, or it has not settled yet.
+   */
+  consumeResult(id: string): boolean;
+  /**
+   * Deliver a message to a running or queued agent's conversation — what
+   * `steer_subagent` does. False when the agent is unknown or has settled.
+   */
+  steer(id: string, message: string): boolean;
 }
 
 export interface RpcDeps {
@@ -42,6 +60,8 @@ export interface RpcHandle {
   unsubPing: () => void;
   unsubSpawn: () => void;
   unsubStop: () => void;
+  unsubConsume: () => void;
+  unsubSteer: () => void;
 }
 
 /**
@@ -69,7 +89,7 @@ function handleRpc<P extends { requestId: string }>(
 }
 
 /**
- * Register ping, spawn, and stop RPC handlers on the event bus.
+ * Register ping, spawn, stop, consume and steer RPC handlers on the event bus.
  * Returns unsub functions for cleanup.
  */
 export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
@@ -112,11 +132,51 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
     },
   );
 
+  // Only the session's own agents are this RPC's to stop, steer or consume. A
+  // nested child is owned by the agent *waiting on it*, and aborting, redirecting
+  // or silencing it out from under that owner turns another extension's request
+  // into a failed step here. Defence in depth rather than a live hole: no RPC
+  // hands out agent ids, so a caller has no ordinary way to name one it does not
+  // own — but the guard is cheap and the id may leak some other way.
+  const assertOwned = (agentId: string): void => {
+    const record = manager.getRecord(agentId);
+    if (!record) throw new Error("Agent not found");
+    if (record.parentAgentId) throw new Error("Agent is owned by another agent");
+  };
+
   const unsubStop = handleRpc<{ requestId: string; agentId: string }>(
     events, "subagents:rpc:stop", ({ agentId }) => {
+      assertOwned(agentId);
       if (!manager.abort(agentId)) throw new Error("Agent not found");
     },
   );
 
-  return { unsubPing, unsubSpawn, unsubStop };
+  // A caller that has already shown the model an agent's result — pi-tasks'
+  // TaskOutput is the one in practice — says so here, so the completion
+  // notification for that same result is not delivered on top of it and does
+  // not cost the parent a turn. Deliberately outside the ping version
+  // handshake: an extension built against protocol v2 simply never calls it.
+  const unsubConsume = handleRpc<{ requestId: string; agentId: string }>(
+    events, "subagents:rpc:consume", ({ agentId }) => {
+      assertOwned(agentId);
+      if (!manager.consumeResult(agentId)) throw new Error("Agent not found or still running");
+    },
+  );
+
+  // An extension that spawned an agent over the bus and then learns something
+  // that agent needs — a second CI failure on the head it is already fixing, a
+  // review that landed mid-run — can hand it over instead of spawning a second
+  // agent for the same work or dropping the fact. Outside the ping version
+  // handshake, like consume: additive and best-effort.
+  const unsubSteer = handleRpc<{ requestId: string; agentId: string; message: unknown }>(
+    events, "subagents:rpc:steer", ({ agentId, message }) => {
+      if (typeof message !== "string" || message.trim().length === 0) {
+        throw new Error("Steer message must be a non-empty string");
+      }
+      assertOwned(agentId);
+      if (!manager.steer(agentId, message)) throw new Error("Agent is not running");
+    },
+  );
+
+  return { unsubPing, unsubSpawn, unsubStop, unsubConsume, unsubSteer };
 }