@intentic/sandbox-contract 1.316.0 → 1.318.0

package/src/schemas/needs.ts

@@ -0,0 +1,301 @@
+import { z } from "zod";
+
+// A need: something an agent cannot finish its task without that only a person can provide (a connection, a secret's
+// value, wider reach, a tool in the image). Unlike a parked card it outlives the turn that raised it: the sandbox keeps
+// it until someone answers, draws it wherever it is waiting, and wakes the conversation when it is met
+// (docs/architecture/needs.md). Every word on a need is the daemon's except `why`, the agent's own case.
+
+export const NEED_KINDS = ["capability", "secret", "grant", "release", "environment"] as const;
+export const NeedKindSchema = z.enum(NEED_KINDS).describe("What is being asked for: a connection, a secret's value, wider reach, a gated credential, or a tool in the image.");
+export type NeedKind = z.infer<typeof NeedKindSchema>;
+
+// `working` is a yes still being carried out: a connection whose form is open, an overlay approved but not yet built.
+export const NeedStatusSchema = z
+    .enum(["open", "working", "met", "declined", "cancelled"])
+    .describe(
+        "Where it stands: open (waiting on a person), working (a person said yes and it is being set up), met, declined, or cancelled (the agent withdrew it, or its conversation went away).",
+    );
+export type NeedStatus = z.infer<typeof NeedStatusSchema>;
+
+export const OPEN_NEED_STATUSES: readonly NeedStatus[] = ["open", "working"];
+export const isOpenNeed = (need: { readonly status: NeedStatus }): boolean => OPEN_NEED_STATUSES.includes(need.status);
+
+// A setting value as a form holds it: every field of a catalog entry is a string on the way in.
+const FieldValuesSchema = z.record(z.string(), z.string());
+
+export const CapabilityNeedModeSchema = z
+    .enum(["connect", "reconnect", "change"])
+    .describe("Connect something new, give a connected one a credential that works again, or change a setting on a connected one.");
+export type CapabilityNeedMode = z.infer<typeof CapabilityNeedModeSchema>;
+
+export const CapabilityNeedSchema = z.object({
+    kind: z.literal("capability"),
+    entry: z.string().min(1).describe("The catalog entry, as the catalog names it."),
+    name: z.string().describe("What the catalog calls it, never the agent's spelling."),
+    mode: CapabilityNeedModeSchema,
+    instance: z.string().optional().describe("The connection a reconnect or a change is about."),
+    target: z.string().optional().describe("The site, host or address the connection is for, when the entry can hold several."),
+    prefill: FieldValuesSchema.optional().describe(
+        "Settings the agent could fill in for a new connection, never a credential: the daemon keeps only the entry's own non-secret fields.",
+    ),
+    changes: FieldValuesSchema.optional().describe("For a change: each setting and the value it would take. Never a credential."),
+    reason: z.string().optional().describe("The daemon's own sentence on why this is the ask, such as the refusal a connected credential keeps getting."),
+    reported: z
+        .boolean()
+        .optional()
+        .describe(
+            "The agent reported the credential refused while the connection still probes as working, so only a person's word that it is fixed meets it: the probe could not see the refusal in the first place.",
+        ),
+});
+export type CapabilityNeed = z.infer<typeof CapabilityNeedSchema>;
+
+// The alphabet a `{{secret:NAME}}` reference resolves; a pasted value is stored under exactly this name.
+export const SECRET_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+
+export const SecretNeedSchema = z.object({
+    kind: z.literal("secret"),
+    name: z.string().regex(SECRET_NAME).describe("The name it is stored under, and what `{{secret:NAME}}` will resolve."),
+    where: z.string().max(200).optional().describe("How it will be used: the header, the command, the site it goes to."),
+    link: z
+        .string()
+        .url()
+        .refine((url) => url.startsWith("https://"), "only an https link")
+        .optional()
+        .describe("Where a person gets one, shown as a link on the card."),
+    hint: z.string().max(120).optional().describe("What a valid one looks like, so a wrong paste is caught by eye."),
+    replace: z.boolean().optional().describe("One is stored under this name and is being refused: the ask is for a new value in its place."),
+});
+export type SecretNeed = z.infer<typeof SecretNeedSchema>;
+
+export const GrantSubjectSchema = z
+    .enum(["capability", "folder", "shelf", "site"])
+    .describe(
+        "A connected capability the persona leaves out, a folder outside the conversation's reach, a whole shelf of tools, or a site in the person's own browser, which only their browser extension can allow.",
+    );
+export type GrantSubject = z.infer<typeof GrantSubjectSchema>;
+
+// A site as a person's browser grants it: the host alone, whatever scheme, path or pattern it was written with
+// ("https://github.com/*" and "github.com" are one site). What a site grant need is keyed and met by.
+export const grantSite = (origin: string): string =>
+    origin
+        .trim()
+        .replace(/^[a-z][a-z0-9+.-]*:\/\//i, "")
+        .replace(/[/?#].*$/, "")
+        .toLowerCase();
+
+export const GRANT_SHELVES = ["files", "shell", "code", "web", "browser", "delegate", "sandbox"] as const;
+export const GrantShelfSchema = z.enum(GRANT_SHELVES);
+export type GrantShelf = z.infer<typeof GrantShelfSchema>;
+
+export const GrantScopeSchema = z
+    .enum(["conversation", "persona"])
+    .describe("How far a yes goes: this conversation only, or the persona itself, for every conversation that wears it.");
+export type GrantScope = z.infer<typeof GrantScopeSchema>;
+
+export const GrantNeedSchema = z.object({
+    kind: z.literal("grant"),
+    subject: GrantSubjectSchema,
+    what: z.string().min(1).describe("The capability's id, the folder, or the shelf."),
+    label: z.string().describe("What it is, in the daemon's words: the account and its kind, the folder, the shelf's name."),
+    persona: z.string().optional().describe("The persona that withholds it, when one does."),
+    scope: GrantScopeSchema.optional().describe("How far the yes went, once there was one."),
+});
+export type GrantNeed = z.infer<typeof GrantNeedSchema>;
+
+export const ReleaseNeedSchema = z.object({
+    kind: z.literal("release"),
+    subject: z.string().min(1).describe("The gated account or connector."),
+    approvers: z.array(z.string()).describe("Who may release it. Anyone else's answer is refused and leaves it waiting."),
+});
+export type ReleaseNeed = z.infer<typeof ReleaseNeedSchema>;
+
+export const EnvironmentNeedSchema = z.object({
+    kind: z.literal("environment"),
+    tool: z.string().min(1).describe("What the steps install, the name the proposal is filed under."),
+    steps: z.string().min(1).describe("The Dockerfile steps proposed for the image's custom section: RUN and ENV lines only."),
+    approvedHash: z.string().optional().describe("The overlay these steps were approved into; met once the running container was built from it."),
+});
+export type EnvironmentNeed = z.infer<typeof EnvironmentNeedSchema>;
+
+export const NeedSubjectSchema = z
+    .discriminatedUnion("kind", [CapabilityNeedSchema, SecretNeedSchema, GrantNeedSchema, ReleaseNeedSchema, EnvironmentNeedSchema])
+    .describe("What exactly is asked for.");
+export type NeedSubject = z.infer<typeof NeedSubjectSchema>;
+
+// How the agent learned the outcome: the call it raised the need with, words into its live turn, a turn of its own, or
+// queued behind what the conversation was doing.
+export const NeedToldSchema = z.enum(["call", "turn", "queued"]);
+export type NeedTold = z.infer<typeof NeedToldSchema>;
+
+export const NeedSchema = z.object({
+    id: z.string().describe("The need's handle, the one `needs cancel` takes."),
+    conversationId: z.string().describe("The conversation that asked, and the one its answer wakes."),
+    subject: NeedSubjectSchema,
+    title: z.string().describe("The one line it leads with, in the daemon's words."),
+    why: z.string().max(280).optional().describe("The agent's case for it, and the only words on a need that are the agent's."),
+    status: NeedStatusSchema,
+    createdAt: z.number().describe("When it was raised, in milliseconds."),
+    updatedAt: z.number().describe("When it last moved, in milliseconds."),
+    answeredBy: z.string().optional().describe("Who answered it, as the sandbox verified them."),
+    outcome: z.string().optional().describe("How it ended, in the daemon's words, once it has."),
+    told: NeedToldSchema.optional().describe("How the agent heard the outcome, once it has."),
+    unattended: z.boolean().optional().describe("Raised by a turn nobody was watching, so the card waited for whoever came next."),
+});
+export type Need = z.infer<typeof NeedSchema>;
+
+// What an agent may send: the kind and what it can know about it. Names, titles and every other field the card shows are
+// the daemon's to fill in, from the catalog, the persona, the gate policy.
+export const NeedAskSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("capability"),
+        entry: z.string().min(1).describe("The catalog entry or a connected instance's id."),
+        target: z.string().max(200).optional().describe("The site, host or address it is for."),
+        set: FieldValuesSchema.optional().describe("Settings to fill in, or to change on a connected one. Credentials are refused."),
+        reconnect: z
+            .boolean()
+            .optional()
+            .describe("It is connected, but its credential is being refused: ask for a new one rather than being told to use it."),
+    }),
+    SecretNeedSchema,
+    z.object({
+        kind: z.literal("grant"),
+        subject: GrantSubjectSchema,
+        what: z.string().min(1).max(400),
+    }),
+    z.object({ kind: z.literal("release"), subject: z.string().min(1) }),
+    z.object({ kind: z.literal("environment"), tool: z.string().min(1).max(64), steps: z.string().min(1).max(20_000) }),
+]);
+export type NeedAsk = z.infer<typeof NeedAskSchema>;
+
+// The longest a raising call holds: under the agent shell's 110-second cutoff, so the answer returns on the call.
+export const NEED_WAIT_MAX_S = 100;
+export const NEED_WAIT_DEFAULT_S = 90;
+
+export const NeedRaiseSchema = z.object({
+    ask: NeedAskSchema,
+    why: z.string().max(280).optional(),
+    wait: z
+        .number()
+        .int()
+        .min(0)
+        .max(NEED_WAIT_MAX_S)
+        .optional()
+        .describe("Seconds to hold the call for an answer. Absent is 90 for a watched turn and 0 for an unattended one."),
+});
+export type NeedRaise = z.infer<typeof NeedRaiseSchema>;
+
+// How a raising call ended. `met`: usable now, exit 0. `open`: asked and still waiting, exit 3; the answer arrives in the
+// conversation by itself. `refused`: nothing was raised or it was declined, exit 1.
+export const NeedRaisedSchema = z.object({
+    state: z.enum(["met", "open", "refused"]),
+    message: z.string().describe("The sentence the CLI prints, written for the agent to act on."),
+    need: NeedSchema.optional(),
+    code: z.string().optional().describe("A refusal's type, for a script to branch on."),
+});
+export type NeedRaised = z.infer<typeof NeedRaisedSchema>;
+
+// A person's answer, by what the card offered. A secret's value travels on its own route (needs.contract.ts), never here.
+export const NeedAnswerSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("decline"), note: z.string().max(500).optional().describe("Why not, passed to the agent.") }),
+    // A connection's yes before its form is saved: moves the need to working, so the board keeps saying so.
+    z.object({ kind: z.literal("accept") }),
+    // A change to a connected capability's settings, applied as the card showed it.
+    z.object({ kind: z.literal("apply") }),
+    z.object({ kind: z.literal("grant"), scope: GrantScopeSchema }),
+    z.object({ kind: z.literal("release") }),
+    z.object({ kind: z.literal("approve") }),
+]);
+export type NeedAnswer = z.infer<typeof NeedAnswerSchema>;
+
+export const NeedIdParamSchema = z.object({ id: z.string().min(1).describe("Which need.") });
+export const NeedAnswerInputSchema = NeedIdParamSchema.extend({ answer: NeedAnswerSchema });
+export const NeedSecretInputSchema = NeedIdParamSchema.extend({
+    value: z.string().min(1).max(64_000).describe("The secret's value. Stored, never echoed, never written into a transcript."),
+});
+export const NeedsQuerySchema = z.object({
+    conversationId: z.string().optional().describe("One conversation's needs. Absent is every conversation's."),
+    open: z.boolean().optional().describe("Only the ones still waiting."),
+});
+export const NeedsListSchema = z.object({ needs: z.array(NeedSchema).describe("Newest first.") });
+
+// What `capabilities list` reads (GET /capabilities/connectable, a raw route): shared by the daemon's handler and the
+// CLI's suite, so the two cannot drift apart again the way a renamed field once left the command printing nothing.
+export const CapabilityConnectableSchema = z.object({
+    entries: z.array(
+        z.object({
+            entry: z.string().describe("The catalog entry's id, what `capabilities request` takes."),
+            name: z.string(),
+            description: z.string(),
+            connected: z.boolean().describe("Whether an instance of it is live, not merely added."),
+        }),
+    ),
+    suggested: z
+        .array(
+            z.object({
+                entry: z.string(),
+                claim: z.string().describe("What the workspace seems to want, in words."),
+                evidence: z.string().describe("What was read to say so, verbatim: a file, a remote."),
+            }),
+        )
+        .default([]),
+});
+export type CapabilityConnectable = z.infer<typeof CapabilityConnectableSchema>;
+
+// One open need as the conversation's card lists it: enough for the board to say what the agent waits on.
+export const AgentNeedSchema = z.object({
+    id: z.string(),
+    kind: NeedKindSchema,
+    title: z.string(),
+    status: NeedStatusSchema,
+});
+export type AgentNeed = z.infer<typeof AgentNeedSchema>;
+
+// What a person allowed one conversation beyond its persona and area, from a grant need's card
+// (personas/conversation-grants.ts). Honoured from that conversation's next turn on, and revocable on the Grants page.
+export const ConversationGrantSchema = z.object({
+    capabilities: z.array(z.string()).default([]).describe("Connected capabilities it may use although its persona leaves them out."),
+    folders: z.array(z.string()).default([]).describe("Workspace folders its file tools may touch beyond its fence."),
+    shelves: z.array(GrantShelfSchema).default([]).describe("Shelves of tools opened for it."),
+    // Answered on an install card's "Allow installs for this conversation", read live by the command gate, so it holds
+    // from the install that asked onward, this turn included, and across restarts.
+    installs: z
+        .boolean()
+        .default(false)
+        .describe("Whether its own dependency installs run without asking, where the owner's setting would otherwise ask first."),
+    updatedAt: z.number().describe("When it last changed, in milliseconds."),
+    by: z.string().optional().describe("Who last allowed something here."),
+});
+export type ConversationGrant = z.infer<typeof ConversationGrantSchema>;
+
+// Every yes still standing, by conversation: what its grants widened past its persona or area, and which gated
+// credentials a named person released to it. Reviewed and taken back from Needs you.
+export const StandingGrantsSchema = z.object({
+    conversations: z.array(
+        z.object({
+            conversationId: z.string(),
+            capabilities: z.array(z.string()).describe("Connected capabilities allowed although its persona leaves them out."),
+            folders: z.array(z.string()).describe("Workspace folders its file tools may touch beyond its fence."),
+            shelves: z.array(GrantShelfSchema).describe("Shelves of tools opened for it."),
+            installs: z.boolean().default(false).describe("Whether its own dependency installs run without asking."),
+            by: z.string().optional().describe("Who last allowed one of those."),
+            updatedAt: z.number().optional().describe("When one of those last changed, in milliseconds."),
+            releases: z
+                .array(z.object({ subject: z.string(), approvedBy: z.string(), at: z.number() }))
+                .describe("Gated credentials released to it, until somebody takes one back."),
+        }),
+    ),
+});
+export type StandingGrants = z.infer<typeof StandingGrantsSchema>;
+
+export const GrantRevokeSchema = z.object({
+    conversationId: z.string(),
+    kind: z
+        .enum(["capability", "folder", "shelf", "release", "install"])
+        .describe("Which kind of yes: a grant past the persona or area, a credential's release, or letting its installs run unasked."),
+    what: z.string().describe("The capability id, folder, shelf or released credential it named; empty for installs."),
+});
+export type GrantRevoke = z.infer<typeof GrantRevokeSchema>;
+
+// The file the needs store keeps: every open need and the recent closed ones, by id.
+export const NeedsFileSchema = z.record(z.string(), NeedSchema);
+export type NeedsFile = z.infer<typeof NeedsFileSchema>;

package/src/schemas/personas.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { type ModelSource, readyChain } from "../models/model-pins.js";
 import { type ModelPin, ModelPinSchema } from "./agent.js";
 import { entryId } from "./internal.js";
-import { SkillDraftSchema, SkillNameSchema, SystemPromptModeSchema } from "./settings.js";
+import { SkillDraftSchema, SkillNameSchema, SYSTEM_PROMPT_MAX, SystemPromptModeSchema } from "./settings.js";
 // A named face the sandbox shows outward: who it speaks as, what it may do, where it works, what it's told, what it
 // runs on. No credential lives on the card; accounts stay private, per-sandbox. Not a security boundary for a watched
 // chat — a real fence only for an unattended turn, whose resolver defaults to nothing.
@@ -176,7 +176,12 @@ export interface TurnBriefingFixture {
 export const TURN_BRIEFING_FIXTURES: readonly TurnBriefingFixture[] = [
     { label: "Where this turn's files live", why: "Without it a runtime that is only cwd'd into its branch writes into the shared checkout." },
     { label: "Who this turn is acting as", why: "The card's own identity, on the runtimes that have nowhere else to put it." },
-    { label: "Standing instructions for this workspace", why: "Your own AGENTS.md rules. Replace them by giving this card its own system prompt." },
+    // Kept under a card's own system prompt too (system-prompt.ts `ownPrompt`): writing a prompt withdraws this product's
+    // guidance, never the owner's own rules.
+    {
+        label: "Standing instructions for this workspace",
+        why: "Your own AGENTS.md rules, sent even when this card has its own system prompt. Change them in AGENTS.md.",
+    },
     {
         label: "Some connected accounts need a person's approval",
         why: "Names who to ask; without it a withheld account reads as simply not connected.",
@@ -307,7 +312,7 @@ export type PersonaKit = z.infer<typeof PersonaKitSchema>;
 export const PersonaPromptSchema = PersonaIdParamSchema.extend({
     prompt: z
         .string()
-        .max(20000)
+        .max(SYSTEM_PROMPT_MAX)
         .describe(
             "What to tell this persona. Sending an empty one removes it entirely rather than storing a blank, so the persona falls back to the sandbox's own instructions.",
         ),

package/src/schemas/providers/provider-oauth.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { AccountStateSchema, AccountUsageSchema } from "./plan-limits.js";
+import { SignInCatcherSchema } from "../loopback-catch.js";
 import { KeyedProviderSchema } from "./provider-subscriptions.js";
 // 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 —
@@ -91,6 +92,12 @@ export const LoginStartSchema = z.object({
             "This attempt's id, for finishing or abandoning it. Not a credential and not redeemable: the proof that completes 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."),
+    catchers: z
+        .array(SignInCatcherSchema)
+        .optional()
+        .describe(
+            "Who is watching for where the browser lands, on the machine it is on: a device or a browser of yours. Listed means the sign-in finishes by itself once the page is approved there; the paste stays open for a browser anywhere else. Empty or absent means nothing is watching.",
+        ),
 });
 export type LoginStart = z.infer<typeof LoginStartSchema>;
 // e.g. Z.ai's international vs. mainland plans.
@@ -111,6 +118,18 @@ export const LoginCompletedSchema = z.object({
         "The account it connected, where the sign-in ends here. Absent means keep watching the account list.",
     ),
 });
+// One attempt's standing, for a card to watch the attempt itself rather than the account list: a list that already
+// held an account says nothing about whether this sign-in, adding another, has landed.
+export const LoginStatusSchema = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("wait") }),
+    z.object({
+        status: z.literal("ok"),
+        account: OauthAccountSchema.optional().describe("The account it connected. Absent where the row lands in the account list a little later."),
+    }),
+    z.object({ status: z.literal("error"), error: z.string().min(1).describe("Why it failed, to show as it is.") }),
+]);
+export type LoginStatus = z.infer<typeof LoginStatusSchema>;
+export const LoginStatusQuerySchema = z.object({ handshake: z.string().min(1).describe("Which attempt.") });
 // 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.") });
 // codex/grok/kimi/gemini via CLIProxyAPI; `flow` is explicit even when a provider's URL already embeds an optional
@@ -124,6 +143,12 @@ export const TranslatorStartSchema = z.object({
         .describe(
             "Which shape this is. A device sign-in finishes by itself and you poll the attempt; a redirect needs the address it landed on handed back. Said outright rather than guessed at from whether a code happens to exist.",
         ),
+    catchers: z
+        .array(SignInCatcherSchema)
+        .optional()
+        .describe(
+            "Who is watching for where the browser lands, on the machine it is on: a device or a browser of yours. Listed means the sign-in finishes by itself once the page is approved there; the paste stays open for a browser anywhere else. Empty or absent means nothing is watching.",
+        ),
 });
 export const TranslatorStatusSchema = z.discriminatedUnion("status", [
     z.object({ status: z.literal("wait") }),
@@ -142,6 +167,13 @@ export const TranslatorCompleteSchema = z.object({
 // 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>;
+// Why a model may run one-shot helper jobs (a commit message, a title) and never an agent turn. Only a positive answer
+// sets it, so a server that says nothing leaves a model usable:
+// no-tool-calls: its server reports a chat template that cannot call tools (llama.cpp's /props `chat_template_caps`),
+//   and llama.cpp drops a turn's tools without a word, so the turn would run and do nothing useful
+// instant-tier: the curated local model sold as too small to drive a turn (LOCAL_MODELS' `instant` rung)
+export const HelperOnlySchema = z.enum(["no-tool-calls", "instant-tier"]);
+export type HelperOnly = z.infer<typeof HelperOnlySchema>;
 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."),
@@ -156,6 +188,9 @@ export const ModelSchema = z.object({
     // 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."),
+    helperOnly: HelperOnlySchema.optional().describe(
+        "Set where this model may write commit messages, titles and other one-shot jobs but never run a chat turn, and why: its server says it cannot call tools, or it is the small local model kept for quick jobs. Absent means nothing has said it cannot.",
+    ),
     // Epoch seconds. A fact about the MODEL, not about any one account: a routed provider balances across credentials,
     // so a model every one of them is benched on is unrunnable however much headroom their rings show. Absent is the
     // ordinary case and means runnable, never "unknown".

package/src/schemas/secrets.ts

@@ -1,5 +1,6 @@
 // secrets: user-supplied env-var secrets the daemon writes to desired-state/.env
 import { z } from "zod";
+import { SECRET_HOST_MAX, SECRET_HOST_PATTERN_RE, SECRET_HOSTS_MAX } from "../policy/secret-hosts.js";
 // 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.
 // An env var name, as a shell exports it. Exported so the browser validates against this rather than restating it:
@@ -19,6 +20,29 @@ export const SecretKeysSchema = z.object({
 export const SecretKeyParamSchema = z.object({ key: secretKey.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 secret nobody has to find or paste: a session key, a webhook signing secret, a database password the task sets up
+// itself. The sandbox makes it and keeps it; the caller gets its reference and length, never the value.
+export const SECRET_FORMATS = ["hex", "base64url", "alnum"] as const;
+export const SecretGenerateSchema = z.object({
+    key: secretKey.describe("The name to store it under: a name nothing here holds yet, since a new value would break whatever uses the old one."),
+    bytes: z
+        .number()
+        .int()
+        .min(16)
+        .max(128)
+        .default(32)
+        .describe("How much randomness, in bytes. 32 unless whatever reads it demands a particular length."),
+    format: z
+        .enum(SECRET_FORMATS)
+        .default("hex")
+        .describe("How it is spelled: `hex` (0-9, a-f), `base64url` (letters, digits, - and _), or `alnum` (letters and digits only, for readers that refuse symbols)."),
+});
+export const SecretGeneratedSchema = z.object({
+    key: z.string().describe("The name it is stored under."),
+    length: z.number().int().describe("How many characters it is, which a reader's validation may care about."),
+    stored: z.enum(["env", "sandbox"]).describe("Where it was kept: desired-state/.env once DevOps is active, the sandbox's own store before that."),
+});
+
 // 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
@@ -81,6 +105,66 @@ export const CredentialGrantSchema = z.object({
     message: z.string().describe("What the grant means in practice, and what to do next."),
 });
 
+// The host guard: the second way a secret can need a person, beside a named approver. On, a use goes unasked only when
+// every host its text names is on the secret's list; one aimed anywhere else, or anywhere its text does not show, waits
+// for a person's click, whatever the safety judge says and whether or not it could be asked. Off, the guard never asks.
+// Keyed like a gate: a secret by its name, a connected capability by its id, covering every field of it.
+export const SecretHostSchema = z
+    .string()
+    .max(SECRET_HOST_MAX)
+    .regex(SECRET_HOST_PATTERN_RE)
+    .describe(
+        "One host, `api.github.com`, or every host under a domain, `*.github.com` (which does not include github.com itself). Lowercase, no scheme or port.",
+    );
+
+export const SecretHostSourceSchema = z
+    .enum(["owner", "connector"])
+    .describe(
+        "Who set it: the owner, or the connector the credential belongs to, whose guard is on with its own service's hosts until the owner changes it.",
+    );
+export type SecretHostSource = z.infer<typeof SecretHostSourceSchema>;
+
+export const SecretHostGuardSchema = z.object({
+    subject: z.string().min(1).describe("Which secret, by the name its reference carries, or which connected capability, by its id."),
+    kind: CredentialGateKindSchema,
+    guard: z.boolean().describe("On: a use off the list, or whose destination cannot be read, asks a person first. Off: it never asks."),
+    hosts: z
+        .array(SecretHostSchema)
+        .max(SECRET_HOSTS_MAX)
+        .describe("Where it goes without asking while the guard is on. Empty with the guard on: every use asks. Kept while it is off, for turning it back on."),
+    source: SecretHostSourceSchema,
+});
+export type SecretHostGuard = z.infer<typeof SecretHostGuardSchema>;
+
+export const SecretHostGuardsSchema = z.object({
+    guards: z
+        .array(SecretHostGuardSchema)
+        .describe("Every secret whose host guard has been set, or that a connector guards by default. One not listed has its guard off. Names and hosts only, never a value."),
+});
+
+export const SecretHostGuardSetSchema = z.object({
+    subject: z.string().min(1).describe("Which secret, by name, or which connected capability, by id."),
+    kind: CredentialGateKindSchema.optional().describe("Whether the subject is a secret or a capability. Worked out from the name when absent."),
+    guard: z.boolean().describe("Whether a use off the list, or whose destination cannot be read, must ask a person first."),
+    hosts: z
+        .array(SecretHostSchema)
+        .max(SECRET_HOSTS_MAX)
+        .describe(
+            "The whole new list. Turning the guard on or taking hosts away is open to anybody who may use secrets; turning it off or adding a host is the owner's to approve.",
+        ),
+    // Filled by the CLI itself, so the model cannot aim the owner's card at somebody else's conversation.
+    conversationId: z
+        .string()
+        .optional()
+        .describe("Which conversation to ask the owner in, when the change needs them. The CLI fills this from the running turn."),
+});
+
+export const SecretHostGuardSetResultSchema = z.object({
+    guard: z.boolean().describe("Whether the guard is on now."),
+    hosts: z.array(z.string()).describe("Where it goes without asking while the guard is on."),
+    approvedBy: z.string().optional().describe("Who approved the change, when it needed the owner's click. Absent when nobody had to."),
+});
+
 // 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({
@@ -128,6 +212,15 @@ export const SecretInventoryEntrySchema = z.object({
         })
         .optional()
         .describe("Who has to release this before the agent can use it, and for how long one release lasts. Absent when it is not gated."),
+    // Joined from the host guards, the owner's and a connector's own, so the row can say where it may go.
+    hosts: z
+        .object({
+            guard: z.boolean().describe("Whether a use off the list, or whose destination cannot be read, asks a person first."),
+            list: z.array(z.string()).describe("The hosts it goes to unasked while the guard is on, each exact or `*.domain`."),
+            source: SecretHostSourceSchema,
+        })
+        .optional()
+        .describe("Its host guard. Absent when none was ever set and no connector sets one: the guard is off."),
 });
 export type SecretInventoryEntry = z.infer<typeof SecretInventoryEntrySchema>;
 export const SecretInventorySchema = z.object({

package/src/schemas/settings-history.ts

@@ -107,4 +107,6 @@ export const SETTINGS_HISTORY = [
     keepWarmObject,
     // Where the check after landing ran (2026-09-27): nothing checks work after it lands any more, CI does.
     at("offload", drop("landCheck")),
+    // The model list for the fix a refused push offered (2026-09-28): a refused push now says why and offers nothing.
+    at("modelRoles", drop("pre-push-fix")),
 ] as const;

package/src/schemas/settings.test.ts

@@ -23,7 +23,7 @@ describe(`which built-in stands at which moment`, () => {
         expect(rule(`agent.landed`, { kind: `command`, command: `pnpm test` }).success).toBe(false);
     });
 
-    test(`there is no push moment: the repository's own pre-push hook gates a push`, () => {
+    test(`there is no push moment: nothing runs on the way to a push, CI checks what was pushed`, () => {
         expect(rule(`push.starting`, { kind: `command`, command: `pnpm test` }).success).toBe(false);
     });
 });
@@ -111,3 +111,21 @@ describe(`the folded keep-warm settings`, () => {
         expect(convertDocument(SETTINGS_HISTORY, `object`, current, true).changes).toEqual([]);
     });
 });
+
+// The pre-push fix's model list went with the fix a refused push used to offer (2026-09-28). A settings file that still
+// names it must read, since an unknown role refuses the whole file, and every other job's list stays as its owner set it.
+describe(`the retired pre-push fix role`, () => {
+    const pin = { provider: `claude`, model: `claude-opus-5-5` };
+
+    test(`is dropped from a stored file, leaving every other job's list, and the file reads`, () => {
+        const stored = { modelRoles: { "pipeline-fix": [pin], "pre-push-fix": [pin] } };
+        expect(SandboxSettingsSchema.safeParse(stored).success).toBe(false);
+        const converted = convertDocument(SETTINGS_HISTORY, `object`, stored, true);
+        expect(converted.value).toEqual({ modelRoles: { "pipeline-fix": [pin] } });
+        expect(SandboxSettingsSchema.parse(converted.value).modelRoles).toEqual({ "pipeline-fix": [pin] });
+    });
+
+    test(`leaves a file without it alone`, () => {
+        expect(convertDocument(SETTINGS_HISTORY, `object`, { modelRoles: { "pipeline-fix": [pin] } }, true).changes).toEqual([]);
+    });
+});