@sema-agent/server 7.79.3 → 7.80.0

package/dist/http/routes/admin-drain.js

@@ -1,40 +1,41 @@
 import { sendJson, sendError } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
+import { assertNever } from "../route-ctx.js";
 export const ADMIN_DRAIN_PATH = "/v1/admin/drain";
 export const MAX_DRAIN_REASON_CHARS = 256;
 const OPERATOR_ONLY_MESSAGE = "drain declaration is operator-only: the caller principal is not in OPERATOR_PRINCIPALS (an empty list means NO one is an operator — configure it to enable this endpoint)";
-export async function handleAdminDrain(req, res, url, ctx) {
-    const miss = { fell: false };
-    await handleAdminDrainBody(req, res, url, ctx, miss);
-    return !miss.fell;
-}
-async function handleAdminDrainBody(req, res, url, ctx, miss) {
+export async function handleAdminDrain(req, res, match, ctx) {
     const { deps } = ctx;
-    const path = url.split("?")[0] ?? url;
-    if (req.method !== "POST" || path !== ADMIN_DRAIN_PATH) {
-        miss.fell = true;
-        return;
-    }
-    const principal = gatedPrincipal(req, deps.config);
-    if (deps.config.requirePrincipal && !principal) {
-        sendPrincipalRefusal(res, req, deps.config);
-        return;
-    }
-    if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
-        sendError(res, 403, "auth.operator_only", OPERATOR_ONLY_MESSAGE);
-        return;
-    }
-    const body = (await ctx.helpers.readJson(req));
-    const reason = body?.reason;
-    if (typeof reason !== "string" || reason.trim().length === 0 || reason.length > MAX_DRAIN_REASON_CHARS) {
-        sendError(res, 400, "request.field_invalid", `the drain reason is surfaced verbatim on the UNAUTHENTICATED /health endpoint (and in 503 draining bodies), so anyone who can reach this port can read it — do not put ticket ids, hostnames, or internal identifiers in it. body must be { reason: string }: a non-empty string of at most ${MAX_DRAIN_REASON_CHARS} characters`);
-        return;
-    }
-    if (!deps.drainState) {
-        sendError(res, 501, "capability.drain_state_required", "this deployment has no drain state wired (embedded host?) — the declared reason would have nowhere to surface");
-        return;
+    switch (match.decl.id) {
+        case "admin-drain": {
+            const principal = gatedPrincipal(req, deps.config);
+            if (deps.config.requirePrincipal && !principal) {
+                sendPrincipalRefusal(res, req, deps.config);
+                return;
+            }
+            if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
+                sendError(res, 403, "auth.operator_only", OPERATOR_ONLY_MESSAGE);
+                return;
+            }
+            const body = (await ctx.helpers.readJson(req));
+            const reason = body?.reason;
+            if (typeof reason !== "string" || reason.trim().length === 0 || reason.length > MAX_DRAIN_REASON_CHARS) {
+                sendError(res, 400, "request.field_invalid", `the drain reason is surfaced verbatim on the UNAUTHENTICATED /health endpoint (and in 503 draining bodies), so anyone who can reach this port can read it — do not put ticket ids, hostnames, or internal identifiers in it. body must be { reason: string }: a non-empty string of at most ${MAX_DRAIN_REASON_CHARS} characters`);
+                return;
+            }
+            if (!deps.drainState) {
+                sendError(res, 501, "capability.drain_state_required", "this deployment has no drain state wired (embedded host?) — the declared reason would have nowhere to surface");
+                return;
+            }
+            deps.drainState.reason = reason.trim();
+            sendJson(res, 200, { ok: true });
+            return;
+        }
+        default:
+            return assertNever(match.decl.id);
     }
-    deps.drainState.reason = reason.trim();
-    sendJson(res, 200, { ok: true });
 }
+export const ADMIN_DRAIN_ROUTES = [
+    { id: "admin-drain", path: ADMIN_DRAIN_PATH, methods: ["POST"] },
+];
 //# sourceMappingURL=admin-drain.js.map

package/dist/http/routes/admin-memory-optout.d.ts

@@ -40,9 +40,35 @@
  * prepare 即读到新 verdict(撤权后新声明具名拒;已声明会话 record wins,core 判,server 零码)。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { RouteCtx } from "../route-ctx.js";
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 export declare const ADMIN_MEMORY_OPTOUT_PATH = "/v1/admin/memory-optout";
 /** 带参口(`:principal`)⇒ 路由声明表(`http/route-table.ts`)里走 `pattern` 行,不是 `path` 行。 */
 export declare const ADMIN_MEMORY_OPTOUT_OVERRIDE_RE: RegExp;
-export declare function handleMemoryOptOut(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+export declare function handleMemoryOptOut(req: IncomingMessage, res: ServerResponse, match: RouteMatch<MemoryOptOutRouteId>, ctx: RouteCtx): Promise<void>;
+export declare const MEMORY_OPTOUT_ROUTES: readonly [{
+    readonly id: "memory-optout-grants-list";
+    readonly path: "/v1/admin/memory-optout";
+    readonly credentialGated: readonly ["GET"];
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "memory-optout-put-default";
+    readonly path: "/v1/admin/memory-optout";
+    readonly credentialGated: readonly ["PUT"];
+    readonly methods: readonly ["PUT"];
+}, {
+    readonly id: "memory-optout-put-override";
+    readonly pattern: RegExp;
+    readonly label: "/v1/admin/memory-optout/:principal";
+    readonly methods: readonly ["PUT"];
+}, {
+    readonly id: "memory-optout-delete-override";
+    readonly pattern: RegExp;
+    readonly label: "/v1/admin/memory-optout/:principal";
+    readonly methods: readonly ["DELETE"];
+}, {
+    readonly prefix: "/v1/admin/memory-optout/";
+    readonly credentialGated: readonly ["PUT", "DELETE"];
+}];
+/** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
+export type MemoryOptOutRouteId = RouteIdsOf<typeof MEMORY_OPTOUT_ROUTES>;
 //# sourceMappingURL=admin-memory-optout.d.ts.map

package/dist/http/routes/admin-memory-optout.js

@@ -1,41 +1,16 @@
 import { z } from "zod";
 import { sendJson, sendError } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
+import { assertNever } from "../route-ctx.js";
 import { memoryOptOutPrincipalShapeProblem } from "../../plugins/memory-optout-grant-store-sql.js";
 export const ADMIN_MEMORY_OPTOUT_PATH = "/v1/admin/memory-optout";
 export const ADMIN_MEMORY_OPTOUT_OVERRIDE_RE = /^\/v1\/admin\/memory-optout\/([^/]+)$/;
 const PutBodySchema = z.object({ allow: z.boolean(), note: z.string().min(1).max(500).optional() }).strict();
-export async function handleMemoryOptOut(req, res, url, ctx) {
-    const miss = { fell: false };
-    await handleBody(req, res, url, ctx, miss);
-    return !miss.fell;
-}
-function decideVerb(method, path, safeDecode) {
-    if (path === ADMIN_MEMORY_OPTOUT_PATH) {
-        if (method === "GET")
-            return { kind: "list" };
-        if (method === "PUT")
-            return { kind: "putDefault" };
-        return undefined;
-    }
-    const m = ADMIN_MEMORY_OPTOUT_OVERRIDE_RE.exec(path);
-    if (m === null)
-        return undefined;
-    if (method !== "PUT" && method !== "DELETE")
-        return undefined;
-    const principal = safeDecode(m[1]);
-    if (principal === null)
-        return "malformed";
-    return method === "PUT" ? { kind: "putOverride", principal } : { kind: "deleteOverride", principal };
-}
-async function handleBody(req, res, url, ctx, miss) {
+export async function handleMemoryOptOut(req, res, match, ctx) {
     const { deps } = ctx;
-    const path = url.split("?")[0] ?? url;
-    const verb = decideVerb(req.method, path, ctx.helpers.safeDecode);
-    if (verb === undefined) {
-        miss.fell = true;
-        return;
-    }
+    const target = match.decl.id === "memory-optout-grants-list" || match.decl.id === "memory-optout-put-default"
+        ? undefined
+        : ctx.helpers.safeDecode(match.params.principal);
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
         sendPrincipalRefusal(res, req, deps.config);
@@ -51,17 +26,22 @@ async function handleBody(req, res, url, ctx, miss) {
         sendError(res, 501, "capability.memory_optout_grant_required", "this deployment has no memory opt-out grant table: the per-principal memory-capture opt-out authorization store lives on a SQL store backend (DB_BACKEND=mysql|pg) and the local backend deliberately keeps no forgetting twin — wire a SQL backend to administer opt-out grants");
         return;
     }
-    if (verb === "malformed" || ((verb.kind === "putOverride" || verb.kind === "deleteOverride") && memoryOptOutPrincipalShapeProblem(verb.principal) !== undefined)) {
+    if (target !== undefined && (target === null || memoryOptOutPrincipalShapeProblem(target) !== undefined)) {
         sendError(res, 400, "request.path_malformed", "invalid memory opt-out grant principal — the path segment must percent-decode to a non-empty principal of at most 190 chars with no leading/trailing whitespace or control characters (the deployment default row is addressed by PUT on the collection root, not by a path segment)");
         return;
     }
-    if (verb.kind === "list") {
-        sendJson(res, 200, await store.list());
-        return;
-    }
-    if (verb.kind === "deleteOverride") {
-        sendJson(res, 200, { principal: verb.principal, deleted: await store.deleteOverride(verb.principal) });
-        return;
+    switch (match.decl.id) {
+        case "memory-optout-grants-list":
+            sendJson(res, 200, await store.list());
+            return;
+        case "memory-optout-delete-override":
+            sendJson(res, 200, { principal: target, deleted: await store.deleteOverride(target) });
+            return;
+        case "memory-optout-put-default":
+        case "memory-optout-put-override":
+            break;
+        default:
+            return assertNever(match.decl.id);
     }
     const parsed = PutBodySchema.safeParse(await ctx.helpers.readJson(req));
     if (!parsed.success) {
@@ -69,7 +49,14 @@ async function handleBody(req, res, url, ctx, miss) {
         return;
     }
     const input = { allow: parsed.data.allow, updatedBy: operator, ...(parsed.data.note !== undefined ? { note: parsed.data.note } : {}) };
-    const row = verb.kind === "putDefault" ? await store.putDefault(input) : await store.putOverride(verb.principal, input);
+    const row = match.decl.id === "memory-optout-put-default" ? await store.putDefault(input) : await store.putOverride(target, input);
     sendJson(res, 200, row);
 }
+export const MEMORY_OPTOUT_ROUTES = [
+    { id: "memory-optout-grants-list", path: ADMIN_MEMORY_OPTOUT_PATH, credentialGated: ["GET"], methods: ["GET"] },
+    { id: "memory-optout-put-default", path: ADMIN_MEMORY_OPTOUT_PATH, credentialGated: ["PUT"], methods: ["PUT"] },
+    { id: "memory-optout-put-override", pattern: /^\/v1\/admin\/memory-optout\/(?<principal>[^/]+)$/, label: "/v1/admin/memory-optout/:principal", methods: ["PUT"] },
+    { id: "memory-optout-delete-override", pattern: /^\/v1\/admin\/memory-optout\/(?<principal>[^/]+)$/, label: "/v1/admin/memory-optout/:principal", methods: ["DELETE"] },
+    { prefix: "/v1/admin/memory-optout/", credentialGated: ["PUT", "DELETE"] },
+];
 //# sourceMappingURL=admin-memory-optout.js.map

package/dist/http/routes/adoption.d.ts

@@ -21,6 +21,19 @@
  * 分层:本模块不值 import `server.ts`(那条边闭合运行时装载环),只 `import type`。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { RouteCtx } from "../route-ctx.js";
-export declare function handleAdoption(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
+export declare function handleAdoption(req: IncomingMessage, res: ServerResponse, match: RouteMatch<AdoptionRouteId>, ctx: RouteCtx): Promise<void>;
+export declare const ADOPTION_ROUTES: readonly [{
+    readonly id: "adoption-submit";
+    readonly path: "/v1/adoption";
+    readonly credentialGated: readonly ["POST"];
+    readonly methods: readonly ["POST"];
+}, {
+    readonly id: "adoption-detail";
+    readonly pattern: RegExp;
+    readonly label: "/v1/adoption/:id";
+    readonly methods: readonly ["GET"];
+}];
+/** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
+export type AdoptionRouteId = RouteIdsOf<typeof ADOPTION_ROUTES>;
 //# sourceMappingURL=adoption.d.ts.map

package/dist/http/routes/adoption.js

@@ -3,7 +3,7 @@ import { AdoptionRequestSchema } from "../../adoption/wire.js";
 import { checkAdoptionPrincipalShape, checkAdoptionWidths } from "../../adoption/plan.js";
 import { sendJson, sendError } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
-const ADOPTION_ID_RE = /^\/v1\/adoption\/([^/]+)$/;
+import { assertNever } from "../route-ctx.js";
 function sendOutcome(res, out) {
     switch (out.kind) {
         case "receipt":
@@ -38,20 +38,9 @@ function sendOutcome(res, out) {
 function assertNoRejectCodeLeft(unhandled) {
     throw new Error(`adoption: unhandled reject code ${JSON.stringify(unhandled)} — the wire contract's closed set and this switch have drifted apart`);
 }
-export async function handleAdoption(req, res, url, ctx) {
-    const miss = { fell: false };
-    await handleAdoptionBody(req, res, url, ctx, miss);
-    return !miss.fell;
-}
-async function handleAdoptionBody(req, res, url, ctx, miss) {
+export async function handleAdoption(req, res, match, ctx) {
     const { deps } = ctx;
     const { readJson } = ctx.helpers;
-    const isPost = req.method === "POST" && url === "/v1/adoption";
-    const idMatch = req.method === "GET" ? ADOPTION_ID_RE.exec(url) : null;
-    if (!isPost && !idMatch) {
-        miss.fell = true;
-        return;
-    }
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
         sendPrincipalRefusal(res, req, deps.config);
@@ -67,49 +56,60 @@ async function handleAdoptionBody(req, res, url, ctx, miss) {
         return;
     }
     const runner = createAdoptionRunner({ store, dialect: deps.backend?.kind === "pg" ? "pg" : "tidb", now: Date.now, logger: deps.logger });
-    if (idMatch) {
-        const id = ctx.helpers.safeDecode(idMatch[1]);
-        if (id === null) {
-            sendError(res, 400, "request.id_invalid", "invalid adoption id");
+    switch (match.decl.id) {
+        case "adoption-detail": {
+            const id = ctx.helpers.safeDecode(match.params.id);
+            if (id === null) {
+                sendError(res, 400, "request.id_invalid", "invalid adoption id");
+                return;
+            }
+            const out = await runner.get(id);
+            if (!out) {
+                sendError(res, 404, "not_found.adoption", "adoption not found");
+                return;
+            }
+            sendOutcome(res, out);
             return;
         }
-        const out = await runner.get(id);
-        if (!out) {
-            sendError(res, 404, "not_found.adoption", "adoption not found");
+        case "adoption-submit": {
+            let raw;
+            try {
+                raw = await readJson(req);
+            }
+            catch {
+                sendError(res, 400, "request.invalid_json", "invalid JSON body");
+                return;
+            }
+            const parsed = AdoptionRequestSchema.safeParse(raw);
+            if (!parsed.success) {
+                sendError(res, 400, "request.body_shape", "invalid adoption body — expected {fromPrincipal, toPrincipal} as non-empty strings");
+                return;
+            }
+            const { fromPrincipal, toPrincipal } = parsed.data;
+            const badShape = checkAdoptionPrincipalShape(fromPrincipal, toPrincipal);
+            if (badShape !== undefined) {
+                sendError(res, 400, "request.field_invalid", "the adoption principals are not in a portable identity shape", { detail: badShape });
+                return;
+            }
+            const tooWide = checkAdoptionWidths(fromPrincipal, toPrincipal);
+            if (tooWide !== undefined) {
+                sendError(res, 400, "request.field_invalid", "the adoption principals do not fit every identity column and derived key this adoption must write", { detail: tooWide });
+                return;
+            }
+            if (fromPrincipal === toPrincipal) {
+                sendError(res, 400, "request.field_invalid", "fromPrincipal and toPrincipal are the same — nothing to adopt");
+                return;
+            }
+            const out = await runner.start(fromPrincipal, toPrincipal);
+            sendOutcome(res, out);
             return;
         }
-        sendOutcome(res, out);
-        return;
-    }
-    let raw;
-    try {
-        raw = await readJson(req);
-    }
-    catch {
-        sendError(res, 400, "request.invalid_json", "invalid JSON body");
-        return;
-    }
-    const parsed = AdoptionRequestSchema.safeParse(raw);
-    if (!parsed.success) {
-        sendError(res, 400, "request.body_shape", "invalid adoption body — expected {fromPrincipal, toPrincipal} as non-empty strings");
-        return;
-    }
-    const { fromPrincipal, toPrincipal } = parsed.data;
-    const badShape = checkAdoptionPrincipalShape(fromPrincipal, toPrincipal);
-    if (badShape !== undefined) {
-        sendError(res, 400, "request.field_invalid", "the adoption principals are not in a portable identity shape", { detail: badShape });
-        return;
-    }
-    const tooWide = checkAdoptionWidths(fromPrincipal, toPrincipal);
-    if (tooWide !== undefined) {
-        sendError(res, 400, "request.field_invalid", "the adoption principals do not fit every identity column and derived key this adoption must write", { detail: tooWide });
-        return;
-    }
-    if (fromPrincipal === toPrincipal) {
-        sendError(res, 400, "request.field_invalid", "fromPrincipal and toPrincipal are the same — nothing to adopt");
-        return;
+        default:
+            return assertNever(match.decl.id);
     }
-    const out = await runner.start(fromPrincipal, toPrincipal);
-    sendOutcome(res, out);
 }
+export const ADOPTION_ROUTES = [
+    { id: "adoption-submit", path: "/v1/adoption", credentialGated: ["POST"], methods: ["POST"] },
+    { id: "adoption-detail", pattern: /^\/v1\/adoption\/(?<id>[^/]+)$/, label: "/v1/adoption/:id", methods: ["GET"] },
+];
 //# sourceMappingURL=adoption.js.map

package/dist/http/routes/agents-roster.d.ts

@@ -25,9 +25,16 @@
  *  · **能力位同源**:`capabilities.agentRoster` 与这里的 501 谓词是同一个 `deps.backgroundAgentStore`。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { RouteCtx } from "../route-ctx.js";
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 /** 名册窗的扫描上限(与 fleet 的终态窗同姿势:读面要有界)。窗满时回体带 `truncated:true`,
  *  `total` 于是诚实地是「窗内行数」而不是租户全量 —— 一个悄悄封顶的 total 比没有 total 更坏。 */
 export declare const ROSTER_SCAN_LIMIT = 500;
-export declare function handleAgentRoster(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+export declare function handleAgentRoster(req: IncomingMessage, res: ServerResponse, match: RouteMatch<AgentRosterRouteId>, ctx: RouteCtx): Promise<void>;
+export declare const AGENT_ROSTER_ROUTES: readonly [{
+    readonly id: "agents-roster";
+    readonly path: "/v1/agents/roster";
+    readonly methods: readonly ["GET"];
+}];
+/** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
+export type AgentRosterRouteId = RouteIdsOf<typeof AGENT_ROSTER_ROUTES>;
 //# sourceMappingURL=agents-roster.d.ts.map

package/dist/http/routes/agents-roster.js

@@ -1,4 +1,5 @@
 import { sendJson, sendError } from "../send.js";
+import { assertNever } from "../route-ctx.js";
 export const ROSTER_SCAN_LIMIT = 500;
 const ROSTER_STATUSES = ["running", "parked", "completed", "failed", "killed"];
 const ROSTER_KEY_DISPOSITION = {
@@ -48,91 +49,92 @@ function decodeCursor(raw) {
         return { ok: false, why: "cursor payload lacks a non-empty `handle`" };
     return { ok: true, cursor: { spawnedAt, handle } };
 }
-export async function handleAgentRoster(req, res, url, ctx) {
-    const miss = { fell: false };
-    await handleAgentRosterBody(req, res, url, ctx, miss);
-    return !miss.fell;
-}
-async function handleAgentRosterBody(req, res, url, ctx, miss) {
+export async function handleAgentRoster(req, res, match, ctx) {
     const { deps } = ctx;
     const { sessionOwnerScope } = ctx.helpers;
-    if (req.method !== "GET" || url !== "/v1/agents/roster") {
-        miss.fell = true;
-        return;
-    }
-    const { fleetWide, gateOwner } = sessionOwnerScope(req);
-    if (!fleetWide && gateOwner === null) {
-        sendError(res, 401, "auth.unauthorized", "unauthorized");
-        return;
-    }
-    const store = deps.backgroundAgentStore;
-    if (!store) {
-        sendError(res, 501, "capability.background_agent_store_required", "the agent roster requires a durable background-agent store (DB_BACKEND=mysql|pg, or the local file backend)");
-        return;
-    }
-    const q = new URL(req.url ?? "", "http://x").searchParams;
-    const limitRaw = q.get("limit");
-    if (limitRaw !== null && !(/^[0-9]+$/.test(limitRaw) && Number(limitRaw) >= 1 && Number(limitRaw) <= 100)) {
-        sendError(res, 400, "request.query_invalid", "limit must be a decimal integer in 1..100");
-        return;
-    }
-    const limit = limitRaw === null ? 20 : Number(limitRaw);
-    const beforeRaw = q.get("before");
-    const decoded = beforeRaw === null ? undefined : decodeCursor(beforeRaw);
-    if (decoded !== undefined && !decoded.ok) {
-        sendError(res, 400, "request.query_invalid", "before must be the opaque `nextBefore` cursor from a previous page of this endpoint", { detail: decoded.why });
-        return;
-    }
-    const cursor = decoded?.ok === true ? decoded.cursor : undefined;
-    const statusRaw = q.get("status");
-    if (statusRaw !== null && !ROSTER_STATUSES.includes(statusRaw)) {
-        sendError(res, 400, "request.query_invalid", `status must be one of: ${ROSTER_STATUSES.join(", ")}`);
-        return;
-    }
-    const status = statusRaw === null ? undefined : statusRaw;
-    let scope;
-    if (gateOwner !== null) {
-        scope = gateOwner;
-    }
-    else {
-        const raw = q.get("scope");
-        if (raw === null) {
-            scope = "default";
-        }
-        else {
-            const s = raw.trim();
-            if (s === "" || s.length > 190) {
-                sendError(res, 400, "request.query_invalid", "scope must be a non-blank tenant principal of at most 190 characters");
+    switch (match.decl.id) {
+        case "agents-roster": {
+            const { fleetWide, gateOwner } = sessionOwnerScope(req);
+            if (!fleetWide && gateOwner === null) {
+                sendError(res, 401, "auth.unauthorized", "unauthorized");
+                return;
+            }
+            const store = deps.backgroundAgentStore;
+            if (!store) {
+                sendError(res, 501, "capability.background_agent_store_required", "the agent roster requires a durable background-agent store (DB_BACKEND=mysql|pg, or the local file backend)");
+                return;
+            }
+            const q = new URLSearchParams(match.search);
+            const limitRaw = q.get("limit");
+            if (limitRaw !== null && !(/^[0-9]+$/.test(limitRaw) && Number(limitRaw) >= 1 && Number(limitRaw) <= 100)) {
+                sendError(res, 400, "request.query_invalid", "limit must be a decimal integer in 1..100");
+                return;
+            }
+            const limit = limitRaw === null ? 20 : Number(limitRaw);
+            const beforeRaw = q.get("before");
+            const decoded = beforeRaw === null ? undefined : decodeCursor(beforeRaw);
+            if (decoded !== undefined && !decoded.ok) {
+                sendError(res, 400, "request.query_invalid", "before must be the opaque `nextBefore` cursor from a previous page of this endpoint", { detail: decoded.why });
+                return;
+            }
+            const cursor = decoded?.ok === true ? decoded.cursor : undefined;
+            const statusRaw = q.get("status");
+            if (statusRaw !== null && !ROSTER_STATUSES.includes(statusRaw)) {
+                sendError(res, 400, "request.query_invalid", `status must be one of: ${ROSTER_STATUSES.join(", ")}`);
+                return;
+            }
+            const status = statusRaw === null ? undefined : statusRaw;
+            let scope;
+            if (gateOwner !== null) {
+                scope = gateOwner;
+            }
+            else {
+                const raw = q.get("scope");
+                if (raw === null) {
+                    scope = "default";
+                }
+                else {
+                    const s = raw.trim();
+                    if (s === "" || s.length > 190) {
+                        sendError(res, 400, "request.query_invalid", "scope must be a non-blank tenant principal of at most 190 characters");
+                        return;
+                    }
+                    scope = s;
+                }
+            }
+            const session = q.get("session");
+            if (session !== null && session.trim() === "") {
+                sendError(res, 400, "request.query_invalid", "session must be a non-blank session id when present");
                 return;
             }
-            scope = s;
+            const opts = { ...(status !== undefined ? { status } : {}), limit: ROSTER_SCAN_LIMIT + 1 };
+            const scanned = session !== null ? await store.listBySession(scope, session, opts) : await store.listByScope(scope, opts);
+            const truncated = scanned.length > ROSTER_SCAN_LIMIT;
+            let window = truncated ? scanned.slice(0, ROSTER_SCAN_LIMIT) : scanned;
+            if (truncated && window.length > 0 && scanned[ROSTER_SCAN_LIMIT].spawnedAt === window[window.length - 1].spawnedAt) {
+                const cut = window[window.length - 1].spawnedAt;
+                const clean = window.filter((r) => r.spawnedAt > cut);
+                if (clean.length > 0)
+                    window = clean;
+            }
+            const sorted = [...window].sort((a, b) => (b.spawnedAt - a.spawnedAt) || (a.handle < b.handle ? 1 : a.handle > b.handle ? -1 : 0));
+            const scoped = cursor === undefined ? sorted : sorted.filter((r) => r.spawnedAt < cursor.spawnedAt || (r.spawnedAt === cursor.spawnedAt && r.handle < cursor.handle));
+            const page = scoped.slice(0, limit);
+            const last = page[page.length - 1];
+            const hasMore = last !== undefined && scoped.length > page.length;
+            sendJson(res, 200, {
+                agents: page.map(projectRow),
+                total: window.length,
+                ...(truncated ? { truncated: true } : {}),
+                ...(hasMore ? { nextBefore: encodeCursor({ spawnedAt: last.spawnedAt, handle: last.handle }) } : {}),
+            });
+            return;
         }
+        default:
+            return assertNever(match.decl.id);
     }
-    const session = q.get("session");
-    if (session !== null && session.trim() === "") {
-        sendError(res, 400, "request.query_invalid", "session must be a non-blank session id when present");
-        return;
-    }
-    const opts = { ...(status !== undefined ? { status } : {}), limit: ROSTER_SCAN_LIMIT + 1 };
-    const scanned = session !== null ? await store.listBySession(scope, session, opts) : await store.listByScope(scope, opts);
-    const truncated = scanned.length > ROSTER_SCAN_LIMIT;
-    let window = truncated ? scanned.slice(0, ROSTER_SCAN_LIMIT) : scanned;
-    if (truncated && window.length > 0 && scanned[ROSTER_SCAN_LIMIT].spawnedAt === window[window.length - 1].spawnedAt) {
-        const cut = window[window.length - 1].spawnedAt;
-        const clean = window.filter((r) => r.spawnedAt > cut);
-        if (clean.length > 0)
-            window = clean;
-    }
-    const sorted = [...window].sort((a, b) => (b.spawnedAt - a.spawnedAt) || (a.handle < b.handle ? 1 : a.handle > b.handle ? -1 : 0));
-    const scoped = cursor === undefined ? sorted : sorted.filter((r) => r.spawnedAt < cursor.spawnedAt || (r.spawnedAt === cursor.spawnedAt && r.handle < cursor.handle));
-    const page = scoped.slice(0, limit);
-    const last = page[page.length - 1];
-    const hasMore = last !== undefined && scoped.length > page.length;
-    sendJson(res, 200, {
-        agents: page.map(projectRow),
-        total: window.length,
-        ...(truncated ? { truncated: true } : {}),
-        ...(hasMore ? { nextBefore: encodeCursor({ spawnedAt: last.spawnedAt, handle: last.handle }) } : {}),
-    });
 }
+export const AGENT_ROSTER_ROUTES = [
+    { id: "agents-roster", path: "/v1/agents/roster", methods: ["GET"] },
+];
 //# sourceMappingURL=agents-roster.js.map