@intentic/sandbox-contract 1.325.0 → 1.327.0

package/src/contracts/secrets.contract.ts

@@ -4,6 +4,8 @@ import {
     CredentialGuardSubjectParamSchema,
     CredentialGatesSchema,
     CredentialGrantSchema,
+    CredentialPolicySchema,
+    CredentialPolicySetSchema,
     CredentialRequestSchema,
     SecretInventorySchema,
     SecretKeyParamSchema,
@@ -141,6 +143,29 @@ export const secretsContract = {
         .meta({ agent: true })
         .input(SecretHostGuardSetSchema)
         .output(SecretHostGuardSetResultSchema),
+    // The credential gateway's say over one connection: how its credential reaches the agent, and what it may do there.
+    policy: secretRoute
+        .route({
+            method: "GET",
+            path: "/secrets/policy/{subject}",
+            summary: "How a connection's credential reaches the agent, and what it may do",
+            description:
+                "Whether the credential gateway holds this connection's credential or the agent is handed it, and the method and path rules the gateway enforces on every request it attaches it to. Names and rules only, never values.",
+        })
+        // The `secrets policy` CLI's read, on the agent token: knowing the rules lets a turn plan around them.
+        .meta({ agent: true })
+        .input(CredentialGuardSubjectParamSchema)
+        .output(CredentialPolicySchema),
+    setPolicy: secretRoute
+        .route({
+            method: "PUT",
+            path: "/secrets/policy/{subject}",
+            summary: "Set how a connection's credential reaches the agent, and its rules",
+            description:
+                "The owner's alone, and never the agent's: handing the agent the credential itself, or replacing what the gateway lets it do, is a decision about the credential, not a use of it.",
+        })
+        .input(CredentialPolicySetSchema)
+        .output(CredentialPolicySchema),
     request: secretRoute
         .route({
             method: "POST",

package/src/contracts/settings.contract.ts

@@ -1,6 +1,7 @@
 import { FIELD_NOTES_FILE } from "@intentic/constants";
 import { procedure } from "../protocol/route-meta.js";
 import {
+    AgentDomainPolicySchema,
     AudienceAnswerSchema,
     AudienceStateSchema,
     BuiltinPromptSchema,
@@ -24,6 +25,15 @@ import { DayWindowQuerySchema } from "../schemas/providers/usage.js";
 // overwrites whole. `savings` measures each token-reduction mechanism's worth over the same UTC day window the spend
 // ledger takes. `builtinPrompt` returns a built-in prompt's actual text to show or fork.
 export const settingsContract = {
+    agentDomain: procedure
+        .route({ method: "GET", path: "/settings/agent-domain", summary: "Read the agent execution domain" })
+        .meta({ panel: false, control: "never" })
+        .output(AgentDomainPolicySchema),
+    setAgentDomain: procedure
+        .route({ method: "POST", path: "/settings/agent-domain", summary: "Choose the agent execution domain" })
+        .meta({ floor: "owner", panel: false, control: "never" })
+        .input(AgentDomainPolicySchema)
+        .output(OkSchema),
     get: procedure
         .route({
             method: "GET",

package/src/contracts/system.contract.ts

@@ -18,6 +18,9 @@ import { AutoUpdateInputSchema, AutoUpdateSchema, SkipUpdateInputSchema } from "
 import {
     BrowserNameParamSchema,
     BrowsersListSchema,
+    OpenBrowserInputSchema,
+    OpenBrowserResultSchema,
+    DesktopStateSchema,
     SubagentsListSchema,
     TerminalNameParamSchema,
     TerminalScrollbackQuerySchema,
@@ -229,6 +232,17 @@ export const systemContract = {
                 "Every browser a conversation currently has running and the pages inside each one. The picture of what they are showing comes over a separate socket; this is the roster.",
         })
         .output(BrowsersListSchema),
+    // The person's own window: started on the first call, given a new tab on every later one, never an agent's.
+    openBrowser: systemRoute
+        .route({
+            method: "POST",
+            path: "/system/browsers",
+            summary: "Open a tab in your own browser",
+            description:
+                "Opens a tab in your own browser window, starting the window first when it is not running. It is a Chromium of its own, with a profile that keeps your sign-ins between windows, and no agent drives it. Answers once the window can be watched.",
+        })
+        .input(OpenBrowserInputSchema)
+        .output(OpenBrowserResultSchema),
     closeBrowser: systemRoute
         .route({
             method: "DELETE",
@@ -239,6 +253,18 @@ export const systemContract = {
         })
         .input(BrowserNameParamSchema)
         .output(OkSchema),
+    // The picture and the hands come over /system/desktop-view; this is whether there is anything on it, and which windows
+    // a tab could show alone. Pushed through the `desktop` runtime domain as windows open, close and take the keyboard,
+    // and as their titles change while a view is open; never polled by the client.
+    desktop: systemRoute
+        .route({
+            method: "GET",
+            path: "/system/desktop",
+            summary: "The sandbox's own desktop",
+            description:
+                "Whether the sandbox's desktop is up, which display it is, and which windows are open on it. The live picture of it, or of one window on it, comes over a separate socket; this says whether there is anything to see.",
+        })
+        .output(DesktopStateSchema),
     // In-process and spawned alike: the board draws each under the card of the conversation that started it, and a chat
     // draws it on the card of the call that started it. Pushed through the `subagents` runtime domain, never polled. A
     // subagent's work is read where it lives: an in-process one's on its delegation's card in its parent's record, a

package/src/documents/conversions.ts

@@ -1,3 +1,5 @@
+import { errorMessage } from "@intentic/base/errors";
+
 // A stored document's history as data: each conversion is a guarded, pure rewrite of the raw JSON a store reads, run
 // before the schema on every read. The guard makes a conversion a no-op on a document already past it, so running the
 // whole list over a document from any era converges on today's shape without the document carrying a version, and
@@ -355,7 +357,7 @@ export class ConversionError extends Error {
     readonly conversion: string;
 
     constructor(conversion: string, cause: unknown) {
-        super(`conversion "${conversion}" failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        super(`conversion "${conversion}" failed: ${errorMessage(cause)}`, { cause });
         this.name = "ConversionError";
         this.conversion = conversion;
     }

package/src/documents/read.ts

@@ -1,3 +1,4 @@
+import { errorMessage } from "@intentic/base/errors";
 import type { ManifestProblem } from "../schemas/system.js";
 import { type Conversion, convertDocument, type Granularity } from "./conversions.js";
 import { carryUnknown, type IdKeys, reemitQuarantined } from "./passthrough.js";
@@ -35,8 +36,6 @@ export interface DocumentRead<T> {
     readonly problems: readonly ManifestProblem[];
 }
 
-const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
-
 const unreadable = <T>(reason: NonNullable<ManifestProblem["reason"]>, detail: string): DocumentRead<T> => ({
     value: undefined,
     carry: (updated) => updated,
@@ -67,7 +66,7 @@ export const readDocument = <T>(text: string, shape: DocumentShape, how: Documen
                 const converted = convertDocument(shape.history, shape.granularity, raw, checkSettles).value;
                 whole = Array.isArray(converted) ? converted : [];
             } catch (error) {
-                return unreadable("conversion-failed", `a conversion to this build's shape failed (${message(error)})`);
+                return unreadable("conversion-failed", `a conversion to this build's shape failed (${errorMessage(error)})`);
             }
         }
         whole.forEach((written, index) => {
@@ -80,7 +79,7 @@ export const readDocument = <T>(text: string, shape: DocumentShape, how: Documen
                 report({
                     kind: "invalidEntry",
                     reason: "conversion-failed",
-                    detail: `entry ${index} could not be converted to this build's shape (${message(error)}); it is kept as written`,
+                    detail: `entry ${index} could not be converted to this build's shape (${errorMessage(error)}); it is kept as written`,
                 });
                 return;
             }
@@ -104,7 +103,7 @@ export const readDocument = <T>(text: string, shape: DocumentShape, how: Documen
     try {
         raw = convertDocument(shape.history, shape.granularity, raw, checkSettles).value;
     } catch (error) {
-        return unreadable("conversion-failed", `a conversion to this build's shape failed (${message(error)})`);
+        return unreadable("conversion-failed", `a conversion to this build's shape failed (${errorMessage(error)})`);
     }
     const value = how.parse(raw, report);
     if (value === undefined) {

package/src/events/agent-events.ts

@@ -10,7 +10,7 @@ import { PromptCacheOpeningSchema, PromptFingerprintSchema } from "../schemas/ke
 import { AgentReplySchema, UsageWindowSchema } from "../schemas/providers/plan-limits.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "../schemas/terminal.js";
 import { RetryLadderSchema } from "../schemas/turn-break.js";
-import { AgentCommandSchema, browserHelpRequest, capabilityOfferRequest, CapabilityOutcomeSchema, ContextUsageSchema, credentialOfferRequest, CredentialReceiptSchema, paymentOfferRequest, PaymentReceiptSchema, PermissionRequestSchema, PlanRequestSchema, QuestionRequestSchema, terminalHelpRequest, TodoItemSchema, ToolCallContentSchema, ToolCallLocationSchema, ToolCallStatusSchema, ToolKindSchema } from "./requests.js";
+import { AgentCommandSchema, browserHelpRequest, capabilityOfferRequest, CapabilityOutcomeSchema, ContextUsageSchema, credentialOfferRequest, CredentialReceiptSchema, pageAskRequest, PageSchema, paymentOfferRequest, PaymentReceiptSchema, PermissionRequestSchema, PlanRequestSchema, QuestionRequestSchema, terminalHelpRequest, TodoItemSchema, ToolCallContentSchema, ToolCallLocationSchema, ToolCallStatusSchema, ToolKindSchema } from "./requests.js";
 import { TranscriptPatchSchema, TranscriptRowSchema, TurnNoteSchema } from "./transcript.js";
 import { agentNoticeEvent, agentStatusEvent } from "./agent-ui.js";
 
@@ -229,6 +229,23 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // Something the agent asked a person for (docs/architecture/needs.md). Parks nothing: the turn carries on, the need
     // outlives it in the needs store, and its card draws the store's live state by `need.id`.
     z.object({ kind: z.literal("need"), need: NeedSchema }),
+    // A page the agent showed (its `show_page` tool): drawn inline where the turn stands, in a sealed frame. Parks
+    // nothing. A page whose id an earlier one already holds is a redraw, and the earlier row folds to a line.
+    z.object({ kind: z.literal("page"), page: PageSchema }),
+    // A page the agent showed to be answered (`ask_page`): parks the turn until the page sends its answer back, or the
+    // person dismisses it. Not journalled for restore: the tool call waiting on it dies with the daemon.
+    z.object({ kind: z.literal("page_ask"), ...pageAskRequest }),
+    // A page as the model is still writing it, for the chat to draw as it arrives: `text` is what came at `at` in the
+    // page's markup, so a window that missed nothing appends and one joining late replays them in order. Live state, not
+    // transcript: `done` ends it (the page itself, or the call's failure, takes over), and every draft goes with the turn.
+    z.object({
+        kind: z.literal("page_draft"),
+        callId: z.string().describe("The tool call writing it."),
+        at: z.number().int().nonnegative().describe("Where in the page's markup this text starts."),
+        text: z.string().describe("The next stretch of the page's markup."),
+        title: z.string().optional().describe("The page's title, once the call has written it."),
+        done: z.boolean().optional().describe("The draft is over: the page is published, or the call failed."),
+    }),
     // The named card is released and the turn resumes; emitted the moment its waiter settles, since nothing else on
     // this stream marks a park's end. `reply` is what a rebuilt transcript freezes the card with.
     z.object({ kind: z.literal("resolved"), requestId: z.string(), reply: AgentReplySchema.optional() }),
@@ -276,9 +293,15 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 // The model can only write one-shot jobs (Model.helperOnly: its server says it cannot call tools, or
                 // it is the quick-jobs local model), refused before sending; the words wait for another model.
                 "model-helper-only",
-                // The privacy shield is on, the provider is untrusted, and the runtime is one its gateway cannot stand in
-                // front of (Cursor, an ACP agent, Pi), refused before sending; the words wait for a covered provider.
+                // The privacy shield is on, the provider is untrusted, and the runtime is one it cannot read by content at
+                // all (an ACP agent, Pi), refused before sending; the words wait for a covered provider.
                 "privacy-unshielded",
+                // The protected execution-domain policy is unsupported or unreadable; refused before any model/helper ran.
+                "agent-domain-refused",
+                // The privacy shield found personal data in instructions the runtime loads itself, past every channel it
+                // could mask (Cursor's project rules, AGENTS.md), refused before sending; the words wait for the owner to
+                // let the provider read this conversation, trust it, or take the data out of those files.
+                "privacy-instructions",
                 // The session outgrew the model's context window mid-turn; resuming that session only overflows again,
                 // so the daemon re-runs the turn once in a fresh session carrying the hand-off.
                 "context-overflow",
@@ -379,6 +402,7 @@ export const TURN_FACT_KINDS = [
     "context_usage",
     "mode",
     "agent_status",
+    "page_draft",
     "error",
 ] as const;
 export type TurnFact = Extract<AgentEvent, { kind: (typeof TURN_FACT_KINDS)[number] }>;

package/src/events/requests.ts

@@ -266,6 +266,48 @@ export const RequestDocumentSchema = z.object({
 });
 export type RequestDocument = z.infer<typeof RequestDocumentSchema>;
 
+// A page the agent showed in the chat (its `show_page`/`ask_page` tools): a self-contained HTML document the daemon
+// stored under the workspace's records, drawn inline in a sealed frame. The row carries where it lives, not its bytes,
+// so a long chat full of charts stays a light record; the file is the page as it was shown, never rewritten after.
+export const PAGE_MIN_HEIGHT = 80;
+export const PAGE_MAX_HEIGHT = 2000;
+export const PAGE_TITLE_MAX = 200;
+export const PageSchema = z.object({
+    id: z.string().min(1).describe("The page's own id, which a later `replaces` names to redraw it in place."),
+    title: z.string().max(PAGE_TITLE_MAX).describe("What it is, in a few words."),
+    path: z.string().min(1).describe("Where the page is stored, as a workspace path."),
+    height: z
+        .number()
+        .int()
+        .min(PAGE_MIN_HEIGHT)
+        .max(PAGE_MAX_HEIGHT)
+        .optional()
+        .describe("The tallest the agent wants its frame, in pixels; the page scrolls inside it beyond that. Absent, the frame fits the page."),
+    measured: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("The page's height at the chat's column width, as the sandbox's own browser laid it out, so its room is held before it loads."),
+    source: z.string().optional().describe("The workspace file the page was built from, when the agent showed a file rather than writing the page inline."),
+    revision: z.number().int().nonnegative().optional().describe("How many times the agent redrew this page; each redraw is a new file at a new path."),
+    superseded: z
+        .boolean()
+        .optional()
+        .describe("A later redraw of this page stands further down the conversation, so this one is drawn folded to a line."),
+    app: z
+        .object({
+            server: z.string().min(1).describe("The connected MCP server whose app it is, by its capability id."),
+            tool: z.string().min(1).describe("The tool whose call the app shows."),
+        })
+        .optional()
+        .describe("Present when the page is an MCP server's own app (an MCP Apps `ui://` resource), shown for one of its tool calls."),
+});
+export type Page = z.infer<typeof PageSchema>;
+
+// What a page sent back is capped at: an answer, not a document.
+export const PAGE_VALUE_MAX = 64_000;
+
 // One request's fields, spelled once: the raising frame, the parked-card journal entry, and the transcript row all share
 // this shape rather than declaring it three times.
 const REQUEST_ID = z.string().describe("What to send back when you answer.");
@@ -296,6 +338,11 @@ export const terminalHelpRequest = {
     session: z.string(),
     message: z.string(),
 };
+// A page the agent showed to be answered (`ask_page`): the turn waits until the page sends its answer back.
+export const pageAskRequest = {
+    requestId: REQUEST_ID,
+    page: PageSchema.describe("The page to answer on."),
+};
 export const capabilityOfferRequest = { requestId: z.string(), offer: CapabilityOfferSchema };
 export const paymentOfferRequest = { requestId: z.string(), offer: PaymentOfferSchema };
 export const credentialOfferRequest = { requestId: z.string(), offer: CredentialOfferSchema };

package/src/events/transcript.ts

@@ -14,6 +14,8 @@ import {
     CapabilityOutcomeSchema,
     credentialOfferRequest,
     CredentialReceiptSchema,
+    pageAskRequest,
+    PageSchema,
     paymentOfferRequest,
     PaymentReceiptSchema,
     PermissionAskSchema,
@@ -92,6 +94,14 @@ export const TranscriptCredentialOfferSchema = z.object({
     receipt: CredentialReceiptSchema.optional().describe("Who released it, or that somebody refused (the credential_receipt frame)."),
 });
 export type TranscriptCredentialOffer = z.infer<typeof TranscriptCredentialOfferSchema>;
+// A page asked to be answered, and what it sent back: the value as the page gave it, JSON text, which is also exactly
+// what the agent was handed.
+export const TranscriptPageAskSchema = z.object({
+    ...pageAskRequest,
+    status: QuestionStatusSchema.describe("Where the answer stands."),
+    value: z.string().optional().describe("What the page sent back, as JSON text."),
+});
+export type TranscriptPageAsk = z.infer<typeof TranscriptPageAskSchema>;
 
 // One row shape across live folding, storage and replay; a reopened chat redraws the transcript, not paraphrases it. A
 // subagent's own calls nest under the card that spawned them (z.lazy, self-referential).
@@ -353,6 +363,9 @@ export const TranscriptRowSchema = z.object({
         "Another agent's words that reached this conversation, whose they are, and the prompt they came as.",
     ),
     backgroundJob: TranscriptBackgroundJobSchema.optional().describe("The background job this row marks the start of."),
+    // Not a card: a page parks nothing, it is part of what the agent said. On the bubble whose tool call showed it.
+    page: PageSchema.optional().describe("A page the agent showed here, drawn inline."),
+    pageAsk: TranscriptPageAskSchema.optional().describe("A page the agent asked to be answered on, and what it sent back."),
     credentialOffer: TranscriptCredentialOfferSchema.optional().describe(
         "The gated credential this row asked to use, who may release it, and who did.",
     ),
@@ -369,6 +382,7 @@ export const REQUEST_FIELDS = [
     "capabilityOffer",
     "paymentOffer",
     "credentialOffer",
+    "pageAsk",
 ] as const;
 export type RequestField = (typeof REQUEST_FIELDS)[number];
 export type TranscriptRequests = Pick<TranscriptRow, RequestField>;

package/src/ids/hostnames.fixture.json

@@ -1,13 +1,13 @@
 [
-    { "host": "preview-web-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345", "panel": "web" },
-    { "host": "preview-my-app-abcdef012345.sbx.example.test:443", "sandboxId": "abcdef012345", "panel": "my-app" },
-    { "host": "preview-shop--web-abcdef012345.example.com", "sandboxId": "abcdef012345", "panel": "shop--web" },
-    { "host": "preview-web-0123456789ab.sbx.example.test", "sandboxId": "abcdef012345" },
-    { "host": "preview--abcdef012345.sbx.example.test", "sandboxId": "abcdef012345" },
-    { "host": "preview-x-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345", "panel": "x" },
-    { "host": "port-1a2b3c4d5e6f-abcdef012345.sbx.example.test:8443", "sandboxId": "abcdef012345", "port": "1a2b3c4d5e6f" },
-    { "host": "public-9f8e7d6c5b4a-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345", "public": "9f8e7d6c5b4a" },
-    { "host": "sandbox-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345" },
+    { "host": "preview-web-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345", "panel": "web", "owner": "abcdef012345" },
+    { "host": "preview-my-app-abcdef012345.sbx.example.test:443", "sandboxId": "abcdef012345", "panel": "my-app", "owner": "abcdef012345" },
+    { "host": "preview-shop--web-abcdef012345.example.com", "sandboxId": "abcdef012345", "panel": "shop--web", "owner": "abcdef012345" },
+    { "host": "preview-web-0123456789ab.sbx.example.test", "sandboxId": "abcdef012345", "owner": "0123456789ab" },
+    { "host": "preview--abcdef012345.sbx.example.test", "sandboxId": "abcdef012345", "owner": "abcdef012345" },
+    { "host": "preview-x-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345", "panel": "x", "owner": "abcdef012345" },
+    { "host": "port-1a2b3c4d5e6f-abcdef012345.sbx.example.test:8443", "sandboxId": "abcdef012345", "port": "1a2b3c4d5e6f", "owner": "abcdef012345" },
+    { "host": "public-9f8e7d6c5b4a-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345", "public": "9f8e7d6c5b4a", "owner": "abcdef012345" },
+    { "host": "sandbox-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345", "owner": "abcdef012345", "daemon": "abcdef012345" },
     { "host": "app.example.com", "sandboxId": "abcdef012345" },
     { "host": "preview-web.localhost:8788", "panel": "web" },
     { "host": "port-a.localhost", "port": "a" },
@@ -16,5 +16,9 @@
     { "host": "127.0.0.1:8788" },
     { "host": "[::1]:8788" },
     { "host": "" },
-    { "host": "Preview-web-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345" }
+    { "host": "Preview-web-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345", "owner": "abcdef012345" },
+    { "host": "SANDBOX-abcdef012345.sbx.example.test:443", "owner": "abcdef012345", "daemon": "abcdef012345" },
+    { "host": "sandbox-abcdef012345x.sbx.example.test" },
+    { "host": "myapp-0123456789ab.example.com", "owner": "0123456789ab" },
+    { "host": "abcdef012345.local.sbx.example.test" }
 ]

package/src/ids/hostnames.test.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import {
+    hostOwnerId,
     labelHostname,
     panelFromHost,
     portHostname,
@@ -12,22 +13,26 @@ import {
     publicSlotFromHost,
     sandboxHostname,
     sandboxIdFromUrl,
+    sandboxIdOfDaemonUrl,
     syncFolder,
 } from "./hostnames.js";
 
 const ID = "abc123def456";
 
-// The cases the front's Rust router is held to as well (_sandbox/front, route.rs), read from the one file both run.
+// The cases netd's Rust router is held to as well (_sandbox/netd, route.rs), read from the one file both run.
 interface HostCase {
     readonly host: string;
     readonly sandboxId?: string;
     readonly panel?: string;
     readonly port?: string;
     readonly public?: string;
+    // The sandbox the name routes to (hostOwnerId), and the minted id it carries as a daemon's own address.
+    readonly owner?: string;
+    readonly daemon?: string;
 }
 const HOST_CASES = JSON.parse(readFileSync(new URL("./hostnames.fixture.json", import.meta.url), "utf8")) as HostCase[];
 
-test.each(HOST_CASES)("the shared host cases parse as the front parses them: $host", (hostCase) => {
+test.each(HOST_CASES)("the shared host cases parse as netd parses them: $host", (hostCase) => {
     expect({
         panel: panelFromHost(hostCase.host, hostCase.sandboxId),
         port: portSlotFromHost(hostCase.host, hostCase.sandboxId),
@@ -35,6 +40,20 @@ test.each(HOST_CASES)("the shared host cases parse as the front parses them: $ho
     }).toEqual({ panel: hostCase.panel, port: hostCase.port, public: hostCase.public });
 });
 
+test.each(HOST_CASES)("the shared host cases name their owner, and a daemon address its minted id: $host", (hostCase) => {
+    expect({ owner: hostOwnerId(hostCase.host), daemon: sandboxIdOfDaemonUrl(hostCase.host) }).toEqual({
+        owner: hostCase.owner,
+        daemon: hostCase.daemon,
+    });
+});
+
+test("a daemon address is read with or without its scheme, and an unparsable one names no sandbox", () => {
+    expect(sandboxIdOfDaemonUrl(`https://sandbox-82789f4106b4.radarsu.com`)).toBe(`82789f4106b4`);
+    expect(sandboxIdOfDaemonUrl(`sandbox-82789f4106b4.radarsu.com/`)).toBe(`82789f4106b4`);
+    expect(sandboxIdOfDaemonUrl(`https://sandbox.example.com`)).toBeUndefined();
+    expect(sandboxIdOfDaemonUrl(`http://[not a host`)).toBeUndefined();
+});
+
 test("preview and port hostnames round-trip through their Host-header parsers", () => {
     expect(panelFromHost(`${previewHostname("shop--web", ID, "example.com")}:443`, ID)).toBe("shop--web");
     expect(portSlotFromHost(`${portHostname("a", ID, "example.com")}:443`, ID)).toBe("a");

package/src/ids/hostnames.ts

@@ -77,19 +77,45 @@ export const portSlotFromHost = (hostHeader: string | undefined, sandboxId: stri
 export const publicSlotFromHost = (hostHeader: string | undefined, sandboxId: string | undefined): string | undefined =>
     keyFromHost("public-", hostHeader, sandboxId);
 
+// WHICH SANDBOX A NAME BELONGS TO is three questions, and each has its own answer below; they disagree on purpose:
+// - hostOwnerId: the sandbox a hostname routes to, by the 12-hex id the platform mints into every name it makes. The
+//   edge routes a Host by it, and the platform's DNS reaper reads a record's owner by it.
+// - sandboxIdOfDaemonUrl: the minted id in a daemon's own address, `sandbox-<id>` exactly, which is what the platform's
+//   lookup names. A preview or port name is not a daemon's address, and an own domain carries none, its /health says it.
+// - sandboxIdFromUrl: the identity as the user sees it, whatever the label, for naming a sync folder.
+
+const MINTED_ID = "[0-9a-f]{12}";
+// A URL's hostname, scheme optional; undefined for one that does not parse.
+const hostnameOf = (url: string): string | undefined => {
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? url : `https://${url}`;
+    try {
+        return new URL(withScheme).hostname;
+    } catch {
+        return undefined;
+    }
+};
+
+// The sandbox that owns a Host (port optional): its leftmost DNS label is `sandbox-<id>` or ends in `-<id>` (a preview,
+// port or outbox name). Anything else, including the loopback `<id>.local.<zone>` label, is no sandbox's.
+export const hostOwnerId = (host: string): string | undefined => {
+    const label = host.split(":")[0]?.split(".")[0] ?? "";
+    return new RegExp(`-(${MINTED_ID})$`).exec(label)?.[1];
+};
+
+// The platform-minted id a daemon's address carries (`https://sandbox-<id>.<zone>`), or undefined for a sandbox behind a
+// domain of its own, or an address that does not parse.
+export const sandboxIdOfDaemonUrl = (url: string): string | undefined => {
+    const label = hostnameOf(url)?.split(".")[0] ?? "";
+    return new RegExp(`^${SANDBOX_PREFIX}(${MINTED_ID})$`).exec(label)?.[1];
+};
+
 // The sandbox's identity as the user sees it: the URL's leading DNS label minus the `sandbox-` prefix. On the
 // own-Cloudflare path the label is whatever subdomain the owner chose, so that is the id there.
 export const sandboxIdFromUrl = (url: string | undefined): string | undefined => {
     if (url === undefined || url === "") {
         return undefined;
     }
-    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? url : `https://${url}`;
-    let label: string;
-    try {
-        label = new URL(withScheme).hostname.split(".")[0] ?? "";
-    } catch {
-        return undefined;
-    }
+    const label = hostnameOf(url)?.split(".")[0] ?? "";
     if (label === "" || label === SANDBOX_PREFIX) {
         return undefined;
     }
@@ -114,14 +140,7 @@ export const zoneFromUrl = (url: string | undefined): string | undefined => {
     if (url === undefined || url === "") {
         return undefined;
     }
-    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? url : `https://${url}`;
-    let hostname: string;
-    try {
-        hostname = new URL(withScheme).hostname;
-    } catch {
-        return undefined;
-    }
-    const labels = hostname.split(".");
+    const labels = hostnameOf(url)?.split(".") ?? [];
     if (labels.length < 3) {
         return undefined;
     }

package/src/ids/sandbox-id.ts

@@ -0,0 +1,3 @@
+// Twelve lowercase hex characters, a gate applied before trusting an id off the wire (a hostname, a ticket, a path).
+// Its own module so a browser bundle can take it without tunnel-ids.ts's node:crypto.
+export const SANDBOX_ID = /^[0-9a-f]{12}$/;

package/src/ids/tunnel-ids.ts

@@ -4,8 +4,7 @@ import { createHash } from "node:crypto";
 // hashes, hashline anchors). node:crypto makes this subpath node-only.
 export const sha256Hex = (value: string): string => createHash("sha256").update(value).digest("hex");
 
-// Twelve lowercase hex characters, a gate applied before trusting an id off the wire (a hostname, a ticket).
-export const SANDBOX_ID = /^[0-9a-f]{12}$/;
+export { SANDBOX_ID } from "./sandbox-id.js";
 
 // The sandbox's stable 12-hex id, digested from the connect token; every public hostname embeds it, and the platform's
 // grant mint, tunnelId lookup and the desktop agent's loopback dial all must derive the identical value.