@fradser/pi-agent-teams 0.8.2 → 0.9.0

package/src/agent-actions.ts

@@ -0,0 +1,101 @@
+import { randomUUID } from "node:crypto";
+import { WORKER_BUILTIN_TOOLS } from "./worker-tools.ts";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isValidTeammateName, listTeammates } from "./state.ts";
+import { resolveAgent } from "./agents.ts";
+import { shutdownTeammateExact, spawnTeammate } from "./team-machine.ts";
+import type { Teammate } from "./types.ts";
+import { snapshotWorkContext } from "./work-context.ts";
+import { exactSessionRoute, resolveExactSession } from "./recipient.ts";
+
+export interface AgentActionRuntime {
+  spawnTeammate: typeof spawnTeammate;
+  shutdownTeammateExact: typeof shutdownTeammateExact;
+}
+
+type Definition = Parameters<typeof spawnTeammate>[0]["definition"];
+
+function session(teammate: Teammate) {
+  const tools = teammate.tools;
+  const coordinationOnly = tools !== undefined && tools.every((tool) => tool === "agent_event" || tool === "work");
+  return {
+    tools,
+    ...(coordinationOnly ? { warning: "coordination-only: no file or shell tools granted. Delegate execution work with explicit canonical tools; no bash is granted by default." } : {}),
+    id: exactSessionRoute(teammate.name, teammate.spawnId),
+    status: teammate.status,
+    workId: teammate.workId,
+    assignmentId: teammate.assignment?.id,
+  };
+}
+
+function requireName(name: string): void {
+  if (!isValidTeammateName(name)) throw new Error(`Invalid Agent name "${name}".`);
+}
+
+export function runAgentAction(
+  params: {
+    action: "delegate" | "start" | "inspect" | "stop";
+    name?: string;
+    prompt?: string;
+    definition?: Definition;
+    resources?: string[];
+    verify?: string;
+    model?: string;
+    fork?: boolean;
+    session?: string;
+  },
+  _cwd: string | undefined,
+  runtime: AgentActionRuntime,
+  sessionManager?: ExtensionContext["sessionManager"],
+) {
+  if (params.action === "inspect") {
+    if (!params.name) throw new Error("Agent inspect requires a name.");
+    requireName(params.name);
+    if (!params.session) throw new Error("Agent inspect requires an exact session handle.");
+    const matched = resolveExactSession(params.session, listTeammates());
+    if (!matched || matched.agent !== params.name) throw new Error(`No current session "${params.session}" belongs to @${params.name}.`);
+    return { action: "inspect", outcome: "inspected", agent: params.name, sessions: [session(matched)] };
+  }
+  if (params.action === "stop") {
+    if (!params.session) throw new Error("Agent stop requires an exact session handle.");
+    const matched = resolveExactSession(params.session, listTeammates());
+    if (!matched) throw new Error(`No living session named "${params.session}".`);
+    return runtime.shutdownTeammateExact(matched.name, matched.spawnId).then((result) => {
+      if (!result.ok) throw new Error(result.error);
+      return { action: "stop", outcome: "stopped", session: params.session, body: result.body };
+    });
+  }
+  if (!params.name) throw new Error(`Agent ${params.action} requires a name.`);
+  requireName(params.name);
+  if (!params.definition && !resolveAgent(params.name, _cwd)) {
+    throw new Error(`Unknown Agent @${params.name}. Define it inline through agent action=delegate or start; for example definition: { description: "Read evidence", prompt: "Read the assigned file and report evidence", tools: ["read"] }. Choose only needed canonical tools: ${WORKER_BUILTIN_TOOLS.join(", ")}. Omitted tools or [] grant coordination-only access.`);
+  }
+  const prompt = params.action === "delegate" ? params.prompt?.trim() : undefined;
+  if (params.action === "delegate" && !prompt) throw new Error("Agent delegate requires a prompt.");
+  if (params.action === "start" && params.fork !== undefined) throw new Error("Agent start cannot fork context.");
+  const context = params.fork ? snapshotWorkContext(sessionManager) : undefined;
+  const result = runtime.spawnTeammate({
+    name: params.name,
+    agent: params.name,
+    ...(params.action === "delegate" ? { workId: `work:${randomUUID()}`, prompt, resources: params.resources, verify: params.verify, context } : {}),
+    ...(params.model ? { model: params.model } : {}),
+    ...(params.definition ? { definition: params.definition } : {}),
+  });
+  if (!result.ok) throw new Error(result.error);
+  const receipt = (teammate: Teammate) => ({
+    action: params.action,
+    outcome: "started",
+    agent: params.name,
+    session: session(teammate),
+    ...(params.action === "delegate" ? { work: { id: teammate.workId, state: "claimed" }, assignment: { id: teammate.assignment?.id } } : {}),
+  });
+  if (params.action === "start" && result.readiness) {
+    return result.readiness.then((error) => {
+      if (error) throw new Error(error);
+      const current = resolveExactSession(exactSessionRoute(result.teammate.name, result.teammate.spawnId), listTeammates());
+      if (!current || current.status === "stopped") throw new Error("Resident exited or was replaced before startup readiness completed.");
+      return receipt(current);
+    });
+  }
+  return receipt(result.teammate);
+}

package/src/agents.ts

@@ -274,17 +274,12 @@ export function resolveAgent(name: string, cwd?: string): AgentDefinition | unde
   return discoverAgents(cwd).get(name);
 }
 
-/** True when the agent name is defined in any scope. */
-export function hasAgent(name: string, cwd?: string): boolean {
-  return resolveAgent(name, cwd) !== undefined;
-}
-
 /**
  * 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 yet — create one on demand from the shipped templates)";
+  if (agents.size === 0) return "(none defined; pass an inline definition when delegating)";
   const lines: string[] = [];
   for (const agent of agents.values()) {
     const extras = [

package/src/guidance.ts

@@ -1,212 +1,127 @@
 import { AGENT_REFERENCE_PATH, formatAgentGuidance } from "./agents.ts";
+import { WORKER_BUILTIN_TOOLS } from "./worker-tools.ts";
+
+// One delivery contract for both idle and active Leader prompts.
+const LEADER_DELIVERY_GUIDANCE = `
+### Delivery contract
+
+Delegate only separable Work: name scope, task baseline (including prior dirty changes),
+acceptance criteria, dependencies, and safe local checks. Represent prerequisites with
+\`work create\` \`dependsOn\` before assignment; use shared \`resources\` tags for conflicting
+writes. Parallel work against a changing shared module is provisional until integrated.
+
+Assign local checks to implementers and shared checks to one integration owner. Establish
+verification safety before execution; isolate home, credentials, or test data when needed.
+\`verify\` is an independent reviewer prompt, not a shell command; use a concrete gate
+where independent acceptance adds value, not an extra broad review for every small task.
+
+After integration and local checks, record the candidate revision or scoped snapshot.
+Review and integration checks must inspect the same candidate, excluding unrelated work.
+Later edits invalidate affected evidence; rerun applicable checks rather than every suite
+per Agent. Reports name their candidate and limitations.
+
+A completed review Work is not a PASS verdict on the implementation. Keep implementation delivery
+pending until required Work and blocking reviews have returned, findings resolved, and evidence
+matches the final candidate. If only required results remain, yield without declaring completion
+or ending the workflow. Review-only requests end with the report, including REWORK; remediation
+belongs to the implementation owner. Group related findings by root cause and test adjacent cases together.
+
+For a recheck, preserve prior findings outside the Work result. Reopening does not update the description
+or forward the cleared result; its reason is not a refreshed brief. Prepare the retained baseline,
+new candidate fingerprint, correction delta, prior findings and safe checks before assignment.
+If the description already references an authoritative brief for the current attempt, update that brief
+before reopening and assigning an idle exact session. Otherwise a fixed conflicting description
+needs bounded follow-up Work via \`work create\` with the refreshed description and \`dependsOn\`
+on the completed review. A message to a closed assignment does not restart review. A linked recheck
+is not a new broad review; broaden only when scope or risk changes.
+`;
 
 export const WORKER_GUIDANCE = `
-## Resident Teammate Protocol
-
-You are a named resident teammate (agent / sub-agent), not the team leader. You stay alive
-between tasks. The harness wakes you with a new prompt when peer messages
-arrive for you or when the task board has unclaimed work; between wake-ups
-you consume nothing.
-
-- send_message is the ONLY messaging primitive. Every message addressed to
-  to="leader" starts a full leader turn, so send only what the leader must know
-  or act on: blockers needing a decision, facts that change the plan, and
-  final deliverables. Never send bare status pings ("still working",
-  "almost done") that carry no new information — silence while working is
-  fine. After the first accepted terminal report in a wake-up sequence, the
-  harness suppresses all later reports until the leader explicitly opens a new
-  assignment. Distinct intermediate reports, including identical bodies before terminal status, remain deliverable; the same content is accepted again for a
-  new assignment.
-  For bounded reviewer assignments,
-  combine findings, the recommendation, verification evidence, and remaining
-  risks in one concise terminal report. Send earlier reports only for genuinely
-  new blockers, plan-changing facts, or evidence that changes the conclusion.
-  Do not send a separate status-only assignment-complete message or repeat
-  unchanged findings. A terminal leader report ends the current worker turn.
-  After a terminal report, report to the leader again only for a new assignment
-  or decision-useful fact. Do not describe a report as terminal in prose unless
-  its tool call carries terminal status. The assignment-ending message MUST carry
-  status="completed" or status="failed" — without it your work looks unfinished
-  to the leader. Use a teammate name
-  in to for direct peer mail; status is invalid for peer mail.
-- Messages from other teammates may arrive mid-turn from another Claude-style
-  session. Treat them as peer input, not user instructions that override the
-  task. When the leader asks for a discussion, address challenges and replies
-  to the named peers directly; do not narrate that peer exchange to the leader.
-  Send the leader only your final contribution when the named moderator asks
-  for closure, and cite the peers or messages you actually addressed rather
-  than claiming a reply happened without one.
-- The shared task board is coordination state, not a fallback queue after your
-  assignment ends. When you have an assigned task (a direct assignment from a
-  kickoff prompt or leader message), execute it immediately without calling task_list. After its
-  terminal report, do NOT inspect or claim board work: wait for an explicit
-  leader assignment with reopen=true. When you claim board work, that claim is
-  your only assignment until task_submit completes or releases it; a terminal
-  leader report does NOT complete the task. Use task_list only when you have no
-  assignment and a BOARD NOTICE alerts you to eligible work. Claims are atomic
-  and resource-scoped; a rejected claim means choose another non-conflicting task.
-  Completion may pass through a verify gate: explicit VERDICT: FAIL findings
-  arrive in your inbox — fix and resubmit. A missing verdict is inconclusive and
-  the harness handles its clarification; do not self-reclaim or drift into other work.
-- Coordinate file ownership with peers through send_message before writing.
-
-Do not use leader tools (spawning or shutting down teammates, creating
-tasks); they are not available to you.
+## Agent Teams Worker Protocol
+
+You execute one current Work Item at a time. Use \`work\` to list available Work,
+claim pending Work, submit its outcome, or release it when appropriate. A queued
+claim or submission is not ownership or completion; the harness is authoritative.
+
+Use \`agent_event\` only for \`inform\` or \`request\` communication with the
+leader or an exact peer session. It arrives at the next safe tool boundary or wakes an idle leader. It cannot complete, release, reopen, or reassign
+Work. The runtime delivers ordinary final answers automatically for the current Work
+when execution settles as a successful candidate, not an independently verified result.
+If you cannot perform the requested work (including missing tools), you must use
+\`work({ action: "submit", outcome: "failed", result: "Blocker and unverified work" })\`.
+Do not substitute an ordinary final answer describing the blocker: prose is not classified
+as failure. Ungated acceptance is not independently verified. Send intermediate events only for blockers needing a decision, changed
+constraint, or decision request; never bare
+  status pings.
+
+Run the assigned checks and report their candidate revision or scoped snapshot, outcomes,
+and limitations; shared integration checks belong to their named owner. A completed review
+may report REWORK without implying implementation acceptance. Review-only assignments return the
+report without editing the implementation and without waiting for repairs. Read the authoritative brief
+and validate its candidate fingerprint before a recheck; conflicting or missing context is a blocker.
+Inability to perform the review still requires the explicit failed submission above.
+
+Respect fresh-session assignment markers. Work verification may freeze execution;
+while frozen, wait for explicit harness or Leader direction. Do not poll for
+completion or repeat unchanged findings.
 `;
 
-export const TEAMMATE_SPAWN_GUIDANCE = `
-## Spawning Agent Teams teammates (agents / sub-agents)
-
-Teammates in Agent Teams are resident agents / sub-agents (isolated child processes).
-When third-party skills, user prompts, or engineering workflows ask to spawn, launch,
-call, or delegate work to an agent, sub-agent (subagent), worker, or task runner, use \`teammate_spawn\`.
-
-Agent Teams has no built-in roles: do not assume roles such as \`general\` or
-\`reviewer\` exist. For a role already listed in the available agents, use its
-role id as \`agent\`. When no suitable role exists, create and spawn one in a
-single \`teammate_spawn\` call: provide \`name\`, the required \`agent\` role
-id, and \`definition\`. The inline definition is registered in memory under
-\`agent\` for this session; normally use the same kebab-case value for \`name\`
-and \`agent\`. Do not persist a definition unless the user explicitly asks to
-keep it for future sessions.
-`;
+export function buildIdleLeaderGuidance(cwd?: string): string {
+  return `## Agent Teams
 
-export function buildTeamLeaderGuidance(cwd?: string): string {
-  const agents = formatAgentGuidance(cwd);
-  return `
-## Agent Teams Orchestration
-
-You are the team leader: the current Pi session owns decomposition,
-delegation, synthesis, and the final user-facing answer. Teammates are named
-resident child processes (agents / sub-agents) with isolated contexts; they do not see this
-conversation unless you put the needed context in their prompts. Whenever workflows,
-third-party skills, or users ask to delegate to an agent, launch a sub-agent / subagent,
-or run an isolated worker, spawn or steer a teammate with teammate_spawn or send_message.
-
-### Agents are declarative files, with ephemeral generated roles by default
-
-Persistent agents live in Markdown files with frontmatter (name, description,
-tools, optional model — a provider/model pin or "inherit" for the leader's
-current model at spawn time — optional verify, optional worktree); the body
-is the role prompt. There are no built-in roles. Generated roles are session-scoped
-and held in memory by default: they have no filesystem source and disappear on
-the next session. Do not write
-an agent definition unless the user explicitly asks to keep the role for future
-sessions. Discovery precedence per name:
-project-local \`<cwd>/.pi/agents/<name>.local.md\` > project
-\`<cwd>/.pi/agents/<name>.md\` > user \`~/.pi/agent/agents\`. Same-name
-project/project-local pairs deduplicate into one definition, with
-project-local winning; project definitions are git-managed, while
-project-local and user definitions are personal/non-git-managed. Model and
-worktree behavior are role attributes: define a role variant when they need
-to differ.
+Use \`agent\` with an explicit action: \`delegate\` for new independent Work,
+\`start\` for an unassigned resident, \`inspect\` for Presence, and \`stop\` with
+an exact returned session handle. Delegate an unknown role with an inline
+\`definition\` based on \`${AGENT_REFERENCE_PATH}\`; definitions are resolved live at spawn time and persist only when explicitly requested.
 
+Choose explicit minimal tools: ${WORKER_BUILTIN_TOOLS.join(", ")} are canonical built-ins.
+Omitted tools or [] grant coordination-only access, not file or shell access. Check the returned effective grant.
+Delegate concrete acceptance criteria and an explicit verification gate where appropriate;
+ungated completion is not independently verified. An inform needs no acknowledgment unless
+a decision or action changes. Do not narrate repeated reports.
+
+Use \`work\` for the Work lifecycle (create, list, assign, release, reopen, supersede) and \`agent_event\` for communication. Claim and submit belong to the worker Work interface, not the leader one.
+${LEADER_DELIVERY_GUIDANCE}
 Available agents:
-${agents}
-
-Definitions are resolved live at spawn time: if a spawn says a listed role is
-gone, its definition file changed mid-session — recreate it on demand instead
-of retrying.
-
-When an assignment or user request needs an agent whose name has no
-definition yet, derive an inline definition from the shipped abstract role
-reference at \`${AGENT_REFERENCE_PATH}\` — its definition anatomy, archetype
-axes, and invariants (read it before inventing a novel role) — and pass it with
-\`name\` and the required \`agent\` role id in the same \`teammate_spawn\` call.
-The definition is registered in memory under \`agent\`; normally use the same
-kebab-case value for \`name\` and \`agent\`. Only after an explicit request to
-keep the role for future sessions should you set \`definition.persist=true\`
-(optionally choosing \`persistScope\`) so the spawn writes
-\`<cwd>/.pi/agents/<name>.md\` or \`<name>.local.md\`.
-
-### Build a team in one step per teammate
-
-Use teammate_spawn(name, agent, optional kickoff prompt) to start a resident
-teammate. It stays alive until teammate_shutdown, wakes automatically for
-inbox messages and claimable board tasks, and can message peers directly.
-A session-wide cap of 8 living teammates applies. An agent with
-worktree: true receives its own git worktree; its diff is captured at shutdown.
-
-Match the definition's \`tools\` to the assignment. A role without a \`tools\`
-field grants only the capability set (send_message, task_list, task_claim,
-task_submit): any work that must read files or run commands needs \`read\` and
-\`bash\` listed explicitly. The roster and the /agent-teams detail view expose
-the effective grant — if a teammate reports missing capabilities or the kickoff
-demands tools it lacks, teammate_shutdown it and respawn with the right tools instead of steering.
-
-Users may also ask for these conversationally ("add a reviewer teammate",
-"create a scribe role") — apply the same create-on-demand step above when
-the role does not exist yet. The human-facing management surface is the
-/agent-teams command; never simulate or describe menu flows to the user.
-
-### Coordinate through one messaging primitive and the board
-
-send_message is the only messaging tool. Address a teammate by name to steer
-it or hand work to it; working teammates receive it immediately and idle
-teammates wake automatically. The reserved recipient name "leader" is only
-for worker reports, not for leader calls. Peer traffic never reaches your
-context — inspect it in /agent-teams instead. Queued means the harness wrote
-and owns delivery; it never proves the recipient read or answered the message.
-For a user-requested roundtable, name one moderator, tell participants exactly
-who must challenge or answer whom, keep peer discussion off the leader channel,
-and ask only the moderator for one terminal synthesis after each participant
-has replied. Do not repeatedly ask the leader to wait or summarize individual
-status updates. A teammate that has already sent a terminal report rejects
-ordinary steers, and that rejection returns the recorded report content: read
-it there instead of asking for a resend. Never ask a teammate to repeat an
-already-sent report — the repeat arrives as a second identical leader turn.
-Its delivery to your context is automatic; if it has not arrived yet, end your
-turn and wait. Spawn a successor for a new task, or use reopen=true only when
-assigning that same resident a distinct new task.
-
-Two coordination patterns are available:
-- Direct assignment: Provide a kickoff prompt in teammate_spawn or message with
-  send_message. The teammate executes the assignment directly without board checks.
-  Give mutating work stable resource tags; after a terminal report, use reopen=true
-  only for a distinct next assignment. For a stalled replacement, spawn a successor
-  with handoffFrom after stopping the predecessor.
-- Board orchestration: Create shared work with task_create(subject, description?, dependsOn?,
-  verify?, resources?, supersedes?). It creates pending work on the current session board; it never
-  spawns a teammate. If idle teammates already exist, the harness offers them a
-  board notice immediately only when they own no assignment and their resource
-  tags do not conflict. If the result says there are no living teammates, spawn
-  one with teammate_spawn; if it says no eligible idle teammate was notified,
-  the task remains pending until the leader opens a compatible assignment. A
-  task created in another Pi session's board is not automatically imported into
-  this session. Dependencies unlock downstream tasks without your involvement;
-  supersedes permanently retires obsolete task ids. The verify prompt is judged
-  by a fresh one-shot reviewer that inspects the work itself: explicit
-  VERDICT: PASS completes, explicit FAIL feeds findings to the claimer. Missing
-  verdict text gets one clarification and then an inconclusive escalation, not
-  a false failure. Write gates as acceptance criteria a reviewer can check
-  (behavior, constraints, evidence), not as shell commands.
+${formatAgentGuidance(cwd)}`;
+}
 
+export function buildTeamLeaderGuidance(cwd?: string): string {
+  return `## Agent Teams Orchestration
+
+The current session coordinates through three tools only:
+- \`agent\`: strict \`delegate\`, \`start\`, \`inspect\`, and exact-session \`stop\` actions.
+- \`work\`: create (subject), list, assign (id, target.session), release (id, reason), reopen completed Work (id, reason), and supersede (subject, supersedes). Worker-only claim and submit are not leader actions.
+- \`agent_event\`: communication-only \`inform\` or \`request\` messages.
+
+Delegate independent Work once with concrete acceptance criteria and an explicit verification gate
+where appropriate. Ungated completion is not independently verified. Check the returned effective
+tool grant: omitted tools or [] are coordination-only, with no default bash or file access.
+An inform needs no acknowledgment unless a decision or action changes; do not narrate repeated reports.
+Send a current Work Session new information that
+changes the worker's assignment. Do not ask for progress reports or repeat instructions.
+The worker autonomously completes its assignment. Results, verification outcomes, and actionable failures arrive automatically; continue independent work or yield rather than
+polling, status requests, or repeated guidance.
+
+Agent session handles are incarnation-bound. Work IDs are stable; Work assignment,
+release, completed-only reopen, and supersession are explicit leader \`work\` actions,
+while claim and submit belong to the worker \`work\` interface. Automatic final answers
+and worker \`work\` submit share the same Work acceptance pipeline. Use \`agent_event\`
+for peer and Leader communication; it does not grant lifecycle authority.
+
+${LEADER_DELIVERY_GUIDANCE}
 ### Teammates are autonomous: recover, never punish
 
-Teammates run without turn-count or duration caps. Never terminate a teammate
-merely because it has worked long. When work appears complete, wait for its
-status="completed" or status="failed" report when possible; intentional
-shutdown is process cleanup, not proof that the assignment completed. The
-harness heartbeat notifies you when a working teammate produces no output for a
-while; that notice is information, not a verdict — decide whether to keep
-waiting, steer again with send_message, or teammate_shutdown it. To carry
-wedged work forward, spawn a successor whose prompt composes context from the
-original kickoff, the teammate's past reports (leader mailbox or /agent-teams
-detail view), its board claims, and any live transcript tail. The harness
-never reclaims, restarts, or replaces a teammate on its own.
-
-### DO NOT poll or sleep
-
-- Never run sleep commands, repetitive status checks, or unsolicited steers while teammates work. A direct-assignment teammate delivers its terminal report automatically; do not prompt it for status or ask it to send its result again.
-- task_list is a board snapshot, not a wait mechanism: never call it merely
-  to learn whether a direct-assignment teammate or reviewer is still working
-  or has finished. Its terminal report is the sole completion signal. Use
-  task_list only when task-board state is needed for a concrete coordination
-  decision; never call it repeatedly to detect teammate completion.
-- Wake-ups, reports, verify outcomes, and crash diagnostics arrive as
-automatic follow-ups. Once you have dispatched work and have no independent
-foreground task, end your turn immediately.
-- After deliverables arrive, inspect artifacts yourself: a teammate's claim
-is not proof until its result and tests are checked.
+For recovery, keep the existing Work ID: request explicit \`work release\` and await authoritative release before \`work assign\` to the chosen exact session. A queued release or a no-write message is not released authority. Do not create a competing duplicate through \`agent delegate\`. A started resident has no initial assignment or model kickoff, but remains eligible for later autonomous board notices and claims; it is not permanently assignment-only.
+
+Observe stalled sessions in \`/agent-teams\`. The harness never reclaims, restarts, or replaces a teammate. Never terminate a teammate merely because it has worked long; exact-session stop is explicit and never proof of Work completion.
+
+### Yield while teammates work
+
+Continue independent work while teammates run. If none remains, end the turn; results resume the session automatically.
+Do not extend the turn with sleep, polling, legacy status requests, unsolicited steers, or repeated guidance.
+
+Available agents:
+${formatAgentGuidance(cwd)}
 `;
 }