@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/schemas/provider-oauth.ts

@@ -1,21 +1,13 @@
 import { z } from "zod";
 import { AccountUsageSchema } from "./plan-limits.js";
 import { KeyedProviderSchema } from "./provider-subscriptions.js";
-// Claude uses the PKCE authorize-URL + paste-back handshake (start → exchange). Codex uses OpenAI's device-code
-// flow (start → poll): the browser signs in at verificationUri and enters userCode; the daemon polls until done.
-// A sandbox can hold several accounts per provider side by side: `id` is the daemon-minted store key, `label`
-// the user's display name (auto-filled from the sign-in identity where the token carries one). Tokens never
-// ride this shape, connection status is existence in the list.
+// Claude uses PKCE paste-back (start → exchange); Codex uses OpenAI's device-code flow (start → poll). A sandbox can
+// hold several accounts per provider; `id` is the store key, `label` the display name. Tokens never ride this shape —
+// connection is existence in the list.
 
 export const OauthAccountSchema = z.object({
     id: z.string().describe("The account's id, which is what a turn names to spend on it and what disconnecting takes."),
     label: z.string().describe("What it is called here, which somebody can change."),
-    // WHO this account signs in as, in the provider's own words. Anthropic returns the email and the
-    // organization alongside the tokens, so a connection can name itself instead of arriving as a second row
-    // called "Claude". Kept BESIDE `label` rather than folded into it: the label is the user's to rename, and a
-    // renamed account still has to be able to say whose it is. Absent when the provider tells us nothing (a
-    // pasted API key carries no identity), which is exactly when renaming is the only answer, so every
-    // sandbox-owned account can be renamed.
     email: z
         .string()
         .optional()
@@ -25,18 +17,11 @@ export const OauthAccountSchema = z.object({
     organization: z.string().optional().describe("Which organisation it belongs to, where the provider says."),
     scope: z.string().optional().describe("What the credential is permitted to do, in the provider's terms."),
     connectedAt: z.number().describe("When it was connected, in milliseconds."),
-    // Set only when the account's stored credential can no longer be refreshed (revoked/expired refresh token)
-    //, the user must reconnect. Absent ⇒ healthy or not-yet-probed; `detail` carries the reason for the UI.
-    // Provider-agnostic; only Codex probes it today (Claude refreshes on-demand, Grok's tokens are OpenCode's).
     needsReauth: z
         .boolean()
         .optional()
         .describe("Its stored credential can no longer be renewed and somebody has to sign in again. Absent means healthy, or not checked yet."),
     detail: z.string().optional().describe("Why, in words a person can act on."),
-    // The account's last known subscription-usage snapshot, so the picker can show what's left on each account
-    // before the user commits a turn to one. Absent until a reading exists for it, an unmeasured account reads
-    // as unknown, never 0%. Claude is the provider that fills it here, because its stream reports the windows;
-    // the routed subscriptions carry the identical field on TranslatorAccount, filled by a pulled reading.
     usage: AccountUsageSchema.optional().describe(
         "How full its plan limits were when last measured, so a picker can show what is left before committing work to it. Absent until a reading exists, which reads as unknown rather than as nothing left.",
     ),
@@ -48,12 +33,7 @@ export const OauthAccountListSchema = z.object({
         .describe("The connected accounts. Tokens never travel in this shape: being in this list is what connected means."),
 });
 export type OauthAccountList = z.infer<typeof OauthAccountListSchema>;
-/* RE-MEASURE THIS PROVIDER'S PLAN LIMITS BEFORE ANSWERING, rather than serving whatever reading is current
- * enough by the daemon's own bound. Every ordinary read of the list wants that bound, it is what keeps a page
- * load off the upstream quota endpoint, but a person who has just changed something about the account
- * (a seat downgraded, a plan swapped, another device's spend) is asking precisely whether the reading they can
- * see is still true, and an answer from the last minute cannot tell them. Read off the query string, so the
- * caller says it as `?force=1`. */
+// Read off the query string as `?force=1`.
 export const AccountListQuerySchema = z.object({
     force: z
         .stringbool()
@@ -64,24 +44,16 @@ export const AccountListQuerySchema = z.object({
 });
 // Address one account of a provider (disconnect, and the turn's `account`).
 export const AccountIdSchema = z.object({ id: z.string().min(1).describe("Which account.") });
-// Rename one account of a provider whose credential the sandbox owns. Blank ⇒ the daemon falls back to the
-// derived name, so clearing a label restores the sign-in identity rather than leaving a nameless row.
+// Only for accounts whose credential the sandbox itself owns.
 export const AccountRenameSchema = z.object({
     id: z.string().min(1).describe("Which account."),
     label: z.string().max(80).describe("The new name. Blank restores the one derived from the sign-in, rather than leaving a nameless row."),
 });
-/* ONE SIGN-IN SHAPE FOR EVERY ACCOUNT THE SANDBOX ITSELF HOLDS, whatever the vendor's mechanism underneath.
- *
- * Four handshakes used to answer four shapes, and the shapes differed in where the SECRET lived during the
- * handshake. Anthropic's is paste-back: the browser shows a code and the user brings it here. Cursor's PKCE
- * verifier must never leave the process that generated it (anyone holding it can redeem the login and mint a
- * durable key), so the daemon runs the whole flow and the caller only watches the account list. xAI's is a
- * device code. Meta's and Z.ai's mint the vendor's own key, by a device poll or by a redirect that dead-ends in
- * the user's address bar. Every one of them is now the daemon's to hold: nothing redeemable is on this shape,
- * and the one thing the caller can hand back (a code off a page, or the address a redirect landed on) goes to
- * `complete` with the attempt's handshake. `flow` says how the attempt ENDS, which is the only thing a card
- * cannot infer from the fields: a device sign-in finishes upstream and the account appears on its own; a
- * redirect needs the landing address brought back; a paste needs the code the page showed. */
+// One shape for every sign-in, whatever the vendor's mechanism; nothing redeemable rides on it, only the daemon ever
+// holds a secret. `flow` says how the attempt ends, which no other field can tell you:
+// device: finishes upstream; watch the account list.
+// redirect: needs the landing address brought back.
+// paste: needs the code the page showed.
 export const LoginFlowSchema = z.enum(["device", "redirect", "paste"]);
 export type LoginFlow = z.infer<typeof LoginFlowSchema>;
 export const LoginStartSchema = z.object({
@@ -100,32 +72,26 @@ export const LoginStartSchema = z.object({
     expiresAt: z.number().describe("When this attempt stops being answerable, in milliseconds, so a card can stop waiting instead of spinning."),
 });
 export type LoginStart = z.infer<typeof LoginStartSchema>;
-// The estate to sign in to, where a provider has more than one (Z.ai's international and mainland plans). Absent
-// takes the provider's default, which is what a provider with a single estate always sends.
+// e.g. Z.ai's international vs. mainland plans.
 export const LoginRequestSchema = z.object({
     variant: z.string().min(1).optional().describe("Which estate to sign in to. Absent takes the provider's default."),
 });
-/* The half a person brings back, for the two flows that have one: the code the page showed (a paste), or the
- * whole address a redirect landed on. Not the handshake's state, unlike the translator's version below: that
- * one addresses a session CLIProxyAPI holds, so the state has to travel, while this handshake is held right
- * here and taking the caller's word for its own state would be checking a claim against itself. */
+// Only the two flows needing something back (paste's code, redirect's address) supply one; no state field, unlike the
+// translator's — this handshake is held right here, so the caller's own state would be checking a claim against itself.
 export const LoginCompleteSchema = z.object({
     handshake: z.string().min(1).describe("Which attempt this belongs to."),
     code: z.string().optional().describe("The code the sign-in page showed, for a paste sign-in."),
     redirectUrl: z.string().optional().describe("The address the browser was sent to, whole, for a redirect sign-in. The grant is inside it."),
     label: z.string().optional().describe("What to call the account. Blank derives one from the sign-in."),
 });
-// What finishing hands back: the account, where the exchange answers with one at once (a paste); absent where
-// the daemon still has a mint to do behind the answer and the row lands in the account list minutes later.
+// Absent when the daemon still has minting to do; the row lands in the account list minutes later.
 export const LoginCompletedSchema = z.object({
     account: OauthAccountSchema.optional().describe("The account it connected, where the sign-in ends here. Absent means keep watching the account list."),
 });
-// Abandon a sign-in nobody completed, so the daemon stops polling the vendor for it. Ordinary tidiness rather
-// than a security boundary: an unanswered attempt also times out on its own (see `expiresAt`).
+// Tidiness, not a security boundary: an unanswered attempt also times out on its own (`expiresAt`).
 export const LoginCancelSchema = z.object({ handshake: z.string().min(1).describe("Which attempt to stop waiting on.") });
-// A routed-provider subscription login start (codex/grok/kimi/gemini via CLIProxyAPI). Device flows poll to
-// completion after the user approves upstream; redirect flows need the browser's landing URL pasted back. The
-// explicit flow discriminator matters even when a provider's verification URL already embeds its optional code.
+// codex/grok/kimi/gemini via CLIProxyAPI; `flow` is explicit even when a provider's URL already embeds an optional
+// code.
 export const TranslatorStartSchema = z.object({
     url: z.string().describe("The page to open."),
     code: z.string().describe("The one-time code, where the provider uses one."),
@@ -136,28 +102,15 @@ export const TranslatorStartSchema = z.object({
             "Which shape this is. A device sign-in finishes by itself and you poll the account list; a redirect needs the address it landed on handed back. Said outright rather than guessed at from whether a code happens to exist.",
         ),
 });
-// The paste-back half of a redirect login: the URL the provider sent the browser to, carrying the grant as
-// ?code=&state=. `state` ties it to the handshake that issued it, the translator rejects a mismatch.
+// Grant rides in the URL as `?code=&state=`.
 export const TranslatorCompleteSchema = z.object({
     provider: KeyedProviderSchema.describe("Which provider."),
     redirectUrl: z.string().min(1).describe("The address the browser was sent to, whole. The grant is inside it."),
     state: z.string().min(1).describe("The handshake this belongs to. A mismatch is refused."),
 });
-// A provider's model catalog, resolved daemon-side from live discovery with a persisted last-known-good list and
-// a seed floor (Grok via opencode.ts xaiModels, Codex via codex-models.ts, Claude via the Agent SDK's
-// supportedModels), never empty, so the picker is never blank. `label` is the provider's display name; `default`
-// is the model a fresh chat on that provider seeds (always present). Served by the one catalog route every
-// provider shares. `efforts` is the reasoning-effort tiers the model accepts (Claude reports them per model);
-// empty ⇒ the client's default tiers.
-//
-// EVERY field here is provider-reported, nothing about a model is curated in this repo, so a new release or a
-// renamed family flows to the UI with no code change. Providers differ in how much they publish: the Claude
-// Agent SDK reports a display name, a capability description, effort tiers, and capability flags, while the
-// Some OpenAI-compatible /v1/models endpoints report ids only, those rows render label-only, and that absence
-// is the honest answer rather than something to paper over with a hand-written table.
-//
-// ORDER IS MEANINGFUL: `models` arrives in the provider's own preference order, which is what the picker sorts
-// by, and `default` is the provider's own default. Neither is re-ranked locally.
+// Resolved daemon-side (live discovery, a persisted fallback, a seed floor), never empty. Every field is
+// provider-reported, nothing curated here, so an id-only provider renders label-only rather than a hand-written table.
+// Order is meaningful: the provider's own preference order, never re-ranked.
 export const ModelBadgeSchema = z.enum(["reasoning", "fast"]);
 export type ModelBadge = z.infer<typeof ModelBadgeSchema>;
 export const ModelSchema = z.object({
@@ -171,14 +124,8 @@ export const ModelSchema = z.object({
             "What it is good for, in the provider's own words. Absent where the provider publishes only ids, which is the honest answer rather than something to paper over with a hand-written table.",
         ),
     badges: z.array(ModelBadgeSchema).optional().describe("What it is known for, where the provider says so."),
-    /* HOW MUCH THE SERVER WILL ACCEPT IN ONE REQUEST, where the server says so, and the one field here that a
-     * turn is refused against rather than merely rendered (agent/context-budget.ts).
-     *
-     * The SERVED window, never the weights' training length. An inference server takes its context size from a
-     * flag and then clamps it to the memory it actually has, so a 3B model whose GGUF advertises 131k can be
-     * serving 16k, and it is the 16k that refuses the request. Read from llama.cpp's /props and vLLM's
-     * `max_model_len`; absent for every provider that publishes no such number, which is most of them, and
-     * absent means unknown rather than unlimited: nothing gates on a window it was never told. */
+    // The served window, not the training length — memory can clamp it lower. Turns are refused against this. Absent
+    // means unknown, never unlimited.
     contextWindow: z.number().optional().describe("How many tokens this model will accept in one request, where the server publishes it."),
 });
 export type Model = z.infer<typeof ModelSchema>;

package/src/schemas/provider-subscriptions.ts

@@ -1,16 +1,7 @@
 import { z } from "zod";
-import { TRANSLATOR_PROVIDERS, type TranslatorProvider } from "../provider-specs.js";
-// The providers whose model can run UNDER the Claude Code harness through the bundled translator (CLIProxyAPI),
-// which holds their SUBSCRIPTION OAuth and re-serves it behind an Anthropic endpoint. The `claude` provider is
-// absent, native Anthropic OAuth serves it directly, without the translator. Codex, Grok and Gemini also have a
-// native runtime and so carry the harness axis; Kimi is routed-only, so its turns always use Claude Code.
-//
-// Gemini is in BOTH camps and that is not a contradiction: its native runtime (OpenCode) reaches Google through
-// this same translator and these same auth files. The harness axis picks the loop; the translator is the road
-// under either.
-//
-// DERIVED from the provider table's `auth.kind`, never listed here: this enum and the accounts schema built on
-// it (TranslatorAccountsSchema) and the daemon's CLIProxyAPI id map are three readings of one fact, and they
-// used to be three hand-kept lists that had to agree.
+import { TRANSLATOR_PROVIDERS, type TranslatorProvider } from "../models/provider-specs.js";
+// Providers reachable via the translator (CLIProxyAPI), which holds their subscription OAuth behind an Anthropic
+// endpoint; `claude` is absent, served natively. Gemini is in both camps: its native runtime reaches Google through
+// this same translator. Derived from the provider table's `auth.kind`, never listed here.
 export const KeyedProviderSchema = z.enum(TRANSLATOR_PROVIDERS);
 export type KeyedProvider = TranslatorProvider;

package/src/schemas/public.ts

@@ -1,21 +1,15 @@
 // public: the workspace outbox
 import { z } from "zod";
-// The mirror image of the reference shelf. Files under the workspace's `public/` directory are served as static
-// files at public-<slot>-<sandboxId>.<zone>, with no auth in front of them, the process-free half of preview
-// (a panel needs a running dev server; a file needs nothing). The directory's existence is the switch: it is
-// absent until something is published and removed again when the last file leaves, so "publishing is off" is
-// the resting state rather than a flag someone has to remember to set back.
+// Files under `public/` are served as static, unauthenticated files at public-<slot>-<sandboxId>.<zone> — the
+// process-free half of preview. The directory's existence is the switch: absent until something is published, removed
+// again when the last file leaves.
 
 export const PublicFileSchema = z.object({
-    // Outbox-relative, forward-slash ("report.pdf", "site/index.html").
+    // Forward-slash, e.g. "report.pdf", "site/index.html".
     path: z.string().describe("Where it sits inside the outbox."),
     size: z.number().describe("Size in bytes."),
     modifiedAt: z.number().describe("When it last changed, in milliseconds."),
-    // The file's public URL. Absent when the sandbox has no tunnel, or when a guard refuses this file.
     url: z.string().optional().describe("Its public address. Absent when this sandbox has no outside address, or when the file is being refused."),
-    // Why a file sitting in the outbox is NOT served, a hidden name, a credential-shaped name, contents that
-    // match a known token format, or sheer size. The publisher reads it here; a stranger requesting the same
-    // file only ever gets the same 404 every other miss returns, so this list can't be probed from outside.
     blocked: z
         .string()
         .optional()
@@ -24,15 +18,11 @@ export const PublicFileSchema = z.object({
         ),
 });
 export type PublicFile = z.infer<typeof PublicFileSchema>;
-// `url` is the outbox root, the base every file's URL hangs off, and what the view shows as "your public
-// address". Absent on a loopback/no-tunnel sandbox, which has nowhere to publish to.
 export const PublicListSchema = z.object({
     url: z.string().optional().describe("Your public address, which every file's own hangs off. Absent on a sandbox with nowhere to publish to."),
     files: z.array(PublicFileSchema).describe("What the outbox holds."),
 });
 export type PublicList = z.infer<typeof PublicListSchema>;
-// A WORKSPACE-relative path (the space the file tree speaks) to copy into the outbox. A copy, not a move: the
-// repo a build output came from must not lose it because someone shared it.
 export const PublishSchema = z.object({
     path: z
         .string()
@@ -41,7 +31,6 @@ export const PublishSchema = z.object({
             "What to publish, as a workspace path. It is copied rather than moved, so a repository does not lose its build output because somebody shared it.",
         ),
 });
-// An OUTBOX-relative path to withdraw, the path space PublicFile.path speaks, not the workspace's.
 export const UnpublishSchema = z.object({
     path: z.string().min(1).describe("What to withdraw, as a path inside the outbox rather than a workspace path."),
 });

package/src/schemas/push.ts

@@ -1,19 +1,12 @@
 // push: notifications to the owner's devices
 import { z } from "zod";
-// The daemon is the only tier that knows what the agent is doing, so it is the sender. A registration is
-// per-DEVICE and comes in two kinds, distinguished by who can be posted to directly:
-//   webpush  a browser (including the Android TWA, which IS Chrome). The endpoint is minted by that
-//            browser's push service and the daemon sends to it directly, end-to-end encrypted.
-//   relay    a native app install (the iOS shell), whose OS push service (APNs) only accepts sends from
-//            the app's vendor. The daemon posts plain JSON to the platform's push relay, which holds the
-//            vendor credential and forwards. The payload transits the relay readable, the price of Apple
-//            requiring the vendor in the loop, which is why the channel records WHERE to post (`url`)
-//            rather than the daemon knowing any platform by name.
-// Channels live here and not on the platform because the daemon is on the command path: the platform would
-// have to be told about every turn to be useful.
+// The daemon is the only tier that knows what the agent is doing, so it is the sender. A registration is per-device, in
+// two kinds:
+// webpush: a browser (including the Android TWA); the daemon sends to its push service directly, end-to-end encrypted.
+// relay: a native app (iOS); its OS push service only accepts sends from the vendor, so the daemon posts through a
+// relay, which can read the payload.
 
-// A browser's PushSubscription, in the exact shape `web-push` consumes, the browser produces it via
-// PushManager.subscribe() and the client posts it back verbatim, so the daemon never reshapes it.
+// Exact shape `web-push` consumes, from `PushManager.subscribe()`; posted back verbatim.
 export const WebPushChannelSchema = z.object({
     kind: z.literal("webpush").describe("A browser, which the sandbox can reach directly and encrypt end to end."),
     endpoint: z.url().describe("Where that browser's push service accepts sends. It also identifies the device everywhere else in this group."),
@@ -25,16 +18,12 @@ export const WebPushChannelSchema = z.object({
         .describe("What the browser handed you when it subscribed. Post it back exactly as it came; nothing reshapes it."),
 });
 export type WebPushChannel = z.infer<typeof WebPushChannelSchema>;
-// A native install, addressed through a push relay. `secret` is the send capability the relay minted at
-// registration, the daemon proves it may notify this device by presenting it; the relay never learns which
-// sandbox is calling. `deviceId` doubles as the channel's identity (see channelId below).
 export const RelayChannelSchema = z.object({
     kind: z
         .literal("relay")
         .describe(
             "A native app, whose operating system only accepts sends from the app's publisher, so the sandbox posts through a relay instead. The message passes through that relay readable, which is the price of the publisher having to be in the loop.",
         ),
-    // The absolute URL the daemon POSTs a send to, minted by the relay at registration, stored verbatim.
     url: z.url().describe("Where to post a send. Recorded rather than assumed, so the sandbox need not know any platform by name."),
     deviceId: z.string().min(1).describe("The device's id, which also identifies this registration everywhere else in this group."),
     secret: z.string().min(1).describe("Proof that this sandbox may notify this device. The relay never learns which sandbox is calling."),
@@ -42,16 +31,9 @@ export const RelayChannelSchema = z.object({
 export type RelayChannel = z.infer<typeof RelayChannelSchema>;
 export const PushChannelSchema = z.discriminatedUnion("kind", [WebPushChannelSchema, RelayChannelSchema]);
 export type PushChannel = z.infer<typeof PushChannelSchema>;
-// The one identity every push route speaks: subscribe upserts by it, unsubscribe and the config probe name
-// devices by it. Shape-derived so the daemon and the web app can never disagree about what identifies a row,
-// a browser is its push endpoint, a native install is the deviceId its relay registration minted.
+// The one identity every push route uses (subscribe, unsubscribe, config); derived from the channel's own shape so the
+// daemon and web app can't disagree about it.
 export const channelId = (channel: PushChannel): string => (channel.kind === "webpush" ? channel.endpoint : channel.deviceId);
-// What the service worker renders. `url` is the in-app route the notification opens (the click handler
-// focuses an existing tab there rather than spawning a new one); `tag` collapses repeats, a second
-// "waiting on you" for the same conversation REPLACES the first instead of stacking. Push payloads are
-// capped by the push services themselves (~4KB after encryption), which is why nothing here carries a
-// transcript or a diff, the notification is a pointer back into the workspace, not a delivery mechanism
-// for content.
 export const PushNotificationSchema = z.object({
     title: z.string().min(1).describe("The headline."),
     body: z
@@ -64,8 +46,6 @@ export const PushNotificationSchema = z.object({
         .string()
         .optional()
         .describe("Collapses repeats: a second notification with the same tag replaces the first instead of stacking beside it."),
-    // Whether the notification stays on screen until dismissed. Set for the "agent is blocked on you" cases,
-    // where a notification that auto-dismisses is a request that silently went unanswered.
     requireInteraction: z
         .boolean()
         .optional()
@@ -74,9 +54,6 @@ export const PushNotificationSchema = z.object({
         ),
 });
 export type PushNotification = z.infer<typeof PushNotificationSchema>;
-// The VAPID public key a browser needs to subscribe (native shells ignore it), plus whether the asking
-// device's channel is already known, so the settings toggle can render its true state instead of trusting
-// the device's permission alone (a granted permission with no daemon-side row would notify nothing).
 export const PushConfigSchema = z.object({
     publicKey: z.string().describe("The key a browser needs in order to subscribe. Native apps ignore it."),
     subscribed: z
@@ -88,8 +65,6 @@ export const PushConfigSchema = z.object({
 export const PushChannelIdSchema = z.object({
     id: z.string().min(1).describe("Which device: a browser's push address, or a native install's device id."),
 });
-// The optional `id` says WHICH device is asking (see channelId); without it `subscribed` could only speak
-// for the sandbox as a whole, which is never the question the settings toggle needs answered.
 export const PushConfigQuerySchema = z.object({
     id: z
         .string()
@@ -97,9 +72,6 @@ export const PushConfigQuerySchema = z.object({
         .optional()
         .describe("Which device is asking. Without it the answer can only speak for the sandbox as a whole, which is rarely the question."),
 });
-// What a test send actually achieved. `{ ok: true }` would be a lie the one place it matters most: the button
-// exists to prove a chain the user cannot inspect, so "the daemon accepted the request" is not the answer to
-// 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()

package/src/schemas/secrets.ts

@@ -1,8 +1,7 @@
 // secrets: user-supplied env-var secrets the daemon writes to desired-state/.env
 import { z } from "zod";
-// The web posts a Cloudflare token / GitHub PAT / another-host SSH key straight to the sandbox daemon (never
-// through the platform); `apply` reloads .env each run so a new secret is picked up with NO restart. `list`
-// returns KEYS ONLY, the values never leave the sandbox; `reveal` is the one deliberate, owner-only exception.
+// Straight to the sandbox daemon, never through the platform; `apply` reloads .env with no restart. `list` returns keys
+// only; `reveal` is the one owner-only exception that returns a value.
 export const SecretSetSchema = z.object({
     key: z
         .string()
@@ -17,28 +16,8 @@ export const SecretKeysSchema = z.object({
 export const SecretKeyParamSchema = z.object({ key: z.string().describe("Which secret, by name.") });
 export const SecretRevealSchema = z.object({ value: z.string().describe("The value itself. The only place in this API one is ever returned.") });
 
-/* A CREDENTIAL THE AGENT MAY NOT USE UNTIL A NAMED PERSON SAYS SO, and who that person is.
- *
- * Masking already answers "can the model SEE this value" (no: it reads a `{{secret:name}}` reference), and
- * the answer was enough while the only question was disclosure. It is not the whole question. A reference the
- * model can write is a credential the model can SPEND, at whatever moment its own reasoning arrives at, and
- * for the small set of credentials where one wrong spend is the incident — the production database's
- * password, the company X account, the card-shaped connector — the owner wants the moment itself decided by a
- * person, not the storage of the value. That is what a gate is: not a second lock on the vault, a REQUIRED
- * CLICK in front of the exit.
- *
- * WHAT IT IS NOT A WALL AGAINST. A shell in this container runs as the workspace's owner and the policy file
- * sits beside the vault it guards; anything that can read one can read the other, and a compromised container
- * is out of scope here exactly as it is for the vault (SECURITY.md). The gate is a wall against the AGENT's
- * own judgment being the last word — a prompt-injected model can ask for a release and cannot grant itself
- * one — and against the ordinary accident of a turn reaching for the live credential when the staging one was
- * meant.
- *
- * THE APPROVERS ARE AN EXACT LIST, not a role floor, and the owner is not on it implicitly. "Only Bob may
- * release the production password" is the sentence people actually mean, and a floor cannot say it: a floor of
- * `maintainer` says "anyone senior enough", which is the thing the owner was trying to narrow. So the list is
- * the list, the owner adds themselves when they mean themselves, and a click from anybody else is refused
- * server-side with the card left standing for whoever can. */
+// A wall against the agent's own judgment, not a compromised container: a shell here can read the policy same as the
+// vault. Approvers are an exact list, never a role floor; the owner isn't on it unless added.
 export const CredentialGateScopeSchema = z
     .enum(["use", "conversation"])
     .describe(
@@ -46,29 +25,21 @@ export const CredentialGateScopeSchema = z
     );
 export type CredentialGateScope = z.infer<typeof CredentialGateScopeSchema>;
 
-// What a gate is ABOUT: one stored secret by its reference name, or one whole connected capability (a
-// connector's env, a browser account's profile, an MCP server) by its id. Two kinds rather than one because
-// they are withheld differently — a secret is refused at the exit it would resolve at, a capability is simply
-// never mounted for the turn — and the subject namespaces are disjoint anyway (env keys are SCREAMING_SNAKE).
+// Withheld differently: a secret is refused at the exit it would resolve at, a capability is simply never mounted for
+// the turn.
 export const CredentialGateKindSchema = z
     .enum(["secret", "capability"])
     .describe("Whether this gate covers one stored secret, by the name a reference carries, or one whole connected capability, by its id.");
 export type CredentialGateKind = z.infer<typeof CredentialGateKindSchema>;
 
-/* WHICH EXIT A RELEASE WAS ASKED FOR, so the card can say what is about to happen in the reader's terms
- * rather than in the daemon's. The three secret exits are the ones the use ledger already names (a shell
- * command, a JS run's script, a browser keystroke); `session` is a whole capability being mounted for the
- * turn (a signed-in browser profile, a connector's env, an MCP server), and `otp` is one derived one-time
- * code off a stored TOTP seed. */
 export const CredentialLaneSchema = z
     .enum(["shell", "code", "browser", "session", "otp"])
     .describe("What the credential was about to be used for: a shell command, a script, typing into a page, mounting a connected account, or one one-time code.");
 export type CredentialLane = z.infer<typeof CredentialLaneSchema>;
 
 export const CredentialGateSchema = z.object({
-    // An env/generated KEY (`DATABASE_URL`), or a capability id (`reddit`, `komodo`). A vault name's field
-    // half (`reddit/password`) is deliberately NOT a subject: gating one field of a connected account and not
-    // its neighbours would be a gate with a hole in it, so the whole capability is the unit.
+    // Never a vault field (`reddit/password`): gating part of a capability and not the rest would be a gate with a hole
+    // in it.
     subject: z.string().min(1).describe("What is gated: a secret's name, or a connected capability's id."),
     kind: CredentialGateKindSchema,
     approvers: z
@@ -92,17 +63,12 @@ export const CredentialGateSubjectParamSchema = z.object({
     subject: z.string().min(1).describe("Which gate, by the secret name or capability id it covers."),
 });
 
-/* THE AGENT'S OWN DOOR, `secrets request <subject> --why "…"`. A gated capability is ABSENT from a turn
- * rather than refused inside it (its profile is not mounted, its env is not exported), so the model cannot
- * discover the gate by tripping over it the way a secret reference does — it would conclude the account is
- * disconnected and go looking for another road. This route is the road: it raises the same card the exits
- * raise, and a release is worded as a grant for the REST OF THE CONVERSATION, because a session-shaped
- * credential cannot be handed out for one use. */
+// A gated capability is absent from a turn, not refused inside it, so the model can't discover the gate by tripping
+// over it. A release here covers the rest of the conversation, since a session credential can't be single-use.
 export const CredentialRequestSchema = z.object({
     subject: z.string().min(1).describe("What to ask for: the secret's name, or the connected capability's id."),
     why: z.string().max(280).optional().describe("One line on what it is for. The only words on the card that are the agent's."),
-    // Which conversation's chat the card goes up in, filled by the CLI from the turn's own environment, so
-    // the model cannot aim a card at somebody else's conversation.
+    // Filled by the CLI itself, so the model cannot aim a card at somebody else's conversation.
     conversationId: z.string().optional().describe("Which conversation to raise the card in. The CLI fills this from the running turn."),
 });
 
@@ -112,27 +78,25 @@ export const CredentialGrantSchema = z.object({
     message: z.string().describe("What the grant means in practice, and what to do next."),
 });
 
-// One entry per secret the sandbox knows about, across every store: intent env secrets and intentic-generated
-// passwords (from the desired-state repo), capability credentials, and AI-provider accounts. Values never ride
-// this shape, `revealable` says whether `reveal` can return one (everything but provider accounts).
+// Across every store: env/generated secrets, capability credentials, AI-provider accounts. Values never ride this
+// shape; `revealable` says whether `reveal` can return one (everything but provider accounts).
 export const SecretInventoryEntrySchema = z.object({
-    // Env-var key for env|generated; `<provider>:<accountId>` for provider entries; capability instance id
-    // otherwise. Unique within the inventory, several accounts of one provider each get their own entry.
+    // Env-var key for env|generated; `<provider>:<accountId>` for provider; capability instance id otherwise.
     key: z.string().describe("What identifies it. Unique across the whole inventory, so several accounts of one provider each get their own entry."),
     kind: z
         .enum(["env", "generated", "capability", "provider"])
         .describe("Where it came from: you set it, the sandbox generated it, a connection needs it, or it is a model account's credential."),
-    // Display name for provider entries: "<ProviderName> · <accountLabel>". Absent on env/generated entries.
+    // e.g. "<ProviderName> · <accountLabel>" for provider entries; absent on env/generated.
     label: z.string().optional().describe("A friendlier name, for entries that have one."),
     status: z.enum(["missing", "set", "connected"]).describe("Whether it exists and, for a connection, whether it is working."),
-    // The artifact resources referencing this secret ({$secret} refs); [] for capability/provider entries.
+    // Resources referencing it via `{$secret}` refs.
     requiredBy: z
         .array(z.object({ resourceId: z.string().describe("Which resource."), type: z.string().describe("What kind of resource it is.") }))
         .describe("What is waiting on it. Empty for a connection's or an account's own credential."),
-    // Human-readable provenance, e.g. "desired-state/.env", the UI's "where does this live" line.
+    // e.g. "desired-state/.env".
     storedAt: z.string().describe("Where it actually lives, in words."),
     revealable: z.boolean().describe("Whether its value can be shown at all. Everything except a model account's credential can be."),
-    // Forgejo Actions replication state, present only after adopt on env|generated entries.
+    // Forgejo Actions only, and only after adopt, on env|generated entries.
     ci: z
         .object({
             synced: z.boolean().describe("Whether the pipeline has it."),
@@ -140,10 +104,7 @@ export const SecretInventoryEntrySchema = z.object({
         })
         .optional()
         .describe("Whether a copy has been given to the build pipeline."),
-    /* The newest row of the use ledger that concerns this entry, when the agent last SPENT it, on which lane
-     * (a shell command, a JS run's script, a browser field), and where it went (the head of the command or
-     * script, or the page's host). Names and destinations only, never values. Absent while a secret has never
-     * been used, which most never are. */
+    // Records only the lane and a destination (command/script head, or page host) — never values.
     lastUse: z
         .object({
             at: z.number().describe("When, in milliseconds."),
@@ -152,16 +113,11 @@ export const SecretInventoryEntrySchema = z.object({
                 .string()
                 .optional()
                 .describe("Where it went: the start of the command or script, or the site. Names and destinations only, never values."),
-            // Who released it, when a gate made that use somebody's decision. Absent on an ungated use, which
-            // is nearly all of them: the ledger row records a person only where a person was actually asked.
             approvedBy: z.string().optional().describe("Who released it for that use, when it is gated. Absent when nothing had to be approved."),
         })
         .optional()
         .describe("The last time an agent actually spent this secret. Absent while it never has been, which most never are."),
-    /* THE APPROVAL THIS ENTRY IS BEHIND, joined on from the gate policy so the row can say "needs approval
-     * from Bob" without a second call. Absent on the overwhelming majority of entries: gating is for the few
-     * credentials where one wrong use is the incident, and a sandbox where everything asks is a sandbox where
-     * nobody reads the cards. */
+    // Joined from the gate policy, so the row can name the approver without a second call.
     gate: z
         .object({
             approvers: z.array(z.string()).describe("Who may release it, by email. Nobody else can, whatever their role."),