@intentic/sandbox-contract 1.232.0 → 1.233.0

package/src/schemas/provider-oauth.ts

@@ -0,0 +1,191 @@
+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.
+
+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()
+        .describe(
+            "Who it signs in as, in the provider's own words. Kept beside the label rather than folded into it, so a renamed account can still say whose it is. Absent when the provider says nothing, which is exactly when renaming is the only answer.",
+        ),
+    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.",
+    ),
+});
+export type OauthAccount = z.infer<typeof OauthAccountSchema>;
+export const OauthAccountListSchema = z.object({
+    accounts: z
+        .array(OauthAccountSchema)
+        .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`. */
+export const AccountListQuerySchema = z.object({
+    force: z
+        .stringbool()
+        .default(false)
+        .describe(
+            "Measure the plan limits again before answering, rather than serving a recent reading. Slower, and the right thing when somebody has just changed a plan and is asking whether what they can see is still true.",
+        ),
+});
+// 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 (Claude, Kimi). Blank ⇒ the daemon falls
+// back to the derived name, so clearing a label restores the sign-in identity rather than leaving a nameless
+// row. Grok is absent for the same reason it holds one account: OpenCode owns that credential, not this store.
+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."),
+});
+// The completing calls carry the user-chosen label (blank ⇒ the daemon derives one from the sign-in identity
+// or a provider default).
+export const OauthExchangeSchema = z.object({
+    code: z.string().min(1).describe("The code the sign-in handed back."),
+    verifier: z.string().min(1).describe("The proof from the start of the handshake, which is what stops somebody else's code being redeemed here."),
+    state: z.string().min(1).describe("The handshake this belongs to. A mismatch is refused."),
+    label: z.string().optional().describe("What to call the account. Blank derives one from the sign-in."),
+});
+export const AuthorizeChallengeSchema = z.object({
+    authorizeUrl: z.string().describe("Where to send somebody to sign in."),
+    verifier: z.string().describe("Keep this and send it back when finishing. It is what proves the code that comes back belongs to this handshake."),
+    state: z.string().describe("The handshake's own id, sent back with it."),
+});
+/* CURSOR'S SIGN-IN START. A third login shape, and the reason it is not one of the two above is where the
+ * SECRET lives during the handshake.
+ *
+ * Claude's is paste-back: the browser receives a code and the caller hands it plus its verifier to `exchange`,
+ * so the handshake's proof has to travel on the wire and AuthorizeChallengeSchema carries it. 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 starts the whole flow, keeps the verifier in memory, polls Cursor itself, and
+ * writes the account when it lands. Nothing redeemable is on this shape at all.
+ *
+ * Which makes it behave like a DEVICE flow from the caller's side (open the page, then watch the account list),
+ * except that there is no one-time code to display: the login page is addressed to this handshake already. So
+ * DeviceStartSchema's `code` would be a permanently blank field on every card, and TranslatorStartSchema's
+ * `state` a value nothing sends back. `handshake` is neither, it is a cancellation handle. */
+export const CursorLoginStartSchema = z.object({
+    url: z.string().describe("The page to open and sign in on. It is already addressed to this attempt, so there is no code to type."),
+    handshake: z
+        .string()
+        .describe(
+            "This attempt's id, for abandoning it. Not a credential and not redeemable: the proof that finishes the sign-in never leaves the sandbox.",
+        ),
+    expiresAt: z.number().describe("When this attempt stops being answerable, in milliseconds, so a card can stop waiting instead of spinning."),
+});
+export type CursorLoginStart = z.infer<typeof CursorLoginStartSchema>;
+// Abandon a sign-in nobody completed, so the daemon stops polling Cursor for it. Ordinary tidiness rather than
+// a security boundary: an unanswered attempt also times out on its own (see `expiresAt`).
+export const CursorLoginCancelSchema = z.object({ handshake: z.string().min(1).describe("Which attempt to stop waiting on.") });
+// xAI Grok (via OpenCode) uses subscription OAuth via the headless device-code method. `start` returns the
+// `url` the user opens (xAI's verification_uri_complete, which pre-fills the code) and `code`, the same
+// one-time code, surfaced so the card matches x.ai exactly. There is no paste-back: OpenCode polls to
+// completion and the UI polls `/grok/accounts`.
+// ponytail: OpenCode holds one xAI auth per data dir, so Grok stays single-account, the list is 0 or 1. Per
+// account would need an OpenCode server per data dir; add when there's demand.
+// A device-code login start: the verification URL + the one-time code the user enters there. The native Grok
+// flow (via OpenCode), see TranslatorStartSchema for the routed-provider connect, which adds `state`.
+export const DeviceStartSchema = z.object({
+    url: z.string().describe("The page to open, which already has the code in it."),
+    code: z
+        .string()
+        .describe(
+            "The one-time code, shown as well so the page and the card say the same thing. Nothing is pasted back: the sandbox waits for the sign-in to complete on its own.",
+        ),
+});
+// 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.
+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."),
+    state: z.string().describe("The handshake's id, which the finishing call sends back."),
+    flow: z
+        .enum(["device", "redirect"])
+        .describe(
+            "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.
+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.
+export const ModelBadgeSchema = z.enum(["reasoning", "fast"]);
+export type ModelBadge = z.infer<typeof ModelBadgeSchema>;
+export const ModelSchema = z.object({
+    id: z.string().describe("What to name when asking for this model."),
+    label: z.string().describe("What to call it on screen."),
+    efforts: z.array(z.string()).optional().describe("The thinking levels it accepts, where the provider says. Empty means use your own defaults."),
+    description: z
+        .string()
+        .optional()
+        .describe(
+            "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. */
+    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>;
+export const ModelsSchema = z.object({
+    models: z.array(ModelSchema).describe("What this provider serves, in its own preference order, which is not rearranged here. Never empty."),
+    default: z.string().describe("Which one a fresh conversation starts on. Always present."),
+});

package/src/schemas/provider-subscriptions.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+// 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.
+export const KeyedProviderSchema = z.enum(["codex", "grok", "kimi", "gemini"]);
+export type KeyedProvider = z.infer<typeof KeyedProviderSchema>;

package/src/schemas/public.ts

@@ -0,0 +1,52 @@
+// 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.
+
+export const PublicFileSchema = z.object({
+    // Outbox-relative, forward-slash ("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()
+        .describe(
+            "Why a file sitting in the outbox is not being served: a hidden name, a credential-shaped name, contents that look like a token, or sheer size. Only the publisher sees this; a stranger asking for the same file gets the same nothing every other miss gets.",
+        ),
+});
+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()
+        .min(1)
+        .describe(
+            "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."),
+});
+export const PublishResultSchema = z.object({
+    path: z.string().describe("Where it landed inside the outbox."),
+    url: z.string().optional().describe("Its public address. Absent on a sandbox with nowhere to publish to."),
+});
+export type PublishResult = z.infer<typeof PublishResultSchema>;

package/src/schemas/push.ts

@@ -0,0 +1,112 @@
+// 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.
+
+// 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.
+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."),
+    keys: z
+        .object({
+            p256dh: z.string().min(1).describe("The browser's public key, for encrypting what is sent."),
+            auth: z.string().min(1).describe("The browser's secret, for the same."),
+        })
+        .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."),
+});
+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.
+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
+        .string()
+        .describe(
+            "The line under it. Push services cap the whole payload at a few kilobytes, which is why nothing here carries a transcript or a diff: a notification is a pointer back, not a delivery.",
+        ),
+    url: z.string().optional().describe("Where tapping it goes. An existing tab is focused rather than a new one opened."),
+    tag: z
+        .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()
+        .describe(
+            "Keep it on screen until it is dismissed. Used when the agent is waiting for you, where one that fades away is a question that went unanswered in silence.",
+        ),
+});
+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
+        .boolean()
+        .describe(
+            "Whether the asking device is already registered, so a toggle can show its real state instead of trusting the device's own permission, which can be granted with nothing behind it.",
+        ),
+});
+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()
+        .min(1)
+        .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()
+        .int()
+        .nonnegative()
+        .describe(
+            "How many devices actually accepted it. A count rather than a yes, because this button exists to prove a chain nobody can inspect, and the sandbox having accepted the request is not the question being asked.",
+        ),
+});
+export type PushTest = z.infer<typeof PushTestSchema>;

package/src/schemas/secrets.ts

@@ -0,0 +1,68 @@
+// 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.
+export const SecretSetSchema = z.object({
+    key: z
+        .string()
+        .regex(/^[A-Za-z_][A-Za-z0-9_]*$/)
+        .max(128)
+        .describe("The name to store it under, which is the name a process will find it by."),
+    value: z.string().min(1).describe("The value. It goes straight to your sandbox and never through the platform."),
+});
+export const SecretKeysSchema = z.object({
+    keys: z.array(z.string()).describe("The names that exist here. Only the names: the values never leave the sandbox."),
+});
+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.") });
+// 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).
+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.
+    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.
+    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.
+    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.
+    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.
+    ci: z
+        .object({
+            synced: z.boolean().describe("Whether the pipeline has it."),
+            pushedAt: z.string().optional().describe("When it was last sent there."),
+        })
+        .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. */
+    lastUse: z
+        .object({
+            at: z.number().describe("When, in milliseconds."),
+            lane: z.enum(["shell", "code", "browser"]).describe("How it was used: a command, a script, or typed into a page."),
+            detail: z
+                .string()
+                .optional()
+                .describe("Where it went: the start of the command or script, or the site. Names and destinations only, never values."),
+        })
+        .optional()
+        .describe("The last time an agent actually spent this secret. Absent while it never has been, which most never are."),
+});
+export type SecretInventoryEntry = z.infer<typeof SecretInventoryEntrySchema>;
+export const SecretInventorySchema = z.object({
+    entries: z
+        .array(SecretInventoryEntrySchema)
+        .describe("One entry per secret this sandbox knows about, from every place they live. No values, ever."),
+});

package/src/schemas/sessions.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { MatchSnippetSchema } from "./agents.js";
+export const SessionIdParamSchema = z.object({ id: z.string().describe("Which past conversation.") });
+export const SessionSummarySchema = z.object({
+    id: z.string().describe("Its id."),
+    title: z.string().describe("What it is called."),
+    updatedAt: z.number().describe("When it last moved, in milliseconds."),
+    // Why a searched session matched: the line the query hit, windowed around it, and who said it. Absent on an
+    // unfiltered list, and on a match the title already shows, a snippet repeating the row's own heading is
+    // noise, not evidence. See AgentMatchSchema for the same field on the fleet's side.
+    snippet: MatchSnippetSchema.optional().describe(
+        "Why a search matched: the line it hit, with a little around it, and who said it. Absent on an unfiltered list, and on a match the title already shows, where repeating it would be noise rather than evidence.",
+    ),
+});
+export type SessionSummary = z.infer<typeof SessionSummarySchema>;
+export const SessionsListSchema = z.object({ sessions: z.array(SessionSummarySchema).describe("Past conversations, newest first.") });