@app-vitals/agent-lib 0.0.1 → 0.1.0

package/pool-observability.unit.test.ts

@@ -0,0 +1,233 @@
+import { describe, expect, test } from "bun:test";
+import {
+  type CheckoutPool,
+  type Clock,
+  isPoolTimeoutError,
+  poolErrorContext,
+  routeContextMiddleware,
+  runWithRouteContext,
+  snapshotPool,
+  startPoolMonitor,
+  trackConnectionHold,
+} from "./pool-observability.ts";
+
+function makePool(over: Partial<CheckoutPool> = {}) {
+  const released: unknown[][] = [];
+  const pool: CheckoutPool = {
+    totalCount: 3,
+    idleCount: 1,
+    waitingCount: 0,
+    options: { max: 10 },
+    connect: async () => ({
+      release: (...args: unknown[]) => {
+        released.push(args);
+      },
+    }),
+    ...over,
+  };
+  return { pool, released };
+}
+
+function makeClock(startMs = 0) {
+  let t = startMs;
+  const clock: Clock = { now: () => new Date(t) };
+  return {
+    clock,
+    advance: (ms: number) => {
+      t += ms;
+    },
+  };
+}
+
+describe("snapshotPool", () => {
+  test("maps pool counts and max", () => {
+    expect(snapshotPool(makePool().pool)).toEqual({
+      total: 3,
+      idle: 1,
+      waiting: 0,
+      max: 10,
+    });
+  });
+});
+
+describe("isPoolTimeoutError", () => {
+  test("matches Prisma P2028", () => {
+    expect(isPoolTimeoutError({ code: "P2028", message: "x" })).toBe(true);
+  });
+  test("matches message variants", () => {
+    expect(
+      isPoolTimeoutError(
+        new Error("Unable to start a transaction in the given time."),
+      ),
+    ).toBe(true);
+    expect(
+      isPoolTimeoutError(new Error("timeout exceeded when trying to connect")),
+    ).toBe(true);
+    expect(
+      isPoolTimeoutError(
+        new Error("Connection terminated due to connection timeout"),
+      ),
+    ).toBe(true);
+  });
+  test("rejects unrelated errors", () => {
+    expect(isPoolTimeoutError(new Error("syntax error"))).toBe(false);
+    expect(isPoolTimeoutError({ code: "P2002" })).toBe(false);
+    expect(isPoolTimeoutError(null)).toBe(false);
+    expect(isPoolTimeoutError("timeout")).toBe(false);
+  });
+});
+
+describe("startPoolMonitor", () => {
+  function harness(pool: CheckoutPool) {
+    let tick: () => void = () => {};
+    let cleared: unknown;
+    const logs: unknown[][] = [];
+    const stop = startPoolMonitor(pool, {
+      intervalMs: 5,
+      log: (...a) => void logs.push(a),
+      setInterval: (fn, ms) => {
+        expect(ms).toBe(5);
+        tick = fn;
+        return "h";
+      },
+      clearInterval: (h) => {
+        cleared = h;
+      },
+    });
+    return { tick: () => tick(), stop, logs, cleared: () => cleared };
+  }
+
+  test("does not log when nobody is waiting", () => {
+    const h = harness(makePool().pool);
+    h.tick();
+    expect(h.logs).toHaveLength(0);
+  });
+
+  test("logs a snapshot when waiting > 0", () => {
+    const h = harness(makePool({ waitingCount: 4 }).pool);
+    h.tick();
+    expect(h.logs).toHaveLength(1);
+    expect(h.logs[0]?.[1]).toMatchObject({ waiting: 4, total: 3, max: 10 });
+  });
+
+  test("stop fn clears the interval", () => {
+    const h = harness(makePool().pool);
+    h.stop();
+    expect(h.cleared()).toBe("h");
+  });
+});
+
+describe("trackConnectionHold", () => {
+  async function run(
+    holdMs: number,
+    route?: { method: string; route: string },
+  ) {
+    const { pool, released } = makePool({ waitingCount: 2 });
+    const { clock, advance } = makeClock();
+    const logs: unknown[][] = [];
+    trackConnectionHold(pool, {
+      thresholdMs: 2000,
+      clock,
+      log: (...a) => void logs.push(a),
+    });
+    const exec = async () => {
+      const client = await pool.connect();
+      advance(holdMs);
+      client.release();
+      return client;
+    };
+    const client = route
+      ? await runWithRouteContext(route, exec)
+      : await exec();
+    return { client, logs, released };
+  }
+
+  test("does not log under the threshold", async () => {
+    const { logs, released } = await run(1500);
+    expect(logs).toHaveLength(0);
+    expect(released).toHaveLength(1);
+  });
+
+  test("logs route, heldMs and pool snapshot over the threshold", async () => {
+    const { logs } = await run(2500, { method: "GET", route: "/tasks/:id" });
+    expect(logs).toHaveLength(1);
+    expect(logs[0]?.[1]).toMatchObject({
+      route: "GET /tasks/:id",
+      heldMs: 2500,
+      pool: { total: 3, waiting: 2 },
+    });
+  });
+
+  test("route is null outside a request", async () => {
+    const { logs } = await run(2500);
+    expect(logs[0]?.[1]).toMatchObject({ route: null });
+  });
+
+  test("release is called once per call, error arg forwarded", async () => {
+    const { pool, released } = makePool();
+    trackConnectionHold(pool);
+    const client = await pool.connect();
+    const err = new Error("boom");
+    client.release(err);
+    expect(released).toEqual([[err]]);
+  });
+
+  test("double release behaves as unwrapped (underlying called each time)", async () => {
+    const { pool, released } = makePool();
+    const { clock, advance } = makeClock();
+    const logs: unknown[][] = [];
+    trackConnectionHold(pool, { clock, log: (...a) => void logs.push(a) });
+    const client = await pool.connect();
+    advance(5000);
+    client.release();
+    client.release(true);
+    expect(released).toEqual([[], [true]]);
+    expect(logs).toHaveLength(1);
+  });
+
+  test("restore fn reinstates original connect", async () => {
+    const { pool } = makePool();
+    const original = pool.connect;
+    const restore = trackConnectionHold(pool);
+    expect(pool.connect).not.toBe(original);
+    restore();
+    expect(pool.connect).toBe(original);
+  });
+});
+
+describe("routeContextMiddleware", () => {
+  test("records method and matched route pattern for poolErrorContext", async () => {
+    const { pool } = makePool();
+    let seen: Record<string, unknown> | undefined;
+    const c = {
+      req: {
+        method: "GET",
+        path: "/tasks/42",
+        matchedRoutes: [{ path: "/*" }, { path: "/tasks/:id" }],
+      },
+    };
+    await routeContextMiddleware()(c, async () => {
+      seen = poolErrorContext(pool);
+    });
+    expect(seen).toEqual({
+      total: 3,
+      idle: 1,
+      waiting: 0,
+      max: 10,
+      route: "GET /tasks/:id",
+    });
+  });
+
+  test("falls back to the request path without matchedRoutes", async () => {
+    let seen: Record<string, unknown> | undefined;
+    const c = { req: { method: "POST", path: "/x" } };
+    await routeContextMiddleware()(c, async () => {
+      seen = poolErrorContext(makePool().pool);
+    });
+    expect(seen?.route).toBe("POST /x");
+  });
+
+  test("poolErrorContext has null route outside a request", () => {
+    expect(poolErrorContext(makePool().pool).route).toBeNull();
+  });
+});

package/pricing.ts

@@ -0,0 +1,98 @@
+export interface TokenUsage {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_input_tokens: number;
+  cache_creation_input_tokens: number;
+}
+
+interface ModelRates {
+  input: number;
+  output: number;
+}
+
+export const OPUS_MODEL = "claude-opus-4-8";
+
+export const RATES: Record<string, ModelRates> = {
+  "claude-fable-5-1": { input: 10.0, output: 50.0 },
+  "claude-fable-5": { input: 10.0, output: 50.0 },
+  "claude-opus-5-5": { input: 4.0, output: 20.0 },
+  "claude-opus-4-8": { input: 5.0, output: 25.0 },
+  "claude-opus-4-7": { input: 5.0, output: 25.0 },
+  "claude-opus-4-6": { input: 5.0, output: 25.0 },
+  "claude-sonnet-5-5": { input: 2.0, output: 10.0 },
+  "claude-sonnet-4-6": { input: 3.0, output: 15.0 },
+  "claude-haiku-5-5": { input: 0.1, output: 0.5 },
+  "claude-haiku-4-5": { input: 1.0, output: 5.0 },
+  "claude-haiku-4-6": { input: 1.0, output: 5.0 },
+};
+
+/**
+ * Context window (input tokens) per rate key. Used by the prompt-audit
+ * tooling to express always-loaded context as a share of the window and to
+ * size the skill-listing budget (Claude Code reserves 1% of the window for
+ * the skill listing). Keys mirror RATES.
+ */
+export const CONTEXT_WINDOW: Record<string, number> = {
+  "claude-fable-5-1": 1_000_000,
+  "claude-fable-5": 1_000_000,
+  "claude-opus-5-5": 1_000_000,
+  "claude-opus-4-8": 1_000_000,
+  "claude-opus-4-7": 1_000_000,
+  "claude-opus-4-6": 1_000_000,
+  "claude-sonnet-5-5": 1_000_000,
+  "claude-sonnet-4-6": 1_000_000,
+  "claude-haiku-5-5": 1_000_000,
+  "claude-haiku-4-5": 200_000,
+  "claude-haiku-4-6": 200_000,
+};
+
+export function calculateCost(usage: TokenUsage, model: string): number {
+  const rates = RATES[model];
+  if (!rates) return 0;
+
+  const { input, output } = rates;
+  const cost =
+    usage.input_tokens * input +
+    usage.output_tokens * output +
+    usage.cache_creation_input_tokens * input * 1.25 +
+    usage.cache_read_input_tokens * input * 0.1;
+
+  return cost / 1_000_000;
+}
+
+export function normalizeModelToRateKey(model: string): string | null {
+  const bareModel = model.replace(/-\d{8}$/, "");
+  // Current-generation ids price as themselves. The bare "sonnet"/"opus"/
+  // "haiku" aliases resolve to the 5.5 keys; 4.x ids keep their own mapping.
+  if (
+    bareModel === "claude-fable-5-1" ||
+    bareModel === "claude-opus-5-5" ||
+    bareModel === "claude-sonnet-5-5" ||
+    bareModel === "claude-haiku-5-5"
+  ) {
+    return bareModel;
+  }
+  if (bareModel === "haiku") return "claude-haiku-5-5";
+  if (bareModel === "opus") return "claude-opus-5-5";
+  if (bareModel === "sonnet") return "claude-sonnet-5-5";
+  if (
+    bareModel === "claude-haiku-4-5" ||
+    bareModel === "claude-haiku-4-6"
+  ) {
+    return "claude-haiku-4-5";
+  }
+  if (bareModel === "claude-sonnet-4-6") {
+    return "claude-sonnet-4-6";
+  }
+  if (
+    bareModel === "claude-opus-4-8" ||
+    bareModel === "claude-opus-4-7" ||
+    bareModel === "claude-opus-4-6"
+  ) {
+    return "claude-opus-4-8";
+  }
+  if (bareModel === "fable" || bareModel === "claude-fable-5") {
+    return "claude-fable-5";
+  }
+  return null;
+}

package/pricing.unit.test.ts

@@ -0,0 +1,214 @@
+import { describe, expect, test } from "bun:test";
+import {
+  CONTEXT_WINDOW,
+  OPUS_MODEL,
+  RATES,
+  calculateCost,
+  normalizeModelToRateKey,
+} from "./pricing.ts";
+
+const SAMPLE_USAGE = {
+  input_tokens: 100,
+  output_tokens: 200,
+  cache_read_input_tokens: 50,
+  cache_creation_input_tokens: 10,
+};
+
+const ZERO_USAGE = {
+  input_tokens: 0,
+  output_tokens: 0,
+  cache_read_input_tokens: 0,
+  cache_creation_input_tokens: 0,
+};
+
+describe("OPUS_MODEL", () => {
+  test("is the canonical opus key present in RATES", () => {
+    expect(OPUS_MODEL).toBe("claude-opus-4-8");
+    expect(RATES[OPUS_MODEL]).toBeDefined();
+  });
+});
+
+describe("calculateCost — non-zero for known keys", () => {
+  test("returns non-zero for claude-sonnet-4-6 with sample usage", () => {
+    expect(calculateCost(SAMPLE_USAGE, "claude-sonnet-4-6")).toBeGreaterThan(0);
+  });
+
+  test("returns non-zero for claude-haiku-4-5 with sample usage", () => {
+    expect(calculateCost(SAMPLE_USAGE, "claude-haiku-4-5")).toBeGreaterThan(0);
+  });
+
+  test("returns non-zero for claude-opus-4-8 with sample usage", () => {
+    expect(calculateCost(SAMPLE_USAGE, "claude-opus-4-8")).toBeGreaterThan(0);
+  });
+
+  test("returns 0 for unknown model", () => {
+    expect(calculateCost(SAMPLE_USAGE, "gpt-4")).toBe(0);
+  });
+
+  test("returns 0 for zero usage", () => {
+    expect(calculateCost(ZERO_USAGE, "claude-sonnet-4-6")).toBe(0);
+  });
+});
+
+describe("normalizeModelToRateKey — haiku family", () => {
+  test('"haiku" maps to haiku canonical key', () => {
+    expect(normalizeModelToRateKey("haiku")).toBe("claude-haiku-5-5");
+  });
+
+  test('"claude-haiku-4-5" maps to haiku canonical key', () => {
+    expect(normalizeModelToRateKey("claude-haiku-4-5")).toBe("claude-haiku-4-5");
+  });
+
+  test('"claude-haiku-4-6" maps to haiku canonical key', () => {
+    expect(normalizeModelToRateKey("claude-haiku-4-6")).toBe("claude-haiku-4-5");
+  });
+});
+
+describe("normalizeModelToRateKey — sonnet family", () => {
+  test('"sonnet" maps to sonnet canonical key', () => {
+    expect(normalizeModelToRateKey("sonnet")).toBe("claude-sonnet-5-5");
+  });
+
+  test('"claude-sonnet-4-6" maps to sonnet canonical key', () => {
+    expect(normalizeModelToRateKey("claude-sonnet-4-6")).toBe("claude-sonnet-4-6");
+  });
+});
+
+describe("normalizeModelToRateKey — opus family", () => {
+  test('"opus" maps to opus canonical key', () => {
+    expect(normalizeModelToRateKey("opus")).toBe("claude-opus-5-5");
+  });
+
+  test('"claude-opus-4-8" maps to opus canonical key', () => {
+    expect(normalizeModelToRateKey("claude-opus-4-8")).toBe("claude-opus-4-8");
+  });
+
+  test('"claude-opus-4-7" maps to opus canonical key', () => {
+    expect(normalizeModelToRateKey("claude-opus-4-7")).toBe("claude-opus-4-8");
+  });
+
+  test('"claude-opus-4-6" maps to opus canonical key', () => {
+    expect(normalizeModelToRateKey("claude-opus-4-6")).toBe("claude-opus-4-8");
+  });
+});
+
+describe("normalizeModelToRateKey — fable family", () => {
+  test('"fable" maps to fable canonical key', () => {
+    expect(normalizeModelToRateKey("fable")).toBe("claude-fable-5");
+  });
+
+  test('"claude-fable-5" maps to fable canonical key', () => {
+    expect(normalizeModelToRateKey("claude-fable-5")).toBe("claude-fable-5");
+  });
+});
+
+describe("normalizeModelToRateKey — dated CLI snapshot IDs", () => {
+  test('"claude-haiku-4-5-20251001" strips snapshot suffix and maps to haiku canonical key', () => {
+    expect(normalizeModelToRateKey("claude-haiku-4-5-20251001")).toBe(
+      "claude-haiku-4-5",
+    );
+  });
+
+  test('"claude-haiku-4-6-20251001" strips snapshot suffix and maps to haiku canonical key', () => {
+    expect(normalizeModelToRateKey("claude-haiku-4-6-20251001")).toBe(
+      "claude-haiku-4-5",
+    );
+  });
+
+  test('"claude-sonnet-4-6-20250929" strips snapshot suffix and maps to sonnet canonical key', () => {
+    expect(normalizeModelToRateKey("claude-sonnet-4-6-20250929")).toBe(
+      "claude-sonnet-4-6",
+    );
+  });
+
+  test('"claude-opus-4-8-20250915" strips snapshot suffix and maps to opus canonical key', () => {
+    expect(normalizeModelToRateKey("claude-opus-4-8-20250915")).toBe(
+      "claude-opus-4-8",
+    );
+  });
+
+  test('"claude-opus-4-7-20250601" strips snapshot suffix and maps to opus canonical key', () => {
+    expect(normalizeModelToRateKey("claude-opus-4-7-20250601")).toBe(
+      "claude-opus-4-8",
+    );
+  });
+
+  test('"claude-fable-5-20251101" strips snapshot suffix and maps to fable canonical key', () => {
+    expect(normalizeModelToRateKey("claude-fable-5-20251101")).toBe(
+      "claude-fable-5",
+    );
+  });
+
+  test('unknown dated snapshot still returns null (no crash)', () => {
+    expect(normalizeModelToRateKey("claude-nope-1-0-20251001")).toBeNull();
+  });
+});
+
+describe("normalizeModelToRateKey — unknown inputs", () => {
+  test('"unknown-model" returns null', () => {
+    expect(normalizeModelToRateKey("unknown-model")).toBeNull();
+  });
+
+  test('empty string returns null', () => {
+    expect(normalizeModelToRateKey("")).toBeNull();
+  });
+
+  test('"gpt-4" returns null', () => {
+    expect(normalizeModelToRateKey("gpt-4")).toBeNull();
+  });
+});
+
+describe("normalizeModelToRateKey — 5.x ids price as themselves", () => {
+  for (const id of [
+    "claude-fable-5-1",
+    "claude-opus-5-5",
+    "claude-sonnet-5-5",
+    "claude-haiku-5-5",
+  ]) {
+    test(`${id} resolves to itself`, () => {
+      expect(normalizeModelToRateKey(id)).toBe(id);
+      expect(RATES[id]).toBeDefined();
+    });
+
+    test(`${id} dated snapshot resolves to itself`, () => {
+      expect(normalizeModelToRateKey(`${id}-20260101`)).toBe(id);
+    });
+  }
+});
+
+describe("5.x rates match the published rate card", () => {
+  test.each([
+    ["claude-fable-5-1", 10, 50],
+    ["claude-opus-5-5", 4, 20],
+    ["claude-sonnet-5-5", 2, 10],
+    ["claude-haiku-5-5", 0.1, 0.5],
+  ])("%s is $%d in / $%d out per MTok", (key, input, output) => {
+    expect(RATES[key]).toEqual({ input, output });
+  });
+});
+
+describe("normalizeModelToRateKey — bare aliases resolve to 5.5 keys", () => {
+  test("haiku/sonnet/opus aliases map to the 5.5 generation", () => {
+    expect(normalizeModelToRateKey("haiku")).toBe("claude-haiku-5-5");
+    expect(normalizeModelToRateKey("sonnet")).toBe("claude-sonnet-5-5");
+    expect(normalizeModelToRateKey("opus")).toBe("claude-opus-5-5");
+  });
+});
+
+describe("CONTEXT_WINDOW", () => {
+  test("has exactly the same keys as RATES", () => {
+    expect(Object.keys(CONTEXT_WINDOW).sort()).toEqual(Object.keys(RATES).sort());
+  });
+
+  test("every window is a positive integer", () => {
+    for (const size of Object.values(CONTEXT_WINDOW)) {
+      expect(Number.isInteger(size) && size > 0).toBe(true);
+    }
+  });
+
+  test("haiku 4.x is 200k; 5.x models are 1M", () => {
+    expect(CONTEXT_WINDOW["claude-haiku-4-5"]).toBe(200_000);
+    expect(CONTEXT_WINDOW["claude-opus-5-5"]).toBe(1_000_000);
+    expect(CONTEXT_WINDOW["claude-haiku-5-5"]).toBe(1_000_000);
+  });
+});

package/progress-phases.ts

@@ -0,0 +1,58 @@
+/**
+ * lib/progress-phases.ts
+ * The closed set of generic progress phases derived from a Claude Code
+ * `stream-json` session (see `agent/src/runtime/progress-milestones.ts`), plus their
+ * human-readable labels. Consumed by `agent/src/runtime/claude.ts`'s `ProgressCallback`
+ * and, eventually, by UI surfaces that want to show "what is the agent doing
+ * right now" without exposing raw tool inputs (which may contain secrets or
+ * file paths).
+ */
+
+/** The closed set of generic progress phases a Claude stream can report. */
+export type ProgressPhase =
+  | "starting"
+  | "thinking"
+  | "reading"
+  | "searching"
+  | "web"
+  | "editing"
+  | "running"
+  | "delegating"
+  | "planning"
+  | "tool"
+  | "writing";
+
+/** Runtime-checkable list of every valid ProgressPhase, in a stable order. */
+export const PROGRESS_PHASES: readonly ProgressPhase[] = [
+  "starting",
+  "thinking",
+  "reading",
+  "searching",
+  "web",
+  "editing",
+  "running",
+  "delegating",
+  "planning",
+  "tool",
+  "writing",
+];
+
+/**
+ * Short human-readable label per phase, for eventual UI use. Every label
+ * ends in an ellipsis ("…") — they describe an *in-progress* action (e.g.
+ * a Slack Thinking Steps card mid-run), and a bare label like "Reading
+ * files" reads as already-completed rather than ongoing.
+ */
+export const PROGRESS_LABELS: Record<ProgressPhase, string> = {
+  starting: "Starting up…",
+  thinking: "Thinking…",
+  reading: "Reading files…",
+  searching: "Searching the codebase…",
+  web: "Searching the web…",
+  editing: "Editing files…",
+  running: "Running commands…",
+  delegating: "Delegating to a subagent…",
+  planning: "Planning…",
+  tool: "Using a tool…",
+  writing: "Writing a response…",
+};

package/progress-phases.unit.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import { PROGRESS_LABELS, PROGRESS_PHASES } from "./progress-phases.ts";
+
+describe("PROGRESS_PHASES", () => {
+  test("is the closed set of exactly eleven phases", () => {
+    expect(PROGRESS_PHASES).toHaveLength(11);
+    expect(new Set(PROGRESS_PHASES).size).toBe(11);
+  });
+
+  test("contains exactly the documented phase names", () => {
+    expect([...(PROGRESS_PHASES as readonly string[])].sort()).toEqual(
+      [
+        "starting",
+        "thinking",
+        "reading",
+        "searching",
+        "web",
+        "editing",
+        "running",
+        "delegating",
+        "planning",
+        "tool",
+        "writing",
+      ].sort(),
+    );
+  });
+});
+
+describe("PROGRESS_LABELS", () => {
+  test("has exactly one label per phase in PROGRESS_PHASES", () => {
+    const labelKeys = Object.keys(PROGRESS_LABELS).sort();
+    expect(labelKeys).toEqual([...PROGRESS_PHASES].sort());
+  });
+
+  test("every label is a non-empty human-readable string", () => {
+    for (const phase of PROGRESS_PHASES) {
+      expect(typeof PROGRESS_LABELS[phase]).toBe("string");
+      expect(PROGRESS_LABELS[phase].length).toBeGreaterThan(0);
+    }
+  });
+
+  // STS2-1.1: every in-progress label must end in "…" for consistent
+  // Thinking Steps stream rendering (a bare, un-ellipsized label like
+  // "Reading files" reads as a completed action, not an in-progress one).
+  test("every label ends in an ellipsis (…), consistently", () => {
+    for (const phase of PROGRESS_PHASES) {
+      expect(PROGRESS_LABELS[phase].endsWith("…")).toBe(true);
+    }
+  });
+});

package/request-context.ts

@@ -0,0 +1,23 @@
+/**
+ * Represents an authenticated request caller, shared across services that
+ * resolve caller identity in auth middleware (admin, task-store, metrics).
+ *
+ * scope === "*" → unrestricted/admin (all clients/agents)
+ * scope === "<id>" → scoped to a single identity (clientId, agentId, etc.)
+ */
+export interface Caller {
+  name: string;
+  scope: string; // "*" or a scoped identity such as a clientId/agentId
+}
+
+/**
+ * Produce a stable, readable label for a caller, suitable for log lines.
+ * Returns "anonymous" when no caller is present (e.g. unauthenticated or
+ * not-yet-resolved requests). When the auth middleware's scope kind is
+ * known, it is appended in brackets (e.g. "svc (platform.read) [platform-read]").
+ */
+export function callerLabel(caller?: Caller, scopeKind?: string): string {
+  if (!caller) return "anonymous";
+  const label = `${caller.name} (${caller.scope})`;
+  return scopeKind ? `${label} [${scopeKind}]` : label;
+}