@sealkeeper/schema 0.4.6 → 0.4.8

package/dist/api.js

@@ -3,14 +3,16 @@ import { AgentId } from './agent-id.js';
 import { AgentName } from './agent-name.js';
 import { base64urlDecode, base64urlEncode, utf8Decode, utf8Encode, } from './base64url.js';
 import { CredentialPayload, SealPayload } from './credential.js';
-import { BaseDimension, Dimension, TaskType } from './dimensions.js';
+import { AcceptedDimension, COMPETENCE_TYPES_MAX, Dimension, TaskType, } from './dimensions.js';
 import { Jws } from './envelope.js';
-import { Version } from './events.js';
+import { StoredVersion, Version } from './events.js';
+import { AgentFingerprint, Fingerprint } from './fingerprint.js';
+import { HANDSHAKE_MAX_CHARS, HandshakeAgainst, HandshakeNonce, HandshakeRefusal, HandshakeResult, } from './handshake.js';
 import { boundedJsonObject } from './json-shape.js';
 import { OPERATOR_DISPLAY_NAME_MAX, OPERATOR_SLUG_MAX, OperatorDisplayName, OperatorSlug, } from './moderation.js';
 import { Runtime } from './runtime.js';
 import { Level, Standing } from './standing.js';
-import { PublicVerificationSpec, Sha256Hex, ShownVerificationSpec, TaskOutcome, TaskState, VerificationSpec, } from './tasks.js';
+import { CheckMethod, Disclosure, PublicVerificationSpec, Sha256Hex, ShownVerificationSpec, TaskCategory, TaskInputRef, TaskOutcome, TaskOutputShape, TaskSize, TaskState, VerificationSpec, } from './tasks.js';
 export const MAX_EVENTS_PER_BATCH = 500;
 // The window an event's occurred_at must fall in for the API to take it, at
 // most this many days old and this many seconds ahead of the API clock.
@@ -112,7 +114,7 @@ export const AgentCounts = z.strictObject({
 export const AgentResponse = z.strictObject({
     id: AgentId,
     name: Name,
-    version: Version,
+    version: StoredVersion,
     operator: AgentOperator,
     createdAt: Timestamp,
     // True for an agent SealKeeper runs itself, such as the one that posts the
@@ -153,6 +155,13 @@ export const AgentResponse = z.strictObject({
     // by handle, left out of registration and rename for the same reason as
     // counts.
     avatarUrl: z.url().optional(),
+    // The agent's current fingerprint (VB-4), the one with the latest
+    // captured_at any of its signed requests carried, as its hash, when it
+    // was captured and each part's state, never a part hash. null when it
+    // has declared none. A second record beside version, never the scoring
+    // key. Sent by GET by id and GET by handle only, for the same reason as
+    // counts.
+    fingerprint: AgentFingerprint.nullable().optional(),
 });
 // Old handles keep resolving, as a redirect, for this many days after an
 // agent rename. The profile shows the old name for as long.
@@ -212,8 +221,6 @@ export const DeleteAgentBody = z.union([
     z.strictObject({ envelope: Jws.max(MAX_ENVELOPE_CHARS) }),
     z.strictObject({}),
 ]);
-// A GitHub login. Letters, digits and hyphens, at most 39 characters.
-export const GithubLogin = z.string().regex(/^[A-Za-z0-9-]{1,39}$/);
 // The slug half of a handle as a caller writes it, in a URL, a query or
 // tasks post --for. Letters, digits and hyphens, at most OPERATOR_SLUG_MAX.
 // Slugs are lowercase and the API lowercases this before it looks one up,
@@ -285,20 +292,21 @@ export const AgentsListQuery = z.strictObject({
     operator: HandleSlug.optional(),
 });
 export const TopScore = z.strictObject({
-    dimension: BaseDimension,
+    dimension: Dimension,
     value: z.number().min(0).max(1),
 });
 // One agent in the directory. lastSeenAt is the newest received_at of its
-// events, null when it has sent none. topScores holds at most two base trust
-// dimensions on the current version, highest first, only those with a value.
-// cost_latency is never one of them. verifiedTasks and seedTasks are the
+// events, null when it has sent none. topScores holds at most two trust
+// dimensions on the current version, base or competence category
+// (topDimensions), highest first, only those with a value. cost_latency is
+// never one of them. verifiedTasks and seedTasks are the
 // same counts as on AgentResponse. level and standing are as on
 // AgentResponse, left out until the current version has been scored.
 export const AgentSummary = z.strictObject({
     id: AgentId,
     name: Name,
     handle: AgentHandle,
-    version: Version,
+    version: StoredVersion,
     operator: OperatorRef,
     // True for an agent SealKeeper runs itself. See AgentResponse.
     operatedBySealKeeper: z.boolean(),
@@ -321,21 +329,18 @@ export const AgentsListResponse = z.strictObject({
     agents: z.array(AgentSummary),
     nextCursor: z.string().nullable(),
 });
-export const AgentCardResponse = z.looseObject({
-    name: z.string(),
-    capabilities: z.looseObject({
-        extensions: z.array(z.looseObject({
-            uri: z.string(),
-            description: z.string().optional(),
-            params: z.record(z.string(), z.unknown()).optional(),
-        })),
-    }),
-});
+// fingerprint is the signing agent's fingerprint as its CLI last computed
+// it (VB-4), a JWS signed by the same agent over FingerprintDeclaration in
+// ./fingerprint.ts. The API refuses one that does not verify, names
+// another agent or whose hash is not the hash of its parts, and keeps it
+// as the agent's current fingerprint when it was captured later than the
+// stored one. Optional, so a CLI from before it syncs unchanged.
 export const EventsBatchRequest = z.strictObject({
     envelopes: z
         .array(Jws.max(MAX_ENVELOPE_CHARS))
         .min(1)
         .max(MAX_EVENTS_PER_BATCH),
+    fingerprint: Jws.max(MAX_ENVELOPE_CHARS).optional(),
 });
 // accepted counts rows newly stored. duplicates counts events already stored
 // for this agent (same event_id), which are skipped, so a retry is safe.
@@ -372,6 +377,11 @@ export const TaskOrigin = z.enum(['manual', 'template', 'routine']);
 // poster gets 409. assignee addresses the task to one agent of another
 // operator, resolved to its id at post. Only that agent can claim it, and it
 // counts at reduced weight as evidence. Without it the task is open to all.
+//
+// The real task fields (RT-2) are optional. The API stores what the post
+// says, else what derivedTaskFields gives from the type and the spec, so an
+// older CLI posts without them. disclosure sealed and verdict_only are
+// reserved, and the API refuses them with 400 disclosure_reserved.
 export const PostTaskRequest = z.strictObject({
     taskId: z.uuid(),
     taskType: TaskType,
@@ -380,6 +390,52 @@ export const PostTaskRequest = z.strictObject({
     expiresAt: Timestamp.optional(),
     assignee: AgentRef.optional(),
     origin: TaskOrigin.optional(),
+    category: TaskCategory.optional(),
+    size: TaskSize.optional(),
+    disclosure: Disclosure.optional(),
+    inputRef: TaskInputRef.optional(),
+    outputShape: TaskOutputShape.optional(),
+});
+/*
+ * An adoption (RT-11, D-RT-2), the other payload POST /v1/tasks takes. The
+ * agent names a category and the API picks a candidate in it, a task with a
+ * known answer SealKeeper made from the shared templates, and posts it as
+ * the agent's own open template task. So the payload carries no task type,
+ * spec or verification, the spec reaches only the agent that adopted it,
+ * and the known answer never leaves the server. origin is template, the
+ * default, or routine for a routine run's adoption (RT-12), so an adopted
+ * task carries the same origin as any other post of its kind. taskId and
+ * expiresAt work as in PostTaskRequest.
+ */
+export const AdoptTaskRequest = z.strictObject({
+    taskId: z.uuid(),
+    category: TaskCategory,
+    expiresAt: Timestamp.optional(),
+    origin: z.enum(['template', 'routine']).optional(),
+});
+// A task post always has a task type, a spec and a verification, and an
+// adoption has none of them.
+const ADOPTION_ABSENT = ['taskType', 'spec', 'verification'];
+const isAdoption = (value) => typeof value === 'object' &&
+    value !== null &&
+    ADOPTION_ABSENT.every((key) => !Object.hasOwn(value, key));
+/*
+ * The payload POST /v1/tasks parses. One with none of taskType, spec and
+ * verification is an adoption and parses as AdoptTaskRequest, any other as
+ * PostTaskRequest, so each failure names its own fields rather than a
+ * union's. A transform that picks the schema, shown once. The issues of
+ * the schema it picked are copied onto this one, paths and all.
+ */
+export const PostTaskPayload = z.unknown().transform((value, ctx) => {
+    const parsed = isAdoption(value)
+        ? AdoptTaskRequest.safeParse(value)
+        : PostTaskRequest.safeParse(value);
+    if (parsed.success)
+        return parsed.data;
+    for (const issue of parsed.error.issues) {
+        ctx.addIssue({ ...issue, input: value });
+    }
+    return z.NEVER;
 });
 // The agent an addressed task is for, as it is now.
 export const TaskAssignee = z.strictObject({
@@ -389,6 +445,24 @@ export const TaskAssignee = z.strictObject({
     // from an API before runtimes parses.
     runtime: Runtime.optional(),
 });
+/*
+ * The real task fields (RT-1), on TaskResponse and TaskView alike. category,
+ * checkMethod, disclosure and size always have a value, and the other three
+ * are null when the task does not say. The API always sends all seven. Each
+ * is optional, so an answer from an API before them parses.
+ */
+const realTaskFields = {
+    category: TaskCategory.optional(),
+    checkMethod: CheckMethod.optional(),
+    disclosure: Disclosure.optional(),
+    size: TaskSize.optional(),
+    // UTF-8 bytes of the task's input.
+    inputBytes: z.number().int().min(0).nullable().optional(),
+    // A link to a public input the task reads.
+    inputRef: z.string().nullable().optional(),
+    // A short statement of what the answer looks like.
+    outputShape: z.string().nullable().optional(),
+};
 export const TaskResponse = z.strictObject({
     id: z.uuid(),
     posterAgentId: AgentId,
@@ -408,22 +482,58 @@ export const TaskResponse = z.strictObject({
     submittedAt: Timestamp.nullable(),
     verifiedAt: Timestamp.nullable(),
     expiresAt: Timestamp,
+    // When the poster of a counterparty task let its response time lapse and
+    // the claimant's success report stood, which verified the task (POST-4).
+    // Null otherwise. Optional so the CLI still parses an API from before it.
+    posterLapsedAt: Timestamp.nullable().optional(),
     // True when the seed agent posted the task, so a CLI tells seed tasks
     // apart without looking the poster up. A CLI reads an API from before it
     // as not saying.
     seed: z.boolean(),
+    ...realTaskFields,
+    // Where the post came from, manual when the poster's CLI did not say, so
+    // a routine finds other operators' template tasks (RT-8). The API always
+    // sends it. Optional so the CLI still parses an API from before it.
+    origin: TaskOrigin.optional(),
+    // The poster as it is now, in list answers only (GET /v1/tasks and POST
+    // /v1/tasks/open). level is its current version's level from the last
+    // scoring run, left out until it is scored, so a routine tells a poster
+    // at bronze or above without a lookup (RT-8). Optional so the CLI still
+    // parses an API from before it.
+    poster: z
+        .strictObject({
+        handle: AgentHandle,
+        level: Level.optional(),
+        operatedBySealKeeper: z.boolean(),
+    })
+        .optional(),
     // Present only in responses to the poster or the claimant.
     submission: z.string().optional(),
 });
 // Claim and submit payloads name the task they are for, and the server checks
 // it against the path. Without it a signed claim for one task could be
-// replayed against any other.
-export const ClaimTaskRequest = z.strictObject({ taskId: z.uuid() });
+// replayed against any other. origin is the claimant's, TaskOrigin above,
+// routine when the unattended daily routine claims, which waits out the
+// claim age threshold (RT-8). Absent means manual.
+//
+// fingerprint, on claim, submit and outcome, is the signing agent's
+// fingerprint as its CLI last computed it (VB-3), Fingerprint in
+// ./fingerprint.ts. The API stores it with the claim, replaces it with one
+// a submit declares, keeps it when a submit declares none, and keeps the
+// reporter's with each outcome report. It refuses one
+// whose hash is not the hash of its parts. Absent means not declared, as
+// from a CLI from before it.
+export const ClaimTaskRequest = z.strictObject({
+    taskId: z.uuid(),
+    origin: TaskOrigin.optional(),
+    fingerprint: Fingerprint.optional(),
+});
 export const SubmitTaskRequest = z.strictObject({
     taskId: z.uuid(),
     submission: z
         .string()
         .refine((text) => utf8Encode(JSON.stringify(text)).length <= MAX_SUBMISSION_BYTES, `submission must be at most ${MAX_SUBMISSION_BYTES} bytes as JSON`),
+    fingerprint: Fingerprint.optional(),
 });
 // Named for its task like claim and submit, checked against the path.
 // origin is the reporting side's, TaskOrigin above.
@@ -432,6 +542,7 @@ export const TaskOutcomeRequest = z.strictObject({
     outcome: TaskOutcome,
     evidenceHash: Sha256Hex.optional(),
     origin: TaskOrigin.optional(),
+    fingerprint: Fingerprint.optional(),
 });
 // POST /v1/tasks/:id/submission, the poster's signed read of its task with
 // the submission and both outcome reports. The public GET leaves the
@@ -474,7 +585,9 @@ const QueryFlag = z.union([
 // assignee is given. assignee keeps the tasks addressed to that agent, in
 // the state asked for. poster and claimant keep one agent's tasks on that
 // side. seed true keeps only the tasks the seed agent posted and false
-// leaves them out. Without these a caller reads one global page and a
+// leaves them out. origin keeps the tasks posted with that origin, so a
+// routine reads other operators' template tasks without paging past every
+// manual one (RT-8). Without these a caller reads one global page and a
 // flood of older tasks can hide the ones it wants (VOU-208).
 export const ListTasksQuery = z.strictObject({
     state: TaskState.default('open'),
@@ -483,8 +596,23 @@ export const ListTasksQuery = z.strictObject({
     poster: AgentId.optional(),
     claimant: AgentId.optional(),
     seed: QueryFlag.optional(),
+    origin: TaskOrigin.optional(),
+    limit: Limit,
+    cursor: TasksCursorParam.optional(),
+});
+// POST /v1/tasks/open, the open pool as the signing agent sees it
+// (VOU-200). The same page as GET /v1/tasks?state=open with these filters,
+// less the tasks this agent is barred from after its failed submits. Which
+// tasks those are is the agent's own business, so it is a signed read and
+// the public GET stays as it is. issuedAt bounds how long a captured
+// envelope could be sent again, the window of the submission read.
+export const OpenTasksRequest = z.strictObject({
+    taskType: TaskType.optional(),
+    seed: z.boolean().optional(),
+    origin: TaskOrigin.optional(),
     limit: Limit,
     cursor: TasksCursorParam.optional(),
+    issuedAt: Timestamp,
 });
 // nextCursor is null on the last page.
 export const ListTasksResponse = z.strictObject({
@@ -499,6 +627,7 @@ export const ListTasksResponse = z.strictObject({
 // with their assignee.
 export const TaskBoardQuery = z.strictObject({
     taskType: TaskType.optional(),
+    category: TaskCategory.optional(),
     limit: Limit,
     cursor: TasksCursorParam.optional(),
 });
@@ -511,6 +640,18 @@ export const AgentTasksQuery = z.strictObject({
     limit: Limit,
     cursor: TasksCursorParam.optional(),
 });
+// Why the issuer withholds a SEAL for cause, the classes of the SEAL
+// standard, section 6 (VOU-85), and why it voids a task's credit (COL-5).
+// The class is public, on the SEAL routes' 404, in the feed and on a
+// voided task. The detail never is. The agent_holds.reason and
+// task_voids.reason check constraints list the same values.
+export const HoldReason = z.enum([
+    'fraud',
+    'collusion',
+    'safety',
+    'operator_ban',
+    'key_compromise',
+]);
 // One side of a task, as it is now.
 export const TaskParty = z.strictObject({
     id: AgentId,
@@ -521,7 +662,9 @@ export const TaskParty = z.strictObject({
     // The level of the agent's current version from the last scoring run,
     // for the name line. Left out until the agent has been scored.
     level: Level.optional(),
-    // True for an agent SealKeeper runs itself, the seed agent.
+    // True for an agent SealKeeper runs itself, the seed agent that posts the
+    // seed tasks or the taker that completes template tasks nobody else took
+    // (TAKER-5). The taker is only ever a claimant.
     operatedBySealKeeper: z.boolean(),
 });
 export const TaskView = z.strictObject({
@@ -539,6 +682,7 @@ export const TaskView = z.strictObject({
     assignee: TaskParty.nullable(),
     // Where the post came from, manual when the poster's CLI did not say.
     origin: TaskOrigin,
+    ...realTaskFields,
     // The scoring rule. True when the poster is the seed agent or an agent of
     // another operator than the claimant, false when both sides share an
     // operator or the task is addressed and came past its operator pair's
@@ -550,8 +694,10 @@ export const TaskView = z.strictObject({
     // when countsForTrust is false. Null when countsForTrust is null.
     evidenceWeight: z.number().min(0).max(1).nullable(),
     // What the task adds to the claimant's counted evidence (VOU-139), after
-    // the daily ceiling and diminishing returns and times evidenceWeight. 0
-    // when countsForTrust is false, null when it is null.
+    // the daily ceiling and diminishing returns and times evidenceWeight, as
+    // the last scoring run computed it (VOU-216). 0 when countsForTrust is
+    // false, null when it is null, and null for a task verified since its
+    // claimant's last scoring run, until that run.
     counted: z.number().min(0).max(1).nullable(),
     // Why a task that counts adds less than its weight, or nothing.
     // daily_ceiling when COUNTED_EVIDENCE.dailyCeiling heavier, more valuable
@@ -562,6 +708,10 @@ export const TaskView = z.strictObject({
     countedNote: z
         .enum(['daily_ceiling', 'diminishing', 'outside_window'])
         .nullable(),
+    // The reason class of a void in force on the task (COL-5), which makes it
+    // weigh 0 and count for nothing on either side. Absent without one. Never
+    // the note. Optional so the web still reads an answer from an older API.
+    voided: HoldReason.optional(),
     postedAt: Timestamp,
     claimedAt: Timestamp.nullable(),
     submittedAt: Timestamp.nullable(),
@@ -596,15 +746,27 @@ export const RatingResponse = z.strictObject({
     value: RatingValue,
     raterScoreAtTime: z.number().min(0).max(1),
 });
+// One task type's competence under its category (RT-3), verified over
+// claimed for that type on the version's own signal. A breakdown for the
+// profile, never a dimension and never in a SEAL.
+export const CompetenceTypeScore = z.strictObject({
+    taskType: TaskType,
+    value: z.number().min(0).max(1),
+});
 // A base dimension with no row is still listed, with every field after
-// dimension null. Competence entries appear only where a row exists.
+// dimension null. Competence entries appear only where a row exists, one
+// per category. types is the per task type breakdown of a competence
+// entry, highest claimed first, at most COMPETENCE_TYPES_MAX. It is left
+// out on base entries and on a competence entry the version only
+// inherited, since a breakdown is never fabricated from no signal.
 export const ScoreEntry = z.strictObject({
-    version: Version,
+    version: StoredVersion,
     dimension: Dimension,
     value: z.number().min(0).max(1).nullable(),
     windowStart: Timestamp.nullable(),
     windowEnd: Timestamp.nullable(),
     computedAt: Timestamp.nullable(),
+    types: z.array(CompetenceTypeScore).max(COMPETENCE_TYPES_MAX).optional(),
 });
 // The agent's current version only.
 export const ScoreResponse = z.strictObject({
@@ -621,7 +783,7 @@ export const MeAgent = z.strictObject({
     name: Name,
     handle: AgentHandle,
     operator: OperatorRef,
-    version: Version,
+    version: StoredVersion,
     createdAt: Timestamp,
     lastSeenAt: Timestamp.nullable(),
     scores: ScoreResponse,
@@ -688,7 +850,7 @@ export const LeaderboardEntry = z.strictObject({
     name: Name,
     handle: AgentHandle,
     operator: OperatorRef,
-    version: Version,
+    version: StoredVersion,
     // What the agent runs in. The API always sends it. Optional so the web
     // still reads an answer from an older API.
     runtime: Runtime.optional(),
@@ -722,9 +884,17 @@ export const FeedKind = z.enum([
     'version_change',
     'level_change',
     'milestone',
+    // The issuer withheld the agent's SEAL for cause (VOU-85). Written when a
+    // hold is placed, one per agent it covers.
+    'refusal',
 ]);
-// The one flag code today. Two sides of a counterparty task disagreed.
-export const FeedFlagCode = z.enum(['outcome_disagreement']);
+// Why an agent was flagged. outcome_disagreement, the two sides of a
+// counterparty task disagreed. taker_failures, the SealKeeper taker failed
+// on TAKER_POSTER_FAILURES of the agent's tasks within
+// TAKER_POSTER_FAILURE_DAYS and skips its tasks for now (TAKER-3). Written
+// once per pause on the agent that posted them, with the task that paused
+// it. Nothing is voided.
+export const FeedFlagCode = z.enum(['outcome_disagreement', 'taker_failures']);
 // Milestones an agent passes once. Its first SEAL level above none, then
 // 100 and 1,000 verified tasks.
 export const FeedMilestone = z.enum([
@@ -739,7 +909,7 @@ const FeedAgent = {
     name: Name,
 };
 export const FeedPayloads = {
-    registration: z.strictObject({ ...FeedAgent, version: Version }),
+    registration: z.strictObject({ ...FeedAgent, version: StoredVersion }),
     task_verified: z.strictObject({
         ...FeedAgent,
         taskId: z.uuid(),
@@ -750,8 +920,9 @@ export const FeedPayloads = {
     }),
     score_change: z.strictObject({
         ...FeedAgent,
-        version: Version,
-        dimension: Dimension,
+        version: StoredVersion,
+        // Old items can name a competence task type (AcceptedDimension).
+        dimension: AcceptedDimension,
         // null when the dimension had no value before.
         old: z.number().min(0).max(1).nullable(),
         new: z.number().min(0).max(1),
@@ -765,24 +936,30 @@ export const FeedPayloads = {
     // version, beside the agent every item names.
     version_change: z.strictObject({
         ...FeedAgent,
-        old: Version,
-        new: Version,
+        old: StoredVersion,
+        new: StoredVersion,
     }),
     // The scoring run moved the level of the agent's current version, up or
     // down. The first move above none is a first_seal milestone instead.
     level_change: z.strictObject({
         ...FeedAgent,
-        version: Version,
+        version: StoredVersion,
         old: Level,
         new: Level,
     }),
     // level is the current version's level when the milestone was passed.
     milestone: z.strictObject({
         ...FeedAgent,
-        version: Version,
+        version: StoredVersion,
         milestone: FeedMilestone,
         level: Level,
     }),
+    // The SEAL is withheld for cause. The reason class only, as the SEAL
+    // standard's section 6 says, never the detail or the internal note.
+    refusal: z.strictObject({
+        ...FeedAgent,
+        reason: HoldReason,
+    }),
 };
 const feedItemOf = (kind) => z.strictObject({
     // The SSE event id. Ascending in insert order.
@@ -798,6 +975,10 @@ const feedItemOf = (kind) => z.strictObject({
     // API's answer. level is left out until the agent has been scored.
     runtime: Runtime.optional(),
     level: Level.optional(),
+    // True when the agent is one SealKeeper runs itself, so a task_verified
+    // item of the taker reads as completed by SealKeeper (TAKER-5). The API
+    // always sends it. Optional so the web reads an older API's answer.
+    operatedBySealKeeper: z.boolean().optional(),
     payload: FeedPayloads[kind],
     createdAt: Timestamp,
 });
@@ -809,6 +990,7 @@ export const FeedItem = z.discriminatedUnion('kind', [
     feedItemOf('version_change'),
     feedItemOf('level_change'),
     feedItemOf('milestone'),
+    feedItemOf('refusal'),
 ]);
 export const FEED_RECENT_MAX = 200;
 export const FeedRecentQuery = z.strictObject({
@@ -824,6 +1006,10 @@ export const StatsResponse = z.strictObject({
     agents: z.int().min(0),
     verifiedTasks: z.int().min(0),
     eventsLast24h: z.int().min(0),
+    // Tasks the SealKeeper taker completed in the last 24 hours, by
+    // verified_at (TAKER-3). 0 while no taker is configured. The API always
+    // sends it. Optional so the web still reads an older API's answer.
+    takerCompletions24h: z.int().min(0).optional(),
 });
 // GET /v1/check/:slug/:name. One call for a caller that is about to
 // delegate work and wants a yes or no on the agent's track record. Query
@@ -909,9 +1095,31 @@ export const SealWithheldResponse = z.strictObject({
     id: AgentId,
     dormant_days: z.int().min(0).nullable(),
 });
+// The same three routes while a hold is in force on the agent or its
+// operator (VOU-85). No SEAL is issued until the hold is lifted, and a SEAL
+// issued before runs out at its own expiry. reason is the class only.
+export const SealHeldResponse = z.strictObject({
+    error: z.strictObject({
+        code: z.literal('withheld'),
+        message: z.string(),
+    }),
+    id: AgentId,
+    reason: HoldReason,
+});
 // POST /v1/seal/verify. The route's body cap keeps the SEAL small, so the
-// string itself has no tighter limit here.
-export const SealVerifyRequest = z.strictObject({ seal: z.string() });
+// string itself has no tighter limit here. handshake is the agent's signed
+// handshake (VB-6, ./handshake.ts), checked beside the SEAL. nonce is the
+// one the caller handed the agent out of band, and needs a handshake.
+export const SealVerifyRequest = z
+    .strictObject({
+    seal: z.string(),
+    handshake: z.string().max(HANDSHAKE_MAX_CHARS).optional(),
+    nonce: HandshakeNonce.optional(),
+})
+    .refine((b) => b.nonce === undefined || b.handshake !== undefined, {
+    message: 'nonce needs a handshake',
+    path: ['nonce'],
+});
 export const SealBrokenReason = z.enum([
     'malformed',
     'unknown_kid',
@@ -921,19 +1129,34 @@ export const SealBrokenReason = z.enum([
     'expired',
     'not_yet_valid',
 ]);
+// The handshake beside a valid SEAL. Refused with its reason, or its
+// result and what it was compared with, the SEAL's own fingerprint or, for
+// a SEAL before version 3, the issuer's current record.
+export const HandshakeAnswer = z.discriminatedUnion('valid', [
+    z.strictObject({
+        valid: z.literal(true),
+        result: HandshakeResult,
+        against: HandshakeAgainst,
+    }),
+    z.strictObject({ valid: z.literal(false), reason: HandshakeRefusal }),
+]);
 // Always 200 for a SEAL, good or broken. expiresIn is whole seconds left.
-// payload is version 1, or a legacy payload without ver before
-// LEGACY_UNTIL.
+// payload is version 1, 2 or 3. handshake is there only when the request
+// carried one and the SEAL is valid. A broken SEAL names no agent to check
+// it against.
 export const SealVerifyResponse = z.discriminatedUnion('valid', [
     z.strictObject({
         valid: z.literal(true),
         payload: SealPayload,
         expiresIn: z.int().min(1),
+        handshake: HandshakeAnswer.optional(),
     }),
     z.strictObject({ valid: z.literal(false), reason: SealBrokenReason }),
 ]);
 export const ScoreRunResponse = z.strictObject({
     scored: z.int().min(0),
+    // Feed items the run could not write after it committed. Zero normally.
+    feedFailed: z.int().min(0),
 });
 // POST /internal/seed/run. open is the seed agent's open tasks after the
 // run, added is how many this run posted.
@@ -941,6 +1164,41 @@ export const SeedRunResponse = z.strictObject({
     open: z.int().min(0),
     added: z.int().min(0),
 });
+// POST /internal/candidates/run (RT-11). open is the candidates nobody has
+// adopted after the run, added is how many this run wrote.
+export const CandidateRunResponse = z.strictObject({
+    open: z.int().min(0),
+    added: z.int().min(0),
+});
+// POST /internal/taker/run (TAKER-3). medianMinutes is the gate's median
+// time to claim over the last 24 hours, null when nothing was claimed. A
+// run that ran says which gate branch let it, no_claims, median above the
+// threshold, or waiting for an eligible open task past it, and counts its
+// tasks. completed were claimed, submitted and verified. skipped were
+// left alone with no claim and no failure, a spec the template cannot
+// solve, a poster at silver or above at claim time, or a task taken or
+// gone meanwhile. failed counts a failure for the poster, a stored check
+// that disagrees with the template's answer or a submit that failed.
+// flagged is the posters this run paused and flagged. A run that did not
+// run says why. keeping_up, the median is at or below the threshold and no
+// eligible task waits past it. daily_cap, TAKER_PER_DAY is reached for the
+// UTC day. locked, another run holds the lock.
+export const TakerRunResponse = z.discriminatedUnion('ran', [
+    z.strictObject({
+        ran: z.literal(true),
+        gate: z.enum(['no_claims', 'median', 'waiting']),
+        medianMinutes: z.number().min(0).nullable(),
+        completed: z.int().min(0),
+        skipped: z.int().min(0),
+        failed: z.int().min(0),
+        flagged: z.int().min(0),
+    }),
+    z.strictObject({
+        ran: z.literal(false),
+        reason: z.enum(['keeping_up', 'daily_cap', 'locked']),
+        medianMinutes: z.number().min(0).nullable(),
+    }),
+]);
 // GET /internal/metrics (VOU-146). days is the number of UTC days the
 // perDay rows cover, today included.
 export const INTERNAL_METRICS_MAX_DAYS = 90;
@@ -952,6 +1210,49 @@ export const InternalMetricsQuery = z.strictObject({
         .max(INTERNAL_METRICS_MAX_DAYS)
         .default(30),
 });
+// POST /internal/holds places a hold on one agent or on every agent of one
+// operator (VOU-85), exactly one of agentId and operatorId. note is for the
+// person who placed it, stored and never served or logged.
+export const HOLD_NOTE_MAX = 2000;
+export const HoldPlaceRequest = z
+    .strictObject({
+    agentId: AgentId.optional(),
+    operatorId: z.uuid().optional(),
+    reason: HoldReason,
+    note: z.string().min(1).max(HOLD_NOTE_MAX).optional(),
+})
+    .refine((r) => (r.agentId === undefined) !== (r.operatorId === undefined), 'exactly one of agentId and operatorId');
+// DELETE /internal/holds/:id lifts one.
+export const HoldParams = z.strictObject({ id: z.uuid() });
+// Both routes answer the hold without its note. agents is how many agents
+// it covers now, the agent itself or the operator's agents.
+export const HoldResponse = z.strictObject({
+    id: z.uuid(),
+    agentId: AgentId.nullable(),
+    operatorId: z.uuid().nullable(),
+    reason: HoldReason,
+    placedAt: Timestamp,
+    liftedAt: Timestamp.nullable(),
+    agents: z.int().min(0),
+});
+// POST /internal/voids voids one task's credit for cause (COL-5), with a
+// hold reason class. note is for the person who placed it, stored and never
+// served or logged.
+export const VoidPlaceRequest = z.strictObject({
+    taskId: z.uuid(),
+    reason: HoldReason,
+    note: z.string().min(1).max(HOLD_NOTE_MAX).optional(),
+});
+// DELETE /internal/voids/:id lifts one.
+export const VoidParams = z.strictObject({ id: z.uuid() });
+// Both routes answer the void without its note.
+export const VoidResponse = z.strictObject({
+    id: z.uuid(),
+    taskId: z.uuid(),
+    reason: HoldReason,
+    voidedAt: Timestamp,
+    liftedAt: Timestamp.nullable(),
+});
 // A count split by operator. sealkeeper is the operator that owns the seed
 // agent (SEED_AGENT_ID), others is everyone else.
 const OperatorSplit = z.strictObject({
@@ -983,6 +1284,18 @@ const MetricsDay = z.strictObject({
         tasksPosted: z.int().min(0),
         outcomes: z.int().min(0),
     }),
+    // The median minutes from post to first claim of the tasks with origin
+    // template or routine whose first claim fell that day, a released claim
+    // included and the taker's claims left out. null when there were none.
+    claimLatencyMedianMinutes: z.number().min(0).nullable(),
+    // The SealKeeper taker that day (TAKER-3). completions, tasks it claimed
+    // that were verified that day. flags, the taker_failures flags written
+    // that day, one per poster it paused. Both 0 while no taker is
+    // configured.
+    taker: z.strictObject({
+        completions: z.int().min(0),
+        flags: z.int().min(0),
+    }),
 });
 export const InternalMetricsResponse = z.strictObject({
     days: z.int().min(1),