@intentic/sandbox-contract 1.223.0 → 1.225.0

package/src/routes.ts

@@ -6,18 +6,18 @@ import { z } from "zod";
  * normal and neither should force an update.
  *
  * What must not happen is the failure being SILENT. A route the daemon predates answers 404, which the browser
- * has no way to tell apart from "you asked for a file that isn't there" — so a missing feature reads as a
+ * has no way to tell apart from "you asked for a file that isn't there", so a missing feature reads as a
  * broken one, and diagnosing it costs an hour of "did the image rebuild?".
  *
  * So the daemon ADVERTISES the routes it implements (the /events hello frame) and the browser compares that
  * against the contract it was itself built with. Everything present on both sides works exactly as before;
  * anything the daemon lacks is a KNOWN, NAMED gap the UI can gate a feature on or explain in an error, instead
- * of a mystery 404. Old daemon + new browser stays fully supported — it just stops being confusing.
+ * of a mystery 404. Old daemon + new browser stays fully supported, it just stops being confusing.
  *
  * Route names are `<group>.<route>` (`vpn.list`, `kimi.models`), derived from the contract object both sides
  * import. Nothing is generated and nothing is hand-maintained: adding a route to the contract adds it here.
  *
- * Everything here is a pure function of a contract passed in — index.ts binds them to `sandboxContract` once it
+ * Everything here is a pure function of a contract passed in, index.ts binds them to `sandboxContract` once it
  * is assembled, which is what keeps this module out of an import cycle with it. */
 
 // The shape we read off an oRPC contract procedure. `~orpc.route` is the contract metadata oRPC attaches to
@@ -43,7 +43,7 @@ const procedureRoute = (value: unknown): { method: string; path: string } | unde
 export interface ContractRoute {
     readonly name: string;
     readonly method: string;
-    // The oRPC path template, with `{param}` placeholders — e.g. `/system/terminals/{name}`.
+    // The oRPC path template, with `{param}` placeholders, e.g. `/system/terminals/{name}`.
     readonly path: string;
 }
 
@@ -69,7 +69,7 @@ export const contractRoutes = (contract: Record<string, unknown>): ContractRoute
  *
  * The route list above answers "does this daemon have it". It cannot answer the other half: a route that
  * exists on BOTH sides but whose payload changed between the two builds. Names match, so the call goes out,
- * and a field the browser expects is simply missing from the answer — no 404, no message, nothing to attribute
+ * and a field the browser expects is simply missing from the answer, no 404, no message, nothing to attribute
  * it to. That is the one skew failure the named-gap mechanism still leaves silent.
  *
  * So each route also advertises a fingerprint of its wire shape: input and output schema together, reduced to
@@ -82,25 +82,25 @@ export const contractRoutes = (contract: Record<string, unknown>): ContractRoute
  * "hangs on someone remembering"). Changing a field in a contract schema changes that route's fingerprint by
  * itself, on both sides, with nobody to remember anything. */
 
-// The schemas oRPC hangs off a contract procedure, read structurally for the same reason as `route` above —
+// The schemas oRPC hangs off a contract procedure, read structurally for the same reason as `route` above,
 // they are internal metadata, not part of its public surface.
 interface ContractSchemasLike {
     readonly "~orpc": { readonly inputSchema?: unknown; readonly outputSchema?: unknown };
 }
 
-/* The JSON Schema keywords whose array value is a SET — order carries no meaning, so two schemas that differ
+/* The JSON Schema keywords whose array value is a SET, order carries no meaning, so two schemas that differ
  * only in it are the same wire shape. `required` is the one that matters in practice: JSON Schema spells an
  * object's fields twice, once as `properties` (an object, so key-sorting settles it) and once as `required`
- * (an array, in declaration order) — so without this, moving a field up a `z.object` for readability reads as
+ * (an array, in declaration order), so without this, moving a field up a `z.object` for readability reads as
  * drift on every route that carries it. The union keywords are here for the same reason a step lower down. */
 const UNORDERED = new Set(["required", "enum", "anyOf", "oneOf", "allOf"]);
 
 /* Canonical JSON: object keys sorted, set-valued arrays sorted, everything else left in the order it was
- * written. So the fingerprint depends on what the schema SAYS rather than how zod happened to emit it — which
+ * written. So the fingerprint depends on what the schema SAYS rather than how zod happened to emit it, which
  * is what keeps a purely cosmetic edit from being reported to a user as a payload that moved.
  *
  * Ordered arrays stay ordered: a tuple's `prefixItems` is positional, and sorting it would call two genuinely
- * different shapes identical — the failure that actually costs something here. */
+ * different shapes identical, the failure that actually costs something here. */
 const canonical = (value: unknown, key?: string): unknown => {
     if (Array.isArray(value)) {
         const items = value.map((item) => canonical(item));
@@ -114,7 +114,7 @@ const canonical = (value: unknown, key?: string): unknown => {
 };
 
 /* FNV-1a over the canonical JSON, base36. Deliberately not a cryptographic hash: this is a drift SIGNAL, and
- * the cost of a collision is one warning that never appears — never a wrong action, never a blocked call. A
+ * the cost of a collision is one warning that never appears, never a wrong action, never a blocked call. A
  * crypto digest would mean a subtle-crypto round trip in the browser (async, and unavailable on insecure
  * origins) to buy nothing this use has any need of. */
 const fingerprint = (value: unknown): string => {
@@ -133,8 +133,8 @@ const fingerprint = (value: unknown): string => {
  * way out, so reading both sides in the same direction would call two genuinely different shapes identical.
  *
  * A schema that will not convert yields undefined rather than throwing the walk away. Every such route in the
- * contract today is a streaming one — oRPC wraps an event iterator's output in an opaque type with no schema
- * underneath it — and their absence lands them in exactly the right place: a route with no advertised shape is
+ * contract today is a streaming one, oRPC wraps an event iterator's output in an opaque type with no schema
+ * underneath it, and their absence lands them in exactly the right place: a route with no advertised shape is
  * assumed compatible, which is the same "positive evidence only" rule the missing-route check already runs on. */
 const procedureShape = (value: unknown): string | undefined => {
     if (typeof value !== "object" || value === null || !("~orpc" in value)) {
@@ -174,7 +174,7 @@ export const routeShapes = (contract: Record<string, unknown>): Record<string, s
 };
 
 // Does a concrete request path match this route's template? Segment-wise, with `{param}` matching exactly one
-// segment — the same shape oRPC mounts, so a template can never match a longer or shorter path.
+// segment, the same shape oRPC mounts, so a template can never match a longer or shorter path.
 const pathMatches = (template: string, path: string): boolean => {
     const wanted = template.split("/");
     const actual = path.split("/");
@@ -185,7 +185,7 @@ const pathMatches = (template: string, path: string): boolean => {
 };
 
 // The contract route a concrete request belongs to, or undefined when the path is not a contract route at all
-// (the daemon also serves hand-written Hono routes like /health and /workspace/raw — those are never gated).
+// (the daemon also serves hand-written Hono routes like /health and /workspace/raw, those are never gated).
 // The query string is stripped first; callers pass whatever they handed to fetch.
 export const routeNameForRequest = (routes: readonly ContractRoute[], method: string, pathWithQuery: string): string | undefined => {
     const path = pathWithQuery.split("?")[0] ?? pathWithQuery;
@@ -193,18 +193,18 @@ export const routeNameForRequest = (routes: readonly ContractRoute[], method: st
     return routes.find((route) => route.method.toUpperCase() === upper && pathMatches(route.path, path))?.name;
 };
 
-// The route a typed client call belongs to. oRPC addresses a procedure by its position in the contract —
-// `['git','stashApply']` — which is the contract's own name for it, so this is a lookup rather than a match.
+// The route a typed client call belongs to. oRPC addresses a procedure by its position in the contract,
+// `['git','stashApply']`, which is the contract's own name for it, so this is a lookup rather than a match.
 export const routeForProcedure = (routes: readonly ContractRoute[], procedure: readonly string[]): ContractRoute | undefined =>
     routes.find((route) => route.name === procedure.join("."));
 
-// THE CONCRETE PATH A TYPED CALL WILL CARRY — the route template with every `{param}` replaced by the input
+// THE CONCRETE PATH A TYPED CALL WILL CARRY, the route template with every `{param}` replaced by the input
 // field of the same name, which is how the OpenAPI link fills them.
 //
 // This exists so a permission gate can check the string the daemon will actually route on rather than the
 // template it came from. Checking the template would quietly widen every grant: a wildcard glob matches the
 // literal `{repo}` braces just as happily as it matches a repo name, so a manifest that narrowed the grant to
-// one repo would still admit calls for every other — the gate would be comparing two patterns instead of
+// one repo would still admit calls for every other, the gate would be comparing two patterns instead of
 // testing a value against one.
 //
 // A param with no matching input field keeps its placeholder. That cannot be reached through the typed client

package/src/runtime-state.test.ts

@@ -39,7 +39,7 @@ describe(`runtimeBoundQueryKeys`, () => {
         expect(joined(runtimeBoundQueryKeys())).toEqual(joined(RUNTIME_DOMAIN_BINDINGS.flatMap((binding) => binding.invalidates)));
     });
 
-    it(`leaves no domain declaring no keys — a domain nothing renders has no reason to be pushed`, () => {
+    it(`leaves no domain declaring no keys: a domain nothing renders has no reason to be pushed`, () => {
         expect(RUNTIME_DOMAIN_BINDINGS.filter((binding) => binding.invalidates.length === 0)).toEqual([]);
     });
 });

package/src/runtime-state.ts

@@ -1,9 +1,9 @@
-/* WHICH RUNNING THING BACKS WHICH VIEW — the twin of workspace-state.ts, for state that never touches a file.
+/* WHICH RUNNING THING BACKS WHICH VIEW, the twin of workspace-state.ts, for state that never touches a file.
  *
  * That table answers "the agent wrote a file, so which view is stale". This one answers the same question for
  * the half of the sandbox that has no file to watch: the tmux sessions, the dev-server panels, the listening
  * sockets, the agent's Chromiums, the children its turns spawn. None of them are on disk, so no
- * `workspaceChanged` batch can ever mention them — and for want of a push, every one of those views polled.
+ * `workspaceChanged` batch can ever mention them, and for want of a push, every one of those views polled.
  *
  * The polls were the tell. Six always-on timers (a 10s terminals relist behind THREE mounted surfaces, a 15s
  * port scan behind the shell rail, a 4s panel relist for as long as any dev server ran) that each asked a
@@ -14,14 +14,14 @@
  * told to. The declaration lives HERE for the reason its twin does: the daemon publishes a DOMAIN and the
  * browser turns it into query keys, and those two facts drift the moment they are written down in two packages.
  *
- * A key belongs to whoever queries it — the extension views that render ports and panels ask under the SAME key
+ * A key belongs to whoever queries it, the extension views that render ports and panels ask under the SAME key
  * as core (api.sandbox.key("ports") is sandboxKey("ports")), so one entry here refreshes both surfaces and an
  * extension needs no declaration of its own. */
 
-/* One query key as the browser files it, a segment per level — so a binding can name a NESTED key and not only
+/* One query key as the browser files it, a segment per level, so a binding can name a NESTED key and not only
  * a top-level one. Most domains here are a single segment and read as they always did; the review is not. Its
  * key is `["git", "changes"]` (the browser appends the sandbox id, and every open file diff hangs beneath it),
- * and a domain that could only say `"git"` would drop the commit log along with it — a second read of the graph
+ * and a domain that could only say `"git"` would drop the commit log along with it, a second read of the graph
  * to deliver a sentence that has nothing to do with it. */
 export type QueryKeyPath = readonly string[];
 
@@ -29,24 +29,24 @@ export interface RuntimeDomainBinding {
     // What moved, in the daemon's words. Wire data: it rides the runtimeChanged frame.
     readonly domain: string;
     /* The browser query keys this domain's state feeds. Invalidation reaches only queries something is
-     * OBSERVING, so a domain nobody has on screen costs a frame and no request — which is what lets a domain be
+     * OBSERVING, so a domain nobody has on screen costs a frame and no request, which is what lets a domain be
      * pushed eagerly without billing every tab for a view it isn't showing. */
     readonly invalidates: readonly QueryKeyPath[];
 }
 
 /* Declared `as const` so the domain names survive as literal types (see RuntimeDomain below), then published
- * under the interface — the same two-binding shape, for the same reason, as WORKSPACE_STATE_FILES. */
+ * under the interface, the same two-binding shape, for the same reason, as WORKSPACE_STATE_FILES. */
 const RUNTIME_DOMAINS = [
     /* Every attachable tmux session: the terminal panel's tab strip, the rail's activity badge, and the work
-     * popover's background-process rows all read this one list. Sampled rather than announced — a pane dies
-     * when its command exits and tmux tells nobody — but sampled ONCE in the daemon, on a connection the
+     * popover's background-process rows all read this one list. Sampled rather than announced, a pane dies
+     * when its command exits and tmux tells nobody, but sampled ONCE in the daemon, on a connection the
      * browsers already hold, instead of once per browser per 10s over the tunnel. */
     { domain: "terminals", invalidates: [["terminals"]] },
 
     /* A repo's dev server: running, healthy, and the preview URL it answers on. Two independent things move it,
-     * and it needs both — the process manager starting or reaping a session (announced), and the server
+     * and it needs both, the process manager starting or reaping a session (announced), and the server
      * actually binding its port some seconds later, which is what flips "starting" to "healthy" (seen by the
-     * port sampler, since panel health is read off the listening sockets — see panels.ts listenersByRepo).
+     * port sampler, since panel health is read off the listening sockets, see panels.ts listenersByRepo).
      *
      * `apps` rides it because a monorepo's per-app previews ARE managed processes under the same manager
      * (workspace.routes appsList reads processes.portOf), just listed per repo instead of per repo-root. One
@@ -54,13 +54,13 @@ const RUNTIME_DOMAINS = [
     { domain: "panels", invalidates: [["panels"], ["apps"]] },
 
     /* Every listening TCP socket in the sandbox, and which of them are forwarded to a public preview hostname.
-     * The daemon runs no port poller for the ANSWER — attributing a socket to its process walks every /proc fd
-     * table, far too much to do on a timer — so what is sampled is only the LISTEN set out of /proc/net/tcp:
+     * The daemon runs no port poller for the ANSWER, attributing a socket to its process walks every /proc fd
+     * table, far too much to do on a timer, so what is sampled is only the LISTEN set out of /proc/net/tcp:
      * two file reads, enough to know that the answer changed and worth nobody's while to compute until a view
      * asks. Change detection and payload are deliberately different sizes here. */
     { domain: "ports", invalidates: [["ports"]] },
 
-    // The agent's Chromiums and the pages each holds open — daemon-held records, minted from the hooks that see
+    // The agent's Chromiums and the pages each holds open, daemon-held records, minted from the hooks that see
     // the agent's own browser tool calls, so every change to this roster passes through this process.
     { domain: "browsers", invalidates: [["browsers"]] },
 
@@ -72,17 +72,17 @@ const RUNTIME_DOMAINS = [
     /* The post queue, when the DAEMON moves it rather than the owner. Approving is the owner's own mutation and
      * refetches itself, but everything after that happens while nobody is touching the page: a held post coming
      * due, a Discord send landing, a publish turn writing back what went out. Those are the moments the row on
-     * screen stops being true — and this queue is watched precisely because its rows go out in public, so it is
+     * screen stops being true, and this queue is watched precisely because its rows go out in public, so it is
      * the last place to leave someone reading a stale one. */
     { domain: "drafts", invalidates: [["drafts"]] },
 
-    /* WHAT A LANDED AGENT'S WORK IS CALLED — the commit message drafted from the diff the moment that work
+    /* WHAT A LANDED AGENT'S WORK IS CALLED, the commit message drafted from the diff the moment that work
      * reaches the main tree (agents/landed-subject.ts), which the review's "From" chip files into the commit box.
      *
      * It needs a push of its own because it arrives LATE, and alone. The review refreshes when a turn ends; the
      * sentence is a model call that STARTS there and answers seconds later, so the refresh the landing itself
      * causes is always too early to carry it. Nothing followed. The message then sat in the daemon, correct and
-     * unread, until some unrelated write happened to refresh the panel again — and a chip clicked in that window
+     * unread, until some unrelated write happened to refresh the panel again, and a chip clicked in that window
      * filed nothing at all, which is indistinguishable from the feature having been removed.
      *
      * Neither a file nor a ref, so this is the only feed that could carry it: the entry holding it lives on
@@ -91,23 +91,23 @@ const RUNTIME_DOMAINS = [
      * Being in this table also puts the review on the reconnect re-ask (runtimeBoundQueryKeys), and that is the
      * half of the fix nothing else covers: a publish with no browser connected is dropped, so a landing drafted
      * while the app was closed or the tunnel was down would otherwise stay invisible for as long as the panel's
-     * snapshot survived — which, at staleTime Infinity, is until something unrelated moved. It costs one review
+     * snapshot survived, which, at staleTime Infinity, is until something unrelated moved. It costs one review
      * read per (re)connect, against a chip that files nothing for the rest of the session. */
     { domain: "landings", invalidates: [["git", "changes"]] },
 ] as const satisfies readonly RuntimeDomainBinding[];
 
 export const RUNTIME_DOMAIN_BINDINGS: readonly RuntimeDomainBinding[] = RUNTIME_DOMAINS;
 
-/* Every domain this table declares, as a type — so a publish site names one of THESE and nothing else, and a
+/* Every domain this table declares, as a type, so a publish site names one of THESE and nothing else, and a
  * renamed domain is a compile error in the daemon rather than a frame the browser silently routes nowhere. */
 export type RuntimeDomain = (typeof RUNTIME_DOMAINS)[number]["domain"];
 
-/* Distinct key paths, in table order — two domains in one frame routinely feed the same view, and a Set cannot
+/* Distinct key paths, in table order, two domains in one frame routinely feed the same view, and a Set cannot
  * see that because each path is its own array. Compared by their segments joined, which is exact: a segment is
  * one identifier from this file, never a caller's string, so there is no separator to collide on. */
 const dedupe = (keys: readonly QueryKeyPath[]): readonly QueryKeyPath[] => [...new Map(keys.map((key) => [key.join(`/`), key])).values()];
 
-/* The query keys a pushed set of domains makes stale, deduped and stable — the browser's `/events` handler
+/* The query keys a pushed set of domains makes stale, deduped and stable, the browser's `/events` handler
  * calls this, exactly as it calls staleQueryKeys for a path batch. Kept here rather than in the web so the rule
  * is unit-testable without a query client, and so the daemon can assert against the same table.
  *
@@ -116,7 +116,7 @@ const dedupe = (keys: readonly QueryKeyPath[]): readonly QueryKeyPath[] => [...n
 export const staleRuntimeQueryKeys = (domains: readonly string[]): readonly QueryKeyPath[] =>
     dedupe(RUNTIME_DOMAIN_BINDINGS.filter((binding) => domains.includes(binding.domain)).flatMap((binding) => binding.invalidates));
 
-/* Every query key any runtime domain feeds — what a NEW /events connection re-asks wholesale, for precisely the
+/* Every query key any runtime domain feeds, what a NEW /events connection re-asks wholesale, for precisely the
  * reason fileBoundQueryKeys exists: this push is these views' ONLY live feed, and a frame produced while the
  * stream was down is a frame nobody will resend. A panel that finished starting, a session that exited, a port
  * that closed while the browser was away would otherwise sit wrong until the next unrelated change. Re-asking

package/src/schemas.test.ts

@@ -3,8 +3,8 @@ import { CapabilitiesListSchema, IpsecVpnConfigSchema, SandboxSettingsSchema } f
 
 /* The settings shape spans a version seam that really moves: the browser ships with the platform, the daemon
  * ships inside the user's sandbox image, so a web build routinely parses a payload from an OLDER daemon. These
- * tests pin the property that makes that survivable — an absent key is that flag's default, not a parse
- * failure — because failing instead reaches the user as a settings page whose switches silently do nothing. */
+ * tests pin the property that makes that survivable: an absent key is that flag's default, not a parse
+ * failure, because failing instead reaches the user as a settings page whose switches silently do nothing. */
 
 test("a payload from a build that predates a toggle parses, with the new toggle at its default", () => {
     // What a daemon built before the output-cleaner backend switch answers with: every key it knew, and
@@ -19,25 +19,25 @@ test("a payload from a build that predates a toggle parses, with the new toggle
         outputHoldout: 0.1,
     };
     // The defaults come from the schema, not from a copy of it written here. Transcribing them made every
-    // setting the product gained land as a failure in this file — a diff that only ever said "the list moved",
+    // setting the product gained land as a failure in this file: a diff that only ever said "the list moved",
     // never "tolerance broke", and whose fix was always to paste the new default in. What this test is about
     // is the seam: what the old build sent survives verbatim, and what it never heard of arrives at default.
     expect(SandboxSettingsSchema.parse(older)).toEqual({ ...SandboxSettingsSchema.parse({}), ...older });
 });
 
 /* The invariant a fresh sandbox depends on: NO field is required. A settings object is written for the first
- * time only when the user changes something, so until then the daemon parses `{}` — one field without a
+ * time only when the user changes something, so until then the daemon parses `{}`: one field without a
  * `.default()` turns that into a throw at boot, and the version tolerance above is built on the same property.
  *
  * Asserted by shape rather than by value: what each default IS belongs next to the field in schemas.ts, where
  * the reason it holds is written down. A second copy here proved nothing the schema didn't already say and
  * failed on every field the product added. */
-test("no field is required — a workspace that has never written settings parses", () => {
+test("no field is required: a workspace that has never written settings parses", () => {
     const defaults = SandboxSettingsSchema.parse({});
     expect(Object.keys(defaults).toSorted()).toEqual(Object.keys(SandboxSettingsSchema.shape).toSorted());
 });
 
-test("a key of the wrong type is still a parse failure — tolerance is for absence, not for garbage", () => {
+test("a key of the wrong type is still a parse failure: tolerance is for absence, not for garbage", () => {
     expect(SandboxSettingsSchema.safeParse({ iqSearch: "yes" }).success).toBe(false);
     expect(SandboxSettingsSchema.safeParse({ outputHoldout: 4 }).success).toBe(false);
     // The prompt cap is a real bound, not advice: the text IS the system prompt, and every turn pays for it.
@@ -46,7 +46,7 @@ test("a key of the wrong type is still a parse failure — tolerance is for abse
 
 /* The capability list crosses the same seam, and its failure mode is worse than a dead switch: the browser
  * parses ONE object for the whole page, so a required key the older daemon never sends takes the Capabilities
- * page down entirely — to hide an advisory badge. */
+ * page down entirely: to hide an advisory badge. */
 
 test("a capability list from a daemon that predates recommendations parses, with none recommended", () => {
     const older = { capabilities: [{ id: "github", kind: "cli", status: { state: "active" }, config: { provider: "github" } }] };
@@ -66,7 +66,7 @@ test("an ipsec tunnel is a full tunnel unless it says otherwise", () => {
 test("routed networks take a CIDR list and reject what charon could not load", () => {
     expect(IpsecVpnConfigSchema.parse({ ...ipsec, routedNetworks: "10.0.0.0/8, 192.168.0.0/16" }).routedNetworks).toBe("10.0.0.0/8, 192.168.0.0/16");
     expect(IpsecVpnConfigSchema.parse({ ...ipsec, routedNetworks: "fd00::/8" }).routedNetworks).toBe("fd00::/8");
-    // A bare host address is the easy mistake — strongSwan wants the prefix, and the message says so.
+    // A bare host address is the easy mistake: strongSwan wants the prefix, and the message says so.
     expect(IpsecVpnConfigSchema.safeParse({ ...ipsec, routedNetworks: "192.168.0.168" }).success).toBe(false);
     expect(IpsecVpnConfigSchema.safeParse({ ...ipsec, routedNetworks: "10.0.0.0/8,nonsense" }).success).toBe(false);
     expect(IpsecVpnConfigSchema.safeParse({ ...ipsec, routedNetworks: "" }).success).toBe(false);