paseo-bm-plugin 0.0.0-placeholder.0

package/server/fallback-manager.ts

@@ -0,0 +1,170 @@
+/**
+ * "Switch to <candidate>" for a stopped Manager (delta 20260921 §4.5.2,
+ * REQ-066 c): the user is chatting with the Manager that stopped, so the
+ * plugin creates the replacement in the same workspace, and the user opens it
+ * from the usual entries (Beads Manager skips a replaced Manager).
+ *
+ * 1. The incident is still `pending` with a candidate (`fallback.act` runs one
+ *    action at a time); the old Manager has no `bm.replacedBy`; the
+ *    candidate's provider is available.
+ * 2. `BM-HANDOVER` role manager (`managerHandover`, 5 s budget).
+ * 3. `createManager` — the same path as `manager.ensure`, so the same
+ *    instructions, Runtime facts and labels — on `bm-manager-fallback-<n>/<model>`,
+ *    with the Manager rule's mode (`bm.modeSet` when one is chosen), the
+ *    entry's thinking, `bm.replaces` = the old Manager, and the handover as
+ *    its first message.
+ * 4. `bm.replacedBy` on the old Manager; a failure only logs.
+ * 5. Every live, non-replaced Worker of the workspace gets a `BM-SETTINGS`
+ *    with the new Manager's id, through the notice queue.
+ * 6. `switched` with `replacementId`; the caller sends BM-FALLBACK into the
+ *    old Manager's chat.
+ * 7. A creation that fails records `failed` and returns
+ *    `E_FALLBACK_CREATE_FAILED`, never back to `pending`.
+ */
+import { peersOfWorkspace } from "./chat-peers";
+import { createLocationResolver, resolveLocationFromPaseo } from "./collector";
+import { bmAgentsOf, type DashboardPaseo } from "./dashboard-rpc";
+import { REPLACED_BY_LABEL } from "./fallback-detect";
+import { liveWorkersOf, managerHandover } from "./fallback-handover";
+import { decidePending, type FallbackAction, type FallbackRpcDeps } from "./fallback-rpc";
+import { readIncidents, replacementsOf } from "./fallback-state";
+import { createManager, type ManagerPaseo } from "./manager";
+import { enqueue as defaultEnqueue, type NoticeOutcome, type NoticePaseo } from "./notice-queue";
+import { SETTINGS_NOTICE_MARKER } from "./notices";
+import { setAgentLabels, type CliResult } from "./paseo-cli";
+import { asRecord, availableProviders, nonEmpty, reasonOf } from "./role-choices";
+import { currentInstructions } from "./role-extras";
+import { capabilityOf, featuresFor, managerModeFor, modesFor, runPostureOf } from "./role-mode";
+import { managerIdNotice } from "./settings-notices";
+import type { TraceStoreLocation } from "./trace-store";
+import { DashboardError, type FallbackIncident } from "../shared/contracts";
+
+const REPLACES_LABEL = "bm.replaces";
+const MODE_SET_LABEL = "bm.modeSet";
+
+export interface ManagerSwitchDeps {
+  log?: (message: string) => void;
+  now?: () => Date;
+  /** `setAgentLabels` of `paseo-cli.ts` by default. */
+  setLabels?: (agentId: string, labels: Record<string, string>) => Promise<CliResult>;
+  enqueue?: (targetId: string, kind: string, text: string, paseo?: NoticePaseo) => Promise<NoticeOutcome>;
+  /** The Manager instructions; `currentInstructions("manager", paseo)` by default. */
+  readInstructions?: (paseo: unknown) => Promise<string>;
+  /** `managerHandover` by default. */
+  handover?: (incident: FallbackIncident, deps: { paseo: unknown; location: TraceStoreLocation | null; incidents: readonly FallbackIncident[] | null }) => Promise<string>;
+  /** The workspace trace store; the collector's resolver by default. */
+  location?: (paseo: unknown) => Promise<TraceStoreLocation | null>;
+}
+
+/** The mode and features the replacement Manager starts with, by the candidate provider's capability. */
+async function postureFor(
+  paseo: unknown,
+  candidate: NonNullable<FallbackIncident["candidate"]>,
+  log: (message: string) => void,
+): Promise<{ modeId?: string; featureValues?: Record<string, unknown> }> {
+  const modes = await modesFor(paseo, candidate.alias, log);
+  const capability = capabilityOf(modes);
+  if (capability === "none") return {};
+  if (capability === "tiered") {
+    const modeId = managerModeFor(modes!, candidate.modeId);
+    return modeId === undefined ? {} : { modeId };
+  }
+  if (capability === "untiered") {
+    const features = await featuresFor(paseo, `${candidate.alias}/${candidate.model}`, undefined, log);
+    const posture = runPostureOf("manager", capability, modes!, features, candidate.modeId);
+    return {
+      ...(typeof posture?.modeId === "string" ? { modeId: posture.modeId } : {}),
+      ...(posture?.featureValues ? { featureValues: posture.featureValues } : {}),
+    };
+  }
+  return candidate.modeId === null ? {} : { modeId: candidate.modeId };
+}
+
+/** The `switch` action of `fallback.act` for a Manager. */
+export function createManagerSwitch(deps: ManagerSwitchDeps = {}): FallbackAction {
+  const log = deps.log ?? ((message: string) => console.warn(message));
+  const setLabels = deps.setLabels ?? ((agentId: string, labels: Record<string, string>) => setAgentLabels(agentId, labels));
+  const enqueue = deps.enqueue ?? defaultEnqueue;
+  const readInstructions = deps.readInstructions ?? ((paseo: unknown) => currentInstructions("manager", paseo));
+  const handover = deps.handover ?? managerHandover;
+  const location = deps.location ?? createLocationResolver(resolveLocationFromPaseo);
+
+  return async (incident, paseo, rpcDeps: FallbackRpcDeps) => {
+    const now = rpcDeps.now ?? deps.now ?? (() => new Date());
+    const home = rpcDeps.home ?? null;
+    if (home === null) throw new DashboardError("E_FALLBACK_NOT_FOUND", "paseo-bm cannot find its install home");
+    if (incident.role !== "manager") throw new DashboardError("E_FALLBACK_NO_CANDIDATE", `not a Manager incident (${incident.role})`);
+
+    // 1. Still pending, with a candidate, and the old Manager not replaced yet.
+    const incidents = readIncidents(home, log).incidents;
+    const current = incidents.find((entry) => entry.id === incident.id);
+    if (current === undefined) throw new DashboardError("E_FALLBACK_NOT_FOUND", `no fallback incident ${incident.id}`);
+    if (current.status !== "pending") throw new DashboardError("E_FALLBACK_NOT_PENDING", `incident ${current.id} is ${current.status}, not pending`);
+    const candidate = current.candidate;
+    if (candidate === null) throw new DashboardError("E_FALLBACK_NO_CANDIDATE", "the fallback chain has no entry left for this Manager");
+    let labels: Record<string, unknown>;
+    try {
+      const ref = (paseo as { agents: { ref(id: string): { refresh(): Promise<{ agent?: unknown } | null> } } }).agents.ref(current.agentId);
+      labels = asRecord(asRecord((await ref.refresh())?.agent)?.["labels"]) ?? {};
+    } catch (error) {
+      // Nothing was created: the incident stays pending, so the user can try again.
+      throw new DashboardError("E_FALLBACK_CREATE_FAILED", `could not read Manager ${current.agentId}: ${reasonOf(error)}; try again`);
+    }
+    const replacedBy = nonEmpty(labels[REPLACED_BY_LABEL]);
+    if (replacedBy !== null) throw new DashboardError("E_FALLBACK_NOT_PENDING", `Manager ${current.agentId} was already replaced by ${replacedBy}`);
+    const available = await availableProviders(paseo);
+    if (available !== null && !available.has(candidate.baseProvider)) {
+      throw new DashboardError("E_FALLBACK_NO_CANDIDATE", `${candidate.baseProvider} is not available in Paseo right now`);
+    }
+
+    // 2. The handover, within its own budget.
+    const prompt = await handover(current, { paseo, location: await location(paseo).catch(() => null), incidents });
+
+    // 3. The replacement Manager, through the same path as manager.ensure.
+    const posture = await postureFor(paseo, candidate, log);
+    let created: { agentId: string };
+    try {
+      created = await createManager(paseo as ManagerPaseo, current.workspaceId, {
+        providerSelection: `${candidate.alias}/${candidate.model}`,
+        ...(posture.modeId !== undefined ? { modeId: posture.modeId } : {}),
+        ...(candidate.thinkingOptionId !== null ? { thinkingOptionId: candidate.thinkingOptionId } : {}),
+        ...(posture.featureValues !== undefined ? { featureValues: posture.featureValues } : {}),
+        labels: { [REPLACES_LABEL]: current.agentId, ...(posture.modeId !== undefined ? { [MODE_SET_LABEL]: posture.modeId } : {}) },
+        prompt,
+        readInstructions: () => readInstructions(paseo),
+      });
+    } catch (error) {
+      const detail = `could not create the fallback Manager on ${candidate.alias}/${candidate.model}: ${reasonOf(error)}`;
+      await decidePending(home, current.id, (entry) => ({ ...entry, status: "failed", decidedAt: now().toISOString(), error: detail }), log);
+      throw new DashboardError("E_FALLBACK_CREATE_FAILED", detail);
+    }
+
+    // 4. Mark the old Manager; Beads Manager also skips it by the incident.
+    try {
+      const labelled = await setLabels(current.agentId, { [REPLACED_BY_LABEL]: created.agentId });
+      if (!labelled.ok) log(`[paseo-bm] could not label Manager ${current.agentId} as replaced by ${created.agentId}: ${labelled.reason}`);
+    } catch (error) {
+      log(`[paseo-bm] could not label Manager ${current.agentId} as replaced by ${created.agentId}: ${reasonOf(error)}`);
+    }
+
+    // 5. Every live Worker of the workspace reports to the new Manager from now on.
+    try {
+      const all = await bmAgentsOf(paseo as DashboardPaseo);
+      const peers = await peersOfWorkspace(all, current.workspaceId, async () => [], replacementsOf(incidents));
+      for (const worker of liveWorkersOf(peers)) {
+        const outcome = await enqueue(worker.id, SETTINGS_NOTICE_MARKER, managerIdNotice(created.agentId), paseo as NoticePaseo);
+        if (outcome === "dropped") log(`[paseo-bm] Worker ${worker.id} could not be told the new Manager ${created.agentId}.`);
+      }
+    } catch (error) {
+      log(`[paseo-bm] telling the Workers of ${current.workspaceId} about the new Manager failed: ${reasonOf(error)}`);
+    }
+
+    // 6. Decided.
+    return decidePending(
+      home,
+      current.id,
+      (entry) => ({ ...entry, status: "switched", decidedAt: now().toISOString(), replacementId: created.agentId }),
+      log,
+    );
+  };
+}

package/server/fallback-reviewer.ts

@@ -0,0 +1,198 @@
+/**
+ * Fallback for a stopped Reviewer (delta 20260921 §4.5.1, REQ-066 b).
+ *
+ * A Reviewer is created by its Worker, and Paseo wakes the Worker when the
+ * Reviewer ends a turn. A Reviewer the plugin created itself would never be
+ * heard by the Worker, so on **Switch** the plugin creates NO agent: it marks
+ * the incident `switched` and sends the parent Worker (through the notice
+ * queue) a `BM-FALLBACK` whose closing lines are the exact `create_agent`
+ * call to make — alias, mode, thinking, labels with `bm.replaces` — and the
+ * instruction to send the new Reviewer, unchanged, the review message the old
+ * one got.
+ *
+ * When that Reviewer appears (`agent.created`, `bm.replaces` = the old
+ * Reviewer of a `switched` incident), the incident records its id and the old
+ * Reviewer gets `bm.replacedBy`. If the notice queue was lost (a plugin reload)
+ * before the Worker got the instructions, the card offers **Resend to Worker**,
+ * which sends the same message again.
+ */
+import { aliasBases, decidePending, fallbackNotice, type FallbackAction, type FallbackRpcDeps } from "./fallback-rpc";
+import { readIncidents, updateIncidents } from "./fallback-state";
+import { FALLBACK_NOTICE_MARKER } from "./notices";
+import { enqueue as defaultEnqueue, type NoticeOutcome, type NoticePaseo } from "./notice-queue";
+import { setAgentLabels, type CliResult } from "./paseo-cli";
+import { roleOfProvider } from "./agent-role";
+import { asRecord, availableProviders, nonEmpty, reasonOf } from "./role-choices";
+import { REVIEWER_FALLBACK_MODE, REVIEWER_FALLBACK_PROVIDERS, installHomeOf } from "./role-extras";
+import { TIMED_OUT, capabilityOf, chooseModeId, featuresFor, modesFor, runPostureOf, withTimeout } from "./role-mode";
+import { DashboardError, type FallbackIncident } from "../shared/contracts";
+
+/** Label a replacement agent carries: the id of the agent it replaces. */
+const REPLACES_LABEL = "bm.replaces";
+const PARENT_AGENT_LABEL = "paseo.parent-agent-id";
+const REQUEST_ID_LABEL = "bm.requestId";
+const REPLACED_BY_LABEL = "bm.replacedBy";
+
+/**
+ * The instructions the Worker gets for a switched Reviewer (agent-facing, so
+ * English, word for word). `mode` null → the "do not pass" wording (a provider
+ * without modes); `thinking` null → the thinking clause is left out.
+ */
+export function reviewerInstructions(incident: FallbackIncident, mode: string | null, thinking: string | null): string {
+  const candidate = incident.candidate!;
+  const old = incident.agentId;
+  return [
+    `The user chose to replace Reviewer ${old}. Create the new Reviewer now with create_agent:`,
+    `provider \`${candidate.alias}/${candidate.model}\`, ${mode === null ? "do not pass settings.modeId" : `settings.modeId \`${mode}\``},`,
+    `${thinking === null ? "" : `settings.thinkingOptionId \`${thinking}\`, `}and the labels you give any Reviewer plus \`${REPLACES_LABEL}\` = \`${old}\`.`,
+    `Send it, unchanged, the message you sent ${old}. This is the same review call, not a new one.`,
+  ].join("\n");
+}
+
+/**
+ * The mode the replacement Reviewer is created in, for the candidate's alias:
+ * the posture rule for an untiered provider (§4.2.2), the hook's Reviewer rule
+ * for a tiered one (never `dangerous` / `planning`), null for a provider
+ * without modes. Modes that cannot be read: the entry's own mode, else `auto`
+ * on Claude or Codex, else null (Paseo then answers with its own list).
+ */
+export async function reviewerModeFor(
+  paseo: unknown,
+  candidate: NonNullable<FallbackIncident["candidate"]>,
+  log: (message: string) => void,
+): Promise<string | null> {
+  const modes = await modesFor(paseo, candidate.alias, log);
+  const capability = capabilityOf(modes);
+  if (capability === "none") return null;
+  if (capability === "tiered") return chooseModeId("reviewer", modes!, undefined, candidate.modeId) ?? null;
+  if (capability === "untiered") {
+    const features = await featuresFor(paseo, `${candidate.alias}/${candidate.model}`, undefined, log);
+    return runPostureOf("reviewer", capability, modes!, features, candidate.modeId)?.modeId ?? candidate.modeId;
+  }
+  return candidate.modeId ?? (REVIEWER_FALLBACK_PROVIDERS.includes(candidate.baseProvider) ? REVIEWER_FALLBACK_MODE : null);
+}
+
+export interface ReviewerFallbackDeps {
+  log?: (message: string) => void;
+  now?: () => Date;
+  enqueue?: (targetId: string, kind: string, text: string, paseo?: NoticePaseo) => Promise<NoticeOutcome>;
+  /** `setAgentLabels` of `paseo-cli.ts` by default. */
+  setLabels?: (agentId: string, labels: Record<string, string>) => Promise<CliResult>;
+  /** The install home (tests); looked up otherwise. */
+  home?: string | null;
+}
+
+/** Sends the Worker its BM-FALLBACK with the instructions; the outcome of the queue. */
+async function tellWorker(incident: FallbackIncident, paseo: unknown, deps: ReviewerFallbackDeps): Promise<NoticeOutcome> {
+  const log = deps.log ?? ((message: string) => console.warn(message));
+  const candidate = incident.candidate!;
+  const mode = await reviewerModeFor(paseo, candidate, log);
+  const bases = await aliasBases(paseo);
+  const text = fallbackNotice(incident, (alias) => bases[alias] ?? null, reviewerInstructions(incident, mode, candidate.thinkingOptionId));
+  const outcome = await (deps.enqueue ?? defaultEnqueue)(incident.parentId!, FALLBACK_NOTICE_MARKER, text, paseo as NoticePaseo);
+  if (outcome === "dropped") log(`[paseo-bm] the Worker ${incident.parentId} could not be told to replace Reviewer ${incident.agentId}; the card offers Resend to Worker.`);
+  return outcome;
+}
+
+/**
+ * The `switch` action for a Reviewer (§4.5.1): no agent is created. The
+ * incident must have a candidate whose provider is still available and a
+ * parent Worker; it becomes `switched` (no replacement yet) and the Worker is
+ * sent its instructions.
+ */
+export function createReviewerSwitch(deps: ReviewerFallbackDeps = {}): FallbackAction {
+  const log = deps.log ?? ((message: string) => console.warn(message));
+  return async (incident, paseo, rpcDeps: FallbackRpcDeps) => {
+    const now = rpcDeps.now ?? deps.now ?? (() => new Date());
+    const home = rpcDeps.home ?? null;
+    if (home === null) throw new DashboardError("E_FALLBACK_NOT_FOUND", "paseo-bm cannot find its install home");
+    if (incident.role !== "reviewer") throw new DashboardError("E_FALLBACK_NO_CANDIDATE", `not a Reviewer incident (${incident.role})`);
+    const candidate = incident.candidate;
+    if (candidate === null) throw new DashboardError("E_FALLBACK_NO_CANDIDATE", "the fallback chain has no entry left for this Reviewer");
+    if (incident.parentId === null) throw new DashboardError("E_FALLBACK_CREATE_FAILED", `the Worker of Reviewer ${incident.agentId} is not known`);
+    const available = await availableProviders(paseo);
+    if (available !== null && !available.has(candidate.baseProvider)) {
+      throw new DashboardError("E_FALLBACK_NO_CANDIDATE", `${candidate.baseProvider} is not available in Paseo right now`);
+    }
+    const switched = await decidePending(home, incident.id, (entry) => ({ ...entry, status: "switched", decidedAt: now().toISOString() }), log);
+    await tellWorker(switched, paseo, deps);
+    return switched;
+  };
+}
+
+/** The `resend` action (§7): the same instructions to the Worker again; the incident does not change. */
+export function createReviewerResend(deps: ReviewerFallbackDeps = {}): FallbackAction {
+  return async (incident, paseo) => {
+    if (incident.candidate === null || incident.parentId === null) {
+      throw new DashboardError("E_FALLBACK_CREATE_FAILED", `nothing to resend for incident ${incident.id}`);
+    }
+    const outcome = await tellWorker(incident, paseo, deps);
+    if (outcome === "dropped") throw new DashboardError("E_FALLBACK_CREATE_FAILED", `the Worker ${incident.parentId} could not be reached`);
+    return incident;
+  };
+}
+
+/**
+ * On `agent.created`: when the new agent is a Reviewer carrying `bm.replaces`
+ * = the old Reviewer of a `switched` incident without a replacement, record
+ * its id and label the old Reviewer `bm.replacedBy`. The label alone is not
+ * trusted (review b7): the new Reviewer must be in the incident's workspace,
+ * a child of the incident's Worker, and — when both carry one — of the same
+ * request; otherwise another workspace's or request's Reviewer could claim
+ * the incident and change its review count. Returns the incident it
+ * completed, or null. Never throws.
+ */
+export async function linkReplacementReviewer(
+  agentId: string,
+  provider: unknown,
+  paseo: unknown,
+  deps: ReviewerFallbackDeps = {},
+): Promise<FallbackIncident | null> {
+  const log = deps.log ?? ((message: string) => console.warn(message));
+  try {
+    if (roleOfProvider(provider) !== "reviewer") return null;
+    const ref = (paseo as { agents: { ref(id: string): { refresh(): Promise<{ agent?: unknown } | null> } } }).agents.ref(agentId);
+    const snapshot = asRecord((await ref.refresh())?.agent);
+    const labels = asRecord(snapshot?.["labels"]) ?? {};
+    const replaces = nonEmpty(labels[REPLACES_LABEL]);
+    if (replaces === null) return null;
+    const workspaceId = nonEmpty(snapshot?.["workspaceId"]);
+    const parentId = nonEmpty(labels[PARENT_AGENT_LABEL]) ?? nonEmpty(snapshot?.["parentAgentId"]);
+    const requestId = nonEmpty(labels[REQUEST_ID_LABEL]);
+    let home = deps.home;
+    if (home === undefined) {
+      const found = await withTimeout(installHomeOf(paseo));
+      home = found === TIMED_OUT ? null : found;
+    }
+    if (home === null) return null;
+    const match = (incident: FallbackIncident) =>
+      incident.role === "reviewer" &&
+      incident.status === "switched" &&
+      incident.agentId === replaces &&
+      incident.replacementId === null &&
+      // Same workspace, same Worker, and the same request when both name one.
+      workspaceId === incident.workspaceId &&
+      parentId !== null &&
+      parentId === incident.parentId &&
+      (requestId === null || incident.requestId === null || requestId === incident.requestId);
+    if (!readIncidents(home, log).incidents.some(match)) return null;
+    let linked: FallbackIncident | null = null;
+    await updateIncidents(
+      home,
+      (incidents) => {
+        const index = incidents.findIndex(match);
+        if (index === -1) return null;
+        linked = { ...incidents[index]!, replacementId: agentId };
+        return incidents.map((incident, at) => (at === index ? linked! : incident));
+      },
+      log,
+    );
+    if (linked === null) return null;
+    const labelled = await (deps.setLabels ?? ((id: string, labels: Record<string, string>) => setAgentLabels(id, labels)))(replaces, { [REPLACED_BY_LABEL]: agentId });
+    if (!labelled.ok) log(`[paseo-bm] could not label Reviewer ${replaces} as replaced by ${agentId}: ${labelled.reason}`);
+    return linked;
+  } catch (error) {
+    log(`[paseo-bm] linking the replacement Reviewer ${agentId} failed: ${reasonOf(error)}`);
+    return null;
+  }
+}