@ian-pascoe/pi-minimal-subagents 0.1.0

package/src/minimal-subagents-extension.ts

@@ -0,0 +1,279 @@
+import { fileURLToPath } from "node:url";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import {
+  buildSessionContext,
+  getAgentDir,
+  SessionManager,
+  SettingsManager,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import { MinimalSubagentsCoordinator } from "./minimal-subagents-coordinator.js";
+import { resolveMinimalSubagentsSettings } from "./minimal-subagents-config.js";
+import { snapshotCommittedContext } from "./minimal-subagents-context.js";
+import { rememberForkSnapshot, takeForkSnapshot } from "./minimal-subagents-fork-lifecycle.js";
+import {
+  buildEligibleModelIds,
+  COORDINATOR_TOOL_NAMES,
+  excludeCoordinatorTools,
+} from "./minimal-subagents-capabilities.js";
+import {
+  CHILD_IDENTITY_ENTRY_TYPE,
+  REGISTRY_ENTRY_TYPE,
+  replayRegistryEntries,
+} from "./minimal-subagents-registry.js";
+import { createCoordinatorToolSchemas } from "./minimal-subagents-tool-schemas.js";
+import { findDeliveryEvidence, PiAgentSessionFactory } from "./minimal-subagents-sessions.js";
+import { shutdownMinimalSubagentsSession } from "./minimal-subagents-shutdown.js";
+import { createCoordinatorToolDefinitions } from "./minimal-subagents-tools.js";
+import {
+  renderMinimalSubagentsMessage,
+  renderMinimalSubagentsResult,
+} from "./minimal-subagents-rendering.js";
+import { MinimalSubagentsUiController } from "./minimal-subagents-ui.js";
+import type {
+  CallerSnapshot,
+  CoordinatorNotification,
+  ForkSnapshot,
+  RegistrySnapshot,
+  RootConversationEndpoint,
+} from "./minimal-subagents-types.js";
+
+const EXTENSION_ENTRYPOINT = fileURLToPath(new URL("./index.ts", import.meta.url));
+
+function currentConversationMessages(context: ExtensionContext): AgentMessage[] {
+  const entries = context.sessionManager.getEntries() as SessionEntry[];
+  const messages = buildSessionContext(entries, context.sessionManager.getLeafId()).messages;
+  return snapshotCommittedContext(messages, !context.isIdle());
+}
+
+function rootCallerSnapshot(pi: ExtensionAPI, context: ExtensionContext): CallerSnapshot {
+  if (!context.model) throw new Error("Minimal subagents spawn: root has no effective model");
+  const activeTools = excludeCoordinatorTools(pi.getActiveTools());
+  const availableTools = excludeCoordinatorTools(pi.getAllTools().map((tool) => tool.name));
+  return {
+    messages: currentConversationMessages(context),
+    model: `${context.model.provider}/${context.model.id}`,
+    thinkingLevel: context.thinkingLevel ?? pi.getThinkingLevel(),
+    ordinaryTools: activeTools,
+    capabilityCeiling: availableTools,
+    availableTools,
+    spawnEntryId: context.sessionManager.getLeafId() ?? "root",
+  };
+}
+
+function createRootConversationEndpoint(
+  pi: ExtensionAPI,
+  context: ExtensionContext,
+): RootConversationEndpoint {
+  return {
+    async steerCoordinatorMessage(message) {
+      pi.sendMessage(
+        {
+          customType: message.customType,
+          content: message.content,
+          display: true,
+          details: message.details,
+        },
+        {
+          triggerTurn: true,
+          deliverAs: "steer",
+        },
+      );
+    },
+    hasDeliveryEvidence: (sourceAgentId, sourceTurnId) =>
+      findDeliveryEvidence(context.sessionManager.getEntries(), sourceAgentId, sourceTurnId),
+  };
+}
+
+function shouldSurfaceNotification(notification: CoordinatorNotification): boolean {
+  return ["failure", "interruption", "unavailable", "fork-clone-failure"].includes(
+    notification.type,
+  );
+}
+
+function notificationLevel(notification: CoordinatorNotification): "info" | "warning" | "error" {
+  if (notification.type === "failure" || notification.type === "fork-clone-failure") return "error";
+  if (
+    notification.type === "cancellation" ||
+    notification.type === "interruption" ||
+    notification.type === "unavailable"
+  ) {
+    return "warning";
+  }
+  return "info";
+}
+
+function hasHistoricalChildIdentity(entries: readonly SessionEntry[]): boolean {
+  return entries.some(
+    (entry) => entry.type === "custom" && entry.customType === CHILD_IDENTITY_ENTRY_TYPE,
+  );
+}
+
+function replayPreviousRoot(previousSessionFile: string): RegistrySnapshot {
+  const previousSession = SessionManager.open(previousSessionFile);
+  const previousRootSessionId = previousSession.getSessionId();
+  return replayRegistryEntries(previousSession.getEntries(), previousRootSessionId);
+}
+
+async function waitForRootSessionIdle(context: ExtensionContext): Promise<void> {
+  while (!context.isIdle()) {
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+}
+
+/** Register the six root coordinator tools and bind root-owned persistent subagent lifecycle hooks. */
+export default function minimalSubagentsExtension(pi: ExtensionAPI) {
+  let coordinator: MinimalSubagentsCoordinator | undefined;
+  let uiController: MinimalSubagentsUiController | undefined;
+  let preparedFork: ForkSnapshot | undefined;
+
+  pi.registerMessageRenderer("minimal-subagents.message", renderMinimalSubagentsMessage);
+  pi.registerMessageRenderer("minimal-subagents.result", renderMinimalSubagentsResult);
+
+  pi.on("session_start", async (event, context) => {
+    const rootSessionId = context.sessionManager.getSessionId();
+    const agentDir = getAgentDir();
+    const settingsManager = SettingsManager.create(context.cwd, agentDir, {
+      projectTrusted: context.isProjectTrusted(),
+    });
+    const enabledModelPatterns = settingsManager.getEnabledModels();
+    const availableModels = context.modelRegistry.getAvailable();
+    const eligibleModelIds = buildEligibleModelIds({
+      availableModels,
+      scopedModels: context.scopedModels,
+      scopeConfigured: enabledModelPatterns !== undefined,
+    });
+    const minimalSubagentsConfig = resolveMinimalSubagentsSettings(
+      settingsManager,
+      eligibleModelIds,
+    );
+    if (minimalSubagentsConfig.warnings.length > 0) {
+      context.ui.notify(
+        `Minimal subagents configuration warnings:\n- ${minimalSubagentsConfig.warnings.join("\n- ")}`,
+        "warning",
+      );
+    }
+    const models = [...availableModels];
+    if (
+      context.model &&
+      !models.some(
+        (model) => model.provider === context.model?.provider && model.id === context.model?.id,
+      )
+    ) {
+      models.push(context.model);
+    }
+    const availableToolNames = excludeCoordinatorTools(pi.getAllTools().map((tool) => tool.name));
+    const schemas = createCoordinatorToolSchemas(eligibleModelIds);
+    let activeCoordinator!: MinimalSubagentsCoordinator;
+    const sessionFactory = new PiAgentSessionFactory({
+      cwd: context.cwd,
+      agentDir,
+      sessionDir: context.sessionManager.getSessionDir(),
+      rootSessionId,
+      extensionEntrypoint: EXTENSION_ENTRYPOINT,
+      models,
+      eligibleModelIds,
+      modelScopeRestricted: enabledModelPatterns !== undefined,
+      availableToolNames,
+      projectTrusted: context.isProjectTrusted(),
+      maxSubagentDepth: minimalSubagentsConfig.maxSubagentDepth,
+      onChildSessionActivity: () => activeCoordinator.scheduleDeliveryReconciliation(),
+      getCoordinatorTools: (callerId) =>
+        createCoordinatorToolDefinitions({
+          coordinator: activeCoordinator,
+          callerId,
+          allowFanoutTools: activeCoordinator.canAgentSpawn(callerId),
+          modelRoles: minimalSubagentsConfig.modelRoles,
+          schemas,
+          captureCaller: (childContext) =>
+            activeCoordinator.snapshotChildCaller(
+              callerId,
+              childContext.sessionManager.getLeafId() ?? callerId,
+            ),
+          onAttention: (message) => context.ui.notify(message, "error"),
+        }),
+    });
+    activeCoordinator = new MinimalSubagentsCoordinator({
+      sessions: sessionFactory,
+      root: createRootConversationEndpoint(pi, context),
+      maxSubagentDepth: minimalSubagentsConfig.maxSubagentDepth,
+      registry: {
+        rootSessionId,
+        append: (registryEvent) => pi.appendEntry(REGISTRY_ENTRY_TYPE, registryEvent),
+      },
+      notify: (notification) => {
+        uiController?.refresh();
+        if (shouldSurfaceNotification(notification)) {
+          context.ui.notify(notification.message, notificationLevel(notification));
+        }
+      },
+    });
+    coordinator = activeCoordinator;
+
+    let snapshot: RegistrySnapshot;
+    if (event.reason === "fork" && event.previousSessionFile) {
+      let forkSnapshot = takeForkSnapshot(event.previousSessionFile);
+      if (!forkSnapshot) {
+        await activeCoordinator.restore(replayPreviousRoot(event.previousSessionFile));
+        forkSnapshot = await activeCoordinator.prepareFork(event.previousSessionFile);
+      }
+      snapshot = forkSnapshot;
+    } else {
+      snapshot = replayRegistryEntries(context.sessionManager.getEntries(), rootSessionId);
+    }
+    await activeCoordinator.restore(snapshot);
+    activeCoordinator.writeCheckpoint();
+    uiController = new MinimalSubagentsUiController(activeCoordinator, context);
+    uiController.refresh();
+
+    const rootTools = createCoordinatorToolDefinitions({
+      coordinator: activeCoordinator,
+      callerId: "root",
+      allowFanoutTools: true,
+      modelRoles: minimalSubagentsConfig.modelRoles,
+      schemas,
+      captureCaller: (toolContext) => rootCallerSnapshot(pi, toolContext),
+      onActivity: () => uiController?.refresh(),
+      onAttention: (message) => context.ui.notify(message, "error"),
+    });
+    for (const tool of rootTools) pi.registerTool(tool);
+    pi.setActiveTools([...new Set([...pi.getActiveTools(), ...COORDINATOR_TOOL_NAMES])]);
+
+    if (hasHistoricalChildIdentity(context.sessionManager.getEntries() as SessionEntry[])) {
+      context.ui.notify(
+        "Opened a former subagent session directly. It is now an independent root; former descendants and parent messaging were not restored. Concurrent ownership by its original root is unsupported.",
+        "warning",
+      );
+    }
+  });
+
+  pi.on("session_before_fork", async (_event, context) => {
+    const sessionFile = context.sessionManager.getSessionFile();
+    if (!coordinator || !sessionFile) return;
+    preparedFork = await coordinator.prepareFork(sessionFile);
+    rememberForkSnapshot(preparedFork);
+  });
+
+  pi.on("message_end", async (event) => {
+    if (!coordinator) return;
+    if (event.message.role === "toolResult" || event.message.role === "custom") {
+      await coordinator.reconcileDeliveries();
+      uiController?.refresh();
+    }
+  });
+
+  pi.on("session_shutdown", async (event, context) => {
+    if (coordinator) {
+      await shutdownMinimalSubagentsSession(event.reason, coordinator, {
+        isRootIdle: () => context.isIdle(),
+        waitForRootIdle: () => waitForRootSessionIdle(context),
+      });
+    }
+    uiController?.dispose();
+    uiController = undefined;
+    coordinator = undefined;
+    preparedFork = undefined;
+  });
+}

package/src/minimal-subagents-fork-lifecycle.ts

@@ -0,0 +1,36 @@
+import { existsSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ForkSnapshot } from "./minimal-subagents-types.js";
+
+const FORK_SNAPSHOT_SYMBOL = Symbol.for("minimal-subagents.pending-fork-snapshots.v1");
+
+type GlobalWithForkSnapshots = typeof globalThis & {
+  [FORK_SNAPSHOT_SYMBOL]?: Map<string, ForkSnapshot>;
+};
+
+function forkSnapshotStore(): Map<string, ForkSnapshot> {
+  const processGlobal = globalThis as GlobalWithForkSnapshots;
+  processGlobal[FORK_SNAPSHOT_SYMBOL] ??= new Map();
+  return processGlobal[FORK_SNAPSHOT_SYMBOL];
+}
+
+function canonicalSessionFile(sessionFile: string): string {
+  const absolutePath = resolve(sessionFile);
+  return existsSync(absolutePath) ? realpathSync(absolutePath) : absolutePath;
+}
+
+/** Retain a complete pre-fork hierarchy across Pi extension-instance replacement. */
+export function rememberForkSnapshot(snapshot: ForkSnapshot): void {
+  forkSnapshotStore().set(
+    canonicalSessionFile(snapshot.source_root_session_file),
+    structuredClone(snapshot),
+  );
+}
+
+/** Consume the pre-fork hierarchy once when the destination root session starts. */
+export function takeForkSnapshot(previousSessionFile: string): ForkSnapshot | undefined {
+  const key = canonicalSessionFile(previousSessionFile);
+  const snapshot = forkSnapshotStore().get(key);
+  if (snapshot) forkSnapshotStore().delete(key);
+  return snapshot ? structuredClone(snapshot) : undefined;
+}

package/src/minimal-subagents-registry.ts

@@ -0,0 +1,219 @@
+import type {
+  PersistedAgent,
+  PersistedDelivery,
+  RegistrySnapshot,
+  TurnResult,
+} from "./minimal-subagents-types.js";
+
+/** Names append-only root conversation entries that own the persistent agent registry. */
+export const REGISTRY_ENTRY_TYPE = "minimal-subagents.registry";
+/** Names the first custom entry that promotes a child JSONL session to persistent identity. */
+export const CHILD_IDENTITY_ENTRY_TYPE = "minimal-subagents.identity";
+
+interface RegistryEventBaseV1 {
+  version: 1;
+  root_session_id: string;
+  timestamp: string;
+}
+
+/** Stores one complete versioned root registry checkpoint. */
+export interface RegistryCheckpointV1 extends RegistryEventBaseV1 {
+  event: "checkpoint";
+  snapshot: RegistrySnapshot;
+}
+
+/** Records one persistent child identity before runtime initialization. */
+export interface AgentCreatedV1 extends RegistryEventBaseV1 {
+  event: "agent-created";
+  agent: PersistedAgent;
+}
+
+/** Records one collision-resistant active turn identity and start time. */
+export interface TurnStartedV1 extends RegistryEventBaseV1 {
+  event: "turn-started";
+  agent_id: string;
+  turn_id: string;
+  started_at: string;
+}
+
+/** Records one terminal turn result for waits, status, and delivery recovery. */
+export interface TurnSettledV1 extends RegistryEventBaseV1 {
+  event: "turn-settled";
+  result: TurnResult;
+}
+
+/** Records successful output awaiting keyed destination evidence. */
+export interface DeliveryPendingV1 extends RegistryEventBaseV1 {
+  event: "delivery-pending";
+  delivery: PersistedDelivery;
+}
+
+/** Records keyed destination evidence or the latest delivery error. */
+export interface DeliverySettledV1 extends RegistryEventBaseV1 {
+  event: "delivery-settled";
+  source_agent_id: string;
+  source_turn_id: string;
+  error?: string;
+}
+
+/** Records durable deletion tombstones for canonical agent identities. */
+export interface AgentDeletedV1 extends RegistryEventBaseV1 {
+  event: "agent-deleted";
+  agent_ids: string[];
+}
+
+/** Unites all version-one append-only registry event envelopes. */
+export type RegistryEventV1 =
+  | RegistryCheckpointV1
+  | AgentCreatedV1
+  | TurnStartedV1
+  | TurnSettledV1
+  | DeliveryPendingV1
+  | DeliverySettledV1
+  | AgentDeletedV1;
+
+/** Defines unversioned registry payloads accepted by the event factory. */
+export type RegistryEventData =
+  | { event: "checkpoint"; snapshot: RegistrySnapshot }
+  | { event: "agent-created"; agent: PersistedAgent }
+  | { event: "turn-started"; agent_id: string; turn_id: string; started_at: string }
+  | { event: "turn-settled"; result: TurnResult }
+  | { event: "delivery-pending"; delivery: PersistedDelivery }
+  | { event: "delivery-settled"; source_agent_id: string; source_turn_id: string; error?: string }
+  | { event: "agent-deleted"; agent_ids: string[] };
+
+/** Add the versioned root ownership envelope to one append-only registry event. */
+export function createRegistryEvent<TEvent extends RegistryEventData["event"]>(
+  rootSessionId: string,
+  event: TEvent,
+  data: Omit<Extract<RegistryEventData, { event: TEvent }>, "event">,
+  timestamp = new Date().toISOString(),
+): RegistryEventV1 {
+  return {
+    version: 1,
+    root_session_id: rootSessionId,
+    timestamp,
+    event,
+    ...data,
+  } as unknown as RegistryEventV1;
+}
+
+interface RegistryEntryLike {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+}
+
+function isRegistryEvent(value: unknown, rootSessionId: string): value is RegistryEventV1 {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<RegistryEventV1>;
+  return (
+    candidate.version === 1 &&
+    candidate.root_session_id === rootSessionId &&
+    typeof candidate.timestamp === "string" &&
+    typeof candidate.event === "string"
+  );
+}
+
+function cloneSnapshot(snapshot: RegistrySnapshot): RegistrySnapshot {
+  return structuredClone(snapshot);
+}
+
+function deliveryKey(sourceAgentId: string, sourceTurnId: string): string {
+  return `${sourceAgentId}\u0000${sourceTurnId}`;
+}
+
+/** Replay root-session-wide registry entries, starting from the latest complete checkpoint. */
+export function replayRegistryEntries(
+  entries: readonly RegistryEntryLike[],
+  rootSessionId: string,
+): RegistrySnapshot {
+  const events = entries
+    .filter((entry) => entry.type === "custom" && entry.customType === REGISTRY_ENTRY_TYPE)
+    .map((entry) => entry.data)
+    .filter((data): data is RegistryEventV1 => isRegistryEvent(data, rootSessionId));
+  let checkpointIndex = -1;
+  for (let index = events.length - 1; index >= 0; index--) {
+    if (events[index]?.event === "checkpoint") {
+      checkpointIndex = index;
+      break;
+    }
+  }
+
+  let snapshot: RegistrySnapshot = { agents: [], tombstones: [], deliveries: [] };
+  if (checkpointIndex >= 0) {
+    snapshot = cloneSnapshot((events[checkpointIndex] as RegistryCheckpointV1).snapshot);
+  }
+  const agents = new Map(snapshot.agents.map((agent) => [agent.agent_id, agent]));
+  const tombstones = new Set(snapshot.tombstones);
+  const deliveries = new Map(
+    snapshot.deliveries.map((delivery) => [
+      deliveryKey(delivery.source_agent_id, delivery.source_turn_id),
+      delivery,
+    ]),
+  );
+
+  for (const event of events.slice(checkpointIndex + 1)) {
+    switch (event.event) {
+      case "checkpoint": {
+        snapshot = cloneSnapshot(event.snapshot);
+        agents.clear();
+        for (const agent of snapshot.agents) agents.set(agent.agent_id, agent);
+        tombstones.clear();
+        for (const agentId of snapshot.tombstones) tombstones.add(agentId);
+        deliveries.clear();
+        for (const delivery of snapshot.deliveries) {
+          deliveries.set(deliveryKey(delivery.source_agent_id, delivery.source_turn_id), delivery);
+        }
+        break;
+      }
+      case "agent-created":
+        if (!tombstones.has(event.agent.agent_id))
+          agents.set(event.agent.agent_id, structuredClone(event.agent));
+        break;
+      case "turn-started": {
+        const agent = agents.get(event.agent_id);
+        if (agent) {
+          agent.active_turn_id = event.turn_id;
+          agent.active_turn_started_at = event.started_at;
+        }
+        break;
+      }
+      case "turn-settled": {
+        const agent = agents.get(event.result.agent_id);
+        if (agent) {
+          agent.active_turn_id = undefined;
+          agent.active_turn_started_at = undefined;
+          agent.latest_result = structuredClone(event.result);
+        }
+        break;
+      }
+      case "delivery-pending":
+        deliveries.set(
+          deliveryKey(event.delivery.source_agent_id, event.delivery.source_turn_id),
+          structuredClone(event.delivery),
+        );
+        break;
+      case "delivery-settled": {
+        const delivery = deliveries.get(deliveryKey(event.source_agent_id, event.source_turn_id));
+        if (delivery) {
+          delivery.settled = event.error === undefined;
+          delivery.error = event.error;
+        }
+        break;
+      }
+      case "agent-deleted":
+        for (const agentId of event.agent_ids) {
+          agents.delete(agentId);
+          tombstones.add(agentId);
+        }
+        break;
+    }
+  }
+
+  return {
+    agents: [...agents.values()],
+    tombstones: [...tombstones],
+    deliveries: [...deliveries.values()],
+  };
+}