@jopqior/pi-subagents 1.0.0

package/src/session/conversation.ts

@@ -0,0 +1,49 @@
+/**
+ * conversation.ts — Render a subagent session's messages as formatted text.
+ *
+ * Extracted from agent-runner.ts (issue #265) into the session domain, where the
+ * other message-extraction helpers (content-items, context) live. Consumed by
+ * the get_subagent_result tool's verbose output.
+ */
+
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { extractAssistantContent } from "#src/session/content-items";
+import { extractText } from "#src/session/context";
+
+/**
+ * Get the subagent's conversation messages as formatted text.
+ */
+export function getAgentConversation(session: AgentSession): string {
+  const parts: string[] = [];
+
+  for (const msg of session.messages) {
+    if (msg.role === "user") {
+      const text =
+        typeof msg.content === "string"
+          ? msg.content
+          : extractText(msg.content);
+      if (text.trim()) parts.push(`[User]: ${text.trim()}`);
+    } else if (msg.role === "assistant") {
+      const { textParts, toolNames } = extractAssistantContent(msg.content);
+      const attribution = formatAttribution(msg);
+      if (textParts.length > 0)
+        parts.push(`[Assistant${attribution}]: ${textParts.join("\n")}`);
+      if (toolNames.length > 0)
+        parts.push(`[Tool Calls]:\n${toolNames.map((n) => `  Tool: ${n}`).join("\n")}`);
+    } else if (msg.role === "toolResult") {
+      const text = extractText(msg.content);
+      const truncated = text.length > 200 ? text.slice(0, 200) + "..." : text;
+      parts.push(`[Tool Result (${msg.toolName})]: ${truncated}`);
+    }
+  }
+
+  return parts.join("\n\n");
+}
+
+/** Build a `(provider/model)` attribution suffix for assistant messages. */
+function formatAttribution(msg: { provider?: string; model?: string }): string {
+  const { provider, model } = msg;
+  if (!provider && !model) return "";
+  if (provider && model) return ` (${provider}/${model})`;
+  return ` (${provider ?? model})`;
+}

package/src/session/env.ts

@@ -0,0 +1,40 @@
+/**
+ * env.ts — Detect environment info (git, platform) for subagent system prompts.
+ */
+
+import { debugLog } from "#src/debug";
+import type { ShellExec } from "#src/types";
+
+export interface EnvInfo {
+  isGitRepo: boolean;
+  branch: string;
+  platform: string;
+}
+
+export async function detectEnv(exec: ShellExec, cwd: string): Promise<EnvInfo> {
+  let isGitRepo = false;
+  let branch = "";
+
+  try {
+    const result = await exec("git", ["rev-parse", "--is-inside-work-tree"], { cwd, timeout: 5000 });
+    isGitRepo = result.code === 0 && result.stdout.trim() === "true";
+  } catch (err) {
+    debugLog("git rev-parse", err);
+  }
+
+  if (isGitRepo) {
+    try {
+      const result = await exec("git", ["branch", "--show-current"], { cwd, timeout: 5000 });
+      branch = result.code === 0 ? result.stdout.trim() : "unknown";
+    } catch (err) {
+      debugLog("git branch", err);
+      branch = "unknown";
+    }
+  }
+
+  return {
+    isGitRepo,
+    branch,
+    platform: process.platform,
+  };
+}

package/src/session/model-resolver.ts

@@ -0,0 +1,126 @@
+/**
+ * Model resolution: exact match ("provider/modelId") with fuzzy fallback.
+ */
+import type { Model } from "@earendil-works/pi-ai";
+
+export interface ModelRegistry {
+  find(provider: string, modelId: string): Model<any> | undefined;
+  getAll(): Model<any>[];
+  getAvailable?(): Model<any>[];
+}
+
+/** Successful model resolution — `model` is the resolved or inherited model instance. */
+export interface ModelResolutionResult {
+  model: Model<any> | undefined;
+  error?: undefined;
+}
+
+/** Failed model resolution when the model was user-specified (params) — surface the error. */
+export interface ModelResolutionError {
+  model?: undefined;
+  error: string;
+}
+
+/** Discriminated union returned by `resolveInvocationModel`. */
+export type ModelResolution = ModelResolutionResult | ModelResolutionError;
+
+/**
+ * Resolve the effective model for an agent invocation.
+ *
+ * Encapsulates the three-branch fallback policy used in `Agent.execute`:
+ * 1. No `modelInput` → inherit `parentModel`.
+ * 2. `modelInput` resolves → return the resolved model.
+ * 3. `modelInput` fails:
+ *    - `modelFromParams` true  → return `{ error }` so the caller can surface it.
+ *    - `modelFromParams` false → silent fallback to `parentModel`.
+ *
+ * `modelFromParams` reports which side supplied the winning string, not merely whether
+ * the caller passed one — a caller whose value an agent's `locked:` frontmatter discarded
+ * did not win, so its typo is not the string being resolved here.
+ */
+export function resolveInvocationModel(
+  parentModel: Model<any> | undefined,
+  modelInput: string | undefined,
+  modelFromParams: boolean,
+  registry: ModelRegistry | undefined,
+): ModelResolution {
+  if (!modelInput) return { model: parentModel };
+  if (!registry) return { error: "No model registry available." };
+  const resolved = resolveModel(modelInput, registry);
+  if (typeof resolved !== "string") return { model: resolved };
+  if (modelFromParams) return { error: resolved };
+  return { model: parentModel };
+}
+
+/**
+ * Resolve a model string to a Model instance.
+ * Tries exact match first ("provider/modelId"), then fuzzy match against all available models.
+ * Returns the Model on success, or an error message string on failure.
+ */
+export function resolveModel(
+  input: string,
+  registry: ModelRegistry,
+): Model<any> | string {
+  // Available models (those with auth configured)
+  const all = registry.getAvailable?.() ?? registry.getAll();
+  const availableSet = new Set(all.map(m => `${m.provider}/${m.id}`.toLowerCase()));
+
+  // 1. Exact match: "provider/modelId" — only if available (has auth)
+  const slashIdx = input.indexOf("/");
+  if (slashIdx !== -1) {
+    const provider = input.slice(0, slashIdx);
+    const modelId = input.slice(slashIdx + 1);
+    if (availableSet.has(input.toLowerCase())) {
+      const found = registry.find(provider, modelId);
+      if (found) return found;
+    }
+  }
+
+  // 2. Fuzzy match against available models
+  const bestMatch = findBestFuzzyMatch(all, input.toLowerCase());
+  if (bestMatch) {
+    const found = registry.find(bestMatch.provider, bestMatch.id);
+    if (found) return found;
+  }
+
+  // 3. No match — list available models
+  const modelList = all
+    .map(m => `  ${m.provider}/${m.id}`)
+    .sort()
+    .join("\n");
+  return `Model not found: "${input}".\n\nAvailable models:\n${modelList}`;
+}
+
+/**
+ * Score each candidate model — prefer exact id match > id contains > name
+ * contains > provider+id contains — and return the best match at or above
+ * the acceptance threshold (20), or undefined if nothing scores high enough.
+ */
+function findBestFuzzyMatch(all: Model<any>[], query: string): Model<any> | undefined {
+  let bestMatch: Model<any> | undefined;
+  let bestScore = 0;
+
+  for (const m of all) {
+    const id = m.id.toLowerCase();
+    const name = m.name.toLowerCase();
+    const full = `${m.provider}/${m.id}`.toLowerCase();
+
+    let score = 0;
+    if (id === query || full === query) {
+      score = 100; // exact
+    } else if (id.includes(query) || full.includes(query)) {
+      score = 60 + (query.length / id.length) * 30; // substring, prefer tighter matches
+    } else if (name.includes(query)) {
+      score = 40 + (query.length / name.length) * 20;
+    } else if (query.split(/[\s\-/]+/).every(part => id.includes(part) || name.includes(part) || m.provider.toLowerCase().includes(part))) {
+      score = 20; // all parts present somewhere
+    }
+
+    if (score > bestScore) {
+      bestScore = score;
+      bestMatch = m;
+    }
+  }
+
+  return bestScore >= 20 ? bestMatch : undefined;
+}

package/src/session/notify-parent-tool.ts

@@ -0,0 +1,83 @@
+/**
+ * notify-parent-tool.ts — The tool a child sends its delegating agent a one-way
+ * update with.
+ *
+ * A running child that discovers something material — a course change, a wrong
+ * premise, a scope problem — says so without abandoning its run. The call
+ * returns at once; the parent may reply by steering, which the child picks up
+ * at its next turn boundary.
+ *
+ * Supplied to every child, gated only on the `midRunUpdates` setting. Where
+ * the message lands is decided per call rather than per child: while a carrier
+ * holds this run's outcome it is blocked awaiting the child, so that carrier
+ * renders the update into its own return instead of an announcement arriving
+ * after it. A child whose parent is free is nudged as it goes.
+ *
+ * Lives in `session/` alongside `ask-parent-tool.ts`, for the same reason.
+ */
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+export const NOTIFY_PARENT_TOOL_NAME = "notify_parent";
+
+/**
+ * The longest update the channel carries.
+ *
+ * Neither carrier can be pulled from again — unlike a result, there is no
+ * `get_subagent_result` that returns the untruncated text — so the cut is made
+ * here, where the child is told about it and can be briefer next time.
+ */
+export const UPDATE_MESSAGE_MAX_LENGTH = 2000;
+
+const RESULT_TEXT =
+	"Update sent to the delegating agent. Continue working; it may steer you if it wants to redirect.";
+
+/** Announces a child's update to its parent. */
+export type UpdateAnnouncer = (message: string) => void;
+
+export class NotifyParentTool {
+	constructor(private readonly announce: UpdateAnnouncer) {}
+
+	execute(
+		_toolCallId: string,
+		params: { message: string },
+		_signal: AbortSignal,
+		_onUpdate: unknown,
+		_ctx: unknown,
+	) {
+		const truncated = params.message.length > UPDATE_MESSAGE_MAX_LENGTH;
+		this.announce(truncated ? params.message.slice(0, UPDATE_MESSAGE_MAX_LENGTH) : params.message);
+		const note = truncated
+			? ` Your message was truncated to ${UPDATE_MESSAGE_MAX_LENGTH} characters; keep the next one shorter.`
+			: "";
+		// `details` is required by the SDK's result type; this tool renders none.
+		return { content: [{ type: "text" as const, text: RESULT_TEXT + note }], details: undefined };
+	}
+
+	toToolDefinition() {
+		return defineTool({
+			name: NOTIFY_PARENT_TOOL_NAME,
+			label: "Notify Parent",
+			promptSnippet: "Send the delegating agent a one-way update without pausing.",
+			description:
+				"Send a one-way update to the agent that delegated this task and keep working. Use it only " +
+				"for a material finding that changes what the delegating agent would do — a course change, a " +
+				"wrong premise, a scope problem — not for routine progress. It does not wait for a reply; the " +
+				"delegating agent may steer you if it wants to redirect.",
+			parameters: Type.Object({
+				message: Type.String({
+					description: "The finding the delegating agent should know about now rather than at the end.",
+				}),
+			}),
+			// The tool's own work is synchronous; the SDK's execute contract is not.
+			execute: (
+				toolCallId: string,
+				params: { message: string },
+				signal: AbortSignal,
+				onUpdate: unknown,
+				ctx: unknown,
+			) => Promise.resolve(this.execute(toolCallId, params, signal, onUpdate, ctx)),
+		});
+	}
+}

package/src/session/package-exclusions.ts

@@ -0,0 +1,75 @@
+/**
+ * package-exclusions.ts — build a child-local view of Pi's package settings
+ * that disables selected packages' extensions (issue #696).
+ *
+ * Pi resolves a child session's resources from `Settings.packages`. An entry in
+ * object form with `extensions: []` loads none of that package's extensions in
+ * both of Pi's filter modes — the default mode treats the empty array as an
+ * explicit disable, and `autoload: false` delta mode starts empty and only adds
+ * explicitly listed patterns. Filtering here, at resolution time, means the
+ * excluded package's extension module is never imported and its factory never
+ * runs, which is what makes this a prevent-load seam rather than a deny-at-use
+ * one. The package's skills, prompts, and themes are untouched.
+ */
+
+import type { PackageSource, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+/** Pi does not export `Settings` from its package root; derive it from the accessor. */
+type PiSettings = ReturnType<SettingsManager["getGlobalSettings"]>;
+
+/** Pi does not export `SettingsStorage` either; derive it from the public factory. */
+type PiSettingsStorage = Parameters<typeof SettingsManager.fromStorage>[0];
+
+/** The parent-settings reads a child view needs — narrower than `SettingsManager`. */
+export interface ParentSettingsView {
+  getGlobalSettings(): PiSettings;
+  getProjectSettings(): PiSettings;
+}
+
+/**
+ * A storage backend that serves the parent's settings with the excluded
+ * packages' extensions disabled, for `SettingsManager.fromStorage`.
+ *
+ * Reads pass through to `parent` on every load, so a `reload()` reflects the
+ * parent's current values rather than a construction-time snapshot.
+ *
+ * Writes are discarded deliberately. `withLock` persists whatever its callback
+ * returns, and the callback here is handed synthesized `extensions: []` entries;
+ * forwarding that write would disable those packages in the user's real
+ * settings file, for the parent and every future session.
+ */
+export function createExcludedPackagesStorage(
+  parent: ParentSettingsView,
+  excluded: ReadonlySet<string>,
+): PiSettingsStorage {
+  return {
+    withLock(scope, fn) {
+      const settings = scope === "global" ? parent.getGlobalSettings() : parent.getProjectSettings();
+      fn(JSON.stringify(withPackageExtensionsDisabled(settings, excluded)));
+    },
+  };
+}
+
+/**
+ * Return `settings` with every excluded package's `extensions` filter emptied.
+ * Non-matched entries are returned by identity and the input is never mutated.
+ */
+export function withPackageExtensionsDisabled(
+  settings: PiSettings,
+  excluded: ReadonlySet<string>,
+): PiSettings {
+  if (!settings.packages || excluded.size === 0) return settings;
+  return {
+    ...settings,
+    packages: settings.packages.map((pkg) => disableExtensionsIfExcluded(pkg, excluded)),
+  };
+}
+
+function disableExtensionsIfExcluded(
+  pkg: PackageSource,
+  excluded: ReadonlySet<string>,
+): PackageSource {
+  const source = typeof pkg === "string" ? pkg : pkg.source;
+  if (!excluded.has(source)) return pkg;
+  return typeof pkg === "string" ? { source, extensions: [] } : { ...pkg, extensions: [] };
+}

package/src/session/prompts.ts

@@ -0,0 +1,231 @@
+/**
+ * prompts.ts — System prompt builder for agents.
+ */
+
+import type { EnvInfo } from "#src/session/env";
+import type { AgentPromptConfig, PromptInheritance } from "#src/types";
+
+/** The parent session's contribution to a child prompt, plus the cwd that text claims. */
+export interface InheritedPrompt {
+  /** The parent agent's effective system prompt. */
+  systemPrompt: string;
+  /** The parent's working directory — the cwd its prompt footer names. */
+  cwd: string;
+  /**
+   * Which of the parent's contributions the child adopts as its identity.
+   * Absent means `"full"`, the strategy every provider gets unless its
+   * operator has said otherwise.
+   */
+  strategy?: PromptInheritance;
+  /**
+   * The parent's operator-authored parts, for a `"portable"` child. May be
+   * absent even then — the parent may have assembled no prompt yet, or have no
+   * such parts.
+   */
+  portablePrompt?: string;
+}
+
+/**
+ * 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 inherited identity is a leading prefix the
+ * child shares with its parent across all subagent invocations. What that is
+ * worth is host-dependent — see ADR 0008.
+ *
+ * - "replace" mode: parent/genericBase + active_agent tag + env header +
+ *   config.systemPrompt.  No `<agent_instructions>` wrapper — the custom
+ *   prompt has full control and the final say.
+ * - "append" mode: parent/genericBase + active_agent tag + env header +
+ *   config.systemPrompt (wrapped in `<agent_instructions>` when non-empty).
+ * - "append" with empty systemPrompt: pure parent clone.
+ *
+ * The two modes now differ only in the `<agent_instructions>` wrapper. The
+ * `<sub_agent_context>` bridge append mode used to carry was removed in #890:
+ * its tool bullets duplicated the `promptGuidelines` Pi's own tools contribute
+ * to every child's prompt, and it asserted them unconditionally — telling a
+ * read-only child to use `edit` and `write` when it has neither.
+ *
+ * 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.
+ *
+ * Only the parent prompt's identity is inherited — see `inheritedIdentity`.
+ *
+ * @param inherited  The parent agent's effective system prompt and the cwd it names.
+ */
+export function buildAgentPrompt(
+  config: AgentPromptConfig,
+  cwd: string,
+  env: EnvInfo,
+  inherited?: InheritedPrompt,
+): string {
+  const header = buildPromptHeader(config.name, cwd, env);
+
+  const identity = inherited ? adoptedIdentity(inherited) : genericBase;
+
+  if (config.promptMode === "append") {
+    const customSection = config.systemPrompt.trim()
+      ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
+      : "";
+
+    // Place the inherited identity first so it forms a shared leading prefix
+    // with the parent session, which prefix-reusing inference engines reuse
+    // instead of reprocessing. The <active_agent> tag and env block vary per
+    // call and are placed after that prefix.
+    return identity + "\n\n" + header + customSection;
+  }
+
+  // "replace" mode — identity prefix first, then the active_agent tag, env
+  // block, and the config's full system prompt. Unlike append mode, no
+  // <agent_instructions> wrapper is injected — the custom prompt retains full
+  // control.
+  return identity + "\n\n" + header + "\n\n" + config.systemPrompt;
+}
+
+/**
+ * The parent contribution the child adopts, per the strategy its provider set.
+ *
+ * `full` takes the assembled prompt's identity region, which stays a leading
+ * prefix shared with the parent (ADR 0008). `portable` takes the parent's
+ * operator-authored parts instead, for a provider that re-homes the prompt into
+ * a harness supplying its own base (ADR 0009).
+ *
+ * An absent or whitespace-only portable capture falls back to the generic base,
+ * never to the full prompt: opting into portable must never silently re-embed
+ * the harness base it exists to avoid.
+ */
+function adoptedIdentity(inherited: InheritedPrompt): string {
+  if (inherited.strategy !== "portable") {
+    return inheritedIdentity(inherited.systemPrompt, inherited.cwd);
+  }
+  // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- || intentional: a whitespace-only capture must fall back too, which ?? would not do
+  return inherited.portablePrompt?.trim() || genericBase;
+}
+
+/**
+ * The per-call header both prompt modes share: the `<active_agent>` tag and the
+ * environment block. Both vary per invocation, so both sit after the cacheable
+ * identity prefix — and both modes need any content added here, which is why it
+ * has one home rather than being composed at each `return`.
+ */
+function buildPromptHeader(agentName: string, cwd: string, env: EnvInfo): string {
+  const activeAgentTag = `<active_agent name="${agentName}"/>\n\n`;
+
+  const envBlock = `# Environment
+Working directory: ${cwd}
+${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
+Platform: ${env.platform}`;
+
+  return `${activeAgentTag}${envBlock}`;
+}
+
+/** First line of the section Pi writes above the `<available_skills>` catalogue. */
+const SKILLS_SECTION_HEADING =
+  "The following skills provide specialized instructions for specific tasks.";
+
+/** Closing tag of that catalogue. */
+const SKILLS_CATALOGUE_CLOSE = "</available_skills>";
+
+/**
+ * Reduce an inherited prompt to the identity a child may adopt as its own.
+ *
+ * Pi's `buildSystemPrompt` ends every prompt with layers it resolves per
+ * session — the `<available_skills>` catalogue, then a
+ * `Current working directory:` footer — and extensions append further blocks
+ * after those from `before_agent_start`, rebuilt from the base prompt on every
+ * turn. The child's own session rebuilds all of it against the child's
+ * directory, tool set, and extensions, so an inherited copy is a second, stale
+ * claim of each: a catalogue naming skills the child may not have (#801), and
+ * a footer that walks a workspace-isolated child back into the parent's
+ * directory (#640).
+ *
+ * Everything from the first such layer onward is therefore dropped. What
+ * precedes it is returned byte for byte, so it stays a shared prefix with the
+ * parent's prompt for hosts that reuse one over the system text (#180, #400).
+ * That is why no extension may edit the region in place: `Available tools:`
+ * sits a few hundred characters into it, and narrowing it there ended the
+ * shared prefix for every child with a narrowed tool set (#890).
+ *
+ * A prompt carrying neither layer is not one `buildSystemPrompt` assembled, and
+ * is returned unchanged.
+ */
+function inheritedIdentity(prompt: string, parentCwd: string): string {
+  const lines = prompt.split("\n");
+  const tailStart = sessionResolvedTailStart(lines, parentCwd);
+  return tailStart === -1
+    ? prompt
+    : lines.slice(0, tailStart).join("\n").trimEnd();
+}
+
+/**
+ * Line index at which Pi's per-session layers begin, or -1 when none is present.
+ *
+ * The catalogue precedes the footer, so cutting at the catalogue already
+ * removes it; the footer is the anchor only for a parent session that resolved
+ * no skills. Matching whole lines makes the footer match exact, so a footer
+ * naming a directory that merely shares a prefix with the parent's is not
+ * mistaken for it, and it mirrors the separator normalization
+ * `buildSystemPrompt` applies.
+ */
+function sessionResolvedTailStart(
+  lines: readonly string[],
+  parentCwd: string,
+): number {
+  const footerAt = lines.lastIndexOf(
+    `Current working directory: ${toPromptPath(parentCwd)}`,
+  );
+  const catalogueAt = skillsSectionStart(lines, footerAt);
+  return catalogueAt === -1 ? footerAt : catalogueAt;
+}
+
+/**
+ * Line index of the skills section's heading, or -1 when the section is absent.
+ *
+ * The heading is located by searching back from the catalogue's closing tag, so
+ * prose quoting Pi's heading ahead of the section is not mistaken for it.
+ */
+function skillsSectionStart(
+  lines: readonly string[],
+  footerAt: number,
+): number {
+  const catalogueEnd = catalogueCloseBefore(lines, footerAt);
+  return catalogueEnd === -1
+    ? -1
+    : lines.lastIndexOf(SKILLS_SECTION_HEADING, catalogueEnd);
+}
+
+/**
+ * Line index of Pi's own catalogue closing tag, or -1 when it wrote none.
+ *
+ * `buildSystemPrompt` writes the cwd footer immediately after the catalogue, in
+ * both of its branches and unconditionally, so the tag on the line before the
+ * footer is Pi's own. Identifying it by that position rather than by document
+ * order keeps a catalogue quoted elsewhere — in a project-context file, or in a
+ * block an extension appended after the footer — from being taken for the
+ * section, in either direction.
+ *
+ * Without a footer to anchor on, something downstream has rewritten Pi's
+ * output; the last closing tag is the best remaining guess.
+ */
+function catalogueCloseBefore(
+  lines: readonly string[],
+  footerAt: number,
+): number {
+  if (footerAt === -1) {
+    return lines.lastIndexOf(SKILLS_CATALOGUE_CLOSE);
+  }
+  return lines[footerAt - 1] === SKILLS_CATALOGUE_CLOSE ? footerAt - 1 : -1;
+}
+
+/** Render a path the way `buildSystemPrompt` writes it into a prompt. */
+function toPromptPath(cwd: string): string {
+  return cwd.replaceAll("\\", "/");
+}
+
+/** 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/provider-inheritance.ts

@@ -0,0 +1,56 @@
+/**
+ * Provider inheritance — replay a parent session's runtime provider
+ * registrations onto a child session's model runtime.
+ *
+ * Pi builds a fresh ModelRuntime for every session that is not handed one, and
+ * runtime registrations (pi.registerProvider) live on that instance rather than
+ * in models.json or auth.json. A child therefore starts with none of them and
+ * cannot resolve the parent's provider, which surfaces as
+ * "No API key found for <provider>" (Refs #812).
+ *
+ * The collaborators are narrow structural contracts rather than the SDK's
+ * ModelRegistry: the concrete class carries a private field, which would force
+ * test doubles to cast or replicate internals. Provider and config values are
+ * pass-through only — this module never inspects them — so they stay generic,
+ * which also avoids naming SDK types the package entry does not export.
+ */
+
+/** Enumerates the providers registered on a session at runtime. */
+export interface RegisteredProviderSource<TNative, TConfig> {
+  getRegisteredProviderIds(): readonly string[];
+  getRegisteredNativeProvider(id: string): TNative | undefined;
+  getRegisteredProviderConfig(id: string): TConfig | undefined;
+}
+
+/**
+ * Accepts provider registrations on behalf of a session.
+ *
+ * The two forms are separate methods rather than the SDK's single overloaded
+ * `registerProvider`, so a plain `vi.fn()` can stand in for each without a cast.
+ */
+export interface ProviderRegistrar<TNative, TConfig> {
+  registerNative(provider: TNative): void;
+  registerConfigured(id: string, config: TConfig): void;
+}
+
+/**
+ * Copy every runtime-registered provider from `source` onto `target`.
+ *
+ * Pi keeps native and configured registrations in disjoint maps — registering
+ * one form deletes the id from the other — so each id resolves to exactly one
+ * form. An id that resolves to neither is skipped rather than registered empty.
+ */
+export function inheritRegisteredProviders<TNative, TConfig>(
+  source: RegisteredProviderSource<TNative, TConfig>,
+  target: ProviderRegistrar<TNative, TConfig>,
+): void {
+  for (const id of source.getRegisteredProviderIds()) {
+    const native = source.getRegisteredNativeProvider(id);
+    if (native !== undefined) {
+      target.registerNative(native);
+      continue;
+    }
+    const config = source.getRegisteredProviderConfig(id);
+    if (config !== undefined) target.registerConfigured(id, config);
+  }
+}