@baique/pi-web-sky 0.1.54 → 0.1.56

package/lib/subagent-runtime.ts

@@ -0,0 +1,587 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import {
+  createAgentSessionFromServices,
+  createAgentSessionServices,
+  getAgentDir,
+  initTheme,
+  SessionManager,
+  SettingsManager,
+  type ModelRuntime,
+} from "@earendil-works/pi-coding-agent";
+import type { AgentSessionLike } from "./pi-types";
+import {
+  subagentFinalText,
+  subagentToolDetails,
+  type ResumeSubagentRequest,
+  type StartSubagentRequest,
+  type SubagentExecution,
+  type SubagentExtensionRuntime,
+} from "./subagent-extension";
+import {
+  readSubagentRun,
+  resolveSubagentProfile,
+  SUBAGENT_CONTROL_TOOL_NAMES,
+  SUBAGENT_META_TYPE,
+  SUBAGENT_STATUS_TYPE,
+  SUBAGENT_RESULT_TYPE,
+  selectSubagentExtensionTools,
+  withSubagentExtensionTools,
+  type SubagentMetadata,
+  type SubagentResultMetadata,
+  type SubagentRunInfo,
+} from "./subagents";
+import type { SessionEntry } from "./types";
+import { buildSubagentPromptPlan } from "./subagent-prompt";
+import { appendSubagentInputFiles, loadSubagentInputFiles } from "./subagent-input";
+import { projectTrustReloadOptions } from "./project-trust";
+import { resolveShellTools } from "./powershell-settings";
+import { isBuiltInSubagentsEnabled, readSubagentSettings } from "./subagent-settings";
+import { SubagentQueue } from "./subagent-queue";
+import { addWorktree, removeWorktree } from "./worktree";
+import { randomUUID } from "node:crypto";
+
+interface HostSession {
+  readonly inner: AgentSessionLike;
+  readonly sessionFile: string;
+  readonly cwd: string;
+  isAlive(): boolean;
+  isRunning(): boolean;
+  waitUntilReady(): Promise<void>;
+}
+
+export interface SubagentRuntimeDependencies {
+  getSession(sessionId: string): HostSession | undefined;
+  registerSession(
+    inner: AgentSessionLike,
+    options?: { exactSystemPrompt?: string; chatOnly?: boolean },
+  ): void;
+  reopenSession(sessionId: string, sessionFile: string): Promise<HostSession>;
+  resolveSessionPath(sessionId: string): Promise<string | null>;
+  invalidateSessionList(): void;
+  isBuiltInSubagentsEnabled?(): boolean;
+}
+
+export interface SubagentController {
+  readonly extensionRuntime: SubagentExtensionRuntime;
+  get(sessionId: string): Promise<SubagentRunInfo | null>;
+  steer(sessionId: string, message: string): Promise<void>;
+  abort(sessionId: string): Promise<void>;
+}
+
+type StoredSubagentExecution = {
+  run: SubagentRunInfo;
+  completion: Promise<SubagentRunInfo>;
+  abortRequested: boolean;
+  cancelQueued?: () => boolean;
+};
+
+declare global {
+  var __piSubagentRuns: Map<string, StoredSubagentExecution> | undefined;
+  var __piSubagentQueue: SubagentQueue<SubagentRunInfo> | undefined;
+}
+const SUBAGENT_CONTEXT_LIMIT = 50_000;
+const THINKING_LEVELS = new Set<ThinkingLevel>(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+
+function getSubagentRuns(): Map<string, StoredSubagentExecution> {
+  if (!globalThis.__piSubagentRuns) globalThis.__piSubagentRuns = new Map();
+  return globalThis.__piSubagentRuns;
+}
+
+function getSubagentQueue(): SubagentQueue<SubagentRunInfo> {
+  if (!globalThis.__piSubagentQueue) globalThis.__piSubagentQueue = new SubagentQueue();
+  return globalThis.__piSubagentQueue;
+}
+
+function parseSubagentModel(runtime: ModelRuntime, value: string | undefined) {
+  if (!value?.trim()) return undefined;
+  const requested = value.trim();
+  const slash = requested.indexOf("/");
+  if (slash > 0) {
+    const provider = requested.slice(0, slash);
+    const modelId = requested.slice(slash + 1);
+    const model = runtime.getModel(provider, modelId);
+    if (!model) throw new Error(`Subagent model not found: ${requested}`);
+    return model;
+  }
+  const matches = runtime.getModels().filter((model) => model.id === requested);
+  if (matches.length === 1) return matches[0];
+  if (matches.length === 0) throw new Error(`Subagent model not found: ${requested}`);
+  throw new Error(`Subagent model is ambiguous; use provider/modelId: ${requested}`);
+}
+
+function parentContextText(parent: HostSession): string {
+  const messages = parent.inner.sessionManager.buildSessionContext().messages;
+  const serialized = JSON.stringify(messages);
+  if (serialized.length <= SUBAGENT_CONTEXT_LIMIT) return serialized;
+  return `${serialized.slice(0, SUBAGENT_CONTEXT_LIMIT)}\n[Parent context truncated]`;
+}
+
+async function cleanupWorktree(
+  parentCwd: string,
+  worktree: { path: string; branch: string } | undefined,
+): Promise<string | undefined> {
+  if (!worktree) return undefined;
+  try {
+    await removeWorktree(parentCwd, worktree.path);
+    return undefined;
+  } catch (error) {
+    return `Worktree retained at ${worktree.path}: ${error instanceof Error ? error.message : String(error)}`;
+  }
+}
+
+export function createSubagentController(
+  dependencies: SubagentRuntimeDependencies,
+): SubagentController {
+  async function start(request: StartSubagentRequest): Promise<SubagentExecution> {
+    const enabled = dependencies.isBuiltInSubagentsEnabled ?? isBuiltInSubagentsEnabled;
+    if (!enabled()) throw new Error("Pi Web built-in sub-agents are disabled");
+    const parentSessionId = request.parentContext.sessionManager.getSessionId();
+    const parent = dependencies.getSession(parentSessionId);
+    if (!parent?.isAlive()) throw new Error("Parent session is no longer available");
+    if (!parent.sessionFile) throw new Error("Parent session must be persisted before starting a subagent");
+
+    let isolatedWorktree: { path: string; branch: string } | undefined;
+    try {
+      const profile = resolveSubagentProfile(parent.cwd, request.profile);
+      if (!profile) throw new Error(`Unknown or disabled subagent profile: ${request.profile}`);
+
+      const runInBackground = request.runInBackground ?? profile.runInBackground;
+      const isolation = profile.isolation === "off" ? undefined : request.isolation ?? profile.isolation;
+      if (isolation === "worktree") {
+        isolatedWorktree = await addWorktree(parent.cwd, `pi-web-agent-${randomUUID()}`);
+      }
+      const childCwd = isolatedWorktree?.path ?? parent.cwd;
+      const inheritContext = request.inheritContext ?? profile.inheritContext;
+      const maxTurns = request.maxTurns ?? profile.maxTurns;
+      if (maxTurns !== undefined && (!Number.isFinite(maxTurns) || maxTurns < 0)) {
+        throw new Error("max_turns must be a non-negative number");
+      }
+      const turnLimit = maxTurns && maxTurns > 0 ? Math.floor(maxTurns) : undefined;
+      const thinking = request.thinking ?? profile.thinking ?? parent.inner.agent.state?.thinkingLevel;
+      if (thinking && !THINKING_LEVELS.has(thinking as ThinkingLevel)) {
+        throw new Error(`Invalid subagent thinking level: ${thinking}`);
+      }
+
+      const agentDir = getAgentDir();
+      const parentModelRuntime = (parent.inner as unknown as { modelRuntime: ModelRuntime }).modelRuntime;
+      const settingsManager = SettingsManager.create(childCwd, agentDir);
+      const inheritedParentContext = inheritContext
+        ? `The following is the active conversation context from the parent session. Use it only as background for the delegated task:\n${parentContextText(parent)}`
+        : undefined;
+      const inputFiles = loadSubagentInputFiles(parent.cwd, request.inputFiles ?? []);
+      const promptPlan = buildSubagentPromptPlan({
+        profileSystemPrompt: profile.systemPrompt,
+        tools: profile.tools,
+        loadSkills: profile.loadSkills,
+        loadExtensions: profile.loadExtensions,
+        promptMode: profile.promptMode,
+        task: appendSubagentInputFiles(request.task, inputFiles),
+        inheritedParentContext,
+      });
+      const { chatOnly, appendSystemPrompt, delegatedTask } = promptPlan;
+      if (!chatOnly) initTheme();
+      const services = await createAgentSessionServices({
+        cwd: childCwd,
+        agentDir,
+        modelRuntime: parentModelRuntime,
+        settingsManager,
+        resourceLoaderOptions: {
+          noExtensions: !profile.loadExtensions,
+          noSkills: !profile.loadSkills,
+          noPromptTemplates: true,
+          noThemes: true,
+          noContextFiles: true,
+          ...(chatOnly || promptPlan.exactSystemPrompt !== undefined
+            ? {
+                systemPrompt: " ",
+                systemPromptOverride: () => undefined,
+              }
+            : {}),
+          appendSystemPrompt,
+        },
+        ...((profile.loadExtensions || profile.loadSkills)
+          ? { resourceLoaderReloadOptions: projectTrustReloadOptions(childCwd, agentDir) }
+          : {}),
+      });
+
+      const extensionToolNames = profile.loadExtensions
+        ? profile.extensionTools?.length
+          ? selectSubagentExtensionTools(services.resourceLoader.getExtensions().extensions, profile.extensionTools)
+          : services.resourceLoader.getExtensions().extensions.flatMap((extension) => [...extension.tools.keys()])
+        : [];
+      const activeTools = resolveShellTools(
+        withSubagentExtensionTools(profile.tools, extensionToolNames),
+        settingsManager.getDefaultTools(),
+      );
+
+      const sessionManager = isolatedWorktree
+        ? SessionManager.create(childCwd, undefined, { parentSession: parent.sessionFile })
+        : SessionManager.create(parent.cwd, undefined, { parentSession: parent.sessionFile });
+      const createdAt = new Date().toISOString();
+      const metadata: SubagentMetadata = {
+        version: 1,
+        parentSessionId,
+        parentSessionPath: parent.sessionFile,
+        parentToolCallId: request.parentToolCallId,
+        profile: profile.name,
+        description: request.description.trim() || profile.displayName,
+        task: request.task,
+        runInBackground,
+        createdAt,
+        resourceSnapshot: {
+          version: 1,
+          appendSystemPrompt: [...appendSystemPrompt],
+          tools: [...activeTools],
+          loadSkills: profile.loadSkills,
+        loadExtensions: profile.loadExtensions,
+        ...(promptPlan.exactSystemPrompt !== undefined ? { exactSystemPrompt: promptPlan.exactSystemPrompt } : {}),
+        },
+        ...(isolatedWorktree ? { worktreePath: isolatedWorktree.path, worktreeBranch: isolatedWorktree.branch } : {}),
+      };
+      sessionManager.appendCustomEntry(SUBAGENT_META_TYPE, metadata);
+      sessionManager.appendSessionInfo(metadata.description);
+
+      const requestedModel = parseSubagentModel(parentModelRuntime, request.model ?? profile.model);
+      const parentModel = parent.inner.model as ReturnType<ModelRuntime["getModel"]>;
+      const { session: inner } = await createAgentSessionFromServices({
+        services,
+        sessionManager,
+        model: requestedModel ?? parentModel,
+        ...(thinking ? { thinkingLevel: thinking as ThinkingLevel } : {}),
+        tools: activeTools,
+        excludeTools: [...SUBAGENT_CONTROL_TOOL_NAMES],
+      });
+      dependencies.registerSession(inner, {
+        ...(promptPlan.exactSystemPrompt !== undefined
+          ? { exactSystemPrompt: promptPlan.exactSystemPrompt }
+          : {}),
+        chatOnly,
+      });
+
+      const initialRun: SubagentRunInfo = {
+        sessionId: inner.sessionId,
+        sessionPath: inner.sessionFile ?? sessionManager.getSessionFile() ?? "",
+        parentSessionId,
+        parentToolCallId: request.parentToolCallId,
+        profile: profile.name,
+        description: metadata.description,
+        task: request.task,
+        runInBackground,
+        status: "queued",
+        createdAt,
+        ...(isolatedWorktree ? { worktreePath: isolatedWorktree.path, worktreeBranch: isolatedWorktree.branch } : {}),
+      };
+
+      let turnCount = 0;
+      let maxTurnsReached = false;
+      let softLimitReached = false;
+      const unsubscribeTurns = turnLimit
+        ? inner.subscribe((event) => {
+            if (event.type !== "turn_end") return;
+            turnCount += 1;
+            if (!softLimitReached && turnCount >= turnLimit) {
+              softLimitReached = true;
+              void inner.steer("You have reached your turn limit. Wrap up immediately and provide your final answer now.");
+            } else if (softLimitReached && turnCount >= turnLimit + 1) {
+              maxTurnsReached = true;
+              void inner.abort();
+            }
+          })
+        : () => {};
+      let resolveCompletion!: (run: SubagentRunInfo) => void;
+      const completion = new Promise<SubagentRunInfo>((resolve) => { resolveCompletion = resolve; });
+      const stored: StoredSubagentExecution = {
+        run: initialRun,
+        completion,
+        abortRequested: false,
+      };
+      getSubagentRuns().set(initialRun.sessionId, stored);
+      request.onUpdate?.(initialRun);
+      dependencies.invalidateSessionList();
+
+      const handleParentAbort = () => {
+        stored.abortRequested = true;
+        if (stored.run.status === "queued") stored.cancelQueued?.();
+        else void inner.abort();
+      };
+      if (!runInBackground) request.signal?.addEventListener("abort", handleParentAbort, { once: true });
+
+      const execute = async (): Promise<SubagentRunInfo> => {
+        if (stored.abortRequested) {
+          const result: SubagentRunInfo = { ...initialRun, status: "aborted", completedAt: new Date().toISOString() };
+          sessionManager.appendCustomEntry(SUBAGENT_RESULT_TYPE, { version: 1, status: "aborted", completedAt: result.completedAt });
+          await cleanupWorktree(parent.cwd, isolatedWorktree);
+          stored.run = result;
+          request.onUpdate?.(result);
+          getSubagentRuns().delete(initialRun.sessionId);
+          dependencies.invalidateSessionList();
+          return result;
+        }
+        stored.run = { ...stored.run, status: "running" };
+        sessionManager.appendCustomEntry(SUBAGENT_STATUS_TYPE, { version: 1, status: "running" });
+        request.onUpdate?.(stored.run);
+        dependencies.invalidateSessionList();
+        let result: SubagentRunInfo;
+        try {
+          await inner.prompt(delegatedTask, {
+            source: "rpc",
+            ...(chatOnly
+              ? {
+                  preflightResult: (success: boolean) => {
+                    if (success && inner.agent.state) {
+                      inner.agent.state.systemPrompt = profile.systemPrompt;
+                    }
+                  },
+                }
+              : {}),
+          });
+          const text = inner.getLastAssistantText()?.trim();
+          const aborted = stored.abortRequested && !maxTurnsReached;
+          result = {
+            ...initialRun,
+            status: aborted ? "aborted" : "completed",
+            completedAt: new Date().toISOString(),
+            ...(text ? { result: text } : {}),
+          };
+        } catch (error) {
+          const text = inner.getLastAssistantText()?.trim();
+          const aborted = stored.abortRequested || request.signal?.aborted;
+          result = {
+            ...initialRun,
+            status: aborted ? "aborted" : maxTurnsReached ? "completed" : "failed",
+            completedAt: new Date().toISOString(),
+            ...(text ? { result: text } : {}),
+            ...(!aborted && !maxTurnsReached
+              ? { error: error instanceof Error ? error.message : String(error) }
+              : {}),
+          };
+        } finally {
+          unsubscribeTurns();
+          request.signal?.removeEventListener("abort", handleParentAbort);
+        }
+
+        const cleanupError = await cleanupWorktree(parent.cwd, isolatedWorktree);
+        if (cleanupError) result = { ...result, worktreeCleanupError: cleanupError };
+        const persisted: SubagentResultMetadata = {
+          version: 1,
+          status: result.status as SubagentResultMetadata["status"],
+          completedAt: result.completedAt!,
+          ...(result.result ? { result: result.result } : {}),
+          ...(result.error ? { error: result.error } : {}),
+          ...(result.worktreeCleanupError ? { worktreeCleanupError: result.worktreeCleanupError } : {}),
+        };
+        sessionManager.appendCustomEntry(SUBAGENT_RESULT_TYPE, persisted);
+        stored.run = result;
+        request.onUpdate?.(result);
+        getSubagentRuns().delete(initialRun.sessionId);
+        dependencies.invalidateSessionList();
+        return result;
+      };
+
+      const finishQueuedAbort = async () => {
+        if (stored.run.status !== "queued") return;
+        const result: SubagentRunInfo = { ...initialRun, status: "aborted", completedAt: new Date().toISOString() };
+        const cleanupError = await cleanupWorktree(parent.cwd, isolatedWorktree);
+        const finalResult = cleanupError ? { ...result, worktreeCleanupError: cleanupError } : result;
+        sessionManager.appendCustomEntry(SUBAGENT_RESULT_TYPE, { version: 1, status: "aborted", completedAt: finalResult.completedAt, ...(cleanupError ? { worktreeCleanupError: cleanupError } : {}) });
+        stored.run = finalResult;
+        request.onUpdate?.(finalResult);
+        getSubagentRuns().delete(initialRun.sessionId);
+        dependencies.invalidateSessionList();
+        resolveCompletion(finalResult);
+      };
+      const queued = getSubagentQueue().enqueue(
+        parentSessionId,
+        readSubagentSettings().maxConcurrent,
+        execute,
+        (state) => {
+          if (state === "queued") {
+            sessionManager.appendCustomEntry(SUBAGENT_STATUS_TYPE, { version: 1, status: "queued" });
+          }
+          request.onUpdate?.({ ...stored.run, status: state });
+          stored.run = { ...stored.run, status: state };
+          dependencies.invalidateSessionList();
+        },
+        finishQueuedAbort,
+      );
+      stored.cancelQueued = queued.cancel;
+      void queued.promise.then(resolveCompletion, (error) => {
+        resolveCompletion({ ...initialRun, status: "failed", completedAt: new Date().toISOString(), error: error instanceof Error ? error.message : String(error) });
+      });
+
+      return { run: stored.run, completion: stored.completion };
+    } catch (error) {
+      if (isolatedWorktree) {
+        try { await removeWorktree(parent.cwd, isolatedWorktree.path); } catch { /* preserve setup failure and avoid force deletion */ }
+      }
+      throw error;
+    }
+  }
+
+  async function resume(request: ResumeSubagentRequest): Promise<SubagentExecution> {
+    const enabled = dependencies.isBuiltInSubagentsEnabled ?? isBuiltInSubagentsEnabled;
+    if (!enabled()) throw new Error("Pi Web built-in sub-agents are disabled");
+    const parentSessionId = request.parentContext.sessionManager.getSessionId();
+    const existing = await get(request.sessionId);
+    if (!existing) throw new Error(`Subagent not found: ${request.sessionId}`);
+    if (existing.parentSessionId !== parentSessionId) throw new Error("Subagent does not belong to this parent session");
+    if (existing.status === "running" || existing.status === "queued") throw new Error("Subagent is already running");
+    const parent = dependencies.getSession(parentSessionId);
+    if (!parent?.isAlive()) throw new Error("Parent session is no longer available");
+    const sessionPath = existing.sessionPath || await dependencies.resolveSessionPath(request.sessionId);
+    if (!sessionPath) throw new Error(`Subagent session file not found: ${request.sessionId}`);
+    let wrapper = dependencies.getSession(request.sessionId);
+    if (!wrapper?.isAlive()) wrapper = await dependencies.reopenSession(request.sessionId, sessionPath);
+    if (!wrapper.isAlive()) throw new Error("Subagent session is no longer available");
+    if (wrapper.isRunning()) throw new Error("Subagent is already running");
+
+    const runInBackground = request.runInBackground ?? existing.runInBackground;
+    const initialRun: SubagentRunInfo = {
+      ...existing,
+      parentToolCallId: request.parentToolCallId,
+      task: request.task,
+      description: request.description.trim() || existing.description,
+      runInBackground,
+      status: "queued",
+      completedAt: undefined,
+      result: undefined,
+      error: undefined,
+    };
+    const manager = wrapper.inner.sessionManager;
+    let resolveCompletion!: (run: SubagentRunInfo) => void;
+    const completion = new Promise<SubagentRunInfo>((resolve) => { resolveCompletion = resolve; });
+    const stored: StoredSubagentExecution = { run: initialRun, completion, abortRequested: false };
+    getSubagentRuns().set(request.sessionId, stored);
+    request.onUpdate?.(initialRun);
+    dependencies.invalidateSessionList();
+    const handleParentAbort = () => {
+      stored.abortRequested = true;
+      if (stored.run.status === "queued") stored.cancelQueued?.();
+      else void wrapper!.inner.abort();
+    };
+    if (!runInBackground) request.signal?.addEventListener("abort", handleParentAbort, { once: true });
+
+    const execute = async (): Promise<SubagentRunInfo> => {
+      if (stored.abortRequested) {
+        const result: SubagentRunInfo = { ...initialRun, status: "aborted", completedAt: new Date().toISOString() };
+        manager.appendCustomEntry(SUBAGENT_RESULT_TYPE, { version: 1, status: "aborted", completedAt: result.completedAt });
+        stored.run = result;
+        getSubagentRuns().delete(request.sessionId);
+        resolveCompletion(result);
+        return result;
+      }
+      stored.run = { ...stored.run, status: "running" };
+      manager.appendCustomEntry(SUBAGENT_STATUS_TYPE, { version: 1, status: "running" });
+      request.onUpdate?.(stored.run);
+      let result: SubagentRunInfo;
+      try {
+        await wrapper!.inner.prompt(request.task, { source: "rpc" });
+        const text = wrapper!.inner.getLastAssistantText()?.trim();
+        result = { ...initialRun, status: stored.abortRequested ? "aborted" : "completed", completedAt: new Date().toISOString(), ...(text ? { result: text } : {}) };
+      } catch (error) {
+        result = {
+          ...initialRun,
+          status: stored.abortRequested || request.signal?.aborted ? "aborted" : "failed",
+          completedAt: new Date().toISOString(),
+          ...(!stored.abortRequested && !request.signal?.aborted ? { error: error instanceof Error ? error.message : String(error) } : {}),
+        };
+      } finally {
+        request.signal?.removeEventListener("abort", handleParentAbort);
+      }
+      manager.appendCustomEntry(SUBAGENT_RESULT_TYPE, {
+        version: 1,
+        status: result.status as "completed" | "failed" | "aborted",
+        completedAt: result.completedAt!,
+        ...(result.result ? { result: result.result } : {}),
+        ...(result.error ? { error: result.error } : {}),
+      });
+      stored.run = result;
+      request.onUpdate?.(result);
+      getSubagentRuns().delete(request.sessionId);
+      dependencies.invalidateSessionList();
+      return result;
+    };
+    const finishQueuedAbort = () => {
+      if (stored.run.status !== "queued") return;
+      const result: SubagentRunInfo = { ...initialRun, status: "aborted", completedAt: new Date().toISOString() };
+      manager.appendCustomEntry(SUBAGENT_RESULT_TYPE, { version: 1, status: "aborted", completedAt: result.completedAt });
+      stored.run = result;
+      request.onUpdate?.(result);
+      getSubagentRuns().delete(request.sessionId);
+      dependencies.invalidateSessionList();
+      resolveCompletion(result);
+    };
+    const queued = getSubagentQueue().enqueue(parentSessionId, readSubagentSettings().maxConcurrent, execute, (state) => {
+      if (state === "queued") manager.appendCustomEntry(SUBAGENT_STATUS_TYPE, { version: 1, status: "queued" });
+      stored.run = { ...stored.run, status: state };
+      request.onUpdate?.(stored.run);
+      dependencies.invalidateSessionList();
+    }, finishQueuedAbort);
+    stored.cancelQueued = queued.cancel;
+    void queued.promise.then(resolveCompletion, (error) => resolveCompletion({ ...initialRun, status: "failed", completedAt: new Date().toISOString(), error: error instanceof Error ? error.message : String(error) }));
+    return { run: stored.run, completion };
+  }
+
+  async function get(sessionId: string): Promise<SubagentRunInfo | null> {
+    const stored = getSubagentRuns().get(sessionId);
+    if (stored) return stored.run;
+    const wrapper = dependencies.getSession(sessionId);
+    if (wrapper?.isAlive()) {
+      const run = readSubagentRun(
+        wrapper.inner.sessionManager.getEntries() as unknown as SessionEntry[],
+        sessionId,
+        wrapper.sessionFile,
+      );
+      if (run && wrapper.isRunning()) return { ...run, status: "running" };
+      if (run) return run;
+    }
+    const sessionPath = await dependencies.resolveSessionPath(sessionId);
+    if (!sessionPath) return null;
+    const manager = SessionManager.open(sessionPath);
+    return readSubagentRun(manager.getEntries() as unknown as SessionEntry[], sessionId, sessionPath);
+  }
+
+  async function steer(sessionId: string, message: string): Promise<void> {
+    const wrapper = dependencies.getSession(sessionId);
+    if (!wrapper?.isAlive() || !wrapper.isRunning()) throw new Error("Subagent is not running");
+    if (!message.trim()) throw new Error("Steering message is required");
+    await wrapper.inner.steer(message.trim());
+  }
+
+  async function notifyParent(run: SubagentRunInfo): Promise<void> {
+    let parent = dependencies.getSession(run.parentSessionId);
+    if (!parent?.isAlive()) {
+      const sessionFile = await dependencies.resolveSessionPath(run.parentSessionId);
+      if (!sessionFile) throw new Error(`Parent session not found: ${run.parentSessionId}`);
+      parent = await dependencies.reopenSession(run.parentSessionId, sessionFile);
+    }
+    await parent.waitUntilReady();
+    if (!parent.isAlive()) throw new Error(`Parent session is no longer available: ${run.parentSessionId}`);
+    await parent.inner.sendCustomMessage({
+      customType: "pi-web:subagent-notification",
+      content: subagentFinalText(run),
+      display: true,
+      details: subagentToolDetails(run),
+    }, { deliverAs: "followUp", triggerTurn: true });
+  }
+
+  async function abort(sessionId: string): Promise<void> {
+    const wrapper = dependencies.getSession(sessionId);
+    const stored = getSubagentRuns().get(sessionId);
+    if (stored?.run.status === "queued") {
+      stored.abortRequested = true;
+      if (!stored.cancelQueued?.()) throw new Error("Subagent is no longer queued");
+      return;
+    }
+    if (!wrapper?.isAlive() || !wrapper.isRunning()) throw new Error("Subagent is not running");
+    if (stored) stored.abortRequested = true;
+    await wrapper.inner.abort();
+  }
+
+  return {
+    extensionRuntime: { start, resume, get, steer, notifyParent },
+    get,
+    steer,
+    abort,
+  };
+}

package/lib/subagent-settings.test.mjs

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const {
+  isBuiltInSubagentsEnabled,
+  readSubagentSettings,
+  writeBuiltInSubagentsEnabled,
+} = await createJiti(import.meta.url).import("./subagent-settings.ts");
+
+test("subagent settings default the built-in extension to disabled", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "pi-web-subagent-settings-"));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const settingsPath = join(root, "agents", "settings.json");
+
+  assert.deepEqual(readSubagentSettings(settingsPath), { builtInEnabled: false });
+  assert.equal(isBuiltInSubagentsEnabled(settingsPath), false);
+});
+
+test("subagent settings persist both states and preserve unrelated fields", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "pi-web-subagent-settings-"));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const settingsPath = join(root, "agents", "settings.json");
+
+  writeBuiltInSubagentsEnabled(true, settingsPath);
+  assert.deepEqual(readSubagentSettings(settingsPath), { builtInEnabled: true });
+  assert.equal(isBuiltInSubagentsEnabled(settingsPath), true);
+  const first = JSON.parse(await readFile(settingsPath, "utf8"));
+  assert.deepEqual(first, { version: 1, builtInEnabled: true });
+
+  await writeFile(settingsPath, JSON.stringify({ ...first, futureSetting: 3 }));
+  writeBuiltInSubagentsEnabled(false, settingsPath);
+  const second = JSON.parse(await readFile(settingsPath, "utf8"));
+  assert.deepEqual(second, { version: 1, builtInEnabled: false, futureSetting: 3 });
+});
+
+test("damaged settings fail closed and are not overwritten", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "pi-web-subagent-settings-"));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const settingsPath = join(root, "settings.json");
+  await writeFile(settingsPath, "{");
+
+  assert.equal(isBuiltInSubagentsEnabled(settingsPath), false);
+  assert.throws(() => readSubagentSettings(settingsPath));
+  assert.throws(() => writeBuiltInSubagentsEnabled(true, settingsPath));
+  assert.equal(await readFile(settingsPath, "utf8"), "{");
+});