@app-vitals/agent-lib 0.0.1 → 0.1.1

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;
+}

package/request-context.unit.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { callerLabel } from "./request-context.ts";
+
+describe("callerLabel — defined caller", () => {
+  test("formats an admin caller (scope '*')", () => {
+    expect(callerLabel({ name: "bodhi", scope: "*" })).toBe("bodhi (*)");
+  });
+
+  test("formats a caller scoped to a clientId", () => {
+    expect(callerLabel({ name: "sully", scope: "client-xyz" })).toBe(
+      "sully (client-xyz)",
+    );
+  });
+
+  test("formats a caller scoped to an agentId", () => {
+    expect(callerLabel({ name: "agent-123", scope: "agent-456" })).toBe(
+      "agent-123 (agent-456)",
+    );
+  });
+
+  test("is stable across repeated calls with the same input", () => {
+    const caller = { name: "bodhi", scope: "*" };
+    expect(callerLabel(caller)).toBe(callerLabel(caller));
+  });
+});
+
+describe("callerLabel — undefined caller", () => {
+  test("returns a distinct, readable label for undefined", () => {
+    const label = callerLabel(undefined);
+    expect(label).toBe("anonymous");
+  });
+
+  test("returns the same label when called with no argument", () => {
+    expect(callerLabel()).toBe("anonymous");
+  });
+
+  test("undefined label never collides with a defined caller's label", () => {
+    const anonymousLabel = callerLabel(undefined);
+    expect(callerLabel({ name: "anonymous", scope: "*" })).not.toBe(
+      anonymousLabel,
+    );
+  });
+});
+
+describe("callerLabel — scope kind", () => {
+  test("appends the scope kind when given", () => {
+    expect(
+      callerLabel({ name: "svc", scope: "platform.read" }, "platform-read"),
+    ).toBe("svc (platform.read) [platform-read]");
+  });
+});

package/secret-env-vars.ts

@@ -0,0 +1,41 @@
+/**
+ * lib/secret-env-vars.ts
+ * Canonical list of well-known secret-shaped env var names used by the
+ * shipwright-agent framework. Shared by Sentry log/event scrubbing
+ * (lib/sentry.ts) and by admin's agent env storage (marks these keys as
+ * `secret` so they're masked in GET /agents/:id/envs responses).
+ */
+
+/** Secret-shaped env var names, redacted/masked wherever their value is currently set. */
+export const SECRET_ENV_VARS = [
+  "ANTHROPIC_API_KEY",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "GH_APP_PRIVATE_KEY",
+  "GH_APP_CLIENT_SECRET",
+  "GH_TOKEN",
+  "SLACK_BOT_TOKEN",
+  "SLACK_APP_TOKEN",
+  "SLACK_SIGNING_SECRET",
+  "SLACK_CLIENT_SECRET",
+  "SLACK_ADMIN_TOKEN",
+  "SHIPWRIGHT_AGENT_API_KEY",
+  "SHIPWRIGHT_TASK_STORE_TOKEN",
+  "SHIPWRIGHT_TASK_STORE_ADMIN_TOKEN",
+  "SHIPWRIGHT_CHAT_SERVICE_TOKEN",
+  "SHIPWRIGHT_CHAT_SERVICE_ADMIN_TOKEN",
+  "SHIPWRIGHT_ADMIN_API_KEYS",
+  "SHIPWRIGHT_SESSION_SECRET",
+  "SHIPWRIGHT_ENCRYPTION_KEY",
+  // VAPID private key for Web Push (RFC 8292). The PUBLIC key is NOT secret —
+  // it's sent to the browser — so only the private key is listed here.
+  "SHIPWRIGHT_ADMIN_VAPID_PRIVATE_KEY",
+  // Shared token the chat service presents to admin's push-notify webhook so
+  // an unauthenticated caller can't trigger notifications.
+  "SHIPWRIGHT_ADMIN_PUSH_WEBHOOK_TOKEN",
+  // Bearer token the chat service presents to admin's push-notify webhook
+  // when firing outbound reply notifications. Same shared-secret value as
+  // SHIPWRIGHT_ADMIN_PUSH_WEBHOOK_TOKEN in deployment, but a distinct env
+  // var name (chat-side vs. admin-side).
+  "SHIPWRIGHT_CHAT_PUSH_WEBHOOK_TOKEN",
+  "GOOGLE_CLIENT_SECRET",
+] as const;

package/secret-env-vars.unit.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import { SECRET_ENV_VARS } from "./secret-env-vars.ts";
+
+describe("SECRET_ENV_VARS", () => {
+  test("is a non-empty array", () => {
+    expect(Array.isArray(SECRET_ENV_VARS)).toBe(true);
+    expect(SECRET_ENV_VARS.length).toBeGreaterThan(0);
+  });
+
+  test("contains expected well-known secret env var names", () => {
+    const expectedEntries = [
+      "ANTHROPIC_API_KEY",
+      "CLAUDE_CODE_OAUTH_TOKEN",
+      "GH_APP_PRIVATE_KEY",
+      "GH_APP_CLIENT_SECRET",
+      "GH_TOKEN",
+      "SLACK_BOT_TOKEN",
+      "SLACK_APP_TOKEN",
+      "SLACK_SIGNING_SECRET",
+      "SLACK_CLIENT_SECRET",
+      "SLACK_ADMIN_TOKEN",
+      "SHIPWRIGHT_AGENT_API_KEY",
+      "SHIPWRIGHT_TASK_STORE_TOKEN",
+      "SHIPWRIGHT_TASK_STORE_ADMIN_TOKEN",
+      "SHIPWRIGHT_CHAT_SERVICE_TOKEN",
+      "SHIPWRIGHT_CHAT_SERVICE_ADMIN_TOKEN",
+      "SHIPWRIGHT_ADMIN_API_KEYS",
+      "SHIPWRIGHT_SESSION_SECRET",
+      "SHIPWRIGHT_ENCRYPTION_KEY",
+      "SHIPWRIGHT_ADMIN_VAPID_PRIVATE_KEY",
+      "SHIPWRIGHT_ADMIN_PUSH_WEBHOOK_TOKEN",
+      "SHIPWRIGHT_CHAT_PUSH_WEBHOOK_TOKEN",
+      "GOOGLE_CLIENT_SECRET",
+    ];
+
+    for (const entry of expectedEntries) {
+      expect(SECRET_ENV_VARS as readonly string[]).toContain(entry);
+    }
+  });
+
+  test("has exactly the expected number of entries (catches accidental additions/removals)", () => {
+    expect(SECRET_ENV_VARS.length).toBe(22);
+  });
+
+  test("every entry is a non-empty string", () => {
+    for (const entry of SECRET_ENV_VARS) {
+      expect(typeof entry).toBe("string");
+      expect(entry.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("every entry looks like an env var name (uppercase snake case)", () => {
+    for (const entry of SECRET_ENV_VARS) {
+      expect(entry).toMatch(/^[A-Z][A-Z0-9_]*$/);
+    }
+  });
+
+  test("has no duplicate entries", () => {
+    const uniqueEntries = new Set(SECRET_ENV_VARS);
+    expect(uniqueEntries.size).toBe(SECRET_ENV_VARS.length);
+  });
+});