@intentic/sandbox-contract 1.233.0 → 1.234.0

package/src/credential-material.ts

@@ -0,0 +1,100 @@
+/* WHETHER A FILE ACTUALLY HOLDS A CREDENTIAL, the fact that `secrets.access` only guesses at from a path.
+ *
+ * The classifier next door (command-classes.ts) reads shell text, so the strongest thing it can honestly say
+ * about `sed … ~/.npmrc` is "this names a file that USUALLY holds a token". Usually is not always, and the gap
+ * is where the class earns its reputation: most `~/.npmrc` files are three lines of registry config, most
+ * `.env` files in a monorepo are ports and feature flags, `~/.ssh/known_hosts` is a list of public keys, and a
+ * file that does not exist reads nothing at all. A card raised over one of those is not a near miss, it is
+ * noise, and noise is what teaches an owner to answer the card without reading it, which is precisely how a
+ * real credential read gets waved through six weeks later.
+ *
+ * So the class is split in two. The path table says WHICH FILES ARE WORTH LOOKING AT; this says WHAT A
+ * CREDENTIAL LOOKS LIKE once one has been opened. It lives here, beside that table, because the two halves are
+ * one definition of the class and an enforcement point that has a filesystem should not have to invent the
+ * second half for itself (guard/credential-files.ts is the sandbox's fs half; a caller with no filesystem, the
+ * browser or the machine agent, simply never asks and the path stands on its name alone).
+ *
+ * PURE, over the file's own text: no fs, no path logic, nothing to configure. That keeps this package free of
+ * a runtime the editor bundle cannot have, and keeps the rule testable as a table of strings.
+ *
+ * IT ANSWERS THE EASY DIRECTION WELL AND THE HARD ONE CONSERVATIVELY. Everything below is written to say YES
+ * on anything credential-shaped, because a yes costs one card and a no costs the whole rule: the only use of
+ * this answer is to REMOVE a class the path table already added, so a false yes leaves behavior exactly as it
+ * was and a false no silently un-gates a real read.
+ */
+
+/* A KEY THAT NAMES A CREDENTIAL, AND ITS VALUE. Matched as a suffix of whatever the key is spelled as, because
+ * these files say the same thing a dozen ways and only the last word carries the meaning: `NPM_TOKEN`,
+ * `//registry.npmjs.org/:_authToken`, `"accessToken"`, `aws_secret_access_key`, `password =`.
+ *
+ * The three value arms are the three ways a value is quoted across the formats this ever sees: JSON's double
+ * quotes, a shell-ish dotenv's single quotes, and an ini file's bare rest-of-line.
+ *
+ * THE SEPARATOR MAY NOT CROSS A LINE, which is the difference between reading a file and reading a soup: with
+ * `\s*` around it, an empty `GITHUB_TOKEN=` borrows the NEXT line as its value, and a dotenv of nine blank
+ * placeholders reads as eight credentials. Every format here puts a value on its key's own line. */
+const CREDENTIAL_ASSIGNMENT =
+    /(?:auth[_-]?token|access[_-]?token|refresh[_-]?token|api[_-]?key|access[_-]?key|secret[_-]?key|client[_-]?secret|private[_-]?key|passwo?rd|passphrase|credentials?|secret|token|bearer)["']?[ \t]*[:=][ \t]*(?:"([^"\n]*)"|'([^'\n]*)'|([^\s"',;}\n]*))/gi;
+
+/* A VALUE THAT IS NOT A CREDENTIAL EVEN THOUGH ITS KEY SAYS IT IS: the empty one, the one still holding the
+ * template's own words, and the one deferring to an environment variable or a secret reference. Every dotenv
+ * that ships in a repo is made of these, and firing on `GITHUB_TOKEN=${GITHUB_TOKEN}` would put a card in front
+ * of reading a file whose entire content is the absence of a secret. */
+const PLACEHOLDER =
+    /^(?:\$\{?[\w:.-]+\}?|\{\{[^}]*\}\}|<[^>]*>|%\w+%|x{3,}|\*{3,}|\.{3,}|…|(?:your|my|our|the)[-_\s].*|change[-_]?me|replace[-_]?(?:me|this|with)|todo|tbd|fixme|none|null|nil|undefined|true|false|example|placeholder|redacted|dummy|sample|test|fake|secret|password|token|value|here)$/i;
+
+/* Shorter than any credential a service actually issues. It clears the dev-compose defaults an agent reads all
+ * day (`POSTGRES_PASSWORD=dev`, `password=x`), which are not what a card asking about credential material is
+ * for, and it is well under the shortest real token below (a 36-character npm one). */
+const MIN_VALUE = 6;
+
+/* A CREDENTIAL RECOGNISABLE WITHOUT ITS KEY: the issuers whose tokens carry their own prefix, the PEM and PuTTY
+ * headers that ARE the private key file, and a URL that carries a password in its userinfo (which is the whole
+ * content of `.git-credentials`, and the shape a `DATABASE_URL` hides one in).
+ *
+ * These are checked first and independently of any key, because half of these files have no `key = value` in
+ * them at all. */
+const TOKEN_SHAPES = [
+    /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----/,
+    /PuTTY-User-Key-File-\d/,
+    // scheme://user:password@host — the password is the point; a Sentry DSN (`https://key@host`) has no colon
+    // before the `@` and is deliberately not this.
+    /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]{3,}@/i,
+    /\bnpm_[A-Za-z0-9]{30,}/,
+    /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{30,}/,
+    /\bgithub_pat_[A-Za-z0-9_]{50,}/,
+    /\bglpat-[A-Za-z0-9_-]{16,}/,
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}/,
+    /\bsk-[A-Za-z0-9_-]{20,}/,
+    /\b(?:sk|rk)_live_[A-Za-z0-9]{16,}/,
+    /\bAKIA[0-9A-Z]{16}\b/,
+    /\bASIA[0-9A-Z]{16}\b/,
+    /\bAIza[0-9A-Za-z_-]{35}\b/,
+    /\bhf_[A-Za-z0-9]{30,}/,
+    /\bdop_v1_[a-f0-9]{60,}/,
+    // A JWT: three base64url segments, the first two of which decode from `{"` and so always begin `ey`.
+    /\bey[A-Za-z0-9_-]{10,}\.ey[A-Za-z0-9_-]{10,}\./,
+];
+
+/* A VALUE DEFERRED TO SOMEWHERE ELSE, removed before anything is read, because it is not one value but two
+ * things to get wrong. `STRIPE_SECRET={{secret:STRIPE}}` holds no credential — that is the platform's own
+ * convention for a file that must not hold one — and yet it reads as a credential twice over: the outer
+ * assignment has a substantial-looking value, and the reference's own `secret:STRIPE` is a second `key: value`
+ * inside it. Cutting them out first is simpler and steadier than teaching the value patterns to survive them. */
+const DEFERRED_VALUE = /\{\{[^}\n]*\}\}|\$\{[^}\n]*\}/g;
+
+// Does this file's text hold something worth a card? Handed the WHOLE file by its caller, which is why the
+// caller (not this) is the one that decides how much of a large file is worth reading.
+export const holdsCredentialMaterial = (file: string): boolean => {
+    const text = file.replace(DEFERRED_VALUE, "");
+    if (TOKEN_SHAPES.some((pattern) => pattern.test(text))) {
+        return true;
+    }
+    for (const match of text.matchAll(CREDENTIAL_ASSIGNMENT)) {
+        const value = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+        if (value.length >= MIN_VALUE && !PLACEHOLDER.test(value)) {
+            return true;
+        }
+    }
+    return false;
+};

package/src/history-state.ts

@@ -37,6 +37,18 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // The fleet: every conversation card, its branch, its session ids, its standing.
     { path: "agents.json", portability: "carry" },
     { path: "turns/", portability: "carry" },
+    /* THE ARMED CONDITION WATCHES, one file per watch, put back at boot (agent/watchers.ts `restoreWatchers`).
+     *
+     * Carried for the reason loops.json is: an arrangement the agent entered into on the user's behalf and
+     * that is still outstanding travels with the conversation that is waiting on it, or a restored sandbox
+     * shows a card parked on a condition nothing will ever check. It can be carried safely because the journal
+     * holds no credential, only the NAMES of the environment its check ran with (agent/watch-journal.ts); the
+     * values are re-derived on the target from whatever capabilities it actually has, so a watch landing
+     * somewhere without them fails its check honestly and ends in a wake that says so, rather than arriving
+     * with a working copy of a token the bundle was never supposed to carry. A watch whose isolated checkout
+     * did not travel (those are `derived`) is dropped by the restore rather than re-armed against a tree that
+     * is not there. */
+    { path: "watches/", portability: "carry" },
     { path: "transcripts/", portability: "carry" },
     // What each message can be put back to, a workspace checkpoint, or an isolated conversation's own commits.
     // Carried WITH the transcripts and the scopes above, because it is the join between them: without it a

package/src/hostnames.ts

@@ -14,7 +14,7 @@ export const sandboxHostname = (id: string, zone: string): string => `${sandboxS
 // The container sshd hostname the desktop-sync (Mutagen) reaches over the sandbox tunnel: `ssh-<id>.<zone>`.
 export const sshHostname = (id: string, zone: string): string => `ssh-${id}.${zone}`;
 
-/* The LOOPBACK name: `local-<id>.<zone>`, an A record pointing at 127.0.0.1.
+/* The LOOPBACK name: `<id>.local.<zone>`, resolving to 127.0.0.1 under ONE wildcard record for the whole zone.
  *
  * A public DNS name for a private address looks odd until you ask what the alternative is. A browser on the
  * same machine as the sandbox can reach its daemon in microseconds instead of crossing to a Cloudflare edge
@@ -23,9 +23,25 @@ export const sshHostname = (id: string, zone: string): string => `ssh-${id}.${zo
  * one; this can. The daemon holds the key and gets the certificate by proving control of the zone over
  * DNS-01 (there is nothing on the public internet for a CA to connect to).
  *
+ * IT IS A LABEL DEEPER THAN THE OTHER NAMES, and that is the entire point rather than a naming preference. A
+ * DNS wildcard matches ONE label, so `*.<zone>` cannot cover `<id>.local.<zone>` and `*.local.<zone>` covers
+ * every sandbox that will ever exist: one record for the platform, not one per sandbox. The shape it replaced,
+ * `local-<id>.<zone>`, needed a record each, and a zone has a hard per-record quota (Cloudflare 81045). Every
+ * OTHER per-sandbox record went away with the move to the zrok hub, so this was the last thing consuming that
+ * quota, and when the zone filled the platform could no longer write the record OR the ACME challenge beside
+ * it: the certified shortcut stopped resolving, every browser fell back to the plain-http loopback, and that
+ * transport is HTTP/1.1 with six connections per origin (see the editor's streamBudget.ts for what that cost).
+ * A quota nothing can exhaust is the fix that keeps working.
+ *
  * It discloses nothing: the id is already the leading label of the sandbox's public hostname, and the address
  * it resolves to is every machine's own loopback. */
-export const localHostname = (id: string, zone: string): string => `local-${id}.${zone}`;
+export const localHostname = (id: string, zone: string): string => `${id}.${LOCAL_LABEL}.${zone}`;
+
+// The label the loopback names live under, so the wildcard has something to be a wildcard OF.
+export const LOCAL_LABEL = "local";
+
+// The single record that answers for all of them. Never per-sandbox, never reaped.
+export const localWildcardHostname = (zone: string): string => `*.${LOCAL_LABEL}.${zone}`;
 
 // What that record points at, and the reason it is safe to publish: every resolver on earth gets 127.0.0.1.
 export const LOCAL_ADDRESS = "127.0.0.1";

package/src/index.ts

@@ -19,6 +19,7 @@ import { grokContract } from "./contracts/grok.contract.js";
 import { historyContract } from "./contracts/history.contract.js";
 import { intenticContract } from "./contracts/intentic.contract.js";
 import { inventoryContract } from "./contracts/inventory.contract.js";
+import { issuesContract } from "./contracts/issues.contract.js";
 import { logsContract } from "./contracts/logs.contract.js";
 import { loopsContract } from "./contracts/loops.contract.js";
 import { panelsContract } from "./contracts/panels.contract.js";
@@ -66,6 +67,7 @@ export { webextContract } from "./contracts/webext.contract.js";
 export { runnerContract } from "./contracts/runner.contract.js";
 export { intenticContract } from "./contracts/intentic.contract.js";
 export { inventoryContract } from "./contracts/inventory.contract.js";
+export { issuesContract } from "./contracts/issues.contract.js";
 export { logsContract } from "./contracts/logs.contract.js";
 export { REQUEST_ID_EVIDENCE_ROUTE, REQUEST_ID_HEADER } from "./request-id.js";
 export { loopsContract } from "./contracts/loops.contract.js";
@@ -108,6 +110,7 @@ export * from "./agent-catalog.js";
 export * from "./agent-run-model.js";
 export * from "./capability-env.js";
 export * from "./command-classes.js";
+export * from "./credential-material.js";
 export * from "./capability-secrets.js";
 export * from "./conversation-ids.js";
 export * from "./documents.js";
@@ -151,6 +154,7 @@ export * from "./schemas/history.js";
 export * from "./schemas/hosts.js";
 export * from "./schemas/intentic.js";
 export * from "./schemas/inventory.js";
+export * from "./schemas/issues.js";
 export * from "./schemas/logs.js";
 export * from "./schemas/loops.js";
 export * from "./schemas/maintenance.js";
@@ -213,6 +217,7 @@ export const sandboxContract = {
     history: historyContract,
     workspace: workspaceContract,
     inventory: inventoryContract,
+    issues: issuesContract,
     logs: logsContract,
     loops: loopsContract,
     panels: panelsContract,

package/src/routes.test.ts

@@ -77,7 +77,9 @@ describe(`routeShapes`, () => {
     it(`changes the fingerprint when a field is added`, () => {
         const before = routeShapes(shaped(z.object({ a: z.string() })))[`vpn.list`];
         const after = routeShapes(shaped(z.object({ a: z.string(), b: z.number() })))[`vpn.list`];
-        expect(before).toBeDefined();
+        // A fingerprint is a string, and saying so is what makes the line below mean something: with `before`
+        // undefined and `after` a real shape, "they differ" is true for the wrong reason.
+        expect(before).toEqual(expect.any(String));
         expect(after).not.toBe(before);
     });
 
@@ -99,7 +101,7 @@ describe(`routeShapes`, () => {
         const one = z.object({ a: z.string().default(`x`) });
         const asOutput = routeShapes(shaped(one))[`vpn.list`];
         const asInput = routeShapes({ vpn: { list: oc.route({ method: "GET", path: "/vpn" }).input(one) } })[`vpn.list`];
-        expect(asOutput).toBeDefined();
+        expect(asOutput).toEqual(expect.any(String));
         expect(asInput).not.toBe(asOutput);
     });
 

package/src/runtime-state.ts

@@ -69,6 +69,22 @@ const RUNTIME_DOMAINS = [
     // is why the daemon rate-limits this domain rather than pushing every mutation (see runtime-watch.ts).
     { domain: "subagents", invalidates: [["subagents"]] },
 
+    /* THE MACHINES ON THE OTHER END OF A SOCKET, three domains that are one story: the user's computers, the
+     * browsers holding the extension, and this sandbox's runners.
+     *
+     * Announced, and about as announced as a fact can be. "Online" here is not sampled, inferred or timed out
+     * of, it IS a socket in this process: the hub accepts one, replaces one, drops one on a failed heartbeat, or
+     * cuts one on a revoke, and those four moments are the entire set of ways the answer changes. Nothing on
+     * disk moves, no pane appears, and no other feed could carry it.
+     *
+     * They land on `capabilities` because a host or webext card's state is LITERALLY the hub's answer
+     * (handlers/host.ts: `hub.online(id) ? active : pending`), which is what a person watches while they paste a
+     * pairing command into a laptop. That wait is the whole reason these are here: it was three seconds of
+     * polling per card, running only because nobody had told the browser that the daemon already knew. */
+    { domain: "hosts", invalidates: [["capabilities"], ["computers"]] },
+    { domain: "webext", invalidates: [["capabilities"]] },
+    { domain: "runners", invalidates: [["runners"]] },
+
     /* The post queue, when the DAEMON moves it rather than the owner. Approving is the owner's own mutation and
      * refetches itself, but everything after that happens while nobody is touching the page: a held post coming
      * due, a Discord send landing, a publish turn writing back what went out. Those are the moments the row on

package/src/schemas/agent.ts

@@ -74,7 +74,7 @@ export type AgentOrigin = z.infer<typeof AgentOriginSchema>;
  * gate); never sent by a client. Chat and loops are absent deliberately: both begin with the owner's own
  * click, and holding the owner's work in their own queue is a queue entry that says nothing (the same argument
  * fireAutomation's `cleared` makes about a by-hand fire). */
-export const WakeSourceSchema = z.enum(["schedule", "event", "listener", "webchat", "workspace", "workflow"]);
+export const WakeSourceSchema = z.enum(["schedule", "event", "listener", "webchat", "issues", "workspace", "workflow"]);
 export type WakeSource = z.infer<typeof WakeSourceSchema>;
 // One admission verdict the owner can configure: let it run, hold it for approval, or refuse it outright.
 export const AdmissionRuleSchema = z.enum(["allow", "hold", "deny"]);
@@ -96,7 +96,11 @@ export const CommandClassSchema = z.enum([
      * owner wrote no rule, which is why it is separate from files.destructive rather than a shade of it:
      * `rm -rf build` is ordinary work in a disposable container and `rm -rf /` is the end of the machine. */
     "system.destructive",
-    // Names credential material: a .env file, an ssh key, ~/.aws/credentials, .npmrc, a stored token file.
+    /* READS credential material: a `{{secret:NAME}}` reference (which becomes the value on the way into the
+     * process), or a file that actually holds one — a dotenv, a private key, ~/.aws/credentials, an npmrc.
+     * "Actually" is load-bearing and is checked rather than assumed where the caller can open the file: an
+     * npmrc with no token in it, a dotenv of ports, a public key, a path that is not there, are none of them
+     * this class, however much they look like it from the command line. See command-classes.ts. */
     "secrets.access",
     // Publishes outward and irreversibly: npm/pnpm/yarn/cargo publish, gh release create, docker push.
     "package.publish",
@@ -114,6 +118,15 @@ export const AdmissionPolicySchema = z.object({
     event: AdmissionRuleSchema.default("allow"),
     listener: AdmissionRuleSchema.default("allow"),
     webchat: AdmissionRuleSchema.default("allow"),
+    /* THE ONE SOURCE THAT HOLDS BY DEFAULT, and the exception is argued rather than assumed. A Front Desk wake
+     * runs the read-only Front Desk persona: a stranger drives the prompt and the toolbox is a shelf of two.
+     * A bug-report wake is the opposite on both counts, it is pointed at the repository with the powers to
+     * change it, and the brief is a stack trace and a sentence somebody else's browser wrote.
+     *
+     * Held is not blocked: the wake sits in the same approvals queue every other hold uses, with the issue's
+     * own title on the card, and one click runs it. An owner who wants their crashes fixed while they sleep
+     * sets this to `allow` deliberately, which is the direction that decision should have to be made in. */
+    issues: AdmissionRuleSchema.default("hold"),
     workspace: AdmissionRuleSchema.default("allow"),
     workflow: z.enum(["allow", "deny"]).default("allow"),
 });

package/src/schemas/automations.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema } from "./agent.js";
 import { AgentSummarySchema } from "./agents.js";
 import { entryId } from "./internal.js";
+import { IssuesConfigSchema } from "./issues.js";
 // An automation wakes the agent autonomously: the daemon's scheduler fires each enabled automation on its
 // trigger, runs the optional guard command (a shell command in the workspace; non-zero exit skips the wake),
 // then runs one agent turn with the prompt. The manifest is user config; run history is daemon-recorded.
@@ -108,8 +109,14 @@ export const TriggerSchema = z.discriminatedUnion("kind", [
             .min(1)
             .optional()
             .describe("Narrow it to one branch, for the sources that have branches. Absent means every branch of the repositories it matches."),
-        // webchat only: the website origins allowed to POST to the widget endpoint. Absent/empty ⇒ none admitted.
-        allowedOrigins: z.array(z.string()).optional().describe("Which websites may reach the chat widget. Absent or empty admits nobody."),
+        /* The two gateway-less browser sources, `webchat` and `issues`: the website origins allowed to POST to
+         * the public endpoint. Absent/empty ⇒ none admitted, on both. One field rather than one per source,
+         * because it is the same question asked of the same header by the same kind of caller, and an intake
+         * whose allowlist lived somewhere else would be a second gate to keep in step with the first. */
+        allowedOrigins: z
+            .array(z.string())
+            .optional()
+            .describe("Which websites may reach the public endpoint, the chat widget's or the bug reporter's. Absent or empty admits nobody."),
     }),
     // `repo` narrows to events whose span touches one workspace repo ("root" or a repo id); absent ⇒ any.
     z.object({
@@ -266,6 +273,11 @@ export const AutomationSchema = z.object({
     prompt: z.string().min(1).describe("What the woken agent is told."),
     // The Front Desk widget's settings, `webchat` listener automations only, ignored on every other trigger.
     webchat: WebchatConfigSchema.optional().describe("Settings for the public chat widget, for an automation that answers visitors."),
+    // The bug intake's settings, `issues` listener automations only, ignored on every other trigger. Its own
+    // field rather than a shared "public endpoint" bag: the two sources answer different questions (a chat's
+    // greeting and access model, an intake's dedup ceiling and ingest key) and a union of both would be a
+    // schema where most fields are wrong for whichever source is reading it.
+    issues: IssuesConfigSchema.optional().describe("Settings for the bug reporter, for an automation that takes crash reports from your own sites and apps."),
     /* NARROW THIS ONE JOB FURTHER than the persona it runs as, raw tool names, and the escape hatch under the
      * shelves rather than the way anyone is expected to answer this question.
      *

package/src/schemas/extension-updates.ts

@@ -315,8 +315,10 @@ export const ExtensionProcessParamSchema = z.object({
 });
 export const ExtensionProcessStatusSchema = z.object({
     name: z.string().describe("Which process."),
-    running: z.boolean().describe("Whether it is up."),
+    running: z.boolean().describe("Whether it is up. False with a port means it crashed and the supervisor is waiting to retry it."),
     port: z.number().optional().describe("The port it was given."),
+    restarts: z.number().optional().describe("How many times it died and was brought back since it was started. A growing number is a service in trouble."),
+    lastExitCode: z.number().optional().describe("How it last exited, when it has crashed at least once."),
     previewUrl: z.string().optional().describe("Where to open it, when it has an address."),
 });
 export type ExtensionProcessStatus = z.infer<typeof ExtensionProcessStatusSchema>;

package/src/schemas/issues.ts

@@ -0,0 +1,279 @@
+// issues: 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. */
+
+// 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.
+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. */
+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."),
+    message: z.string().max(300).describe("What it said, already truncated by the SDK."),
+});
+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.
+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.
+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. */
+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. */
+    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. */
+    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. */
+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.
+    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.
+    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.
+    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. */
+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.
+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".
+    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. */
+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.
+    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.
+    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.
+    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."),
+    count: z.number().describe("How many times this exact thing has arrived."),
+    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.
+    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. */
+    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."),
+});
+export type Issue = z.infer<typeof IssueSchema>;
+
+// The list row: the stored group plus its filename id (the fingerprint).
+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 drafts 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.
+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."),
+});
+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.
+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. */
+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. */
+    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.
+    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. */
+    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.
+    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 ---- */
+    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.
+    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.
+    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. */
+export const IssuePublicConfigSchema = z.object({
+    automationId: z.string(),
+    title: z.string(),
+    prompt: z.string(),
+    thanks: z.string(),
+    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.
+    antiBot: z.enum(["pow", "off"]),
+});
+export type IssuePublicConfig = z.infer<typeof IssuePublicConfigSchema>;
+
+// The proof-of-work challenge, the same shape and the same solver as the Front Desk's.
+export const IssueChallengeSchema = z.object({ salt: z.string(), difficulty: z.number().int().positive() });
+export type IssueChallenge = z.infer<typeof IssueChallengeSchema>;
+
+/* 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. */
+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". */
+export const IssueInstallSchema = z.object({
+    origin: z.string(),
+    allowed: z.boolean(),
+    lastSeenAt: z.number(),
+    loads: z.number(),
+});
+export const IssueInstallsSchema = z.object({ origins: z.array(IssueInstallSchema) });
+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. */
+
+/* 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. */
+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. */
+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.
+export const ISSUE_PAYLOAD_MAX = 96_000;