@intentic/sandbox-contract 1.306.0 → 1.308.0

package/src/protocol/route-meta.ts

@@ -0,0 +1,39 @@
+import { oc } from "@orpc/contract";
+import type { MemberRole } from "../schemas/shared.js";
+
+// Every route's policy, declared beside it: how a request authenticates, which member tier and which machine
+// credentials reach it, and how the daemon's outer middleware treats it. Each field has a default, so most routes
+// declare nothing; the daemon's bearer, boot, timer, role-floor and grant decisions all derive from this.
+
+// How far a control token reaches a route beyond what its floor alone gives the `read`/`drive` rungs.
+// `never`: no rung; `editor`: the editor slice too; `read`: the read rung, though no GET; `land`: the land rung too.
+export type ControlReach = "never" | "editor" | "read" | "land";
+
+export interface RouteMeta {
+    // `door`: the session middleware lets it through, and the handler checks its own credential or none.
+    readonly auth?: "session" | "door";
+    // Loaded by third-party pages: CORS reflects the caller's origin, and the route's own allowlist is the gate.
+    readonly embedded?: true;
+    // Answers while the boot chain is still converging; everything else waits for it.
+    readonly beforeBoot?: true;
+    // Held open by design, so the request timer leaves it out.
+    readonly stream?: true;
+    // The lowest member role that may call it. Absent: viewer for a read (GET, HEAD), maintainer for anything else.
+    readonly floor?: MemberRole;
+    // On a guest member's allowlist, which is the whole of what a guest reaches.
+    readonly guest?: true;
+    // The floor an upload aimed inside ATTACHMENTS_DIR gets instead, one a guest may also make.
+    readonly attachmentFloor?: MemberRole;
+    // A passkey-registration door: a proof with no passkey yet may pass the require-passkey policy.
+    readonly enrolment?: true;
+    // The agent token, which the CLIs on the agent's PATH carry, reaches it.
+    readonly agent?: true;
+    // The desktop-sync token reaches it; a `poll` refreshes the machine's heartbeat, the held-open `pipe` does not.
+    readonly sync?: "poll" | "pipe";
+    // Withheld from the panel token, which reaches every other route: it puts a stored credential in motion.
+    readonly panel?: false;
+    readonly control?: ControlReach;
+}
+
+// The builder every sandbox procedure starts from, so each carries a RouteMeta and whatever it leaves out defaults.
+export const procedure = oc.$meta<RouteMeta>({});

package/src/protocol/routes.test.ts

@@ -2,7 +2,8 @@ import { eventIterator, oc } from "@orpc/contract";
 import { describe, it, expect } from "bun:test";
 import { z } from "zod";
 import { SANDBOX_ROUTE_NAMES, SANDBOX_ROUTE_SHAPES, SANDBOX_ROUTES, sandboxRouteName } from "../index.js";
-import { contractRoutes, routeNameForRequest, routeShapes, streamOf } from "./routes.js";
+import { procedure } from "./route-meta.js";
+import { contractRoutes, routeNameForRequest, routeShapes, servedRoute, streamOf } from "./routes.js";
 
 const fixture = {
     vpn: {
@@ -27,9 +28,16 @@ describe(`contractRoutes`, () => {
             name: `vpn.connect`,
             method: `POST`,
             path: `/vpn/{id}/connect`,
+            meta: {},
         });
     });
 
+    it(`carries the policy a procedure declared, merged over its builder's`, () => {
+        const operated = procedure.meta({ agent: true, control: `never` });
+        const routes = contractRoutes({ vpn: { connect: operated.route({ method: "POST", path: "/vpn/{id}/connect" }).meta({ floor: `collaborator` }) } });
+        expect(routes).toEqual([{ name: `vpn.connect`, method: `POST`, path: `/vpn/{id}/connect`, meta: { agent: true, control: `never`, floor: `collaborator` } }]);
+    });
+
     it(`ignores non-procedure members rather than inventing routes for them`, () => {
         expect(contractRoutes({ vpn: { list: fixture.vpn.list, NOT_A_ROUTE: { hello: true } } }).map((r) => r.name)).toEqual([`vpn.list`]);
     });
@@ -72,15 +80,70 @@ describe(`routeNameForRequest`, () => {
         expect(routeNameForRequest(routes, `POST`, `/vpn/connect`)).toBeUndefined();
     });
 
-    it(`does not let an empty segment stand in for a param`, () => {
+    it(`reads a trailing slash as the end of the path, never as an empty param`, () => {
         expect(routeNameForRequest(routes, `DELETE`, `/system/terminals/`)).toBeUndefined();
     });
 
+    // What oRPC's router (rou3) dispatches: a spelling it serves must resolve to the route it serves, or a policy
+    // keyed on the route would not hold at that spelling.
+    it(`reads the path as oRPC's router does: two trailing slashes dropped, an empty inner segment still a param`, () => {
+        expect(routeNameForRequest(routes, `GET`, `/vpn/`)).toBe(`vpn.list`);
+        expect(routeNameForRequest(routes, `GET`, `/vpn//`)).toBe(`vpn.list`);
+        expect(routeNameForRequest(routes, `GET`, `/vpn///`)).toBeUndefined();
+        expect(routeNameForRequest(routes, `POST`, `/vpn//connect`)).toBe(`vpn.connect`);
+        expect(routeNameForRequest(routes, `POST`, `/vpn/corp-gw/connect/`)).toBe(`vpn.connect`);
+        expect(routeNameForRequest(routes, `GET`, `//vpn`)).toBeUndefined();
+    });
+
     it(`returns undefined for the daemon's hand-written non-contract routes`, () => {
         expect(routeNameForRequest(routes, `GET`, `/health`)).toBeUndefined();
     });
 });
 
+describe(`servedRoute`, () => {
+    const contract = contractRoutes(fixture);
+    const raw = [
+        { name: `GET /health`, method: `GET`, path: `/health`, meta: { auth: `door` as const } },
+        { name: `POST /vpn/{id}/connect`, method: `POST`, path: `/vpn/{id}/connect`, meta: { auth: `door` as const } },
+        { name: `DELETE /vpn/{id}/connect`, method: `DELETE`, path: `/vpn/{id}/connect`, meta: {} },
+        { name: `ALL /x/*`, method: `ALL`, path: `/x/*`, meta: {} },
+    ];
+    const served = (method: string, path: string) => servedRoute(raw, contract, method, path)?.name;
+
+    it(`answers with a raw route before the contract, as the daemon registers them ahead of oRPC's catch-all`, () => {
+        expect(served(`POST`, `/vpn/corp-gw/connect`)).toBe(`POST /vpn/{id}/connect`);
+        expect(served(`GET`, `/vpn`)).toBe(`vpn.list`);
+    });
+
+    // Hono is strict where oRPC is not, so a raw route's variant spelling falls through to the contract.
+    it(`matches a raw route exactly: no trailing slash, no empty param`, () => {
+        expect(served(`POST`, `/vpn/corp-gw/connect/`)).toBe(`vpn.connect`);
+        expect(served(`POST`, `/vpn//connect`)).toBe(`vpn.connect`);
+        expect(served(`GET`, `/health/`)).toBeUndefined();
+    });
+
+    it(`answers HEAD with a raw GET route and every method with an ALL one, in registration order`, () => {
+        expect(served(`HEAD`, `/health`)).toBe(`GET /health`);
+        expect(served(`HEAD`, `/vpn`)).toBeUndefined();
+        expect(served(`PATCH`, `/x/a/b`)).toBe(`ALL /x/*`);
+        expect(served(`DELETE`, `/vpn/corp-gw/connect`)).toBe(`DELETE /vpn/{id}/connect`);
+    });
+
+    // The CORS middleware answers a preflight for whatever sits at the path, before any route runs.
+    it(`resolves a preflight to the most literal route at its path, whatever method that route serves`, () => {
+        expect(served(`OPTIONS`, `/vpn/corp-gw/connect`)).toBe(`POST /vpn/{id}/connect`);
+        expect(served(`OPTIONS`, `/vpn`)).toBe(`vpn.list`);
+        expect(served(`OPTIONS`, `/no/such/route`)).toBeUndefined();
+    });
+
+    it(`gives a trailing /* the segments after the prefix, never the bare prefix`, () => {
+        expect(served(`GET`, `/x/`)).toBe(`ALL /x/*`);
+        expect(served(`GET`, `/x/a`)).toBe(`ALL /x/*`);
+        expect(served(`GET`, `/x`)).toBeUndefined();
+        expect(served(`GET`, `/xy/a`)).toBeUndefined();
+    });
+});
+
 describe(`routeShapes`, () => {
     it(`gives the same fingerprint for the same shape, twice`, () => {
         expect(routeShapes(shaped(z.object({ a: z.string() })))).toEqual(routeShapes(shaped(z.object({ a: z.string() }))));

package/src/protocol/routes.ts

@@ -1,5 +1,6 @@
 import { eventIterator } from "@orpc/contract";
 import { z } from "zod";
+import type { RouteMeta } from "./route-meta.js";
 
 // Named route surface of the daemon's contract (`<group>.<route>`), derived automatically so nothing here is
 // hand-maintained. The daemon advertises which routes it implements (the /events hello frame); the browser diffs that
@@ -18,29 +19,30 @@ export const streamOf = <T extends z.ZodType>(frame: T) => Object.assign(eventIt
 const frameOf = (schema: unknown): z.ZodType | undefined =>
     typeof schema === "object" && schema !== null && FRAME in schema ? ((schema as Record<symbol, unknown>)[FRAME] as z.ZodType) : undefined;
 
-// Structural shape of `~orpc.route`, the metadata oRPC attaches to every `oc.route(...)` procedure; read this way since
-// oRPC's internal types aren't public.
+// Structural shape of `~orpc`, what oRPC attaches to every procedure: its route, and the RouteMeta its builder carried
+// (route-meta.ts). Read this way since oRPC's internal types aren't public.
 interface ContractProcedureLike {
-    readonly "~orpc": { readonly route?: { readonly method?: string; readonly path?: string } };
+    readonly "~orpc": { readonly route?: { readonly method?: string; readonly path?: string }; readonly meta?: RouteMeta };
 }
 
-const procedureRoute = (value: unknown): { method: string; path: string } | undefined => {
+const procedureRoute = (value: unknown): Omit<ContractRoute, "name"> | undefined => {
     if (typeof value !== "object" || value === null || !("~orpc" in value)) {
         return undefined;
     }
-    const { route } = (value as ContractProcedureLike)["~orpc"];
+    const { route, meta } = (value as ContractProcedureLike)["~orpc"];
     if (route?.method === undefined || route.path === undefined) {
         return undefined;
     }
-    return { method: route.method, path: route.path };
+    return { method: route.method, path: route.path, meta: meta ?? {} };
 };
 
-// One advertised route: contract name plus wire shape, matched back to a concrete request path by routeNameForRequest.
+// One declared route: its name and wire shape, matched back to a concrete request by servedRoute, and its policy.
 export interface ContractRoute {
     readonly name: string;
     readonly method: string;
-    // oRPC path template with `{param}` placeholders, e.g. `/system/terminals/{name}`.
+    // Path template with `{param}` placeholders, e.g. `/system/terminals/{name}`; a raw route's may end in `/*`.
     readonly path: string;
+    readonly meta: RouteMeta;
 }
 
 // Walks a contract object (group → procedure) into a flat route list, sorted by name for a stable diff.
@@ -53,7 +55,7 @@ export const contractRoutes = (contract: Record<string, unknown>): ContractRoute
         for (const [name, procedure] of Object.entries(procedures as Record<string, unknown>)) {
             const route = procedureRoute(procedure);
             if (route !== undefined) {
-                routes.push({ name: `${group}.${name}`, method: route.method, path: route.path });
+                routes.push({ name: `${group}.${name}`, ...route });
             }
         }
     }
@@ -143,30 +145,89 @@ export const routeShapes = (contract: Record<string, unknown>): Record<string, s
     return shapes;
 };
 
-// Matches a concrete path against a route template segment-wise; `{param}` matches exactly one segment, so length must
-// match too.
-const pathMatches = (template: string, path: string): boolean => {
-    const wanted = template.split("/");
-    const actual = path.split("/");
-    if (wanted.length !== actual.length) {
+// A template split once: a literal segment, or undefined for a `{param}`; `tail` for a raw route's trailing `/*`.
+interface Pattern {
+    readonly route: ContractRoute;
+    readonly segments: readonly (string | undefined)[];
+    readonly tail: boolean;
+}
+
+const compiled = new WeakMap<readonly ContractRoute[], readonly Pattern[]>();
+
+const patternsOf = (routes: readonly ContractRoute[]): readonly Pattern[] => {
+    const known = compiled.get(routes);
+    if (known !== undefined) {
+        return known;
+    }
+    const patterns = routes.map((route) => {
+        const parts = route.path.split("/").slice(1);
+        const tail = parts.at(-1) === "*";
+        const segments = (tail ? parts.slice(0, -1) : parts).map((part) => (part.startsWith("{") && part.endsWith("}") ? undefined : part));
+        return { route, segments, tail };
+    });
+    compiled.set(routes, patterns);
+    return patterns;
+};
+
+// Whether a template takes a request's segments. Hono (`raw`) gives a `{param}` only a non-empty segment and a `/*` one
+// or more further ones; oRPC's router gives a `{param}` any segment, the empty one included.
+const takes = (pattern: Pattern, segments: readonly string[], raw: boolean): boolean => {
+    const { segments: wanted, tail } = pattern;
+    if (tail ? segments.length <= wanted.length : segments.length !== wanted.length) {
         return false;
     }
-    return wanted.every((segment, index) => (segment.startsWith("{") && segment.endsWith("}") ? actual[index] !== "" : segment === actual[index]));
+    return wanted.every((segment, index) => (segment === undefined ? !raw || segments[index] !== "" : segment === segments[index]));
+};
+
+// oRPC's router tries a literal segment before a parameter, left to right: `/agents/search` is the search route, not
+// `get` with an id of "search", whichever of the two the list happens to hold first.
+const moreLiteral = (a: Pattern, b: Pattern): boolean => {
+    const at = a.segments.findIndex((segment, index) => (segment === undefined) !== (b.segments[index] === undefined));
+    return at >= 0 && a.segments[at] !== undefined;
 };
 
-// The contract route a request belongs to, or undefined for a hand-written daemon route (/health, /workspace/raw) never
-// gated by the contract. Query string stripped first.
-// How many segments a template leaves open; the tie-breaker below prefers the template that leaves fewest.
-const paramCount = (template: string): number => template.split("/").filter((segment) => segment.startsWith("{") && segment.endsWith("}")).length;
+const mostLiteral = (patterns: readonly Pattern[]): Pattern | undefined =>
+    patterns.reduce<Pattern | undefined>((best, pattern) => (best === undefined || moreLiteral(pattern, best) ? pattern : best), undefined);
+
+// Whether a route declared for one method answers a request's. The CORS middleware answers a preflight (OPTIONS) for
+// every route at its path; Hono (`raw`) answers every method with an `ALL` route and HEAD with a GET one.
+const answers = (declared: string, method: string, raw: boolean): boolean =>
+    method === "OPTIONS" || declared === method || (raw && (declared === "ALL" || (declared === "GET" && method === "HEAD")));
+
+// A request path as oRPC's router reads it: one trailing slash dropped, then one trailing empty segment, so `/a/` and
+// `/a//` are `/a` while `/a///` is not.
+const orpcSegments = (path: string): string[] => {
+    const segments = (path.endsWith("/") ? path.slice(0, -1) : path).split("/").slice(1);
+    return segments.at(-1) === "" ? segments.slice(0, -1) : segments;
+};
+
+const contractRouteFor = (routes: readonly ContractRoute[], method: string, path: string): ContractRoute | undefined => {
+    const segments = orpcSegments(path);
+    return mostLiteral(patternsOf(routes).filter((pattern) => answers(pattern.route.method.toUpperCase(), method, false) && takes(pattern, segments, false)))
+        ?.route;
+};
+
+// Hono matches the path exactly, and among overlapping routes the first registered answers; a preflight belongs to none
+// of them, so the most literal names it.
+const rawRouteFor = (routes: readonly ContractRoute[], method: string, path: string): ContractRoute | undefined => {
+    const segments = path.split("/").slice(1);
+    const matching = patternsOf(routes).filter((pattern) => answers(pattern.route.method, method, true) && takes(pattern, segments, true));
+    return (method === "OPTIONS" ? mostLiteral(matching) : matching[0])?.route;
+};
+
+const pathOf = (pathWithQuery: string): string => pathWithQuery.split("?")[0] ?? pathWithQuery;
+
+// The contract route a request belongs to, read as oRPC's router reads it, or undefined for a hand-written daemon route
+// (/health, /workspace/raw) the contract never declared. Query string stripped first.
+export const routeNameForRequest = (routes: readonly ContractRoute[], method: string, pathWithQuery: string): string | undefined =>
+    contractRouteFor(routes, method.toUpperCase(), pathOf(pathWithQuery))?.name;
 
-export const routeNameForRequest = (routes: readonly ContractRoute[], method: string, pathWithQuery: string): string | undefined => {
-    const path = pathWithQuery.split("?")[0] ?? pathWithQuery;
+// The route that serves a request to the daemon: a raw route as Hono matches it, since those are registered ahead of
+// oRPC's catch-all, else a contract route as oRPC's router does; undefined when neither serves it.
+export const servedRoute = (raw: readonly ContractRoute[], contract: readonly ContractRoute[], method: string, pathWithQuery: string): ContractRoute | undefined => {
     const upper = method.toUpperCase();
-    // A literal segment outranks a parameter: `/agents/search` is the search route, not `get` with an id of "search",
-    // whichever of the two the sorted list happens to hold first.
-    return routes
-        .filter((route) => route.method.toUpperCase() === upper && pathMatches(route.path, path))
-        .toSorted((a, b) => paramCount(a.path) - paramCount(b.path))[0]?.name;
+    const path = pathOf(pathWithQuery);
+    return rawRouteFor(raw, upper, path) ?? contractRouteFor(contract, upper, path);
 };
 
 // The route a typed client call belongs to; oRPC addresses a procedure by contract position (`['git','stashApply']`),

package/src/schemas/agent.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import { AgentTurnSchema, profileOf, TurnProfileSchema } from "./agent.js";
+
+// The profile is what every continuation carries whole, so its field set and its normalisation are the contract: a key
+// dropped here is a knob every resume, wake and nudge silently resets.
+describe("TurnProfile", () => {
+    test("names exactly the fields that say which turn this is", () => {
+        expect(Object.keys(TurnProfileSchema.shape).toSorted()).toEqual([
+            "account",
+            "actsAs",
+            "agent",
+            "effort",
+            "fast",
+            "harness",
+            "isolated",
+            "model",
+            "runRole",
+            "thinking",
+            "unattended",
+        ]);
+    });
+
+    test("takes every stated field off a turn, and nothing it says or where it goes", () => {
+        const turn = AgentTurnSchema.parse({
+            prompt: "Fix the login bug",
+            conversationId: "c-1",
+            sessionId: "s-1",
+            agent: "codex",
+            harness: "claude-code",
+            account: "acct-2",
+            model: "gpt-5",
+            effort: "high",
+            thinking: false,
+            fast: true,
+            actsAs: "support",
+            isolated: true,
+            unattended: true,
+            runRole: "loop-iteration",
+            permissionMode: "plan",
+            autoLand: false,
+        });
+        expect(profileOf(turn)).toStrictEqual({
+            agent: "codex",
+            harness: "claude-code",
+            account: "acct-2",
+            model: "gpt-5",
+            effort: "high",
+            thinking: false,
+            fast: true,
+            actsAs: "support",
+            isolated: true,
+            unattended: true,
+            runRole: "loop-iteration",
+        });
+    });
+
+    test("leaves absent fields absent rather than naming them undefined", () => {
+        expect(profileOf({ model: "sonnet", effort: undefined })).toStrictEqual({ model: "sonnet" });
+        expect(Object.keys(profileOf({}))).toEqual([]);
+    });
+
+    // `thinking: false` is a choice the next turn must keep; `isolated: false` only restates the default.
+    test("carries a false knob but not a false placement or audience", () => {
+        expect(profileOf({ thinking: false, fast: false, isolated: false, unattended: false })).toStrictEqual({ thinking: false, fast: false });
+    });
+});