@intentic/sandbox-contract 1.340.0 → 1.342.0

package/src/schemas/git/index-run.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { CommandRunSchema } from "../ci.js";
+import { RepoParamSchema } from "../shared.js";
+import { CommitResultSchema, GitTargetSchema } from "./git.js";
+
+// Stage-all and commit-all as runs the daemon keeps, not requests held open: over a tree of tens of thousands of
+// untracked files `git add -A` alone outlives the browser's header deadline (seconds), and a request that dies there
+// leaves git running with nobody told how it ended. Modelled on the push run (PushRunSchema): started and answered at
+// once, polled for progress and verdict, one per repository, a second start of the same thing joining the first.
+
+// The guardrail's line, past which a run stops before staging and asks: a stage that size is almost always a dependency
+// or build tree nobody meant to commit. Either one trips it.
+export const INDEX_RUN_FILE_LIMIT = 2_000;
+export const INDEX_RUN_BYTE_LIMIT = 100 * 1024 * 1024;
+
+export const IndexRunOpSchema = z.enum(["stage", "commit"]);
+export type IndexRunOp = z.infer<typeof IndexRunOpSchema>;
+
+// Where a running run is, in the order it passes them; a plain commit skips counting and staging.
+// waiting: queued behind another write on the same repository (an agent's land, another commit).
+// counting: reading what the stage would take, for the guardrail.
+// staging / committing: git is running.
+// reading: re-reading the repository the commit just wrote, for the answer.
+export const IndexRunPhaseSchema = z.enum(["waiting", "counting", "staging", "committing", "reading"]);
+
+export const IndexRunDirSchema = z.object({
+    dir: z.string().describe("A top-level directory of the repository, or an empty string for the files directly at its root."),
+    files: z.number().describe("How many of the files the stage would take sit under it."),
+    bytes: z.number().optional().describe("Their combined size on disk. Absent when the run did not measure sizes, which it skips once the file count alone is over the line."),
+});
+export type IndexRunDir = z.infer<typeof IndexRunDirSchema>;
+
+// What a held run found, so the question names the directories rather than only a number.
+export const IndexRunHoldSchema = z.object({
+    files: z.number().describe("How many files the stage would take."),
+    bytes: z.number().optional().describe("Their combined size on disk, when measured."),
+    dirs: z.array(IndexRunDirSchema).describe("The largest top-level directories among them, biggest first, at most a handful."),
+});
+export type IndexRunHold = z.infer<typeof IndexRunHoldSchema>;
+
+// Flat rather than a union on `op`: the route's path parameter merges into the input, which a discriminated union cannot
+// take, and the one cross-field rule (a commit needs a message) is a refine.
+export const IndexRunStartSchema = RepoParamSchema.extend({
+    op: IndexRunOpSchema.describe("Stage, or commit (staging `target` first when given)."),
+    target: GitTargetSchema.optional().describe(
+        "What to stage. For a stage, leave it out for the whole repository. For a commit, leave it out to record the index exactly as it stands, or give an empty object to stage everything first.",
+    ),
+    message: z.string().min(1).optional().describe("The commit message. Required for a commit, refused for a stage."),
+    confirmed: z
+        .boolean()
+        .optional()
+        .describe(
+            `Go ahead past the guardrail. Without it, a stage that would take more than ${String(INDEX_RUN_FILE_LIMIT)} files or ${String(INDEX_RUN_BYTE_LIMIT / 1024 / 1024)} MB stops before touching the index and settles holding what it found, for a person to confirm.`,
+        ),
+})
+    .refine((start) => start.target === undefined || start.target.paths === undefined || start.target.scope === undefined, {
+        message: "name paths or a scope, not both",
+    })
+    .refine((start) => (start.op === "commit") === (start.message !== undefined), { message: "a commit takes a message and a stage does not" });
+export type IndexRunStart = z.infer<typeof IndexRunStartSchema>;
+
+export const IndexRunSchema = CommandRunSchema.extend({
+    id: z.string().describe("This run's own id, new on every start that did not join one already going. Empty when idle."),
+    repo: z.string().describe("The repository this run is about, the same id the routes take."),
+    op: IndexRunOpSchema.optional().describe("What was started. Absent when idle."),
+    phase: IndexRunPhaseSchema.optional().describe("Where a running run is. Absent once it settles."),
+    files: z
+        .object({
+            total: z.number().optional().describe("How many files the stage takes, once counted."),
+            done: z.number().optional().describe("How many of them are staged so far. git stages a whole repository in one go, so this jumps from 0 to the total."),
+        })
+        .optional()
+        .describe("Progress in files, where known."),
+    reason: z.string().optional().describe("Why it did not go, in git's own words where git said something."),
+    held: IndexRunHoldSchema.optional().describe(
+        "Present when the run stopped at the guardrail before touching anything (status `error`): what it would have staged. Start again with `confirmed` to go ahead.",
+    ),
+    result: CommitResultSchema.optional().describe("A commit's answer, the same one the commit call gives, once it passes."),
+});
+export type IndexRun = z.infer<typeof IndexRunSchema>;

package/src/schemas/keep-warm.ts

@@ -131,3 +131,37 @@ export type PromptFingerprint = z.infer<typeof PromptFingerprintSchema>;
 /** Which parts differ between two fingerprints, by name; empty when they match. */
 export const changedParts = (before: PromptFingerprint, after: PromptFingerprint): string[] =>
     [...new Set([...Object.keys(before.parts), ...Object.keys(after.parts)])].filter((name) => before.parts[name] !== after.parts[name]).toSorted();
+
+// keep-warm's knobs, one object since each only means anything beside the others (cache-keepwarm.ts).
+export const KeepWarmSettingsSchema = z.object({
+    auto: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Keep a Claude conversation's prompt cache warm after each turn a person asked for. Each refresh re-reads the cached context at the cache price and adds nothing to the conversation.",
+        ),
+    hours: z
+        .number()
+        .min(1)
+        .max(8)
+        .default(4)
+        .describe(
+            "How long an idle conversation is kept warm after its last turn, in hours, and what a press on one offers first. Shortened where refreshing would cost more than the cold resume it saves, and at midnight where the agent runs, when the date in its prompt changes.",
+        ),
+    minTokens: z
+        .number()
+        .int()
+        .min(0)
+        .default(100_000)
+        .describe("Only conversations at least this large, in tokens, are kept warm by `auto`: a small one is cheap to re-read anyway."),
+    reserve: z
+        .number()
+        .int()
+        .min(0)
+        .max(90)
+        .default(15)
+        .describe(
+            "How much of an account's usage limit, in percent, keeping conversations warm must leave untouched for real work. Refreshing stops once any limit that account's model spends is fuller than that.",
+        ),
+});
+export type KeepWarmSettings = z.infer<typeof KeepWarmSettingsSchema>;

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

@@ -148,6 +148,14 @@ export const ProviderRefusalSchema = z.object({
         .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({
@@ -476,6 +484,35 @@ export const QueueScheduleSchema = z
         message: "a conversation cannot wait for its own work to land",
     });
 export type QueueSchedule = z.infer<typeof QueueScheduleSchema>;
+// Books the conversation to carry on from where its last turn stopped, at an instant or once another conversation's work
+// lands: a Continue (`agent.run` with `continues`) that waits in the queue, where every window draws it as scheduled,
+// rather than words. What a spent allowance's "Continue at 05:00" books, where it once booked the word "Continue".
+export const QueueContinueSchema = z
+    .object({
+        conversationId: z.string().min(1).describe("Which conversation carries on."),
+        sendAt: z
+            .number()
+            .int()
+            .positive()
+            .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."),
+        routing: ResumeRoutingSchema.optional().describe(
+            "Who serves the turn it starts. Leave it out to carry on where the conversation runs when it goes.",
+        ),
+        messageId: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Names the booking, so the same press sent twice books it once."),
+    })
+    .refine((input) => (input.sendAt === undefined) !== (input.sendAfter === undefined), {
+        message: "name exactly one of sendAt and sendAfter",
+    })
+    .refine((input) => input.sendAfter !== input.conversationId, {
+        message: "a conversation cannot wait for its own work to land",
+    });
+export type QueueContinue = z.infer<typeof QueueContinueSchema>;
 // Moves a conversation to another account of the provider it runs on: the one command that changes who pays, so the
 // account a conversation runs on is always the daemon's record and never a window's guess.
 export const SwitchAccountSchema = z.object({

package/src/schemas/providers/usage.ts

@@ -96,6 +96,15 @@ export const UsageTurnSchema = z.object({
     // Hash of the brief that was sent, recorded on control turns too. Load-bearing rather than decorative: the file is
     // rewritten monthly, so a 30-day window holds two different treatments and pooling them would measure neither.
     notesCohort: z.string().optional(),
+    // Arm of the tool-search experiment, stable per conversation: true loads connected tools' schemas on demand, false
+    // sends them all with every request. Absent where the turn was not a native Claude one on the Claude Code loop.
+    toolSearchArm: z.boolean().optional(),
+    // Arm of the stable-prompt experiment, stable per conversation: true says the guidance that moves between turns on
+    // the message when it changed, false keeps it in the system block. Absent outside the Claude Code loop.
+    stablePromptArm: z.boolean().optional(),
+    // Assigned on cold-eligible follow-ups only, including controls; cleared results only when a copy was resumed.
+    coldTrimArm: z.boolean().optional(),
+    coldTrimmed: z.number().int().min(0).optional(),
     // What became of pre-turn retrieval on this turn, and how long it took. Assignment and DELIVERY are different
     // facts: the first version of this mechanism was assigned to every eligible turn and reached four in five of them,
     // which is the difference between a null result and a mechanism that never ran. Absent means the flag was off, so

package/src/schemas/settings-experiments.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+
+// Agent experiments share conversation-stable arms; the sandbox settings schema owns their persisted shape.
+export const claudeExperimentSettings = {
+    // Claude Code turns itself out of tool search whenever its base URL is not Anthropic's own host, and the privacy
+    // shield's gateway is a loopback address, so every shielded native Claude turn paid every MCP tool's schema on every
+    // call (2026-10-18: a median 83k-token prompt before the first tool ran). The gateway forwards `tool_reference`
+    // blocks and the beta header untouched, so this asks for it by name. Native Claude only: a translator or minted
+    // endpoint may not speak the beta.
+    toolSearch: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Load the schemas of connected tools (browsers, devices, accounts, phones) only when the agent looks one up, instead of sending all of them with every request. The tools the agent leans on every turn stay loaded. Applies to Claude models on the Claude Code loop.",
+        ),
+    // Both arms set the CLI's switch explicitly, so a shielded turn and an unshielded one compare the same two things.
+    toolSearchHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.5)
+        .describe(
+            "What share of conversations to run with every tool loaded up front, so the two can be compared. Whole conversations rather than individual turns, because switching mid-conversation would rewrite the prompt the cache holds.",
+        ),
+    // Until 2026-10-18 this switch was read by nothing. The guidance paragraphs whose condition moves between turns (who
+    // is watching, which of the owner's machines, browsers and phones are online) sat in the system block, so each move
+    // rewrote the whole conversation to the provider's cache, and where Claude Code records a session's system prompt
+    // once the move never reached the model. Now they ride the turn's message, said when they changed.
+    stableSystemPrompt: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Keep the instructions identical between turns so the provider can cache them, saying what changes between turns (who is watching, which of your computers, browsers and phones are connected) on the message instead, and only when it changed. Applies to the Claude Code loop.",
+        ),
+    stableSystemPromptHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.5)
+        .describe(
+            "What share of conversations to run with those changing paragraphs kept in the instructions, so the two can be compared. Whole conversations rather than individual turns, because moving them mid-conversation would itself rewrite the cached prompt.",
+        ),
+    coldTrim: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Resume large Claude Code conversations with older tool output cleared once their prompt cache has expired. Keeps the conversation and tool calls, with directions to recover cleared output, and shows a trim notice.",
+        ),
+    coldTrimHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.5)
+        .describe(
+            "What share of conversations to resume whole when their cache is cold, so opening prompt size and failed tool calls can be compared. Whole conversations keep the same arm across follow-up turns.",
+        ),
+    coldTrimMinTokens: z
+        .number()
+        .int()
+        .min(0)
+        .default(100_000)
+        .describe(
+            "How many measured context tokens a Claude Code session must exceed before a cold follow-up can clear older tool output. Smaller sessions save little from trimming.",
+        ),
+};
+
+export const iqSearchSettings = {
+    iqSearch: z
+        .boolean()
+        .default(false)
+        .describe("Teach the agent how to use this workspace's own search tool, rather than leaving it to grep around."),
+    iqSearchHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0)
+        .describe(
+            "What share of conversations to run without that teaching, so the two can be compared. Whole conversations rather than individual turns, because once the teaching is in a session, withholding it from the next request does not make the model forget it.",
+        ),
+};

package/src/schemas/settings.ts

@@ -2,10 +2,12 @@
 // itself, which those settings adopt.
 import { STATE_DIR } from "@intentic/constants";
 import { z } from "zod";
+import { claudeExperimentSettings, iqSearchSettings } from "./settings-experiments.js";
 import { CommandJudgeModeSchema, ProjectInstallModeSchema } from "../policy/safety-policy.js";
 import { ModelRoleSchema } from "../models/model-roles.js";
 import { MODEL_SETUP_ID, ModelSetupSchema } from "../models/model-setups.js";
 import { AdmissionPolicySchema, AdmissionRuleSchema } from "./agent.js";
+import { KeepWarmSettingsSchema } from "./keep-warm.js";
 import { LimitHandoffSchema } from "./providers/handoff.js";
 import { SessionsPlacementSchema } from "./offload.js";
 import { LimitPolicySchema, RetryPolicySchema, RoomPolicySchema } from "./turn-break.js";
@@ -211,39 +213,8 @@ export type SkillSwitch = z.infer<typeof SkillSwitchSchema>;
 // picks rather than failing whole. A setting removed or reshaped here gets its conversion in settings-history.ts, which
 // also names every retired setting, none of whose names may come back.
 
-// keep-warm's knobs, one object since each only means anything beside the others (cache-keepwarm.ts).
-export const KeepWarmSettingsSchema = z.object({
-    auto: z
-        .boolean()
-        .default(false)
-        .describe(
-            "Keep a Claude conversation's prompt cache warm after each turn a person asked for. Each refresh re-reads the cached context at the cache price and adds nothing to the conversation.",
-        ),
-    hours: z
-        .number()
-        .min(1)
-        .max(8)
-        .default(4)
-        .describe(
-            "How long an idle conversation is kept warm after its last turn, in hours, and what a press on one offers first. Shortened where refreshing would cost more than the cold resume it saves, and at midnight where the agent runs, when the date in its prompt changes.",
-        ),
-    minTokens: z
-        .number()
-        .int()
-        .min(0)
-        .default(100_000)
-        .describe("Only conversations at least this large, in tokens, are kept warm by `auto`: a small one is cheap to re-read anyway."),
-    reserve: z
-        .number()
-        .int()
-        .min(0)
-        .max(90)
-        .default(15)
-        .describe(
-            "How much of an account's usage limit, in percent, keeping conversations warm must leave untouched for real work. Refreshing stops once any limit that account's model spends is fuller than that.",
-        ),
-});
-export type KeepWarmSettings = z.infer<typeof KeepWarmSettingsSchema>;
+// keep-warm's knobs live with its clock (keep-warm.ts); re-exported, as every settings reader imports them from here.
+export { type KeepWarmSettings, KeepWarmSettingsSchema } from "./keep-warm.js";
 
 // Who the editor's screens are written for: `developer` reads git's own words (branch, land, commit), `maker` plain ones
 // (draft, accept, save) over the same mechanisms. The editor's vocabulary, never anything an agent does. A person's own
@@ -273,12 +244,6 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Which clock this sandbox's schedules are set by, as a zone name like Europe/Warsaw. Automations that repeat on a clock fire by this, not by the machine's own time. Leave it empty and they fire by UTC, which is almost certainly not what you meant when you typed a time.",
         ),
-    stableSystemPrompt: z
-        .boolean()
-        .default(false)
-        .describe(
-            "Keep the instructions identical between turns so the provider can cache them, moving anything that varies into the message instead. Cheaper, at the cost of some flexibility.",
-        ),
     skills: z.array(z.string()).default(["lsp", "fileq"]).describe("Which built-in tools are switched on. A skill of your own is not listed here: it is on while the agent's copy of it exists."),
     // One half of the reading a new chat gets between send and its first turn (chat-router.ts): with this on, the
     // message and one line per card are put to the same model that chooses what the chat runs on, in the same call.
@@ -306,6 +271,15 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Keep the text of every document in the workspace (pdf, Word, OpenDocument, spreadsheets, presentations, epub, and scans where OCR is installed) ready to search. In the background, one low-priority process at a time, each document is rendered to text when it appears or changes, so `rg` and iq find what documents say under their own paths, cited by page. Off, nothing renders until someone opens a document, and searches skip them.",
         ),
+    // Whether the daemon tells its host it is unneeded (system/quiet-watch.ts): off, the work signal carries no
+    // `quietSince` and says `keepAwake`, so the machine's keeper never puts it to sleep (ic's `sandbox sleep`). Only a
+    // sandbox on somebody's own computer sleeps that way; a hosted machine's idle stop is the plan's and ignores this.
+    sleepWhenUnused: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Let the computer this sandbox runs on put it to sleep after a stretch nobody needs it (no editor open, no agent working, no terminal typed in, no app of it open), which frees its memory. It starts again when somebody opens it, and a few minutes before anything it has scheduled comes due, so automations still run on time. Off keeps it running. Applies only to a sandbox on your own computer.",
+        ),
     hashlineEdits: z
         .boolean()
         .default(false)
@@ -329,18 +303,8 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Your own instructions, used only when the mode above says custom. Then it is the whole of them: both built-in bases go, and so does everything this product would otherwise add, including the guidance the chat's own cards are driven by. That is the price of total control.",
         ),
-    iqSearch: z
-        .boolean()
-        .default(false)
-        .describe("Teach the agent how to use this workspace's own search tool, rather than leaving it to grep around."),
-    iqSearchHoldout: z
-        .number()
-        .min(0)
-        .max(1)
-        .default(0)
-        .describe(
-            "What share of conversations to run without that teaching, so the two can be compared. Whole conversations rather than individual turns, because once the teaching is in a session, withholding it from the next request does not make the model forget it.",
-        ),
+    ...iqSearchSettings,
+    ...claudeExperimentSettings,
     // Rooted at the run's own starting folder (a persona's, an isolated conversation's worktree), not the workspace
     // root — it maps the project containing that folder.
     workspaceMap: z
@@ -452,6 +416,10 @@ export const SandboxSettingsSchema = z.object({
     outagePolicy: RetryPolicySchema.default("wait").describe(
         "What happens to a turn the model provider's own failure killed. `wait` holds it for a press. `retry` re-runs it on the shared per-provider breaker, backing off between attempts. The sandbox-wide default; any one conversation can say otherwise. Worth `retry` for a sandbox whose work mostly happens with nobody in the room.",
     ),
+    // A vendor loop's hard cap on one turn; half an hour ended two Gemini children mid-work as failures (2026-10-17).
+    turnCapMinutes: z.number().int().min(5).max(1440).default(30).describe(
+        "The longest one turn may run on a loop the sandbox drives itself (OpenCode, an ACP agent, Pi, Muse) before it is ended, in minutes, however busy it keeps. A subagent's turn that reaches it is carried on in a fresh turn of the same session rather than ended as a failure. The Claude Code and Codex loops have no such cap.",
+    ),
     // The posture that used to live only in a browser tab; moving it here is what lets it fire with nothing open.
     stopPolicy: RetryPolicySchema.default("wait").describe(
         "What happens to a turn that stopped short with nothing to repair — a hung runtime, a crashed harness. `wait` holds it for a press. `retry` re-runs the held turn on a short ladder, standing down after three tries that got nowhere rather than looping forever.",
@@ -734,10 +702,14 @@ export const SavingsArmSchema = z.object({ turns: z.number(), mean: z.number() }
 // openedWithListing: whether a turn listed directories to orient itself, as a share of turns (the project map).
 // callsBeforeTarget: how far a turn walked before touching a file it went on to edit.
 // failedCalls: tool calls that ended in error (the field notes, whose largest section is a failure taxonomy).
+// openingPrompt: tokens a turn's first request sent (cache reads plus cache writes), which is what every later call of
+// the turn reads again (tool search, which moves the tool schemas out of it).
+// openingWrite: tokens a follow-up turn's first request wrote to the cache instead of reading them (the stable prompt).
 // Every reading is the main agent's own: a subagent's calls are counted toward the turn and read for nothing.
-// Never cost: each mechanism moves one small part of a turn's work, inside the noise of the rest.
+// Never cost: each mechanism moves one small part of a turn's work, inside the noise of the rest. The prompt's size is
+// the exception that proves it: it is the part every call pays again, so it is read directly rather than through cost.
 export const TurnMetricReadingSchema = z.object({
-    metric: z.enum(["searchCalls", "openingSearches", "openedWithListing", "callsBeforeTarget", "failedCalls"]),
+    metric: z.enum(["searchCalls", "openingSearches", "openedWithListing", "callsBeforeTarget", "failedCalls", "openingPrompt", "openingWrite"]),
     on: SavingsArmSchema,
     off: SavingsArmSchema,
     // Additional control turns to reach a fixed target resolution, not today's delta (which inherits noise and always
@@ -806,6 +778,9 @@ export const SavingsReportSchema = z.object({
     // Same absence rule as `search`: not measured, never zero.
     map: TurnExperimentSchema.optional(),
     notes: TurnExperimentSchema.optional(),
+    toolSearch: TurnExperimentSchema.optional(),
+    stablePrompt: TurnExperimentSchema.optional(),
+    coldTrim: TurnExperimentSchema.optional(),
 });
 export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 

package/src/schemas/voice.ts

@@ -159,7 +159,13 @@ export const VoiceServerMessageSchema = z.discriminatedUnion("type", [
         type: z.literal("audio"),
         id: z.number(),
         sampleRate: z.number(),
-        samples: z.number().describe("How many mono s16le samples the binary frame right after this one holds."),
+        samples: z.number().describe("How many mono samples the binary frame right after this one holds, as s16le or once decoded."),
+        codec: z
+            .literal("opus")
+            .optional()
+            .describe(
+                "Absent: the frame is s16le PCM. `opus`, only for a socket opened with `codec=opus`: the frame is the chunk's Opus packets, each a big-endian 16-bit length then the packet (opusPackets), one Opus stream per utterance and sample rate.",
+            ),
     }),
     z.object({ type: z.literal("done"), id: z.number() }),
     z.object({
@@ -170,3 +176,36 @@ export const VoiceServerMessageSchema = z.discriminatedUnion("type", [
     z.object({ type: z.literal("error"), id: z.number().optional(), message: z.string() }),
 ]);
 export type VoiceServerMessage = z.infer<typeof VoiceServerMessageSchema>;
+
+// Opus on the voice sockets, for a client that asks with `codec=opus` where the daemon's /events hello names it among
+// `voiceCodecs`: about a tenth of PCM's bytes (24 kbit/s for 16 kHz speech against 256, 33 for 24 kHz against 384).
+// `/speech/stream` takes one 20 ms packet per binary frame; `/speech/say` sends each chunk's packets in one frame, framed
+// by these two. A client that asks nothing is sent PCM, and an older daemon that ignores the ask sends PCM too.
+
+/** Packets as one frame: each a big-endian 16-bit length, then the packet. */
+export const framedOpus = (packets: readonly Uint8Array[]): Uint8Array<ArrayBuffer> => {
+    const frame = new Uint8Array(packets.reduce((total, packet) => total + 2 + packet.byteLength, 0));
+    const view = new DataView(frame.buffer);
+    let at = 0;
+    for (const packet of packets) {
+        view.setUint16(at, packet.byteLength);
+        frame.set(packet, at + 2);
+        at += 2 + packet.byteLength;
+    }
+    return frame;
+};
+
+/** The packets of a frame framedOpus made; a frame cut short ends at its last whole packet. */
+export const opusPackets = (frame: Uint8Array): Uint8Array[] => {
+    const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+    const packets: Uint8Array[] = [];
+    for (let at = 0; at + 2 <= frame.byteLength;) {
+        const length = view.getUint16(at);
+        if (at + 2 + length > frame.byteLength) {
+            break;
+        }
+        packets.push(frame.subarray(at + 2, at + 2 + length));
+        at += 2 + length;
+    }
+    return packets;
+};

package/src/schemas/workspace/workspace-tree.ts

@@ -160,6 +160,26 @@ export const WorkspaceDownloadTicketSchema = z.object({
     expiresAt: z.number().describe("When it stops working, in milliseconds. It is meant to be used at once."),
     filename: z.string().describe("What the archive is saved as, so a caller can say what is on its way."),
 });
+// Credential for GET /workspace/preview/{ticket}/*, which a frame loads a web page from so it runs as it would on a
+// static file server: its scripts, modules, fetches and links resolve against real addresses. The ticket is the path's
+// first segment, so every relative address the page names carries it on.
+export const WorkspacePreviewTicketQuerySchema = WorkspaceScopeSchema.extend({
+    path: z.string().min(1).describe("The web page to preview, as a workspace path."),
+    source: z
+        .string()
+        .max(8 * 1024 * 1024)
+        .optional()
+        .describe("The page's text as the editor holds it, when it has edits not yet saved; served in place of the file on disk."),
+});
+export const WorkspacePreviewTicketSchema = z.object({
+    page: z.string().describe("The page's address on this daemon, a path to put after its base URL; the ticket is inside it."),
+    root: z
+        .string()
+        .describe(
+            "The folder the ticket serves, as a workspace path (empty for the workspace's root): the page's own repository. An address under the ticket names the file at the same place under this folder.",
+        ),
+    expiresAt: z.number().describe("When it stops working, in milliseconds."),
+});
 // A read of a window: offset negative reads that many bytes from the end (for following a growing log); limit is
 // clamped to the daemon's own cap. Coerced from query strings.
 export const WorkspaceFileReadQuerySchema = WorkspaceScopeSchema.extend({

package/src/text/packed-formats.ts

@@ -0,0 +1,17 @@
+// File formats whose bytes are already compressed (images, audio, video, archives, office documents, fonts): encoding
+// them again spends CPU and saves next to nothing. The daemon stores them as they are in a ZIP it streams, and the
+// browser sends them plain where it gzips the rest of an upload, so both read the one list here.
+
+const PACKED = new Set(
+    (
+        "7z aac apk avif br bz2 cab deb docx dmg epub flac gif gz heic heif ico jar jpeg jpg jxl lz lz4 lzma m4a m4v mkv mov mp3 mp4 mpeg mpg " +
+        "odg odp ods odt ogg ogv opus pdf png pptx rar rpm tbz tgz txz webm webp whl woff woff2 xlsx xz zip zst"
+    ).split(" "),
+);
+
+/** Whether a file of this name holds bytes that are already compressed, by its extension. */
+export const isPackedName = (name: string): boolean => {
+    const base = name.slice(name.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    return dot > 0 && PACKED.has(base.slice(dot + 1).toLowerCase());
+};