pi-extended-teams 2.3.0 → 2.3.2

package/extensions/runtime/team-host.ts

@@ -0,0 +1,124 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+type Handler = (...args: any[]) => any;
+export interface TeamHostBinding { pi: ExtensionAPI; ctx: any; event: any }
+
+// Explicit root-facing capabilities used by the execution owner. This is not
+// an ExtensionAPI proxy: registrations are data, and detached sends are kept
+// separate from native agent work and its raw delivery promises.
+export function createTeamHost() {
+  let binding: TeamHostBinding | undefined;
+  let generation = 0;
+  let ready = false;
+  let closed = false;
+  const handlers = new Map<string, Handler[]>();
+  const tools = new Map<string, any>();
+  const shortcuts = new Map<string, any>();
+  const subscriptions = new Set<{ name: string; handler: Handler; unsubscribe?: () => void }>();
+  const pending: Array<(pi: ExtensionAPI) => void> = [];
+  const waiters = new Set<{ resolve(): void; reject(error: Error): void }>();
+  const current = () => {
+    if (!binding) throw new Error("The team host is detached during reload.");
+    return binding;
+  };
+  function send(action: (pi: ExtensionAPI) => void) {
+    if (binding && ready) action(binding.pi);
+    else if (!closed) pending.push(action);
+  }
+  const api = {
+    on(name: string, handler: Handler) { handlers.set(name, [...(handlers.get(name) ?? []), handler]); },
+    registerTool(tool: any) { tools.set(tool.name, tool); },
+    registerCommand() {},
+    registerShortcut(key: string, shortcut: any) { shortcuts.set(key, shortcut); },
+    getCommands: () => current().pi.getCommands(),
+    getAllTools: () => current().pi.getAllTools(),
+    appendEntry: (...args: Parameters<ExtensionAPI["appendEntry"]>) => current().pi.appendEntry(...args),
+    sendUserMessage: (...args: Parameters<ExtensionAPI["sendUserMessage"]>) => send(pi => pi.sendUserMessage(...args)),
+    sendMessage: (...args: Parameters<ExtensionAPI["sendMessage"]>) => send(pi => {
+      if (typeof pi.sendMessage === "function") pi.sendMessage(...args);
+      else pi.sendUserMessage(args[0].content);
+    }),
+    events: {
+      emit(name: string, payload: unknown) { send(pi => pi.events.emit(name, payload)); },
+      on(name: string, handler: Handler) {
+        const subscription = { name, handler, unsubscribe: binding?.pi.events.on(name, handler) };
+        subscriptions.add(subscription);
+        return () => { subscription.unsubscribe?.(); subscriptions.delete(subscription); };
+      },
+    },
+  };
+  function detach() {
+    ready = false;
+    binding = undefined;
+    generation++;
+    for (const subscription of subscriptions) {
+      subscription.unsubscribe?.();
+      subscription.unsubscribe = undefined;
+    }
+  }
+  function snapshot(ctx: any) {
+    const epoch = generation;
+    const available = () => binding && generation === epoch;
+    const ui: Record<string, unknown> = {};
+    for (const name of ["notify", "setStatus", "setWidget", "setTitle", "setEditorComponent", "setWorkingMessage", "setHeader", "setFooter"]) {
+      ui[name] = (...args: unknown[]) => { if (available()) return binding!.ctx.ui?.[name]?.(...args); };
+    }
+    for (const name of ["custom", "select", "confirm", "input", "editor", "getEditorComponent", "getToolsExpanded"]) {
+      ui[name] = (...args: unknown[]) => { if (available()) return binding!.ctx.ui?.[name]?.(...args); };
+    }
+    Object.defineProperty(ui, "theme", { get: () => available() ? binding!.ctx.ui?.theme : undefined });
+    const trusted = ctx.isProjectTrusted?.() === true;
+    return {
+      cwd: ctx.cwd, sessionManager: ctx.sessionManager, modelRegistry: ctx.modelRegistry,
+      model: ctx.model, thinkingLevel: ctx.thinkingLevel, hasUI: ctx.hasUI, mode: ctx.mode, ui,
+      isProjectTrusted: () => trusted,
+      isIdle: () => available() ? binding!.ctx.isIdle() : false,
+      getContextUsage: () => available() ? binding!.ctx.getContextUsage?.() : undefined,
+      getSystemPrompt: () => available() ? binding!.ctx.getSystemPrompt?.() : "",
+      shutdown: () => { if (available()) return binding!.ctx.shutdown(); },
+    };
+  }
+  return {
+    api, tools, shortcuts, snapshot,
+    get attached() { return !!binding; },
+    get ready() { return ready && !!binding; },
+    get context() { return binding ? snapshot(binding.ctx) : undefined; },
+    attach(next: TeamHostBinding) {
+      if (closed) throw new Error("The team execution owner is closing.");
+      binding = next;
+      ready = false;
+      generation++;
+      for (const subscription of subscriptions) subscription.unsubscribe = next.pi.events.on(subscription.name, subscription.handler);
+    },
+    detach,
+    async emit(name: string, event: any, ctx: any) {
+      let result: any;
+      for (const handler of handlers.get(name) ?? []) {
+        const value = await handler(event, ctx);
+        if (value !== undefined) result = value;
+      }
+      return result;
+    },
+    flush() {
+      ready = !!binding && !closed;
+      while (ready && binding && pending.length) {
+        const action = pending.shift()!;
+        // Remove before invoking: a thrown/uncertain host send is not replayed.
+        try { action(binding.pi); }
+        catch (error) { binding.ctx.ui?.notify?.(`Team delivery needs attention: ${String(error)}. Read the saved inbox/reports.`, "warning"); }
+      }
+      if (binding) { for (const waiter of waiters) waiter.resolve(); waiters.clear(); }
+    },
+    whenAttached(): Promise<void> {
+      if (closed) return Promise.reject(new Error("Team execution is closing."));
+      if (binding && ready) return Promise.resolve();
+      return new Promise((resolve, reject) => waiters.add({ resolve, reject }));
+    },
+    close() {
+      closed = true;
+      detach();
+      for (const waiter of waiters) waiter.reject(new Error("Team reload recovery expired or the session closed."));
+      waiters.clear();
+    },
+  };
+}

package/extensions/team/session-cost.ts

@@ -7,6 +7,8 @@ export interface CostRun {
   settle(snapshot: AgentCostSnapshot | undefined, outcome: CostOutcome): void;
   exclude(): void;
 }
+export type SessionCostContext = Pick<ExtensionContext, "sessionManager">;
+type CostHost = Pick<ExtensionAPI, "on" | "appendEntry" | "events">;
 interface Receipt {
   rootSessionId: string;
   teamName: string;
@@ -16,6 +18,11 @@ interface Receipt {
   costUsd?: number | null;
   outcome?: CostOutcome;
 }
+interface Scope {
+  root: string;
+  failed: Set<string>;
+  pending: Map<string, Receipt>;
+}
 const object = (value: unknown): Record<string, unknown> =>
   value !== null && typeof value === "object" ? value as Record<string, unknown> : {};
 const validCost = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
@@ -40,8 +47,13 @@ export function recordedSessionCost(entries: readonly unknown[]): { usd: number;
   return { usd, complete };
 }
 
-export function createCombinedSessionCost(pi: Pick<ExtensionAPI, "on" | "appendEntry" | "events">) {
-  let scope: { root: string; ctx: ExtensionContext; failed: Set<string>; pending: Map<string, Receipt> } | undefined;
+export function createCombinedSessionCost(initialHost: CostHost) {
+  let scope: Scope | undefined;
+  let host: CostHost | undefined;
+  let context: SessionCostContext | undefined;
+  let displayTotal: ReturnType<typeof recordedSessionCost> | undefined;
+  let unsubscribeDisplay: (() => void) | undefined;
+  let listenerGeneration = 0;
   const receipts = (entries: readonly unknown[]) => {
     const runs = new Map<string, Receipt>();
     let complete = true;
@@ -62,10 +74,11 @@ export function createCombinedSessionCost(pi: Pick<ExtensionAPI, "on" | "appendE
     }
     return { runs, complete };
   };
+  const active = () => !!scope && !!host && !!context && context.sessionManager.getSessionId() === scope.root;
   const total = () => {
     try {
-      if (!scope || scope.ctx.sessionManager.getSessionId() !== scope.root) return { usd: 0, complete: false };
-      const entries = scope.ctx.sessionManager.getEntries();
+      if (!active() || !scope || !context) return { usd: 0, complete: false };
+      const entries = context.sessionManager.getEntries();
       const own = recordedSessionCost(entries);
       const replay = receipts(entries);
       let complete = own.complete && replay.complete && scope.failed.size === 0;
@@ -85,65 +98,122 @@ export function createCombinedSessionCost(pi: Pick<ExtensionAPI, "on" | "appendE
       return { usd, complete };
     } catch { return { usd: 0, complete: false }; }
   };
-  let displayTotal: ReturnType<typeof recordedSessionCost> | undefined;
-  // Synchronous display-only query: native usage and durable receipts stay untouched.
-  const unsubscribe = pi.events.on("pi-extended-teams:cost-request", (value) => {
-    const request = object(value);
-    if (scope && request.sessionId === scope.root && scope.ctx.sessionManager.getSessionId() === scope.root) {
-      request.result = displayTotal;
-    }
-  });
   const refresh = () => {
-    displayTotal = scope ? total() : undefined;
-    try { pi.events.emit("pi-extended-teams:cost-changed", undefined); }
+    if (!host) {
+      displayTotal = undefined;
+      return;
+    }
+    displayTotal = total();
+    try { host.events.emit("pi-extended-teams:cost-changed", undefined); }
     catch { /* Display observers must not affect lifecycle cleanup. */ }
   };
-  pi.on("session_start", (_event, ctx) => {
-    scope = { root: ctx.sessionManager.getSessionId(), ctx, failed: new Set(), pending: new Map() };
-    refresh();
-  });
-  pi.on("turn_end", refresh);
-  pi.on("agent_end", refresh);
-  pi.on("session_compact", refresh);
-  pi.on("session_tree", refresh);
+  const append = (origin: Scope, key: string, receipt: Receipt) => {
+    if (!active() || scope !== origin || !host) return false;
+    try {
+      host.appendEntry(COST_ENTRY_TYPE, receipt);
+      origin.failed.delete(key);
+      origin.pending.delete(key);
+      refresh();
+      return true;
+    } catch {
+      // Keep the terminal receipt, not its pending predecessor, for reload retry.
+      origin.failed.add(key);
+      origin.pending.set(key, receipt);
+      refresh();
+      return false;
+    }
+  };
+  const listen = (nextHost: CostHost) => {
+    host = nextHost;
+    const generation = ++listenerGeneration;
+    unsubscribeDisplay = nextHost.events.on("pi-extended-teams:cost-request", (value) => {
+      const request = object(value);
+      if (generation === listenerGeneration && scope && context && request.sessionId === scope.root
+        && context.sessionManager.getSessionId() === scope.root) request.result = displayTotal;
+    });
+    nextHost.on("session_start", (_event, nextContext) => {
+      if (generation !== listenerGeneration) return;
+      const root = nextContext.sessionManager.getSessionId();
+      if (!scope || scope.root !== root) scope = { root, failed: new Set(), pending: new Map() };
+      context = nextContext;
+      refresh();
+    });
+    const refreshCurrent = () => { if (generation === listenerGeneration) refresh(); };
+    nextHost.on("turn_end", refreshCurrent);
+    nextHost.on("agent_end", refreshCurrent);
+    nextHost.on("session_compact", refreshCurrent);
+    nextHost.on("session_tree", refreshCurrent);
+  };
+  const flushFinalReceipts = () => {
+    if (!scope || !context) return;
+    const durable = receipts(context.sessionManager.getEntries()).runs;
+    for (const [key, receipt] of scope.pending) {
+      if (receipt.phase === "pending") continue;
+      const persisted = durable.get(key);
+      if (persisted && persisted.phase !== "pending") {
+        scope.pending.delete(key);
+        scope.failed.delete(key);
+      } else append(scope, key, receipt);
+    }
+  };
+  const detach = () => {
+    listenerGeneration++;
+    unsubscribeDisplay?.();
+    unsubscribeDisplay = undefined;
+    host = undefined;
+    context = undefined;
+    displayTotal = undefined;
+  };
+  listen(initialHost);
   return {
     total,
+    // The reload owner must pass the newly supplied context for this saved root; other roots are never adopted.
+    attach(nextHost: CostHost, nextContext: SessionCostContext) {
+      try {
+        if (!scope || scope.root !== nextContext.sessionManager.getSessionId()) return false;
+      } catch { return false; }
+      detach();
+      context = nextContext;
+      listen(nextHost);
+      try { flushFinalReceipts(); }
+      catch { refresh(); }
+      refresh();
+      return true;
+    },
+    detach,
     deactivate() {
+      detach();
       scope = undefined;
-      unsubscribe();
-      refresh();
     },
     begin(rootSessionId: string, teamName: string, lifecycleRunId: string): CostRun {
       const origin = scope;
       if (!origin || origin.root !== rootSessionId) return { settle() {}, exclude() {} };
       const pending: Receipt = { rootSessionId, teamName, lifecycleRunId, phase: "pending" };
       const key = identity(pending);
-      const active = () => scope === origin && origin.ctx.sessionManager.getSessionId() === rootSessionId;
-      const append = (receipt: Receipt) => {
-        try {
-          if (!active()) return false;
-          pi.appendEntry(COST_ENTRY_TYPE, receipt);
-          origin.failed.delete(key);
-          origin.pending.delete(key);
-          refresh();
-          return true;
-        } catch {
-          origin.failed.add(key);
-          origin.pending.set(key, pending);
-          refresh();
-          return false;
+      if (!origin.pending.has(key)) {
+        if (!context) origin.pending.set(key, pending);
+        else {
+          try {
+            if (!receipts(context.sessionManager.getEntries()).runs.has(key)) append(origin, key, pending);
+          } catch { origin.failed.add(key); origin.pending.set(key, pending); refresh(); }
         }
-      };
-      try {
-        if (!receipts(origin.ctx.sessionManager.getEntries()).runs.has(key)) append(pending);
-      } catch { origin.failed.add(key); origin.pending.set(key, pending); refresh(); }
+      }
       const finish = (receipt: Receipt) => {
+        if (scope !== origin) return;
+        const previous = origin.pending.get(key);
+        if (!active() || !context) {
+          if (!previous || previous.phase === "pending") {
+            origin.failed.add(key);
+            origin.pending.set(key, receipt);
+          }
+          return;
+        }
         try {
-          if (!active()) return;
-          const previous = origin.pending.get(key) ?? receipts(origin.ctx.sessionManager.getEntries()).runs.get(key);
-          if (previous?.phase !== "pending") return;
-          append(receipt);
-        } catch { origin.failed.add(key); refresh(); }
+          const durable = receipts(context.sessionManager.getEntries()).runs.get(key);
+          const current = previous ?? durable;
+          if (current?.phase !== "pending") return;
+          append(origin, key, receipt);
+        } catch { origin.failed.add(key); origin.pending.set(key, receipt); refresh(); }
       };
       return {
         settle: (snapshot, outcome) => finish({ ...pending, phase: "final", outcome,

package/extensions/tools/public-team-tools.ts

@@ -0,0 +1,51 @@
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "../internal/schema";
+import { ACCEPTED_FAVORITE_MODEL_SLOTS } from "../../src/utils/settings";
+import { CheckPolicySchema } from "../../src/results/check-policy";
+import { RepairPolicySchema } from "../../src/results/repair-policy";
+import { CheckpointPolicySchema } from "../../src/results/checkpoint-policy";
+import { CompletionGroupPolicySchema } from "../../src/results/completion-group";
+
+const levelDescription = "Required intent tier. Configured favorites take priority; an unconfigured tier inherits the current lead model and thinking. Read tiers: read-collect gathers bounded facts without owning the conclusion; read-review is the normal default for focused review, verification, and bounded synthesis; read-analyze explains behavior or root cause across connected evidence; read-critical is only for irreducible high-stakes security, architecture, concurrency, migration, or data-correctness reasoning. Write tiers: write-patch makes a narrow localized change; write-feature implements a bounded feature with a known design; write-system owns a cross-cutting integration or refactor within explicitly claimed files; write-critical is only for high-risk security, concurrency, recovery, migration, or data-integrity changes. Prefer canonical tiers; legacy reading-*/writing-* aliases remain accepted for this minor release. Do not pass role, model, or thinking directly; see README.md.";
+const base = {
+  name: Type.Optional(Type.String({ description: "Stable display name. Defaults to a generated agent name." })),
+  prompt: Type.String({ description: "The agent's assignment, relevant prior context, evidence already gathered, constraints, and report shape." }),
+  cwd: Type.Optional(Type.String({ description: "Working directory. Defaults to the lead session cwd." })),
+  checks: Type.Optional(CheckPolicySchema),
+  repair: Type.Optional(RepairPolicySchema),
+  checkpoint: Type.Optional(CheckpointPolicySchema),
+  continue_from: Type.Optional(Type.String({ description: "Continue this checkpoint as a fresh recipient/run with the current assignment and tier. name is a prefix, not a recipient to reuse." })),
+  session_context: Type.Optional(StringEnum(["none", "lazy"] as const, { description: "Optional filtered snapshot of the lead's active session branch. Use lazy only when omitted session history may materially affect the lane; the child reads it on demand rather than receiving transcript content in its prompt.", default: "none" })),
+  metadata: Type.Optional(Type.Record(Type.String(), Type.Any())),
+  allow_nested_read_agents: Type.Optional(Type.Boolean({ description: "Opt in eligible depth-0 write-feature/write-critical agents to restricted read-only child spawning.", default: false })),
+};
+
+// Metadata is available before session_start without creating a second queue,
+// lifecycle controller, or execution owner during host reload.
+export const publicTeamToolMetadata = {
+  get_agent_status: {
+    name: "get_agent_status", label: "Get Agent Status",
+    description: "Get one read-only snapshot of one or all agents owned by this parent. Omit agent_name to inspect all. This call is allowed when current status is needed; it never waits, polls, stops, or changes agents. Do not call it repeatedly. Final reports arrive automatically and resume this agent.",
+    parameters: Type.Object({ agent_name: Type.Optional(Type.String({ description: "One owned agent to inspect. Omit to inspect all owned agents." })) }),
+  },
+  spawn_agent: {
+    name: "spawn_agent", label: "Spawn Agent",
+    description: "Spawn one agent by intent tier only. Configured favorites take priority; an unconfigured tier inherits the current lead model and thinking. Give it the relevant goal, decisions, prior attempts, inspected evidence, constraints, and expected delta rather than a context-free task. Use session_context=lazy only as an on-demand fallback when omitted session history may materially matter; it never replaces a good mission prompt. read-review is the normal read default; use read-collect for bounded fact gathering, read-analyze for connected explanation/root cause, and read-critical only for irreducible high-stakes reasoning. For edits, choose write-patch, write-feature, write-system, or the rare high-risk write-critical by scope and risk. After spawning, do not duplicate or take over its lane; work only on unrelated work, then end the turn so the automatic report can resume you. One get_agent_status snapshot is allowed when current status is needed; never sleep, busy-wait, repeatedly read inbox/status, or treat healthy silence as failure. Wait for the actual report before synthesizing; intervene only on a reported blocker/error, actual health failure, or explicit user cancellation. model_slot selects behavior, model, and thinking; do not pass role, model, or thinking directly.",
+    parameters: Type.Object({ ...base, model_slot: StringEnum(ACCEPTED_FAVORITE_MODEL_SLOTS, { description: levelDescription, default: "read-review" }) }),
+  },
+  spawn_swarm_agents: {
+    name: "spawn_swarm_agents", label: "Spawn Swarm Agents",
+    description: "Spawn a batch by intent tier only. Configured favorites take priority; unconfigured tiers inherit the current lead model and thinking. Give each lane the relevant goal, decisions, prior attempts, inspected evidence, constraints, and expected delta. Use session_context=lazy selectively as an on-demand fallback, never instead of a good mission prompt. Use read-review as the normal default, read-collect for bounded collection lanes, read-analyze for connected explanation, and read-critical only for irreducible high-stakes reasoning; choose write-patch/feature/system/critical by edit scope and risk. Each spawned lane is delegation-locked: do not duplicate or take it over. After unrelated work is done, end the turn so automatic reports can resume you. One get_agent_status snapshot is allowed when current status is needed; never sleep, busy-wait, repeatedly read inbox/status, or intervene early. Synthesize only after actual reports; intervene only on blocker/error, actual failure, or explicit cancellation. Each agent gets model_slot directly or from defaults; do not pass role, model, or thinking directly.",
+    parameters: Type.Object({
+      defaults: Type.Optional(Type.Object({
+        cwd: Type.Optional(Type.String()), checks: Type.Optional(CheckPolicySchema), repair: Type.Optional(RepairPolicySchema),
+        checkpoint: Type.Optional(CheckpointPolicySchema), model_slot: Type.Optional(StringEnum(ACCEPTED_FAVORITE_MODEL_SLOTS, { description: levelDescription })),
+        metadata: Type.Optional(Type.Record(Type.String(), Type.Any())),
+        session_context: Type.Optional(StringEnum(["none", "lazy"] as const, { description: "Shared lazy session-reference policy.", default: "none" })),
+        allow_nested_read_agents: Type.Optional(Type.Boolean({ description: "Shared opt-in for eligible depth-0 write-feature/write-critical agents.", default: false })),
+      })),
+      completion_group: Type.Optional(CompletionGroupPolicySchema),
+      agents: Type.Array(Type.Object({ ...base, model_slot: Type.Optional(StringEnum(ACCEPTED_FAVORITE_MODEL_SLOTS, { description: levelDescription })) }), { description: "Agents to spawn as one batch. Each one must have model_slot directly or inherit it from defaults." }),
+    }),
+  },
+};