@nklisch/pi-enhanced 0.1.0

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/session/prompts.ts

@@ -0,0 +1,92 @@
+/**
+ * prompts.ts — System prompt builder for agents.
+ */
+
+import type { EnvInfo } from "#src/session/env";
+import type { AgentPromptConfig } from "#src/types";
+
+/**
+ * Build the system prompt for an agent from its config.
+ *
+ * Both modes place the shared/stable parent prompt (or `genericBase` when no
+ * parent is available) first so the LLM's KV cache can reuse the inherited
+ * prefix across all subagent invocations.
+ *
+ * - "replace" mode: parent/genericBase + active_agent tag + env header +
+ *   config.systemPrompt.  No `<sub_agent_context>` bridge and no
+ *   `<agent_instructions>` wrapper — the custom prompt has full control and
+ *   the final say.
+ * - "append" mode: parent/genericBase + sub-agent context bridge +
+ *   active_agent tag + env header + config.systemPrompt (wrapped in
+ *   `<agent_instructions>` when non-empty).
+ * - "append" with empty systemPrompt: pure parent clone.
+ *
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so
+ * downstream extensions (e.g. `@gotgenes/pi-permission-system`) can resolve
+ * per-agent policy inside the child session by parsing the system prompt.
+ * The tag follows the cacheable parent prefix in both modes.
+ *
+ * @param parentSystemPrompt  The parent agent's effective system prompt.
+ */
+export function buildAgentPrompt(
+  config: AgentPromptConfig,
+  cwd: string,
+  env: EnvInfo,
+  parentSystemPrompt?: string,
+): string {
+  const activeAgentTag = `<active_agent name="${config.name}"/>\n\n`;
+
+  const envBlock = `# Environment
+Working directory: ${cwd}
+${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
+Platform: ${env.platform}`;
+
+  const identity = parentSystemPrompt ?? genericBase;
+
+  if (config.promptMode === "append") {
+
+    const bridge = `<sub_agent_context>
+You are operating as a sub-agent invoked to handle a specific task.
+- Use the read tool instead of cat/head/tail
+- Use the edit tool instead of sed/awk
+- Use the write tool instead of echo/heredoc
+- Use the find tool instead of bash find/ls for file search
+- Use the grep tool instead of bash grep/rg for content search
+- Make independent tool calls in parallel
+- Use absolute file paths
+- Do not use emojis
+- Be concise but complete
+</sub_agent_context>`;
+
+    const customSection = config.systemPrompt.trim()
+      ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
+      : "";
+
+    // Place shared/stable content first so the LLM's KV cache can reuse the
+    // inherited prefix across all subagent invocations. The parent prompt is
+    // placed verbatim (no wrapper tag) so it forms an identical byte prefix
+    // with the parent session, maximising KV cache hits. The <active_agent>
+    // tag and env block vary per call and are placed after the cached prefix.
+    return (
+      identity +
+      "\n\n" +
+      bridge +
+      "\n\n" +
+      activeAgentTag +
+      envBlock +
+      customSection
+    );
+  }
+
+  // "replace" mode — parent/genericBase prefix first for KV cache reuse, then
+  // the active_agent tag, env block, and the config's full system prompt.
+  // Unlike append mode, no <sub_agent_context> bridge or <agent_instructions>
+  // wrapper is injected — the custom prompt retains full control.
+  return identity + "\n\n" + activeAgentTag + envBlock + "\n\n" + config.systemPrompt;
+}
+
+/** Fallback base prompt when parent system prompt is unavailable (both modes). */
+const genericBase = `# Role
+You are a general-purpose coding agent for complex, multi-step tasks.
+You have full access to read, write, edit files, and execute commands.
+Do what has been asked; nothing more, nothing less.`;

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/session/session-config.ts

@@ -0,0 +1,187 @@
+/**
+ * session-config.ts — Pure configuration assembler for agent sessions.
+ *
+ * `assembleSessionConfig()` is the pure assembly core called by
+ * `createSubagentSession()`. It accepts resolved inputs (agent type, narrow
+ * context, run options, env info) and returns everything the factory 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 type { AgentConfigLookup } from "#src/config/agent-types";
+import type { EnvInfo } from "#src/session/env";
+import type { AgentPromptConfig, SubagentType, ThinkingLevel } from "#src/types";
+
+// ── Public interfaces ────────────────────────────────────────────────────────
+
+/**
+ * IO collaborators injected into `assembleSessionConfig`.
+ *
+ * Bundling the IO-touching (or promptly testable) function into a single
+ * interface keeps the assembler free of direct module imports and makes it
+ * trivially testable without `vi.mock()` — callers inject real implementations
+ * at the edge (`create-subagent-session.ts`) or stubs in tests.
+ */
+export interface AssemblerIO {
+  buildAgentPrompt: (
+    config: AgentPromptConfig,
+    cwd: string,
+    env: EnvInfo,
+    parentPrompt?: string,
+  ) => string;
+}
+
+/**
+ * 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 per-spawn execution fields 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;
+  /** 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 `createSubagentSession()`.
+ * 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 name allowlist for this agent type. */
+  toolNames: 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;
+  /** 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 — all IO is delegated through the `io`
+ * parameter. 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, model, thinkingLevel).
+ * @param env        Pre-resolved environment info from `detectEnv()`.
+ * @param registry   Agent config lookup — provides resolveAgentConfig and getToolNamesForType.
+ * @param io         IO collaborators (skill loader, memory builder, prompt builder).
+ */
+export function assembleSessionConfig(
+  type: SubagentType,
+  ctx: AssemblerContext,
+  options: AssemblerOptions,
+  env: EnvInfo,
+  registry: AgentConfigLookup,
+  io: AssemblerIO,
+): SessionConfig {
+  const agentConfig = registry.resolveAgentConfig(type);
+
+  const effectiveCwd = options.cwd ?? ctx.cwd;
+
+  const toolNames = registry.getToolNamesForType(type);
+
+  // Build system prompt from the resolved agent config
+  const systemPrompt = io.buildAgentPrompt(
+    agentConfig,
+    effectiveCwd,
+    env,
+    ctx.parentSystemPrompt,
+  );
+
+  // 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 per-call maxTurns and defaultMaxTurns by SubagentSession.runTurnLoop)
+  const agentMaxTurns = agentConfig.maxTurns;
+
+  return {
+    effectiveCwd,
+    systemPrompt,
+    toolNames,
+    model,
+    thinkingLevel,
+    agentMaxTurns,
+  };
+}

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/session/session-dir.ts

@@ -0,0 +1,38 @@
+/**
+ * session-dir.ts — Pure function for deriving subagent session directories.
+ *
+ * Subagent sessions are nested under the parent session's basename so they are
+ * discoverable via the parent session path without cluttering the main session list.
+ */
+
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+/**
+ * Derive the session directory for a subagent from the parent session file.
+ *
+ * Layout: `<parent-dir>/<parent-basename>/tasks/`
+ *
+ * Example:
+ *   parent: `~/.pi/agent/sessions/--project--/2026-05-20T12-00-00Z_.jsonl`
+ *   result: `~/.pi/agent/sessions/--project--/2026-05-20T12-00-00Z_/tasks`
+ *
+ * Falls back to a temp directory when the parent session is not persisted
+ * (e.g. API/headless mode where the parent uses `SessionManager.inMemory()`).
+ */
+export function deriveSubagentSessionDir(
+  parentSessionFile: string | undefined,
+  cwd: string,
+): string {
+  if (parentSessionFile) {
+    const dir = dirname(parentSessionFile);
+    const base = basename(parentSessionFile, ".jsonl");
+    return join(dir, base, "tasks");
+  }
+
+  // Fallback: use a temp directory keyed by uid and cwd so different
+  // projects don't collide when the parent session is not persisted.
+  const encoded = cwd.replace(/[/\\]/g, "-").replace(/^[A-Za-z]:-/, "").replace(/^-+/, "");
+  const root = join(tmpdir(), `pi-subagents-${process.getuid?.() ?? 0}`);
+  return join(root, encoded, "tasks");
+}

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/settings.ts

@@ -0,0 +1,228 @@
+// Persistence for pi-subagents operational settings.
+// - Global:  ~/.pi/agent/subagents.json (agentDir injected at construction) — manual defaults, never written here
+// - Project: <cwd>/.pi/subagents.json — written by /agents → Settings; overrides global on load
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { type LayeredSettingsSource, loadLayeredSettings } from "#src/layered-settings";
+export interface SubagentsSettings {
+  maxConcurrent?: number;
+  /**
+   * 0 = unlimited — the extension's single source of truth for that convention:
+   * `normalizeMaxTurns()` in turn-limits.ts treats 0 → `undefined`, and the
+   * `/agents` → Settings input prompt explicitly says "0 = unlimited".
+   */
+  defaultMaxTurns?: number;
+  graceTurns?: number;
+}
+
+
+/** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
+export type SettingsEmit = (event: string, payload: unknown) => void;
+
+const DEFAULT_MAX_CONCURRENT = 4;
+const DEFAULT_GRACE_TURNS = 5;
+
+/**
+ * Owns all three in-memory settings values and their load/save/persist cycle.
+ * Replaces the scattered free-function + SettingsAppliers callback pattern.
+ */
+export class SettingsManager {
+  private _defaultMaxTurns: number | undefined = undefined;
+  private _graceTurns: number = DEFAULT_GRACE_TURNS;
+  private _maxConcurrent: number = DEFAULT_MAX_CONCURRENT;
+
+  private readonly emit: SettingsEmit;
+  private readonly cwd: string;
+  private readonly agentDir: string;
+  private readonly onMaxConcurrentChanged: (() => void) | undefined;
+
+  constructor(deps: { emit: SettingsEmit; cwd: string; agentDir: string; onMaxConcurrentChanged?: () => void }) {
+    this.emit = deps.emit;
+    this.cwd = deps.cwd;
+    this.agentDir = deps.agentDir;
+    this.onMaxConcurrentChanged = deps.onMaxConcurrentChanged;
+  }
+
+  // ── defaultMaxTurns: 0 or undefined → unlimited (undefined); else max(1, n) ──
+
+  get defaultMaxTurns(): number | undefined {
+    return this._defaultMaxTurns;
+  }
+
+  set defaultMaxTurns(n: number | undefined) {
+    if (n == null || n === 0) {
+      this._defaultMaxTurns = undefined;
+    } else {
+      this._defaultMaxTurns = Math.max(1, n);
+    }
+  }
+
+  // ── graceTurns: minimum 1 ──
+
+  get graceTurns(): number {
+    return this._graceTurns;
+  }
+
+  set graceTurns(n: number) {
+    this._graceTurns = Math.max(1, n);
+  }
+
+  // ── maxConcurrent: minimum 1 ──
+
+  get maxConcurrent(): number {
+    return this._maxConcurrent;
+  }
+
+  set maxConcurrent(n: number) {
+    this._maxConcurrent = Math.max(1, n);
+  }
+
+  // ── Lifecycle methods ──
+
+  /**
+   * Load merged settings (global + project), apply to in-memory values,
+   * and emit the `subagents:settings_loaded` lifecycle event.
+   * Returns the raw loaded settings object.
+   */
+  load(): SubagentsSettings {
+    const settings = loadSettings(this.agentDir, this.cwd);
+    if (typeof settings.maxConcurrent === "number") this.maxConcurrent = settings.maxConcurrent;
+    if (typeof settings.defaultMaxTurns === "number") this.defaultMaxTurns = settings.defaultMaxTurns;
+    if (typeof settings.graceTurns === "number") this.graceTurns = settings.graceTurns;
+    this.emit("subagents:settings_loaded", { settings });
+    return settings;
+  }
+
+  /**
+   * Snapshot current in-memory values for persistence.
+   * `defaultMaxTurns` uses 0 as the on-disk marker for unlimited (undefined).
+   */
+  snapshot(): { maxConcurrent: number; defaultMaxTurns: number; graceTurns: number } {
+    return {
+      maxConcurrent: this._maxConcurrent,
+      defaultMaxTurns: this._defaultMaxTurns ?? 0,
+      graceTurns: this._graceTurns,
+    };
+  }
+
+  /**
+   * Set maxConcurrent, notify interested parties, persist, and return the toast.
+   * Owns the full consequence chain so callers just say what they want.
+   */
+  applyMaxConcurrent(n: number): { message: string; level: "info" | "warning" } {
+    this.maxConcurrent = n; // setter normalizes: max(1, n)
+    this.onMaxConcurrentChanged?.();
+    return this.saveAndNotify(`Max concurrency set to ${this.maxConcurrent}`);
+  }
+
+  /**
+   * Set defaultMaxTurns, persist, and return the toast.
+   * Pass 0 for unlimited (maps to undefined internally).
+   */
+  applyDefaultMaxTurns(n: number): { message: string; level: "info" | "warning" } {
+    this.defaultMaxTurns = n === 0 ? undefined : n; // setter normalizes further
+    const label = this.defaultMaxTurns == null ? "unlimited" : String(this.defaultMaxTurns);
+    return this.saveAndNotify(`Default max turns set to ${label}`);
+  }
+
+  /**
+   * Set graceTurns, persist, and return the toast.
+   */
+  applyGraceTurns(n: number): { message: string; level: "info" | "warning" } {
+    this.graceTurns = n; // setter normalizes: max(1, n)
+    return this.saveAndNotify(`Grace turns set to ${this.graceTurns}`);
+  }
+
+  /**
+   * Persist the current snapshot, emit `subagents:settings_changed`,
+   * and return the toast the UI should display.
+   */
+  saveAndNotify(successMsg: string): { message: string; level: "info" | "warning" } {
+    const snap = this.snapshot();
+    const persisted = saveSettings(snap, this.cwd);
+    this.emit("subagents:settings_changed", { settings: snap, persisted });
+    return persistToastFor(successMsg, persisted);
+  }
+}
+
+// Sanity ceilings — prevent hand-edited configs from asking for values that
+// make no operational sense (e.g. 1e6 concurrent subagents). Permissive enough
+// that any realistic power-user setting passes through.
+const MAX_CONCURRENT_CEILING = 1024;
+const MAX_TURNS_CEILING = 10_000;
+const GRACE_TURNS_CEILING = 1_000;
+
+/** Drop fields that don't match the expected shape. Silent — garbage becomes absent. */
+function sanitize(raw: unknown): SubagentsSettings {
+  if (!raw || typeof raw !== "object") return {};
+  const r = raw as Record<string, unknown>;
+  const out: SubagentsSettings = {};
+  if (
+    Number.isInteger(r.maxConcurrent) &&
+    (r.maxConcurrent as number) >= 1 &&
+    (r.maxConcurrent as number) <= MAX_CONCURRENT_CEILING
+  ) {
+    out.maxConcurrent = r.maxConcurrent as number;
+  }
+  if (
+    Number.isInteger(r.defaultMaxTurns) &&
+    (r.defaultMaxTurns as number) >= 0 &&
+    (r.defaultMaxTurns as number) <= MAX_TURNS_CEILING
+  ) {
+    out.defaultMaxTurns = r.defaultMaxTurns as number;
+  }
+  if (
+    Number.isInteger(r.graceTurns) &&
+    (r.graceTurns as number) >= 1 &&
+    (r.graceTurns as number) <= GRACE_TURNS_CEILING
+  ) {
+    out.graceTurns = r.graceTurns as number;
+  }
+  return out;
+}
+
+function projectPath(cwd: string): string {
+  return join(cwd, ".pi", "subagents.json");
+}
+
+/** Load merged settings: global provides defaults, project overrides. */
+export function loadSettings(agentDir: string, cwd: string): SubagentsSettings {
+  return loadLayeredSettings({
+    agentDir,
+    cwd,
+    filename: "subagents.json",
+    sanitize,
+    warnLabel: "pi-subagents",
+  } satisfies LayeredSettingsSource<SubagentsSettings>);
+}
+
+/**
+ * Write project-local settings. Global is never touched from code.
+ * Returns `true` on success, `false` if the write (or mkdir) failed so the
+ * caller can surface a warning — persistence isn't fatal but isn't silent.
+ */
+export function saveSettings(s: SubagentsSettings, cwd: string = process.cwd()): boolean {
+  const path = projectPath(cwd);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(s, null, 2), "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Format the user-facing toast for a settings mutation. Pure function —
+ * routes the success/failure of `saveSettings` into the right message + level
+ * so the UI layer (index.ts) stays a thin wire between input and notification.
+ */
+export function persistToastFor(
+  successMsg: string,
+  persisted: boolean,
+): { message: string; level: "info" | "warning" } {
+  return persisted
+    ? { message: successMsg, level: "info" }
+    : { message: `${successMsg} (session only; failed to persist)`, level: "warning" };
+}