windows-development-sandbox 1.1.0 → 1.4.1

package/dist/shared/guest-paths.js

@@ -2,6 +2,7 @@
 // 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.
+import { win32 } from 'node:path';
 /** 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>. */
@@ -31,6 +32,73 @@ export const isValidGuestPath = (guest) => {
         return !RESERVED_GUEST.test('C:\\' + rest);
     return MIRROR_LETTER.test(letter);
 };
+/** Where a mapping lands when the path it asks for (or the PC path) cannot be used inside the sandbox. */
+export const MAPPED_ROOT = 'C:\\Mapped';
+/** A guest path as typed, tidied: '/' -> '\', no doubled or trailing backslashes, upper-case drive letter. */
+export const tidyGuestPath = (guest) => {
+    const p = guest.trim().replace(/\//g, '\\').replace(/\\{2,}/g, '\\').replace(/\\+$/, '');
+    return /^[a-z]:/.test(p) ? p[0].toUpperCase() + p.slice(1) : p;
+};
+/** Why a guest path cannot be used as it is (null: it can). Short, plain English. */
+export const guestPathProblem = (guest) => {
+    if (isValidGuestPath(guest))
+        return null;
+    const letter = guestDrive(guest);
+    if (letter === 'C' && RESERVED_GUEST.test(guest))
+        return guest + ' is a folder the sandbox keeps for itself (Windows, Program Files, Users, AgentData, ...)';
+    if (letter && !MIRROR_LETTER.test(letter) && letter !== 'C')
+        return 'the sandbox cannot show drive ' + letter + ':';
+    if (letter && /^[A-Za-z]:\\?$/.test(guest))
+        return guest + ' is a whole drive';
+    return guest + ' is not a folder path the sandbox can use';
+};
+/** C:\Mapped\<drive>\<rest of path>: a safe place for a folder whose own path cannot be used (odd characters made safe). */
+export const mappedFallback = (path) => {
+    const m = /^([A-Za-z]):\\?(.*)$/.exec(tidyGuestPath(path)) ?? /^\\\\(.*)$/.exec(path);
+    const letter = m && m.length === 3 ? m[1].toUpperCase() : 'UNC';
+    const rest = (m ? m[m.length - 1] : path).split(/[\\/]+/).map((s) => s.replace(/[<>:"|?*\x00-\x1f]/g, '_').replace(/[. ]+$/, '')).filter((s) => s !== '' && s !== '..').join('\\');
+    return MAPPED_ROOT + '\\' + letter + (rest ? '\\' + rest : '');
+};
+/** Two guest folders overlap where they really are (F:\x is C:\Mirror\F\x): the same, or one inside the other. */
+export const guestOverlaps = (a, b) => {
+    const x = sandboxFolder(a).replace(/\\+$/, '').toLowerCase();
+    const y = sandboxFolder(b).replace(/\\+$/, '').toLowerCase();
+    return x === y || x.startsWith(y + '\\') || y.startsWith(x + '\\');
+};
+/**
+ * Where an extra folder appears in the sandbox. `wanted` is the guest path asked for (or the one derived from the PC
+ * path); when the sandbox cannot use it (reserved, invalid, or overlapping a folder in `taken`), the folder goes to
+ * C:\Mapped\<drive>\<path> instead (made unique with -2, -3 ...), and `note` says where and why.
+ */
+export const placeGuest = (host, wanted, taken) => {
+    const clash = (g) => taken.find((t) => guestOverlaps(g, t.guest));
+    const tidy = tidyGuestPath(wanted);
+    const problem = guestPathProblem(tidy);
+    const other = problem ? null : clash(tidy);
+    if (!problem && !other)
+        return { guest: tidy, note: null };
+    const why = problem ?? tidy + ' is already used by ' + other.what + (other.guest.toLowerCase() === tidy.toLowerCase() ? '' : ' (' + other.guest + ')');
+    const guest = freePlace(mappedFallback(/^[A-Za-z]:/.test(tidy) ? tidy : host), clash);
+    return { guest, note: host + ': ' + why + ', so it is at ' + guest + ' in the sandbox.' };
+};
+/**
+ * The guest path a mapping asks for when it gives none: a folder inside the project at the same place in the project's
+ * guest folder, any other folder at the same path as on this PC (D: to Z: through C:\Mirror and subst).
+ */
+export const deriveGuest = (host, projectHost, projectGuest) => {
+    const rel = win32.relative(win32.resolve(projectHost), win32.resolve(host));
+    const inside = rel === '' || (!rel.startsWith('..') && !win32.isAbsolute(rel));
+    return inside ? (rel ? win32.join(projectGuest, rel) : projectGuest) : tidyGuestPath(win32.resolve(host));
+};
+const freePlace = (base, clash) => {
+    const ok = (g) => isValidGuestPath(g) && !clash(g);
+    if (ok(base))
+        return base;
+    for (let i = 2; i < 1000; i++)
+        if (ok(base + '-' + i))
+            return base + '-' + i;
+    return base + '-' + Date.now();
+};
 /** 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);

package/dist/shared/netpolicy.d.ts

@@ -0,0 +1,27 @@
+/** A host name or a "*.example.com" pattern (lower case, no scheme, no port). */
+export declare const HOST_PATTERN: RegExp;
+/**
+ * What "@developer" stands for in allowOnly: package registries, source hosts, toolchain downloads and the AI
+ * providers the agents talk to. Enough for an agent to install dependencies, push to GitHub and reach its model.
+ */
+export declare const DEVELOPER_HOSTS: string[];
+/** The allowOnly list with "@developer" expanded, lower case, without duplicates. */
+export declare const expandAllowList: (list: string[]) => string[];
+/** Does `host` match one of the patterns? "*.example.com" matches its subdomains (not example.com itself). */
+export declare const hostAllowed: (host: string, patterns: string[]) => boolean;
+export declare const HOSTS_BEGIN = "# >>> windows-development-sandbox network.blockHosts";
+export declare const HOSTS_END = "# <<< windows-development-sandbox network.blockHosts";
+/** The hosts file with our block section replaced by `hosts` (each sent to 0.0.0.0 and ::); everything else stays. */
+export declare const withBlockedHosts: (hostsFile: string, hosts: string[]) => string;
+/** One forwarded port: <pc> on this PC (localhost only) reaches <sandbox> inside. */
+export interface PortForward {
+    pc: number;
+    sandbox: number;
+}
+/**
+ * The port the sandbox's relay for forward `index` listens on (it connects on to localhost:<sandbox> inside, so a
+ * server that only listens on localhost is reachable too). Out of the range Windows hands out for outgoing connections.
+ */
+export declare const relayPort: (index: number) => number;
+/** The address the sandbox's built-in proxy listens on (allowOnly). */
+export declare const PROXY_PORT = 38080;

package/dist/shared/netpolicy.js

@@ -0,0 +1,51 @@
+// The network settings as rules: which hosts the sandbox may reach (network.allowOnly), which never (blockHosts), and
+// the ports forwarded from this PC into the sandbox. Pure (tested); the guest applies them (guest/setup/network.ts,
+// guest/netproxy.ts) and the host runs the forwarders (host/port-forward.ts).
+/** A host name or a "*.example.com" pattern (lower case, no scheme, no port). */
+export const HOST_PATTERN = /^(\*\.)?([a-z0-9-]+\.)*[a-z0-9-]+$/i;
+/**
+ * What "@developer" stands for in allowOnly: package registries, source hosts, toolchain downloads and the AI
+ * providers the agents talk to. Enough for an agent to install dependencies, push to GitHub and reach its model.
+ */
+export const DEVELOPER_HOSTS = [
+    // AI providers
+    'api.anthropic.com', 'claude.ai', '*.claude.ai', 'console.anthropic.com', 'statsig.anthropic.com', 'sentry.io', '*.sentry.io',
+    'api.openai.com', 'chatgpt.com', '*.openai.com', 'generativelanguage.googleapis.com', 'oauth2.googleapis.com', 'accounts.google.com',
+    // source hosts
+    'github.com', '*.github.com', '*.githubusercontent.com', 'codeload.github.com', 'gitlab.com', '*.gitlab.com', 'bitbucket.org',
+    // package registries
+    'registry.npmjs.org', '*.npmjs.org', 'registry.yarnpkg.com', 'pypi.org', 'files.pythonhosted.org', 'crates.io', 'index.crates.io', 'static.crates.io',
+    'proxy.golang.org', 'sum.golang.org', 'repo1.maven.org', 'repo.maven.apache.org', 'plugins.gradle.org', 'services.gradle.org', 'api.nuget.org',
+    '*.nuget.org', 'rubygems.org', 'index.rubygems.org', 'repo.packagist.org', 'packagist.org', 'jsr.io', 'deno.land',
+    // toolchains
+    'nodejs.org', '*.nodejs.org', 'static.rust-lang.org', 'go.dev', 'dl.google.com', 'aka.ms', 'download.visualstudio.microsoft.com',
+    'dotnetcli.azureedge.net', 'builds.dotnet.microsoft.com', 'api.adoptium.net', 'objects.githubusercontent.com', 'marketplace.visualstudio.com',
+    '*.gallerycdn.vsassets.io', '*.vscode-cdn.net', 'update.code.visualstudio.com',
+];
+/** The allowOnly list with "@developer" expanded, lower case, without duplicates. */
+export const expandAllowList = (list) => [...new Set(list.flatMap((h) => (h.trim().toLowerCase() === '@developer' ? DEVELOPER_HOSTS : [h])).map((h) => h.trim().toLowerCase()).filter((h) => HOST_PATTERN.test(h)))];
+/** Does `host` match one of the patterns? "*.example.com" matches its subdomains (not example.com itself). */
+export const hostAllowed = (host, patterns) => {
+    const h = host.toLowerCase().replace(/\.$/, '');
+    return patterns.some((p) => (p.startsWith('*.') ? h.endsWith(p.slice(1)) && h.length > p.length - 1 : h === p));
+};
+export const HOSTS_BEGIN = '# >>> windows-development-sandbox network.blockHosts';
+export const HOSTS_END = '# <<< windows-development-sandbox network.blockHosts';
+/** The hosts file with our block section replaced by `hosts` (each sent to 0.0.0.0 and ::); everything else stays. */
+export const withBlockedHosts = (hostsFile, hosts) => {
+    const begin = hostsFile.indexOf(HOSTS_BEGIN);
+    const end = hostsFile.indexOf(HOSTS_END);
+    const outside = begin >= 0 && end > begin ? hostsFile.slice(0, begin) + hostsFile.slice(end + HOSTS_END.length) : hostsFile;
+    const clean = [...new Set(hosts.map((h) => h.trim().toLowerCase()).filter((h) => HOST_PATTERN.test(h) && !h.startsWith('*.')))];
+    const base = outside.replace(/\s+$/, '');
+    if (!clean.length)
+        return base + '\r\n';
+    return [base, HOSTS_BEGIN, ...clean.flatMap((h) => ['0.0.0.0 ' + h, ':: ' + h]), HOSTS_END, ''].join('\r\n');
+};
+/**
+ * The port the sandbox's relay for forward `index` listens on (it connects on to localhost:<sandbox> inside, so a
+ * server that only listens on localhost is reachable too). Out of the range Windows hands out for outgoing connections.
+ */
+export const relayPort = (index) => 38100 + index;
+/** The address the sandbox's built-in proxy listens on (allowOnly). */
+export const PROXY_PORT = 38080;

package/dist/shared/projects.d.ts

@@ -1,5 +1,12 @@
-/** Where roots, boot-mapped projects and shared folders appear inside the sandbox. */
+/** Where project roots appear inside the sandbox. */
 export declare const PROJECTS_GUEST = "C:\\Projects";
+/** Where projects mapped on their own appear (the launch folder with guestWorkspace "auto", boot-mapped and shared ones). */
+export declare const WORKSPACES_GUEST = "C:\\Workspace";
+/**
+ * guestWorkspace "auto" for a folder: C:\Workspace\<folder name>. Keeping the real folder name means Claude's
+ * per-project history and claude-mem's project name match this PC instead of every project being "Workspace".
+ */
+export declare const autoGuestFolder: (hostDir: string) => string;
 /** How a project got into the sandbox. */
 export type Mechanism = 'launch' | 'root' | 'boot' | 'wsb';
 /** One project the running sandbox works on. */
@@ -37,17 +44,33 @@ export declare const hostDirFor: (mapped: {
 }, 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). */
+/**
+ * A guest folder some project can be in: below C:\Projects or C:\Workspace (projects mapped on their own, also shared
+ * after boot), or inside one of `roots` (the roots' and boot-mapped projects' guest paths).
+ */
 export declare const insideProjects: (guestDir: string, roots?: string[], projectsDir?: string) => boolean;
 export interface RootMapping {
     host: string;
     guest: string;
 }
+/** The project roots that are mapped, in order: existing folders, none inside a root listed before it. */
+export declare const usableRoots: (roots: string[], exists: (dir: string) => boolean) => 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.
+ * Where a project mapped on its own appears, the same place it has as the launch folder: with "mirror" its PC path
+ * when the sandbox can show it there, else C:\Workspace\<name>. -2, -3, ... when that overlaps a folder in `taken`.
+ */
+export declare const ownGuestFolder: (hostDir: string, mirror: boolean, 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
+ * other). A root's folder depends only on the roots, so every launch with the same roots shows them at the same place.
  */
 export declare const planProjectMappings: (roots: string[], projects: string[], mirror: boolean, taken?: string[]) => {
     roots: RootMapping[];
     projects: RootMapping[];
 };
+/**
+ * Where a folder inside one of the (usable) roots appears: under the root's guest folder, whichever project started
+ * the sandbox. Null when it is in no root.
+ */
+export declare const rootGuestDir: (roots: string[], mirror: boolean, hostDir: string) => string | null;

package/dist/shared/projects.js

@@ -1,16 +1,30 @@
 // 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);
+//  - the launch folder (mapped directly, or shown by the project root it is in);
 //  - 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").
+// 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);
+//  - any other project, mapped on its own, is always at C:\Workspace\<name> (also when it is mapped at boot or shared).
+// With guestWorkspace "mirror" both appear at their PC paths when the sandbox can show them there.
 // 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. */
+import { isValidGuestPath, planMirrorWorkspace } from './guest-paths.js';
+/** Where project roots appear inside the sandbox. */
 export const PROJECTS_GUEST = 'C:\\Projects';
+/** Where projects mapped on their own appear (the launch folder with guestWorkspace "auto", boot-mapped and shared ones). */
+export const WORKSPACES_GUEST = 'C:\\Workspace';
+/**
+ * guestWorkspace "auto" for a folder: C:\Workspace\<folder name>. Keeping the real folder name means Claude's
+ * per-project history and claude-mem's project name match this PC instead of every project being "Workspace".
+ */
+export const autoGuestFolder = (hostDir) => {
+    const name = path.win32.basename(hostDir.replace(/[\\/]+$/, '')).replace(/[^A-Za-z0-9._ -]/g, '_').replace(/^[. ]+|[. ]+$/g, '');
+    return WORKSPACES_GUEST + '\\' + (name || 'project');
+};
 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) => {
@@ -47,21 +61,66 @@ export const hostDirFor = (mapped, guestDir) => {
 };
 /** 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.
+ * A guest folder some project can be in: below C:\Projects or C:\Workspace (projects mapped on their own, also shared
+ * after boot), or inside one of `roots` (the roots' and boot-mapped projects' guest paths).
+ */
+export const insideProjects = (guestDir, roots = [], projectsDir = PROJECTS_GUEST) => isBelow(projectsDir, guestDir) || isBelow(WORKSPACES_GUEST, guestDir) || roots.some((r) => isWithin(r, guestDir));
+const resolveDir = (dir) => path.win32.resolve(dir).replace(/[\\/]+$/, '');
+/** The project roots that are mapped, in order: existing folders, none inside a root listed before it. */
+export const usableRoots = (roots, exists) => {
+    const out = [];
+    for (const root of roots.map(resolveDir))
+        if (exists(root) && !out.some((r) => isWithin(r, root)))
+            out.push(root);
+    return out;
+};
+/**
+ * Where a project mapped on its own appears, the same place it has as the launch folder: with "mirror" its PC path
+ * when the sandbox can show it there, else C:\Workspace\<name>. -2, -3, ... when that overlaps a folder in `taken`.
+ */
+export const ownGuestFolder = (hostDir, mirror, taken = []) => {
+    const host = resolveDir(hostDir);
+    const free = (guest) => !taken.some((t) => isWithin(t, guest) || isWithin(guest, t));
+    const mirrored = mirror ? planMirrorWorkspace(host, '').guest : '';
+    if (mirrored && !isWithin(PROJECTS_GUEST, mirrored) && !isWithin(WORKSPACES_GUEST, mirrored) && free(mirrored))
+        return mirrored;
+    const base = autoGuestFolder(host);
+    if (free(base))
+        return base;
+    for (let i = 2;; i++)
+        if (free(base + '-' + i))
+            return 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
+ * other). A root's folder depends only on the roots, so every launch with the same roots shows them at the same place.
  */
 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))
+    const names = [];
+    const placeRoot = (host) => {
+        const resolved = resolveDir(host);
+        if (mirror && 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)) };
+    const planned = roots.map(placeRoot);
+    const used = [...taken, ...planned.map((r) => r.guest)];
+    const placed = projects.map((p) => {
+        const guest = ownGuestFolder(p, mirror, used);
+        used.push(guest);
+        return { host: resolveDir(p), guest };
+    });
+    return { roots: planned, projects: placed };
+};
+/**
+ * Where a folder inside one of the (usable) roots appears: under the root's guest folder, whichever project started
+ * the sandbox. Null when it is in no root.
+ */
+export const rootGuestDir = (roots, mirror, hostDir) => {
+    const root = projectForHostDir(planProjectMappings(roots, [], mirror).roots, hostDir);
+    return root ? guestDirFor(root, hostDir) : null;
 };

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

@@ -10,6 +10,7 @@ export declare const FrameType: {
     readonly Error: 18;
     readonly Restarting: 19;
     readonly Status: 20;
+    readonly Console: 21;
 };
 /** HELLO flags: control-only connections get no output and never size the console; a query only asks for STATUS. */
 export declare const HelloFlag: {
@@ -36,6 +37,8 @@ export type ClientResult = {
     reason: 'error';
     message: string;
 };
+/** Turns off every mouse tracking mode a program may have turned on in your terminal (normal, button, any, UTF-8, SGR, urxvt). */
+export declare const MOUSE_OFF = "\u001B[?1000l\u001B[?1002l\u001B[?1003l\u001B[?1005l\u001B[?1006l\u001B[?1015l";
 /** 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;
@@ -49,12 +52,16 @@ export declare class FrameReader {
     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.
+ * Removes the terminal "strings" an untrusted program could abuse from the sandbox's output before it reaches your
+ * terminal: clipboard writes (OSC 52), terminal macros (ConEmu's OSC 9), DCS / APC / PM / SOS, and their C1 forms.
+ * Titles, links, progress and colours pass. A byte-level state machine, so no split across chunks, leading zero
+ * (ESC]052) or huge payload slips through: a dropped string stays dropped until its terminator, however long it is.
  */
 export declare class OutputFilter {
-    private carry;
+    /** text: normal output; esc: after ESC; c2: after a 0xC2 lead byte; string: inside an OSC/DCS/...; stringEsc / stringC2: a possible terminator inside one. */
+    private state;
+    /** The string being read: an OSC worth keeping is collected until its terminator; null = being dropped. */
+    private body;
     push(chunk: Buffer): Buffer;
 }
 /** Tries every address the sandbox published and returns the first one that answers. */
@@ -77,6 +84,21 @@ export declare const queryViewers: (endpoint: Endpoint, timeoutMs?: number) => P
  * what terminals send. ConPTY reads ^H as Ctrl+Backspace (delete a word), so swap them back.
  */
 export declare const fixWindowsKeys: (chunk: Buffer) => Buffer;
+/** How long an unfinished escape sequence is held back waiting for the rest (a lone Esc key press waits this long). */
+export declare const JOIN_MS = 30;
+/**
+ * Keeps each escape sequence typed into your terminal (keys, mouse reports, the terminal's replies) in one INPUT frame.
+ * The console can hand one over in pieces; ConPTY reads a lone "ESC[" as Alt+[ and the rest as typed text, so a split
+ * Right arrow (ESC[C) left a stray "C" in the agent's prompt. An unfinished sequence at the end of a chunk is held
+ * until the rest arrives (or JOIN_MS passes).
+ */
+export declare class InputJoiner {
+    private held;
+    /** The bytes to send now; an unfinished sequence at the end is kept for the next chunk. */
+    push(chunk: Buffer): Buffer;
+    holding(): boolean;
+    flush(): 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.