@intentic/sandbox-contract 1.344.0 → 1.346.0

package/src/schemas/privacy-egress.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { type PrivacyShieldPolicy, trustedInConversation } from "./privacy.js";
+
+// THE ONE DECISION about bytes bound for a model provider: pass them as they are, watch them, mask them, or refuse them.
+// Every place they leave by asks it (the gateway, a hooked runtime's channels, a sealed helper prompt, a turn's
+// admission, a runner's placement, a credential that would go around the gateway), and so does the editor before a
+// send, so the warning above the composer is this verdict and never a guess of its own. Before 2026-10-20 the formula
+// was written out at each of those places, and they drifted: helpers refused where turns ran, a child kept here where
+// its parent could go, a strip that warned on opening a composer and stayed silent about a runner.
+
+// How bytes reach the provider. Through a seam the shield reads every byte at: the gateway a runtime is pointed at, the
+// hooks a runtime hands each channel's text to before its model reads it, a sealed prompt (a helper's whole request, in
+// hand before any runtime has it). Or past every seam: a runtime with neither (an ACP agent, Pi), a runner calling its
+// provider from its own machine, a key the provider is called with directly (Codex on the container's OpenAI key), a
+// shared server started before the shield was on.
+export type PrivacySeam = "gateway" | "hooks" | "sealed";
+export const PrivacyBypassSchema = z.enum(["runtime", "runner", "own-key", "shared-server"]);
+export type PrivacyBypass = z.infer<typeof PrivacyBypassSchema>;
+export type PrivacyRoute = PrivacySeam | PrivacyBypass;
+
+const SEAMS: ReadonlySet<PrivacyRoute> = new Set<PrivacySeam>(["gateway", "hooks", "sealed"]);
+const isSeam = (route: PrivacyRoute): route is PrivacySeam => SEAMS.has(route);
+
+// The route of a turn on a runtime, from its `privacy` capability (agent-runtimes.ts), placed on `runner` or here.
+export const turnRoute = (privacy: "gateway" | "hooks" | "none", runner?: string): PrivacyRoute =>
+    runner !== undefined ? "runner" : privacy === "none" ? "runtime" : privacy;
+
+export interface PrivacyEgress {
+    readonly provider: string;
+    // A model this machine serves: nothing it reads leaves.
+    readonly local: boolean;
+    // A conversation's own grant counts there; a request outside any conversation has none.
+    readonly conversationId?: string | undefined;
+    readonly route: PrivacyRoute;
+}
+
+// Why bytes pass as they are: the shield is off, the model is on this machine, the owner trusts the provider everywhere
+// or let it read this conversation, or the shield only watches and cannot see this route at all.
+export type PassReason = "off" | "local" | "trusted" | "granted" | "unwatched";
+
+export type ShieldVerdict =
+    | { readonly kind: "pass"; readonly because: PassReason }
+    | { readonly kind: "watch" }
+    | { readonly kind: "mask" }
+    | { readonly kind: "refuse"; readonly route: PrivacyBypass };
+
+const pass = (because: PassReason): ShieldVerdict => ({ kind: "pass", because });
+
+export const shieldVerdict = (policy: Pick<PrivacyShieldPolicy, "mode" | "trusted" | "conversations">, egress: PrivacyEgress): ShieldVerdict => {
+    if (policy.mode === "off") {
+        return pass("off");
+    }
+    if (egress.local) {
+        return pass("local");
+    }
+    if (policy.trusted.includes(egress.provider)) {
+        return pass("trusted");
+    }
+    if (trustedInConversation(policy, egress.provider, egress.conversationId)) {
+        return pass("granted");
+    }
+    if (!isSeam(egress.route)) {
+        return policy.mode === "on" ? { kind: "refuse", route: egress.route } : pass("unwatched");
+    }
+    return policy.mode === "on" ? { kind: "mask" } : { kind: "watch" };
+};
+
+// Whether the owner let the provider read what it is sent as it is (here, everywhere, or in this conversation): what
+// the log calls trusted.
+export const ownerTrusted = (verdict: ShieldVerdict): boolean =>
+    verdict.kind === "pass" && (verdict.because === "local" || verdict.because === "trusted" || verdict.because === "granted");
+
+// The failure codes a turn the shield turned away ends with: refused by its verdict (`privacy-unshielded`), or for what
+// it found where it could not mask (`privacy-instructions`). The way through both is the same grant.
+const REFUSAL_CODES = ["privacy-unshielded", "privacy-instructions"] as const;
+export type PrivacyRefusalCode = (typeof REFUSAL_CODES)[number];
+const REFUSAL_CODE_SET: ReadonlySet<string> = new Set(REFUSAL_CODES);
+export const isPrivacyRefusal = (code: string | undefined): code is PrivacyRefusalCode => code !== undefined && REFUSAL_CODE_SET.has(code);
+
+// A refusal as the shield both words and types it: the sentence a turn ends with, and the route its verdict refused,
+// which rides the turn's error frame (`privacyRoute`) so a reader acts on the route rather than on the sentence. Absent
+// for a policy that could not be read, which refuses whatever the route.
+export interface PrivacyRefusal {
+    readonly sentence: string;
+    readonly route?: PrivacyBypass;
+}

package/src/schemas/privacy.ts

@@ -42,6 +42,10 @@ export type PrivacyNames = z.infer<typeof PrivacyNamesSchema>;
 
 export const PRIVACY_TRUSTED_MAX = 200;
 export const PRIVACY_ALLOW_MAX = 1000;
+
+// How a never-masked value (policy `allow`) is compared with what the shield finds, by the detectors and by the editor
+// that keeps the list: case, Unicode composition and runs of whitespace do not tell two values apart.
+export const allowKey = (value: string): string => value.normalize("NFC").toLowerCase().replace(/\s+/g, " ").trim();
 export const PRIVACY_CONVERSATIONS_MAX = 200;
 
 // The owner's own additions to what the shield finds. The policy travels whole on every write, so each is kept to what a

package/src/schemas/project-delivery.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 
-// LANDED WORK DELIVERED TO THE OWNER'S FOLDER. A folder attached to this computer's own sandbox is copied one way into
+// LANDED WORK DELIVERED TO THE OWNER'S FOLDER. A folder with a sandbox made for it is copied one way into
 // `/work/<name>`; when a conversation's work lands there, the daemon hands the same change to the machine agent that
 // holds the folder, which applies it file by file under a restore point and never over an edit of the owner's own.
 // The daemon asks (`deliverProject` on the device contract), the machine decides and writes; nothing an agent runs can

package/src/schemas/providers/plan-limits.test.ts

@@ -0,0 +1,16 @@
+import { sandboxAnswerSchema } from "../../index.js";
+import { ProviderRefusalsSchema } from "./plan-limits.js";
+
+// 2026-10-21: /agent/refusals went from one refusal per provider to a list per provider, and the editor parses every
+// answer with its own build's schema. Against a released daemon (1.249.0 to 1.345.0) the parse failed, the read was kept
+// as nothing, and every spent account and model read as ready.
+test("reads a released daemon's one refusal per provider as a list of one, and today's lists as they are", () => {
+    const spent = { at: 1_760_000_000_000, kind: "limit", message: "Claude AI usage limit reached", account: "acct-1", resetsAt: 1_760_010_000 };
+    const schema = sandboxAnswerSchema(["agent", "refusals"]);
+    const older = schema?.safeParse({ refusals: { claude: spent } });
+    expect(older?.success).toBe(true);
+    expect(older?.data).toEqual({ refusals: { claude: [spent] } });
+    const today = { refusals: { claude: [spent, { at: 1_760_000_000_001, kind: "auth", message: "OAuth token revoked", account: "acct-2" }], codex: [] } };
+    expect(schema?.safeParse(today).data).toEqual(today);
+    expect(ProviderRefusalsSchema.safeParse({ refusals: { claude: "spent" } }).success).toBe(false);
+});

package/src/schemas/providers/plan-limits.ts

@@ -36,6 +36,12 @@ export const UsageWindowSchema = z.object({
         .describe(
             "When the window this pool was last read in closed, in epoch seconds, while nothing has read the pool since. Its `utilization` is then 0, the floor every new window starts from, not a measurement, and `resetsAt` is absent because the next reset is unknown.",
         ),
+    missingSince: z
+        .number()
+        .optional()
+        .describe(
+            "When the provider stopped reporting this pool, in epoch seconds: a later reading of the account named every other pool but not this one. Its figure is the last one read, still a valid floor until its window closes, and the pool is dropped once it has.",
+        ),
 });
 export type UsageWindow = z.infer<typeof UsageWindowSchema>;
 // A failed re-read, whatever the cause: a 429 park, a 403 asking for verification, a 5xx, a timeout. Recorded as the fact
@@ -50,6 +56,12 @@ export const UsageUnreadSchema = z.object({
         ),
 });
 export type UsageUnread = z.infer<typeof UsageUnreadSchema>;
+// A turn answered against a reading that said its model could not run: the provider's own word that the reading is wrong.
+export const UsageContradictionSchema = z.object({
+    at: z.number().describe("When the turn was answered, in milliseconds."),
+    model: z.string().describe("The model the answered turn ran on."),
+});
+export type UsageContradiction = z.infer<typeof UsageContradictionSchema>;
 // Every window kept, not just the binding one, since which pool binds changes between turns. Utilization only climbs
 // within a window, so a stale reading is still a valid floor. `measuredAt` is epoch ms — windows are seconds.
 export const AccountUsageSchema = z.object({
@@ -58,15 +70,25 @@ export const AccountUsageSchema = z.object({
     unread: UsageUnreadSchema.optional().describe(
         "Present while re-reading this account keeps failing: these windows are the last reading that succeeded, and `measuredAt` will not move until a read succeeds again.",
     ),
+    uncovered: z
+        .array(z.string())
+        .optional()
+        .describe(
+            "Models this account serves that no pool in this reading gates, by id: the provider published no allowance for them, so their room is unknown, never assumed spent. Absent when every model is covered or the account's models are not known.",
+        ),
+    contradicted: UsageContradictionSchema.optional()
+        .describe(
+            "A turn on `model` was answered after this reading said every pool it spends was empty, so the reading is wrong about that model: those pools read as at the line, not spent, until a new reading replaces this one.",
+        ),
 });
 export type AccountUsage = z.infer<typeof AccountUsageSchema>;
 // Who has to act for a blocked account, which is the only thing a surface chooses its instruction by: the reason is the
 // words for a person, never a key.
 export const AccountFixSchema = z.enum(["reconnect", "admin", "verify", "wait"]);
 export type AccountFix = z.infer<typeof AccountFixSchema>;
-// Whether an account can serve a turn, decided once by the daemon (models/plan-pools.ts `serviceState`) from every fact
-// it holds about it: a revoked sign-in, a lost seat, a translator bench, a refusal still standing, and its plan limits.
-// Every picker (an unnamed turn, a limit move, a keep-warm refresh) and every surface reads this one verdict.
+// Whether an account can serve a turn, judged by one rule (models/plan-pools.ts `serviceStates`) from every fact on file
+// about it: a revoked sign-in, a lost seat, a translator bench, every refusal still standing, and its plan limits. The
+// daemon and the editor run that rule on the same facts; nothing publishes or keeps a judged copy.
 export const AccountStateSchema = z.discriminatedUnion("kind", [
     z.object({
         kind: z.literal("ready"),
@@ -82,6 +104,10 @@ export const AccountStateSchema = z.discriminatedUnion("kind", [
             .number()
             .optional()
             .describe("When every full pool has reopened, in epoch seconds, where the plan publishes it. Absent means unknown, never now."),
+        pool: z
+            .string()
+            .optional()
+            .describe("The pool holding it shut, by the plan's own name for it, where the plan meters it apart from other models. Absent for an undivided allowance."),
     }),
     z.object({
         kind: z.literal("blocked"),
@@ -123,49 +149,7 @@ export const LimitResetClaimSchema = z.object({
     detail: z.string().optional().describe("What went wrong, in words, for the two outcomes that are this sandbox's fault rather than the plan's."),
 });
 export type LimitResetClaim = z.infer<typeof LimitResetClaimSchema>;
-// Observed and exact, unlike a polled usage snapshot that can be stale; keyed by provider, not account, since a routed
-// turn doesn't know which served it. `kind` is read off what the provider said, not the frame code.
-export const ProviderRefusalSchema = z.object({
-    // Read side by side with `AccountUsage.measuredAt` (also ms).
-    at: z.number().describe("When it refused, in milliseconds."),
-    // Only a turn that actually runs settles an entitlement refusal — nothing else can.
-    kind: z
-        .enum(["limit", "auth", "entitlement"])
-        .describe(
-            "Three different noes, kept apart because what fixes each is different. A spent allowance is answered by waiting; a refused credential by signing in again; and an entitlement refusal, where somebody has switched this off for your seat, by neither of those. That last one authenticates fine and reports healthy limits the whole time it refuses everything.",
-        ),
-    message: z.string().describe("The provider's own words, verbatim. The only part that says which limit or which credential."),
-    // Known for native turns only; a routed turn doesn't say which account served it.
-    account: z.string().optional().describe("Which account was serving, where that is known."),
-    // Lets a `limit` refusal be read against the pool that model spends (`UsageWindow.gates`), not the account's
-    // fullest pool.
-    model: z.string().optional().describe("Which model the refused turn was on, where that is known."),
-    // The provider's own "try again at …", which a polled reading cannot contradict: a usage endpoint can keep showing
-    // room while the plan refuses every turn.
-    resetsAt: z
-        .number()
-        .optional()
-        .describe(
-            "When the provider said to try again, in epoch seconds, for a spent allowance where it named one. Until then the refusal stands whatever a reading says; after it, it is over.",
-        ),
-    // Codex's "To get more access now, send a request to your admin": a team's credit, which no usage endpoint reads,
-    // so a weekly pool at 57% says nothing about it (2026-10-17).
-    unmetered: z
-        .literal(true)
-        .optional()
-        .describe(
-            "Set on a spent allowance no usage reading measures, such as a credit an organisation's admin grants. No reading answers it: it stands until the provider's own reset, or until a turn is answered.",
-        ),
-});
-export type ProviderRefusal = z.infer<typeof ProviderRefusalSchema>;
-export const ProviderRefusalsSchema = z.object({
-    refusals: z
-        .record(z.string(), ProviderRefusalSchema)
-        .describe(
-            "The most recent refusal per provider. Read alongside an account's usage: that says how full it was when last checked, this says whether it has since started saying no.",
-        ),
-});
-export type ProviderRefusals = z.infer<typeof ProviderRefusalsSchema>;
+export { type ProviderRefusal, ProviderRefusalSchema, type ProviderRefusals, ProviderRefusalsSchema } from "./refusals.js";
 // `name` is CLIProxyAPI's auth-file name, the stable key a disconnect addresses; `label` is the reported sign-in
 // identity (email, else the file name).
 export const TranslatorAccountSchema = z.object({
@@ -190,9 +174,6 @@ export const TranslatorAccountSchema = z.object({
             verify: z.string().optional(),
         })
         .optional(),
-    state: AccountStateSchema.optional().describe(
-        "Whether it can serve a turn now, judged from everything above plus the provider's last refusal. Absent from a daemon older than this field.",
-    ),
 });
 export type TranslatorAccount = z.infer<typeof TranslatorAccountSchema>;
 // A list per provider, not a flag: CLIProxyAPI holds several auth files per provider and balances across them. Built
@@ -408,6 +389,8 @@ export const ResumeRoutingSchema = z.object({
         ),
     // A client whose catalog hasn't loaded has nothing to send; the turn's own model is the better fallback.
     model: z.string().optional().describe("Which model. Leave it out to keep the one the refused turn named."),
+    // A tier named for one model may mean nothing on another, so a move onto a ladder rung carries that rung's own.
+    effort: z.string().optional().describe("How hard the model should think on the re-run. Leave it out to keep the refused turn's."),
     // A session is a file the daemon keeps; a credential is an env var. That's what lets a same-provider account switch
     // resume the existing session instead of opening a fresh one.
     carry: z
@@ -458,6 +441,19 @@ export const QueueResumeSchema = z.object({
         ),
 });
 export type QueueResume = z.infer<typeof QueueResumeSchema>;
+// Points a person's waiting messages at another provider, model or account without letting them go: what a pick in the
+// model picker does to the words already waiting, which would otherwise go by themselves on the pick they were sent under.
+export const QueueRerouteSchema = z.object({
+    conversationId: z.string().min(1).describe("Whose queue."),
+    routing: ResumeRoutingSchema.describe(
+        "Who serves the turn each message starts from now on. A model or effort left out keeps each message's own; an account left out goes on the conversation's own when it goes.",
+    ),
+    ids: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Which waiting messages to move. Leave it out to move every person's waiting message, held or booked; each keeps its own booking."),
+});
+export type QueueReroute = z.infer<typeof QueueRerouteSchema>;
 // Re-times what a conversation's queue holds: the same messages (or only those `ids` names), booked for another instant
 // or for after another conversation's work lands. One of the two, never both, since a booking waits on exactly one thing.
 export const QueueScheduleSchema = z
@@ -472,6 +468,12 @@ export const QueueScheduleSchema = z
         sendAfter: ConversationIdSchema.optional().describe(
             "Send what waits once that conversation has finished and all of its work has landed in the workspace, instead. Sent now when it has nothing running and nothing left to land.",
         ),
+        sendAtReopen: z
+            .literal(true)
+            .optional()
+            .describe(
+                "Says `sendAt` is the reopen of the allowance what waits would be refused by, not a time you chose; the queue records it as `reopenOf`. Only with `sendAt`.",
+            ),
         ids: z
             .array(z.string().min(1))
             .optional()
@@ -497,6 +499,10 @@ export const QueueContinueSchema = z
             .optional()
             .describe("Carry on at this instant (epoch milliseconds). At most a month ahead; an instant already past carries on now."),
         sendAfter: ConversationIdSchema.optional().describe("Carry on once that conversation has finished and all of its work has landed, instead."),
+        sendAtReopen: z
+            .literal(true)
+            .optional()
+            .describe("Says `sendAt` is the reopen of a spent allowance, not a time you chose; the queue records it as `reopenOf`. Only with `sendAt`."),
         routing: ResumeRoutingSchema.optional().describe(
             "Who serves the turn it starts. Leave it out to carry on where the conversation runs when it goes.",
         ),

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { AccountStateSchema, AccountUsageSchema } from "./plan-limits.js";
+import { 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
@@ -38,9 +38,6 @@ export const OauthAccountSchema = z.object({
     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.",
     ),
-    state: AccountStateSchema.optional().describe(
-        "Whether it can serve a turn now, judged once from the sign-in, the seat, the provider's last refusal and the plan limits: the verdict every picker in the sandbox uses. Read this rather than the fields it was judged from. Absent from a daemon older than this field.",
-    ),
 });
 export type OauthAccount = z.infer<typeof OauthAccountSchema>;
 export const OauthAccountListSchema = z.object({
@@ -191,15 +188,6 @@ export const ModelSchema = z.object({
     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".
-    availableAt: z
-        .number()
-        .optional()
-        .describe(
-            "When this model can be asked again, where every credential that serves it is currently refused. Absent means it can be asked now. A model here is still worth showing, unlike one the plan does not cover at all: the wait is the whole answer.",
-        ),
 });
 export type Model = z.infer<typeof ModelSchema>;
 export const ModelsSchema = z.object({

package/src/schemas/providers/refusals.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+
+// WHAT A PROVIDER SAID WHEN IT REFUSED A TURN, and the ledger of them the sandbox answers with. Kept out of plan-limits.ts,
+// which re-exports both, so the plan and turn schemas there stay within one file's reach.
+
+// Observed and exact, unlike a polled usage snapshot that can be stale; keyed by provider, not account, since a routed
+// turn doesn't know which served it. `kind` is read off what the provider said, not the frame code.
+export const ProviderRefusalSchema = z.object({
+    // Read side by side with `AccountUsage.measuredAt` (also ms).
+    at: z.number().describe("When it refused, in milliseconds."),
+    // Only a turn that actually runs settles an entitlement refusal — nothing else can.
+    kind: z
+        .enum(["limit", "auth", "entitlement"])
+        .describe(
+            "Three different noes, kept apart because what fixes each is different. A spent allowance is answered by waiting; a refused credential by signing in again; and an entitlement refusal, where somebody has switched this off for your seat, by neither of those. That last one authenticates fine and reports healthy limits the whole time it refuses everything.",
+        ),
+    message: z.string().describe("The provider's own words, verbatim. The only part that says which limit or which credential."),
+    // Known for native turns only; a routed turn doesn't say which account served it.
+    account: z.string().optional().describe("Which account was serving, where that is known."),
+    // Lets a `limit` refusal be read against the pool that model spends (`UsageWindow.gates`), not the account's
+    // fullest pool.
+    model: z.string().optional().describe("Which model the refused turn was on, where that is known."),
+    // The provider's own "try again at …", which a polled reading cannot contradict: a usage endpoint can keep showing
+    // room while the plan refuses every turn.
+    resetsAt: z
+        .number()
+        .optional()
+        .describe(
+            "When the provider said to try again, in epoch seconds, for a spent allowance where it named one. Until then the refusal stands whatever a reading says; after it, it is over.",
+        ),
+    // Stamped by the daemon's ledger as it files a spent allowance naming no instant (plan-pools.ts refusedPoolReset).
+    poolResetsAt: z.number().optional().describe("Epoch seconds the refused pool reopens, for a spent allowance naming no time: it ends then."),
+    // Cursor's "ask your admin to increase your limit": a team's spend limit, which no usage endpoint reads. Not Codex's
+    // "send a request to your admin", which names a window its reading measures (failure-sentences.ts ADMIN_GRANTED).
+    unmetered: z
+        .literal(true)
+        .optional()
+        .describe(
+            "Set on a spent allowance no usage reading measures, such as a credit an organisation's admin grants. No reading answers it: it stands until the provider's own reset, or until a turn is answered.",
+        ),
+    byHand: z
+        .literal(true)
+        .optional()
+        .describe(
+            "Set by a person rather than by a refused turn, for a plan nothing can read: believed for a day, or until unmarked or a turn on it is answered.",
+        ),
+});
+export type ProviderRefusal = z.infer<typeof ProviderRefusalSchema>;
+// A released daemon (1.345.0 and earlier) answers one refusal per provider, its last: read as a list of one, as the
+// /events frame's `refusal` is (refusalsOf). What this build sends, and its output shape, is still the list.
+const RefusalsOnFileSchema = z.codec(z.union([z.array(ProviderRefusalSchema), ProviderRefusalSchema]), z.array(ProviderRefusalSchema), {
+    decode: (filed) => (Array.isArray(filed) ? filed : [filed]),
+    encode: (list) => list,
+});
+export const ProviderRefusalsSchema = z.object({
+    refusals: z
+        .record(z.string(), RefusalsOnFileSchema)
+        .describe(
+            "Every refusal on file per provider, each the latest of its kind for the account and model it names: what every verdict on that provider's accounts is judged against. Read alongside an account's usage: that says how full it was when last checked, these say whether it has since started saying no.",
+        ),
+});
+export type ProviderRefusals = z.infer<typeof ProviderRefusalsSchema>;

package/src/schemas/providers/usage.ts

@@ -74,6 +74,8 @@ export const UsageTurnSchema = z.object({
     iqSearchCohort: z.string().optional(),
     // Every tool call that searched, including CLI searches like `iq q`; absent means unmeasured, not zero.
     searchCalls: z.number().optional(),
+    // Of searchCalls, the ones that ran iq: the search teaching's uptake. Absent on rows written before 2026-10-19.
+    iqSearches: z.number().optional(),
     // Search calls before the first file touch; absent as searchCalls; a turn touching nothing counts them all.
     openingSearches: z.number().optional(),
     // Directory listings (ls, tree, LS tool) before the turn's first file touch, same window as openingSearches.

package/src/schemas/push.ts

@@ -3,8 +3,9 @@ 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, 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.
+// relay: a native app (the iPhone app, the Android editor app, the Intentic Device app); its OS push service only accepts
+// sends from the vendor, so the daemon posts through a relay, which can read the payload. Only Apple is handed the words:
+// an Android app gets a data-only message and fetches them from the daemon itself.
 
 // Exact shape `web-push` consumes, from `PushManager.subscribe()`; posted back verbatim.
 export const WebPushChannelSchema = z.object({
@@ -26,7 +27,12 @@ export const RelayChannelSchema = z.object({
         ),
     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."),
+    secret: z
+        .string()
+        .min(1)
+        .describe(
+            "Proof that this sandbox may notify this device. A send names no sandbox; the relay knows which sandbox a device belongs to only when the editor app registered it for that one sandbox, so the app can be told which sandbox to ask.",
+        ),
 });
 export type RelayChannel = z.infer<typeof RelayChannelSchema>;
 export const PushChannelSchema = z.discriminatedUnion("kind", [WebPushChannelSchema, RelayChannelSchema]);
@@ -61,6 +67,16 @@ export const PushNotificationSchema = z.object({
         ),
 });
 export type PushNotification = z.infer<typeof PushNotificationSchema>;
+export const PushSentQuerySchema = z.object({
+    tag: z.string().min(1).describe("The tag the push carried, which is all a native app's push says about what it was."),
+});
+// What a native app's data-only push leaves out, read back over the app's own session so the words never pass through
+// the push service or the relay.
+export const PushSentNotificationSchema = PushNotificationSchema.extend({
+    tag: z.string().min(1).describe("The tag it was sent under, the one asked for."),
+    sentAt: z.string().describe("When the sandbox sent it (ISO)."),
+});
+export type PushSentNotification = z.infer<typeof PushSentNotificationSchema>;
 export const PushConfigSchema = z.object({
     publicKey: z.string().describe("The key a browser needs in order to subscribe. Native apps ignore it."),
     subscribed: z

package/src/schemas/sandbox-passwords.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { KeyringOriginSchema, KeyringRememberSchema, KeyringShareModeSchema } from "./keyring.js";
+
+// THE SANDBOX'S SIDE OF PASSWORDS (2026-10-19): an agent asking for a credential by where it is to be used (`secrets
+// want`, `type_secret` aimed at a page or a window), and the hosted Passwords view's three reads. The vault and its
+// management stay on the owner's computers; what a sandbox learns of an entry is the pointer its keyring shared here.
+
+/** `secrets want`: a credential by the place it is for, asked of the owner's keyrings. */
+export const SecretWantSchema = z
+    .object({
+        origin: KeyringOriginSchema.describe("Where it is to be used: a site, a program on the owner's computer, an ssh target, a git host."),
+        username: z.string().max(256).optional().describe("The account wanted, when the agent knows it."),
+        why: z.string().min(1).max(300).describe("What it is for, in words for the person's prompt."),
+        // Filled by the CLI itself, from the running turn, so the prompt names the conversation that asked.
+        conversationId: z.string().max(200).optional(),
+    })
+    .strict();
+export type SecretWant = z.infer<typeof SecretWantSchema>;
+
+export const SecretWantResultSchema = z.discriminatedUnion("state", [
+    z.object({
+        state: z.literal("allowed"),
+        name: z.string().describe("The name a secret reference uses from now on."),
+        machine: z.string().describe("The computer whose keyring shares it."),
+        message: z.string(),
+    }),
+    z.object({ state: z.literal("pending"), id: z.string(), machine: z.string(), message: z.string().describe("Where the owner's answer is awaited.") }),
+    z.object({ state: z.literal("denied"), message: z.string() }),
+    z.object({ state: z.literal("unknown"), message: z.string().describe("No keyring had it and nobody typed it once, or none could be asked.") }),
+]);
+export type SecretWantResult = z.infer<typeof SecretWantResultSchema>;
+
+/** One need this sandbox raised, as its record and the hosted view's Requests keep it. */
+export const SandboxNeedSchema = z.object({
+    id: z.string(),
+    origin: KeyringOriginSchema,
+    username: z.string().optional(),
+    detail: z.string(),
+    conversation: z.string().optional(),
+    machine: z.string().optional().describe("The computer it was answered on, or waits on."),
+    state: z.enum(["pending", "allowed", "denied", "unknown"]),
+    name: z.string().optional().describe("The entry it was answered with, once allowed."),
+    at: z.number().int(),
+});
+export type SandboxNeed = z.infer<typeof SandboxNeedSchema>;
+export const SandboxNeedsSchema = z.object({ needs: z.array(SandboxNeedSchema) });
+
+/** One of the owner's computers as the hosted Passwords view shows its keyring. */
+export const SandboxPasswordsKeyringSchema = z.object({
+    machine: z.string(),
+    online: z.boolean(),
+    setUp: z.boolean().describe("Answering, set up, and trusted by this sandbox: it can be asked."),
+    locked: z.boolean().optional(),
+    remember: KeyringRememberSchema.optional(),
+});
+export type SandboxPasswordsKeyring = z.infer<typeof SandboxPasswordsKeyringSchema>;
+
+/** One password this sandbox may use: a pointer one of the owner's keyrings shares here. Never a value. */
+export const SandboxPasswordSchema = z.object({
+    name: z.string(),
+    title: z.string(),
+    kind: z.enum(["password", "text"]),
+    origins: z.array(KeyringOriginSchema).describe("Where it works, from the entry's rules."),
+    anyField: z.boolean(),
+    machine: z.string().describe("The computer whose keyring keeps it."),
+    mode: KeyringShareModeSchema.describe("How this sandbox may use it."),
+    online: z.boolean(),
+    updatedAt: z.number(),
+    lastUsedAt: z.number().optional().describe("This sandbox's last use of it, from its own use ledger."),
+});
+export type SandboxPassword = z.infer<typeof SandboxPasswordSchema>;
+
+export const SandboxPasswordsSchema = z.object({
+    sandbox: z.string().describe("This sandbox's own address, as the keyrings name it."),
+    items: z.array(SandboxPasswordSchema),
+    keyrings: z.array(SandboxPasswordsKeyringSchema),
+});
+export type SandboxPasswords = z.infer<typeof SandboxPasswordsSchema>;
+
+/** One use of a keyring-held password by this sandbox, from its use ledger. */
+export const SandboxPasswordUseSchema = z.object({
+    at: z.number(),
+    name: z.string(),
+    lane: z.string(),
+    detail: z.string().optional(),
+    approvedBy: z.string().optional(),
+});
+export const SandboxPasswordsActivitySchema = z.object({ lines: z.array(SandboxPasswordUseSchema) });

package/src/schemas/secrets.ts

@@ -257,6 +257,10 @@ export const SandboxKeyringSchema = z.object({
     machine: z.string().describe("The computer, by its device card."),
     online: z.boolean().describe("Whether it answers now."),
     locked: z.boolean().optional().describe("Whether its keyring is locked, as last heard. Absent while offline."),
+    setUp: z
+        .boolean()
+        .optional()
+        .describe("Whether its keyring answers with a vault this sandbox trusts, so a value can be kept there. Absent while offline, and from a daemon older than 2026-10-19."),
     version: z.string().optional().describe("The keyring's release, as last heard."),
     pendingInbox: z.number().int().nonnegative().optional().describe("Values sent to be kept there that wait for its next unlock."),
     shared: z.number().int().nonnegative().describe("How many of its entries are shared with this sandbox."),

package/src/schemas/sessions.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { MatchSnippetSchema } from "./agents.js";
+import { MatchSnippetSchema } from "./agent-search.js";
 export const SessionIdParamSchema = z.object({ id: z.string().describe("Which past conversation.") });
 export const SessionSummarySchema = z.object({
     id: z.string().describe("Its id."),