@sealkeeper/schema 0.0.1 → 0.4.1

package/dist/api.js

@@ -0,0 +1,633 @@
+import { z } from 'zod';
+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 { Jws } from './envelope.js';
+import { Version } from './events.js';
+import { Level, Standing } from './standing.js';
+import { Sha256Hex, TaskOutcome, TaskState, VerificationSpec, } from './tasks.js';
+export const MAX_EVENTS_PER_BATCH = 500;
+export const MAX_ENVELOPE_CHARS = 4096;
+export const MAX_TASK_SPEC_BYTES = 16384;
+// Measured as the UTF-8 bytes of the submission's JSON encoding, which is
+// what gets signed. Counting chars would let escapes and multi-byte text
+// grow the envelope past its cap.
+export const MAX_SUBMISSION_BYTES = 65536;
+// Task writes carry a spec or a submission, so their envelopes are larger
+// than an event's. The largest submission payload is about 64K bytes of
+// JSON, which base64url encodes to about 88K chars. The largest post (spec
+// plus jsonSchema, 16K bytes each) is about 45K chars. Both fit.
+export const MAX_TASK_ENVELOPE_CHARS = 131072;
+// A task without expiresAt lives this long. A later expiresAt is capped.
+export const TASK_DEFAULT_TTL_HOURS = 24;
+export const TASK_MAX_TTL_DAYS = 7;
+const Timestamp = z.iso.datetime();
+const Limit = z.coerce.number().int().min(1).max(100).default(50);
+export const AgentParams = z.strictObject({ id: AgentId });
+export const TaskParams = z.strictObject({ id: z.uuid() });
+// The body of a signed task write.
+export const SignedTaskRequest = z.strictObject({
+    envelope: Jws.max(MAX_TASK_ENVELOPE_CHARS),
+});
+export const RegisterAgentRequest = z.strictObject({
+    publicKey: AgentId,
+    githubToken: z.string().min(1).max(256),
+    name: AgentName,
+    version: Version,
+});
+// A name as the API sends it. Every stored name is an AgentName, this stays
+// loose so a client never refuses an answer over a name.
+const Name = z.string().min(1).max(64);
+const Operator = z.strictObject({ login: z.string().min(1).max(39) });
+// login/name, as in alice/claude-code. Built by the API from the
+// operator's current login and the agent's current name, so clients show
+// and link it as they got it and never assemble it.
+export const AgentHandle = z.string().min(3).max(79);
+const Count = z.int().min(0);
+// What an agent has done, counted live. events is every signed event,
+// sessions the session.start events, toolCalls the tool.call events and
+// incidents the incident events. verifiedTasks counts tasks the agent claimed
+// that reached verified and that count toward trust, meaning the poster is
+// an agent of another operator or the seed agent. Same rule as scoring.
+// seedTasks is how many of those the seed agent posted. GET by id and GET
+// by handle both send it. Optional so an answer from an older API parses.
+// These are live, all time counts. The standing counts on the same answer
+// are the scoring window's, as of the last run.
+export const AgentCounts = z.strictObject({
+    events: Count,
+    verifiedTasks: Count,
+    seedTasks: Count.optional(),
+    incidents: Count,
+    sessions: Count,
+    toolCalls: Count,
+});
+export const AgentResponse = z.strictObject({
+    id: AgentId,
+    name: Name,
+    version: Version,
+    operator: Operator,
+    createdAt: Timestamp,
+    // True for an agent SealKeeper runs itself, such as the one that posts the
+    // seed tasks. GET /v1/agents/:id always sends it. The registration answer
+    // leaves it out, because CLI 0.1.0 parses that answer strictly and would
+    // refuse a key it does not know.
+    operatedBySealKeeper: z.boolean().optional(),
+    // Deprecated. The old name of operatedBySealKeeper, sent with the same
+    // value wherever the new one is, because CLI 0.4.2 and earlier read only
+    // this one. Removed in VOU-77.
+    operatedByVouched: z.boolean().optional(),
+    // Sent by every read and by rename, left out of the registration answer
+    // for the same reason as operatedBySealKeeper.
+    handle: AgentHandle.optional(),
+    // The name before the latest rename, when that rename was in the last
+    // RENAME_REDIRECT_DAYS days, else null. Sent with handle.
+    previousName: Name.nullable().optional(),
+    // Live from the database on every read, so they never lag behind the
+    // stored credential. Sent by GET by id and GET by handle only. Registration
+    // and rename leave them out, since a CLI parses those answers strictly.
+    counts: AgentCounts.optional(),
+    // The newest received_at of the agent's events, null when it has sent none.
+    lastSeenAt: Timestamp.nullable().optional(),
+    // The current version's SEAL standard level and the evidence behind it,
+    // from the last scoring run. Sent by GET by id and GET by handle once the
+    // version has been scored. Optional so CLI 0.3.0 and older answers parse.
+    level: Level.optional(),
+    standing: Standing.optional(),
+});
+// Old handles keep resolving, as a redirect, for this many days after a
+// rename.
+export const RENAME_REDIRECT_DAYS = 30;
+// A signed rename is accepted for this long after its issuedAt.
+export const RENAME_MAX_AGE_SEC = 300;
+// PATCH /v1/agents/:id, signed by the agent's own key. issuedAt is signed
+// with the name, so an old envelope sent again changes nothing.
+export const RenameAgentRequest = z.strictObject({
+    name: AgentName,
+    issuedAt: Timestamp,
+});
+// How many times an agent may move its version in a day. A real change
+// costs a scoring run the work of a new version, so a script that flaps
+// between versions is stopped here.
+export const VERSION_CHANGES_PER_DAY = 10;
+// PATCH /v1/agents/:id with a new version, signed by the agent's own key.
+// The version follows the same rule as registration. Ingest never moves it,
+// only this signed request does.
+export const ChangeVersionRequest = z.strictObject({
+    version: Version,
+    issuedAt: Timestamp,
+});
+// What PATCH /v1/agents/:id accepts. A rename, a version change or both in
+// one signed request, never neither.
+export const UpdateAgentRequest = z
+    .strictObject({
+    name: AgentName.optional(),
+    version: Version.optional(),
+    issuedAt: Timestamp,
+})
+    .refine((r) => r.name !== undefined || r.version !== undefined, {
+    message: 'name or version is required',
+});
+// The body of a signed rename or version change. Small, so it takes the
+// event envelope cap.
+export const SignedRenameRequest = z.strictObject({
+    envelope: Jws.max(MAX_ENVELOPE_CHARS),
+});
+// A signed delete is accepted for this long after its issuedAt, the same
+// window as rename.
+export const DELETE_AGENT_MAX_AGE_SEC = RENAME_MAX_AGE_SEC;
+// DELETE /v1/agents/:id from the CLI, signed by the agent's own key.
+// issuedAt bounds how long a captured envelope could be sent again.
+export const DeleteAgentRequest = z.strictObject({
+    issuedAt: Timestamp,
+});
+// The body of DELETE /v1/agents/:id. The CLI sends { envelope }. The web
+// sends no body and the session cookie instead, which reads as {}.
+export const DeleteAgentBody = z.union([
+    z.strictObject({ envelope: Jws.max(MAX_ENVELOPE_CHARS) }),
+    z.strictObject({}),
+]);
+// GET /v1/agents/:login/:name. Case does not matter in the login, as on
+// GitHub. Names are lowercase.
+export const AgentHandleParams = z.strictObject({
+    login: z.string().regex(/^[A-Za-z0-9-]{1,39}$/),
+    name: AgentName,
+});
+// The 404 for a handle an agent gave up in a rename in the last
+// RENAME_REDIRECT_DAYS days. id and handle name the agent as it is now, so a
+// client can redirect.
+export const AgentRenamedResponse = z.strictObject({
+    error: z.strictObject({
+        code: z.literal('renamed'),
+        message: z.string(),
+    }),
+    id: AgentId,
+    handle: AgentHandle,
+});
+// The public agents directory, GET /v1/agents. Newest registration first,
+// ties broken by id, paged with an opaque cursor.
+// A GitHub login. Letters, digits and hyphens, at most 39 characters.
+export const GithubLogin = z.string().regex(/^[A-Za-z0-9-]{1,39}$/);
+const CURSOR_TEXT = /^(\d{1,18})\.([A-Za-z0-9_-]{43})$/;
+export function encodeAgentsCursor(cursor) {
+    return base64urlEncode(utf8Encode(`${cursor.createdAtMicros}.${cursor.id}`));
+}
+// Null for anything that is not a cursor this API made.
+export function decodeAgentsCursor(raw) {
+    let text;
+    try {
+        text = utf8Decode(base64urlDecode(raw));
+    }
+    catch {
+        return null;
+    }
+    const m = CURSOR_TEXT.exec(text);
+    if (!m?.[1] || !m[2] || !AgentId.safeParse(m[2]).success)
+        return null;
+    return { createdAtMicros: m[1], id: m[2] };
+}
+export const AgentsCursorParam = z
+    .string()
+    .max(128)
+    .transform((raw, ctx) => {
+    const cursor = decodeAgentsCursor(raw);
+    if (cursor)
+        return cursor;
+    ctx.addIssue({ code: 'custom', message: 'Invalid cursor' });
+    return z.NEVER;
+});
+export const AgentsListQuery = z.strictObject({
+    limit: Limit,
+    cursor: AgentsCursorParam.optional(),
+    // Only this operator's agents. Case does not matter, as on GitHub.
+    operator: GithubLogin.optional(),
+});
+export const TopScore = z.strictObject({
+    dimension: BaseDimension,
+    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
+// 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,
+    operator: Operator,
+    // True for an agent SealKeeper runs itself. See AgentResponse.
+    operatedBySealKeeper: z.boolean(),
+    // Deprecated, the old name with the same value. Removed in VOU-77.
+    operatedByVouched: z.boolean().optional(),
+    createdAt: Timestamp,
+    lastSeenAt: Timestamp.nullable(),
+    topScores: z.array(TopScore).max(2),
+    verifiedTasks: Count,
+    seedTasks: Count,
+    level: Level.optional(),
+    standing: Standing.optional(),
+});
+// nextCursor is null on the last page.
+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(),
+        })),
+    }),
+});
+export const EventsBatchRequest = z.strictObject({
+    envelopes: z
+        .array(Jws.max(MAX_ENVELOPE_CHARS))
+        .min(1)
+        .max(MAX_EVENTS_PER_BATCH),
+});
+// accepted counts rows newly stored. duplicates counts events already stored
+// for this agent (same event_id), which are skipped, so a retry is safe.
+export const EventsBatchResponse = z.strictObject({
+    accepted: z.int().min(0),
+    duplicates: z.int().min(0),
+});
+const TaskSpec = z
+    .record(z.string(), z.unknown())
+    .refine((spec) => utf8Encode(JSON.stringify(spec)).length <= MAX_TASK_SPEC_BYTES, `spec must be at most ${MAX_TASK_SPEC_BYTES} bytes`);
+// taskId is generated by the client and becomes the task id, so a retried
+// post is a no-op. The same poster gets the existing task back, any other
+// poster gets 409.
+export const PostTaskRequest = z.strictObject({
+    taskId: z.uuid(),
+    taskType: TaskType,
+    spec: TaskSpec,
+    verification: VerificationSpec,
+    expiresAt: Timestamp.optional(),
+});
+export const TaskResponse = z.strictObject({
+    id: z.uuid(),
+    posterAgentId: AgentId,
+    claimantAgentId: AgentId.nullable(),
+    taskType: TaskType,
+    spec: z.record(z.string(), z.unknown()),
+    verification: VerificationSpec,
+    state: TaskState,
+    postedAt: Timestamp,
+    claimedAt: Timestamp.nullable(),
+    submittedAt: Timestamp.nullable(),
+    verifiedAt: Timestamp.nullable(),
+    expiresAt: Timestamp,
+    // 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() });
+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`),
+});
+// Named for its task like claim and submit, checked against the path.
+export const TaskOutcomeRequest = z.strictObject({
+    taskId: z.uuid(),
+    outcome: TaskOutcome,
+    evidenceHash: Sha256Hex.optional(),
+});
+export const ListTasksQuery = z.strictObject({
+    state: TaskState.default('open'),
+    taskType: TaskType.optional(),
+    limit: Limit,
+});
+export const ListTasksResponse = z.strictObject({
+    tasks: z.array(TaskResponse),
+});
+// The body of a signed rating. A rating payload is small, so it takes the
+// event envelope cap.
+export const SignedRatingRequest = z.strictObject({
+    envelope: Jws.max(MAX_ENVELOPE_CHARS),
+});
+export const RatingValue = z.int().min(1).max(5);
+// One rater rates one ratee on one dimension. A new rating on the same
+// dimension replaces the old one. issuedAt is signed with the rest, so an
+// old envelope sent again can never replace a newer rating.
+export const RatingRequest = z.strictObject({
+    rateeAgentId: AgentId,
+    dimension: Dimension,
+    value: RatingValue,
+    issuedAt: Timestamp,
+});
+// The stored rating. raterScoreAtTime is the rater's score when it rated,
+// which is the weight the rating carries in scoring.
+export const RatingResponse = z.strictObject({
+    rateeAgentId: AgentId,
+    dimension: Dimension,
+    value: RatingValue,
+    raterScoreAtTime: 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.
+export const ScoreEntry = z.strictObject({
+    version: Version,
+    dimension: Dimension,
+    value: z.number().min(0).max(1).nullable(),
+    windowStart: Timestamp.nullable(),
+    windowEnd: Timestamp.nullable(),
+    computedAt: Timestamp.nullable(),
+});
+// The agent's current version only.
+export const ScoreResponse = z.strictObject({
+    agentId: AgentId,
+    scores: z.array(ScoreEntry),
+});
+// The signed in operator and the agents they own, for the web's my agents
+// page. lastSeenAt is the newest received_at of the agent's events, null
+// when it has sent none. Agents are ordered by lastSeenAt, newest first,
+// with the never seen last. verifiedTasks and seedTasks are the same counts
+// as on AgentResponse, and so are level and standing.
+export const MeAgent = z.strictObject({
+    id: AgentId,
+    name: Name,
+    handle: AgentHandle,
+    operator: Operator,
+    version: Version,
+    createdAt: Timestamp,
+    lastSeenAt: Timestamp.nullable(),
+    scores: ScoreResponse,
+    verifiedTasks: Count,
+    seedTasks: Count,
+    level: Level.optional(),
+    standing: Standing.optional(),
+});
+// operator.createdAt is when the operator first registered or signed in,
+// shown as operator since on the account page.
+export const MeResponse = z.strictObject({
+    operator: z.strictObject({
+        login: z.string().min(1).max(39),
+        githubId: z.int().positive(),
+        createdAt: Timestamp,
+    }),
+    agents: z.array(MeAgent),
+});
+// DELETE /v1/me. The operator types their GitHub login to confirm, and it
+// must equal the signed in login exactly.
+export const DeleteMeRequest = z.strictObject({
+    login: z.string().min(1).max(39),
+});
+// GET /v1/agents/:id/seal and its alias /credential. seal and credential are
+// the same compact JWS. credential is kept for one release (VOU-77).
+export const CredentialResponse = z.strictObject({
+    credential: Jws,
+    seal: Jws,
+    payload: CredentialPayload,
+});
+// A bare /v1/leaderboard is the reliability board.
+export const LeaderboardQuery = z.strictObject({
+    dimension: Dimension.default('reliability'),
+    limit: Limit,
+});
+// Rows on the current version only, ranked by level first (gold, silver,
+// bronze, then none or not yet scored), then by value, highest first. Ties
+// go to the value computed first.
+export const LeaderboardEntry = z.strictObject({
+    rank: z.int().min(1),
+    agentId: AgentId,
+    name: Name,
+    handle: AgentHandle,
+    operator: Operator,
+    version: Version,
+    value: z.number().min(0).max(1),
+    // Tasks this agent claimed that reached verified and count toward trust,
+    // across all versions. The same rule as AgentCounts.verifiedTasks.
+    verifiedTasks: z.int().min(0),
+    // How many of verifiedTasks the seed agent posted. The API always sends
+    // it. Optional so the web still reads an answer from an older API.
+    seedTasks: Count.optional(),
+    // True for an agent SealKeeper runs itself. See AgentResponse.
+    operatedBySealKeeper: z.boolean(),
+    // Deprecated, the old name with the same value. Removed in VOU-77.
+    operatedByVouched: z.boolean().optional(),
+    // As on AgentResponse. Optional so the web reads an older API's answer.
+    level: Level.optional(),
+    standing: Standing.optional(),
+});
+export const LeaderboardResponse = z.strictObject({
+    dimension: Dimension,
+    entries: z.array(LeaderboardEntry),
+});
+// The public feed. Payloads carry public facts only. Never an operator
+// email, an envelope, a spec or a submission.
+export const FeedKind = z.enum([
+    'registration',
+    'task_verified',
+    'score_change',
+    'flag',
+    'version_change',
+]);
+// The one flag code today. Two sides of a counterparty task disagreed.
+export const FeedFlagCode = z.enum(['outcome_disagreement']);
+// name is the agent's name when the item was written. The item's handle
+// is the agent as it is now.
+const FeedAgent = {
+    agentId: AgentId,
+    name: Name,
+};
+export const FeedPayloads = {
+    registration: z.strictObject({ ...FeedAgent, version: Version }),
+    task_verified: z.strictObject({
+        ...FeedAgent,
+        taskId: z.uuid(),
+        taskType: TaskType,
+    }),
+    score_change: z.strictObject({
+        ...FeedAgent,
+        version: Version,
+        dimension: Dimension,
+        // null when the dimension had no value before.
+        old: z.number().min(0).max(1).nullable(),
+        new: z.number().min(0).max(1),
+    }),
+    flag: z.strictObject({
+        ...FeedAgent,
+        code: FeedFlagCode,
+        taskId: z.uuid(),
+    }),
+    // The agent moved its version with a signed request. The old and the new
+    // version, beside the agent every item names.
+    version_change: z.strictObject({
+        ...FeedAgent,
+        old: Version,
+        new: Version,
+    }),
+};
+const feedItemOf = (kind) => z.strictObject({
+    // The SSE event id. Ascending in insert order.
+    id: z.int().min(1),
+    kind: z.literal(kind),
+    agentId: AgentId.nullable(),
+    // The agent the payload names, as it is now. Looked up when the item is
+    // read, so a renamed agent's old items link to where it lives today.
+    operator: Operator,
+    handle: AgentHandle,
+    payload: FeedPayloads[kind],
+    createdAt: Timestamp,
+});
+export const FeedItem = z.discriminatedUnion('kind', [
+    feedItemOf('registration'),
+    feedItemOf('task_verified'),
+    feedItemOf('score_change'),
+    feedItemOf('flag'),
+    feedItemOf('version_change'),
+]);
+export const FEED_RECENT_MAX = 200;
+export const FeedRecentQuery = z.strictObject({
+    limit: z.coerce.number().int().min(1).max(FEED_RECENT_MAX).default(50),
+});
+// Newest first.
+export const FeedRecentResponse = z.strictObject({
+    items: z.array(FeedItem),
+});
+// Network totals for the landing page. eventsLast24h counts by the server's
+// received_at, so a client clock cannot move it.
+export const StatsResponse = z.strictObject({
+    agents: z.int().min(0),
+    verifiedTasks: z.int().min(0),
+    eventsLast24h: z.int().min(0),
+});
+// GET /v1/check/:login/: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
+// values arrive as text and are parsed exactly, so an empty or odd value is
+// a 400 and never quietly becomes 0.
+const QueryCount = z
+    .string()
+    .regex(/^\d{1,7}$/, 'must be a whole number')
+    .transform(Number);
+const QueryScore = z
+    .string()
+    .regex(/^[01](\.\d{1,6})?$/, 'must be a number from 0 to 1')
+    .transform(Number)
+    .pipe(z.number().min(0).max(1));
+// minVerified, maxIncidents and minLevel always run, with these defaults.
+// minReliability and minSafety run only when given. minLevel defaults to
+// bronze, the first level that recommends. minLevel=none asks for no level,
+// which every agent meets.
+export const CHECK_DEFAULT_MIN_VERIFIED = 1;
+export const CHECK_DEFAULT_MAX_INCIDENTS = 0;
+export const CHECK_DEFAULT_MIN_LEVEL = 'bronze';
+export const CheckQuery = z.strictObject({
+    minVerified: QueryCount.default(CHECK_DEFAULT_MIN_VERIFIED),
+    maxIncidents: QueryCount.default(CHECK_DEFAULT_MAX_INCIDENTS),
+    minReliability: QueryScore.optional(),
+    minSafety: QueryScore.optional(),
+    minLevel: Level.default(CHECK_DEFAULT_MIN_LEVEL),
+});
+// The checks, named after the query value that sets them, so the name says
+// which way the comparison goes. min is actual >= required, max is
+// actual <= required. For minLevel that is the order of LEVEL_RANK. seal is
+// the one check no query value sets. It is sent only when the SEAL is
+// withheld, required present and actual withheld, and it fails.
+export const CheckName = z.enum([
+    'seal',
+    'minVerified',
+    'maxIncidents',
+    'minReliability',
+    'minSafety',
+    'minLevel',
+]);
+// Whether the agent holds a current SEAL, for the seal check.
+export const SealPresence = z.enum(['present', 'withheld']);
+// actual is null when the agent has no value yet, as for a trust dimension
+// before any verified task. A null never passes. minLevel carries levels
+// in required and actual, and seal carries SealPresence.
+export const Check = z.strictObject({
+    name: CheckName,
+    required: z.union([z.number().min(0), Level, SealPresence]),
+    actual: z.union([z.number().min(0), Level, SealPresence]).nullable(),
+    ok: z.boolean(),
+});
+// ok is true only when every check is. credential is the agent's current
+// SEAL, so the caller can verify the numbers offline with the Vouched public
+// key. This is the shape the CLI's Mastra adapter publishes as its own type,
+// so it stays as it is. What the API sends is SealCheckResponse below.
+export const CheckResponse = z.strictObject({
+    ok: z.boolean(),
+    id: AgentId,
+    handle: AgentHandle,
+    checks: z.array(Check).min(1),
+    credential: Jws,
+});
+// What GET /v1/check answers. CheckResponse plus seal, the same string as
+// credential. Both are sent for one release, then credential goes (VOU-77).
+// Both are null when the SEAL is withheld after 90 dormant days, and the
+// answer then carries a failing seal check, so ok is false.
+export const SealCheckResponse = CheckResponse.extend({
+    credential: Jws.nullable(),
+    seal: Jws.nullable(),
+}).refine((r) => r.seal === r.credential &&
+    (r.seal !== null ||
+        r.checks.some((k) => k.name === 'seal' && k.actual === 'withheld')), 'seal and credential are the same, and null only with a withheld seal check');
+// GET /v1/agents/:id/seal, its alias /credential and the handle route, when
+// the agent's current version has been dormant for 90 days or more and the
+// last scoring run marked it no_seal. No SEAL is issued until the next run
+// after an accepted event. dormant_days is counted at the answer.
+export const SealWithheldResponse = z.strictObject({
+    error: z.strictObject({
+        code: z.literal('no_seal'),
+        message: z.string(),
+    }),
+    id: AgentId,
+    dormant_days: z.int().min(0).nullable(),
+});
+// 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() });
+export const SealBrokenReason = z.enum([
+    'malformed',
+    'unknown_kid',
+    'bad_signature',
+    'wrong_issuer',
+    'unsupported_version',
+    'expired',
+    'not_yet_valid',
+]);
+// 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.
+export const SealVerifyResponse = z.discriminatedUnion('valid', [
+    z.strictObject({
+        valid: z.literal(true),
+        payload: SealPayload,
+        expiresIn: z.int().min(1),
+    }),
+    z.strictObject({ valid: z.literal(false), reason: SealBrokenReason }),
+]);
+export const ScoreRunResponse = z.strictObject({
+    scored: 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.
+export const SeedRunResponse = z.strictObject({
+    open: z.int().min(0),
+    added: z.int().min(0),
+});
+export const ErrorIssue = z.strictObject({
+    path: z.array(z.union([z.string(), z.number()])),
+    code: z.string(),
+    message: z.string(),
+});
+export const ErrorResponse = z.strictObject({
+    error: z.strictObject({
+        code: z.string(),
+        message: z.string(),
+        issues: z.array(ErrorIssue).optional(),
+    }),
+});

package/dist/base64url.d.ts

@@ -0,0 +1,4 @@
+export declare function base64urlEncode(bytes: Uint8Array): string;
+export declare function base64urlDecode(text: string): Uint8Array<ArrayBuffer>;
+export declare const utf8Encode: (text: string) => Uint8Array<ArrayBuffer>;
+export declare const utf8Decode: (bytes: Uint8Array) => string;

package/dist/base64url.js

@@ -0,0 +1,43 @@
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const LOOKUP = new Map([...ALPHABET].map((char, i) => [char, i]));
+export function base64urlEncode(bytes) {
+    let out = '';
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        buffer = ((buffer << 8) | byte) & 0xffff;
+        bits += 8;
+        while (bits >= 6) {
+            bits -= 6;
+            out += ALPHABET[(buffer >> bits) & 63];
+        }
+    }
+    if (bits > 0)
+        out += ALPHABET[(buffer << (6 - bits)) & 63];
+    return out;
+}
+export function base64urlDecode(text) {
+    if (text.length % 4 === 1)
+        throw new Error('Invalid base64url length');
+    const out = new Uint8Array(Math.floor((text.length * 6) / 8));
+    let buffer = 0;
+    let bits = 0;
+    let j = 0;
+    for (const char of text) {
+        const value = LOOKUP.get(char);
+        if (value === undefined)
+            throw new Error('Invalid base64url character');
+        buffer = ((buffer << 6) | value) & 0xfff;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[j++] = (buffer >> bits) & 0xff;
+        }
+    }
+    if ((buffer & ((1 << bits) - 1)) !== 0) {
+        throw new Error('Non-canonical base64url');
+    }
+    return out;
+}
+export const utf8Encode = (text) => new TextEncoder().encode(text);
+export const utf8Decode = (bytes) => new TextDecoder('utf-8', { fatal: true }).decode(bytes);