@yefengr/pi-subagents 0.0.0-stage → 0.1.0

package/src/session/model-resolver.ts

@@ -0,0 +1,135 @@
+/**
+ * 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 resolution of an explicitly specified model (agent profile or tool parameter). */
+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 fallback policy used in `Agent.execute`:
+ * 1. No `modelInput` (`undefined`) → inherit `parentModel`.
+ * 2. `modelInput` resolves → return the resolved model.
+ * 3. `modelInput` fails → return `{ error }`. A model chosen explicitly (agent profile
+ *    or tool parameter) is never replaced by the parent model; `modelFromParams` only
+ *    labels the error's origin. An explicit empty or all-whitespace value also fails:
+ *    only omission inherits.
+ */
+export function resolveInvocationModel(
+  parentModel: Model<any> | undefined,
+  modelInput: string | undefined,
+  modelFromParams: boolean,
+  registry: ModelRegistry | undefined,
+): ModelResolution {
+  if (modelInput === undefined) return { model: parentModel };
+  if (!registry) return { error: "No model registry available." };
+  const resolved = resolveModel(modelInput, registry);
+  if (typeof resolved !== "string") return { model: resolved };
+  const source = modelFromParams ? "tool parameter" : "agent profile";
+  return { error: `${resolved}\n\nExplicit model from ${source} must resolve; not inheriting the parent model.` };
+}
+
+/**
+ * Resolve a model string to a Model instance.
+ * A qualified "provider/modelId" is an exact pin against available models: it never
+ * falls back to fuzzy matching, so a typo, another provider, or an unauthenticated
+ * model fails instead of silently selecting a sibling. Qualified input is compared
+ * case-insensitively, but the registry lookup uses the matched model's canonical
+ * provider/id. Unqualified input is fuzzy-matched. Empty or all-whitespace input is
+ * invalid rather than a query that matches everything.
+ * 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();
+
+  // 0. Empty or all-whitespace values are invalid explicit models, not fuzzy queries.
+  if (input.trim() === "") return formatNotFound(input, all);
+
+  // 1. Qualified "provider/modelId": exact pin only — no fuzzy fallback
+  const slashIdx = input.indexOf("/");
+  if (slashIdx !== -1) {
+    const matched = all.find(m => `${m.provider}/${m.id}`.toLowerCase() === input.toLowerCase());
+    if (matched) {
+      const found = registry.find(matched.provider, matched.id);
+      if (found) return found;
+    }
+    return formatNotFound(input, all);
+  }
+
+  // 2. Fuzzy match unqualified names 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
+  return formatNotFound(input, all);
+}
+
+/** Build the shared "model not found" message with the available-model list. */
+function formatNotFound(input: string, all: Model<any>[]): string {
+  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/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,145 @@
+/**
+ * prompts.ts — System prompt builder for agents.
+ */
+
+import type { EnvInfo } from "#src/session/env";
+import type { AgentPromptConfig } 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;
+}
+
+/**
+ * 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 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 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 = inherited
+    ? withoutContradictoryCwdFooter(inherited.systemPrompt, inherited.cwd, cwd)
+    : 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;
+}
+
+/**
+ * Remove the parent's `Current working directory:` footer from the prompt the
+ * child inherits, when it names a different directory than the child's.
+ *
+ * Pi's `buildSystemPrompt` ends every prompt with that footer and appends a
+ * fresh one — naming the child session's own cwd — after this string. Left in
+ * place, the inherited line gives a workspace-isolated child (e.g. one placed
+ * in a git worktree by a `WorkspaceProvider`) a second, stale claim in the
+ * exact phrasing Pi uses for the authoritative one, and the child follows it
+ * back into the parent's directory (#640).
+ *
+ * A child sharing the parent's directory inherits a footer that agrees with its
+ * own, so the prompt is returned untouched — keeping the inherited prefix
+ * byte-identical to the parent's for prefix-caching providers. Editing it would
+ * cost shared prefix (the parent's trailing extension-appended blocks shift
+ * offset) to delete an accurate duplicate.
+ *
+ * The match is whole-line, so a footer naming a directory that merely shares a
+ * prefix with the parent's survives, and it mirrors the separator normalization
+ * `buildSystemPrompt` applies. An unmatched prompt is returned unchanged.
+ */
+function withoutContradictoryCwdFooter(
+  prompt: string,
+  parentCwd: string,
+  childCwd: string,
+): string {
+  const inheritedClaim = toPromptPath(parentCwd);
+  if (inheritedClaim === toPromptPath(childCwd)) {
+    return prompt;
+  }
+
+  const footerLine = `Current working directory: ${inheritedClaim}`;
+  return prompt
+    .split("\n")
+    .filter((line) => line !== footerLine)
+    .join("\n");
+}
+
+/** 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,38 @@
+/**
+ * 将父会话运行时注册的 provider 复制到子会话独立的 model runtime。
+ *
+ * Pi 的 provider 注册保存在 ModelRuntime 实例内，不会写入 models.json；
+ * 子会话创建独立 runtime 时必须显式继承，否则自定义 provider 无法工作。
+ */
+
+/** 枚举会话运行时注册的 provider。 */
+export interface RegisteredProviderSource<TNative, TConfig> {
+  getRegisteredProviderIds(): readonly string[];
+  getRegisteredNativeProvider(id: string): TNative | undefined;
+  getRegisteredProviderConfig(id: string): TConfig | undefined;
+}
+
+/** 接收复制后的原生或配置型 provider。 */
+export interface ProviderRegistrar<TNative, TConfig> {
+  registerNative(provider: TNative): void;
+  registerConfigured(id: string, config: TConfig): void;
+}
+
+/**
+ * 按父 registry 的枚举顺序复制全部运行时注册项。
+ * 原生与配置型注册理论上互斥；异常情况下优先保留原生 provider。
+ */
+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);
+  }
+}

package/src/session/session-config.ts

@@ -0,0 +1,177 @@
+/**
+ * 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, 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 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;
+}
+
+// ── 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);
+
+  // Build system prompt from the resolved agent config
+  const systemPrompt = io.buildAgentPrompt(agentConfig, effectiveCwd, env, {
+    systemPrompt: ctx.parentSystemPrompt,
+    cwd: ctx.cwd,
+  });
+
+  // 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;
+
+  return {
+    effectiveCwd,
+    systemPrompt,
+    toolNames,
+    model,
+    thinkingLevel,
+  };
+}

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-subagent-${process.getuid?.() ?? 0}`);
+  return join(root, encoded, "tasks");
+}