@intentic/sandbox-contract 1.231.0 → 1.233.0

package/src/schemas/drafts.ts

@@ -0,0 +1,108 @@
+// drafts: agent-proposed posts awaiting owner approval (.intentic/config/drafts/<id>.json)
+import { z } from "zod";
+import { entryId } from "./internal.js";
+// One JSON file per draft. The AGENT creates drafts with its normal file tools, it can't call daemon routes,
+// the same split as the environment proposal, while the daemon edits/deletes them on the owner's behalf, so
+// the two writers never share a file. The id IS the filename (entryId charset ⇒ path-safe); the body never
+// carries it. Posting is the agent's job too (there is no typed publish path): a "publish approved drafts"
+// automation wakes the agent for due drafts, which posts via the platform skills and flips the status.
+
+export const DraftStatusSchema = z.enum(["proposed", "approved", "posting", "posted", "failed"]);
+export type DraftStatus = z.infer<typeof DraftStatusSchema>;
+// The on-disk file body. proposed (agent) → approved (owner) → posting (publisher, set BEFORE acting so a dead
+// turn can't double-post) → posted | failed. Reject = delete the file; retry = re-approve a failed draft.
+export const DraftSchema = z.object({
+    // Which skill posts it: "x" | "reddit" | "youtube" | "discord" | …, a bare string so new platforms need
+    // no contract change; an unknown platform simply fails at posting time.
+    platform: z
+        .string()
+        .min(1)
+        .describe("Where it should go. A plain name, so a new site needs no change here; an unknown one simply fails when it tries to post."),
+    /* WHOSE NAME THIS GOES OUT UNDER, a PersonaSchema id, handed to the publish turn as AgentTurnSchema.actsAs.
+     * Required in practice for every platform outside DIRECT_PUBLISH_PLATFORMS, and the reason is the whole
+     * shape of turnPersona: publishing through a browser needs a logged-in account, and an UNATTENDED turn that
+     * names no persona is denied every account there is. Without this field the publisher could only wake such a
+     * turn, one structurally unable to reach the login the post needs, which read from inside the turn as "this
+     * account is not connected" and cost two approved posts before anyone traced it back here.
+     *
+     * A PERSONA RATHER THAN AN ACCOUNT ID, because that is the vocabulary the rest of the system already speaks:
+     * `actsAs` is the only pin turnPersona honours, and a card carries the workspace scope the turn also needs to
+     * write this file's own status back. Naming the account directly would invent a second way to say the same
+     * thing, and the two would disagree the first time a card's accounts changed.
+     *
+     * The daemon never guesses it. One site can be connected several times over, five Reddit logins here, and
+     * picking for the owner means picking wrong in public, with no undo. A draft that needs a turn and names
+     * nobody is failed with that sentence instead of sent. */
+    actsAs: entryId
+        .optional()
+        .describe(
+            "Whose name it goes out under. Needed for anywhere that requires being logged in, because an unwatched turn naming nobody is allowed no account at all. Never guessed: one site can be connected five times over, and picking for you means picking wrong in public with no undo.",
+        ),
+    content: z.string().min(1).describe("The post itself."),
+    // Reddit posts / YouTube uploads need one.
+    title: z.string().optional().describe("A title, where the site wants one."),
+    /* Where on the platform: subreddit / Discord channel id / community. OR the URL of the thing this draft
+     * replies to. A URL target means the draft is a reply, and on reddit the difference between a thread's
+     * address and one comment's permalink is the difference between talking to the room and answering the
+     * person: the publisher opens exactly this and replies where it lands. */
+    target: z
+        .string()
+        .optional()
+        .describe(
+            "Where on the site: a community, a channel. Or the address of the thing this replies to, in which case it is a reply, and on some sites the difference between a thread's address and one comment's is the difference between talking to the room and answering the person.",
+        ),
+    // Workspace-relative attachment paths, e.g. ".intentic/config/drafts/media/chart.png".
+    media: z.array(z.string()).optional().describe("Anything to attach, as workspace paths."),
+    // Suggested post time (epoch ms, the at/nextRun convention). Optional, the agent may propose without a
+    // date and the owner sets one at approval; an approved draft with no date posts as soon as it's picked up.
+    scheduledAt: z
+        .number()
+        .optional()
+        .describe(
+            "When it should go out, in milliseconds. An agent may propose without one and you set it when approving; an approved draft with no time goes as soon as it is picked up.",
+        ),
+    // Agent-written files only need platform + content; status defaults, the rest are optional, so a
+    // well-formed proposal never lands in `invalid` just for omitting bookkeeping fields.
+    status: DraftStatusSchema.default("proposed").describe(
+        "Where it is: proposed by the agent, approved by you, being sent, sent, or failed. Rejecting is deleting it; retrying is approving a failed one again.",
+    ),
+    createdAt: z.number().optional().describe("When it was written, in milliseconds."),
+    // When sending STARTED, stamped with status "posting". The publisher needs it to tell a send that is under
+    // way from one whose run died mid-flight, and those two are indistinguishable from the due time, a post
+    // scheduled for last week is not a post that has been sending since last week.
+    postingAt: z
+        .number()
+        .optional()
+        .describe(
+            "When sending started, in milliseconds. Needed to tell a send that is under way from one whose run died mid-flight, which the scheduled time cannot: a post due last week is not a post that has been sending since last week.",
+        ),
+    postedAt: z.number().optional().describe("When it went out, in milliseconds."),
+    // Where it landed, when the platform hands back an address for it. The one thing a posted row can offer
+    // that reading the draft cannot: the post itself, to go and look at.
+    postedUrl: z
+        .string()
+        .optional()
+        .describe(
+            "Where it landed, when the site hands back an address. The one thing a sent draft can offer that reading it cannot: the post itself, to go and look at.",
+        ),
+    // Why posting failed; set with status "failed". Written for the owner to read in the queue, so it is a
+    // sentence rather than a code.
+    error: z.string().optional().describe("Why it failed, written as a sentence for a person to read rather than as a code."),
+});
+export type Draft = z.infer<typeof DraftSchema>;
+// The list row / upsert input: the file body plus its filename id.
+export const DraftSummarySchema = DraftSchema.extend({ id: entryId.describe("The draft's id.") });
+export type DraftSummary = z.infer<typeof DraftSummarySchema>;
+// `invalid` = filenames that failed to parse. Agent-written files are a trust boundary, without this a typo'd
+// draft would silently never post.
+export const DraftsListSchema = z.object({
+    drafts: z.array(DraftSummarySchema).describe("The queue."),
+    invalid: z
+        .array(z.string())
+        .describe(
+            "Drafts that could not be read at all. Listed rather than skipped, because an agent writes these files directly and a malformed one would otherwise never post and never say why.",
+        ),
+});
+export type DraftsList = z.infer<typeof DraftsListSchema>;
+// entryId, not a bare string: the id becomes a filename under .intentic/config/drafts/.
+export const DraftIdParamSchema = z.object({ id: entryId.describe("Which draft.") });

package/src/schemas/environment.ts

@@ -0,0 +1,276 @@
+// environment: the overlay Dockerfile extending the sandbox image
+import { z } from "zod";
+// The approved file is DAEMON-COMPOSED: pinned FROM + capability fragments + the owner-approved custom section.
+// The agent drafts one file per thing it needs (.intentic/config/environment.d/<tool>.Dockerfile, custom-section
+// content only, no FROM) with its normal file tools, and the daemon folds those into the single proposal file
+// (.intentic/config/environment.Dockerfile) the owner reads. The owner approves it in the browser, which stores it as
+// the custom file and recomposes the approved artifact whose sha256 the rebuild executor pins. Both composed
+// files are written only when the composition CHANGES, see writeComposed, and the read loop it exists to end.
+// Status is derived, never stored:
+// applied = sha256(approved) === appliedHash; pending rebuild = approved present but hashes differ; proposed =
+// proposal present with a hash different from custom's.
+
+const environmentFileSchema = z.object({ content: z.string(), hash: z.string() });
+/* ---- environment DRIFT: what the live container has that the image did not put there ----
+ *
+ * Anything installed outside /work dies with the container, and transcript mining showed the same tools being
+ * reinstalled session after session (cargo-xwin six times, a Windows rustup target eight) before anyone thought
+ * to bake them. Drift is the daemon OBSERVING that gap rather than trusting the model to report it: apt installs
+ * read from dpkg's own log, everything else from system paths newer than the container itself. Two channels
+ * because they are disjoint by construction — dpkg unpacks files with their archive mtimes, so an mtime sweep
+ * cannot see apt, and nothing apt does lands under the swept prefixes' hand-installed corners. */
+export const EnvironmentDriftSchema = z.object({
+    // When this container was created (PID 1's start). A snapshot whose bornAt is not the running container's
+    // describes a container that no longer exists, and every reader must treat it as no drift at all.
+    bornAt: z.number(),
+    // When the probe ran.
+    at: z.number(),
+    // Debian packages installed since the container was born, from /var/log/dpkg.log.
+    apt: z.array(z.string()),
+    // System paths (outside /work) newer than the container, collapsed so a browser download is one entry.
+    paths: z.array(z.string()),
+});
+export type EnvironmentDrift = z.infer<typeof EnvironmentDriftSchema>;
+// How a runtime install was made, which decides whether the daemon can draft a Dockerfile step for it
+// mechanically (apt/cargo/npm/rustup-target) or only surface it for a person to route (pip belongs in a venv or
+// a Debian package, "other" is a curl|sh whose replay could embed anything).
+export const RuntimeInstallKindSchema = z.enum(["apt", "pip", "cargo", "npm", "rustup-target", "playwright", "gem", "pipx", "go", "other"]);
+export type RuntimeInstallKind = z.infer<typeof RuntimeInstallKindSchema>;
+/* One tool's runtime-install history across sessions: the ledger entry behind the recurrence signal. Sessions
+ * are the unit of recurrence — a session that retries an install five times needed it once — and the entry
+ * survives container recreates (the file lives under /work), which is exactly what makes "installed again in a
+ * fresh container" observable at all. */
+export const RuntimeInstallSchema = z.object({
+    tool: z.string(),
+    kind: RuntimeInstallKindSchema,
+    // Distinct conversation ids that installed it, capped; length is the recurrence count that gates drafting.
+    sessions: z.array(z.string()),
+    // The most recent install commands, capped, secrets already masked to references by the harness.
+    commands: z.array(z.string()),
+    firstAt: z.number(),
+    lastAt: z.number(),
+    count: z.number(),
+    // The owner rejected an auto-drafted step for this tool: never propose it again until this is cleared.
+    declinedAt: z.number().optional(),
+});
+export type RuntimeInstall = z.infer<typeof RuntimeInstallSchema>;
+export const RuntimeInstallsFileSchema = z.object({
+    installs: z.array(RuntimeInstallSchema),
+    // The last drift snapshot, persisted so a daemon restart does not blank the card until the next sweep.
+    drift: EnvironmentDriftSchema.optional(),
+});
+export type RuntimeInstallsFile = z.infer<typeof RuntimeInstallsFileSchema>;
+// A ledger entry as the Environment card shows it: recurrence joined with whether the install is present in the
+// LIVE container (drift-corroborated), already drafted for approval, or previously declined.
+export const EnvironmentRecurringSchema = z.object({
+    tool: z.string(),
+    kind: RuntimeInstallKindSchema,
+    sessions: z.number(),
+    lastAt: z.number(),
+    live: z.boolean(),
+    drafted: z.boolean().optional(),
+    declined: z.boolean().optional(),
+});
+export type EnvironmentRecurring = z.infer<typeof EnvironmentRecurringSchema>;
+export const EnvironmentSchema = z.object({
+    proposal: environmentFileSchema.optional(),
+    // The owner-approved agent-written custom section (.intentic/config/environment.custom.Dockerfile).
+    custom: environmentFileSchema.optional(),
+    approved: environmentFileSchema.optional(),
+    // sha256 of the overlay the running container was built from (SANDBOX_ENVIRONMENT_HASH); absent = stock image.
+    appliedHash: z.string().optional(),
+    // config.sandbox.name, the UI derives the rebuild one-liner's slug from it.
+    container: z.string().optional(),
+    // What the live container has that the image did not put there; absent until the first sweep of this container.
+    drift: EnvironmentDriftSchema.optional(),
+    // Runtime installs worth the owner's attention: recurring across sessions, or present-and-doomed right now.
+    recurring: z.array(EnvironmentRecurringSchema).optional(),
+});
+export type Environment = z.infer<typeof EnvironmentSchema>;
+export const EnvironmentApproveSchema = z.object({ hash: z.string().min(1) });
+/* ---- environment CONTENTS: what the sandbox has, as opposed to how it was built ----
+ *
+ * The overlay above answers "what was added on top, and do you approve it?". Nobody opens the Environment tab
+ * asking that, they ask "can this sandbox compile my Rust app / transcode a video / drive a browser?", and a
+ * build recipe is a bad answer to it: it is install plumbing, it names packages rather than abilities, and it is
+ * only the DELTA, so an inventory read off it alone would claim a sandbox has ffmpeg and no Node.
+ *
+ * So this is a second read of the same sandbox, and its authority is different in a way that matters: NAMES,
+ * GROUPING and RATIONALE come from the recipe (which is where the agent wrote them), while PRESENCE and VERSION
+ * come from asking the environment itself. That split is what makes it honest. A version is never parsed out of
+ * an install line, half the entries pin nothing, and a pinned number is a lie the moment something is approved
+ * but not yet rebuilt, so an item whose tools cannot be probed carries no version at all rather than a guess.
+ * And presence is OBSERVED, which is what makes per-item state exact without diffing anything: an item the
+ * recipe contains and the probe cannot find is precisely one that arrives with the next rebuild.
+ */
+
+const environmentToolSchema = z.object({
+    // The binary as it is invoked (`rustc`, `ffmpeg`), because that is what somebody types next.
+    name: z.string(),
+    // What the binary itself reports, absent when it is not installed (yet) or answers no version flag.
+    version: z.string().optional(),
+});
+export const EnvironmentItemSchema = z.object({
+    id: z.string(),
+    // The block's own name, how the thing is referred to, not the packages it happens to install.
+    name: z.string(),
+    /* WHY IT IS HERE, which is also whether the reader may remove it: `custom` is what an agent asked for and the
+     * owner approved for this workspace, `capability` is the cost of a capability they turned on, `base` comes
+     * with every sandbox and is nobody's decision. */
+    origin: z.enum(["custom", "capability", "base"]),
+    // Which capability/extension/pack pulled it in, the answer to "why do I have this?" for an origin the
+    // reader did not choose item by item.
+    originLabel: z.string().optional(),
+    // Observed, not inferred: `active` means the probe found it, `after-rebuild` that the recipe has it and the
+    // container does not, `awaiting-approval` that it is in a proposal nobody has approved yet.
+    state: z.enum(["active", "after-rebuild", "awaiting-approval"]),
+    // Every binary this one block puts on PATH, with the version each reports. Usually one; a toolchain is several.
+    tools: z.array(environmentToolSchema),
+    // How many further packages the block installs that are not commands anyone runs (libraries, headers). A
+    // count rather than a list: eleven rows of `libssl-dev` is noise, "+11 packages" is the same fact.
+    extras: z.number().optional(),
+    // One standalone line, from the block's opening comment, the part everyone reads.
+    purpose: z.string().optional(),
+    /* That comment in full, as prose, absent when the line above already is the whole of it. NOT the remainder
+     * after the line: `purpose` is a summary of this (a parenthetical dropped, an over-long sentence cut back to
+     * its claim), so the two overlap by design and it is the reader's view that picks one. Long, the rationale
+     * for a toolchain runs to paragraphs, so it lives behind a disclosure rather than on the row. */
+    detail: z.string().optional(),
+    // The block's own instruction lines, for the reader who wants to see exactly what runs.
+    commands: z.string().optional(),
+});
+export type EnvironmentItem = z.infer<typeof EnvironmentItemSchema>;
+export const EnvironmentContentsSchema = z.object({ items: z.array(EnvironmentItemSchema) });
+export type EnvironmentContents = z.infer<typeof EnvironmentContentsSchema>;
+/* ---- portability: exporting a sandbox's environment and restoring it into a fresh one ----
+ *
+ * A sandbox is four stores, not one: `/work` (the workspace and the daemon's manifests), `/history` (every
+ * repo's real git dir, the fleet registry, the ledgers), the CONTAINER (the built overlay image plus the env
+ * the run contract replays) and the AI-provider credential root. A bundle carries the first two, declared entry
+ * by entry in WORKSPACE_STATE_FILES / HISTORY_STATE_FILES. It cannot carry the other two, and the honest
+ * consequence is that an import ends in a REPORT rather than a claim of equivalence, the container has no
+ * docker socket, so only the host can rebuild the image the overlay describes.
+ *
+ * The bundle's manifest (BundleManifestSchema) lives in definition.ts beside the sandbox DEFINITION it embeds:
+ * a bundle is definition + state, and keeping the two schemas together is what keeps the two export doors from
+ * drifting into different answers about what an environment is. */
+
+// What a restore actually did. `needsAction` is the part that matters: the environment rebuild command, the
+// credentials to re-enter, the logins to redo, each one a thing the target cannot do for itself.
+export const ImportReportSchema = z.object({
+    restored: z.object({ workspaceFiles: z.number(), historyFiles: z.number(), repos: z.array(z.string()), bytes: z.number() }),
+    // Entries the bundle carried that this daemon refused to write (an identity file, an escaping path), empty
+    // for any bundle a matching exporter produced, and a tamper signal when it is not.
+    refused: z.array(z.string()),
+    needsAction: z.array(z.object({ subject: z.string(), detail: z.string() })),
+});
+export type ImportReport = z.infer<typeof ImportReportSchema>;
+/* ---- migrations: importing a FOREIGN assistant's setup (Hermes, OpenClaw) ----
+ *
+ * A different crossing than a bundle restore, and deliberately a different surface: a bundle is our own format,
+ * re-derived entry by entry against the state manifests, while a migration reads a directory some OTHER
+ * program laid out (`~/.hermes`) and TRANSLATES it into native things, skills, automations, capabilities,
+ * merged memory. Nothing foreign is executed or copied verbatim into daemon state; every item lands through the
+ * same write paths the settings/skills/automations/capabilities surfaces use, which is what keeps an imported
+ * setup editable and deletable in the ordinary UI the day after (docs/assistant-import-design.md).
+ *
+ * The flow is PREVIEW-FIRST, mirroring what these tools' own `migrate` commands taught their users to expect:
+ * `plan` parses the uploaded archive into an itemized checklist and holds the upload in memory under a token;
+ * `apply` names the ticked item ids and the token. The plan is RE-DERIVED from the held archive at apply, the
+ * wire plan is a rendering for the owner, never the input the write trusts (restore.ts's rule, kept). */
+export const MigrationSourceSchema = z.enum(["hermes", "openclaw"]);
+export type MigrationSource = z.infer<typeof MigrationSourceSchema>;
+// What an item becomes here, not what it was there, the apply loop dispatches on this, and the checklist
+// groups by it so the owner reads "3 skills, 2 automations" rather than a foreign directory listing.
+export const MigrationTargetSchema = z.enum(["memory", "skill", "automation", "capability", "secret", "file"]);
+export type MigrationTarget = z.infer<typeof MigrationTargetSchema>;
+export const MigrationItemSchema = z.object({
+    // Deterministic (derived from the source artifact, e.g. `skill:weather`), so the ids the owner ticked name
+    // the same items when the plan is re-derived at apply.
+    id: z.string(),
+    target: MigrationTargetSchema,
+    // The checklist line, plain words: "Skill, weather", "Nightly digest (9:00 every day)".
+    label: z.string(),
+    detail: z.string().optional(),
+    /* The default tick. False marks the items the owner should read before taking, a server URL that points at
+     * localhost on the OLD machine, an .env key that looks like tuning rather than a credential. They still
+     * import fine when ticked; the flag is the adapter's judgment, not a gate. */
+    recommended: z.boolean(),
+    // Names of the secrets this item would store (never values, values stay in the held archive until apply,
+    // and only move when the apply says includeSecrets). Empty for items that carry none.
+    secrets: z.array(z.string()),
+});
+export type MigrationItem = z.infer<typeof MigrationItemSchema>;
+export const MigrationNeedsActionSchema = z.object({ subject: z.string(), detail: z.string() });
+export const MigrationPlanSchema = z.object({
+    source: MigrationSourceSchema,
+    // Names the held upload for the apply call. Minted per plan; a new upload replaces the held one.
+    token: z.string(),
+    items: z.array(MigrationItemSchema),
+    // What the adapter saw and will not move, sessions, logs, pairing state, listed rather than silent.
+    refused: z.array(z.string()),
+    // What is already known not to move mechanically (channels to reconnect, a model to pick), the same
+    // honesty ImportReportSchema carries, surfaced at PREVIEW time so the owner ticks with open eyes.
+    needsAction: z.array(MigrationNeedsActionSchema),
+});
+export type MigrationPlan = z.infer<typeof MigrationPlanSchema>;
+/* One of the owner's own computers, as an import SOURCE, the answer to "where is my setup" that needs no
+ * packing at all. Read on the card's first render for every enrolled machine, so the offer appears before the
+ * owner has read a single instruction.
+ *
+ * `found` absent means "connected, and nothing to import here", which is a real answer worth rendering
+ * quietly, not an error: the machine may simply be a different one from the machine the assistant runs on. */
+export const MigrationHostSchema = z.object({
+    id: z.string(),
+    online: z.boolean(),
+    found: MigrationSourceSchema.optional(),
+    // Why this machine cannot be read right now, when it cannot, offline, or its own refusal, in its words.
+    detail: z.string().optional(),
+});
+export const MigrationHostsSchema = z.object({ hosts: z.array(MigrationHostSchema) });
+export type MigrationHost = z.infer<typeof MigrationHostSchema>;
+// Read the setup off a connected computer instead of an upload. Answers with a plan, exactly as the upload
+// route does, everything after this point is identical whichever door the setup came through.
+export const MigrationScanSchema = z.object({ host: z.string().min(1) });
+export const MigrationApplySchema = z.object({
+    token: z.string(),
+    // The ticked item ids. Ids the re-derived plan does not contain are ignored rather than erroring, the
+    // archive is the truth, and a stale checklist must not block the items that still exist.
+    items: z.array(z.string()),
+    // The owner's explicit consent to move credential VALUES (mirrors the bundle export's `?secrets=`, and the
+    // `--include-secrets` these tools' own migrate commands require). Off: secret items are skipped and
+    // capability configs land without their keys.
+    includeSecrets: z.boolean(),
+});
+export type MigrationApply = z.infer<typeof MigrationApplySchema>;
+export const MigrationReportSchema = z.object({
+    applied: z.array(z.object({ id: z.string(), target: MigrationTargetSchema, label: z.string() })),
+    // Items that were ticked and did not land, each with the reason, a full disk, an env store that needs
+    // DevOps active. Distinct from `refused`, which is the class of things never attempted.
+    failed: z.array(z.object({ id: z.string(), label: z.string(), error: z.string() })),
+    refused: z.array(z.string()),
+    needsAction: z.array(MigrationNeedsActionSchema),
+});
+export type MigrationReport = z.infer<typeof MigrationReportSchema>;
+/* One export sitting in the daemon's export directory, the ARTIFACT a bundle is, rather than the request that
+ * produced it. Packing takes minutes over a real workspace, so tying it to a response made it a property of one
+ * browser tab: a refresh abandoned the work and left nothing to come back to. It is a file now, and every field
+ * below is read off that file rather than remembered anywhere.
+ *
+ * `status` is derived from the extension (.part / .tar.gz / .failed) and `bytes` is the file's own size, which
+ * is what makes a live pack's progress free to report. */
+export const BundleExportSchema = z.object({
+    // The finished bundle's filename, which is the id in every route, and, once downloaded, the name the owner
+    // sees on disk. Carries its own timestamp and a `-with-secrets` marker so it stays self-describing there.
+    name: z.string(),
+    status: z.enum(["packing", "ready", "failed"]),
+    // Bytes written so far while packing; the finished size once ready.
+    bytes: z.number(),
+    // mtime: when packing ended for a finished bundle, when it last made progress for a live one.
+    createdAt: z.number(),
+    secrets: z.boolean(),
+    // Why it stopped, for a failed one. Read from the .failed marker's own contents.
+    error: z.string().optional(),
+});
+export type BundleExport = z.infer<typeof BundleExportSchema>;
+export const BundleExportsSchema = z.object({ exports: z.array(BundleExportSchema) });

package/src/schemas/exit.ts

@@ -0,0 +1,222 @@
+// Geo exits: somewhere the agent's traffic can LEAVE from, so a page fetches as if read elsewhere. Its own
+// capability kind rather than a fourth `vpn` provider — an exit routes NOTHING into the main table.
+import { z } from "zod";
+import { autoStart } from "./internal.js";
+/* A GEO EXIT: somewhere the agent's traffic can LEAVE from, so a page fetches as if read in Berlin or Osaka.
+ * Its own kind rather than a fourth `vpn` provider, and the distinction is the whole reason this works:
+ *
+ *   a `vpn` REACHES a private network , one stored gateway, dialled, pushing its routes into the main table.
+ *   an `exit` LEAVES from somewhere else, a POOL with a catalog, switched at runtime, routing NOTHING into
+ *     the main table.
+ *
+ * That last clause is load-bearing. An exit is a full tunnel by definition, and a full tunnel on the main
+ * table swallows the sandbox's own uplink, the model endpoint and the tunnel that makes this sandbox
+ * reachable, which reads to a user as the agent breaking mid-turn (see IpsecVpnConfigSchema.routedNetworks
+ * for the same trap on the vpn kind). So an exit never touches the default route. It publishes a local SOCKS
+ * proxy and callers opt in: a browser account naming it, `curl --proxy`, and nothing else. The side benefit
+ * is trust, a volunteer relay carries only what was pointed at it, never the agent's own working traffic.
+ *
+ * Three providers, chosen because each is reachable with no paid account:
+ *   tor      , the Tor network. ~52 exit countries, no account, no credentials, no privileges: it is a SOCKS
+ *              proxy already. Country is a torrc line, a new IP is a control-port signal. The free default.
+ *   vpngate  , the University of Tsukuba's volunteer relay pool. No account; its public CSV IS the catalog,
+ *              so servers auto-fill. Overwhelmingly Japan/Korea in practice, which is the half of the map Tor
+ *              covers worst, so the two complement rather than duplicate.
+ *   wireguard, bring your own .conf files, one per country, from a provider's dashboard (Proton VPN's free
+ *              tier, Mullvad, anything). The catalog is built by parsing what was pasted.
+ * Starting, switching country and rotating are LIVE operations (see exit.contract.ts), never config, so an
+ * exit's real state is read off the machine. `country` is the resting preference and `autoStart` the only
+ * other persisted intent. */
+export const ExitProviderSchema = z.enum(["tor", "vpngate", "wireguard"]);
+export type ExitProvider = z.infer<typeof ExitProviderSchema>;
+// An ISO 3166-1 alpha-2 code, normalised up so "de", "DE" and "De" are one country rather than three. The
+// catalogs, the CLI and the manifest all speak this one spelling.
+export const CountryCodeSchema = z
+    .string()
+    .regex(/^[A-Za-z]{2}$/, "A country is its two-letter code, like DE, US or JP.")
+    .transform((value) => value.toUpperCase());
+export const TorExitConfigSchema = z.object({
+    provider: z.literal("tor"),
+    // Where to come out, when nothing has asked for somewhere else. Absent ⇒ let Tor choose, which is both
+    // faster and kinder to the network.
+    country: CountryCodeSchema.optional(),
+    autoStart,
+});
+export const VpngateExitConfigSchema = z.object({
+    provider: z.literal("vpngate"),
+    country: CountryCodeSchema.optional(),
+    autoStart,
+});
+export const WireguardExitConfigSchema = z.object({
+    /* One or more WireGuard .conf files in one field, pasted back to back. One field rather than one
+     * capability per country because they are one POOL: the whole point is switching between them under a
+     * proxy port that never moves, and a user with five Proton free countries should not add five capabilities
+     * to get five countries out of one account.
+     *
+     * Country per conf comes from an optional `# country: DE` line, else from the provider's own naming
+     * convention in the Endpoint host (Proton's `de-free-01.protonvpn.net`, Mullvad's `de-ber-wg-001`), else
+     * from a lookup through the tunnel once it is up. Whole thing is the secret: each conf holds a private key. */
+    provider: z.literal("wireguard"),
+    config: z.string().min(1),
+    country: CountryCodeSchema.optional(),
+    autoStart,
+});
+export const ExitConfigSchema = z.discriminatedUnion("provider", [TorExitConfigSchema, VpngateExitConfigSchema, WireguardExitConfigSchema]);
+export type TorExitConfig = z.infer<typeof TorExitConfigSchema>;
+export type VpngateExitConfig = z.infer<typeof VpngateExitConfigSchema>;
+export type WireguardExitConfig = z.infer<typeof WireguardExitConfigSchema>;
+export type ExitConfig = z.infer<typeof ExitConfigSchema>;
+// The manifest says which exits EXIST; this says which are up, where they come out, and what the world sees.
+// Read off the machine and off the wire, never remembered: an exit the agent stopped from a shell and one the
+// UI stopped read identically, and a daemon restart observes the truth rather than a stale guess.
+
+export const ExitStateSchema = z.enum([
+    // Carrying traffic: the proxy is listening and the last check came out where it was asked to.
+    "up",
+    // Coming up, or moving to another country. The proxy port may already be open and not yet where you want.
+    "starting",
+    // Configured and idle. The resting state, and the default one: exits are not held open for nothing.
+    "down",
+    // The client isn't installed yet (tor, openvpn): the capability's image fragment needs an owner rebuild.
+    "unavailable",
+    // The last start or switch failed; `detail` carries the reason.
+    "failed",
+]);
+export type ExitState = z.infer<typeof ExitStateSchema>;
+/* WHAT THE WORLD SEES, fetched THROUGH the exit's own proxy. This is the load-bearing type of the whole
+ * feature: "switch to Germany" is worth nothing as a report that a tunnel came up, and worth everything as a
+ * report that the egress address is now German. Every start, use and rotate ends by producing one of these,
+ * and a switch that cannot produce one fails instead of quietly leaving traffic where it was. */
+export const ExitObservationSchema = z.object({
+    ip: z.string().describe("The address the world sees, looked up through the exit's own proxy rather than assumed."),
+    // Absent when the lookup answered with an address but no country: a switch is judged on the country when
+    // one is known, and on the address having CHANGED when it is not.
+    country: z
+        .string()
+        .optional()
+        .describe(
+            "Which country that address is in. Absent when the lookup gave an address and no country, in which case a switch is judged on the address having changed instead.",
+        ),
+    countryName: z.string().optional().describe("That country's name, spelled out."),
+});
+export type ExitObservation = z.infer<typeof ExitObservationSchema>;
+/* One country an exit can come out of, as the picker and `exit countries` render it. `servers` and `share`
+ * are what stop a country list being a lie: Tor lists 52 countries and a third of them are one underpowered
+ * relay, so the ranking has to carry how much is actually there, not just that the flag exists. */
+export const ExitPointSchema = z.object({
+    country: z.string().describe("The country's code."),
+    countryName: z.string().describe("Its name, spelled out."),
+    // How many relays/servers this provider has there right now.
+    servers: z.number().describe("How many servers this provider has there."),
+    // This country's share of the provider's total exit capacity, 0..1. Used to sort and to grey out the
+    // countries that technically exist and practically do not.
+    share: z
+        .number()
+        .optional()
+        .describe(
+            "How much of the provider's actual capacity is there, from zero to one. This is what a list should be sorted by: a third of the countries on offer are one overloaded machine behind a flag, and a count of servers would rank them first.",
+        ),
+});
+export type ExitPoint = z.infer<typeof ExitPointSchema>;
+export const ExitCountriesSchema = z.object({
+    countries: z.array(ExitPointSchema).describe("Where this exit can put you, best-supplied first."),
+    // Whether this list came off the provider live or out of the baked fallback (no network, or the provider
+    // is down). The picker says so rather than presenting a stale list as current.
+    live: z
+        .boolean()
+        .describe("Whether the provider answered, or this came from a built-in list. Said out loud rather than presenting an old list as current."),
+});
+export const ExitLinkSchema = z.object({
+    id: z.string().describe("Which exit."),
+    provider: ExitProviderSchema.describe("What it runs on."),
+    state: ExitStateSchema.describe(
+        "Whether it is carrying traffic, coming up, resting, failed, or not installable yet because its client needs a rebuild to arrive.",
+    ),
+    // The SOCKS endpoint callers point at. Fixed per exit and stable across country switches, which is what
+    // lets a long task change country halfway without reconfiguring anything downstream.
+    proxy: z
+        .string()
+        .describe(
+            "Where to point traffic that should go through it. Fixed per exit and unchanged by a country switch, which is what lets a long job move country halfway through without reconfiguring anything.",
+        ),
+    // The country ASKED for (manifest preference, or the last `use`). Absent = provider's choice.
+    country: z.string().optional().describe("Where it was asked to come out. Absent means the provider chose."),
+    // The country actually OBSERVED at the last check, and the address behind it. These two disagreeing is
+    // the single most useful fault signal this feature has, so they are separate fields, never merged.
+    observedCountry: z
+        .string()
+        .optional()
+        .describe(
+            "Where it actually comes out, as last checked. Kept separate from what was asked for, because those two disagreeing is the most useful fault signal this whole feature has.",
+        ),
+    ip: z.string().optional().describe("The address behind that observation."),
+    // Epoch ms of the observation above, so a stale reading can be rendered as stale.
+    checkedAt: z.number().optional().describe("When that was checked, in milliseconds, so an old reading can be shown as old."),
+    // The tunnel interface, for the providers that have one (vpngate, wireguard). Tor has none by design.
+    interface: z.string().optional().describe("The network interface, for the kinds that have one."),
+    since: z.number().optional().describe("When it came up, in milliseconds."),
+    autoStart: z.boolean().describe("Whether it starts itself when the sandbox does."),
+    detail: z.string().optional().describe("Why it failed, or a note about a healthy one."),
+});
+export type ExitLink = z.infer<typeof ExitLinkSchema>;
+export const ExitListSchema = z.object({
+    links: z.array(ExitLinkSchema).describe("Every configured exit, with where it was asked to come out and where it actually does."),
+});
+/* WHERE EACH FREE PROVIDER CAN ACTUALLY COME OUT, as measured, and the reason it lives in the contract rather
+ * than in the daemon: two consumers need the same answer and must not drift. The daemon uses it as the
+ * FALLBACK catalog when a provider's own list cannot be fetched; the add form uses it to fill the country
+ * picker, so a user chooses from a list instead of guessing a code and finding out later that nothing serves
+ * it. A second copy of these numbers would let the picker offer a country the driver cannot dial.
+ *
+ * `share` is the country's slice of the provider's exit capacity, and it is the number that matters. A third
+ * of Tor's fifty-two countries are one overloaded relay behind a flag; ranking by relay COUNT alone would put
+ * the United States first on 1,171 slow relays when the Netherlands carries three times the traffic on half as
+ * many. Both surfaces sort on this so the top of the list is the part that works.
+ *
+ * Measured 2026-08-21 from onionoo.torproject.org and vpngate.net's public CSV. Stale by construction, which
+ * is exactly why the daemon prefers a live fetch and labels this one as not-live when it falls back to it. */
+export const TOR_EXIT_COUNTRIES: readonly ExitPoint[] = [
+    { country: "NL", countryName: "Netherlands", servers: 607, share: 0.304 },
+    { country: "DE", countryName: "Germany", servers: 415, share: 0.242 },
+    { country: "SE", countryName: "Sweden", servers: 344, share: 0.14 },
+    { country: "US", countryName: "United States", servers: 1171, share: 0.097 },
+    { country: "AT", countryName: "Austria", servers: 123, share: 0.054 },
+    { country: "LU", countryName: "Luxembourg", servers: 92, share: 0.033 },
+    { country: "FR", countryName: "France", servers: 63, share: 0.032 },
+    { country: "NO", countryName: "Norway", servers: 54, share: 0.026 },
+    { country: "RO", countryName: "Romania", servers: 71, share: 0.011 },
+    { country: "DK", countryName: "Denmark", servers: 15, share: 0.007 },
+    { country: "HU", countryName: "Hungary", servers: 20, share: 0.006 },
+    { country: "IT", countryName: "Italy", servers: 15, share: 0.006 },
+    { country: "UA", countryName: "Ukraine", servers: 23, share: 0.006 },
+    { country: "CH", countryName: "Switzerland", servers: 23, share: 0.006 },
+    { country: "IS", countryName: "Iceland", servers: 23, share: 0.003 },
+    { country: "PL", countryName: "Poland", servers: 8, share: 0.002 },
+    { country: "BG", countryName: "Bulgaria", servers: 17, share: 0.002 },
+    { country: "GB", countryName: "United Kingdom", servers: 8, share: 0.002 },
+    { country: "FI", countryName: "Finland", servers: 13, share: 0.002 },
+];
+// VPN Gate, and its shape is the honest headline: 87% of its pool is Japan and Korea. That is not a defect to
+// hide behind a long country list, it is the reason to have it, Tor's Asian exit capacity is close to nothing,
+// so the two providers cover each other rather than overlapping.
+export const VPNGATE_EXIT_COUNTRIES: readonly ExitPoint[] = [
+    { country: "JP", countryName: "Japan", servers: 46, share: 0.48 },
+    { country: "KR", countryName: "Korea, South", servers: 37, share: 0.39 },
+    { country: "VN", countryName: "Vietnam", servers: 3, share: 0.03 },
+    { country: "TH", countryName: "Thailand", servers: 2, share: 0.02 },
+    { country: "RU", countryName: "Russia", servers: 2, share: 0.02 },
+    { country: "RO", countryName: "Romania", servers: 1, share: 0.01 },
+    { country: "MX", countryName: "Mexico", servers: 1, share: 0.01 },
+    { country: "IN", countryName: "India", servers: 1, share: 0.01 },
+    { country: "CN", countryName: "China", servers: 1, share: 0.01 },
+    { country: "BY", countryName: "Belarus", servers: 1, share: 0.01 },
+];
+export const ExitIdParamSchema = z.object({ id: z.string().describe("Which exit.") });
+// POST /exit/{id}/use body. An absent country means "let the provider choose", the same thing an absent
+// `country` in the manifest means, so clearing a country is expressible rather than only setting one.
+export const ExitUseInputSchema = z.object({
+    id: z.string().describe("Which exit."),
+    country: CountryCodeSchema.optional().describe(
+        "Where to come out. Leaving it out means letting the provider choose, so clearing a country is something you can actually say rather than only setting one.",
+    ),
+});