@jopqior/pi-subagents 1.0.0

package/src/session/selection-catalogue.ts

@@ -0,0 +1,143 @@
+/**
+ * selection-catalogue.ts — Authenticated choices and validation for per-spawn selection.
+ *
+ * The selection path's own view of the spawning parent's model registry: it
+ * reads only authenticated availability (`getAvailable()`, never a `getAll()`
+ * fallback — a model the session cannot authenticate is not a choice a human
+ * can be offered), snapshots the choices for the duration of one selection,
+ * and validates the provider's answer against that snapshot plus a fresh
+ * availability read before the pair reaches the child factory.
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import { parseThinkingLevel, type SubagentThinkingLevel } from "#src/config/thinking-level";
+import type { SpawnSelection } from "#src/service/service";
+import type { ModelRegistry } from "#src/session/model-resolver";
+
+/** The validated pair a gated run carries into the factory. */
+export interface ValidatedSpawnSelection {
+	/** The catalogue's own model object, canonicalized from the provider's answer. */
+	model: Model<any>;
+	/** A level the selected model supports — mandatory, never defaulted. */
+	thinkingLevel: SubagentThinkingLevel;
+}
+
+/**
+ * Read the authenticated choices for one selection.
+ *
+ * Missing availability support or an empty catalogue is an error, not a
+ * fallback: the ordinary resolver's `getAll()` fallback serves a different
+ * constituency (silent inheritance), and a gated run must not offer models the
+ * session cannot authenticate.
+ */
+export function readSelectionChoices(registry: ModelRegistry): Model<any>[] {
+	const available = registry.getAvailable?.();
+	if (available === undefined) {
+		throw new Error(
+			"The model registry does not expose authenticated availability (getAvailable); a model selection cannot be offered.",
+		);
+	}
+	if (available.length === 0) {
+		throw new Error("No authenticated models are available to select from.");
+	}
+	return available;
+}
+
+/**
+ * Validate the provider's answer for one selection: the model must be in the
+ * snapshot (canonicalized to the catalogue's own object) and still available
+ * now, and the thinking level must be one the selected model supports.
+ *
+ * Anything else — an unknown model, a level the model rejects, an omitted
+ * level, a forged result — rejects rather than clamping or defaulting.
+ */
+export async function validateSpawnSelection(
+	selection: SpawnSelection,
+	choices: readonly Model<any>[],
+	registry: ModelRegistry,
+): Promise<ValidatedSpawnSelection> {
+	const model = canonicalizeModel(selection.model, choices);
+	revalidateAvailability(model, registry);
+	const thinkingLevel = await validateThinkingLevel(selection.thinkingLevel, model);
+	return { model, thinkingLevel };
+}
+
+/** The signature of pi-ai's supported-level helper, feature-detected at use. */
+type SupportedLevelsHelper = (model: Model<any>) => string[];
+
+/** Memoized feature detection of the supported-level helper on the installed peer. */
+let supportedLevelsLoader: Promise<SupportedLevelsHelper | undefined> | undefined;
+
+/**
+ * Resolve pi-ai's `getSupportedThinkingLevels` through the package namespace.
+ *
+ * The core's peer floor predates the helper, so an unconditional named import
+ * would be unavailable on an older supported peer; absence denies only gated
+ * execution (the caller reports an error) and never the ordinary path.
+ */
+function loadSupportedLevelsHelper(): Promise<SupportedLevelsHelper | undefined> {
+	supportedLevelsLoader ??= import("@earendil-works/pi-ai").then((ns) => {
+		const helper = (ns as Record<string, unknown>).getSupportedThinkingLevels;
+		return typeof helper === "function" ? (helper as SupportedLevelsHelper) : undefined;
+	});
+	return supportedLevelsLoader;
+}
+
+/** Canonicalize the answered model to the catalogue entry with that identity. */
+function canonicalizeModel(model: unknown, choices: readonly Model<any>[]): Model<any> {
+	const identity = modelIdentity(model);
+	const found = choices.find(
+		(candidate) => candidate.provider === identity.provider && candidate.id === identity.id,
+	);
+	if (!found) {
+		throw new Error(
+			`Selected model is not in the available catalogue: "${identity.provider}/${identity.id}".`,
+		);
+	}
+	return found;
+}
+
+/** Extract a provider/id identity, rejecting answers that do not name a model. */
+function modelIdentity(model: unknown): { provider: string; id: string } {
+	if (typeof model !== "object" || model === null) {
+		throw new Error("The selection did not name a model.");
+	}
+	const { provider, id } = model as { provider?: unknown; id?: unknown };
+	if (typeof provider !== "string" || typeof id !== "string") {
+		throw new Error("The selection did not name a model.");
+	}
+	return { provider, id };
+}
+
+/** Re-read availability and confirm the chosen model is still one of the choices. */
+function revalidateAvailability(model: Model<any>, registry: ModelRegistry): void {
+	const fresh = registry.getAvailable?.();
+	if (!fresh?.some((candidate) => candidate.provider === model.provider && candidate.id === model.id)) {
+		throw new Error(`Selected model "${model.provider}/${model.id}" is no longer available.`);
+	}
+}
+
+/** Validate the answered level against the vocabulary and the selected model. */
+async function validateThinkingLevel(
+	level: unknown,
+	model: Model<any>,
+): Promise<SubagentThinkingLevel> {
+	const parsed = parseThinkingLevel(level);
+	if (parsed === undefined) {
+		throw new Error(
+			`The selection did not include a valid thinking level: ${typeof level === "string" ? `"${level}"` : String(level)}.`,
+		);
+	}
+	const supported = await loadSupportedLevelsHelper();
+	if (supported === undefined) {
+		throw new Error(
+			"pi-ai's getSupportedThinkingLevels is unavailable on the installed peer; the selected thinking level cannot be validated.",
+		);
+	}
+	if (!supported(model).includes(parsed)) {
+		throw new Error(
+			`Model "${model.provider}/${model.id}" does not support thinking level "${parsed}".`,
+		);
+	}
+	return parsed;
+}

package/src/session/session-config.ts

@@ -0,0 +1,202 @@
+/**
+ * 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 { Model } from "@earendil-works/pi-ai";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { EnvInfo } from "#src/session/env";
+import type { ModelRegistry } from "#src/session/model-resolver";
+import type { InheritedPrompt } from "#src/session/prompts";
+import type {
+  AgentPromptConfig,
+  PromptInheritance,
+  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,
+    inherited?: InheritedPrompt,
+  ) => string;
+}
+
+/**
+ * Narrow context the assembler reads from the parent session.
+ * Tests construct plain objects satisfying this interface — no SDK mocking needed.
+ *
+ * The assembler never inspects model internals, only passes them through;
+ * `resolveDefaultModel` reads `provider`/`id` from `getAvailable()` for the
+ * availability check.
+ */
+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 operator-authored parts, for a child on a re-homing provider. */
+  parentPortablePrompt?: string;
+  /**
+   * Which prompt-inheritance strategy the child's provider calls for.
+   * Absent resolves every child to `"full"`.
+   */
+  resolvePromptInheritance?: (provider: string | undefined) => PromptInheritance;
+  /** Parent's current model instance (fallback when agent config has no model). */
+  parentModel?: Model<any>;
+  /** Model registry for resolving config.model strings. */
+  modelRegistry: ModelRegistry;
+}
+
+/**
+ * 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?: Model<any>;
+  /** 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).
+   * The assembler passes it through without inspection.
+   */
+  model: Model<any> | undefined;
+  /** 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: Model<any> | undefined,
+  registry: AssemblerContext["modelRegistry"],
+  configModel?: string,
+): Model<any> | undefined {
+  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);
+
+  // Model resolution: explicit option > config model string > parent model.
+  // Resolved before the prompt because the child's provider is what selects a
+  // prompt-inheritance strategy; the two computations are otherwise
+  // independent, so the order is free.
+  const model =
+    options.model ??
+    resolveDefaultModel(ctx.parentModel, ctx.modelRegistry, agentConfig.model);
+
+  // Build system prompt from the resolved agent config. The strategy is keyed
+  // on the child's own provider, so a per-spawn model override moves the child
+  // between transports and takes the right strategy with it.
+  const systemPrompt = io.buildAgentPrompt(agentConfig, effectiveCwd, env, {
+    systemPrompt: ctx.parentSystemPrompt,
+    cwd: ctx.cwd,
+    strategy: ctx.resolvePromptInheritance?.(model?.provider) ?? "full",
+    portablePrompt: ctx.parentPortablePrompt,
+  });
+
+  // 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");
+}