@intentic/sandbox-contract 1.318.0 → 1.319.0

package/src/front/generated/front-wire.json

@@ -50,6 +50,18 @@
               "plan"
             ],
             "type": "object"
+          },
+          {
+            "properties": {
+              "answer": {
+                "const": "pong",
+                "type": "string"
+              }
+            },
+            "required": [
+              "answer"
+            ],
+            "type": "object"
           }
         ]
       },
@@ -699,6 +711,19 @@
               "query"
             ],
             "type": "object"
+          },
+          {
+            "description": "Whether Node's event loop turns, and how fast: answered `pong` at once, by the link itself. The front sends one\nevery 2 s once the previous one is answered, and reports the round trip as the vitals' lag. An older Node answers\nwith a refusal, or with an answer the front cannot read, and either still counts as answered.",
+            "properties": {
+              "question": {
+                "const": "ping",
+                "type": "string"
+              }
+            },
+            "required": [
+              "question"
+            ],
+            "type": "object"
           }
         ]
       }

package/src/front/generated/wire.ts

@@ -4,7 +4,7 @@ export type Answer = { "answer": "preview", route: PreviewRoute, } | { "answer":
 /**
  * The member whose ticket opened it, lowercased; absent when the daemon runs without auth.
  */
-member?: string, };
+member?: string, } | { "answer": "pong" };
 
 /**
  * A PEM certificate chain and its PEM private key.
@@ -61,7 +61,7 @@ export type PreviewRoute = { "to": "upstream", upstream: Upstream, } | { "to": "
 /**
  * A question the front asks Node.
  */
-export type Question = { "question": "preview", host: string, probe: boolean, } | { "question": "terminal", query: string, };
+export type Question = { "question": "preview", host: string, probe: boolean, } | { "question": "terminal", query: string, } | { "question": "ping" };
 
 export type Scheme = "http" | "https";
 

package/src/front/wire-manifests.test.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { EDGE_VERDICT_HEADER, edgeVerdictOf } from "../protocol/edge-verdict.js";
 import { INGRESS_GRANT_HEADER, INGRESS_TUNNEL_PATH } from "../protocol/ingress-contract.js";
+import { VITALS_PATH } from "../protocol/vitals.js";
 import { EDGE_TRANSPORTS, TERMINAL_PATH, WEBTRANSPORT_PATH } from "./browser-wire.js";
 import { ASK_PATIENCE_MS, FRAME_LENGTH_BYTES, FRONT_SOCKET_ENV, NODE_SOCKET_ENV } from "./front-wire.js";
 
@@ -23,6 +24,7 @@ const socket = manifest("front-wire") as {
 const browser = manifest("browser-wire") as {
     edge: { verdictHeader: string; verdicts: { oneOf: { const: string }[] } };
     terminal: { path: string; upgrade: string };
+    vitals: { path: string; body: { $defs: { NodeLink: { oneOf: { const: string }[] } } } };
     webTransport: { path: string };
 };
 
@@ -58,4 +60,9 @@ describe("the wire outside oRPC, as the Rust crates define it", () => {
             upgrade: browser.terminal.upgrade,
         });
     });
+
+    it("finds the front's vitals where browser-wire says it answers them, in the states it names", () => {
+        expect(VITALS_PATH).toBe(browser.vitals.path);
+        expect(browser.vitals.body.$defs.NodeLink.oneOf.map((state) => state.const)).toEqual(["starting", "up", "restarting"]);
+    });
 });

package/src/index.ts

@@ -88,6 +88,7 @@ export { issuesContract } from "./contracts/issues.contract.js";
 export { logsContract } from "./contracts/logs.contract.js";
 export { REQUEST_ID_HEADER } from "./protocol/request-id.js";
 export * from "./protocol/edge-verdict.js";
+export * from "./protocol/vitals.js";
 export { loopsContract } from "./contracts/loops.contract.js";
 export { panelsContract } from "./contracts/panels.contract.js";
 export { portsContract } from "./contracts/ports.contract.js";

package/src/protocol/raw-routes.ts

@@ -28,6 +28,9 @@ export const RAW_ROUTES = {
     "POST /system/ws-ticket": { beforeBoot: true, floor: "collaborator", control: "never" },
     // A WebSocket upgrade carries no Authorization header; the terminal and both browser wires check a query ticket.
     "GET /system/terminal": { auth: "door", beforeBoot: true, control: "never", front: true },
+    // The front's proof of life (vitals.ts): no credential and nothing of the workspace, readable by any origin, answered
+    // whatever state the daemon is in.
+    "GET /system/vitals": { auth: "door", beforeBoot: true, front: true },
     // Desktop sync's byte pipe, guarded again by sshd's own key check against the same enrollment.
     "GET /system/sync/ssh": { sync: "pipe", control: "never", lane: "bulk" },
     "GET /system/browser-profile": { auth: "door", beforeBoot: true, control: "never" },

package/src/protocol/vitals.test.ts

@@ -0,0 +1,46 @@
+import { RAW_ROUTES, rawRoutePath } from "./raw-routes.js";
+import { parseVitals, type SandboxVitals, VITALS_PATH } from "./vitals.js";
+
+// The JSON browser-wire's own test pins (`vitals_are_the_camel_case_json_the_editor_parses_with_null_for_what_is_unknown`):
+// what the front writes, the editor reads.
+const RUST_GOLDEN_JSON = `{"node":"restarting","lagMs":null,"restarts":2,"uptimeS":3600,"pressure":{"cpu":12.34,"memory":0.0,"io":1.5}}`;
+
+const up: SandboxVitals = { node: "up", lagMs: 12, restarts: 0, uptimeS: 60, pressure: { cpu: 0.29, memory: 0.49, io: 0.88 } };
+
+it("reads the front's own answer as it writes it", () => {
+    expect(parseVitals(JSON.parse(RUST_GOLDEN_JSON))).toEqual({
+        node: "restarting",
+        lagMs: null,
+        restarts: 2,
+        uptimeS: 3600,
+        pressure: { cpu: 12.34, memory: 0, io: 1.5 },
+    });
+    expect(parseVitals(up)).toEqual(up);
+    expect(parseVitals({ ...up, node: "starting" })?.node).toBe("starting");
+});
+
+it("reads a lag or pressure it cannot make out as unknown, and keeps the rest", () => {
+    const { lagMs: _lag, pressure: _pressure, ...bare } = up;
+    expect(parseVitals(bare)).toEqual({ ...bare, lagMs: null, pressure: null });
+    expect(parseVitals({ ...up, lagMs: -1, pressure: { cpu: 1 } })).toEqual({ ...up, lagMs: null, pressure: null });
+    // A later front's extra fields are not this reader's business.
+    expect(parseVitals({ ...up, since: "later" })).toEqual(up);
+});
+
+it("is undefined for anything that is not the front's answer", () => {
+    // An older sandbox forwards the path to Node, which answers 404 as JSON, or a preview's HTML page.
+    expect(parseVitals({ error: "Not Found" })).toBeUndefined();
+    expect(parseVitals("<!doctype html><title>Not found</title>")).toBeUndefined();
+    expect(parseVitals(null)).toBeUndefined();
+    expect(parseVitals(42)).toBeUndefined();
+    expect(parseVitals([up])).toBeUndefined();
+    expect(parseVitals({ ...up, node: "crashed" })).toBeUndefined();
+    expect(parseVitals({ ...up, restarts: -1 })).toBeUndefined();
+    expect(parseVitals({ ...up, uptimeS: 1.5 })).toBeUndefined();
+    expect(parseVitals({ ...up, restarts: "2" })).toBeUndefined();
+});
+
+it("is a route the front serves itself, with no credential, before the daemon boots", () => {
+    expect(rawRoutePath("GET /system/vitals")).toBe(VITALS_PATH);
+    expect(RAW_ROUTES["GET /system/vitals"]).toEqual({ auth: "door", beforeBoot: true, front: true });
+});

package/src/protocol/vitals.ts

@@ -0,0 +1,38 @@
+// The sandbox's proof of life, which intentic-front answers itself on the daemon's own address and never forwards to
+// Node: whether Node is up, how long its event loop takes to answer the front's ping, how often the front restarted it,
+// how long the container has run, and its pressure stall. The daemon's heartbeat on /events rides Node's event loop,
+// so a busy sandbox and a dead one look alike from there; this route tells them apart. The Rust crate `browser-wire`
+// is the definition (SandboxVitals), and wire-manifests.test.ts holds the path here to the manifest it writes.
+
+import { z } from "zod";
+import type { NodeLink, Pressure, SandboxVitals } from "../front/generated/browser-wire.js";
+
+export type { NodeLink, Pressure, SandboxVitals };
+
+// A plain GET any origin may read, answered by the front whatever state Node is in. The route is registered as
+// `front: true` in raw-routes.ts, so the daemon serves none.
+export const VITALS_PATH = "/system/vitals";
+
+// Every state, so a new one in the Rust enum fails this file's typecheck until it is read here too.
+const NODE_LINKS = { starting: "starting", up: "up", restarting: "restarting" } as const satisfies { readonly [K in NodeLink]: K };
+
+const PressureSchema = z.object({ cpu: z.number(), memory: z.number(), io: z.number() });
+
+// Lenient where a figure is only a detail: a lag or a pressure it cannot read is unknown, and the rest still stands.
+const VitalsSchema = z.object({
+    node: z.enum(NODE_LINKS),
+    lagMs: z.number().nonnegative().nullable().catch(null),
+    restarts: z.number().int().nonnegative(),
+    uptimeS: z.number().int().nonnegative(),
+    pressure: PressureSchema.nullable().catch(null),
+});
+
+// A response body as `Response.json()` hands it over: any JSON value, not yet known to be the front's answer.
+type JsonBody = string | number | boolean | null | readonly JsonBody[] | { readonly [key: string]: JsonBody };
+
+// The front's answer, or undefined for anything else: an older sandbox forwards the path to Node, which answers 404 or
+// an HTML page, and an edge in between may answer for a box that is not there.
+export const parseVitals = (body: JsonBody): SandboxVitals | undefined => {
+    const parsed = VitalsSchema.safeParse(body);
+    return parsed.success ? parsed.data : undefined;
+};

package/src/schemas/agent.ts

@@ -304,6 +304,16 @@ const AgentTurnFieldsSchema = z.object({
     editorContext: EditorContextSchema.optional().describe(
         'What the user has open in their editor, folded into the prompt so that pointing words like "this" resolve.',
     ),
+    // The composer's scheduled send: a person who knows the account is spent books the message for its reopen instead of
+    // sending it into a refusal. Held in the conversation's queue, never started early; the queue's `until` is this.
+    sendAt: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe(
+            "Hold this message until then (epoch milliseconds) instead of starting a turn now, for an allowance you know is spent. It waits in the conversation's queue, where it can be sent early, reworded or removed, and goes by itself at that instant. Ignored when already past, or when a turn is running.",
+        ),
 });
 export const AgentTurnSchema = AgentTurnFieldsSchema
     // An attachment-only send (no text) is legal; an entirely empty turn is not.
@@ -473,7 +483,7 @@ export const QueuedMessageSchema = z.object({
 });
 export type QueuedMessage = z.infer<typeof QueuedMessageSchema>;
 // Why a queue holds its messages rather than letting them go when the conversation is free.
-export const QueuePauseSchema = z.enum(["stopped", "refused"]);
+export const QueuePauseSchema = z.enum(["stopped", "refused", "scheduled"]);
 export type QueuePause = z.infer<typeof QueuePauseSchema>;
 // What waits for a conversation's next turn: messages that arrived while a turn that could not take them ran, and
 // held ones. Conversation state, the same for every window and kept across a restart.
@@ -481,8 +491,12 @@ export const ConversationQueueSchema = z.object({
     items: z.array(QueuedMessageSchema).describe("What waits, in the order it goes out."),
     revision: z.number().int().nonnegative().describe("Moves with every change to the queue, so of two copies the higher is the newer."),
     paused: QueuePauseSchema.optional().describe(
-        "Why nothing goes out by itself: somebody stopped the turn, or the turn these messages started was refused before it ran. Resuming, or sending another message, lets them go.",
+        "Why nothing goes out by itself: somebody stopped the turn, the turn these messages started was refused before it ran, or they were scheduled for later. Resuming lets them go, and so does sending another message unless they are scheduled.",
     ),
+    until: z
+        .number()
+        .optional()
+        .describe("When scheduled messages go out by themselves, in milliseconds. Only on a queue paused as `scheduled`."),
 });
 export type ConversationQueue = z.infer<typeof ConversationQueueSchema>;
 // What resuming a queue did: started a turn with what waited, when nothing else ran.

package/src/schemas/settings-history.ts

@@ -85,6 +85,7 @@ export const SETTINGS_HISTORY = [
         "quickModel",
         "resumeAfterLimit",
         "resumeAfterOutage",
+        "sidecars",
         "terseHoldout",
         "terseOutput",
         "testFaultDetection",

package/src/schemas/settings.ts

@@ -372,13 +372,6 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "What share of conversations to run without the brief, so the two can be compared. Whole conversations rather than individual turns, because the brief sits in the prompt for the whole session and withholding it from one turn would not take it back.",
         ),
-    // Only the eager background pass; the `fileq` CLI itself is always on PATH regardless, gated only by its own skill.
-    sidecars: z
-        .boolean()
-        .default(false)
-        .describe(
-            "Keep an up-to-date markdown rendering of every document, image and audio file in the workspace, made in the background as files land, so the agent reads a pre-derived text instead of paying to parse the file mid-task. Costs background CPU on a document-heavy workspace, so it is a switch rather than a default.",
-        ),
     outputCleaners: z
         .string()
         .default("")
@@ -630,6 +623,7 @@ export const InputSavingsSchema = z.object({
 });
 export type InputSavings = z.infer<typeof InputSavingsSchema>;
 // One arm of a turn-level experiment; mean is per turn, since the two arms never hold the same count.
+// `mean` is over samples capped at both arms' pooled 95th percentile, so one runaway conversation cannot carry an arm.
 export const SavingsArmSchema = z.object({ turns: z.number(), mean: z.number() });
 // One metric's reading of a turn-level experiment (the two arms, plus the arithmetic over them). `metric` says what
 // `mean`/`deltaPct` count:

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

@@ -210,29 +210,14 @@ export const WorkspaceDerivedQuerySchema = z.object({
         .min(1)
         .describe("The file you want the text of, as a workspace path. The real file, not its shadow: where the text is kept is this route's business."),
 });
-// Where the background pass stands, workspace-wide. Nothing about a file on disk can say this, and without it an
-// unrendered file and a file queued behind forty others look identical to a reader.
-export const SidecarStatusSchema = z.object({
-    enabled: z.boolean().describe("Whether the background pass is on (the `sidecars` setting). Off means a shadow exists only where someone asked for one."),
-    queued: z.number().describe("Files waiting for a shadow, not counting the batch being rendered right now."),
-    deriving: z
-        .array(z.string())
-        .describe("The files being rendered at this moment, as workspace paths. One batch at a time, because derivation shares the box with the agent it serves."),
-    sweeping: z.boolean().describe("Whether a whole-tree pass is running, which is what a freshly enabled setting or an unlistably large batch triggers."),
-    broken: z.boolean().describe("Whether the `fileq` binary is missing, in which case nothing renders in the background until this sandbox restarts."),
-    shadows: z.number().optional().describe("How many shadows the last whole-tree pass counted. Absent until one has run in this daemon's lifetime."),
-    sweptAt: z.string().optional().describe("When that pass finished, as an ISO timestamp."),
-});
-export type SidecarStatus = z.infer<typeof SidecarStatusSchema>;
-// Where one file stands with that pass, which is the question a reader looking at a missing or stale shadow is
-// actually asking. `idle` means the pass is on and this file is not waiting for anything: what it has is what it gets.
-export const DerivedStateSchema = z.enum(["off", "queued", "deriving", "idle", "broken", "undeliverable"]);
+// Where one file stands, which is the question a reader looking at a missing or stale rendering is actually asking.
+// Nothing renders in the background: a file has text once someone asks for it, and fileq keeps it until the file changes.
+export const DerivedStateSchema = z.enum(["deriving", "idle", "broken", "undeliverable"]);
 export type DerivedState = z.infer<typeof DerivedStateSchema>;
 const DerivedStandingShape = {
     state: DerivedStateSchema.describe(
-        "Where this file stands with the background pass: switched off, waiting its turn, being read right now, settled, or unreachable because the renderer is missing. `undeliverable` is a format nothing here reads.",
+        "Where this file stands: being read right now, settled (what it has is what it gets until someone asks), or unreachable because the renderer is missing. `undeliverable` is a format nothing here reads.",
     ),
-    queue: SidecarStatusSchema.describe("How the background pass as a whole is doing, so a wait can be reported as a queue rather than as nothing happening."),
 };
 export const WorkspaceDerivedPresentSchema = z.object({
     ...DerivedStandingShape,
@@ -257,7 +242,7 @@ export const WorkspaceDerivedPresentSchema = z.object({
 });
 export const WorkspaceDerivedAbsentSchema = z.object({
     ...DerivedStandingShape,
-    present: z.literal(false).describe("There is no derived text for that file. Read `state` before saying so to anyone: absent and queued are different answers."),
+    present: z.literal(false).describe("There is no derived text for that file. Read `state` before saying so to anyone: absent and being read are different answers."),
     path: z.string().describe("The file, as asked for."),
     derivable: z
         .boolean()