paseo-bm-plugin 0.0.0-placeholder.0

package/server/fallback-switch.ts

@@ -0,0 +1,191 @@
+/**
+ * "Switch to <candidate>" for a stopped Worker (delta 20260921 §4.4.7,
+ * REQ-065 d): the plugin creates the replacement Worker on the candidate's
+ * fallback alias, with a handover built in code.
+ *
+ * 1. One switch at a time (in-process mutex; `fallback.act` also runs every
+ *    card action one at a time, so a concurrent Wait or Dismiss cannot decide
+ *    the incident while a Switch is under way — review b6): the incident must
+ *    still be `pending` with a candidate, and the old Worker not already
+ *    replaced (`bm.replacedBy`). A second click waits, then finds it decided.
+ * 2. The candidate's base provider is still available.
+ * 3. The handover (`fallback-handover.ts`, 5 s budget).
+ * 4. `agents.create` on `bm-worker-fallback-<n>/<model>`, in the old Worker's
+ *    directory, as a child of its Manager. The `agent.create` hook still runs,
+ *    so the Worker gets its instructions and its start posture.
+ * 5. `bm.replacedBy` on the old Worker (Paseo CLI); a failure only logs — the
+ *    incident's `replacementId` excludes the old Worker too (§4.4.8).
+ * 6. The old Worker's RUNNING Reviewers get the existing stop notice.
+ * 7. `switched`, `replacementId`, `decidedAt`; the caller sends BM-FALLBACK.
+ * 8. A creation that fails records `failed` with the error and returns
+ *    `E_FALLBACK_CREATE_FAILED`: the incident never goes back to `pending`, so
+ *    a repeated click can never create two Workers. A problem found BEFORE the
+ *    creation (the old Worker cannot be read) creates nothing and leaves the
+ *    incident pending.
+ */
+import { createLocationResolver, resolveLocationFromPaseo } from "./collector";
+import { decidePending, type FallbackAction, type FallbackRpcDeps } from "./fallback-rpc";
+import { REPLACED_BY_LABEL } from "./fallback-detect";
+import { workerHandover } from "./fallback-handover";
+import { readIncidents } from "./fallback-state";
+import { setAgentLabels, type CliResult } from "./paseo-cli";
+import { asRecord, availableProviders, nonEmpty, reasonOf } from "./role-choices";
+import { installHomeOf } from "./role-extras";
+import { TIMED_OUT, capabilityOf, chooseModeId, featuresFor, modesFor, runPostureOf, withTimeout } from "./role-mode";
+import { stopRunningReviewers, type StopPaseo } from "./stop-propagation";
+import type { TraceStoreLocation } from "./trace-store";
+import { DashboardError, type FallbackIncident } from "../shared/contracts";
+import { PLUGIN_VERSION } from "../shared/version";
+
+/** Title of every replacement Worker. */
+export const FALLBACK_WORKER_TITLE = "Beads Worker (fallback)";
+
+/** Label a replacement agent carries: the id of the agent it replaces. */
+export const REPLACES_LABEL = "bm.replaces";
+
+/** The SDK slice a switch uses; `PaseoApi` is structurally assignable. */
+export interface SwitchPaseo {
+  agents: {
+    create(options: {
+      config: Record<string, unknown>;
+      cwd: string;
+      parent?: string;
+      title: string;
+      labels: Record<string, string>;
+      prompt: string;
+    }): Promise<{ id: string }>;
+    ref(agentId: string): { refresh(): Promise<{ agent?: unknown } | null> };
+  };
+}
+
+export interface SwitchDeps {
+  log?: (message: string) => void;
+  now?: () => Date;
+  /** `setAgentLabels` of `paseo-cli.ts` by default. */
+  setLabels?: (agentId: string, labels: Record<string, string>) => Promise<CliResult>;
+  /** `stopRunningReviewers` of `stop-propagation.ts` by default. */
+  stopReviewers?: (paseo: unknown, workerId: string, workspaceId: string | null) => Promise<unknown>;
+  /** `workerHandover` by default. */
+  handover?: (incident: FallbackIncident, deps: { paseo: unknown; location: TraceStoreLocation | null }) => Promise<string>;
+  /** The workspace trace store; the collector's resolver by default. */
+  location?: (paseo: unknown) => Promise<TraceStoreLocation | null>;
+}
+
+let queue: Promise<unknown> = Promise.resolve();
+
+/** Runs `work` after every switch queued before it; a failure does not block the next one. */
+function serialised<T>(work: () => Promise<T>): Promise<T> {
+  const run = queue.then(work, work);
+  queue = run.catch(() => undefined);
+  return run;
+}
+
+/** The `switch` action of `fallback.act`, for the Worker. */
+export function createWorkerSwitch(deps: SwitchDeps = {}): FallbackAction {
+  const log = deps.log ?? ((message: string) => console.warn(message));
+  const setLabels = deps.setLabels ?? ((agentId: string, labels: Record<string, string>) => setAgentLabels(agentId, labels));
+  const stopReviewers =
+    deps.stopReviewers ?? ((paseo: unknown, workerId: string, workspaceId: string | null) => stopRunningReviewers(paseo as StopPaseo, workerId, workspaceId));
+  const handover = deps.handover ?? workerHandover;
+  const location = deps.location ?? createLocationResolver(resolveLocationFromPaseo);
+
+  return (incident, paseo, rpcDeps: FallbackRpcDeps) =>
+    serialised(async () => {
+      const now = rpcDeps.now ?? deps.now ?? (() => new Date());
+      const found = await withTimeout(rpcDeps.home !== undefined ? Promise.resolve(rpcDeps.home) : installHomeOf(paseo));
+      const home = found === TIMED_OUT ? null : found;
+      if (home === null) throw new DashboardError("E_FALLBACK_NOT_FOUND", "paseo-bm cannot find its install home");
+      if (incident.role !== "worker") throw new DashboardError("E_FALLBACK_NO_CANDIDATE", `switching a ${incident.role} arrives in a later release`);
+
+      // 1. Still pending (a second click finds it decided) and not replaced yet.
+      const current = readIncidents(home, log).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 Worker");
+      const api = paseo as SwitchPaseo;
+      let snapshot: Record<string, unknown> | null;
+      try {
+        snapshot = asRecord((await api.agents.ref(current.agentId).refresh())?.agent);
+      } 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 Worker ${current.agentId}: ${reasonOf(error)}; try again`);
+      }
+      const labels = asRecord(snapshot?.["labels"]) ?? {};
+      const replacedBy = nonEmpty(labels[REPLACED_BY_LABEL]);
+      if (replacedBy !== null) throw new DashboardError("E_FALLBACK_NOT_PENDING", `Worker ${current.agentId} was already replaced by ${replacedBy}`);
+
+      // 2. The candidate's provider is still there (when Paseo can say).
+      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 fail = async (detail: string): Promise<never> => {
+        await decidePending(home, current.id, (entry) => ({ ...entry, status: "failed", decidedAt: now().toISOString(), error: detail }), log);
+        throw new DashboardError("E_FALLBACK_CREATE_FAILED", detail);
+      };
+      const cwd = nonEmpty(snapshot?.["cwd"]);
+      if (cwd === null) throw new DashboardError("E_FALLBACK_CREATE_FAILED", `the directory of Worker ${current.agentId} cannot be read`);
+
+      // 3. The handover, within its own budget.
+      const prompt = await handover(current, { paseo, location: await location(paseo).catch(() => null) });
+
+      // 4. The replacement Worker; the agent.create hook adds its instructions.
+      const alias = candidate.alias;
+      const modes = await modesFor(paseo, alias, log, cwd);
+      const capability = capabilityOf(modes);
+      const features = capability === "untiered" ? await featuresFor(paseo, `${alias}/${candidate.model}`, cwd, log) : null;
+      const posture = runPostureOf("worker", capability, modes ?? [], features, candidate.modeId);
+      // Tiered (Claude, Codex): the Worker rule the hook applies, passed explicitly.
+      const modeId =
+        candidate.modeId ?? (capability === "tiered" && modes !== null ? chooseModeId("worker", modes, undefined, null) : (posture?.modeId ?? undefined));
+      const featureValues = posture?.featureValues ?? undefined;
+      let created: { id: string };
+      try {
+        created = await api.agents.create({
+          config: {
+            provider: `${alias}/${candidate.model}`,
+            ...(candidate.thinkingOptionId !== null ? { thinkingOptionId: candidate.thinkingOptionId } : {}),
+            ...(modeId !== undefined && capability !== "none" ? { modeId } : {}),
+            ...(featureValues !== undefined ? { featureValues } : {}),
+          },
+          cwd,
+          ...(current.managerId !== null ? { parent: current.managerId } : {}),
+          title: FALLBACK_WORKER_TITLE,
+          labels: {
+            "bm.role": "worker",
+            ...(current.requestId !== null ? { "bm.requestId": current.requestId } : {}),
+            "bm.version": PLUGIN_VERSION,
+            [REPLACES_LABEL]: current.agentId,
+          },
+          prompt,
+        });
+      } catch (error) {
+        return fail(`could not create the fallback Worker on ${alias}/${candidate.model}: ${reasonOf(error)}`);
+      }
+
+      // 5. Mark the old Worker; the incident's replacementId excludes it even if this fails.
+      try {
+        const labelled = await setLabels(current.agentId, { [REPLACED_BY_LABEL]: created.id });
+        if (!labelled.ok) log(`[paseo-bm] could not label Worker ${current.agentId} as replaced by ${created.id}: ${labelled.reason}`);
+      } catch (error) {
+        log(`[paseo-bm] could not label Worker ${current.agentId} as replaced by ${created.id}: ${reasonOf(error)}`);
+      }
+
+      // 6. The old Worker's running Reviewers stop.
+      try {
+        await stopReviewers(paseo, current.agentId, current.workspaceId);
+      } catch (error) {
+        log(`[paseo-bm] could not stop the Reviewers of Worker ${current.agentId}: ${reasonOf(error)}`);
+      }
+
+      // 7. Decided.
+      return decidePending(
+        home,
+        current.id,
+        (entry) => ({ ...entry, status: "switched", decidedAt: now().toISOString(), replacementId: created.id }),
+        log,
+      );
+    });
+}

package/server/fallback-wait.ts

@@ -0,0 +1,188 @@
+/**
+ * "Wait until the reset" (delta 20260921 §4.4.9, REQ-065 e): one timer per
+ * Wait click, for any role (phase 2a-16 offers the Worker's only).
+ *
+ * The owner accepted it as a narrow exception to the root design's "no
+ * background task" rule (Q6 a): each wait has exactly one timer, set by the
+ * user's click; it is written to the incidents file (`waiting`, `waitUntil`)
+ * and set again after a plugin reload; a status change of the incident ends
+ * it; nothing scans the disk or repeats.
+ *
+ * Paseo hands a plugin no SDK handle when it loads (no start-up event, and
+ * `PluginServerContext` carries no `paseo`), so the timers of `waiting`
+ * incidents are set again at the first hook or fallback RPC that brings one —
+ * the same once-per-run pattern as the label scan of delta 20260918g. A timer
+ * already past due fires at once.
+ *
+ * When it fires: the stopped agent archived, gone, running or already replaced
+ * (`bm.replacedBy`) → `expired`. Otherwise it is sent `RESUME_NOTICE`, the
+ * incident becomes `resumed`, and its Manager chat gets a `BM-FALLBACK` with
+ * `status: resumed`. Never throws into a timer: failures cost one log line.
+ */
+import { decidePending, notifyFallback, type FallbackAction, type FallbackRpcDeps } from "./fallback-rpc";
+import { readIncidents, updateIncidents } from "./fallback-state";
+import { REPLACED_BY_LABEL } from "./fallback-detect";
+import { asRecord, reasonOf } from "./role-choices";
+import { installHomeOf } from "./role-extras";
+import { TIMED_OUT, withTimeout } from "./role-mode";
+import { DashboardError, FALLBACK_MAX_WAIT_MS, type FallbackIncident } from "../shared/contracts";
+
+/** What the stopped agent is sent when its usage reset (agent-facing, so English). */
+export const RESUME_NOTICE = "BM-RESUME The usage limit that stopped you has reset. Continue from where you stopped; do not redo finished work.";
+
+/** The agent is resumed this long after `resetsAt`. */
+export const WAIT_GRACE_MS = 60_000;
+
+/** A reset further ahead than this is not waited for; the card offers Wait by the same limit. */
+export const MAX_WAIT_MS = FALLBACK_MAX_WAIT_MS;
+
+type Timer = ReturnType<typeof setTimeout>;
+
+export interface WaiterDeps {
+  now?: () => Date;
+  log?: (message: string) => void;
+  setTimer?: (fire: () => void, ms: number) => Timer;
+  clearTimer?: (timer: Timer) => void;
+  /** The Manager chat notice; `notifyFallback` by default. */
+  notify?: (incident: FallbackIncident, paseo: unknown) => Promise<unknown>;
+  /** The install home when the caller knows it (tests); looked up otherwise. */
+  home?: string | null;
+}
+
+/** The part of the SDK a resume uses; `PaseoApi` is structurally assignable. */
+interface ResumePaseo {
+  agents: { ref(agentId: string): { refresh(): Promise<{ agent?: unknown } | null>; send(text: string): Promise<void> } };
+}
+
+export interface FallbackWaiter {
+  /** The `wait` action of `fallback.act`. */
+  wait: FallbackAction;
+  /** Sets the timers of every `waiting` incident, once per plugin run. Never throws. */
+  ensureArmed(paseo: unknown): Promise<void>;
+  /** Ends the timer of one incident (its status changed). */
+  cancel(incidentId: string): void;
+  /** Ends every timer (plugin cleanup). */
+  clear(): void;
+}
+
+export function createFallbackWaiter(deps: WaiterDeps = {}): FallbackWaiter {
+  const log = deps.log ?? ((message: string) => console.warn(message));
+  const now = deps.now ?? (() => new Date());
+  const setTimer =
+    deps.setTimer ??
+    ((fire: () => void, ms: number) => {
+      const timer = setTimeout(fire, ms);
+      timer.unref?.();
+      return timer;
+    });
+  const clearTimer = deps.clearTimer ?? ((timer: Timer) => clearTimeout(timer));
+  const notify = deps.notify ?? ((incident: FallbackIncident, paseo: unknown) => notifyFallback(incident, paseo));
+  const timers = new Map<string, Timer>();
+  let armed = false;
+
+  const homeOf = async (paseo: unknown, known?: string | null): Promise<string | null> => {
+    if (known !== undefined) return known;
+    if (deps.home !== undefined) return deps.home;
+    const found = await withTimeout(installHomeOf(paseo));
+    return found === TIMED_OUT ? null : found;
+  };
+
+  const cancel = (incidentId: string): void => {
+    const timer = timers.get(incidentId);
+    if (timer !== undefined) clearTimer(timer);
+    timers.delete(incidentId);
+  };
+
+  /** Moves a `waiting` incident to `resumed` or `expired`; null when it is no longer waiting. */
+  const finish = async (home: string, incidentId: string, status: "resumed" | "expired"): Promise<FallbackIncident | null> => {
+    let finished: FallbackIncident | null = null;
+    await updateIncidents(
+      home,
+      (incidents) => {
+        const index = incidents.findIndex((incident) => incident.id === incidentId && incident.status === "waiting");
+        if (index === -1) return null;
+        finished = { ...incidents[index]!, status };
+        return incidents.map((incident, at) => (at === index ? finished! : incident));
+      },
+      log,
+    );
+    return finished;
+  };
+
+  const fire = async (incidentId: string, paseo: unknown, home: string): Promise<void> => {
+    timers.delete(incidentId);
+    try {
+      const current = readIncidents(home, log).incidents.find((incident) => incident.id === incidentId);
+      // Any other status means the wait was ended by a later decision.
+      if (current === undefined || current.status !== "waiting") return;
+      const ref = (paseo as ResumePaseo).agents.ref(current.agentId);
+      const snapshot = asRecord((await ref.refresh())?.agent);
+      const status = snapshot?.["status"];
+      const labels = asRecord(snapshot?.["labels"]) ?? {};
+      const gone = snapshot === null || snapshot["archivedAt"] != null || status === "closed";
+      const busy = status === "running" || status === "initializing";
+      if (gone || busy || Object.prototype.hasOwnProperty.call(labels, REPLACED_BY_LABEL)) {
+        await finish(home, incidentId, "expired");
+        return;
+      }
+      await ref.send(RESUME_NOTICE);
+      const resumed = await finish(home, incidentId, "resumed");
+      if (resumed !== null) await notify(resumed, paseo);
+    } catch (error) {
+      log(`[paseo-bm] resuming the agent of fallback incident ${incidentId} failed: ${reasonOf(error)}`);
+    }
+  };
+
+  const arm = (incident: FallbackIncident, paseo: unknown, home: string): void => {
+    cancel(incident.id);
+    const due = incident.waitUntil === null ? Number.NaN : Date.parse(incident.waitUntil);
+    const delay = Number.isNaN(due) ? 0 : Math.max(0, due - now().getTime());
+    timers.set(
+      incident.id,
+      setTimer(() => void fire(incident.id, paseo, home), delay),
+    );
+  };
+
+  const wait: FallbackAction = async (incident, paseo, rpcDeps: FallbackRpcDeps) => {
+    const home = await homeOf(paseo, rpcDeps.home);
+    if (home === null) throw new DashboardError("E_FALLBACK_NOT_FOUND", "paseo-bm cannot find its install home");
+    const resetsAt = incident.resetsAt === null ? Number.NaN : Date.parse(incident.resetsAt);
+    const at = (rpcDeps.now ?? now)();
+    if (Number.isNaN(resetsAt)) throw new DashboardError("E_FALLBACK_NO_RESET", "the reset time of this limit is not known");
+    if (resetsAt - at.getTime() > MAX_WAIT_MS) throw new DashboardError("E_FALLBACK_NO_RESET", "the limit resets more than 7 days from now");
+    const waiting = await decidePending(
+      home,
+      incident.id,
+      (current) => ({ ...current, status: "waiting", decidedAt: at.toISOString(), waitUntil: new Date(resetsAt + WAIT_GRACE_MS).toISOString() }),
+      log,
+    );
+    arm(waiting, paseo, home);
+    return waiting;
+  };
+
+  return {
+    wait,
+    cancel,
+    async ensureArmed(paseo: unknown): Promise<void> {
+      if (armed) return;
+      armed = true;
+      try {
+        const home = await homeOf(paseo);
+        if (home === null) {
+          armed = false;
+          return;
+        }
+        for (const incident of readIncidents(home, log).incidents) {
+          if (incident.status === "waiting" && !timers.has(incident.id)) arm(incident, paseo, home);
+        }
+      } catch (error) {
+        armed = false;
+        log(`[paseo-bm] setting the fallback wait timers failed: ${reasonOf(error)}`);
+      }
+    },
+    clear(): void {
+      for (const timer of timers.values()) clearTimer(timer);
+      timers.clear();
+    },
+  };
+}