@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/src/extension/parent-runtime.ts

@@ -0,0 +1,405 @@
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { discoverAgents } from "../agents/agents.ts";
+import {
+  ARTIFACT_CLEANUP_DAYS,
+  cleanupAllArtifactDirs,
+  cleanupOldArtifacts,
+  getArtifactsDir,
+} from "../shared/artifacts.ts";
+import { resolveCurrentSessionId } from "../shared/session-identity.ts";
+import { cleanupOldChainDirs } from "../shared/settings.ts";
+import { cleanupOldRunStorage } from "../shared/temp-root.ts";
+import { AgentViewController } from "../tui/agent-view.ts";
+import { createSubagentExecutor } from "../runs/foreground/subagent-executor.ts";
+import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
+import { rememberOwnedRun, restoreOwnedRunsAsync } from "../runs/shared/run-records.ts";
+import { closeRunHistory, runHistoryIndex, startRunHistory } from "../runs/shared/history-index.ts";
+import { registerParentUsage } from "../runs/shared/parent-usage.ts";
+import { createCompletionDelivery } from "../runs/background/completion-delivery.ts";
+import { isObsoleteIdleNotice } from "../runs/shared/subagent-control.ts";
+import { registerSlashCommands } from "../slash/slash-commands.ts";
+import { clearSlashSnapshots, restoreSlashFinalSnapshots } from "../slash/slash-live-state.ts";
+import { isTuiContext } from "../shared/ui-mode.ts";
+import { isRecord } from "../shared/unknown.ts";
+import type { ReadonlyInput } from "../shared/types/inputs.ts";
+import {
+  ASYNC_DIR,
+  RESULTS_DIR,
+  SUBAGENT_ASYNC_COMPLETE_EVENT,
+  SUBAGENT_ASYNC_STARTED_EVENT,
+  SUBAGENT_CONTROL_EVENT,
+  WIDGET_KEY,
+  type ExtensionConfig,
+  type SubagentExecutionResult,
+  type SubagentState,
+} from "../shared/types.ts";
+import {
+  handleSubagentControlNotice,
+  SUBAGENT_CONTROL_MESSAGE_TYPE,
+  type SubagentControlMessageDetails,
+} from "./control-notices.ts";
+import { parseControlNotice } from "./control-notice-schema.ts";
+import { adaptFinalizedToolResult, registerToolResultAdapter } from "./tool-result.ts";
+import { registerCompactSubagentTools } from "./compact-tools.ts";
+import { registerParentSubagentTool, SUBAGENT_GUIDELINES } from "./primary-tool.ts";
+import { registerMessageRenderers } from "./message-renderers.ts";
+import { registerDelegationBridges } from "./delegation-bridges.ts";
+import {
+  createRuntimeState,
+  ensureAccessibleDir,
+  expandTilde,
+  getSubagentSessionRoot,
+} from "./runtime-storage.ts";
+import {
+  cleanupStaleSubscriptions,
+  EVENT_UNSUBSCRIBES_KEY,
+  isStaleExtensionContextError,
+  removeSharedRuntimeValue,
+  RUNTIME_CLEANUP_KEY,
+  setSharedRuntimeValue,
+  visibleControlNotices,
+} from "./runtime-reload.ts";
+
+const TOOL_NAMES = ["subagent", "delegate", "agent_runs"];
+
+/** Owns one extension runtime's session projection, timers, delivery, subscriptions and UI. */
+export class ParentSubagentRuntime {
+  private readonly pi: ExtensionAPI;
+  private readonly config: ExtensionConfig;
+  private readonly state: SubagentState;
+  private readonly tracker: ReturnType<typeof createAsyncJobTracker>;
+  private readonly executor: ReturnType<typeof createSubagentExecutor>;
+  private readonly agentView: AgentViewController;
+  private readonly parentUsage: ReturnType<typeof registerParentUsage>;
+  private readonly completionDelivery: ReturnType<typeof createCompletionDelivery>;
+  private readonly adaptToolResult: ReturnType<typeof registerToolResultAdapter>;
+  private readonly bridges: ReturnType<typeof registerDelegationBridges>;
+  private readonly visibleNotices = visibleControlNotices();
+  private readonly pendingIdleNotices = new Map<string, SubagentControlMessageDetails>();
+  private readonly pendingReconciliations = new Set<Promise<void>>();
+  private readonly runtimeCleanup = (): void => this.cleanupRuntime();
+  private eventUnsubscribes: Array<() => void> = [];
+  private sessionReset: Promise<void> | undefined;
+  private reconcileTools: () => Promise<void> = () => Promise.resolve();
+
+  constructor(pi: ExtensionAPI, config: ExtensionConfig) {
+    this.pi = pi;
+    this.config = config;
+    this.state = createRuntimeState(pi);
+    this.tracker = createAsyncJobTracker(pi, this.state, ASYNC_DIR, {
+      render: () => {
+        this.refreshView();
+      },
+    });
+    this.executor = createSubagentExecutor({
+      pi,
+      state: this.state,
+      config,
+      asyncByDefault: config.asyncByDefault !== false,
+      tempArtifactsDir: getArtifactsDir(null),
+      getSubagentSessionRoot,
+      expandTilde,
+      discoverAgents,
+      ensureSessionState: (ctx) => this.ensureSession(ctx),
+    });
+    this.agentView = new AgentViewController(pi, this.state, (params, ctx) =>
+      this.executor.execute({ toolCallId: randomUUID(), params, ctx }),
+    );
+    this.parentUsage = registerParentUsage(pi, TOOL_NAMES);
+    this.completionDelivery = createCompletionDelivery(pi, this.state, this.parentUsage);
+    this.adaptToolResult = registerToolResultAdapter(pi, TOOL_NAMES);
+    this.bridges = registerDelegationBridges({
+      events: pi.events,
+      getContext: () => this.state.lastUiContext,
+      executor: this.executor,
+    });
+    setSharedRuntimeValue(RUNTIME_CLEANUP_KEY, this.runtimeCleanup);
+  }
+
+  register(): void {
+    registerMessageRenderers(this.pi);
+    this.registerTools();
+    registerSlashCommands(this.pi, this.state);
+    this.registerRunEvents();
+    this.registerSessionEvents();
+  }
+
+  private registerTools(): void {
+    const asyncByDefault = this.config.asyncByDefault !== false;
+    const adapt = (
+      result: ReadonlyInput<SubagentExecutionResult>,
+      ctx: ExtensionContext,
+    ): SubagentExecutionResult =>
+      adaptFinalizedToolResult(result, ctx, this.parentUsage, this.adaptToolResult);
+    this.reconcileTools = registerCompactSubagentTools(this.pi, {
+      executor: this.executor,
+      state: this.state,
+      adapt,
+      guidelines: SUBAGENT_GUIDELINES,
+      asyncByDefault,
+      getHistoryIndex: () => runHistoryIndex(this.state),
+    });
+    this.state.onRunsChanged = () => {
+      this.reconcileInBackground();
+      this.refreshView();
+    };
+    registerParentSubagentTool(this.pi, {
+      executor: this.executor,
+      adapt,
+      config: this.config,
+      asyncByDefault,
+    });
+  }
+
+  private refreshView(): void {
+    this.agentView.refresh().catch((error: unknown) => {
+      console.error("Could not refresh subagent view:", error);
+    });
+  }
+
+  private reconcileInBackground(): void {
+    const operation = this.reconcileTools();
+    this.pendingReconciliations.add(operation);
+    operation
+      .finally(() => {
+        this.pendingReconciliations.delete(operation);
+      })
+      .catch((error: unknown) => {
+        console.error("Could not reconcile subagent run controls:", error);
+      });
+  }
+
+  private deliverControlNotice(details: SubagentControlMessageDetails): void {
+    handleSubagentControlNotice({
+      pi: this.pi,
+      visibleControlNotices: this.visibleNotices,
+      details,
+    });
+  }
+
+  private controlEvent(data: unknown): void {
+    const details = parseControlNotice(data);
+    if (!details) {
+      return;
+    }
+    // Keep idle references out of Pi's active turn queue until its native settle boundary.
+    if (
+      details.source === "async" &&
+      details.event.reason === "idle" &&
+      !details.event.supervisorQuestion &&
+      this.state.lastUiContext &&
+      !this.state.lastUiContext.isIdle()
+    ) {
+      this.pendingIdleNotices.set(`${details.event.runId}:${details.event.index ?? ""}`, details);
+      return;
+    }
+    this.deliverControlNotice(details);
+  }
+
+  private flushIdleNotices(): void {
+    for (const details of this.pendingIdleNotices.values()) {
+      this.deliverControlNotice(details);
+    }
+    this.pendingIdleNotices.clear();
+  }
+
+  private startedEvent(data: unknown): void {
+    this.tracker.handleStarted(data);
+    if (!isRecord(data) || typeof data.id !== "string" || data.id.length === 0) {
+      return;
+    }
+    const run = this.state.ownedRuns?.get(data.id);
+    if (run) {
+      rememberOwnedRun(this.state, {
+        ...run,
+        source: "async",
+        asyncDir: typeof data.asyncDir === "string" ? data.asyncDir : undefined,
+        pid: typeof data.pid === "number" ? data.pid : undefined,
+      });
+    }
+  }
+
+  private subscribeEvents(): void {
+    this.eventUnsubscribes = [];
+    setSharedRuntimeValue(EVENT_UNSUBSCRIBES_KEY, this.eventUnsubscribes);
+    // Retain each successful subscription even if a later registration fails.
+    this.eventUnsubscribes.push(
+      this.pi.events.on(SUBAGENT_ASYNC_STARTED_EVENT, (data) => this.startedEvent(data)),
+    );
+    this.eventUnsubscribes.push(
+      this.pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, this.tracker.handleComplete),
+    );
+    this.eventUnsubscribes.push(
+      this.pi.events.on(SUBAGENT_CONTROL_EVENT, (data) => this.controlEvent(data)),
+    );
+  }
+
+  private registerRunEvents(): void {
+    cleanupStaleSubscriptions();
+    this.subscribeEvents();
+    this.pi.on("turn_end", () => this.flushIdleNotices());
+    this.pi.on("agent_before_settle", () => this.flushIdleNotices());
+    this.pi.on("context", (event) => ({
+      messages: event.messages.filter((message) => {
+        if (message.role !== "custom" || message.customType !== SUBAGENT_CONTROL_MESSAGE_TYPE) {
+          return true;
+        }
+        const notice = parseControlNotice(message.details);
+        return !notice || !isObsoleteIdleNotice(notice);
+      }),
+    }));
+    this.pi.on("tool_result", (event, ctx) => {
+      if (!TOOL_NAMES.includes(event.toolName) || !isTuiContext(ctx)) {
+        return;
+      }
+      this.state.lastUiContext = ctx;
+      if (this.state.asyncJobs.size > 0) {
+        this.refreshView();
+        const ui: ExtensionContext["ui"] & { requestRender?: () => void } = ctx.ui;
+        ui.requestRender?.();
+        this.tracker.ensurePoller();
+      }
+    });
+  }
+
+  private registerSessionEvents(): void {
+    this.pi.on("session_start", async (_event, ctx) => {
+      if (this.eventUnsubscribes.length === 0) {
+        this.subscribeEvents();
+      }
+      await this.resetSession(ctx);
+      await this.reconcileTools();
+    });
+    this.pi.on("session_shutdown", () => this.shutdown());
+  }
+
+  private stopPoller(): void {
+    if (this.state.poller) {
+      clearInterval(this.state.poller);
+    }
+    this.state.poller = null;
+  }
+
+  private cleanupRuntime(): void {
+    this.agentView.dispose();
+    closeRunHistory(this.state).catch((error: unknown) => {
+      console.error("Could not close subagent history:", error);
+    });
+    this.completionDelivery.stop();
+    this.stopPoller();
+  }
+
+  private ensureSession(ctx: ExtensionContext): Promise<void> {
+    if (this.sessionReset) {
+      return this.sessionReset;
+    }
+    return this.state.currentSessionId !== resolveCurrentSessionId(ctx.sessionManager)
+      ? this.resetSession(ctx)
+      : Promise.resolve();
+  }
+
+  private resetSession(ctx: ExtensionContext): Promise<void> {
+    if (this.sessionReset) {
+      return this.sessionReset;
+    }
+    this.sessionReset = this.restoreSession(ctx).finally(() => {
+      this.sessionReset = undefined;
+    });
+    return this.sessionReset;
+  }
+
+  private async restoreSession(ctx: ExtensionContext): Promise<void> {
+    this.pendingIdleNotices.clear();
+    this.agentView.dispose();
+    this.stopPoller();
+    await this.completionDelivery.stopAndJoin();
+    closeRunHistory(this.state).catch((error: unknown) => {
+      console.error("Could not close subagent history:", error);
+    });
+    ensureAccessibleDir(RESULTS_DIR);
+    ensureAccessibleDir(ASYNC_DIR);
+    this.state.baseCwd = ctx.cwd;
+    this.state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
+    this.state.lastUiContext = ctx;
+    this.tracker.resetJobs();
+    const restoration = await restoreOwnedRunsAsync(this.state, ctx);
+    try {
+      this.tracker.restoreJobs(this.state.currentSessionId, ctx, restoration);
+    } catch (error) {
+      console.error("Failed to restore active async jobs:", error);
+      this.tracker.resetJobs(ctx);
+    }
+    startRunHistory(this.state, ctx);
+    this.reconcileInBackground();
+    this.agentView.start(ctx);
+    await this.cleanupArtifacts(ctx);
+    restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
+    this.completionDelivery.start();
+  }
+
+  private async cleanupArtifacts(ctx: ExtensionContext): Promise<void> {
+    await cleanupOldRunStorage();
+    await cleanupOldChainDirs();
+    await cleanupAllArtifactDirs(ARTIFACT_CLEANUP_DAYS);
+    try {
+      const file = ctx.sessionManager.getSessionFile();
+      if (file !== undefined && file.length > 0) {
+        await cleanupOldArtifacts(getArtifactsDir(file), ARTIFACT_CLEANUP_DAYS);
+      }
+    } catch {
+      // Artifact failures must not block native session lifecycle events.
+    }
+  }
+
+  private async shutdown(): Promise<void> {
+    // A reset can still publish history, view and delivery after its awaited restoration/cleanup.
+    // Join that owner before disposing the resources it may start.
+    try {
+      await this.sessionReset;
+    } finally {
+      await this.disposeSession();
+    }
+  }
+
+  private async disposeSession(): Promise<void> {
+    this.agentView.dispose();
+    this.stopPoller();
+    await this.completionDelivery.stopAndJoin({ preservePending: true });
+    await closeRunHistory(this.state);
+    await Promise.allSettled(this.pendingReconciliations);
+    for (const unsubscribe of this.eventUnsubscribes) {
+      try {
+        unsubscribe();
+      } catch {
+        /* Shutdown also owns already-disposed subscriptions. */
+      }
+    }
+    removeSharedRuntimeValue(EVENT_UNSUBSCRIBES_KEY, this.eventUnsubscribes);
+    this.eventUnsubscribes = [];
+    for (const timer of this.state.cleanupTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.state.cleanupTimers.clear();
+    this.state.asyncJobs.clear();
+    clearSlashSnapshots();
+    this.bridges.slash.cancelAll();
+    this.bridges.slash.dispose();
+    this.bridges.template.cancelAll();
+    this.bridges.template.dispose();
+    removeSharedRuntimeValue(RUNTIME_CLEANUP_KEY, this.runtimeCleanup);
+    this.clearWidget();
+  }
+
+  private clearWidget(): void {
+    try {
+      if (this.state.lastUiContext && isTuiContext(this.state.lastUiContext)) {
+        this.state.lastUiContext.ui.setWidget(WIDGET_KEY, undefined);
+      }
+    } catch (error) {
+      if (!isStaleExtensionContextError(error)) {
+        throw error;
+      }
+    }
+  }
+}

package/src/extension/primary-tool.ts

@@ -0,0 +1,130 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import type { Static } from "typebox";
+import {
+  normalizeSubagentParamsLike,
+  resolveAsyncExecutionMode,
+  type createSubagentExecutor,
+} from "../runs/foreground/subagent-executor.ts";
+import { applyForceTopLevelAsyncOverride } from "../runs/background/top-level-async.ts";
+import { renderSubagentResult } from "../tui/render.ts";
+import type { ReadonlyDetails, SubagentExecutionResult, ExtensionConfig } from "../shared/types.ts";
+import type { ReadonlyInput } from "../shared/types/inputs.ts";
+import { SubagentParams } from "./schemas.ts";
+
+export const SUBAGENT_GUIDELINES = [
+  "Use subagent for materially parallelizable scouting, review, or implementation work where another focused agent adds value.",
+  "Top-level subagent execution uses the stock async default unless configuration opts out. Launch a small bounded fanout of independent agents as separate single-agent runs so each completion wakes the parent, with at most one writer. Use one tasks call for non-review fanout when all child results are required together, when shared concurrency/task limits are needed, or when multiple writers require worktree isolation; the parent receives one aggregate completion. If no useful parent work remains, end the turn and wait instead of polling; completion wakes the parent. This also applies when an incomplete active Pi goal needs child evidence: yield, then continue the goal after automatic completion delivery. Set async:false only for explicitly chosen foreground execution.",
+  'Before executing subagent runs, call subagent with { action: "list" } unless the requested executable agent or chain is already known from this conversation.',
+  "Keep the parent session responsible for final decisions, verification, and user-facing status; treat subagent output as evidence to review, not automatic truth.",
+  "Fresh-child handoffs must include relevant exact user instructions and settled decisions or readable source references alongside the bounded task; summaries do not replace original requirements.",
+  "Keep independent review as a separate parent-launched reviewer run after the worker; acceptance.review is unsupported.",
+  "For review-only tasks, omit acceptance unless the user explicitly requests a same-session acceptance contract; acceptance adds a finalization turn and is not independent review.",
+  "For live child guidance, answers, corrections, or blockers, inspect status and prefer action='nudge'; it sends a non-blocking steer that supplements the active task unless the message explicitly replaces it. Use the shown blocking intercom ask only when the parent must stay alive waiting for a reply.",
+  "Do not use subagent when a direct local tool call or small edit is cheaper than delegation.",
+] as const;
+
+interface ParentToolOptions {
+  readonly executor: Readonly<ReturnType<typeof createSubagentExecutor>>;
+  readonly adapt: (
+    result: ReadonlyInput<SubagentExecutionResult>,
+    ctx: ExtensionContext,
+  ) => SubagentExecutionResult;
+  readonly config: ExtensionConfig;
+  readonly asyncByDefault: boolean;
+}
+
+function effectiveParallelTaskCount(
+  tasks: readonly { readonly count?: unknown }[] | undefined,
+): number {
+  return (
+    tasks?.reduce(
+      (total, task) =>
+        total +
+        (typeof task.count === "number" && Number.isInteger(task.count) && task.count >= 1
+          ? task.count
+          : 1),
+      0,
+    ) ?? 0
+  );
+}
+
+type RenderArgs = ReadonlyInput<Partial<Static<typeof SubagentParams>>>;
+
+function renderManagement(args: RenderArgs & { readonly action: string }, theme: Theme): Text {
+  const agent = args.agent ?? "";
+  const target = agent.length > 0 ? agent : (args.chainName ?? "");
+  const title = theme.fg("toolTitle", theme.bold("subagent "));
+  return new Text(
+    `${title}${args.action}${target.length > 0 ? ` ${theme.fg("accent", target)}` : ""}`,
+    0,
+    0,
+  );
+}
+
+function renderExecution(
+  args: RenderArgs,
+  theme: Theme,
+  options: Pick<ParentToolOptions, "config" | "asyncByDefault">,
+): Text {
+  const title = theme.fg("toolTitle", theme.bold("subagent "));
+  const renderedArgs = applyForceTopLevelAsyncOverride(
+    args,
+    0,
+    options.config.forceTopLevelAsync === true,
+  );
+  const asyncLabel = resolveAsyncExecutionMode(renderedArgs, options.asyncByDefault).effectiveAsync
+    ? theme.fg("warning", " [async]")
+    : "";
+  if (args.chain !== undefined && args.chain.length > 0) {
+    return new Text(`${title}chain (${args.chain.length})${asyncLabel}`, 0, 0);
+  }
+  if (args.tasks !== undefined && args.tasks.length > 0) {
+    return new Text(
+      `${title}parallel (${effectiveParallelTaskCount(args.tasks)})${asyncLabel}`,
+      0,
+      0,
+    );
+  }
+  const agent = args.agent ?? "";
+  return new Text(
+    `${title}${theme.fg("accent", agent.length > 0 ? agent : "?")}${asyncLabel}`,
+    0,
+    0,
+  );
+}
+
+export function registerParentSubagentTool(pi: ExtensionAPI, options: ParentToolOptions): void {
+  const tool: ToolDefinition<typeof SubagentParams, ReadonlyDetails> = {
+    name: "subagent",
+    defaultActive: false,
+    label: "Subagent",
+    description: `Delegate bounded work to configured Pi subagents, chains, or parallel reviewers; manage agent definitions; inspect/control async runs. Indexed status lists support global agent/state/text filters and sort/cursors; history pages bounded native previews and search finds saved visible words or one quoted phrase. Browse freshness is not canonical proof. Use exactly one execution mode (agent, tasks, or chain) or one management/control action. Before execution, use { action: "list" } to inspect configured agents/chains. Only execute agents listed as executable/non-disabled. Parallel tasks support output?,reads?,progress?. maxOutput accepts { bytes?: number, lines?: number }. Prefer acceptance for goal/spec handoffs and status/resume/interrupt/extend/nudge for active runs. Exact status is concise by default; full:true includes the full task/configuration. Review notes are parent-only, not sent to children; put actionable instructions in resume/nudge. Resume/answer preserves saved settings unless agent selects a current profile (including model/thinking/fallbacks); a separate model override wins. Live guidance never mutates model or acceptance.`,
+    parameters: SubagentParams,
+    async execute(id, params, signal, onUpdate, ctx) {
+      return options.adapt(
+        await options.executor.execute({
+          toolCallId: id,
+          params: normalizeSubagentParamsLike(params),
+          signal,
+          onUpdate,
+          ctx,
+        }),
+        ctx,
+      );
+    },
+    renderCall: (args, theme) => {
+      if (args.action !== undefined && args.action.length > 0) {
+        return renderManagement({ ...args, action: args.action }, theme);
+      }
+      return renderExecution(args, theme, options);
+    },
+    renderResult: renderSubagentResult,
+  };
+  pi.registerTool(tool);
+}

package/src/extension/result-snapshot.ts

@@ -0,0 +1,35 @@
+import type {
+  AgentProgress,
+  Details,
+  SingleResult,
+  SubagentExecutionResult,
+} from "../shared/types.ts";
+import type { ReadonlyInput } from "../shared/types/inputs.ts";
+
+/** A new result owns its progress buffers; native messages and accounting stay shared snapshots. */
+export function copyProgress(progress: ReadonlyInput<AgentProgress>): AgentProgress {
+  return {
+    ...progress,
+    recentTools: progress.recentTools.map((tool) => ({ ...tool })),
+    recentOutput: [...progress.recentOutput],
+  };
+}
+
+export function copyResult(result: ReadonlyInput<SingleResult>): SingleResult {
+  return { ...result, progress: result.progress ? copyProgress(result.progress) : undefined };
+}
+
+export function copyDetails(details: ReadonlyInput<Details>): Details {
+  return {
+    ...details,
+    results: details.results.map(copyResult),
+    progress: details.progress?.map(copyProgress),
+  };
+}
+
+/** Preserve the native result envelope while giving the receiving tool its own content array. */
+export function copyExecutionResult(
+  result: ReadonlyInput<SubagentExecutionResult>,
+): SubagentExecutionResult {
+  return { ...result, content: [...result.content] };
+}

package/src/extension/runtime-reload.ts

@@ -0,0 +1,72 @@
+import { isUnknownArray } from "../shared/unknown.ts";
+
+export const RUNTIME_CLEANUP_KEY = "__piSubagentRuntimeCleanup";
+export const EVENT_UNSUBSCRIBES_KEY = "__piSubagentEventUnsubscribes";
+const VISIBLE_NOTICES_KEY = "__piSubagentVisibleControlNotices";
+
+export function sharedRuntimeValue(key: string): unknown {
+  return Reflect.get(globalThis, key);
+}
+
+export function setSharedRuntimeValue(key: string, value: unknown): void {
+  if (!Reflect.set(globalThis, key, value)) {
+    throw new Error(`Could not register subagent runtime value '${key}'.`);
+  }
+}
+
+export function removeSharedRuntimeValue(key: string, current: unknown): void {
+  if (sharedRuntimeValue(key) === current) {
+    Reflect.deleteProperty(globalThis, key);
+  }
+}
+
+function isCallback(value: unknown): value is () => unknown {
+  return typeof value === "function";
+}
+
+function cleanupCallback(value: unknown): void {
+  if (!isCallback(value)) {
+    return;
+  }
+  try {
+    const pending = value();
+    if (pending instanceof Promise) {
+      pending.catch((error: unknown) => {
+        console.error("Could not clean stale subagent runtime:", error);
+      });
+    }
+  } catch {
+    // Stale cleanup must not prevent the replacement extension from registering.
+  }
+}
+
+export function cleanupStaleRuntime(key = RUNTIME_CLEANUP_KEY): void {
+  cleanupCallback(sharedRuntimeValue(key));
+}
+
+export function isStaleExtensionContextError(error: unknown): boolean {
+  return error instanceof Error && error.message.includes("Extension context no longer active");
+}
+
+export function cleanupStaleSubscriptions(): void {
+  const previous = sharedRuntimeValue(EVENT_UNSUBSCRIBES_KEY);
+  if (isUnknownArray(previous)) {
+    for (const unsubscribe of previous) {
+      cleanupCallback(unsubscribe);
+    }
+  }
+}
+
+function isStringSet(value: unknown): value is Set<string> {
+  return value instanceof Set && [...value].every((entry: unknown) => typeof entry === "string");
+}
+
+export function visibleControlNotices(): Set<string> {
+  const previous = sharedRuntimeValue(VISIBLE_NOTICES_KEY);
+  if (isStringSet(previous)) {
+    return previous;
+  }
+  const notices = new Set<string>();
+  setSharedRuntimeValue(VISIBLE_NOTICES_KEY, notices);
+  return notices;
+}

package/src/extension/runtime-storage.ts

@@ -0,0 +1,49 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { OWNED_RUN_ENTRY } from "../runs/shared/run-records.ts";
+import { ensureSafeTempPath } from "../shared/temp-root.ts";
+import type { SubagentState } from "../shared/types.ts";
+
+export function getSubagentSessionRoot(parentSessionFile: string | null): string {
+  if (parentSessionFile !== null && parentSessionFile.length > 0) {
+    return path.join(path.dirname(parentSessionFile), path.basename(parentSessionFile, ".jsonl"));
+  }
+  return fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
+}
+
+export function expandTilde(value: string): string {
+  return value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
+}
+
+export function ensureAccessibleDir(dir: string): void {
+  ensureSafeTempPath(dir);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.accessSync(dir, fs.constants.R_OK | fs.constants.W_OK);
+}
+
+export function createRuntimeState(pi: ExtensionAPI): SubagentState {
+  return {
+    baseCwd: "",
+    currentSessionId: null,
+    asyncJobs: new Map(),
+    foregroundRuns: new Map(),
+    ownedRuns: new Map(),
+    persistOwnedRun: (run) => {
+      pi.appendEntry(OWNED_RUN_ENTRY, run);
+    },
+    cleanupTimers: new Map(),
+    lastUiContext: null,
+    poller: null,
+    completionSeen: new Map(),
+    watcher: null,
+    watcherRestartTimer: null,
+    resultFileCoalescer: {
+      schedule: () => false,
+      clear: () => {
+        /* The async tracker installs a real coalescer when its watcher starts. */
+      },
+    },
+  };
+}