windows-development-sandbox 1.13.2 → 1.15.0

package/dist/selftest/web.test.js

@@ -9,7 +9,7 @@ import { cancelled } from '../app/kernel/index.js';
 import { webSession } from '../cli/services/index.js';
 import { fail } from '../core/util/index.js';
 import { cookieValue, csrfOk, hostAllowed, LiveHub, originAllowed, sameSecret, StaticFiles, WebAuth, WebServer, WebStore, } from '../host/web/index.js';
-import { encodeFrame, FrameReader, FrameType } from '../shared/pty/index.js';
+import { encodeFrame, FrameReader, FrameType, MOUSE_OFF } from '../shared/pty/index.js';
 import { CSRF_HEADER, CSRF_VALUE, parseClientMessage } from '../shared/web/index.js';
 const TOKEN = 'a'.repeat(64);
 const ATTACH_TOKEN = 'SECRET-ATTACH-TOKEN';
@@ -249,7 +249,7 @@ export const webSuite = {
         }
         t.section('an unused server ends by itself (no process left behind)');
         {
-            const idleServer = async (sandbox, limits) => {
+            const idleServer = async (sandbox, limits, sleepMs = 0) => {
                 let ended = false;
                 const idle = new WebServer({
                     port: 0,
@@ -272,6 +272,16 @@ export const webSuite = {
                     onStop: () => (ended = true),
                 });
                 await idle.start();
+                if (sleepMs) {
+                    // The PC "sleeps": no timer runs, then the overdue check fires at once on waking.
+                    const until = Date.now() + sleepMs;
+                    while (Date.now() < until)
+                        ;
+                    await new Promise((r) => setTimeout(r, 20));
+                    const endedOnWaking = ended;
+                    await idle.stop();
+                    return endedOnWaking;
+                }
                 await new Promise((r) => setTimeout(r, 1500));
                 await idle.stop();
                 return ended;
@@ -279,6 +289,7 @@ export const webSuite = {
             t.check(await idleServer('stopped', { exit: 60_000, quiet: 200 }), 'no browser and no sandbox: it ends after the short wait');
             t.check(!(await idleServer('running', { exit: 60_000, quiet: 200 })), 'a sandbox runs: the short wait does not end it');
             t.check(await idleServer('running', { exit: 300, quiet: 200 }), 'no browser for the long wait: it ends even while a sandbox runs');
+            t.check(!(await idleServer('stopped', { exit: 60_000, quiet: 200 }, 1200)), 'after the PC slept, it does not end on waking: open pages get time to reconnect');
         }
         t.section('the server');
         const fake = new FakePtyHost();
@@ -373,6 +384,7 @@ export const webSuite = {
             tab.socket.send(Buffer.from('x'));
             await t.waitFor(() => tab.closeCode !== null, 5000);
             t.check(tab.texts.includes('{"t":"exit","code":3}'), 'EXIT reaches the browser with its code');
+            t.check(Buffer.concat(tab.binary).toString('latin1').endsWith(MOUSE_OFF), "before it, the browser's terminal is told to stop tracking the mouse (a drag selects text again)");
             t.equal(tab.closeCode, 1000, 'and the socket closes cleanly');
             const rude = new Tab(url, { Origin: origin, Cookie });
             await t.waitFor(() => rude.binary.length > 0, 5000);

package/dist/shared/channel/index.d.ts

@@ -1,3 +1,4 @@
 export * from './schema.js';
 export * from './run-dir.js';
 export * from './secrets.js';
+export * from './live.js';

package/dist/shared/channel/index.js

@@ -1,3 +1,4 @@
 export * from './schema.js';
 export * from './run-dir.js';
 export * from './secrets.js';
+export * from './live.js';

package/dist/shared/channel/live.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+/** This tool's vSMB share names: never the 64-hex names Windows Sandbox gives its own shares. */
+export declare const LIVE_SHARE_NAME: RegExp;
+/** A folder name under C:\Workspace: no dots or spaces, so no "..", "foo." or "foo " aliases of other folders. */
+export declare const LIVE_FOLDER_NAME: RegExp;
+export declare const LIVE_KEY: RegExp;
+export declare const LIVE_TOKEN: RegExp;
+/** How old (or how far in the future) a request may be, by the guest's clock. */
+export declare const LIVE_MAX_AGE_MS: number;
+export declare const LivePayloadSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    kind: z.ZodEnum<{
+        map: "map";
+        canary: "canary";
+        unmap: "unmap";
+    }>;
+    id: z.ZodString;
+    launchId: z.ZodString;
+    share: z.ZodOptional<z.ZodString>;
+    folder: z.ZodString;
+    readOnly: z.ZodBoolean;
+    createdAt: z.ZodString;
+}, z.core.$strict>;
+export type LivePayload = z.output<typeof LivePayloadSchema>;
+export declare const LiveEnvelopeSchema: z.ZodObject<{
+    payload: z.ZodString;
+    mac: z.ZodString;
+}, z.core.$strict>;
+export type LiveEnvelope = z.output<typeof LiveEnvelopeSchema>;
+/** run\live-replies\<id>.json (guest-written: checked, capped; the host only ever compares the token). */
+export declare const LiveReplySchema: z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodBoolean;
+    message: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+    finishedAt: z.ZodString;
+}, z.core.$strict>;
+export type LiveReply = z.output<typeof LiveReplySchema>;
+/** A signed request for `payload` (host side). */
+export declare function signLive(key: string, payload: LivePayload): LiveEnvelope;
+/** Why a request is refused (guest side), or the payload it carries. */
+export declare function openLive(key: string | null, envelope: unknown, o: {
+    launchId: string;
+    now: number;
+}): {
+    payload: LivePayload;
+} | {
+    refused: string;
+};
+/** A new random share name (host side). */
+export declare function newShareName(): string;
+/** A new launch key (host side). */
+export declare function newLiveKey(): string;

package/dist/shared/channel/live.js

@@ -0,0 +1,92 @@
+// Live folders through HCS (opt-in alpha, docs/design/hcs-live-folders.md): the host -> guest messages that make a
+// folder the host shared into the running sandbox appear at C:\Workspace\<name>. Requests go in run\live, replies in
+// run\live-replies. Every request is signed: {payload: "<the JSON text>", mac: HMAC-SHA256(key, payload)}; the MAC is
+// over the exact payload text, never over a re-serialised object. The key is made per launch, travels to the sandbox
+// only in the one-shot secrets file (other users of a shared sandbox may write run\, never secrets\) and is kept on the
+// host sealed with DPAPI. The agent is an administrator in the sandbox, so it can read the key there: the signature
+// keeps other users and stale or replayed files from driving the daemon, and the real boundary is that only the host
+// decides what is shared (a guest can only show or hide what it was given).
+import crypto from 'node:crypto';
+import { z } from 'zod';
+import { IdSchema } from './schema.js';
+/** This tool's vSMB share names: never the 64-hex names Windows Sandbox gives its own shares. */
+export const LIVE_SHARE_NAME = /^agentsbx-[0-9a-f]{8,32}$/;
+/** A folder name under C:\Workspace: no dots or spaces, so no "..", "foo." or "foo " aliases of other folders. */
+export const LIVE_FOLDER_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export const LIVE_KEY = /^[0-9a-f]{64}$/;
+export const LIVE_TOKEN = /^[0-9a-f]{32}$/;
+/** How old (or how far in the future) a request may be, by the guest's clock. */
+export const LIVE_MAX_AGE_MS = 2 * 60 * 1000;
+const MAX_PAYLOAD = 4096;
+export const LivePayloadSchema = z.strictObject({
+    v: z.literal(1),
+    /** canary: show the share, read token.txt, hide it again and reply with the token; map / unmap: the real folder. */
+    kind: z.enum(['canary', 'map', 'unmap']),
+    id: IdSchema,
+    launchId: z.string().min(1).max(64),
+    share: z.string().regex(LIVE_SHARE_NAME).optional(),
+    folder: z.string().regex(LIVE_FOLDER_NAME),
+    readOnly: z.boolean(),
+    createdAt: z.string().max(64),
+});
+export const LiveEnvelopeSchema = z.strictObject({
+    payload: z.string().min(2).max(MAX_PAYLOAD),
+    mac: z.string().regex(/^[0-9a-f]{64}$/),
+});
+/** run\live-replies\<id>.json (guest-written: checked, capped; the host only ever compares the token). */
+export const LiveReplySchema = z.strictObject({
+    id: IdSchema,
+    ok: z.boolean(),
+    message: z.string().max(1000),
+    token: z.string().regex(LIVE_TOKEN).optional(),
+    finishedAt: z.string().max(64),
+});
+function mac(key, payload) {
+    return crypto.createHmac('sha256', Buffer.from(key, 'hex')).update(payload, 'utf8').digest('hex');
+}
+/** A signed request for `payload` (host side). */
+export function signLive(key, payload) {
+    if (!LIVE_KEY.test(key))
+        throw new Error('not a live-folder key');
+    const text = JSON.stringify(LivePayloadSchema.parse(payload));
+    return { payload: text, mac: mac(key, text) };
+}
+/** Why a request is refused (guest side), or the payload it carries. */
+export function openLive(key, envelope, o) {
+    if (!key || !LIVE_KEY.test(key))
+        return { refused: 'no live-folder key (live folders were off when the sandbox started)' };
+    const env = LiveEnvelopeSchema.safeParse(envelope);
+    if (!env.success)
+        return { refused: 'not a live-folder request' };
+    const want = Buffer.from(mac(key, env.data.payload), 'hex');
+    const got = Buffer.from(env.data.mac, 'hex');
+    if (want.length !== got.length || !crypto.timingSafeEqual(want, got))
+        return { refused: 'the signature does not match' };
+    let json;
+    try {
+        json = JSON.parse(env.data.payload);
+    }
+    catch {
+        return { refused: 'the signed payload is not JSON' };
+    }
+    const parsed = LivePayloadSchema.safeParse(json);
+    if (!parsed.success)
+        return { refused: 'the signed payload has the wrong shape' };
+    const p = parsed.data;
+    if (p.launchId !== o.launchId)
+        return { refused: 'it is for another launch' };
+    const at = Date.parse(p.createdAt);
+    if (!Number.isFinite(at) || Math.abs(o.now - at) > LIVE_MAX_AGE_MS)
+        return { refused: 'it is too old' };
+    if (p.kind !== 'unmap' && !p.share)
+        return { refused: 'it names no share' };
+    return { payload: p };
+}
+/** A new random share name (host side). */
+export function newShareName() {
+    return 'agentsbx-' + crypto.randomBytes(8).toString('hex');
+}
+/** A new launch key (host side). */
+export function newLiveKey() {
+    return crypto.randomBytes(32).toString('hex');
+}

package/dist/shared/channel/run-dir.d.ts

@@ -17,12 +17,23 @@ export declare class RunDir {
     readonly projectsDir: string;
     /** audit.processes: programs the sandbox started, in small .jsonl files the host takes in and deletes. */
     readonly auditDir: string;
+    /**
+     * Each running session's process tree, recorded by its ptyhost (guest only: the daemon ends what a ptyhost that was
+     * itself ended left running).
+     */
+    readonly treesDir: string;
     /** One-shot secrets the host hands over (see secrets.ts). Next to run, not in it: shared-use users can change run. */
     readonly secretsDir: string;
+    /** Live folders (live.ts): signed host requests, and the daemon's replies. */
+    readonly liveDir: string;
+    readonly liveRepliesDir: string;
     constructor(dataDir: string);
+    liveFile(id: string): string;
+    liveReplyFile(id: string): string;
     requestFile(id: string): string;
     responseFile(id: string): string;
     sessionFile(id: string): string;
+    treeFile(id: string): string;
     projectFile(name: string): string;
     secretFile(id: string): string;
     readSandboxStatus(): SandboxStatus | null;

package/dist/shared/channel/run-dir.js

@@ -44,8 +44,16 @@ export class RunDir {
     projectsDir;
     /** audit.processes: programs the sandbox started, in small .jsonl files the host takes in and deletes. */
     auditDir;
+    /**
+     * Each running session's process tree, recorded by its ptyhost (guest only: the daemon ends what a ptyhost that was
+     * itself ended left running).
+     */
+    treesDir;
     /** One-shot secrets the host hands over (see secrets.ts). Next to run, not in it: shared-use users can change run. */
     secretsDir;
+    /** Live folders (live.ts): signed host requests, and the daemon's replies. */
+    liveDir;
+    liveRepliesDir;
     constructor(dataDir) {
         this.root = path.join(dataDir, 'run');
         this.sandboxFile = path.join(this.root, 'sandbox.json');
@@ -57,7 +65,16 @@ export class RunDir {
         this.sessionsDir = path.join(this.root, 'sessions');
         this.projectsDir = path.join(this.root, 'projects');
         this.auditDir = path.join(this.root, 'audit');
+        this.treesDir = path.join(this.root, 'trees');
         this.secretsDir = path.join(dataDir, 'secrets');
+        this.liveDir = path.join(this.root, 'live');
+        this.liveRepliesDir = path.join(this.root, 'live-replies');
+    }
+    liveFile(id) {
+        return path.join(this.liveDir, safeId(id) + '.json');
+    }
+    liveReplyFile(id) {
+        return path.join(this.liveRepliesDir, safeId(id) + '.json');
     }
     requestFile(id) {
         return path.join(this.requestsDir, safeId(id) + '.json');
@@ -68,6 +85,9 @@ export class RunDir {
     sessionFile(id) {
         return path.join(this.sessionsDir, safeId(id) + '.json');
     }
+    treeFile(id) {
+        return path.join(this.treesDir, safeId(id) + '.json');
+    }
     projectFile(name) {
         return path.join(this.projectsDir, safeId(name) + '.json');
     }

package/dist/shared/channel/secrets.d.ts

@@ -10,6 +10,7 @@ export declare const SecretsFileSchema: z.ZodObject<{
     }, z.core.$strict>>;
     wireguardConfig: z.ZodOptional<z.ZodString>;
     githubToken: z.ZodOptional<z.ZodString>;
+    liveFoldersKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type SecretsFile = z.output<typeof SecretsFileSchema>;
 interface WithHarnesses {

package/dist/shared/channel/secrets.js

@@ -28,6 +28,11 @@ export const SecretsFileSchema = z.strictObject({
         .optional(),
     /** The GitHub token you saved for sandboxes (github.shareToken), only with git access "full". */
     githubToken: GithubTokenSchema.optional(),
+    /** projects.liveFolders "hcs": this launch's key for signed live-folder requests (live.ts). */
+    liveFoldersKey: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .optional(),
 });
 /** The environment a harness gets: its own, then the values that travelled in the secrets file. */
 const withEnvironment = (harness, environment) => (environment ? { ...harness, environment: { ...harness.environment, ...environment } } : harness);

package/dist/shared/paths/projects.d.ts

@@ -11,7 +11,7 @@ export declare const WORKSPACES_GUEST = "C:\\Workspace";
  */
 export declare function autoGuestFolder(hostDir: string): string;
 /** How a project got into the sandbox. */
-export type Mechanism = 'launch' | 'root' | 'boot' | 'wsb';
+export type Mechanism = 'launch' | 'root' | 'boot' | 'wsb' | 'hcs';
 /** One project the running sandbox works on. */
 export interface ProjectEntry {
     name: string;
@@ -65,6 +65,11 @@ export declare function usableRoots(roots: string[], exists: (dir: string) => bo
  * when the sandbox can show it there, else C:\Workspace\<name>. -2, -3, ... when that overlaps a folder in `taken`.
  */
 export declare function ownGuestFolder(hostDir: string, mirror: boolean, taken?: string[]): string;
+/**
+ * Where a live folder (projects.liveFolders "hcs") appears: C:\Workspace\<name>, the name in the strict form the guest
+ * daemon accepts (lower-case letters, digits, '-' and '_'; no dots or spaces), -2, -3, ... when it overlaps `taken`.
+ */
+export declare function liveGuestFolder(hostDir: string, taken?: string[]): string;
 /**
  * Guest folders for the project roots (C:\Projects\<name>, unique; with guestWorkspace "mirror" at its PC path when
  * the sandbox can show it there) and the projects mapped at boot (ownGuestFolder, unique against `taken` and each

package/dist/shared/paths/projects.js

@@ -4,7 +4,8 @@
 //  - 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).
+//  - a folder shared into the running sandbox with `wsb share` (Windows 11 24H2+, untested);
+//  - a folder shared into the running sandbox through HCS (projects.liveFolders "hcs", alpha, untested on a PC).
 // A project is at the same place inside the sandbox whichever project started it (git worktrees and Claude's project
 // folders store absolute paths):
 //  - a project inside a root is always under the root's folder, C:\Projects\<root>\<name> (also as the launch folder);
@@ -115,6 +116,25 @@ export function ownGuestFolder(hostDir, mirror, taken = []) {
         if (free(base + '-' + i))
             return base + '-' + i;
 }
+/**
+ * Where a live folder (projects.liveFolders "hcs") appears: C:\Workspace\<name>, the name in the strict form the guest
+ * daemon accepts (lower-case letters, digits, '-' and '_'; no dots or spaces), -2, -3, ... when it overlaps `taken`.
+ */
+export function liveGuestFolder(hostDir, taken = []) {
+    const base = path.win32
+        .basename(resolveDir(hostDir))
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/^[-_]+|-+$/g, '')
+        .slice(0, 56) || 'project';
+    const free = (guest) => !taken.some((t) => isWithin(t, guest) || isWithin(guest, t));
+    const at = (name) => WORKSPACES_GUEST + '\\' + name;
+    if (free(at(base)))
+        return at(base);
+    for (let i = 2;; i++)
+        if (free(at(base + '-' + i)))
+            return at(base + '-' + i);
+}
 /**
  * Guest folders for the project roots (C:\Projects\<name>, unique; with guestWorkspace "mirror" at its PC path when
  * the sandbox can show it there) and the projects mapped at boot (ownGuestFolder, unique against `taken` and each

package/dist/shared/pty/index.d.ts

@@ -1,6 +1,8 @@
 export { FrameType, HelloFlag, PING_INTERVAL_MS, type Frame, DETACH_KEY, encodeFrame, helloFrame, resizeFrame, MAX_FRAME_BYTES, FrameReader, } from './protocol.js';
 export { type Endpoint, connect, sendControl, type Viewers, queryViewers } from './client.js';
-export { type ClientResult, MOUSE_OFF, fixWindowsKeys, runTerminalClient } from './terminal.js';
+export { type ClientResult, MOUSE_OFF, runTerminalClient } from './terminal.js';
+export { fixWindowsKeys, KeyGate } from './key-gate.js';
+export { MouseModes } from './mouse-modes.js';
 export { JOIN_MS, InputJoiner } from './input-joiner.js';
 export { CTRL_C_CONFIRM_MS, CTRL_C_HINT, CtrlCGuard } from './ctrl-c.js';
 export { type VtInput, enableVtInput } from './console-input.js';

package/dist/shared/pty/index.js

@@ -1,6 +1,8 @@
 export { FrameType, HelloFlag, PING_INTERVAL_MS, DETACH_KEY, encodeFrame, helloFrame, resizeFrame, MAX_FRAME_BYTES, FrameReader, } from './protocol.js';
 export { connect, sendControl, queryViewers } from './client.js';
-export { MOUSE_OFF, fixWindowsKeys, runTerminalClient } from './terminal.js';
+export { MOUSE_OFF, runTerminalClient } from './terminal.js';
+export { fixWindowsKeys, KeyGate } from './key-gate.js';
+export { MouseModes } from './mouse-modes.js';
 export { JOIN_MS, InputJoiner } from './input-joiner.js';
 export { CTRL_C_CONFIRM_MS, CTRL_C_HINT, CtrlCGuard } from './ctrl-c.js';
 export { enableVtInput } from './console-input.js';

package/dist/shared/pty/key-gate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 function fixWindowsKeys(chunk: Buffer): Buffer;
+/**
+ * Typed input before the console's mode is settled. Once ENABLE_VIRTUAL_TERMINAL_INPUT is on (enableVtInput), the
+ * console hands over the terminal's own bytes (DEL for Backspace, ^H for Ctrl+Backspace) and nothing may be swapped;
+ * only when it could not be turned on are keys read as console key records and swapped (fixWindowsKeys). Turning it
+ * on takes a moment (a PowerShell helper), and input read meanwhile used to be swapped although it was the terminal's
+ * own: a Backspace pressed then reached the agent as ^H and deleted a word. So input waits here until the mode is
+ * known.
+ */
+export declare class KeyGate {
+    private pending;
+    private decided;
+    private swap;
+    /** windowsConsole: input comes from a Windows console in raw mode (its mode is decided later); else it goes as is. */
+    constructor(windowsConsole: boolean);
+    /** The bytes to send now (empty while the mode is not known yet). */
+    push(data: Buffer): Buffer;
+    /** The console's mode is known: what was held, ready to send. Later calls only change how new input is read. */
+    decide(vtInput: boolean): Buffer;
+}

package/dist/shared/pty/key-gate.js

@@ -0,0 +1,45 @@
+// Windows: holds what you type until the client knows how the console hands keys over, so Backspace stays Backspace.
+/**
+ * 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 function fixWindowsKeys(chunk) {
+    if (!chunk.includes(0x08) && !chunk.includes(0x7f))
+        return chunk;
+    return Buffer.from(chunk.map((b) => (b === 0x08 ? 0x7f : b === 0x7f ? 0x08 : b)));
+}
+/**
+ * Typed input before the console's mode is settled. Once ENABLE_VIRTUAL_TERMINAL_INPUT is on (enableVtInput), the
+ * console hands over the terminal's own bytes (DEL for Backspace, ^H for Ctrl+Backspace) and nothing may be swapped;
+ * only when it could not be turned on are keys read as console key records and swapped (fixWindowsKeys). Turning it
+ * on takes a moment (a PowerShell helper), and input read meanwhile used to be swapped although it was the terminal's
+ * own: a Backspace pressed then reached the agent as ^H and deleted a word. So input waits here until the mode is
+ * known.
+ */
+export class KeyGate {
+    pending = [];
+    decided;
+    swap = false;
+    /** windowsConsole: input comes from a Windows console in raw mode (its mode is decided later); else it goes as is. */
+    constructor(windowsConsole) {
+        this.decided = !windowsConsole;
+    }
+    /** The bytes to send now (empty while the mode is not known yet). */
+    push(data) {
+        if (!data.length)
+            return data;
+        if (!this.decided) {
+            this.pending.push(data);
+            return Buffer.alloc(0);
+        }
+        return this.swap ? fixWindowsKeys(data) : data;
+    }
+    /** The console's mode is known: what was held, ready to send. Later calls only change how new input is read. */
+    decide(vtInput) {
+        this.swap = !vtInput;
+        this.decided = true;
+        const held = Buffer.concat(this.pending);
+        this.pending = [];
+        return this.swap ? fixWindowsKeys(held) : held;
+    }
+}

package/dist/shared/pty/mouse-modes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Follows the private modes a program turns on and off in its output (DECSET / DECRST, kept across chunks: mouse
+ * tracking 9, 1000, 1002, 1003, the encodings 1005 and 1015, bracketed paste 2004 ...) and drops the mouse reports it
+ * did not ask for: none without tracking, motion only with 1002 (while a button is held: a drag) or 1003 (every move).
+ * Your terminal reports what the program's modes say; what is dropped is what was still on its way when the program
+ * turned tracking off, exited or restarted, and would reach it as text.
+ */
+export declare class MouseModes {
+    private readonly on;
+    /** 0 text, 1 after ESC, 2 after ESC[, 3 in ESC[? parameters, 4 after ESC[! */
+    private state;
+    private params;
+    /** Reads the program's output (after OutputFilter): the mode changes in it. */
+    watch(output: Buffer): void;
+    /** The program is gone (exited or restarting): its modes went with it. */
+    reset(): void;
+    /** True while the program tracks the mouse in any way. */
+    tracking(): boolean;
+    /** True while the program has a mode on (2004: bracketed paste). */
+    has(mode: number): boolean;
+    /** The mode numbers on now (for the report and tests). */
+    modes(): number[];
+    /** `input` without the mouse reports the program has not asked for. Sequences must be whole (InputJoiner). */
+    filter(input: Buffer): Buffer;
+    private allows;
+    private apply;
+}

package/dist/shared/pty/mouse-modes.js

@@ -0,0 +1,155 @@
+// The mouse tracking a program asked for, read from its output, and the mouse reports it may receive.
+/** X10 compatibility (press only), normal (press/release/wheel), button-event (+ drag), any-event (+ every motion). */
+const TRACKING = [9, 1000, 1002, 1003];
+/** Longest DECSET / DECRST parameter list followed; anything longer is not a mode change. */
+const MAX_PARAMS = 64;
+/** Button code bits of a mouse report: motion (drag or move), and "no button" in the low two bits. */
+const MOTION = 32;
+const NO_BUTTON = 3;
+/**
+ * Follows the private modes a program turns on and off in its output (DECSET / DECRST, kept across chunks: mouse
+ * tracking 9, 1000, 1002, 1003, the encodings 1005 and 1015, bracketed paste 2004 ...) and drops the mouse reports it
+ * did not ask for: none without tracking, motion only with 1002 (while a button is held: a drag) or 1003 (every move).
+ * Your terminal reports what the program's modes say; what is dropped is what was still on its way when the program
+ * turned tracking off, exited or restarted, and would reach it as text.
+ */
+export class MouseModes {
+    on = new Set();
+    /** 0 text, 1 after ESC, 2 after ESC[, 3 in ESC[? parameters, 4 after ESC[! */
+    state = 0;
+    params = '';
+    /** Reads the program's output (after OutputFilter): the mode changes in it. */
+    watch(output) {
+        for (const b of output) {
+            if (b === 0x1b) {
+                this.state = 1;
+                continue;
+            }
+            if (this.state === 1) {
+                // RIS (ESC c), a full reset, turns every mode off.
+                if (b === 0x63)
+                    this.on.clear();
+                this.state = b === 0x5b ? 2 : 0;
+            }
+            else if (this.state === 2) {
+                // DECSTR (ESC[!p), a soft reset, turns mouse tracking off too.
+                this.state = b === 0x3f ? 3 : b === 0x21 ? 4 : 0;
+                this.params = '';
+            }
+            else if (this.state === 4) {
+                if (b === 0x70)
+                    this.on.clear();
+                this.state = 0;
+            }
+            else if (this.state === 3) {
+                if ((b >= 0x30 && b <= 0x39) || b === 0x3b) {
+                    this.params += String.fromCharCode(b);
+                    if (this.params.length > MAX_PARAMS)
+                        this.state = 0;
+                }
+                else {
+                    if (b === 0x68 || b === 0x6c)
+                        this.apply(this.params, b === 0x68);
+                    this.state = 0;
+                }
+            }
+        }
+    }
+    /** The program is gone (exited or restarting): its modes went with it. */
+    reset() {
+        this.on.clear();
+        this.state = 0;
+        this.params = '';
+    }
+    /** True while the program tracks the mouse in any way. */
+    tracking() {
+        return TRACKING.some((m) => this.on.has(m));
+    }
+    /** True while the program has a mode on (2004: bracketed paste). */
+    has(mode) {
+        return this.on.has(mode);
+    }
+    /** The mode numbers on now (for the report and tests). */
+    modes() {
+        return [...this.on].sort((a, b) => a - b);
+    }
+    /** `input` without the mouse reports the program has not asked for. Sequences must be whole (InputJoiner). */
+    filter(input) {
+        if (!input.includes(0x1b))
+            return input;
+        const parts = [];
+        let from = 0;
+        let i = input.indexOf(0x1b);
+        while (i !== -1) {
+            const report = mouseReport(input, i, this.on.has(1005), this.on.has(1015));
+            if (report && !this.allows(report.button)) {
+                parts.push(input.subarray(from, i));
+                from = i + report.length;
+                i = input.indexOf(0x1b, from);
+            }
+            else
+                i = input.indexOf(0x1b, i + 1);
+        }
+        if (from === 0)
+            return input;
+        parts.push(input.subarray(from));
+        return Buffer.concat(parts);
+    }
+    allows(button) {
+        if (!this.tracking())
+            return false;
+        if ((button & MOTION) === 0)
+            return true;
+        if (this.on.has(1003))
+            return true;
+        return this.on.has(1002) && (button & NO_BUTTON) !== NO_BUTTON;
+    }
+    apply(params, set) {
+        for (const p of params.split(';')) {
+            const mode = Number(p);
+            if (!p || !Number.isSafeInteger(mode))
+                continue;
+            if (set)
+                this.on.add(mode);
+            else
+                this.on.delete(mode);
+        }
+    }
+}
+/**
+ * The mouse report starting at `at`: SGR (ESC[<b;x;yM or m, 1006), urxvt (ESC[b;x;yM, 1015, b offset by 32; only while
+ * 1015 is on) or X10
+ * (ESC[M and three bytes; not with UTF-8 coordinates, 1005, where its length cannot be told). Null when there is none.
+ */
+function mouseReport(data, at, utf8, urxvt) {
+    if (data[at + 1] !== 0x5b)
+        return null;
+    const sgr = data[at + 2] === 0x3c;
+    if (sgr || (urxvt && data[at + 2] >= 0x30 && data[at + 2] <= 0x39)) {
+        let i = at + (sgr ? 3 : 2);
+        let digits = '';
+        let fields = 1;
+        for (; i < data.length && i - at < 32; i++) {
+            const b = data[i];
+            if (b >= 0x30 && b <= 0x39) {
+                if (fields === 1)
+                    digits += String.fromCharCode(b);
+            }
+            else if (b === 0x3b)
+                fields++;
+            else
+                break;
+        }
+        if (i >= data.length || fields !== 3 || !digits)
+            return null;
+        if (sgr ? data[i] !== 0x4d && data[i] !== 0x6d : data[i] !== 0x4d)
+            return null;
+        const button = Number(digits) - (sgr ? 0 : 32);
+        return button >= 0 ? { button, length: i - at + 1 } : null;
+    }
+    if (data[at + 2] === 0x4d && !utf8 && data.length - at >= 6) {
+        const button = data[at + 3] - 32;
+        return button >= 0 ? { button, length: 6 } : null;
+    }
+    return null;
+}

package/dist/shared/pty/terminal.d.ts

@@ -13,11 +13,6 @@ export type ClientResult = {
  * urxvt).
  */
 export declare const MOUSE_OFF = "\u001B[?1000l\u001B[?1002l\u001B[?1003l\u001B[?1005l\u001B[?1006l\u001B[?1015l";
-/**
- * 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 function 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.