@gperezmz/bb-plugin-thread-glance 0.1.2

package/server/notes.ts

@@ -0,0 +1,236 @@
+// One-line notes on why a thread is blocked, failed or done: one kv row per
+// thread, `note:<threadId>`, read into memory once and written through.
+import type { BbPluginApi, PluginThreadEventPayloads } from "@get-bb/plugin-sdk";
+import {
+  CHANNELS,
+  NOTE_MAX_LENGTH,
+  threadNotesSchema,
+  type Note,
+  type NotesSignal,
+  type ThreadNotes,
+} from "../shared/contract";
+import { createSerialQueue } from "./serial";
+
+export const NOTE_KEY_PREFIX = "note:";
+/** bb's builtin plugin that lets any provider ask a multiple-choice question. */
+export const ASK_USER_QUESTION_PLUGIN_ID = "ask-user-question";
+const FALLBACK_PENDING_TEXT = "Needs your input";
+
+type PendingInteraction = PluginThreadEventPayloads["interaction.pending"]["interaction"];
+export type NoteSlot = keyof ThreadNotes;
+export type NoteDraft = Pick<Note, "kind" | "text">;
+
+export function noteKvKey(threadId: string): string {
+  return `${NOTE_KEY_PREFIX}${threadId}`;
+}
+
+/**
+ * Collapses whitespace, strips leading markdown headings, bullets, numbers
+ * and quote marks, and truncates to NOTE_MAX_LENGTH with an ellipsis.
+ */
+export function noteText(raw: string): string {
+  let text = raw.replace(/\s+/g, " ").trim();
+  for (;;) {
+    const stripped = text.replace(/^(?:#{1,6}|[-*+>]|\d+[.)])\s+/, "");
+    if (stripped === text) break;
+    text = stripped;
+  }
+  if (text.length <= NOTE_MAX_LENGTH) return text;
+  return `${text.slice(0, NOTE_MAX_LENGTH - 1).trimEnd()}…`;
+}
+
+/** The first line with text, without its markdown heading marks. */
+function firstNonEmptyLine(text: string): string {
+  for (const line of text.split("\n")) {
+    const stripped = line.replace(/^\s*#+/, "").trim();
+    if (stripped !== "") return stripped;
+  }
+  return "";
+}
+
+function withMore(first: string, total: number): string {
+  return total > 1 ? `${first} (+${total - 1} more)` : first;
+}
+
+/** The first question's prompt from a `{ questions: [{ prompt }] }` object. */
+function questionsText(data: unknown): string | null {
+  if (data === null || typeof data !== "object" || Array.isArray(data)) return null;
+  const questions = (data as { questions?: unknown }).questions;
+  if (!Array.isArray(questions) || questions.length === 0) return null;
+  const prompt = (questions[0] as { prompt?: unknown } | null)?.prompt;
+  return typeof prompt === "string" && prompt.trim() !== ""
+    ? withMore(prompt, questions.length)
+    : null;
+}
+
+function approvalText(subjectText: string, reason: string | null): string {
+  return subjectText.trim() === "" && reason ? reason : subjectText;
+}
+
+function describeRaw(interaction: PendingInteraction): NoteDraft {
+  const payload = interaction.payload as { kind: string };
+  switch (interaction.payload.kind) {
+    case "user_question": {
+      const { questions } = interaction.payload;
+      const first = questions[0]?.prompt ?? "";
+      return { kind: "question", text: withMore(first, questions.length) };
+    }
+    case "approval": {
+      const { subject, reason } = interaction.payload;
+      switch (subject.kind) {
+        case "command":
+          return { kind: "approval", text: approvalText(subject.command, reason) };
+        case "file_change":
+          return {
+            kind: "approval",
+            text: `File changes${subject.writeScope ? ` in ${subject.writeScope}` : ""}`,
+          };
+        case "permission_grant":
+          return {
+            kind: "approval",
+            text: `Permissions${subject.toolName ? ` for ${subject.toolName}` : ""}`,
+          };
+        case "tool_use":
+          return { kind: "approval", text: subject.presentation.title ?? subject.tool };
+        case "plan":
+          return { kind: "plan", text: firstNonEmptyLine(subject.plan) };
+        default:
+          return { kind: "approval", text: reason ?? "" };
+      }
+    }
+    case "plugin": {
+      if (interaction.origin?.kind !== "plugin") break;
+      const { title, presentation, data } = interaction.payload as {
+        title: string;
+        presentation?: { detail?: string };
+        data: unknown;
+      };
+      if (interaction.origin.pluginId === ASK_USER_QUESTION_PLUGIN_ID) {
+        return { kind: "question", text: questionsText(data) ?? title };
+      }
+      const detail = presentation?.detail ? noteText(presentation.detail) : "";
+      const combined = `${title}: ${detail}`;
+      return {
+        kind: "input",
+        text: detail !== "" && combined.length <= NOTE_MAX_LENGTH ? combined : title,
+      };
+    }
+  }
+  if ("title" in payload && typeof payload.title === "string") {
+    return { kind: "input", text: payload.title };
+  }
+  return { kind: "input", text: FALLBACK_PENDING_TEXT };
+}
+
+/** The `pending` note for an interaction; never empty. */
+export function describeInteraction(interaction: PendingInteraction): NoteDraft {
+  const draft = describeRaw(interaction);
+  const text = noteText(draft.text);
+  return { kind: draft.kind, text: text === "" ? FALLBACK_PENDING_TEXT : text };
+}
+
+/** The `failed` note for a failure's text (see `failureText`); never empty. */
+export function describeFailure(error: string | null): NoteDraft {
+  const text = error === null ? "" : noteText(error);
+  return { kind: "failed", text: text === "" ? "Failed" : text };
+}
+
+/** The `done` note for the last assistant text, or null when there is none. */
+export function describeDone(lastAssistantText: string | null): NoteDraft | null {
+  const text = lastAssistantText === null ? "" : noteText(lastAssistantText);
+  return text === "" ? null : { kind: "done", text };
+}
+
+/** Per slot: a note to store, or null to delete it. Absent slots are kept. */
+export type NoteChanges = Partial<Record<NoteSlot, Note | null>>;
+
+export interface NoteStore {
+  list(): Promise<Record<string, ThreadNotes>>;
+  get(threadId: string): Promise<ThreadNotes | undefined>;
+  /** Applies the changes and publishes the thread's notes if they changed. */
+  update(threadId: string, changes: NoteChanges): Promise<void>;
+  /** Deletes every note of each thread, publishing `notes: null` for each. */
+  forget(threadIds: readonly string[]): Promise<void>;
+  /**
+   * Forgets threads missing from `liveIds` whose newest note is older than
+   * `before`, and returns their ids.
+   */
+  prune(liveIds: ReadonlySet<string>, before: number): Promise<string[]>;
+}
+
+export function createNoteStore(bb: Pick<BbPluginApi, "storage" | "realtime" | "log">): NoteStore {
+  const { kv } = bb.storage;
+  const serial = createSerialQueue();
+  let cache: Map<string, ThreadNotes> | null = null;
+
+  async function load(): Promise<Map<string, ThreadNotes>> {
+    if (cache !== null) return cache;
+    const loaded = new Map<string, ThreadNotes>();
+    for (const key of await kv.list(NOTE_KEY_PREFIX)) {
+      const threadId = key.slice(NOTE_KEY_PREFIX.length);
+      const parsed = threadNotesSchema.safeParse(await kv.get<unknown>(key));
+      if (!parsed.success || Object.keys(parsed.data).length === 0) {
+        bb.log.warn(`stored notes for ${threadId} are invalid; dropping them`);
+        await kv.delete(key);
+        continue;
+      }
+      loaded.set(threadId, parsed.data);
+    }
+    cache = loaded;
+    return loaded;
+  }
+
+  async function save(
+    rows: Map<string, ThreadNotes>,
+    threadId: string,
+    notes: ThreadNotes,
+  ): Promise<void> {
+    const empty = Object.keys(notes).length === 0;
+    if (empty) {
+      rows.delete(threadId);
+      await kv.delete(noteKvKey(threadId));
+    } else {
+      rows.set(threadId, notes);
+      await kv.set(noteKvKey(threadId), notes);
+    }
+    const signal: NotesSignal = { threadId, notes: empty ? null : notes };
+    bb.realtime.publish(CHANNELS.notes, signal);
+  }
+
+  return {
+    list: () => serial(async () => Object.fromEntries(await load())),
+    get: (threadId) => serial(async () => (await load()).get(threadId)),
+    update: (threadId, changes) =>
+      serial(async () => {
+        const rows = await load();
+        const current = rows.get(threadId) ?? {};
+        const next: ThreadNotes = { ...current };
+        for (const [slot, note] of Object.entries(changes) as [NoteSlot, Note | null][]) {
+          if (note === null) delete next[slot];
+          else next[slot] = note;
+        }
+        if (JSON.stringify(next) === JSON.stringify(current)) return;
+        await save(rows, threadId, next);
+      }),
+    forget: (threadIds) =>
+      serial(async () => {
+        const rows = await load();
+        for (const threadId of threadIds) {
+          if (rows.has(threadId)) await save(rows, threadId, {});
+        }
+      }),
+    prune: (liveIds, before) =>
+      serial(async () => {
+        const rows = await load();
+        const pruned: string[] = [];
+        for (const [threadId, notes] of [...rows]) {
+          if (liveIds.has(threadId)) continue;
+          const newest = Math.max(...Object.values(notes).map((note) => note.at));
+          if (newest >= before) continue;
+          await save(rows, threadId, {});
+          pruned.push(threadId);
+        }
+        return pruned;
+      }),
+  };
+}

package/server/preference-store.ts

@@ -0,0 +1,96 @@
+// Server-side preferences in the plugin kv, the same pattern as bb's
+// own thread-list server: one row per key, validated on every read and write.
+import type { BbPluginApi } from "@get-bb/plugin-sdk";
+import { CHANNELS, type PreferenceSignal } from "../shared/contract";
+import {
+  PREFERENCE_KEYS,
+  defaultPreferences,
+  parsePreference,
+  preferenceDefault,
+  type PreferenceKey,
+  type Preferences,
+} from "../shared/preferences";
+
+const PREFERENCE_KEY_PREFIX = "preference:";
+
+export function preferenceKvKey(key: PreferenceKey): string {
+  return `${PREFERENCE_KEY_PREFIX}${key}`;
+}
+
+/** A value that fails the key's schema. The message names the key. */
+export class PreferenceValidationError extends Error {
+  readonly key: PreferenceKey;
+  readonly detail: string;
+
+  constructor(key: PreferenceKey, detail: string) {
+    super(`Invalid value for ${key}: ${detail}`);
+    this.name = "PreferenceValidationError";
+    this.key = key;
+    this.detail = detail;
+  }
+}
+
+export interface PreferenceStore {
+  /** The stored value, or the default when none is stored or it is invalid. */
+  read<K extends PreferenceKey>(key: K): Promise<Preferences[K]>;
+  readAll(): Promise<Preferences>;
+  /** Whether the kv holds a row for the key, valid or not. */
+  isStored(key: PreferenceKey): Promise<boolean>;
+  /**
+   * Validates, stores and publishes the value, and returns it as parsed.
+   *
+   * @throws PreferenceValidationError when the value fails the key's schema.
+   */
+  write<K extends PreferenceKey>(key: K, value: unknown): Promise<Preferences[K]>;
+  /** Deletes the stored value, publishes the default and returns it. */
+  reset<K extends PreferenceKey>(key: K): Promise<Preferences[K]>;
+}
+
+export function createPreferenceStore(
+  bb: Pick<BbPluginApi, "storage" | "realtime" | "log">,
+): PreferenceStore {
+  const { kv } = bb.storage;
+
+  function publish(key: PreferenceKey, value: unknown): void {
+    const signal: PreferenceSignal = { key, value };
+    bb.realtime.publish(CHANNELS.preferences, signal);
+  }
+
+  async function read<K extends PreferenceKey>(key: K): Promise<Preferences[K]> {
+    const stored = await kv.get<unknown>(preferenceKvKey(key));
+    if (stored === undefined) return preferenceDefault(key);
+    const parsed = parsePreference(key, stored);
+    if (parsed.success) return parsed.value;
+    bb.log.warn(`stored preference ${key} is invalid (${parsed.message}); using the default`);
+    return preferenceDefault(key);
+  }
+
+  return {
+    read,
+    async readAll() {
+      const result = defaultPreferences();
+      await Promise.all(
+        PREFERENCE_KEYS.map(async (key) => {
+          (result as Record<PreferenceKey, unknown>)[key] = await read(key);
+        }),
+      );
+      return result;
+    },
+    async isStored(key) {
+      return (await kv.get<unknown>(preferenceKvKey(key))) !== undefined;
+    },
+    async write(key, value) {
+      const parsed = parsePreference(key, value);
+      if (!parsed.success) throw new PreferenceValidationError(key, parsed.message);
+      await kv.set(preferenceKvKey(key), parsed.value);
+      publish(key, parsed.value);
+      return parsed.value;
+    },
+    async reset(key) {
+      await kv.delete(preferenceKvKey(key));
+      const value = preferenceDefault(key);
+      publish(key, value);
+      return value;
+    },
+  };
+}

package/server/scheduled.ts

@@ -0,0 +1,129 @@
+// Scheduled sends: queued rows whose `sendAt` is in the future, kept in
+// memory and seeded again on every server start.
+import type { ScheduledSignal } from "../shared/contract";
+
+/** The fields of a queued row the tracker reads. */
+export interface QueuedRow {
+  id: string;
+  threadId: string;
+  sendAt: number | null;
+}
+
+type Change =
+  | { type: "upsert"; row: QueuedRow }
+  | { type: "remove"; rowId: string }
+  | { type: "remove-thread"; threadId: string };
+
+export interface ScheduledTracker {
+  /** `message.queued`: keeps the row while its `sendAt` is in the future. */
+  queued(row: QueuedRow): void;
+  /** `message.dispatched` and `message.cancelled`. */
+  removed(rowId: string): void;
+  /** `thread.archived` and `thread.deleted`. */
+  threadGone(threadId: string): void;
+  /**
+   * Replaces the rows with `load`'s result. Changes that arrive while `load`
+   * runs are applied on top, so they are not lost. A failed load sets the
+   * status to `error` and keeps the rows it had. Returns whether it loaded.
+   */
+  seed(load: () => Promise<readonly QueuedRow[]>): Promise<boolean>;
+  /** The current map; waits for a seed that is running. */
+  snapshot(): Promise<ScheduledSignal>;
+}
+
+/**
+ * Creates a tracker that calls `publish` whenever the per-thread map or the
+ * status changes. The status is `error` until the first seed succeeds.
+ */
+export function createScheduledTracker(options: {
+  publish: (signal: ScheduledSignal) => void;
+  now?: () => number;
+}): ScheduledTracker {
+  const now = options.now ?? Date.now;
+  let rows = new Map<string, { threadId: string; sendAt: number }>();
+  let status: ScheduledSignal["status"] = "error";
+  let duringSeed: Change[] | null = null;
+  let seeding: Promise<boolean> | null = null;
+  let lastPublished = JSON.stringify({ status, scheduled: {} } satisfies ScheduledSignal);
+
+  function apply(change: Change): void {
+    switch (change.type) {
+      case "upsert": {
+        const { id, threadId, sendAt } = change.row;
+        if (sendAt !== null && sendAt > now()) rows.set(id, { threadId, sendAt });
+        else rows.delete(id);
+        break;
+      }
+      case "remove":
+        rows.delete(change.rowId);
+        break;
+      case "remove-thread":
+        for (const [id, row] of rows) if (row.threadId === change.threadId) rows.delete(id);
+        break;
+    }
+  }
+
+  function current(): ScheduledSignal {
+    const at = now();
+    const scheduled: Record<string, number> = {};
+    for (const [id, row] of rows) {
+      if (row.sendAt <= at) {
+        rows.delete(id);
+        continue;
+      }
+      const earliest = scheduled[row.threadId];
+      if (earliest === undefined || row.sendAt < earliest) scheduled[row.threadId] = row.sendAt;
+    }
+    return { status, scheduled };
+  }
+
+  function publishIfChanged(): void {
+    const signal = current();
+    const serialized = JSON.stringify(signal);
+    if (serialized === lastPublished) return;
+    lastPublished = serialized;
+    options.publish(signal);
+  }
+
+  function change(next: Change): void {
+    duringSeed?.push(next);
+    apply(next);
+    publishIfChanged();
+  }
+
+  async function runSeed(load: () => Promise<readonly QueuedRow[]>): Promise<boolean> {
+    duringSeed = [];
+    try {
+      const loaded = await load();
+      const pending = duringSeed;
+      rows = new Map();
+      for (const row of loaded) apply({ type: "upsert", row });
+      for (const later of pending) apply(later);
+      status = "ready";
+      return true;
+    } catch {
+      status = "error";
+      return false;
+    } finally {
+      duringSeed = null;
+      publishIfChanged();
+    }
+  }
+
+  return {
+    queued: (row) => change({ type: "upsert", row }),
+    removed: (rowId) => change({ type: "remove", rowId }),
+    threadGone: (threadId) => change({ type: "remove-thread", threadId }),
+    seed(load) {
+      const run = runSeed(load).finally(() => {
+        if (seeding === run) seeding = null;
+      });
+      seeding = run;
+      return run;
+    },
+    async snapshot() {
+      if (seeding !== null) await seeding;
+      return current();
+    },
+  };
+}

package/server/serial.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns a runner that executes tasks one at a time, in call order. A failed
+ * task rejects its own promise and does not stop the tasks after it.
+ */
+export function createSerialQueue(): <T>(task: () => Promise<T>) => Promise<T> {
+  let tail: Promise<unknown> = Promise.resolve();
+  return <T>(task: () => Promise<T>): Promise<T> => {
+    const result = tail.then(task, task);
+    tail = result.catch(() => undefined);
+    return result;
+  };
+}

package/server/stamps.ts

@@ -0,0 +1,142 @@
+// Per-thread timestamps: one kv row per thread, `stamp:<threadId>`,
+// holding whichever of the four kinds it has. Rows are read into memory once
+// and written through, so listing does not read every row per call.
+import type { BbPluginApi } from "@get-bb/plugin-sdk";
+import { CHANNELS, type StampKind, type StampSignal, type Stamps } from "../shared/contract";
+import { createSerialQueue } from "./serial";
+
+export const STAMP_KEY_PREFIX = "stamp:";
+export const STAMP_KINDS: readonly StampKind[] = ["startedAt", "finishedAt", "pendingAt", "seenAt"];
+
+export type ThreadStamps = Partial<Record<StampKind, number>>;
+
+export function stampKvKey(threadId: string): string {
+  return `${STAMP_KEY_PREFIX}${threadId}`;
+}
+
+/** Keeps the known kinds whose value is a finite number; null if none. */
+export function parseThreadStamps(raw: unknown): ThreadStamps | null {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const record = raw as Record<string, unknown>;
+  const result: ThreadStamps = {};
+  for (const kind of STAMP_KINDS) {
+    const value = record[kind];
+    if (typeof value === "number" && Number.isFinite(value)) result[kind] = value;
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+export interface StampStore {
+  list(): Promise<Stamps>;
+  /** Sets `kind` to `at` for each thread and publishes one signal. */
+  stamp(kind: StampKind, threadIds: readonly string[], at: number): Promise<void>;
+  /** Deletes `kind` for each thread and publishes one signal with `value: null`. */
+  clear(kind: StampKind, threadIds: readonly string[]): Promise<void>;
+  /** Deletes every stamp of each thread. Publishes nothing. */
+  forget(threadIds: readonly string[]): Promise<void>;
+  /**
+   * Forgets threads missing from `liveIds` whose newest stamp is older than
+   * `before`, and returns their ids. Publishes nothing.
+   *
+   * `before` is when the caller started listing threads, so a thread created
+   * after the list was read, and stamped since, is kept.
+   */
+  prune(liveIds: ReadonlySet<string>, before: number): Promise<string[]>;
+}
+
+export function createStampStore(
+  bb: Pick<BbPluginApi, "storage" | "realtime" | "log">,
+): StampStore {
+  const { kv } = bb.storage;
+  const serial = createSerialQueue();
+  let cache: Map<string, ThreadStamps> | null = null;
+
+  async function load(): Promise<Map<string, ThreadStamps>> {
+    if (cache !== null) return cache;
+    const loaded = new Map<string, ThreadStamps>();
+    for (const key of await kv.list(STAMP_KEY_PREFIX)) {
+      const threadId = key.slice(STAMP_KEY_PREFIX.length);
+      const stamps = parseThreadStamps(await kv.get<unknown>(key));
+      if (stamps === null) {
+        bb.log.warn(`stored stamps for ${threadId} are invalid; dropping them`);
+        await kv.delete(key);
+        continue;
+      }
+      loaded.set(threadId, stamps);
+    }
+    cache = loaded;
+    return loaded;
+  }
+
+  async function save(
+    rows: Map<string, ThreadStamps>,
+    threadId: string,
+    stamps: ThreadStamps,
+  ): Promise<void> {
+    if (Object.keys(stamps).length === 0) {
+      rows.delete(threadId);
+      await kv.delete(stampKvKey(threadId));
+      return;
+    }
+    rows.set(threadId, stamps);
+    await kv.set(stampKvKey(threadId), stamps);
+  }
+
+  function publish(signal: StampSignal): void {
+    bb.realtime.publish(CHANNELS.stamps, signal);
+  }
+
+  return {
+    list: () =>
+      serial(async () => {
+        const result: Stamps = { startedAt: {}, finishedAt: {}, pendingAt: {}, seenAt: {} };
+        for (const [threadId, stamps] of await load()) {
+          for (const kind of STAMP_KINDS) {
+            const value = stamps[kind];
+            if (value !== undefined) result[kind][threadId] = value;
+          }
+        }
+        return result;
+      }),
+    stamp: (kind, threadIds, at) =>
+      serial(async () => {
+        if (threadIds.length === 0) return;
+        const rows = await load();
+        for (const threadId of new Set(threadIds)) {
+          await save(rows, threadId, { ...rows.get(threadId), [kind]: at });
+        }
+        publish({ kind, threadIds: [...threadIds], value: at });
+      }),
+    clear: (kind, threadIds) =>
+      serial(async () => {
+        if (threadIds.length === 0) return;
+        const rows = await load();
+        for (const threadId of new Set(threadIds)) {
+          const current = rows.get(threadId);
+          if (current?.[kind] === undefined) continue;
+          const { [kind]: _removed, ...rest } = current;
+          await save(rows, threadId, rest);
+        }
+        publish({ kind, threadIds: [...threadIds], value: null });
+      }),
+    forget: (threadIds) =>
+      serial(async () => {
+        const rows = await load();
+        for (const threadId of threadIds) {
+          if (rows.has(threadId)) await save(rows, threadId, {});
+        }
+      }),
+    prune: (liveIds, before) =>
+      serial(async () => {
+        const rows = await load();
+        const pruned: string[] = [];
+        for (const [threadId, stamps] of [...rows]) {
+          if (liveIds.has(threadId)) continue;
+          if (Math.max(...Object.values(stamps)) >= before) continue;
+          await save(rows, threadId, {});
+          pruned.push(threadId);
+        }
+        return pruned;
+      }),
+  };
+}