@sema-agent/server 7.146.0 → 7.148.0

package/dist/http/routes/a2a-serve.js

@@ -6,25 +6,33 @@ import { HttpError } from "../../security.js";
 import { idemCallerOf, idemIdentityOf, idemKeyOf, inflightKeyOf } from "../idempotency.js";
 import { isRunExistsConflictBody, replayOfExistingRun } from "../submit-replay.js";
 import { isActiveRunConflictBody } from "../active-run-conflict.js";
-import { sendJson, sendError } from "../send.js";
+import { sendJson, sendError, sendHttpError } from "../send.js";
 import { admissionRefusalOf, readinessOf, sendBillableRefusal } from "../readiness.js";
-import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
-import { readOwnedRun } from "../owner-access.js";
+import { gatedPerson, gatedSubject, sendPrincipalRefusal, verifiedIdentitySource } from "../principal-gate.js";
+import { callerOf, protocolEntry, readVisibleRun, runRowAt } from "../owner-access.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { createDurableRun } from "./runs.js";
 export const A2A_PROTOCOL_VERSION = "1.0";
 export const A2A_VERSION_HEADER = "a2a-version";
-export function buildAgentCard(serve) {
+export function buildAgentCard(serve, reader, methods) {
     return {
         name: serve.name,
         ...(serve.description !== undefined ? { description: serve.description } : {}),
         protocolVersion: A2A_PROTOCOL_VERSION,
         url: serve.url,
         preferredTransport: "JSONRPC",
-        skills: serve.skills.map((s) => ({ id: s.id, name: s.name ?? s.id, ...(s.description !== undefined ? { description: s.description } : {}) })),
+        supportsAuthenticatedExtendedCard: methods.has(EXTENDED_CARD_METHOD),
+        skills: skillsOfferedTo(serve, reader).map((s) => ({ id: s.id, name: s.name ?? s.id, ...(s.description !== undefined ? { description: s.description } : {}) })),
     };
 }
+export const EXTENDED_CARD_METHOD = "agent/getAuthenticatedExtendedCard";
+export function skillsOfferedTo(serve, reader) {
+    return serve.skills.filter((s) => s.audience === undefined || (reader !== undefined && s.audience.includes(reader)));
+}
+function cardReaderOf(req, config) {
+    return verifiedIdentitySource(req, config) === undefined ? undefined : gatedPerson(req, config);
+}
 export async function handleA2aServe(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
@@ -35,7 +43,7 @@ export async function handleA2aServe(req, res, match, ctx) {
                 return;
             }
             res.setHeader(A2A_VERSION_HEADER, A2A_PROTOCOL_VERSION);
-            sendJson(res, 200, buildAgentCard(peer.serve));
+            sendJson(res, 200, buildAgentCard(peer.serve, undefined, A2A_METHODS));
             return;
         }
         default:
@@ -58,9 +66,7 @@ const A2A_STATE_BY_RUN_STATUS = {
     suspended: null,
     needs_review: null,
 };
-export function a2aStateForRun(run, stale) {
-    if (stale)
-        return "failed";
+export function a2aStateForRun(run) {
     if (isParkedRunStatus(run.status))
         return "input-required";
     const mapped = A2A_STATE_BY_RUN_STATUS[run.status];
@@ -91,8 +97,8 @@ function statusTextForRun(run, state) {
         return memo("errorMessage", runPlaneMessage);
     return undefined;
 }
-function taskFromRun(run, stale) {
-    const state = a2aStateForRun(run, stale);
+function taskFromRun(run) {
+    const state = a2aStateForRun(run);
     const text = statusTextForRun(run, state);
     return {
         kind: "task",
@@ -153,7 +159,8 @@ function objectiveFromParts(parts) {
     return objective;
 }
 const SKILL_METADATA_KEY = "sema.skillId";
-function skillFromMetadata(metadata, serve) {
+export const A2A_UNOFFERED_SKILL_MESSAGE = `unknown skill id — params.message.metadata["${SKILL_METADATA_KEY}"] does not name a skill offered to this caller; the skills a caller can name are the ones on the agent card it can read (the public card, or the authenticated extended card)`;
+function skillFromMetadata(metadata, serve, reader) {
     if (metadata === undefined || metadata === null)
         return undefined;
     const meta = asRecord(metadata, "params.message.metadata");
@@ -161,15 +168,14 @@ function skillFromMetadata(metadata, serve) {
     if (raw === undefined)
         return undefined;
     const id = asNonEmptyString(raw, `params.message.metadata["${SKILL_METADATA_KEY}"]`, MAX_SKILL_ID_CHARS);
-    const skill = serve.skills.find((s) => s.id === id);
+    const skill = skillsOfferedTo(serve, reader).find((s) => s.id === id);
     if (!skill)
-        throw new RpcError(JSONRPC_INVALID_PARAMS, `unknown skill id ${JSON.stringify(id)} — the skills this agent serves are the ones listed on its agent card`);
+        throw new RpcError(JSONRPC_INVALID_PARAMS, A2A_UNOFFERED_SKILL_MESSAGE);
     return skill;
 }
-function rpcErrorFromTypedFailure(err, skillId) {
-    const where = skillId !== undefined ? `skill ${JSON.stringify(skillId)}` : "this request";
+function rpcErrorFromTypedFailure(err) {
     if (err.status >= 400 && err.status < 500) {
-        return new RpcError(JSONRPC_INVALID_PARAMS, `the serving deployment refused this submission for ${where} (its configuration does not currently admit it); the operator's logs carry the reason`);
+        return new RpcError(JSONRPC_INVALID_PARAMS, "the serving deployment refused this request (its configuration does not currently admit it); the operator's logs carry the reason");
     }
     return new RpcError(JSONRPC_INTERNAL_ERROR, "internal error");
 }
@@ -191,9 +197,6 @@ function readBlocking(params) {
         throw new RpcError(JSONRPC_INVALID_PARAMS, "params.configuration.blocking must be a boolean");
     return c.blocking;
 }
-function isStaleRun(run, runStaleSec) {
-    return run.status === "running" && Date.now() - new Date(run.updatedAt).getTime() > runStaleSec * 1000;
-}
 async function waitForRun(ctx, store, res, taskId, budgetMs) {
     const { deps } = ctx;
     const deadline = Date.now() + budgetMs;
@@ -201,14 +204,15 @@ async function waitForRun(ctx, store, res, taskId, budgetMs) {
     for (;;) {
         let run;
         try {
-            run = (await store.getRun(taskId)) ?? null;
+            const raw = await store.getRun(taskId);
+            run = raw ? await runRowAt("run.a2a", store, raw) : null;
         }
         catch (e) {
             deps.logger?.warn?.("a2a_serve_wait_read_failed", { error: e?.message });
             return last;
         }
         last = run ?? last;
-        if (run && a2aStateForRun(run, isStaleRun(run, deps.config.runStaleSec)) !== "working")
+        if (run && a2aStateForRun(run) !== "working")
             return run;
         const left = deadline - Date.now();
         if (left <= 0)
@@ -231,7 +235,7 @@ async function handleMessageSend({ req, res, ctx, params, serve, runStore }) {
     const objective = objectiveFromParts(message.parts);
     const contextId = message.contextId === undefined ? undefined : asString(message.contextId, "params.message.contextId");
     const messageId = asNonEmptyString(message.messageId, "params.message.messageId", MAX_MESSAGE_ID_CHARS);
-    const skill = skillFromMetadata(message.metadata, serve);
+    const skill = skillFromMetadata(message.metadata, serve, cardReaderOf(req, deps.config));
     const skillId = skill?.id;
     const scenario = skill?.scenario;
     const blocking = readBlocking(params);
@@ -242,7 +246,7 @@ async function handleMessageSend({ req, res, ctx, params, serve, runStore }) {
         .update(contextId ?? "").update("\x1f")
         .update(skillId ?? "")
         .digest("hex");
-    const submitter = gatedPrincipal(req, deps.config);
+    const submitter = gatedSubject(req, deps.config);
     const idem = { key: idemKeyOf(fingerprint, caller, "run"), bodyFingerprint: fingerprint };
     const body = {
         objective,
@@ -251,9 +255,9 @@ async function handleMessageSend({ req, res, ctx, params, serve, runStore }) {
         ...(scenario !== undefined ? { scenario } : {}),
     };
     const keyed = (await runStore.getRunByIdem(idem.key).catch(() => undefined)) ?? (await runStore.getRun(body.taskId).catch(() => undefined));
-    const replay = keyed ? await replayOfExistingRun(keyed, { principal: submitter, clientTaskId: body.taskId, idem }, "durable", deps, runStore) : undefined;
+    const replay = keyed ? await replayOfExistingRun(keyed, { subject: submitter, clientTaskId: body.taskId, idem }, "durable", deps, runStore) : undefined;
     if (keyed && replay?.status === 202) {
-        return taskFromRun(keyed, isStaleRun(keyed, deps.config.runStaleSec));
+        return taskFromRun(await runRowAt("run.a2a", runStore, keyed));
     }
     const inflight = replay === undefined ? ctx.registry.idemCache.peek(inflightKeyOf(idem, "durable", body.taskId)) : undefined;
     let receipt;
@@ -273,8 +277,10 @@ async function handleMessageSend({ req, res, ctx, params, serve, runStore }) {
             typed = e;
         });
         if (!prepared) {
-            if (typed)
-                throw rpcErrorFromTypedFailure(typed, skillId);
+            if (typed) {
+                deps.logger?.warn?.("a2a_serve_submission_refused", { status: typed.status, ...(typed.code !== undefined ? { errorCode: typed.code } : {}) });
+                throw rpcErrorFromTypedFailure(typed);
+            }
             return undefined;
         }
         try {
@@ -294,7 +300,7 @@ async function handleMessageSend({ req, res, ctx, params, serve, runStore }) {
     const sessionId = receiptBody.sessionId;
     const run = await waitForRun(ctx, runStore, res, taskId, blocking ? serve.blockingWaitMs : 0);
     if (run)
-        return taskFromRun(run, isStaleRun(run, deps.config.runStaleSec));
+        return taskFromRun(run);
     return {
         kind: "task",
         id: taskId,
@@ -322,15 +328,19 @@ function durableIdempotencyTaskId(scope, messageId) {
 async function handleTasksGet({ req, ctx, params, runStore }) {
     const { deps } = ctx;
     const id = asNonEmptyString(params.id, "params.id", MAX_TASK_ID_CHARS);
-    const run = await readOwnedRun(deps.config, runStore, gatedPrincipal(req, deps.config), id, "owner");
+    const run = await readVisibleRun(protocolEntry(req, deps, "run.a2a", callerOf(req, deps)), runStore, id);
     if (!run)
         throw new RpcError(A2A_TASK_NOT_FOUND, A2A_TASK_NOT_FOUND_MESSAGE);
-    return taskFromRun(run, isStaleRun(run, deps.config.runStaleSec));
+    return taskFromRun(run);
 }
-const A2A_METHODS = {
-    "message/send": handleMessageSend,
-    "tasks/get": handleTasksGet,
-};
+async function handleExtendedCard({ req, ctx, serve }) {
+    return buildAgentCard(serve, cardReaderOf(req, ctx.deps.config), A2A_METHODS);
+}
+const A2A_METHODS = new Map([
+    ["message/send", handleMessageSend],
+    ["tasks/get", handleTasksGet],
+    [EXTENDED_CARD_METHOD, handleExtendedCard],
+]);
 export async function handleA2a(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
@@ -347,7 +357,18 @@ export async function handleA2a(req, res, match, ctx) {
     const { serve, runStore } = peer;
     const requestedVersion = req.headers[A2A_VERSION_HEADER];
     res.setHeader(A2A_VERSION_HEADER, A2A_PROTOCOL_VERSION);
-    if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
+    let a2aSubject;
+    try {
+        a2aSubject = gatedSubject(req, deps.config);
+    }
+    catch (e) {
+        if (!(e instanceof HttpError))
+            throw e;
+        deps.metrics?.inc("a2a_serve_rejected_total", { reason: "identity_refused" });
+        sendHttpError(res, e);
+        return;
+    }
+    if (deps.config.requirePrincipal && !a2aSubject) {
         deps.metrics?.inc("a2a_serve_rejected_total", { reason: "principal_required" });
         sendPrincipalRefusal(res, req, deps.config);
         return;
@@ -374,7 +395,7 @@ export async function handleA2a(req, res, match, ctx) {
         return;
     }
     const method = rpc.method;
-    const handler = A2A_METHODS[method];
+    const handler = A2A_METHODS.get(method);
     if (!handler) {
         deps.metrics?.inc("a2a_serve_rpc_total", { method: "(unknown)", outcome: "method_not_found" });
         deps.metrics?.inc("a2a_serve_rejected_total", { reason: "method_not_found" });

package/dist/http/routes/admin-config-refresh.js

@@ -1,5 +1,5 @@
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedPerson, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
 import * as facts from "../../capability-facts.js";
 import { assertNever } from "../route-ctx.js";
 export const ADMIN_CONFIG_REFRESH_PATH = "/v1/admin/config/refresh";
@@ -8,7 +8,7 @@ export async function handleAdminConfigRefresh(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
         case "admin-config-refresh": {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedPerson(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;

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

@@ -1,6 +1,6 @@
 import { DRAIN_ACTION_ID, readDrainRequest } from "@sema-agent/settings-schema/fleet";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedPerson, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
 import * as facts from "../../capability-facts.js";
 import { fleetScopeOf } from "../../config-types.js";
 import { drainIdentityMismatches } from "../../fleet/drain-entry.js";
@@ -12,7 +12,7 @@ export async function handleAdminDrain(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
         case "admin-drain": {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedPerson(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;

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

@@ -1,9 +1,10 @@
 import { z } from "zod";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedPerson, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { memoryOptOutPrincipalShapeProblem } from "../../plugins/memory-optout-grant-store-sql.js";
+import { PRINCIPAL_MAX_BYTES } from "../../principal-shape.js";
 export const ADMIN_MEMORY_OPTOUT_PATH = "/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, match, ctx) {
@@ -11,7 +12,7 @@ export async function handleMemoryOptOut(req, res, match, ctx) {
     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);
+    const principal = gatedPerson(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
         sendPrincipalRefusal(res, req, deps.config);
         return;
@@ -40,7 +41,7 @@ export async function handleMemoryOptOut(req, res, match, ctx) {
     }
     const store = fact.store;
     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)");
+        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 ${PRINCIPAL_MAX_BYTES} UTF-8 bytes 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;
     }
     switch (match.decl.id) {

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

@@ -12,6 +12,9 @@
  *  · `adoption.destination_unrepresentable` (409):目的地身份装不进这次收编会**派生**出来的某个键
  *    (典型:memory 的 `proj:` 键 = 新 tenant 段 + 原有项目段后缀,合起来越过列宽)。与上一条分家的理由:
  *    运维的动作完全不同 —— 那条要去清理另一个 principal 的行,这条要换一个更短的目的地身份。
+ *  · `adoption.table_missing` (409):这个部署**接线了**某个可选存储面(记忆引擎 DB 后端 / 对象存储上的附件店),库上却没有它的表(表被人删了、或 boot 的建表没跑过)。
+ *    与前两条分家:那两条是**数据**事实、落永久终态;这条是**部署**事实 —— 弧不落终态(行停在 INTENT、零 UPDATE),补好表(重启一个副本,boot 会建缺的表)后**重发同一请求**即续。
+ *    **没接线的可选面不在此列**:缺省 file 记忆引擎 / 没配对象存储的部署上那些表本来就不存在,它们的腿不在回执里(`legs[]` 只列真跑的腿)。
  *  · `not_found.adoption` (404):operator 拿着一个不存在的 id 来读。
  *
  * 幂等:同参数重跑秒回**同一份** `AdoptionReceipt`(`immutableReport` 逐字节恒同 —— 它在 phase 6

package/dist/http/routes/adoption.js

@@ -4,7 +4,7 @@ import { checkAdoptionPrincipalShape, checkAdoptionWidths } from "../../adoption
 import { judgeAdoptionImportBinding, readAdoptionImportBody, runAdoptionImport } from "../../adoption/import.js";
 import { limitRefusal } from "../../limit-refusal.js";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedPerson, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 function sendOutcome(res, out) {
@@ -19,19 +19,23 @@ function sendOutcome(res, out) {
                 boundTo: out.boundTo,
             });
             return;
+        case "tables_missing":
+            sendError(res, 409, "adoption.table_missing", `this deployment wires stores whose tables are absent from the database (${out.tables.join(", ")}): nothing was migrated — restart a replica so its boot creates the missing tables, then resend the same request`, {
+                adoptionId: out.adoptionId,
+                tables: out.tables,
+            });
+            return;
         case "rejected":
             switch (out.code) {
                 case "adoption.destination_conflict":
-                    sendError(res, 409, "adoption.destination_conflict", "the destination principal already holds rows sharing a logical key with the source", {
+                    sendError(res, 409, "adoption.destination_conflict", `the destination principal already holds rows sharing a logical key with the source: ${out.detail}`, {
                         adoptionId: out.adoptionId,
-                        detail: out.detail,
                         conflicts: out.conflicts,
                     });
                     return;
                 case "adoption.destination_unrepresentable":
-                    sendError(res, 409, "adoption.destination_unrepresentable", "the destination principal does not fit every key this adoption would derive from it", {
+                    sendError(res, 409, "adoption.destination_unrepresentable", `the destination principal does not fit every key this adoption would derive from it: ${out.detail}`, {
                         adoptionId: out.adoptionId,
-                        detail: out.detail,
                     });
                     return;
             }
@@ -58,7 +62,7 @@ export async function handleAdoption(req, res, match, ctx) {
 async function operatorLane(req, res, id, params, ctx) {
     const { deps } = ctx;
     const { readJson } = ctx.helpers;
-    const principal = gatedPrincipal(req, deps.config);
+    const principal = gatedPerson(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
         sendPrincipalRefusal(res, req, deps.config);
         return;
@@ -85,7 +89,8 @@ async function operatorLane(req, res, id, params, ctx) {
         }
     }
     const store = fact.backend.adoptionLog();
-    const runner = createAdoptionRunner({ store, dialect: deps.backend?.kind === "pg" ? "pg" : "mysql", now: Date.now, logger: deps.logger });
+    const wiring = { memoryEngine: facts.memoryExport(deps).available, taskAttachment: deps.taskAttachmentStore !== undefined };
+    const runner = createAdoptionRunner({ store, dialect: deps.backend?.kind === "pg" ? "pg" : "mysql", now: Date.now, wiring, logger: deps.logger });
     switch (id) {
         case "adoption-detail": {
             const adoptionId = ctx.helpers.safeDecode(params.id);
@@ -111,12 +116,12 @@ async function operatorLane(req, res, id, params, ctx) {
             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 });
+                sendError(res, 400, "request.field_invalid", `the adoption principals are not in a portable identity shape: ${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 });
+                sendError(res, 400, "request.field_invalid", `the adoption principals do not fit every identity column and derived key this adoption must write: ${tooWide}`);
                 return;
             }
             if (fromPrincipal === toPrincipal) {
@@ -124,6 +129,8 @@ async function operatorLane(req, res, id, params, ctx) {
                 return;
             }
             const out = await runner.start(fromPrincipal, toPrincipal);
+            if (out.kind === "receipt")
+                await deps.toolApproval?.followRowOwners();
             sendOutcome(res, out);
             return;
         }
@@ -135,7 +142,7 @@ async function sourceLane(req, res, params, ctx) {
     const { deps } = ctx;
     if (ctx.helpers.rateLimited(req, res))
         return;
-    const principal = gatedPrincipal(req, deps.config);
+    const principal = gatedPerson(req, deps.config);
     if (principal === undefined) {
         sendPrincipalRefusal(res, req, deps.config);
         return;

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

@@ -1,6 +1,10 @@
 import { chosenAgentName } from "@sema-agent/core";
 import { sendJson, sendError } from "../send.js";
-import { fleetViewOf, sendUnauthorized } from "../principal-gate.js";
+import { gatedSubject, sendUnauthorized } from "../principal-gate.js";
+import { PRINCIPAL_MAX_BYTES } from "../../principal-shape.js";
+import { partsOf } from "../../owner-brands.js";
+import { taskSpecIdentityOf } from "../../engine-identity.js";
+import { routeListFilter } from "../owner-access.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { backgroundAgentNameOf } from "../../background-agent-name.js";
@@ -63,7 +67,7 @@ export async function handleAgentRoster(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
         case "agents-roster": {
-            const { fleetWide, gateOwner } = fleetViewOf(req, deps, "read");
+            const { fleetWide, gateOwner } = routeListFilter(req, deps, match.decl.id);
             if (!fleetWide && gateOwner === null) {
                 sendUnauthorized(res, "identity");
                 return;
@@ -84,7 +88,7 @@ export async function handleAgentRoster(req, res, match, ctx) {
             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 });
+                sendError(res, 400, "request.query_invalid", `before must be the opaque \`nextBefore\` cursor from a previous page of this endpoint: ${decoded.why}`);
                 return;
             }
             const cursor = decoded?.ok === true ? decoded.cursor : undefined;
@@ -94,19 +98,21 @@ export async function handleAgentRoster(req, res, match, ctx) {
                 return;
             }
             const status = statusRaw === null ? undefined : statusRaw;
+            const subject = gatedSubject(req, deps.config);
+            const ownScope = taskSpecIdentityOf(subject === undefined ? undefined : partsOf(subject)).principal ?? "default";
             let scope;
             if (gateOwner !== null) {
-                scope = gateOwner;
+                scope = ownScope;
             }
             else {
                 const raw = q.get("scope");
                 if (raw === null) {
-                    scope = "default";
+                    scope = ownScope;
                 }
                 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");
+                    if (s === "" || Buffer.byteLength(s, "utf8") > PRINCIPAL_MAX_BYTES) {
+                        sendError(res, 400, "request.query_invalid", `scope must be a non-blank tenant principal of at most ${PRINCIPAL_MAX_BYTES} UTF-8 bytes (the principal length every identity column holds)`);
                         return;
                     }
                     scope = s;