paseo-bm-plugin 0.0.0-placeholder.0

package/server/model-costs.ts

@@ -0,0 +1,238 @@
+/**
+ * Model rates from Paseo's own model list (delta 20260921 §4.2.7, F2, REQ-063 g).
+ *
+ * The bundled table in `shared/prices.ts` only knows Claude models. Paseo lists
+ * every model of a provider with `providers.listModels(provider)`, and a model
+ * there may carry `metadata.cost = { input, output, cache: { read, write },
+ * tiers?, experimentalOver200K? }` in US dollars per million tokens (every
+ * OpenCode model does). `costOf` turns that into a `ModelPrice`:
+ *
+ * - `input` → `inputUsdPerMTok`, `output` → `outputUsdPerMTok`;
+ * - `cache.read` → `cacheReadUsdPerMTok`, or the input rate when the model
+ *   lists no cache-read rate (never a guessed discount);
+ * - `cache.write`, `tiers` and `experimentalOver200K` are ignored: the
+ *   Dashboard's usage has no cache-write count, and a tier is a surcharge above
+ *   a context size the usage does not record.
+ *
+ * Model ids are matched whole: an OpenCode id contains `/`
+ * (`anthropic/claude-sonnet-4-6`), so the part after a slash is never enough.
+ *
+ * Each provider's list is asked for ONCE per plugin run and remembered,
+ * whatever the answer, so a failure costs one `console.warn` line and not one
+ * per Dashboard refresh. Every wait is raced against `LOOKUP_TIMEOUT_MS`; a
+ * slow call keeps running, and a later lookup uses its answer once it lands.
+ * Nothing here throws.
+ *
+ * The Dashboard prices synchronously (`priceUsage`), so its handlers resolve
+ * the listed rates of the models their records name first
+ * (`listedPricesFor`) and hand the result in as a plain map.
+ */
+import { priceFor, type ListedPrices } from "./cost";
+import { providerId } from "./provider-id";
+import { LOOKUP_TIMEOUT_MS, TIMED_OUT, withTimeout } from "./role-mode";
+import { effectiveModel } from "./traces";
+import { modelPriceSchema, type ModelPrice } from "../shared/prices";
+import type { TraceRecord } from "../shared/contracts";
+
+/** What one provider's model list gave: rates by model id, or why there are none. */
+type ModelList = { prices: Map<string, ModelPrice>; readAt: string } | { failure: string };
+
+interface ListEntry {
+  answer: Promise<ModelList>;
+  warned: boolean;
+}
+
+/** One entry per provider id for the life of the plugin. */
+const lists = new Map<string, ListEntry>();
+
+/** Forgets every remembered list; for tests. */
+export function forgetModelCosts(): void {
+  lists.clear();
+}
+
+const isRate = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
+
+/**
+ * A `ModelPrice` from one model's `metadata.cost`, or null when the input or
+ * output rate is missing or not a usable number.
+ */
+export function priceOfCost(cost: unknown): ModelPrice | null {
+  if (cost === null || typeof cost !== "object") return null;
+  const { input, output, cache } = cost as { input?: unknown; output?: unknown; cache?: unknown };
+  if (!isRate(input) || !isRate(output)) return null;
+  const read = cache !== null && typeof cache === "object" ? (cache as { read?: unknown }).read : undefined;
+  const parsed = modelPriceSchema.safeParse({
+    inputUsdPerMTok: input,
+    cacheReadUsdPerMTok: isRate(read) ? read : input,
+    outputUsdPerMTok: output,
+  });
+  return parsed.success ? parsed.data : null;
+}
+
+/** Rates by model id (and alias, when no id claims it) from a `listModels` answer. */
+function parseModelList(answer: unknown): ModelList {
+  const result = answer as { models?: unknown; error?: unknown; fetchedAt?: unknown } | null | undefined;
+  if (typeof result?.error === "string" && result.error !== "") return { failure: result.error };
+  if (!Array.isArray(result?.models)) return { failure: "no models listed" };
+  const prices = new Map<string, ModelPrice>();
+  const aliases: Array<[string, ModelPrice]> = [];
+  for (const model of result.models as unknown[]) {
+    if (model === null || typeof model !== "object") continue;
+    const { id, aliases: names, metadata } = model as { id?: unknown; aliases?: unknown; metadata?: unknown };
+    if (typeof id !== "string" || id === "") continue;
+    const price = priceOfCost(metadata !== null && typeof metadata === "object" ? (metadata as { cost?: unknown }).cost : undefined);
+    if (price === null) continue;
+    if (!prices.has(id)) prices.set(id, price);
+    if (Array.isArray(names)) {
+      for (const name of names) if (typeof name === "string" && name !== "") aliases.push([name, price]);
+    }
+  }
+  for (const [name, price] of aliases) if (!prices.has(name)) prices.set(name, price);
+  const fetchedAt = typeof result?.fetchedAt === "string" && result.fetchedAt !== "" ? result.fetchedAt : null;
+  return { prices, readAt: fetchedAt ?? new Date().toISOString() };
+}
+
+/** Asks for one provider's list. Never rejects: a failure is a value. */
+async function readModelList(paseo: unknown, provider: string, cwd: string | undefined): Promise<ModelList> {
+  const providers = (paseo as { providers?: { listModels?: unknown } } | null | undefined)?.providers;
+  const listModels = providers?.listModels;
+  if (typeof listModels !== "function") return { failure: "this Paseo host cannot list models" };
+  try {
+    return parseModelList(
+      await (cwd === undefined ? listModels.call(providers, provider) : listModels.call(providers, provider, { cwd })),
+    );
+  } catch (error) {
+    return { failure: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function warnOnce(entry: ListEntry, log: (message: string) => void, message: string): void {
+  if (entry.warned) return;
+  entry.warned = true;
+  log(message);
+}
+
+/**
+ * The listed rate of `model` on `provider` and when the list was read, or
+ * null. `provider` may be a bare id (`bm-worker`) or a selection
+ * (`bm-worker/<model>`); a bm-* alias is passed as is, since Paseo resolves it
+ * the way it does for `listModes`.
+ */
+async function listedCostOf(
+  paseo: unknown,
+  provider: string,
+  model: string,
+  log: (message: string) => void,
+  cwd: string | undefined,
+): Promise<{ price: ModelPrice; readAt: string } | null> {
+  try {
+    const id = providerId(provider);
+    if (id === null || id === "" || model === "") return null;
+    let entry = lists.get(id);
+    if (entry === undefined) {
+      entry = { answer: readModelList(paseo, id, cwd), warned: false };
+      lists.set(id, entry);
+    }
+    const list = await withTimeout(entry.answer);
+    if (list === TIMED_OUT) {
+      warnOnce(
+        entry,
+        log,
+        `[paseo-bm] reading the models of ${id} took longer than ${LOOKUP_TIMEOUT_MS} ms; models missing from the bundled price table show tokens only.`,
+      );
+      return null;
+    }
+    if ("failure" in list) {
+      warnOnce(
+        entry,
+        log,
+        `[paseo-bm] could not read the models of ${id} (${list.failure}); models missing from the bundled price table show tokens only.`,
+      );
+      return null;
+    }
+    const price =
+      list.prices.get(model) ?? (model.startsWith(`${id}/`) ? list.prices.get(model.slice(id.length + 1)) : undefined);
+    return price === undefined ? null : { price, readAt: list.readAt };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The rate Paseo lists for `model` on `provider`, or null when it lists none
+ * or the list cannot be read in time. Does not consult the bundled table: the
+ * order "table first" is the caller's (`priceUsage`, `listedPricesFor`).
+ */
+export async function costOf(
+  paseo: unknown,
+  provider: string,
+  model: string,
+  log: (message: string) => void = (message) => console.warn(message),
+  cwd?: string,
+): Promise<ModelPrice | null> {
+  return (await listedCostOf(paseo, provider, model, log, cwd))?.price ?? null;
+}
+
+const lastSegment = (model: string): string => model.slice(model.lastIndexOf("/") + 1);
+
+const samePrice = (a: ModelPrice, b: ModelPrice): boolean =>
+  a.inputUsdPerMTok === b.inputUsdPerMTok &&
+  a.cacheReadUsdPerMTok === b.cacheReadUsdPerMTok &&
+  a.outputUsdPerMTok === b.outputUsdPerMTok;
+
+/**
+ * Listed rates for the models `records` ran on, ready for `priceUsage`.
+ *
+ * Only records that name `runtime.provider` and a model the bundled table
+ * lacks are looked up; a record written before `runtime.provider` existed is
+ * priced from the table alone. Lookups for distinct providers run together.
+ *
+ * Keys: the model id as recorded and its last `/` segment, because the trace
+ * roll-up groups models by that segment and hands either form to the pricer.
+ * When two recorded ids share a segment but their listed rates differ, none of
+ * them gets a listed rate: a group mixing both could only be priced wrongly.
+ * Never throws; a failure leaves the map without that model.
+ */
+export async function listedPricesFor(
+  paseo: unknown,
+  records: readonly TraceRecord[],
+  log: (message: string) => void = (message) => console.warn(message),
+  cwd?: string,
+): Promise<ListedPrices> {
+  const out = new Map<string, { price: ModelPrice; updatedAt: string }>();
+  try {
+    const wanted = new Map<string, { provider: string; model: string }>();
+    for (const record of records) {
+      const provider = record.runtime?.provider;
+      const model = effectiveModel(record);
+      if (typeof provider !== "string" || provider === "" || model === null || model === "") continue;
+      if (priceFor(model) !== null) continue;
+      wanted.set(JSON.stringify([provider, model]), { provider, model });
+    }
+    if (wanted.size === 0) return out;
+
+    const found = await Promise.all(
+      [...wanted.values()].map(async ({ provider, model }) => ({
+        model,
+        listed: await listedCostOf(paseo, provider, model, log, cwd),
+      })),
+    );
+    const bySegment = new Map<string, Array<{ model: string; price: ModelPrice; updatedAt: string }>>();
+    for (const { model, listed } of found) {
+      if (listed === null) continue;
+      const segment = lastSegment(model);
+      const group = bySegment.get(segment) ?? [];
+      group.push({ model, price: listed.price, updatedAt: listed.readAt.slice(0, 10) });
+      bySegment.set(segment, group);
+    }
+    for (const [segment, group] of bySegment) {
+      const [first] = group;
+      if (first === undefined || !group.every((entry) => samePrice(entry.price, first.price))) continue;
+      out.set(segment, { price: first.price, updatedAt: first.updatedAt });
+      for (const entry of group) out.set(entry.model, { price: entry.price, updatedAt: entry.updatedAt });
+    }
+  } catch {
+    // A pricing extra: without it the Dashboard shows tokens only, as before.
+  }
+  return out;
+}

package/server/notice-queue.ts

@@ -0,0 +1,315 @@
+/**
+ * The notice queue: the one way the plugin delivers a notice to an agent that
+ * may be running (delta 20260921 §4.2.4, §4.3.5, §4.4.6, F13; REQ-063 d,
+ * REQ-064 d, REQ-065 c).
+ *
+ * `PaseoAgentHandle.send()` on a running agent REPLACES its turn (delta
+ * 20260918g K10; `stop-propagation.ts` relies on exactly that to interrupt a
+ * Reviewer). `BM-TOOLS`, `BM-SETTINGS` and `BM-FALLBACK` go to Managers and
+ * Workers that are often mid-turn, so none of them calls `send()` itself.
+ *
+ * API — what consumer modules import:
+ *
+ * - `enqueue(targetId, kind, text, paseo?)` → `Promise<NoticeOutcome>`, never
+ *   rejects. `refresh()`es the target (as `review-budget.ts` does before its
+ *   send); when it is not `running` or `initializing` the notice is sent now
+ *   (`"sent"`), otherwise `{ kind, text }` is held in memory (`"queued"`) and
+ *   sent at a later `agent.turn_ended` of that target. `kind` is the notice's
+ *   marker (`"BM-TOOLS"`, `"BM-SETTINGS"`, `"BM-FALLBACK"`). `paseo` is the
+ *   handle of the caller's own hook or RPC context (`context.paseo`, the
+ *   `{ paseo }` of a handler); without it the queue uses the last handle a
+ *   hook gave it, and with none yet the notice waits for the target's turn end,
+ *   whose hook context brings one. `"dropped"`: bad input, the target is
+ *   archived, closed or gone, or its send failed. `"replaced"`: a newer notice
+ *   of the same kind for the same target took its place before it went out.
+ * - `noticeQueue`: the one shared queue `enqueue` uses. `createNoticeQueue()`
+ *   makes a private one (tests).
+ * - `registerNoticeQueue(host)` → `{ host, remove }`: the queue does not add a
+ *   lifecycle hook of its own. It rides on an existing `agent.turn_ended` hook:
+ *   pass the returned `host` to the module that registers one (index.server.ts
+ *   uses the BM-FORMAT check), and every turn end that hook sees then also
+ *   delivers the queue, AFTER that module's handler. So a BM-FORMAT notice sent
+ *   at the same turn end is already running when the queue `refresh()`es, and
+ *   the queue waits instead of replacing it. `remove()` detaches the queue and
+ *   forgets what it holds.
+ *
+ * Rules this module must never lose:
+ * - **Never into a running turn.** Nothing is sent unless `refresh()`, read
+ *   just before, says the target is neither `running` nor `initializing`.
+ * - **One notice per idle moment.** The notice sent starts a turn on the
+ *   target, and a second `send()` would replace that turn; so each chance
+ *   sends the oldest queued notice only, and that turn's end carries the next
+ *   (the lesson `review-budget.ts` records). Queued notices therefore go out
+ *   in order, one turn apart. A send that fails costs one log line and drops
+ *   that notice; the next queued one is tried at once, after a fresh
+ *   `refresh()`.
+ * - **The newest notice of a kind wins.** A new notice replaces a queued one of
+ *   the SAME kind for the SAME target and moves to the back of that target's
+ *   queue; other kinds and other targets are kept.
+ * - **Lifecycle belongs to the user (ADR-005).** `send()` un-archives an
+ *   archived agent and starts a turn on it, so an archived, closed or unknown
+ *   target is never sent to: its queued notices are dropped with one log line.
+ * - **Keyed by agent id and kind, never by turn id.** Paseo reuses turn ids
+ *   inside one agent (AGENTS.md).
+ * - **In memory only.** A plugin reload loses the queue; each consumer
+ *   documents its own fallback.
+ * - **Never throws.** Every failure costs one `console.warn` line that starts
+ *   with `[paseo-bm]`.
+ */
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+
+/** A notice's marker, for example `"BM-TOOLS"`; one queued notice per kind and target. */
+export type NoticeKind = string;
+
+export type NoticeOutcome = "sent" | "queued" | "replaced" | "dropped";
+
+/** The snapshot fields this module reads; `PaseoAgent` is structurally assignable. */
+export interface NoticeAgentSnapshot {
+  status?: string | null;
+  archivedAt?: string | null;
+}
+
+/** The SDK slice this module uses; `PaseoApi` from a hook or handler context is structurally assignable. */
+export interface NoticePaseo {
+  agents: {
+    ref(agentId: string): {
+      refresh(): Promise<{ agent?: NoticeAgentSnapshot | null } | null>;
+      send(text: string): Promise<void>;
+    };
+  };
+}
+
+/** A queued notice, as `pending()` shows it. */
+export interface QueuedNotice {
+  kind: NoticeKind;
+  text: string;
+}
+
+export interface NoticeQueue {
+  /** Sends now when the target is idle, otherwise holds the notice for its next turn end. Never rejects. */
+  enqueue(targetId: string, kind: NoticeKind, text: string, paseo?: NoticePaseo): Promise<NoticeOutcome>;
+  /** One `agent.turn_ended`: delivers the ended agent's queued notices when it is idle. Never rejects. */
+  turnEnded(event: unknown, paseo?: unknown): Promise<void>;
+  /** What is queued for `targetId`, oldest first (a copy). */
+  pending(targetId: string): QueuedNotice[];
+  /** Forgets every queued notice and the remembered Paseo handle. */
+  clear(): void;
+}
+
+export interface NoticeQueueDeps {
+  /** Where failures are reported. Defaults to `console.warn`. */
+  log?: (message: string) => void;
+}
+
+interface Entry extends QueuedNotice {
+  state: "queued" | "sending" | NoticeOutcome;
+}
+
+type DeliveryStep = "empty" | "unknown" | "gone" | "busy" | "sent" | "failed";
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function nonEmpty(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+function isPaseo(value: unknown): value is NoticePaseo {
+  if (value === null || typeof value !== "object") return false;
+  const agents = (value as { agents?: unknown }).agents;
+  return agents !== null && typeof agents === "object" && typeof (agents as { ref?: unknown }).ref === "function";
+}
+
+function agentIdOf(event: unknown): string | null {
+  if (event === null || typeof event !== "object") return null;
+  const agent = (event as { agent?: unknown }).agent;
+  if (agent === null || typeof agent !== "object") return null;
+  const id = (agent as { id?: unknown }).id;
+  return nonEmpty(id) ? id : null;
+}
+
+function isBusy(status: string | null | undefined): boolean {
+  return status === "running" || status === "initializing";
+}
+
+export function createNoticeQueue(deps: NoticeQueueDeps = {}): NoticeQueue {
+  const log = deps.log ?? ((message: string) => console.warn(message));
+  /** Target agent id → its queued notices, oldest first. */
+  const queued = new Map<string, Entry[]>();
+  /** Targets being delivered to right now; `again` asks that delivery for one more look. */
+  const delivering = new Map<string, { again: boolean }>();
+  let lastPaseo: NoticePaseo | null = null;
+
+  function handleFor(paseo: unknown): NoticePaseo | null {
+    if (isPaseo(paseo)) lastPaseo = paseo;
+    return lastPaseo;
+  }
+
+  function put(targetId: string, entry: Entry): void {
+    const kept: Entry[] = [];
+    for (const old of queued.get(targetId) ?? []) {
+      if (old.kind === entry.kind) old.state = "replaced";
+      else kept.push(old);
+    }
+    kept.push(entry);
+    queued.set(targetId, kept);
+  }
+
+  function take(targetId: string): Entry | undefined {
+    const list = queued.get(targetId);
+    const first = list?.shift();
+    if (list !== undefined && list.length === 0) queued.delete(targetId);
+    return first;
+  }
+
+  function dropAll(targetId: string): void {
+    const list = queued.get(targetId) ?? [];
+    queued.delete(targetId);
+    if (list.length === 0) return;
+    for (const entry of list) entry.state = "dropped";
+    log(
+      `[paseo-bm] ${targetId} is archived, closed or gone; dropped its queued notices (${list.map((entry) => entry.kind).join(", ")}).`,
+    );
+  }
+
+  /** One look at the target: sends its oldest notice when it is idle. */
+  async function step(targetId: string, paseo: NoticePaseo): Promise<DeliveryStep> {
+    const head = queued.get(targetId)?.[0];
+    if (head === undefined) return "empty";
+    let agent: NoticeAgentSnapshot | null;
+    try {
+      agent = (await paseo.agents.ref(targetId).refresh())?.agent ?? null;
+    } catch (error) {
+      log(`[paseo-bm] could not read ${targetId} to deliver its ${head.kind} notice: ${describeError(error)}; it waits for that agent's next turn end.`);
+      return "unknown";
+    }
+    if (agent === null || agent.archivedAt != null || agent.status === "closed") {
+      dropAll(targetId);
+      return "gone";
+    }
+    if (isBusy(agent.status)) return "busy";
+    const entry = take(targetId);
+    if (entry === undefined) return "empty";
+    // Taken off the queue BEFORE the await: a turn end handled meanwhile never sends it twice.
+    entry.state = "sending";
+    try {
+      await paseo.agents.ref(targetId).send(entry.text);
+      entry.state = "sent";
+      return "sent";
+    } catch (error) {
+      entry.state = "dropped";
+      log(`[paseo-bm] could not send the ${entry.kind} notice to ${targetId}: ${describeError(error)}; dropped it.`);
+      return "failed";
+    }
+  }
+
+  async function deliver(targetId: string, paseo: NoticePaseo): Promise<void> {
+    const current = delivering.get(targetId);
+    if (current !== undefined) {
+      // Another delivery is reading this target: it takes one more look when it is done.
+      current.again = true;
+      return;
+    }
+    const flag = { again: false };
+    delivering.set(targetId, flag);
+    try {
+      for (;;) {
+        flag.again = false;
+        const result = await step(targetId, paseo);
+        // The notice started a turn; that turn's end carries the next one.
+        if (result === "sent" || result === "empty" || result === "gone") return;
+        // The target stayed idle: the next queued notice may go now.
+        if (result === "failed") continue;
+        // Busy or unreadable: wait for its next turn end, unless something changed meanwhile.
+        if (!flag.again) return;
+      }
+    } finally {
+      delivering.delete(targetId);
+    }
+  }
+
+  async function enqueue(targetId: string, kind: NoticeKind, text: string, paseo?: NoticePaseo): Promise<NoticeOutcome> {
+    try {
+      if (!nonEmpty(targetId) || !nonEmpty(kind) || !nonEmpty(text)) {
+        log("[paseo-bm] a plugin notice without a target, a kind or a text was not queued.");
+        return "dropped";
+      }
+      const entry: Entry = { kind, text, state: "queued" };
+      put(targetId, entry);
+      const handle = handleFor(paseo);
+      if (handle !== null) await deliver(targetId, handle);
+      return entry.state === "sending" ? "queued" : entry.state;
+    } catch (error) {
+      log(`[paseo-bm] queueing the ${String(kind)} notice for ${String(targetId)} failed: ${describeError(error)}`);
+      return "dropped";
+    }
+  }
+
+  async function turnEnded(event: unknown, paseo?: unknown): Promise<void> {
+    try {
+      const handle = handleFor(paseo);
+      const targetId = agentIdOf(event);
+      if (targetId === null || handle === null || !queued.has(targetId)) return;
+      await deliver(targetId, handle);
+    } catch (error) {
+      log(`[paseo-bm] delivering queued notices failed: ${describeError(error)}`);
+    }
+  }
+
+  return {
+    enqueue,
+    turnEnded,
+    pending: (targetId) => (queued.get(targetId) ?? []).map(({ kind, text }) => ({ kind, text })),
+    clear() {
+      for (const list of queued.values()) for (const entry of list) entry.state = "dropped";
+      queued.clear();
+      lastPaseo = null;
+    },
+  };
+}
+
+/** The queue every consumer shares; `registerNoticeQueue` delivers it by default. */
+export const noticeQueue: NoticeQueue = createNoticeQueue();
+
+/** `noticeQueue.enqueue`: send now when `targetId` is idle, otherwise at its next turn end. Never rejects. */
+export function enqueue(targetId: string, kind: NoticeKind, text: string, paseo?: NoticePaseo): Promise<NoticeOutcome> {
+  return noticeQueue.enqueue(targetId, kind, text, paseo);
+}
+
+export type NoticeHost = Partial<Pick<PluginServerContext, "on">>;
+
+export interface NoticeQueueRegistration {
+  /** Hand this to the module whose `agent.turn_ended` hook the queue rides on. */
+  host: NoticeHost;
+  /** Detaches the queue from that hook and forgets what it holds. */
+  remove(): void;
+}
+
+/**
+ * Lets the queue ride on an `agent.turn_ended` hook another module registers
+ * through the returned `host`: after that module's handler settles, the same
+ * turn end delivers the queue. Every other registration passes through
+ * untouched. On a host without `on` the queue is never delivered at turn ends;
+ * `enqueue` still sends to an idle target.
+ */
+export function registerNoticeQueue(host: NoticeHost, queue: NoticeQueue = noticeQueue): NoticeQueueRegistration {
+  let attached = true;
+  const remove = (): void => {
+    attached = false;
+    queue.clear();
+  };
+  if (typeof host.on !== "function") return { host, remove };
+  const register = host.on.bind(host);
+  const on: PluginServerContext["on"] = (name, handler) => {
+    if (name !== "agent.turn_ended") return register(name, handler);
+    return register(name, async (event, context) => {
+      try {
+        await handler(event, context);
+      } finally {
+        if (attached) await queue.turnEnded(event, context?.paseo);
+      }
+    });
+  };
+  return { host: { on }, remove };
+}

package/server/notices.ts

@@ -0,0 +1,81 @@
+/**
+ * Messages the PLUGIN sends to an agent, and how to recognise them again.
+ *
+ * Paseo's SDK always attaches a `messageId` to `PaseoAgentHandle.send()`, and
+ * the daemon stores it as `clientMessageId` — the very field the collector uses
+ * to tell a message the user typed from one an agent relayed (AGENTS.md). So
+ * without this list the plugin's own notices are recorded as the user's words:
+ * the Metric screen shows "you" saying `BM-BUDGET …`, counts it among the
+ * user's messages, and can even take it for the request text (review b2).
+ *
+ * Kept in its own module so the pure modules (`traces.ts`) and the senders
+ * (`stop-propagation.ts`, `review-budget.ts`) can share one definition without
+ * importing each other.
+ */
+
+/** First word of the review-budget notice (`review-budget.ts`). */
+export const BUDGET_NOTICE_MARKER = "BM-BUDGET";
+
+/** Start of the stop notice a Worker's Reviewers receive (`stop-propagation.ts`). */
+export const REVIEWER_STOP_NOTICE_PREFIX = "STOP: The Beads Worker that created you was stopped";
+
+/** First word of the stop notice a Worker receives from `/bm-worker-stop-all`. */
+export const WORKER_STOP_NOTICE_MARKER = "BM-STOP";
+
+/**
+ * What `/bm-worker-stop-all` sends to a running Worker.
+ *
+ * It POINTS AT the Worker's own stop rule rather than restating it. Restating
+ * would create a second procedure that drifts from `roles/worker.md`: the first
+ * draft of delta 20260917e did exactly that and its wording would have deleted
+ * the mandatory `cancel_agent` on the Worker's own Reviewers, and asked for a
+ * `blocked` report that `manager.md` renders as a question list — for a stop
+ * that has no questions.
+ */
+export const WORKER_STOP_NOTICE =
+  `${WORKER_STOP_NOTICE_MARKER} The user asked every Beads Worker and Reviewer in this workspace to stop. This is a stop: follow your Stop rule.`;
+
+/**
+ * First word of the notice the sender of a block that breaks its template
+ * receives (`format-check.ts`, delta 20260918g §4.7). Listed here so the trace
+ * store never records it as the user's words and `reviewCallsOf` never counts
+ * one sent to a Reviewer as a review call.
+ */
+export const FORMAT_NOTICE_MARKER = "BM-FORMAT";
+
+/**
+ * First word of the notice a Manager receives when a Worker it created has no
+ * Paseo tools (`tools-check.ts`, delta 20260921 §4.2.4).
+ */
+export const TOOLS_NOTICE_MARKER = "BM-TOOLS";
+
+/**
+ * First word of the notice a live Manager or Worker receives when the user
+ * changed the start mode of the agents it creates (`settings-notices.ts`,
+ * delta 20260921 §4.3.5).
+ */
+export const SETTINGS_NOTICE_MARKER = "BM-SETTINGS";
+
+/**
+ * First words of the plugin's fallback notices (delta 20260921 §4.4.6,
+ * §4.4.9): `BM-FALLBACK` tells a Manager about an incident and its decision;
+ * `BM-RESUME` asks an agent to carry on after its usage reset.
+ */
+export const FALLBACK_NOTICE_MARKER = "BM-FALLBACK";
+export const RESUME_NOTICE_MARKER = "BM-RESUME";
+
+const PREFIXES: readonly string[] = [
+  BUDGET_NOTICE_MARKER,
+  REVIEWER_STOP_NOTICE_PREFIX,
+  WORKER_STOP_NOTICE_MARKER,
+  FORMAT_NOTICE_MARKER,
+  TOOLS_NOTICE_MARKER,
+  SETTINGS_NOTICE_MARKER,
+  FALLBACK_NOTICE_MARKER,
+  RESUME_NOTICE_MARKER,
+];
+
+/** True when this text is one of the plugin's own notices, not a person's words. */
+export function isPluginNotice(text: unknown): boolean {
+  return typeof text === "string" && PREFIXES.some((prefix) => text.startsWith(prefix));
+}