@fradser/pi-agent-teams 0.9.2 → 1.0.0

package/src/agents.ts

@@ -1,296 +0,0 @@
-/**
- * Declarative agent definitions: Markdown files with YAML-style frontmatter.
- *
- * Discovery scopes (later scopes override earlier ones for the same name):
- *   1. user          — ~/.pi/agent/agents/ (respects PI_CODING_AGENT_DIR)
- *   2. project       — <cwd>/.pi/agents/<name>.md
- *   3. project-local — <cwd>/.pi/agents/<name>.local.md (personal override)
- *
- * There are no built-in roles: references/agent-roles.md ships template
- * shapes that the leader consults when generating a new definition on demand.
- *
- * Frontmatter fields:
- *   name        — unique agent id (required)
- *   description — routing contract: when the leader should choose this agent
- *   tools       — comma-separated list or YAML list of Pi tool ids
- *   model       — optional provider/model pin, or "inherit" for the leader's
- *                 current model at spawn time
- *   verify      — optional role-default completion gate: a review prompt a
- *                 fresh one-shot reviewer answers with VERDICT: PASS/FAIL
- *   worktree    — optional role-default Git worktree isolation (true/false)
- * The Markdown body is the worker's role prompt.
- */
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-
-export type AgentScope = "user" | "project" | "project-local" | "session";
-
-export interface AgentDefinition {
-  name: string;
-  description: string;
-  tools: string[];
-  model?: string;
-  /** Role-default completion gate; task-level verify overrides this. */
-  verify?: string;
-  /** Whether this role always receives a dedicated Git worktree. */
-  worktree: boolean;
-  /** The Markdown body, trimmed; used as the teammate's role prompt. */
-  prompt: string;
-  /** Scope that supplied this definition (precedence: project-local > project > user > bundled). */
-  scope: AgentScope;
-  /** True only for the shared project scope that is expected to be git-managed.
-   * user and project-local definitions are machine/personal by definition. */
-  gitManaged: boolean;
-  /** Absolute path of the definition file; absent for session-only roles. */
-  source?: string;
-}
-
-export interface AgentDefinitionInput {
-  name: string;
-  description: string;
-  tools: string[];
-  model?: string;
-  verify?: string;
-  worktree?: boolean;
-  prompt: string;
-}
-
-/** Reserved model value meaning "use the leader session's current model",
- *  resolved at spawn time (Claude-Code-style inherit). */
-export const MODEL_INHERIT_ALIAS = "inherit";
-
-const sessionAgents = new Map<string, AgentDefinition>();
-const AGENT_NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/i;
-
-function normalizeAgentInput(input: AgentDefinitionInput): AgentDefinitionInput {
-  const name = input.name.trim();
-  if (!AGENT_NAME_PATTERN.test(name)) {
-    throw new Error(`Invalid agent name "${name}". Use letters, digits, dots, dashes, underscores.`);
-  }
-  const prompt = input.prompt.trim();
-  if (!prompt) throw new Error(`Agent "${name}" prompt must not be empty.`);
-  return {
-    ...input,
-    name,
-    description: input.description.trim(),
-    tools: input.tools.map((tool) => tool.trim()).filter(Boolean),
-    model: input.model?.trim() || undefined,
-    verify: input.verify?.trim() || undefined,
-    worktree: input.worktree ?? false,
-    prompt,
-  };
-}
-
-/** Register a generated role for this session without writing a definition file. */
-export function registerSessionAgent(input: AgentDefinitionInput): AgentDefinition {
-  const normalized = normalizeAgentInput(input);
-  const definition: AgentDefinition = {
-    ...normalized,
-    worktree: normalized.worktree ?? false,
-    scope: "session",
-    gitManaged: false,
-    source: undefined,
-  };
-  sessionAgents.set(definition.name, definition);
-  return definition;
-}
-
-/** Persist a generated role only when the user explicitly requests it. */
-export function persistAgentDefinition(
-  input: AgentDefinitionInput,
-  scope: "project" | "project-local",
-  cwd = process.cwd(),
-): AgentDefinition {
-  const normalized = normalizeAgentInput(input);
-  const directory = agentsDir("project", cwd);
-  fs.mkdirSync(directory, { recursive: true });
-  const filename = `${normalized.name}${scope === "project-local" ? LOCAL_DEFINITION_SUFFIX : ".md"}`;
-  const source = path.join(directory, filename);
-  const frontmatter = [
-    "---",
-    `name: ${normalized.name}`,
-    `description: ${normalized.description.replace(/[\\r\\n]+/g, " ")}`,
-    `tools: ${normalized.tools.join(", ")}`,
-    ...(normalized.model ? [`model: ${normalized.model}`] : []),
-    ...(normalized.verify ? [`verify: ${normalized.verify.replace(/[\\r\\n]+/g, " ")}`] : []),
-    `worktree: ${normalized.worktree ? "true" : "false"}`,
-    "---",
-    normalized.prompt,
-    "",
-  ].join("\n");
-  fs.writeFileSync(source, frontmatter, { encoding: "utf8", mode: 0o600 });
-  sessionAgents.delete(normalized.name);
-  return {
-    ...normalized,
-    worktree: normalized.worktree ?? false,
-    scope,
-    gitManaged: scope === "project",
-    source,
-  };
-}
-
-/** Drop generated session roles; persistent user/project definitions remain discoverable. */
-export function clearSessionAgents(): void {
-  sessionAgents.clear();
-}
-
-/** Shipped role templates: reference material for generating new definitions
- * on demand — never discovered and never spawnable directly. */
-export const AGENT_REFERENCE_PATH = path.resolve(
-  path.dirname(fileURLToPath(import.meta.url)), "..", "references", "agent-roles.md",
-);
-
-/** Files named `xxx.local.md` in the project agents directory are personal
- * overrides: same teammate name as `xxx.md`, project-local scope, never git-
- * managed by convention. */
-export const LOCAL_DEFINITION_SUFFIX = ".local.md";
-
-function agentsDir(scope: "user" | "project", cwd?: string): string {
-  if (scope === "user") {
-    return path.join(getAgentDir(), "agents");
-  }
-  return path.join(cwd || process.cwd(), ".pi", "agents");
-}
-
-function parseFrontmatter(raw: string): { fields: Record<string, string | string[]>; body: string } {
-  const fields: Record<string, string | string[]> = {};
-  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
-  if (!match) return { fields, body: raw.trim() };
-  const lines = match[1].split("\n");
-  for (let index = 0; index < lines.length; index++) {
-    const line = lines[index];
-    const separator = line.indexOf(":");
-    if (separator <= 0) continue;
-    const key = line.slice(0, separator).trim();
-    // Strip inline YAML comments (# ...) and surrounding whitespace/quotes.
-    let value = line.slice(separator + 1).replace(/\s+#.*$/, "").trim();
-    if (key === "tools") {
-      if (value === "") {
-        // YAML block sequence: "- item" lines, flush-left or indented,
-        // possibly interleaved with blank or comment-only lines.
-        const items: string[] = [];
-        index += 1;
-        while (index < lines.length) {
-          const trimmed = lines[index].trim();
-          if (trimmed === "" || trimmed.startsWith("#")) {
-            index += 1;
-            continue;
-          }
-          if (!/^-.+/.test(trimmed)) break;
-          const rawItem = trimmed.replace(/^-\s*/, "");
-          const item = rawItem
-            .replace(/\s+#.*$/, "")
-            .trim()
-            .replace(/^["']|["']$/g, "");
-          // "- # comment" is a comment-only entry, not a tool.
-          if (item && !rawItem.trimStart().startsWith("#")) items.push(item);
-          index += 1;
-        }
-        index -= 1; // The for-loop steps past the last consumed line.
-        fields.tools = items;
-        continue;
-      }
-      const tools = value
-        .replace(/^\[|\]$/g, "")
-        .split(",")
-        .map((tool) => tool.trim().replace(/^["']|["']$/g, ""))
-        .filter(Boolean);
-      fields.tools = tools;
-      continue;
-    }
-    fields[key] = value.replace(/^["']|["']$/g, "");
-  }
-  return { fields, body: match[2].trim() };
-}
-
-function loadDir(baseScope: AgentScope, dir: string, agents: Map<string, AgentDefinition>): void {
-  let entries: fs.Dirent[];
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return; // A missing agents directory is not an error.
-  }
-  // Dedup by name within the directory: plain .md first so a same-name
-  // xxx.local.md (personal override) overwrites it in the map.
-  const ordered = [...entries].sort((left, right) =>
-    Number(left.name.endsWith(LOCAL_DEFINITION_SUFFIX)) - Number(right.name.endsWith(LOCAL_DEFINITION_SUFFIX))
-    || left.name.localeCompare(right.name),
-  );
-  for (const entry of ordered) {
-    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-    const source = path.join(dir, entry.name);
-    let raw: string;
-    try {
-      raw = fs.readFileSync(source, "utf8");
-    } catch {
-      continue;
-    }
-    const { fields, body } = parseFrontmatter(raw);
-    const isLocal = baseScope === "project" && entry.name.endsWith(LOCAL_DEFINITION_SUFFIX);
-    const baseName = isLocal
-      ? entry.name.slice(0, -LOCAL_DEFINITION_SUFFIX.length)
-      : entry.name.replace(/\.md$/, "");
-    const name = typeof fields.name === "string" ? fields.name : baseName;
-    if (!name || !body) continue;
-    agents.set(name, {
-      name,
-      description: typeof fields.description === "string" ? fields.description : "",
-      tools: Array.isArray(fields.tools) ? fields.tools : [],
-      model: typeof fields.model === "string" && fields.model ? fields.model : undefined,
-      verify: typeof fields.verify === "string" && fields.verify ? fields.verify : undefined,
-      worktree: fields.worktree === "true",
-      prompt: body,
-      scope: isLocal ? "project-local" : baseScope,
-      gitManaged: scopeIsGitManaged(isLocal ? "project-local" : baseScope),
-      source,
-    });
-  }
-}
-
-/** Only the shared project layer is expected to be git-managed. */
-function scopeIsGitManaged(scope: AgentScope): boolean {
-  return scope === "project";
-}
-
-/**
- * Resolve all agent definitions visible from the given cwd, with later scopes
- * overriding earlier ones per name: project-local > project > user.
- */
-export function discoverAgents(cwd?: string): Map<string, AgentDefinition> {
-  const agents = new Map<string, AgentDefinition>();
-  loadDir("user", agentsDir("user", cwd), agents);
-  loadDir("project", agentsDir("project", cwd), agents);
-  // Generated roles fill gaps only: filesystem scopes keep precedence over
-  // session memory.
-  for (const [name, definition] of sessionAgents) if (!agents.has(name)) agents.set(name, definition);
-  return agents;
-}
-
-/** Resolve one agent by name, or undefined when no scope defines it. */
-export function resolveAgent(name: string, cwd?: string): AgentDefinition | undefined {
-  return discoverAgents(cwd).get(name);
-}
-
-/**
- * Format discovered agents as Markdown for prompt injection in before_agent_start.
- */
-export function formatAgentGuidance(cwd?: string): string {
-  const agents = discoverAgents(cwd);
-  if (agents.size === 0) return "(none defined; pass an inline definition when delegating)";
-  const lines: string[] = [];
-  for (const agent of agents.values()) {
-    const extras = [
-      agent.model ? `Model: ${agent.model}` : "",
-      agent.verify ? `Verify: ${agent.verify}` : "",
-      agent.worktree ? "Worktree: true" : "",
-      agent.scope === "session" ? "in-memory" : agent.gitManaged ? "git-managed" : "local",
-    ].filter(Boolean);
-    lines.push(`- **${agent.name}** (${agent.scope})`);
-    if (agent.description) lines.push(`  ${agent.description}`);
-    lines.push(`  Tools: ${agent.tools.join(", ") || "(role defaults)"}${extras.length > 0 ? ` | ${extras.join(" | ")}` : ""}`);
-  }
-  return lines.join("\n");
-}

package/src/leader-reports.ts

@@ -1,92 +0,0 @@
-export const TEAMMATE_REPORT_MESSAGE_TYPE = "agent-teams-report";
-export const TEAMMATE_HARNESS_MESSAGE_TYPE = "agent-teams-harness";
-
-export interface LeaderReport {
-  teammate?: string;
-  agent?: string;
-  spawnId?: string;
-  assignmentId?: string;
-  workId?: string;
-  body: string;
-  /** Worker-authored reports are the default; harness events use a separate envelope. */
-  origin?: "teammate" | "harness";
-  harnessEvent?: {
-    type: string;
-    subject: string;
-  };
-  finished?: boolean;
-  /** Original append-only outbox event identifier, retained for session forensics. */
-  eventId?: string;
-  /** Original worker status, including omitted status, retained for session forensics. */
-  status?: "in_progress" | "completed" | "failed" | "inform" | "request" | "handoff";
-  runId?: string;
-  /** Wall-clock time the message was authored, not when Pi consumed it. */
-  timestamp?: number;
-  deliveredAt?: number;
-  processStoppedAt?: number;
-  deliveredAfterStop?: boolean;
-}
-
-export interface LeaderReportGroup {
-  teammate: string;
-  reports: LeaderReport[];
-}
-
-export function groupReportsByTeammate(reports: LeaderReport[]): LeaderReportGroup[] {
-  const groups = new Map<string, LeaderReportGroup>();
-  for (const report of reports) {
-    const teammate = report.teammate ?? report.agent ?? "teammate";
-    if (report.origin === "harness" || report.harnessEvent) {
-      groups.set(`harness:${groups.size}:${teammate}`, { teammate, reports: [report] });
-      continue;
-    }
-    const key = `message:${teammate}`;
-    const group = groups.get(key);
-    if (group) {
-      group.reports.push(report);
-    } else {
-      groups.set(key, { teammate, reports: [report] });
-    }
-  }
-  return [...groups.values()];
-}
-
-export function annotateReportDelivery(report: LeaderReport, deliveredAt: number, processStoppedAt?: number): LeaderReport {
-  if (processStoppedAt === undefined || deliveredAt < processStoppedAt) return { ...report, deliveredAt };
-  return { ...report, deliveredAt, processStoppedAt, deliveredAfterStop: true };
-}
-
-function timestampAttribute(name: string, timestamp: number | undefined): string {
-  return timestamp !== undefined && Number.isFinite(timestamp)
-    ? ` ${name}="${new Date(timestamp).toISOString()}"`
-    : "";
-}
-
-export function formatReports(reports: LeaderReport[]): string {
-  return reports
-    .map((report) => {
-      const { teammate, body, timestamp, origin, harnessEvent } = report;
-      const at = timestampAttribute("at", timestamp);
-      if (origin === "harness" || harnessEvent) {
-        const type = escapeAttribute(harnessEvent?.type ?? "event");
-        const subject = escapeAttribute(harnessEvent?.subject ?? "Agent Teams event");
-        return `<harness-event type="${type}" subject="${subject}"${at}>\n${body}\n</harness-event>`;
-      }
-      const name = teammate ?? "teammate";
-      const delivery = timestampAttribute("delivered-at", report.deliveredAt);
-      const stopped = timestampAttribute("process-stopped-at", report.processStoppedAt);
-      const late = report.deliveredAfterStop ? ' delivery="after-stop"' : "";
-      const work = report.workId ? ` work="${escapeAttribute(report.workId)}"` : "";
-      const assignment = report.assignmentId ? ` assignment="${escapeAttribute(report.assignmentId)}"` : "";
-      const status = report.status ? ` status="${escapeAttribute(report.status)}"` : "";
-      const note = report.deliveredAfterStop
-        ? "Delivery note: this report was queued before shutdown and delivered after the process stopped. It does not reopen the assignment.\n\n"
-        : "";
-      return `<agent-message from="${escapeAttribute(name)}"${at}${delivery}${stopped}${late}${work}${assignment}${status}>\n${note}${body}\n</agent-message>`;
-    })
-    .join("\n\n");
-}
-
-function escapeAttribute(value: string): string {
-  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
-}