@fradser/pi-agent-teams 0.8.2 → 0.9.0

package/src/types.ts

@@ -1,5 +1,6 @@
 import type { Static } from "typebox";
 import { Type } from "typebox";
+import { WORKER_BUILTIN_TOOLS } from "./worker-tools.ts";
 
 // ── Teammate ──────────────────────────────────────────────────────
 
@@ -31,6 +32,9 @@ export interface Teammate {
   agent: string;
   /** Per-spawn capability identity, regenerated for every process. */
   spawnId: string;
+  /** Stable Work Item selected by agent; each reopen creates a new assignment attempt. */
+  workId?: string;
+  context?: "fresh" | "fork";
   pid: number;
   status: TeammateStatus;
   /** Working directory (the worktree root when isolated). */
@@ -69,15 +73,13 @@ export interface Teammate {
    *  the capability set). Absent only for legacy snapshots. */
   tools?: string[];
   /** True once recognized model/stream activity was observed for this
-   * incarnation; the stall classifier uses this, not usage totals. */
+   * incarnation; console telemetry only, never a leader notification. */
   modelOutputSeen?: boolean;
   createdAt: number;
   updatedAt: number;
   stoppedAt?: number;
   /** Last wall-clock time output was observed (any stream event or prompt delivery). */
   lastOutputAt?: number;
-  /** When the current stall episode notice was sent (one per episode). */
-  stallNoticeSentAt?: number;
 }
 
 // ── Task board ────────────────────────────────────────────────────
@@ -111,6 +113,8 @@ export interface BoardTask {
   /** Replacement task that made this task obsolete. */
   supersededBy?: string;
   result?: string;
+  /** Deferred mail archived when an accepted result closes its Work Item. */
+  deferredMessages?: Array<{ from: string; subject: string; body: string; timestamp: number }>;
   errorMessage?: string;
   createdAt: number;
   updatedAt: number;
@@ -123,6 +127,7 @@ export interface TaskIntent {
   taskId: string;
   worker: string;
   spawnId: string;
+  assignmentId?: string;
   status?: "completed" | "failed";
   result?: string;
   timestamp: number;
@@ -144,10 +149,12 @@ export interface WorkerUsage {
 
 export interface MailboxMessage {
   id: string;
+  assignmentId?: string;
+  spawnId?: string;
   from: string;
   subject: string;
   body: string;
-  status?: "in_progress" | "completed" | "failed";
+  status?: "in_progress" | "completed" | "failed" | "inform" | "request" | "handoff";
   /** The harness retained this report for console inspection after shutdown;
    * it never initiated a leader follow-up. */
   archived?: boolean;
@@ -158,11 +165,12 @@ export interface MailboxMessage {
  * is derived by the harness from the first line of the body. */
 export interface WorkerReportEvent {
   id: string;
+  assignmentId?: string;
   type: "message";
   worker: string;
   spawnId: string;
   body: string;
-  status?: "in_progress" | "completed" | "failed";
+  status?: "in_progress" | "completed" | "failed" | "inform" | "request" | "handoff";
   /** Wall-clock time the teammate wrote the event. */
   timestamp?: number;
 }
@@ -178,7 +186,8 @@ export function isWorkerEvent(value: unknown): value is WorkerReportEvent {
     && typeof event.worker === "string"
     && typeof event.spawnId === "string"
     && typeof event.body === "string"
-    && (event.status === undefined || ["in_progress", "completed", "failed"].includes(event.status))
+    && (event.assignmentId === undefined || typeof event.assignmentId === "string")
+    && (event.status === undefined || ["in_progress", "completed", "failed", "inform", "request", "handoff"].includes(event.status))
     && (event.timestamp === undefined || (typeof event.timestamp === "number" && Number.isFinite(event.timestamp)));
 }
 
@@ -197,84 +206,113 @@ export interface InboxMessage {
   from: string;
   subject: string;
   body: string;
+  /** Incarnation the sender addressed. A replacement resident of the same name
+   *  must never consume mail written for its predecessor. */
+  toSpawnId?: string;
   timestamp: number;
 }
 
 // ── Tool parameter schemas (typebox) ──────────────────────────────
 
-/** Spawn one named resident teammate or sub-agent. */
-export const TeammateSpawnParams = Type.Object({
-  name: Type.String({ minLength: 1, description: "Teammate name, unique among living teammates; used for messaging and claiming" }),
-  agent: Type.String({ description: "Agent definition name or role id; an inline definition may create this role in memory for the current session" }),
-  prompt: Type.Optional(Type.String({ description: "Optional kickoff prompt delivered as the agent / teammate's first turn; omit to let it wait for messages or board claims" })),
-  resources: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { description: "Stable resource tags owned by this direct assignment. Overlapping board claims are rejected until it closes." })),
-  handoffFrom: Type.Optional(Type.String({ minLength: 1, description: "Stopped teammate whose assignment, claim, and recent reports should be summarized in this successor kickoff." })),
-  definition: Type.Optional(Type.Object({
-    description: Type.String({ description: "Routing contract for the generated role" }),
-    tools: Type.Optional(Type.Array(Type.String(), { description: "Pi tool ids for the generated role; only pi built-ins (read, bash, edit, write, grep, find, ls, powershell) are grantable — teammates run without extensions, so MCP/extension ids fail the spawn" })),
-    model: Type.Optional(Type.String({ description: 'Optional provider/model pin, or "inherit" to run on the leader\'s current model' })),
-    verify: Type.Optional(Type.String({ description: "Role-default completion gate: a review prompt a fresh reviewer answers with VERDICT: PASS or FAIL" })),
-    worktree: Type.Optional(Type.Boolean({ description: "Whether this role receives a dedicated Git worktree" })),
-    prompt: Type.String({ minLength: 1, description: "Role prompt for this generated teammate / sub-agent" }),
-    persist: Type.Optional(Type.Boolean({ description: "Persist only when the user explicitly asks to keep this role for future sessions" })),
-    persistScope: Type.Optional(Type.Union([
-      Type.Literal("project"),
-      Type.Literal("project-local"),
-    ], { description: "Persistence scope; defaults to project-local when persist is true" })),
-  }, { description: "Optional generated role definition; kept in memory unless explicitly persisted" })),
-});
+export const InlineAgentDefinitionParams = Type.Object({
+  description: Type.String({ minLength: 1, description: "Routing contract for the generated Agent" }),
+  tools: Type.Optional(Type.Array(Type.String(), { description: `Explicit minimal tool grant. Canonical built-ins: ${WORKER_BUILTIN_TOOLS.join(", ")}. Omitted or [] means coordination-only (agent_event and work), with no file or shell access. No aliases or inherited leader extension tools.` })),
+  model: Type.Optional(Type.String({ description: "Provider/model pin or inherit" })),
+  verify: Type.Optional(Type.String({ description: "Default Work verification gate" })),
+  worktree: Type.Optional(Type.Boolean({ description: "Dedicated Git worktree" })),
+  prompt: Type.String({ minLength: 1, description: "Agent role prompt" }),
+  persist: Type.Optional(Type.Boolean({ description: "Persist only when explicitly requested" })),
+  persistScope: Type.Optional(Type.Union([Type.Literal("project"), Type.Literal("project-local")])),
+}, { additionalProperties: false });
 
-/** Shut down one living teammate. */
-export const TeammateShutdownParams = Type.Object({
-  name: Type.String({ description: "Teammate name on the roster" }),
-});
+/** Legacy overloaded Agent control; replaced by AgentActionParams at final cutover. */
+export const AgentActionParams = Type.Union([
+  Type.Object({ action: Type.Literal("delegate"), name: Type.String({ minLength: 1 }), prompt: Type.String({ minLength: 1 }), definition: Type.Optional(InlineAgentDefinitionParams), resources: Type.Optional(Type.Array(Type.String({ minLength: 1 }))), verify: Type.Optional(Type.String()), model: Type.Optional(Type.String()), fork: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+  Type.Object({ action: Type.Literal("start"), name: Type.String({ minLength: 1 }), definition: Type.Optional(InlineAgentDefinitionParams), model: Type.Optional(Type.String()) }, { additionalProperties: false }),
+  Type.Object({ action: Type.Literal("inspect"), name: Type.String({ minLength: 1 }), session: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+  Type.Object({ action: Type.Literal("stop"), session: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+], { description: "Delegate, start, inspect, or stop an Agent session" });
 
+/** Shut down one living teammate. */
 /** Create a board task (leader-only). */
-export const TaskCreateParams = Type.Object({
-  subject: Type.String({ minLength: 1, description: "Short task title shown on the board" }),
-  description: Type.Optional(Type.String({ description: "Full task description for the claiming teammate" }),
-  ),
-  dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Task ids that must complete before this task is claimable" })),
-  verify: Type.Optional(Type.String({ description: "Completion gate: a fresh reviewer judges the acceptance criteria. Explicit PASS/FAIL completes or returns the task; an inconclusive review escalates without counting as failure." })),
-  resources: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { description: "Stable resource tags this task mutates, e.g. firmware/sub-node. Overlapping active tags cannot be claimed concurrently." })),
-  supersedes: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { description: "Obsolete task ids this new task replaces. Superseded work cannot be claimed or completed." })),
-});
+/** First public Work interface slice. Work creation reuses the current
+ * single-writer task record until every acquisition path shares one lifecycle. */
+export const WorkToolParams = Type.Union([
+  Type.Object({
+    action: Type.Literal("create"),
+    subject: Type.String({ minLength: 1, description: "Work title" }),
+    description: Type.Optional(Type.String({ description: "Full Work description" })),
+    dependsOn: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { description: "Work IDs that must complete first" })),
+    verify: Type.Optional(Type.String({ description: "Completion gate for this Work Item" })),
+    resources: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { description: "Resource tags that cannot overlap active Work" })),
+  }, { additionalProperties: false }),
+  Type.Object({ action: Type.Literal("list") }, { additionalProperties: false }),
+  Type.Object({
+    action: Type.Literal("assign"),
+    id: Type.String({ minLength: 1, description: "Pending Work Item ID" }),
+    target: Type.Object({ session: Type.String({ minLength: 1, description: "Exact idle session route" }) }, { additionalProperties: false }),
+  }, { additionalProperties: false }),
+  Type.Object({
+    action: Type.Literal("release"),
+    id: Type.String({ minLength: 1, description: "Claimed Work Item ID" }),
+    reason: Type.String({ minLength: 1, description: "Reason Work is returned to pending" }),
+  }, { additionalProperties: false }),
+  Type.Object({
+    action: Type.Literal("reopen"),
+    id: Type.String({ minLength: 1, description: "Completed Work Item ID" }),
+    reason: Type.String({ minLength: 1, description: "Reason this completed Work is reopened" }),
+  }, { additionalProperties: false }),
+  Type.Object({
+    action: Type.Literal("supersede"),
+    subject: Type.String({ minLength: 1, description: "Replacement Work title" }),
+    description: Type.Optional(Type.String({ description: "Full replacement Work description" })),
+    dependsOn: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { description: "Replacement Work dependencies" })),
+    verify: Type.Optional(Type.String({ description: "Replacement completion gate" })),
+    resources: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { description: "Replacement resource tags" })),
+    supersedes: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, description: "Obsolete Work IDs replaced atomically" }),
+  }, { additionalProperties: false }),
+], { description: "Create, list, assign, release, reopen, or supersede current Work Items" });
 
 /** Shared leader/worker read-only board view. */
-export const TaskListParams = Type.Object({});
+/** Shared communication event parameters across Leader, Worker, and Peers. */
+export const AgentEventParams = Type.Object({
+  message: Type.String({ description: "Message content" }),
+  to: Type.Optional(Type.String({ minLength: 1, description: "Recipient Agent, leader, or exact session route" })),
+  intent: Type.Optional(Type.Union([Type.Literal("inform"), Type.Literal("request")])),
+}, { additionalProperties: false });
 
 /** The reserved recipient name for reports to the team leader. */
 export const LEADER_RECIPIENT = "leader";
 
 /** The single messaging primitive: addressed peer mail and leader reports.
  * `status` is honored only for to="leader" terminal reports. */
-export const SendMessageParams = Type.Object({
-  to: Type.String({ minLength: 1, description: 'Recipient: a teammate name on the roster, or "leader" to report to the team leader' }),
-  message: Type.String({ description: "Message content; the first line becomes the title shown in the console" }),
-  reopen: Type.Optional(Type.Boolean({ description: "Leader only: explicitly start a new assignment after the teammate reported completion" })),
-  resources: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { description: "Leader only: resource tags for a reopened direct assignment. Ignored for worker reports." })),
-  status: Type.Optional(Type.Union([
-    Type.Literal("in_progress"),
-    Type.Literal("completed"),
-    Type.Literal("failed"),
-  ], { description: 'Only for to="leader": completed or failed ends the current assignment and triggers immediate follow-up delivery' })),
-});
-
 /** Self-claim a pending board task. */
-export const TaskClaimParams = Type.Object({
-  taskId: Type.Optional(Type.String({ description: "Specific task id to claim; omit to claim the first claimable task" })),
-});
+/** Worker-only Work claim operation. It queues an intent; the single-writer
+ * harness remains the only authority that can grant ownership. */
+export const WorkerWorkToolParams = Type.Union([
+  Type.Object({ action: Type.Literal("list") }, { additionalProperties: false }),
+  Type.Object({
+    action: Type.Literal("claim"),
+    id: Type.Optional(Type.String({ minLength: 1, description: "Specific claimable Work Item ID" })),
+  }, { additionalProperties: false }),
+  Type.Object({
+    action: Type.Literal("release"),
+    result: Type.Optional(Type.String({ description: "Reason owned Work is released" })),
+  }, { additionalProperties: false }),
+  Type.Object({
+    action: Type.Literal("submit"),
+    outcome: Type.Union([Type.Literal("success"), Type.Literal("failed")]),
+    result: Type.Optional(Type.String({ description: "Result evidence for the owned Work Item" })),
+  }, { additionalProperties: false }),
+], { description: "Worker claim or submit operation for Work" });
 
 /** Submit a claimed task outcome. Completion passes through the verify gate. */
-export const TaskSubmitParams = Type.Object({
-  taskId: Type.String({ description: "The claimed task id" }),
-  status: Type.Union([Type.Literal("completed"), Type.Literal("failed")], { description: "Outcome of the claimed task" }),
-  result: Type.Optional(Type.String({ description: "Result summary recorded on the board when completed" })),
-});
-
 // ── State snapshot for persistence ────────────────────────────────
 
+export const TEAM_RUNTIME_VERSION = 2;
+
 export interface TeamState {
+  runtimeVersion: number;
   teammates: Record<string, Teammate>;
   tasks: Record<string, BoardTask>;
   /** Unified teammate model for this session; spawns without a role pin use it. */
@@ -290,7 +328,8 @@ export interface TeamState {
   peerInboxOffsets: Record<string, number>;
   /** Delivered peer message ids per inbox, capped FIFO for deduplication. */
   peerDeliveredIds: Record<string, string[]>;
-  /** Harness-owned peer-delivery transition by message id. This records queueing
-   * or control-stream acceptance only; it never asserts recipient processing. */
-  peerDeliveryStates: Record<string, "queued" | "routed">;
+  /** Harness-owned peer-delivery transition by message id. This records queueing,
+   *  control-stream acceptance, or a drop aimed at a retired incarnation; it
+   *  never asserts recipient processing. */
+  peerDeliveryStates: Record<string, "queued" | "routed" | "dropped">;
 }

package/src/ui.ts

@@ -3,6 +3,8 @@
 
 import { truncateToWidth, Key, matchesKey, fuzzyFilter } from "@earendil-works/pi-tui";
 import {
+  agentColor,
+  createLiveActivityWidget,
   createPiThemeStyle,
   createSearchPicker,
   modelLabel,
@@ -11,15 +13,15 @@ import {
   PI_SPINNER_INTERVAL_MS,
   notifyPi,
   renderPiPanel,
-  renderPiWidgetRow,
+  renderLiveActivityIdentity,
   sortModels,
   type SearchPicker,
 } from "@fradser/pi-kit";
-import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import {
   clampConsoleScroll, consoleScrollRange, maxConsoleBody, scrollConsoleDetail, wrapConsoleDetail,
 } from "./console-viewport.ts";
-import { fitTeammateRow, formatTeammateLabel, runningTeammateActivity } from "./activity.ts";
+import { formatTeammateLabel, runningTeammateActivity } from "./activity.ts";
 import { MODEL_INHERIT_ALIAS, discoverAgents, resolveAgent, type AgentDefinition } from "./agents.ts";
 import { getPeerDeliveryState, getState, getTeammate, getTeamDefaultModel, listTasks, listTeammates, livingTeammates, setTeamDefaultModel } from "./state.ts";
 import {
@@ -38,19 +40,15 @@ import { inboxPath } from "./statefile.ts";
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-const TEAM_COLORS = ["success", "warning", "error", "mdLink"] as const;
 let spinnerTimer: ReturnType<typeof setInterval> | undefined;
 let spinnerFrame = 0;
 
-function hashName(name: string): number {
-  let h = 0;
-  for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(0) + i * 7) | 0;
-  return Math.abs(h);
-}
-
-function colorFor(name: string): (typeof TEAM_COLORS)[number] {
-  return TEAM_COLORS[hashName(name) % TEAM_COLORS.length];
-}
+const teamActivityWidget = createLiveActivityWidget({
+  key: "teammate",
+  placement: "aboveEditor",
+  fit: truncateToWidth,
+  activityFormat: "markdown",
+});
 
 function ensureSpinner(): void {
   const working = livingTeammates().some(isWorking);
@@ -73,41 +71,12 @@ export function stopUiTimers(): void {
 }
 
 export function ensureTeamWidget(ctx?: { ui?: ExtensionUIContext; mode?: string }): void {
-  if (!ctx?.ui?.setWidget) return;
-  if (ctx.mode && ctx.mode !== "tui") return;
-
-  if (livingTeammates().filter(isWorking).length === 0) {
-    ctx.ui.setWidget("teammate", undefined);
-    return;
-  }
-
-  ctx.ui.setWidget("teammate", (tui, theme) => {
-    const timer = setInterval(() => tui.requestRender(), PI_SPINNER_INTERVAL_MS);
-    timer.unref?.();
-    const style = createPiThemeStyle(theme);
-    return {
-      placement: "belowEditor",
-      render: (width: number) => {
-        // Only WORKING teammates appear above the input box; idle and
-        // stopped teammates stay in the /agent-teams console instead.
-        const working = livingTeammates().filter(isWorking);
-        if (working.length === 0) return [];
-        const lines: string[] = [];
-        for (const teammate of working) {
-          lines.push(renderPiWidgetRow(fitTeammateRow(
-            PI_SPINNER_FRAMES[spinnerFrame],
-            style.fg(colorFor(teammate.name), teammate.name),
-            runningTeammateActivity(teammate) + stallSuffix(teammate),
-            Math.max(1, width - 1),
-            (activity) => theme.bold(style.fg("accent", activity)),
-          ), width, truncateToWidth));
-        }
-        return lines;
-      },
-      invalidate: () => {},
-      dispose: () => clearInterval(timer),
-    };
-  });
+  const working = livingTeammates().filter(isWorking);
+  teamActivityWidget.update(ctx, working.map((teammate) => ({
+    id: teammate.name,
+    identity: teammate.name,
+    activity: runningTeammateActivity(teammate) + stallSuffix(teammate),
+  })));
 }
 
 function isWorking(teammate: { status: string }): boolean {
@@ -289,7 +258,7 @@ function describeSpawnModel(pinned: string | undefined): string {
   const resolved = resolveSpawnModel(pinned, getTeamDefaultModel(), currentLeaderModelRef());
   if (pinned && pinned.trim().toLowerCase() !== MODEL_INHERIT_ALIAS) return pinned.trim();
   if (resolved.model) {
-    const suffix = pinned ? "inherit -> " : "[team default] ";
+    const suffix = pinned ? "inherit -> " : resolved.source === "team-default" ? "[team default] " : "";
     return `${suffix}${resolved.model}`;
   }
   return pinned ? "inherit -> (unavailable at spawn)" : "(Pi default)";
@@ -333,7 +302,7 @@ const LIST_CHROME_LINES = 5;
  * teammate-model picker. */
 export function openTeamConsole(ctx: {
   ui: ExtensionUIContext;
-  modelRegistry?: { getAvailable(): Array<{ provider: string; id: string; name?: string }> };
+  modelRegistry?: { getAll?(): Array<{ provider: string; id: string; name?: string }>; getAvailable(): Array<{ provider: string; id: string; name?: string }> };
 }): Promise<void> {
   return ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
     let page: ConsolePage = "roster";
@@ -396,7 +365,11 @@ export function openTeamConsole(ctx: {
       model?.id === CLEAR_TEAM_MODEL_ENTRY.id;
 
     const openModelPicker = (): void => {
-      const models = sortModels([...(ctx.modelRegistry?.getAvailable() ?? [])]);
+      const registryModels =
+        typeof ctx.modelRegistry?.getAll === "function"
+          ? ctx.modelRegistry.getAll()
+          : (ctx.modelRegistry?.getAvailable() ?? []);
+      const models = sortModels([...registryModels]);
       if (models.length === 0) return;
       picker = createSearchPicker([CLEAR_TEAM_MODEL_ENTRY, ...models], {
         filter: fuzzyFilter,
@@ -520,7 +493,7 @@ export function openTeamConsole(ctx: {
     const teammateRowText = (key: string, selected: boolean): string => {
       const teammate = getTeammate(key)!;
       const marker = selected ? style.accent("❯ ") : "  ";
-      const name = theme.bold(theme.fg(colorFor(teammate.name), `@${teammate.name}`));
+      const name = renderLiveActivityIdentity(teammate.name, theme, "@");
       if (isWorking(teammate)) {
         const prefix = `${marker}${name} `;
         const width = tui.terminal.columns;
@@ -537,7 +510,7 @@ export function openTeamConsole(ctx: {
     const roleRowText = (key: string, selected: boolean): string => {
       const def = getRoles().find((candidate) => candidate.name === key)!;
       const marker = selected ? style.accent("❯ ") : "  ";
-      const name = theme.bold(theme.fg(colorFor(key), `@${key}`));
+      const name = renderLiveActivityIdentity(key, theme, "@");
       const live = livingTeammates().filter((teammate) => teammate.agent === key && teammate.status !== "stopped").length;
       const liveTag = live > 0 ? style.success(`[${live} live]`) : style.dim("[0 live]");
       const provenance = def.scope === "session" ? "in-memory" : displaySource(def.source);
@@ -547,7 +520,7 @@ export function openTeamConsole(ctx: {
     const taskRowText = (key: string, selected: boolean): string => {
       const task = listTasks().find((candidate) => candidate.id === key)!;
       const marker = selected ? style.accent("❯ ") : "  ";
-      const label = theme.fg(colorFor(key), `[${key}]`);
+      const label = theme.fg(agentColor(key), `[${key}]`);
       const holder = task.claimedBy ? style.dim(` @${task.claimedBy}`) : "";
       const statusText = task.status === "completed"
         ? style.success("✓")
@@ -564,7 +537,7 @@ export function openTeamConsole(ctx: {
       const lines: ContentLine[] = [];
       if (page === "board") {
         if (rows.length === 0) {
-          lines.push({ text: style.dim("The task board is empty. Create tasks with task_create."), select: -1 });
+          lines.push({ text: style.dim("The Work list is empty. Create Work with work action=create."), select: -1 });
         }
         rows.forEach((row, index) => lines.push({ text: taskRowText(row.key, index === currentPageSelection(rows.length)), select: index }));
         return lines;
@@ -691,7 +664,10 @@ export function openTeamConsole(ctx: {
           return;
         }
         if (data === "m" || data === "M") {
-          if (ctx.modelRegistry && ctx.modelRegistry.getAvailable().length > 0) {
+          const availableCount = ctx.modelRegistry
+            ? (typeof ctx.modelRegistry.getAll === "function" ? ctx.modelRegistry.getAll() : ctx.modelRegistry.getAvailable()).length
+            : 0;
+          if (ctx.modelRegistry && availableCount > 0) {
             openModelPicker();
           } else {
             notifyPi(ctx.ui, "No models are available in the model registry.", "warning");

package/src/work-context.ts

@@ -0,0 +1,88 @@
+import { randomUUID } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import {
+  buildSessionContext,
+  SessionManager,
+  type ExtensionContext,
+  type SessionContext,
+  type SessionMessageEntry,
+} from "@earendil-works/pi-coding-agent";
+
+type AgentMessage = SessionContext["messages"][number];
+type ContextReader = Pick<ExtensionContext["sessionManager"], "getBranch" | "getLeafId">;
+type AssistantMessage = Extract<AgentMessage, { role: "assistant" }>;
+type ToolResultMessage = Extract<AgentMessage, { role: "toolResult" }>;
+type ToolCall = Extract<AssistantMessage["content"][number], { type: "toolCall" }>;
+
+function withoutRuntimeState(message: AgentMessage): AgentMessage {
+  if (message.role === "custom") {
+    const { details: _details, ...history } = message;
+    return history;
+  }
+  if (message.role === "toolResult") {
+    const { details: _details, addedToolNames: _tools, ...history } = message;
+    return history;
+  }
+  return message;
+}
+
+function completedExchanges(messages: AgentMessage[]): { calls: Set<ToolCall>; results: Set<ToolResultMessage> } {
+  const pending = new Map<string, ToolCall>();
+  const calls = new Set<ToolCall>();
+  const results = new Set<ToolResultMessage>();
+  for (const message of messages) {
+    if (message.role === "user" || message.role === "assistant") pending.clear();
+    if (message.role === "assistant") {
+      for (const block of message.content) {
+        if (block.type === "toolCall" && !pending.has(block.id)) pending.set(block.id, block);
+      }
+    } else if (message.role === "toolResult") {
+      const call = pending.get(message.toolCallId);
+      if (!call || call.name !== message.toolName) continue;
+      calls.add(call);
+      results.add(message);
+      pending.delete(call.id);
+    }
+  }
+  return { calls, results };
+}
+
+/** Snapshot the active Pi context without moving the parent's branch or replaying pending tools. */
+export function snapshotWorkContext(sessionManager: ContextReader | undefined): AgentMessage[] {
+  if (!sessionManager || typeof sessionManager.getBranch !== "function" || typeof sessionManager.getLeafId !== "function") {
+    throw new Error("Fork context unavailable: leader session manager is unavailable.");
+  }
+  const messages = buildSessionContext(sessionManager.getBranch(), sessionManager.getLeafId()).messages;
+  const completed = completedExchanges(messages);
+  const history: AgentMessage[] = [];
+  for (const message of messages) {
+    if (message.role === "toolResult" && !completed.results.has(message)) continue;
+    if (message.role !== "assistant") {
+      history.push(withoutRuntimeState(message));
+      continue;
+    }
+    const content = message.content.filter((block) => block.type !== "toolCall" || completed.calls.has(block));
+    if (content.length === 0 && message.content.length > 0) continue;
+    const hasTools = content.some((block) => block.type === "toolCall");
+    const stopReason = message.stopReason === "toolUse" && !hasTools ? "stop" : message.stopReason;
+    history.push({ ...message, content, stopReason });
+  }
+  return structuredClone(history);
+}
+
+/** Materialize already-rebuilt context; appendMessage cannot represent Pi summary roles. */
+export function writeWorkContext(cwd: string, directory: string, messages: AgentMessage[]): string {
+  const session = SessionManager.create(cwd, directory);
+  const file = session.getSessionFile()!;
+  let parentId: string | null = null;
+  const entries = messages.map((message): SessionMessageEntry => {
+    const entry: SessionMessageEntry = {
+      type: "message", id: randomUUID(), parentId, timestamp: new Date().toISOString(), message,
+    };
+    parentId = entry.id;
+    return entry;
+  });
+  const content = [session.getHeader(), ...entries].map((entry) => JSON.stringify(entry)).join("\n");
+  writeFileSync(file, `${content}\n`, { mode: 0o600, flag: "wx" });
+  return file;
+}

package/src/worker-tools.ts

@@ -0,0 +1,4 @@
+/** Pi built-ins available to a bare worker; extension aliases are not inherited. */
+export const WORKER_BUILTIN_TOOLS: readonly string[] = [
+  "read", "bash", "edit", "write", "grep", "find", "ls", "powershell",
+];