@app-vitals/agent-admin 0.8.0 → 0.9.1

package/src/admin-ui-pages.unit.test.ts

@@ -16,7 +16,6 @@ import {
   type MemberItem,
   type PluginItem,
   renderAddAnotherOrgAction,
-  AUTOPLAY_STORAGE_KEY_PREFIX,
   renderAgentDetailPage,
   renderAgentsPage,
   renderChatMessageBubble,
@@ -3497,6 +3496,88 @@ describe("renderChatMessageBubble — audio attachment vs. filename badge (VM-3.
   });
 });
 
+describe("renderChatMessageBubble — voice reply play control (COS-63.1)", () => {
+  const MSG: ChatMessage = {
+    id: "msg-63",
+    threadId: "thread-63",
+    role: "assistant",
+    body: "hello there",
+    createdAt: "2024-01-01T00:00:00.000Z",
+    claimedBy: null,
+    repliedAt: null,
+    tokens: null,
+    costUsd: null,
+    errorKind: null,
+    attachmentFilename: "1700000000000-response.wav",
+    attachmentSize: 10,
+  };
+  const URL63 =
+    "/admin/chat/agent-1/threads/thread-63/messages/msg-63/attachment";
+
+  test("assistant audio renders a 56px labelled play button, time, progress and a hidden audio", () => {
+    const html = renderChatMessageBubble(MSG, null, "agent-1");
+    expect(html).toContain("chat-voice-play");
+    expect(html).toContain('aria-label="Play"');
+    expect(html).toContain("chat-voice-time");
+    expect(html).toContain("chat-voice-progress");
+    expect(html).toMatch(/<audio[^>]*hidden[^>]*>/);
+    expect(html).not.toMatch(/<audio[^>]*controls/);
+    expect(html).toContain(URL63);
+  });
+
+  test("assistant transcript body is still rendered above the control", () => {
+    const html = renderChatMessageBubble(MSG, null, "agent-1");
+    expect(html.indexOf("hello there")).toBeLessThan(
+      html.indexOf("chat-voice-play"),
+    );
+  });
+
+  test("includes an error fallback with a download link and message", () => {
+    const html = renderChatMessageBubble(MSG, null, "agent-1");
+    expect(html).toContain("Could not play this reply");
+    expect(html).toMatch(
+      new RegExp(
+        `<a[^>]*download[^>]*href="${URL63}"|<a[^>]*href="${URL63}"[^>]*download`,
+      ),
+    );
+  });
+
+  test("user audio keeps native controls and no custom control", () => {
+    const html = renderChatMessageBubble(
+      { ...MSG, role: "user" },
+      null,
+      "agent-1",
+    );
+    expect(html).toMatch(/<audio[^>]*controls/);
+    expect(html).not.toContain("chat-voice-play");
+  });
+
+  test("thread page ships the 56px CSS and delegated click handler", () => {
+    const html = renderChatThreadPage(
+      "agent-1",
+      { id: "thread-63", title: "t" } as never,
+      [MSG],
+      "alice",
+    );
+    expect(html).toMatch(/\.chat-voice-play\s*\{[^}]*width:56px/);
+    expect(html).toContain("chat-voice-play");
+  });
+
+  test("chat stylesheet has no orphaned comment text before .chat-voice", () => {
+    const html = renderChatThreadPage(
+      "agent-1",
+      { id: "thread-63", title: "t" } as never,
+      [MSG],
+      "alice",
+    );
+    // A stray comment tail would swallow the next rule's selector.
+    expect(html).not.toContain("will speak on their own");
+    expect(html).toMatch(
+      /\}\s*\/\*[^*]*\*\/\s*\.chat-voice\s*\{[^}]*display:flex/,
+    );
+  });
+});
+
 describe("renderChatThreadPage — CFB-3.2 mobile drawer", () => {
   const THREAD: ChatThread = {
     id: "thread-abc",
@@ -4321,18 +4402,9 @@ describe("queue-activity links (AEP-3.6)", () => {
 
 describe("renderAgentDetailPage — signed commits toggle", () => {
   const render = (envVars: Record<string, string>) =>
-    renderAgentDetailPage(
-      AGENT,
-      envVars,
-      [],
-      [],
-      [],
-      [],
-      [],
-      USER_NAME,
-      true,
-      { timezone: "UTC" },
-    );
+    renderAgentDetailPage(AGENT, envVars, [], [], [], [], [], USER_NAME, true, {
+      timezone: "UTC",
+    });
 
   test("hidden when the agent has no GH_APP_ID", () => {
     expect(render({ SHIPWRIGHT_SIGNED_COMMITS: "1" })).not.toContain(
@@ -4354,211 +4426,3 @@ describe("renderAgentDetailPage — signed commits toggle", () => {
     expect(checkbox).toContain("checked");
   });
 });
-
-// ─── Auto-play voice replies toggle + phone mic sizing ───────────────────────
-
-describe("renderChatThreadPage — auto-play voice replies toggle", () => {
-  const THREAD: ChatThread = {
-    id: "thread-ap",
-    agentId: "agent-ap",
-    title: "Voice Thread",
-    memberId: null,
-    createdAt: "2024-01-01T00:00:00.000Z",
-    updatedAt: "2024-01-01T00:00:00.000Z",
-  };
-
-  test("renders an aria-pressed auto-play toggle right after the mic button", () => {
-    const html = renderChatThreadPage("agent-ap", THREAD, [], "alice");
-    const micIdx = html.indexOf('id="mic-btn"');
-    const toggleIdx = html.indexOf('id="autoplay-btn"');
-    const attachIdx = html.indexOf('id="attach-btn"');
-    expect(micIdx).toBeGreaterThan(-1);
-    expect(toggleIdx).toBeGreaterThan(micIdx);
-    expect(attachIdx).toBeGreaterThan(toggleIdx);
-    expect(html).toContain('aria-pressed="false"');
-    expect(html).toContain('aria-label="Auto-play voice replies"');
-  });
-
-  test("inline script carries the per-thread localStorage key prefix", () => {
-    const html = renderChatThreadPage("agent-ap", THREAD, [], "alice");
-    expect(html).toContain(JSON.stringify(AUTOPLAY_STORAGE_KEY_PREFIX));
-    expect(html).toContain("maybeAutoplay(newAssistantNodes)");
-    expect(html).toContain("data:audio/wav;base64,");
-  });
-
-  test("phone breakpoint grows the mic and toggle to 56px round buttons", () => {
-    const html = renderChatThreadPage("agent-ap", THREAD, [], "alice");
-    expect(html).toContain(
-      ".chat-composer-btn--mic, .chat-composer-btn--autoplay { width:56px;height:56px;padding:0;border-radius:50%",
-    );
-    expect(html).toContain("@keyframes chat-mic-pulse");
-    // Desktop rule stays the plain 44px text button.
-    expect(html).toContain(".chat-composer-btn--mic { padding:0 16px }");
-  });
-
-  // Runs the inline script against stub DOM/fetch/storage (no globals touched)
-  // and fires the first poll with one new message; returns the audio stub's
-  // play() call count.
-  async function bootAndPoll(opts: {
-    stored: string | null;
-    role: "assistant" | "user";
-    withAudio: boolean;
-    seededInDom?: boolean;
-  }): Promise<{ plays: number; storedKeys: string[] }> {
-    const html = renderChatThreadPage("agent-ap", THREAD, [], "alice");
-    const script = html.match(
-      /<script>\n\(function\(\) \{[\s\S]*?\n<\/script>/,
-    );
-    if (!script) throw new Error("inline chat script not found");
-    const code = script[0].replace(/^<script>/, "").replace(/<\/script>$/, "");
-
-    let plays = 0;
-    const audioStub = {
-      play() {
-        plays++;
-        return Promise.resolve();
-      },
-      addEventListener() {},
-      getAttribute: () => "/attachment",
-      currentSrc: "",
-      parentNode: null,
-    };
-    const makeEl = (): Record<string, unknown> => ({
-      style: {},
-      classList: { add() {}, remove() {}, toggle() {} },
-      addEventListener() {},
-      setAttribute() {},
-      getAttribute: () => null,
-      appendChild() {},
-      insertBefore() {},
-      querySelectorAll: () => [],
-      querySelector: () => null,
-    });
-    const bubbleNode = {
-      ...makeEl(),
-      querySelector: (sel: string) =>
-        sel === "audio" && opts.withAudio ? audioStub : null,
-    };
-    const seeded = opts.seededInDom
-      ? [{ getAttribute: () => "msg-new" }]
-      : [];
-    const container = {
-      ...makeEl(),
-      scrollTop: 0,
-      scrollHeight: 1000,
-      clientHeight: 400,
-      querySelectorAll: () => seeded,
-    };
-    const document = {
-      getElementById: (id: string) =>
-        id === "messages-container"
-          ? container
-          : id === "live-status-bubble"
-            ? null
-            : makeEl(),
-      createElement: (tag: string) =>
-        tag === "template"
-          ? { innerHTML: "", content: { firstChild: bubbleNode } }
-          : makeEl(),
-      querySelectorAll: () => [],
-    };
-    const storage = new Map<string, string>();
-    if (opts.stored !== null)
-      storage.set(`${AUTOPLAY_STORAGE_KEY_PREFIX}thread-ap`, opts.stored);
-    const window = {
-      addEventListener() {},
-      localStorage: {
-        getItem: (k: string) => storage.get(k) ?? null,
-        setItem: (k: string, v: string) => storage.set(k, v),
-        removeItem: (k: string) => storage.delete(k),
-      },
-    };
-    const fetchStub = () =>
-      Promise.resolve({
-        json: () =>
-          Promise.resolve({
-            messages: [
-              {
-                id: "msg-new",
-                role: opts.role,
-                body: "",
-                repliedAt: "2024-01-01T00:00:01.000Z",
-                bubbleHtml: "<div><audio></audio></div>",
-              },
-            ],
-          }),
-      });
-    const timers: Array<() => void> = [];
-    new Function(
-      "document",
-      "fetch",
-      "setTimeout",
-      "clearTimeout",
-      "setInterval",
-      "clearInterval",
-      "window",
-      code,
-    )(
-      document,
-      fetchStub,
-      (fn: () => void) => {
-        timers.push(fn);
-        return timers.length;
-      },
-      () => {},
-      () => 0,
-      () => {},
-      window,
-    );
-    timers[timers.length - 1]();
-    await new Promise((r) => setTimeout(r, 0));
-    await new Promise((r) => setTimeout(r, 0));
-    return { plays, storedKeys: [...storage.keys()] };
-  }
-
-  test("switch on + new assistant audio bubble -> plays it once", async () => {
-    const { plays } = await bootAndPoll({
-      stored: "1",
-      role: "assistant",
-      withAudio: true,
-    });
-    expect(plays).toBe(1);
-  });
-
-  test("switch off -> a new assistant audio bubble is not played", async () => {
-    const { plays } = await bootAndPoll({
-      stored: null,
-      role: "assistant",
-      withAudio: true,
-    });
-    expect(plays).toBe(0);
-  });
-
-  test("switch on but the new bubble is the user's own recording -> not played", async () => {
-    const { plays } = await bootAndPoll({
-      stored: "1",
-      role: "user",
-      withAudio: true,
-    });
-    expect(plays).toBe(0);
-  });
-
-  test("switch on but the message was already in the DOM at load -> never replayed", async () => {
-    const { plays } = await bootAndPoll({
-      stored: "1",
-      role: "assistant",
-      withAudio: true,
-      seededInDom: true,
-    });
-    expect(plays).toBe(0);
-  });
-
-  test("switch on but the assistant bubble has no audio -> no-op", async () => {
-    const { plays } = await bootAndPoll({
-      stored: "1",
-      role: "assistant",
-      withAudio: false,
-    });
-    expect(plays).toBe(0);
-  });
-});

package/src/admin-ui-push-test.ts

@@ -83,9 +83,13 @@ export function renderPushTestControl(): string {
     btn.addEventListener('click', function() {
       btn.disabled = true;
       status.textContent = 'Sending…';
-      fetch(${JSON.stringify(PUSH_TEST_PATH)}, { method: 'POST', credentials: 'same-origin' })
+      fetch(${JSON.stringify(PUSH_TEST_PATH)}, { method: 'POST', credentials: 'same-origin', headers: { 'Accept': 'application/json' } })
         .then(function(res) { return res.json().then(function(body) { return { status: res.status, body: body }; }); })
         .then(function(r) {
+          if (r.status === 401) {
+            window.location.href = '/admin/login?returnTo=' + encodeURIComponent(location.pathname + location.search);
+            return;
+          }
           if (r.status !== 200 || !r.body || !r.body.ok) {
             status.textContent = 'Push is not enabled on this server.';
           } else if (r.body.delivered === 0) {

package/src/admin-ui.smoke.test.ts

@@ -40,18 +40,81 @@ const TYPE = TYPE_MANIFEST.metadata.name;
 // ─── Auth redirect tests ──────────────────────────────────────────────────────
 
 describe("admin UI — unauthenticated redirects", () => {
-  it("unauthenticated GET /admin/agents redirects to /admin/login", async () => {
+  const NAV = { "Sec-Fetch-Mode": "navigate" };
+
+  it("unauthenticated GET /admin/agents redirects to /admin/login with returnTo", async () => {
     const app = createAdminUIApp(makeMockDeps());
-    const res = await app.request("/admin/agents");
+    const res = await app.request("/admin/agents", { headers: NAV });
     expect(res.status).toBe(302);
-    expect(res.headers.get("Location")).toBe("/admin/login");
+    expect(res.headers.get("Location")).toBe(
+      "/admin/login?returnTo=%2Fadmin%2Fagents",
+    );
   });
 
-  it("unauthenticated GET /admin/agents/:id redirects to /admin/login", async () => {
+  it("unauthenticated GET /admin/agents/:id redirects to /admin/login with returnTo", async () => {
     const app = createAdminUIApp(makeMockDeps());
-    const res = await app.request(`/admin/agents/${AGENT_ID}`);
+    const res = await app.request(`/admin/agents/${AGENT_ID}`, {
+      headers: { Accept: "text/html,application/xhtml+xml" },
+    });
     expect(res.status).toBe(302);
-    expect(res.headers.get("Location")).toBe("/admin/login");
+    expect(res.headers.get("Location")).toBe(
+      `/admin/login?returnTo=${encodeURIComponent(`/admin/agents/${AGENT_ID}`)}`,
+    );
+  });
+
+  it("navigation redirect preserves the query string in returnTo", async () => {
+    const app = createAdminUIApp(makeMockDeps());
+    const res = await app.request("/admin/agents?x=1&y=2", { headers: NAV });
+    expect(res.headers.get("Location")).toBe(
+      `/admin/login?returnTo=${encodeURIComponent("/admin/agents?x=1&y=2")}`,
+    );
+  });
+
+  it("unauthenticated fetch-style request gets 401 signed_out JSON", async () => {
+    const app = createAdminUIApp(makeMockDeps());
+    const res = await app.request("/admin/agents", {
+      headers: { Accept: "application/json", "Sec-Fetch-Mode": "cors" },
+    });
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: "signed_out" });
+  });
+
+  it("request with no navigation hints gets 401 signed_out JSON", async () => {
+    const app = createAdminUIApp(makeMockDeps());
+    const res = await app.request("/admin/agents");
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: "signed_out" });
+  });
+
+  it("unauthenticated POST fetch gets 401 signed_out JSON", async () => {
+    const app = createAdminUIApp(makeMockDeps());
+    const res = await app.request("/admin/agents", { method: "POST" });
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: "signed_out" });
+  });
+
+  it("returnTo is never an open redirect (protocol-relative path dropped)", async () => {
+    const app = createAdminUIApp(makeMockDeps());
+    const res = await app.request("//evil.com/x", { headers: NAV });
+    expect(res.headers.get("Location") ?? "").not.toContain("evil.com");
+  });
+});
+
+describe("admin UI — GET /admin/session.json", () => {
+  it("returns 200 {signedIn:true} with a valid session", async () => {
+    const app = createAdminUIApp(makeMockDeps());
+    const res = await app.request("/admin/session.json", {
+      headers: { Cookie: `admin_session=${await makeSessionCookie()}` },
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ signedIn: true });
+  });
+
+  it("returns 401 without a session", async () => {
+    const app = createAdminUIApp(makeMockDeps());
+    const res = await app.request("/admin/session.json");
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: "signed_out" });
   });
 });
 

package/src/admin-ui.ts

@@ -85,6 +85,7 @@ import {
   audioContentTypeForFilename,
   validateAttachment,
 } from "./attachment-validation.ts";
+import { parseByteRange } from "./http-range.ts";
 import {
   type CallerScopeResolver,
   memberOnlyCallerScopeResolver,
@@ -515,6 +516,28 @@ async function getSessionUser(
 
 // ─── Auth middleware ──────────────────────────────────────────────────────────
 
+/**
+ * Accepts a `returnTo` value only when it is a same-origin relative path:
+ * must start with a single "/", so protocol-relative (//evil.com), absolute
+ * (https://evil.com) and backslash-smuggled (/\\evil.com) values are dropped.
+ */
+export function validateReturnTo(
+  raw: string | undefined | null,
+): string | undefined {
+  return raw?.startsWith("/") && !raw.startsWith("//") && !raw.includes("\\")
+    ? raw
+    : undefined;
+}
+
+/** True for browser page navigations (as opposed to fetch/XHR calls). */
+function isNavigationRequest(c: Context): boolean {
+  if (c.req.header("Sec-Fetch-Mode") === "navigate") return true;
+  return (
+    c.req.method === "GET" &&
+    (c.req.header("Accept") ?? "").includes("text/html")
+  );
+}
+
 export function createUIAuthMiddleware(
   sessionSecret: string,
 ): MiddlewareHandler<AdminUIEnv> {
@@ -524,7 +547,20 @@ export function createUIAuthMiddleware(
       ? await getSessionUser(sessionToken, sessionSecret)
       : null;
     if (!user) {
-      return c.redirect("/admin/login", 302);
+      if (!isNavigationRequest(c)) {
+        return c.json({ error: "signed_out" }, 401);
+      }
+      const url = new URL(c.req.url);
+      const returnTo =
+        c.req.method === "GET"
+          ? validateReturnTo(url.pathname + url.search)
+          : undefined;
+      return c.redirect(
+        returnTo
+          ? `/admin/login?returnTo=${encodeURIComponent(returnTo)}`
+          : "/admin/login",
+        302,
+      );
     }
     c.set("userEmail", user.email);
     c.set("isAdmin", user.isAdmin);
@@ -861,10 +897,7 @@ export function createAdminUIApp(deps: AdminUIDeps): Hono<AdminUIEnv> {
       path: "/",
     });
     // Redirect to returnTo if it's a valid same-origin relative path, otherwise default.
-    const destination =
-      returnTo?.startsWith("/") && !returnTo.startsWith("//")
-        ? returnTo
-        : "/admin/agents";
+    const destination = validateReturnTo(returnTo) ?? "/admin/agents";
     return c.redirect(destination, 302);
   }
 
@@ -880,10 +913,7 @@ export function createAdminUIApp(deps: AdminUIDeps): Hono<AdminUIEnv> {
     const nonce = crypto.randomUUID();
 
     const rawReturnTo = c.req.query("returnTo");
-    const returnTo =
-      rawReturnTo?.startsWith("/") && !rawReturnTo.startsWith("//")
-        ? rawReturnTo
-        : undefined;
+    const returnTo = validateReturnTo(rawReturnTo);
 
     const oauthState = JSON.stringify({ nonce, returnTo });
     setCookie(c, OAUTH_STATE_COOKIE, oauthState, {
@@ -999,6 +1029,12 @@ export function createAdminUIApp(deps: AdminUIDeps): Hono<AdminUIEnv> {
     }
   });
 
+  // Cheap signed-in probe for client JS (a 401 {error:"signed_out"} from
+  // requireAuth means the session is gone).
+  app.get("/admin/session.json", requireAuth, (c) =>
+    c.json({ signedIn: true }),
+  );
+
   app.get("/admin/login", (c) => {
     const error = c.req.query("error") ?? undefined;
     const returnTo = c.req.query("returnTo") ?? undefined;
@@ -3349,9 +3385,34 @@ export function createAdminUIApp(deps: AdminUIDeps): Hono<AdminUIEnv> {
         // .slice() normalizes to Uint8Array<ArrayBuffer> — Hono's Data type
         // requires that exact generic, not the wider Uint8Array<ArrayBufferLike>
         // that new Uint8Array(await res.arrayBuffer()) produces.
-        return c.body(attachment.bytes.slice(), 200, {
+        const total = attachment.bytes.byteLength;
+        const baseHeaders = {
           "Content-Type": contentType,
           "Content-Disposition": `inline; filename="${attachment.filename.replace(/"/g, "")}"`,
+          "Accept-Ranges": "bytes",
+        };
+        // iOS Safari only plays media from servers that honour byte ranges.
+        const range = parseByteRange(c.req.header("Range"), total);
+        if (range.kind === "unsatisfiable") {
+          return c.body(null, 416, {
+            ...baseHeaders,
+            "Content-Range": `bytes */${total}`,
+          });
+        }
+        if (range.kind === "range") {
+          return c.body(
+            attachment.bytes.slice(range.start, range.end + 1),
+            206,
+            {
+              ...baseHeaders,
+              "Content-Range": `bytes ${range.start}-${range.end}/${total}`,
+              "Content-Length": String(range.end - range.start + 1),
+            },
+          );
+        }
+        return c.body(attachment.bytes.slice(), 200, {
+          ...baseHeaders,
+          "Content-Length": String(total),
         });
       } catch {
         return c.json({ error: "failed to fetch attachment" }, 500);

package/src/agent-cron-jobs.ts

@@ -17,6 +17,7 @@ import {
 } from "./specialty-manifest-loader.ts";
 import type { SpecialtyManifest } from "./specialty-registry.ts";
 import { type Clock, SystemClock } from "./clock.ts";
+import { resolveSpecialty } from "./agent-specialty.ts";
 import { NotFoundError, UnprocessableEntityError } from "./errors.ts";
 
 /**
@@ -488,15 +489,16 @@ export class AgentCronJobService {
     // than leaving its crons untouched.
     const agent = await this.prisma.agent.findUnique({
       where: { id: agentId },
-      select: { typeName: true },
+      select: { typeName: true, specialty: true },
     });
     if (!agent) {
       throw new NotFoundError(`agent ${agentId} not found`);
     }
-    const manifest = this.specialtyRegistry.tryGetManifest(agent.typeName);
+    const specialty = resolveSpecialty(agent);
+    const manifest = this.specialtyRegistry.tryGetManifest(specialty);
     if (!manifest) {
       const defaultName = resolveDefaultSpecialtyName();
-      if (agent.typeName === defaultName) {
+      if (specialty === defaultName) {
         throw missingDefaultSpecialtyError(
           defaultName,
           resolveSpecialtiesDir(),
@@ -504,7 +506,7 @@ export class AgentCronJobService {
         );
       }
       console.error(
-        `reconcileSystemCrons: no loadable manifest for typeName "${agent.typeName}" (agent ${agentId}) — leaving crons untouched`,
+        `reconcileSystemCrons: no loadable manifest for specialty "${specialty}" (agent ${agentId}) — leaving crons untouched`,
       );
       return { created: 0, updated: 0, deleted: 0 };
     }

package/src/agent-specialty.ts

@@ -0,0 +1,22 @@
+/**
+ * AGR-6.1: typeName -> specialty rename, ADD step. `Agent.specialty` is a
+ * nullable column written alongside `typeName`; reads prefer it and fall back
+ * to `typeName` for rows that predate the column. Nothing is retired yet.
+ */
+
+export interface SpecialtyBearingRow {
+  typeName: string;
+  specialty?: string | null;
+}
+
+/** The agent's specialty: the new column when set, else the legacy `typeName`. */
+export function resolveSpecialty(row: SpecialtyBearingRow): string {
+  return row.specialty ?? row.typeName;
+}
+
+/** Returns the row with `specialty` resolved to a non-null string. */
+export function withResolvedSpecialty<T extends SpecialtyBearingRow>(
+  row: T,
+): Omit<T, "specialty"> & { specialty: string } {
+  return { ...row, specialty: resolveSpecialty(row) };
+}

package/src/agent-specialty.unit.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Unit tests for the AGR-6.1 specialty mapper (typeName -> specialty ADD step).
+ */
+
+import { describe, expect, it } from "bun:test";
+import { resolveSpecialty, withResolvedSpecialty } from "./agent-specialty.ts";
+
+describe("resolveSpecialty", () => {
+  it("prefers specialty when set", () => {
+    expect(
+      resolveSpecialty({ typeName: "coding", specialty: "research" }),
+    ).toBe("research");
+  });
+
+  it("falls back to typeName when specialty is null", () => {
+    expect(resolveSpecialty({ typeName: "coding", specialty: null })).toBe(
+      "coding",
+    );
+  });
+
+  it("falls back to typeName when specialty is absent", () => {
+    expect(resolveSpecialty({ typeName: "coding" })).toBe("coding");
+  });
+
+  it("does not treat an empty-string specialty as unset", () => {
+    expect(resolveSpecialty({ typeName: "coding", specialty: "" })).toBe("");
+  });
+});
+
+describe("withResolvedSpecialty", () => {
+  it("returns a copy with specialty resolved and typeName preserved", () => {
+    const row = { id: "a1", typeName: "coding", specialty: null };
+    const out = withResolvedSpecialty(row);
+    expect(out).toEqual({ id: "a1", typeName: "coding", specialty: "coding" });
+    expect(row.specialty).toBeNull();
+  });
+
+  it("keeps an explicit specialty", () => {
+    expect(
+      withResolvedSpecialty({ typeName: "coding", specialty: "research" }),
+    ).toEqual({ typeName: "coding", specialty: "research" });
+  });
+});

package/src/agents-api.smoke.test.ts

@@ -2349,6 +2349,7 @@ describe("admin API — POST /agents/reconcile", () => {
       name: "Regular Agent",
       selfHosted: false,
       typeName: "coding",
+      specialty: "coding",
     });
   });
 });