@app-vitals/agent-admin 0.8.0 → 0.9.1

package/src/agents-api.ts

@@ -65,6 +65,7 @@ import type { AgentEnvService } from "./agent-envs.ts";
 import type { AgentGitHubInstallationsService } from "./agent-github-installations.ts";
 import type { AgentMemberService } from "./agent-members.ts";
 import type { AgentPluginService } from "./agent-plugins.ts";
+import { resolveSpecialty } from "./agent-specialty.ts";
 import {
   type AgentProvisioner,
   hasPerAgentIdentity,
@@ -411,6 +412,8 @@ const GetAgentResultSchema = z
     patchAuthorAllowlist: z.array(z.string()),
     restrictSlackToMembers: z.boolean(),
     typeName: z.string(),
+    /** AGR-6.1: specialty (specialty ?? typeName); additive next to typeName. */
+    specialty: z.string(),
     /** COS-49.1: the pod ServiceAccount; null when unset. */
     podServiceAccountName: z.string().nullable(),
     /** Owning account; null for unassigned agents (task-store maps null to its 'default' account). */
@@ -1905,7 +1908,7 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
         anthropicFederationRuleId: _r,
         k8sServiceAccountName: _k,
         ...summary
-      }) => summary,
+      }) => ({ ...summary, specialty: resolveSpecialty(summary) }),
     );
     if (c.get("isAdmin") === true || email === undefined) {
       return c.json(agents, 200);
@@ -2816,6 +2819,7 @@ function serializeAgent(
     patchAuthorAllowlist?: string[];
     restrictSlackToMembers?: boolean;
     typeName: string;
+    specialty?: string | null;
     accountId?: string | null;
     podServiceAccountName?: string | null;
     createdAt: Date;
@@ -2846,6 +2850,7 @@ function serializeAgent(
     patchAuthorAllowlist: agent.patchAuthorAllowlist ?? [],
     restrictSlackToMembers: agent.restrictSlackToMembers ?? false,
     typeName: agent.typeName,
+    specialty: resolveSpecialty(agent),
     accountId: agent.accountId ?? null,
     podServiceAccountName: agent.podServiceAccountName ?? null,
     createdAt: agent.createdAt.toISOString(),

package/src/agents.integration.test.ts

@@ -510,3 +510,93 @@ describeOrSkip("createAgent() — integration (real Postgres)", () => {
     });
   });
 });
+
+describeOrSkip("Agent.specialty — dual-write + fallback read (AGR-6.1)", () => {
+  let prisma: PrismaClient;
+  let agentService: AgentService;
+  const createdIds: string[] = [];
+
+  beforeEach(() => {
+    prisma = makePrisma();
+    agentService = new AgentService(prisma, fakeSpecialtyRegistry());
+  });
+
+  afterEach(async () => {
+    await prisma.agent.deleteMany({ where: { id: { in: createdIds } } });
+    createdIds.length = 0;
+    await prisma.$disconnect();
+  });
+
+  it("create() writes specialty and typeName with the same value", async () => {
+    const created = await agentService.create({
+      name: "Dual Write",
+      typeName: "coding",
+    });
+    createdIds.push(created.id);
+
+    const row = await prisma.agent.findUniqueOrThrow({
+      where: { id: created.id },
+    });
+    expect(row.typeName).toBe("coding");
+    expect(row.specialty).toBe("coding");
+    expect(created.typeName).toBe("coding");
+    expect(created.specialty).toBe("coding");
+  });
+
+  it("reads prefer specialty over typeName", async () => {
+    const created = await agentService.create({
+      name: "Prefers Specialty",
+      typeName: "coding",
+    });
+    createdIds.push(created.id);
+    await prisma.agent.update({
+      where: { id: created.id },
+      data: { specialty: "research" },
+    });
+
+    const detail = await agentService.getDetail(created.id);
+    expect(detail?.typeName).toBe("coding");
+    expect(detail?.specialty).toBe("research");
+    expect((await agentService.getSummary(created.id))?.specialty).toBe(
+      "research",
+    );
+    expect(
+      (await agentService.list()).find((a) => a.id === created.id)?.specialty,
+    ).toBe("research");
+  });
+
+  it("falls back to typeName when specialty is NULL (pre-migration row)", async () => {
+    const created = await agentService.create({
+      name: "Legacy Row",
+      typeName: "coding",
+    });
+    createdIds.push(created.id);
+    await prisma.agent.update({
+      where: { id: created.id },
+      data: { specialty: null },
+    });
+
+    const detail = await agentService.getDetail(created.id);
+    expect(detail?.specialty).toBe("coding");
+    expect((await agentService.getSummary(created.id))?.specialty).toBe(
+      "coding",
+    );
+    expect((await agentService.getById(created.id))?.specialty).toBe("coding");
+    expect((await agentService.listByIds([created.id]))[0]?.specialty).toBe(
+      "coding",
+    );
+  });
+
+  it("createAgent() leaves both columns populated", async () => {
+    const created = await agentService.create({ name: "No Type" });
+    createdIds.push(created.id);
+    const row = await prisma.agent.findUniqueOrThrow({
+      where: { id: created.id },
+    });
+    // typeName omitted: column default applies and specialty stays NULL,
+    // so the fallback read still yields the default.
+    expect(row.typeName).toBe("coding");
+    expect(row.specialty).toBeNull();
+    expect(created.specialty).toBe("coding");
+  });
+});

package/src/agents.ts

@@ -24,6 +24,7 @@ import {
   SpecialtyRegistry,
 } from "./specialty-manifest-loader.ts";
 import { ANTHROPIC_CREDENTIALS_BLOCKED_CODE } from "./anthropic-credential-guard.ts";
+import { resolveSpecialty, withResolvedSpecialty } from "./agent-specialty.ts";
 import type { PrismaTransactionClient } from "./prisma-tx.ts";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -54,6 +55,8 @@ export interface AgentRecord {
   slackId: string | null;
   selfHosted: boolean;
   typeName: string;
+  /** AGR-6.1: resolved specialty (specialty ?? typeName). */
+  specialty?: string;
   createdAt: Date;
   updatedAt: Date;
   /** Owning account (SSP-5.2 admin Account column); null for legacy agents. */
@@ -82,6 +85,8 @@ export interface AgentSummary extends Partial<AgentAnthropicIdentity> {
   name: string;
   selfHosted: boolean;
   typeName: string;
+  /** AGR-6.1: resolved specialty (specialty ?? typeName). */
+  specialty?: string;
   /** Owning account; null/absent for platform agents. */
   accountId?: string | null;
 }
@@ -98,6 +103,8 @@ export interface AgentDetail extends Partial<AgentAnthropicIdentity> {
   patchAuthorAllowlist: string[];
   restrictSlackToMembers: boolean;
   typeName: string;
+  /** AGR-6.1: resolved specialty (specialty ?? typeName). */
+  specialty?: string;
   /**
    * Owning account, null for unassigned (platform) agents. Optional here so
    * existing test doubles constructing a narrower AgentDetail literal don't
@@ -205,6 +212,8 @@ interface AgentIdAndRepos {
    * Optional for the same fixture-compat reason as trialExpiresAt.
    */
   typeName?: string;
+  /** AGR-6.1: resolved specialty (specialty ?? typeName). */
+  specialty?: string;
   /**
    * APM-1.5: the 6 agent-policy fields, read by the runtime GET /:id/config
    * route for direct passthrough. Required (not optional) since the Prisma
@@ -255,6 +264,7 @@ const SUMMARY_SELECT = {
   name: true,
   selfHosted: true,
   typeName: true,
+  specialty: true,
   accountId: true,
   ownerEmail: true,
   anthropicIdentityName: true,
@@ -274,6 +284,7 @@ const DETAIL_SELECT = {
   patchAuthorAllowlist: true,
   restrictSlackToMembers: true,
   typeName: true,
+  specialty: true,
   accountId: true,
   createdAt: true,
   updatedAt: true,
@@ -327,7 +338,9 @@ export class AgentService {
         name: input.name,
         slackId: input.slackId ?? null,
         selfHosted: input.selfHosted ?? false,
-        ...(input.typeName !== undefined ? { typeName: input.typeName } : {}),
+        ...(input.typeName !== undefined
+          ? { typeName: input.typeName, specialty: input.typeName }
+          : {}),
         ...(input.repos !== undefined ? { repos: input.repos } : {}),
         ...(input.reviewAuthorAllowlist !== undefined
           ? { reviewAuthorAllowlist: input.reviewAuthorAllowlist }
@@ -348,10 +361,10 @@ export class AgentService {
     });
     const missingRequiredEnv = await this.computeMissingRequiredEnv(
       row.id,
-      row.typeName,
+      resolveSpecialty(row),
       client,
     );
-    return { ...row, missingRequiredEnv };
+    return { ...withResolvedSpecialty(row), missingRequiredEnv };
   }
 
   /**
@@ -385,10 +398,11 @@ export class AgentService {
    * List all agents (id + name + selfHosted + typeName), ordered by name asc.
    */
   async list(): Promise<AgentSummary[]> {
-    return this.prisma.agent.findMany({
+    const rows = await this.prisma.agent.findMany({
       select: SUMMARY_SELECT,
       orderBy: { name: "asc" },
     });
+    return rows.map(withResolvedSpecialty);
   }
 
   /**
@@ -396,10 +410,11 @@ export class AgentService {
    * not found.
    */
   async getSummary(id: string): Promise<AgentSummary | null> {
-    return this.prisma.agent.findUnique({
+    const row = await this.prisma.agent.findUnique({
       where: { id },
       select: SUMMARY_SELECT,
     });
+    return row ? withResolvedSpecialty(row) : null;
   }
 
   /**
@@ -445,9 +460,9 @@ export class AgentService {
 
     const missingRequiredEnv = await this.computeMissingRequiredEnv(
       id,
-      row.typeName,
+      resolveSpecialty(row),
     );
-    return { ...row, missingRequiredEnv };
+    return { ...withResolvedSpecialty(row), missingRequiredEnv };
   }
 
   /**
@@ -516,9 +531,9 @@ export class AgentService {
     });
     const missingRequiredEnv = await this.computeMissingRequiredEnv(
       id,
-      row.typeName,
+      resolveSpecialty(row),
     );
-    return { ...row, missingRequiredEnv };
+    return { ...withResolvedSpecialty(row), missingRequiredEnv };
   }
 
   /**
@@ -539,6 +554,7 @@ export class AgentService {
         trialExpiresAt: true,
         selfHosted: true,
         typeName: true,
+        specialty: true,
         account: { select: { status: true } },
         autoPostReviews: true,
         allowSelfReview: true,
@@ -553,7 +569,11 @@ export class AgentService {
     const members = await this.agentMemberService.listByAgentId(id);
     const memberEmails = members.map((m) => m.email);
     const { account, ...rest } = row;
-    return { ...rest, memberEmails, accountStatus: account?.status ?? null };
+    return {
+      ...withResolvedSpecialty(rest),
+      memberEmails,
+      accountStatus: account?.status ?? null,
+    };
   }
 
   /**
@@ -563,7 +583,7 @@ export class AgentService {
    * order Prisma returns.
    */
   async listAll(): Promise<AgentRecord[]> {
-    return this.prisma.agent.findMany();
+    return (await this.prisma.agent.findMany()).map(withResolvedSpecialty);
   }
 
   /**
@@ -572,7 +592,10 @@ export class AgentService {
    * and agentNames-resolution on the tasks/PRs pages).
    */
   async listByIds(ids: string[]): Promise<AgentRecord[]> {
-    return this.prisma.agent.findMany({ where: { id: { in: ids } } });
+    const rows = await this.prisma.agent.findMany({
+      where: { id: { in: ids } },
+    });
+    return rows.map(withResolvedSpecialty);
   }
 
   /**
@@ -580,9 +603,10 @@ export class AgentService {
    * /admin/tasks agent-name filter.
    */
   async searchByName(query: string): Promise<AgentRecord[]> {
-    return this.prisma.agent.findMany({
+    const rows = await this.prisma.agent.findMany({
       where: { name: { contains: query, mode: "insensitive" } },
     });
+    return rows.map(withResolvedSpecialty);
   }
 
   /**
@@ -653,10 +677,10 @@ export class AgentService {
     });
     const missingRequiredEnv = await this.computeMissingRequiredEnv(
       id,
-      row.typeName,
+      resolveSpecialty(row),
       client,
     );
-    return { ...row, missingRequiredEnv };
+    return { ...withResolvedSpecialty(row), missingRequiredEnv };
   }
 }
 

package/src/agents.unit.test.ts

@@ -409,8 +409,20 @@ describe("AgentService.list", () => {
     const result = await service.list();
 
     expect(result).toEqual([
-      { id: "a2", name: "Alpha", selfHosted: true, typeName: "coding" },
-      { id: "a1", name: "Zeta", selfHosted: false, typeName: "coding" },
+      {
+        id: "a2",
+        name: "Alpha",
+        selfHosted: true,
+        typeName: "coding",
+        specialty: "coding",
+      },
+      {
+        id: "a1",
+        name: "Zeta",
+        selfHosted: false,
+        typeName: "coding",
+        specialty: "coding",
+      },
     ]);
   });
 
@@ -435,6 +447,7 @@ describe("AgentService.getSummary", () => {
       name: "Existing",
       selfHosted: true,
       typeName: "coding",
+      specialty: "coding",
     });
   });
 
@@ -475,6 +488,7 @@ describe("AgentService.getDetail", () => {
       patchAuthorAllowlist: [],
       restrictSlackToMembers: false,
       typeName: "coding",
+      specialty: "coding",
       createdAt: row.createdAt,
       updatedAt: row.updatedAt,
       missingRequiredEnv: [],
@@ -735,6 +749,7 @@ describe("AgentService.getById", () => {
       accountStatus: null,
       // ARD-6.1: getById() now selects typeName for the runtime config response.
       typeName: "coding",
+      specialty: "coding",
       selfHosted: false,
       // APM-1.5: getById() now selects these 6 policy fields too.
       autoPostReviews: true,
@@ -772,6 +787,7 @@ describe("AgentService.getById", () => {
       accountStatus: null,
       // ARD-6.1: getById() now selects typeName for the runtime config response.
       typeName: "coding",
+      specialty: "coding",
       selfHosted: false,
       // APM-1.5: getById() now selects these 6 policy fields too.
       autoPostReviews: true,
@@ -1040,6 +1056,7 @@ describe("AgentService.updateFields", () => {
       patchAuthorAllowlist: [],
       restrictSlackToMembers: false,
       typeName: "coding",
+      specialty: "coding",
       createdAt: row.createdAt,
       updatedAt: new Date("2024-01-02"),
       missingRequiredEnv: [],

package/src/api.ts

@@ -23,6 +23,7 @@ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
 import type { AgentCronJob } from "./agent-cron-jobs.ts";
 import type { AgentEnvBundle } from "./agent-envs.ts";
 import type { AgentTokenService } from "./agent-tokens.ts";
+import { resolveSpecialty } from "./agent-specialty.ts";
 import { anthropicCredentialKeysIn } from "./anthropic-credential-guard.ts";
 import { type AdminApiKey, createAdminAuthMiddleware } from "./api-auth.ts";
 import {
@@ -71,6 +72,8 @@ export interface AgentConfigResponse {
    * the agent runtime treats an absent value as "coding".
    */
   typeName?: string;
+  /** AGR-6.1: specialty (specialty ?? typeName); additive, optional for doubles. */
+  specialty?: string;
   /**
    * PMC-1.1: phase -> subagentType (or null) map, covering all six pipeline
    * phases regardless of whether the agent has an explicit override row for
@@ -134,6 +137,7 @@ interface AgentServiceLike {
     /** SSP-8.3: owning account status; optional for pre-existing test doubles. */
     accountStatus?: string | null;
     typeName?: string;
+    specialty?: string | null;
     /** WIF-2.1: optional so pre-existing test doubles keep compiling; absent is treated as not self-hosted. */
     selfHosted?: boolean;
     /** APM-1.5: the 6 agent-policy fields, direct-passthrough into the response. */
@@ -346,6 +350,13 @@ export function createAgentRuntimeApp(deps: AgentRuntimeDeps): OpenAPIHono {
         : null,
       accountStatus: agent.accountStatus ?? null,
       typeName: agent.typeName,
+      specialty:
+        agent.typeName === undefined
+          ? undefined
+          : resolveSpecialty({
+              typeName: agent.typeName,
+              specialty: agent.specialty,
+            }),
       // Omitted entirely when no phase-methodology service was supplied
       // (platform-only admin, no coding extension).
       ...(agentPhaseMethodologyService ? { phaseMethodology } : {}),

package/src/chat.smoke.test.ts

@@ -413,9 +413,13 @@ function makeBaseDeps(overrides?: Partial<AdminUIDeps>): AdminUIDeps {
 describe("GET /admin/chat — auth gate", () => {
   it("returns 302 redirect to login without session cookie", async () => {
     const app = createAdminUIApp(makeBaseDeps());
-    const res = await app.request("/admin/chat");
+    const res = await app.request("/admin/chat", {
+      headers: { Accept: "text/html" },
+    });
     expect(res.status).toBe(302);
-    expect(res.headers.get("location")).toContain("/admin/login");
+    expect(res.headers.get("location")).toBe(
+      "/admin/login?returnTo=%2Fadmin%2Fchat",
+    );
   });
 });
 
@@ -616,14 +620,15 @@ describe("GET /admin/chat/:agentId/threads/:threadId — thread detail", () => {
     sessionCookie = await makeSessionCookie();
   });
 
-  it("returns 401 without session cookie", async () => {
+  it("redirects navigations to login with returnTo without session cookie", async () => {
     const chatClient = makeMockChatClient();
     const app = createAdminUIApp(makeBaseDeps({ chatClient }));
     const res = await app.request(
       `/admin/chat/${AGENT_ID}/threads/${THREAD_ID}`,
+      { headers: { "Sec-Fetch-Mode": "navigate" } },
     );
     expect(res.status).toBe(302);
-    expect(res.headers.get("location")).toContain("/admin/login");
+    expect(res.headers.get("location")).toContain("/admin/login?returnTo=");
   });
 
   it("returns 200 with messages when chatClient present", async () => {
@@ -1026,14 +1031,14 @@ describe("GET /admin/chat/:agentId/threads/:threadId/messages.json", () => {
     sessionCookie = await makeSessionCookie();
   });
 
-  it("returns 302 to login without session cookie", async () => {
+  it("returns 401 signed_out without session cookie", async () => {
     const chatClient = makeMockChatClient();
     const app = createAdminUIApp(makeBaseDeps({ chatClient }));
     const res = await app.request(
       `/admin/chat/${AGENT_ID}/threads/${THREAD_ID}/messages.json`,
     );
-    expect(res.status).toBe(302);
-    expect(res.headers.get("location")).toContain("/admin/login");
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: "signed_out" });
   });
 
   it("returns 200 JSON with messages array when chatClient present", async () => {
@@ -1148,7 +1153,7 @@ describe("POST /admin/chat/:agentId/threads/:threadId/messages.json", () => {
     sessionCookie = await makeSessionCookie();
   });
 
-  it("returns 302 to login without session cookie", async () => {
+  it("returns 401 signed_out without session cookie", async () => {
     const chatClient = makeMockChatClient();
     const app = createAdminUIApp(makeBaseDeps({ chatClient }));
     const res = await app.request(
@@ -1159,8 +1164,8 @@ describe("POST /admin/chat/:agentId/threads/:threadId/messages.json", () => {
         body: JSON.stringify({ body: "test message" }),
       },
     );
-    expect(res.status).toBe(302);
-    expect(res.headers.get("location")).toContain("/admin/login");
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: "signed_out" });
   });
 
   it("returns 200 JSON with message when chatClient present", async () => {
@@ -1237,7 +1242,7 @@ describe("POST /admin/chat/:agentId/threads/:threadId/messages/upload", () => {
     sessionCookie = await makeSessionCookie();
   });
 
-  it("returns 302 to login without session cookie", async () => {
+  it("returns 401 signed_out without session cookie", async () => {
     const chatClient = makeMockChatClient();
     const app = createAdminUIApp(makeBaseDeps({ chatClient }));
     const res = await app.request(
@@ -1248,8 +1253,8 @@ describe("POST /admin/chat/:agentId/threads/:threadId/messages/upload", () => {
         body: "body=test+message",
       },
     );
-    expect(res.status).toBe(302);
-    expect(res.headers.get("location")).toContain("/admin/login");
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: "signed_out" });
   });
 
   it("returns 201 JSON with message when chatClient present", async () => {
@@ -1368,14 +1373,14 @@ describe("GET /admin/chat/:agentId/threads/:threadId/messages/:messageId/attachm
     sessionCookie = await makeSessionCookie();
   });
 
-  it("returns 302 to login without session cookie", async () => {
+  it("returns 401 signed_out without session cookie", async () => {
     const chatClient = makeMockChatClient();
     const app = createAdminUIApp(makeBaseDeps({ chatClient }));
     const res = await app.request(
       `/admin/chat/${AGENT_ID}/threads/${THREAD_ID}/messages/msg-1/attachment`,
     );
-    expect(res.status).toBe(302);
-    expect(res.headers.get("location")).toContain("/admin/login");
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: "signed_out" });
   });
 
   it("streams bytes with an audio/* Content-Type for a .webm attachment", async () => {
@@ -1397,6 +1402,63 @@ describe("GET /admin/chat/:agentId/threads/:threadId/messages/:messageId/attachm
     expect(Array.from(body)).toEqual(Array.from(bytes));
   });
 
+  describe("Range support", () => {
+    const bytes = new Uint8Array(Array.from({ length: 100 }, (_, i) => i));
+    async function get(range?: string) {
+      const chatClient = makeMockChatClient({
+        getAttachment: async () => ({ bytes, filename: "reply.wav" }),
+      });
+      const app = createAdminUIApp(makeBaseDeps({ chatClient }));
+      return app.request(
+        `/admin/chat/${AGENT_ID}/threads/${THREAD_ID}/messages/msg-1/attachment`,
+        {
+          headers: {
+            Cookie: `admin_session=${sessionCookie}`,
+            ...(range ? { Range: range } : {}),
+          },
+        },
+      );
+    }
+
+    it("200 with Accept-Ranges and Content-Length when no Range is sent", async () => {
+      const res = await get();
+      expect(res.status).toBe(200);
+      expect(res.headers.get("accept-ranges")).toBe("bytes");
+      expect(res.headers.get("content-length")).toBe("100");
+      expect((await res.arrayBuffer()).byteLength).toBe(100);
+    });
+
+    it("206 with Content-Range for a mid-file range", async () => {
+      const res = await get("bytes=10-19");
+      expect(res.status).toBe(206);
+      expect(res.headers.get("content-range")).toBe("bytes 10-19/100");
+      expect(res.headers.get("accept-ranges")).toBe("bytes");
+      expect(res.headers.get("content-length")).toBe("10");
+      expect(Array.from(new Uint8Array(await res.arrayBuffer()))).toEqual(
+        Array.from(bytes.slice(10, 20)),
+      );
+    });
+
+    it("206 for an open-ended range", async () => {
+      const res = await get("bytes=90-");
+      expect(res.status).toBe(206);
+      expect(res.headers.get("content-range")).toBe("bytes 90-99/100");
+      expect((await res.arrayBuffer()).byteLength).toBe(10);
+    });
+
+    it("206 for a suffix range", async () => {
+      const res = await get("bytes=-5");
+      expect(res.status).toBe(206);
+      expect(res.headers.get("content-range")).toBe("bytes 95-99/100");
+    });
+
+    it("416 with Content-Range bytes */total when unsatisfiable", async () => {
+      const res = await get("bytes=500-600");
+      expect(res.status).toBe(416);
+      expect(res.headers.get("content-range")).toBe("bytes */100");
+    });
+  });
+
   it("returns 404 when the chat client reports no attachment", async () => {
     const chatClient = makeMockChatClient({ getAttachment: async () => null });
     const app = createAdminUIApp(makeBaseDeps({ chatClient }));

package/src/http-range.ts

@@ -0,0 +1,31 @@
+/**
+ * Single-range HTTP `Range` header parsing (RFC 9110 §14) for the attachment
+ * proxy. Pure — no I/O. Multi-range, malformed and non-`bytes` requests are
+ * ignored (`none`), which the caller answers with a normal 200.
+ */
+export type ByteRange =
+  | { kind: "none" }
+  | { kind: "range"; start: number; end: number }
+  | { kind: "unsatisfiable" };
+
+export function parseByteRange(
+  header: string | null | undefined,
+  size: number,
+): ByteRange {
+  if (!header) return { kind: "none" };
+  const m = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+  if (!m || (m[1] === "" && m[2] === "")) return { kind: "none" };
+
+  if (m[1] === "") {
+    // Suffix: the last n bytes.
+    const n = Number(m[2]);
+    if (n === 0 || size === 0) return { kind: "unsatisfiable" };
+    return { kind: "range", start: Math.max(0, size - n), end: size - 1 };
+  }
+
+  const start = Number(m[1]);
+  if (m[2] !== "" && Number(m[2]) < start) return { kind: "none" };
+  if (start >= size) return { kind: "unsatisfiable" };
+  const end = m[2] === "" ? size - 1 : Math.min(Number(m[2]), size - 1);
+  return { kind: "range", start, end };
+}