paseo-bm-plugin 0.0.0-placeholder.0

package/server/agent-role.ts

@@ -0,0 +1,102 @@
+/**
+ * Which paseo-bm role an agent has (delta 20260918g §4.1, REQ-061 a).
+ *
+ * The `bm.role` label is the usual answer, but it is not the only one: an agent
+ * started from Paseo's own new-agent flow with a paseo-bm profile runs the role
+ * (the `before("agent.create")` hook gives it the instructions) and carries no
+ * label at all, because that hook can change `{ config, env }` only. The owner's
+ * "Refactor Dependency" Manager was such an agent, and every lookup that
+ * filtered on the label treated its chat as "not paseo-bm's" (bead bm-llmg).
+ * So the provider decides whenever the label does not.
+ *
+ * Pure apart from `listAllAgents`, which only calls the `list` it is given.
+ */
+import { fallbackAliasOf } from "../shared/fallback";
+import { providerId } from "./provider-id";
+
+export type BmRole = "manager" | "worker" | "reviewer";
+
+/** The role, and whether it came from the `bm.role` label (true) or only from the provider (false). */
+export interface RoleFact {
+  role: BmRole;
+  labelled: boolean;
+}
+
+/** Label key that names an agent's paseo-bm role. */
+export const ROLE_LABEL = "bm.role";
+
+/**
+ * The three main paseo-bm provider aliases and the role each one runs. A
+ * fallback alias `bm-<role>-fallback-<n>` runs the role in its name
+ * (`roleOfProvider`, delta 20260921 §4.4.1); it is not listed here.
+ */
+export const ROLE_BY_PROVIDER: Readonly<Record<string, BmRole>> = {
+  "bm-manager": "manager",
+  "bm-worker": "worker",
+  "bm-reviewer": "reviewer",
+};
+
+const ROLES: ReadonlySet<string> = new Set(["manager", "worker", "reviewer"]);
+
+/**
+ * The role a provider selection runs, or null: `bm-worker` and
+ * `bm-worker/<model>` run the Worker, and so do `bm-worker-fallback-<1..3>`
+ * (with or without `/<model>`).
+ */
+export function roleOfProvider(provider: unknown): BmRole | null {
+  const id = providerId(provider);
+  if (id === null) return null;
+  if (Object.prototype.hasOwnProperty.call(ROLE_BY_PROVIDER, id)) return ROLE_BY_PROVIDER[id]!;
+  return fallbackAliasOf(id)?.role ?? null;
+}
+
+/**
+ * The role of an agent snapshot, or null when it is not a paseo-bm agent.
+ * A valid `bm.role` label wins; otherwise the provider decides, which also
+ * covers a label holding an unknown value. Never throws.
+ */
+export function roleOfAgent(agent: unknown): RoleFact | null {
+  try {
+    if (agent === null || typeof agent !== "object") return null;
+    const { labels, provider } = agent as { labels?: unknown; provider?: unknown };
+    const label =
+      labels !== null && typeof labels === "object" ? (labels as Record<string, unknown>)[ROLE_LABEL] : undefined;
+    if (typeof label === "string" && ROLES.has(label)) return { role: label as BmRole, labelled: true };
+    const role = roleOfProvider(provider);
+    return role === null ? null : { role, labelled: false };
+  } catch {
+    return null;
+  }
+}
+
+/** Page size of every `agents.list` walk; the daemon caps a page at 200. */
+export const LIST_PAGE_LIMIT = 200;
+
+/**
+ * Walks every page of an `agents.list` query and returns all snapshots.
+ * A page without `pageInfo` is the last one, so a host (or fake) that pages
+ * nothing still works.
+ */
+export async function listAllAgents<Filter, Snapshot>(
+  list: (options: {
+    filter: Filter;
+    page: { limit: number; cursor?: string };
+  }) => Promise<{
+    entries: Array<{ agent: Snapshot }>;
+    pageInfo?: { nextCursor: string | null; hasMore: boolean };
+  }>,
+  filter: Filter,
+): Promise<Snapshot[]> {
+  const found: Snapshot[] = [];
+  let cursor: string | undefined;
+  for (;;) {
+    const page = await list({
+      filter,
+      page: cursor === undefined ? { limit: LIST_PAGE_LIMIT } : { limit: LIST_PAGE_LIMIT, cursor },
+    });
+    for (const { agent } of page.entries) found.push(agent);
+    if (!page.pageInfo?.hasMore || !page.pageInfo.nextCursor) break;
+    cursor = page.pageInfo.nextCursor;
+  }
+  return found;
+}

package/server/answer-marks.ts

@@ -0,0 +1,120 @@
+/**
+ * Where "Mark as answered" is remembered (delta 20260918d-card-replies §4.9,
+ * REQ-059 k; owner decision Q16 a).
+ *
+ * A mark says the user considers a question card answered, even if its Worker
+ * still looks like it waits. It must survive an app reload, so it lives in a
+ * small file of the install home, next to the launcher's pinned order, and is
+ * written through the same machinery: the no-follow path guard and the atomic
+ * temp-then-rename the trace store uses.
+ *
+ * Reads never repair the file. A corrupt or too-new file reads as "no marks"
+ * and says so; writing over a newer version's file is refused.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { UI_DIR_NAME } from "./install-home";
+import { assertNoSymlinkOnPath, ensureStoreDir, writeStoreFileAtomically, type TraceStoreLocation } from "./trace-store";
+import { DashboardError } from "../shared/contracts";
+
+/** Bumped only when the shape below changes incompatibly. */
+export const ANSWER_MARKS_SCHEMA_VERSION = 1;
+export const ANSWER_MARKS_FILE_NAME = "answer-marks.json";
+/** Oldest marks go first once there are more: a mark only matters for a live card. */
+export const ANSWER_MARKS_LIMIT = 500;
+export const ANSWER_MARK_KEY_MAX = 400;
+
+const answerMarksFileSchema = z.object({
+  schemaVersion: z.number().int().positive(),
+  marks: z.array(z.object({ key: z.string(), at: z.string() })),
+});
+
+export interface AnswerMarks {
+  /** Card keys, oldest first. */
+  keys: string[];
+  /** What could not be read, in the user's terms. Empty when all is well. */
+  notices: string[];
+  /** True when the file on disk is newer than this plugin understands. */
+  tooNew: boolean;
+}
+
+/** True when `text` holds an ASCII control character (codes 0-31 and 127). */
+function hasControlCharacter(text: string): boolean {
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+    if (code < 32 || code === 127) return true;
+  }
+  return false;
+}
+
+/** A key this store accepts: a card key is `agentId|requestId|questionIds|hash`. */
+export function isAnswerMarkKey(key: unknown): key is string {
+  return typeof key === "string" && key.length > 0 && key.length <= ANSWER_MARK_KEY_MAX && !hasControlCharacter(key);
+}
+
+export function answerMarksPath(location: TraceStoreLocation): string {
+  return join(dirname(location.tracesDir), UI_DIR_NAME, ANSWER_MARKS_FILE_NAME);
+}
+
+function readMarks(location: TraceStoreLocation): { marks: Array<{ key: string; at: string }>; notices: string[]; tooNew: boolean } {
+  const path = answerMarksPath(location);
+  // Before the read, so a symlinked path is refused rather than followed.
+  assertNoSymlinkOnPath(dirname(location.tracesDir), path);
+
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { marks: [], notices: [], tooNew: false };
+    return { marks: [], notices: [`Could not read the answered marks (${(error as Error).message}).`], tooNew: false };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { marks: [], notices: ["The answered-marks file is not valid JSON; no card is marked."], tooNew: false };
+  }
+  const result = answerMarksFileSchema.safeParse(parsed);
+  if (!result.success) {
+    return { marks: [], notices: ["The answered-marks file does not have the expected shape; no card is marked."], tooNew: false };
+  }
+  if (result.data.schemaVersion > ANSWER_MARKS_SCHEMA_VERSION) {
+    return {
+      marks: [],
+      notices: [
+        `The answered-marks file is version ${result.data.schemaVersion}, newer than this plugin understands (${ANSWER_MARKS_SCHEMA_VERSION}); no card is marked and nothing will be written.`,
+      ],
+      tooNew: true,
+    };
+  }
+  const marks = result.data.marks.filter((mark) => isAnswerMarkKey(mark.key));
+  const dropped = result.data.marks.length - marks.length;
+  return { marks, notices: dropped > 0 ? [`Ignored ${dropped} unusable mark(s) in the answered-marks file.`] : [], tooNew: false };
+}
+
+/** The marks, or none. Never throws for a bad file; throws only for a symlinked path. */
+export function readAnswerMarks(location: TraceStoreLocation): AnswerMarks {
+  const { marks, notices, tooNew } = readMarks(location);
+  return { keys: marks.map((mark) => mark.key), notices, tooNew };
+}
+
+/** Adds (as the newest) or removes one mark. Refuses a bad key and a newer file. */
+export function writeAnswerMark(location: TraceStoreLocation, key: string, marked: boolean, now: () => Date = () => new Date()): AnswerMarks {
+  if (!isAnswerMarkKey(key)) {
+    throw new DashboardError("E_TRACE_STORE_UNWRITABLE", `not a usable card key: ${JSON.stringify(String(key).slice(0, 60))}`);
+  }
+  const current = readMarks(location);
+  if (current.tooNew) {
+    throw new DashboardError("E_TRACE_STORE_UNWRITABLE", "the answered-marks file was written by a newer version of paseo-bm; refusing to overwrite it");
+  }
+  const others = current.marks.filter((mark) => mark.key !== key);
+  const marks = (marked ? [...others, { key, at: now().toISOString() }] : others).slice(-ANSWER_MARKS_LIMIT);
+  ensureStoreDir(location.tracesDir, join(dirname(location.tracesDir), UI_DIR_NAME));
+  writeStoreFileAtomically(
+    location,
+    answerMarksPath(location),
+    `${JSON.stringify({ schemaVersion: ANSWER_MARKS_SCHEMA_VERSION, marks }, null, 2)}\n`,
+  );
+  return { keys: marks.map((mark) => mark.key), notices: [], tooNew: false };
+}

package/server/bead-actions.ts

@@ -0,0 +1,88 @@
+/**
+ * The Beads screen: list, detail and the three hand-off actions
+ * (design delta 20260916-beads-screen).
+ *
+ * An action never touches the bead store. It makes sure the workspace has a
+ * Beads Manager and sends it a request; the Manager delegates to a Worker like
+ * any other request, so labels, reports, the review budget and the Metric
+ * screen all keep working.
+ */
+import { isReady, readBeads, type BeadRecord } from "./beads-store";
+import { DashboardError, type BeadAction, type BeadDetail, type BeadRow } from "../shared/contracts";
+
+export function beadRowOf(bead: BeadRecord, all: Map<string, BeadRecord>): BeadRow {
+  return {
+    id: bead.id,
+    title: bead.title,
+    status: bead.status,
+    issueType: bead.issueType,
+    priority: bead.priority,
+    labels: bead.labels,
+    createdAt: bead.createdAt,
+    updatedAt: bead.updatedAt === "" ? null : bead.updatedAt,
+    closedAt: bead.closedAt,
+    ready: bead.status !== "closed" && isReady(bead, all),
+    parentId: bead.parentId,
+    work: null,
+  };
+}
+
+/** Every bead of a workspace, newest update first. */
+export function listBeadRows(workspaceDirectory: string): BeadRow[] {
+  const { beads } = readBeads(workspaceDirectory);
+  return [...beads.values()]
+    .map((bead) => beadRowOf(bead, beads))
+    .sort((a, b) => ((a.updatedAt ?? "") < (b.updatedAt ?? "") ? 1 : (a.updatedAt ?? "") > (b.updatedAt ?? "") ? -1 : 0));
+}
+
+export function getBeadDetail(workspaceDirectory: string, id: string): BeadDetail {
+  const { beads } = readBeads(workspaceDirectory);
+  const bead = beads.get(id);
+  if (bead === undefined) throw new DashboardError("E_BEAD_NOT_FOUND", `no bead ${id} in ${workspaceDirectory}`);
+  return {
+    ...beadRowOf(bead, beads),
+    description: bead.description,
+    closeReason: bead.closeReason,
+    blockedBy: bead.blockedBy,
+    children: [...beads.values()].filter((other) => other.parentId === id).map((other) => other.id),
+  };
+}
+
+const INSTRUCTION: Record<BeadAction, string> = {
+  implement: "Have a Worker implement this bead until it is closed with evidence, following its acceptance criteria.",
+  delete:
+    "Have a Worker assess whether this bead is still needed. If it is not, delete it with the tracker (br) and report why. If it is still needed, do not delete it; report the reason instead.",
+  close:
+    "Have a Worker check whether this bead can be closed: its acceptance criteria are met and nothing it requires is still open. If so, close it with the tracker (br) and the evidence as the reason. If not, leave it open and report what is missing.",
+};
+
+/** The request the Manager receives. Agent-facing, so English. */
+export function actionMessage(action: BeadAction, bead: Pick<BeadRow, "id" | "title">): string {
+  const title = bead.title === null ? "" : ` ("${bead.title}")`;
+  return [
+    `[Beads screen] The user asks: ${action} bead ${bead.id}${title}.`,
+    INSTRUCTION[action],
+    "The user confirmed this action on the Beads screen. Treat it as a new request from the user. Do not commit or push.",
+  ].join("\n");
+}
+
+export interface BeadActionPaseo {
+  agents: { ref(agentId: string): { send(text: string): Promise<void> } };
+}
+
+/**
+ * Sends the action to the workspace's Manager. `ensure` is the existing
+ * `ensureManager` bound to this host, so a workspace without a Manager gets
+ * one exactly as the launcher would create it.
+ */
+export async function runBeadAction(
+  input: { workspaceId: string; action: BeadAction; bead: Pick<BeadRow, "id" | "title"> },
+  deps: {
+    paseo: BeadActionPaseo;
+    ensure: (workspaceId: string) => Promise<{ agentId: string; created: boolean }>;
+  },
+): Promise<{ managerId: string; created: boolean }> {
+  const manager = await deps.ensure(input.workspaceId);
+  await deps.paseo.agents.ref(manager.agentId).send(actionMessage(input.action, input.bead));
+  return { managerId: manager.agentId, created: manager.created };
+}

package/server/bead-work.ts

@@ -0,0 +1,80 @@
+/**
+ * Who is working on a bead, and since when, read from the trace store.
+ *
+ * The bead store cannot say: `br` records no start time, and Workers do not set
+ * an assignee. What the store of traces does have is every shell command a
+ * Worker ran and every report it sent, so:
+ *
+ * - **started**: the latest Worker command that moved the bead to
+ *   `in_progress` (`br update <id> --status in_progress` or `--claim`);
+ * - **last**: the latest Worker command or `BM-REPORT` that named the bead.
+ *
+ * Only Worker turns count: a Reviewer reading a bead with `br show` is not
+ * working on it. Pure: records and agents in, marks out.
+ */
+import { brActions } from "./shell";
+import type { AgentFacts } from "./traces";
+import type { BeadWork, TraceRecord } from "../shared/contracts";
+
+interface Seen {
+  agentId: string;
+  at: string;
+}
+
+/** A matcher for `id` as a whole id (`bm-a.1` does not match `bm-a.12`). */
+function wholeId(id: string): RegExp {
+  const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?<![A-Za-z0-9_.-])${escaped}(?![A-Za-z0-9_-]|\\.[A-Za-z0-9])`);
+}
+
+/** True when `text` names `id` as a whole id. */
+export function namesBead(text: string, id: string): boolean {
+  return wholeId(id).test(text);
+}
+
+export function beadWorkOf(
+  beadIds: readonly string[],
+  records: readonly TraceRecord[],
+  agents: ReadonlyMap<string, AgentFacts>,
+): Map<string, BeadWork> {
+  const started = new Map<string, Seen>();
+  const last = new Map<string, Seen>();
+  const later = (map: Map<string, Seen>, id: string, seen: Seen) => {
+    const current = map.get(id);
+    if (current === undefined || current.at <= seen.at) map.set(id, seen);
+  };
+
+  // Built once: the loop below runs them over every Worker command.
+  const matchers = beadIds.map((id) => [id, wholeId(id)] as const);
+  for (const record of records) {
+    if (record.role !== "worker") continue;
+    for (const evidence of record.evidence) {
+      if (evidence.kind !== "shell") continue;
+      const seen = { agentId: record.agentId, at: evidence.at ?? record.at };
+      const actions = brActions(evidence.detail);
+      const startedIds = new Set(actions.flatMap((action) => (action.startsWork ? action.ids : [])));
+      for (const [id, matcher] of matchers) {
+        if (startedIds.has(id)) later(started, id, seen);
+        if (matcher.test(evidence.detail)) later(last, id, seen);
+      }
+    }
+    for (const report of record.reports) {
+      const named = new Set([...report.beadsCreated, ...report.beadsUpdated, ...report.beadsClosed, ...report.beadsReady]);
+      for (const id of beadIds) {
+        if (named.has(id)) later(last, id, { agentId: report.agentId, at: report.at });
+      }
+    }
+  }
+
+  const mark = (seen: Seen | undefined) => {
+    if (seen === undefined) return null;
+    const agent = agents.get(seen.agentId);
+    return { ...seen, title: agent?.title ?? null, status: agent?.status ?? null };
+  };
+  const out = new Map<string, BeadWork>();
+  for (const id of beadIds) {
+    if (!started.has(id) && !last.has(id)) continue;
+    out.set(id, { started: mark(started.get(id)), last: mark(last.get(id)) });
+  }
+  return out;
+}