@gotgenes/pi-subagents 2.0.0 → 4.0.0

package/src/service-adapter.ts

@@ -0,0 +1,130 @@
+/**
+ * service-adapter.ts — Adapter that wraps AgentManager to satisfy SubagentsService.
+ *
+ * Handles model resolution at the API boundary, record serialization
+ * (stripping non-serializable fields), and session gating.
+ */
+
+import type { ModelRegistry } from "./model-resolver.js";
+import type { SubagentRecord, SubagentsService } from "./service.js";
+import type { AgentRecord } from "./types.js";
+
+/** Narrow interface for the AgentManager — avoids coupling to the concrete class. */
+export interface AgentManagerLike {
+  spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: unknown): string;
+  getRecord(id: string): AgentRecord | undefined;
+  listAgents(): AgentRecord[];
+  abort(id: string): boolean;
+  waitForAll(): Promise<void>;
+  hasRunning(): boolean;
+}
+
+/** Dependencies injected into the adapter factory. */
+export interface AdapterDeps {
+  manager: AgentManagerLike;
+  resolveModel: (input: string, registry: ModelRegistry) => unknown | string;
+  getCtx: () => { pi: unknown; ctx: unknown } | undefined;
+  getModelRegistry: () => ModelRegistry | undefined;
+}
+
+/** Create a SubagentsService backed by the given dependencies. */
+export function createSubagentsService(deps: AdapterDeps): SubagentsService {
+  const { manager } = deps;
+
+  return {
+    spawn(type: string, prompt: string, options?) {
+      const session = deps.getCtx();
+      if (!session) {
+        throw new Error("No active session — cannot spawn agents outside a session.");
+      }
+
+      let model: unknown;
+      if (options?.model) {
+        const registry = deps.getModelRegistry();
+        if (!registry) {
+          throw new Error("No model registry available.");
+        }
+        const resolved = deps.resolveModel(options.model, registry);
+        if (typeof resolved === "string") {
+          throw new Error(resolved);
+        }
+        model = resolved;
+      }
+
+      const description = options?.description ?? prompt.slice(0, 80);
+      const isBackground = !(options?.foreground ?? false);
+
+      return manager.spawn(session.pi, session.ctx, type, prompt, {
+        description,
+        model,
+        maxTurns: options?.maxTurns,
+        thinkingLevel: options?.thinkingLevel,
+        isolated: options?.isolated,
+        inheritContext: options?.inheritContext,
+        bypassQueue: options?.bypassQueue,
+        isolation: options?.isolation,
+        isBackground,
+      });
+    },
+
+    getRecord(id: string): SubagentRecord | undefined {
+      const record = manager.getRecord(id);
+      return record ? toSubagentRecord(record) : undefined;
+    },
+
+    listAgents(): SubagentRecord[] {
+      return manager.listAgents().map(toSubagentRecord);
+    },
+
+    abort(id: string): boolean {
+      return manager.abort(id);
+    },
+
+    async steer(id: string, message: string): Promise<boolean> {
+      const record = manager.getRecord(id);
+      if (!record || record.status !== "running") {
+        return false;
+      }
+      if (!record.session) {
+        // Session not ready yet — queue for delivery once initialized
+        if (!record.pendingSteers) record.pendingSteers = [];
+        record.pendingSteers.push(message);
+        return true;
+      }
+      await record.session.steer(message);
+      return true;
+    },
+
+    async waitForAll(): Promise<void> {
+      return manager.waitForAll();
+    },
+
+    hasRunning(): boolean {
+      return manager.hasRunning();
+    },
+  };
+}
+
+/**
+ * Convert an internal AgentRecord to a serializable SubagentRecord.
+ * Uses an explicit allowlist — new fields must be opted in.
+ */
+export function toSubagentRecord(record: AgentRecord): SubagentRecord {
+  const out: SubagentRecord = {
+    id: record.id,
+    type: record.type,
+    description: record.description,
+    status: record.status,
+    toolUses: record.toolUses,
+    startedAt: record.startedAt,
+    lifetimeUsage: record.lifetimeUsage,
+    compactionCount: record.compactionCount,
+  };
+
+  if (record.result !== undefined) out.result = record.result;
+  if (record.error !== undefined) out.error = record.error;
+  if (record.completedAt !== undefined) out.completedAt = record.completedAt;
+  if (record.worktreeResult !== undefined) out.worktreeResult = record.worktreeResult;
+
+  return out;
+}

package/src/service.ts

@@ -0,0 +1,104 @@
+/**
+ * service.ts — Public API surface for cross-extension access to subagents.
+ *
+ * Consumers declare this package as an optional peer dependency and use
+ * dynamic import to access the accessor functions:
+ *
+ *   const { getSubagentsService } = await import("@gotgenes/pi-subagents");
+ *   const svc = getSubagentsService();
+ *   svc?.spawn("Explore", "Check for stale TODOs");
+ */
+
+import type { LifetimeUsage } from "./usage.js";
+
+export type { LifetimeUsage };
+
+export type SubagentStatus =
+  | "queued"
+  | "running"
+  | "completed"
+  | "steered"
+  | "aborted"
+  | "stopped"
+  | "error";
+
+/** Serializable snapshot of an agent's state — no live session objects. */
+export interface SubagentRecord {
+  id: string;
+  type: string;
+  description: string;
+  status: SubagentStatus;
+  result?: string;
+  error?: string;
+  toolUses: number;
+  startedAt: number;
+  completedAt?: number;
+  lifetimeUsage: LifetimeUsage;
+  compactionCount: number;
+  worktreeResult?: { hasChanges: boolean; branch?: string };
+}
+
+/** Options for spawning an agent via the service. */
+export interface SpawnOptions {
+  description?: string;
+  model?: string;
+  maxTurns?: number;
+  thinkingLevel?: string;
+  isolated?: boolean;
+  inheritContext?: boolean;
+  foreground?: boolean;
+  bypassQueue?: boolean;
+  isolation?: "worktree";
+}
+
+/** The public service contract for cross-extension subagent access. */
+export interface SubagentsService {
+  /** Spawn an agent. Returns the agent ID immediately. */
+  spawn(type: string, prompt: string, options?: SpawnOptions): string;
+
+  /** Get a snapshot of an agent's current state. */
+  getRecord(id: string): SubagentRecord | undefined;
+
+  /** List all tracked agents, most recent first. */
+  listAgents(): SubagentRecord[];
+
+  /** Abort a running or queued agent. Returns false if not found. */
+  abort(id: string): boolean;
+
+  /** Send a steering message to a running agent. */
+  steer(id: string, message: string): Promise<boolean>;
+
+  /** Wait for all running and queued agents to complete. */
+  waitForAll(): Promise<void>;
+
+  /** Whether any agents are running or queued. */
+  hasRunning(): boolean;
+}
+
+/** Event channel constants for pi.events subscriptions. */
+export const SUBAGENT_EVENTS = {
+  STARTED: "subagents:started",
+  COMPLETED: "subagents:completed",
+  ACTIVITY: "subagents:activity",
+} as const;
+
+// ---- Accessor functions ----
+
+const SERVICE_KEY = Symbol.for("@gotgenes/pi-subagents:service");
+
+/** Publish the SubagentsService on globalThis for cross-extension access. */
+export function publishSubagentsService(service: SubagentsService): void {
+  (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
+}
+
+/** Retrieve the published SubagentsService, or undefined if not yet published. */
+export function getSubagentsService(): SubagentsService | undefined {
+  return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as
+    | SubagentsService
+    | undefined;
+}
+
+/** Remove the SubagentsService from globalThis (call on shutdown/reload). */
+export function unpublishSubagentsService(): void {
+  delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
+}

package/src/settings.ts

@@ -5,8 +5,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import type { JoinMode } from "./types.js";
-
 export interface SubagentsSettings {
   maxConcurrent?: number;
   /**
@@ -16,7 +14,6 @@ export interface SubagentsSettings {
    */
   defaultMaxTurns?: number;
   graceTurns?: number;
-  defaultJoinMode?: JoinMode;
 }
 
 /** Setter hooks used by applySettings to wire persisted values into in-memory state. */
@@ -24,14 +21,11 @@ export interface SettingsAppliers {
   setMaxConcurrent: (n: number) => void;
   setDefaultMaxTurns: (n: number) => void;
   setGraceTurns: (n: number) => void;
-  setDefaultJoinMode: (mode: JoinMode) => void;
 }
 
 /** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
 export type SettingsEmit = (event: string, payload: unknown) => void;
 
-const VALID_JOIN_MODES: ReadonlySet<string> = new Set<JoinMode>(["async", "group", "smart"]);
-
 // Sanity ceilings — prevent hand-edited configs from asking for values that
 // make no operational sense (e.g. 1e6 concurrent subagents). Permissive enough
 // that any realistic power-user setting passes through.
@@ -65,9 +59,6 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.graceTurns = r.graceTurns as number;
   }
-  if (typeof r.defaultJoinMode === "string" && VALID_JOIN_MODES.has(r.defaultJoinMode)) {
-    out.defaultJoinMode = r.defaultJoinMode as JoinMode;
-  }
   return out;
 }
 
@@ -121,7 +112,6 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   if (typeof s.maxConcurrent === "number") appliers.setMaxConcurrent(s.maxConcurrent);
   if (typeof s.defaultMaxTurns === "number") appliers.setDefaultMaxTurns(s.defaultMaxTurns);
   if (typeof s.graceTurns === "number") appliers.setGraceTurns(s.graceTurns);
-  if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode);
 }
 
 /**

package/src/types.ts

@@ -55,8 +55,6 @@ export interface AgentConfig {
   source?: "default" | "project" | "global";
 }
 
-export type JoinMode = 'async' | 'group' | 'smart';
-
 export interface AgentRecord {
   id: string;
   type: SubagentType;
@@ -70,8 +68,6 @@ export interface AgentRecord {
   session?: AgentSession;
   abortController?: AbortController;
   promise?: Promise<string>;
-  groupId?: string;
-  joinMode?: JoinMode;
   /** Set when result was already consumed via get_subagent_result — suppresses completion notification. */
   resultConsumed?: boolean;
   /** Steering messages queued before the session was ready. */
@@ -122,8 +118,7 @@ export interface NotificationDetails {
   outputFile?: string;
   error?: string;
   resultPreview: string;
-  /** Additional agents in a group notification. */
-  others?: NotificationDetails[];
+
 }
 
 export interface EnvInfo {

package/src/cross-extension-rpc.ts

@@ -1,95 +0,0 @@
-/**
- * Cross-extension RPC handlers for the subagents extension.
- *
- * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
- * using per-request scoped reply channels.
- *
- * Reply envelope follows pi-mono convention:
- *   success → { success: true, data?: T }
- *   error   → { success: false, error: string }
- */
-
-/** Minimal event bus interface needed by the RPC handlers. */
-export interface EventBus {
-  on(event: string, handler: (data: unknown) => void): () => void;
-  emit(event: string, data: unknown): void;
-}
-
-/** RPC reply envelope — matches pi-mono's RpcResponse shape. */
-export type RpcReply<T = void> =
-  | { success: true; data?: T }
-  | { success: false; error: string };
-
-/** RPC protocol version — bumped when the envelope or method contracts change. */
-export const PROTOCOL_VERSION = 2;
-
-/** Minimal AgentManager interface needed by the spawn/stop RPCs. */
-export interface SpawnCapable {
-  spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: any): string;
-  abort(id: string): boolean;
-}
-
-export interface RpcDeps {
-  events: EventBus;
-  pi: unknown;                    // passed through to manager.spawn
-  getCtx: () => unknown | undefined;  // returns current ExtensionContext
-  manager: SpawnCapable;
-}
-
-export interface RpcHandle {
-  unsubPing: () => void;
-  unsubSpawn: () => void;
-  unsubStop: () => void;
-}
-
-/**
- * Wire a single RPC handler: listen on `channel`, run `fn(params)`,
- * emit the reply envelope on `channel:reply:${requestId}`.
- */
-function handleRpc<P extends { requestId: string }>(
-  events: EventBus,
-  channel: string,
-  fn: (params: P) => unknown | Promise<unknown>,
-): () => void {
-  return events.on(channel, async (raw: unknown) => {
-    const params = raw as P;
-    try {
-      const data = await fn(params);
-      const reply: { success: true; data?: unknown } = { success: true };
-      if (data !== undefined) reply.data = data;
-      events.emit(`${channel}:reply:${params.requestId}`, reply);
-    } catch (err: any) {
-      events.emit(`${channel}:reply:${params.requestId}`, {
-        success: false, error: err?.message ?? String(err),
-      });
-    }
-  });
-}
-
-/**
- * Register ping, spawn, and stop RPC handlers on the event bus.
- * Returns unsub functions for cleanup.
- */
-export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
-  const { events, pi, getCtx, manager } = deps;
-
-  const unsubPing = handleRpc(events, "subagents:rpc:ping", () => {
-    return { version: PROTOCOL_VERSION };
-  });
-
-  const unsubSpawn = handleRpc<{ requestId: string; type: string; prompt: string; options?: any }>(
-    events, "subagents:rpc:spawn", ({ type, prompt, options }) => {
-      const ctx = getCtx();
-      if (!ctx) throw new Error("No active session");
-      return { id: manager.spawn(pi, ctx, type, prompt, options ?? {}) };
-    },
-  );
-
-  const unsubStop = handleRpc<{ requestId: string; agentId: string }>(
-    events, "subagents:rpc:stop", ({ agentId }) => {
-      if (!manager.abort(agentId)) throw new Error("Agent not found");
-    },
-  );
-
-  return { unsubPing, unsubSpawn, unsubStop };
-}

package/src/group-join.ts

@@ -1,141 +0,0 @@
-/**
- * group-join.ts — Manages grouped background agent completion notifications.
- *
- * Instead of each agent individually nudging the main agent on completion,
- * agents in a group are held until all complete (or a timeout fires),
- * then a single consolidated notification is sent.
- */
-
-import type { AgentRecord } from "./types.js";
-
-export type DeliveryCallback = (records: AgentRecord[], partial: boolean) => void;
-
-interface AgentGroup {
-  groupId: string;
-  agentIds: Set<string>;
-  completedRecords: Map<string, AgentRecord>;
-  timeoutHandle?: ReturnType<typeof setTimeout>;
-  delivered: boolean;
-  /** Shorter timeout for stragglers after a partial delivery. */
-  isStraggler: boolean;
-}
-
-/** Default timeout: 30s after first completion in a group. */
-const DEFAULT_TIMEOUT = 30_000;
-/** Straggler re-batch timeout: 15s. */
-const STRAGGLER_TIMEOUT = 15_000;
-
-export class GroupJoinManager {
-  private groups = new Map<string, AgentGroup>();
-  private agentToGroup = new Map<string, string>();
-
-  constructor(
-    private deliverCb: DeliveryCallback,
-    private groupTimeout = DEFAULT_TIMEOUT,
-  ) {}
-
-  /** Register a group of agent IDs that should be joined. */
-  registerGroup(groupId: string, agentIds: string[]): void {
-    const group: AgentGroup = {
-      groupId,
-      agentIds: new Set(agentIds),
-      completedRecords: new Map(),
-      delivered: false,
-      isStraggler: false,
-    };
-    this.groups.set(groupId, group);
-    for (const id of agentIds) {
-      this.agentToGroup.set(id, groupId);
-    }
-  }
-
-  /**
-   * Called when an agent completes.
-   * Returns:
-   * - 'pass'      — agent is not grouped, caller should send individual nudge
-   * - 'held'      — result held, waiting for group completion
-   * - 'delivered'  — this completion triggered the group notification
-   */
-  onAgentComplete(record: AgentRecord): 'delivered' | 'held' | 'pass' {
-    const groupId = this.agentToGroup.get(record.id);
-    if (!groupId) return 'pass';
-
-    const group = this.groups.get(groupId);
-    if (!group || group.delivered) return 'pass';
-
-    group.completedRecords.set(record.id, record);
-
-    // All done — deliver immediately
-    if (group.completedRecords.size >= group.agentIds.size) {
-      this.deliver(group, false);
-      return 'delivered';
-    }
-
-    // First completion in this batch — start timeout
-    if (!group.timeoutHandle) {
-      const timeout = group.isStraggler ? STRAGGLER_TIMEOUT : this.groupTimeout;
-      group.timeoutHandle = setTimeout(() => {
-        this.onTimeout(group);
-      }, timeout);
-    }
-
-    return 'held';
-  }
-
-  private onTimeout(group: AgentGroup): void {
-    if (group.delivered) return;
-    group.timeoutHandle = undefined;
-
-    // Partial delivery — some agents still running
-    const remaining = new Set<string>();
-    for (const id of group.agentIds) {
-      if (!group.completedRecords.has(id)) remaining.add(id);
-    }
-
-    // Clean up agentToGroup for delivered agents (they won't complete again)
-    for (const id of group.completedRecords.keys()) {
-      this.agentToGroup.delete(id);
-    }
-
-    // Deliver what we have
-    this.deliverCb([...group.completedRecords.values()], true);
-
-    // Set up straggler group for remaining agents
-    group.completedRecords.clear();
-    group.agentIds = remaining;
-    group.isStraggler = true;
-    // Timeout will be started when the next straggler completes
-  }
-
-  private deliver(group: AgentGroup, partial: boolean): void {
-    if (group.timeoutHandle) {
-      clearTimeout(group.timeoutHandle);
-      group.timeoutHandle = undefined;
-    }
-    group.delivered = true;
-    this.deliverCb([...group.completedRecords.values()], partial);
-    this.cleanupGroup(group.groupId);
-  }
-
-  private cleanupGroup(groupId: string): void {
-    const group = this.groups.get(groupId);
-    if (!group) return;
-    for (const id of group.agentIds) {
-      this.agentToGroup.delete(id);
-    }
-    this.groups.delete(groupId);
-  }
-
-  /** Check if an agent is in a group. */
-  isGrouped(agentId: string): boolean {
-    return this.agentToGroup.has(agentId);
-  }
-
-  dispose(): void {
-    for (const group of this.groups.values()) {
-      if (group.timeoutHandle) clearTimeout(group.timeoutHandle);
-    }
-    this.groups.clear();
-    this.agentToGroup.clear();
-  }
-}