@esso0428/pi-subagents 0.17.16 → 0.17.18

package/src/agent-types.ts

@@ -7,9 +7,10 @@
 
 import { createCodingTools, createReadOnlyTools } from "@earendil-works/pi-coding-agent";
 import { DEFAULT_AGENTS } from "./default-agents.js";
-import { applyNicoOverride, applyNicoOverridesToMap, readNicoAgentOverrides } from "./nico-overrides.js";
+import { applyNicoOverridesToMap, readNicoAgentOverrides } from "./nico-overrides.js";
 import type { AgentConfig } from "./types.js";
 
+
 /**
  * All known built-in tool names, derived from pi's own tool factories rather
  * than hardcoded so the set tracks pi-mono if it adds/renames a built-in.
@@ -34,41 +35,6 @@ 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";
-
-/**
- * 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).
@@ -76,163 +42,39 @@ export function buildAgentRegistry(userAgents: Map<string, AgentConfig>): Map<st
  */
 export function registerAgents(userAgents: Map<string, AgentConfig>): void {
   agents.clear();
-  for (const [name, config] of buildAgentRegistry(userAgents)) {
-    agents.set(name, config);
-  }
-  const { overrides, defaultModel } = readNicoAgentOverrides(process.cwd());
+
+  // Start with defaults (unless disabled via settings)
   if (!disableDefaults) {
-    applyNicoOverridesToMap(agents, overrides, defaultModel);
-  } else {
-    // Disabling built-ins must also prevent JSON-only built-ins from being
-    // synthesized; explicit user agents remain eligible for their overrides.
-    for (const [name, config] of agents) {
-      const override = overrides[name];
-      if (override) agents.set(name, applyNicoOverride(config, override, defaultModel));
+    for (const [name, config] of DEFAULT_AGENTS) {
+      agents.set(name, config);
     }
   }
-}
 
-/** 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 registry.keys()) {
-    if (key.toLowerCase() === lower) return key;
+  // Overlay user agents (overrides defaults with same name)
+  for (const [name, config] of userAgents) {
+    agents.set(name, config);
   }
-  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);
 }
 
 /**
- * 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.
+ * Apply npm:pi-subagents-style JSON overrides to the current agent registry.
+ * Reads from ~/.pi/agent/settings.json and .pi/settings.json and applies
+ * them as the highest-priority layer. Auto-registers agents that don't
+ * exist in the registry yet.
  */
-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;
-}
-
-/**
- * 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. Nested delegation resolves with this directly, since
- * "unknown types are rejected rather than falling back" is its own contract.
- */
-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;
+export function applyNicoOverrides(): void {
+  const { overrides, defaultModel } = readNicoAgentOverrides(process.cwd());
+  applyNicoOverridesToMap(agents, overrides, defaultModel);
 }
 
-/** 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, cross-extension RPC, and the nested
- * tools — 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) {
-    // 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.
-    const fallbackKey = resolveUnambiguousKeyIn(registry, configured);
-    if (fallbackKey === undefined || registry.get(fallbackKey)?.enabled === false) {
-      return {
-        ok: false,
-        message:
-          `${reason} The configured fallbackSubagent "${configured}" is itself ` +
-          `unknown or disabled. Available: ${available()}.`,
-      };
-    }
-    return { ok: true, type: fallbackKey, fellBackFrom: raw };
+/** Case-insensitive key resolution. */
+function resolveKey(name: string): string | undefined {
+  if (agents.has(name)) return name;
+  const lower = name.toLowerCase();
+  for (const key of agents.keys()) {
+    if (key.toLowerCase() === lower) return key;
   }
-
-  // Unset: historical behavior, deliberately unchanged. #183 asks for the
-  // fallback to remain 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: "general-purpose", fellBackFrom: raw };
-}
-
-/** Resolve a caller-supplied agent type against the process-wide registry. */
-export function resolveSpawnType(requested: unknown): SpawnTypeResolution {
-  return resolveSpawnTypeIn(agents, requested);
+  return undefined;
 }
 
 /** Resolve a type name case-insensitively. Returns the canonical key or undefined. */
@@ -242,12 +84,15 @@ export function resolveType(name: string): string | undefined {
 
 /** Get the agent config for a type (case-insensitive). */
 export function getAgentConfig(name: string): AgentConfig | undefined {
-  return getAgentConfigIn(agents, name);
+  const key = resolveKey(name);
+  return key ? agents.get(key) : undefined;
 }
 
 /** Get all enabled type names (for spawning and tool descriptions). */
 export function getAvailableTypes(): string[] {
-  return getAvailableTypesIn(agents);
+  return [...agents.entries()]
+    .filter(([_, config]) => config.enabled !== false)
+    .map(([name]) => name);
 }
 
 /** Get all type names including disabled (for UI listing). */
@@ -265,13 +110,15 @@ export function getDefaultAgentNames(): string[] {
 /** Get names of user-defined agents (non-defaults) currently in the registry. */
 export function getUserAgentNames(): string[] {
   return [...agents.entries()]
-    .filter(([_, config]) => config.isDefault !== true && !config.description.startsWith("Auto-registered from npm:pi-subagents JSON settings"))
+    .filter(([_, config]) => config.isDefault !== true)
     .map(([name]) => name);
 }
 
 /** Check if a type is valid and enabled (case-insensitive). */
 export function isValidType(type: string): boolean {
-  return isValidTypeIn(agents, type);
+  const key = resolveKey(type);
+  if (!key) return false;
+  return agents.get(key)?.enabled !== false;
 }
 
 /** Tool names required for memory management. */
@@ -307,7 +154,6 @@ export function getToolNamesForType(type: string): string[] {
 /** Get config for a type (case-insensitive, returns a SubagentTypeConfig-compatible object). Falls back to general-purpose. */
 export function getConfig(type: string): {
   displayName: string;
-  color?: string;
   description: string;
   builtinToolNames: string[];
   extensions: true | string[] | false;
@@ -320,7 +166,6 @@ export function getConfig(type: string): {
   if (config && config.enabled !== false) {
     return {
       displayName: config.displayName ?? config.name,
-      color: config.color,
       description: config.description,
       builtinToolNames: config.builtinToolNames ?? BUILTIN_TOOL_NAMES,
       extensions: config.extensions,
@@ -335,7 +180,6 @@ export function getConfig(type: string): {
   if (gp && gp.enabled !== false) {
     return {
       displayName: gp.displayName ?? gp.name,
-      color: gp.color,
       description: gp.description,
       builtinToolNames: gp.builtinToolNames ?? BUILTIN_TOOL_NAMES,
       extensions: gp.extensions,

package/src/cross-extension-rpc.ts

@@ -1,22 +1,15 @@
 /**
  * Cross-extension RPC handlers for the subagents extension.
  *
- * Exposes ping, spawn, stop, and consume RPCs over the pi.events event bus,
+ * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
  * using per-request scoped reply channels.
  *
  * Reply envelope follows pi-mono convention:
  *   success → { success: true, data?: T }
  *   error   → { success: false, error: string }
- *
- * @see docs/rpc.md — the caller-facing integration reference: spawn options
- * (including the fields spawnTopLevel strips), every error string, the
- * completion-notification race, and what protocol version 2 does not promise.
  */
 
-import { isTopLevelAgent } from "./agent-manager.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
-import { checkModelScope } from "./model-scope.js";
-import type { AgentRecord } from "./types.js";
 
 /** Minimal event bus interface needed by the RPC handlers. */
 export interface EventBus {
@@ -32,24 +25,10 @@ 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/consume RPCs. */
+/** Minimal AgentManager interface needed by the spawn/stop RPCs. */
 export interface SpawnCapable {
   spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: any): string;
-  /** Resolves once the spawned agent is running; rejects on a startup failure. */
-  awaitStartup(id: string): Promise<void>;
   abort(id: string): boolean;
-  /**
-   * The record behind an id, for the stop handler's ownership check. Narrowed
-   * to the two fields `isTopLevelAgent` reads, so the RPC layer keeps its
-   * deliberately shallow view of the manager.
-   */
-  getRecord(id: string): Pick<AgentRecord, "parentAgentId" | "workflowId"> | 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;
 }
 
 export interface RpcDeps {
@@ -63,7 +42,6 @@ export interface RpcHandle {
   unsubPing: () => void;
   unsubSpawn: () => void;
   unsubStop: () => void;
-  unsubConsume: () => void;
 }
 
 /**
@@ -91,7 +69,7 @@ function handleRpc<P extends { requestId: string }>(
 }
 
 /**
- * Register ping, spawn, stop, and consume RPC handlers on the event bus.
+ * Register ping, spawn, and stop RPC handlers on the event bus.
  * Returns unsub functions for cleanup.
  */
 export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
@@ -102,7 +80,7 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
   });
 
   const unsubSpawn = handleRpc<{ requestId: string; type: string; prompt: string; options?: any }>(
-    events, "subagents:rpc:spawn", async ({ type, prompt, options }) => {
+    events, "subagents:rpc:spawn", ({ type, prompt, options }) => {
       const ctx = getCtx();
       if (!ctx) throw new Error("No active session");
 
@@ -113,86 +91,32 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
       // agent's auth lookup doesn't crash with "No API key found for
       // undefined".
       let normalizedOptions = options ?? {};
-      // `!= null` on purpose: a JSON-forwarding caller can serialize an unset
-      // field as null, and the runner reads `options.model ?? default`, so null
-      // means "inherit" — not an override to resolve or scope-check.
-      const override = normalizedOptions.model;
-      if (override != null) {
-        const { modelRegistry, cwd } = ctx as { modelRegistry?: ModelRegistry; cwd?: string };
-        // Names the override the same way in both messages below; an object
-        // override would otherwise interpolate as "[object Object]".
-        const label = typeof override === "string" ? override : `${override.provider}/${override.id}`;
-        if (!modelRegistry) {
-          throw new Error(`Model override "${label}" provided but ctx.modelRegistry is unavailable`);
+      if (typeof normalizedOptions.model === "string") {
+        const registry = (ctx as { modelRegistry?: ModelRegistry }).modelRegistry;
+        if (!registry) {
+          throw new Error(
+            `Model override "${normalizedOptions.model}" provided but ctx.modelRegistry is unavailable`,
+          );
         }
-        let model = override;
-        if (typeof override === "string") {
-          const resolved = resolveModel(override, modelRegistry);
-          if (typeof resolved === "string") {
-            // resolveModel returns a human-readable error string when the
-            // input doesn't match any available model. Surface it instead of
-            // silently falling back so the caller sees the auth/typo issue.
-            throw new Error(resolved);
-          }
-          model = resolved;
-          normalizedOptions = { ...normalizedOptions, model: resolved };
+        const resolved = resolveModel(normalizedOptions.model, registry);
+        if (typeof resolved === "string") {
+          // resolveModel returns a human-readable error string when the
+          // input doesn't match any available model. Surface it instead of
+          // silently falling back so the caller sees the auth/typo issue.
+          throw new Error(resolved);
         }
-
-        // A model on the RPC payload is an orchestrator-level choice, exactly
-        // like Agent({ model }) — so it gets the Agent tool's hard error, never
-        // the frontmatter warn (#240). The check reads the RESOLVED model:
-        // resolveModel is fuzzy, so a bare "sonnet" can land on a provider the
-        // caller never named. Frontmatter-pinned and parent-inherited models are
-        // resolved later, in agent-runner, and keep warn-and-proceed.
-        const verdict = checkModelScope({
-          model,
-          cwd: cwd ?? process.cwd(),
-          modelRegistry,
-          callerSupplied: true,
-          agentLabel: type,
-          modelInput: label,
-        });
-        if (verdict.kind === "error") throw new Error(verdict.message);
+        normalizedOptions = { ...normalizedOptions, model: resolved };
       }
 
-      const id = manager.spawn(pi, ctx, type, prompt, normalizedOptions);
-      // With isolation: "worktree" the agent starts asynchronously — wait for
-      // it, so a strict-isolation failure is still an error envelope rather
-      // than an id for an agent that never ran.
-      await manager.awaitStartup(id);
-      return { id };
+      return { id: manager.spawn(pi, ctx, type, prompt, normalizedOptions) };
     },
   );
 
   const unsubStop = handleRpc<{ requestId: string; agentId: string }>(
     events, "subagents:rpc:stop", ({ agentId }) => {
-      const record = manager.getRecord(agentId);
-      if (!record) throw new Error("Agent not found");
-      // Only the session's own agents are this RPC's to stop. A nested child or
-      // a workflow's agent is owned by something that is *waiting on it*, and
-      // aborting it out from under that owner turns another extension's stop
-      // 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. Same refuse-what-we-should-not-touch stance as `consume` below.
-      if (!isTopLevelAgent(record)) throw new Error("Agent is owned by another agent or workflow");
-      // Not "not found" — the lookup above already proved it exists. `abort`
-      // returns false only for a record that is neither running nor queued,
-      // which is an agent that has already finished.
-      if (!manager.abort(agentId)) throw new Error("Agent is not running");
-    },
-  );
-
-  // 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 }) => {
-      if (!manager.consumeResult(agentId)) throw new Error("Agent not found or still running");
+      if (!manager.abort(agentId)) throw new Error("Agent not found");
     },
   );
 
-  return { unsubPing, unsubSpawn, unsubStop, unsubConsume };
+  return { unsubPing, unsubSpawn, unsubStop };
 }