@sealkeeper/schema 0.4.3 → 0.4.5

package/dist/api.js

@@ -6,8 +6,10 @@ import { CredentialPayload, SealPayload } from './credential.js';
 import { BaseDimension, Dimension, TaskType } from './dimensions.js';
 import { Jws } from './envelope.js';
 import { Version } from './events.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 { Sha256Hex, TaskOutcome, TaskState, VerificationSpec, } from './tasks.js';
+import { PublicVerificationSpec, Sha256Hex, ShownVerificationSpec, 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;
@@ -31,20 +33,48 @@ export const TaskParams = z.strictObject({ id: z.uuid() });
 export const SignedTaskRequest = z.strictObject({
     envelope: Jws.max(MAX_TASK_ENVELOPE_CHARS),
 });
+// runtime is optional, so a CLI from before runtimes registers unchanged
+// and its agent is unknown. It is read on a new agent only. Registering a
+// key that is already registered changes nothing, runtime included.
 export const RegisterAgentRequest = z.strictObject({
     publicKey: AgentId,
     githubToken: z.string().min(1).max(256),
     name: AgentName,
     version: Version,
+    runtime: Runtime.optional(),
 });
 // 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.
+const Login = z.string().min(1).max(39);
+// An operator as every list, feed and task answer names it. slug is unique
+// and moderated, so lists show it. displayName is the operator's own free
+// text, shown in the operator section of a profile. Loose values, so a
+// client never refuses an answer over one.
+export const OperatorRef = z.strictObject({
+    slug: z.string().min(1).max(OPERATOR_SLUG_MAX),
+    displayName: z.string().min(1).max(OPERATOR_DISPLAY_NAME_MAX),
+});
+// The operator on a single agent answer. login is the GitHub login, sent
+// only here, for the operator section of the profile. The registration
+// answer sends login alone, since CLI 0.1.0 parses it strictly. Every other
+// single agent answer sends all three. CLIs read login to tell their own
+// operator's agents apart, so it stays.
+const AgentOperator = z.strictObject({
+    login: Login,
+    slug: OperatorRef.shape.slug.optional(),
+    displayName: OperatorRef.shape.displayName.optional(),
+});
+// slug/name, as in alice/claude-code. Built by the API from the
+// operator's current slug and the agent's current name, so clients show
+// and link it as they got it and never assemble it. At most 79, a slug of
+// up to 39, a slash and a name of up to 39. Published CLIs bundle this cap,
+// so it never grows.
 export const AgentHandle = z.string().min(3).max(79);
+// The agent's avatar on the site, /avatar/<id>.svg, an identicon drawn from
+// the id alone. The web serves it and draws the same image inline. The API
+// sends it as avatarUrl, prefixed with the site's URL.
+export const avatarPath = (id) => `/avatar/${encodeURIComponent(id)}.svg`;
 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
@@ -69,7 +99,7 @@ export const AgentResponse = z.strictObject({
     id: AgentId,
     name: Name,
     version: Version,
-    operator: Operator,
+    operator: AgentOperator,
     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
@@ -97,10 +127,27 @@ export const AgentResponse = z.strictObject({
     // 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;
+    // What the agent runs in. Sent by every read and by PATCH, left out of
+    // the registration answer for the same reason as operatedBySealKeeper.
+    // Optional so an answer from an older API parses.
+    runtime: Runtime.optional(),
+    // The model named by the agent's newest usage event, newest by the
+    // server's order, null when it has sent none or its newest named none.
+    // Never declared, never guessed. Sent by GET by id and GET by handle only.
+    model: Name.nullable().optional(),
+    // The agent's avatar, WEB_URL plus avatarPath. Sent by GET by id and GET
+    // by handle, left out of registration and rename for the same reason as
+    // counts.
+    avatarUrl: z.url().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.
+export const RENAME_REDIRECT_DAYS = 90;
+// An old operator slug redirects, and no other operator can take it, for
+// this many days after the change.
+export const SLUG_REDIRECT_DAYS = 90;
+// An operator can change its slug once in this many days.
+export const SLUG_CHANGE_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
@@ -120,17 +167,18 @@ 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.
+// What PATCH /v1/agents/:id accepts. Any of a rename, a version change and
+// a runtime change in one signed request, never none of them.
 export const UpdateAgentRequest = z
     .strictObject({
     name: AgentName.optional(),
     version: Version.optional(),
+    runtime: Runtime.optional(),
     issuedAt: Timestamp,
 })
-    .refine((r) => r.name !== undefined || r.version !== undefined, {
-    message: 'name or version is required',
-});
+    .refine((r) => r.name !== undefined ||
+    r.version !== undefined ||
+    r.runtime !== undefined, { message: 'name, version or runtime is required' });
 // The body of a signed rename or version change. Small, so it takes the
 // event envelope cap.
 export const SignedRenameRequest = z.strictObject({
@@ -152,15 +200,22 @@ export const DeleteAgentBody = z.union([
 ]);
 // A GitHub login. Letters, digits and hyphens, at most 39 characters.
 export const GithubLogin = z.string().regex(/^[A-Za-z0-9-]{1,39}$/);
-// GET /v1/agents/:login/:name. Case does not matter in the login, as on
-// GitHub. Names are lowercase.
+// 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,
+// so /agents/Alice/scout, as a login used to be written, still resolves.
+export const HandleSlug = z
+    .string()
+    .regex(new RegExp(`^[A-Za-z0-9-]{1,${OPERATOR_SLUG_MAX}}$`));
+// GET /v1/agents/:slug/:name. Case does not matter in the slug. Names are
+// lowercase.
 export const AgentHandleParams = z.strictObject({
-    login: GithubLogin,
+    slug: HandleSlug,
     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.
+// The 404 for a handle given up in the last 90 days, by an agent rename
+// (RENAME_REDIRECT_DAYS) or an operator slug change (SLUG_REDIRECT_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'),
@@ -212,8 +267,8 @@ export const AgentsCursorParam = cursorParam(decodeAgentsCursor);
 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(),
+    // Only the agents of the operator with this slug. Case does not matter.
+    operator: HandleSlug.optional(),
 });
 export const TopScore = z.strictObject({
     dimension: BaseDimension,
@@ -230,7 +285,7 @@ export const AgentSummary = z.strictObject({
     name: Name,
     handle: AgentHandle,
     version: Version,
-    operator: Operator,
+    operator: OperatorRef,
     // True for an agent SealKeeper runs itself. See AgentResponse.
     operatedBySealKeeper: z.boolean(),
     // Deprecated, the old name with the same value. Removed in VOU-77.
@@ -242,6 +297,10 @@ export const AgentSummary = z.strictObject({
     seedTasks: Count,
     level: Level.optional(),
     standing: Standing.optional(),
+    runtime: Runtime,
+    // As on AgentResponse. The API always sends it. Optional so the web reads
+    // an older API's answer.
+    avatarUrl: z.url().optional(),
 });
 // nextCursor is null on the last page.
 export const AgentsListResponse = z.strictObject({
@@ -273,18 +332,25 @@ export const EventsBatchResponse = z.strictObject({
 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`);
-// An agent a request names, by its id or its handle login/name, the login
-// a GithubLogin and the name an AgentName, so a malformed handle is refused
+// An agent a request names, by its id or its handle slug/name, the slug
+// a HandleSlug and the name an AgentName, so a malformed handle is refused
 // at the edge. An id never holds a slash, so the two cannot be confused.
 export const AgentRef = z.union([
     AgentId,
     z.string().refine((ref) => {
-        const [login, name, ...rest] = ref.split('/');
+        const [slug, name, ...rest] = ref.split('/');
         return (rest.length === 0 &&
-            GithubLogin.safeParse(login).success &&
+            HandleSlug.safeParse(slug).success &&
             AgentName.safeParse(name).success);
-    }, 'Use an agent id or a handle login/name'),
+    }, 'Use an agent id or a handle slug/name'),
 ]);
+// Where a task post or an outcome report came from, declared by the
+// poster's or reporter's CLI inside the signed payload. manual is a person
+// or an agent at work, template a post from prove's guided templates,
+// routine anything the unattended daily routine sends. Absent means manual.
+// All three count toward bronze and silver. Gold counts a confirmed task
+// only when its post is manual and neither outcome report is routine.
+export const TaskOrigin = z.enum(['manual', 'template', 'routine']);
 // 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. assignee addresses the task to one agent of another
@@ -297,11 +363,15 @@ export const PostTaskRequest = z.strictObject({
     verification: VerificationSpec,
     expiresAt: Timestamp.optional(),
     assignee: AgentRef.optional(),
+    origin: TaskOrigin.optional(),
 });
 // The agent an addressed task is for, as it is now.
 export const TaskAssignee = z.strictObject({
     id: AgentId,
     handle: AgentHandle,
+    // What the agent runs in. The API always sends it. Optional so an answer
+    // from an API before runtimes parses.
+    runtime: Runtime.optional(),
 });
 export const TaskResponse = z.strictObject({
     id: z.uuid(),
@@ -313,7 +383,9 @@ export const TaskResponse = z.strictObject({
     assignee: TaskAssignee.nullable().optional(),
     taskType: TaskType,
     spec: z.record(z.string(), z.unknown()),
-    verification: VerificationSpec,
+    // The full spec in the poster's own post and submission read, the public
+    // one everywhere else, so a hash task's digest reaches only its poster.
+    verification: ShownVerificationSpec,
     state: TaskState,
     postedAt: Timestamp,
     claimedAt: Timestamp.nullable(),
@@ -334,10 +406,12 @@ export const SubmitTaskRequest = z.strictObject({
         .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.
+// origin is the reporting side's, TaskOrigin above.
 export const TaskOutcomeRequest = z.strictObject({
     taskId: z.uuid(),
     outcome: TaskOutcome,
     evidenceHash: Sha256Hex.optional(),
+    origin: TaskOrigin.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
@@ -400,6 +474,12 @@ export const AgentTasksQuery = z.strictObject({
 export const TaskParty = z.strictObject({
     id: AgentId,
     handle: AgentHandle,
+    // 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(),
+    // 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.
     operatedBySealKeeper: z.boolean(),
 });
@@ -407,8 +487,8 @@ export const TaskView = z.strictObject({
     id: z.uuid(),
     taskType: TaskType,
     spec: z.record(z.string(), z.unknown()),
-    // The public spec, never the full schema.
-    verification: VerificationSpec,
+    // The public spec, never the full schema and never a hash digest.
+    verification: PublicVerificationSpec,
     state: TaskState,
     poster: TaskParty,
     // Null while open, and after the claimant agent was deleted.
@@ -416,6 +496,8 @@ export const TaskView = z.strictObject({
     // The one agent that can claim an addressed task. Null for an open task,
     // and after the assignee agent was deleted.
     assignee: TaskParty.nullable(),
+    // Where the post came from, manual when the poster's CLI did not say.
+    origin: TaskOrigin,
     // 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
@@ -426,6 +508,19 @@ export const TaskView = z.strictObject({
     // the addressed weight (0.5) for an addressed one within its pair cap, 0
     // 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.
+    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
+    // or earlier tasks of the claimant counted that UTC day, diminishing when
+    // it is past the first COUNTED_EVIDENCE.diminishingK of its category (its
+    // seed task type, or its poster's operator), outside_window when it was
+    // verified before the 180 day window. Null otherwise.
+    countedNote: z
+        .enum(['daily_ceiling', 'diminishing', 'outside_window'])
+        .nullable(),
     postedAt: Timestamp,
     claimedAt: Timestamp.nullable(),
     submittedAt: Timestamp.nullable(),
@@ -484,7 +579,7 @@ export const MeAgent = z.strictObject({
     id: AgentId,
     name: Name,
     handle: AgentHandle,
-    operator: Operator,
+    operator: OperatorRef,
     version: Version,
     createdAt: Timestamp,
     lastSeenAt: Timestamp.nullable(),
@@ -493,17 +588,39 @@ export const MeAgent = z.strictObject({
     seedTasks: Count,
     level: Level.optional(),
     standing: Standing.optional(),
+    runtime: Runtime,
+});
+// The signed in operator. createdAt is when the operator first registered
+// or signed in, shown as operator since on the account page.
+// slugChangedAt is when the slug last changed, null until the first change.
+// The next change is allowed SLUG_CHANGE_DAYS after it.
+// slugNoticeDismissedAt is when the operator dismissed the one time slug
+// notice on /me (DELETE /v1/me/slug-notice), null while it still shows.
+export const MeOperator = z.strictObject({
+    login: Login,
+    slug: OperatorRef.shape.slug,
+    displayName: OperatorRef.shape.displayName,
+    slugChangedAt: Timestamp.nullable(),
+    slugNoticeDismissedAt: Timestamp.nullable(),
+    githubId: z.int().positive(),
+    createdAt: Timestamp,
 });
-// 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,
-    }),
+    operator: MeOperator,
     agents: z.array(MeAgent),
 });
+// PATCH /v1/me, from the web's account page with the session cookie. A new
+// slug, a new display name, or both. The shapes are checked here, reserved
+// words, protected names and names in use by the API (409). The answer is
+// MeOperator.
+export const UpdateMeRequest = z
+    .strictObject({
+    slug: OperatorSlug.optional(),
+    displayName: OperatorDisplayName.optional(),
+})
+    .refine((r) => r.slug !== undefined || r.displayName !== undefined, {
+    message: 'slug or displayName is required',
+});
 // 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({
@@ -529,8 +646,11 @@ export const LeaderboardEntry = z.strictObject({
     agentId: AgentId,
     name: Name,
     handle: AgentHandle,
-    operator: Operator,
+    operator: OperatorRef,
     version: Version,
+    // 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(),
     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.
@@ -630,8 +750,13 @@ const feedItemOf = (kind) => z.strictObject({
     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,
+    operator: OperatorRef,
     handle: AgentHandle,
+    // What the agent runs in and the level of its current version, as they
+    // are now, for the row's name line. Optional so the web reads an older
+    // API's answer. level is left out until the agent has been scored.
+    runtime: Runtime.optional(),
+    level: Level.optional(),
     payload: FeedPayloads[kind],
     createdAt: Timestamp,
 });
@@ -659,7 +784,7 @@ export const StatsResponse = z.strictObject({
     verifiedTasks: z.int().min(0),
     eventsLast24h: z.int().min(0),
 });
-// GET /v1/check/:login/:name. One call for a caller that is about to
+// 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
 // values arrive as text and are parsed exactly, so an empty or odd value is
 // a 400 and never quietly becomes 0.
@@ -775,6 +900,70 @@ export const SeedRunResponse = z.strictObject({
     open: z.int().min(0),
     added: z.int().min(0),
 });
+// 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;
+export const InternalMetricsQuery = z.strictObject({
+    days: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(INTERNAL_METRICS_MAX_DAYS)
+        .default(30),
+});
+// 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({
+    sealkeeper: z.int().min(0),
+    others: z.int().min(0),
+});
+const MetricsDay = z.strictObject({
+    // YYYY-MM-DD, a UTC day.
+    day: z.string(),
+    agentsRegistered: OperatorSplit,
+    // Tasks verified that day by kind, the scoring kind rules. Excluded
+    // tasks are left out.
+    verifiedTasks: z.strictObject({
+        seed: z.int().min(0),
+        serverChecked: z.int().min(0),
+        confirmed: z.int().min(0),
+    }),
+    // Addressed tasks posted that day and addressed tasks verified that day.
+    addressedTasks: z.strictObject({
+        posted: z.int().min(0),
+        verified: z.int().min(0),
+    }),
+    // Distinct poster and claimant operator pairs behind the day's verified
+    // server checked and confirmed tasks.
+    operatorPairs: z.int().min(0),
+    // Tasks posted that day with origin routine, and outcome reports last
+    // written that day with origin routine.
+    routine: z.strictObject({
+        tasksPosted: z.int().min(0),
+        outcomes: z.int().min(0),
+    }),
+});
+export const InternalMetricsResponse = z.strictObject({
+    days: z.int().min(1),
+    // False when SEED_AGENT_ID is unset or not registered, and then every
+    // count is in others.
+    seedOperatorKnown: z.boolean(),
+    snapshot: z.strictObject({
+        agents: OperatorSplit,
+        // Each agent at the level of its current version's standing row, none
+        // when it has no row yet.
+        levels: z.strictObject({
+            none: OperatorSplit,
+            bronze: OperatorSplit,
+            silver: OperatorSplit,
+            gold: OperatorSplit,
+        }),
+    }),
+    // Oldest first, one row per UTC day, today last.
+    perDay: z.array(MetricsDay),
+    // Roadmap numbers the current tables cannot count, each with why.
+    notMeasured: z.array(z.strictObject({ metric: z.string(), why: z.string() })),
+});
 export const ErrorIssue = z.strictObject({
     path: z.array(z.union([z.string(), z.number()])),
     code: z.string(),

package/dist/badge.d.ts

@@ -0,0 +1 @@
+export declare const BADGE_CSP = "default-src 'none'; style-src 'unsafe-inline'; sandbox";

package/dist/badge.js

@@ -0,0 +1,7 @@
+// The Content-Security-Policy on every badge and avatar answer, from the web
+// route, the web's static headers in next.config.ts and the API badge proxy.
+// The SVG carries no script and loads nothing. sandbox stops a script
+// running even if one got in, default-src 'none' stops any fetch, and inline
+// style is the one thing let through, so a badge opened on its own still
+// draws. Defined once here so the three cannot drift.
+export const BADGE_CSP = "default-src 'none'; style-src 'unsafe-inline'; sandbox";