paseo-bm-plugin 0.0.0-placeholder.0

package/server/stop-propagation.ts

@@ -0,0 +1,365 @@
+import type { PluginLifecycleEvents, PluginServerContext } from "@getpaseo/plugin/server";
+import { PARENT_AGENT_LABEL } from "./manager";
+import { REVIEWER_STOP_NOTICE_PREFIX, WORKER_STOP_NOTICE } from "./notices";
+import { listAllAgents, roleOfAgent, roleOfProvider } from "./agent-role";
+
+/**
+ * Stop propagation from a Beads Worker to its running Reviewers (bm-wq6, REQ-026f).
+ *
+ * When the user stops a Worker (app Stop button or `paseo stop`), Paseo 0.8
+ * interrupts only the Worker's turn; a Reviewer the Worker created keeps
+ * running. Paseo gives plugins no agent cancel, so the closest supported
+ * interrupt is used: `PaseoAgentHandle.send()` on a running agent replaces its
+ * current turn with a new one carrying a fixed stop notice, which
+ * `roles/reviewer.md` answers with one line and no tool calls.
+ *
+ * SDK facts this relies on (checked against @getpaseo/plugin 0.8.0 and
+ * @getpaseo/client 0.8.0 typings, not guessed):
+ * - `on("agent.turn_ended", (event, { paseo, signal }) => …)`; the event carries
+ *   `agent: { id, workspaceId, provider, … }` and `outcome`, whose `kind` is
+ *   `completed`, `failed` or `canceled` (lifecycle.d.ts).
+ * - `canceled` does not tell a user stop from a message that replaced the
+ *   turn, so the Worker is re-read with `agents.ref(id).refresh()`: `running`
+ *   means a new turn already started and nothing is done.
+ * - `agents.list({ filter: { labels, includeArchived }, page })` pages like
+ *   `manager.ts`; the result is filtered again here, never trusted.
+ *
+ * Lifecycle belongs to the user (ADR-005): nothing here archives or deletes.
+ */
+
+/** `bm.role` value that identifies a Reviewer (design §5). */
+export const REVIEWER_ROLE_VALUE = "reviewer";
+
+/**
+ * Wait before the single re-check of a Worker that still reads `running` right
+ * after its turn was canceled. Mirrors the plugin poll interval of design §8
+ * (`PLUGIN_POLL_INTERVAL_MS` in the CLI, which the plugin bundle cannot import);
+ * it is not a new product timeout.
+ */
+export const STOP_RECHECK_MS = 500;
+
+/**
+ * The notice sent to each running Reviewer of a stopped Worker. `roles/reviewer.md`
+ * recognises it verbatim; do not reword it without changing the role.
+ */
+export const REVIEWER_STOP_NOTICE =
+  `${REVIEWER_STOP_NOTICE_PREFIX} by the user. Stop this review now: do not read files, run commands or call any tool; reply with the single line "BM-REVIEW STOPPED" and end your turn.`;
+
+const LOG_PREFIX = "[paseo-bm] stop propagation:";
+
+// ---------------------------------------------------------------------------
+// Minimal, injectable view of the Paseo SDK. `PaseoApi` from @getpaseo/client
+// is structurally assignable to it (registerStopPropagation passes the real
+// one, which `npm run typecheck:plugin` checks); tests pass a fake.
+// ---------------------------------------------------------------------------
+
+export interface StopAgentSnapshot {
+  id: string;
+  workspaceId?: string;
+  status: string;
+  labels: Record<string, string>;
+  /** Provider selection; decides the role when the `bm.role` label is missing (delta 20260918g). */
+  provider?: string;
+  archivedAt?: string | null;
+}
+
+export interface StopAgentHandle {
+  refresh(): Promise<{ agent: StopAgentSnapshot } | null>;
+  send(text: string): Promise<void>;
+}
+
+export interface StopPaseo {
+  agents: {
+    list(options: {
+      filter: { labels?: Record<string, string>; includeArchived: boolean };
+      page: { limit: number; cursor?: string };
+    }): Promise<{
+      entries: Array<{ agent: StopAgentSnapshot }>;
+      pageInfo: { nextCursor: string | null; hasMore: boolean };
+    }>;
+    ref(agentId: string): StopAgentHandle;
+  };
+}
+
+export type TurnEndedEvent = PluginLifecycleEvents["agent.turn_ended"];
+
+export interface StopPropagationContext {
+  paseo: StopPaseo;
+  signal?: AbortSignal;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isAborted(signal: AbortSignal | undefined): boolean {
+  return signal?.aborted === true;
+}
+
+/** Resolves after `ms`, or at once when `signal` aborts. Never rejects. */
+function wait(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  return new Promise((resolve) => {
+    if (isAborted(signal)) {
+      resolve();
+      return;
+    }
+    const done = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+
+/** The event is the end of a canceled turn of a Worker (`bm-worker`, or a fallback Worker alias). */
+export function isCanceledWorkerTurn(event: TurnEndedEvent): boolean {
+  const candidate = event as Partial<TurnEndedEvent> | null | undefined;
+  return (
+    candidate?.outcome?.kind === "canceled" &&
+    typeof candidate.agent?.id === "string" &&
+    roleOfProvider(candidate.agent.provider) === "worker"
+  );
+}
+
+/** A live, running Reviewer created by `workerId` in `workspaceId` (when known). */
+function isRunningReviewerOf(
+  agent: StopAgentSnapshot | null | undefined,
+  workerId: string,
+  workspaceId: string | null,
+): agent is StopAgentSnapshot {
+  if (!agent) return false;
+  const labels = agent.labels ?? {};
+  return (
+    labels[PARENT_AGENT_LABEL] === workerId &&
+    // By label, or by the bm-reviewer provider when the label is missing (delta 20260918g §4.2).
+    roleOfAgent(agent)?.role === REVIEWER_ROLE_VALUE &&
+    !agent.archivedAt &&
+    agent.status === "running" &&
+    (workspaceId === null || agent.workspaceId === workspaceId)
+  );
+}
+
+async function readStatus(paseo: StopPaseo, agentId: string): Promise<StopAgentSnapshot | null> {
+  const result = await paseo.agents.ref(agentId).refresh();
+  return result?.agent ?? null;
+}
+
+/** Every running Reviewer of the Worker, walking all pages. */
+async function listRunningReviewers(
+  paseo: StopPaseo,
+  workerId: string,
+  workspaceId: string | null,
+): Promise<StopAgentSnapshot[]> {
+  // Filtered on the parent only: a Reviewer without the bm.role label is still
+  // a Reviewer when its provider is bm-reviewer (delta 20260918g §4.2).
+  const children = await listAllAgents((options) => paseo.agents.list(options), {
+    labels: { [PARENT_AGENT_LABEL]: workerId },
+    includeArchived: false,
+  });
+  return children.filter((agent) => isRunningReviewerOf(agent, workerId, workspaceId));
+}
+
+/**
+ * Sends `REVIEWER_STOP_NOTICE` to every running Reviewer of `workerId` (in
+ * `workspaceId` when known), re-reading each one just before the send and
+ * skipping it unless it is still running. Returns the ids it sent to. Never
+ * throws: a failure costs one log line; an aborted `signal` ends it quietly.
+ * Also used when a fallback Worker replaces a stopped one (delta 20260921 §4.4.7).
+ */
+export async function stopRunningReviewers(
+  paseo: StopPaseo,
+  workerId: string,
+  workspaceId: string | null,
+  signal?: AbortSignal,
+): Promise<string[]> {
+  const stopped: string[] = [];
+  let reviewers: StopAgentSnapshot[];
+  try {
+    reviewers = await listRunningReviewers(paseo, workerId, workspaceId);
+  } catch (error) {
+    if (!isAborted(signal)) {
+      console.warn(`${LOG_PREFIX} could not list the Reviewers of Worker ${workerId}: ${describeError(error)}`);
+    }
+    return stopped;
+  }
+  for (const reviewer of reviewers) {
+    if (isAborted(signal)) return stopped;
+    try {
+      const handle = paseo.agents.ref(reviewer.id);
+      const fresh = await handle.refresh();
+      if (isAborted(signal)) return stopped;
+      if (!isRunningReviewerOf(fresh?.agent, workerId, workspaceId)) continue;
+      await handle.send(REVIEWER_STOP_NOTICE);
+      stopped.push(reviewer.id);
+    } catch (error) {
+      if (isAborted(signal)) return stopped;
+      console.warn(`${LOG_PREFIX} could not stop Reviewer ${reviewer.id} of Worker ${workerId}: ${describeError(error)}`);
+    }
+  }
+  return stopped;
+}
+
+/**
+ * Handler body of `on("agent.turn_ended")`. Resolves in every case: failures are
+ * logged with `console.warn`, an aborted `signal` ends it quietly.
+ *
+ * 1. Ignore anything but a canceled turn of a `bm-worker`.
+ * 2. Re-read the Worker; if it is `running`, wait `STOP_RECHECK_MS` once and
+ *    read again. Still `running` means a message replaced the turn: stop here.
+ * 3. List the Worker's running, non-archived `bm.role=reviewer` children in its
+ *    workspace; re-read each one just before sending and skip it unless it is
+ *    still running; send `REVIEWER_STOP_NOTICE`.
+ */
+export async function propagateWorkerStop(
+  event: TurnEndedEvent,
+  context: StopPropagationContext,
+): Promise<void> {
+  const signal = context?.signal;
+  try {
+    if (!isCanceledWorkerTurn(event) || isAborted(signal)) return;
+    const { paseo } = context;
+    const workerId = event.agent.id;
+
+    let worker: StopAgentSnapshot | null;
+    try {
+      worker = await readStatus(paseo, workerId);
+      if (isAborted(signal)) return;
+      if (worker?.status === "running") {
+        await wait(STOP_RECHECK_MS, signal);
+        if (isAborted(signal)) return;
+        worker = await readStatus(paseo, workerId);
+        if (isAborted(signal)) return;
+        if (worker?.status === "running") return;
+      }
+    } catch (error) {
+      if (!isAborted(signal)) {
+        console.warn(`${LOG_PREFIX} could not re-read Worker ${workerId}: ${describeError(error)}`);
+      }
+      return;
+    }
+
+    const workspaceId = event.agent.workspaceId ?? worker?.workspaceId ?? null;
+    await stopRunningReviewers(paseo, workerId, workspaceId, signal);
+  } catch (error) {
+    if (!isAborted(signal)) {
+      console.warn(`${LOG_PREFIX} unexpected failure: ${describeError(error)}`);
+    }
+  }
+}
+
+/** The part of the server context this hook needs; `on` is absent on older hosts. */
+export type StopPropagationHost = Partial<Pick<PluginServerContext, "on" | "before">>;
+
+/**
+ * Registers the `on("agent.turn_ended")` hook and returns its remover. On a host
+ * without `on` it returns a no-op and logs one line — unless the host has no
+ * lifecycle hooks at all (no `before` either), where `registerRoleHook` has
+ * already logged the one line for that host.
+ */
+export function registerStopPropagation(host: StopPropagationHost): () => void {
+  if (typeof host.on !== "function") {
+    if (typeof host.before === "function") {
+      console.warn(
+        "[paseo-bm] this Paseo host has no on(\"agent.turn_ended\") hook; stopping a Worker will not stop its running Reviewers.",
+      );
+    }
+    return () => {};
+  }
+  const remove = host.on("agent.turn_ended", (event, context) =>
+    propagateWorkerStop(event, { paseo: context?.paseo, signal: context?.signal }),
+  );
+  return typeof remove === "function" ? remove : () => {};
+}
+
+// ---------------------------------------------------------------------------
+// `/bm-worker-stop-all` (delta 20260917e §4.4).
+// ---------------------------------------------------------------------------
+
+/** Label value of a Beads Worker. */
+export const WORKER_ROLE_VALUE = "worker";
+
+export interface StopAllResult {
+  /** Workers the notice reached. */
+  workers: number;
+  /** Reviewers the notice reached. */
+  reviewers: number;
+  /** Candidates that were archived, closed or no longer running when re-read. */
+  skipped: number;
+}
+
+/**
+ * Every non-archived agent of one role in one workspace, walking all pages.
+ *
+ * Listed with no label filter and decided by `roleOfAgent` (delta 20260918g
+ * §4.2): a Worker or Reviewer started without the bm.role label is found by its
+ * provider. The role is decided per agent here, never by the daemon's filter, so
+ * nothing this command never promised to touch — the Manager above all — can
+ * slip in: a Manager's role is `manager` by label and by provider alike.
+ */
+async function listByRole(paseo: StopPaseo, role: string, workspaceId: string): Promise<StopAgentSnapshot[]> {
+  const all = await listAllAgents((options) => paseo.agents.list(options), { includeArchived: false });
+  return all.filter(
+    (agent) => agent && roleOfAgent(agent)?.role === role && !agent.archivedAt && agent.workspaceId === workspaceId,
+  );
+}
+
+/**
+ * Asks every running Worker and Reviewer of one workspace to stop.
+ *
+ * **This asks; it does not force.** Paseo gives plugins no agent cancel, so the
+ * only supported interrupt is `send()` on a running agent, which replaces the
+ * turn it is in with one carrying a stop notice. Everything downstream — the
+ * command's reply to the user, the wording in the role files — has to say
+ * "asked to stop", never "stopped".
+ *
+ * Three rules the loop exists to keep:
+ * - **The Manager is never touched.** It is the user's point of contact, and the
+ *   command's own name only promises Workers. Only the worker and reviewer
+ *   roles are ever collected, by label or by provider.
+ * - **One workspace only** (owner decision Q28). A machine-wide stop is too
+ *   large a consequence for one mistyped line.
+ * - **An archived agent is skipped**, because `send()` would UN-archive it, and
+ *   ADR-005 says agents belong to the user. Each candidate is re-read
+ *   immediately before the send, so an agent archived or finished since the
+ *   listing is skipped too rather than resurrected.
+ */
+export async function stopAllInWorkspace(
+  paseo: StopPaseo,
+  workspaceId: string,
+  log: (message: string) => void = (message) => console.warn(message),
+): Promise<StopAllResult> {
+  const result: StopAllResult = { workers: 0, reviewers: 0, skipped: 0 };
+  const targets: Array<{ agent: StopAgentSnapshot; role: string; notice: string }> = [
+    ...(await listByRole(paseo, WORKER_ROLE_VALUE, workspaceId)).map((agent) => ({
+      agent,
+      role: WORKER_ROLE_VALUE,
+      notice: WORKER_STOP_NOTICE,
+    })),
+    ...(await listByRole(paseo, REVIEWER_ROLE_VALUE, workspaceId)).map((agent) => ({
+      agent,
+      role: REVIEWER_ROLE_VALUE,
+      notice: REVIEWER_STOP_NOTICE,
+    })),
+  ];
+
+  for (const target of targets) {
+    // Re-read: the listing is a moment old, and `send()` on an agent archived
+    // in between would bring it back (ADR-005).
+    const fresh = await readStatus(paseo, target.agent.id);
+    if (!fresh || fresh.archivedAt || fresh.status !== "running") {
+      result.skipped += 1;
+      continue;
+    }
+    try {
+      await paseo.agents.ref(target.agent.id).send(target.notice);
+      if (target.role === WORKER_ROLE_VALUE) result.workers += 1;
+      else result.reviewers += 1;
+    } catch (error) {
+      result.skipped += 1;
+      log(`${LOG_PREFIX} could not ask ${target.agent.id} to stop (${error instanceof Error ? error.message : String(error)}).`);
+    }
+  }
+  return result;
+}

package/server/tools-check.ts

@@ -0,0 +1,118 @@
+/**
+ * Whether a new Manager or Worker has Paseo's tools (delta 20260921 §4.2.4,
+ * REQ-063 d).
+ *
+ * Pi drops `mcpServers` silently when the `pi-mcp-adapter` extension is
+ * missing (proposal P4): the agent is created but has no Paseo tools, so a
+ * Worker cannot send a `BM-REPORT` or create a Reviewer. The agent's
+ * `capabilities.supportsMcpServers` says so. For a new Worker the plugin tells
+ * the parent Manager with a `BM-TOOLS` notice, through the notice queue, since
+ * that Manager is usually still running the turn that created the Worker
+ * (design F13). Every check is also kept in memory for the Setup screen.
+ *
+ * That `supportsMcpServers` is `false` for Pi without its adapter is inferred
+ * from the code (proposal O4), not observed: the owner checks it on the real
+ * daemon at the phase acceptance. Nothing here throws.
+ */
+import { roleOfAgent } from "./agent-role";
+import { TOOLS_NOTICE_MARKER } from "./notices";
+import { enqueue as defaultEnqueue, type NoticeOutcome, type NoticePaseo } from "./notice-queue";
+
+/** The two roles that need Paseo's tools. */
+export type ToolsRole = "manager" | "worker";
+
+export type ToolsState = "ok" | "missing" | "unknown";
+
+/** The last check of one role, as `setup.status` reports it. */
+export interface ToolsSeen {
+  state: ToolsState;
+  agentId: string;
+  provider: string;
+  at: string;
+}
+
+const seen = new Map<ToolsRole, ToolsSeen>();
+
+/** The state a `supportsMcpServers` value means. */
+export function toolsStateOf(supportsMcpServers: unknown): ToolsState {
+  return supportsMcpServers === true ? "ok" : supportsMcpServers === false ? "missing" : "unknown";
+}
+
+/** Records the check of one agent; the newest check of a role wins. */
+export function recordTools(role: ToolsRole, agentId: string, provider: string, supportsMcpServers: unknown, at: string = new Date().toISOString()): ToolsSeen {
+  const entry: ToolsSeen = { state: toolsStateOf(supportsMcpServers), agentId, provider, at };
+  seen.set(role, entry);
+  return entry;
+}
+
+/** The last check of each role, or `null` when none ran in this plugin run. */
+export function toolsSeen(): { manager: ToolsSeen | null; worker: ToolsSeen | null } {
+  return { manager: seen.get("manager") ?? null, worker: seen.get("worker") ?? null };
+}
+
+/** Forgets every check; for tests. */
+export function forgetTools(): void {
+  seen.clear();
+}
+
+/** The notice the parent Manager gets. Agent-facing, so English. */
+export function toolsNotice(workerId: string, provider: string): string {
+  return `${TOOLS_NOTICE_MARKER} Worker ${workerId} runs on ${provider} without Paseo tools (on Pi this means pi-mcp-adapter is missing). It cannot send you a BM-REPORT or create a Reviewer. Tell the user in one line; do not create another Worker for this request unless the user asks.`;
+}
+
+/** The snapshot fields this module reads. */
+export interface ToolsAgentSnapshot {
+  status?: string | null;
+  archivedAt?: string | null;
+  provider?: string;
+  labels?: Record<string, string> | null;
+  capabilities?: { supportsMcpServers?: unknown } | null;
+}
+
+/** The SDK slice this module reads; `PaseoApi` is structurally assignable, and so is it to the notice queue's. */
+export interface ToolsPaseo {
+  agents: {
+    ref(agentId: string): {
+      refresh(): Promise<{ agent?: ToolsAgentSnapshot | null } | null>;
+      send(text: string): Promise<void>;
+    };
+  };
+}
+
+export interface ToolsCheckDeps {
+  enqueue?: (targetId: string, kind: string, text: string, paseo?: NoticePaseo) => Promise<NoticeOutcome>;
+  log?: (message: string) => void;
+}
+
+/**
+ * Checks a Worker just created. `agent` is the `agent.created` event's agent.
+ * Records the result; when the Worker has no Paseo tools and its parent is a
+ * Manager, queues `BM-TOOLS` for that Manager. Never throws.
+ */
+export async function checkWorkerTools(
+  agent: { id: string; provider: string; parentAgentId?: string | null },
+  paseo: ToolsPaseo,
+  deps: ToolsCheckDeps = {},
+): Promise<ToolsState> {
+  const log = deps.log ?? ((message: string) => console.warn(message));
+  try {
+    const snapshot = await paseo.agents.ref(agent.id).refresh();
+    const entry = recordTools("worker", agent.id, agent.provider, snapshot?.agent?.capabilities?.supportsMcpServers);
+    if (entry.state !== "missing") return entry.state;
+    const parentId = agent.parentAgentId ?? null;
+    if (parentId === null) {
+      log(`[paseo-bm] Worker ${agent.id} runs on ${agent.provider} without Paseo tools, and has no Manager to tell.`);
+      return entry.state;
+    }
+    const parent = await paseo.agents.ref(parentId).refresh();
+    if (roleOfAgent(parent?.agent)?.role !== "manager") {
+      log(`[paseo-bm] Worker ${agent.id} runs on ${agent.provider} without Paseo tools; its parent ${parentId} is not a Beads Manager, so nobody is told.`);
+      return entry.state;
+    }
+    await (deps.enqueue ?? defaultEnqueue)(parentId, TOOLS_NOTICE_MARKER, toolsNotice(agent.id, agent.provider), paseo);
+    return entry.state;
+  } catch (error) {
+    log(`[paseo-bm] checking the Paseo tools of ${agent.id} failed: ${error instanceof Error ? error.message : String(error)}`);
+    return "unknown";
+  }
+}