@fradser/pi-agent-teams 0.6.0 → 0.8.0

package/src/tools.ts

@@ -1,8 +1,10 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { formatAgentMessagePrefix, formatAgentTaskName, formatToolEventLabel } from "@fradser/pi-kit";
+import { keyHint, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { formatAgentMessagePrefix, formatAgentTaskName, formatExpandHint, formatToolEventLabel, safeDisplayText } from "@fradser/pi-kit";
 import {
   createBoardTask,
   formatSilenceDuration,
+  hasAnnouncedFinish,
+  hasTerminalReport,
   publishStateSnapshot,
   sendLeaderMessage,
   shutdownTeammate,
@@ -12,13 +14,8 @@ import { listTasks, livingTeammates } from "./state.ts";
 import { LEADER_RECIPIENT, SendMessageParams, TeammateShutdownParams, TeammateSpawnParams, TaskCreateParams } from "./types.ts";
 import { registerTaskListTool } from "./worker.ts";
 import { openTeamConsole, refreshTeamUI } from "./ui.ts";
+import { discoverAgents } from "./agents.ts";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-function isValidAgentName(name: string): boolean {
-  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) && !name.includes("..") && name !== "con";
-}
 
 function rosterSummary(): string {
   const alive = livingTeammates();
@@ -31,7 +28,7 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     name: "teammate_spawn",
     promptSnippet: "Spawn a named resident teammate",
     label: "Spawn Teammate",
-    description: "Spawn one named resident teammate. Model and worktree behavior come from its declarative agent definition; the kickoff prompt is optional.",
+    description: "Spawn one named resident teammate. Generated role definitions stay in memory by default; persist one only when the user explicitly asks to keep it for future sessions.",
     parameters: TeammateSpawnParams,
     // Canonical lifecycle rows (same as packages/monitor): empty renderCall,
     // ONE startup row owned by renderResult.
@@ -39,7 +36,7 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     renderCall: () => new Text("", 0, 0),
     renderResult(result, _options, theme, context) {
       const text = result.content[0]?.type === "text" ? (result.content[0] as { type: string; text: string }).text : "";
-      if ((result as { isError?: boolean }).isError) {
+      if (context.isError) {
         return new Text(theme.fg("error", text.split("\n")[0] || "Failed to spawn teammate."), 0, 0);
       }
       const params = context.args as { name: string; agent: string; prompt?: string };
@@ -71,17 +68,27 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     parameters: TeammateShutdownParams,
     renderShell: "self",
     renderCall: () => new Text("", 0, 0),
-    renderResult(result, _options, theme, context) {
+    renderResult(result, options, theme, context) {
       const text = result.content[0]?.type === "text" ? (result.content[0] as { type: string; text: string }).text : "";
-      if ((result as { isError?: boolean }).isError) {
+      if (context.isError) {
         return new Text(theme.fg("error", text.split("\n")[0] || "Failed to shut down teammate."), 0, 0);
       }
       const name = String((context.args as { name?: string }).name ?? "");
-      const line = `${theme.fg("toolTitle", theme.bold(formatToolEventLabel("event", `@${name} shut down`).trimEnd()))}`;
-      return {
-        render: (width: number) => [truncateToWidth(line, Math.max(1, width))],
-        invalidate: () => {},
+      // The finish entry already announced this end of life (or its terminal
+      // report is queued to); a second event row is noise.
+      if (hasAnnouncedFinish(name) || hasTerminalReport(name)) return { render: () => [], invalidate: () => {} };
+      const title = theme.fg("toolTitle", theme.bold(formatToolEventLabel("event", `@${name} shut down`, "agent")));
+      const render = (width: number) => {
+        if (width <= 0) return [];
+        if (!options.expanded) {
+          return [truncateToWidth(`${title}${formatExpandHint(keyHint("app.tools.expand", "to expand"), theme)}`, width)];
+        }
+        return [
+          truncateToWidth(title, width),
+          ...text.split("\n").map((line) => truncateToWidth(theme.fg("customMessageText", safeDisplayText(line)), width)),
+        ];
       };
+      return { render, invalidate: () => {} };
     },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const result = await shutdownTeammate(params.name);
@@ -97,10 +104,26 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     label: "Send Message",
     description: "The only messaging primitive. Address a living teammate by name; working teammates receive a steer immediately and idle teammates wake with the message. status is reserved for worker reports to leader.",
     parameters: SendMessageParams,
-    renderCall(args, theme) {
-      const prefix = theme.fg("toolTitle", theme.bold(formatAgentMessagePrefix("to")));
-      const recipient = theme.fg("accent", `@${String(args.to ?? "")}`);
-      return new Text(`${prefix}${recipient}`, 0, 0);
+    // Canonical lifecycle rows (same as packages/monitor): empty call slot,
+    // ONE delivery row owned by renderResult.
+    renderShell: "self",
+    renderCall: () => new Text("", 0, 0),
+    renderResult(result, _options, theme, context) {
+      const text = result.content[0]?.type === "text" ? (result.content[0] as { type: string; text: string }).text : "";
+      if (context.isError) {
+        return new Text(theme.fg("error", text.split("\n")[0] || "Failed to send message."), 0, 0);
+      }
+      const to = String((context.args as { to?: string }).to ?? "");
+      const details = result.details as { queued?: boolean; stalledMs?: number } | undefined;
+      const suffix = details?.queued ? "queued" : "delivered";
+      let line = `${theme.fg("toolTitle", theme.bold(formatAgentMessagePrefix("to")))}${theme.fg("accent", `@${to}`)}${theme.fg("dim", ` · ${suffix}`)}`;
+      if (!details?.queued && details?.stalledMs !== undefined) {
+        line += theme.fg("dim", ` · stalled ${formatSilenceDuration(details.stalledMs)}`);
+      }
+      return {
+        render: (width: number) => width > 0 ? [truncateToWidth(line, width)] : [],
+        invalidate: () => {},
+      };
     },
     async execute(_toolCallId, params) {
       if (params.to === LEADER_RECIPIENT) throw new Error('The leader cannot send a message to itself.');
@@ -112,7 +135,12 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
       if (!result.queued && result.stalledMs !== undefined) {
         text += `\nWarning: @${params.to} has been stalled with no output for ${formatSilenceDuration(result.stalledMs)} — the control-stream write succeeded, but the teammate may be wedged. Consider teammate_shutdown if it stays silent.`;
       }
-      return { content: [{ type: "text", text }], details: {} };
+      return {
+        content: [{ type: "text", text }],
+        details: result.stalledMs !== undefined && !result.queued
+          ? { queued: result.queued, stalledMs: result.stalledMs }
+          : { queued: result.queued },
+      };
     },
   });
 
@@ -120,8 +148,24 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     name: "task_create",
     promptSnippet: "Create a shared board task",
     label: "Create Task",
-    description: "Create one shared board task. Resident teammates self-claim it when dependencies are met; an optional verify command gates completion.",
+    description: "Create one shared board task. Resident teammates self-claim it when dependencies are met; an optional verify prompt gates completion through a fresh reviewer.",
     parameters: TaskCreateParams,
+    // Canonical lifecycle rows (same as packages/monitor): empty call slot,
+    // ONE created row owned by renderResult.
+    renderShell: "self",
+    renderCall: () => new Text("", 0, 0),
+    renderResult(result, _options, theme, context) {
+      const text = result.content[0]?.type === "text" ? (result.content[0] as { type: string; text: string }).text : "";
+      if (context.isError) {
+        return new Text(theme.fg("error", text.split("\n")[0] || "Failed to create task."), 0, 0);
+      }
+      const subject = String((context.args as { subject?: string }).subject ?? "");
+      const line = theme.fg("toolTitle", theme.bold(formatToolEventLabel("created", subject, "board")));
+      return {
+        render: (width: number) => width > 0 ? [truncateToWidth(line, width)] : [],
+        invalidate: () => {},
+      };
+    },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const tasks = listTasks();
       if (params.dependsOn?.some((dep) => !tasks.some((task) => task.id === dep))) {
@@ -137,81 +181,23 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
   registerTaskListTool(pi);
 }
 
+function teamStatusSummary(): string {
+  const roles = [...discoverAgents().keys()].map((name) => `@${name}`);
+  const rolesLine = roles.length > 0
+    ? `${roles.length} persistent agent role${roles.length === 1 ? "" : "s"}: ${roles.join(", ")}`
+    : "No agent roles discovered.";
+  return `${rosterSummary()}\n${rolesLine}`;
+}
+
 export function registerTeamCommand(pi: ExtensionAPI): void {
   pi.registerCommand("agent-teams", {
-    description: "Agent Teams menu: console and create agents from session history",
+    description: "Agent Teams management console: session teammates and persistent agent roles",
     handler: async (_args, ctx) => {
-      const choice = await ctx.ui.select("agent-teams", ["console", "project", "local"]);
-      if (!choice) return;
-      if (choice === "console") {
-        publishStateSnapshot();
-        if (ctx.mode !== "tui") { ctx.ui.notify(rosterSummary(), "info"); return; }
-        await openTeamConsole(ctx);
-        refreshTeamUI(ctx);
-        return;
-      }
-      await createAgentFromHistory(ctx, choice === "local");
+      publishStateSnapshot();
+      if (ctx.mode !== "tui") { ctx.ui.notify(teamStatusSummary(), "info"); return; }
+      await openTeamConsole(ctx);
+      refreshTeamUI(ctx);
     },
   });
 }
 
-interface GeneratedAgent { name?: string; description?: string; tools?: string[]; prompt?: string; content?: string; }
-
-function parseGeneratedAgents(raw: string): GeneratedAgent[] {
-  const cleaned = raw.trim().replace(/^```(?:json)?\s*|\s*```$/g, "");
-  const start = cleaned.indexOf("[");
-  const end = cleaned.lastIndexOf("]");
-  if (start < 0 || end <= start) return [];
-  try {
-    const value: unknown = JSON.parse(cleaned.slice(start, end + 1));
-    return Array.isArray(value) ? value.filter((item): item is GeneratedAgent => Boolean(item && typeof item === "object")) : [];
-  } catch { return []; }
-}
-
-function renderAgentDefinition(agent: GeneratedAgent): string {
-  const name = agent.name!.trim();
-  const description = (agent.description || "Agent created from session history").replace(/[\r\n]+/g, " ").trim();
-  const tools = Array.isArray(agent.tools) ? agent.tools.filter((tool) => typeof tool === "string" && tool.trim()).join(", ") : "";
-  return `---\nname: ${name}\ndescription: ${description}${tools ? `\ntools: ${tools}` : ""}\n---\n\n${(agent.prompt || "").trim()}`;
-}
-
-async function createAgentFromHistory(ctx: ExtensionContext, local: boolean): Promise<void> {
-  const branch = ctx.sessionManager?.getBranch?.() ?? [];
-  const history = branch.map((entry: any) => {
-    const text = typeof entry?.text === "string" ? entry.text : typeof entry?.content === "string" ? entry.content : "";
-    return text ? text : Array.isArray(entry?.content) ? entry.content.map((part: any) => part?.text ?? "").join("") : "";
-  }).filter(Boolean).slice(-20).join("\n\n");
-  const generated = await generateAgentPrompt(ctx, history);
-  if (!generated) return;
-  const dir = path.join(ctx.cwd || process.cwd(), ".pi", "agents");
-  fs.mkdirSync(dir, { recursive: true });
-  const definitions = parseGeneratedAgents(generated)
-    .filter((item) => typeof item.name === "string" && (item.content?.trim() || item.prompt?.trim()))
-    .map((item) => ({ name: item.name!.trim(), content: item.content?.trim() || renderAgentDefinition(item) }));
-  if (definitions.length === 0) { ctx.ui.notify("Model returned no usable agent definitions", "error"); return; }
-  let created = 0;
-  for (const definition of definitions) {
-    if (!isValidAgentName(definition.name)) continue;
-    const filename = `${definition.name}${local ? ".local" : ""}.md`;
-    try { fs.writeFileSync(path.join(dir, filename), definition.content, { encoding: "utf8", flag: "wx" }); created++; } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-    }
-  }
-  ctx.ui.notify(`Created ${created} agent definition${created === 1 ? "" : "s"}`, created ? "info" : "warning");
-}
-
-async function generateAgentPrompt(ctx: ExtensionContext, history: string): Promise<string | undefined> {
-  const model = ctx.model;
-  const registry = ctx.modelRegistry;
-  if (!model || !registry?.complete) {
-    ctx.ui.notify("No model available to generate an agent", "error");
-    return undefined;
-  }
-  const response = await registry.complete(model, {
-    systemPrompt: "Design a complementary resident coding agent team from session history. Return a JSON array of 2-4 complementary agent definitions. Each item must have name, description, tools, and prompt fields. Names use letters, digits, dots, dashes, underscores. Return JSON only, with no code fences.",
-    messages: [{ role: "user", content: `Session history:\n${history || "(empty)"}`, timestamp: Date.now() }],
-  }, { maxTokens: 2000, temperature: 0, cacheRetention: "none" });
-  const content = response.content?.filter((part: any) => part.type === "text").map((part: any) => part.text).join("\\n").trim();
-  if (!content) { ctx.ui.notify("Model returned no agent definition", "error"); return undefined; }
-  return content;
-}

package/src/types.ts

@@ -30,6 +30,8 @@ export interface Teammate {
   isolation: "worktree" | "none";
   /** Board task currently claimed by this teammate, if any. */
   currentTaskId?: string;
+  /** Effective launch model reference ("provider/model"); absent when Pi picks its default. */
+  model?: string;
   /** Live assistant text assembled from the RPC stream. */
   liveText?: string;
   /** Current child tool name, if a tool is executing. */
@@ -42,6 +44,8 @@ export interface Teammate {
   sequenceEnded?: boolean;
   /** When the harness last sent a claimable-task notice to this teammate. */
   lastNoticeAt?: number;
+  /** Claimable task ids already announced to this teammate; one notice per id until it re-arms. */
+  noticedTaskIds?: string[];
   usage?: WorkerUsage;
   error?: string;
   createdAt: number;
@@ -72,7 +76,8 @@ export interface BoardTask {
   description?: string;
   /** Task ids that must complete before this task is claimable. */
   dependsOn: string[];
-  /** Deterministic completion gate; overrides the agent-role default. */
+  /** Completion gate: a review prompt a fresh one-shot reviewer answers with
+   *  VERDICT: PASS or FAIL; overrides the agent-role default. */
   verify?: string;
   status: TaskStatus;
   claimedBy?: string;
@@ -165,8 +170,21 @@ export interface InboxMessage {
 /** Spawn one named resident teammate. */
 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 (bundled, user, or project scope); its frontmatter pins model and optional worktree isolation" }),
+  agent: Type.String({ description: "Agent definition name; 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 teammate's first turn; omit to let it wait for messages or board claims" })),
+  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" })),
+    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" }),
+    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" })),
 });
 
 /** Shut down one living teammate. */
@@ -180,7 +198,7 @@ export const TaskCreateParams = Type.Object({
   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: "Deterministic completion gate command; zero exit completes the task. Overrides any agent-role default verify." })),
+  verify: Type.Optional(Type.String({ description: "Completion gate: a review prompt a fresh reviewer answers with VERDICT: PASS or FAIL. Overrides any agent-role default verify." })),
 });
 
 /** Shared leader/worker read-only board view. */
@@ -218,10 +236,11 @@ export const TaskSubmitParams = Type.Object({
 export interface TeamState {
   teammates: Record<string, Teammate>;
   tasks: Record<string, BoardTask>;
+  /** Unified teammate model for this session; spawns without a role pin use it. */
+  defaultModel?: string;
   /** Single leader inbox for teammate reports and harness diagnostics. */
   leaderMailbox: MailboxMessage[];
   messageCounter: number;
-  taskCounter: number;
   /** Byte offsets consumed by the parent from each teammate's outbox. */
   workerEventOffsets: Record<string, number>;
   /** Report event ids already applied, keyed by teammate spawn. */