@gotgenes/pi-subagents 5.1.0 → 5.3.0

package/src/session-config.ts

@@ -0,0 +1,263 @@
+/**
+ * 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 {
+  getAgentConfig,
+  getConfig,
+  getMemoryToolNames,
+  getReadOnlyMemoryToolNames,
+  getToolNamesForType,
+} from "./agent-types.js";
+import { DEFAULT_AGENTS } from "./default-agents.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 config = getConfig(type);
+  const agentConfig = getAgentConfig(type);
+
+  const effectiveCwd = options.cwd ?? ctx.cwd;
+
+  // Resolve extensions/skills: isolated overrides to false
+  const extensions = options.isolated ? false : config.extensions;
+  const skills = options.isolated ? false : config.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 agent config (or general-purpose fallback for unknown types)
+  let systemPrompt: string;
+  if (agentConfig) {
+    systemPrompt = buildAgentPrompt(
+      agentConfig,
+      effectiveCwd,
+      env,
+      ctx.parentSystemPrompt,
+      extras,
+    );
+  } else {
+    // Unknown type fallback: spread the canonical general-purpose config (defensive —
+    // unreachable in practice since index.ts resolves unknown types before calling runAgent).
+    const fallback = DEFAULT_AGENTS.get("general-purpose");
+    if (!fallback) {
+      throw new Error(`No fallback config available for unknown type "${type}"`);
+    }
+    systemPrompt = buildAgentPrompt(
+      { ...fallback, name: type },
+      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,6 +1,6 @@
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
-import { getDefaultMaxTurns, normalizeMaxTurns } from "../agent-runner.js";
+import { normalizeMaxTurns } from "../agent-runner.js";
 import { getAgentConfig, resolveType } from "../agent-types.js";
 import { resolveAgentInvocationConfig } from "../invocation-config.js";
 import { resolveInvocationModel } from "../model-resolver.js";
@@ -146,6 +146,8 @@ export interface AgentToolDeps {
   typeListText: string;
   availableTypesText: string;
   agentDir: string;
+  /** Returns the runtime default max turns (undefined = unlimited). */
+  getDefaultMaxTurns: () => number | undefined;
 }
 
 // ---- Factory ----
@@ -396,7 +398,7 @@ Guidelines:
           ? (model?.name ?? effectiveModelId).replace(/^Claude\s+/i, "").toLowerCase()
           : undefined;
       const effectiveMaxTurns = normalizeMaxTurns(
-        resolvedConfig.maxTurns ?? getDefaultMaxTurns(),
+        resolvedConfig.maxTurns ?? deps.getDefaultMaxTurns(),
       );
       const agentInvocation: AgentInvocation = {
         modelName,

package/src/ui/agent-menu.ts

@@ -1,11 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import {
-  getDefaultMaxTurns,
-  getGraceTurns,
-  setDefaultMaxTurns,
-  setGraceTurns,
-} from "../agent-runner.js";
+
 import {
   BUILTIN_TOOL_NAMES,
   getAgentConfig,
@@ -42,6 +37,14 @@ export interface AgentMenuDeps {
   ) => { message: string; level: string };
   emitEvent: (name: string, data: unknown) => void;
   personalAgentsDir: string;
+  /** Returns the runtime default max turns (undefined = unlimited). */
+  getDefaultMaxTurns: () => number | undefined;
+  /** Returns the runtime grace turns value. */
+  getGraceTurns: () => number;
+  /** Updates the runtime default max turns (undefined = unlimited). */
+  setDefaultMaxTurns: (n: number | undefined) => void;
+  /** Updates the runtime grace turns value (minimum 1). */
+  setGraceTurns: (n: number) => void;
 }
 
 // ---- Narrow UI context types ----
@@ -620,8 +623,8 @@ ${systemPrompt}
   async function showSettings(ctx: MenuContext) {
     const choice = await ctx.ui.select("Settings", [
       `Max concurrency (current: ${deps.manager.getMaxConcurrent()})`,
-      `Default max turns (current: ${getDefaultMaxTurns() ?? "unlimited"})`,
-      `Grace turns (current: ${getGraceTurns()})`,
+      `Default max turns (current: ${deps.getDefaultMaxTurns() ?? "unlimited"})`,
+      `Grace turns (current: ${deps.getGraceTurns()})`,
     ]);
     if (!choice) return;
 
@@ -642,15 +645,15 @@ ${systemPrompt}
     } else if (choice.startsWith("Default max turns")) {
       const val = await ctx.ui.input(
         "Default max turns before wrap-up (0 = unlimited)",
-        String(getDefaultMaxTurns() ?? 0),
+        String(deps.getDefaultMaxTurns() ?? 0),
       );
       if (val) {
         const n = parseInt(val, 10);
         if (n === 0) {
-          setDefaultMaxTurns(undefined);
+          deps.setDefaultMaxTurns(undefined);
           notifyApplied(ctx, "Default max turns set to unlimited");
         } else if (n >= 1) {
-          setDefaultMaxTurns(n);
+          deps.setDefaultMaxTurns(n);
           notifyApplied(ctx, `Default max turns set to ${n}`);
         } else {
           ctx.ui.notify("Must be 0 (unlimited) or a positive integer.", "warning");
@@ -659,12 +662,12 @@ ${systemPrompt}
     } else if (choice.startsWith("Grace turns")) {
       const val = await ctx.ui.input(
         "Grace turns after wrap-up steer",
-        String(getGraceTurns()),
+        String(deps.getGraceTurns()),
       );
       if (val) {
         const n = parseInt(val, 10);
         if (n >= 1) {
-          setGraceTurns(n);
+          deps.setGraceTurns(n);
           notifyApplied(ctx, `Grace turns set to ${n}`);
         } else {
           ctx.ui.notify("Must be a positive integer.", "warning");