@intentic/sandbox-contract 1.169.0 → 1.171.0

package/src/hostnames.ts

@@ -43,18 +43,16 @@ export const CATCH_ALL = { service: "http_status:404" } as const;
 // covers exactly one level), where <panel> is `<repo>` or `<repo>--<app>` and <sandboxId> pins the hostname to
 // this sandbox (the shared intentic zone hosts many sandboxes; without the id two users' panels would collide).
 // Port-forward scheme: `port-<slot>-<sandboxId>.<zone>` — the same shape with a `port-` prefix, where <slot>
-// is one of the sandbox's fixed forward slots (see PORT_SLOTS), not the port number itself: slots keep the
-// intentic-provided path's minted routes bounded and warm while dev servers churn ephemeral ports.
+// is one of the sandbox's forward slots (portSlotsFromToken in ./tunnel-ids), not the port number itself:
+// slots keep the intentic-provided path's minted routes bounded and warm while dev servers churn ephemeral
+// ports. The slot labels are salted with the connect token rather than being the letters a…h, so a forwarded
+// port's hostname is not derivable from the (public) sandbox id alone — see tunnel-ids for why that matters.
 //
 // A *label* is the first-DNS-label prefix before `-<sandboxId>` (`preview-<panel>` / `port-<slot>`) — the unit
 // the platform's /sandbox/preview-route mints, so one endpoint serves both schemes.
 export const previewLabel = (panel: string): string => `preview-${panel}`;
 export const portLabel = (slot: string): string => `port-${slot}`;
 
-// The fixed per-sandbox forward slots. Eight is deliberate: enough for a monorepo's worth of concurrent dev
-// servers, and the hard cap on preview DNS records a sandbox can ever cost the shared intentic zone.
-export const PORT_SLOTS = ["a", "b", "c", "d", "e", "f", "g", "h"] as const;
-
 // The hostname a label resolves to — what the platform's /sandbox/preview-route mints from the label alone.
 export const labelHostname = (label: string, id: string, zone: string): string => `${label}-${id}.${zone}`;
 export const previewHostname = (panel: string, id: string, zone: string): string => labelHostname(previewLabel(panel), id, zone);

package/src/index.ts

@@ -5,6 +5,7 @@ import { agentContract } from "./contracts/agent.contract.js";
 import { agentsContract } from "./contracts/agents.contract.js";
 import { automationsContract } from "./contracts/automations.contract.js";
 import { capabilitiesContract } from "./contracts/capabilities.contract.js";
+import { choresContract } from "./contracts/chores.contract.js";
 import { ciContract } from "./contracts/ci.contract.js";
 import { claudeContract } from "./contracts/claude.contract.js";
 import { codexContract } from "./contracts/codex.contract.js";
@@ -37,6 +38,7 @@ export { agentContract } from "./contracts/agent.contract.js";
 export { agentsContract } from "./contracts/agents.contract.js";
 export { automationsContract } from "./contracts/automations.contract.js";
 export { capabilitiesContract } from "./contracts/capabilities.contract.js";
+export { choresContract } from "./contracts/chores.contract.js";
 export { ciContract } from "./contracts/ci.contract.js";
 export { claudeContract } from "./contracts/claude.contract.js";
 export { codexContract } from "./contracts/codex.contract.js";
@@ -86,6 +88,7 @@ export const sandboxContract = {
     agents: agentsContract,
     automations: automationsContract,
     capabilities: capabilitiesContract,
+    chores: choresContract,
     ci: ciContract,
     claude: claudeContract,
     codex: codexContract,

package/src/schemas.ts

@@ -122,6 +122,12 @@ export const AgentTurnSchema = z
         // 'acceptEdits' auto-accepts file edits; 'bypassPermissions' runs everything. The agent can move
         // itself between modes mid-turn (EnterPlanMode/ExitPlanMode), which rides back as a `mode` frame.
         permissionMode: PermissionModeSchema.optional(),
+        /* Narrows the turn to these tool names (the SDK option of the same name — not to be confused with the
+         * daemon's MCP `tools`, which are servers). Absent ⇒ every tool the runtime has, which is what an
+         * owner-driven chat wants. Set by the automation dispatchers from Automation.allowedTools: a wake driven
+         * by an OUTSIDE message runs bypassPermissions like any other automation turn, so for a public Doorbell
+         * this list is the actual boundary — prompt wording is advice, an empty toolbox is not. */
+        allowedTools: z.array(z.string().min(1)).optional(),
         effort: z.string().optional(),
         thinking: z.boolean().optional(),
         // The opt-in editor context chip: what the user is looking at, folded into the prompt daemon-side.
@@ -286,6 +292,7 @@ export type AgentSummary = z.infer<typeof AgentSummarySchema>;
 // mutated agents back. The browser drops any roster older than the newest it has applied, and holds its own
 // pending change until a roster at or past the revision that applied it arrives. See useAgents.ts.
 export const AgentsListSchema = z.object({ agents: z.array(AgentSummarySchema), rev: z.number() });
+export type AgentsList = z.infer<typeof AgentsListSchema>;
 export const AgentIdSchema = z.object({ id: z.string().min(1) });
 // archive's input: the agents to take off the board. Absent `ids` ⇒ every finished agent that is archivable
 // right now (the lane header's "Clear"); unarchive always names its ids (a restore, or a bulk archive's undo).
@@ -353,6 +360,11 @@ export const LandConflictSchema = z.object({
     repo: z.string(),
     paths: z.array(LandConflictPathSchema),
     clean: z.number(),
+    // The branch the user's checkout is on — the thing the agent has to rebase onto. Carried because only the
+    // daemon can see it: an isolated turn's worktree is mounted over the agent's whole view, so the resolution
+    // errand could otherwise only tell it to go and read the name off `git worktree list`. Absent on a detached
+    // HEAD or a vanished checkout, where there is no name to give.
+    mainBranch: z.string().optional(),
 });
 export type LandConflict = z.infer<typeof LandConflictSchema>;
 
@@ -414,7 +426,7 @@ export type UsageWindow = z.infer<typeof UsageWindowSchema>;
 // An account's headroom: EVERY window the provider reports, read together, plus when the reading was taken.
 // All of them, not the binding one, because "which pool is binding" changes between turns and a reader
 // comparing accounts needs the same pools on every row. How the reading is TAKEN is per provider and stops at
-// the daemon's readers: Claude's rides the turn's own stream, ChatGPT's and Google's are pulled through
+// the daemon's readers: Claude's rides the turn's own stream, ChatGPT's, Google's and Kimi's are pulled through
 // CLIProxyAPI's credential-scoped management call. All of them are control requests, so none costs tokens.
 //
 // Within one window utilization only climbs, so an un-reset window stays a valid FLOOR however old it is; past
@@ -426,13 +438,45 @@ export const AccountUsageSchema = z.object({
 });
 export type AccountUsage = z.infer<typeof AccountUsageSchema>;
 
+/* THE LAST TIME A PROVIDER ACTUALLY REFUSED A TURN — the other half of "can I run on this", and the half no
+ * meter can supply.
+ *
+ * A snapshot above is POLLED and therefore always a floor: read at turn end (Claude) or on a five-minute sweep
+ * (the routed subscriptions), and account-wide, so every other client on the plan spends the same pools without
+ * this sandbox hearing about it. A refusal is the opposite kind of fact — observed, exact, and timestamped by
+ * the only event that proves the plan said no. Between them they answer a question neither can alone: a green
+ * meter beside "refused a turn 4 minutes ago" means the reading is stale, not that the account has room.
+ *
+ * Keyed by PROVIDER rather than by account, because that is the resolution the daemon honestly has. A native
+ * Claude turn knows which account served it and names it; a routed turn does not — CLIProxyAPI picks the auth
+ * file itself and only refuses once every credential it holds is cooling down, which makes the refusal a fact
+ * about the provider in the first place.
+ *
+ * `kind` is read off what the provider SAID, not off the frame code the harness filed it under, because those
+ * two disagree: Kimi answers a spent plan with `403 You've reached your usage limit for this billing cycle`,
+ * which the CLI prints under "Failed to authenticate" and the stream codes as a refused credential. Sending
+ * someone to reconnect a perfectly good account is the cost of believing the code over the sentence. */
+export const ProviderRefusalSchema = z.object({
+    // Epoch MS, matching AccountUsage.measuredAt — the two are read side by side.
+    at: z.number(),
+    kind: z.enum(["limit", "auth"]),
+    // The provider's own sentence, verbatim. It is the only part that says WHICH pool or WHICH credential.
+    message: z.string(),
+    // The account that was serving, when the daemon knows it (native turns only — see above).
+    account: z.string().optional(),
+});
+export type ProviderRefusal = z.infer<typeof ProviderRefusalSchema>;
+
+export const ProviderRefusalsSchema = z.object({ refusals: z.record(z.string(), ProviderRefusalSchema) });
+export type ProviderRefusals = z.infer<typeof ProviderRefusalsSchema>;
+
 // One connected subscription in the translator. `name` is CLIProxyAPI's auth-file name — the stable store key a
 // disconnect addresses — and `label` the sign-in identity it reported (the account email, else the file name).
 export const TranslatorAccountSchema = z.object({
     name: z.string(),
     label: z.string(),
     // The same headroom an OauthAccount carries, on the same field, for the same reason: the account rows are
-    // one list to the reader. Optional because a provider whose quota this sandbox cannot read (Grok, Kimi) —
+    // one list to the reader. Optional because a provider whose quota this sandbox cannot read (Grok) —
     // or one that did not answer — must still render as the connected account it is, with a dot instead of a
     // ring.
     usage: AccountUsageSchema.optional(),
@@ -552,6 +596,7 @@ export const OauthAccountSchema = z.object({
 });
 export type OauthAccount = z.infer<typeof OauthAccountSchema>;
 export const OauthAccountListSchema = z.object({ accounts: z.array(OauthAccountSchema) });
+export type OauthAccountList = z.infer<typeof OauthAccountListSchema>;
 // Address one account of a provider (disconnect, and the turn's `account`).
 export const AccountIdSchema = z.object({ id: z.string().min(1) });
 // Rename one account of a provider whose credential the sandbox owns (Claude, Kimi). Blank ⇒ the daemon falls
@@ -631,6 +676,7 @@ export const SessionSummarySchema = z.object({
     // own heading is noise, not evidence. See AgentMatchSchema for the same field on the fleet's side.
     snippet: z.string().optional(),
 });
+export type SessionSummary = z.infer<typeof SessionSummarySchema>;
 export const SessionsListSchema = z.object({ sessions: z.array(SessionSummarySchema) });
 
 // ---- settings: per-sandbox agent settings (.intentic/settings.json) ----
@@ -1222,24 +1268,37 @@ export type FileDiff = z.infer<typeof FileDiffSchema>;
 
 // ---- workspace tree + files ----
 
-// One node of the full /work filesystem tree the agent sees (untracked + generated files included), distinct
-// from the git-tracked listing. `path` is root-relative with forward slashes so it feeds straight back to the
-// file route. Recursive via zod's getter form (so the type is inferred, not hand-annotated).
-export const WorkspaceTreeEntrySchema = z.object({
+/* One node of the full /work filesystem tree the agent sees (untracked + generated files included), distinct
+ * from the git-tracked listing. `path` is root-relative with forward slashes so it feeds straight back to the
+ * file route.
+ *
+ * Recursive, and the type is declared rather than inferred. Zod's getter form does infer one, but it collapses
+ * to `{}` below the first level of nesting — so `entry.children[0].name` type-checked as an index-signature
+ * read on both sides of the wire, and the tree walker's own suite was reading a `hidden` field off entries
+ * that has never existed there without the compiler minding. The interface is the contract; the schema
+ * validates against it, and z.ZodType makes a divergence between the two an error here. */
+export interface WorkspaceTreeEntry {
+    readonly name: string;
+    readonly path: string;
+    readonly type: "file" | "dir";
+    readonly size?: number | undefined;
+    // Ignored-by-tooling (node_modules, .git, .gitignore'd paths, browser profiles): the client grays the row.
+    readonly ignored?: boolean | undefined;
+    // A DIR without `children` was listed but not descended into — because it's ignored, or because the walk's
+    // breadth-first budget stopped above it. Either way the client lazy-loads it via /workspace/children on
+    // expand, so "not loaded yet" and "empty directory" (`children: []`) stay distinguishable.
+    readonly children?: readonly WorkspaceTreeEntry[] | undefined;
+}
+export const WorkspaceTreeEntrySchema: z.ZodType<WorkspaceTreeEntry> = z.object({
     name: z.string(),
     path: z.string(),
     type: z.enum(["file", "dir"]),
     size: z.number().optional(),
-    // Ignored-by-tooling (node_modules, .git, .gitignore'd paths, browser profiles): the client grays the row.
     ignored: z.boolean().optional(),
-    // A DIR without `children` was listed but not descended into — because it's ignored, or because the walk's
-    // breadth-first budget stopped above it. Either way the client lazy-loads it via /workspace/children on
-    // expand, so "not loaded yet" and "empty directory" (`children: []`) stay distinguishable.
     get children() {
         return z.array(WorkspaceTreeEntrySchema).optional();
     },
 });
-export type WorkspaceTreeEntry = z.infer<typeof WorkspaceTreeEntrySchema>;
 export const WorkspaceTreeSchema = z.object({
     root: z.string(),
     tree: z.array(WorkspaceTreeEntrySchema),
@@ -1300,14 +1359,20 @@ export type WorkspaceClassification = z.infer<typeof WorkspaceClassificationSche
 // The workspace-search wire shape — shared by the daemon's /workspace/search route and the web client.
 // (Implementation detail, not part of the contract: the daemon backs this route with a resident in-process iq
 // engine; the engine is interchangeable behind this shape.) Groups are relevance-ranked (best first, never path
-// order); each hit carries the match-reason tags the fused engines contributed. `start`/`end` are char offsets
-// within `text` so clients highlight without re-finding the needle.
+// order); each hit carries the match-reason tags the fused engines contributed, and the char spans within `text`
+// that matched, so clients highlight without re-finding the needle.
 export const WorkspaceSearchQuerySchema = z.object({
     query: z.string().min(2).max(512),
     // Search verbs only — anchor/git verbs (outline, context, log, who, …) are CLI-only surface. Natural language
     // has no verb of its own: `q` classifies the query and answers it semantically when the words call for it.
     mode: z.enum(["q", "find", "files", "def", "refs", "sym", "ast"]).optional(),
     includeIgnored: z.stringbool().optional(),
+    // How `find` reads the query — the three switches every editor's search box has (VSCode: Aa, ab, .*).
+    // `literal` treats it as fixed text instead of a regex; `caseSensitive` off means case-INSENSITIVE, not
+    // ripgrep's smart case.
+    literal: z.stringbool().optional(),
+    word: z.stringbool().optional(),
+    caseSensitive: z.stringbool().optional(),
     limit: z.coerce.number().int().positive().optional(),
     after: z.string().optional(),
 });
@@ -1316,11 +1381,14 @@ export const WorkspaceSearchTagSchema = z.object({
     score: z.number().optional(),
 });
 export type WorkspaceSearchTag = z.infer<typeof WorkspaceSearchTagSchema>;
+export const WorkspaceSearchSpanSchema = z.object({ start: z.number(), end: z.number() });
+export type WorkspaceSearchSpan = z.infer<typeof WorkspaceSearchSpanSchema>;
 export const WorkspaceSearchHitSchema = z.object({
     line: z.number(),
     text: z.string(),
-    start: z.number().optional(),
-    end: z.number().optional(),
+    // Every matched span in `text`, in order — a text search marks all of them, the way an editor does. Empty
+    // where the LINE is the match and no span of it is (a semantic or definition hit reports none).
+    spans: z.array(WorkspaceSearchSpanSchema),
     tags: z.array(WorkspaceSearchTagSchema),
     // Enclosing symbol ("createWidget (fn)") — parent-document context so the reader often needs no follow-up.
     context: z.string().optional(),
@@ -1342,12 +1410,19 @@ export type WorkspaceSearchFreshness = z.infer<typeof WorkspaceSearchFreshnessSc
 export const WorkspaceSearchResultSchema = z.object({
     mode: z.string(),
     total: z.number(),
+    // Files the query matched in total, which `groups` reports only for the page it carries — the count a
+    // results panel puts beside the hit total ("218 results in 61 files").
+    files: z.number(),
     shown: z.number(),
     groups: z.array(WorkspaceSearchGroupSchema),
     freshness: WorkspaceSearchFreshnessSchema,
     truncated: z.boolean(),
     cursor: z.string().optional(),
     hint: z.string().optional(),
+    // What the engine did with the query that the query did not ask for — a pattern rerun as literal text
+    // because it is not valid regex, grep-style escapes rewritten, a language filter that matched no files. The
+    // text surface has always printed this above the results; a JSON caller could not see it at all.
+    note: z.string().optional(),
     // Code-graph neighbors of the top hits (definition anchors + the strongest caller of each).
     related: z.array(z.string()).optional(),
     // Ranked `path:line` anchors that placed but were NOT shown, best first — the answer often sits at rank 5–13,
@@ -1961,6 +2036,10 @@ export const ExtensionSummarySchema = z.object({
     // Image-baked first-party extension (no git checkout, not removable) vs a git-installed capability — the
     // web hides the uninstall affordance for baked ones.
     builtin: z.boolean(),
+    // The owner's switch (.intentic/extension-enablement.json). A disabled extension is still listed — that's
+    // what makes it switchable back on — but the daemon wires none of its contributions up and the web host
+    // doesn't activate it.
+    enabled: z.boolean(),
 });
 export type ExtensionSummary = z.infer<typeof ExtensionSummarySchema>;
 export const ExtensionsListSchema = z.object({ extensions: z.array(ExtensionSummarySchema) });
@@ -1977,6 +2056,9 @@ export const ExtensionSettingsInputSchema = z.object({
     id: z.string(),
     settings: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
 });
+// Flip one extension on or off. Persisted by publisher.name (like settings), so the choice outlives the
+// checkout; the daemon's immediate half of the flip — declared processes — converges in the same handler.
+export const ExtensionEnabledInputSchema = z.object({ id: z.string(), enabled: z.boolean() });
 // One declared background process (contributes.processes) — status/start/stop, addressed by the capability
 // entry id + the manifest's process name. Undeclared names are NOT_FOUND, the manifest-honesty rule again.
 export const ExtensionProcessParamSchema = z.object({ id: z.string(), name: z.string() });
@@ -2064,12 +2146,130 @@ export const TriggerSchema = z.discriminatedUnion("kind", [
 ]);
 export type Trigger = z.infer<typeof TriggerSchema>;
 
+/* The Doorbell widget's settings — everything about the embeddable chat that isn't the automation's prompt.
+ * Present only on `webchat` listener automations; the trigger keeps `allowedOrigins` because that one is the
+ * admission gate the message route reads, not a rendering choice.
+ *
+ * Split deliberately into what the WIDGET may read (title/greeting/accent/position/access/googleClientId/
+ * turnstileSiteKey — all public by construction, they ship to a stranger's browser) and what only the daemon
+ * may read (turnstileSecret). GET /webchat/<id>/config serves the first group by naming it, never by omitting
+ * the second: a field added here is invisible to the widget until it is listed there. */
+export const WebchatConfigSchema = z.object({
+    // `public` admits anyone; `google` refuses a message that carries no verifiable Google ID token. Absent ⇒
+    // public — a Doorbell with no access setting is the anonymous support box it looks like.
+    access: z.enum(["public", "google"]).optional(),
+    // Ask an anonymous visitor for a display name before the first message. Cosmetic: the name is typed, so it
+    // reaches the model as untrusted `displayName`, never as identity.
+    requireName: z.boolean().optional(),
+    /* The bot ceiling. `turnstile` is Cloudflare's (invisible, needs the site's own keys); `pow` is a
+     * hashcash-style challenge the daemon issues and the widget solves in a worker, so a site with no
+     * Cloudflare account still has something. Absent ⇒ off: the origin allowlist and the rate limit are then
+     * the whole boundary, which is the right default for an internal or invite-only page. */
+    antiBot: z.enum(["turnstile", "pow"]).optional(),
+    turnstileSiteKey: z.string().optional(),
+    turnstileSecret: z.string().optional(),
+    // The site's OWN Google OAuth web client id. It cannot be intentic's: Google Identity Services only issues
+    // a token to an authorized JavaScript origin, and intentic's client can't list every customer domain.
+    googleClientId: z.string().optional(),
+    // Widget chrome. `accent` is any CSS colour the host page can render; `position` picks the launcher corner.
+    title: z.string().max(80).optional(),
+    greeting: z.string().max(500).optional(),
+    accent: z.string().max(40).optional(),
+    position: z.enum(["top-right", "top-left", "bottom-right", "bottom-left"]).optional(),
+    /* Two ceilings on top of the route's fixed per-minute window, because a public endpoint's real exposure is
+     * cost, not request rate: `dailyMessageMax` caps the whole automation per UTC day, `conversationMessageMax`
+     * caps one visitor thread for its lifetime.
+     *
+     * `dailyMessageMax` absent ⇒ WEBCHAT_DAILY_MAX_DEFAULT, not uncapped. Every message here is an agent turn
+     * billed to the owner, and the per-minute window bounds the RATE without bounding the DAY — twenty a minute,
+     * sustained, is tens of thousands of turns before anyone notices. A Doorbell nobody configured should not be
+     * able to spend that, so the safe number is the one you get for free and the owner raises it deliberately.
+     * `conversationMessageMax` stays optional-means-uncapped: it is per visitor thread, which the daily ceiling
+     * already bounds in aggregate. */
+    dailyMessageMax: z.number().int().positive().optional(),
+    conversationMessageMax: z.number().int().positive().optional(),
+    // (WEBCHAT_DAILY_MAX_DEFAULT, below the schema, is the number `dailyMessageMax` falls back to.)
+    // How long a visitor thread keeps resuming the same conversation before the next message starts a fresh
+    // one. Absent ⇒ WEBCHAT_SESSION_TTL_MS (the daemon's default).
+    sessionTtlMinutes: z.number().int().positive().optional(),
+});
+export type WebchatConfig = z.infer<typeof WebchatConfigSchema>;
+
+/* The daily agent-turn ceiling a Doorbell gets when its owner sets none. Lives here rather than beside the
+ * route that enforces it because both ends need the number: the daemon to apply it, and the automation editor
+ * to show the owner what they are already protected by (an invisible limit is one people hit and file as a bug).
+ *
+ * 200 is chosen to be irrelevant to real support traffic and decisive against a script. A Doorbell answering
+ * two hundred questions in one UTC day is a busy one; a scripted flood reaches that in ten seconds and then
+ * stops costing anything. */
+export const WEBCHAT_DAILY_MAX_DEFAULT = 200;
+
+/* ---- the widget wire: three shapes GET /webchat/<id>/config, GET …/challenge and POST …/message speak ----
+ *
+ * They live here, beside the stored config they derive from, because the Doorbell widget is a SECOND client of
+ * this daemon — a bundle running on a stranger's page — and the reason this package exists is that both ends of
+ * a wire read one definition. The widget imports these as types only (`import type`), so zod never reaches a
+ * visitor's browser. */
+
+// What the widget is told about itself. Fully RESOLVED — every default is applied daemon-side, so the widget
+// carries no fallback logic and one place decides what an unset field means. Everything here is public by
+// construction: it ships to any browser that can reach the endpoint from an allowed origin.
+export const WebchatPublicConfigSchema = z.object({
+    automationId: z.string(),
+    title: z.string(),
+    greeting: z.string(),
+    accent: z.string(),
+    position: z.enum(["top-right", "top-left", "bottom-right", "bottom-left"]),
+    access: z.enum(["public", "google"]),
+    requireName: z.boolean(),
+    // "off" is spelled out rather than left absent: the widget branches on this, and a missing field that means
+    // "no challenge" is the kind of default that turns one serialization bug into an open door.
+    antiBot: z.enum(["turnstile", "pow", "off"]),
+    turnstileSiteKey: z.string().optional(),
+    googleClientId: z.string().optional(),
+});
+export type WebchatPublicConfig = z.infer<typeof WebchatPublicConfigSchema>;
+
+// A proof-of-work challenge: find a nonce whose SHA-256 of `${salt}:${nonce}` starts with `difficulty` zero
+// bits. Issued per visitor conversation, spent on its first message.
+export const WebchatChallengeSchema = z.object({ salt: z.string(), difficulty: z.number().int().positive() });
+export type WebchatChallenge = z.infer<typeof WebchatChallengeSchema>;
+
+// One visitor message. `conversationId` is the widget's own localStorage id — it threads the visitor's messages
+// into ONE sandbox conversation, so it is the thread key, not a secret (anyone can mint one; the origin
+// allowlist, the challenge and the rate limit are the gate).
+export const WebchatMessageSchema = z.object({
+    conversationId: z.string().min(1).max(200),
+    content: z.string().min(1),
+    // What the visitor TYPED as their name. Never identity — it reaches the model tagged as unverified, and a
+    // signed-in visitor's verified name comes from the ID token instead.
+    displayName: z.string().max(200).optional(),
+    // A Google ID token from the site's own client id, verified daemon-side against Google's JWKS.
+    idToken: z.string().optional(),
+    // The anti-bot answer, whichever kind the config asked for. Checked once per conversation, not per message.
+    turnstileToken: z.string().optional(),
+    powNonce: z.string().optional(),
+    // The widget's own transcript, sent ONLY on the first message of a thread — after that the sandbox
+    // conversation resumes and carries its own context.
+    history: z
+        .array(z.object({ author: z.string().optional(), content: z.string() }))
+        .max(50)
+        .optional(),
+});
+export type WebchatMessage = z.infer<typeof WebchatMessageSchema>;
+
 export const AutomationSchema = z.object({
     id: entryId,
     trigger: TriggerSchema,
     // Shell command run in the workspace root before waking; exit 0 ⇒ wake, non-zero ⇒ the run is "skipped".
     guard: z.string().min(1).optional(),
     prompt: z.string().min(1),
+    // The Doorbell widget's settings — `webchat` listener automations only, ignored on every other trigger.
+    webchat: WebchatConfigSchema.optional(),
+    // The tool names this automation's wake may call (AgentTurnSchema.allowedTools). The reason it exists: a
+    // webchat automation is driven by strangers, and an automation turn runs bypassPermissions by default — so
+    // the allowlist, not the prompt's wording, is what bounds what an injected instruction can reach.
+    allowedTools: z.array(z.string().min(1)).optional(),
     // Which provider adapter serves the wake; absent ⇒ claude. Same dispatch as a chat turn (AgentTurnSchema.agent).
     agent: AgentProviderSchema.optional(),
     // Which harness (agentic loop) runs the wake; absent ⇒ native. Same semantics as AgentTurnSchema.harness.
@@ -2427,10 +2627,9 @@ export type PortForwardResult = z.infer<typeof PortForwardResultSchema>;
 // it lists from /system/browsers with the pages it has open (BrowserSessionSchema below).
 //
 // `activityAt` (epoch ms of the session's last output) and `exitCode` (the LAST window's exit status, absent
-// while that pane still lives) are what let a finished session be READ rather than merely listed: the panel's
-// Recent-terminals popover orders by the one and reports the other ("exit 1 · 1h ago"), and the daemon's
-// retention sweep ages sessions out by the same clock. 0 is "tmux didn't say" — treated as unknown by both,
-// never as 1970.
+// while that pane still lives) describe a session beyond "it exists": the panel's work popover orders its live
+// rows by the one and dates them off it, and the daemon's retention sweep ages sessions out by the same clock.
+// 0 is "tmux didn't say" — treated as unknown by both, never as 1970.
 export const TerminalSessionSchema = z.object({
     name: z.string(),
     label: z.string().optional(),
@@ -2626,6 +2825,7 @@ export const InfoSchema = z.object({
     latest: z.string().optional(),
     updateAvailable: z.boolean().optional(),
 });
+export type Info = z.infer<typeof InfoSchema>;
 
 // A daemon-minted session (system.session): the steady-state browser credential, exchanged for a verified
 // Google ID token so Google UI is a sign-in moment instead of an hourly renewal. `expiresAt` is epoch ms —
@@ -2932,3 +3132,211 @@ export const PushConfigQuerySchema = z.object({ endpoint: z.string().url().optio
 // the question being asked. A count separates "your OS swallowed it" from "nothing was sent at all".
 export const PushTestSchema = z.object({ delivered: z.number().int().nonnegative() });
 export type PushTest = z.infer<typeof PushTestSchema>;
+
+// ---- maintenance: the standing evidence a chore is decided from ----
+
+/* THE DAEMON SERVES FACTS; THE BROWSER DECIDES. Everything below is measurement — what a tool reported, what the
+ * manifests say, when a chore last ran. Not one field here says "you should do something", and that is the whole
+ * boundary: which chore is DUE is computed by @intentic/sandbox-contract/chores, which both the Maintenance view and its rail
+ * badge run, so the number on the tile and the reason in the panel can never disagree. Put the verdict on the wire
+ * instead and a daemon one image behind would be quietly arguing with the browser about what needs doing.
+ *
+ * The split inside the evidence is by COST, not by subject:
+ *   probes   subprocesses (pnpm outdated, pnpm audit, knip, jscpd) — minutes, so they are cached on disk with a
+ *            TTL and refreshed by a background runner. A route hit never waits on one.
+ *   signals  things the daemon already knows — the resident iq index's health ranking, the package manifests it
+ *            reads for the dependency graph, its own node version. Recomputed per request; all of it is cheap. */
+
+export const PROBE_IDS = ["outdated", "audit", "knip", "jscpd"] as const;
+export const ProbeIdSchema = z.enum(PROBE_IDS);
+export type ProbeId = z.infer<typeof ProbeIdSchema>;
+
+// One dependency the registry has moved past. `kind` is the SEMVER distance, which is the whole reason this is
+// not one number: forty patch releases behind is a morning's work and one major is a project.
+export const OutdatedPackageSchema = z.object({
+    name: z.string(),
+    current: z.string(),
+    latest: z.string(),
+    kind: z.enum(["major", "minor", "patch"]),
+    // "dependencies" / "devDependencies" / "optionalDependencies" — a dev-only major is a different risk.
+    section: z.string(),
+});
+export type OutdatedPackage = z.infer<typeof OutdatedPackageSchema>;
+
+// One advisory, reduced to what a decision needs. No CVSS vector and no reference list: those are for reading on
+// the advisory page, and carrying them would put a kilobyte of prose per finding on every poll of this route.
+export const AdvisorySchema = z.object({
+    name: z.string(),
+    severity: z.enum(["critical", "high", "moderate", "low", "info"]),
+    title: z.string(),
+    // The range that fixes it, when the advisory names one. Absent ⇒ no patch published yet, which is the case
+    // where a chore must NOT offer to bump and say so instead.
+    patched: z.string().optional(),
+    // Whether it reaches a production dependency path. A build-time-only tool's transitive CVE is a different
+    // problem, and the chore's prompt says so rather than treating every advisory alike.
+    dev: z.boolean(),
+});
+export type Advisory = z.infer<typeof AdvisorySchema>;
+
+// knip's counts, by the kind of thing it found unreachable. Counts plus a sample rather than the full list: the
+// agent re-runs knip itself against the live tree (a list from a probe hours old would send it at files that are
+// already gone), so what travels here only has to be enough to decide whether the turn is worth starting.
+export const DeadCodeSchema = z.object({
+    files: z.number().int().nonnegative(),
+    exports: z.number().int().nonnegative(),
+    types: z.number().int().nonnegative(),
+    dependencies: z.number().int().nonnegative(),
+    devDependencies: z.number().int().nonnegative(),
+    // A handful of the unreferenced files, for the panel to show instead of asking the reader to take "31" on faith.
+    sample: z.array(z.string()),
+});
+export type DeadCode = z.infer<typeof DeadCodeSchema>;
+
+// jscpd's headline plus the biggest clones. `percentage` is of scanned lines, which is the figure a threshold is
+// worth setting against — a clone COUNT grows with the repo and would mean something different every quarter.
+export const DuplicationSchema = z.object({
+    percentage: z.number(),
+    clones: z.number().int().nonnegative(),
+    top: z.array(z.object({ lines: z.number().int().nonnegative(), first: z.string(), second: z.string() })),
+});
+export type Duplication = z.infer<typeof DuplicationSchema>;
+
+/* One probe's cached result. The three states are deliberately distinct, because a panel that collapses them
+ * lies about the most important case:
+ *   ok           the tool ran and reported. `facts` carries its findings — including "nothing found", which is
+ *                a real answer and the one that keeps a chore quiet.
+ *   unavailable  the tool is not part of this repo (knip is not a devDependency, there is no lockfile to audit).
+ *                Not a failure and not evidence of health: the chore renders as unmeasured, and can never badge.
+ *   failed       the tool ran and broke — a network-less audit, a jscpd that ran out of memory. Says so, with
+ *                the tail of what it printed, rather than reading as "clean".
+ * Merging `unavailable` into `ok`-with-zeros is how a maintenance surface ends up reporting a green repository
+ * it has never actually measured. */
+export const ProbeStateSchema = z.enum(["ok", "unavailable", "failed"]);
+export type ProbeState = z.infer<typeof ProbeStateSchema>;
+
+// The findings, discriminated by which probe produced them. Absent while the probe has never completed, and on
+// `unavailable`/`failed` — a reader must go through `state` to reach facts, so there is no shape in which a
+// missing measurement can be mistaken for a zero.
+export const ProbeFactsSchema = z.discriminatedUnion("id", [
+    z.object({ id: z.literal("outdated"), packages: z.array(OutdatedPackageSchema) }),
+    z.object({ id: z.literal("audit"), advisories: z.array(AdvisorySchema) }),
+    z.object({ id: z.literal("knip"), deadCode: DeadCodeSchema }),
+    z.object({ id: z.literal("jscpd"), duplication: DuplicationSchema }),
+]);
+export type ProbeFacts = z.infer<typeof ProbeFactsSchema>;
+
+export const ProbeResultSchema = z.object({
+    id: ProbeIdSchema,
+    state: ProbeStateSchema,
+    // When the probe last COMPLETED — the age the panel shows, and what the runner's TTL is measured from.
+    ranAt: z.number(),
+    // How long it took. Shown because a seven-minute jscpd is why the tier-2 refresh is weekly, and a reader
+    // deciding whether to force a refresh deserves to know what they are asking for.
+    tookMs: z.number().int().nonnegative(),
+    facts: ProbeFactsSchema.optional(),
+    // Why it is unavailable, or how it failed — the tail of the tool's own output. Never invented here.
+    reason: z.string().optional(),
+});
+export type ProbeResult = z.infer<typeof ProbeResultSchema>;
+
+// One workspace package as its manifest declares it — what the daemon already reads to build the dependency
+// graph, carried through so chores can reason about the repo's own shape without a probe. `documented` is the
+// one derived field: whether docs/architecture/<dir>/doc.md exists, a stat per package.
+export const ChorePackageSchema = z.object({
+    dir: z.string(),
+    name: z.string(),
+    // The manifest's `engines` map, verbatim — the runtime chore compares it against what the daemon is running.
+    engines: z.record(z.string(), z.string()).optional(),
+    dependencies: z.array(z.string()),
+    devDependencies: z.array(z.string()),
+    documented: z.boolean(),
+});
+export type ChorePackage = z.infer<typeof ChorePackageSchema>;
+
+/* The cheap half of the evidence: what the daemon knows without starting anything. `hotspots` and `keyModules`
+ * are the same rankings GET /workspace/health serves, capped tighter — a chore only ever asks whether a file has
+ * ENTERED the top of the ranking, so a leaderboard is enough and a full report per repo per poll is not. */
+/* WHAT THIS REPOSITORY IS MADE OF — the facts that decide whether a chore is a QUESTION worth asking of it at
+ * all, as opposed to whether the answer happens to be yes.
+ *
+ * The distinction is the difference between a maintenance surface that reads as attentive and one that reads as
+ * generic. "Re-read the documentation against the code" in a repository with no documentation is not a chore
+ * that is currently clear — it is a chore that will never make sense here, and showing it teaches the owner that
+ * this list was written by someone who had not looked. Same for a Docker chore with no Dockerfile, or a CI chore
+ * with no pipeline.
+ *
+ * These are all paths, deliberately: presence of a FILE is checkable, cheap, and cannot be argued with, which is
+ * the same evidence-over-identity rule the extension activation facts follow. Every field is a list rather than a
+ * boolean where the paths themselves are worth showing — a chore that says "not applicable: no Dockerfile" is
+ * useful, and one that says "3 Dockerfiles: ./Dockerfile, _apps/web/Dockerfile, …" is more so. */
+export const ChoreShapeSchema = z.object({
+    // Architecture documents that actually exist (docs/architecture/**/doc.md), capped — the count is what
+    // matters, and the drift survey needs to know there is something to re-read.
+    docs: z.array(z.string()),
+    dockerfiles: z.array(z.string()),
+    // CI pipeline definitions: .github/workflows/*.yml, .gitlab-ci.yml, and the other single-file conventions.
+    ci: z.array(z.string()),
+    // Whether dependencies are resolved to a lockfile — what makes an audit mean anything.
+    lockfile: z.boolean(),
+    // A package.json at the repo root. The gate for every chore whose subject is the JavaScript dependency tree:
+    // a Rust or Go repository has no majors to be behind on and no engines field to be pinned by, and offering it
+    // those chores would be this surface guessing at what it is looking at.
+    packageManifest: z.boolean(),
+});
+export type ChoreShape = z.infer<typeof ChoreShapeSchema>;
+
+export const ChoreSignalsSchema = z.object({
+    packages: z.array(ChorePackageSchema),
+    shape: ChoreShapeSchema,
+    hotspots: z.array(WorkspaceHotspotSchema),
+    keyModules: z.array(WorkspaceKeyModuleSchema),
+    totals: z.object({ files: z.number(), symbols: z.number(), complexity: z.number(), hotspots: z.number() }),
+    // Whether the index these rankings came from is current. A chore must not fire on a half-built index, and
+    // this is how the browser knows to hold its verdict rather than act on a partial ranking.
+    indexed: z.boolean(),
+});
+export type ChoreSignals = z.infer<typeof ChoreSignalsSchema>;
+
+// What a finished chore turn left behind — written by the agent, read back to decide whether the chore is still
+// due. `clean` is the load-bearing one: an agent that looked and found the tool's findings to be false positives
+// must be able to say so, or the next poll starts the same turn again forever.
+export const ChoreOutcomeSchema = z.enum(["acted", "reported", "clean"]);
+export type ChoreOutcome = z.infer<typeof ChoreOutcomeSchema>;
+
+/* One chore's history in one repo. The DIGEST is what makes this a debounce rather than a suppression: it is a
+ * hash of the evidence that was standing when the turn ran, so a chore whose evidence has since changed is due
+ * again on its own merits while one whose evidence is unchanged stays quiet — with the run still visible in the
+ * panel, saying when it ran and what it concluded. Nothing here can hide a chore from the view; it only decides
+ * whether the rail is allowed to speak. */
+export const ChoreLedgerEntrySchema = z.object({
+    repo: z.string(),
+    chore: z.string(),
+    ranAt: z.number(),
+    runId: z.string(),
+    outcome: ChoreOutcomeSchema,
+    digest: z.string(),
+    // Set by the owner from the panel — the chore stays visible and stays out of the badge until this passes.
+    // Distinct from opting out, which is the absence of the chore from `enabled` in the sandbox's settings.
+    snoozedUntil: z.number().optional(),
+});
+export type ChoreLedgerEntry = z.infer<typeof ChoreLedgerEntrySchema>;
+
+// GET /chores — every discovered repo's standing evidence, plus the ledger, in one read. One route rather than
+// one per repo because the rail badge scans ALL of them on a timer, and N requests a minute to answer "is
+// anything due" is the kind of poll that shows up in a battery graph.
+export const ChoresReportSchema = z.object({
+    repos: z.array(z.object({ repo: z.string(), probes: z.array(ProbeResultSchema), signals: ChoreSignalsSchema })),
+    ledger: z.array(ChoreLedgerEntrySchema),
+    // The daemon's own runtime, for the chore that asks whether this sandbox is running something end-of-life.
+    // Read off the process rather than a manifest: what is INSTALLED is the fact that matters, and an `engines`
+    // range is a wish.
+    node: z.string(),
+});
+export type ChoresReport = z.infer<typeof ChoresReportSchema>;
+
+// POST /chores/probe — force one probe to re-run now, ahead of its TTL. Returns immediately; the runner does the
+// work and the next GET /chores carries the result, the same shape the panel already polls.
+export const ChoreProbeRequestSchema = z.object({ repo: z.string().min(1), id: ProbeIdSchema });
+// POST /chores/ledger — record a run, or snooze. Written daemon-side rather than by the browser so a chore turn
+// started from anywhere (the panel, an automation, the agent itself) lands in one ledger.
+export const ChoreLedgerWriteSchema = ChoreLedgerEntrySchema;