@intentic/sandbox-contract 1.248.0 → 1.250.0

package/src/schemas/history.ts

@@ -1,9 +1,8 @@
 // history: daemon-owned workspace snapshots (diff + restore)
 import { z } from "zod";
-// The daemon snapshots /work into bare git dirs on /history (outside the agent's reach). A "snapshot" groups
-// one commit per scope (root + each nested repo) under a shared id. Only checkpoint triggers (turn / user /
-// pre-restore / restore) are listed; "interval" captures are a hidden safety net that dissolves into the next
-// visible checkpoint's diff.
+// Daemon snapshots /work into bare git dirs on /history, outside the agent's reach; a snapshot groups one commit per
+// scope (root + each nested repo) under a shared id. "interval" captures are a hidden safety net that dissolves into
+// the next visible checkpoint's diff.
 
 export const SnapshotTriggerSchema = z.enum(["turn", "interval", "pre-restore", "restore", "user"]);
 export type SnapshotTrigger = z.infer<typeof SnapshotTriggerSchema>;
@@ -14,24 +13,19 @@ export const SnapshotSchema = z.object({
     trigger: SnapshotTriggerSchema.describe(
         "What caused it. The automatic between-turn captures are a safety net and are not listed; they dissolve into the next visible point's differences.",
     ),
-    // Human-readable checkpoint label, the turn's prompt for "turn" snapshots; absent otherwise.
+    // Absent for anything but a "turn" snapshot.
     label: z.string().optional().describe("What to call it. For one taken before a turn, that turn's prompt."),
 });
 export type Snapshot = z.infer<typeof SnapshotSchema>;
-/* WHICH CONVERSATION MESSAGE A TURN ANSWERS, carried alongside the turn so its pre-turn checkpoint can be
- * filed under it (see the sandbox's agent/turn-anchors.ts). `index` is the transcript position the turn began
- * at, which is also how many messages a rewind to it keeps. */
+// Which conversation message a turn answers, so its pre-turn checkpoint can be filed under it. `index` is the
+// transcript position the turn began at, and how many messages a rewind to it keeps.
 export interface SnapshotTurn {
     readonly conversationId: string;
     readonly index: number;
 }
 export const SnapshotsListSchema = z.object({ snapshots: z.array(SnapshotSchema).describe("Every point you can go back to, newest first.") });
-/* REWIND, go back to a message and carry on from there. Restores the workspace to that turn's checkpoint,
- * drops every message after it, and forgets the provider session so the next turn opens a fresh one.
- *
- * `index` is the transcript position of the user message being rewound TO, which is also how many messages
- * survive, rewinding to the first message of a conversation keeps none of it and restores the workspace to
- * before it ran. */
+// Restores the workspace to that turn's checkpoint, drops every message after it, and forgets the provider session so
+// the next turn opens fresh.
 export const RewindTurnSchema = z.object({
     conversationId: z.string().min(1).describe("Which conversation to rewind."),
     index: z
@@ -43,23 +37,20 @@ export const RewindTurnSchema = z.object({
         ),
 });
 export const RewindResultSchema = z.object({
-    /* The checkpoint the workspace was restored to, for the History timeline to select. Absent when the
-     * conversation works in a checkout of its own: that rewind moved the conversation's own branch, which the
-     * workspace timeline does not carry, there is no row there to select. */
     snapshot: z
         .string()
         .optional()
         .describe(
             "The saved point the files were put back to. Absent for a conversation working in its own copy, whose rewind moved a branch rather than the shared timeline.",
         ),
-    // Messages dropped from the transcript, what the client removes from its own bubbles.
+    // What the client removes from its own message bubbles.
     dropped: z.number().int().nonnegative().describe("How many messages were removed."),
 });
 export type RewindResult = z.infer<typeof RewindResultSchema>;
 export const SnapshotIdSchema = z.object({ id: z.string().min(1).describe("Which saved point.") });
 export const SnapshotChangeSchema = z.object({
     scope: z.string().describe("Which part of the workspace the path belongs to: the workspace root, or one of the repositories inside it."),
-    // Scope-relative path with forward slashes.
+    // Forward slashes.
     path: z.string().describe("The path, relative to that scope."),
     status: z.enum(["added", "modified", "deleted", "type-changed"]).describe("What happened to it."),
 });
@@ -72,25 +63,8 @@ export const SnapshotFileDiffQuerySchema = z.object({
     scope: z.string().min(1).describe("Which part of the workspace the path belongs to."),
     path: z.string().min(1).describe("The file, relative to that scope."),
 });
-/* WHAT A FILE TOO BIG TO SEND WHOLE ANSWERS WITH INSTEAD, and why that is not simply "no".
- *
- * Both whole sides of a half-megabyte file are a megabyte of JSON per click, so above the cap they are not
- * sent, which used to be the end of it: the response said "too large" and every review surface printed one
- * sentence over an empty pane. That is the wrong trade, because the thing a reader wants out of a big file is
- * almost never the file: it is the handful of lines that MOVED, and those are small however big the file is.
- *
- * So the daemon diffs it and sends the CHANGED REGIONS as a unified patch, at the same three lines of context
- * a collapsed region keeps elsewhere. A 40 KB patch stands in for a 60 MB pair, and the reader gets the actual
- * review rather than a refusal. `patch` carries the `@@` sections only, the file headers git prints above them
- * name rev-specs no one can apply anyway.
- *
- * An added or deleted file has no counterpart to diff against, so its patch IS the file, one region of pure
- * +/− lines. That is still the right answer: cut to the budget, it is the head of the file, which is the peek
- * the reader came for.
- *
- * `patch` is absent only when there was nothing to make one from: a change too large even to render as a
- * patch, or a git that refused. The sizes are still there, so a surface can at least say how big the thing it
- * is not showing is. */
+// Unified-diff hunks of the changed regions only, not the whole file. An added/deleted file's patch is the whole file;
+// `patch` is absent only when even that could not be made.
 export const PartialFileDiffSchema = z.object({
     beforeBytes: z.number().int().nonnegative().optional().describe("How big the before side is, in bytes. Absent when the file did not exist yet."),
     afterBytes: z.number().int().nonnegative().optional().describe("How big the after side is, in bytes. Absent when the file was deleted."),
@@ -101,8 +75,8 @@ export const PartialFileDiffSchema = z.object({
     more: z.boolean().optional().describe("There were more changed regions than fit; the patch stops at a region boundary."),
 });
 export type PartialFileDiff = z.infer<typeof PartialFileDiffSchema>;
-// Both sides of a file diff, a snapshot vs its parent, or a working tree vs HEAD; an absent side means the
-// file was added/deleted. Binary content is flagged instead of shipped; oversized content arrives as `partial`.
+// Both sides of a file diff (snapshot vs parent, or worktree vs HEAD); an absent side means added/deleted. Binary is
+// flagged, not shipped; oversized arrives as `partial`.
 export const FileDiffSchema = z.object({
     before: z.string().optional().describe("The whole file as it was. Absent when it did not exist yet, or when `partial` is set."),
     after: z.string().optional().describe("The whole file as it is now. Absent when it was deleted, or when `partial` is set."),

package/src/schemas/hosts.ts

@@ -1,15 +1,12 @@
 // hosts: the user's own connected devices (the `host` capability's live half)
 import { z } from "zod";
-// The manifest says which machines the user INTENDS to have connected; this says which are actually holding a
-// socket right now. Nothing here is remembered across a daemon restart except the enrollment itself: a machine
-// is "online" exactly while its WebSocket is attached, so a laptop that closed its lid reads as offline within
-// a heartbeat rather than staying green until someone asks it to do something.
+// Manifest says which machines are intended; this says which actually hold a socket now. Nothing persists across a
+// daemon restart except the enrollment itself, so a closed laptop reads offline within a heartbeat.
 
-// What a machine reports about itself once, at connect (the agent's own `host.describe`, cached until it
-// reconnects). It is the difference between an agent guessing what is on the box and knowing: the SKILL pack
-// tells it HOW to drive Windows, this tells it WHICH Windows this is.
+// What a machine reports once at connect (`host.describe`), cached until it reconnects: the skill pack says how to
+// drive Windows, this says which Windows it is.
 export const HostFactsSchema = z.object({
-    // The OS's own name for itself, "Windows 11 Pro 24H2", "Ubuntu 24.04.1 LTS".
+    // The OS's own name for itself, e.g. "Windows 11 Pro 24H2".
     os: z.string(),
     arch: z.string(),
     // The shell run_command actually spawns, so the agent writes for the right one from its first command.
@@ -18,9 +15,8 @@ export const HostFactsSchema = z.object({
     home: z.string(),
     // Roots in force right now (the capability's `roots`, or [home]), the agent sees its own boundary.
     roots: z.array(z.string()),
-    /* The Docker ENGINE's size — the WSL guest on Windows, the Desktop VM on macOS, the host on Linux — which
-     * is the ceiling a sandbox's share is bounded by, and the number a Resources dialog draws its limits from.
-     * Absent when the machine has no docker to ask, which is a machine that runs no sandboxes anyway. */
+    // Docker engine's size (WSL guest on Windows, Desktop VM on macOS, host on Linux); the ceiling a sandbox's share is
+    // bounded by.
     engine: z.object({ memoryBytes: z.number(), cpus: z.number() }).optional(),
 });
 export type HostFacts = z.infer<typeof HostFactsSchema>;
@@ -29,11 +25,9 @@ export const HostSummarySchema = z.object({
     id: z.string(),
     platform: z.string().min(1),
     online: z.boolean(),
-    // The agent binary's version, so a machine running an old build is visible rather than mysteriously lacking
-    // a tool. Absent until the machine has connected once.
+    // Agent binary version; absent until the machine has connected once.
     version: z.string().optional(),
-    // Epoch ms of the last time this machine held a socket. Absent ⇒ it has not connected since this daemon
-    // booted, liveness is a fact about a socket, so a restart forgets it rather than claiming stale uptime.
+    // Epoch ms of the last held socket; absent means not since this daemon booted (liveness resets on restart).
     lastSeen: z.number().optional(),
     facts: HostFactsSchema.optional(),
 });

package/src/schemas/inventory.ts

@@ -1,14 +1,13 @@
 // inventory: the i.have.* / i.want.service entries in deploy.config.ts's managed region
 import { z } from "zod";
-// The daemon renders/parses these; the browser edits them through the inventory routes. Moved here from the
-// daemon's deploy-config.ts so the daemon and the browser validate against ONE schema (no cross-repo dupes).
+// The daemon renders/parses these; the browser edits them through the inventory routes.
 
 export const InventoryProviderSchema = z.enum(["host", "cloudflare", "github", "gitlab", "stripe"]);
 export type InventoryProvider = z.infer<typeof InventoryProviderSchema>;
 export const ServiceKindSchema = z.enum(["signoz", "outline", "paperless", "openproject", "invoiceninja", "infisical"]);
 export type ServiceKind = z.infer<typeof ServiceKindSchema>;
-// Non-secret option values the user provides; secret options (sshKey, apiToken, apiKey) are emitted as env()
-// references and never travel over the wire.
+// Non-secret option values; secret options (sshKey, apiToken, apiKey) are emitted as env() references, never sent over
+// the wire.
 export const InventoryValuesSchema = z.record(z.string(), z.union([z.string(), z.number()]));
 // `const <name>` binding in deploy.config.ts, so it must be a valid identifier.
 const inventoryName = z
@@ -30,8 +29,8 @@ export const ServiceEntrySchema = z.object({
     on: z.string().describe("Which of your machines to put it on."),
     expose: z.string().describe("How it should be reachable."),
 });
-// i.want.app, a deployable app built from source. Single production environment on `main`; `values.domain` is
-// where it's exposed. Multi-env/teams/use wiring is hand-authored outside the managed region.
+// i.want.app: single production environment on `main`; `values.domain` is where it's exposed. Multi-env/teams wiring is
+// hand-authored outside the managed region.
 export const AppEntrySchema = z.object({
     kind: z.literal("app").describe("An app of your own, built from source and deployed."),
     name: z.string().describe("What to call it."),
@@ -51,8 +50,8 @@ export const InventoryNameParamSchema = z.object({ name: z.string().describe("Wh
 export const InventoryListSchema = z.object({
     entries: z.array(InventoryEntrySchema).describe("Everything declared: what you have, and what you want provisioned."),
 });
-// A deploy-target host self-registering via the connect-host script's POST /enroll (connect-token auth). The SSH
-// key (+ optional Cloudflare token) is written to desired-state/.env; the host (+ cf) is upserted into inventory.
+// A deploy-target host self-registering via POST /enroll (connect-token auth); the SSH key (+ optional Cloudflare
+// token) is written to desired-state/.env, and upserted into inventory.
 export const EnrollHostInputSchema = z.object({
     name: inventoryName,
     user: z.string().min(1),
@@ -61,8 +60,7 @@ export const EnrollHostInputSchema = z.object({
     via: z.enum(["direct", "cloudflared"]).default("cloudflared"),
     sshKey: z.string().min(1),
     cfToken: z.string().optional(),
-    // The zone the connect script resolved alongside cfToken, recorded on the i.have.cloudflare entry so
-    // resolve validates against it (no re-discovery) and the Add-service dialog offers `<subdomain>.<zone>`.
+    // Resolved alongside cfToken; avoids re-discovery and lets Add-service offer `<subdomain>.<zone>`.
     cfZone: z.string().optional(),
 });
 export type EnrollHostInput = z.infer<typeof EnrollHostInputSchema>;

package/src/schemas/issues.ts

@@ -1,33 +1,19 @@
-// issues: inbound bug reports from the owner's own sites and apps, grouped by fingerprint
-// (.intentic/records/issues/<fingerprint>.json, one file per group)
+// Inbound bug reports from the owner's own sites and apps, grouped by fingerprint
+// (.intentic/records/issues/<fingerprint>.json, one file per group).
 import { z } from "zod";
 import { entryId } from "./internal.js";
 
-/* WHAT A USER'S CRASH LOOKS LIKE BY THE TIME AN AGENT CAN ACT ON IT.
- *
- * Three shapes live here and the split between them is the whole design:
- *
- *   IssueReportSchema  what a stranger's browser POSTs to /intake/<id>/report. UNTRUSTED, every field of it,
- *                      and bounded field by field because the endpoint is public and the body is a stack trace
- *                      somebody else's machine wrote.
- *   IssueSchema        what the daemon KEEPS: one group per fingerprint, with a count, a first/last seen and
- *                      the most recent sample. A crash loop is one of these, not ten thousand.
- *   IssuesConfigSchema what the owner configures on the automation, and IssuePublicConfigSchema the subset the
- *                      SDK is allowed to read back. Named field by field there, never by omission, the same
- *                      rule WebchatConfig's public half is built on.
- *
- * The SDK imports these as TYPES ONLY (`import type`), so zod never reaches a visitor's browser, which is why
- * the wire shapes live in this package beside the stored ones rather than being re-typed in the bundle. */
+// Three shapes: `IssueReportSchema` (untrusted, from a stranger's POST), `IssueSchema` (the daemon's per-fingerprint
+// group with a count and latest sample), and `IssuesConfigSchema`/`IssuePublicConfigSchema` (owner settings vs. what
+// the SDK reads back). Imported as types only, so zod never reaches a browser.
 
-// What kind of thing arrived. `crash` and `detection` GROUP (one fingerprint, a rising count); `report` never
-// does, because two people describing the same annoyance in their own words are two things to read.
+// `crash` and `detection` group under one fingerprint with a rising count; `report` never groups, since two people's
+// own words are two different things.
 export const IssueKindSchema = z.enum(["crash", "report", "detection"]);
 export type IssueKind = z.infer<typeof IssueKindSchema>;
 
-/* One thing that happened before the crash. Deliberately a flat {at, kind, message} rather than a per-source
- * union: the value of a breadcrumb is being READ in order next to the others, and a shape the SDK can produce
- * for a console line, a failed fetch and a route change alike is one the agent can render as a timeline
- * without knowing which instrumentations the site switched on. */
+// Flat {at, kind, message} rather than a per-source union, so breadcrumbs from any instrumentation render as one
+// ordered timeline without the agent knowing which ones fired.
 export const IssueBreadcrumbSchema = z.object({
     at: z.number().describe("When, in milliseconds."),
     kind: z.string().max(40).describe("What sort of thing it was: a console line, a request, a click, a route change."),
@@ -35,97 +21,79 @@ export const IssueBreadcrumbSchema = z.object({
 });
 export type IssueBreadcrumb = z.infer<typeof IssueBreadcrumbSchema>;
 
-// How much of the reporter we are willing to believe: nothing. Both fields are typed by whoever is reporting,
-// so they reach the model beside the content rather than above it, exactly as a Front Desk visitor's
-// `unverifiedDisplayName` does. There is no signed identity on this endpoint and there should not be one: a
-// crash handler fires on a dying page, where no sign-in ceremony can run.
+// Unverified by construction: both fields are typed by the reporter and ride beside the content, never above it. No
+// sign-in ceremony can run on a dying page.
 export const IssueReporterSchema = z.object({
     email: z.string().max(320).optional().describe("An address they typed, to reach them about it. Unverified."),
     name: z.string().max(200).optional().describe("A name they typed. Unverified, and never identity."),
 });
 export type IssueReporter = z.infer<typeof IssueReporterSchema>;
 
-// A small bag of host-supplied strings (route, app version, locale, tenant). Bounded in both dimensions
-// because it is the one open-ended field on a public endpoint, and an unbounded map is a storage bug waiting
-// for the first person who loops over it.
+// Host-supplied strings (route, version, locale, tenant); bounded in both key count and length, the one open-ended
+// field on a public endpoint.
 const CONTEXT_KEYS_MAX = 20;
 const IssueContextSchema = z
     .record(z.string().max(60), z.string().max(300))
     .refine((context) => Object.keys(context).length <= CONTEXT_KEYS_MAX, { message: `at most ${CONTEXT_KEYS_MAX} context entries` });
 
-/* ONE REPORT, AS IT ARRIVES. Everything optional except `kind` and `message`, because the three kinds carry
- * genuinely different evidence and a schema that demanded the union of them would refuse the commonest case:
- * `window.onerror` in an old browser, which has a message and very little else. */
+// One report as it arrives; only `kind`/`message` are required, since demanding every kind's fields would refuse the
+// commonest case (`window.onerror` with little else).
 export const IssueReportSchema = z.object({
     kind: IssueKindSchema.describe("A crash the SDK caught, something a person wrote in, or a problem the SDK noticed on its own."),
     message: z.string().min(1).max(1000).describe("The error's own message, or the headline of what a person reported."),
     stack: z.string().max(20_000).optional().describe("The stack, verbatim from the browser."),
     url: z.string().max(2000).optional().describe("Where it happened: the page's address, or a screen name in an app."),
-    /* THE ONE FIELD THAT REPLACES AN ENTIRE INTEGRATION. The agent has the repository, so a build's sha or tag
-     * is enough to check that commit out and read the real frames; there is nothing to upload, no artifact
-     * store, and no sourcemap pipeline to keep in step with a deploy. A site that sets nothing here still gets
-     * a grouped, readable issue: it just costs the agent a guess about which build it came from. */
+    // No artifact store or sourcemap pipeline needed: absent, the agent just guesses which build it came from.
     release: z.string().max(200).optional().describe("Which build it came from: a commit sha or a tag. With it the agent reads your real source rather than minified frames."),
     userAgent: z.string().max(400).optional().describe("What the browser said it was."),
     description: z.string().max(5000).optional().describe("What the person typed, when a person is the one reporting."),
     reporter: IssueReporterSchema.optional().describe("Who says they are reporting it. Unverified by construction."),
     breadcrumbs: z.array(IssueBreadcrumbSchema).max(40).optional().describe("What happened just before, oldest first."),
     context: IssueContextSchema.optional().describe("Whatever else the app attached: a route, a version, a locale."),
-    /* The host's own grouping override, Sentry's convention and worth keeping: an app that knows two crashes
-     * are the same thing (or knows one crash is really two) can say so, and the daemon groups on this instead
-     * of on the stack. It is hashed like everything else, never used as a filename directly. */
+    // Hashed like everything else; never used as a filename directly.
     fingerprint: z.string().max(200).optional().describe("Group by this instead of by the stack, when your app knows better than the stack does."),
 });
 export type IssueReport = z.infer<typeof IssueReportSchema>;
 
-/* The body POSTed to /intake/<id>/report: the report plus the two things the GATE needs and the report itself
- * has no business carrying, a client id to rate-limit against and the anti-bot answer. Kept out of
- * IssueReportSchema so that what gets STORED (the sample) is the evidence and not the doorman's paperwork. */
+// POSTed to /intake/<id>/report: the report plus what the gate needs (client id, anti-bot answer) but never stores —
+// keeps the stored sample pure evidence, not doorman's paperwork.
 export const IssueIngestSchema = z.object({
     report: IssueReportSchema,
-    // The SDK's own per-browser id (localStorage). Not a secret and not identity, anyone can mint one: it is
-    // the key the per-minute limit counts against, so one runaway tab cannot spend the whole day's budget.
+    // Per-minute limit key; distinct from the daily budget below.
     clientId: z.string().min(1).max(200).describe("The SDK's own id for this browser. Not a secret: it is what the rate limit counts against."),
-    // Only for `report`, and only when the automation asks for a proof of work: a crash fires on a dying page,
-    // where there is no second to spend on a puzzle and no user to wait for it.
+    // Only for `report`, and only if a proof-of-work is asked for; a crash has no second to spend on a puzzle.
     powNonce: z.string().max(400).optional(),
-    // Minted by the owner, pasted into a mobile or server SDK that has no Origin header for the allowlist to
-    // read. An abuse LABEL rather than a secret (it ships inside a mobile binary and can be pulled out of one):
-    // the real ceilings are the dedup, the rate limit and the daily budget.
+    // For a client with no Origin header; an abuse label, not a secret (ships inside a binary) — dedup, rate limit and
+    // daily budget are the real ceilings.
     key: z.string().max(200).optional(),
 });
 export type IssueIngest = z.infer<typeof IssueIngestSchema>;
 
-/* Where a group stands with the owner. `investigating` is set by the daemon when a turn is actually started
- * for it (from a wake or from the Investigate button), never guessed: it is the difference between "nobody has
- * looked at this" and "something is looking at it right now", which is the question a triage inbox is for. */
+// `investigating` is set only by the daemon when a turn actually starts (a wake, or the Investigate button); never
+// guessed, never settable by a click.
 export const IssueStatusSchema = z.enum(["open", "investigating", "resolved", "ignored"]);
 export type IssueStatus = z.infer<typeof IssueStatusSchema>;
 
-// One agent turn started for this issue. The conversation id is the link: the fleet board already knows how to
-// open one, so the inbox does not have to store anything about the run beyond which conversation it became.
+// One agent turn for this issue; the conversation id is the link, so nothing about the run itself needs storing beyond
+// it.
 export const IssueRunSchema = z.object({
     conversationId: z.string().describe("The conversation this run became."),
     at: z.number().describe("When it started, in milliseconds."),
-    // What the count stood at when this run was started, so a recurrence after a fix reads as "it came back",
-    // not as "someone already looked at this".
+    // Lets a post-fix recurrence read as "it came back", not "already looked at".
     atCount: z.number().describe("How many times it had happened when this run started."),
 });
 export type IssueRun = z.infer<typeof IssueRunSchema>;
 
-/* ONE GROUP. The id is the fingerprint and is the FILENAME, never in the body (json-dir.ts owns that rule), so
- * a body that disagrees with its own grouping cannot be written. */
+// One group; the id is the fingerprint and the filename, never in the body, so a body cannot disagree with its own
+// grouping.
 export const IssueSchema = z.object({
     kind: IssueKindSchema,
-    // The one-line headline the inbox lists it under, derived from the report rather than typed, so two
-    // recurrences of one crash cannot be filed under two names.
+    // Derived from the report, never typed, so two recurrences of one crash can't end up under two titles.
     title: z.string().min(1).max(300).describe("The one line this is listed under."),
     culprit: z.string().max(300).optional().describe("The frame it came from, when the stack named one."),
-    // Which issues automation received it. A workspace can run several (one per site), and the inbox is one
-    // list across all of them, so the group has to say which door it came in through.
+    // A workspace can run several intakes (one per site); the inbox is one list across all of them.
     automationId: entryId.describe("Which intake received it."),
-    // The site or app it came from, as the browser's Origin or the SDK's declared one; absent for a keyed
-    // client (a mobile app, a server) that has no origin to send.
+    // Absent for a keyed client (mobile app, server) with no Origin header to send.
     origin: z.string().max(400).optional().describe("Which site it came from."),
     firstSeen: z.number().describe("When it first happened, in milliseconds."),
     lastSeen: z.number().describe("When it last happened, in milliseconds."),
@@ -133,14 +101,10 @@ export const IssueSchema = z.object({
     status: IssueStatusSchema.default("open").describe("Where it stands with you."),
     statusAt: z.number().optional().describe("When the status last changed, in milliseconds."),
     release: z.string().max(200).optional().describe("The build the latest one came from."),
-    // The most recent event in full. The LATEST rather than the first, deliberately: when a crash is still
-    // happening, what it looks like now is what a fix has to reproduce, and the first one is often from a
-    // build that no longer exists.
+    // Latest, not first: a fix must match what it looks like now, not a build that may no longer exist.
     sample: IssueReportSchema.describe("The most recent one, in full."),
-    /* How many arrivals had been counted the last time this group WOKE an agent. The whole of the escalation
-     * rule lives in this one number: a group fires once when it is new, and again only when it has moved this
-     * far past its last firing. Stored rather than derived, because "how many since the last wake" is not
-     * recoverable from a count and a timestamp after a restart. */
+    // Escalation rule lives in this number: fires once when new, again only once count has moved this far past it.
+    // Stored, since a restart can't derive it from a count and timestamp.
     firedAt: z.number().optional().describe("What the count stood at the last time this woke an agent."),
     runs: z.array(IssueRunSchema).max(20).optional().describe("The turns started for it."),
 });
@@ -150,9 +114,8 @@ export type Issue = z.infer<typeof IssueSchema>;
 export const IssueSummarySchema = IssueSchema.extend({ id: entryId.describe("The issue's id, which is its fingerprint.") });
 export type IssueSummary = z.infer<typeof IssueSummarySchema>;
 
-// `invalid` is the same trust-boundary confession the approvals list makes, for the opposite reason: nothing but
-// the daemon writes these, so a file in here that will not parse is a BUG in this daemon or a half-written
-// volume, and either is worth seeing rather than silently skipping.
+// `invalid`: nothing but the daemon writes these files, so one that fails to parse is a bug in this daemon or a
+// half-written volume, worth surfacing not skipping.
 export const IssuesListSchema = z.object({
     issues: z.array(IssueSummarySchema).describe("The inbox, most recently seen first."),
     invalid: z.array(z.string()).describe("Files in the issues directory that could not be read at all."),
@@ -160,66 +123,45 @@ export const IssuesListSchema = z.object({
 export type IssuesList = z.infer<typeof IssuesListSchema>;
 
 export const IssueIdParamSchema = z.object({ id: entryId.describe("Which issue.") });
-// Triage: the owner moving one row. `investigating` is not offered here, the daemon sets it when a turn
-// actually starts, and letting a click claim it would make the one status that means something a lie.
+// `investigating` is not offered here: the daemon sets it when a turn actually starts, so a click can't fake the one
+// status that means something.
 export const IssueStatusInputSchema = z.object({
     id: entryId.describe("Which issue."),
     status: z.enum(["open", "resolved", "ignored"]).describe("Where it now stands with you."),
 });
 export type IssueStatusInput = z.infer<typeof IssueStatusInputSchema>;
 
-/* ---- the automation's own settings ----
- *
- * Present only on `issues` listener automations, ignored on every other trigger, the shape WebchatConfig
- * already established. `allowedOrigins` is NOT here: it lives on the trigger, because it is the admission gate
- * the ingest route reads rather than a rendering choice, and one gate in two places is one gate. */
+// Present only on `issues` listener automations. `allowedOrigins` is not here: it lives on the trigger, since the
+// ingest route reads it as the admission gate, not a rendering choice.
 export const IssuesConfigSchema = z.object({
-    /* The key a client with no Origin presents (a mobile app, a server, a desktop build). Minted by the daemon
-     * on upsert like the event webhook's token, and for the same reason: every sender supports "paste this
-     * string", and nothing else is available to a caller with no identity and no browser.
-     *
-     * It is an abuse LABEL, not a secret, and the difference matters: it ships inside a binary anyone can pull
-     * apart. What it buys is that a leaked key can be rotated in one click while the origin allowlist keeps
-     * covering the web. The ceilings are what actually bound the damage. */
-    ingestKey: z.string().min(1).optional().describe("The key an app with no website origin presents. Rotate it freely: the limits, not this, are what bound the damage."),
-    /* Whether a browser with no allowed origin may still report by presenting the key. Off by default: the
-     * commonest way an intake gets abused is its key ending up in a public web bundle, and the allowlist is
-     * the thing that stops that mattering. */
+    // Ingest key lives in the secrets store (`AutomationSummary.ingestKey`), not here — an abuse label the origin
+    // allowlist and ceilings actually bound, not a secret.
+    // Off by default: a leaked key in a public bundle is the commonest abuse, and the allowlist is what limits it.
     keyFromBrowsers: z.boolean().optional().describe("Let a browser report with the key alone, rather than only from a site you listed. Off unless you need it."),
-    // The whole intake's ceiling per UTC day, counted in reports that reach the store. Absent ⇒
-    // ISSUES_DAILY_MAX_DEFAULT, never uncapped, for the reason the Front Desk's own daily cap gives.
+    // Per UTC day, counted in reports that reach the store; absent means ISSUES_DAILY_MAX_DEFAULT, never uncapped.
     dailyReportMax: z.number().int().positive().optional().describe("How many reports a day this intake accepts at all."),
-    /* HOW FAR A KNOWN CRASH HAS TO GO BEFORE IT INTERRUPTS ANYONE AGAIN. A group wakes an agent when it is
-     * new, and after that only when its count has grown by this much since the last wake. Absent ⇒
-     * ISSUES_ESCALATE_AFTER_DEFAULT.
-     *
-     * This is the number that makes the whole product safe to leave on. Without it a crash loop on one popular
-     * page is an agent turn per affected browser, which is a bill rather than a bug report. */
+    // Wakes an agent on new, then again once count has grown this much since the last wake; absent means
+    // ISSUES_ESCALATE_AFTER_DEFAULT. Without a cap, a crash loop is a turn per browser.
     escalateAfter: z.number().int().positive().optional().describe("How many more times a known crash must happen before it wakes an agent again."),
-    // A proof-of-work puzzle on WRITTEN REPORTS only (a crash has no second to spend and no user to wait for
-    // it). Absent ⇒ off, leaving the origin allowlist and the ceilings as the whole boundary.
+    // Written reports only, never a crash; absent means off, leaving the allowlist and ceilings as the boundary.
     antiBot: z.enum(["pow"]).optional().describe("Make a person's browser solve a small puzzle before it accepts a written report."),
-    /* ---- the report dialog's chrome, all of it public by construction ---- */
+    // The report dialog's chrome; public by construction.
     title: z.string().max(80).optional().describe("The dialog's heading."),
     prompt: z.string().max(300).optional().describe("The line above the box they type in."),
     thanks: z.string().max(300).optional().describe("What it says once they have sent it."),
     askEmail: z.boolean().optional().describe("Ask for an address to reply to. Optional for them either way."),
-    // A hex colour, for the reason WebchatConfig's `accent` is one: the SDK derives a hover and a focus ring
-    // from its channels rather than only painting it.
+    // Hex colour; the SDK derives a hover and focus ring from its channels, not just paints it.
     accent: z
         .string()
         .regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, "accent must be a hex colour, e.g. #e47100")
         .optional(),
-    // Whether the SDK arms window.onerror / unhandledrejection at all. Absent ⇒ on: a site that embedded a
-    // crash reporter meant to report crashes.
+    // Absent means on: a site that embedded this meant to report crashes.
     captureCrashes: z.boolean().optional().describe("Catch uncaught errors automatically, as well as what people write in."),
 });
 export type IssuesConfig = z.infer<typeof IssuesConfigSchema>;
 
-/* What the SDK is told about itself, fully RESOLVED daemon-side so the bundle carries no fallback logic. Every
- * field is named here rather than spread from the config: a secret added to IssuesConfig later is invisible to
- * a stranger's browser until somebody deliberately lists it, which is the property this shape exists for.
- * `ingestKey` is conspicuously absent, a browser proves itself by its origin. */
+// Fully resolved daemon-side; every field is named here so a secret added to `IssuesConfig` later stays invisible until
+// deliberately listed. `ingestKey` is absent — a browser proves itself by origin.
 export const IssuePublicConfigSchema = z.object({
     automationId: z.string(),
     title: z.string(),
@@ -228,21 +170,18 @@ export const IssuePublicConfigSchema = z.object({
     askEmail: z.boolean(),
     accent: z.string(),
     captureCrashes: z.boolean(),
-    // "off" spelled out rather than left absent, for the reason the Front Desk's is: the SDK branches on it,
-    // and a missing field meaning "no challenge" is how one serialization bug becomes an open door.
+    // "off" spelled out, not absent: a missing field meaning no challenge is how a serialization bug opens a door.
     antiBot: z.enum(["pow", "off"]),
 });
 export type IssuePublicConfig = z.infer<typeof IssuePublicConfigSchema>;
 
-/* What the intake answers with. A short reference the reporter can be shown ("we filed this as 4f3a…"), and
- * nothing else: whether this crash is new, how often it has happened and whether it woke anybody are the
- * owner's facts, and the caller is a stranger's browser. */
+// A short reference to show the reporter ("we filed this as 4f3a…"), and nothing else: whether it's new, its count, who
+// it woke are the owner's facts, not a stranger's.
 export const IssueAcceptedSchema = z.object({ ok: z.literal(true), id: z.string() });
 export type IssueAccepted = z.infer<typeof IssueAcceptedSchema>;
 
-/* Which origins have loaded this intake's SDK, and which were turned away. The Front Desk's install probe,
- * whole, because the setup mistake is identical and so is the silence it produces: a snippet that was never
- * pasted, and one pasted on an origin the allowlist does not have, are both "an intake with no reports". */
+// Which origins loaded this intake's SDK, and which were turned away: a snippet never pasted and one pasted on a
+// disallowed origin both look like "no reports".
 export const IssueInstallSchema = z.object({
     origin: z.string(),
     allowed: z.boolean(),
@@ -253,23 +192,16 @@ export const IssueInstallsSchema = z.object({ origins: z.array(IssueInstallSchem
 export type IssueInstalls = z.infer<typeof IssueInstallsSchema>;
 export const IssueIntakeIdParamSchema = z.object({ automationId: entryId.describe("Which intake.") });
 
-/* ---- the numbers both ends need ----
- *
- * Here rather than beside the route that enforces them, for WebchatConfig's reason: the automation editor has
- * to be able to show the owner what they are already protected by, and a limit that is invisible until it is
- * hit gets filed as a bug. */
+// Constants both the editor and the route need, so a limit is visible to the owner before it is hit.
 
-/* The daily ceiling an intake gets when its owner sets none. Larger than the Front Desk's 200 because the unit
- * is different: a report is a file write and only SOMETIMES an agent turn (dedup decides), where a visitor
- * message is always a turn. High enough that a real product's bad afternoon fits inside it, low enough that a
- * script pointed at the endpoint stops being interesting within seconds. */
+// Default daily ceiling; higher than the Front Desk's 200 since a report is only sometimes a turn (dedup decides),
+// unlike a visitor message.
 export const ISSUES_DAILY_MAX_DEFAULT = 2000;
 
-/* How much a known crash has to grow before it wakes anybody again. Ten is chosen to be quiet on the tail (one
- * more person hitting a known bug is not news) and prompt on a spike: a regression that starts affecting
- * everybody crosses it almost at once, which is exactly when the second wake is worth having. */
+// Default escalation threshold; quiet on the long tail, but a spike that starts affecting everybody crosses it almost
+// immediately.
 export const ISSUES_ESCALATE_AFTER_DEFAULT = 10;
 
-// How much of one ingest body the daemon will read. A stack plus forty breadcrumbs plus a description is a few
-// kilobytes; this leaves room for a pathological framework trace without letting the endpoint be a file upload.
+// Max ingest body size; a normal report is a few KB, this leaves room for a pathological trace without becoming a file
+// upload.
 export const ISSUE_PAYLOAD_MAX = 96_000;