paseo-bm-plugin 0.0.0-placeholder.0

package/shared/fallback-patterns.ts

@@ -0,0 +1,201 @@
+/**
+ * Text patterns of a provider-plan failure, and the classifier that applies
+ * them (delta 20260921 §4.4.4, REQ-065 b).
+ *
+ * No Paseo provider classifies a usage limit (proposal S5), so the plugin reads
+ * the words of the failure: a failed turn's error message, or the short last
+ * reply of a turn that did nothing else (`server/fallback-detect.ts`).
+ *
+ * | Class | Meaning                       | Fallback |
+ * |-------|-------------------------------|----------|
+ * | L1    | plan usage limit              | yes      |
+ * | L2    | billing                       | yes      |
+ * | L4    | not logged in                 | yes      |
+ * | L5    | provider unavailable          | yes      |
+ * | L3    | temporary rate limit          | no       |
+ * | L6    | no pattern matched            | no       |
+ *
+ * The defaults are a starting point never checked on a real incident
+ * (proposal §1.5): the phase 2a-16 acceptance and the entry to phase 2a-18
+ * check them again. So they are one table of data, and the optional `patterns`
+ * of `role-fallback.json` (edited by hand only) replaces the defaults of any
+ * class it lists.
+ *
+ * The text is cut to `MAX_MATCH_CHARS` before matching. That bounds a pattern
+ * whose cost grows with the square of the text; it does not bound one that
+ * backtracks exponentially, such as `(a+)+$`, which already takes seconds on
+ * 25 characters and would hang the plugin inside the daemon. So a user
+ * pattern with a nested quantifier — a repeated group that itself holds a
+ * quantifier — is dropped like a broken one (owner decision Q16 a). Rarer
+ * shapes such as `(a|aa)*$` still get through: an accepted risk of a file
+ * edited by hand only. The defaults have no nested quantifier.
+ *
+ * Shared by server and client: no Node, no React.
+ */
+
+/** A class a pattern can name. L6 is the absence of a match, so no pattern names it. */
+export type PatternClass = "L1" | "L2" | "L3" | "L4" | "L5";
+
+/** What a text classifies as. */
+export type TextClass = PatternClass | "L6";
+
+/** The classes that lead to a fallback; L3 and L6 do not. */
+export type FallbackClass = "L1" | "L2" | "L4" | "L5";
+
+/** The optional `patterns` of `role-fallback.json`: regular expression sources per class. */
+export type UserPatterns = Partial<Record<PatternClass, readonly string[]>>;
+
+/** One class and its patterns, compiled case-insensitive, in match order. */
+export type PatternTable = ReadonlyArray<{ readonly class: PatternClass; readonly patterns: readonly RegExp[] }>;
+
+/** Characters of a text that are matched; the rest is ignored. */
+export const MAX_MATCH_CHARS = 2000;
+
+/**
+ * The default patterns as regular expression sources, in match order: the
+ * first class with a matching pattern wins. L1 comes before L3 because a
+ * plan-limit message may also say "rate limit".
+ */
+export const DEFAULT_PATTERNS: ReadonlyArray<{ readonly class: PatternClass; readonly patterns: readonly string[] }> = [
+  { class: "L1", patterns: ["usage limit", "limit reached", "hit your (usage )?limit", "limit (will )?reset", "resets? (at|in) "] },
+  {
+    class: "L2",
+    patterns: ["credit balance", "billing", "subscription (has )?(expired|ended|inactive)", "payment (required|failed)", "quota exceeded"],
+  },
+  {
+    class: "L4",
+    patterns: ["not logged in", "please (run )?/?login", "invalid api key", "authentication (failed|error)", "\\b401\\b", "oauth token (has )?expired"],
+  },
+  { class: "L5", patterns: ["provider (is )?unavailable", "process exited with code", "command not found", "ENOENT"] },
+  { class: "L3", patterns: ["rate[ _]limit", "overloaded", "\\b429\\b", "\\b529\\b", "too many requests"] },
+];
+
+const FALLBACK_CLASSES: ReadonlySet<string> = new Set(["L1", "L2", "L4", "L5"]);
+
+/** True for L1, L2, L4 and L5. */
+export function isFallbackClass(value: unknown): value is FallbackClass {
+  return typeof value === "string" && FALLBACK_CLASSES.has(value);
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * True when `source` repeats a group that holds a quantifier: `(a+)+`,
+ * `(\w*)*`, `(?:x{2,}){3,}`. A group counts as repeated after `*`, `+` or a
+ * `{n,}` / `{n,m}` with m > 1; `?` and `{0,1}` do not repeat. Escapes and
+ * character classes are skipped, so `\(a+\)+` and `[(a+)+]` are fine. Only a
+ * syntax check: it runs on a source that already compiles.
+ */
+export function hasNestedQuantifier(source: string): boolean {
+  /** Per open group: whether anything inside it is quantified. */
+  const groups: boolean[] = [];
+  /** Whether the group closed just before the current position held a quantifier. */
+  let closedHeldQuantifier = false;
+  const markQuantified = () => {
+    for (let depth = 0; depth < groups.length; depth += 1) groups[depth] = true;
+  };
+  let index = 0;
+  while (index < source.length) {
+    const char = source[index]!;
+    if (char === "\\") {
+      index += 2;
+      closedHeldQuantifier = false;
+      continue;
+    }
+    if (char === "[") {
+      // Skip the class: `]` right after `[` or `[^` is a literal.
+      index += 1;
+      if (source[index] === "^") index += 1;
+      if (source[index] === "]") index += 1;
+      while (index < source.length && source[index] !== "]") index += source[index] === "\\" ? 2 : 1;
+      index += 1;
+      closedHeldQuantifier = false;
+      continue;
+    }
+    if (char === "(") {
+      groups.push(false);
+      index += 1;
+      closedHeldQuantifier = false;
+      continue;
+    }
+    if (char === ")") {
+      closedHeldQuantifier = groups.pop() ?? false;
+      index += 1;
+      continue;
+    }
+    let repeats = false;
+    let quantifier = false;
+    let length = 1;
+    if (char === "*" || char === "+") {
+      quantifier = true;
+      repeats = true;
+    } else if (char === "?") {
+      quantifier = true;
+    } else if (char === "{") {
+      const range = /^\{(\d*)(,(\d*))?\}/.exec(source.slice(index));
+      if (range !== null) {
+        quantifier = true;
+        length = range[0].length;
+        const upper = range[2] === undefined ? Number(range[1]) : range[3] === "" ? Infinity : Number(range[3]);
+        repeats = upper > 1;
+      }
+    }
+    if (quantifier) {
+      if (repeats && closedHeldQuantifier) return true;
+      markQuantified();
+      // A lazy suffix (`+?`, `*?`, `{2,}?`) belongs to this quantifier.
+      if (source[index + length] === "?") length += 1;
+    }
+    closedHeldQuantifier = false;
+    index += length;
+  }
+  return false;
+}
+
+/**
+ * Compiles the table. A class the user lists with at least one entry uses the
+ * user's patterns instead of the defaults; an empty or missing list keeps the
+ * defaults. A user pattern that does not compile, is empty (it would match
+ * every text) or has a nested quantifier (`hasNestedQuantifier`) is dropped
+ * with one `[paseo-bm]` line; the rest of its class still counts. Never throws.
+ */
+export function compilePatterns(
+  user?: UserPatterns | null,
+  log: (message: string) => void = (message) => console.warn(message),
+): PatternTable {
+  return DEFAULT_PATTERNS.map((row) => {
+    const own: unknown = user?.[row.class];
+    if (!Array.isArray(own) || own.length === 0) {
+      return { class: row.class, patterns: row.patterns.map((source) => new RegExp(source, "i")) };
+    }
+    const patterns: RegExp[] = [];
+    for (const source of own as unknown[]) {
+      try {
+        if (typeof source !== "string" || source === "") throw new Error("a pattern must be a non-empty string");
+        const compiled = new RegExp(source, "i");
+        if (hasNestedQuantifier(source)) throw new Error("a repeated group holds a quantifier, which can hang the plugin (for example (a+)+)");
+        patterns.push(compiled);
+      } catch (error) {
+        log(`[paseo-bm] role-fallback.json: ${row.class} pattern ${JSON.stringify(source)} is ignored: ${describeError(error)}`);
+      }
+    }
+    return { class: row.class, patterns };
+  });
+}
+
+/** Classifies a text against a compiled table; a non-string or empty text is L6. */
+export function matchClass(text: unknown, table: PatternTable): TextClass {
+  if (typeof text !== "string" || text === "") return "L6";
+  const cut = text.slice(0, MAX_MATCH_CHARS);
+  for (const row of table) {
+    if (row.patterns.some((pattern) => pattern.test(cut))) return row.class;
+  }
+  return "L6";
+}
+
+/** Compiles and classifies in one call. Pure apart from the log line of a dropped user pattern. */
+export function classifyText(text: unknown, user?: UserPatterns | null, log?: (message: string) => void): TextClass {
+  return matchClass(text, compilePatterns(user, log));
+}

package/shared/fallback.ts

@@ -0,0 +1,46 @@
+/**
+ * Fallback aliases (delta 20260921 §4.4.1, REQ-065 f, REQ-031 a).
+ *
+ * Entry `n` (1…3) of a role's fallback chain runs on its own provider alias
+ * `bm-<role>-fallback-<n>`, which extends the entry's base provider. The alias
+ * has no agent profile: the entry's model, thinking and mode live in
+ * `role-fallback.json`, because the chain is paseo-bm's own concept (ADR-008).
+ *
+ * Shared by server and client: no Node, no React.
+ */
+
+/** A role that can have a fallback chain. */
+export type FallbackRole = "manager" | "worker" | "reviewer";
+
+/** Roles whose chain is offered: every role since phase 2a-17 (2a-16 offered the Worker's only). */
+export const FALLBACK_ROLES: readonly FallbackRole[] = ["worker", "reviewer", "manager"];
+
+/** Longest chain per role. */
+export const MAX_FALLBACK_ENTRIES = 3;
+
+/** A fallback alias id, the role it runs in group 1 and its position in group 2. */
+export const FALLBACK_ALIAS_PATTERN = /^bm-(manager|worker|reviewer)-fallback-([1-3])$/;
+
+/** `bm-<role>-fallback-<n>`; throws on a position outside 1…3 (a programming error). */
+export function fallbackAlias(role: FallbackRole, n: number): string {
+  if (!Number.isInteger(n) || n < 1 || n > MAX_FALLBACK_ENTRIES) {
+    throw new RangeError(`fallback position must be 1…${MAX_FALLBACK_ENTRIES}, got ${n}`);
+  }
+  return `bm-${role}-fallback-${n}`;
+}
+
+/** The role and position of a fallback alias id (no `/<model>`), or null. */
+export function fallbackAliasOf(alias: unknown): { role: FallbackRole; position: number } | null {
+  if (typeof alias !== "string") return null;
+  const match = FALLBACK_ALIAS_PATTERN.exec(alias);
+  return match === null ? null : { role: match[1] as FallbackRole, position: Number(match[2]) };
+}
+
+/**
+ * Where an alias id stands in its role's chain: 0 for the role's main alias
+ * (`bm-worker`), 1…3 for a fallback alias, null for anything else.
+ */
+export function positionOfAlias(alias: unknown): number | null {
+  if (alias === "bm-manager" || alias === "bm-worker" || alias === "bm-reviewer") return 0;
+  return fallbackAliasOf(alias)?.position ?? null;
+}

package/shared/new-request.ts

@@ -0,0 +1,20 @@
+/**
+ * The flag `/bm-worker-new` puts on the first line of the message it sends.
+ *
+ * It lives in `shared/` because both halves need it and neither may import the
+ * other: the client writes the flag, the server's collector takes it back off.
+ *
+ * It is a flag on the USER's words, not a notice of the plugin's own, so it is
+ * deliberately absent from `isPluginNotice`. Listing it there would make the
+ * collector record the whole message as `origin: "agent"` and the Dashboard
+ * would lose the request text itself (delta 20260917f §4.1).
+ */
+
+export const NEW_REQUEST_MARKER = "BM-NEW-REQUEST";
+
+/** The user's words, with the flag line removed if it carried one. */
+export function stripNewRequestMarker(text: string): string {
+  if (!text.startsWith(NEW_REQUEST_MARKER)) return text;
+  const newline = text.indexOf("\n");
+  return newline === -1 ? "" : text.slice(newline + 1).replace(/^\s+/, "");
+}

package/shared/order.ts

@@ -0,0 +1,22 @@
+/**
+ * Two tiny helpers every trace and bead view needs: chronological order and
+ * first-wins de-duplication. Pure and environment-neutral.
+ */
+
+/** Oldest first by an ISO timestamp; a missing timestamp sorts first. */
+export function byAt<T extends { at: string | null }>(a: T, b: T): number {
+  const left = a.at ?? "";
+  const right = b.at ?? "";
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/** Keeps the first item for each key, in the original order. */
+export function uniqueBy<T>(items: readonly T[], key: (item: T) => string): T[] {
+  const seen = new Set<string>();
+  return items.filter((item) => {
+    const value = key(item);
+    if (seen.has(value)) return false;
+    seen.add(value);
+    return true;
+  });
+}

package/shared/prices.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+/**
+ * Model price table bundled with the release (WP-201, REQ-052c).
+ *
+ * Source of truth: docs/design/paseo-bm-dashboard.md §9.
+ *
+ * Two rules make this table safe to ship:
+ *
+ * 1. **Never fetched at run time.** Runtime code reads this constant and
+ *    nothing else; the Dashboard makes no network call (REQ-052e).
+ * 2. **A model that is not listed gets no price.** The cost then reports
+ *    `costBasis: "unavailable"` and the UI shows tokens only (REQ-052d).
+ *    Guessing a rate would be worse than showing nothing.
+ *
+ * The figures are *Anthropic first-party API* rates, checked on the date in
+ * `PRICES_UPDATED_AT`. They are not an invoice: a provider-reported cost always
+ * wins over this table, and the same model on Amazon Bedrock or Google Vertex
+ * is billed at that partner's own rates, which are deliberately absent here.
+ *
+ * Cache reads are priced separately and are an order of magnitude cheaper than
+ * fresh input. Charging `cachedInputTokens` at the input rate is the one
+ * mistake that would make every estimate wildly too high, which is why the
+ * table carries an explicit `cacheReadUsdPerMTok` per row instead of a ratio
+ * applied in code.
+ *
+ * Models deliberately NOT in this table, so they resolve to "unavailable":
+ * - Codex / OpenAI models (for example `gpt-5.6-sol`, which the `bm-reviewer`
+ *   profile uses on this machine). No sourced figure was available when this
+ *   table was written, and Design §9 says other providers' rates come from
+ *   that provider's own published page. Adding a guessed number is forbidden.
+ * - Claude Fable / Mythos tiers. Their cache-read rate differs by version, and
+ *   an unverified rate belongs nowhere near a cost display.
+ *
+ * This module is `shared/`, so it stays free of Node and React Native imports.
+ */
+
+/** The day the rates below were checked against the provider's published prices. */
+export const PRICES_UPDATED_AT = "2026-06-24";
+
+/** Rates for one model, in US dollars per one million tokens. */
+export const modelPriceSchema = z.object({
+  inputUsdPerMTok: z.number().nonnegative(),
+  cacheReadUsdPerMTok: z.number().nonnegative(),
+  outputUsdPerMTok: z.number().nonnegative(),
+});
+
+export type ModelPrice = z.infer<typeof modelPriceSchema>;
+
+/**
+ * Keyed by the bare model id Paseo reports in an agent's `runtimeInfo`/profile
+ * (never `provider/model`): resolving the key is WP-209's job.
+ */
+export const MODEL_PRICES: Readonly<Record<string, ModelPrice>> = {
+  "claude-opus-5": { inputUsdPerMTok: 5, cacheReadUsdPerMTok: 0.5, outputUsdPerMTok: 25 },
+  "claude-opus-4-8": { inputUsdPerMTok: 5, cacheReadUsdPerMTok: 0.5, outputUsdPerMTok: 25 },
+  "claude-opus-4-7": { inputUsdPerMTok: 5, cacheReadUsdPerMTok: 0.5, outputUsdPerMTok: 25 },
+  "claude-opus-4-6": { inputUsdPerMTok: 5, cacheReadUsdPerMTok: 0.5, outputUsdPerMTok: 25 },
+  "claude-sonnet-5": { inputUsdPerMTok: 2, cacheReadUsdPerMTok: 0.2, outputUsdPerMTok: 10 },
+  "claude-sonnet-4-6": { inputUsdPerMTok: 3, cacheReadUsdPerMTok: 0.3, outputUsdPerMTok: 15 },
+  "claude-haiku-4-5": { inputUsdPerMTok: 1, cacheReadUsdPerMTok: 0.1, outputUsdPerMTok: 5 },
+};
+
+/** Every id that has a bundled rate. */
+export const PRICED_MODEL_IDS = Object.keys(MODEL_PRICES) as readonly string[];

package/shared/settings.ts

@@ -0,0 +1,57 @@
+import { defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+
+/**
+ * Host-scoped settings of the paseo-bm Dashboard (WP-201, REQ-055d).
+ *
+ * Source of truth: docs/design/paseo-bm-dashboard.md §3.6.
+ *
+ * Only one value for now: the size at which the Dashboard *warns* about the
+ * trace store. It never deletes on its own — ADR-007 decision 6 forbids that,
+ * so this threshold is a notice, not a retention policy.
+ *
+ * Paseo 0.8 offers exactly one settings scope, `"host"`, so this threshold is
+ * one value for the whole machine rather than per workspace (REQ-055e). The
+ * screen has to say that out loud; Q-042 records the option of a per-workspace
+ * threshold and deliberately leaves it unbuilt.
+ *
+ * This module is `shared/`, so it stays free of Node and React Native imports.
+ */
+
+/** 200 MB — the agreed default warning threshold (Q-040). */
+export const DEFAULT_WARN_ABOVE_BYTES = 200 * 1024 * 1024;
+
+/**
+ * Stored shape. `warnAboveBytes` must be a positive integer: zero would warn
+ * forever and a negative number is meaningless, so both are rejected at the
+ * write and the previously stored value stays in effect (REQ-055f).
+ */
+export const dashboardSettingsSchema = z.object({
+  warnAboveBytes: z.number().int().positive().default(DEFAULT_WARN_ABOVE_BYTES),
+});
+
+/**
+ * Keeps a stored threshold across a future schema version bump.
+ *
+ * Version 1 has nothing to migrate *from*, but the hook has to exist now:
+ * without it, bumping `version` later would silently drop the user's threshold
+ * back to the default. It ignores `fromVersion` on purpose: there is only one
+ * version so far, and the value it carries is validated the same way whatever
+ * version wrote it. A stored value that no longer validates is dropped on
+ * purpose — falling back to a known-good default beats carrying a broken one.
+ */
+export function migrateDashboardSettings(values: unknown): unknown {
+  const stored = (values as { warnAboveBytes?: unknown } | null | undefined)?.warnAboveBytes;
+  return dashboardSettingsSchema.safeParse({ warnAboveBytes: stored }).success
+    ? { warnAboveBytes: stored }
+    : {};
+}
+
+/** The definition `index.server.ts` registers and the settings screen reads with `useSettings`. */
+export const dashboardSettings = defineSettings({
+  id: "paseo-bm",
+  scope: "host",
+  version: 1,
+  schema: dashboardSettingsSchema,
+  migrate: migrateDashboardSettings,
+});

package/shared/sole-worker.ts

@@ -0,0 +1,20 @@
+/**
+ * Which Worker a request belongs to (delta 20260918f F12, owner decision Q7 a).
+ *
+ * The one live `worker` carrying the request id; nobody when there is none, or
+ * more than one. An archived agent never counts: sending to it would bring it
+ * back (ADR-005), and a broken Worker the Manager replaced keeps the request's
+ * label. Nor does a Worker a fallback Worker replaced (`replaced`, delta
+ * 20260921 §4.4.8): the replacement carries the same request id. `chat.waiting` (server) and the chat card (client) both decide with
+ * this, so a pill and its card always agree.
+ *
+ * Pure and environment-neutral.
+ */
+export function soleWorkerOf<P extends { role: string; requestId: string | null; archived: boolean; replaced?: boolean }>(
+  peers: readonly P[],
+  requestId: string | null,
+): P | null {
+  if (requestId === null) return null;
+  const live = peers.filter((peer) => peer.role === "worker" && !peer.archived && peer.replaced !== true && peer.requestId === requestId);
+  return live.length === 1 ? live[0]! : null;
+}

package/shared/version.ts

@@ -0,0 +1,6 @@
+// GENERATED FILE — do not edit by hand.
+// Regenerated from the package version by scripts/generate-plugin-version.mjs,
+// which the build runs before packing. Design ref: docs/design/paseo-bm.md §2.4.
+
+/** Version of the paseo-bm payload, baked in at build time. */
+export const PLUGIN_VERSION = "0.3.0-alpha.5";

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2023"],
+    "types": ["react", "node"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["**/*.ts", "**/*.tsx"]
+}