@intentic/sandbox-contract 1.232.0 → 1.233.0

package/src/schemas/usage.ts

@@ -0,0 +1,303 @@
+// usage: the durable spend ledger
+// usage: per-account token/cost totals
+import { z } from "zod";
+// One row per attributed turn, appended at turn end and NEVER pruned. This exists because the activity log
+// can't answer a money question: it prunes to its most recent entries, so a month's spend is unanswerable and
+//, worse for a cost readout, the totals SHRINK as newer turns evict older ones. The ledger keeps the raw
+// per-turn facts and the rollup projects them on read, so a new grouping (by day, by model, by conversation)
+// needs no new storage and no migration.
+export const UsageTurnSchema = z.object({
+    // Epoch ms at turn end. Kept alongside `day` so a future timezone-aware rollup is a pure change over data
+    // already on disk.
+    at: z.number().describe("When the turn ended, in milliseconds."),
+    // The UTC calendar day (YYYY-MM-DD) `at` fell in, precomputed so a rollup never re-derives a timezone.
+    day: z.string().describe("The day it fell in, as YYYY-MM-DD in UTC, worked out once so nothing downstream has to do timezone arithmetic."),
+    provider: z.string().describe("Which model provider served it."),
+    // Absent on an env-token turn, which has no account to attribute to (same rule as the activity log).
+    account: z.string().optional().describe("Which account paid. Absent for a turn run on a plain key, which belongs to no account."),
+    // The model the turn ACTUALLY ran, resolved past the client's pick and every provider default. Absent only
+    // when the provider's own subscription default served it without the daemon naming one.
+    model: z
+        .string()
+        .optional()
+        .describe(
+            "The model that actually ran, past whatever was asked for and every default. Absent only when the provider's own default served it without being named.",
+        ),
+    /* WHAT THE CLIENT ASKED FOR, beside `model` above, which is what ran. The pair is the point: a routing
+     * surprise is then a diff on one row rather than an investigation through the routing code.
+     *
+     * The gap between the two is real and was unreadable. A pick is resolved past the tier judge's downgrade,
+     * a provider's own subscription default, a catalog validity check that silently substitutes (Grok rejects
+     * a retired models.dev id, so an invalid pin becomes the catalog default), and CLIProxyAPI's own choice on
+     * a routed turn. Every one of those is a legitimate substitution and none of them was recorded, so "I
+     * chose one model and got another's error" could only be answered by reading four resolution paths and
+     * guessing which had fired.
+     *
+     * Absent ⇒ the client named nothing and asked for the default, which is not the same as asking for what it
+     * got. Equal to `model` on the overwhelming majority of turns; the rows where they differ are the whole
+     * reason this is here. */
+    modelRequested: z
+        .string()
+        .optional()
+        .describe("The model that was asked for, when one was named. Differs from `model` when something resolved it."),
+    harness: z.string().describe("Which agentic loop it ran on."),
+    /* HOW THE TURN ENDED. The field that turns the ledger from an accounting record into a diagnostic one.
+     *
+     * Without it a turn that died is byte-for-byte indistinguishable from one that succeeded, except that it
+     * cost less, so "four sessions all broke a minute ago" had no record to read and had to be answered by
+     * re-running the destructive act in a live sandbox. The failure was never nowhere: it was in the activity
+     * log, which prunes to its most recent entries, so an incident survives only until the feed rolls past it.
+     * This log is never pruned, which is the entire difference.
+     *
+     * "cancelled" is a user pressing Stop, which is not a failure and must never be read as one, the registry
+     * learned that lesson already (see the abort branch in streamAgent). "error" is a turn the provider or the
+     * request killed. Both still carry whatever they spent before they ended.
+     *
+     * Absent ⇒ the row predates this being recorded, NOT a turn that succeeded. Readers that count failures
+     * must treat absent as unknown, and the experiment readers do exactly that. */
+    outcome: z.enum(["ok", "error", "cancelled"]).optional().describe("How it ended: finished, failed, or was stopped by the user."),
+    // The failing frame's code, when it carried one, e.g. `rate_limit`, `provider-outage`, `claude-not-entitled`.
+    // Present only alongside outcome "error", and absent even then for a failure that named no code, which is
+    // itself the interesting case: an unclassified failure is one nothing downstream knows how to handle.
+    errorCode: z.string().optional().describe("The failure's code, when it had one."),
+    // The failing frame's own sentence, capped at ERROR_MESSAGE_CHARS. Capped rather than omitted because the
+    // provider's wording is routinely the only thing that distinguishes two failures sharing one code, and
+    // uncapped it would let one bad provider message dominate a file that must stay cheap to read whole.
+    errorMessage: z.string().optional().describe("What the failure said, trimmed."),
+    // The conversation this turn belonged to, so spend can join to a fleet agent. Absent only for an internal
+    // one-shot turn that has no conversation identity.
+    conversationId: z
+        .string()
+        .optional()
+        .describe(
+            "Which conversation it belonged to, so spending can be traced to a card. Absent only for an internal one-off with no conversation at all.",
+        ),
+    // The provider's own turn count for the request (a Claude "turn" can be several under the hood), so turns
+    // and cost stay comparable across providers. 1 when the provider reported none.
+    turns: z
+        .number()
+        .describe("The provider's own count for the request, since one exchange can be several under the hood. One when it reported none."),
+    inputTokens: z.number().describe("Tokens sent."),
+    outputTokens: z.number().describe("Tokens received."),
+    cacheReadTokens: z.number().describe("Tokens served from cache, which cost less."),
+    cacheCreationTokens: z.number().describe("Tokens written to cache, which cost more up front and less afterwards."),
+    costUsd: z.number().describe("What it cost, in dollars."),
+    durationMs: z.number().describe("How long it took, in milliseconds."),
+    /* Which arm of the terse experiment this turn ran on (settings.terseHoldout), the only record of it, and
+     * the reason the savings report can say what the steer is worth instead of guessing.
+     *
+     * ABSENT means "not part of the experiment", not "off": a turn under a custom system prompt drops the
+     * steer along with everything else the daemon appends, and a turn run with the experiment switched off has
+     * no control to be compared against. Pooling those into the off-arm would compare steered turns against a
+     * population selected by something other than the coin flip, which is not a control at all. */
+    terse: z.boolean().optional(),
+    /* Which arm of the iq SEARCH-TEACHING experiment this conversation runs on
+     * (settings.iqSearchHoldout). Stable for every turn in one conversation: the treatment is instruction
+     * loaded into a provider session, so flipping it per turn would call a remembered treatment a control.
+     * Absent ⇒ measurement is off; true/false ⇒ taught/cold. */
+    iqSearchArm: z.boolean().optional(),
+    // Hash of the plugin nudge + skill body used for this arm. Control turns carry it too, so a report can keep
+    // both sides of one treatment revision together and exclude older wording after an upgrade.
+    iqSearchCohort: z.string().optional(),
+    /* Characters of the model's own PROSE this turn, the `delta` frames only, so no tool-call arguments and no
+     * thinking. What the terse steer is judged on, and the reason it can be judged at all.
+     *
+     * `outputTokens` cannot serve: measured over a day of real turns it is 91.6% tool-call arguments (an Edit's
+     * old_string and new_string, a Write's whole file body) and 7.8% prose. The steer moves prose. So a fifth
+     * off the model's narration moves the total by 1.6%, against a margin of ±35 points, which is to say the
+     * experiment was structurally unable to see its own treatment, and the number it printed instead was
+     * whichever arm happened to draw the bigger tasks.
+     *
+     * CHARACTERS, not tokens, because the provider bills a total and never breaks it down, a token figure here
+     * would be chars÷4 wearing a unit it had not earned. For a comparison of two arms the constant cancels
+     * anyway, and the honest unit is the one actually counted.
+     *
+     * Absent ⇒ the turn predates this being measured; `armOf` drops it from the population rather than reading
+     * it as a silent turn. */
+    proseChars: z.number().optional(),
+    /* SEARCHES THIS TURN RAN, every tool call that went looking for code, the dedicated search tools and the
+     * CLI searches alike (isSearchCall owns the rule; `iq q` is Bash and would otherwise not be counted at all).
+     * What the search teaching is judged on, and the same correction `proseChars` is to the terse steer.
+     *
+     * COST PER TURN CANNOT SERVE: cost is a whole turn's worth of work, a search mechanism touches one part of
+     * it, and the part lives inside the noise of the rest, exactly the shape that made output tokens unable to
+     * see the steer. Nine days of a since-removed retrieval experiment proved it with an interval from −2.9% to
+     * +56.9%, driven entirely by which arm had drawn the bigger jobs.
+     *
+     * Searches are what the mechanism acts on directly. Turns that never search stay in the population at zero
+     * rather than being filtered out, they dilute both arms equally, while selecting on "did it search" would
+     * select on the treatment itself.
+     *
+     * Absent ⇒ the turn predates this being measured; `armOf` drops it rather than reading it as a turn that
+     * searched nothing. */
+    searchCalls: z.number().optional(),
+    /* …and how many of them came BEFORE the turn first opened or changed a file, the orientation burst. A turn
+     * that already knows where to look starts working; one that doesn't goes hunting first.
+     *
+     * The narrower of the two readings and the less confounded: `searchCalls` still grows with the size of the
+     * job, while the walk up to the first file is roughly the same act whatever the job turns out to be.
+     *
+     * A turn that never reads or edits counts all of its searches here, it never arrived, so all of it was
+     * orientation. Dropping those instead would select the population by an OUTCOME the treatment moves, which
+     * is the one bias an arm-based reading cannot absorb.
+     *
+     * Absent ⇒ as for `searchCalls`. */
+    openingSearches: z.number().optional(),
+    /* DID THIS TURN FINISH, OR DID IT STOP TALKING. The fields that tell the two apart, and the reason
+     * `outcome` alone could never.
+     *
+     * A turn ends at least five different ways: its stop condition was met, the model ran out of things to say,
+     * the loop hit a cap, the budget ran out, or the model asserted it was done and nothing checked the claim.
+     * `outcome` collapses four of those into "ok", so a ledger that already recorded every failure perfectly
+     * still wrote the same word over a turn that proved its work and a turn that went quiet halfway through its
+     * own checklist. The daemon was computing the difference and discarding it at turn end.
+     *
+     * NO SINGLE STOP-REASON WORD IS STORED, deliberately: these are the facts, and which of the five modes they
+     * add up to is a rule that will get better. A word written down now would freeze today's rule into rows
+     * that outlive it and cannot be re-read under the next one, the same reason `tierRouted` is recorded beside
+     * `tierScore` instead of being derived from it once and forgotten.
+     *
+     * `verification` is the four-state VerificationState the child roster already speaks (agent-verification.ts):
+     * "verified" = a check passed AFTER the last code edit, "failing" = the last one after it did not,
+     * "unproven" = nothing ran, "no-code" = nothing a check could speak to was edited. Folded from this turn's
+     * own tool-call frames, subagents' included, so a Codex turn is judged exactly as a Claude one is. Absent ⇒
+     * the row predates this, NOT a turn nothing was known about.
+     *
+     * `check` is the command that SPOKE, the one that cleared the work or the one that broke, capped. It is
+     * what keeps "verified" auditable: a passing `vitest run one.test.ts` is evidence about one file and must
+     * never read as the repo being green, and only the command itself shows which was which.
+     *
+     * `filesEdited` counts every file written, prose included, where `verification` speaks only about code. The
+     * pair is the point: `{ verification: "no-code", filesEdited: 3 }` is a documentation turn, and
+     * `{ verification: "unproven", filesEdited: 0 }` cannot happen. */
+    verification: z.enum(["verified", "unproven", "failing", "no-code"]).optional(),
+    check: z.string().optional(),
+    filesEdited: z.number().optional(),
+    /* THE AGENT'S OWN CHECKLIST WHEN THE TURN ENDED, reconstructed from the Task tool family and reported by
+     * every runtime that keeps one (`todos` frames). `checklistOpen` is pending plus in-progress.
+     *
+     * This is the honest reading of "the model stopped emitting": a turn that ended `ok` with items still open
+     * abandoned a plan it wrote itself, which is a different event from a turn that finished one, and the two
+     * were indistinguishable in every record this daemon kept. Absent ⇒ the turn kept no checklist at all,
+     * which is most short turns and is not the same as an empty one. */
+    checklistTotal: z.number().optional(),
+    checklistOpen: z.number().optional(),
+    /* HOW MANY TIMES THE CONTEXT WAS COMPACTED under this turn, and how full the window was when it ended.
+     *
+     * Compaction is the least observable thing a harness does to a turn: a poorly timed one discards the
+     * partial result the turn still needed, and the only trace was a frame streamed to whoever was watching.
+     * Recorded here, "did compaction hurt" becomes a question this ledger can answer, by joining these against
+     * `verification` and `outcome` over months of real turns, which is a number nobody currently has.
+     *
+     * `contextTokens`/`contextWindow` are the last `context_usage` frame, absent for a runtime that reports
+     * none. Both, rather than a percentage: the window is a per-model constant that moves between model
+     * versions, and a fraction computed today cannot be recomputed tomorrow from what it threw away.
+     *
+     * Together they carry ~90 bytes onto a ~250-byte row. A heavy day is ~100 turns, so a year of hard use goes
+     * from ~9 MB to ~12 MB, which is the price of a log that can answer why a turn ended rather than only what
+     * it cost. */
+    compactions: z.number().optional(),
+    contextTokens: z.number().optional(),
+    contextWindow: z.number().optional(),
+    /* WHAT THE COMPLEXITY JUDGE SAID ABOUT THIS TURN, and whether anything was done about it. The three fields
+     * automatic tier selection is calibrated from, and the reason it can ship in shadow at all.
+     *
+     * They live on the SPEND ledger rather than in a log of their own because the question they exist to answer
+     * is a question about money: what did the turns we would have downgraded actually cost, and what did the
+     * ones we did downgrade cost instead. A separate log would have to be joined back to this one on every
+     * read, and the join key (a turn) is already the row.
+     *
+     * `tierScore` is 0..1 from judgeComplexity, comparable against FAST_CEILING, which is the cutoff it was
+     * judged against at the time. Absent ⇒ the judge did not run (settings.autoTier "off", or a row written
+     * before this existed), which is NOT the same as a turn that scored zero.
+     *
+     * `tierRules` is which named features fired, and it is the half that makes the ledger analysable rather
+     * than merely tallyable: a score says a threshold was crossed, the rules say which feature is doing the
+     * work, and re-fitting the weights needs the second. Bounded by construction, there are ~19 of them.
+     *
+     * `tierRouted` is whether the turn ACTUALLY ran on the cheap rung. It is not implied by the score: a turn
+     * judged fast still runs standard in shadow mode, and still runs standard in `on` mode when the provider
+     * publishes nothing cheaper than the user's pick. Reading the score as the decision would report savings
+     * that were never made. */
+    tierScore: z.number().optional(),
+    tierRules: z.array(z.string()).optional(),
+    tierRouted: z.boolean().optional(),
+    /* THE VERDICT ITSELF, and the cutoff it was reached against.
+     *
+     * `tierScore` stopped being able to answer "was this called simple" the moment the cutoff became the owner's
+     * to choose (settings.autoTierEagerness): 0.35 is standard on the middle stop and fast on the eager one, and
+     * a fast verdict also requires a positively-easy signal that no score can express. So the answer is written
+     * down rather than re-derived, and the ceiling goes with it because a refit reading a column of bare scores
+     * could not otherwise tell two rows apart.
+     *
+     * Absent on rows written before the knob existed, which were all judged at the `balanced` cutoff — which is
+     * exactly what a reader falls back to (FAST_CEILING), so old and new rows stay one population. */
+    tierFast: z.boolean().optional(),
+    tierCeiling: z.number().optional(),
+    /* THE USER SAID NO: the turn carried AgentTurn.tierHold, so a fast verdict moved nothing. Recorded rather
+     * than folded into `tierRouted: false` because it is the strongest calibration label this ledger ever gets,
+     * a person looking at this very conversation deciding the cheap rung was not to be trusted with it, and the
+     * refit (docs/model-routing-design.md §4) needs it kept apart from "nothing cheaper was published". Absent ⇒
+     * no veto, which is every row written before the control existed and most rows after. */
+    tierDenied: z.boolean().optional(),
+});
+export type UsageTurn = z.infer<typeof UsageTurnSchema>;
+// The ledger grouped by day × provider × account × model × harness × conversation, the finest grouping any
+// dashboard panel needs, and a handful of rows per active day instead of one per turn, so a year of history is
+// well under a MB over the tunnel. Every panel (spend per day, cost by model, cost by agent, cache hit rate) is
+// a projection of these.
+// The conversation is in the KEY, not merely along for the ride, because cost-by-agent has to answer within the
+// same window as every other panel on the screen. The fleet registry also carries a per-agent total, but only a
+// cumulative, all-time one, reading it beside a "last 7 days" filter would print an all-time number under a
+// windowed heading, which is the shrinking-totals bug wearing a different hat.
+export const UsageRollupRowSchema = z.object({
+    day: z.string().describe("The day, as YYYY-MM-DD in UTC."),
+    provider: z.string().describe("Which model provider."),
+    account: z.string().optional().describe("Which account. Absent for work run on a plain key."),
+    model: z.string().optional().describe("Which model."),
+    harness: z.string().describe("Which agentic loop."),
+    conversationId: z.string().optional().describe("Which conversation."),
+    turns: z.number().describe("Turns in this group."),
+    inputTokens: z.number().describe("Tokens sent."),
+    outputTokens: z.number().describe("Tokens received."),
+    cacheReadTokens: z.number().describe("Tokens served from cache."),
+    cacheCreationTokens: z.number().describe("Tokens written to cache."),
+    costUsd: z.number().describe("What the group cost, in dollars."),
+    durationMs: z.number().describe("Time spent, in milliseconds."),
+});
+export type UsageRollupRow = z.infer<typeof UsageRollupRowSchema>;
+// Inclusive UTC day bounds (YYYY-MM-DD). Both absent ⇒ the whole ledger. Shared by every windowed read of a
+// daemon ledger (spend, savings): one window shape, so a screen that filters two ledgers at once filters them
+// with the same calendar.
+export const DayWindowQuerySchema = z.object({
+    from: z.string().optional().describe("First day to include, as YYYY-MM-DD in UTC. Leave it out for everything up to the end day."),
+    to: z
+        .string()
+        .optional()
+        .describe(
+            "Last day to include, as YYYY-MM-DD in UTC, and it is included rather than excluded. Leave it out for everything from the start day onwards.",
+        ),
+});
+export type DayWindowQuery = z.infer<typeof DayWindowQuerySchema>;
+export const UsageRollupSchema = z.object({
+    rows: z
+        .array(UsageRollupRowSchema)
+        .describe(
+            "Spending grouped by day, provider, account, model and conversation. Everything a cost screen shows is a rearrangement of these rows, which is why there is no second call for any of it.",
+        ),
+});
+// The account picker's headroom readout, folded from the ledger above (all-time, not a log window), grouped by
+// provider+account. `account` is the attribution key, so env-token turns are excluded rather than pooled under
+// a blank id, an unattributed turn belongs to no account's total.
+export const UsageAccountSchema = z.object({
+    provider: z.string(),
+    account: z.string(),
+    turns: z.number(),
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+    cacheReadTokens: z.number(),
+    cacheCreationTokens: z.number(),
+    costUsd: z.number(),
+});
+export type UsageAccount = z.infer<typeof UsageAccountSchema>;
+export const UsageSummarySchema = z.object({ accounts: z.array(UsageAccountSchema) });

package/src/{schemas.test.ts → schemas/version-seam.test.ts}

@@ -1,5 +1,7 @@
 import { expect, test } from "vitest";
-import { CapabilitiesListSchema, IpsecVpnConfigSchema, SandboxSettingsSchema } from "./schemas.js";
+import { CapabilitiesListSchema } from "./capabilities.js";
+import { SandboxSettingsSchema } from "./settings.js";
+import { IpsecVpnConfigSchema } from "./vpn.js";
 
 /* The settings shape spans a version seam that really moves: the browser ships with the platform, the daemon
  * ships inside the user's sandbox image, so a web build routinely parses a payload from an OLDER daemon. These
@@ -29,7 +31,7 @@ test("a payload from a build that predates a toggle parses, with the new toggle
  * time only when the user changes something, so until then the daemon parses `{}`: one field without a
  * `.default()` turns that into a throw at boot, and the version tolerance above is built on the same property.
  *
- * Asserted by shape rather than by value: what each default IS belongs next to the field in schemas.ts, where
+ * Asserted by shape rather than by value: what each default IS belongs next to the field in settings.ts, where
  * the reason it holds is written down. A second copy here proved nothing the schema didn't already say and
  * failed on every field the product added. */
 test("no field is required: a workspace that has never written settings parses", () => {

package/src/schemas/vpn.ts

@@ -0,0 +1,215 @@
+// vpn: live tunnel state + connect/disconnect
+import { z } from "zod";
+// A VPN the agent's traffic rides. One capability = one tunnel, discriminated by `provider` so a new protocol
+// is a new arm (plus a driver in the daemon's vpn/), never a reinterpretation of an existing field:
+//   wireguard, a pasted .conf, brought up with wg-quick.
+//   fortinet , a FortiGate SSL-VPN (what FortiClient's <sslvpn> connections speak), dialled with openconnect
+//               --protocol=fortinet. openconnect is the client rather than openfortivpn because it routes over
+//               tun instead of pppd: it needs exactly the tun + NET_ADMIN grant this kind already carries, and
+//               no /dev/ppp device (which the runtime allowlist does not, and should not, include).
+//   ipsec    , an IKEv1/IKEv2 tunnel with a pre-shared key and optional XAuth (FortiClient's <ipsecvpn>
+//               connections), run by strongSwan. `aggressive` mirrors FortiClient's dial-up default.
+// Connecting is NOT a config field: connect/disconnect are live operations (see vpn.contract.ts) that both the
+// user and the agent drive, so a stored tunnel's up/down state is read from the OS, never from the manifest.
+// `autoConnect` is the only persisted intent, whether the daemon dials this tunnel again on boot.
+export const VpnProviderSchema = z.enum(["wireguard", "fortinet", "ipsec"]);
+export type VpnProvider = z.infer<typeof VpnProviderSchema>;
+const autoConnect = z.enum(["on", "off"]).default("on");
+// FortiClient wraps every stored credential in its own "EncX <hex>" (older builds: "Enc <hex>") encryption,
+// keyed to the machine that exported the config, it is NOT recoverable from the file. Pasting one is an easy
+// mistake to make, because in the XML it sits exactly where the credential belongs, and the failure it causes
+// is unreadable: phase 1 negotiates fine and IKE then reports "calculated HASH does not match HASH payload",
+// which says nothing about where the bad value came from. Rejecting it here turns that into a sentence at the
+// point of entry. (The FortiClient importer already drops these, this catches a hand-paste.)
+// Exported so the add form can flag it inline on blur instead of only on a rejected round-trip, one
+// definition of what "this is ciphertext, not a credential" means, shared by the browser and the daemon.
+export const isForticlientCiphertext = (value: string): boolean => /^Enc[X]?\s+[0-9A-Fa-f]{8,}$/.test(value.trim());
+const notForticlientCiphertext = <T extends z.ZodType<string>>(field: T, label: string): T =>
+    field.refine((value) => !isForticlientCiphertext(value), {
+        message: `That looks like a value copied straight out of a FortiClient config, FortiClient encrypts it with a key tied to the machine that exported it, so it can't be used here. Enter the actual ${label} (ask whoever administers the gateway).`,
+    }) as unknown as T;
+export const WireguardVpnConfigSchema = z.object({
+    provider: z.literal("wireguard"),
+    // The pasted .conf ([Interface] + [Peer]), it holds the private key, so it's this arm's secret field.
+    config: z.string().min(1),
+    autoConnect,
+});
+export const FortinetVpnConfigSchema = z.object({
+    provider: z.literal("fortinet"),
+    // Gateway host only; the port is its own field so a pasted "host:port" can be split on import.
+    server: z.string().min(1),
+    port: z.coerce.number().int().min(1).max(65535).default(443),
+    username: z.string().min(1),
+    password: notForticlientCiphertext(z.string().min(1), "password"),
+    // A FortiGate on a self-signed/private-CA certificate: openconnect pins this digest
+    // ("sha256:…", copied from its own refusal message) instead of trusting a CA. Absent ⇒ normal CA validation.
+    trustedCert: z.string().min(1).optional(),
+    // Some gateways scope a login to a realm/group (openconnect --usergroup, FortiClient's tunnel realm).
+    realm: z.string().min(1).optional(),
+    autoConnect,
+});
+export const IpsecVpnConfigSchema = z.object({
+    provider: z.literal("ipsec"),
+    server: z.string().min(1),
+    presharedKey: notForticlientCiphertext(z.string().min(1), "pre-shared key"),
+    // The local IKE identity (FortiClient's <localid>), dial-up FortiGates key their phase-1 selection off it.
+    localId: z.string().min(1).optional(),
+    remoteId: z.string().min(1).optional(),
+    // XAuth (FortiClient's <xauth>), absent for PSK-only tunnels.
+    username: z.string().min(1).optional(),
+    password: notForticlientCiphertext(z.string().min(1), "XAuth password").optional(),
+    ikeVersion: z.enum(["1", "2"]).default("1"),
+    // Perfect Forward Secrecy for phase 2. Must match the gateway EXACTLY: it decides whether a KE payload is
+    // sent in quick mode, and a mismatch fails with NO_PROPOSAL_CHOSEN only after phase 1 and XAuth have
+    // succeeded, which reads like anything but a phase 2 problem. FortiClient stores it as <pfs> under
+    // <ipsec_settings> and defaults it on, so that is the default here too.
+    pfs: z.enum(["on", "off"]).default("on"),
+    // The Diffie-Hellman group, as FortiClient numbers them. ONE field for both phases on purpose: in IKEv1
+    // strongSwan sends a single KE payload in quick mode and the phase-2 group ends up following phase 1, so
+    // offering a phase-1 list that starts with a different group than the gateway wants for phase 2 fails with
+    // NO_PROPOSAL_CHOSEN no matter what the esp= line says. 14 (modp2048) is FortiClient's phase-2 default;
+    // it is <dhgroup> under <ipsec_settings> in an export.
+    dhGroup: z.enum(["2", "5", "14", "15", "16", "19", "20"]).default("14"),
+    // IKEv1 aggressive mode: insecure by construction, and exactly what FortiGate dial-up with a group PSK
+    // requires, hence opt-in per connection rather than a global strongSwan setting.
+    aggressive: z.enum(["on", "off"]).default("on"),
+    // WHICH networks ride the tunnel, strongSwan's rightsubnet, the traffic selector this client offers in
+    // quick mode. The single most consequential setting on an ipsec tunnel, and the one with no visible symptom
+    // until it is wrong: 0.0.0.0/0 offers the gateway EVERYTHING the sandbox sends, including the sandbox's own
+    // outbound connection to the model endpoint. A gateway that routes only its own networks accepts that
+    // selector, assigns a virtual IP, and then black-holes the rest, so the agent goes silent mid-turn, which
+    // reads as the agent breaking rather than as a VPN setting. Narrowing this to the networks actually behind
+    // the gateway (10.0.0.0/8,192.168.0.0/16) fixes it with nothing lost: the gateway is asked for less, not for
+    // something different, and it needs no change of its own to accept that.
+    // Comma-separated because strongSwan takes a list; under IKEv1 each entry is its own CHILD_SA, which not
+    // every gateway will negotiate, a list that dials as one entry is a gateway limit, not a config error.
+    // The DEFAULT STAYS 0.0.0.0/0: narrowing it for everyone would cut existing tunnels off from networks they
+    // reach today, and a full tunnel is right whenever the gateway does route the internet.
+    routedNetworks: z
+        .string()
+        .default("0.0.0.0/0")
+        .refine(
+            (value) =>
+                value
+                    .split(",")
+                    .map((entry) => entry.trim())
+                    .every((entry) => z.cidrv4().safeParse(entry).success || z.cidrv6().safeParse(entry).success),
+            {
+                message:
+                    "Routed networks is a comma-separated list of CIDRs, like 10.0.0.0/8,192.168.0.0/16. A single host needs its prefix too (192.168.0.168/32). Leave it at 0.0.0.0/0 to send everything through the gateway.",
+            },
+        ),
+    autoConnect,
+});
+export const VpnConfigSchema = z.discriminatedUnion("provider", [WireguardVpnConfigSchema, FortinetVpnConfigSchema, IpsecVpnConfigSchema]);
+export type WireguardVpnConfig = z.infer<typeof WireguardVpnConfigSchema>;
+export type FortinetVpnConfig = z.infer<typeof FortinetVpnConfigSchema>;
+export type IpsecVpnConfig = z.infer<typeof IpsecVpnConfigSchema>;
+export type VpnConfig = z.infer<typeof VpnConfigSchema>;
+// The manifest says which VPNs EXIST; this says which are UP right now. Every field is read back from the OS
+// (wg show / ip / openconnect's pidfile / swanctl), never remembered by the daemon, so a tunnel the agent
+// dropped from a shell and one the UI dropped read identically, and a daemon restart loses nothing.
+
+export const VpnStateSchema = z.enum([
+    // The tunnel is up and carrying traffic.
+    "connected",
+    // Dialling: openconnect authenticated but the interface has no address yet, or strongSwan is negotiating.
+    "connecting",
+    // Configured and idle, the normal resting state for a tunnel nobody asked for.
+    "disconnected",
+    // The tunnel's client isn't installed yet: the capability's image fragment needs an owner-run rebuild.
+    "unavailable",
+    // The last dial failed; `detail` carries the client's own message.
+    "failed",
+]);
+export type VpnState = z.infer<typeof VpnStateSchema>;
+export const VpnLinkSchema = z.object({
+    id: z.string().describe("Which tunnel."),
+    provider: VpnProviderSchema.describe("What kind of tunnel it is."),
+    state: VpnStateSchema.describe(
+        "Whether it is up, dialling, resting, failed, or not installable yet because its client needs a rebuild to arrive.",
+    ),
+    // The gateway this tunnel dials, host:port for fortinet, the [Peer] endpoint for wireguard, the IKE peer
+    // for ipsec. Display only; never a secret.
+    gateway: z.string().optional().describe("What it dials. For display only, and never a credential."),
+    // The tun/wg interface carrying the tunnel, once it exists.
+    interface: z.string().optional().describe("The network interface carrying it, once one exists."),
+    // The address the gateway assigned this sandbox, the single most useful "am I on the VPN?" fact.
+    address: z
+        .string()
+        .optional()
+        .describe("The address the far end gave this sandbox, which is the single most useful answer to whether you are on the VPN."),
+    // The CIDRs routed into the tunnel ("0.0.0.0/0" = full tunnel). Empty until the link is up.
+    routes: z
+        .array(z.string())
+        .default([])
+        .describe("What goes through it. Everything, when the range covers the whole internet. Empty until it is up."),
+    // DNS servers the tunnel pushed, when it pushed any.
+    dns: z.array(z.string()).default([]).describe("Name servers it pushed, when it pushed any."),
+    // Epoch ms the link came up, the UI renders "connected 14m ago". Absent unless connected.
+    since: z.number().optional().describe("When it came up, in milliseconds. Absent unless it is."),
+    // Whether the daemon re-dials this tunnel on boot (the manifest's autoConnect).
+    autoConnect: z.boolean().describe("Whether it dials itself when the sandbox starts."),
+    // Why it is failed/unavailable, or an extra note on a healthy link. Never carries credentials.
+    detail: z.string().optional().describe("Why it failed, or a note about a healthy one. Never a credential."),
+});
+export type VpnLink = z.infer<typeof VpnLinkSchema>;
+export const VpnListSchema = z.object({
+    links: z
+        .array(VpnLinkSchema)
+        .describe("Every configured tunnel with its live state, read back from the operating system each time rather than remembered."),
+});
+// POST /vpn/{id}/connect body. `otp` is a one-time 2FA code, supplied per dial and NEVER stored, a FortiGate
+// with token auth rejects the dial without it, and the daemon surfaces that as a retry-with-a-code error.
+export const VpnConnectInputSchema = z.object({
+    id: z.string().describe("Which tunnel to dial."),
+    otp: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("A one-time code, where the gateway wants one. Supplied per dial and never stored; without it such a gateway refuses and says so."),
+});
+export const VpnIdParamSchema = z.object({ id: z.string().describe("Which tunnel.") });
+// POST /vpn/import-forticlient: parse an exported FortiClient configuration (the XML FortiClient writes from
+// File → Settings → Backup) into addable connections. Credentials in that file are wrapped in FortiClient's
+// proprietary "EncX …" encryption, which is NOT reversible here, so a parsed connection carries the endpoint
+// and, when it was stored in the clear, the username; the password is always typed by the user afterwards.
+export const ForticlientImportInputSchema = z.object({
+    xml: z.string().min(1).describe("The exported configuration file, whole. Nothing is stored: it is read and thrown away."),
+});
+export const ForticlientConnectionSchema = z.object({
+    // FortiClient's connection name, slugged into a legal capability id.
+    id: z.string().describe("The id it would be added under."),
+    // The original <name>, shown so the user recognises the connection they picked.
+    label: z.string().describe("Its name as the file has it, so somebody recognises the connection they are picking."),
+    provider: VpnProviderSchema.describe("What kind of tunnel it is."),
+    server: z.string().describe("Where it dials."),
+    port: z.number().describe("On which port."),
+    // Present only when FortiClient stored it unencrypted; an EncX-wrapped username is dropped, not guessed.
+    username: z
+        .string()
+        .optional()
+        .describe("The username, but only when the file stored it in the clear. An encrypted one is dropped rather than guessed at."),
+    description: z.string().optional().describe("Whatever the file said about it."),
+    // ipsec-only, and only when the file stored them in the clear.
+    localId: z.string().optional().describe("An identity some tunnel types need, when the file stored it readably."),
+    aggressive: z.boolean().optional().describe("Which negotiation mode it used."),
+    // Phase-2 settings, read from <ipsec_settings>, the pair that decides whether quick mode can succeed.
+    pfs: z.boolean().optional().describe("Whether it asked for forward secrecy."),
+    dhGroup: z
+        .string()
+        .optional()
+        .describe(
+            "Which key-exchange group it used. Together with the setting above, this is what decides whether the connection can complete at all.",
+        ),
+    // What the user still has to supply for this connection to dial (always at least the password).
+    needs: z
+        .array(z.string())
+        .describe(
+            "What you still have to type in before it can dial. Always at least the password, because the export wraps credentials in encryption that cannot be undone here.",
+        ),
+});
+export type ForticlientConnection = z.infer<typeof ForticlientConnectionSchema>;
+export const ForticlientImportSchema = z.object({
+    connections: z.array(ForticlientConnectionSchema).describe("The connections found in the file, ready to be added one at a time."),
+});

package/src/schemas/webext.ts

@@ -0,0 +1,79 @@
+// webext: the user's own browser (the `webext` capability's live half)
+import { z } from "zod";
+/* ONE SITE THE PERSON ALLOWED, as the browser itself understands it. `origin` is Chrome's own match pattern
+ * for that grant ("https://github.com/*"), because that is the string the extension asked `chrome.permissions`
+ * for and the string the browser will show in its own settings — inventing a prettier spelling here would mean
+ * a card naming something the browser's permission list does not.
+ *
+ * `mode` is this extension's own narrowing on top of Chrome's grant: a site may be readable without being
+ * driveable. Chrome has no concept for that, so it is enforced in the extension and shown here so the card can
+ * say which is which. */
+export const WebExtGrantSchema = z.object({
+    origin: z.string(),
+    mode: z.enum(["read", "act"]),
+});
+export type WebExtGrant = z.infer<typeof WebExtGrantSchema>;
+// What a connected browser reports about itself. The parallel of HostFacts, and the same job: the SKILL pack
+// teaches the agent how to drive a browser, this tells it which browser, how many tabs are open, and — the
+// part with no equivalent on a machine — exactly which sites it may touch right now.
+export const WebExtFactsSchema = z.object({
+    // How a person would name it: "Chrome 141 on Windows".
+    browser: z.string(),
+    // Tabs open right now. A count rather than a list: the list is a tool call away and changes every minute,
+    // and a card that renders someone's open tabs is a card nobody wants to screenshot.
+    tabs: z.number(),
+    /* The sites the person has allowed, live from the browser's own permission store rather than from anything
+     * this daemon remembers. It is the answer to the question every reader of this card actually has, and the
+     * only honest source for it is the browser: a grant can be revoked in Chrome's UI without the sandbox
+     * being told. */
+    grants: z.array(WebExtGrantSchema),
+    // The extension's own kill switch, flipped in its popup. True ⇒ every tool refuses, and says so.
+    paused: z.boolean(),
+});
+export type WebExtFacts = z.infer<typeof WebExtFactsSchema>;
+export const WebExtSummarySchema = z.object({
+    // The capability id, the browser's name, and the prefix of its tools (mcp__<id>__click).
+    id: z.string(),
+    platform: z.string().min(1),
+    online: z.boolean(),
+    // The extension build, so a browser running an old one is visible rather than mysteriously lacking a tool.
+    version: z.string().optional(),
+    // Epoch ms of the last time this browser held a socket. Absent ⇒ it has not connected since this daemon
+    // booted: liveness is a fact about a socket, so a restart forgets it rather than claiming stale uptime.
+    lastSeen: z.number().optional(),
+    facts: WebExtFactsSchema.optional(),
+});
+export type WebExtSummary = z.infer<typeof WebExtSummarySchema>;
+export const WebExtsListSchema = z.object({ browsers: z.array(WebExtSummarySchema) });
+/* ---- handing a site's session to the sandbox: what the extension POSTs, and what comes back ----
+ *
+ * THE PAYLOAD IS A CREDENTIAL, the whole of one. It travels on its own HTTPS door (webext-protocol.ts's
+ * webextSessionUrl) rather than as an answer on the socket, because socket answers are MCP results and MCP
+ * results land in the model's context. Nothing here is ever logged, echoed in an error, or written anywhere
+ * but the target profile's cookie store. */
+export const WebExtCookieSchema = z.object({
+    name: z.string(),
+    value: z.string(),
+    // Chrome's own spelling, leading dot and all (".github.com"): it is what the browser stored, and rewriting
+    // it here is how a session arrives that the target site does not recognise.
+    domain: z.string(),
+    path: z.string(),
+    // Epoch SECONDS, Chrome's unit. Absent ⇒ a session cookie, which dies with the browser that receives it.
+    expires: z.number().optional(),
+    httpOnly: z.boolean(),
+    secure: z.boolean(),
+    sameSite: z.enum(["Strict", "Lax", "None"]),
+});
+export type WebExtCookie = z.infer<typeof WebExtCookieSchema>;
+export const WebExtSessionImportSchema = z.object({
+    // The `browser`-kind capability whose profile receives this. Named by the agent from the roster it can
+    // already read, so a session can only ever land in an account the owner had already created.
+    account: z.string().min(1),
+    // The site this came from, for the message the owner reads afterwards. Never used to place the cookies:
+    // each cookie carries its own domain.
+    origin: z.string().min(1),
+    // A ceiling rather than a guess: a big site's cookie jar for one registrable domain runs to dozens, and
+    // anything past this is a caller that misunderstood the tool, not a login.
+    cookies: z.array(WebExtCookieSchema).min(1).max(300),
+});
+export type WebExtSessionImport = z.infer<typeof WebExtSessionImportSchema>;