@intentic/sandbox-contract 1.271.0 → 1.273.0

package/src/schemas/devices.ts

@@ -1,6 +1,6 @@
 // What one of the user's own machines is running.
 import { z } from "zod";
-import { HostFactsSchema } from "./hosts.js";
+import { type HostFacts, HostFactsSchema, WslEnvironmentSchema } from "./hosts.js";
 import { DEV_VERSION } from "../state/versions.js";
 // Desktop-sync report shape shared by the agent, daemon and browser, produced only by `intentic-machine status --json`.
 // The agent never reports `sandboxes`; the docker half is filled in by whoever reads the report, scoped to the reader's
@@ -303,10 +303,8 @@ export const DeviceReportSchema = z.object({
     // own: a WSL distro inherits the Windows machine's name, so `wsl` below is what tells those apart.
     hostname: z.string(),
     os: z.string(),
-    // Present only inside a WSL distro. `distro` is that distro's own name ("Arch", "Ubuntu-22.04"), empty when the
-    // machine won't say. Windows, and every distro it hosts, all answer `hostname` with the same string while being
-    // separate filesystems running separate agents, so this is the only thing that keeps them apart.
-    wsl: z.object({ distro: z.string() }).optional(),
+    // Present only inside a WSL distro; the same fact rides the connect-time facts, which no scope can withhold.
+    wsl: WslEnvironmentSchema.optional(),
     pairings: z.array(DevicePairingSchema),
     ports: z.array(DevicePortSchema),
     // The one agent this device runs, on disk and in flight, in one block.
@@ -321,21 +319,23 @@ export type DeviceReport = z.infer<typeof DeviceReportSchema>;
 export const REPORT_QUIET_AFTER_MS = 60_000;
 export const reportQuiet = (report: DeviceReport, receivedAt: number): boolean => receivedAt - report.capturedAt > REPORT_QUIET_AFTER_MS;
 
-// The environment a reading came from, as opposed to the machine hosting it: a Windows install and every WSL distro
-// on it are separate filesystems running separate agents, and all of them answer `hostname` with the same string.
-// Undefined when nothing has reported — an absence of evidence, never read as agreement.
-export const environmentOf = (report: DeviceReport | undefined): string | undefined =>
-    report === undefined ? undefined : report.wsl === undefined ? report.os : `wsl:${report.wsl.distro}`;
-
-// Whether two readings positively disagree about which environment they describe. False whenever either side has not
-// said, so this only ever blocks a fold it holds evidence against, and an agent too old to report `wsl` keeps the
-// behaviour it had before the field existed.
-export const differentEnvironment = (left: DeviceReport | undefined, right: DeviceReport | undefined): boolean => {
-    const a = environmentOf(left);
-    const b = environmentOf(right);
-    return a !== undefined && b !== undefined && a !== b;
+// The environment a device's evidence describes, as opposed to the machine hosting it: `wsl:<distro>` inside a
+// distro, `native` for an install on the metal. Connect-time facts are read first, since no scope can withhold them;
+// facts from an agent too old to carry `hostname` say nothing, and a report without `wsl` is native, as it always
+// was. Undefined is an absence of evidence, never read as agreement.
+export const environmentOf = (facts: Pick<HostFacts, "hostname" | "wsl"> | undefined, report: DeviceReport | undefined): string | undefined => {
+    const wsl = facts?.wsl ?? report?.wsl;
+    if (wsl !== undefined) {
+        return `wsl:${wsl.distro}`;
+    }
+    return facts?.hostname !== undefined || report !== undefined ? "native" : undefined;
 };
 
+// Whether two devices positively disagree about which environment they are. False whenever either side has not said,
+// so this only ever blocks a fold it holds evidence against.
+export const differentEnvironment = (left: string | undefined, right: string | undefined): boolean =>
+    left !== undefined && right !== undefined && left !== right;
+
 // Compares running build against installed; silent when the loop is stopped, nothing installed, or installed is a dev
 // build. An unstamped `running` still counts as skew.
 export const agentBuildSkew = (agent: DeviceAgent): { readonly running: string | undefined; readonly installed: string } | undefined => {
@@ -402,6 +402,57 @@ export const DeviceSchema = z.object({
 export type Device = z.infer<typeof DeviceSchema>;
 export const DevicesListSchema = z.object({ devices: z.array(DeviceSchema) });
 
+// The physical computer a device is an environment of. Windows and every WSL distro on it are one machine with one
+// Docker engine, one screen and one set of disks, each environment holding its own agent and its own door.
+export interface Machine {
+    /** A lone device's own key, so its address does not change; a folded machine's is the hostname its doors share. */
+    readonly key: string;
+    readonly label: string;
+    /** Windows first, then distros by label: the side that owns the screen leads. */
+    readonly environments: readonly Device[];
+}
+
+export const deviceHostname = (device: Device): string | undefined => device.facts?.hostname ?? device.report?.hostname;
+export const deviceEnvironment = (device: Device): string | undefined => environmentOf(device.facts, device.report);
+export const isWslDevice = (device: Device): boolean => deviceEnvironment(device)?.startsWith("wsl:") === true;
+
+// Two native installs that merely share a name stay two machines; only a distro joins the machine whose hostname it
+// carries, which is the one fact that makes the name safe to join on.
+const byEnvironment = (a: Device, b: Device): number => Number(isWslDevice(a)) - Number(isWslDevice(b)) || a.label.localeCompare(b.label);
+
+const hostnameKey = (device: Device): string | undefined => deviceHostname(device)?.toLowerCase();
+
+const siblingsOf = (device: Device, devices: readonly Device[]): Device[] => {
+    const key = hostnameKey(device);
+    const shared = key === undefined ? [device] : devices.filter((candidate) => hostnameKey(candidate) === key);
+    return shared.length > 1 && shared.some(isWslDevice) ? shared.toSorted(byEnvironment) : [device];
+};
+
+const machineOf = (device: Device, environments: readonly Device[]): Machine => {
+    if (environments.length === 1) {
+        return { key: device.key, label: device.label, environments };
+    }
+    // Folding needs a hostname, so it is present here; the fallback only keeps the type honest.
+    const hostname = deviceHostname(device) ?? device.key;
+    return { key: hostname, label: hostname, environments };
+};
+
+export const machinesOf = (devices: readonly Device[]): Machine[] => {
+    const folded = new Set<Device>();
+    const machines: Machine[] = [];
+    for (const device of devices) {
+        if (folded.has(device)) {
+            continue;
+        }
+        const environments = siblingsOf(device, devices);
+        for (const environment of environments) {
+            folded.add(environment);
+        }
+        machines.push(machineOf(device, environments));
+    }
+    return machines;
+};
+
 // The connected, online device whose docker reports a given sandbox slug: the machine that sandbox RUNS ON, as opposed
 // to any machine merely paired with it. Answers the question every "run it there instead of asking the owner to type
 // it" path starts from, and is `undefined` for a sync-only agent, which reports no containers at all.

package/src/schemas/hosts.ts

@@ -3,6 +3,12 @@ import { z } from "zod";
 // Manifest says which machines are intended; this says which actually hold a socket now. Nothing persists across a
 // daemon restart except the enrollment itself, so a closed laptop reads offline within a heartbeat.
 
+// Which WSL distro a Linux agent runs inside. Windows and every distro it hosts answer `hostname` with the same string
+// while being separate filesystems running separate agents, so this is what keeps a distro apart from the install
+// hosting it. `distro` is WSL's own name for it ("Arch", "Ubuntu-22.04"), empty when the distro won't say.
+export const WslEnvironmentSchema = z.object({ distro: z.string() });
+export type WslEnvironment = z.infer<typeof WslEnvironmentSchema>;
+
 // What a machine reports once at connect (`host.describe`), cached until it reconnects: the skill pack says how to
 // drive Windows, this says which Windows it is.
 export const HostFactsSchema = z.object({
@@ -18,8 +24,23 @@ export const HostFactsSchema = z.object({
     // Docker engine's size (WSL guest on Windows, Desktop VM on macOS, host on Linux); the ceiling a sandbox's share is
     // bounded by.
     engine: z.object({ memoryBytes: z.number(), cpus: z.number() }).optional(),
+    // OS hostname: the key that joins the doors of one physical machine. Reported by every agent that also reports
+    // `wsl`, so a hostname with no `wsl` beside it is a native install; absent from an agent older than both.
+    hostname: z.string().optional(),
+    // Present only inside a WSL distro.
+    wsl: WslEnvironmentSchema.optional(),
+    // Windows only: the distros `wsl -l -q` lists, the names `run_command`'s `in: "wsl:<name>"` accepts.
+    wslDistros: z.array(z.string()).optional(),
 });
 export type HostFacts = z.infer<typeof HostFactsSchema>;
+
+// One folder, two names. Windows sees a distro's files under a UNC share and a distro sees the Windows drives under
+// /mnt, so a path handed across the boundary is translated here rather than by hand at every call site.
+export const wslPathOf = (windowsPath: string): string | undefined => {
+    const drive = /^([A-Za-z]):[\\/](.*)$/.exec(windowsPath);
+    return drive === null ? undefined : `/mnt/${drive[1]?.toLowerCase()}/${(drive[2] ?? "").replaceAll("\\", "/")}`.replace(/\/$/, "");
+};
+export const windowsPathOf = (distro: string, linuxPath: string): string => `\\\\wsl.localhost\\${distro}${linuxPath.replaceAll("/", "\\")}`;
 export const HostSummarySchema = z.object({
     // The capability id, the machine's name, and the prefix of its tools (mcp__<id>__run_command).
     id: z.string(),

package/src/schemas/remote-refs.ts

@@ -0,0 +1,39 @@
+// What a git remote advertises right now: the versions an install form can pin to without anyone reading a sha off a
+// web page. Answered from `git ls-remote`, so nothing is cloned and nothing is written.
+import { z } from "zod";
+
+// POST so a private repository's token never rides a URL or an access log, the same reasoning as the marketplace read.
+export const RemoteRefsRequestSchema = z.object({
+    url: z.url().describe("The repository to ask. http(s) only: an ssh remote would stop on a host-key prompt nobody can answer."),
+    token: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+            "A credential for a private one. Sent as a body rather than in the address, so it never lands in a log. A form editing a live connection has never been shown its token: it sends the VAULTED marker here and names the connection in `keeping`, so a private repository still answers without anyone retyping a key.",
+        ),
+    keeping: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Which connection a VAULTED token belongs to. Ignored when a real token is sent."),
+});
+
+export const RemoteRefSchema = z.object({
+    name: z.string().describe("The branch or tag as a person names it: `main`, `v1.4.0`."),
+    kind: z.enum(["branch", "tag"]),
+    sha: z
+        .string()
+        .regex(/^[0-9a-f]{40}$/)
+        .describe("The commit it points at. An annotated tag is peeled here, so this is always a commit, never a tag object."),
+});
+export type RemoteRef = z.infer<typeof RemoteRefSchema>;
+
+export const RemoteRefsSchema = z.object({
+    defaultBranch: z
+        .string()
+        .optional()
+        .describe("The branch the remote advertises as HEAD, the one to offer first. Absent when the remote advertises no symref."),
+    refs: z.array(RemoteRefSchema).describe("Every branch the remote advertises, then every tag. Which to offer first is the reader's question, not this one's."),
+});
+export type RemoteRefs = z.infer<typeof RemoteRefsSchema>;