@yandy0725/pi-subagents 0.1.0

package/src/session/prompts.ts

@@ -0,0 +1,83 @@
+/**
+ * prompts.ts — System prompt builder for agents.
+ */
+
+import type { EnvInfo } from "../session/env";
+import type { AgentPromptConfig } from "../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. `@yandy0725/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/src/session/session-config.ts

@@ -0,0 +1,172 @@
+/**
+ * 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 "../config/agent-types";
+import type { EnvInfo } from "../session/env";
+import type { AgentPromptConfig, SubagentType, ThinkingLevel } from "../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/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/src/settings.ts

@@ -0,0 +1,227 @@
+// 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 "./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" };
+}