windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/shared/guest-paths.d.ts

@@ -0,0 +1,30 @@
+/** Guest folders no mapping may use: the OS, the sandbox's own folders and the mirror root. */
+export declare const RESERVED_GUEST: RegExp;
+/** Where folders for other drive letters really live inside the sandbox: C:\Mirror\<letter>. */
+export declare const MIRROR_ROOT = "C:\\Mirror";
+/** Letters a mirrored path may use. Never C: (the sandbox's own disk); A:/B: are left alone (floppy-era tools). */
+export declare const MIRROR_LETTER: RegExp;
+/** The upper-case drive letter of an absolute guest path (F:\x -> F), or null. */
+export declare const guestDrive: (guest: string) => string | null;
+/**
+ * A folder the sandbox can show a host folder at: C:\<not reserved>\... or <D-Z>:\..., never a drive root,
+ * no '..' or empty segments, no characters Windows rejects in paths.
+ */
+export declare const isValidGuestPath: (guest: string) => boolean;
+/** Where a guest path really is inside the sandbox (the .wsb SandboxFolder): C: paths as-is, F:\x -> C:\Mirror\F\x. */
+export declare const sandboxFolder: (guest: string) => string;
+export interface SubstDrive {
+    letter: string;
+    target: string;
+}
+/** The subst drives the guest must create at boot for these guest paths, one per letter, sorted. */
+export declare const substDrives: (guests: string[]) => SubstDrive[];
+/**
+ * guestWorkspace "mirror": the workspace at the same path as on this PC, so absolute paths (configs, build caches,
+ * cargo fingerprints, Claude's project folder) match. Falls back to `fallback` (C:\Workspace\<name>) when the host
+ * path cannot be used inside the sandbox (C:\Users\..., a UNC path, A:/B:, odd characters), with a note saying why.
+ */
+export declare const planMirrorWorkspace: (workspaceHost: string, fallback: string) => {
+    guest: string;
+    note: string | null;
+};

package/dist/shared/guest-paths.js

@@ -0,0 +1,61 @@
+// Guest paths on drive letters other than C:. Windows Sandbox can only map folders onto its own C: drive, so a
+// guest path like F:\SteamLibrary\x is mapped to C:\Mirror\F\SteamLibrary\x and, at boot (bootstrap.ps1, before
+// anything else uses the workspace), `subst F: C:\Mirror\F` makes it appear at F:\SteamLibrary\x.
+// Pure functions only: used by the schema, the host (.wsb, session.json) and history sync.
+/** Guest folders no mapping may use: the OS, the sandbox's own folders and the mirror root. */
+export const RESERVED_GUEST = /^C:\\(?:Windows|Program Files|Program Files \(x86\)|ProgramData|Users|AgentLaunch|AgentData|HostTools|nvm|Mirror)(?:\\|$)/i;
+/** Where folders for other drive letters really live inside the sandbox: C:\Mirror\<letter>. */
+export const MIRROR_ROOT = 'C:\\Mirror';
+/** Letters a mirrored path may use. Never C: (the sandbox's own disk); A:/B: are left alone (floppy-era tools). */
+export const MIRROR_LETTER = /^[D-Z]$/;
+const DRIVE_PATH = /^([A-Za-z]):\\(.*)$/;
+// No other ':' (alternate data streams), no wildcards or pipes, no control characters, no forward slashes.
+const BAD_CHARS = /[<>:"|?*/\x00-\x1f]/;
+/** The upper-case drive letter of an absolute guest path (F:\x -> F), or null. */
+export const guestDrive = (guest) => DRIVE_PATH.exec(guest)?.[1].toUpperCase() ?? null;
+/**
+ * A folder the sandbox can show a host folder at: C:\<not reserved>\... or <D-Z>:\..., never a drive root,
+ * no '..' or empty segments, no characters Windows rejects in paths.
+ */
+export const isValidGuestPath = (guest) => {
+    const m = DRIVE_PATH.exec(guest);
+    if (!m)
+        return false;
+    const letter = m[1].toUpperCase();
+    const rest = m[2].replace(/\\+$/, '');
+    if (rest === '' || BAD_CHARS.test(rest))
+        return false;
+    if (rest.split('\\').some((segment) => segment === '' || segment === '.' || segment === '..' || /[. ]$/.test(segment)))
+        return false;
+    if (letter === 'C')
+        return !RESERVED_GUEST.test('C:\\' + rest);
+    return MIRROR_LETTER.test(letter);
+};
+/** Where a guest path really is inside the sandbox (the .wsb SandboxFolder): C: paths as-is, F:\x -> C:\Mirror\F\x. */
+export const sandboxFolder = (guest) => {
+    const m = DRIVE_PATH.exec(guest);
+    if (!m || m[1].toUpperCase() === 'C')
+        return guest;
+    return MIRROR_ROOT + '\\' + m[1].toUpperCase() + (m[2] ? '\\' + m[2] : '');
+};
+/** The subst drives the guest must create at boot for these guest paths, one per letter, sorted. */
+export const substDrives = (guests) => {
+    const letters = [...new Set(guests.map(guestDrive).filter((l) => l !== null && l !== 'C'))].sort();
+    return letters.map((letter) => ({ letter, target: MIRROR_ROOT + '\\' + letter }));
+};
+/**
+ * guestWorkspace "mirror": the workspace at the same path as on this PC, so absolute paths (configs, build caches,
+ * cargo fingerprints, Claude's project folder) match. Falls back to `fallback` (C:\Workspace\<name>) when the host
+ * path cannot be used inside the sandbox (C:\Users\..., a UNC path, A:/B:, odd characters), with a note saying why.
+ */
+export const planMirrorWorkspace = (workspaceHost, fallback) => {
+    const host = workspaceHost.replace(/\\+$/, '');
+    if (isValidGuestPath(host)) {
+        const letter = guestDrive(host);
+        return { guest: letter + host.slice(1), note: letter === 'C' ? null : 'guestWorkspace "mirror": ' + host + ' is mapped to ' + sandboxFolder(letter + host.slice(1)) + ' and shown as ' + letter + ': (subst) inside the sandbox.' };
+    }
+    const why = !guestDrive(host) ? 'it is not on a drive letter'
+        : guestDrive(host) === 'C' && RESERVED_GUEST.test(host) ? 'that folder is reserved inside the sandbox (Windows, Program Files, Users, ...)'
+            : 'the sandbox cannot show a folder at that path';
+    return { guest: fallback, note: 'guestWorkspace "mirror": ' + host + ' cannot appear at the same path (' + why + '); using ' + fallback + ' instead.' };
+};

package/dist/shared/netrules.d.ts

@@ -0,0 +1,18 @@
+/** Private, carrier-grade NAT (Tailscale and similar live here), link-local and multicast ranges. */
+export declare const PRIVATE_V4: string[];
+export declare const PRIVATE_V6: string[];
+export declare const RULE_NAMES: string[];
+export declare const isIPv4: (ip: string) => boolean;
+export declare const ipToInt: (ip: string) => number;
+export declare const intToIp: (n: number) => string;
+export declare const cidrToRange: (cidr: string) => [number, number];
+export declare const subtractIps: (ranges: [number, number][], ips: string[]) => [number, number][];
+export declare const formatRange: (range: [number, number]) => string;
+export declare const isPrivateV4: (ip: string) => boolean;
+export declare const parseDefaultGateways: (routePrint: string) => string[];
+/** The IPv4 servers in a dns.getServers() list ('8.8.8.8', '8.8.8.8:1053', '[::1]:53'); IPv6 ones are dropped. */
+export declare const ipv4DnsServers: (servers: string[]) => string[];
+/** Fallback only: the "DNS Servers" label is English, so this finds nothing on localised Windows (dns.getServers() does). */
+export declare const parseDnsServers: (ipconfigAll: string) => string[];
+/** netsh argument lists. Private ranges are blocked EXCEPT DNS/DHCP to the sandbox's own gateway, so name resolution keeps working. */
+export declare const buildFirewallCommands: (exemptIps: string[]) => string[][];

package/dist/shared/netrules.js

@@ -0,0 +1,98 @@
+/** Private, carrier-grade NAT (Tailscale and similar live here), link-local and multicast ranges. */
+export const PRIVATE_V4 = ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', '100.64.0.0/10', '169.254.0.0/16', '224.0.0.0/4'];
+export const PRIVATE_V6 = ['fc00::/7', 'fe80::/10', 'ff00::/8'];
+export const RULE_NAMES = ['AgentSandbox-Block-Private', 'AgentSandbox-Block-IPv6-Local', 'AgentSandbox-Block-SMB', 'AgentSandbox-Gateway-TCP', 'AgentSandbox-Gateway-UDP'];
+export const isIPv4 = (ip) => {
+    const parts = ip.split('.');
+    return parts.length === 4 && parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255);
+};
+export const ipToInt = (ip) => {
+    if (!isIPv4(ip))
+        throw new Error('Invalid IPv4 address: ' + ip);
+    const p = ip.split('.').map(Number);
+    return p[0] * 16777216 + p[1] * 65536 + p[2] * 256 + p[3];
+};
+export const intToIp = (n) => {
+    return [Math.floor(n / 16777216) % 256, Math.floor(n / 65536) % 256, Math.floor(n / 256) % 256, n % 256].join('.');
+};
+export const cidrToRange = (cidr) => {
+    const [ip, bits] = cidr.split('/');
+    const size = 2 ** (32 - Number(bits));
+    const start = Math.floor(ipToInt(ip) / size) * size;
+    return [start, start + size - 1];
+};
+export const subtractIps = (ranges, ips) => {
+    let result = ranges.map((r) => [r[0], r[1]]);
+    for (const ip of ips) {
+        const n = ipToInt(ip);
+        const next = [];
+        for (const [start, end] of result) {
+            if (n < start || n > end) {
+                next.push([start, end]);
+                continue;
+            }
+            if (n > start)
+                next.push([start, n - 1]);
+            if (n < end)
+                next.push([n + 1, end]);
+        }
+        result = next;
+    }
+    return result;
+};
+export const formatRange = (range) => {
+    return range[0] === range[1] ? intToIp(range[0]) : intToIp(range[0]) + '-' + intToIp(range[1]);
+};
+export const isPrivateV4 = (ip) => {
+    const n = ipToInt(ip);
+    return PRIVATE_V4.some((c) => { const [s, e] = cidrToRange(c); return n >= s && n <= e; });
+};
+export const parseDefaultGateways = (routePrint) => {
+    const found = [];
+    for (const line of routePrint.split(/\r?\n/)) {
+        const m = /^\s*0\.0\.0\.0\s+0\.0\.0\.0\s+(\d{1,3}(?:\.\d{1,3}){3})\s/.exec(line);
+        if (m && isIPv4(m[1]))
+            found.push(m[1]);
+    }
+    return found;
+};
+/** The IPv4 servers in a dns.getServers() list ('8.8.8.8', '8.8.8.8:1053', '[::1]:53'); IPv6 ones are dropped. */
+export const ipv4DnsServers = (servers) => servers.map((s) => s.replace(/:\d+$/, '')).filter(isIPv4);
+/** Fallback only: the "DNS Servers" label is English, so this finds nothing on localised Windows (dns.getServers() does). */
+export const parseDnsServers = (ipconfigAll) => {
+    const found = [];
+    let inDns = false;
+    for (const line of ipconfigAll.split(/\r?\n/)) {
+        if (/DNS Servers/i.test(line)) {
+            inDns = true;
+            for (const m of line.matchAll(/(\d{1,3}(?:\.\d{1,3}){3})/g))
+                if (isIPv4(m[1]))
+                    found.push(m[1]);
+        }
+        else if (inDns && /^\s+\d{1,3}(?:\.\d{1,3}){3}\s*$/.test(line)) {
+            found.push(line.trim());
+        }
+        else {
+            inDns = false;
+        }
+    }
+    return found;
+};
+/** netsh argument lists. Private ranges are blocked EXCEPT DNS/DHCP to the sandbox's own gateway, so name resolution keeps working. */
+export const buildFirewallCommands = (exemptIps) => {
+    const exempt = [...new Set(exemptIps.filter((ip) => isIPv4(ip) && isPrivateV4(ip)))];
+    const v4 = subtractIps(PRIVATE_V4.map(cidrToRange), exempt).map(formatRange);
+    const add = (name, extra) => ['advfirewall', 'firewall', 'add', 'rule', 'name=' + name, 'dir=out', 'action=block', 'enable=yes', 'profile=any', ...extra];
+    const commands = [];
+    for (const name of RULE_NAMES)
+        commands.push(['advfirewall', 'firewall', 'delete', 'rule', 'name=' + name]);
+    commands.push(['advfirewall', 'set', 'allprofiles', 'state', 'on']);
+    commands.push(add('AgentSandbox-Block-Private', ['protocol=any', 'remoteip=' + v4.join(',')]));
+    commands.push(add('AgentSandbox-Block-IPv6-Local', ['protocol=any', 'remoteip=' + PRIVATE_V6.join(',')]));
+    commands.push(add('AgentSandbox-Block-SMB', ['protocol=tcp', 'remoteport=135,139,445']));
+    if (exempt.length > 0) {
+        commands.push(add('AgentSandbox-Gateway-TCP', ['protocol=tcp', 'remoteip=' + exempt.join(','), 'remoteport=1-52,54-65535']));
+        commands.push(add('AgentSandbox-Gateway-UDP', ['protocol=udp', 'remoteip=' + exempt.join(','), 'remoteport=1-52,54-66,69-65535']));
+    }
+    return commands;
+};

package/dist/shared/paths.d.ts

@@ -0,0 +1,14 @@
+/** Claude Code's per-project folder name: every non-alphanumeric character becomes '-' (F:\A\b -> F--A-b). */
+export declare const projectFolderName: (workspace: string) => string;
+/**
+ * Every path the guest may know its workspace by, the real one first: a mirrored F:\A\b is a subst drive onto
+ * C:\Mirror\F\A\b, and programs that resolve real paths (realpath, GetFinalPathNameByHandle) report that one.
+ */
+export declare const guestWorkspaceAliases: (guestWorkspace: string) => string[];
+/**
+ * A file or folder name that is safe to recreate on this PC. The sandbox can create names Windows would treat as devices
+ * (CON.jsonl opens the console), as streams (a:b), or that end in a dot or space (silently renamed); none of them are copied.
+ */
+export declare const isSafeFileName: (name: string) => boolean;
+/** Rewrites `from` to `to` wherever it appears as a whole path (raw, JSON-escaped or with forward slashes). */
+export declare const translatePaths: (text: string, from: string, to: string) => string;

package/dist/shared/paths.js

@@ -0,0 +1,28 @@
+// Path translation between this PC and the sandbox (shared by the host history sync and the guest plugin fix-up).
+import { sandboxFolder } from './guest-paths.js';
+/** Claude Code's per-project folder name: every non-alphanumeric character becomes '-' (F:\A\b -> F--A-b). */
+export const projectFolderName = (workspace) => workspace.replace(/[^a-zA-Z0-9]/g, '-');
+/**
+ * Every path the guest may know its workspace by, the real one first: a mirrored F:\A\b is a subst drive onto
+ * C:\Mirror\F\A\b, and programs that resolve real paths (realpath, GetFinalPathNameByHandle) report that one.
+ */
+export const guestWorkspaceAliases = (guestWorkspace) => {
+    const real = sandboxFolder(guestWorkspace);
+    return real.toLowerCase() === guestWorkspace.toLowerCase() ? [guestWorkspace] : [real, guestWorkspace];
+};
+const DEVICE_NAME = /^(con|prn|aux|nul|conin\$|conout\$|com[0-9¹²³]|lpt[0-9¹²³])(\..*)?$/i;
+/**
+ * A file or folder name that is safe to recreate on this PC. The sandbox can create names Windows would treat as devices
+ * (CON.jsonl opens the console), as streams (a:b), or that end in a dot or space (silently renamed); none of them are copied.
+ */
+export const isSafeFileName = (name) => name !== '' && name.length <= 200 && name !== '.' && name !== '..' && !/[<>:"|?*/\\\x00-\x1f]/.test(name) && !/[. ]$/.test(name) && !DEVICE_NAME.test(name);
+const jsonEscaped = (p) => JSON.stringify(p).slice(1, -1);
+const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const forward = (p) => p.replace(/\\/g, '/');
+/** Rewrites `from` to `to` wherever it appears as a whole path (raw, JSON-escaped or with forward slashes). */
+export const translatePaths = (text, from, to) => {
+    if (from.toLowerCase() === to.toLowerCase())
+        return text;
+    const pairs = [[jsonEscaped(from), jsonEscaped(to)], [from, to], [forward(from), forward(to)]];
+    return pairs.reduce((out, [a, b]) => out.replace(new RegExp(escapeRegex(a) + '(?=\\\\|/|"|\'|\\s|$)', 'gi'), b.replace(/\$/g, '$$$$')), text);
+};

package/dist/shared/projects.d.ts

@@ -0,0 +1,53 @@
+/** Where roots, boot-mapped projects and shared folders appear inside the sandbox. */
+export declare const PROJECTS_GUEST = "C:\\Projects";
+/** How a project got into the sandbox. */
+export type Mechanism = 'launch' | 'root' | 'boot' | 'wsb';
+/** One project the running sandbox works on. */
+export interface ProjectEntry {
+    name: string;
+    host: string;
+    guest: string;
+    primary: boolean;
+    mechanism: Mechanism;
+}
+/** `child` is `parent` or somewhere below it (Windows paths, case-insensitive). */
+export declare const isWithin: (parent: string, child: string) => boolean;
+/**
+ * A project id (also its folder name under C:\Projects) for a folder: its name with only letters, digits, '-' and
+ * '_' (ids become file names on both sides), at most 48 characters, made unique against `taken` with -2, -3, ...
+ */
+export declare const hubName: (hostDir: string, taken: Iterable<string>) => string;
+/** The project a folder on this PC belongs to: the most specific one that contains it (a project inside another wins). */
+export declare const projectForHostDir: <P extends {
+    host: string;
+}>(projects: P[], hostDir: string) => P | null;
+/** The same for a folder inside the sandbox. */
+export declare const projectForGuestDir: <P extends {
+    guest: string;
+}>(projects: P[], guestDir: string) => P | null;
+/** Where a folder on this PC appears inside the sandbox, given the mapped folder (project or root) that contains it. */
+export declare const guestDirFor: (mapped: {
+    host: string;
+    guest: string;
+}, hostDir: string) => string;
+/** The other way: where a folder inside the sandbox is on this PC, given the mapped folder that contains it. */
+export declare const hostDirFor: (mapped: {
+    host: string;
+    guest: string;
+}, guestDir: string) => string;
+/** Strictly below `parent` (never `parent` itself). */
+export declare const isBelow: (parent: string, child: string) => boolean;
+/** A guest folder some project can be in: below C:\Projects, or inside one of the roots (their guest paths). */
+export declare const insideProjects: (guestDir: string, roots?: string[], projectsDir?: string) => boolean;
+export interface RootMapping {
+    host: string;
+    guest: string;
+}
+/**
+ * Guest folders for the project roots and the projects mapped at boot: C:\Projects\<name>, unique; with
+ * guestWorkspace "mirror" a root appears at its PC path when the sandbox can show it there.
+ */
+export declare const planProjectMappings: (roots: string[], projects: string[], mirror: boolean, taken?: string[]) => {
+    roots: RootMapping[];
+    projects: RootMapping[];
+};

package/dist/shared/projects.js

@@ -0,0 +1,67 @@
+// Several projects in one running sandbox. Windows Sandbox fixes its mapped folders at boot, so a project can only
+// join a running sandbox when it is already visible inside:
+//  - the launch folder (mapped directly, as always);
+//  - a folder inside a project root (projects.roots: whole folders of projects, mapped at every start), including
+//    projects created after boot;
+//  - projects mapped at boot because they were in use when the sandbox was restarted to add them;
+//  - a folder shared into the running sandbox with `wsb share` (Windows 11 24H2+, untested).
+// Roots, boot-mapped projects and shares appear under C:\Projects (roots at their PC path with guestWorkspace "mirror").
+// Pure functions only: used by the host (registration, commands), the guest (daemon checks) and the tests.
+import path from 'node:path';
+import { isValidGuestPath } from './guest-paths.js';
+/** Where roots, boot-mapped projects and shared folders appear inside the sandbox. */
+export const PROJECTS_GUEST = 'C:\\Projects';
+const norm = (p) => path.win32.resolve(p).replace(/[\\/]+$/, '').toLowerCase();
+/** `child` is `parent` or somewhere below it (Windows paths, case-insensitive). */
+export const isWithin = (parent, child) => {
+    const a = norm(parent);
+    const b = norm(child);
+    return a === b || b.startsWith(a.endsWith('\\') ? a : a + '\\');
+};
+/**
+ * A project id (also its folder name under C:\Projects) for a folder: its name with only letters, digits, '-' and
+ * '_' (ids become file names on both sides), at most 48 characters, made unique against `taken` with -2, -3, ...
+ */
+export const hubName = (hostDir, taken) => {
+    const base = path.win32.basename(path.win32.resolve(hostDir)).replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'project';
+    const used = new Set([...taken].map((t) => t.toLowerCase()));
+    if (!used.has(base.toLowerCase()))
+        return base;
+    for (let i = 2;; i++)
+        if (!used.has((base + '-' + i).toLowerCase()))
+            return base + '-' + i;
+};
+/** The project a folder on this PC belongs to: the most specific one that contains it (a project inside another wins). */
+export const projectForHostDir = (projects, hostDir) => projects.filter((p) => isWithin(p.host, hostDir)).sort((a, b) => b.host.length - a.host.length)[0] ?? null;
+/** The same for a folder inside the sandbox. */
+export const projectForGuestDir = (projects, guestDir) => projects.filter((p) => isWithin(p.guest, guestDir)).sort((a, b) => b.guest.length - a.guest.length)[0] ?? null;
+/** Where a folder on this PC appears inside the sandbox, given the mapped folder (project or root) that contains it. */
+export const guestDirFor = (mapped, hostDir) => {
+    const rel = path.win32.relative(path.win32.resolve(mapped.host), path.win32.resolve(hostDir));
+    return rel ? path.win32.join(mapped.guest, rel) : mapped.guest;
+};
+/** The other way: where a folder inside the sandbox is on this PC, given the mapped folder that contains it. */
+export const hostDirFor = (mapped, guestDir) => {
+    const rel = path.win32.relative(path.win32.resolve(mapped.guest), path.win32.resolve(guestDir));
+    return rel ? path.win32.join(mapped.host, rel) : mapped.host;
+};
+/** Strictly below `parent` (never `parent` itself). */
+export const isBelow = (parent, child) => isWithin(parent, child) && norm(parent) !== norm(child);
+/** A guest folder some project can be in: below C:\Projects, or inside one of the roots (their guest paths). */
+export const insideProjects = (guestDir, roots = [], projectsDir = PROJECTS_GUEST) => isBelow(projectsDir, guestDir) || roots.some((r) => isWithin(r, guestDir));
+/**
+ * Guest folders for the project roots and the projects mapped at boot: C:\Projects\<name>, unique; with
+ * guestWorkspace "mirror" a root appears at its PC path when the sandbox can show it there.
+ */
+export const planProjectMappings = (roots, projects, mirror, taken = []) => {
+    const names = [...taken];
+    const place = (host, tryMirror) => {
+        const resolved = path.win32.resolve(host).replace(/[\\/]+$/, '');
+        if (tryMirror && isValidGuestPath(resolved) && !isWithin(PROJECTS_GUEST, resolved))
+            return { host: resolved, guest: resolved };
+        const name = hubName(resolved, names);
+        names.push(name);
+        return { host: resolved, guest: path.win32.join(PROJECTS_GUEST, name) };
+    };
+    return { roots: roots.map((r) => place(r, mirror)), projects: projects.map((p) => place(p, false)) };
+};

package/dist/shared/pty-client.d.ts

@@ -0,0 +1,86 @@
+import net from 'node:net';
+export declare const FrameType: {
+    readonly Hello: 1;
+    readonly Input: 2;
+    readonly Resize: 3;
+    readonly Restart: 4;
+    readonly Ping: 5;
+    readonly Output: 16;
+    readonly Exit: 17;
+    readonly Error: 18;
+    readonly Restarting: 19;
+    readonly Status: 20;
+};
+/** HELLO flags: control-only connections get no output and never size the console; a query only asks for STATUS. */
+export declare const HelloFlag: {
+    readonly ControlOnly: 1;
+    readonly Query: 2;
+};
+/** Viewers ping this often; ptyhost counts a viewer as gone after 15 s of silence (e.g. its terminal tab was closed). */
+export declare const PING_INTERVAL_MS = 5000;
+export interface Frame {
+    type: number;
+    payload: Buffer;
+}
+export interface Endpoint {
+    addresses: string[];
+    port: number;
+    token: string;
+}
+export type ClientResult = {
+    reason: 'exit';
+    exitCode: number;
+} | {
+    reason: 'detach' | 'closed';
+} | {
+    reason: 'error';
+    message: string;
+};
+/** Ctrl+] — the same detach key telnet uses; Claude Code does not bind it. */
+export declare const DETACH_KEY = 29;
+export declare const encodeFrame: (type: number, payload?: Buffer) => Buffer;
+export declare const helloFrame: (token: string, cols: number, rows: number, flags?: number) => Buffer;
+export declare const resizeFrame: (cols: number, rows: number) => Buffer;
+/** Same limit as ptyhost.cs; a peer announcing more is broken or hostile. */
+export declare const MAX_FRAME_BYTES: number;
+/** Splits a TCP byte stream back into frames. */
+export declare class FrameReader {
+    private pending;
+    push(chunk: Buffer): Frame[];
+}
+/**
+ * Removes OSC 52 (clipboard write) from the sandbox's output before it reaches your terminal: an untrusted program
+ * must not be able to silently put text into your clipboard. Everything else (colours, titles, links) passes.
+ * Stateful, so a sequence split across chunks is still caught.
+ */
+export declare class OutputFilter {
+    private carry;
+    push(chunk: Buffer): Buffer;
+}
+/** Tries every address the sandbox published and returns the first one that answers. */
+export declare const connect: (endpoint: Endpoint, timeoutMs?: number) => Promise<net.Socket>;
+/** Sends one control frame (e.g. RESTART) without taking over the screen. */
+export declare const sendControl: (endpoint: Endpoint, type: number) => Promise<void>;
+/** Who is watching a session right now: `remote` counts viewers on the PC (not the sandbox's own tabs). */
+export interface Viewers {
+    viewers: number;
+    remote: number;
+}
+/**
+ * Asks a session's ptyhost who is attached. Only viewers heard from in the last few seconds count, so a terminal that
+ * was closed (or a PC that went to sleep) is not reported. null when the session does not answer: an older ptyhost
+ * treats the query as a silent control connection, so the caller must not assume anything.
+ */
+export declare const queryViewers: (endpoint: Endpoint, timeoutMs?: number) => Promise<Viewers | null>;
+/**
+ * Node on Windows reads keys through the console API, where Backspace is ^H and Ctrl+Backspace is DEL: the reverse of
+ * what terminals send. ConPTY reads ^H as Ctrl+Backspace (delete a word), so swap them back.
+ */
+export declare const fixWindowsKeys: (chunk: Buffer) => Buffer;
+/**
+ * Bridges this process's terminal to the remote program until it exits, the connection drops, or the user presses
+ * the detach key. Restores the terminal before resolving.
+ */
+export declare const runTerminalClient: (socket: net.Socket, token: string, options?: {
+    detachKey?: number;
+}) => Promise<ClientResult>;