@app-vitals/agent-admin 0.8.0 → 0.9.0

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,
@@ -3349,9 +3350,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",
     });
   });
 });

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

@@ -1397,6 +1397,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 };
+}