@gotgenes/pi-subagents 5.2.0 → 5.4.0

package/src/agent-types.ts

@@ -48,12 +48,6 @@ export function resolveType(name: string): string | undefined {
   return resolveKey(name);
 }
 
-/** 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;
-}
-
 /** Get all enabled type names (for spawning and tool descriptions). */
 export function getAvailableTypes(): string[] {
   return [...agents.entries()]
@@ -116,49 +110,29 @@ export function getToolNamesForType(type: string): string[] {
   return names;
 }
 
-/** Get config for a type (case-insensitive, returns a SubagentTypeConfig-compatible object). Falls back to general-purpose. */
-export function getConfig(type: string): {
-  displayName: string;
-  description: string;
-  builtinToolNames: string[];
-  extensions: true | string[] | false;
-  skills: true | string[] | false;
-  promptMode: "replace" | "append";
-} {
+/** Resolve agent config with guaranteed non-null return. Falls back: unknown → general-purpose → absolute fallback. */
+export function resolveAgentConfig(type: string): AgentConfig {
   const key = resolveKey(type);
   const config = key ? agents.get(key) : undefined;
-  if (config && config.enabled !== false) {
-    return {
-      displayName: config.displayName ?? config.name,
-      description: config.description,
-      builtinToolNames: config.builtinToolNames ?? BUILTIN_TOOL_NAMES,
-      extensions: config.extensions,
-      skills: config.skills,
-      promptMode: config.promptMode,
-    };
+  if (config) {
+    return config;
   }
 
-  // Fallback for unknown/disabled types — general-purpose config
+  // Fallback to general-purpose for unknown types
   const gp = agents.get("general-purpose");
-  if (gp && gp.enabled !== false) {
-    return {
-      displayName: gp.displayName ?? gp.name,
-      description: gp.description,
-      builtinToolNames: gp.builtinToolNames ?? BUILTIN_TOOL_NAMES,
-      extensions: gp.extensions,
-      skills: gp.skills,
-      promptMode: gp.promptMode,
-    };
+  if (gp) {
+    return gp;
   }
 
-  // Absolute fallback (should never happen)
+  // Absolute fallback (should never happen in practice)
   return {
+    name: type,
     displayName: "Agent",
     description: "General-purpose agent for complex, multi-step tasks",
     builtinToolNames: BUILTIN_TOOL_NAMES,
     extensions: true,
     skills: true,
+    systemPrompt: "",
     promptMode: "append",
   };
 }
-

package/src/index.ts

@@ -14,7 +14,7 @@ import { join } from "node:path";
 import { defineTool, type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { AgentManager } from "./agent-manager.js";
 import { getAgentConversation, normalizeMaxTurns, steerAgent } from "./agent-runner.js";
-import { getAgentConfig, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, } from "./agent-types.js";
+import { getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveAgentConfig, } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { buildEventData, createNotificationSystem } from "./notification.js";
@@ -149,14 +149,14 @@ export default function (pi: ExtensionAPI) {
     const userNames = getUserAgentNames();
 
     const defaultDescs = defaultNames.map((name) => {
-      const cfg = getAgentConfig(name);
-      const modelSuffix = cfg?.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
-      return `- ${name}: ${cfg?.description ?? name}${modelSuffix}`;
+      const cfg = resolveAgentConfig(name);
+      const modelSuffix = cfg.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
+      return `- ${name}: ${cfg.description}${modelSuffix}`;
     });
 
     const customDescs = userNames.map((name) => {
-      const cfg = getAgentConfig(name);
-      return `- ${name}: ${cfg?.description ?? name}`;
+      const cfg = resolveAgentConfig(name);
+      return `- ${name}: ${cfg.description}`;
     });
 
     return [
@@ -237,8 +237,8 @@ export default function (pi: ExtensionAPI) {
     reloadCustomAgents,
     agentActivity: runtime.agentActivity,
     getModelLabel: (type, registry) => {
-      const cfg = getAgentConfig(type);
-      if (!cfg?.model) return 'inherit';
+      const cfg = resolveAgentConfig(type);
+      if (!cfg.model) return 'inherit';
       if (registry) {
         const resolved = resolveModel(cfg.model, registry as any);
         if (typeof resolved === 'string') return 'inherit';

package/src/session-config.ts

@@ -0,0 +1,243 @@
+/**
+ * session-config.ts — Pure configuration assembler for agent sessions.
+ *
+ * `assembleSessionConfig()` is the pure core extracted from `runAgent()`.
+ * It accepts resolved inputs (agent type, narrow context, run options, env info)
+ * and returns everything `runAgent()` needs to create the SDK session — without
+ * importing or constructing any Pi SDK types.
+ *
+ * The only async IO in the assembly phase (`detectEnv`) is handled by the caller
+ * before invoking this function, keeping the assembler synchronous.
+ */
+
+import {
+  getMemoryToolNames,
+  getReadOnlyMemoryToolNames,
+  getToolNamesForType,
+  resolveAgentConfig,
+} from "./agent-types.js";
+import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
+import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
+import { preloadSkills } from "./skill-loader.js";
+import type { EnvInfo, SubagentType, ThinkingLevel } from "./types.js";
+
+// ── Public interfaces ────────────────────────────────────────────────────────
+
+/**
+ * Narrow context the assembler reads from the parent session.
+ * Tests construct plain objects satisfying this interface — no SDK mocking needed.
+ *
+ * Models are treated as opaque handles: the assembler never inspects their
+ * internals, only passes them through. `getAvailable` returns just enough
+ * structural information ({ provider, id }) for the availability check in
+ * `resolveDefaultModel`.
+ */
+export interface AssemblerContext {
+  /** Parent working directory (overridable via options.cwd). */
+  cwd: string;
+  /** Parent's effective system prompt (for append-mode agents). */
+  parentSystemPrompt: string;
+  /** Parent's current model instance (fallback when agent config has no model). */
+  parentModel?: unknown;
+  /** Model registry for resolving config.model strings. */
+  modelRegistry: {
+    find(provider: string, modelId: string): unknown;
+    getAvailable?(): Array<{ provider: string; id: string }>;
+  };
+}
+
+/**
+ * Narrow slice of RunOptions consumed by the assembler.
+ * All fields are optional — callers pass only what they have.
+ */
+export interface AssemblerOptions {
+  /** Override working directory (e.g. for worktree isolation). */
+  cwd?: string;
+  /** When true, forces extensions and skills to false. */
+  isolated?: boolean;
+  /** Explicit model override — wins over agentConfig.model and parent model. */
+  model?: unknown;
+  /** Explicit thinking level — wins over agentConfig.thinking. */
+  thinkingLevel?: ThinkingLevel;
+}
+
+/**
+ * Assembled configuration returned to `runAgent()`.
+ * Contains everything needed to create the SDK session and filter tools —
+ * with no SDK object references.
+ */
+export interface SessionConfig {
+  /** Resolved working directory (`options.cwd ?? ctx.cwd`). */
+  effectiveCwd: string;
+  /** Fully-assembled system prompt string (ready for `systemPromptOverride`). */
+  systemPrompt: string;
+  /** Built-in tool names for session creation, filtering, and memory augmentation. */
+  toolNames: string[];
+  /** Disallowed tool set from agentConfig (for `filterActiveTools`). undefined when empty. */
+  disallowedSet: Set<string> | undefined;
+  /** Resolved extensions setting for resource loader and tool filtering. */
+  extensions: boolean | string[];
+  /**
+   * Resolved model instance (undefined → use parent model as passed to SDK).
+   * Opaque handle — the assembler passes it through without inspection.
+   * Caller casts to the SDK’s Model<any> at the session-creation boundary.
+   */
+  model: unknown;
+  /** Resolved thinking level (undefined → inherit from session). */
+  thinkingLevel: ThinkingLevel | undefined;
+  /** Whether to skip skill loading in the resource loader (`noSkills` flag). */
+  noSkills: boolean;
+  /** Prompt extras (memory block, preloaded skill blocks) — for transparency. */
+  extras: PromptExtras;
+  /** Per-agent configured max turns (from agentConfig.maxTurns). */
+  agentMaxTurns: number | undefined;
+}
+
+// ── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Resolve the default model from the agent config's model string.
+ *
+ * Priority: parentModel is the fallback; if `configModel` is a "provider/modelId"
+ * string that resolves against the registry AND is in the available set, return
+ * that model instead.
+ */
+function resolveDefaultModel(
+  parentModel: unknown,
+  registry: AssemblerContext["modelRegistry"],
+  configModel?: string,
+): unknown {
+  if (configModel) {
+    const slashIdx = configModel.indexOf("/");
+    if (slashIdx !== -1) {
+      const provider = configModel.slice(0, slashIdx);
+      const modelId = configModel.slice(slashIdx + 1);
+
+      const available = registry.getAvailable?.();
+      const availableKeys = available
+        ? new Set(available.map((m) => `${m.provider}/${m.id}`))
+        : undefined;
+      const isAvailable = (p: string, id: string) =>
+        !availableKeys || availableKeys.has(`${p}/${id}`);
+
+      const found = registry.find(provider, modelId);
+      if (found && isAvailable(provider, modelId)) return found;
+    }
+  }
+  return parentModel;
+}
+
+// ── Public function ──────────────────────────────────────────────────────────
+
+/**
+ * Assemble all configuration needed to create an agent session.
+ *
+ * Synchronous and side-effect-free (beyond calling `preloadSkills` which reads
+ * the filesystem). The caller is responsible for resolving `EnvInfo` beforehand
+ * via `detectEnv()`.
+ *
+ * @param type       The subagent type name (case-insensitive registry lookup).
+ * @param ctx        Narrow context from the parent session.
+ * @param options    Per-call overrides (cwd, isolated, model, thinkingLevel).
+ * @param env        Pre-resolved environment info from `detectEnv()`.
+ */
+export function assembleSessionConfig(
+  type: SubagentType,
+  ctx: AssemblerContext,
+  options: AssemblerOptions,
+  env: EnvInfo,
+): SessionConfig {
+  const agentConfig = resolveAgentConfig(type);
+
+  const effectiveCwd = options.cwd ?? ctx.cwd;
+
+  // Resolve extensions/skills: isolated overrides to false
+  const extensions = options.isolated ? false : agentConfig.extensions;
+  const skills = options.isolated ? false : agentConfig.skills;
+
+  // Build prompt extras (memory, preloaded skills)
+  const extras: PromptExtras = {};
+
+  // Skill preloading: when skills is string[], preload their content into the prompt
+  if (Array.isArray(skills)) {
+    const loaded = preloadSkills(skills, effectiveCwd);
+    if (loaded.length > 0) {
+      extras.skillBlocks = loaded;
+    }
+  }
+
+  let toolNames = getToolNamesForType(type);
+
+  // Persistent memory: detect write capability and branch accordingly.
+  // Account for disallowedTools — a tool in the base set but on the denylist
+  // is not truly available.
+  if (agentConfig.memory) {
+    const existingNames = new Set(toolNames);
+    const denied = agentConfig.disallowedTools
+      ? new Set(agentConfig.disallowedTools)
+      : undefined;
+    const effectivelyHas = (name: string) =>
+      existingNames.has(name) && !denied?.has(name);
+    const hasWriteTools = effectivelyHas("write") || effectivelyHas("edit");
+
+    if (hasWriteTools) {
+      const extraNames = getMemoryToolNames(existingNames);
+      if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
+      extras.memoryBlock = buildMemoryBlock(
+        agentConfig.name,
+        agentConfig.memory,
+        effectiveCwd,
+      );
+    } else {
+      const extraNames = getReadOnlyMemoryToolNames(existingNames);
+      if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
+      extras.memoryBlock = buildReadOnlyMemoryBlock(
+        agentConfig.name,
+        agentConfig.memory,
+        effectiveCwd,
+      );
+    }
+  }
+
+  // Build system prompt from the resolved agent config
+  const systemPrompt = buildAgentPrompt(
+    agentConfig,
+    effectiveCwd,
+    env,
+    ctx.parentSystemPrompt,
+    extras,
+  );
+
+  // noSkills: when we've already preloaded skills into the prompt, or skills = false,
+  // tell the resource loader not to load them again.
+  const noSkills = skills === false || Array.isArray(skills);
+
+  // Disallowed tools set (for filterActiveTools in runAgent)
+  const disallowedSet = agentConfig.disallowedTools
+    ? new Set(agentConfig.disallowedTools)
+    : undefined;
+
+  // Model resolution: explicit option > config model string > parent model
+  const model =
+    options.model ??
+    resolveDefaultModel(ctx.parentModel, ctx.modelRegistry, agentConfig.model);
+
+  // Thinking level: explicit option > agent config > undefined (inherit)
+  const thinkingLevel = options.thinkingLevel ?? agentConfig.thinking;
+
+  // Per-agent max turns (combined with options.maxTurns and defaultMaxTurns by runAgent)
+  const agentMaxTurns = agentConfig.maxTurns;
+
+  return {
+    effectiveCwd,
+    systemPrompt,
+    toolNames,
+    disallowedSet,
+    extensions,
+    model,
+    thinkingLevel,
+    noSkills,
+    extras,
+    agentMaxTurns,
+  };
+}

package/src/tools/agent-tool.ts

@@ -1,7 +1,7 @@
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { normalizeMaxTurns } from "../agent-runner.js";
-import { getAgentConfig, resolveType } from "../agent-types.js";
+import { resolveAgentConfig, resolveType } from "../agent-types.js";
 import { resolveAgentInvocationConfig } from "../invocation-config.js";
 import { resolveInvocationModel } from "../model-resolver.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "../output-file.js";
@@ -370,8 +370,8 @@ Guidelines:
 
       const displayName = getDisplayName(subagentType);
 
-      // Get agent config (if any)
-      const customConfig = getAgentConfig(subagentType);
+      // Get agent config for invocation resolution
+      const customConfig = resolveAgentConfig(subagentType);
 
       const resolvedConfig = resolveAgentInvocationConfig(customConfig, params);
 

package/src/ui/agent-menu.ts

@@ -3,8 +3,9 @@ import { join } from "node:path";
 
 import {
   BUILTIN_TOOL_NAMES,
-  getAgentConfig,
   getAllTypes,
+  resolveAgentConfig,
+  resolveType,
 } from "../agent-types.js";
 import type { AgentConfig, AgentRecord } from "../types.js";
 import type { AgentActivity } from "./agent-widget.js";
@@ -152,21 +153,21 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     };
 
     const entries = allNames.map((name) => {
-      const cfg = getAgentConfig(name);
-      const disabled = cfg?.enabled === false;
+      const cfg = resolveAgentConfig(name);
+      const disabled = cfg.enabled === false;
       const model = deps.getModelLabel(name, ctx.modelRegistry);
       const indicator = sourceIndicator(cfg);
       const prefix = `${indicator}${name} · ${model}`;
-      const desc = disabled ? "(disabled)" : (cfg?.description ?? name);
+      const desc = disabled ? "(disabled)" : cfg.description;
       return { name, prefix, desc };
     });
     const maxPrefix = Math.max(...entries.map((e) => e.prefix.length));
 
     const hasCustom = allNames.some((n) => {
-      const c = getAgentConfig(n);
-      return c && !c.isDefault && c.enabled !== false;
+      const c = resolveAgentConfig(n);
+      return !c.isDefault && c.enabled !== false;
     });
-    const hasDisabled = allNames.some((n) => getAgentConfig(n)?.enabled === false);
+    const hasDisabled = allNames.some((n) => resolveAgentConfig(n).enabled === false);
     const legendParts: string[] = [];
     if (hasCustom) legendParts.push("• = project  ◦ = global");
     if (hasDisabled) legendParts.push("✕ = disabled");
@@ -184,7 +185,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
       .split(" · ")[0]
       .replace(/^[•◦✕\s]+/, "")
       .trim();
-    if (getAgentConfig(agentName)) {
+    if (resolveType(agentName) != null) {
       await showAgentDetail(ctx, agentName);
       await showAllAgentsList(ctx);
     }
@@ -245,11 +246,11 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
   }
 
   async function showAgentDetail(ctx: MenuContext, name: string) {
-    const cfg = getAgentConfig(name);
-    if (!cfg) {
+    if (resolveType(name) == null) {
       ctx.ui.notify(`Agent config not found for "${name}".`, "warning");
       return;
     }
+    const cfg = resolveAgentConfig(name);
 
     const file = findAgentFile(name);
     const isDefault = cfg.isDefault === true;

package/src/ui/agent-widget.ts

@@ -7,7 +7,7 @@
 
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { AgentManager } from "../agent-manager.js";
-import { getConfig } from "../agent-types.js";
+import { resolveAgentConfig } from "../agent-types.js";
 import type { AgentInvocation, SubagentType } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent, type LifetimeUsage, type SessionLike } from "../usage.js";
 
@@ -144,12 +144,13 @@ export function formatDuration(startedAt: number, completedAt?: number): string
 
 /** Get display name for any agent type (built-in or custom). */
 export function getDisplayName(type: SubagentType): string {
-  return getConfig(type).displayName;
+  const config = resolveAgentConfig(type);
+  return config.displayName ?? config.name;
 }
 
 /** Short label for prompt mode: "twin" for append, nothing for replace (the default). */
 export function getPromptModeLabel(type: SubagentType): string | undefined {
-  const config = getConfig(type);
+  const config = resolveAgentConfig(type);
   return config.promptMode === "append" ? "twin" : undefined;
 }